toiljs 0.0.85 → 0.0.87

package/server/auth/AuthController.ts

@@ -0,0 +1,336 @@
+import { Response, RouteContext } from 'toiljs/server/runtime';
+import { DataReader, DataWriter } from 'data';
+
+/**
+ * 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 for whatever `@user` this program has (built-in or the app's own
+        //    extended one). `__toilEncodeAuthUser` is injected by `--authUser`: it constructs the `@user`
+        //    (app fields at their defaults), sets the reserved identity, and encodes it. The stable
+        //    ToilUserId is derived from the login public key + username + tenant domain.
+        const domain = authDomain(ctx);
+        const toilUserId = ToilUserId.derive(acct.publicKey, ch.username, domain).toBytes();
+        const userData = __toilEncodeAuthUser(toilUserId, ch.username);
+        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;
+    }
+}

package/server/auth/AuthUser.ts

@@ -0,0 +1,23 @@
+/**
+ * The framework's built-in authenticated-user shape for `server.auth` (the zero-config `/auth/*` PQ-login
+ * controller). Shipped as a SOURCE file the `server.auth` build APPENDS to the toilscript entry set in
+ * BUILTIN mode (the app declares no `@user` of its own), so its `@user` decorator weaves as a user entry.
+ *
+ * The class is deliberately EMPTY. The build runs with `--authUser`, which injects the reserved
+ * `toilUserId` + `username` identity fields (toilUserId FIRST, so `AuthService.userId()` reads it straight
+ * from the session codec) and a shape-agnostic `__toilEncodeAuthUser(id, username)` global the controller
+ * uses to mint a session. This keeps the wire layout identical whether the user is this built-in shape or an
+ * app's own.
+ *
+ * EXTEND mode: an app that wants a richer authenticated user just declares its OWN `@user` (with extra
+ * fields like `admin` or `tenant`). The build detects it, extends THAT class with the same reserved fields,
+ * and does not append this file. Either way there is exactly one `@user` per program.
+ *
+ * Named `SessionUser`, NOT `AuthUser`: the toilscript `@user` transform injects a `@global class AuthUser
+ * extends <thisClass>`, so naming this class `AuthUser` would self-extend (a compile error).
+ */
+
+// @user: the authenticated-user shape. The reserved `toilUserId` + `username` fields are INJECTED by the
+// build (`--authUser`); do not declare them here.
+@user
+class SessionUser {}

package/server/auth/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Escape-hatch marker for the built-in auth surface. A bare
+ * `import 'toiljs/server/auth';` in `server/main.ts` is the lighter-weight opt-in
+ * (an alternative to the canonical `server: { auth: true }` config flag): the
+ * toiljs build DETECTS this import and appends the shipped `@user` shape +
+ * `@rest('auth')` controller to the toilscript ENTRY set, so their decorators
+ * weave and the controller self-mounts at `/auth/*`.
+ *
+ * This module is intentionally EMPTY (a pure marker). Framework-shipped
+ * decorator sources under `node_modules` only weave when handed to toilscript as
+ * explicit ENTRIES; a transitive `import` resolves them under the `~lib/` LIBRARY
+ * prefix, where `@data`/`@rest`/`@user` do NOT weave — and, worse, would then
+ * collide with the entry-injected copies as duplicate modules. So the barrel must
+ * NOT itself import the controller; the build does the entry injection instead.
+ */
+export {};

package/server/globals/auth.ts

@@ -278,6 +278,37 @@ export namespace AuthService {
         return bytes == null ? null : __toilDecodeAuthUser(bytes);
     }
 
+    /**
+     * The stable, tenant-scoped {@link ToilUserId} of the current request's
+     * authenticated user, or `null` if there is no valid session. Recovered from
+     * the session codec directly (the built-in `server.auth` `@user` shape puts
+     * the 32-byte id FIRST, see `server/auth/AuthUser.ts`), so this stays generic
+     * — it does NOT depend on the app's injected `@user` type carrying a
+     * `toilUserId` field — while matching the built-in layout. An app whose custom
+     * `@user` does not lead with the id should read `getUser()` instead.
+     *
+     * NULL CHECK: `ToilUserId` overloads `==` for value equality, so `userId() ==
+     * null` does NOT type-check. Gate on {@link hasSession} first (then the result
+     * is non-null), e.g. `if (AuthService.hasSession()) { const id =
+     * AuthService.userId()!; ... }`.
+     */
+    export function userId(): ToilUserId | null {
+        const bytes = getSessionBytes();
+        if (bytes == null) return null;
+        return ToilUserId.fromBytes(new DataReader(bytes).readBytes());
+    }
+
+    /**
+     * A no-op discoverability marker for the built-in auth surface. The REAL
+     * opt-in is `server: { auth: true }` in `toil.config.ts` (or a bare
+     * `import 'toiljs/server/auth'`), which appends the shipped `@user` shape +
+     * `@rest('auth')` controller to the build's toilscript entry set so they weave
+     * and self-mount at `/auth/*`. `enable()` exists so `AuthService.enable()` in
+     * `main.ts` type-checks and the surface is discoverable via this namespace; it
+     * mounts nothing on its own.
+     */
+    export function enable(): void {}
+
     /**
      * Mint a signed session cookie carrying `userData` (the `@user` codec bytes,
      * i.e. `myUser.encode()`), valid for `ttlSecs`. Set it on the response with

package/server/globals/userid.ts

@@ -0,0 +1,107 @@
+/**
+ * `ToilUserId` — the stable, tenant-scoped 256-bit user identity.
+ *
+ * Derived once as `sha256(mldsaPublicKey || identifier || domain)`, so the SAME user (same ML-DSA login
+ * public key + the same email/username) on the SAME tenant domain always maps to the SAME id — independent
+ * of session, cookie, or device. It is opaque and one-way (a hash), so it is safe to store, log, or use as
+ * a stable database key without leaking the underlying key or address.
+ *
+ * Backed by four 64-bit words (a 256-bit value), NOT a byte array, so equality is four word compares with
+ * early-out — no allocation, no byte loop. `==` / `!=` are overloaded to value equality, and `equals()` is
+ * the explicit form. (`===` in AssemblyScript is reference identity and is NOT overloadable; use `==` for
+ * value equality.)
+ *
+ * A global (no import), like `crypto` / `AuthService`. `AuthService` mints the current user's id from the
+ * login key + identifier + the request's tenant domain, so `@auth` handlers can key on a stable user.
+ */
+export class ToilUserId {
+    constructor(
+        public w0: u64 = 0,
+        public w1: u64 = 0,
+        public w2: u64 = 0,
+        public w3: u64 = 0,
+    ) {}
+
+    /**
+     * Derive the id from the user's ML-DSA public key, their identifier (email or username), and the
+     * tenant `domain` (the site on dacely). Deterministic: identical inputs → identical id. The three
+     * inputs are concatenated in order and SHA-256'd; length-framing is unnecessary because the ML-DSA
+     * public key is a FIXED length (1312 bytes for ML-DSA-44), so the boundary before `identifier` is
+     * unambiguous, and `domain` is the trusted tail supplied by the host, not the user.
+     */
+    static derive(mldsaPublicKey: Uint8Array, identifier: string, domain: string): ToilUserId {
+        const id = Uint8Array.wrap(String.UTF8.encode(identifier));
+        const dom = Uint8Array.wrap(String.UTF8.encode(domain));
+        const buf = new Uint8Array(mldsaPublicKey.length + id.length + dom.length);
+        buf.set(mldsaPublicKey, 0);
+        buf.set(id, mldsaPublicKey.length);
+        buf.set(dom, mldsaPublicKey.length + id.length);
+        return ToilUserId.fromBytes(crypto.sha256(buf));
+    }
+
+    /** Build from a 32-byte digest. Bytes past 32 are ignored; a shorter array zero-pads the tail. */
+    static fromBytes(b: Uint8Array): ToilUserId {
+        if (b.length >= 32) {
+            const p = b.dataStart;
+            return new ToilUserId(load<u64>(p, 0), load<u64>(p, 8), load<u64>(p, 16), load<u64>(p, 24));
+        }
+        const tmp = new Uint8Array(32);
+        tmp.set(b, 0);
+        const p = tmp.dataStart;
+        return new ToilUserId(load<u64>(p, 0), load<u64>(p, 8), load<u64>(p, 16), load<u64>(p, 24));
+    }
+
+    /** The 32-byte identity (the original SHA-256 digest bytes; wasm is little-endian, so this round-trips). */
+    toBytes(): Uint8Array {
+        const out = new Uint8Array(32);
+        const p = out.dataStart;
+        store<u64>(p, this.w0, 0);
+        store<u64>(p, this.w1, 8);
+        store<u64>(p, this.w2, 16);
+        store<u64>(p, this.w3, 24);
+        return out;
+    }
+
+    /** Lowercase hex, 64 chars. */
+    toHex(): string {
+        const b = this.toBytes();
+        const HEX = '0123456789abcdef';
+        let s = '';
+        for (let i = 0; i < 32; i++) {
+            const v = <i32>b[i];
+            s += HEX.charAt(v >> 4);
+            s += HEX.charAt(v & 0xf);
+        }
+        return s;
+    }
+
+    /** True when unset (the all-zero id, e.g. an absent / anonymous user). */
+    isZero(): bool {
+        return (this.w0 | this.w1 | this.w2 | this.w3) == 0;
+    }
+
+    /** Value equality: four u64 compares, short-circuiting. O(1), no allocation. */
+    @inline
+    equals(other: ToilUserId): bool {
+        return (
+            this.w0 == other.w0 &&
+            this.w1 == other.w1 &&
+            this.w2 == other.w2 &&
+            this.w3 == other.w3
+        );
+    }
+
+    /** `a == b` value equality (overloaded). */
+    @operator('==')
+    @inline
+    eq(other: ToilUserId): bool {
+        return this.equals(other);
+    }
+
+    /** `a != b` value inequality (overloaded). */
+    @operator('!=')
+    @inline
+    ne(other: ToilUserId): bool {
+        return !this.equals(other);
+    }
+}

package/src/compiler/config.ts

@@ -140,6 +140,16 @@ export interface ServerConfig {
     readonly email?: EmailBackendConfig;
     /** Which layer the dev process emulates. Default `all`. */
     readonly nodeMode?: DevNodeMode;
+    /**
+     * Built-in auth. `true` opts into the framework's post-quantum login: the
+     * build appends a shipped `@rest('auth')` controller + its `@user` shape to
+     * the toilscript entry set, so the app gets the full `/auth/register|login`
+     * API + sessions (`/auth/me`, `/auth/logout`) with no hand-written boilerplate.
+     * Default `false`. (The escape hatch `import 'toiljs/server/auth'` in
+     * `server/main.ts` does the same without this flag.) An app that opts in must
+     * NOT declare its own `@user` — the built-in owns the single per-program one.
+     */
+    readonly auth?: boolean;
     /** Daemon (L4) config mirror (dev / self-host). */
     readonly daemon?: DaemonConfig;
     /**
@@ -202,6 +212,8 @@ export interface ResolvedToilConfig {
     readonly email: EmailBackendConfig | null;
     /** Which layer the dev process emulates (dev / self-host). Default `all`. */
     readonly nodeMode: DevNodeMode;
+    /** Whether the built-in `/auth/*` PQ-login controller is compiled + mounted. */
+    readonly auth: boolean;
     /** Daemon (L4) config mirror (dev / self-host), every field resolved. */
     readonly daemon: ResolvedDaemonConfig;
     /** Self-host HTTP worker count for `toiljs start`. */
@@ -279,6 +291,7 @@ export async function loadConfig(
         seo: client.seo ?? null,
         email: user.server?.email ?? null,
         nodeMode: resolveNodeMode(user.server?.nodeMode),
+        auth: user.server?.auth === true,
         daemon: resolveDaemonConfig(user.server?.daemon),
         threads: resolveThreads(user.server?.threads),
         runtimePath: resolveRuntimePath(),

package/src/compiler/docs.ts

@@ -10,45 +10,23 @@ import { TOIL_DOCS } from './toil-docs.generated.js';
 
 export { TOIL_DOCS };
 
-/**
- * One-line summaries for the pointer files' bullet list, keyed by `.toil/docs/` filename.
- * A doc with no entry here still appears in the list (using its `# ` heading as the label),
- * so adding a `docs/*.md` is picked up automatically without re-listing it by hand.
- */
-const DOC_SUMMARIES: Record<string, string> = {
-    'index.md': 'overview and project layout',
-    'getting-started.md': 'the two halves, build/dev, and the request lifecycle',
-    'routing.md': 'file-based routing, nested layouts, loading / error files',
-    'client.md': 'the `Toil` global, Link / NavLink, router hooks',
-    'styling.md': 'CSS / Sass / Less / Stylus / Tailwind (via `toiljs configure`)',
-    'server.md': 'the toilscript server target, `@data` / `@remote` / `@rest`',
-    'ssr.md': 'server-side rendering (`ssr = true`, hole markers, the server `render`)',
-    'rpc.md': '`@service` / `@remote` and the generated typed client',
-    'data.md': 'the `@data` decorator and the binary codec',
-    'caching.md': 'the `@cache` decorator and `Response.cache(...)`',
-    'ratelimit.md': 'the `@ratelimit` decorator',
-    'auth.md': '`@auth` guards, `@user`, sessions, the client half',
-    'environment.md': '`Environment.get` / `getSecure` config + secrets',
-    'email.md': '`EmailService`, templates, provider config',
-    'cookies.md': 'the `Cookie` builder, `SecureCookies`, signing / encryption',
-    'crypto.md': 'the synchronous `crypto` global and `crypto.subtle`',
-    'time.md': '`Time.nowMillis()` / `Time.nowSeconds()`',
-    'cli.md': 'toiljs CLI commands',
-};
-
-/** First-level `# ` heading of a Markdown doc, used as a fallback bullet label. */
+/** First-level `# ` heading of a Markdown doc, used as the bullet label. */
 function docTitle(content: string): string {
     const m = content.match(/^#\s+(.+)$/m);
     return m ? m[1].trim() : '';
 }
 
 /**
- * The pointer files' bullet list, derived from the generated `TOIL_DOCS` map so it never
- * drifts from the docs actually written into `.toil/docs/` (no second hand-kept list).
+ * The pointer files' navigation list, derived from the generated `TOIL_DOCS` map so it never
+ * drifts from the docs actually written into `.toil/docs/` (no second hand-kept list). We list
+ * the section landing pages (each folder's `README.md`, plus the root one) rather than all
+ * fifty-plus pages; every landing links onward to its own topic pages, and
+ * `.toil/docs/README.md` is the root map.
  */
 const DOC_POINTERS = Object.keys(TOIL_DOCS)
+    .filter((name) => name === 'README.md' || name.endsWith('/README.md'))
     .map((name) => {
-        const summary = DOC_SUMMARIES[name] ?? docTitle(TOIL_DOCS[name]);
+        const summary = docTitle(TOIL_DOCS[name]);
         return `- \`.toil/docs/${name}\`${summary ? `, ${summary}` : ''}`;
     })
     .join('\n');
@@ -59,8 +37,9 @@ const POINTER_BODY = `# toiljs, AI assistant guide
 This is a **toiljs** project, a full-stack React framework (React + Vite client, file-based
 routing, and a toilscript→WebAssembly server).
 
-**Before editing this project, read the generated documentation in \`.toil/docs/\`.** It describes
-the conventions you must follow:
+**Before editing this project, read the generated documentation in \`.toil/docs/\`, starting at
+\`.toil/docs/README.md\`.** It describes the conventions you must follow. The sections, each a
+folder whose \`README.md\` links onward to its topic pages:
 
 ${DOC_POINTERS}
 
@@ -113,6 +92,10 @@ export function writeDocs(toilDir: string): void {
     const dir = path.join(toilDir, 'docs');
     fs.mkdirSync(dir, { recursive: true });
     for (const [name, content] of Object.entries(TOIL_DOCS)) {
-        fs.writeFileSync(path.join(dir, name), content);
+        const dest = path.join(dir, name);
+        // Doc keys can be nested (e.g. "auth/configuration.md"), so ensure the
+        // file's parent directory exists before writing it.
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, content);
     }
 }

package/src/compiler/generate.ts

@@ -125,8 +125,12 @@ export const TOIL_SERVER_ENV_DTS =
     `declare class TwoFactorIssue { code: string; token: string; constructor(code: string, token: string); }\n` +
     `declare class TwoFactorChallenge { token: string; status: EmailStatus; constructor(token: string, status: EmailStatus); }\n` +
     `declare namespace TwoFactor { const DEFAULT_TTL_SECS: u64; const DEFAULT_DIGITS: i32; function setSecret(secret: Uint8Array): void; function issue(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorIssue; function send(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorChallenge; function verify(token: string, recipient: string, code: string): bool; }\n` +
-    `declare namespace AuthService { const SESSION_COOKIE: string; const USER_COOKIE: string; const LOGIN_CONTEXT: string; const PUBLIC_KEY_LEN: i32; const SIGNATURE_LEN: i32; const DEFAULT_SESSION_TTL_SECS: u64; function setSecret(secret: Uint8Array): void; function hasSession(): bool; function getSessionBytes(): Uint8Array | null; function getUser(): __ToilAuthUser | null; function mintSession(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearSession(): Cookie; function userCookie(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearUserCookie(): Cookie; function buildLoginMessage(sub: string, aud: string, cid: Uint8Array, nonce: Uint8Array, iat: u64, exp: u64, ciphertext: Uint8Array, memKiB: u32, iterations: u32, parallelism: u32, serverKemKeyId: Uint8Array): Uint8Array; function verifyLogin(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; const KEM_CIPHERTEXT_LEN: i32; const KEM_SECRET_KEY_LEN: i32; const KEM_PUBLIC_KEY_LEN: i32; const SHARED_SECRET_LEN: i32; const OPRF_ELEMENT_LEN: i32; const OPRF_SEED_LEN: i32; const SESSION_KEY_LABEL: string; const SERVER_CONFIRM_LABEL: string; function setOprfSeed(seed: Uint8Array): void; function setServerKemSecretKey(secretKey: Uint8Array): void; function setServerKemPublicKey(publicKey: Uint8Array): void; function serverKemKeyId(): Uint8Array; function oprfEvaluate(username: string, blinded: Uint8Array): Uint8Array; function mlkemDecapsulate(ciphertext: Uint8Array): Uint8Array; function sha256(data: Uint8Array): Uint8Array; function deriveSessionKey(sharedSecret: Uint8Array, transcriptHash: Uint8Array): Uint8Array; function serverConfirmTag(sessionKey: Uint8Array, transcriptHash: Uint8Array): Uint8Array; const REGISTER_CONTEXT: string; function buildRegisterMessage(username: string, publicKey: Uint8Array): Uint8Array; function verifyRegister(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; }\n` +
-    `interface __ToilAuthUser {}\n`;
+    `declare namespace AuthService { const SESSION_COOKIE: string; const USER_COOKIE: string; const LOGIN_CONTEXT: string; const PUBLIC_KEY_LEN: i32; const SIGNATURE_LEN: i32; const DEFAULT_SESSION_TTL_SECS: u64; function setSecret(secret: Uint8Array): void; function hasSession(): bool; function getSessionBytes(): Uint8Array | null; function getUser(): __ToilAuthUser | null; function userId(): ToilUserId | null; function enable(): void; function mintSession(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearSession(): Cookie; function userCookie(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearUserCookie(): Cookie; function buildLoginMessage(sub: string, aud: string, cid: Uint8Array, nonce: Uint8Array, iat: u64, exp: u64, ciphertext: Uint8Array, memKiB: u32, iterations: u32, parallelism: u32, serverKemKeyId: Uint8Array): Uint8Array; function verifyLogin(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; const KEM_CIPHERTEXT_LEN: i32; const KEM_SECRET_KEY_LEN: i32; const KEM_PUBLIC_KEY_LEN: i32; const SHARED_SECRET_LEN: i32; const OPRF_ELEMENT_LEN: i32; const OPRF_SEED_LEN: i32; const SESSION_KEY_LABEL: string; const SERVER_CONFIRM_LABEL: string; function setOprfSeed(seed: Uint8Array): void; function setServerKemSecretKey(secretKey: Uint8Array): void; function setServerKemPublicKey(publicKey: Uint8Array): void; function serverKemKeyId(): Uint8Array; function oprfEvaluate(username: string, blinded: Uint8Array): Uint8Array; function mlkemDecapsulate(ciphertext: Uint8Array): Uint8Array; function sha256(data: Uint8Array): Uint8Array; function deriveSessionKey(sharedSecret: Uint8Array, transcriptHash: Uint8Array): Uint8Array; function serverConfirmTag(sessionKey: Uint8Array, transcriptHash: Uint8Array): Uint8Array; const REGISTER_CONTEXT: string; function buildRegisterMessage(username: string, publicKey: Uint8Array): Uint8Array; function verifyRegister(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; }\n` +
+    `interface __ToilAuthUser {}\n` +
+    `declare class ToilUserId { w0: u64; w1: u64; w2: u64; w3: u64; constructor(w0?: u64, w1?: u64, w2?: u64, w3?: u64); static derive(mldsaPublicKey: Uint8Array, identifier: string, domain: string): ToilUserId; static fromBytes(b: Uint8Array): ToilUserId; toBytes(): Uint8Array; toHex(): string; isZero(): bool; equals(other: ToilUserId): bool; }\n` +
+    // Built-in auth (server.auth): injected by --authUser. Mints a session for the program's single @user
+    // (built-in or the app's extended one): constructs it, sets the reserved identity, encodes it.
+    `declare function __toilEncodeAuthUser(toilUserId: Uint8Array, username: string): Uint8Array;\n`;
 
 /**
  * Returns a `./`-prefixed, **extensionless** POSIX module specifier from `.toil` to `abs`, for use