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

package/README.md

@@ -136,6 +136,7 @@ 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` |
@@ -184,6 +185,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 +293,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.
@@ -337,6 +437,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
@@ -779,6 +883,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 +1103,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 +1345,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 +1481,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

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. */

package/dist/client-proof.js

@@ -1078,6 +1078,60 @@ var AUTH_SURFACE_OPERATIONS = [
     responseType: "RevokeAllKeysResponse",
     summary: "Revokes every key the caller has, sparing the calling device unless asked otherwise.",
     since: "0.4.1"
+  },
+  {
+    id: "auth.device.start",
+    method: "POST",
+    path: "/_auth/device/start",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "StartDeviceAuthRequest",
+    responseType: "StartDeviceAuthResponse",
+    summary: "Parks a new device's public key and returns the codes it shows and polls with.",
+    since: "0.10.0"
+  },
+  {
+    id: "auth.device.poll",
+    method: "POST",
+    path: "/_auth/device/poll",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "PollDeviceAuthRequest",
+    responseType: "PollDeviceAuthResponse",
+    summary: "Asks whether the request has been answered; the approved answer is the login it produced.",
+    since: "0.10.0"
+  },
+  {
+    id: "auth.device.info",
+    method: "POST",
+    path: "/_auth/device/info",
+    authProfile: "clientProofV1",
+    requiresSession: false,
+    requestType: "DeviceAuthInfoRequest",
+    responseType: "DeviceAuthInfoResponse",
+    summary: "Describes the device waiting on a user code, so the approver can recognise it before deciding.",
+    since: "0.10.0"
+  },
+  {
+    id: "auth.device.approve",
+    method: "POST",
+    path: "/_auth/device/approve",
+    authProfile: "clientProofV1",
+    requiresSession: false,
+    requestType: "ApproveDeviceAuthRequest",
+    responseType: "DeviceAuthInfoResponse",
+    summary: "Lets the waiting device in, answering with the device it just let in.",
+    since: "0.10.0"
+  },
+  {
+    id: "auth.device.deny",
+    method: "POST",
+    path: "/_auth/device/deny",
+    authProfile: "clientProofV1",
+    requiresSession: false,
+    requestType: "DenyDeviceAuthRequest",
+    summary: "Refuses the waiting device. Answers 204 with no body, so it names no response type.",
+    since: "0.10.0"
   }
 ];
 var ContractTypeError = class extends Error {
@@ -1325,6 +1379,7 @@ import {
 
 // src/server/types.ts
 var KEY_ALGORITHM = ["ES256", "RS256"];
+var KEY_PLATFORM = ["ios", "android", "web", "desktop"];
 
 // src/server/client-proof/wire-headers.ts
 var CLIENT_IDENTITY_HEADERS = {
@@ -1342,9 +1397,9 @@ function isAppKind(kind) {
 }
 
 // src/server/client-proof/contract-bundle.ts
-var CONTRACT_VERSION = "0.9.0";
+var CONTRACT_VERSION = "0.10.0";
 var CONTRACT_MAJOR = 0;
-var CONTRACT_SUPPORTED_RANGE = ">=0.9.0 <0.10.0";
+var CONTRACT_SUPPORTED_RANGE = ">=0.10.0 <0.11.0";
 function required(name, type) {
   return { name, type, optional: false };
 }
@@ -1515,7 +1570,7 @@ var CONTRACT_TYPES = [
     fields: [
       required("keyId", "string"),
       optional("deviceName", "string"),
-      optional("platform", "string"),
+      optional("platform", "KeyPlatform"),
       required("algorithm", "KeyAlgorithm"),
       required("fingerprintPrefix", "string"),
       required("createdAtMillis", "integer"),
@@ -1557,10 +1612,94 @@ var CONTRACT_TYPES = [
       required("revokedCount", "integer"),
       required("currentKeyRevoked", "boolean")
     ]
+  },
+  {
+    name: "StartDeviceAuthRequest",
+    fields: [
+      required("publicKey", "string"),
+      required("keyId", "string"),
+      required("fingerprint", "string"),
+      optional("algorithm", "KeyAlgorithm"),
+      optional("deviceName", "string"),
+      optional("platform", "KeyPlatform")
+    ]
+  },
+  {
+    name: "StartDeviceAuthResponse",
+    fields: [
+      required("deviceCode", "string"),
+      required("userCode", "string"),
+      required("expiresAtMillis", "integer"),
+      required("intervalMillis", "integer")
+    ]
+  },
+  {
+    name: "PollDeviceAuthRequest",
+    fields: [
+      required("deviceCode", "string")
+    ]
+  },
+  /**
+   * The poll union, flattened into the one shape this grammar can carry.
+   *
+   * `status` is the discriminant and the only required field; everything else
+   * belongs to one branch and is therefore optional. `intervalMillis` is the
+   * pending branch, and the five after it are the approved branch — the same
+   * fields `LoginResponse` carries, because an approved poll is the login the
+   * approval produced. `deviceAuthorization.pollStatusRule` states the pairing
+   * the grammar cannot.
+   */
+  {
+    name: "PollDeviceAuthResponse",
+    fields: [
+      required("status", "DeviceAuthPollStatus"),
+      optional("intervalMillis", "integer"),
+      optional("userId", "string"),
+      optional("publicId", "string"),
+      optional("email", "string"),
+      optional("phone", "string"),
+      optional("passwordChangeRequired", "boolean")
+    ]
+  },
+  /**
+   * Info, approve and deny each declare their own request type although all
+   * three carry nothing but `userCode`. An operation's request shape is its
+   * own: a field added to one of them later must not appear on the other two
+   * by accident, which is what a shared type would do.
+   */
+  {
+    name: "DeviceAuthInfoRequest",
+    fields: [
+      required("userCode", "string")
+    ]
+  },
+  {
+    name: "DeviceAuthInfoResponse",
+    fields: [
+      optional("deviceName", "string"),
+      optional("platform", "KeyPlatform"),
+      required("fingerprintPrefix", "string"),
+      required("requestedAtMillis", "integer"),
+      required("expiresAtMillis", "integer")
+    ]
+  },
+  {
+    name: "ApproveDeviceAuthRequest",
+    fields: [
+      required("userCode", "string")
+    ]
+  },
+  {
+    name: "DenyDeviceAuthRequest",
+    fields: [
+      required("userCode", "string")
+    ]
   }
 ];
 var CONTRACT_ENUMS = [
-  { name: "KeyAlgorithm", values: [...KEY_ALGORITHM] }
+  { name: "KeyAlgorithm", values: [...KEY_ALGORITHM] },
+  { name: "KeyPlatform", values: [...KEY_PLATFORM] },
+  { name: "DeviceAuthPollStatus", values: ["pending", "approved"] }
 ];
 var BUNDLE_FILENAME = "spfn-mobile-contract.json";
 var BUNDLE_REPO_PATH = `contracts/mobile/${BUNDLE_FILENAME}`;