@spfn/auth 0.3.0-beta.2 → 0.3.0-beta.20

package/README.md

@@ -21,7 +21,7 @@ Underneath: asymmetric client-signed JWTs (ES256/RS256), OTP verification, OAuth
 through a pluggable provider registry (Google, GitHub, Kakao and Naver built in), session
 cookies for Next.js, and runtime RBAC. Routes mount under `/_auth/*` and are reached
 through a typed `authApi` client. Requires `@spfn/core`; Next.js is an optional peer
-(`^16.2.11`).
+(`^16.3.3`).
 
 ## Install
 
@@ -29,6 +29,11 @@ through a typed `authApi` client. Requires `@spfn/core`; Next.js is an optional
 pnpm add @spfn/auth drizzle-orm@1.0.0-rc.4
 ```
 
+`@simplewebauthn/server` and `@simplewebauthn/browser` come along as dependencies —
+[passkeys](#passkeys-webauthn) need them, and standards conformance is the whole risk there.
+The browser half is bundled into the `./client` entry rather than marked external, so nothing
+in your app has to know about it.
+
 ## Import paths
 
 Entry points (from `package.json` `exports`). Picking the wrong one breaks the build —
@@ -78,10 +83,10 @@ applied globally via `.use()`. Public routes opt out per-route with `.skip(['aut
 ```typescript
 import { defineRouter } from '@spfn/core/route';
 import { authRouter, authenticate } from '@spfn/auth/server';
-import { getHealth } from './routes/health';
+import { getStatus } from './routes/status';
 
 export const appRouter = defineRouter({
-    getHealth,
+    getStatus,
     // ...your routes
 })
     .packages([authRouter])   // mounts /_auth/* and exposes routes on authApi
@@ -136,17 +141,19 @@ real secret values out of band, never commit them.
 | `SPFN_AUTH_JWT_SECRET` / `SPFN_AUTH_JWT_EXPIRES_IN` | `.env.server` | — | legacy server-signed JWT mode only |
 | `SPFN_AUTH_BCRYPT_SALT_ROUNDS` | `.env.server` | — | default `12` (native bcrypt, off the event loop) |
 | `SPFN_AUTH_COOKIE_SECURE` | both | — | override Secure flag (defaults to `NODE_ENV==='production'`) |
+| `SPFN_AUTH_CSRF` | `.env.local` | — | `off` \| `warn` \| `enforce`; unset behaves as `warn` — see [CSRF protection](#csrf-protection) |
 | `SPFN_AUTH_ADMIN_*` | `.env.server` | — | admin seeding (see below) |
 | `SPFN_AUTH_GOOGLE_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | enables Google OAuth when both set |
 | `SPFN_AUTH_GOOGLE_SCOPES` | `.env.server` | — | comma-separated; default `email,profile` |
-| `SPFN_AUTH_GOOGLE_REDIRECT_URI` | `.env.server` | — | default `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}/_auth/oauth/google/callback` — see [OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite) |
+| `SPFN_AUTH_GOOGLE_REDIRECT_URI` | `.env.server` | — | default `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}/_auth/oauth/google/callback`; an override must stay on the web app origin at that path and is **checked at boot** — see [OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite) |
 | `SPFN_AUTH_KAKAO_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | REST API key enables Kakao Login; secret is included when configured |
 | `SPFN_AUTH_KAKAO_ADMIN_KEY` | `.env.server` | — | app admin key; required to verify the Kakao User Unlinked webhook |
-| `SPFN_AUTH_KAKAO_SCOPES` / `_REDIRECT_URI` | `.env.server` | — | default scope `account_email`; callback `/_auth/oauth/kakao/callback` |
+| `SPFN_AUTH_KAKAO_SCOPES` / `_REDIRECT_URI` | `.env.server` | — | default scope `account_email`; callback `/_auth/oauth/kakao/callback` on the web app origin, **checked at boot** — see [OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite) |
 | `SPFN_AUTH_NAVER_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | both values enable Naver Login |
-| `SPFN_AUTH_NAVER_REDIRECT_URI` | `.env.server` | — | default `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}/_auth/oauth/naver/callback` |
+| `SPFN_AUTH_NAVER_REDIRECT_URI` | `.env.server` | — | default `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}/_auth/oauth/naver/callback`; an override must stay on the web app origin at that path and is **checked at boot** — see [OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite) |
 | `SPFN_AUTH_GITHUB_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | both values enable GitHub OAuth |
-| `SPFN_AUTH_GITHUB_SCOPES` / `_REDIRECT_URI` | `.env.server` | — | default scopes `read:user,user:email`; callback `/_auth/oauth/github/callback` |
+| `SPFN_AUTH_GITHUB_SCOPES` / `_REDIRECT_URI` | `.env.server` | — | default scopes `read:user,user:email`; callback `/_auth/oauth/github/callback` on the web app origin, **checked at boot** — see [OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite) |
+| `SPFN_AUTH_OAUTH_CALLBACK_ORIGIN_CHECK` | `.env.server` | — | `off` disables the boot check of the four `_REDIRECT_URI` overrides; any other value (unset included) runs it — see [OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite) |
 | `SPFN_AUTH_GOOGLE_NATIVE_CLIENT_IDS` | `.env.server` | — | comma-separated client IDs accepted as native id_token audience (iOS/Android/web); enables Google native sign-in |
 | `SPFN_AUTH_APPLE_CLIENT_IDS` | `.env.server` | — | comma-separated Apple client IDs (bundle ID / Services ID); enables Apple native sign-in |
 | `SPFN_AUTH_KAKAO_NATIVE_CLIENT_IDS` | `.env.server` | — | comma-separated Kakao app keys accepted as native id_token audience (native app key); `SPFN_AUTH_KAKAO_CLIENT_ID` is also accepted, so either one enables Kakao native sign-in |
@@ -154,6 +161,14 @@ real secret values out of band, never commit them.
 | `SPFN_AUTH_OAUTH_SUCCESS_URL` | `.env.server` | — | default `/auth/callback` |
 | `SPFN_AUTH_OAUTH_ERROR_URL` | `.env.server` | — | default `/auth/error?error={error}` |
 | `SPFN_AUTH_RESERVED_USERNAMES` / `_USERNAME_MIN_LENGTH` / `_USERNAME_MAX_LENGTH` | `.env.server` | — | username rules |
+| `SPFN_AUTH_SIGNUP_LINK_TTL_MINUTES` / `_SETUP_TTL_MINUTES` | `.env.server` | — | defaults `30` / `15` — see [Verified-email signup](#verified-email-signup) |
+| `SPFN_AUTH_SIGNUP_CONFIRM_PATH` | `.env.server` | — | default `/signup/confirm`; the page in your app the emailed link opens |
+| `SPFN_AUTH_PASSWORD_RESET_LINK_TTL_MINUTES` / `_SETUP_TTL_MINUTES` | `.env.server` | — | defaults `30` / `15` — see [Password reset](#password-reset-verified-email) |
+| `SPFN_AUTH_PASSWORD_RESET_CONFIRM_PATH` | `.env.server` | — | default `/password/reset`; the page in your app the emailed link opens |
+| `SPFN_AUTH_LINK_MAIL_DELIVERY` | `.env.server` | — | `auto` (default) \| `inline` \| `queued`; who sends signup-link, reset and account-exists mail — see [Link mail delivery](#link-mail-delivery) |
+| `SPFN_AUTH_PASSKEY_RP_ID` / `_RP_NAME` / `_ORIGINS` | `.env.server` | — | relying party for passkeys; defaults derive from `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}` and are **checked at boot** — see [Passkeys](#passkeys-webauthn) |
+| `SPFN_AUTH_PASSKEY_USER_VERIFICATION` | `.env.server` | — | `preferred` (default) or `required`; `discouraged` refuses boot |
+| `SPFN_AUTH_PASSKEY_CHALLENGE_TTL_SECONDS` / `_RECENT_AUTH_MINUTES` | `.env.server` | — | defaults `300` / `10` — see [Passkeys](#passkeys-webauthn) |
 | `NEXT_PUBLIC_SPFN_API_URL` / `NEXT_PUBLIC_SPFN_APP_URL` | `.env.local` | — | browser-facing URLs for OAuth redirects |
 
 Read validated values via `import { env } from '@spfn/auth/config'` (a proxy validated at
@@ -178,7 +193,25 @@ routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-si
 | `sendVerificationCode` | POST `/_auth/codes` | public | send 6-digit OTP |
 | `verifyCode` | POST `/_auth/codes/verify` | public | verify OTP → verification token |
 | `register` | POST `/_auth/register` | public | create user + register public key |
+| `requestSignupLink` | POST `/_auth/signup/email` | public | email a one-time signup confirmation link — see [Verified-email signup](#verified-email-signup) |
+| `confirmSignupLink` | POST `/_auth/signup/email/confirm` | public | exchange the link for a password-setup session |
+| `completeSignup` | POST `/_auth/signup/password` | setup session | set the password, which creates the account and signs in |
+| `requestPasswordReset` | POST `/_auth/password/reset` | public | email a one-time password reset link — see [Password reset](#password-reset-verified-email) |
+| `confirmPasswordReset` | POST `/_auth/password/reset/confirm` | public | exchange the link for a password-setup session |
+| `completePasswordReset` | POST `/_auth/password/reset/complete` | setup session | set the new password, sign every other device out, sign this one in |
 | `login` | POST `/_auth/login` | public | password login + new session key |
+| `startDeviceAuth` | POST `/_auth/device/start` | public | begin a device-code login — see [Device-code login](#device-code-login) |
+| `pollDeviceAuth` | POST `/_auth/device/poll` | public | ask whether the request was answered; the approved answer *is* the login |
+| `getDeviceAuthInfo` | POST `/_auth/device/info` | yes | what device is asking, so the approval screen can show it |
+| `approveDeviceAuth` | POST `/_auth/device/approve` | yes | let the waiting device in |
+| `denyDeviceAuth` | POST `/_auth/device/deny` | yes | refuse it |
+| `passkeyRegisterOptions` | POST `/_auth/passkeys/register/options` | yes | begin enrolling a passkey — see [Passkeys](#passkeys-webauthn) |
+| `passkeyRegisterVerify` | POST `/_auth/passkeys/register/verify` | yes | verify the attestation and keep the credential |
+| `passkeyLoginOptions` | POST `/_auth/passkeys/login/options` | public | begin a passkey sign-in; takes no identifier |
+| `passkeyLoginVerify` | POST `/_auth/passkeys/login/verify` | public | verify the assertion; answers exactly as `login` |
+| `listPasskeys` | POST `/_auth/passkeys/list` | yes | the caller's enrolled passkeys |
+| `renamePasskey` | POST `/_auth/passkeys/rename` | yes | rename one |
+| `revokePasskey` | POST `/_auth/passkeys/revoke` | yes | retire one (refused if it is the last way in) |
 | `logout` | POST `/_auth/logout` | yes | revoke current key |
 | `rotateKey` | POST `/_auth/keys/rotate` | yes | rotate public key before 90-day expiry |
 | `listKeys` | POST `/_auth/keys/list` | yes | the caller's registered devices — see [Registered devices](#registered-devices-key-management) |
@@ -194,6 +227,7 @@ routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-si
 | `cancelAccountDeletion` | POST `/_auth/deletion/cancel` | public | cancel a pending deletion (credential-based recovery) |
 | `listRoles` / `createAdminRole` / `updateAdminRole` / `deleteAdminRole` / `updateUserRole` | — | superadmin | admin RBAC management |
 | OAuth routes | — | — | see OAuth section |
+| `registerOAuth2Client` / `getOAuth2Authorize` / `createOAuth2AuthorizationCode` / `oauth2Token` / `oauth2Revoke` / `listOAuth2Grants` / `revokeOAuth2Grant` | `/_auth/oauth2/*` | mixed | OAuth 2.1 authorization server for MCP clients — see [Authorization server for MCP clients](#authorization-server-for-mcp-clients). 404 unless configured |
 
 There is deliberately **no account-existence endpoint**. `POST /_auth/exists` was removed
 because it answered "does this account exist" directly, which is user enumeration; the
@@ -205,8 +239,280 @@ sends the public key on register/login, signs request JWTs locally, and the serv
 with the stored public key (`keyId` carried in the JWT). The server never holds a private key.
 Keys expire after 90 days — rotate with `rotateKey`.
 
+### Verified-email signup
+
+A second way in, alongside the six-digit code. The address is proven before a password
+exists, so nothing is stored for someone who never confirms.
+
+```
+request  → a one-time link is emailed
+confirm  → the link becomes a short-lived, HttpOnly password-setup session
+password → the account is created, the device registered, the user signed in
+```
+
+The six-digit-code path (`sendVerificationCode` → `verifyCode` → `register`) is unchanged.
+Offer whichever suits your product, or both.
+
+**1 — request the link.** The response is identical whether or not the address already has
+an account, so it cannot be used to probe for accounts. When one exists, the owner gets a
+"you already have an account" notice instead of a usable link.
+
+```typescript
+await authApi.requestSignupLink.call({
+    body: { email: 'user@example.com', returnPath: '/welcome' },   // returnPath optional
+});
+// → { success: true, expiresAt }
+```
+
+Calling it again is how a resend works: it invalidates the previous link and any setup
+session opened from it. `returnPath` must be a path inside your app — absolute URLs,
+`//host`, and `..` are refused, so the link cannot become an open redirect.
+
+The mail leaves through the `auth.link-mail` job when pg-boss is initialised — register
+`authJobRouter` — so neither branch of this endpoint waits on a mail provider; see
+[Link mail delivery](#link-mail-delivery).
+
+**2 — the page the link opens.** The email points at a page in *your* app
+(`SPFN_AUTH_SIGNUP_CONFIRM_PATH`, default `/signup/confirm`), not at an API route. That page
+reads the token from the query string and posts it:
+
+```typescript
+'use client';
+
+const token = useSearchParams().get('token');
+
+const { email, returnPath } = await authApi.confirmSignupLink.call({ body: { token } });
+
+// Drop the token from the URL so it does not linger in history or a Referer header.
+window.history.replaceState({}, '', window.location.pathname);
+```
+
+The setup session comes back as an HttpOnly cookie — the proxy interceptor moves it there
+and strips it from the response body, so page script never holds it. Serve this page with
+`Referrer-Policy: no-referrer`.
+
+**3 — set the password.** This is the step that creates the account. The setup cookie
+authorizes it; the device keypair is injected by the interceptor exactly as it is for
+`register`.
+
+```typescript
+await authApi.completeSignup.call({ body: { password } });
+// → { userId, publicId, email }  + session cookie, same as register
+```
+
+Creating the user, registering the device key, and marking the setup session used all commit
+together. A password that fails the strength policy leaves the session usable, so the user
+retypes rather than requesting a fresh email.
+
+**Settings.**
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `SPFN_AUTH_SIGNUP_LINK_TTL_MINUTES` | `30` | how long the emailed link works |
+| `SPFN_AUTH_SIGNUP_SETUP_TTL_MINUTES` | `15` | how long the password-setup session works |
+| `SPFN_AUTH_SIGNUP_CONFIRM_PATH` | `/signup/confirm` | the page in your app the link opens |
+
+The link URL is built on `NEXT_PUBLIC_SPFN_APP_URL || SPFN_APP_URL`, the same resolution the
+OAuth callbacks use. Delivery uses the `signup-link` template in `@spfn/notification` —
+override it there to change the copy.
+
+**What is stored.** Only SHA-256 hashes of the link token and the setup secret, in
+`spfn_auth.signup_link_tokens`. Neither credential is recoverable from the database, and
+both are one-time: a link opens one setup session, and a setup session sets one password.
+
+### Password reset (verified email)
+
+The way back into an account whose password is gone, using the address the account already
+proved. Same three steps as the signup above, and the same posture on the two credentials.
+
+```
+request  → a one-time link is emailed
+confirm  → the link becomes a short-lived, HttpOnly password-setup session
+complete → the new password is written, every other device is signed out, this one is signed in
+```
+
+**Who can reset.** An `active` account whose `emailVerifiedAt` is set **or** that already has
+a password. The second half is what makes the rule work on accounts created before the
+column was stamped: both register paths proved the address at signup. An OAuth-only account
+whose provider reported the address unverified has neither and is excluded — for it, a reset
+would be a way in built on an address nobody proved.
+
+**1 — request the link.** The response is identical for every input — same status, same two
+fields, same `expiresAt` arithmetic — and mail goes only to an account that can be reset, so
+neither the answer nor the mailbox reveals whether an address has an account here.
+
+```typescript
+await authApi.requestPasswordReset.call({
+    body: { email: 'user@example.com', returnPath: '/account' },   // returnPath optional
+});
+// → { success: true, expiresAt }
+```
+
+Calling it again is how a resend works: it invalidates the previous link and any setup
+session opened from it. `returnPath` must be a path inside your app — absolute URLs,
+`//host`, and `..` are refused, so the link cannot become an open redirect.
+
+The mail leaves through the `auth.link-mail` job when pg-boss is initialised — register
+`authJobRouter` — so an address with an account and one without cost the same; see
+[Link mail delivery](#link-mail-delivery).
+
+**2 — the page the link opens.** The email points at a page in *your* app
+(`SPFN_AUTH_PASSWORD_RESET_CONFIRM_PATH`, default `/password/reset`), not at an API route.
+That page reads the token from the query string and posts it:
+
+```typescript
+'use client';
+
+const token = useSearchParams().get('token');
+
+const { email, returnPath } = await authApi.confirmPasswordReset.call({ body: { token } });
+
+// Drop the token from the URL so it does not linger in history or a Referer header.
+window.history.replaceState({}, '', window.location.pathname);
+```
+
+The setup session comes back as an HttpOnly cookie — the proxy interceptor moves it there
+and strips it from the response body, so page script never holds it. It is a cookie of its
+own, not the signup one, so neither secret is ever accepted by the other flow. Serve this
+page with `Referrer-Policy: no-referrer`.
+
+**3 — set the new password.** The setup cookie authorizes it; the device keypair is injected
+by the interceptor exactly as it is for `login`.
+
+```typescript
+await authApi.completePasswordReset.call({ body: { password } });
+// → { userId, publicId, email }  + session cookie, same as login
+```
+
+**Every other device is signed out.** Completing a reset denies every pending device
+authorization and revokes every active key, exactly as `changePassword` does — whoever was
+signed in on the old password, including the person the reset was needed for, has to sign in
+again. The browser that performed the reset is signed in on a fresh key registered after the
+revocation, so it does not have to retype the new password. `emailVerifiedAt` is stamped if
+it was not already, `passwordChangeRequired` is cleared, and `auth.password.reset` is emitted
+after commit.
+
+The new hash, the revocations, the new device key and the completion mark commit together. A
+password that fails the strength policy leaves the session usable, so the user retypes rather
+than requesting a fresh email.
+
+**Settings.**
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `SPFN_AUTH_PASSWORD_RESET_LINK_TTL_MINUTES` | `30` | how long the emailed link works |
+| `SPFN_AUTH_PASSWORD_RESET_SETUP_TTL_MINUTES` | `15` | how long the password-setup session works |
+| `SPFN_AUTH_PASSWORD_RESET_CONFIRM_PATH` | `/password/reset` | the page in your app the link opens |
+
+The link URL is built on `NEXT_PUBLIC_SPFN_APP_URL || SPFN_APP_URL`, the same resolution the
+signup link uses. Delivery uses the `password-reset` template in `@spfn/notification` —
+override it there to change the copy.
+
+**What is stored.** Only SHA-256 hashes of the link token and the setup secret, in
+`spfn_auth.password_reset_tokens`. Neither credential is recoverable from the database, and
+both are one-time: a link opens one setup session, and a setup session sets one password.
+A separate table from `signup_link_tokens`, so a signup secret can never address a reset row.
+
+### Device-code login
+
+A way in for a device that has a screen but no comfortable keyboard — a TV, a console, a CLI
+on a headless box. The new device shows a short code; the account owner types that code on a
+device that is already signed in.
+
+```typescript
+// On the new device — it has no key on file, so this call is public.
+const { deviceCode, userCode, expiresAtMillis, intervalMillis } =
+    await authApi.startDeviceAuth.call({ body: {
+        publicKey, keyId, fingerprint, algorithm: 'ES256',
+        deviceName: 'Living room TV', platform: 'desktop',
+    } });
+
+// Show `userCode` (XXXX-XXXX) on this device's screen, then poll every intervalMillis.
+const answer = await authApi.pollDeviceAuth.call({ body: { deviceCode } });
+// → { status: 'pending', intervalMillis }
+// → { status: 'approved', userId, publicId, email?, phone?, passwordChangeRequired }
+```
+
+```typescript
+// On the signed-in device — the user typed the code they read off the other screen.
+const asking = await authApi.getDeviceAuthInfo.call({ body: { userCode } });
+// → { deviceName?, platform?, fingerprintPrefix, requestedAtMillis, expiresAtMillis }
+
+await authApi.approveDeviceAuth.call({ body: { userCode } });   // or denyDeviceAuth
+```
+
+**There is no token handed over, because there is no token.** Every request in this system is
+signed by the calling device's own key, so "logging a device in" means getting its public key
+into `user_public_keys` under the right account — which is exactly what the winning poll does.
+That is why the approved answer is the same shape `login` returns: from the client's side the
+two ways in are indistinguishable.
+
+- **Only ever show the code on the new device's screen.** The whole attack on this flow is
+  someone sending a victim a code and asking them to approve it — a support call, a chat
+  message, a "verify your account" email. A code that arrived any way other than off the
+  device in front of you is an attack. This is why `info` and `approve` answer with the
+  requesting device's name, platform and fingerprint prefix, and why an approval screen that
+  shows only the code is doing it wrong: it is asking the user to confirm a number they were
+  just told.
+- **The device code is stored only as a SHA-256 hash**, like the ops-token and signup-link
+  secrets. It is returned once. A dump of `spfn_auth.device_authorizations` does not let its
+  reader finish anyone's login.
+- **The user code is stored in the clear, and that is fine** — it authorizes nothing without
+  an approver who is already signed in. It is drawn from an alphabet with no `0`/`O` or
+  `1`/`I`/`L`, since it is read off one screen and typed on another.
+- **A decision is made once.** Approve and deny move the record from `pending` and nowhere
+  else, so a second approval, a deny after an approve, or two approvals racing each other all
+  get `DeviceAuthAlreadyHandledError` (409) — a refusal is never undone.
+- **The approval is one-shot.** The poll that registers the key spends the record in the same
+  statement that reads it, so of two polls arriving together exactly one registers the key and
+  the other is answered as if the code were unknown.
+- **A spent code and a code that never existed answer identically** (`DeviceAuthNotFoundError`,
+  404). Saying "that one was real, but it is used up" is the difference between guessing at
+  random and knowing a guess landed. Every route that accepts a code is rate limited for the
+  same reason: `start` and `poll` per IP, `info` / `approve` / `deny` per IP *and* per calling
+  account.
+- **Expiry outranks state.** A code that sat past its TTL is expired whatever it says, so an
+  approval nobody collected in time registers nothing. The TTL travels in the statement that
+  moves the record, not only in the read before it, so a code cannot be spent by a poll that
+  read it a moment before it died.
+- **A global revocation reaches the codes too.** `revoke-all`, a password change and a
+  deletion request each refuse the account's live device authorizations, so an approval nobody
+  collected cannot register a fresh key seconds after the user signed everything out — which
+  would hand one back to exactly the device they were cutting off. Revoking a single key,
+  logging out and rotating a key do not: those name one device, and the waiting one is not it.
+- **The poll re-checks the account.** It is a login, so it refuses a suspended or
+  pending-deletion account with the same errors `/_auth/login` does. Approval and collection
+  are separate moments, and what the account is when the key is registered is what counts.
+- **`start` bounds what it stores.** It is the one route that takes key material from a caller
+  who cannot authenticate, so `publicKey`, `keyId` and `fingerprint` carry length limits —
+  generous next to a real key (an RSA-2048 SPKI is 392 base64 characters against a 2048 limit)
+  and small next to the megabyte that would otherwise sit in a table no job clears.
+- **Clock skew cannot affect this.** Every timestamp in the decision is the server's. The
+  `expiresAtMillis` in the start response is for the waiting device's countdown display, and
+  nothing the client believes about the time reaches the server's judgement.
+
+Two knobs, both announced to the waiting device in the start response and therefore resolved
+at lifecycle time rather than read per call:
+
+```typescript
+createAuthLifecycle({
+    deviceAuth: {
+        ttlMs: 10 * 60 * 1000,   // how long a code lives. default 10 minutes
+        intervalMs: 5000,        // poll interval the server asks for. default 5s
+    },
+})
+```
+
+No job sweeps the table. Rows are judged by `expiresAt` whenever they are read or moved, so a
+stale row authorizes nothing; it only keeps its user code out of circulation, and 31⁸ codes do
+not run out.
+
 ### Registered devices (key management)
 
+A [passkey](#passkeys-webauthn) is **not** one of these keys: it is a credential that proves
+identity at sign-in, after which an ordinary device key is registered exactly as a password
+login registers one.
+
 Keys are per-device, so a login never revokes the previous key and they accumulate on purpose.
 `listKeys` / `revokeKey` / `revokeAllKeys` are what let the account owner see what accumulated and
 cut off anything they no longer recognise.
@@ -236,13 +542,19 @@ await authApi.revokeAllKeys.call({ body: {} });               // other devices o
 await authApi.revokeAllKeys.call({ body: { includeCurrent: true } });   // everything
 ```
 
-> **All three are POST with their arguments in the body, deliberately.** The mobile auth
+> **All three key-management operations are POST with their arguments in the body, deliberately.** The mobile auth
 > profile (clientProofV1) signs the request body, and `canonical-json` fixes exactly how those
 > bytes are written. A `GET` has no body to sign, and a value in the path has no such rule —
 > client and server could disagree on the signed string over percent-encoding, a trailing
 > slash, or a proxy rewrite alone, and the request would be refused with nothing in the logs
-> naming the cause. Every operation in the contract is shaped this way.
-
+> naming the cause. Proof-bearing auth operations are shaped this way; the unproven,
+> bodyless `core.time` synchronization prerequisite is the explicit exception.
+
+- **A key must be the type its algorithm names.** A P-256 SPKI declared `RS256`, an RSA key
+  declared `ES256`, and a curve other than P-256 declared `ES256` are each refused 400 with
+  `KeyAlgorithmMismatchError` on register, login, rotate and device start — the algorithm is
+  stored beside the key and read back at proof verification, so a mismatch accepted at
+  enrollment would surface only once the device already believed it was enrolled.
 - **The public key never leaves the server**, and the fingerprint is truncated to 8 characters.
   The list exists to recognise a device and point at it; the full fingerprint is what a native
   sign-in sends as its nonce, not a label.
@@ -254,6 +566,10 @@ await authApi.revokeAllKeys.call({ body: { includeCurrent: true } });   // every
 - **`revokeAllKeys` spares the calling device unless you ask otherwise**, so the common case is
   "sign out my other devices". `includeCurrent: true` is the full sign-out — until now reachable
   only as a side effect of changing a password, which nobody does for that reason.
+- **It also refuses device-code approvals still in flight**, in both modes, because an approved
+  code is a key that has not been handed out yet: the next poll would register a fresh active one
+  and undo the sign-out. `revokedCount` still counts keys only — a code nobody collected was
+  never a session. See [Device-code login](#device-code-login).
 - **A key id you do not own answers 404** (`KeyNotFoundError`). Every lookup is scoped by user, so
   the answer is only ever "not yours" and reveals nothing about other accounts.
 - **Revocation takes effect immediately.** `authenticate` reads the key from the database on every
@@ -278,6 +594,280 @@ is still active is the one
 exception: it stays a no-op success, so repeated logins from the same device keep working, and an
 expired-but-active key has its expiry extended by the sign-in that proved the identity again.
 
+### Passkeys (WebAuthn)
+
+A passkey is an **optional additional credential** on an account, alongside a password and a
+linked social account rather than in place of either. Enroll one from a session that already
+exists; sign in with it afterwards without typing an identifier at all.
+
+```
+enroll   → register/options (session)  → the browser mints a credential → register/verify
+sign in  → login/options    (public)   → the browser picks a credential → login/verify
+manage   → list / rename / revoke
+```
+
+**A passkey is not a device key.** The assertion proves *who* is asking; the device key the
+Next.js proxy registers right after it is what every later request is signed with, exactly as
+after a password login. Nothing in clientProofV1, in the JWT path, or in
+[Registered devices](#registered-devices-key-management) changes because a session started
+this way — a passkey sign-in produces the same `LoginResult` and the same key row as `login`.
+
+#### Setup
+
+```bash
+# .env.server — nothing is required; these are the overrides
+SPFN_AUTH_PASSKEY_RP_ID=example.com
+SPFN_AUTH_PASSKEY_ORIGINS=https://app.example.com,https://admin.example.com
+```
+
+With neither set, the relying party is derived from `{NEXT_PUBLIC_SPFN_APP_URL || SPFN_APP_URL}`:
+its host becomes the rpId and its origin becomes the single allowed origin. That is the whole
+configuration for a one-origin app.
+
+| Var | File | Notes |
+|-----|------|-------|
+| `SPFN_AUTH_PASSKEY_RP_ID` | `.env.server` | domain credentials are bound to — no protocol, no port. Default: the app URL's host. **Changing it orphans every passkey already enrolled** |
+| `SPFN_AUTH_PASSKEY_RP_NAME` | `.env.server` | name the authenticator's own prompt shows. Default: the rpId |
+| `SPFN_AUTH_PASSKEY_ORIGINS` | `.env.server` | comma-separated full origins allowed to run a ceremony. Default: the app URL's origin |
+| `SPFN_AUTH_PASSKEY_USER_VERIFICATION` | `.env.server` | `preferred` (default) or `required`. `discouraged` refuses boot |
+| `SPFN_AUTH_PASSKEY_CHALLENGE_TTL_SECONDS` | `.env.server` | default `300` — one ceremony at the authenticator, not an abandoned tab |
+| `SPFN_AUTH_PASSKEY_RECENT_AUTH_MINUTES` | `.env.server` | default `10` — see [the recent-authentication gate](#the-recent-authentication-gate) |
+
+Two rules on those origins, **checked at boot** and refused with `PasskeyConfigError`:
+
+- each origin must be `https`, and `localhost` is the one host a browser treats as a secure
+  context over plain `http` — so `http://localhost:3000` is legal and `http://app.example.com`
+  is not;
+- each origin's host must be the rpId or a subdomain of it, because the browser will refuse
+  the ceremony otherwise.
+
+The check runs at `initializeAuth`, deliberately: every one of these values makes *every*
+passkey operation fail, the drift is between environments, and the deploy that introduces it
+is where it has to surface — not the first sign-in after it.
+
+**Boot is only refused for a configuration you wrote.** If no `SPFN_AUTH_PASSKEY_*` variable
+is set, the derived relying party can still be unusable — `SPFN_APP_URL=http://192.168.1.5:3000`
+so a phone on the same network can reach your laptop, say, which is neither https nor
+localhost. Refusing to start over a feature nobody asked for would take that app down to fix
+something it does not use, so it is logged once instead and only a ceremony fails. Set any
+passkey variable and the same configuration refuses to start. This is the posture
+[the OAuth callback origin check](#oauth-callback-origin-web-app-host--rewrite) already takes.
+
+#### Enrolling, from a Next.js client component
+
+```tsx
+'use client';
+import { authApi } from '@spfn/auth';
+import { enrollPasskey, isPasskeySupported } from '@spfn/auth/client';
+
+async function addPasskey()
+{
+    const result = await enrollPasskey(authApi, { label: 'MacBook Touch ID' });
+
+    if (!result.ok)
+    {
+        // 'unsupported' | 'cancelled' | 'error' — 'cancelled' is not an error to show
+        return result.reason === 'cancelled' ? undefined : showError(result.reason);
+    }
+
+    showAdded(result.passkeyId, result.label);
+}
+```
+
+`isPasskeySupported()` is what decides whether to render the button at all.
+
+#### Signing in, with conditional UI
+
+The passkey appears in the browser's ordinary autofill dropdown. That needs an input whose
+`autocomplete` ends in `webauthn`, and a `signInWithPasskey` call started **when the form
+renders**, not on a click:
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { authApi } from '@spfn/auth';
+import { isConditionalMediationAvailable, signInWithPasskey } from '@spfn/auth/client';
+
+export function SignInForm()
+{
+    useEffect(() =>
+    {
+        void (async () =>
+        {
+            if (!await isConditionalMediationAvailable()) return;
+
+            const result = await signInWithPasskey(authApi, { conditional: true });
+            if (result.ok) router.replace('/');
+        })();
+    }, []);
+
+    return (
+        <form>
+            <input name="email" autoComplete="username webauthn" />
+            <input name="password" type="password" autoComplete="current-password" />
+        </form>
+    );
+}
+```
+
+Where conditional mediation is missing, render a visible "Sign in with a passkey" button that
+calls `signInWithPasskey(authApi)` instead.
+
+Both helpers answer with a discriminated union and **never throw a cancellation**: a person
+who dismisses the system sheet raises `NotAllowedError`, and so does a person whose
+authenticator had nothing to offer — neither is an application error, and code that has to
+tell them apart by re-reading `error.name` gets it wrong once and shows a red banner to
+someone who simply changed their mind.
+
+| result | meaning |
+|--------|---------|
+| `{ ok: true, ... }` | signed in / enrolled; the rest of the object is the server's answer |
+| `{ ok: false, reason: 'unsupported' }` | this browser has no WebAuthn; nothing was sent to the server |
+| `{ ok: false, reason: 'cancelled' }` | the person dismissed the enrollment prompt |
+| `{ ok: false, reason: 'no-credential' }` | sign-in: the authenticator offered nothing, or the person dismissed it |
+| `{ ok: false, reason: 'error', error }` | anything else, with the original error attached |
+
+#### The recent-authentication gate
+
+Adding a credential is adding a way in, and removing one can lock an account. Both are refused
+unless the caller has recently proved themselves, in one of two ways:
+
+- **the device key this request is signed with was registered within
+  `SPFN_AUTH_PASSKEY_RECENT_AUTH_MINUTES`** — that is when this device last presented a
+  credential, and it needs no new state; or
+- **the body carries `currentPassword`** and it verifies.
+
+Otherwise: **403 with `code: 'RECENT_AUTH_REQUIRED'`**. Branch on that code to prompt for the
+password and retry — it is a stable field, not a message to match on.
+
+An account with no password stored **cannot** satisfy the gate with a password, however
+plausible the value; it has to sign in again. The comparison still runs, against a dummy hash,
+so "no password on file" costs exactly what "wrong password" costs — otherwise response time
+becomes an oracle for which accounts are OAuth-only.
+
+#### Managing passkeys
+
+```typescript
+const { passkeys } = await authApi.listPasskeys.call({ body: {} });
+// → [{ passkeyId, label, deviceType, backedUp, transports, createdAt, lastUsedAt }]
+
+await authApi.renamePasskey.call({ body: { passkeyId, label: 'Old iPhone' } });
+await authApi.revokePasskey.call({ body: { passkeyId } });
+```
+
+- **Neither `credentialId` nor the public key is ever returned.** They are what an
+  authenticator is addressed by; the list exists to let someone recognise a credential and
+  point at it, which the label, the device type and the last-used moment do.
+- **`deviceType` is `singleDevice` or `multiDevice`**, and `backedUp` says whether a
+  multi-device credential actually has been. "This one only exists on that phone" is what the
+  owner needs before revoking the other entry.
+- **Revocation is soft, and the credential id stays reserved for good.** A credential someone
+  cut off can never be enrolled again — not on another account, and not on the same one
+  (`PasskeyAlreadyRegisteredError`, 409). Re-enrolling means a fresh credential.
+- **A passkey id you do not own answers 404.** Every lookup is owner-scoped, so the answer is
+  only ever "not yours".
+- **Renaming has no recent-authentication gate**: a label is display only and nothing is
+  authorized by it.
+
+#### Recovery — read this before shipping a passkey-only sign-up
+
+The ways back into an account are: a live passkey, a password, a linked social account, or a
+verified email address — the last one because [Password reset](#password-reset-verified-email)
+can always give such an account a password back. Nothing else; support cannot restore an
+account that has none of the four.
+
+That is why **revoking the last live passkey is refused (409, `code:
+'LAST_RECOVERY_CREDENTIAL'`) when the account has no password, no linked social account and no
+verified email.** A phone-only account is the case that reaches it. The refusal is not
+paternalism; it is the absence of an undo. Branch on that code to offer "set a password
+first", "link an account first", or "confirm your email address first".
+
+The same fact should shape your sign-up: an account created without a password, without an
+email and given one passkey has exactly one way in, and losing the device loses the account.
+Ask for a password, an address, or a social link before, or shortly after, the passkey.
+
+#### How the ceremonies are kept honest
+
+- **Discoverable credentials only** (`residentKey: 'required'`). `login/options` takes an empty
+  body — `additionalProperties: false`, so an `email` field is a 400 rather than something
+  quietly ignored — and always answers with an empty `allowCredentials`. There is no input
+  that could make its answer differ by whether an account exists.
+- **A revoked credential and one that was never here answer identically** on `login/verify`.
+  Anything else would say whether this account once had it.
+- **Challenges are one-time database rows**, spent by a single conditional `UPDATE`. Two
+  verifies arriving with the same challenge produce one winner and one refusal, across
+  instances. A challenge is bound to its ceremony (`registration` / `authentication`) and, for
+  enrollment, to the account that minted it.
+- **A refusal leaves the challenge live.** Spending happens inside the transaction that writes
+  what it authorizes, so a failure rolls it back and the ceremony is retryable; only a success
+  is unrepeatable.
+- **A signature counter that goes backwards refuses the sign-in and leaves the row alone.** It
+  is the signal a cloned authenticator would produce — but a synced passkey reports 0 forever
+  and a restored device can hit it, so auto-revoking would lock people out on a false
+  positive. The refusal is logged at `warn` with the passkey id; a human decides what it meant.
+- **Attestation is `none`.** Verifying an attestation statement would tell us which
+  authenticator model was used and nothing about who is holding it.
+
+#### Errors
+
+| error | status | `code` | when |
+|-------|--------|--------|------|
+| `PasskeyChallengeError` | 401 | — | the challenge is unknown, expired, already spent, of the other ceremony, or of another account |
+| `PasskeyVerificationError` | 401 | — | origin, rpId, signature or counter — and, on sign-in, an unknown or revoked credential |
+| `PasskeyNotFoundError` | 404 | — | a passkey the caller does not own, or one already revoked |
+| `PasskeyAlreadyRegisteredError` | 409 | — | that credential is on file for some account, revoked ones included |
+| `RecentAuthenticationRequiredError` | 403 | `RECENT_AUTH_REQUIRED` | the session proved itself too long ago and carried no password |
+| `LastRecoveryCredentialError` | 409 | `LAST_RECOVERY_CREDENTIAL` | revoking it would leave no way back in |
+| `PasskeyConfigError` | boot | — | an origin off the rpId or not https, or an unsupported user-verification value |
+
+#### Events
+
+`passkeyEnrolledEvent` (`auth.passkey.enrolled`: `userId`, `passkeyId`, `label?`) and
+`passkeyRevokedEvent` (`auth.passkey.revoked`: `userId`, `passkeyId`, `reason`) fire after
+commit. `authLoginEvent.provider` gains `'passkey'`. Subscribe to the first to tell the owner
+a new way into their account appeared — which is what it is.
+
+#### The case table
+
+The behaviour above is asserted row by row in
+`src/__tests__/integration/passkeys.test.ts`; each `it` is named for its row.
+
+| row | situation | outcome |
+|-----|-----------|---------|
+| E1 | fresh session, no passkeys | 200, empty `excludeCredentials` |
+| E2 | session key 11 min old, no password | 403 `RECENT_AUTH_REQUIRED` |
+| E3 / E4 | 11 min old, correct / wrong password | 200 / 403 — byte-identical to E2 |
+| E5 | no password on the account, 11 min old | 403; a password can never speak for it |
+| E6 | valid attestation | 200; row written, challenge spent, event emitted |
+| E7 / E8 | challenge replayed / expired | 401; one row, no row |
+| E9 / E10 | another account's / the other ceremony's challenge | 401 |
+| E11 | credential already on some account | 409 |
+| E12 / E13 | wrong origin / wrong rpId | 401 |
+| E14 | two live passkeys | both listed in `excludeCredentials` |
+| E15 | label empty or over 64 chars | 400; challenge stays live |
+| E16 | two concurrent verifies, one challenge | one 200, one 401, one row |
+| L1 / L2 | empty options body / an `email` in it | 200 with empty `allowCredentials` / 400 |
+| L3 | valid assertion | 200, same answer as `login`; counter and device key move |
+| L4 / L5 | revoked / unknown credential | 401, byte-identical |
+| L6 / L7 / L8 | challenge spent / expired / wrong kind | 401; no device key |
+| L9 / L17 | bad signature / wrong origin | 401; counter unmoved |
+| L10 | counter went backwards | 401; row untouched, warn logged, not revoked |
+| L11 | synced passkey reporting 0 both times | 200 |
+| L12 / L13 | disabled / pending deletion | 403, the same errors password login gives |
+| L14 | device-key fields missing (proxy bypassed) | 400; challenge stays live |
+| L15 | an old session key named in the body | it is revoked as the new one is registered |
+| L16 | two concurrent verifies, one assertion | one 200, one 401, one device key |
+| M1 | 2 live + 1 revoked | 2 entries, no credential id, no public key |
+| M2 / M9 | someone else's / an already revoked passkey | 404 |
+| M3 / M4 | rename / revoke on a recent session | 200; revoke emits its event |
+| M5 | revoke on an 11-minute-old session | 403 `RECENT_AUTH_REQUIRED` |
+| M6 / M7 / M8 | last passkey, no password: alone / with a social account / with a second passkey | 409 / 200 / 200 |
+| M10 | re-enrolling a revoked credential | 409 |
+| K1 / K4 | two concurrent revokes: 2 passkeys and nothing else / 1 passkey and a password | 200 + 409 / 200 + 404 |
+| K2 / K3 | last passkey, no password: with a verified email / phone-only | 200 / 409 |
+
+Configuration rows C1–C6 are in `src/__tests__/unit/passkey-config.test.ts`.
+
 ### Writing protected routes (route DSL)
 
 This is the current SPFN route DSL — `route.<method>().input().use().skip().handler()` registered
@@ -360,6 +950,16 @@ Both convenience URL APIs seal `metadata` into the encrypted OAuth state. On a n
 signup, the callback passes it to `beforeRegister` and `authRegisterEvent`; existing-account
 logins do not run the registration hook.
 
+`returnUrl` must be a path inside your app — absolute URLs, `//host`, `..`, a backslash, and a
+tab/CR/LF (which a URL parser strips, turning `/<tab>/host` into `//host`) are refused, so a
+real login cannot become an open redirect. The start seams answer an unsafe value with a 400
+`ValidationError`; the seams that already hold a logged-in user replace the destination instead
+of failing the login — `OAuthCallback` navigates to `/` and `createOAuthCallbackHandler`
+redirects to its `defaultRedirectUrl` (`/` unless you pass one). The rule is exported as
+`isSafeReturnPath` from `@spfn/auth/server`, `@spfn/auth/nextjs/server`, and
+`@spfn/auth/nextjs/client` for apps that validate a destination before calling
+`getGoogleOAuthUrl`.
+
 Built-in OAuth routes: `POST /_auth/oauth/google/url`, `GET /_auth/oauth/google` (redirect),
 `GET /_auth/oauth/google/callback`, `POST /_auth/oauth/finalize`, `GET /_auth/oauth/providers`,
 plus the provider-generic `POST /_auth/oauth/start`. `getGoogleAccessToken(userId)` returns a
@@ -446,9 +1046,25 @@ process), which differs from the API process in a split deployment — the callb
 matches every `spfn_oauth_csrf*` cookie candidate against the state nonce, so no PORT
 coordination is needed.
 
+An explicit `SPFN_AUTH_<PROVIDER>_REDIRECT_URI` is checked when the server boots, because the
+value used to be read lazily on the first OAuth request and a wrong one surfaced much later as
+a CSRF refusal nobody traced back to it. A value that does not parse, or whose origin is not the
+web app origin, or whose path is not `/_auth/oauth/<provider>/callback`, refuses to start — one
+error naming every offending variable:
+
+```
+SPFN_AUTH_GOOGLE_REDIRECT_URI must be on the web app origin (http://localhost:3790) at
+/_auth/oauth/google/callback: the callback's CSRF cookie is host-only and /_auth/* is forwarded
+to the API by the app's rewrite. Unset it to use the default, fix the origin, or set
+SPFN_AUTH_OAUTH_CALLBACK_ORIGIN_CHECK=off for a deployment that deliberately terminates the
+callback elsewhere.
+```
+
 One caveat: the direct `POST /_auth/oauth/start` flow (no Next.js interceptor) sets its CSRF
-cookie on the **API host**. If you use that flow in a split deployment, set
-the corresponding provider redirect URI explicitly to the API host callback instead.
+cookie on the **API host**. If you use that flow in a split deployment, set the corresponding
+provider redirect URI explicitly to the API host callback **and**
+`SPFN_AUTH_OAUTH_CALLBACK_ORIGIN_CHECK=off` — that is the one deployment the check is wrong
+about, and `off` is the only value that disables it.
 
 ### Native social sign-in (mobile / web id_token)
 
@@ -696,6 +1312,155 @@ export default async function AdminPage()
 Also exported: `getAuthSessionData`, `getUserRole`, `getUserPermissions`, `hasAnyRole`,
 `hasAnyPermission`, the OAuth pending-session helpers, and `createOAuthCallbackHandler`.
 
+### Emptying the cookie jar from a route handler or middleware
+
+`clearSession()` works where `next/headers` is writable. The page that answers *the API
+refused your session* is usually a route handler or middleware holding a `NextResponse`
+instead — `clearSessionCookies(response)` expires the session, key-id, OAuth-pending and
+CSRF cookies on it and returns the same response, so the call chains:
+
+```typescript
+import { clearSessionCookies } from '@spfn/auth/nextjs/server';
+
+export function GET(request: NextRequest)
+{
+    return clearSessionCookies(NextResponse.redirect(new URL('/login', request.url)));
+}
+```
+
+Never spell the names in your app. They carry an `SPFN_PORT` suffix (`spfn_session_4001`),
+so two dev instances do not overwrite each other's cookies, and a hand-written copy of that
+rule clears the wrong cookie without failing. Read them from `sessionCookieNames()`, which
+returns `{ session, keyId, oauthPending, csrf }` at call time.
+
+## CSRF protection
+
+Cookie-authenticated mutations carry a CSRF token by default. Nothing to write: the
+Next.js proxy issues the token with the session and the api client sends it back.
+
+**What it protects.** The session cookie is `SameSite=Lax`, which already blocks the
+classic cross-site form POST. What remains is what Lax does not cover: a sibling
+subdomain that can write cookies on your parent domain (an XSS on `blog.example.com`
+against `app.example.com`), browsers that predate or mis-implement Lax, and a domain
+layout that drifts into `SameSite=None` later. This closes those.
+
+**What it does not protect.** Nothing here helps against XSS on your own origin.
+Script running on your origin can read the token cookie and call your API as the
+user — that is true of every CSRF scheme, and no token design changes it. Same-origin
+XSS is out of scope; Content-Security-Policy and output escaping are the answer to it.
+
+### How it works
+
+- On login, OAuth finalize, key rotation and every session renewal, the proxy sets
+  `spfn_csrf` — a readable (non-HttpOnly) cookie holding only an HMAC of the session's
+  key id, keyed by a subkey derived from `SPFN_AUTH_SESSION_SECRET`. No new variable,
+  and the raw session secret is never used as the token key. Sessions that predate
+  the feature get one on their first authenticated response, so upgrading does not
+  require anyone to sign in again.
+- The api client mirrors the cookie into the `x-spfn-csrf` header on **every** RPC call,
+  GET-shaped ones included — see "Which requests are checked" for why it cannot narrow
+  that itself. Where the header is *checked* is the proxy's decision, not the client's.
+- The proxy **recomputes** the expected value from the session it just unsealed and
+  compares it to the header, in constant time. It never compares the cookie to the
+  header — that is the classic double-submit weakness, and it is exactly what a
+  sibling subdomain defeats by tossing a cookie it chose. A tossed cookie fails here.
+- The token derives from the session key id, so rotating the key invalidates it. The
+  proxy reissues the cookie in the same response that rotates or renews the session.
+
+The check runs in the proxy, not the backend, because only the proxy knows the
+request's credential was ambient: it turns the session cookie into a short-lived
+bearer JWT, so the backend sees `scheme:'bearer'` for cookie callers and for genuine
+bearer clients alike.
+
+### Which requests are checked
+
+Only requests the proxy authenticates from the session cookie, and only when the
+resolved **route** method is not GET/HEAD/OPTIONS.
+
+Route method, not the method the browser used to reach the proxy. The api client picks
+its wire method from whether the input has a body, and holds no route map — that is the
+point of "no metadata codegen required" — so a mutation with nothing to send travels as
+GET. `logout` is `POST /_auth/logout`; `revokeOpsToken` is
+`DELETE /_auth/ops-tokens/:id`, called with only a path param. Both are `GET` on the
+wire and both are forwarded as the route's real method. A client that withheld the
+header on GET-shaped calls would therefore 403 them under `enforce`, which is why the
+contract is "every call carries it" and the proxy alone decides where it is checked.
+Gating in the proxy on the wire method would be worse still: a cross-site top-level GET
+navigation *does* carry a `SameSite=Lax` cookie, so every mutation would stay reachable
+that way.
+
+Untouched, by construction: requests with no session, direct-to-backend bearer
+clients, `clientProofV1` mobile callers, machine and ops tokens. None of them pass
+through this code. A request without a session is answered exactly as before (the
+backend returns 401) — a CSRF refusal only ever answers an authenticated request, so
+the refusal itself cannot tell an anonymous caller whether anyone is signed in.
+
+### Modes
+
+| Mode | Behaviour |
+|---|---|
+| `off` | No check. |
+| `warn` | **Default.** Allows the request, logs one line per request that would be refused. |
+| `enforce` | Refuses with `403 {"error":"Forbidden","message":"CSRF token missing or invalid"}`. |
+
+Existing apps get signal before breakage: unset means `warn`. Watch for
+`@spfn/auth:interceptor:csrf` lines, then switch on. Apps scaffolded by `spfn init`
+start at `enforce`.
+
+```bash
+# .env.local — read by the Next.js process, where the proxy runs
+SPFN_AUTH_CSRF=enforce
+```
+
+```typescript
+import { configureAuth } from '@spfn/auth/server';
+
+configureAuth({
+    csrf: {
+        mode: 'enforce',
+        // Exact backend route paths, params already substituted — not /api/rpc/… URLs.
+        // For endpoints a browser session never calls, e.g. webhook receivers that
+        // authenticate themselves by signature. An exempt path is unprotected for
+        // cookie callers too, so list only endpoints that carry their own auth.
+        exemptPaths: ['/webhooks/stripe'],
+    },
+});
+```
+
+`configureAuth` wins over the environment variable. `enforce` and `warn` both need
+`SPFN_AUTH_SESSION_SECRET` — sessions need it anyway — and refuse rather than quietly
+passing everything if it is missing.
+
+### If a request is refused
+
+A refusal in a running app almost always means the token cookie is gone or stale while
+the session is not — cleared by hand or by an extension, or a session that predates this
+feature. Rotation is not a cause: the response that rotates the key reissues the cookie
+in the same breath, and one browser has one jar, so other tabs pick the new value up
+with it.
+
+Two things repair it, and both are mechanical:
+
+- **The 403 carries the fix.** The proxy is the one emitting the refusal, so it sets a
+  fresh `spfn_csrf` on that very response. A browser that repeats the mutation succeeds.
+  The refusal is otherwise unchanged — same status, same body.
+- **Any authenticated response reissues a wrong one.** A response whose request arrived
+  with no CSRF cookie, or with one that no longer matches the session, queues the
+  correct value. A cookie that is merely *present* is not taken as proof it is right.
+
+**The client does not retry a refused call**, so a user sees one failure before the
+repaired state takes effect — the framework fixes the browser, not the click.
+
+**Limitation — calls made from the server.** A Server Component cannot set cookies at
+all, and Next.js does not forward `Set-Cookie` from a fetch the api client made on the
+server to the browser. So neither repair reaches the jar when the refused call came from
+a Server Component, a Server Action or a Route Handler; the next browser-originated
+request through the proxy is what heals it. Server-side callers otherwise need no
+change: the api client reads the whole jar through `next/headers`, and an explicit
+`cookies` option merges over that rather than replacing it. Only a caller that
+hand-builds a jar somewhere `cookies()` cannot be reached — build time, static
+generation — has to include the CSRF cookie itself.
+
 ## How do I define roles and permissions?
 
 Built-in roles: `superadmin` (priority 100), `admin` (80), `user` (10). Built-in permissions:
@@ -788,10 +1553,26 @@ authRegisterEvent.subscribe(async ({ userId, email, provider, metadata }) =>
 });
 ```
 
-Payload types: `AuthLoginPayload`, `AuthRegisterPayload`, `InvitationCreatedPayload`,
+`authLoginEvent`'s `provider` is `'email'`, `'phone'`, a social provider, `'device'` or
+`'passkey'`. `'device'` is a [device-code login](#device-code-login), where the account was
+proven on another device that was already signed in and no credential was presented here;
+`'passkey'` is a [WebAuthn assertion](#passkeys-webauthn). `authRegisterEvent` accepts
+neither: a device-code request can only ever be approved by an account that already exists,
+and a passkey has to be enrolled from a session that already exists, so neither is a signup.
+
+`passkeyEnrolledEvent` (`auth.passkey.enrolled`) and `passkeyRevokedEvent`
+(`auth.passkey.revoked`) fire after commit when a passkey is added or retired.
+
+`authPasswordResetEvent` (`auth.password.reset`: `userId`, `email`) fires after commit when a
+[password reset](#password-reset-verified-email) completes. Distinct from a password
+*change*, which is made from a session that already proved itself: this one is made by
+whoever opened a link in a mailbox, so it is the notice to send the owner.
+
+Payload types: `AuthLoginPayload`, `AuthRegisterPayload`, `AuthPasswordResetPayload`, `InvitationCreatedPayload`,
 `InvitationAcceptedPayload`, `AuthDeletionRequestedPayload`, `AuthDeletionCancelledPayload`,
 `AuthDeletionCompletedPayload`, `OAuthUnlinkedPayload` (`auth.oauth.unlinked` — provider-side
-disconnect, see the OAuth unlink-notify section). These events also bind to `@spfn/core/job`
+disconnect, see the OAuth unlink-notify section), `PasskeyEnrolledPayload`,
+`PasskeyRevokedPayload`. These events also bind to `@spfn/core/job`
 jobs via `.on(event)`.
 
 ## Registration gate (`beforeRegister`)
@@ -826,6 +1607,8 @@ Notes:
   seeding in `initializeAuth()`.
 - OAuth signups have no client-typed fields unless you pass `metadata` at OAuth start — decide
   per channel (reject, or allow and collect during onboarding).
+- `email` arrives trimmed and lower-cased, the same form the account is stored under, so a
+  denylist or domain allowlist keyed on the address is not walked past by capitalizing it.
 - On the `oauth` channel `email` is the provider-reported address and may be **unverified**
   (the created account then stores `email` as `null`). The context carries
   `emailVerified` — an email-based allow/block policy must check it before trusting `email`.
@@ -860,6 +1643,13 @@ export const opsRouter = createOpsRouter({
 }, { auth: opsTokenAuth });
 ```
 
+An application that admits both credentials on one route has to tell an ops token from a
+session JWT *before* either is verified. Do not re-type the literal: `isOpsToken(bearer)`
+and the `OPS_TOKEN_PREFIX` it tests against are both exported from `@spfn/auth/server`, so
+the shape has one definition and a copy in application code cannot drift from it.
+`isOpsToken` answers shape only — it takes a raw header value, returns `false` for a
+missing or non-string one, and leaves unknown/revoked/expired to verification.
+
 `opsRoute` comes from `@spfn/core` **0.3.0-beta.2** onwards; before that release an ops
 route spelled its own `/_ops/` prefix with `route`.
 
@@ -903,6 +1693,81 @@ same 401, so whether a presented secret ever existed is not inferable. A valid t
 missing a route's scope answers 403 naming only the missing scope. `'*'` grants every
 scope.
 
+### One route, two credentials (`opsOrUser`)
+
+An operator action is scripted today — the CLI, holding an ops token — and driven from an
+admin console tomorrow, a browser holding a user session. That is one route with two
+admissible credentials, and neither middleware admits both: `authenticate` refuses an
+`spfn_ops_` bearer before any scope guard runs (see [Machine principals](#machine-principals-registermachineverifier)),
+and `opsTokenAuth` admits nothing else.
+
+```typescript
+import { opsOrUser, getAuth, getOpsToken } from '@spfn/auth/server';
+
+export const exportSignups = route.get('/admin/signups/export')
+    .use([opsOrUser({ opsScopes: ['waitlist:read'], permissions: ['admin.waitlist'] })])
+    // or by role:            opsOrUser({ opsScopes: ['waitlist:read'], roles: ['admin'] })
+    // or both (AND):         opsOrUser({ opsScopes: ['waitlist:read'], roles: ['admin'], permissions: ['admin.waitlist'] })
+    .handler(async (c) =>
+    {
+        // exactly one of these is set
+        const ops = getOpsToken(c.raw);   // the ops branch
+        const user = getAuth(c.raw);      // the session branch
+    });
+```
+
+**The branch is chosen by credential shape, never by caller choice.** The raw
+`Authorization` bearer is tested with [`isOpsToken`](#ops-tokens-spfn-ops); a match runs
+`opsTokenAuth` then `requireOpsScope(...opsScopes)`, and everything else — a user JWT,
+another machine namespace, a malformed header, no header — runs `authenticate` then the
+session guards. Nothing in the request selects a branch except the credential it presents,
+so a caller cannot ask for the weaker check.
+
+**`roles` and `permissions` are AND, roles first.** Two lists only ever narrow. An OR would
+mean that adding one role voids the whole permission list, which is the opposite of what a
+reader of the two lists expects. Roles run first because the role is already on the auth
+context while permissions cost a lookup — so a caller with the wrong role is refused for the
+wrong role. Giving neither list is a definition-time error, as is an empty `opsScopes`: a
+configuration that would admit a credential unchecked fails at boot, not on a request.
+
+**No implicit admin bypass.** Permissions match by name only, and the ops branch has no role
+concept, so neither branch has a principal that passes by virtue of being an administrator.
+A refusal is the selected branch's own refusal, with that branch's existing status and
+message — no error class and no wire message is introduced here.
+
+`opsOrUser` carries `skips: ['auth']`, so a route using it auto-skips the server-level
+`auth` middleware exactly as `optionalAuth` and `opsTokenAuth` do. No `.skip(['auth'])` by
+hand.
+
+**Cookies.** The backend never reads them. A browser session reaches a route as a Bearer
+token because `@spfn/auth/nextjs/api` forwards it as one, so through the app a console
+request is the session rows below; a request carrying only a `Cookie` header is an
+unauthenticated request here.
+
+| bearer | branch | answer |
+|---|---|---|
+| `spfn_ops_…` valid, scope present (or `*`) | ops | 200; `getOpsToken` set, `getAuth` null |
+| `spfn_ops_…` valid, scope missing | ops | 403 `Ops token lacks scope` |
+| `spfn_ops_…` unknown / revoked / expired | ops | 401 `Invalid ops token` (one message for all three) |
+| `spfn_ops_` prefix alone | ops | 401 `Invalid ops token` |
+| user JWT valid, permission held | user | 200; `getAuth` set, `getOpsToken` null |
+| user JWT valid, permission missing | user | 403 `InsufficientPermissionsError` |
+| user JWT expired / bad signature | user | 401 (the existing `authenticate` message) |
+| token in a *registered* machine namespace, not ops | user | 401 — the user path admits no machine credential |
+| malformed bearer / no `Authorization` | user | 401 |
+| session cookie only, no bearer | user | 401 — see Cookies above |
+| `x-spfn-auth-profile` + user JWT | user | `PROFILE_REJECTED` (existing `authenticate` behaviour) |
+| `x-spfn-auth-profile` + ops token | ops | header ignored; `opsTokenAuth` reads `Authorization` only |
+| ops token on a plain `authenticate` route | — | 401, unchanged |
+| `opsScopes: []`, or neither `roles` nor `permissions` | — | throws at definition |
+| server-level `auth` registered | — | auto-skipped on this route |
+| `roles: ['admin']` only; role admin | user | 200 |
+| `roles: ['admin']` only; role user | user | 403 `InsufficientRoleError` |
+| `roles` + `permissions`; role matches, permission missing | user | 403 `InsufficientPermissionsError` |
+| `roles` + `permissions`; permission held, role wrong | user | 403 `InsufficientRoleError` (role is checked first) |
+
+`opsOrUser` is available from **0.3.0-beta.11**.
+
 ## Mobile clientProofV1 (`@spfn/auth/client-proof`)
 
 Server side of the spfn-mobile native SDK auth profile (issue #46; asymmetric revision in
@@ -917,6 +1782,12 @@ the fixed-string contract error envelope (`PROOF_INVALID` · `PROOF_REPLAYED` ·
 `SESSION_REVOKED` · `PROFILE_REJECTED` · `CONTRACT_UNSUPPORTED` — SDKs classify by code, never
 HTTP status).
 
+Before minting the first proof in each client process, the client calls the built-in
+`GET /_core/time` operation (`core.time`) and establishes its proof epoch from
+`serverTimeMillis`. This prerequisite is unproven and session-free. If the operation is
+unavailable or its response cannot be decoded, proof minting fails closed — there is no silent
+fallback to the device's unsynchronized wall clock.
+
 - Wire headers (D23, ratified): `x-spfn-auth-profile`, `x-spfn-client-id`, `x-spfn-key-id`,
   `x-spfn-nonce`, `x-spfn-issued-at`, `x-spfn-proof`, `x-spfn-session`.
 - A request body must be **byte-canonical** — a body that parses but re-encodes differently is
@@ -944,6 +1815,29 @@ HTTP status).
   construction or through the `/control/register-key` hook; the private half never reaches
   the server. No persistence — a production enrollment/rotation story is phase 2.
 
+### Clock synchronization and proof-time boundaries (contract 0.9.0)
+
+`core.time` is imported from `@spfn/core` rather than restated by auth: operation ID, method,
+path, auth class, session requirement, and the closed `ServerTimeResponse` schema all come from
+the core route contract. The mobile contract records it as a bodyless GET prerequisite and
+requires one synchronization before the first proof minted in each process. It does not prescribe
+persistent offset storage, retry sleeps, or device-specific margins.
+
+The server admission rule remains strict: `age = serverNow - issuedAtMillis` must satisfy
+`0 <= age <= 300000`. Synchronization does not widen the replay window or change nonce retention.
+A refused request still leaves its nonce unused; only admission spends it.
+
+| `serverNow - issuedAtMillis` | Result |
+|---:|---|
+| `0` | accept |
+| `-1` (proof is 1 ms in the future) | `PROOF_EXPIRED` |
+| `300000` | accept |
+| `300001` | `PROOF_EXPIRED` |
+
+When `core.time` cannot be read, the client must surface that synchronization failure and stop
+before sending a proof. Using `Date.now()` or a platform wall clock as an implicit fallback would
+reintroduce the skew failure this prerequisite closes.
+
 ### The contract version on the wire (contract 0.6.0)
 
 A client compiled and shipped separately from the server cannot be fixed by redeploying. Until
@@ -992,6 +1886,8 @@ Every operation in the exported bundle carries `since` — the contract version
 | `auth.clientProof.handshake`, `echo.send`, `items.list` | 0.1.0 |
 | `auth.enroll.register`, `auth.enroll.login`, `auth.enroll.oauthNative`, `auth.keys.rotate` | 0.3.0 |
 | `auth.keys.list`, `auth.keys.revoke`, `auth.keys.revokeAll` | 0.4.1 |
+| `core.time` | 0.9.0 |
+| `auth.device.start`, `auth.device.poll`, `auth.device.info`, `auth.device.approve`, `auth.device.deny` | 0.10.0 |
 
 - **This is history, not policy.** The mobile contract's compatibility policy is `allOrNothing`: one
   contract version passes or refuses the whole surface, so these three fields change no verdict here.
@@ -1063,6 +1959,386 @@ app.post('/v1/echo', createClientProofGuard(state), (c) => { /* handler */ });
 Responses and errors MUST be canonical bytes with the contract envelope — build them with
 `encodeCanonicalJson`/`ClientProofRefusal`, never `c.json()` (key order and int64 differ).
 
+## Custom auth profiles (`registerAuthProfile`)
+
+`clientProofV1` is not a special case in the middleware — it is one entry in a registry
+`authenticate` and `optionalAuth` dispatch on. An app registers its own scheme the same way,
+without forking the middleware or wrapping it:
+
+```typescript
+import { registerAuthProfile, type AuthContext } from '@spfn/auth/server';
+import { UnauthorizedError } from '@spfn/core/errors';
+
+// At boot — server.config.ts, before the server starts taking requests.
+registerAuthProfile('serviceTokenV1', {
+    verify: async (c): Promise<AuthContext> =>
+    {
+        const user = await findServiceAccount(c.req.header('x-acme-service-token'));
+        if (user === null)
+        {
+            // A refusal leaves the verifier as a throw. It reaches the app's
+            // error handler exactly as the Bearer path's does.
+            throw new UnauthorizedError({ message: 'Invalid service token' });
+        }
+
+        return {
+            user,
+            userId: String(user.id),
+            keyId: 'service-token',
+            role: null,
+            locale: 'en',
+            scheme: 'serviceTokenV1',
+        };
+    },
+});
+```
+
+A request naming the profile is then answered by that verifier:
+
+```http
+POST /v1/reports
+x-spfn-auth-profile: serviceTokenV1
+x-acme-service-token: <the app's own credential>
+```
+
+- **Register at boot, before the first request.** The registry is read on every dispatch, so a
+  profile registered later is simply a profile the requests before it did not have. Registration
+  is not frozen after startup — it is a contract, not a runtime check.
+- **A duplicate name throws**, `clientProofV1` included. Replacing a registered verifier silently
+  is how an import order or a copied profile name swaps the code that decides who is admitted, so
+  there is no override — and no unregistration API for the same reason.
+- **The verifier must expose a callable `verify`**, and what it resolves must carry a `userId` — a
+  verifier that cannot admit anyone is refused at boot, and a resolve without a principal (`null`,
+  the JS idiom for "no user") is refused as a throw rather than routed as authenticated.
+- **An unknown profile is still refused** (`PROFILE_REJECTED`, 400): registering one name does not
+  open the header to others.
+- **Mixing is still refused.** A request carrying both `x-spfn-auth-profile` and `Authorization` is
+  rejected before either path runs; a custom verifier never sees it.
+- **A verifier's throw propagates**, and only the internal clientProofV1 contract refusal is
+  answered with the canonical envelope. Under `optionalAuth` too: credentials that were presented
+  and refused are never downgraded to anonymous passage — only "presented nothing" continues
+  without an auth context.
+- **`AuthContext.scheme` is an open union** — `'bearer' | 'clientProofV1' | 'oneTimeToken' | (string
+  & {})`. The built-in names keep their autocomplete and a registered profile names its own scheme.
+  The field stays informational: downstream permission and tenant code takes one principal shape and
+  never branches on how it was produced.
+
+## Authorization server for MCP clients
+
+Let Claude Code and Codex connect to your app's `/mcp` endpoint as the user, over the flow
+they already speak: OAuth 2.1 with dynamic client registration and PKCE.
+
+```console
+$ claude mcp add --transport http acme https://api.acme.com/mcp
+$ claude
+> /mcp
+```
+
+Between those two lines the CLI discovers `/.well-known/oauth-authorization-server`, registers
+itself, opens a browser at your consent screen, catches the redirect on a loopback port, and
+exchanges the code for a token. Nobody pastes anything.
+
+The feature is opt-in and the opt-in is one block:
+
+```typescript
+createAuthLifecycle({
+    authorizationServer: {
+        scopes: {
+            'mcp:read': 'Read your projects and tasks',
+            'mcp:write': 'Create and edit your tasks',
+        },
+        defaultScopes: ['mcp:read'],      // what a request with no `scope` asks for. default: all of them
+        // issuer: 'https://api.acme.com',           // default: SPFN_API_URL
+        // authorizeUrl: 'https://acme.com/oauth/authorize',  // default: {app url}/oauth/authorize
+        // allowedRedirectOrigins: [],    // https origins a client may register. loopback needs no entry
+        // accessTokenTtlMs: 8 * 60 * 60 * 1000,     // default 8 hours
+        // refreshTokenTtlMs: 30 * 24 * 60 * 60 * 1000,   // default 30 days
+        // codeTtlMs: 60 * 1000,          // default 60 seconds
+    },
+})
+```
+
+Without that block every endpoint below answers 404 and nothing else changes — including the
+boot check, which does not run. `scopes` is the one setting with no default: the names are
+your application's vocabulary, they are published in the metadata document and read aloud on
+the consent screen, and there is nothing to derive them from.
+
+| Endpoint | Host | Auth | What it is |
+| --- | --- | --- | --- |
+| `GET /.well-known/oauth-authorization-server` | API | public | RFC 8414 discovery — the first request any client makes |
+| `POST /_auth/oauth2/register` | API | public, IP rate limited | RFC 7591 dynamic registration. Public clients only |
+| `GET /_auth/oauth2/authorize` | API | `authenticate` | What the consent screen should say. Records nothing |
+| `POST /_auth/oauth2/authorize` | API | `authenticate` | The decision. Mints the code |
+| `POST /_auth/oauth2/token` | API | public, IP rate limited | `authorization_code` and `refresh_token` |
+| `POST /_auth/oauth2/revoke` | API | public (RFC 7009) | `client_id` required; 200 for an unknown token as surely as for a real one |
+| `GET /_auth/oauth2/grants` · `DELETE /_auth/oauth2/grants/:id` | API | `authenticate` | What the user has connected, and the button that disconnects it |
+| `GET /oauth/authorize` · `POST /oauth/authorize` | web | session | The consent screen itself — see the note at the end |
+
+Two lines wire it to `@spfn/mcp`:
+
+```typescript
+import { verifyAccessToken } from '@spfn/auth/server';
+
+export const mcp = createMcpRoute({ validateToken: verifyAccessToken, tools: [...] });
+```
+
+`verifyAccessToken(token, resource)` answers `{ clientId, scopes, expiresAt, userId }` or
+`null`, and `null` is a refusal — `@spfn/mcp` ≥ 0.3.0-beta.3 accepts it as one rather than
+requiring a throw. `expiresAt` is seconds since the epoch, like every other OAuth field here.
+
+- **Only loopback and origins you allowed.** A client may register `http://localhost:*`,
+  `http://127.0.0.1:*` or `http://[::1]:*` — a CLI cannot know which port the OS will hand it,
+  so the **port** is the one thing allowed to vary. Nothing else does: host, path and query
+  must match the registration exactly, a fragment is refused at registration and at request,
+  and plain `http` anywhere else is refused outright. An `https` redirect URI has to be on an
+  origin listed in `allowedRedirectOrigins`.
+- **Those three spellings are three registrations.** `localhost`, `127.0.0.1` and `[::1]` do
+  not stand in for one another — they resolve differently on a machine with a split-horizon
+  resolver, and a client answered on a host it did not register is a client something
+  redirected. IPv6 is the one place spelling is folded: `http://[0:0:0:0:0:0:0:1]:5/cb` and
+  `http://[::1]:5/cb` are the same registration, because both sides are read through
+  `new URL(...).hostname`.
+- **An unknown client or a mismatched redirect URI is shown, never redirected.** There is no
+  vetted URI to send that error to, and sending it to the one the request supplied is the open
+  redirect the whole rule exists to close. Every other authorize-time error —
+  `invalid_request`, `invalid_scope`, `invalid_target`, `access_denied` — goes back to the
+  client on its registered URI, which is the only form the waiting CLI can read.
+- **PKCE S256, and nothing else.** No `plain`, and no request without a challenge. The code
+  arrives on a loopback port that any process on the machine could have been listening on.
+- **`resource` is required** (RFC 8707) and the token is only good against it. A token your
+  user approved for your MCP server cannot be replayed against a neighbouring deployment that
+  shares this authorization server.
+- **A code is spent by the statement that reads it**, so of two exchanges arriving together
+  exactly one gets tokens — and **presenting a code twice revokes the grant**, because by then
+  somebody else may hold what the first exchange produced.
+- **Refresh tokens rotate, and a rotated one is marked rather than deleted.** Presenting it
+  again revokes the grant, which kills the replacement as well as the replayed token: both
+  hang off the grant and there is no telling which holder is the thief. A refresh may ask for
+  a **subset** of the granted scopes and never for more; narrowing applies to that request and
+  leaves the user's consent record as they gave it.
+- **Every code and refresh failure is one `invalid_grant`, word for word.** Unknown, expired,
+  spent, wrong verifier, another client's. The endpoint is public, and an error that told
+  those apart would answer the question somebody holding a stolen value is asking.
+- **Token endpoint errors are RFC 6749 §5.2, not the SPFN envelope** —
+  `{ "error": "invalid_grant", "error_description": "..." }`, status 400,
+  `Cache-Control: no-store`. The client reading it is an OAuth library that knows those two
+  field names and nothing about this framework. Registration refusals are RFC 7591 §3.2.2 the
+  same way (`invalid_redirect_uri`, `invalid_client_metadata`).
+- **Nothing but a hash is stored.** Codes and tokens are `spfn_at_<64 hex>` /
+  `spfn_rt_<64 hex>` / 43 url-safe characters, and the value exists in the clear exactly once,
+  in the response that issues it. It is never logged and never put in an event.
+- **A global revocation reaches the grants.** `revoke-all`, a password change, a completed
+  password reset and a deletion request each revoke every grant the account has — so a CLI
+  holding a refresh token through "sign me out everywhere" cannot be back within the hour,
+  which is exactly the client that call was aimed at. The user's own
+  `DELETE /_auth/oauth2/grants/:id` does the same for one client, immediately.
+- **The issuer is checked at boot.** It must be an absolute URL with no path — the metadata
+  document is served at an origin's root and nowhere else — and it must be `https`, or `http`
+  on `localhost` / `127.0.0.1` / `[::1]` for development. Anything else refuses to start with
+  a message naming `SPFN_API_URL` or `authorizationServer.issuer`, whichever the value came
+  from. An application with no `authorizationServer` block never reaches this check. The one
+  value that is accepted and rewritten is a bare trailing slash: `https://api.acme.com/` is
+  stored as `https://api.acme.com`, the form `@spfn/mcp` derives, so the two documents naming
+  this server agree (RFC 8414 §3.3). That reduction happens where the config is resolved, not
+  in the boot check, so a document read without the lifecycle hook publishes the same issuer.
+- **Unapproved client rows are swept.** Registration is unauthenticated by necessity, so
+  `auth.oauth2.client-purge` (in `authJobRouter`, daily at 05:00) deletes clients older than a
+  day that no user ever approved. One with a grant against it is never touched. Registration
+  is also capped per IP two ways — a burst rate limit, and a cap on how many unapproved
+  clients one address may have standing, which a rate limit cannot express.
+- **`/mcp` tokens are not sessions.** An access token issued here authorizes the MCP surface
+  for the resource it names. It is not a user session and is not accepted by ordinary API
+  routes.
+
+### The consent screen
+
+The screen itself is one route file on the web app, at the path published as
+`authorization_endpoint`:
+
+```typescript
+// app/oauth/authorize/route.ts
+import { createOAuth2AuthorizeHandlers } from '@spfn/auth/nextjs/server';
+
+export const { GET, POST } = createOAuth2AuthorizeHandlers({ loginPath: '/login' });
+```
+
+`GET` asks `GET /_auth/oauth2/authorize` what the request is and draws it; `POST` checks the
+form's own CSRF token, sends the decision to `POST /_auth/oauth2/authorize`, and redirects the
+browser back to the waiting CLI. Neither decides anything — the API validates the request from
+scratch both times, because the form between the two calls is in the user's browser.
+
+| Option | What it is |
+| --- | --- |
+| `loginPath` | Where a visitor with no session goes. The handler appends `?returnUrl=` pointing at this request's own path and query, so signing in lands back on the screen with its parameters intact. The value is held to `isSafeReturnPath` like every other return destination in this package, and a refusal is a 400 screen rather than a redirect |
+| `render?` | `(view: OAuth2ConsentView) => string`, replacing the default body. Status, headers and the field set stay the handler's |
+
+Every answer carries `Cache-Control: no-store`, and every page also carries
+`Content-Type: text/html; charset=utf-8` and `Content-Security-Policy: frame-ancestors 'none'`
+— a consent screen that can be framed is a consent screen that can be clickjacked.
+
+- **The two refusal kinds become the two answers.** `unknown_client` and
+  `redirect_uri_mismatch` are shown on a 400 screen with no `Location` at all. Every other
+  refusal — `invalid_request`, `invalid_target`, `invalid_scope`, `access_denied` — is a 302 to
+  the redirect URI **the API returned**, carrying `error=` and the `state` verbatim. The
+  `redirect_uri` in the request is forwarded to the API and never built into a `Location`: the
+  API's value is the one that matched a registration, which is the whole difference between a
+  redirect and an open redirect.
+- **The POST carries its own CSRF token.** The page puts the readable CSRF cookie in a hidden
+  `csrf` field and the POST refuses, before calling the API at all, unless the field matches
+  the cookie. The handler's server-side call to the API mints the CSRF header itself and would
+  always pass, so the form's token is the only check that means anything here.
+- **`render` owns the body and nothing else.** `OAuth2ConsentView` carries `clientName`,
+  `redirectHost`, `scopes`, `resource`, the `fields` to echo as hidden inputs, and the
+  `csrfToken`, all raw — put every one of them through the exported `escapeHtml`. `clientName`
+  arrives from unauthenticated dynamic registration, and a renderer that drops `fields` or
+  `csrfToken` produces a form the API refuses.
+
+The end-to-end path — lifecycle config, this route, `/mcp`, and connecting from Claude Code
+and Codex — is [docs/guides/mcp-clients.md](../../docs/guides/mcp-clients.md).
+
+## Machine principals (`registerMachineVerifier`)
+
+A machine credential is issued by a service to a non-interactive process, and its subject is
+an account or a tenant, not a person. `AuthContext` cannot hold one — it requires a `users`
+row — and resolving a machine token to its owning user is worse than the type error: it makes
+the machine's request indistinguishable from that user's own session.
+
+So a machine principal never enters `AuthContext`. It lives in its own context key, is read by
+its own helper, and is admitted by its own middleware:
+
+```typescript
+import { machineAuth, requireMachineScope, getMachinePrincipal } from '@spfn/auth/server';
+
+export const ingest = route.post('/v1/ingest')
+    .use([machineAuth, requireMachineScope('events:write')])
+    .handler(async (c) =>
+    {
+        const { subjectType, subjectId } = getMachinePrincipal(c.raw)!;
+        // subjectType: 'account' | 'service' | whatever the verifier named
+    });
+```
+
+`getAuth(c)` on that route returns nothing, because nothing put a user there. That is the
+whole design: a machine request cannot impersonate a user session, not because a check
+forbids it but because no code path leads there.
+
+**Ownership is not authentication.** Who issued a machine token, who owns it, and who may
+revoke or audit it are the registrant's data-level concerns — put the token id in `claims` and
+answer them from your own tables. What the request *acts as* is the token's own subject and
+scopes, and nothing here resolves a machine subject to a user.
+
+### Registering a verifier
+
+A verifier claims one namespace, by a raw `tokenPrefix` (for an opaque secret, the
+`spfn_ops_` shape) or by a `kidPrefix` on the unverified JOSE header of a JWS. The built-in
+ops token's own shape is exported rather than spelled out — match it with `isOpsToken` or
+`OPS_TOKEN_PREFIX` from `@spfn/auth/server`. Register at boot, before the first request:
+
+```typescript
+import { registerMachineVerifier } from '@spfn/auth/server';
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const RUNTIME_JWKS = createRemoteJWKSet(new URL('https://issuer.example.com/.well-known/jwks.json'));
+
+registerMachineVerifier({
+    id: 'runtimeJwsV1',
+    match: { kidPrefix: 'machine:runtime:' },
+    verify: async (token) =>
+    {
+        const { payload } = await jwtVerify(token, RUNTIME_JWKS, { issuer: 'https://issuer.example.com' });
+
+        return {
+            subjectType: 'account',
+            subjectId: String(payload.sub),
+            scopes: String(payload.scope ?? '').split(' ').filter(Boolean),
+            claims: { tokenId: payload.jti },
+            scheme: 'runtimeJwsV1',
+        };
+    },
+});
+```
+
+The request carries it as an ordinary bearer token — no new wire format, and the
+profile-header channel is not involved:
+
+```http
+POST /v1/ingest
+Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Im1hY2hpbmU6cnVudGltZTo...
+```
+
+- **Namespace your kids.** `machine:` is the convention this package documents, and a user
+  session JWT never carries that shape. The prefix is what tells the two apart before either
+  is verified.
+- **Conflicting discriminators are refused at registration** — a duplicate `id`, a duplicate
+  prefix, or a prefix that would shadow an already-registered one (`machine:` swallowing
+  `machine:runtime:`). Two verifiers one token could match would make admission depend on
+  registration order, so that is a boot-time error rather than something the dispatch
+  resolves per request.
+- **A `tokenPrefix` claims every token that starts with it**, and `authenticate` consults the
+  registry before it decodes anything. A prefix a user's JWT could begin with (`ey…`) would
+  therefore refuse every user session — pick a prefix no other credential on your surface
+  shares, as `spfn_ops_` does.
+- **Register at boot, before the first request.** The registry is module state read on every
+  dispatch, so a verifier registered later is simply a verifier the requests before it did
+  not have. There is no unregistration and no reset — the same contract, and the same reason,
+  as [`registerAuthProfile`](#custom-auth-profiles-registerauthprofile).
+- **Registering nothing costs nothing.** With no verifier registered, `authenticate` is two
+  array-length checks away from what it was. The unverified JOSE header peek happens only
+  once a `kidPrefix` verifier exists.
+- **`scheme` is the registry's answer**, not the verifier's: whatever a verifier returns
+  there, the principal carries the `id` that admitted it, so an audit trail cannot be made to
+  name the wrong verifier.
+
+### The case table
+
+| credential ↓ route → | `authenticate` (user) | `machineAuth` | `optionalAuth` |
+|---|---|---|---|
+| user bearer JWT | ✓ user (unchanged) | 401 | ✓ user (unchanged) |
+| machine token, registered namespace, valid | 401 — refused before the token is decoded | ✓ sets `machinePrincipal` | 401 |
+| machine token, registered namespace, verifier rejects | 401 | 401 | 401 |
+| machine-shaped token, unregistered namespace | 401 (the existing invalid-token path) | 401 | continues, no auth |
+| profile header + any Bearer | `PROFILE_REJECTED` (unchanged) | `PROFILE_REJECTED` | `PROFILE_REJECTED` |
+| nothing | 401 (unchanged) | 401 | continues, no auth |
+| valid principal, missing scope | — | 403 | — |
+| valid principal, sufficient scope | — | 200 | — |
+
+Every 401 above is one message. Whether a namespace is registered, whether a presented token
+was ever valid, and whether a verifier rejected it are not inferable from the answer — the
+same non-disclosure rule the [ops-token](#ops-tokens-spfn-ops) table keeps. 403 is reserved
+for scope, where the caller is already authenticated; `requireMachineScope` matches scopes
+exactly and has no wildcard, and it fails closed with a 401 if it runs without `machineAuth`
+before it.
+
+A verifier that throws something other than a refusal — a bug in registrant code — is the
+same generic 401 on the wire, with the real error logged. Never a 500 carrying registrant
+internals, and never a silent pass.
+
+The last row of the unregistered-namespace case is the one asymmetry: a token in a namespace
+nobody registered is not a machine credential as far as this package can tell, so under
+`optionalAuth` it gets what any unusable bearer token has always got. A token in a
+*registered* namespace is refused there, because refusing it is the difference between
+"presented the wrong credential" and "presented none".
+
+The non-disclosure above is therefore an `authenticate` and `machineAuth` property, not an
+`optionalAuth` one: on an `optionalAuth` route a caller can tell a registered namespace from
+an unregistered one, because one is refused and the other is served anonymously. Closing that
+gap would mean refusing every unusable bearer token on those routes — a change to behaviour
+that predates machine principals, and a worse trade than the inference it prevents. Mount
+`machineAuth` where the distinction matters.
+
+### Issuance is yours
+
+This package verifies machine tokens; it does not mint them. Issuance, rotation, and
+revocation belong to whoever owns the subject — keep the tokens short-lived, and prefer a
+signature you can verify offline (`kidPrefix` + JWKS) over a secret you must look up.
+
+`opsTokenAuth` is the built-in instance of exactly this pattern, hand-written for one
+credential before the registry existed: its own context key (`opsToken`), its own scope guard,
+`AuthContext` never set. It keeps its own implementation and is not registered here.
+A route that must admit an ops token *or* a user session uses
+[`opsOrUser`](#one-route-two-credentials-opsoruser), which composes the two existing
+middleware pairs behind one branch on credential shape rather than widening either path.
+
 ## Account Deletion & Recovery
 
 Grace-period deletion with in-window recovery, an admin/GDPR-response entry point for immediate
@@ -1117,7 +2393,7 @@ export default defineServerConfig()
             },
         },
     }))
-    .jobs(authJobRouter)   // registers the daily (04:00 UTC) purge sweep
+    .jobs(authJobRouter)   // the daily (04:00 UTC) purge sweep, and auth.link-mail
     .routes(appRouter)
     .build();
 ```
@@ -1154,15 +2430,68 @@ is fixed at module-import time, which happens before `createAuthLifecycle()` run
 `createAuthLifecycle()` call, and register that instead:
 
 ```typescript
-import { createAuthDeletionJobRouter } from '@spfn/auth/server';
+import { createAuthJobRouter } from '@spfn/auth/server';
 
 // ... after .lifecycle(createAuthLifecycle({ deletion: { purgeCron: '0 3 * * *' } }))
-.jobs(createAuthDeletionJobRouter({ purgeCron: '0 3 * * *' }))
+.jobs(createAuthJobRouter({ purgeCron: '0 3 * * *' }))
 ```
 
-Register **only one** of `authJobRouter` / `createAuthDeletionJobRouter(...)` — both build a job
-named `auth.deletion.purge`, so registering both (e.g. the static export *and* a custom-cron
-router) double-registers the same job name against pg-boss instead of overriding it.
+Register **only one** of `authJobRouter` / `createAuthJobRouter(...)` — both build the same job
+names, so registering both (e.g. the static export *and* a custom-cron router) double-registers
+each name against pg-boss instead of overriding it.
+
+`createAuthDeletionJobRouter` is the former name of `createAuthJobRouter` and still works, with
+the same argument and the same result. It is deprecated because the router has carried more than
+the deletion purge since `auth.link-mail` joined it.
+
+### Link mail delivery
+
+`auth.link-mail` is the second job on the router, and the reason to register the router even in
+an app that never deletes an account.
+
+**What it queues, and why only a row id.** Three mails leave through it: the verified-email
+signup link, the password reset link, and the "you already have an account" notice the signup
+request answers a known address with. The payload is `{ kind, rowId }` — or `{ kind, target,
+targetType }` for the notice — and never the token, the URL or the rendered mail.
+`@spfn/notification` can queue a send of its own, but its payload carries the *rendered* mail,
+which for these three templates would leave the link token in plaintext in `pgboss.job` until
+archive. So the queue carries a reference and the worker mints the credential moments before
+sending it: the plaintext exists in the mail and nowhere else.
+
+**What that buys.** The request writes its row with `token_hash` null and answers. Both branches
+of both endpoints now cost the same database work, so how long a request took no longer says
+whether the address has an account — the mail was the only asymmetry left. A pending row is not
+confirmable: a null hash matches no lookup, and the worker's `issue` refuses a row that was
+superseded, consumed, completed or expired in the meantime, in the same statement that would
+write the hash. A failed send throws so pg-boss retries, and the retry re-mints, which is why a
+token from a failed attempt stops working.
+
+**The three modes** — `SPFN_AUTH_LINK_MAIL_DELIVERY`:
+
+| mode | behaviour |
+|------|-----------|
+| `auto` (default) | queue when pg-boss is initialised, send on the request when it is not — an app with no jobs keeps working exactly as before |
+| `queued` | always queue; an enqueue failure surfaces as a failed request rather than becoming an inline send |
+| `inline` | always send on the request — today's behaviour, and the timing signal that comes with it |
+
+**When the provider refuses on the request path** — `inline`, `auto` with no pg-boss, or the
+fallback below — the failure is logged and the request still answers as if the mail had gone out,
+because an answer that depended on the mail provider would be an account-existence oracle during
+an outage; the user asks again, and only the job path retries.
+
+**The fallback warning.** In `auto`, an app that initialised pg-boss but never registered this
+router has no `auth.link-mail` queue, so the enqueue fails. Losing the mail there would be silent,
+so that request sends inline instead and the log says once per process:
+
+```
+Queue auth.link-mail does not exist, so this link mail was sent on the request path.
+Register the auth job router — .jobs(authJobRouter) — or set SPFN_AUTH_LINK_MAIL_DELIVERY='inline'.
+```
+
+The fix is in the message: register the router, or say `inline` if sending on the request is what
+you want. Only a missing queue falls back — every other enqueue failure, a database outage above
+all, surfaces, because falling back on those would hide the outage behind mail that still gets
+through.
 
 ## FAQ
 
@@ -1176,9 +2505,20 @@ deploy.
 Almost always the callback origin. The CSRF check is a double-submit against a host-only
 cookie set on your **web app** host, so the provider must return to the web app origin, and
 the app must forward `/_auth/*` to the API with a Next.js rewrite. Without that rewrite the
-callback 404s — including in local dev. Details in
+callback 404s — including in local dev. An explicit `SPFN_AUTH_<PROVIDER>_REDIRECT_URI` on the
+wrong origin or path no longer gets that far: it fails at boot with a message naming the
+variable. Details in
 [OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite).
 
+**I forgot my password.**
+Send the address to `requestPasswordReset` and open the link that arrives. Any `active`
+account whose email is verified — or that already has a password, which covers every account
+created before the column was stamped — can be reset that way. See
+[Password reset](#password-reset-verified-email). Completing it signs every other device out,
+so it is also the answer to "someone else knows my password". An account with neither a
+verified address nor a password (OAuth-only, provider said unverified) cannot be reset by
+email; it signs in through its provider.
+
 **Does the server hold my users' private keys?**
 No. The client generates an ES256/RS256 keypair, sends only the public key on register or
 login, and signs each request itself. The server verifies with the stored public key. Keys
@@ -1208,6 +2548,23 @@ authorization.
 The environment, seeded on startup by `createAuthLifecycle()`. Seeded accounts are email
 verified, active, and required to change their password on first login.
 
+**Is `Foo@Example.com` the same account as `foo@example.com`?**
+Yes. Addresses are trimmed and lower-cased on the way in and on the way out, so one person
+who capitalizes differently on different days reaches one account instead of creating a
+second. Nothing else is folded — Gmail's dot and `+` rules are that provider's delivery
+behaviour, not an internet rule, and applying them would merge addresses other providers
+treat as different people.
+
+`createAuthLifecycle()` brings existing rows into the same form on startup. If two accounts
+differ only by capitalization, both are left exactly as they are and their user ids are
+logged as an error: which one is the real account, and what becomes of the other's data, is
+not a question the package can answer for you. Until you resolve it, the mixed-case one
+cannot sign in.
+
+Admin seeding is unaffected either way. It recognizes a configured admin in whatever form
+the address was stored, so an account the backfill has not reached is skipped rather than
+duplicated into a second privileged row holding the configured password.
+
 ## Pitfalls & anti-patterns
 
 - **"relation \"auth.users\" does not exist" — tables come from bundled migrations, not push.**
@@ -1245,8 +2602,10 @@ verified, active, and required to change their password on first login.
   '@spfn/notification/server'`). Wire verification-code / invitation emails through its events.
 - **`authJobRouter` isn't registered for you.** `createAuthLifecycle()`'s `afterInfrastructure`
   hook runs *before* `@spfn/core` initializes pg-boss and registers jobs, so the lifecycle has no
-  opportunity to auto-register the account-deletion purge job. Call `.jobs(authJobRouter)`
-  yourself — see [Account Deletion & Recovery](#account-deletion--recovery).
+  opportunity to auto-register the jobs. Call `.jobs(authJobRouter)` yourself — see
+  [Account Deletion & Recovery](#account-deletion--recovery). An app that initialises pg-boss and
+  skips this keeps sending link mail, but on the request path, with a warning naming the router —
+  see [Link mail delivery](#link-mail-delivery).
 - **`USER_STATUSES` gained `pending_deletion` / `deleted`.** Any code with a `switch(user.status)`
   or an exhaustive status union must handle both — `enumText` is plain `text` with no DB `CHECK`,
   so nothing enforces this at the database layer.