@spfn/auth 0.2.0-beta.87 → 0.2.0-beta.89

package/README.md

@@ -1,9 +1,27 @@
-# @spfn/auth — Authentication, OAuth, and RBAC for SPFN
+# @spfn/auth
 
-Asymmetric client-signed JWT auth (ES256/RS256), OTP verification, OAuth 2.0 (pluggable
-provider registry; Google, GitHub, Kakao, and Naver built in), session cookies for Next.js, and runtime RBAC.
-Routes are exposed under the `/_auth/*` namespace and reached through a type-safe `authApi`
-client. Requires `@spfn/core`; Next.js is an optional peer (`^15 || ^16`).
+> **Two applications' worth of auth, in one package**
+
+Nothing ships until people can sign in. `@spfn/auth` clears that gate twice over — once
+for the people who use your product, and once for the people who operate it.
+
+- **For your users** — registration, password and OTP login, social sign-in, sessions,
+  registered devices, and account deletion with a recovery window.
+- **For your operators** — admin accounts seeded from the environment, roles and
+  permissions enforced on every route, invitations, and role administration your
+  superadmins can change at runtime.
+
+The second half is what usually becomes a second application: an admin dashboard with its
+own auth, its own screens, and its own maintenance, growing for as long as the product
+does. Attach [`@spfn/mcp`](../mcp/README.md) instead and those operations become tools an
+AI agent runs, gated by the same roles — see
+[Can I operate the app without building an admin dashboard?](#can-i-operate-the-app-without-building-an-admin-dashboard).
+
+Underneath: asymmetric client-signed JWTs (ES256/RS256), OTP verification, OAuth 2.0
+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`).
 
 ## Install
 
@@ -31,9 +49,9 @@ import { createClientProofDevHandler } from '@spfn/auth/client-proof';  // SERVE
 > Database entities (`users`, `userPublicKeys`, …) and all services/repositories are exported
 > from `@spfn/auth/server`, **not** from the root `@spfn/auth`.
 
-## Setup (4 wiring points)
+## How do I add auth to an SPFN app?
 
-Auth needs four edits in the consuming app. All four are required for the flow to work end to end.
+Four edits in the consuming app. All four are required for the flow to work end to end.
 
 ### 1. Lifecycle — `server.config.ts`
 
@@ -101,7 +119,7 @@ import { authApi } from '@spfn/auth';
 const session = await authApi.getAuthSession.call({});   // → GET /_auth/session
 ```
 
-## Environment variables
+## Which environment variables do I need?
 
 Set across **two files** by audience. Server-only secrets go in `.env.server`; values the
 Next.js runtime needs (session cookie crypto) go in `.env.local`. Names only below — supply
@@ -131,6 +149,8 @@ real secret values out of band, never commit them.
 | `SPFN_AUTH_GITHUB_SCOPES` / `_REDIRECT_URI` | `.env.server` | — | default scopes `read:user,user:email`; callback `/_auth/oauth/github/callback` |
 | `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 |
+| `SPFN_AUTH_NAVER_NATIVE_CLIENT_IDS` | `.env.server` | — | comma-separated Naver client IDs accepted as native id_token audience. `SPFN_AUTH_NAVER_CLIENT_ID` is also accepted, so this is only needed for a separate app application |
 | `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 |
@@ -155,13 +175,15 @@ routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-si
 
 | `authApi` method | HTTP | Auth | Purpose |
 |------------------|------|------|---------|
-| `checkAccountExists` | POST `/_auth/exists` | public | email/phone existence check |
 | `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 |
 | `login` | POST `/_auth/login` | public | password login + new session key |
 | `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) |
+| `revokeKey` | POST `/_auth/keys/revoke` | yes | sign one device out |
+| `revokeAllKeys` | POST `/_auth/keys/revoke-all` | yes | sign every device out (spares the caller by default) |
 | `changePassword` | PUT `/_auth/password` | yes | change password |
 | `getAuthSession` | GET `/_auth/session` | yes | current session/user |
 | `issueOneTimeToken` | POST | yes | short-lived token (e.g. SSE handshake) |
@@ -173,11 +195,89 @@ routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-si
 | `listRoles` / `createAdminRole` / `updateAdminRole` / `deleteAdminRole` / `updateUserRole` | — | superadmin | admin RBAC management |
 | OAuth routes | — | — | see OAuth section |
 
+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
+login path is timing-equalized for the same reason. Do not reintroduce one without
+revisiting that decision.
+
 Auth uses **asymmetric, client-signed JWTs**: the client generates an ES256/RS256 keypair,
 sends the public key on register/login, signs request JWTs locally, and the server verifies
 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`.
 
+### Registered devices (key management)
+
+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.
+
+```typescript
+const { keys } = await authApi.listKeys.call({ body: {} });
+// → [{ keyId, deviceName?, platform?, algorithm, fingerprintPrefix, createdAtMillis,
+//      lastUsedAtMillis?, expiresAtMillis?, isExpired, isActive, revokedAtMillis? }]
+
+await authApi.listKeys.call({ body: { includeRevoked: true } });   // also what was cut off
+```
+
+Every moment is epoch milliseconds, not an ISO string — one representation across the whole
+surface, so a generated Swift or Kotlin client reads an integer instead of choosing a date
+formatter. This changed in mobile contract 0.5.0; an app still reading `createdAt` moves to
+`createdAtMillis`.
+
+`algorithm` is the `KeyAlgorithm` enum from contract 0.6.0 rather than a bare string — the routes
+have always constrained it to those values, and the contract had been understating the server. The
+declared values are the ones the server accepts and sends **now**: one can be added, and one can be
+withdrawn for a weakness found later, so a generated client should be built to meet a value it does
+not recognise rather than assume the set is closed.
+
+```typescript
+await authApi.revokeKey.call({ body: { keyId } });            // → { keyId, selfRevoked }
+await authApi.revokeAllKeys.call({ body: {} });               // other devices only
+await authApi.revokeAllKeys.call({ body: { includeCurrent: true } });   // everything
+```
+
+> **All three 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.
+
+- **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.
+- **`isExpired` is computed, not stored.** Nothing flips `isActive` when the TTL runs out —
+  `authenticate` refuses the key at request time. A list that showed such a key as simply active
+  would report something the server does not act on.
+- **Revoking your own key is allowed.** It is this device's sign-out, which `logout` already does.
+  `selfRevoked` in the response tells the two cases apart.
+- **`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.
+- **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
+  request with no cache in front of it.
+- **`includeRevoked: true` shows what was already cut off**, with `revokedAt`. The default is only
+  keys that can still sign.
+
+Every path that registers a key (`register`, `login`, `rotateKey`, native OAuth) accepts optional
+`deviceName` (≤64 chars) and `platform` (`ios` / `android` / `web` / `desktop`). Both are display
+only — nothing is authorized by them — and both are absent on keys registered before they existed.
+Rotation carries the replaced key's label over unless the client sends a new one.
+
+All three are in the mobile contract (0.4.1) as `auth.keys.list` / `auth.keys.revoke` /
+`auth.keys.revokeAll`, so a generated mobile client reaches them the same way it reaches key
+rotation.
+
+A `keyId` is **single-use for its lifetime**: it is unique across all users and is never reissued
+once revoked. A client that logs out, rotates, or is revoked must generate a **fresh keypair and
+`keyId`** for its next sign-in — resending the old one is refused with
+`KeyIdAlreadyRegisteredError` (409), on every path that registers a key. Re-registering a key that
+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.
+
 ### Writing protected routes (route DSL)
 
 This is the current SPFN route DSL — `route.<method>().input().use().skip().handler()` registered
@@ -361,22 +461,154 @@ its own Bearer client token by signing with the on-device private key (the same
 server-verifies model as the rest of auth).
 
 Enable per provider by declaring the accepted audiences: `SPFN_AUTH_GOOGLE_NATIVE_CLIENT_IDS` for
-Google (the web `SPFN_AUTH_GOOGLE_CLIENT_ID` is also accepted) and `SPFN_AUTH_APPLE_CLIENT_IDS` for
-Apple. Apple is native-only here — its web OAuth (code-exchange) methods throw.
+Google (the web `SPFN_AUTH_GOOGLE_CLIENT_ID` is also accepted), `SPFN_AUTH_APPLE_CLIENT_IDS` for
+Apple, and `SPFN_AUTH_KAKAO_NATIVE_CLIENT_IDS` for Kakao (the REST API key in
+`SPFN_AUTH_KAKAO_CLIENT_ID` is also accepted). Apple is native-only here — its web OAuth
+(code-exchange) methods throw.
 
 ```typescript
 await authApi.oauthNative.call({
-    params: { provider: 'apple' },                 // or 'google'
+    params: { provider: 'apple' },                 // or 'google', 'kakao'
     body: { idToken, nonce, publicKey, keyId, fingerprint, algorithm: 'ES256', profile: { name } },
 });
 // → { userId, keyId, isNewUser }; client then signs its own ES256 Bearer token with keyId
 ```
 
+Every refusal names itself. The response body carries `error.code` — the server's error class
+name — alongside the usual `__type`, so a client that has no TypeScript error registry can still
+tell the eleven ways this call fails apart:
+
+| `error.code` | HTTP | What the client does |
+| --- | --- | --- |
+| `ValidationError` | 400 | fix the request body |
+| `NativeSignInUnsupportedError` | 400 | hide that provider's native button — server configuration |
+| `NonceKeyBindingError` | 400 | send `nonce === fingerprint` |
+| `InvalidKeyFingerprintError` | 400 | send the SHA-256 of the submitted key |
+| `UnverifiedEmailLinkError` | 400 | send the user to verify that address |
+| `InvalidSocialTokenError` | 401 | obtain a fresh id_token |
+| `AccountDisabledError` | 403 | show the account status |
+| `AccountPendingDeletionError` | 403 | offer restore |
+| `KeyIdAlreadyRegisteredError` | 409 | generate a new keyId and retry |
+| `TooManyRequestsError` | 429 | **the only retry-the-same-request code** |
+| `Error` | 500 | generic failure |
+
 The `nonce` is the **raw** nonce the client used; Apple hashes it (SHA-256) into the token, so send
-the raw value for either provider. `profile.name` captures the name Apple returns only on first
+the raw value for any provider. `profile.name` captures the name Apple returns only on first
 sign-in. Trade-off: skipping code exchange means no Apple refresh token / server-side revoke —
 revoke SPFN access by revoking the registered key instead.
 
+> **The nonce must be the `fingerprint` of the key being registered.** Since contract 0.4.0 the
+> server refuses the call when `nonce !== fingerprint`, or when that fingerprint is not the
+> SHA-256 of the submitted `publicKey`'s DER bytes. So the client does not mint a random nonce —
+> it asks the provider for a token bound to the key it is about to enroll:
+>
+> ```typescript
+> const fingerprint = sha256Hex(derBytesOf(publicKey));   // lowercase hex, 64 chars
+> const nonce = fingerprint;                              // what the provider echoes back
+> // Apple only: put sha256Hex(nonce) in the authorization request — Apple hashes what it receives
+> ```
+>
+> Why: an `id_token` is a bearer credential. It is not bound to the channel it came over, so
+> verifying it alone means whoever holds one valid token can enroll **their own** key on **someone
+> else's** account — by extracting the app key from a real app binary, from a rooted device, or
+> from a leaked log. The web OAuth flow is not exposed this way: there the public key travels
+> inside encrypted `state` whose nonce must match the browser's CSRF cookie. Deriving the nonce
+> from the key gives the native path the same binding, because a stolen token carries the victim's
+> fingerprint and cannot be re-paired with an attacker's key. Re-submitting the victim's own key
+> stays possible and is worthless — the attacker has no matching private key.
+>
+> Naver's trailing-`A` problem (below) is satisfied for free: a SHA-256 hex digest is lowercase.
+
+> **Generate the nonce as lowercase hex, not base64.** Naver drops a trailing `A` from a base64url
+> nonce before putting it in the id_token. A 16-byte base64url value ends in one of `A Q g w` —
+> its last character carries only 2 bits of data plus 4 bits of padding — so a base64 nonce fails
+> verification for roughly one sign-in in four, intermittently and with nothing in the logs
+> pointing at the cause.
+>
+> The trigger is the character `A`, not the encoding as such. **Uppercase hex ends in `A` once in
+> sixteen and breaks the same way**; lowercase hex (`0-9a-f`) has no `A` in its alphabet, so it
+> cannot hit the case at all. Nonce comparison is exact by design (`jwks-verify.ts`) — accepting a
+> truncated value would also accept any other nonce sharing those first characters — so the fix
+> belongs on the client. Confirmed on Naver; not yet measured on the other providers, and
+> lowercase hex is safe for all of them.
+
+#### The optional `accessToken`
+
+`accessToken` is the provider access token from the same sign-in. It is **optional and
+provider-specific** — the server never requires it, and a client that omits it still signs in.
+
+Send it only when a provider's id_token cannot establish the user's **email**, which is identity
+data: `createOrLinkUser` matches an existing account by verified email. Display-side profile
+(name, avatar) is deliberately *not* a reason to send it — that belongs to the app, not to auth.
+
+| Provider | Send `accessToken`? | Why |
+|---|---|---|
+| Google | No | id_token carries `email` + `email_verified` |
+| Apple | No | same, and Apple relay addresses are already the authoritative value |
+| Kakao | **Optional, recommended** | id_token carries `email` but no `email_verified`; without it the address is stored unverified |
+| Naver | **Optional, recommended** | id_token carries no profile claim at all; userinfo returns the address, which carries no verification flag (see below) |
+
+Whatever the provider, the server trusts a lookup made with this token only after the identity it
+returns matches the id_token's `sub`. A mismatch, or a failed lookup, is treated as if the token
+had not been sent.
+
+**Kakao.** Enable OpenID Connect in the Kakao developer console and request the `openid` scope, or
+the SDK returns no `idToken`. One Kakao app issues several keys (native app key, REST API key), and
+the `aud` claim is whichever key obtained the token — so list the native app key and let the REST
+API key be accepted alongside it. The `sub` (회원번호) is per-app, not per-key, so web and app
+sign-ins resolve to the same user.
+
+Kakao's id_token carries `email` but no `email_verified`, so the identity comes back **unverified**
+and the account is created with a null email. To match the web flow's strength, send the
+`accessToken` the SDK returned in the same sign-in as an optional body field: the server then reads
+`is_email_valid` / `is_email_verified` from `/v2/user/me`. That token is client-supplied, so the
+lookup is trusted only when its 회원번호 equals the id_token's `sub`; a mismatch or a failed lookup
+leaves the email unverified and the sign-in still succeeds.
+
+```typescript
+await authApi.oauthNative.call({
+    params: { provider: 'kakao' },
+    body: { idToken, nonce, accessToken, publicKey, keyId, fingerprint, algorithm: 'ES256' },
+});
+```
+
+**Naver.** Naver runs two login surfaces. The web redirect flow uses `/oauth2.0/*`, which is plain
+OAuth2 and issues no id_token; native verification uses the OIDC surface at `/oauth2/*`. The
+`SPFN_AUTH_NAVER_CLIENT_ID` you already have is accepted as the audience — one Naver application
+has a single client ID covering its web and app environments — so
+`SPFN_AUTH_NAVER_NATIVE_CLIENT_IDS` is only needed when the app registers a separate application.
+
+Naver's native SDK cannot produce an id_token: it is pinned to `/oauth2.0/*` and its authorize
+request has no `scope` parameter at all. The app therefore obtains the id_token through a browser
+flow (`ASWebAuthenticationSession` / Custom Tab) against `/oauth2/authorize?scope=openid` with PKCE
+— `token_endpoint_auth_methods_supported` includes `none`, so no client secret is needed. The
+server contract is the same whichever way the token was obtained.
+
+The id_token carries `iss`, `aud`, `azp`, `sub`, `nonce`, `jti`, `iat`, `exp` — no email, no name,
+no picture, even when the application marks email as required. Send `accessToken` to fill it: the
+server reads `/v1/nid/me`, whose `id` is the same pairwise value as the id_token's `sub`, and
+treats a returned address as verified (the same rule the web flow uses). `sub` being pairwise helps
+here — a token from another application resolves to a different `sub` and is rejected by the match.
+
+That verified verdict rests on one fact and it is worth stating plainly, because `createOrLinkUser`
+links a social identity to an existing account on a verified address alone. The `/v1/nid/me`
+response carries **no** verification flag — unlike Kakao, which reports `is_email_valid` and
+`is_email_verified` and is checked against both. What Naver guarantees instead is at change time:
+moving the contact email requires a code sent to the new address, so the returned value is an
+address the user has proven they control. It is **not** a stable identifier: the user can change it,
+one address can be shared by up to six Naver IDs, and it may be absent entirely. `providerUserId` is
+the only key that identifies the account.
+
+```typescript
+await authApi.oauthNative.call({
+    params: { provider: 'naver' },
+    body: { idToken, nonce, accessToken, publicKey, keyId, fingerprint, algorithm: 'ES256' },
+});
+```
+
+Without `accessToken` a Naver sign-in has no email at all, so every user is created fresh and never
+links to an existing account.
+
 ### Custom providers
 
 Implement `OAuthProvider` and register it. `SOCIAL_PROVIDERS` is `['google','apple','github','kakao','naver','superself']`. Implement the optional `verifyNativeIdToken(idToken, { nonce })` to support native id_token sign-in.
@@ -430,7 +662,7 @@ receives the same account/token context and owns its key rotation policy.
 - `auth.login` / `auth.register` events now carry any `SOCIAL_PROVIDERS` value in `provider` —
   update any `switch(provider)` in subscribers.
 
-## Sessions (Next.js)
+## How do I read the session in a Next.js page?
 
 Sessions are HttpOnly cookies encrypted with `SPFN_AUTH_SESSION_SECRET` (JWE), holding the
 client private key + `keyId` (`SessionData`: `{ userId, privateKey, keyId, algorithm }`). The
@@ -464,7 +696,7 @@ export default async function AdminPage()
 Also exported: `getAuthSessionData`, `getUserRole`, `getUserPermissions`, `hasAnyRole`,
 `hasAnyPermission`, the OAuth pending-session helpers, and `createOAuthCallbackHandler`.
 
-## RBAC
+## How do I define roles and permissions?
 
 Built-in roles: `superadmin` (priority 100), `admin` (80), `user` (10). Built-in permissions:
 `auth:self:manage`, `user:read|write|delete|invite`, `rbac:role:manage`, `rbac:permission:manage`.
@@ -484,6 +716,55 @@ Programmatic checks (server): `hasPermission`, `hasAnyPermission`, `hasAllPermis
 `deleteRole`, `setRolePermissions`, `addPermissionToRole`, `removePermissionFromRole`,
 `getAllRoles`, `getRoleByName`, `getRolePermissions`.
 
+## Can I operate the app without building an admin dashboard?
+
+Yes, and that is the point of the operator half of this package. The day after you deploy,
+someone has to refund an order, look up a user, publish a change, retry a failed job. The
+usual answer is to build screens for each of those. `@spfn/auth` already knows who your
+operators are and which of them may do what; [`@spfn/mcp`](../mcp/README.md) turns those
+operations into tools an AI agent can run, so the screens never get built.
+
+The connection is app code, deliberately. `@spfn/mcp` does not read this package's RBAC on
+its own — it asks you for a `validateToken` and a `listTools`, and those are where auth's
+answers go:
+
+```typescript
+import { createMcpRoute } from '@spfn/mcp/server';
+import { hasPermission, getUserRole } from '@spfn/auth/server';
+
+// one required permission per tool — the same permission names your routes check
+const allTools = [
+    { name: 'orders.refund',   permission: 'order:refund',   /* … */ },
+    { name: 'content.publish', permission: 'post:publish',   /* … */ },
+];
+
+export const mcpRouter = createMcpRoute({
+    appUrl: 'https://app.example.com',
+    serverInfo: { name: 'example-app', version: '1.0.0' },
+
+    validateToken: async (token, resource) => verifyAccessToken(token, resource),
+
+    resolveContext: async (auth) => ({
+        userId: auth.userId,
+        role: await getUserRole(auth.userId),
+    }),
+
+    listTools: async (ctx) =>
+    {
+        const allowed = await Promise.all(
+            allTools.map(t => hasPermission(ctx.userId, t.permission)),
+        );
+
+        return allTools.filter((_, i) => allowed[i]);
+    },
+});
+```
+
+Two rules keep this safe. **Expose operations, not tables** — `orders.refund` carries an
+authorization rule; a generic `db.query` carries none. And **check the permission inside
+the handler too**, not only in `listTools`: hiding a tool from the list is discovery
+control, not authorization.
+
 ## Events
 
 `@spfn/auth` emits decoupled events (via `@spfn/core/event`). Subscribe for welcome emails,
@@ -515,7 +796,8 @@ is the recommended error. The hook receives the same `metadata` the app supplied
 `register` / OAuth start / the invitation — never credentials.
 
 ```typescript
-import { configureAuth, RegistrationRejectedError } from '@spfn/auth/server';
+import { configureAuth } from '@spfn/auth/server';
+import { RegistrationRejectedError } from '@spfn/auth/errors';
 
 configureAuth({
     beforeRegister: async ({ channel, provider, email, phone, metadata }) =>
@@ -584,6 +866,44 @@ 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.
 
+### 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
+0.6.0 a mismatch between what that client was generated against and what the server serves
+surfaced as an undecodable body: the app looked broken and nothing said why.
+
+Both ends now say what they are.
+
+| Header | Direction | Sent by |
+|--------|-----------|---------|
+| `x-spfn-client-kind` | request | every client — `web`, `ios` or `android` |
+| `x-spfn-client-version` | request | the client's own release: a store version, or a bundle build |
+| `x-spfn-client-contract-version` | request | `ios` and `android` only |
+| `x-spfn-server-contract-version` | response | the server, on every response including a refusal |
+| `x-spfn-supported-contract-range` | response | the server, likewise |
+
+```typescript
+import { createClientVersionMiddleware } from '@spfn/auth/client-proof';
+
+// Mount before authentication: enrollment and login carry no proof, and they are
+// where a stale client arrives first.
+app.use('*', createClientVersionMiddleware());
+```
+
+- **`web` states no contract version**, because a browser bundle is deployed with the server that
+  serves it and has no second version to reconcile. It is exempt by construction, not by leniency.
+- **An `ios` or `android` client that states no contract version, or one outside the range, is
+  refused** `CONTRACT_UNSUPPORTED` (409) with the usual envelope.
+- **A request naming no kind passes** — a curl, a health probe, a server-to-server call is not a
+  deployed client this rule is about.
+- **None of it enters the proof input.** These are diagnostic; `PROOF_INPUT_FIELDS` is unchanged.
+- **The server states facts and stops there.** Comparing the announced range against its own version
+  and deciding a user should see an update prompt is the client's judgment, made in the client. The
+  server has no way to make an app update and does not pretend to.
+
+Response header names are deliberately distinct from the request ones: a proxy that echoes a request
+header into the response would otherwise make the client's own version look like the server's.
+
 ### Usage — dev surface (mobile integration target)
 
 The fastest path: run the packaged dev handler, which already serves the three contract
@@ -746,6 +1066,50 @@ Register **only one** of `authJobRouter` / `createAuthDeletionJobRouter(...)`
 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.
 
+## FAQ
+
+**How do I add one social provider?**
+Set its two environment variables. Google, GitHub, Kakao and Naver each turn on when their
+client ID and secret are both present — there is no separate registration step. Then
+register the callback URL in that provider's console, and read the next answer before you
+deploy.
+
+**Social login worked locally and broke after deploying. Why?**
+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
+[OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite).
+
+**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
+expire after 90 days; `rotateKey` renews one.
+
+**Does signing in on a new device sign the old one out?**
+No, and that is on purpose — keys are per-device and accumulate. `listKeys` shows the
+account owner what accumulated, `revokeKey` cuts one off, `revokeAllKeys` cuts off
+everything but the caller.
+
+**How long does a session last?**
+`SPFN_AUTH_SESSION_TTL`, seven days by default. It accepts `7d`, `12h`, `45m`.
+
+**Is account deletion immediate?**
+No. A request moves the account to `pending_deletion`, revokes every session key, and
+schedules the purge for 30 days later by default. The user can cancel with their
+credentials during that window. Two things need your attention: the purge sweep is a job
+you register explicitly (`.jobs(authJobRouter)`), and a purged account's email becomes
+reusable immediately. See [Account Deletion & Recovery](#account-deletion--recovery).
+
+**Can an admin delete a user's account?**
+Yes, through `requestAccountDeletionService(userId, { requestedBy: 'admin', immediate })`
+and `purgeUserService(userId)`. The package exports the services; you own the route and its
+authorization.
+
+**Where do my admin accounts come from?**
+The environment, seeded on startup by `createAuthLifecycle()`. Seeded accounts are email
+verified, active, and required to change their password on first login.
+
 ## Pitfalls & anti-patterns
 
 - **"relation \"auth.users\" does not exist" — tables come from bundled migrations, not push.**
@@ -831,7 +1195,9 @@ const session = await authApi.getAuthSession.call({});
 
 ## Related
 
-- `@spfn/core` — route DSL (`route`, `defineRouter`), `createApi`, env (`@spfn/core/env`),
-  errors (`ErrorRegistry`), db (`Transactional`), events, jobs.
+- [`@spfn/core`](../core/README.md) — route DSL (`route`, `defineRouter`), `createApi`, env
+  (`@spfn/core/env`), errors (`ErrorRegistry`), db (`Transactional`), events, jobs.
+- [`@spfn/mcp`](../mcp/README.md) — exposes operations as MCP tools, so the operator half of
+  this package needs no admin dashboard.
 - `@spfn/notification` — email/SMS/push (verification codes, invitation emails).
 - Full guide: `docs/guides/authentication.md`.