Skip to main content

Zeq Auth — Your Equation Is Your Identity

Zeq Auth is the revolutionary authentication service at the heart of the Zeq OS ecosystem. It replaces passwords entirely with mathematical equations — a paradigm shift in identity verification where the server never stores your credential, only a SHA-256 hash of its evaluated result.

Overview​

Every application in the Zeq OS ecosystem — all 44+ apps — authenticates through Zeq Auth. The service runs on port 3015 and provides a unified identity layer:

  • Equation Key — Your mathematical equation IS your password

When you register with an equation like x^2 + sin(y*pi) + phi, the server evaluates it at the HulyaPulse constants (x = 1.287, y = 0.777), hashes the result with SHA-256, and derives your unique ZEQ ID — a deterministic, permanent identity derived purely from mathematics.

The equation is never stored. The same equation always produces the same identity, across any device, any browser, any time.

Launch: Authentication is integrated into every application via the global navigation bar. Access any app to see the unified Sign In button.

Why Equations Replace Passwords​

Traditional passwords suffer from fundamental weaknesses: they are memorized strings that can be phished, leaked in database breaches, and brute-forced. Zeq Auth addresses all three:

ProblemPasswordsEquation Keys
PhishingUser types password into fake siteEquation produces same ZID regardless of site — no secret transmitted
Database breachHashed passwords can be crackedOnly SHA-256 hash of evaluated result is stored — equation not recoverable
Brute forceLimited character set (a-z, 0-9, symbols)Infinite mathematical function space (sin, cos, sqrt, nested expressions)
MemorabilityRandom strings are hard to rememberMathematical relationships are intuitive and personal
UniquenessUsers reuse passwordsEach equation evaluates to a unique numerical result

How It Works​

Registration Flow​

1. User enters equation:    x^2 + sin(y*pi) + phi
2. Server evaluates:        1.287² + sin(0.777π) + φ = 3.917...
3. Server hashes:           SHA-256("x^2 + sin(y*pi) + phi" + ":" + "3.917...")
4. ZID derived:             zeq- + first 12 hex chars of hash
5. Avatar color derived:    # + first 6 hex chars of hash
6. Only hash + ZID stored in database

Login Flow​

1. User re-enters equation: x^2 + sin(y*pi) + phi
2. Server re-evaluates → same result
3. Server re-hashes → same hash
4. Hash lookup in database → match found
5. Token issued → base64url JSON with 7-day TTL

Token Format​

Tokens are lightweight base64url-encoded JSON:

{ "zid": "zeq-a1b2c3d4e5f6", "exp": 1772589248018 }

Stored in localStorage as zeq_token and zeq_user. Cross-tab synchronization via storage events means logging in on one tab authenticates all open tabs.

Safe Equation Parser​

The parser is a recursive descent parser — no eval(), no Function(), no vm module. It implements a strict grammar:

expr     → term (('+' | '-') term)*
term     → power (('*' | '/') power)*
power    → unary ('^' power)?          // right-associative
unary    → ('+' | '-') unary | call
call     → IDENT '(' expr ')' | primary
primary  → NUMBER | IDENT | '(' expr ')'

Supported Features​

CategoryItems
Functions (16)sin, cos, tan, asin, acos, atan, sqrt, abs, log, ln, log10, exp, floor, ceil, round, sign
Constants (3)pi (π), e (Euler's), phi (φ golden ratio)
Variables (2)x = 1.287 (HulyaPulse), y = 0.777 (Zeqond)
Operators+, -, *, /, ^ (right-associative), unary +/-, parentheses
LimitsMax 500 characters; division by zero and non-finite results rejected

Browser Integration​

The global navigation bar (injected into every Zeq OS page) exposes window.ZeqAuth for client-side integration:

// Check authentication state
if (window.ZeqAuth?.isLoggedIn()) {
  const user = window.ZeqAuth.getUser();
  console.log(user.id);           // zeq-a1b2c3d4e5f6
  console.log(user.displayName);  // Alice
  console.log(user.avatarColor);  // #a1b2c3
}

// Programmatic login modal
window.ZeqAuth.showLoginModal();

// Listen for auth changes
window.ZeqAuth.onAuthChange(user => {
  console.log(user ? `Logged in: ${user.displayName}` : 'Logged out');
});

// Rate limit check (after 20 unauthenticated views)
window.ZeqAuth.shouldPromptLogin();

API Endpoints​

All endpoints are served at /auth/ (proxied from port 3015):

MethodEndpointAuthDescription
POST/auth/registerNoRegister with {displayName, equation}
POST/auth/loginNoLogin with {equation, zid?}
POST/auth/verifyNoVerify {token} → {valid, zid, displayName}
GET/auth/profileBearerGet authenticated user profile
GET/auth/healthNoService health check

Architecture​

┌─────────────────────────────┐
│  Global Navigation Bar       │  window.ZeqAuth API
├─────────────────────────────┤
│  44+ Zeq OS Applications     │  Token-based auth
├─────────────────────────────┤
│  Zeq Auth Server (:3015)     │  Express + SQLite
│  ├── Equation Parser          │  Recursive descent
│  ├── SHA-256 Hashing          │  Identity derivation
│  └── Token Management         │  base64url JSON, 7-day TTL
├─────────────────────────────┤
│  SQLite Database              │  users table (hash only)
└─────────────────────────────┘

Database Schema​

CREATE TABLE users (
    zid            TEXT PRIMARY KEY,
    display_name   TEXT NOT NULL,
    equation_hash  TEXT NOT NULL UNIQUE,
    avatar_color   TEXT NOT NULL,
    gitea_id       TEXT,
    last_seen      TEXT,
    created_at     TEXT DEFAULT (datetime('now'))
);

Note: equation_hash stores SHA-256(equation + ":" + result) — the equation itself is never persisted.

Rate Limiting​

Zeq OS allows unauthenticated users to explore freely. After 20 page views, a non-blocking banner encourages sign-in. Users can dismiss it for 10 additional free views. Applications can check this via window.ZeqAuth.shouldPromptLogin().

Key Operators​

OperatorFormulaRole
AUTH-PARSERecursiveDescent(equation, {x:1.287, y:0.777})Safe equation evaluation
AUTH-HASHSHA-256(equation + ":" + result)Identity hash derivation
AUTH-ZIDzeq- + hash[0:12]Unique identifier
AUTH-COLOR# + hash[0:6]Deterministic avatar color
AUTH-TOKENbase64url({zid, exp})Session token

Running Zeq Auth​

Zeq Auth runs as part of the Docker Compose stack. It is proxied at /auth/ through nginx.

Standalone​

cd apps/zeq-auth
npm install
node server.js
# → Zeq Auth running on port 3015

Environment Variables​

VariableDefaultDescription
AUTH_PORT3015Server port