@spfn/auth 0.3.0-beta.23 → 0.3.0-beta.25

package/README.md

@@ -173,6 +173,12 @@ real secret values out of band, never commit them.
 | `SPFN_AUTH_PASSKEY_CHALLENGE_TTL_SECONDS` / `_RECENT_AUTH_MINUTES` | `.env.server` | — | defaults `300` / `10` — see [Passkeys](#passkeys-webauthn) |
 | `SPFN_AUTH_MFA_ISSUER` | `.env.server` | — | name the authenticator app files the account under; defaults to the passkey relying-party name, then the app URL host — see [Second factor](#second-factor-mfa) |
 | `SPFN_AUTH_MFA_STEP_UP_MINUTES` | `.env.server` | — | default `10`; how recently an enrolled account's device must have proved its second factor for a sensitive change — see [Second factor](#second-factor-mfa) |
+| `SPFN_AUTH_MFA_CHALLENGE_TTL_MINUTES` | `.env.server` | — | default `10`; how long a new-device step-up challenge stays spendable — see [Step-up on a new device](#step-up-on-a-new-device) |
+| `SPFN_AUTH_MFA_CONFIRM_PATH` | `.env.server` | — | default `/auth/mfa`; app page the OAuth callback handler sends a browser to when a social sign-in needs a second factor |
+| `SPFN_AUTH_BOUND_KEY_TTL_HOURS` | `.env.server` | — | default `24`; how long a passkey-bound session key lives — see [Session binding](#session-binding) |
+| `SPFN_AUTH_BOUND_KEY_RENEW_GRACE_HOURS` | `.env.server` | — | default `168`; how long past expiry a bound key may still be renewed. Past it, sign in again |
+| `SPFN_AUTH_CONCURRENT_USE_WINDOW_MS` | `.env.server` | — | default `300000`; how close two sightings from two addresses must be to raise `concurrentUseAtMillis` |
+| `SPFN_AUTH_SESSION_RENEW_PATH` | `.env.local` | — | default `/auth/renew`; the page `RequireAuth` sends a bound session whose key ran out |
 | `NEXT_PUBLIC_SPFN_API_URL` / `NEXT_PUBLIC_SPFN_APP_URL` | `.env.local` | — | browser-facing URLs for OAuth redirects |
 
 Read validated values via `import { env } from '@spfn/auth/config'` (a proxy validated at
@@ -224,11 +230,18 @@ routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-si
 | `mfaStatus` | GET `/_auth/mfa/status` | yes | `{ enrolled, methods, recoveryCodesRemaining }`; no secret |
 | `mfaStepUp` | POST `/_auth/mfa/step-up` | yes | re-prove the second factor on this device |
 | `mfaStepUpOptions` | POST `/_auth/mfa/step-up/options` | yes | options for a step-up by passkey |
+| `mfaVerify` | POST `/_auth/mfa/verify` | public | finish a sign-in that answered `202 { mfaRequired: true }` — see [Step-up on a new device](#step-up-on-a-new-device) |
+| `mfaVerifyOptions` | POST `/_auth/mfa/verify/options` | public | options for finishing that sign-in with a passkey |
 | `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) |
+| `setSessionBinding` | POST `/_auth/session/binding` | yes | turn session binding on or off — see [Session binding](#session-binding) |
+| `getSessionBinding` | GET `/_auth/session/binding` | yes | whether it is on, and when this session's key expires |
+| `sessionBindingDisableOptions` | POST `/_auth/session/binding/disable/options` | yes | the challenge that proves it is you before turning it off |
+| `sessionRenewOptions` | POST `/_auth/session/renew/options` | public | begin renewing a bound session key |
+| `sessionRenewVerify` | POST `/_auth/session/renew/verify` | public | verify the assertion; answers exactly as `login` |
 | `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) |
@@ -249,7 +262,48 @@ 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`.
+Keys expire after 90 days — rotate with `rotateKey`, which starts the ninety days again. A key
+bound to a passkey is the one exception: it lives for hours and a rotation carries its expiry over
+rather than resetting it, because only `session/renew` may move that window — see
+[Session binding](#session-binding).
+
+### Migration — narrow a sign-in on `mfaRequired` before reading `userId`
+
+**Breaking in `@spfn/auth` 0.3.0-beta.25 / mobile contract 0.13.0.** A sign-in no
+longer always answers with a session. An account that enrolled a second factor and
+signs in from a device the account has never seen gets `202` and a challenge
+instead, and the key it registered stays inactive until that challenge is spent —
+see [Second factor](#second-factor-mfa).
+
+So `LoginResult` carries one new required field, `mfaRequired`, and every field it
+carried before is now optional. It is still **one** type rather than a union:
+`authApi.login` infers its result from that declaration, and a union would make
+every `result.userId` in your app a compile error with no way to narrow it that
+was available in 0.12.x. Narrow on the discriminant:
+
+```typescript
+const result = await authApi.login.call({ body: { email, password } });
+
+if (result.mfaRequired)
+{
+    // No session yet. result.challenge is { secret, expiresAtMillis }.
+    router.push('/auth/mfa');
+
+    return;
+}
+
+console.log(result.userId); // string, from here on
+```
+
+The same reshape applies to `authApi.oauthNative` (`OauthNativeResult`), to
+`completePasswordReset`, and to the approved branch of `pollDeviceAuth` — which
+carries `mfaRequired: false` and can never carry anything else, since a
+device-code approval is itself a second factor.
+
+Nothing changes for an account with no second factor: every one of those calls
+answers `200` with `mfaRequired: false` and exactly the fields it always did.
+In the Next.js proxy nothing changes for your code at all — the interceptors
+handle the 202 and the pending cookie themselves.
 
 ### Verified-email signup
 
@@ -529,11 +583,15 @@ Keys are per-device, so a login never revokes the previous key and they accumula
 `listKeys` / `revokeKey` / `revokeAllKeys` are what let the account owner see what accumulated and
 cut off anything they no longer recognise.
 
+A key still waiting on a [second factor](#step-up-on-a-new-device) is in neither list. It
+cannot sign for anything, so it is not a device; and nobody signed it out, so it is not a
+revoked one either. A global revocation deletes it outright rather than revoking it.
+
 ```typescript
 const { keys } = await authApi.listKeys.call({ body: {} });
 // → [{ keyId, deviceName?, platform?, algorithm, fingerprintPrefix, createdAtMillis,
 //      lastUsedAtMillis?, expiresAtMillis?, isExpired, isActive, revokedAtMillis?,
-//      registeredIp?, registeredUserAgent? }]
+//      registeredIp?, registeredUserAgent?, binding?, concurrentUseAtMillis? }]
 
 await authApi.listKeys.call({ body: { includeRevoked: true } });   // also what was cut off
 ```
@@ -602,6 +660,14 @@ Rotation carries the replaced key's label over unless the client sends a new one
   registered before the columns existed; the literal string `unknown` is never stored. They are
   unauthenticated display material, spoofable on any request that does not come through a verified
   proxy, so render them and decide nothing by them. Mobile contract 0.11.0.
+- **`binding` says the key is tied to a passkey**, and is absent on every key that is not — which
+  is every key on an account that did not turn [session binding](#session-binding) on. A bound key
+  expires in hours and only a passkey assertion renews it.
+- **`concurrentUseAtMillis` is when this key was last seen from two addresses at once**, inside
+  `SPFN_AUTH_CONCURRENT_USE_WINDOW_MS`. Absent when that has never been observed, which is the
+  ordinary state. A signal to show, never a refusal — addresses change legitimately — and the
+  addresses themselves are never returned. Meaningful only where proxy-guard is configured. Mobile
+  contract 0.12.0.
 
 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
@@ -1082,6 +1148,99 @@ Two sign-ins deliberately produce a session with no verification of its own: a
 `POST /_auth/mfa/step-up` is for. Marking a passkey as a second factor is likewise not proving
 it, so the device that marks one steps up before it may change the second factor again.
 
+#### Step-up on a new device
+
+The moment the feature exists for. An **enrolled** account signing in from a device it has
+never seen does not get a session — it gets a challenge, and the device key it registered
+stays inactive until that challenge is spent. A password phished from somebody is no longer
+enough to hold their account.
+
+```
+POST /_auth/login            → 202 { mfaRequired: true, challenge: { secret, expiresAtMillis } }
+                               the key is registered, is_active = false, and nothing else moved
+POST /_auth/mfa/verify       → 200 the LoginResult the sign-in would have given
+  { challenge, code }          plus keyId and challengeHash, for the proxy
+  { challenge, recoveryCode }
+  { challenge, response }      options from POST /_auth/mfa/verify/options
+```
+
+Four channels stop: **password**, **oauth** (web), **oauth-native** and **password-reset** —
+the four where one stolen credential would otherwise be enough. A device-code approval and a
+passkey sign-in do not, because each already carried a second proof; nor does a key rotation,
+a renewal, or any path that is creating the account. A brand-new social account is not stepped
+up either, and needs no exemption to say so: an account that was written a moment ago has
+nothing enrolled.
+
+**A 202 moves nothing.** No login event, no new-device event, no `lastLoginAt`. All three are
+held on the challenge row and fire together at `verify`, with the original channel — so the
+owner's record of their own sign-ins stays a record of sign-ins that happened.
+
+**Until it is verified, the key does not exist** to anything the owner can see: `authenticate`
+refuses it, `optionalAuth` reads the caller as anonymous, and `listKeys` omits it in both
+modes. Every global revocation — `revoke-all`, a password change, the sign-out-everywhere
+link, a password reset — **deletes** it and kills its challenge in the same statement, so the
+owner who reacts to an unexpected prompt by signing out everywhere really has.
+
+The challenge is 32 random bytes. Only its hash is stored, so a guess reaches no row and
+cannot touch anybody's attempt counter; it is single use, it lives
+`SPFN_AUTH_MFA_CHALLENGE_TTL_MINUTES` (default 10), it dies with the account's key generation,
+and five wrong proofs end it and delete the pending key. Retrying the same registration while
+a challenge is live resumes it — same row, same expiry, same spent attempts — rather than
+answering 409.
+
+**Recovery codes work here**, which is the point of having them: somebody whose authenticator
+is on the phone they just lost signs in on the replacement with a written-down code.
+
+##### Migration
+
+`LoginResult` gained a required `mfaRequired` and every other field became optional. Narrow on
+it before reading `userId` — see [the migration note](#migration--narrow-a-sign-in-on-mfarequired-before-reading-userid).
+
+##### The web OAuth path
+
+The backend callback redirects with **`?mfaChallenge=`** instead of `userId` and `keyId`. The
+value is not a bearer credential for anything but this one `verify`, it is single use, and
+`requestLogger` records pathnames only — so unlike the sign-out-everywhere link it is not a
+capability riding a URL.
+
+Both consumers of that redirect are served:
+
+- `createOAuthCallbackHandler()` redirects the browser to **`SPFN_AUTH_MFA_CONFIRM_PATH`**
+  (default `/auth/mfa`, or the `mfaPath` option) with `?challenge=` and `?returnUrl=`.
+- An app on the callback-page flow posts `{ mfaChallenge }` to `POST /_auth/oauth/finalize`,
+  which answers **202** with the challenge echoed back instead of finalizing a session.
+
+##### In the Next.js proxy
+
+Nothing to write. `mfaVerifyInterceptor` — registered for you in `authInterceptors` — seals a
+`spfn_mfa_pending` cookie on any 202 (the browser's private key, the key id, and the hash of
+the challenge, for ten minutes) and turns it into the session on a verified `verify`. Its own
+name and audience, so a social login started in another tab does not overwrite it.
+
+A session is sealed **only** when the verified response names the same challenge and the same
+key the cookie holds. Otherwise the proxy answers **401 `SESSION_PENDING_MISMATCH`** without
+sealing anything, and **401 `SESSION_PENDING_EXPIRED`** when the cookie is gone. The key is
+active at the backend in both cases — what failed is this browser's claim to be the one that
+asked — so the remedy is to sign in again.
+
+##### From a browser, with the client helpers
+
+```typescript
+import { completeMfaWithCode, completeMfaWithPasskey } from '@spfn/auth/client';
+
+const result = await authApi.login.call({ body: { email, password } });
+
+if (result.mfaRequired)
+{
+    // Keep result.challenge.secret and send the person to your confirm screen.
+    await completeMfaWithCode(authApi, result.challenge.secret, code);
+    // The session cookie is sealed by the time this resolves.
+}
+```
+
+`completeMfaWithRecoveryCode` takes a written-down code, and `completeMfaWithPasskey` runs the
+ceremony and answers the same discriminated union the other passkey helpers do.
+
 #### Telling people it exists
 
 `authLoginEvent` and `authDeviceRegisteredEvent` carry **`mfaEnrolled: boolean`**, computed as
@@ -1097,22 +1256,172 @@ enrolment at a first login or when a new device appears. Nothing is ever blocked
 | `StepUpRequiredError` | 403 | `STEP_UP_REQUIRED` | an enrolled account's device is outside the window |
 | `MfaAlreadyEnrolledError` | 409 | — | `totp/enroll` on a confirmed enrolment |
 | `MfaConfigError` | 500 | — | `SPFN_AUTH_TOKEN_ENCRYPTION_KEYS` unset, or a stored secret naming a key id no longer in it |
+| `SessionPendingMismatchError` | 401 | `SESSION_PENDING_MISMATCH` | minted by the proxy: a verified step-up whose challenge or key is not the one this browser's pending cookie holds |
+| `SessionPendingExpiredError` | 401 | `SESSION_PENDING_EXPIRED` | minted by the proxy: a verified step-up with no pending cookie left to seal a session from |
 
-None of these is a mobile-contract error: the enrolment routes are not contract operations.
+`MfaVerificationFailedError` is the one contract error here, as the `auth.mfa.*` family of the
+mobile contract (0.13.0). The enrolment routes are not contract operations, so the rest are
+not on that surface.
 
 #### The case table
 
-Asserted row by row in `src/__tests__/integration/mfa-enrolment.test.ts` (enrolment) and
-`mfa-step-up.test.ts` (the window); each `it` is named for its row.
+Asserted row by row in `src/__tests__/integration/mfa-enrolment.test.ts` (enrolment),
+`mfa-step-up.test.ts` (the window), `mfa-step-up-registration.test.ts` (which channels stop a
+new device), `mfa-verify.test.ts` (verify × input) and `src/__tests__/unit/mfa-proxy.test.ts`
+(the Next.js proxy); each `it` is named for its row.
 `mfa-unenrolled-regression.test.ts` pins the status and the body shape an **unenrolled**
 account gets from `login`, `changePassword`, `keys/revoke-all` and `passkeys/revoke`.
 
 #### The sweep
 
-`auth.mfa.sweep` runs daily at 07:00 and deletes enrolments still unconfirmed after 24 hours.
-It is carried by `authJobRouter` beside the other sweeps; pass `mfaSweepCron` to
+`auth.mfa.sweep` runs daily at 07:00 and deletes enrolments still unconfirmed after 24 hours,
+plus step-up challenges that have expired or been spent and the inactive keys they were
+holding. It is carried by `authJobRouter` beside the other sweeps; pass `mfaSweepCron` to
 `createAuthJobRouter()` to move it. A confirmed enrolment is never touched.
 
+### Session binding
+
+A web session's signing key is sealed **inside** the session cookie. That is what makes the
+cookie a credential rather than a pointer to one — and it means a copy of the cookie *is* that
+device. A browser profile copied off a laptop, a value pasted out of DevTools, a jar read by
+malware: the copy signs exactly as the original does, registers no new key, raises no new-device
+notice, and keeps working until the key is revoked or the session runs out. HttpOnly and
+`SameSite=Lax` stop page script and cross-site posts; they do nothing about a copy made on the
+machine.
+
+Session binding is the opt-in that closes that window. An account that has a platform passkey may
+turn it on; from then on a web session runs on a key that expires in **hours** instead of ninety
+days, and only a fresh WebAuthn assertion can put a new one in the cookie. The copy cannot produce
+the assertion, so it stops working at the first renewal.
+
+```typescript
+// Turn it on. Needs a live passkey and a recently-proved session.
+await authApi.setSessionBinding.call({ body: { mode: 'passkey' } });
+// → { mode: 'passkey', keyExpiresAtMillis }
+
+await authApi.getSessionBinding.call();          // → { mode, keyExpiresAtMillis? }
+
+// Turn it off. A fresh credential is required — see below.
+import { disableSessionBinding } from '@spfn/auth/client';
+await disableSessionBinding(api);                             // runs the passkey ceremony
+await disableSessionBinding(api, { currentPassword: '…' });   // or the account password
+```
+
+> **It needs a deployment where the backend can recognise the Next.js proxy.** A key is bound only
+> on a request `proxy-guard` tagged `clientType: 'web'`, because that is the only signal the
+> backend has that a request came through the proxy that holds the session cookie — and nothing
+> else can run the renewal. Without proxy-guard configured, `setSessionBinding` answers 400
+> `SessionBindingUnavailableError` rather than turning on a switch that would protect nothing.
+
+**What a copied cookie can and cannot do.** Before the bound key expires, a copy is
+indistinguishable from the original by anything the server sees — that is the honest statement, and
+the user-agent family check below is the only thing standing in front of it. After the key
+expires, the copy has nothing: renewal needs the passkey, and the account's own browser is the one
+holding it. Turning binding *off* is the privileged direction here, the reverse of the usual
+posture: `assertRecentAuthentication` is satisfied by the age of the device key a request is signed
+with, and a cookie copied in the ten minutes after a sign-in carries exactly that — so leaving
+`'passkey'` mode asks for a passkey assertion or the account password, never key age alone.
+
+**The renewal page.** Once the key has run out, the backend refuses with `KeyExpiredError`, the
+proxy turns that into 401 `SessionRenewalRequiredError` and keeps the cookies: the session is
+waiting on one prompt, not finished. A client component calls `renewSession(api)`, which runs the
+ceremony and gets a new bound key sealed into the cookie.
+
+The proxy never refuses on the cookie's own copy of the expiry. `keyExpiresAt` inside the cookie is
+a hint written at the last seal; the key row is the fact, and only a request that reached the
+backend can read it. That matters on the second device: turning binding **off** rewrites every
+active key to an ordinary 90-day one, but only the browser that asked gets a re-sealed cookie, so
+another device keeps a cookie that says `passkey` with an expiry that no longer applies. Because
+nothing is decided from that hint, its next request is forwarded, the backend sees an ordinary key
+and answers 200 — no renewal prompt for a session that does not need one. What that device does
+keep until it signs in again is its sealed `uaFamily`, so the user-agent family check below goes on
+applying to it.
+
+> **Renewal is bound to the expiring key's own signature.** `session/renew/options` and
+> `session/renew/verify` are not public: they take the ordinary bearer JWT the proxy signs with the
+> private key in the session cookie, and the key being renewed is that JWT's `keyId` rather than
+> anything the body says. The one thing they do differently from every other route is admit a key
+> whose `expiresAt` has passed, while it is bound and inside its grace. So a caller who does not
+> hold the private half of a key gets the same `SessionRenewalRefusedError` whatever key id they
+> name — no credential, a wrong signature, an unbound key, a revoked key, one past its grace and an
+> inactive account are one answer with one body, and whether a key id is live never leaks.
+
+```tsx
+'use client';
+import { renewSession } from '@spfn/auth/client';
+import { authApi } from '@spfn/auth';
+
+export function RenewSession({ returnTo }: { returnTo: string })
+{
+    return <button onClick={async () =>
+    {
+        const result = await renewSession(authApi);
+
+        if (result.ok)
+        {
+            location.href = returnTo;
+        }
+    }}>Confirm it's you</button>;
+}
+```
+
+A server-rendered page cannot run a WebAuthn ceremony, so `RequireAuth` sends it there instead of
+to the sign-in page:
+
+```tsx
+<RequireAuth renewalPath="/auth/renew">
+  <DashboardContent />
+</RequireAuth>
+```
+
+`renewalPath` defaults to `SPFN_AUTH_SESSION_RENEW_PATH`, and that to `/auth/renew`.
+`getAuthSessionData()` answers a third state, `'renewal-required'`, for apps writing their own
+guard.
+
+**The user-agent family check.** Independently of expiry, a bound session presented from a
+different browser family is refused 401 `SessionContextChangedError` and its three cookies are
+cleared. Browsers do not share cookie jars, so that move cannot happen without a copy. The
+comparison is coarse on purpose — five families, `edge` / `chrome` / `firefox` / `safari` /
+`other`, and **no desktop/mobile axis** — so a version bump, a user-agent reduction and Android's
+"Request desktop site" are all the same browser.
+
+- **Chrome on iOS and Safari on iOS are different families.** They are different cookie jars, so a
+  session moving between them moved by being copied. An in-app `SFSafariViewController` shares
+  Safari's jar and carries no badge of its own, so it reads as `safari` and passes.
+- **A request with no `user-agent` is no signal, not a different family.** A server component's
+  `api.` call reaches the proxy as Node `fetch` and carries none; refusing those would refuse every
+  server-rendered page view.
+- **Unbound accounts are neither checked nor logged.** The check exists for sessions that asked
+  for it.
+
+**The concurrent-use signal.** `listKeys` rows carry `concurrentUseAtMillis` — the last time one
+key was seen from two client addresses inside `SPFN_AUTH_CONCURRENT_USE_WINDOW_MS`. It is a signal
+for a device list to show and notify on, never a refusal: addresses change legitimately, several
+times an hour for a phone. The addresses behind it are not exposed.
+
+Only an address `proxy-guard` attested is recorded or compared. Without that attestation
+`x-forwarded-for` is whatever the caller typed, and a caller who could alternate it on their own key
+could raise "used from two places at once" whenever they liked; a request with no attested address
+counts as no observation, which is also why one of them never makes the *next* request look like a
+move. Where proxy-guard is not configured the signal simply never fires. One key writes at most one
+address change per window, so a phone flipping between cellular and wifi costs one row update rather
+than one per request.
+
+**A binding change that cannot re-seal the cookie fails closed.** Turning binding on or off commits
+on the backend and then re-seals the session cookie in the proxy's response. If that re-seal cannot
+happen, the answer is 500 `SessionResealFailedError` with the three session cookies cleared, never
+the route's 200: a cookie that disagrees with the account is the state the feature exists to avoid,
+and signing in again is what produces one that agrees.
+
+**Unbound accounts are unchanged.** Every response, every cookie and every query count is what it
+was: nothing above applies to an account that did not opt in, and a sign-in that answers without
+the two binding fields seals exactly the session it always did — which is also what an app calling
+`saveSession()` by hand gets.
+
+Contract 0.12.0. `KeySummary.binding`, `KeySummary.concurrentUseAtMillis`,
+`LoginResponse.sessionBinding` and `LoginResponse.keyExpiresAtMillis` are all optional and absent
+for an account that did not opt in.
+
 ### Writing protected routes (route DSL)
 
 This is the current SPFN route DSL — `route.<method>().input().use().skip().handler()` registered
@@ -1162,6 +1471,11 @@ Client flow: call `authApi.getGoogleOAuthUrl.call({ body: { returnUrl } })`, red
 to the returned `authUrl`, and render `OAuthCallback` on your success page. The Next.js interceptor
 manages the keypair → pending-session-cookie → full-session handoff transparently.
 
+On an account with a [second factor](#second-factor-mfa) and a device it has not seen, the
+callback carries `?mfaChallenge=` instead of `userId`/`keyId` and no session is created until
+that challenge is spent — see [the web OAuth path](#the-web-oauth-path). Both the
+`createOAuthCallbackHandler` route and the `OAuthCallback` page flow are handled.
+
 ```tsx
 // app/auth/callback/page.tsx
 export { OAuthCallback as default } from '@spfn/auth/nextjs/client';
@@ -1829,6 +2143,13 @@ as the event is emitted. It is the hook an app uses to offer a [second
 factor](#second-factor-mfa) at a first login or when a new device appears; the package itself
 never blocks an account that has none.
 
+A sign-in that answered **202** because the account needs a [step-up on a new
+device](#step-up-on-a-new-device) emits neither event, and does not move `lastLoginAt` either.
+Both are held until `POST /_auth/mfa/verify` succeeds and then fire together, carrying the
+original channel — so an attacker holding only a password produces no login event and no
+device notice on an account they never got into, which is exactly the signal the owner needs
+these events to mean.
+
 Key **rotation** is deliberately not announced — replacing the key of a device that is already
 signed in is not a new device, and a notice for it would teach the owner to ignore the ones that
 matter. A login that names an `oldKeyId` is only a rotation when that key was actually revoked: an

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' | 'auth.device.start' | 'auth.device.poll' | 'auth.device.info' | 'auth.device.approve' | 'auth.device.deny' | typeof CORE_TIME_OPERATION_ID;
+    id: 'auth.clientProof.handshake' | 'echo.send' | 'items.list' | 'auth.enroll.register' | 'auth.enroll.login' | 'auth.enroll.oauthNative' | 'auth.mfa.verify' | 'auth.mfa.status' | '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;
     /**
@@ -481,6 +481,15 @@ declare const CONTRACT_OPERATIONS: readonly ContractOperation[];
  * `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.
+ *
+ * `auth.mfa.verify` is unproven for the same reason the sign-ins are: the key it
+ * activates is not usable until it succeeds, so there is nothing to sign the
+ * call with. It is the only way to finish a sign-in that answered
+ * `mfaRequired: true`, which is why it is a contract operation while the six
+ * enrolment routes — all of which need an account screen — are not.
+ * `auth.mfa.status` is the one exception among them, because a client that has
+ * just met a 202 needs to be able to tell the person what they enrolled. It is
+ * a bodyless GET, like `core.time`, so it declares no request type.
  */
 declare const AUTH_SURFACE_OPERATIONS: readonly ContractOperation[];
 /** The body is canonical JSON but not the declared request type. */

package/dist/client-proof.js

@@ -1035,6 +1035,27 @@ var AUTH_SURFACE_OPERATIONS = [
     summary: "Verifies a native/web social id_token server-side and enrolls the client-generated public key.",
     since: "0.3.0"
   },
+  {
+    id: "auth.mfa.verify",
+    method: "POST",
+    path: "/_auth/mfa/verify",
+    authProfile: "none",
+    requiresSession: false,
+    requestType: "MfaVerifyRequest",
+    responseType: "MfaVerifyResponse",
+    summary: "Finishes a sign-in that answered mfaRequired by spending the challenge, which activates the key.",
+    since: "0.13.0"
+  },
+  {
+    id: "auth.mfa.status",
+    method: "GET",
+    path: "/_auth/mfa/status",
+    authProfile: "clientProofV1",
+    requiresSession: false,
+    responseType: "MfaStatusResponse",
+    summary: "Reports whether the caller has a second factor, which methods, and how many recovery codes remain.",
+    since: "0.13.0"
+  },
   {
     id: "auth.keys.rotate",
     method: "POST",
@@ -1380,6 +1401,7 @@ import {
 // src/server/types.ts
 var KEY_ALGORITHM = ["ES256", "RS256"];
 var KEY_PLATFORM = ["ios", "android", "web", "desktop"];
+var SESSION_BINDINGS = ["none", "passkey"];
 
 // src/server/client-proof/wire-headers.ts
 var CLIENT_IDENTITY_HEADERS = {
@@ -1397,9 +1419,9 @@ function isAppKind(kind) {
 }
 
 // src/server/client-proof/contract-bundle.ts
-var CONTRACT_VERSION = "0.11.0";
+var CONTRACT_VERSION = "0.13.0";
 var CONTRACT_MAJOR = 0;
-var CONTRACT_SUPPORTED_RANGE = ">=0.11.0 <0.12.0";
+var CONTRACT_SUPPORTED_RANGE = ">=0.13.0 <0.14.0";
 function required(name, type) {
   return { name, type, optional: false };
 }
@@ -1513,14 +1535,98 @@ var CONTRACT_TYPES = [
       optional("oldKeyId", "string")
     ]
   },
+  /**
+   * The sign-in union, flattened the way the poll union was.
+   *
+   * `mfaRequired` is the discriminant and the only required field; everything
+   * else belongs to one branch. False is a session and carries the five login
+   * fields; true is a 202 carrying `challenge` and nothing else, which the
+   * client spends at `auth.mfa.verify` (#95). This grammar has no union type,
+   * so a required discriminant plus optional fields is the only way to say it
+   * — and the typed web client infers one result type from the same
+   * declaration, so it could not have been a union there either.
+   */
   {
     name: "LoginResponse",
     fields: [
-      required("userId", "string"),
-      required("publicId", "string"),
+      required("mfaRequired", "boolean"),
+      optional("challenge", "MfaChallenge"),
+      optional("userId", "string"),
+      optional("publicId", "string"),
+      optional("email", "string"),
+      optional("phone", "string"),
+      optional("passwordChangeRequired", "boolean"),
+      optional("sessionBinding", "KeyBinding"),
+      optional("keyExpiresAtMillis", "integer")
+    ]
+  },
+  /**
+   * What a sign-in hands back instead of a session when the account has a
+   * second factor and this device is new to it.
+   *
+   * `secret` is the challenge itself, returned once. The server stores only its
+   * hash and addresses the row by that, so this value is not recoverable from
+   * the database and is not a bearer credential for anything but the one
+   * `auth.mfa.verify` call it belongs to.
+   */
+  {
+    name: "MfaChallenge",
+    fields: [
+      required("secret", "string"),
+      required("expiresAtMillis", "integer")
+    ]
+  },
+  /**
+   * Exactly one of `code` and `recoveryCode`, beside the challenge.
+   *
+   * The third form the server accepts — an assertion from a passkey the owner
+   * marked as a second factor — is not declared: a WebAuthn assertion is a
+   * nested browser object outside this grammar, and the passkey ceremonies are
+   * not on this surface for the same reason.
+   */
+  {
+    name: "MfaVerifyRequest",
+    fields: [
+      required("challenge", "string"),
+      optional("code", "string"),
+      optional("recoveryCode", "string")
+    ]
+  },
+  /**
+   * The sign-in the challenge was standing in for, plus what the proxy needs.
+   *
+   * `mfaRequired` is false on every 200 here — the step-up just happened — and
+   * it is carried so the body is the same `LoginResponse` shape a direct
+   * sign-in answers. `keyId` and `challengeHash` are for the Next.js proxy: it
+   * seals a session only when both match the pending cookie it baked at the
+   * 202, which is what stops a cookie from one flow sealing a session for
+   * another's key.
+   */
+  {
+    name: "MfaVerifyResponse",
+    fields: [
+      required("mfaRequired", "boolean"),
+      required("keyId", "string"),
+      required("challengeHash", "string"),
+      optional("userId", "string"),
+      optional("publicId", "string"),
       optional("email", "string"),
       optional("phone", "string"),
-      required("passwordChangeRequired", "boolean")
+      optional("passwordChangeRequired", "boolean"),
+      optional("sessionBinding", "KeyBinding"),
+      optional("keyExpiresAtMillis", "integer")
+    ]
+  },
+  /**
+   * What the account has enrolled. No secret, no otpauth URI, no recovery code
+   * — only the counts and names an account screen renders.
+   */
+  {
+    name: "MfaStatusResponse",
+    fields: [
+      required("enrolled", "boolean"),
+      required("methods", "array<MfaMethod>"),
+      required("recoveryCodesRemaining", "integer")
     ]
   },
   {
@@ -1535,12 +1641,20 @@ var CONTRACT_TYPES = [
       required("algorithm", "KeyAlgorithm")
     ]
   },
+  /**
+   * Flattened on the same terms as `LoginResponse`: a native social sign-in on
+   * an enrolled account and a device it has not seen answers 202 with a
+   * challenge rather than a key, so the discriminant is required and the three
+   * login fields are the false branch.
+   */
   {
     name: "OauthNativeResponse",
     fields: [
-      required("userId", "string"),
-      required("keyId", "string"),
-      required("isNewUser", "boolean")
+      required("mfaRequired", "boolean"),
+      optional("challenge", "MfaChallenge"),
+      optional("userId", "string"),
+      optional("keyId", "string"),
+      optional("isNewUser", "boolean")
     ]
   },
   {
@@ -1580,7 +1694,9 @@ var CONTRACT_TYPES = [
       required("isActive", "boolean"),
       optional("revokedAtMillis", "integer"),
       optional("registeredIp", "string"),
-      optional("registeredUserAgent", "string")
+      optional("registeredUserAgent", "string"),
+      optional("binding", "KeyBinding"),
+      optional("concurrentUseAtMillis", "integer")
     ]
   },
   {
@@ -1656,11 +1772,14 @@ var CONTRACT_TYPES = [
     fields: [
       required("status", "DeviceAuthPollStatus"),
       optional("intervalMillis", "integer"),
+      optional("mfaRequired", "boolean"),
       optional("userId", "string"),
       optional("publicId", "string"),
       optional("email", "string"),
       optional("phone", "string"),
-      optional("passwordChangeRequired", "boolean")
+      optional("passwordChangeRequired", "boolean"),
+      optional("sessionBinding", "KeyBinding"),
+      optional("keyExpiresAtMillis", "integer")
     ]
   },
   /**
@@ -1701,7 +1820,13 @@ var CONTRACT_TYPES = [
 var CONTRACT_ENUMS = [
   { name: "KeyAlgorithm", values: [...KEY_ALGORITHM] },
   { name: "KeyPlatform", values: [...KEY_PLATFORM] },
-  { name: "DeviceAuthPollStatus", values: ["pending", "approved"] }
+  { name: "KeyBinding", values: [...SESSION_BINDINGS] },
+  { name: "DeviceAuthPollStatus", values: ["pending", "approved"] },
+  // The two things an account screen can show as enrolled. `recovery` is a
+  // verification method but never a method the account *has* — a recovery code
+  // is what is left when the authenticator is not to hand, so `mfa/status`
+  // reports it as a count and not as a factor.
+  { name: "MfaMethod", values: ["totp", "passkey"] }
 ];
 var BUNDLE_FILENAME = "spfn-mobile-contract.json";
 var BUNDLE_REPO_PATH = `contracts/mobile/${BUNDLE_FILENAME}`;