toiljs 0.0.85 → 0.0.86

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).

package/docs/auth/usage.md

@@ -0,0 +1,188 @@
+# Using auth
+
+## 1. Enable it
+
+Either the config flag (canonical) or a one-line import — both do the same thing (the build appends the
+framework's auth controller + user shape to your server as compiled entries, so `/auth/*` self-mounts):
+
+```ts
+// toil.config.ts  — canonical
+export default defineConfig({ server: { auth: true } });
+```
+
+```ts
+// server/main.ts  — escape hatch (equivalent)
+import 'toiljs/server/auth';
+```
+
+There is also an `AuthService.enable()` no-op you can call for discoverability, but enabling is done by the
+flag/import above (it happens at build time). Turn it off by removing the flag/import — with neither, no
+`/auth` routes and no accounts collection are generated. It is strictly opt-in.
+
+## 2. The client
+
+`toiljs/client` ships the browser half — it runs the OPRF blinding, Argon2id, ML-DSA keygen, and ML-KEM
+encapsulation, and talks to `/auth/*`. You never touch the crypto.
+
+```ts
+import { Auth } from 'toiljs/client';
+
+// Create an account. Throws on a taken username or a transport error.
+await Auth.register(username, password);
+
+// Log in. On success the browser holds the signed session cookie; subsequent
+// requests to @auth routes are authorized automatically.
+await Auth.login(username, password);
+```
+
+Options (second argument, `AuthOptions`):
+
+```ts
+await Auth.login(username, password, {
+    baseUrl: '/auth',                 // default; change if you mount elsewhere
+    serverKemPublicKey: MY_KEM_PUB,   // REQUIRED in production — pin your deployment's KEM key
+});
+```
+
+> **Production:** the client ships with the DEV KEM public key pinned. A real deployment MUST pass its own
+> `serverKemPublicKey` (derived from `AUTH_KEM_SK`). See [Configuration](./configuration.md).
+
+## 2b. Client-side: who's logged in, and protecting pages
+
+`register`/`login` set the session cookies; to *render* login state on the client, use the generated
+`getUser()` (emitted from the built-in `@user`). It reads the **readable** `__Secure-toil_user` companion
+cookie and returns the typed user or `null` — instant, no network call. It is **display-only**; the server
+still enforces access via `@auth`, so never trust it for authorization.
+
+```tsx
+import { getUser } from 'shared/server';   // generated; typed to the built-in @user
+
+function Nav() {
+    const user = getUser();                // { toilUserId, username } | null
+    return user
+        ? <span>Hi {user.username} <button onClick={logout}>Log out</button></span>
+        : <a href="/login">Log in</a>;
+}
+
+async function logout() {
+    await fetch('/auth/logout', { method: 'POST' });
+    location.href = '/login';              // cookies are cleared; bounce to login
+}
+```
+
+Gate a whole client route by redirecting when there's no session:
+
+```tsx
+export default function Dashboard() {
+    const user = getUser();
+    if (user == null) { location.href = '/login'; return null; }   // not logged in -> to /login
+    return <main>Welcome, {user.username}</main>;
+}
+```
+
+The authoritative check is still the server: any data this page fetches should come from an `@auth` route,
+so a user who forged/deleted the readable cookie sees the redirect OR a `401`, never real data.
+
+## 2c. Handling errors
+
+`Auth.register` / `Auth.login` reject with a message you can show. The important distinguishable cases:
+
+```ts
+try {
+    await Auth.register(username, password);
+} catch (e) {
+    const m = String(e);
+    if (m.includes('already registered')) setError('That username is taken — log in instead.');
+    else setError('Could not register, try again.');
+}
+
+try {
+    await Auth.login(username, password);
+} catch {
+    // Wrong password OR unknown user both fail generically (anti-enumeration) — one message.
+    setError('Incorrect username or password.');
+}
+```
+
+- **Username taken** → `register` throws `auth: username already registered (log in instead)` (a
+  distinguishable case so you can guide the user).
+- **Wrong password / unknown user** → `login` throws generically (`auth: request failed`) — by design,
+  the two are indistinguishable, so use ONE "incorrect username or password" message.
+- **Rate limited** → after 5 attempts / 60s a `429` surfaces as the same generic throw; back off and tell
+  the user to wait.
+
+## 3. Guard your routes — `@auth`
+
+Put `@auth` on a route method or a whole `@rest` class. The generated dispatcher checks for a valid signed
+session **before** your handler runs and returns `401` otherwise. `@auth` is unchanged by built-in auth —
+it's the same decorator you'd use with hand-written auth.
+
+```ts
+@rest('account')
+class AccountApi {
+    @auth                       // this route needs a session
+    @get('/settings')
+    public settings(): Response { /* … */ }
+
+    @get('/public')             // this one is open
+    public open(): Response { /* … */ }
+}
+
+@auth                           // …or guard the ENTIRE class
+@rest('admin')
+class AdminApi { /* every route requires a session */ }
+```
+
+## 4. Read the current user
+
+Inside any handler:
+
+```ts
+// The typed logged-in user (the built-in `@user`: toilUserId + username), or null.
+const user = AuthService.getUser();
+if (user != null) {
+    user.username;    // string
+    user.toilUserId;  // Uint8Array(32) — the stable id bytes
+}
+
+// The stable identity as a ToilUserId (gate on hasSession() first — see note).
+if (AuthService.hasSession()) {
+    const id = AuthService.userId()!;   // ToilUserId
+    // key your own data on id (see Extending)
+}
+```
+
+> `ToilUserId` overloads `==`, so `AuthService.userId() == null` does not type-check. Gate with
+> `AuthService.hasSession()` and then use `userId()!`, or use `getUser()` and null-check that.
+
+## 5. The endpoint wire contract
+
+You normally use the `Auth` client, but the raw endpoints are binary (`DataWriter`/`DataReader`, never
+JSON):
+
+| Route | Request body | Response |
+| --- | --- | --- |
+| `POST /auth/register/start` | `str(username) bytes(blinded)` | `u8(0) u32(mem) u32(iters) u32(par) bytes(salt) bytes(evaluated)` |
+| `POST /auth/register/finish` | `str(username) bytes(pubkey) bytes(proof)` | `u8(status)` — `0` ok, `1` username taken |
+| `POST /auth/login/start` | `str(username) bytes(blinded)` | `bytes(cid) str(aud) u32(mem) u32(iters) u32(par) bytes(salt) bytes(nonce) u64(iat) u64(exp) bytes(evaluated)` |
+| `POST /auth/login/finish` | `bytes(cid) bytes(ct) bytes(sig)` | `u8(0) bytes(sessionToken) bytes(serverConfirm)` + `Set-Cookie`, or `u8(≠0)` on failure |
+| `GET /auth/me` *(`@auth`)* | — | `bytes(toilUserId) str(username)` |
+| `POST /auth/logout` *(`@auth`)* | — | `200` + cookie-clearing `Set-Cookie` |
+
+Rate limiting: every register/login POST carries `@ratelimit(SlidingWindow, 5, 60)` (5 requests / 60s per
+client) out of the box, so brute-force is throttled before it reaches the crypto.
+
+## 6. Under `toiljs dev`
+
+Everything runs locally with **zero setup**: the dev server emulates the ToilDB account/challenge storage
+and the ML-DSA/ML-KEM/OPRF host functions in process, and the auth secrets fall back to insecure DEV
+values. Register and login span requests (the accounts persist for the dev session). You'll see a warning
+that `AUTH_SESSION_SECRET` is unset — that's expected in dev; set it before you deploy (see
+[Configuration](./configuration.md)).
+
+## 7. `Server.REST.auth.*`
+
+Because the controller is a normal `@rest('auth')` class, a typed `Server.REST.auth.*` fetch client is
+generated for free (`me`, `logout`, and the register/login methods). Use it for `/me` and `/logout`; but
+**drive register/login through `toiljs/client` `Auth`**, not the generated client — only the `Auth` helper
+runs the required browser-side OPRF/Argon2id/ML-DSA/ML-KEM crypto.

package/docs/auth.md

@@ -1,5 +1,11 @@
 # Auth, sessions, and `@user`
 
+> **Just want login working?** Enable **built-in auth** with one line — `server: { auth: true }` — and
+> you get the whole `/auth/*` API + sessions with no code. Start at **[the auth guide](./auth/index.md)**
+> ([how it works](./auth/how-it-works.md) · [usage](./auth/usage.md) · [configuration](./auth/configuration.md) ·
+> [extending](./auth/extending.md)). This page is the deeper reference on the underlying primitives, used
+> both by built-in auth and when you hand-write your own.
+
 toiljs ships **Toil PQ-Auth**: a post-quantum password login where the password
 never leaves the browser and the server stores only public verifier material.
 On top of it sit HMAC-signed session cookies, a `@auth` route guard, and a

package/examples/basic/client/routes/analytics.tsx

@@ -25,8 +25,10 @@ const METRICS = [
     { id: 13, label: 'DB ops', unit: 'count' },
     { id: 26, label: 'Stream bytes out', unit: 'bytes' },
     { id: 39, label: 'Memory bandwidth', unit: 'bytes' },
-    { id: 41, label: 'Connected streams', unit: 'count' },
-    { id: 43, label: 'Committed memory', unit: 'bytes' }
+    { id: 41, label: 'Cache hits', unit: 'count' },
+    { id: 42, label: 'Cache misses', unit: 'count' },
+    { id: 43, label: 'Connected streams', unit: 'count' },
+    { id: 45, label: 'Committed memory', unit: 'bytes' }
 ] as const;
 
 // AnalyticsRange (mirrors the server enum).
@@ -157,20 +159,28 @@ export default function AnalyticsDemo() {
 
             <section style={{ marginTop: 24 }}>
                 <h2>Snapshot</h2>
+                <p style={{ color: '#64748b', marginTop: 0 }}>
+                    All <code>total*</code> values are all-time cumulative totals (since the site was first seen);
+                    the <code>live</code> gauges are the current level, and the windows are the current rate-limit
+                    usage vs the plan cap (cap ∞ = unlimited).
+                </p>
                 <button onClick={loadStats}>Load my site analytics</button>
                 {err && <p style={{ color: '#f87171' }}>{err}</p>}
                 {stats && (
                     <ul>
-                        <li>requests: {String(stats.requests)}</li>
-                        <li>bytes out (L1): {String(stats.bytesOutL1)}</li>
-                        <li>bytes in (L1): {String(stats.bytesInL1)}</li>
-                        <li>gas used: {String(stats.gasUsed)}</li>
-                        <li>2xx responses: {String(stats.status2xx)}</li>
-                        <li>db ops: {String(stats.dbOps)}</li>
-                        <li>connected streams (live): {String(stats.connectedStreams)}</li>
-                        <li>committed memory (live): {fmt(Number(stats.committedMemory), 'bytes')}</li>
-                        <li>requests this minute: {cap(stats.reqMinuteUsed, stats.reqMinuteCap)}</li>
-                        <li>requests today: {cap(stats.reqDayUsed, stats.reqDayCap)}</li>
+                        <li>total requests: {String(stats.totalRequests)}</li>
+                        <li>total bytes out (L1): {String(stats.totalBytesOutL1)}</li>
+                        <li>total bytes in (L1): {String(stats.totalBytesInL1)}</li>
+                        <li>total gas used: {String(stats.totalGasUsed)}</li>
+                        <li>total 2xx responses: {String(stats.totalStatus2xx)}</li>
+                        <li>total db ops: {String(stats.totalDbOps)}</li>
+                        <li>total cache hits: {String(stats.totalCacheHits)}</li>
+                        <li>total cache misses: {String(stats.totalCacheMisses)}</li>
+                        <li>cache hit ratio: {(stats.cacheHitRatio * 100).toFixed(1)}%</li>
+                        <li>connected streams (live): {String(stats.liveConnectedStreams)}</li>
+                        <li>committed memory (live): {fmt(Number(stats.liveCommittedMemoryBytes), 'bytes')}</li>
+                        <li>requests this minute: {cap(stats.requestsThisMinute, stats.requestsThisMinuteCap)}</li>
+                        <li>requests today: {cap(stats.requestsToday, stats.requestsTodayCap)}</li>
                     </ul>
                 )}
             </section>