toiljs 0.0.115 → 0.0.117

package/docs/auth/configuration.md

@@ -1,105 +0,0 @@
-# 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.
-
-## Email confirmation
-
-Two plain env vars (tenant-readable, like `PUBLIC_BASE_URL`) control the built-in email-verification flow. They are separate on purpose: sending a verify email at registration is one decision, blocking login until confirmed is another.
-
-| Key | What it does |
-| --- | --- |
-| `AUTH_EMAIL_CONFIRMATION` | Registration emails a one-time confirm link (`/confirm#token=…`) and stores the account **unconfirmed**. Login is **not** blocked: the user can sign in, and you nudge them to verify. Use this for "verify at signup, but let people in". |
-| `AUTH_REQUIRE_EMAIL_CONFIRMATION` | The stricter form: does everything above AND **refuses login** until the email is confirmed (a distinguishable status the client surfaces as `EmailNotConfirmedError`, so the UI can prompt "confirm your email / resend"). Implies `AUTH_EMAIL_CONFIRMATION`. On the managed edge this is force-set from the per-domain Dacely setting. |
-
-With neither set, accounts are auto-confirmed at registration and no confirm email is sent. The one-time link is delivered by email; in `toiljs dev` it is drawn in the console (no mailer needed). Both use the standard non-enumerating responses (a generic 200 that never reveals whether an address exists).
-
-## 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/emails.md

@@ -1,92 +0,0 @@
-# Customizing the auth emails
-
-Built-in auth sends three transactional emails: the email-verification link, the password-reset link, and the two-factor code. Each ships with a plain, working default. You can replace any of them with your own branded template, and you never touch the auth code to do it.
-
-## The three emails
-
-| Email | When it sends | The value it gives your template |
-| --- | --- | --- |
-| Email verification | On register, when email confirmation is on | `link` (the confirm URL) |
-| Password reset | On `POST /auth/reset/request` | `link` (the reset URL) |
-| Two-factor code | On login or 2FA setup, for the email method | `code` (the numeric code) and `action` (the flow phrase) |
-
-The defaults are intentionally minimal so a fresh project sends real, correct mail with no setup. To match your brand, override them.
-
-## How to override
-
-Drop a React template in your project's `emails/` folder with the reserved name for that email. If the file exists, the build uses it; if not, the default stands. This is the same `emails/*.tsx` system you use for your own mail (see [Email](../services/email.md)), so you get full markup and inline CSS.
-
-| Reserved file | Overrides | Prop it must read |
-| --- | --- | --- |
-| `emails/auth-confirm.tsx` | Email verification | `link` |
-| `emails/auth-reset.tsx` | Password reset | `link` |
-| `emails/auth-2fa.tsx` | Two-factor code | `code`, `action` |
-
-Each template is a default-exported React component. Read the one prop it is given, and it becomes a `{{token}}` hole the edge fills per send. Reading any other prop renders empty, so the build warns you.
-
-```tsx
-// emails/auth-confirm.tsx  ->  overrides the email-verification message.
-export const subject = 'Verify your Acme account';
-
-export default function AuthConfirm({ link }: { link: string }) {
-    return (
-        <div style={{ fontFamily: 'system-ui', padding: 24 }}>
-            <h1 style={{ color: '#cb9820' }}>Welcome to Acme</h1>
-            <p>Tap below to verify your email and finish signing up.</p>
-            <p>
-                <a
-                    href={link}
-                    style={{ background: '#cb9820', color: '#fff', padding: '10px 18px', borderRadius: 8, textDecoration: 'none' }}
-                >
-                    Verify my email
-                </a>
-            </p>
-            <p style={{ color: '#666', fontSize: 13 }}>Or paste this link: {link}</p>
-        </div>
-    );
-}
-```
-
-The reset template works the same way with the `link` prop.
-
-## The subject line
-
-For verification and reset, set the subject with `export const subject = '...'`. Leave it out and the default subject is used (`Confirm your account`, `Reset your password`).
-
-The two-factor email is different. It serves three flows (signing in, enabling 2FA, and turning 2FA off), so besides the `code` it also gets an `action` prop: the framework fills it with the flow phrase, `sign in`, `enable two-factor authentication`, or `turn off two-factor authentication`. Write it into a sentence like "Enter this code to {action}." and the one template reads correctly for every flow. The subject is likewise set by the framework and stays contextual, so a `subject` export in this file is ignored.
-
-```tsx
-// emails/auth-2fa.tsx  ->  overrides the 2FA code message (subject is contextual).
-export default function Auth2fa({ code, action }: { code: string; action: string }) {
-    return (
-        <div style={{ fontFamily: 'system-ui', padding: 24, textAlign: 'center' }}>
-            <p>Your Acme verification code:</p>
-            <p style={{ fontSize: 32, fontWeight: 700, letterSpacing: 6 }}>{code}</p>
-            <p>Enter it to {action}.</p>
-            <p style={{ color: '#666' }}>It expires in a few minutes.</p>
-        </div>
-    );
-}
-```
-
-## What you can and cannot put in
-
-Each template is rendered once, at build time, into a static string of HTML with your styles inlined, and the prop becomes a fill hole. So a fixed layout and inline styles work, but per-send logic does not: a `{items.map(...)}` or a conditional runs at build, not per email. For these three messages that is all you need, one link or one code.
-
-The only values auth hands each template are the ones in the table above (`link`, or `code` plus `action` for 2FA). There is no user name, no app name, no expiry value. Write those into the template text directly.
-
-Styling rules are the same as any toiljs email: write inline `style={{ ... }}`, or import a stylesheet and its rules are inlined for you. A bare CSS import with no inlining has no effect in an email client. See [Email](../services/email.md) for the details.
-
-## Delivery stays safe
-
-You cannot weaken the security of these flows by overriding a template. Every auth email is sent detached (fire-and-forget), so the response time never reveals whether an address maps to an account. That holds whether the message is the default or your override. Overriding only changes what the email looks like, never how it is sent.
-
-## Where the templates go
-
-There is nothing to import and nothing to register. The build reads `emails/auth-*.tsx`, bakes the effective templates into the compiled server, and the auth controller sends them. Changing a template and rebuilding (or saving under `toiljs dev`) is all it takes.
-
-## Related
-
-- [Email](../services/email.md): the full `emails/*.tsx` system, `EmailService`, and `EmailTemplate`.
-- [Configuration](./configuration.md): the auth secrets and the email provider a deployment must set.
-- [Usage](./usage.md): enabling auth, the client API, and guarding routes.

package/docs/auth/extending.md

@@ -1,202 +0,0 @@
-# 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);
-        // Save this user's profile. create is insert-only, so the first save creates
-        // the record and later saves overwrite the existing one with enqueue.
-        if (!AppDb.profiles.create(key, p)) {
-            AppDb.profiles.enqueue(key, p);
-        }
-        return Response.text('saved\n');
-    }
-}
-```
-
-## Extending the user: add your own fields
-
-Built-in auth reserves exactly two fields on the authenticated user: `toilUserId` and `username`. To carry
-more (a role, a display name, a tenant), just declare your OWN `@user` in your server code while
-`server.auth` is on. The build detects it and **extends** it: it injects the reserved `toilUserId` +
-`username` as the first two fields and mints sessions for your shape automatically. You do not opt out of
-anything, and there is still exactly one `@user` per program.
-
-```ts
-@user
-class Account {
-    admin: bool = false;
-    displayName: string = '';
-    tenant: string = '';
-    // toilUserId + username are INJECTED by the build; do not declare them here.
-}
-```
-
-Rules:
-
-- Do **not** declare `toilUserId` or `username` yourself. They are reserved and injected; declaring either is
-  a compile error (`'username' is reserved by built-in auth`).
-- Your `@user` must be default-constructible (give every field an initializer), like any `@data` class.
-
-`AuthService.getUser()` is now typed to YOUR shape:
-
-```ts
-const user = AuthService.getUser();   // { toilUserId, username, admin, displayName, tenant } | null
-```
-
-**Populating your fields.** Login fills `toilUserId` + `username`; your extra fields start at their declared
-defaults (`admin = false`, and so on). The built-in controller cannot know your business fields, so you set
-them yourself on one of your own `@auth` routes by reading the user, updating it, and re-minting the session:
-
-```ts
-@rest('account')
-class AccountApi {
-    @auth @post('/promote')
-    public promote(): Response {
-        const user = AuthService.getUser()!;
-        user.admin = true;
-        const resp = Response.text('promoted\n');
-        resp.setCookie(AuthService.mintSession(user.encode()));   // re-sign the session with the new fields
-        resp.setCookie(AuthService.userCookie(user.encode()));    // update the readable companion cookie
-        return resp;
-    }
-}
-```
-
-If you would rather hand-write the whole controller instead, you still can: do **not** enable `server.auth`,
-and build your own `@user` + routes from the [AuthService primitives](#the-authservice-primitive-reference)
-below. But for most apps, extending is all you need.
-
-## Adding email verification / 2FA
-
-Layer a second factor on top of the session with `TwoFactor` (stateless email codes, no DB; see
-[email](../services/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](../services/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

@@ -1,138 +0,0 @@
-# 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.