@spfn/auth 0.3.0-beta.22 → 0.3.0-beta.24

package/README.md

@@ -135,7 +135,7 @@ real secret values out of band, never commit them.
 | `DATABASE_URL` | both | yes | Postgres connection |
 | `SPFN_AUTH_VERIFICATION_TOKEN_SECRET` | `.env.server` | yes | OTP / verification token signing |
 | `SPFN_AUTH_SESSION_SECRET` | `.env.local` | yes | ≥32 chars, AES-256 session cookie encryption (validated: entropy/unique-char checks) |
-| `SPFN_AUTH_TOKEN_ENCRYPTION_KEYS` | `.env.server` | web OAuth | OAuth token keyring: comma-separated `<keyId>:<base64-32-byte-key>` entries; first key is active |
+| `SPFN_AUTH_TOKEN_ENCRYPTION_KEYS` | `.env.server` | web OAuth, **MFA** | At-rest keyring: comma-separated `<keyId>:<base64-32-byte-key>` entries; first key is active. Required by any app offering a [second factor](#second-factor-mfa), social login or not |
 | `SPFN_API_URL` | `.env.local` | — | default `http://localhost:8790` |
 | `SPFN_AUTH_SESSION_TTL` | both | — | default `7d` (e.g. `7d`, `12h`, `45m`) |
 | `SPFN_AUTH_JWT_SECRET` / `SPFN_AUTH_JWT_EXPIRES_IN` | `.env.server` | — | legacy server-signed JWT mode only |
@@ -171,6 +171,12 @@ real secret values out of band, never commit them.
 | `SPFN_AUTH_PASSKEY_RP_ID` / `_RP_NAME` / `_ORIGINS` | `.env.server` | — | relying party for passkeys; defaults derive from `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}` and are **checked at boot** — see [Passkeys](#passkeys-webauthn) |
 | `SPFN_AUTH_PASSKEY_USER_VERIFICATION` | `.env.server` | — | `preferred` (default) or `required`; `discouraged` refuses boot |
 | `SPFN_AUTH_PASSKEY_CHALLENGE_TTL_SECONDS` / `_RECENT_AUTH_MINUTES` | `.env.server` | — | defaults `300` / `10` — see [Passkeys](#passkeys-webauthn) |
+| `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_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
@@ -214,11 +220,24 @@ routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-si
 | `listPasskeys` | POST `/_auth/passkeys/list` | yes | the caller's enrolled passkeys |
 | `renamePasskey` | POST `/_auth/passkeys/rename` | yes | rename one |
 | `revokePasskey` | POST `/_auth/passkeys/revoke` | yes | retire one (refused if it is the last way in) |
+| `mfaTotpEnroll` | POST `/_auth/mfa/totp/enroll` | yes | mint a TOTP secret — see [Second factor](#second-factor-mfa) |
+| `mfaTotpConfirm` | POST `/_auth/mfa/totp/confirm` | yes | spend the first code; answers the ten recovery codes |
+| `mfaDisable` | POST `/_auth/mfa/disable` | yes + step-up | remove the second factor (204 either way) |
+| `mfaMarkPasskey` | POST `/_auth/mfa/passkey/mark` | yes + step-up | mark or unmark a passkey as the second factor |
+| `mfaRegenerateRecoveryCodes` | POST `/_auth/mfa/recovery/regenerate` | yes + step-up | ten fresh codes; every earlier one stops verifying |
+| `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 |
 | `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) |
@@ -239,7 +258,10 @@ 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).
 
 ### Verified-email signup
 
@@ -523,7 +545,7 @@ cut off anything they no longer recognise.
 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
 ```
@@ -592,6 +614,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
@@ -978,6 +1008,274 @@ The behaviour above is asserted row by row in
 
 Configuration rows C1–C6 are in `src/__tests__/unit/passkey-config.test.ts`.
 
+### Second factor (MFA)
+
+Optional, and optional in the strong sense: an account that never enrols sees exactly the
+behaviour it saw before this existed, on every route. Nothing here blocks anybody — the
+package asks for a second factor only from people who asked it to.
+
+Two forms. A **TOTP** authenticator app (RFC 6238, SHA-1, 30-second steps, six digits, one
+step of drift), or a **passkey** the owner already enrolled through `/_auth/passkeys/*` and
+has marked as a second factor. Either one comes with ten single-use recovery codes.
+
+```
+enrol   → POST /_auth/mfa/totp/enroll      → { secret, otpauthUri }, shown once
+confirm → POST /_auth/mfa/totp/confirm     → { recoveryCodes }, ten of them, shown once
+        → or POST /_auth/mfa/passkey/mark  → an existing passkey becomes the second factor
+inspect → GET  /_auth/mfa/status           → { enrolled, methods, recoveryCodesRemaining }
+step up → POST /_auth/mfa/step-up          → 204, this device's window reopens
+remove  → POST /_auth/mfa/disable          → 204
+```
+
+#### Prerequisite: the encryption keyring
+
+A TOTP secret is encrypted at rest with **`SPFN_AUTH_TOKEN_ENCRYPTION_KEYS`** — the same
+keyring the OAuth tokens use, in the same `enc:v2:<keyId>:` frame, under its own additional
+authenticated data so a row cannot be moved between accounts. That variable is listed above
+as "web OAuth", and it is now also required by any app offering a second factor, **including
+an app with no social login at all**. `totp/enroll` answers a 500 configuration error while
+it is unset, and a key id dropped from the keyring answers the same way rather than the 401 a
+wrong code gets — an operator has to be able to tell a broken deploy from a person misreading
+their phone. A row written under a key that has since been retired is re-encrypted in place
+the next time its owner verifies, so a retired key drains as people use their second factor.
+
+#### Enrolling
+
+`totp/enroll` mints a 20-byte secret and returns it as RFC 4648 base32 (upper case, no
+padding) plus the `otpauth://` URI an authenticator app scans. Nothing is enrolled yet:
+calling it again replaces the pending secret, and a secret nobody confirms is swept away a day
+later by `auth.mfa.sweep`. `totp/confirm` spends the first code, which is what turns the
+enrolment into a second factor and issues the recovery codes.
+
+A submitted code has its spaces and dashes stripped, so `123 456` and `123-456` are the same
+code. Five wrong codes discard the pending secret — the sixth attempt says there is nothing to
+confirm, and a fresh `totp/enroll` is the remedy and what resets the counter. A **confirmed**
+enrolment is never discarded that way; `totp/enroll` on one is a 409, because replacing a
+working second factor is `disable` followed by a fresh enrolment, both step-up gated.
+
+The **same code cannot be spent twice**, which is what makes it single-use: the newest step
+the account has spent is remembered, and a code presented again inside its own thirty seconds
+is refused. That includes the legitimate case of a second device signing in during the same
+step — it gets a 401 with the same body as a wrong code, and the client should **retry on the
+next step** rather than treat it as a bad credential.
+
+#### Recovery codes
+
+Ten codes, format `xxxxx-xxxxx`, shown once at confirmation and once at each regeneration.
+They are stored as **password hashes** rather than as the unsalted SHA-256 the link flows use:
+a code a human transcribes is short enough that a leaked dump of unsalted hashes would fall to
+an offline sweep. `recovery/regenerate` raises the generation, so every code from before it
+stops verifying with the same body as one that never existed. `status` reports how many of the
+current generation are unspent, which is what an app warns on at two remaining.
+
+#### The step-up window
+
+For an **enrolled** account, four kinds of change ask for the second factor again:
+
+| route | what it changes |
+|-------|-----------------|
+| `PUT /_auth/password` | the password, and every other session with it |
+| `POST /_auth/keys/revoke-all` | every device |
+| `POST /_auth/mfa/disable`, `recovery/regenerate`, `passkey/mark`, `totp/enroll` | the second factor itself |
+| `POST /_auth/passkeys/register/options`, `passkeys/revoke` | the account's credentials |
+
+The rule is per **device key**: this device must have proved the second factor within
+`SPFN_AUTH_MFA_STEP_UP_MINUTES` (default 10). Otherwise the answer is **403
+`STEP_UP_REQUIRED`**, and the client sends the user to `POST /_auth/mfa/step-up` — a TOTP
+code, a recovery code, or an assertion from a marked passkey (options from
+`POST /_auth/mfa/step-up/options`) — and retries. 403 rather than 401 on purpose, and for the
+reason `RECENT_AUTH_REQUIRED` is: a 401 on an authenticated route is what a web client reads
+as "the session is gone", so it would sign the user out instead of asking for a code.
+
+A key **rotation carries the window across**, because rotating is already proof of the same
+device — otherwise the web proxy, which rotates at every login, would expire it constantly.
+
+The two passkey routes keep their own `RECENT_AUTH_REQUIRED` rule unchanged and run it after
+the step-up: the two guards are independent, and an unenrolled account meets exactly the rule
+it met before. Unmarking the last second-factor passkey is likewise independent of
+`LAST_RECOVERY_CREDENTIAL` — removing a mark is not removing a way into the account, so
+`passkey/mark false` succeeds where `passkeys/revoke` on the same credential is still refused.
+
+Two sign-ins deliberately produce a session with no verification of its own: a
+[device-code login](#device-code-login) and a passkey sign-in. Both are exempt at
+*registration* and both still step up for a sensitive change, which is what
+`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.
+
+#### Telling people it exists
+
+`authLoginEvent` and `authDeviceRegisteredEvent` carry **`mfaEnrolled: boolean`**, computed as
+the event is emitted. That is the whole of the package's opinion: subscribe and offer
+enrolment at a first login or when a new device appears. Nothing is ever blocked on it.
+
+#### Errors
+
+| error | status | `code` | when |
+|-------|--------|--------|------|
+| `MfaVerificationFailedError` | 401 | — | a wrong or stale code, a spent step, a used / old-generation / foreign recovery code, or an assertion from an unmarked passkey |
+| `MfaNotEnrolledError` | 400 | — | `confirm` with no pending secret (the five-strike deletion included), or `regenerate` on an account with no second factor |
+| `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 |
+
+None of these is a mobile-contract error: the enrolment routes are not contract operations.
+
+#### 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.
+`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
+`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
@@ -1689,6 +1987,11 @@ and not what it began on, so a stolen password used on a new machine was silent
 Send it with a [sign-out-everywhere link](#the-sign-out-everywhere-link), which is the action the
 notice should offer.
 
+Both `authLoginEvent` and `authDeviceRegisteredEvent` carry `mfaEnrolled: boolean`, computed
+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.
+
 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
@@ -1700,7 +2003,8 @@ Payload types: `AuthLoginPayload`, `AuthRegisterPayload`, `AuthPasswordResetPayl
 `InvitationAcceptedPayload`, `AuthDeletionRequestedPayload`, `AuthDeletionCancelledPayload`,
 `AuthDeletionCompletedPayload`, `OAuthUnlinkedPayload` (`auth.oauth.unlinked` — provider-side
 disconnect, see the OAuth unlink-notify section), `PasskeyEnrolledPayload`,
-`PasskeyRevokedPayload`. These events also bind to `@spfn/core/job`
+`PasskeyRevokedPayload`. `AuthLoginPayload` and `AuthDeviceRegisteredPayload` both gained
+`mfaEnrolled` in 0.3.0-beta.23. These events also bind to `@spfn/core/job`
 jobs via `.on(event)`.
 
 ## Registration gate (`beforeRegister`)

package/dist/client-proof.js

@@ -1380,6 +1380,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 +1398,9 @@ function isAppKind(kind) {
 }
 
 // src/server/client-proof/contract-bundle.ts
-var CONTRACT_VERSION = "0.11.0";
+var CONTRACT_VERSION = "0.12.0";
 var CONTRACT_MAJOR = 0;
-var CONTRACT_SUPPORTED_RANGE = ">=0.11.0 <0.12.0";
+var CONTRACT_SUPPORTED_RANGE = ">=0.12.0 <0.13.0";
 function required(name, type) {
   return { name, type, optional: false };
 }
@@ -1520,7 +1521,9 @@ var CONTRACT_TYPES = [
       required("publicId", "string"),
       optional("email", "string"),
       optional("phone", "string"),
-      required("passwordChangeRequired", "boolean")
+      required("passwordChangeRequired", "boolean"),
+      optional("sessionBinding", "KeyBinding"),
+      optional("keyExpiresAtMillis", "integer")
     ]
   },
   {
@@ -1580,7 +1583,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")
     ]
   },
   {
@@ -1660,7 +1665,9 @@ var CONTRACT_TYPES = [
       optional("publicId", "string"),
       optional("email", "string"),
       optional("phone", "string"),
-      optional("passwordChangeRequired", "boolean")
+      optional("passwordChangeRequired", "boolean"),
+      optional("sessionBinding", "KeyBinding"),
+      optional("keyExpiresAtMillis", "integer")
     ]
   },
   /**
@@ -1701,6 +1708,7 @@ var CONTRACT_TYPES = [
 var CONTRACT_ENUMS = [
   { name: "KeyAlgorithm", values: [...KEY_ALGORITHM] },
   { name: "KeyPlatform", values: [...KEY_PLATFORM] },
+  { name: "KeyBinding", values: [...SESSION_BINDINGS] },
   { name: "DeviceAuthPollStatus", values: ["pending", "approved"] }
 ];
 var BUNDLE_FILENAME = "spfn-mobile-contract.json";