toiljs 0.0.85 → 0.0.86

package/examples/basic/server/models/SiteAnalytics.ts

@@ -1,25 +1,138 @@
-/** This site's own analytics, mapped from the toilscript `Analytics.self()` snapshot for the
- *  client. Counts + usage are i64; the rate-limit caps are i64 too (0 = unlimited). */
+/**
+ * This site's own analytics snapshot, mapped 1:1 from the toilscript `Analytics.self()` frame.
+ *
+ * Every `total*` field is an ALL-TIME CUMULATIVE COUNT — a running total since the site was first
+ * seen, monotonically increasing, never reset by a query. They are NOT "last hour" or "last minute":
+ * for time-windowed history use the separate `SeriesData` time-series (`/series`).
+ *
+ * All counter fields are `u64` (the guest exposes `u64` getters, so the mapping needs zero casts). The
+ * `live*` gauges are the current instantaneous level (not a total). The request-window fields are the
+ * current rate-limit bucket usage paired with the plan cap (cap `0` = unlimited).
+ */
 @data
 export class SiteAnalytics {
-    requests: i64 = 0;
-    bytesOutL1: i64 = 0;
-    bytesInL1: i64 = 0;
-    status2xx: i64 = 0;
-    wasmDispatches: i64 = 0;
-    dbOps: i64 = 0;
-    gasUsed: i64 = 0;
-    connectedStreams: i64 = 0;
-    committedMemory: i64 = 0;
-    reqMinuteUsed: i64 = 0;
-    reqMinuteCap: i64 = 0;
-    reqDayUsed: i64 = 0;
-    reqDayCap: i64 = 0;
+    // --- Requests / L1 edge (all-time totals) ---
+    /** Total HTTP requests served, all-time. */
+    totalRequests: u64 = 0;
+    /** Total response bytes sent from the L1 edge, all-time. */
+    totalBytesOutL1: u64 = 0;
+    /** Total request bytes received at the L1 edge, all-time. */
+    totalBytesInL1: u64 = 0;
+    /** Total 2xx responses, all-time. */
+    totalStatus2xx: u64 = 0;
+    /** Total 3xx responses, all-time. */
+    totalStatus3xx: u64 = 0;
+    /** Total 4xx responses, all-time. */
+    totalStatus4xx: u64 = 0;
+    /** Total 5xx responses, all-time. */
+    totalStatus5xx: u64 = 0;
+    /** Total static-asset hits (served without a wasm dispatch), all-time. */
+    totalStaticHits: u64 = 0;
+    /** Total wasm handler dispatches, all-time. */
+    totalWasmDispatches: u64 = 0;
+    /** Total requests rejected because the executor pool was full, all-time. */
+    totalExecutorFullRejects: u64 = 0;
+    /** Total requests rejected for an unknown host, all-time. */
+    totalUnknownHostRejects: u64 = 0;
+    /** Total requests rejected by rate limiting, all-time. */
+    totalRateLimitedRejects: u64 = 0;
+    /** Total wasm gas consumed across all dispatches, all-time. */
+    totalGasUsed: u64 = 0;
+
+    // --- Database (all-time totals) ---
+    /** Total ToilDB operations issued, all-time. */
+    totalDbOps: u64 = 0;
+    /** Total ToilDB read operations, all-time. */
+    totalDbReads: u64 = 0;
+    /** Total ToilDB write operations, all-time. */
+    totalDbWrites: u64 = 0;
+    /** Total ToilDB operations that errored, all-time. */
+    totalDbErrors: u64 = 0;
+    /** Summed host-observed ToilDB op latency in nanoseconds, all-time (divide by totalDbOps for a mean). */
+    totalDbLatencyNsSum: u64 = 0;
+
+    // --- Streams / WebTransport (all-time totals) ---
+    /** Total stream connections accepted, all-time. */
+    totalStreamAccepts: u64 = 0;
+    /** Total streams rejected because they landed on the wrong node, all-time. */
+    totalStreamRejectWrongNode: u64 = 0;
+    /** Total streams rejected for capacity, all-time. */
+    totalStreamRejectCapacity: u64 = 0;
+    /** Total streams rejected for a missing/invalid artifact, all-time. */
+    totalStreamRejectArtifact: u64 = 0;
+    /** Total streams rejected by the guest, all-time. */
+    totalStreamRejectGuest: u64 = 0;
+    /** Total stream guest traps, all-time. */
+    totalStreamTraps: u64 = 0;
+    /** Total streams closed for idle timeout, all-time. */
+    totalStreamIdleTimeouts: u64 = 0;
+    /** Total bytes received on streams, all-time. */
+    totalStreamBytesIn: u64 = 0;
+    /** Total bytes sent on streams, all-time. */
+    totalStreamBytesOut: u64 = 0;
+    /** Total stream backpressure events, all-time. */
+    totalStreamBackpressureEvents: u64 = 0;
+    /** Total clean stream closes, all-time. */
+    totalStreamCloses: u64 = 0;
+    /** Total stream disconnects (abrupt), all-time. */
+    totalStreamDisconnects: u64 = 0;
+
+    // --- Daemons / L4 (all-time totals) ---
+    /** Total daemon starts, all-time. */
+    totalDaemonStarts: u64 = 0;
+    /** Total daemon start failures, all-time. */
+    totalDaemonStartFailures: u64 = 0;
+    /** Total daemon ticks fired, all-time. */
+    totalDaemonTicksFired: u64 = 0;
+    /** Total daemon ticks skipped because this node was not the leader, all-time. */
+    totalDaemonTicksSkippedNotLeader: u64 = 0;
+    /** Total daemon ticks that failed, all-time. */
+    totalDaemonTicksFailed: u64 = 0;
+    /** Total daemon leadership acquisitions, all-time. */
+    totalDaemonLeaderAcquires: u64 = 0;
+    /** Total daemon leadership fences (lost leadership), all-time. */
+    totalDaemonLeaderFenced: u64 = 0;
+    /** Total daemon outbound http_call attempts, all-time. */
+    totalDaemonHttpCallAttempts: u64 = 0;
+    /** Total daemon outbound http_call failures, all-time. */
+    totalDaemonHttpCallFailures: u64 = 0;
+
+    // --- Memory / email / cache (all-time totals) ---
+    /** Total wasm linear-memory bytes grown, all-time. */
+    totalMemGrownBytes: u64 = 0;
+    /** Total emails sent, all-time. */
+    totalEmails: u64 = 0;
+    /** Total responses served from the edge cache, all-time. */
+    totalCacheHits: u64 = 0;
+    /** Total cacheable responses that missed the edge cache, all-time. */
+    totalCacheMisses: u64 = 0;
+
+    // --- Derived ---
+    /** Fraction of cacheable responses served from cache: hits / (hits + misses), in 0..1. 0 when there
+     *  were no cacheable responses. */
+    cacheHitRatio: f64 = 0;
+
+    // --- Live gauges (current instantaneous level, NOT a total) ---
+    /** Streams currently connected right now. */
+    liveConnectedStreams: u64 = 0;
+    /** Wasm linear memory currently committed right now, in bytes. */
+    liveCommittedMemoryBytes: u64 = 0;
+
+    // --- Request windows: current rate-limit usage vs plan cap (cap 0 = unlimited) ---
+    /** Requests used in the current 1-minute window. */
+    requestsThisMinute: u64 = 0;
+    /** Plan cap for the 1-minute window (0 = unlimited). */
+    requestsThisMinuteCap: u64 = 0;
+    /** Requests used in the current 24-hour window. */
+    requestsToday: u64 = 0;
+    /** Plan cap for the 24-hour window (0 = unlimited). */
+    requestsTodayCap: u64 = 0;
 }
 
-/** One metric's historical time-series for a range, from `Analytics.series(metric, range)`: the raw
+/** One metric's historical TIME-SERIES for a range, from `Analytics.series(metric, range)`: the raw
  *  per-bucket totals (oldest→newest) plus the bucket width + newest-bucket end, so the client can draw a
- *  graph and derive per-second rates. Demonstrates the typed series API. */
+ *  graph and derive per-second rates. This is per-bucket HISTORY — distinct from the all-time totals in
+ *  `SiteAnalytics`. Demonstrates the typed series API. */
 @data
 export class SeriesData {
     metric: i32 = 0;

package/examples/basic/server/routes/Analytics.ts

@@ -16,23 +16,74 @@ import { SeriesData, SiteAnalytics } from '../models/SiteAnalytics';
 class AnalyticsRoutes {
     @get('/')
     public self(): SiteAnalytics {
-        const s = Analytics.self();
-        const r = new SiteAnalytics();
-        // Typed getters: no magic strings, no `.has()/.get()` map dance.
-        r.requests = s.requests;
-        r.bytesOutL1 = s.bytesOutL1;
-        r.bytesInL1 = s.bytesInL1;
-        r.status2xx = s.status2xx;
-        r.wasmDispatches = s.wasmDispatches;
-        r.dbOps = s.dbOps;
-        r.gasUsed = s.gasUsed;
-        r.connectedStreams = s.connectedStreams;
-        r.committedMemory = s.committedMemory;
-        r.reqMinuteUsed = s.reqMinuteUsed;
-        r.reqMinuteCap = <i64>s.reqMinuteCap;
-        r.reqDayUsed = s.reqDayUsed;
-        r.reqDayCap = <i64>s.reqDayCap;
-        return r;
+        const stats = Analytics.self();
+        const out = new SiteAnalytics();
+
+        // Requests / L1 edge (all-time totals). Guest getters are u64, model fields are u64: no casts.
+        out.totalRequests = stats.requests;
+        out.totalBytesOutL1 = stats.bytesOutL1;
+        out.totalBytesInL1 = stats.bytesInL1;
+        out.totalStatus2xx = stats.status2xx;
+        out.totalStatus3xx = stats.status3xx;
+        out.totalStatus4xx = stats.status4xx;
+        out.totalStatus5xx = stats.status5xx;
+        out.totalStaticHits = stats.staticHits;
+        out.totalWasmDispatches = stats.wasmDispatches;
+        out.totalExecutorFullRejects = stats.executorFullRejects;
+        out.totalUnknownHostRejects = stats.unknownHostRejects;
+        out.totalRateLimitedRejects = stats.rateLimitedRejects;
+        out.totalGasUsed = stats.gasUsed;
+
+        // Database (all-time totals).
+        out.totalDbOps = stats.dbOps;
+        out.totalDbReads = stats.dbReads;
+        out.totalDbWrites = stats.dbWrites;
+        out.totalDbErrors = stats.dbErrors;
+        out.totalDbLatencyNsSum = stats.dbLatencyNsSum;
+
+        // Streams / WebTransport (all-time totals).
+        out.totalStreamAccepts = stats.streamAccepts;
+        out.totalStreamRejectWrongNode = stats.streamRejectWrongNode;
+        out.totalStreamRejectCapacity = stats.streamRejectCapacity;
+        out.totalStreamRejectArtifact = stats.streamRejectArtifact;
+        out.totalStreamRejectGuest = stats.streamRejectGuest;
+        out.totalStreamTraps = stats.streamTraps;
+        out.totalStreamIdleTimeouts = stats.streamIdleTimeouts;
+        out.totalStreamBytesIn = stats.streamBytesIn;
+        out.totalStreamBytesOut = stats.streamBytesOut;
+        out.totalStreamBackpressureEvents = stats.streamBackpressureEvents;
+        out.totalStreamCloses = stats.streamCloses;
+        out.totalStreamDisconnects = stats.streamDisconnects;
+
+        // Daemons / L4 (all-time totals).
+        out.totalDaemonStarts = stats.daemonStarts;
+        out.totalDaemonStartFailures = stats.daemonStartFailures;
+        out.totalDaemonTicksFired = stats.daemonTicksFired;
+        out.totalDaemonTicksSkippedNotLeader = stats.daemonTicksSkippedNotLeader;
+        out.totalDaemonTicksFailed = stats.daemonTicksFailed;
+        out.totalDaemonLeaderAcquires = stats.daemonLeaderAcquires;
+        out.totalDaemonLeaderFenced = stats.daemonLeaderFenced;
+        out.totalDaemonHttpCallAttempts = stats.daemonHttpCallAttempts;
+        out.totalDaemonHttpCallFailures = stats.daemonHttpCallFailures;
+
+        // Memory / email / cache (all-time totals) + the derived cache-hit ratio.
+        out.totalMemGrownBytes = stats.memGrownBytes;
+        out.totalEmails = stats.emails;
+        out.totalCacheHits = stats.cacheHits;
+        out.totalCacheMisses = stats.cacheMisses;
+        out.cacheHitRatio = stats.cacheRatio;
+
+        // Live gauges (current level, not a total).
+        out.liveConnectedStreams = stats.connectedStreams;
+        out.liveCommittedMemoryBytes = stats.committedMemory;
+
+        // Request windows: current usage vs plan cap (cap 0 = unlimited).
+        out.requestsThisMinute = stats.reqMinuteUsed;
+        out.requestsThisMinuteCap = stats.reqMinuteCap;
+        out.requestsToday = stats.reqDayUsed;
+        out.requestsTodayCap = stats.reqDayCap;
+
+        return out;
     }
 
     /// Any metric's historical time-series for a range, for graphs:

package/examples/basic/server/routes/UserId.ts

@@ -0,0 +1,22 @@
+import { Response } from 'toiljs/server/runtime';
+
+/**
+ * Demo of `ToilUserId` — the stable 256-bit user identity derived from the ML-DSA login public key +
+ * identifier (email/username) + tenant domain. Deterministic, opaque, O(1) to compare with `==` / `!=`.
+ */
+@rest('userid')
+class UserIdDemo {
+    @get('/demo')
+    public demo(): Response {
+        const key = new Uint8Array(1312); // an ML-DSA-44 public key (zeros for the demo)
+        const a = ToilUserId.derive(key, 'alice@example.com', 'acme.dacely.com');
+        const b = ToilUserId.derive(key, 'alice@example.com', 'acme.dacely.com');
+        const c = ToilUserId.derive(key, 'bob@example.com', 'acme.dacely.com');
+        // Same inputs => same id (a == b); a different identifier => a different id (a != c).
+        const same = a == b;
+        const diff = a != c;
+        return Response.text(
+            a.toHex() + '\nsame=' + same.toString() + ' diff=' + diff.toString() + '\n',
+        );
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.85",
+    "version": "0.0.86",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -67,6 +67,10 @@
             "types": "./server/runtime/*.ts",
             "default": "./server/runtime/*.ts"
         },
+        "./server/auth": {
+            "types": "./server/auth/index.ts",
+            "default": "./server/auth/index.ts"
+        },
         "./tsconfig": "./presets/tsconfig.json",
         "./eslint": "./presets/eslint.js",
         "./prettier": "./presets/prettier.json",

package/scripts/gen-toil-docs.mjs

@@ -58,13 +58,22 @@ const ORDER = [
 ];
 
 function collect() {
-    const all = fs
-        .readdirSync(docsDir)
-        .filter((f) => f.endsWith('.md') && !EXCLUDE.has(f))
-        .sort();
+    // Recurse one+ levels so a topic FOLDER (e.g. `docs/auth/*.md`) is bundled too, keyed by its
+    // repo-relative path (`auth/index.md`). Adding a `docs/**/*.md` is picked up automatically.
+    const files = [];
+    const walk = (dir, prefix) => {
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (ent.isDirectory()) {
+                walk(path.join(dir, ent.name), prefix + ent.name + '/');
+            } else if (ent.name.endsWith('.md') && !EXCLUDE.has(prefix + ent.name) && !EXCLUDE.has(ent.name)) {
+                files.push(prefix + ent.name);
+            }
+        }
+    };
+    walk(docsDir, '');
     const ordered = [
-        ...ORDER.filter((f) => all.includes(f)),
-        ...all.filter((f) => !ORDER.includes(f)),
+        ...ORDER.filter((f) => files.includes(f)),
+        ...files.filter((f) => !ORDER.includes(f)),
     ];
     const out = {};
     for (const name of ordered) {

package/server/auth/AuthController.ts

@@ -0,0 +1,335 @@
+import { Response, RouteContext } from 'toiljs/server/runtime';
+import { DataReader, DataWriter } from 'data';
+
+import { encodeSessionUser } from './AuthUser';
+
+/**
+ * Built-in Toil PQ-Auth controller: the full post-quantum password-login API
+ * (`/auth/register|login/start|finish`) plus sessions (`/auth/me`, `/auth/logout`),
+ * mounted automatically when an app opts in with `server: { auth: true }` (or
+ * `import 'toiljs/server/auth'`). It is a framework-shipped SOURCE file the build
+ * APPENDS to the toilscript entry set, so its `@data`/`@database`/`@rest` decorators
+ * weave and its `@rest` class self-mounts at `/auth/*` — no hand-written boilerplate.
+ *
+ * The password never leaves the browser. The client blinds it through the
+ * server-keyed OPRF (precomputation-resistant keyed salt), stretches the OPRF
+ * output with Argon2id into an ML-DSA-44 keypair, and registers only the public
+ * key (+ a proof-of-possession). Login is a challenge-response that also runs an
+ * ML-KEM-768 key encapsulation: the server proves its identity by returning a
+ * confirmation tag only derivable from the decapsulated shared secret (mutual
+ * auth). See `server/globals/auth.ts` (the `AuthService` global) and the client
+ * half in `toiljs/client` (`Auth.register` / `Auth.login`).
+ *
+ * STORAGE: backed by ToilDB (`@database AuthDb`). Accounts are a `record`
+ * collection keyed by username; login challenges are a `record` consumed exactly
+ * once with `getDelete` (atomic fetch-and-delete). The dev server emulates these
+ * `env.data.*` host imports in process (so register -> login spans requests under
+ * `toiljs dev`); the production edge backs the SAME API with ScyllaDB.
+ *
+ * Wire: every body/response is binary (`DataWriter`/`DataReader`), never JSON.
+ *
+ * Tuning (audience, TTLs, Argon2id params, rate-limit tuples) is fixed here for
+ * now; config-driven overrides are a documented follow-up. The secret trio
+ * (`AUTH_SESSION_SECRET` / `AUTH_OPRF_SEED` / `AUTH_KEM_SK`) resolves lazily from
+ * the tenant env store with DEV fallbacks, so this runs with zero config.
+ */
+
+// Demo-light Argon2id params (responsive in a browser tab). A real deployment
+// uses >= 256 MiB / >= 3 iterations. The client derives against whatever it is
+// handed, so this is the single source of truth.
+const MEM_KIB: u32 = 32768; // 32 MiB
+const ITERS: u32 = 2;
+const PAR: u32 = 1;
+
+const CHALLENGE_TTL_SECS: u64 = 120;
+const SESSION_TTL_SECS: u64 = 3600;
+
+// Resolved-and-cached per instance; the audience id (server config, never
+// client-echoed). Read lazily (not at module top level) so the env host import
+// runs during a dispatch, when the request host is bound — the same pattern
+// AuthService uses for its secrets.
+let __aud: string | null = null;
+function aud(): string {
+    const cached = __aud;
+    if (cached != null) return cached;
+    const v = Environment.getSecure('TOIL_AUTH_AUDIENCE');
+    const resolved = v != null ? v : 'toil';
+    __aud = resolved;
+    return resolved;
+}
+
+/**
+ * The tenant domain the stable {@link ToilUserId} is scoped to: the configured
+ * `TOIL_AUTH_DOMAIN` if set, else the request's `Host` header, else `localhost`.
+ * It only needs to be stable per deployment (it is one of the SHA-256 inputs of
+ * the user id), so any robust per-deployment host source is fine.
+ */
+function authDomain(ctx: RouteContext): string {
+    const configured = Environment.getSecure('TOIL_AUTH_DOMAIN');
+    if (configured != null) return configured;
+    const host = ctx.request.header('host');
+    if (host != null) return host;
+    return 'localhost';
+}
+
+function randomBytes(n: i32): Uint8Array {
+    const b = new Uint8Array(n);
+    crypto.getRandomValues(b);
+    return b;
+}
+
+function nowSecs(): u64 {
+    return <u64>(Date.now() / 1000);
+}
+
+/** One generic error on every failure path (anti-enumeration, anti-oracle). */
+function fail(): Response {
+    return Response.text('auth: request failed\n', 401);
+}
+
+/**
+ * Deterministic per-user Argon2id salt (16 bytes). With the OPRF providing
+ * precomputation resistance, a public/deterministic salt is fine: it only needs
+ * to be unique per user (the OPRF output already differs per user). Making it
+ * deterministic means register and login agree with NO stored salt, and an
+ * unknown user yields the SAME stable salt as a known one would -- no
+ * enumeration oracle.
+ */
+function deriveSalt(username: string): Uint8Array {
+    return crypto.sha256Text('toil-auth-salt-v1:' + username).slice(0, 16);
+}
+
+@data
+class Username {
+    name: string = '';
+    constructor(name: string = '') {
+        this.name = name;
+    }
+}
+
+@data
+class ChallengeId {
+    cid: Uint8Array = new Uint8Array(0);
+    constructor(cid: Uint8Array = new Uint8Array(0)) {
+        this.cid = cid;
+    }
+}
+
+@data
+class AuthAccount {
+    username: string = '';
+    salt: Uint8Array = new Uint8Array(0);
+    publicKey: Uint8Array = new Uint8Array(0);
+    memKiB: u32 = 0;
+    iterations: u32 = 0;
+    parallelism: u32 = 0;
+}
+
+@data
+class Challenge {
+    cid: Uint8Array = new Uint8Array(0);
+    username: string = '';
+    nonce: Uint8Array = new Uint8Array(0);
+    iat: u64 = 0;
+    exp: u64 = 0;
+}
+
+@database
+class AuthDb {
+    @collection static accounts: Documents<Username, AuthAccount>;
+    @collection static challenges: Documents<ChallengeId, Challenge>;
+}
+
+@rest('auth')
+class Auth {
+    /** POST /auth/register/start  body: str(username) bytes(blinded)
+     *  resp: u8(status=0) u32(mem) u32(iters) u32(par) bytes(salt) bytes(evaluated)
+     *  No taken-oracle: always succeeds; register/finish rejects a duplicate. */
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/register/start')
+    public registerStart(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const username = r.readString();
+        const blinded = r.readBytes();
+        if (!r.ok) return fail();
+        const evaluated = AuthService.oprfEvaluate(username, blinded);
+        if (evaluated.length != AuthService.OPRF_ELEMENT_LEN) return fail();
+
+        const w = new DataWriter();
+        w.writeU8(0);
+        w.writeU32(MEM_KIB);
+        w.writeU32(ITERS);
+        w.writeU32(PAR);
+        w.writeBytes(deriveSalt(username));
+        w.writeBytes(evaluated);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/register/finish  body: str(username) bytes(pk) bytes(regProof)
+     *  resp: u8(status) -- 0 = ok, 1 = username already registered. Verifies
+     *  proof-of-possession before storing the key. */
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/register/finish')
+    public registerFinish(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const username = r.readString();
+        const pk = r.readBytes();
+        const proof = r.readBytes();
+        if (!r.ok) return fail();
+        if (pk.length != AuthService.PUBLIC_KEY_LEN) return fail();
+        // Already registered: a distinguishable status (not the generic 401) so the
+        // client can say "username taken, log in instead" rather than a blank error.
+        if (AuthDb.accounts.exists(new Username(username))) {
+            return Response.bytes(new DataWriter().writeU8(1).toBytes());
+        }
+
+        // Proof-of-possession: the client signed buildRegisterMessage with the
+        // matching secret key, so we confirm it actually holds it.
+        const regMsg = AuthService.buildRegisterMessage(username, pk);
+        if (!AuthService.verifyRegister(pk, regMsg, proof)) return fail();
+
+        const a = new AuthAccount();
+        a.username = username;
+        a.salt = deriveSalt(username);
+        a.publicKey = pk;
+        a.memKiB = MEM_KIB;
+        a.iterations = ITERS;
+        a.parallelism = PAR;
+        // create-if-absent: a racing duplicate registration loses here, not above.
+        if (!AuthDb.accounts.create(new Username(username), a)) {
+            return Response.bytes(new DataWriter().writeU8(1).toBytes());
+        }
+        return Response.bytes(new DataWriter().writeU8(0).toBytes());
+    }
+
+    /** POST /auth/login/start  body: str(username) bytes(blinded)
+     *  resp: bytes(cid) str(aud) u32(mem) u32(iters) u32(par) bytes(salt)
+     *        bytes(nonce) u64(iat) u64(exp) bytes(evaluated)
+     *  Anti-enumeration: ALWAYS OPRF-evaluates (real or decoy key from the same
+     *  seed+username), returns a deterministic per-user salt + constant params,
+     *  and a fresh challenge -- a known and an unknown user are indistinguishable. */
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/login/start')
+    public loginStart(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const username = r.readString();
+        const blinded = r.readBytes();
+        if (!r.ok) return fail();
+        const evaluated = AuthService.oprfEvaluate(username, blinded);
+        if (evaluated.length != AuthService.OPRF_ELEMENT_LEN) return fail();
+
+        const known = AuthDb.accounts.exists(new Username(username));
+        const cid = randomBytes(16);
+        const nonce = randomBytes(32);
+        const iat = nowSecs();
+        const exp = iat + CHALLENGE_TTL_SECS;
+
+        // Persist only for a real account; the response is identical either way,
+        // and login/finish for an unknown user fails generically at consume.
+        if (known) {
+            const c = new Challenge();
+            c.cid = cid;
+            c.username = username;
+            c.nonce = nonce;
+            c.iat = iat;
+            c.exp = exp;
+            AuthDb.challenges.create(new ChallengeId(cid), c);
+        }
+
+        const w = new DataWriter();
+        w.writeBytes(cid);
+        w.writeString(aud());
+        w.writeU32(MEM_KIB);
+        w.writeU32(ITERS);
+        w.writeU32(PAR);
+        w.writeBytes(deriveSalt(username));
+        w.writeBytes(nonce);
+        w.writeU64(iat);
+        w.writeU64(exp);
+        w.writeBytes(evaluated);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/login/finish  body: bytes(cid) bytes(ct) bytes(sig)
+     *  resp: u8(status) [+ bytes(sessionToken) bytes(serverConfirm)] + Set-Cookie */
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/login/finish')
+    public loginFinish(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const cid = r.readBytes();
+        const ct = r.readBytes();
+        const sig = r.readBytes();
+        if (!r.ok) return fail();
+
+        // 1. CONSUME FIRST: atomic fetch-and-delete. Unknown/used/expired => fail.
+        const ch = AuthDb.challenges.getDelete(new ChallengeId(cid));
+        if (ch == null) return fail();
+        if (nowSecs() >= ch.exp) return fail();
+
+        // 2. Rebuild the message from OUR stored values + the client's ct (and
+        //    the bound params + server key id), load the account key, verify.
+        const acct = AuthDb.accounts.get(new Username(ch.username));
+        if (acct == null) return fail();
+        const message = AuthService.buildLoginMessage(
+            ch.username,
+            aud(),
+            cid,
+            ch.nonce,
+            ch.iat,
+            ch.exp,
+            ct,
+            MEM_KIB,
+            ITERS,
+            PAR,
+            AuthService.serverKemKeyId(),
+        );
+        if (!AuthService.verifyLogin(acct.publicKey, message, sig)) return fail();
+
+        // 3. Decapsulate (proves WE hold the KEM key), derive the session key K
+        //    bound to the transcript, and build the confirmation tag the client
+        //    verifies for mutual auth.
+        const sharedSecret = AuthService.mlkemDecapsulate(ct);
+        if (sharedSecret.length != AuthService.SHARED_SECRET_LEN) return fail();
+        const transcriptHash = AuthService.sha256(message);
+        const sessionKey = AuthService.deriveSessionKey(sharedSecret, transcriptHash);
+        const confirm = AuthService.serverConfirmTag(sessionKey, transcriptHash);
+
+        // 4. Success: mint the session (the built-in @user codec, carrying the
+        //    stable ToilUserId) and return {0, sessionToken, confirm}.
+        const domain = authDomain(ctx);
+        const userData = encodeSessionUser(acct.publicKey, ch.username, domain);
+        const w = new DataWriter();
+        w.writeU8(0);
+        w.writeBytes(userData); // opaque session token (the readable user payload)
+        w.writeBytes(confirm);
+        const resp = Response.bytes(w.toBytes());
+        resp.setCookie(AuthService.mintSession(userData, SESSION_TTL_SECS));
+        resp.setCookie(AuthService.userCookie(userData, SESSION_TTL_SECS));
+        return resp;
+    }
+
+    /** GET /auth/me  (@auth: 401 without a valid session) -> the typed user
+     *  (bytes(toilUserId) str(username)). `AuthService.getUser()` is auto-typed
+     *  to the built-in `@user` with no type argument. */
+    @auth
+    @get('/me')
+    public me(_ctx: RouteContext): Response {
+        const u = AuthService.getUser();
+        if (u == null) return Response.text('no session\n', 401);
+        const w = new DataWriter();
+        w.writeBytes(u.toilUserId);
+        w.writeString(u.username);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/logout  (@auth) -> clears both the signed session and the
+     *  readable companion cookie. */
+    @auth
+    @post('/logout')
+    public logout(_ctx: RouteContext): Response {
+        const resp = Response.text('bye\n', 200);
+        resp.setCookie(AuthService.clearSession());
+        resp.setCookie(AuthService.clearUserCookie());
+        return resp;
+    }
+}