toiljs 0.0.34 → 0.0.37

package/examples/basic/server/core/AppHandler.ts

@@ -39,9 +39,252 @@ export class AppHandler extends ToilHandler {
             return Response.text(crypto.randomUUID() + '\n');
         }
 
+        // Cookies. `Cookie`, `Cookies`, `SecureCookies`, and `SameSite` are ambient
+        // globals (no import), exactly like `crypto`. The demo lives in its own
+        // method; the client page is `client/routes/cookies.tsx`.
+        const cookie = this.cookieDemo(req);
+        if (cookie != null) return cookie;
+
         // Unhandled (not a plain notFound): tells the host this server has no
         // answer for the path, so it may serve it itself. Under `toiljs dev`
         // that falls through to Vite (client routes, assets).
         return Response.unhandled();
     }
+
+    /**
+     * The `/api/cookies/*` demo. Each endpoint returns JSON so the client page can
+     * render the actual cookie output. Returns `null` for a non-cookie path.
+     */
+    private cookieDemo(req: Request): Response | null {
+        // GALLERY: the serialized `Set-Cookie` output of every capability, no
+        // round-trip needed. This is the "everything you can do" reference.
+        if (req.path == '/api/cookies/gallery') {
+            const labels = new Array<string>();
+            const cookies = new Array<string>();
+
+            labels.push('basic');
+            cookies.push(Cookie.create('id', 'abc123').serialize());
+            labels.push('percent-encoded (default)');
+            cookies.push(Cookie.create('msg', 'hello world & more!').serialize());
+            labels.push('base64url-encoded');
+            cookies.push(Cookie.create('data', 'hello').withEncoding(CookieEncoding.Base64Url).serialize());
+            labels.push('raw (no encoding)');
+            cookies.push(Cookie.create('tok', 'AAAA.BBBB').withEncoding(CookieEncoding.Raw).serialize());
+            labels.push('Max-Age');
+            cookies.push(Cookie.create('a', 'b').maxAge(3600).serialize());
+            labels.push('Expires (from epoch seconds)');
+            cookies.push(Cookie.create('a', 'b').expires(1700000000).serialize());
+            labels.push('Domain + Path');
+            cookies.push(Cookie.create('a', 'b').domain('example.com').path('/app').serialize());
+            labels.push('Secure + HttpOnly');
+            cookies.push(Cookie.create('a', 'b').secure().httpOnly().serialize());
+            labels.push('SameSite=Strict');
+            cookies.push(Cookie.create('a', 'b').sameSite(SameSite.Strict).serialize());
+            labels.push('SameSite=None (implies Secure)');
+            cookies.push(Cookie.create('a', 'b').sameSite(SameSite.None).serialize());
+            labels.push('Partitioned / CHIPS (implies Secure)');
+            cookies.push(Cookie.create('a', 'b').partitioned().serialize());
+            labels.push('Priority');
+            cookies.push(Cookie.create('a', 'b').priority('High').serialize());
+            labels.push('__Host- prefix (Secure + Path=/ + no Domain)');
+            cookies.push(Cookie.create('sid', 'x').asHostPrefixed().serialize());
+            labels.push('__Secure- prefix');
+            cookies.push(Cookie.create('sid', 'x').asSecurePrefixed().serialize());
+            labels.push('Max-Age clamped to the 400-day cap');
+            cookies.push(Cookie.create('a', 'b').maxAge(99999999).serialize());
+            labels.push('everything at once');
+            cookies.push(
+                Cookie.create('full', 'v')
+                    .domain('example.com')
+                    .path('/')
+                    .maxAge(86400)
+                    .secure()
+                    .httpOnly()
+                    .sameSite(SameSite.Lax)
+                    .partitioned()
+                    .priority('Medium')
+                    .extension('CustomFlag')
+                    .serialize(),
+            );
+
+            let json = '{';
+            for (let i = 0; i < labels.length; i++) {
+                if (i > 0) json += ',';
+                json += '"' + this.esc(labels[i]) + '":"' + this.esc(cookies[i]) + '"';
+            }
+            json += '}';
+            return Response.json(json);
+        }
+
+        // SET: store three real cookies on the browser. A plain visit counter
+        // (readable by JS), an HMAC-signed session, and an AES-256-GCM-encrypted
+        // secret (both HttpOnly, so invisible to JS but readable by the server).
+        if (req.path == '/api/cookies/set') {
+            const prev = req.cookie('visits');
+            let next: string;
+            if (prev == null) next = '1';
+            else next = (this.toI32(prev) + 1).toString();
+
+            const visits = Cookie.create('visits', next).path('/').sameSite(SameSite.Lax).maxAge(86400);
+            const session = SecureCookies.signed(this.demoKey()).seal(
+                Cookie.create('session', 'user-42').httpOnly().sameSite(SameSite.Strict).asHostPrefixed(),
+            );
+            const secret = SecureCookies.encrypted(this.demoKey()).seal(
+                Cookie.create('secret', 'top-secret-value').httpOnly().path('/'),
+            );
+
+            const json =
+                '{"visits":' +
+                next +
+                ',"emitted":["' +
+                this.esc(visits.serialize()) +
+                '","' +
+                this.esc(session.serialize()) +
+                '","' +
+                this.esc(secret.serialize()) +
+                '"]}';
+            return Response.json(json).setCookie(visits).setCookie(session).setCookie(secret);
+        }
+
+        // INSPECT: what the server sees. Parses the `Cookie` header, then verifies
+        // the signed session (HMAC) and decrypts the secret (AES-GCM) server-side.
+        if (req.path == '/api/cookies/inspect') {
+            const raw = req.header('cookie');
+            const jar = req.cookies();
+            const names = jar.names();
+
+            let parsed = '{';
+            for (let i = 0; i < names.length; i++) {
+                if (i > 0) parsed += ',';
+                const val = jar.get(names[i]);
+                parsed += '"' + this.esc(names[i]) + '":"' + this.esc(val == null ? '' : val) + '"';
+            }
+            parsed += '}';
+
+            const session = SecureCookies.signed(this.demoKey()).open(jar, '__Host-session');
+            const secret = SecureCookies.encrypted(this.demoKey()).open(jar, 'secret');
+
+            const json =
+                '{"raw":"' +
+                this.esc(raw == null ? '' : raw) +
+                '","count":' +
+                names.length.toString() +
+                ',"cookies":' +
+                parsed +
+                ',"session":' +
+                (session == null ? 'null' : '"' + this.esc(session) + '"') +
+                ',"secret":' +
+                (secret == null ? 'null' : '"' + this.esc(secret) + '"') +
+                '}';
+            return Response.json(json);
+        }
+
+        // CLEAR: expire the demo cookies (Max-Age=0 + epoch Expires).
+        if (req.path == '/api/cookies/clear') {
+            const json =
+                '{"cleared":["' +
+                this.esc(this.clearString('visits')) +
+                '","' +
+                this.esc(this.clearString('__Host-session')) +
+                '","' +
+                this.esc(this.clearString('secret')) +
+                '"]}';
+            return Response.json(json)
+                .clearCookie('visits')
+                .clearCookie('__Host-session')
+                .clearCookie('secret');
+        }
+
+        // SEAL: sign and encrypt a value (from `?v=`), then recover both and show
+        // that a tampered signature fails to verify. Pure backend crypto, no headers.
+        if (req.path.indexOf('/api/cookies/seal') == 0) {
+            const value = this.queryValue(req.path, 'v', 'hello toiljs');
+            const signer = SecureCookies.signed(this.demoKey());
+            const box = SecureCookies.encrypted(this.demoKey());
+
+            const signed = signer.sign('demo', value);
+            const encrypted = box.encrypt('demo', value);
+            const unsigned = signer.unsign('demo', signed);
+            const decrypted = box.decrypt('demo', encrypted);
+            const tampered = signer.unsign('demo', this.flip(signed));
+
+            const json =
+                '{"value":"' +
+                this.esc(value) +
+                '","signed":"' +
+                this.esc(signed) +
+                '","unsigned":' +
+                (unsigned == null ? 'null' : '"' + this.esc(unsigned) + '"') +
+                ',"encrypted":"' +
+                this.esc(encrypted) +
+                '","decrypted":' +
+                (decrypted == null ? 'null' : '"' + this.esc(decrypted) + '"') +
+                ',"tamperVerifies":' +
+                (tampered == null ? 'false' : 'true') +
+                '}';
+            return Response.json(json);
+        }
+
+        return null;
+    }
+
+    // Demo signing/encryption key: 32 bytes, valid for AES-256-GCM and HMAC. A real
+    // app loads a long random secret from config; never hard-code one.
+    private demoKey(): Uint8Array {
+        return Uint8Array.wrap(String.UTF8.encode('0123456789abcdef0123456789abcdef'));
+    }
+
+    /** The `Set-Cookie` string `clearCookie(name)` emits, for display. */
+    private clearString(name: string): string {
+        return new Cookie(name, '').path('/').maxAge(0).expires(0).serialize();
+    }
+
+    /** Flip the first character (tamper a sealed value while keeping it base64url). */
+    private flip(s: string): string {
+        if (s.length == 0) return 'A';
+        const c = s.charCodeAt(0);
+        return String.fromCharCode(c == 65 ? 66 : 65) + s.substring(1);
+    }
+
+    /** Read `?key=` (or `&key=`) from `path`, percent-decoded, or `fallback`. */
+    private queryValue(path: string, key: string, fallback: string): string {
+        const q = path.indexOf('?');
+        if (q < 0) return fallback;
+        const pairs = path.substring(q + 1).split('&');
+        const prefix = key + '=';
+        for (let i = 0; i < pairs.length; i++) {
+            if (pairs[i].indexOf(prefix) == 0) {
+                return Cookies.decodeValue(pairs[i].substring(prefix.length));
+            }
+        }
+        return fallback;
+    }
+
+    /** Parse a non-negative base-10 integer prefix of `s`. */
+    private toI32(s: string): i32 {
+        let r = 0;
+        for (let i = 0; i < s.length; i++) {
+            const c = s.charCodeAt(i);
+            if (c < 48 || c > 57) break;
+            r = r * 10 + (c - 48);
+        }
+        return r;
+    }
+
+    /** JSON string escaping for the demo's hand-built JSON (incl. all controls). */
+    private esc(s: string): string {
+        const hex = '0123456789abcdef';
+        let out = '';
+        for (let i = 0; i < s.length; i++) {
+            const c = s.charCodeAt(i);
+            if (c == 34) out += '\\"';
+            else if (c == 92) out += '\\\\';
+            else if (c == 10) out += '\\n';
+            else if (c == 13) out += '\\r';
+            else if (c == 9) out += '\\t';
+            else if (c < 0x20) out += '\\u00' + hex.charAt((c >> 4) & 0xf) + hex.charAt(c & 0xf);
+            else out += String.fromCharCode(c);
+        }
+        return out;
+    }
 }

package/examples/basic/server/deco-main.ts

@@ -0,0 +1,18 @@
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { Request, Response, Rest, ToilHandler } from 'toiljs/server/runtime';
+import './DecoCache';
+
+class DecoHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        const hit = Rest.dispatch(req);
+        if (hit != null) return hit;
+        return Response.notFound();
+    }
+}
+
+Server.handler = () => { return new DecoHandler(); };
+export * from 'toiljs/server/runtime/exports';
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}

package/examples/basic/server/main.ts

@@ -8,6 +8,8 @@ import { AppHandler } from './core/AppHandler';
 // run (which only sees the toilconfig entries) building the exact same server.
 import './routes/Players';
 import './routes/Leaderboard';
+import './routes/Session';
+import './routes/PqDemo';
 import './services/Stats';
 import './services/remotes';
 

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

@@ -0,0 +1,184 @@
+import { Method, Response, RouteContext } from 'toiljs/server/runtime';
+import { DataReader, DataWriter } from 'data';
+
+/**
+ * Post-quantum auth, illustrative. Shows how a tenant wires the no-import
+ * `AuthService` global into a challenge-response login. ML-DSA-44 keypairs are
+ * derived client-side from the password (Argon2id); the server only ever stores
+ * and verifies PUBLIC material.
+ *
+ * STORAGE IS THE APP'S, AND THIS EXAMPLE DOES NOT PROVIDE IT. A tenant's wasm
+ * memory is wiped after every request, so the account record and the login
+ * challenges CANNOT live in this module across the two round trips. A real
+ * deployment must back `Accounts` and `Challenges` with an external store, and
+ * the challenge "consume" MUST be a single atomic fetch-and-delete shared by
+ * all instances (Redis `GETDEL`, or SQL `DELETE ... RETURNING`) -- never a
+ * read-then-delete, or a sniffed signature replays across a race. The stubs
+ * below throw to make that explicit; swap them for your store + a host KV/db
+ * binding. The crypto and encoding (`AuthService`) are production-ready; the
+ * orchestration here is a template.
+ *
+ * Wire: every body/response is binary (`DataWriter`/`DataReader`), never JSON.
+ * The client half lives in `toiljs/client` (`Auth.register` / `Auth.login`).
+ */
+
+const AUD = 'toil-demo'; // this service's audience id (server config; never client-echoed)
+const MIN_MEM_KIB = 256 * 1024; // 256 MiB floor (KDF-params-as-credential)
+const MIN_ITERATIONS = 3;
+
+class AccountRecord {
+    username: string = '';
+    salt: Uint8Array = new Uint8Array(0);
+    publicKey: Uint8Array = new Uint8Array(0);
+    memKiB: u32 = 0;
+    iterations: u32 = 0;
+    parallelism: u32 = 0;
+}
+
+class ChallengeRecord {
+    cid: Uint8Array = new Uint8Array(0);
+    username: string = '';
+    nonce: Uint8Array = new Uint8Array(0);
+    iat: u64 = 0;
+    exp: u64 = 0;
+}
+
+// --- the storage the app MUST provide (external; these throw on purpose) -----
+namespace Accounts {
+    export function get(_username: string): AccountRecord | null {
+        throw new Error('wire Accounts to your store');
+    }
+    export function exists(_username: string): bool {
+        throw new Error('wire Accounts to your store');
+    }
+    export function put(_a: AccountRecord): void {
+        throw new Error('wire Accounts to your store');
+    }
+}
+namespace Challenges {
+    export function put(_c: ChallengeRecord): void {
+        throw new Error('wire Challenges to your store');
+    }
+    /** Atomic fetch-and-delete by cid (Redis GETDEL / SQL DELETE RETURNING). */
+    export function consume(_cid: Uint8Array): ChallengeRecord | null {
+        throw new Error('wire Challenges to an ATOMIC store');
+    }
+}
+
+function randomBytes(n: i32): Uint8Array {
+    const b = new Uint8Array(n);
+    crypto.getRandomValues(b);
+    return b;
+}
+
+function fail(): Response {
+    // One generic error on every failure path (anti-enumeration, anti-oracle).
+    return Response.text('auth: request failed\n', 401);
+}
+
+@rest('auth')
+class Auth {
+    /** POST /auth/register/start  body: str(username)
+     *  resp: u8(status=0) + u32(mem) u32(iters) u32(par) bytes(salt) */
+    @post('/register/start')
+    public registerStart(ctx: RouteContext): Response {
+        const username = new DataReader(ctx.request.body).readString();
+        if (Accounts.exists(username)) {
+            return new Response(200, new DataWriter().writeU8(1).toBytes().slice(0)); // taken
+        }
+        const salt = randomBytes(16);
+        const w = new DataWriter();
+        w.writeU8(0);
+        w.writeU32(<u32>MIN_MEM_KIB);
+        w.writeU32(<u32>MIN_ITERATIONS);
+        w.writeU32(1);
+        w.writeBytes(salt);
+        // NOTE: the salt must be persisted with the pending registration so
+        // registerFinish stores the same one; omitted here (no store).
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/register/finish  body: str(username) bytes(pk)  resp: u8(status) */
+    @post('/register/finish')
+    public registerFinish(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const username = r.readString();
+        const pk = r.readBytes();
+        if (Accounts.exists(username) || pk.length != 1312) return fail(); // ML-DSA-44 pk
+        const a = new AccountRecord();
+        a.username = username;
+        a.publicKey = pk;
+        a.memKiB = <u32>MIN_MEM_KIB;
+        a.iterations = <u32>MIN_ITERATIONS;
+        a.parallelism = 1;
+        // a.salt = <the salt issued in registerStart>;
+        Accounts.put(a);
+        return Response.bytes(new DataWriter().writeU8(0).toBytes());
+    }
+
+    /** POST /auth/login/start  body: str(username)
+     *  resp: bytes(cid) str(aud) u32(mem) u32(iters) u32(par) bytes(salt) bytes(nonce) u64(iat) u64(exp) */
+    @post('/login/start')
+    public loginStart(ctx: RouteContext): Response {
+        const username = new DataReader(ctx.request.body).readString();
+        const acct = Accounts.get(username);
+
+        const cid = randomBytes(16);
+        const nonce = randomBytes(32);
+        const iat = <u64>(Date.now() / 1000);
+        const exp = iat + 120;
+
+        // Anti-enumeration: unknown user still gets a fully-formed challenge with
+        // a throwaway salt; the eventual verify just fails.
+        const salt = acct != null ? acct.salt : randomBytes(16);
+        const mem = acct != null ? acct.memKiB : <u32>MIN_MEM_KIB;
+        const iters = acct != null ? acct.iterations : <u32>MIN_ITERATIONS;
+        const par = acct != null ? acct.parallelism : 1;
+
+        if (acct != null) {
+            const c = new ChallengeRecord();
+            c.cid = cid;
+            c.username = username;
+            c.nonce = nonce;
+            c.iat = iat;
+            c.exp = exp;
+            Challenges.put(c);
+        }
+
+        const w = new DataWriter();
+        w.writeBytes(cid);
+        w.writeString(AUD);
+        w.writeU32(mem);
+        w.writeU32(iters);
+        w.writeU32(par);
+        w.writeBytes(salt);
+        w.writeBytes(nonce);
+        w.writeU64(iat);
+        w.writeU64(exp);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/login/finish  body: bytes(cid) bytes(sig)  resp: u8(status) [+ bytes(session)] */
+    @post('/login/finish')
+    public loginFinish(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const cid = r.readBytes();
+        const sig = r.readBytes();
+
+        // 1. CONSUME FIRST: atomic fetch-and-delete. Unknown/used/expired => fail.
+        const ch = Challenges.consume(cid);
+        if (ch == null) return fail();
+        const now = <u64>(Date.now() / 1000);
+        if (now >= ch.exp) return fail();
+
+        // 2. Rebuild the message from OUR stored values (never client-echoed),
+        //    load the account's public key, verify under the login context.
+        const acct = Accounts.get(ch.username);
+        if (acct == null) return fail();
+        const message = AuthService.buildLoginMessage(ch.username, AUD, cid, ch.nonce, ch.iat, ch.exp);
+        if (!AuthService.verifyLogin(acct.publicKey, message, sig)) return fail();
+
+        // 3. Success: mint a session (cookie / token). App-specific.
+        return Response.bytes(new DataWriter().writeU8(0).toBytes());
+    }
+}

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

@@ -0,0 +1,130 @@
+import { Response, RouteContext, SecureCookies, base64UrlEncode, base64UrlDecode } from 'toiljs/server/runtime';
+import { DataReader, DataWriter } from 'data';
+
+import { Account } from './Session';
+
+/**
+ * Post-quantum identity demo (server half), challenge-response.
+ *
+ *   1. GET  /pq/challenge -> the edge mints a fresh nonce + cid + iat/exp and
+ *      returns them PLUS an HMAC-signed `token` over those values. The token is
+ *      the server-issued challenge: signed with a server-only key, it proves
+ *      "the edge issued exactly this" WITHOUT any cross-request storage (the
+ *      guest's memory is wiped every request).
+ *   2. POST /pq/verify   -> the client signs the login message built from the
+ *      SERVER's nonce/cid/iat/exp (ML-DSA-44, derived from the password) and
+ *      returns {sub, token, publicKey, signature}. The edge re-opens the token
+ *      (rejecting a forged or expired one), rebuilds the message from the values
+ *      INSIDE the token (never client-echoed), and verifies the signature via
+ *      `crypto.mldsa_verify` (`AuthService.verifyLogin`).
+ *
+ * The nonce is server-chosen and tamper-proof, and the challenge is time-bound,
+ * so a client cannot pre-sign or substitute its own nonce. What this stateless
+ * form does NOT have is single-use: within the TTL a captured {token, signature}
+ * could be replayed, because that needs an atomic consume against a store (Redis
+ * GETDEL / SQL DELETE RETURNING). The production login in server/routes/Auth.ts
+ * does exactly that; see docs/auth.md. Pairs with client/routes/pq.tsx.
+ */
+
+const AUD = 'pq-demo'; // this demo's audience id (server config; never client-echoed)
+const CHALLENGE_TTL_SECS: u64 = 120;
+
+/** Server-only key for signing challenge tokens (demo constant; a real
+ *  deployment uses a per-deployment secret, like the session secret). */
+function challengeKey(): Uint8Array {
+    return crypto.sha256Text('toil-pq-demo-challenge-key-v1');
+}
+
+function randomBytes(n: i32): Uint8Array {
+    const b = new Uint8Array(n);
+    crypto.getRandomValues(b);
+    return b;
+}
+
+@rest('pq')
+class PqDemo {
+    /** GET /pq/challenge
+     *  resp: str(aud) bytes(cid) bytes(nonce) u64(iat) u64(exp) str(token) */
+    @get('/challenge')
+    public challenge(_ctx: RouteContext): Response {
+        const cid = randomBytes(16);
+        const nonce = randomBytes(32);
+        const iat = Time.nowSeconds();
+        const exp = iat + CHALLENGE_TTL_SECS;
+
+        // Sign (iat, exp, cid, nonce) so /verify can confirm the edge issued
+        // this exact challenge with no stored state.
+        const blob = new DataWriter()
+            .writeU64(iat)
+            .writeU64(exp)
+            .writeBytes(cid)
+            .writeBytes(nonce)
+            .toBytes();
+        const token = SecureCookies.signed(challengeKey()).sign('pqchal', base64UrlEncode(blob));
+
+        const w = new DataWriter();
+        w.writeString(AUD);
+        w.writeBytes(cid);
+        w.writeBytes(nonce);
+        w.writeU64(iat);
+        w.writeU64(exp);
+        w.writeString(token);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /pq/verify
+     *  body: str(sub) str(token) bytes(publicKey 1312) bytes(signature 2420)
+     *  resp: text VALID / INVALID */
+    @post('/verify')
+    public verify(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const sub = r.readString();
+        const token = r.readString();
+        const pk = r.readBytes();
+        const sig = r.readBytes();
+        if (!r.ok) return Response.text('malformed envelope\n', 400);
+
+        // 1. Re-open the challenge token: must be server-issued + untampered.
+        const blobB64 = SecureCookies.signed(challengeKey()).unsign('pqchal', token);
+        if (blobB64 == null) return Response.text('INVALID: forged or unsigned challenge\n', 401);
+        const blob = base64UrlDecode(blobB64);
+        if (blob == null) return Response.text('INVALID: malformed challenge\n', 401);
+        const br = new DataReader(blob);
+        const iat = br.readU64();
+        const exp = br.readU64();
+        const cid = br.readBytes();
+        const nonce = br.readBytes();
+        if (!br.ok) return Response.text('INVALID: malformed challenge\n', 401);
+        if (Time.nowSeconds() >= exp) return Response.text('INVALID: challenge expired\n', 401);
+
+        // TODO(db): single-use consume is NOT implemented yet (no KV/DB host
+        // binding available). The real fix is an ATOMIC consume of `cid` here --
+        // Redis GETDEL / SQL DELETE ... RETURNING -- so a given challenge verifies
+        // at most once. Until that exists, this token is replayable within its
+        // TTL: a captured {token, signature} re-verifies until `exp`. The
+        // production login (server/routes/Auth.ts) shows the atomic-consume shape.
+
+        // 2. Rebuild the message from the SERVER's values (inside the token,
+        //    never client-echoed) and verify the ML-DSA-44 signature.
+        const message = AuthService.buildLoginMessage(sub, AUD, cid, nonce, iat, exp);
+        if (!AuthService.verifyLogin(pk, message, sig)) {
+            return Response.text('INVALID: signature did not verify\n', 401);
+        }
+
+        // 3. FULL AUTH: a valid post-quantum proof logs the user in. Mint the
+        //    signed session for the proven `sub` via the @user codec, plus the
+        //    readable companion. Every `@auth` route now recognises this user
+        //    and `AuthService.getUser()` returns `{ username: sub, ... }`.
+        const account = new Account();
+        account.username = sub;
+        account.admin = sub == 'root';
+        const userData = account.encode();
+        const resp = Response.text(
+            'VALID: ML-DSA-44 (FIPS 204) verified; session established (@auth ready)\n',
+            200,
+        );
+        resp.setCookie(AuthService.mintSession(userData, 3600));
+        resp.setCookie(AuthService.userCookie(userData, 3600));
+        return resp;
+    }
+}

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

@@ -0,0 +1,74 @@
+import { Response, RouteContext } from 'toiljs/server/runtime';
+import { DataReader, DataWriter } from 'data';
+
+/**
+ * Session demo: the `@user` / `@auth` / typed `AuthService.getUser()` surface.
+ *
+ * `@user` declares the authenticated user's shape; it becomes a binary codec
+ * (like `@data`) AND registers the type of `AuthService.getUser()` everywhere,
+ * server and generated client, with NO type argument.
+ *
+ * `@auth` on a route (or a whole `@rest` class) makes the generated dispatcher
+ * verify a valid signed session BEFORE the handler runs (401 otherwise).
+ *
+ * The session is an HMAC-signed `__Host-` cookie minted by `AuthService.mintSession`.
+ * In a real app you mint it in `Auth.loginFinish` AFTER `verifyLogin` succeeds;
+ * this `/session/dev-login` mints one for a caller-named demo user so the flow is
+ * runnable without the external account store the login example stubs out.
+ *
+ * The server secret defaults to a well-known DEV placeholder; a real deployment
+ * calls `AuthService.setSecret(...)` once at startup (see server/main.ts).
+ */
+
+// @user: the authenticated-user shape. Exactly one per program. Exported so
+// other routes (the PQ login) can mint a session via its generated codec.
+@user
+export class Account {
+    username: string = '';
+    admin: bool = false;
+    score: u64 = 0;
+}
+
+@rest('session')
+class Session {
+    /** POST /session/dev-login  body: str(username)  -> sets the session cookie.
+     *  DEV ONLY: a real app mints in loginFinish after the signature verifies. */
+    @post('/dev-login')
+    public devLogin(ctx: RouteContext): Response {
+        const username = new DataReader(ctx.request.body).readString();
+        const u = new Account();
+        u.username = username;
+        u.admin = username == 'root';
+        u.score = 0;
+
+        const data = u.encode();
+        const resp = Response.text('ok\n', 200);
+        resp.setCookie(AuthService.mintSession(data, 3600)); // HttpOnly signed session
+        resp.setCookie(AuthService.userCookie(data, 3600)); // readable companion (client getUser)
+        return resp;
+    }
+
+    /** GET /session/me  (@auth: 401 without a valid session) -> the typed user.
+     *  `AuthService.getUser()` is auto-typed to `Account` 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.writeString(u.username);
+        w.writeBool(u.admin);
+        w.writeU64(u.score);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /session/logout  (@auth) -> clears the session 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;
+    }
+}