toiljs 0.0.84 → 0.0.86

package/docs/auth/configuration.md

@@ -0,0 +1,94 @@
+# Configuring auth for production
+
+Built-in auth runs locally with **zero configuration** — it falls back to published, insecure DEV secrets
+so `toiljs dev` Just Works. **A deployment MUST replace all three secrets and pin its KEM key.** This page
+is the checklist.
+
+## The secrets
+
+Auth reads these from the tenant environment store (locally, `.env.secrets`; on the edge, the per-host
+secure env). They resolve **lazily** the first time auth runs, so no startup wiring is needed.
+
+| Key | What it is | Dev fallback |
+| --- | --- | --- |
+| `AUTH_SESSION_SECRET` | HMAC-SHA256 key that signs the session cookie. Must be identical on every edge instance (a cookie minted anywhere must verify everywhere). | a public constant — **anyone can forge a session** |
+| `AUTH_OPRF_SEED` | Master seed for the per-user OPRF salt key. Rotating it invalidates every password (users must re-register). | a hashed public constant |
+| `AUTH_KEM_SK` | The server's ML-KEM-768 **secret** key (hex). Its public half is what the client encapsulates to. | a pinned dev key pair |
+
+```bash
+# .env.secrets   (gitignored; mode 0600 on the edge, NEVER under hosts/, NEVER in the .wasm)
+AUTH_SESSION_SECRET=…64 hex chars (32 bytes)…
+AUTH_OPRF_SEED=…64 hex chars (32 bytes)…
+AUTH_KEM_SK=…hex of an ML-KEM-768 secret key…
+```
+
+### Generating them
+
+`AUTH_SESSION_SECRET` and `AUTH_OPRF_SEED` are just 32 random bytes each:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+`AUTH_KEM_SK` is an ML-KEM-768 key pair. Generate it and keep BOTH halves — the secret goes in the env, the
+public half is pinned in the client (next section):
+
+```ts
+import { ml_kem768 } from '@dacely/noble-post-quantum/ml-kem';
+const { secretKey, publicKey } = ml_kem768.keygen();
+console.log('AUTH_KEM_SK =', Buffer.from(secretKey).toString('hex'));
+console.log('client serverKemPublicKey =', Buffer.from(publicKey).toString('hex'));
+```
+
+## Pin the client's KEM public key
+
+The browser must know the server's genuine KEM public key to run the mutual-auth handshake — this is the
+anti-phishing anchor. The `toiljs/client` `Auth` helper ships with the **dev** key pinned, so a deployment
+MUST pass its own:
+
+```ts
+import { Auth } from 'toiljs/client';
+
+const SERVER_KEM_PUBLIC_KEY = /* the publicKey bytes from AUTH_KEM_SK */;
+
+await Auth.login(username, password, { serverKemPublicKey: SERVER_KEM_PUBLIC_KEY });
+await Auth.register(username, password, { serverKemPublicKey: SERVER_KEM_PUBLIC_KEY });
+```
+
+Ship the public key with your client bundle (it's public — safe to embed). If it doesn't match the server's
+`AUTH_KEM_SK`, login's `serverConfirm` check fails and the client aborts.
+
+## Optional: audience & domain
+
+Both are optional and have sensible defaults; set them for stability across host aliases:
+
+| Key | Meaning | Default |
+| --- | --- | --- |
+| `TOIL_AUTH_AUDIENCE` | The service audience bound into the signed login message. | `"toil"` |
+| `TOIL_AUTH_DOMAIN` | The `domain` input of the stable `ToilUserId` (`sha256(pubkey ‖ username ‖ domain)`). | the request `Host` header, else `localhost` |
+
+Set `TOIL_AUTH_DOMAIN` explicitly if your site answers on multiple hostnames — otherwise the same user could
+get different `ToilUserId`s from different aliases. Once users exist, changing it changes everyone's id, so
+pick it before launch.
+
+## Argon2id strength (known limitation)
+
+The built-in controller currently uses **demo-light** Argon2id params (32 MiB, 2 iterations, 1 lane) so it
+stays responsive in a browser tab. These are baked into the shipped controller today; **config-driven
+tuning is a planned follow-up.** For a high-value production deployment you should either wait for the
+config knob or hand-write your own controller with `≥ 256 MiB / ≥ 3 iterations`. The OPRF still provides the
+primary offline-attack resistance regardless, but raise these before protecting anything sensitive.
+
+The client always derives against whatever params the server returns in `/login/start`, so when the config
+knob lands you can raise them server-side with **no client change**.
+
+## Deploy checklist
+
+- [ ] `AUTH_SESSION_SECRET` set (32 random bytes), identical on every edge instance.
+- [ ] `AUTH_OPRF_SEED` set (32 random bytes).
+- [ ] `AUTH_KEM_SK` set (an ML-KEM-768 secret key), and its **public** half pinned in the client via
+      `serverKemPublicKey`.
+- [ ] `TOIL_AUTH_DOMAIN` set if you serve multiple hostnames (stable `ToilUserId`).
+- [ ] (Recommended) Argon2id params reviewed for your threat model.
+
+The CLI doctor warns when `server.auth` is on and the secrets are missing — run it before you ship.

package/docs/auth/extending.md

@@ -0,0 +1,170 @@
+# Extending & integrating auth
+
+Built-in auth is deliberately opinionated so the common case is one line. This page covers the identity
+you build ON — `ToilUserId` — and how to go beyond the defaults: keying your own data on a user, a custom
+user shape, and hand-writing auth from the same primitives.
+
+## `ToilUserId`
+
+The stable, tenant-scoped user identity: `sha256(mldsaPublicKey ‖ identifier ‖ domain)`, a 256-bit value.
+It's a **global** (no import), like `crypto`.
+
+```ts
+// Read the current user's id in any handler (gate on hasSession() — see the null note below).
+const id: ToilUserId = AuthService.userId()!;
+
+// Or derive one yourself.
+const id2 = ToilUserId.derive(mldsaPublicKey, 'alice@example.com', 'acme.dacely.com');
+```
+
+| Member | Description |
+| --- | --- |
+| `ToilUserId.derive(pk, identifier, domain)` | Derive from an ML-DSA public key + email/username + tenant domain. Deterministic. |
+| `ToilUserId.fromBytes(b)` | Rebuild from a 32-byte digest (from `toBytes()` or storage). |
+| `toBytes(): Uint8Array` | The 32 identity bytes. |
+| `toHex(): string` | Lowercase 64-char hex — a convenient string key. |
+| `isZero(): bool` | True for the unset / anonymous id. |
+| `equals(other): bool` | Value equality. |
+| `a == b` / `a != b` | Overloaded value comparison — **O(1)** (four `u64` word compares, no byte loop, no allocation). |
+
+```ts
+const a = ToilUserId.derive(pk, 'alice', 'acme.com');
+const b = ToilUserId.derive(pk, 'alice', 'acme.com');
+const c = ToilUserId.derive(pk, 'bob',   'acme.com');
+a == b;   // true  — same inputs, same id
+a != c;   // true  — different user
+```
+
+> **Null-check gotcha:** because `ToilUserId` overloads `==`, `AuthService.userId() == null` does NOT
+> type-check (`==` expects a `ToilUserId`). Gate with `AuthService.hasSession()` and then `userId()!`, or
+> compare with `getUser()` (a plain nullable). `===` is reference identity in AssemblyScript and is not
+> overloadable — use `==` for value equality.
+
+## Keying your own data on the user
+
+`toilUserId` is the right key for per-user data — it's stable across sessions/devices and opaque. Use the
+hex as a string key, or the bytes in a `@data` key class:
+
+```ts
+@data
+class UserKey {
+    id: Uint8Array = new Uint8Array(0);      // toilUserId bytes
+    constructor(id: Uint8Array = new Uint8Array(0)) { this.id = id; }
+}
+
+@data class Profile { displayName: string = ''; bio: string = ''; }
+
+@database
+class AppDb {
+    @collection static profiles: Documents<UserKey, Profile>;
+}
+
+@rest('profile')
+class ProfileApi {
+    @auth
+    @post('/')
+    public save(ctx: RouteContext): Response {
+        const key = new UserKey(AuthService.userId()!.toBytes());
+        const p = Profile.decode(ctx.request.body);
+        AppDb.profiles.enqueue(key, p);   // upsert this user's profile
+        return Response.text('saved\n');
+    }
+}
+```
+
+## A custom user shape — opt out and hand-write
+
+Built-in auth ships the single `@user` (`{ toilUserId, username }`), and there is exactly **one `@user` per
+program**. If you need a richer authenticated user (roles, a display name, a tenant), do **not** enable
+`server.auth`; hand-write a controller and your own `@user` using the same primitives. The
+`examples/basic` app does exactly this — copy `server/routes/Auth.ts` + `server/routes/Session.ts` as your
+starting point. The shape:
+
+```ts
+@user
+class Account {
+    username: string = '';
+    admin: bool = false;
+    score: u64 = 0;
+}
+
+// After verifyLogin succeeds, mint your own session payload:
+resp.setCookie(AuthService.mintSession(account.encode(), 3600));
+resp.setCookie(AuthService.userCookie(account.encode(), 3600));
+```
+
+You still get `@auth`, `AuthService.getUser()` (typed to YOUR `@user`), and every crypto primitive — you're
+just choosing your own routes and user fields. You can still derive a `ToilUserId` yourself and put it in
+your `@user` if you want the stable id.
+
+## Adding email verification / 2FA
+
+Layer a second factor on top of the session with `TwoFactor` (stateless email codes — no DB; see
+[email](../email.md)). Typical flow: after login, require a verified email before granting access to
+sensitive routes.
+
+```ts
+@rest('2fa')
+class TwoFactorApi {
+    // Step 1: email a code to the logged-in user, hand back the signed token.
+    @auth @post('/send')
+    public send(): Response {
+        const email = /* the user's email — e.g. their username, or a stored profile field */;
+        const ch = TwoFactor.send(email, 'login');    // emails the code, returns { token, status }
+        return Response.bytes(new DataWriter().writeString(ch.token).toBytes());
+    }
+
+    // Step 2: verify the code the user typed against the token.
+    @auth @post('/verify')
+    public verify(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const token = r.readString(); const email = r.readString(); const code = r.readString();
+        if (!TwoFactor.verify(token, email, code)) return Response.text('bad code\n', 401);
+        // Mark this session 2FA-verified: re-mint the session with a flag in your own @user, or store a
+        // per-user "verified" record keyed on AuthService.userId().
+        return Response.text('verified\n');
+    }
+}
+```
+
+`TwoFactor` gives integrity + expiry but not single-use (a code re-verifies within its TTL); keep the TTL
+short. For a branded email, use `TwoFactor.issue(...)` (returns the code without sending) + your own
+`Emails.*` template. Call `TwoFactor.setSecret(...)` once at startup in production.
+
+## The `AuthService` primitive reference
+
+Everything the built-in controller is built from, available for hand-written auth. All are ambient globals
+(no import).
+
+**Sessions & cookies**
+- `mintSession(userData: Uint8Array, ttlSecs?: u64): Cookie` — the signed `__Host-toil_sess` cookie.
+- `userCookie(userData, ttlSecs?): Cookie` — the readable `__Secure-toil_user` companion.
+- `clearSession(): Cookie` / `clearUserCookie(): Cookie`.
+- `hasSession(): bool` — the `@auth` predicate.
+- `getSessionBytes(): Uint8Array | null` — the verified `@user` payload bytes.
+- `getUser(): <your @user> | null` — decoded, typed to your `@user`.
+- `userId(): ToilUserId | null` — the stable id (built-in `@user` layout).
+- `setSecret(secret: Uint8Array)` — override the session HMAC key programmatically.
+
+**Post-quantum login crypto**
+- `oprfEvaluate(username, blinded): Uint8Array` — server-keyed OPRF eval.
+- `buildRegisterMessage(username, pk)` / `verifyRegister(pk, msg, sig): bool` — proof-of-possession.
+- `buildLoginMessage(sub, aud, cid, nonce, iat, exp, ct, memKiB, iterations, parallelism, serverKemKeyId)`
+  / `verifyLogin(pk, msg, sig): bool`.
+- `mlkemDecapsulate(ct): Uint8Array` · `serverKemKeyId(): Uint8Array`.
+- `deriveSessionKey(sharedSecret, transcriptHash)` · `serverConfirmTag(sessionKey, transcriptHash)` — the
+  mutual-auth confirmation.
+- `sha256(data): Uint8Array`.
+- `setOprfSeed(seed)` · `setServerKemSecretKey(sk)` · `setServerKemPublicKey(pk)` — override the seeds/keys.
+- Sizes: `PUBLIC_KEY_LEN`, `SIGNATURE_LEN`, `OPRF_ELEMENT_LEN`, `KEM_CIPHERTEXT_LEN`, `SHARED_SECRET_LEN`, …
+
+**Related globals** — `TwoFactor` (email codes; see [email](../email.md)), `RateLimitService` (used by
+`@ratelimit`), `Environment` (the secret store).
+
+## Two ways in, one behavior
+
+The config flag and the import are identical at build time — both make the build append the shipped
+`@user` + `@rest('auth')` controller to the toilscript **entry** set, where their decorators weave and the
+`@rest` class self-mounts. (A framework decorator source only weaves as an entry; that's why a plain
+`import` of the controller isn't enough on its own — the marker import is detected by the build, which does
+the entry injection.) This is why built-in auth needs no runtime registration call.

package/docs/auth/how-it-works.md

@@ -0,0 +1,138 @@
+# How Toil auth works
+
+Toil auth is a **post-quantum, password-based, mutually-authenticated** login. The design goal: the user
+types a password, but the server never sees it, never stores it, and can't be phished into leaking a
+verifier — and every primitive is quantum-resistant.
+
+This page explains the protocol. You do not need to understand it to use auth (see [Usage](./usage.md)),
+but you should understand the guarantees before you ship.
+
+## The building blocks
+
+| Primitive | Role |
+| --- | --- |
+| **OPRF** (RFC 9497, ristretto255-SHA512) | A *server-keyed* salt. The client blinds its password, the server evaluates it under a per-user key, the client unblinds. The result can't be computed without the server, so a stolen database can't be brute-forced offline. |
+| **Argon2id** | Stretches the OPRF output into key material (memory-hard, GPU/ASIC-resistant). Runs in the browser. |
+| **ML-DSA-44** (FIPS 204) | The user's identity key pair is *derived* from the Argon2id output. The server stores only the **public** key. Login is proved by an ML-DSA signature. |
+| **ML-KEM-768** (FIPS 203) | Key encapsulation on login: the server proves it holds its KEM secret by returning a confirmation tag only derivable from the decapsulated shared secret → **mutual** auth (anti-phishing). |
+| **HMAC-SHA256** | Signs the session cookie (`AUTH_SESSION_SECRET`). |
+
+> The whole thing is sometimes called an *aPAKE* (asymmetric password-authenticated key exchange). Do not
+> call it OPAQUE — this is Toil's own OPRF + KEM + signature construction.
+
+## What the server stores
+
+Per account, in ToilDB (`@database AuthDb`):
+
+- `username`, a deterministic `salt`, the **ML-DSA public key**, and the Argon2id params.
+
+That's it. **No password, no password hash, no verifier that can be brute-forced without the OPRF key.**
+Login challenges are a second collection, consumed exactly once (atomic `getDelete`).
+
+## Registration
+
+```
+ Browser (client)                                   Toil edge (server)
+ ─────────────────                                  ──────────────────
+ blind(password)                                    OPRF key = f(seed, username)
+        │  username, blinded                                │
+        │ ───────── POST /auth/register/start ───────────► │
+        │                                                   │  evaluated = OPRF(blinded)
+        │  ◄──── {mem,iters,par, salt, evaluated} ───────── │  (salt is deterministic per user)
+        │                                                   │
+ unblind → oprfOut                                          │
+ seed  = Argon2id(oprfOut, salt, params)                    │
+ (pk, sk) = ML-DSA-44.keygen(seed)                          │
+ proof = ML-DSA.sign(sk, "register|username|pk")            │
+        │  username, pk, proof                              │
+        │ ───────── POST /auth/register/finish ──────────► │
+        │                                                   │  verifyRegister(pk, msg, proof)  ✓ proof-of-possession
+        │  ◄──────────── {status: 0 ok | 1 taken} ──────── │  store AuthAccount{username, salt, pk, params}
+```
+
+The server never learns the password or the secret key `sk` — only the public key `pk` and a proof the
+client holds the matching `sk`. A duplicate username returns a **distinguishable** `status = 1` (so the UI
+can say "taken, log in instead"); everything else fails generically.
+
+## Login (with mutual auth)
+
+```
+ Browser (client)                                   Toil edge (server)
+ ─────────────────                                  ──────────────────
+ blind(password)                                            │
+        │  username, blinded                                │
+        │ ───────── POST /auth/login/start ──────────────► │  evaluated = OPRF(blinded)   (ALWAYS, even unknown user)
+        │                                                   │  if known: store Challenge{cid, nonce, iat, exp}
+        │  ◄─ {cid, aud, params, salt, nonce, iat, exp, ── │  (identical response whether the user exists or not)
+        │       evaluated}                                  │
+ unblind → Argon2id → (pk, sk) = ML-DSA.keygen              │
+ (ct, ssС) = ML-KEM-768.encapsulate(serverKemPublicKey)     │
+ msg = "login|username|aud|cid|nonce|iat|exp|ct|params|kid" │
+ sig = ML-DSA.sign(sk, msg)                                 │
+        │  cid, ct, sig                                     │
+        │ ───────── POST /auth/login/finish ─────────────► │  ch = challenges.getDelete(cid)   (consume once; check exp)
+        │                                                   │  rebuild msg from OUR stored values + ct
+        │                                                   │  verifyLogin(acct.pk, msg, sig)   ✓ it's really this user
+        │                                                   │  ssS = ML-KEM.decapsulate(ct)     ✓ we hold the KEM key
+        │                                                   │  K = deriveSessionKey(ssS, H(msg))
+        │  ◄──── {0, sessionToken, serverConfirm} ──────── │  serverConfirm = tag(K, H(msg))
+        │      + Set-Cookie: __Host-toil_sess=…             │  mint session cookie
+ verify serverConfirm using ssC   ✓ the server is genuine   │
+```
+
+Two verifications, both required:
+1. **The server verifies the client** — the ML-DSA signature over a message bound to the challenge, the
+   Argon2id params, and the server's KEM key id. Replays fail (the challenge is consumed).
+2. **The client verifies the server** — the `serverConfirm` tag is derivable only from the ML-KEM shared
+   secret, which only the holder of the KEM secret key can decapsulate. A phishing site can't forge it.
+
+## Anti-enumeration
+
+`/login/start` behaves identically for a known and an unknown user: it always runs the OPRF (a decoy key
+for unknown users), returns a **deterministic** per-user salt and constant params, and a fresh challenge.
+The challenge is persisted only for a real account, and `/login/finish` fails generically at consume for an
+unknown user. So an attacker can't probe which usernames exist. Every failure path returns the same
+`401 auth: request failed`.
+
+## Sessions & cookies
+
+On successful login the server mints **two** cookies:
+
+- **`__Host-toil_sess`** — the authoritative session. HMAC-SHA256 signed with `AUTH_SESSION_SECRET`,
+  `HttpOnly`, `Secure`, `SameSite=Lax`. It carries the `@user` codec payload. `@auth` and
+  `AuthService.getUser()` open + verify this cookie server-side; a forged or tampered cookie fails.
+- **`__Secure-toil_user`** — a **readable** companion carrying the same payload, so the browser can show
+  "logged in as …" via the client's `getUser()`. The server **never trusts it** — it is display-only.
+
+Each request runs in a fresh wasm instance, but the signed cookie is self-contained, so no server-side
+session store is needed. `AUTH_SESSION_SECRET` must be identical across every edge instance (it is, via the
+env store) so a cookie minted anywhere verifies everywhere.
+
+## The stable user identity — `ToilUserId`
+
+At login the server derives a stable, tenant-scoped id and stores it in the session (the first field of the
+built-in `@user`):
+
+```
+toilUserId = SHA-256( mldsaPublicKey ‖ username ‖ domain )      // 256 bits
+```
+
+- **Stable:** same login key + username on the same tenant `domain` → same id, forever, across sessions
+  and devices. Key your own data on it.
+- **Opaque + one-way:** it's a hash — safe to store, log, or expose without leaking the key or the address.
+- Read it anywhere with `AuthService.userId()`. See [Extending](./extending.md#toiluserid) for the
+  `ToilUserId` API (O(1) `==` / `!=`, `toHex()`, …).
+
+## Threat-model summary
+
+- **Server database stolen** → attacker gets public keys + salts, not passwords. Brute-forcing needs the
+  OPRF key (server-side) *and* Argon2id work per guess.
+- **Server compromised / malicious** → still can't recover passwords (only public keys) and can't forge a
+  past session without `AUTH_SESSION_SECRET`.
+- **Phishing site** → can't produce the `serverConfirm` tag (no KEM secret), so a correct client aborts.
+- **Quantum adversary** → ML-DSA + ML-KEM are post-quantum; the OPRF/Argon2id/HMAC pieces are classical but
+  not the long-term identity or key-exchange.
+- **Replay** → challenges are single-use (`getDelete`) with a short TTL.
+
+Residual responsibilities are yours: set the [secrets](./configuration.md), pin your deployment's KEM
+public key in the client, and raise the Argon2id params for production.

package/docs/auth/index.md

@@ -0,0 +1,102 @@
+# Authentication
+
+Toil ships a complete, **post-quantum password login** you turn on with one line. No passwords on your
+server, no third-party identity provider, no hand-written crypto: enable it and you get a `/auth/*` API,
+signed sessions, `@auth`-guarded routes, and a stable per-user identity.
+
+```ts
+// toil.config.ts
+import { defineConfig } from 'toiljs/compiler';
+
+export default defineConfig({
+    server: { auth: true }, // ← mounts the full /auth/* API + sessions
+});
+```
+
+That is the whole setup. The build appends the framework's auth controller to your server, so `/auth/*`
+is live and `@auth` works everywhere.
+
+## What you get
+
+| Endpoint | Purpose |
+| --- | --- |
+| `POST /auth/register/start` · `/register/finish` | Create an account (password never leaves the browser) |
+| `POST /auth/login/start` · `/login/finish` | Log in; sets a signed session cookie |
+| `GET /auth/me` *(`@auth`)* | The current user (`toilUserId` + `username`) |
+| `POST /auth/logout` *(`@auth`)* | Clear the session |
+
+Plus, in your own code:
+
+- **`@auth`** on any route (or a whole `@rest` class) → 401 unless there's a valid session.
+- **`AuthService.getUser()`** → the typed logged-in user.
+- **`AuthService.userId()`** → the stable [`ToilUserId`](./extending.md#toiluserid) (a 256-bit id you can
+  key your data on).
+- **The client** — `import { Auth } from 'toiljs/client'`, then `Auth.register(username, password)` /
+  `Auth.login(username, password)`. It does all the browser-side crypto and talks to `/auth/*` for you.
+
+## A login page in full
+
+```tsx
+// client/routes/login.tsx
+import { useState } from 'react';
+import { Auth } from 'toiljs/client';
+
+export default function Login() {
+    const [u, setU] = useState('');
+    const [p, setP] = useState('');
+    const [msg, setMsg] = useState('');
+
+    const register = async () => {
+        try { await Auth.register(u, p); setMsg('registered — now log in'); }
+        catch (e) { setMsg(parseError(e)); }
+    };
+    const login = async () => {
+        try { await Auth.login(u, p); setMsg('logged in'); }   // sets the session cookie
+        catch (e) { setMsg(parseError(e)); }
+    };
+
+    return (
+        <main>
+            <input value={u} onChange={(e) => setU(e.currentTarget.value)} placeholder="username" />
+            <input value={p} type="password" onChange={(e) => setP(e.currentTarget.value)} placeholder="password" />
+            <button onClick={register}>Register</button>
+            <button onClick={login}>Log in</button>
+            <p>{msg}</p>
+        </main>
+    );
+}
+```
+
+```ts
+// server/routes/Secret.ts — a route only a logged-in user can reach
+import { Response } from 'toiljs/server/runtime';
+
+@rest('secret')
+class Secret {
+    @auth                     // 401 without a valid session
+    @get('/')
+    public secret(): Response {
+        const user = AuthService.getUser()!;      // typed: { toilUserId, username }
+        return Response.text('hello ' + user.username + '\n');
+    }
+}
+```
+
+That's a real, production-grade auth system — the password is stretched with Argon2id in the browser into
+an ML-DSA-44 key pair, your server only ever stores a public key, and login is a mutually-authenticated
+ML-KEM-768 challenge. You didn't write any of it.
+
+## Where to go next
+
+- **[How it works](./how-it-works.md)** — the protocol (OPRF + Argon2id + ML-DSA + ML-KEM), sessions,
+  cookies, and the `ToilUserId`, with sequence diagrams.
+- **[Usage](./usage.md)** — enabling it, the client API, guarding routes, reading the user, the full wire
+  contract of each endpoint.
+- **[Configuration](./configuration.md)** — the secrets a deployment MUST set, the audience/domain, tuning
+  Argon2id, and the deploy checklist.
+- **[Extending & integrating](./extending.md)** — `ToilUserId`, keying your own data on a user, a custom
+  user shape / opting out, and the `AuthService` primitive reference.
+
+> **One rule before you ship:** built-in auth runs with **insecure DEV fallback secrets** so it Just Works
+> locally. A deployment MUST set `AUTH_SESSION_SECRET`, `AUTH_OPRF_SEED`, and `AUTH_KEM_SK`. See
+> [Configuration](./configuration.md).