toiljs 0.0.85 → 0.0.87

package/build/devserver/db/types.js

@@ -26,6 +26,8 @@ export function freshDbState() {
         lastResultVersion: -1,
         functionKind: DbFunctionKind.Job,
         writtenCollections: new Set(),
+        deriveId: 0,
+        pendingCheckpoints: new Map(),
     };
 }
 export const MAX_RESERVATIONS = 4096;

package/build/devserver/runtime/module.js

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { DbFunctionKind, derivesForWrites, parseDerives, persistDb, setDbCatalog, } from '../db/index.js';
+import { commitDeriveCheckpoints, DbFunctionKind, derivesForWrites, parseDerives, persistDb, setDbCatalog, } from '../db/index.js';
 import { parseRouteKinds, parseRpcKinds, routeKindForRequest, rpcKindForId, } from '../db/routeKinds.js';
 import { decodeResponseEnvelope, encodeRequestEnvelope, unpackHandleResult, } from '../http/envelope.js';
 import { buildHostImports, freshDispatchState } from './host.js';
@@ -76,6 +76,7 @@ const PROVIDED_IMPORTS = new Set([
     'data.append_once',
     'data.enqueue',
     'data.latest',
+    'data.events_since',
     'data.capacity_set_total',
     'data.capacity_available',
     'data.capacity_reserve',
@@ -229,12 +230,14 @@ export class WasmServerModule {
         const ref = { memory: null };
         const state = freshDispatchState();
         state.db.functionKind = DbFunctionKind.Derive;
+        state.db.deriveId = deriveId;
         const instance = new WebAssembly.Instance(this.module, buildHostImports(ref, state));
         const exports = instance.exports;
         ref.memory = exports.memory;
         if (typeof exports.derive_run !== 'function')
             return;
         exports.derive_run(deriveId);
+        commitDeriveCheckpoints(state.db);
     }
     assertImportSurface(module) {
         const missing = WebAssembly.Module.imports(module)

package/docs/README.md

@@ -1,65 +1,104 @@
-# toiljs docs
-
-Reference documentation for the toiljs server runtime, the decorators the
-ToilScript compiler understands, and the generated client surface.
-
-The server runs as a WebAssembly module: your handler code is written in
-ToilScript (a TypeScript/AssemblyScript dialect), compiled to wasm, and run one
-fresh instance per request on both the dev server and the edge. Most of the
-runtime is exposed two ways: as an ambient **global** (no import, like `crypto`)
-and as a named export from `toiljs/server/runtime`.
-
-## Guides
-
-- [Getting started](./getting-started.md): project layout, `toiljs dev` /
-  `toiljs build`, `main.ts` wiring, and the request lifecycle.
-
-## Reference
-
-- [Routing](./routing.md): `@rest` controllers, the `@get/@post/...` verb
-  decorators and `@route`, path params, `RouteContext`, `Request`, `Response`,
-  and how dispatch + the 404 fallback work.
-- [Data codec (`@data`)](./data.md): the `@data` decorator and the
-  `DataWriter` / `DataReader` binary codec (JSON vs Binary streams), with the
-  exact wire format.
-- [RPC and the generated client](./rpc.md): `@service` / `@remote`, the
-  `--rpcModule` generated `shared/server.ts`, the typed `Server` proxy, and the
-  REST fetch client.
-- [Caching](./caching.md): the `@cache` decorator and `Response.cache(...)`
-  (edge vs browser TTL, private scope, auth gating).
-- [Rate limiting](./ratelimit.md): the `@ratelimit` decorator (FixedWindow /
-  SlidingWindow / TokenBucket), keyed on the unspoofable client IP, with
-  `429` + `Retry-After`.
-- [Auth, sessions, and `@user`](./auth.md): `@auth` route guards, the `@user`
-  type, `AuthService` (post-quantum login, signed sessions, `getUser()`), and
-  the client half.
-- [Environment variables & secrets](./environment.md): `Environment.get` /
-  `getSecure`, per-tenant config + secrets set out of band (GitHub-Actions
-  style), so the `.wasm` carries no credentials. Two disjoint buckets, read-only.
-- [Email](./email.md): `EmailService`, `EmailTemplate`, the `emails/` React
-  template pipeline, the stateless `TwoFactor` codes, provider config
-  (Resend / Gmail / SMTP, in the host-only `[email]` env namespace), and limits.
-- [Cookies](./cookies.md): the `Cookie` builder, the `Cookies` parser/codec,
-  `CookieMap`, `SecureCookies` (HMAC signing and AES-256-GCM encryption), the
-  `base64url` helpers, and the `Request` / `Response` integration.
-- [Time](./time.md): `Time.nowMillis()` / `Time.nowSeconds()`, the host
-  wall-clock binding.
-- [SSR templates](./ssr.md): the `render` entrypoint, `SlotValues`,
-  `HtmlBuilder`, and React-exact escaping.
-- [Web Crypto](./crypto.md): the synchronous `crypto` global and
-  `crypto.subtle` (digests, HMAC, AES-GCM, ECDSA, key import/derive), plus the
-  ML-DSA-44 post-quantum verify import.
-
-## Conventions
-
-- **"Global, no import"**, a symbol marked `@global` in the runtime is in scope
-  everywhere in a tenant without an `import`, exactly like `crypto`. The
-  matching named export exists so editors resolve the type and so the module is
-  pulled into every build. Either form works.
-- **Binary, not JSON, on the hot paths**, request/response bodies, sessions,
-  and cookies use the deterministic `DataWriter`/`DataReader` codec. JSON is
-  available for `@rest` routes but binary is the default for anything
-  performance- or security-sensitive.
-- **One fresh instance per request**, guest memory is wiped between requests,
-  so nothing persists in module globals across requests. Use a host-backed store
-  for anything that must outlive a single request.
+# toiljs
+
+toiljs is a full-stack web framework. You write your **frontend in React** and your **backend in
+TypeScript**, and toiljs turns the backend into a tiny, fast **WebAssembly** program that runs at the edge
+(on servers close to your users, all over the world). One language, one project, one deploy.
+
+If you have used Next.js, this will feel familiar: file-based routes, server code next to client code, a dev
+server with hot reload. The difference is what happens underneath. Your server code is compiled by
+**toilscript** (a TypeScript-to-WebAssembly compiler) into a sandboxed `.wasm` module, and it runs on the
+**Dacely edge** with a built-in worldwide database (**ToilDB**), streaming, background jobs, and auth all
+included.
+
+## The mental model
+
+```mermaid
+flowchart LR
+    A["Your project<br/>(TypeScript + React)"] -->|toiljs build| B["client bundle<br/>(React, runs in the browser)"]
+    A -->|toilscript compile| C["server.wasm<br/>(your backend, sandboxed)"]
+    B --> U["User's browser"]
+    C --> E["Dacely edge<br/>(worldwide)"]
+    E --> D[("ToilDB<br/>global database")]
+    U <-->|HTTP / WebTransport| E
+```
+
+- **client/** is your React app (pages, components, styles). It runs in the browser.
+- **server/** is your backend (routes, database, auth). It compiles to WebAssembly and runs on the edge.
+- **shared/** is the typed bridge: toiljs generates a client here so the browser calls your server with full
+  type safety.
+
+## Hello, toiljs
+
+```ts
+// server/routes/Hello.ts  (a backend HTTP route)
+import { Response } from 'toiljs/server/runtime';
+
+@rest('hello')
+class Hello {
+    @get('/')
+    public hi(): Response {
+        return Response.text('Hello from the edge!\n');
+    }
+}
+```
+
+```tsx
+// client/routes/index.tsx  (a frontend page)
+export default function Home() {
+    return <main><h1>Welcome</h1></main>;
+}
+```
+
+Run `toiljs dev`, open the browser, and both are live with hot reload. That is the whole loop.
+
+## Learn toiljs
+
+**Understand toil first**
+- [Understanding toil](./introduction/README.md): what toil is and the one big idea, then
+  [why toil and who it is for](./introduction/why-toil.md),
+  [the modern stack you get](./introduction/modern-stack.md),
+  [how it works](./introduction/how-it-works.md),
+  [what makes it hyper-scalable](./introduction/hyperscale.md),
+  [how it is distributed](./introduction/distributed.md),
+  [toil versus other frameworks](./introduction/vs-other-frameworks.md), and
+  [why it is built this way](./introduction/design-principles.md).
+
+**Start here**
+- [Getting started](./getting-started/README.md): install, create a project, project structure, your first
+  app, and migrating an existing React app.
+- [The CLI](./cli/README.md): `dev`, `build`, `create`, `doctor`, and every flag.
+- [Deploy](./getting-started/deploy.md): build for production, self-host it, and how the managed edge fits in.
+
+**Build the frontend**
+- [Frontend overview](./frontend/README.md), [Routing](./frontend/routing.md),
+  [Rendering and SSR](./frontend/rendering.md), [Styling](./frontend/styling.md),
+  [Images](./frontend/images.md), [Metadata and SEO](./frontend/metadata.md),
+  [Fetching data](./frontend/data-fetching.md), [Scripts](./frontend/scripts.md),
+  [Search](./frontend/search.md).
+
+**Build the backend**
+- [Backend overview](./backend/README.md), [HTTP routes (`@rest`)](./backend/rest.md),
+  [Typed RPC (`@service`/`@remote`)](./backend/rpc.md), [Data types (`@data`)](./backend/data.md).
+
+**The database (ToilDB)**
+- [Database overview and choosing a family](./database/README.md), [Setup (`@database`)](./database/setup.md),
+  [Documents](./database/documents.md), [Unique](./database/unique.md), [Counters](./database/counters.md),
+  [Events](./database/events.md), [Views and `@derive`](./database/views.md),
+  [Membership](./database/membership.md), [Capacity](./database/capacity.md).
+
+**Auth**: [the full auth guide](./auth/README.md) covers post-quantum login, sessions, and `ToilUserId`.
+
+**Realtime and background**
+- [Streams](./realtime/README.md) and [channels](./realtime/channels.md), [Daemons and scheduled
+  jobs](./background/daemons.md), [Derived views (`@derive`)](./background/derive.md).
+
+**Platform services**
+- [Caching](./services/caching.md), [Rate limiting](./services/ratelimit.md),
+  [Environment and secrets](./services/environment.md), [Email and 2FA](./services/email.md),
+  [Analytics](./services/analytics.md), [Crypto](./services/crypto.md), [Cookies](./services/cookies.md),
+  [Time](./services/time.md).
+
+**Concepts and reference**
+- [Compute tiers (L1 to L4)](./concepts/tiers.md), [Types (u64, u256, and friends)](./concepts/types.md),
+  [Every decorator](./concepts/decorators.md), [Configuration](./concepts/config.md),
+  [Security and SRI](./concepts/security.md).

package/docs/auth/README.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/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,202 @@
+# 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.