Zeq Equation Auth

Universal authentication where your mathematical equation is your password. The server never stores the equation — only a SHA-256 hash of its evaluated result.

Architecture Overview

Zeq Equation Auth replaces traditional passwords with mathematical equations. The flow:

1. User creates an equation — e.g. x^2 + 3*sin(y) - 7
2. Server evaluates at x = 1.287, y = 0.777 using a safe recursive descent parser (no eval())
3. Server hashes the equation and its result using SHA-256 and stores only the hash
4. ZID derived — a deterministic identifier derived from the hash
5. Token issued — base64url-encoded JSON with 7-day TTL

The equation is never stored. To log in, the user re-enters their equation. The server re-evaluates, re-hashes, and compares.

Parser Specification

The safe recursive descent parser supports:

Functions (16)

sin, cos, tan, asin, acos, atan, sqrt, abs, log, ln, log10, exp, floor, ceil, round, sign

Constants (3)

Constant	Value
pi	3.141592653589793
e	2.718281828459045
phi	1.618033988749895 (golden ratio)

Variables (2)

Variable	Value
x	1.287
y	0.777

Operators

+, -, *, /, ^ (right-associative exponentiation), unary +/-, parentheses ()

Grammar

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

Maximum equation length: 500 characters.

API Reference

All endpoints are prefixed with /auth.

POST /auth/register

Create a new account.

Request:

{
  "displayName": "Alice",
  "equation": "x^2 + sin(y*pi)"
}

Response (201):

{
  "zid": "zeq-a1b2c3d4e5f6",
  "displayName": "Alice",
  "avatarColor": "#a1b2c3",
  "token": "<base64url token>"
}

Errors: 400 invalid input, 409 equation already registered or ZID collision.

POST /auth/login

Authenticate with an existing equation.

Request:

{
  "equation": "x^2 + sin(y*pi)",
  "zid": "zeq-a1b2c3d4e5f6"
}

The zid field is optional — lookup is done by hash first, then by ZID as fallback (with hash verification).

Response (200):

{
  "zid": "zeq-a1b2c3d4e5f6",
  "displayName": "Alice",
  "avatarColor": "#a1b2c3",
  "token": "<base64url token>"
}

POST /auth/verify

Validate a token without authentication headers.

Request:

{ "token": "<base64url token>" }

Response (200):

{
  "valid": true,
  "zid": "zeq-a1b2c3d4e5f6",
  "displayName": "Alice"
}

GET /auth/profile

Requires Authorization: Bearer <token> header.

Response (200):

{
  "zid": "zeq-a1b2c3d4e5f6",
  "displayName": "Alice",
  "avatarColor": "#a1b2c3",
  "giteaLinked": false,
  "lastSeen": "2026-03-01T12:00:00",
  "createdAt": "2026-02-28T10:00:00"
}

POST /auth/recovery/export

Requires Authorization: Bearer <token> header. Returns account metadata for device recovery. The hint reminds the user to save their equation.

GET /auth/health

Response (200):

{
  "service": "zeq-equation-auth",
  "version": "1.287.0",
  "status": "ok",
  "port": 3015,
  "users": 42,
  "uptime": 3600,
  "methods": ["equation-key"]
}

Token Format

Tokens are base64url-encoded JSON:

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

• TTL: 7 days from issuance
• Format: base64url(JSON.stringify(payload))
• Verification: Decode, check exp > Date.now(), look up ZID in database

ZID Format

zeq-XXXXXXXXXXXX

Example: zeq-a1b2c3d4e5f6

ZIDs are deterministically derived from the equation hash. The avatar color is derived from the ZID.

Integration Guide

To integrate Equation Auth into another Zeq OS app:

// 1. Register or login
const res = await fetch('/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ equation: userEquation })
});
const { zid, token } = await res.json();

// 2. Store the token
localStorage.setItem('zeq_token', token);

// 3. Use the token for authenticated requests
const profile = await fetch('/auth/profile', {
  headers: { 'Authorization': `Bearer ${token}` }
});

// 4. Verify tokens from other services
const verify = await fetch('/auth/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token })
});
const { valid, zid: verifiedZid } = await verify.json();

SDK Package

For programmatic integration, use the @zeq-os/auth package:

import { ZeqAuthClient, EquationParser } from '@zeq-os/auth';

const auth = new ZeqAuthClient('/auth');
const result = await auth.login('x^2 + sin(y*pi)');

See framework/packages/zeq-auth/ for the full SDK.