@spfn/auth 0.3.0-beta.7 → 0.3.0-beta.9

package/README.md

@@ -136,17 +136,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 |
@@ -184,6 +186,11 @@ routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-si
 | `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 |
 | `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 |
 | `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) |
@@ -287,6 +294,100 @@ override it there to change the copy.
 `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.
 
+### 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)
 
 Keys are per-device, so a login never revokes the previous key and they accumulate on purpose.
@@ -326,6 +427,11 @@ await authApi.revokeAllKeys.call({ body: { includeCurrent: true } });   // every
 > 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.
@@ -337,6 +443,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
@@ -529,9 +639,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)
 
@@ -779,6 +905,134 @@ export default async function AdminPage()
 Also exported: `getAuthSessionData`, `getUserRole`, `getUserPermissions`, `hasAnyRole`,
 `hasAnyPermission`, the OAuth pending-session helpers, and `createOAuthCallbackHandler`.
 
+## 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:
@@ -871,6 +1125,12 @@ authRegisterEvent.subscribe(async ({ userId, email, provider, metadata }) =>
 });
 ```
 
+`authLoginEvent`'s `provider` is `'email'`, `'phone'`, a social provider, or `'device'` — the
+last one being 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.
+`authRegisterEvent` does not accept `'device'`: a device-code request can only ever be
+approved by an account that already exists, so it is never a signup.
+
 Payload types: `AuthLoginPayload`, `AuthRegisterPayload`, `InvitationCreatedPayload`,
 `InvitationAcceptedPayload`, `AuthDeletionRequestedPayload`, `AuthDeletionCancelledPayload`,
 `AuthDeletionCompletedPayload`, `OAuthUnlinkedPayload` (`auth.oauth.unlinked` — provider-side
@@ -1107,6 +1367,7 @@ Every operation in the exported bundle carries `since` — the contract version
 | `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.
@@ -1242,6 +1503,145 @@ x-acme-service-token: <the app's own credential>
   The field stays informational: downstream permission and tenant code takes one principal shape and
   never branches on how it was produced.
 
+## 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. 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.
+
 ## Account Deletion & Recovery
 
 Grace-period deletion with in-window recovery, an admin/GDPR-response entry point for immediate
@@ -1355,7 +1755,9 @@ 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).
 
 **Does the server hold my users' private keys?**

package/dist/client-proof.d.ts

@@ -398,7 +398,7 @@ declare function getClientProofReplayStore(): ClientProofReplayStore;
  */
 
 interface ContractOperation {
-    id: 'auth.clientProof.handshake' | 'echo.send' | 'items.list' | 'auth.enroll.register' | 'auth.enroll.login' | 'auth.enroll.oauthNative' | 'auth.keys.rotate' | 'auth.keys.list' | 'auth.keys.revoke' | 'auth.keys.revokeAll' | typeof CORE_TIME_OPERATION_ID;
+    id: 'auth.clientProof.handshake' | 'echo.send' | 'items.list' | 'auth.enroll.register' | 'auth.enroll.login' | 'auth.enroll.oauthNative' | 'auth.keys.rotate' | 'auth.keys.list' | 'auth.keys.revoke' | 'auth.keys.revokeAll' | 'auth.device.start' | 'auth.device.poll' | 'auth.device.info' | 'auth.device.approve' | 'auth.device.deny' | typeof CORE_TIME_OPERATION_ID;
     method: 'GET' | 'POST';
     path: string;
     /**
@@ -411,7 +411,11 @@ interface ContractOperation {
     requiresSession: boolean;
     /** Absent only when the operation has no request body. */
     requestType?: string;
-    responseType: string;
+    /**
+     * Absent only when the operation answers with no body — a 204, which has
+     * nothing for a consumer to decode and therefore names no type.
+     */
+    responseType?: string;
     summary: string;
     /**
      * The contract version this operation first appeared in. Required, so an
@@ -460,16 +464,23 @@ declare const IMPORTED_CORE_TIME_CONTRACT: {
 declare const CORE_PREREQUISITE_OPERATIONS: readonly ContractOperation[];
 declare const CONTRACT_OPERATIONS: readonly ContractOperation[];
 /**
- * The `/_auth` surface exported into the mobile contract: enrollment, login
- * and key rotation. These are ordinary SPFN REST routes, not canonical-JSON
- * operations — the dev handler never serves them, and their wire rules are
- * the `restOperations` section of the bundle, not `canonicalJson`.
- *
- * The three `authProfile: 'none'` operations are the unproven class: they are
- * accepted with neither proof headers nor a session header, because they are
- * how a client obtains a key in the first place. `auth.keys.rotate` requires
- * an authenticated caller (a clientProofV1 proof on this surface); an
- * unproven call to it is refused like any failed admission.
+ * The `/_auth` surface exported into the mobile contract: enrollment, login,
+ * key rotation and device-code login. These are ordinary SPFN REST routes, not
+ * canonical-JSON operations — the dev handler never serves them, and their wire
+ * rules are the `restOperations` section of the bundle, not `canonicalJson`.
+ *
+ * The `authProfile: 'none'` operations are the unproven class: they are accepted
+ * with neither proof headers nor a session header, because they are how a client
+ * obtains a key in the first place. `auth.keys.rotate` requires an authenticated
+ * caller (a clientProofV1 proof on this surface); an unproven call to it is
+ * refused like any failed admission.
+ *
+ * Device-code login is in both classes at once, because two devices run it. The
+ * device being let in calls `start` and `poll` unproven — it has no registered
+ * key to sign with, and getting one is the point of the flow. The approver calls
+ * `info`, `approve` and `deny` proven, from a device that is already signed in,
+ * which is what lets the server read the approving account from the caller
+ * rather than from the request body.
  */
 declare const AUTH_SURFACE_OPERATIONS: readonly ContractOperation[];
 /** The body is canonical JSON but not the declared request type. */