@ultimat3/auth 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -5,7 +5,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | Rule | |
 |---|---|
 | Deps | `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/db`. No external deps. |
-| Never import | `@ultimat3/policy`, `@ultimat3/http` (tier 2 consumers), `@ultimat3/mail` (sideways) |
+| Never import | `@ultimat3/policy`, `@ultimat3/http` (tier 2 consumers), `@ultimat3/mail` (tier 4, upward) |
 | Policy seam | `PolicyActorFields` in `policy-bridge.ts` mirrors policy's shape structurally |
 | Http seam | `RequestLike` / `CookieJar` in `session.ts` and `AuthRouteDescriptor` in `oauth-route.ts`; http binds to them, not the reverse |
 | Mail seam | injected `MailSender` port in `verify.ts`; the app wires `@ultimat3/mail`'s `send` |
@@ -41,16 +41,26 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 - **The limiter's table is bounded, and the eviction order is the guarantee.** Every bucket carries
   `forgetAtMs`; `policy.maxKeys` (`DEFAULT_MAX_AUTH_LIMIT_KEYS`) is the backstop, and a **live
   lockout outranks its own deadline** in the comparator. Never reduce that sort to recency.
-- **`AuthLimiter` is async on every member and declares the policy it enforces.**
-  `assertAuthLimiterPolicy` (once, in `defineAuth`) refuses a per-process limiter under
-  `scope: 'shared'` (`X_AUTH_LIMITER_NOT_SHARED`) and different `maxAttempts`/`windowMs`/
-  `lockoutMs` (`X_AUTH_LIMITER_POLICY_MISMATCH`). `maxKeys` is not compared. Nothing here reads the
-  environment to guess a replica count.
-- **`postgresAuthLimiter` is the shared limiter, a row per FAILURE** (sliding window: the count is
-  `at_ms > now - windowMs`). The insert and the count are two statements, never one CTE, and the
-  insert takes `pg_advisory_xact_lock` on the key so two outer transactions cannot both read one
-  short (guarantee is READ COMMITTED). `auth.ts` records account → ip → org in that fixed order.
-  `greatest` on the lockout upsert only extends. `PgExecutor` is structural: the pool is the host's.
+- **`AuthLimiter` is async on every member, declares the policy it enforces, and is a
+  RESERVATION.** `reserve(key)` counts the attempt in the step that admits it (refused, counting
+  nothing, while locked); `refund(reservation)` gives ONE back and lifts a lockout the window no
+  longer justifies; `recordSuccess(key)` clears the key. There is no check-then-record pair: N
+  concurrent guesses all passed the check. `assertAuthLimiterPolicy` (once, in `defineAuth`)
+  refuses a per-process limiter under `scope: 'shared'` (`X_AUTH_LIMITER_NOT_SHARED`) and different
+  `maxAttempts`/`windowMs`/`lockoutMs` (`X_AUTH_LIMITER_POLICY_MISMATCH`). `maxKeys` is not
+  compared. Nothing here reads the environment to guess a replica count.
+- **Every credential check runs through `openLoginAttempt`** (`login-attempt.ts`): account → ip →
+  org reserved in that fixed order BEFORE the KDF or the TOTP compare. A failure calls nothing (the
+  reservations are the record); `release()` for no verdict (a shed KDF, a store that is down, a
+  bucket that refused) or a factor proven with another still owed; `succeed()` clears the account
+  and refunds the shared two.
+- **`postgresAuthLimiter` is the shared limiter: ONE row per key in `x_auth_lockouts`, holding the
+  instants still inside the window** (`attempts_ms bigint[]` — a sliding window). The take is one
+  `insert … on conflict do update` reading the window off `x_auth_lockouts.<column>`, never a CTE
+  and never a second table: only the row the statement locks is re-read after a wait. `admitted`
+  is a column because `returning` cannot see the old row; no row back is never an admission. A
+  live lockout is never rewritten. `PgExecutor` (`@ultimat3/core`'s, re-exported) is structural:
+  the pool is the host's.
 - **`configureAuthLimiters` is the HOST's install point and takes a FACTORY**, called with the
   RESOLVED policy once per bucket; the comparison still runs on what comes back. Precedence:
   `config.limiter` → the installed factory → `createAuthLimiter`. `installedAuthLimiter` and
@@ -90,22 +100,27 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 - `takeVerification(purpose, identifier, tokenHash)` consumes **only on a hash match**, in one
   conditional statement (`consumed_at is null` on the UPDATE and its subselect,
   `order by created_at desc limit 1`); `consumeVerification` still compares in constant time.
+  `consumed_at` is the adapter's `Clock`, bound, never `now()`.
 - **Foreign text in a `cause:` goes through `renderCauseValue`, in a `fix:` through
   `renderFixLiteral`, and in a shell `fix:` through `renderFixShellArg`.** Foreign here:
-  `providerDetail()`'s return, `claims.iss`, `accountLocked`'s `key`, and every OAuth endpoint URL
+  `providerDetail()`'s return, `claims.iss`, `accountLocked`'s `key` (an `org:` key is never
+  rendered at all — it was looked up from the caller's address), and every OAuth endpoint URL
   in a command position (`jwks.ts`, `oauth-profile.ts`, `oauth-exchange.ts`,
   `oauth-discovery.ts`) — the registry is filled by an issuer's own discovery document. A LINE
   that would not run degrades to prose: `jwks.ts`'s `readTheKeySet(tail)` decides with core's
   `isFixShellSafe`. `oauth-discovery.ts` still owes that repair (it keeps `auth` on
   `FIX_SHELL_ARG_PINS`). `${provider}` is registry-validated boot config, not foreign.
-- `readCookie` never throws on a malformed value (`decodeURIComponent('%')`).
+- Cookies are read through `@ultimat3/core`'s `readCookie` (`readSessionCookie`, the oauth
+  handshake), which never throws on a malformed value (`decodeURIComponent('%')`).
 - A token endpoint's HTTP 200 is not success — read `error`.
 - Link by address only when the provider **and** the local account both verified it
   (`link: 'verified-email'`, default; `'never'` is the only other value).
 - **The OAuth route paths are not configurable.** `oauth-paths.ts` imports nothing and is read by
   both `oauth-errors.ts` and `oauth-route.ts`; every "start over" fix is `restartAt(provider)`.
 - The routes are **descriptors** (`AuthRouteDescriptor`), never mounted handlers.
-- The callback answers failure as **coded JSON**, and success redirects to a fixed `successPath` —
+- The callback answers failure as **coded JSON** — a fixed body per code (`code`, `title`, `docs`,
+  one `cause`, `fix: x errors explain <CODE> --json`); the authored cause and fix are the
+  `auth.oauth.refused` log line — and success redirects to a fixed `successPath` —
   never `?next=` (`nextAfterSignIn` in `@ultimat3/http` is the one open-redirect check).
 - The handshake cookie is cleared on **every** callback outcome.
 - Refresh is **not implemented**, so the framework **stores no provider token**: `accountFor`
@@ -118,35 +133,58 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   an uncoded adapter throw logs `auth.oauth.uncoded_failure`, a rejecting `OAuthFetch` logs
   `auth.oauth.token_fetch_failed`, and the `POST /token` body is read as
   `providerDetail(response, 'coded-only')` (that request carries `client_secret`).
-- **`x_users.mfa_secret` is a PLAINTEXT secret** and `tables.ts` says so; encrypting it needs a
-  key-management seam this package does not have. Deferred deliberately.
+- **`x_users.mfa_secret` is SEALED** (`mfa-secret.ts`, purpose `auth:x_users.mfa_secret`):
+  `saveTotpSecret` writes, `openTotpSecret` reads and REFUSES a value core's `isSealed` does not
+  recognise (`X_MFA_SECRET_UNSEALED`, fix `x auth seal-mfa --json`). No plaintext fallback, ever —
+  `sealMfaSecrets` is the one-shot — each write a compare-and-set (`replaceMfaSecret`), a row that
+  changed underneath is `skipped` — and `x doctor` counts what is left. Whether a value is sealed is
+  `isSealed`'s to say, never a `like` in an adapter (`listUsersWithMfaSecret` returns them all).
 - **`providerJwks` memoises only the DEFAULT client**; a caller supplying options gets its own.
 - **A JWKS refresh is single-flighted through core's `createSingleFlight` with
   `deadlineMs = timeoutMs * 2`**; eviction frees the key, never the work, and a `createFence`
   generation check (read, never `guard`) stops a superseded refresh overwriting the cache.
   `schedule` is injectable.
 - **A success clears the ACCOUNT bucket and nothing else** — clearing the address bucket made the
-  limiter inert against stuffing.
-- **`MemoryAdapter.createUser` enforces `x_users.email` and `x_users.external_id` uniqueness**
-  (`authUniqueViolation`, `X_AUTH_WRITE_FAILED`), NULLS DISTINCT like Postgres.
+  limiter inert against stuffing. A password proven with a second factor still owed clears
+  NOTHING: `completeMfa` is what clears, or a repeat of the first leg wipes the wrong codes.
+- **`MemoryAdapter.createUser` and `updateUser` enforce `x_users.id`, `email` and `external_id`
+  uniqueness** (`authUniqueViolation`, `X_AUTH_WRITE_FAILED`), NULLS DISTINCT like Postgres;
+  `BuiltinAdapter` answers the same code through `builtin-adapter-violation.ts`.
   **`MemoryAdapter` takes a `Clock`** (default `systemClock`) and stamps every instant from it.
   `adapter-parity.test.ts` pins both.
-- The newer `AuthAdapter` members are OPTIONAL (`findUserByExternalId`, `listUsersByOrg`,
-  `deleteSessionsForUser`, `deleteSessionsForOrg`, `deleteSessionsCreatedBefore`); callers throw
-  `X_NOT_IMPLEMENTED` naming the method.
-- An api key's scopes are the agent actor's scopes. Never union them with the owner's roles.
+- Every `AuthAdapter` member is REQUIRED — a missing one is a compile error at `defineAuth`, and
+  no caller in this package refuses at runtime with `X_NOT_IMPLEMENTED`.
+- **An api key is its owner's credential.** `verifyApiKey` re-reads the owner (after the secret
+  matched, never before) and refuses a missing or disabled one as the same `X_API_KEY_INVALID`; a
+  key with `userId === null` has no owner and is unchanged. `disableUser` revokes the user's live
+  keys beside their sessions, and logs before its first write.
+- **A key's scopes only ever shrink** (`apiKeyScopes`, `policy-bridge.ts`): `*` and `<res>:*` are
+  refused at `issueApiKey` (`X_CONFIG_INVALID`) and dropped from a stored row; an OWNED key keeps
+  only what its owner's grants cover. Roles are policy's to expand, so the default grants are the
+  row's `permissions` + `scopes` (`directGrants`) and a role-based app passes
+  `apiKeyResolver(store, { grantsOf })`. Never union a key with the owner's roles.
+- **`apiKeyResolver(() => store)` is the ONE token → caller mapping** (`api-key-resolver.ts`):
+  `verifyApiKey` → `apiKeyActor`, `X_API_KEY_INVALID` → `null`, everything else rethrown. Its
+  `ApiKeyCaller` is structurally http's `BearerCaller` and mcp's `ResolvedToken` — declared here
+  because tier 2 imports neither. The store is a thunk (a mount is declared before boot installs
+  the database client). No second in-memory key store: `MemoryAdapter` IS an `ApiKeyStore`.
 - Rotate the session id on any privilege change (`rotateSession`, called by `updatePrivileges` in
-  `privileges.ts`), never patch the row.
+  `privileges.ts`), never patch the row. A `passwordHash` change also ends every OTHER session of
+  that user (`deleteOtherSessions`), or all of them when the caller passed no session of theirs.
 - **Every argon2 call goes through `kdfGate()`** — width 8, queue 64, `X_OVERLOADED` past it
   (borrowed from http, in `AUTH_BORROWED_ERROR_CODES`). The pool is core's `createFlightGate`, the
   refusal auth's own through core's `overflow:` seam. `configureKdfGate()` is the ONE install point
   and deliberately not a `defineAuth` key.
-- **MFA has a first leg and no second one, and the second is not a route you can just add.**
-  `login()` / `completeOAuthLogin()` throw `X_MFA_REQUIRED` before any session exists. A
-  `POST /auth/mfa/verify { userId, code }` would be unauthenticated by construction. The follow-up
-  needs three things together: a **sealed pending-MFA credential** built like `sealHandshake`, the
-  completion as an `AuthRouteDescriptor` with its path in `oauth-paths.ts`'s style, and
-  `auth.limiter` around `verifyTotp`. `TotpReplayGuard` is the completion's.
+- **MFA's second leg is `completeMfa(auth, challenge, code)`** (`mfa-challenge.ts`). `login()`
+  ends in `X_MFA_REQUIRED` whose `meta.challenge` is a `seal()` value (purpose
+  `auth:mfa-challenge`: user id, nonce, expiry on the server's clock, `MFA_CHALLENGE_TTL_MS`) —
+  `meta`, never `cause`, and never a bare user id: a second leg keyed by one is unauthenticated by
+  construction. The code is reserved against the same three buckets before it is compared, and a
+  spent step is refused through `auth.totpReplay` (checked and remembered with no `await`
+  between). It needs the app's master key (`X_SEAL_KEY_MISSING`). No route ships: the handler
+  decides how the challenge travels. Anything that is not six digits is a RECOVERY CODE: hashed
+  (`recoveryCodeHash`) and consumed by `adapter.consumeRecoveryCode` — one conditional UPDATE, so
+  single-use is storage's guarantee. There is no read-then-write redemption helper.
 - **`mfa.required` is the literal `false`, and `defineAuth` refuses a `true`** (`X_CONFIG_INVALID`):
   enforcing it would lock out every un-enrolled user. `mfa.issuer` is read by
   `enrolTotp(auth, { account })`.
@@ -168,8 +206,10 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `policy-bridge.ts` | the one funnel: identity → `Actor`, all four `ActorKind`s |
 | `session.ts` | two expiries, rotation, revocation, device list, the cookie |
 | `adapter.ts` | the seam; `builtin-adapter.ts` (Postgres) + `memory-adapter.ts` |
-| `rate-limit.ts` | per-ip, per-account and per-org buckets, lockout, scope check, `loginFailed()` |
-| `rate-limit-postgres.ts` | the SHARED limiter: two tables, a row per failure, over a structural `PgExecutor` |
+| `builtin-adapter-violation.ts` | a Postgres unique violation on an auth table → `authUniqueViolation` |
+| `rate-limit.ts` | per-ip, per-account and per-org buckets as reservations, lockout, scope check, `loginFailed()` |
+| `login-attempt.ts` | one attempt's reservations across the three buckets, taken before the check and settled after it |
+| `rate-limit-postgres.ts` | the SHARED limiter: one table, one row per key, a one-statement take, over a structural `PgExecutor` |
 | `limiter-install.ts` | the host's one install point for that limiter — the factory, what it built, and the purge over it |
 | `oauth.ts` | `OAuthProvider`, PKCE, `beginOAuth`, the callback gate. No I/O, no env |
 | `oauth-builtins.ts` | the three shipped IdPs, as data. Imports only the type, so no cycle |
@@ -177,9 +217,11 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `oauth-discovery.ts` | `/.well-known/openid-configuration` → an `OAuthProvider`. One `fetch` |
 | `jwks.ts` | `crypto.subtle` signature verification, cached by `kid`, one shared in-flight refresh. No dependency |
 | `workload.ts` | a workload JWT (K8s SA / SPIFFE / IMDS / RFC 8693) → a `ServiceIdentity` |
-| `revocation.ts` | per-user, per-org and before-an-instant sweeps; `disableUser` |
+| `revocation.ts` | per-user, per-org and before-an-instant sweeps; `disableUser` (sessions and api keys) |
+| `mfa-challenge.ts` | the sealed challenge `X_MFA_REQUIRED` carries, and `completeMfa` |
+| `mfa-secret.ts` | the TOTP secret at rest: seal on write, open on read, the one-shot that seals older rows |
 | `directory.ts` | `describeUser` (allow-list projection), `listOrgUsers`, external-id lookup |
-| `privileges.ts` | `updatePrivileges` — the grant, and the rotation it requires |
+| `privileges.ts` | `updatePrivileges` — the grant, the rotation it requires, and the sessions a changed password ends |
 | `oauth-cookie.ts` | the handshake's home between the two legs: seal, open, the cookie |
 | `oauth-exchange.ts` | `oauthCredentials` + the one POST to the token endpoint |
 | `id-token.ts` | id token → claims this handshake may believe |
@@ -190,7 +232,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `oauth-login-fixture.ts` | the adapter, clock and profile the three `oauth-login*` suites share. Off `index.ts` |
 | `oauth-paths.ts` | the one declaration of where the two routes live. Imports nothing |
 | `errors.ts` | the codes this package owns and borrows, their titles, the one `registerErrorCodes()` call, `AuthError`, and every non-OAuth factory |
-| `oauth-errors.ts` | the OAuth half of those factories, and `restartAt`. Split off at the 500-line ceiling; declares no code and registers nothing |
+| `oauth-errors.ts` | the OAuth refusals more than one OAuth module raises, and `restartAt`. A refusal with one thrower lives beside it; declares no code and registers nothing |
 | `oauth-route.ts` | `oauthLogin(auth)` — the redirect out and the callback back |
 | `kdf-gate.ts` | the one bound on concurrent argon2 work, and the `X_OVERLOADED` past it — core's `createFlightGate` with auth's own refusal injected |
 | `email.ts` | `normaliseEmail` — the one normalisation an address gets before it is an identity key |
@@ -210,7 +252,8 @@ Gotchas:
   this package **owns**, unconditionally, and lists the borrowed two in `AUTH_BORROWED_ERROR_CODES`
   without a title. A `hasErrorCode()` guard would suppress the `X_ERROR_CODE_DUPLICATE` that is
   supposed to fire when two packages claim one code.
-- Tests run against `MemoryAdapter`; no ADAPTER test needs a database. The two exceptions are
+- Tests run against `MemoryAdapter`; the one ADAPTER test that boots a database is
+  `adapter-parity-identity.test.ts` (PGlite). The two other exceptions are
   `postgresAuthLimiter`'s, and they are exceptions in the shape the repo already has: the
   scripted-executor twin (`rate-limit-postgres.test.ts`) proves the protocol with no server,
   and `rate-limit-postgres.live.test.ts` is `describe.skip` without `TEST_DATABASE_URL` — the

package/README.md

@@ -40,6 +40,9 @@ const { start, callback } = oauthLogin(auth);
 - The lockout counts attempts against one identity, so it has to be **one** count. `AuthLimiter`
   is async on every member and declares the policy it enforces; `defineAuth` refuses a limiter
   that disagrees with the app's declaration.
+- An attempt is **reserved** before the KDF, never checked and recorded after it: `reserve(key)`
+  counts the guess in the step that admits it, so a concurrent burst spends the allowance as it
+  arrives. `refund(reservation)` gives one back on success; a failure calls nothing.
 
 ## The lockout across replicas
 
@@ -70,8 +73,10 @@ refuses any pairing that would make it a lie:
 `account:<email>` and `ip:<addr>` were the only key shapes, so one tenant's misconfigured
 integration hammering login from 400 addresses was capped by neither — each IP bucket allowed its
 own quota, the account buckets protected individuals, and the shared limiter saturated behind
-them. `orgKey(orgId)` is the third shape, checked in `login()` once the address resolves to an org
-and still before the KDF runs.
+them. `orgKey(orgId)` is the third shape, reserved in `login()` once the address resolves to an org
+and still before the KDF runs. A locked tenant answers `X_ACCOUNT_LOCKED` with no org id in it —
+the id was looked up from the address the caller typed — and an attempt the tenant cap turns away
+is not counted against the account or the address.
 
 `rateLimit.orgMaxAttempts` is its own number, defaulting to `maxAttempts * 20`: a whole tenant
 sharing five attempts is a denial of service against that tenant. A success on one member's
@@ -103,14 +108,18 @@ exemption here — the token arrived in a header.
 
 **mTLS is out of scope.** TLS termination is the mesh's job ([axiom
 7](../../docs/idea/README.md)); the framework's part is reading a trusted
-`x-forwarded-client-cert` through `@ultimat3/http`'s trusted-proxy seam, which that package owns.
+`x-forwarded-client-cert` through `@ultimat3/http`'s trusted-proxy seam, which that package owns —
+and only once the app declares `configureHttp({ trustClientCertHeader: true })`: trusting the
+proxy's `x-forwarded-for` is not a promise that it strips a certificate header the client sent.
 
 `maxKeys` is not compared — it bounds one process' table, not a limit. A custom limiter therefore
 does **not** own its own configuration: the policy stays the app's single statement of the limits,
 and the boot check is what keeps it true.
 
-**A shared limiter ships, `As of 2026-08`** — `postgresAuthLimiter({ executor, clock, policy })`,
-two tables, a row per failure so the window still SLIDES across replicas. Until it landed,
+**A shared limiter ships, `As of 2026-10`** — `postgresAuthLimiter({ executor, clock, policy })`,
+one table (`x_auth_lockouts`), one row per key holding the instants still inside the window, so
+the window still SLIDES across replicas and a take is ONE statement: forty concurrent guesses
+against `maxAttempts: 5` are admitted five times. Until it landed,
 `scope: 'shared'` was a declaration nothing in the framework could satisfy while `x new` scaffolded
 `replicas: 2` — `maxAttempts × 2` guesses per account. `executor` is a `PgExecutor`, anything
 speaking `query(text, values)`; **never `Bun.sql`**, whose `.query` is `undefined`.
@@ -152,7 +161,17 @@ defineAuth({
 Both limiters share one table: the keys are prefixed (`account:`, `ip:`, `org:`) and every limit
 travels as a statement parameter, so the tenant bucket's wider allowance cannot leak into the
 account bucket's. It reports `maxKeys: undefined` — there is no in-process table to bound — and
-neither table forgets on its own.
+the table does not forget on its own.
+
+A limiter of your own implements the same five members:
+
+| Member | Contract |
+|---|---|
+| `reserve(key)` | count one attempt atomically; `X_ACCOUNT_LOCKED`, counting nothing, while the key is locked; the attempt that fills the window is admitted and starts the lockout. Answers `{ key, atMs }` |
+| `refund(reservation)` | remove that ONE attempt, and lift a lockout the window no longer justifies |
+| `recordSuccess(key)` | clear the key — its window and its lockout |
+| `lockedUntil(key)` / `reset()` | the live deadline or `null`; drop everything |
+| `purgeExpired?()` | only for a limiter backed by a table |
 
 **An app does not have to write any of that, `As of 2026-08-22`.** The boot fills a seam and every
 `defineAuth` in the process picks it up:
@@ -178,10 +197,10 @@ Precedence is `defineAuth({ limiter })` → the installed factory → `createAut
 `resetAuthLimiters()` puts the per-process default back. `@ultimat3/cli`'s `startServices` calls it
 on every boot, so a scaffolded app gets a fleet-wide lockout with nothing to remember.
 
-Neither table forgets on its own, and `purgeAuthLimits()` is the framework's reader for that:
-it drops failures past the window and lockouts that have expired, measured against the clock the
-host handed the limiter, and it sweeps only the WIDEST window installed — a sweep on a narrower
-one deletes failures another limiter is still counting, which hands a sprayer its attempts back.
+The table does not forget on its own, and `purgeAuthLimits()` is the framework's reader for that:
+it drops every key whose window has emptied and whose lockout has expired, measured against the
+clock the host handed the limiter, and it sweeps only the WIDEST window installed — a sweep on a
+narrower one deletes attempts another limiter is still counting, which hands a sprayer them back.
 `@ultimat3/jobs`' `purge()` job is what calls it hourly; `x dev` and every role container declare
 that sweep at boot.
 
@@ -222,12 +241,13 @@ registerOAuthProvider(await discoverOAuthProvider({ id: 'bigco-sso', issuer: 'ht
 | `registerOAuthProvider(provider)` | the frozen provider; `X_OAUTH_PROVIDER_DUPLICATE` on a second claim of one id |
 | `providerFor(id)` | the provider, or throws `X_OAUTH_PROVIDER_UNKNOWN` — never `undefined` |
 | `hasOAuthProvider(id)` | whether the id is registered |
-| `BUILTIN_OAUTH_PROVIDER_IDS` | the three shipped ids — the only list an **anonymous** refusal names |
+| `BUILTIN_OAUTH_PROVIDER_IDS` | the three shipped ids — the only list an **anonymous** refusal is built from, and it is named in the `auth.oauth.refused` log line, never in the response body |
 | `oauthProviderIds()` | every registered id, live. **NOT** what `defineAuth({ providers })` defaults to — that is `[]`, so an app names what it enabled |
 
 `discoverOAuthProvider` refuses a document with no `jwks_uri`: without a key set there is nothing
 to check an id token's signature against, and the token-endpoint TLS exemption below is a thing a
-caller declares, not one a provider inherits by omission.
+caller declares, not one a provider inherits by omission. It refuses a document whose `issuer` is
+not the one asked for, too (OIDC Discovery §4.3).
 
 **SAML is out of scope and will stay out of scope.** XML-DSig canonicalisation has no Bun native
 and implementing it would mean a real dependency in the primitive vocabulary, which
@@ -284,41 +304,44 @@ rather than never. A seam that returns the stored answer writes nothing.
 
 ## MFA — TOTP and recovery codes
 
-Pure functions over a secret and a clock. This package mints, checks and de-duplicates a code;
-**it persists nothing** — the secret, the recovery-code hashes and the spent steps are the app's
-rows, because `AuthAdapter` has no MFA member and adding one would break every third-party
-adapter.
+TOTP is pure functions over a secret and a clock; what is STORED goes through two writers and one
+reader, `As of 2026-10`: the secret is sealed at rest, and a recovery code is consumed atomically.
 
 ```ts
 import type { Auth } from '@ultimat3/auth';
-import { createTotpReplayGuard, enrolTotp, generateRecoveryCodes, verifyTotp } from '@ultimat3/auth';
-import { systemClock } from '@ultimat3/core';
+import { enrolTotp, generateRecoveryCodes, saveTotpSecret } from '@ultimat3/auth';
 
 declare const auth: Auth;   // the `defineAuth` at the top — `enrolTotp` reads `auth.mfa.issuer`
+declare const userId: string;
 
 const enrolment = enrolTotp(auth, { account: 'ada@example.com' });   // issuer: auth.mfa.issuer
-// enrolment.uri  -> otpauth://…  the QR code
-// enrolment.secret -> base32, store it against the user
-
-const recovery = generateRecoveryCodes();   // { codes, hashes } — show `codes` ONCE, store `hashes`
-const guard = createTotpReplayGuard();
-
-export function secondFactorHolds(userId: string, secret: string, code: string): boolean {
-  const at = systemClock.now();
-  const { ok, step } = verifyTotp({ secret, code, at });
-  if (!ok || step === null || guard.isUsed(userId, step)) return false;
-  guard.remember(userId, step, at);
-  return true;
-}
+// enrolment.uri    -> otpauth://…  the QR code
+await saveTotpSecret(auth, userId, enrolment.secret);                // sealed, onto x_users
+
+const recovery = generateRecoveryCodes();   // { codes, hashes } — show `codes` ONCE
+await auth.adapter.updateUser(userId, { recoveryCodeHashes: recovery.hashes });
 ```
 
+Checking a code at sign-in is `completeMfa` (below) — it opens the secret, meters the guess and
+refuses a spent code; an app does not call `verifyTotp` on a stored secret itself.
+
+**The secret at rest is sealed** under the app's master key (`purpose: 'auth:x_users.mfa_secret'`).
+A TOTP seed is symmetric, so it cannot be a digest — and in the clear, a dump of `x_users` was
+every enrolled user's second factor.
+
+| | |
+|---|---|
+| write | `saveTotpSecret(auth, userId, secret)` — refuses a secret nothing can derive a code from (`X_MFA_SECRET_INVALID`), needs the master key (`X_SEAL_KEY_MISSING`) |
+| read | `openTotpSecret(stored)` — **refuses a value that is not sealed** (`X_MFA_SECRET_UNSEALED`, fix `x auth seal-mfa --json`). There is no plaintext fallback, by decision: a fallback kept "for now" is a plaintext column forever |
+| rows from before sealing | `x auth seal-mfa` once, or `sealMfaSecrets({ adapter })` on an adapter of your own — idempotent, answers `{ sealed, alreadySealed, skipped }`; each write is a compare-and-set (`adapter.replaceMfaSecret`), so a re-enrolment mid-run is `skipped`, never overwritten. `x doctor` reports how many are left |
+
 | Call | Answers |
 |---|---|
 | `enrolTotp(auth, { account, issuer?, secret? })` | `{ secret, uri, digits, periodSeconds }` — `issuer` omitted is `auth.mfa.issuer`, `secret` omitted mints one |
 | `verifyTotp({ secret, code, at, drift?, usedSteps? })` | `{ ok, step }`. `step` is the window the code belonged to, `null` on no match |
 | `createTotpReplayGuard(drift?, maxSubjects?)` | the in-process `{ isUsed, remember, size }`; a fleet passes a Redis-backed pair of the same two methods |
 | `generateRecoveryCodes(count = 10)` | `{ codes, hashes }`. `codes` is shown once and is never re-derivable |
-| `redeemRecoveryCode(code, hashes)` | the **remaining** hashes, or `null`. Persisting that array is what makes a code single-use |
+| `recoveryCodeHash(code)` | what a code is stored and looked up as — dashes, spaces and case removed first. `auth.adapter.consumeRecoveryCode(userId, hash)` removes it in ONE statement and answers whether it was there, so two requests carrying one code cannot both redeem it |
 | `totpStep(at, stepSeconds?)` / `totpCode(secret, step, digits?)` | the RFC 6238 halves, for a test that has to mint a valid code. `totpCode` throws `X_MFA_SECRET_INVALID` on a secret that decodes to zero bytes |
 
 **A secret the decoder cannot read verifies nothing, `As of 2026-08`.** `base32Decode` answers
@@ -360,11 +383,49 @@ at `login()` instead is a lockout — `actorFromUser` degrades only a user who H
 package ships no enrolment route to send the rest to. Gate it in your own sign-in handler —
 `if (user.mfaSecret === null)` send them to `enrolTotp` before you call `createSession`.
 
-**The second leg of login is the app's, `As of 2026-08`.** `login()` and `completeOAuthLogin()`
-throw `X_MFA_REQUIRED` before any session exists; finishing the flow is `verifyTotp` followed by
-`createSession({ mfaSatisfied: true })` in the app's own route. The framework ships no
-`POST /auth/mfa/verify`, deliberately — see [`CLAUDE.md`](CLAUDE.md) for the three things that
-would have to land together, and why fewer is worse than none.
+**The second leg of login is `completeMfa`, `As of 2026-10`.** `login()` and
+`completeOAuthLogin()` throw `X_MFA_REQUIRED` before any session exists, and the error's
+`meta.challenge` is what carries the proven first leg to the second: a value sealed under the
+app's master key (`x secrets init`; `X_SEAL_KEY_MISSING` without one), naming the user, good for
+`MFA_CHALLENGE_TTL_MS` (five minutes) on the server's clock. It is `meta`, never `cause` — the
+problem document publishes `cause` — so the sign-in handler decides how it travels.
+
+```ts
+import { type Auth, completeMfa, login } from '@ultimat3/auth';
+import { isUltimateError } from '@ultimat3/core';
+
+declare const auth: Auth;
+
+export async function signIn(email: string, password: string, ip: string) {
+  try {
+    return { session: await login(auth, { email, password, ip }) };
+  } catch (error) {
+    if (!isUltimateError(error) || error.code !== 'X_MFA_REQUIRED') throw error;
+    return { challenge: String(error.meta?.['challenge']) };   // a cookie, or your own body
+  }
+}
+
+export const secondFactor = (challenge: string, code: string, ip: string) =>
+  completeMfa(auth, challenge, code, { ip });   // what `login()` answers: actor, session, cookie
+```
+
+| `completeMfa` is given | Answer |
+|---|---|
+| a live challenge and the current code, or an unused recovery code | `{ actor, session, token, cookie }`, `mfaSatisfied: true` |
+| a wrong code, or one already spent | `X_UNAUTHENTICATED`; the guess stays counted |
+| a value this app did not seal, an expired one, or one for an account now disabled or un-enrolled | `X_UNAUTHENTICATED`, one refusal for all of them |
+| a guess past `rateLimit.maxAttempts` | `X_ACCOUNT_LOCKED` — the same account, address and tenant buckets a password guess spends |
+
+A code guess is reserved before it is compared, so six digits are worth `maxAttempts` tries per
+window. Repeating the first leg does not buy them back: a proven password with a second factor
+still owed clears nothing — `completeMfa` is what clears the account's window. A spent step is
+refused through `auth.totpReplay` (`defineAuth({ totpReplay })`, in-process by default). No route
+ships.
+
+`code` is either the six digits or a **recovery code**: anything that is not six digits is hashed
+and consumed through the adapter, metered exactly as a wrong digit string is, and gone after one
+use. A stored secret that is not sealed is `X_MFA_SECRET_UNSEALED` (HTTP 500) before any guess is
+counted — the deployment's fault, never the caller's.
 
 ## Email verification and password reset
 
@@ -422,9 +483,9 @@ unauthenticated POST with any token cannot kill the victim's live link.
 | `revokeUserSessions(auth, userId, reason)` | one person, their current session included |
 | `revokeOrgSessions(auth, orgId, reason)` | one tenant, at 03:00, without touching another |
 | `revokeSessionsCreatedBefore(auth, at, reason)` | everything minted under a rotated secret |
-| `disableUser(auth, userId, reason)` | stamps `disabledAt` **and** kills the sessions |
+| `disableUser(auth, userId, reason)` | stamps `disabledAt`, kills the sessions **and** revokes the user's live api keys — `{ user, sessionsRevoked, apiKeysRevoked }`. Re-enabling restores neither |
 | `listOrgUsers(auth, orgId, { role })` | the quarterly access review, as safe summaries |
-| `updatePrivileges(auth, userId, patch, session?)` | the grant, plus the session rotation it requires |
+| `updatePrivileges(auth, userId, patch, session?)` | the grant, plus the session rotation it requires. A `passwordHash` change ends every OTHER session of that user (`sessionsRevoked`) — all of them when no session of theirs was passed, as in a reset |
 
 `reason` is a required argument on every revocation, for the reason `crossTenant()` requires one:
 an incident review asks who killed these sessions and why, and a `delete` with no line answers
@@ -444,7 +505,7 @@ an adapter implementation, not a dependency of this package.
 
 | Driver | Use |
 |---|---|
-| `BuiltinAdapter` | Postgres via `@ultimat3/db`; takes an injected `DbClient` |
+| `BuiltinAdapter` | Postgres via `@ultimat3/db`. `new BuiltinAdapter(client?, clock?)` — the process client and `systemClock` by default; the clock stamps `x_verifications.consumed_at` |
 | `MemoryAdapter` | `x new` before a database exists, and every test in this package. `new MemoryAdapter(clock)` — `systemClock` by default — stamps every instant it writes |
 | your own | implement `AuthAdapter`; DDL in `tables.ts` shows what the columns mean |
 
@@ -454,10 +515,8 @@ would not. Normalisation happens once, above the seam, in `normaliseEmail` (`ema
 lowercase, nothing else. Call it before `findUserByEmail`/`createUser` in any login route of your
 own, and key any bucket of your own with it — `accountKey` does.
 
-The seam's newer members — `findUserByExternalId`, `listUsersByOrg`, `deleteSessionsForUser`,
-`deleteSessionsForOrg`, `deleteSessionsCreatedBefore` — are **optional**, so a 1.2-era adapter
-still satisfies the interface. Calling one an adapter has not implemented is `X_NOT_IMPLEMENTED`
-with the method named, not a silent no-op.
+Every member of the seam is required: an adapter missing one is a compile error, never a runtime
+refusal.
 
 `x_users` gained two columns in 1.3.0 — `scopes text[]` and `external_id text unique` — plus an
 `org_id` index.
@@ -553,7 +612,7 @@ Bun.serve({
 |---|---|---|
 | path | `/auth/oauth/:provider` | `/auth/oauth/:provider/callback` |
 | success | `302` to the provider, `Set-Cookie: __Host-x_oauth_<provider>` | `303` to `successPath`, `Set-Cookie: __Host-x_session` **and** the handshake cleared |
-| failure | the coded JSON body, status per code | the same, handshake cleared either way |
+| failure | coded JSON, status per code: `code` + `title` + `docs`, one fixed `cause`, `fix: x errors explain <CODE> --json` | the same, handshake cleared either way |
 
 A **descriptor**, never a mounted handler — the same category as `mcpHttpRoute()`. `@ultimat3/http`
 is tier 2 like this package, so auth may not import it, and `defineRoute` is tier 4 and describes
@@ -577,8 +636,12 @@ mounting API to call today; do not write one, and do not read this section as pr
 at `GET /auth/oauth/<provider>`; it now quotes `oauthStartPath()`, the same declaration the mount
 reads. A movable base path is that sentence going stale again.
 
-**Failure is JSON, not a redirect carrying `?error=`.** The callback is the one request whose
-failure a developer must read, and there is no `?next=` on the success hop either: an
+`oauthLogin` needs an origin to build the provider's `redirect_uri` from: `baseUrl`, or `APP_URL`.
+With neither, the start leg refuses with `X_ENV_MISSING` rather than trust a request header.
+
+**Failure is JSON, not a redirect carrying `?error=`.** The body is the same for every refusal of
+one code; the authored cause and fix are the `auth.oauth.refused` log line, where only an operator
+reads them. The callback is the one request whose failure a developer must read, and there is no `?next=` on the success hop either: an
 attacker-supplied return target on the endpoint that hands out a session is the classic open
 redirect, and `nextAfterSignIn` in `@ultimat3/http` is the one implementation of that check.
 
@@ -656,12 +719,74 @@ JWT signed with the `.p8` key, which Apple expires every six months.
 looked up by the non-secret id.
 
 ```ts
+import { type Auth, apiKeyActor, issueApiKey, verifyApiKey } from '@ultimat3/auth';
+
+declare const auth: Auth;
+declare const orgId: string;
+
 const { plaintext, record } = issueApiKey({ env: 'prod', scopes: ['post:publish'], orgId });
 await auth.adapter.putApiKey(record);
-const actor = apiKeyActor(await verifyApiKey(auth.adapter, plaintext));  // kind: 'agent'
+export const actor = apiKeyActor(await verifyApiKey(auth.adapter, plaintext));  // kind: 'agent'
+```
+
+`verifyApiKey` answers `{ record, owner }`. A key is its owner's credential, `As of 2026-10`:
+
+| The key | What verification does |
+|---|---|
+| names no `userId` | nothing more — a key no user owns is cut by its scopes and its org alone |
+| names a `userId` | re-reads that user from the store. Missing or disabled is the same `X_API_KEY_INVALID` every other rejection is, on the very next use; `disableUser` also revokes the key outright |
+
+A key's scopes only ever shrink on the way to the actor — never the owning user's roles, never a
+default set:
+
+- `*` and `<resource>:*` are refused at `issueApiKey` (`X_CONFIG_INVALID`), and dropped from a row
+  that already holds one.
+- A key a user owns keeps only the scopes that owner's grants cover. This package can read the
+  row's `permissions` and `scopes` (`directGrants`) and cannot expand a role — that is
+  `@ultimat3/policy`'s — so an app whose users hold roles says what they grant:
+
+```ts
+import { type ApiKeyVerifyStore, apiKeyResolver, directGrants } from '@ultimat3/auth';
+import { expandRoles } from '@ultimat3/policy';
+
+declare const keys: ApiKeyVerifyStore;
+
+export const resolveKey = apiKeyResolver(() => keys, {
+  grantsOf: (owner) => [...directGrants(owner), ...expandRoles(owner.roles)],
+});
 ```
 
-An api key's scopes become **exactly** the agent actor's scopes — never the owning user's roles.
+Without `grantsOf`, a key owned by a user who holds only roles resolves with no scopes at all.
+
+### The resolver a mount takes
+
+`apiKeyResolver(() => store)` is that last line as the `resolveToken` a bearer mount
+(`defineApi({ http: { mounts } })`) and an MCP endpoint (`defineAppMcp`) both take — one resolver
+for both doors.
+
+```ts
+import type { ApiKeyVerifyStore } from '@ultimat3/auth';
+import { apiKeyResolver, BuiltinAdapter } from '@ultimat3/auth';
+
+let keys: ApiKeyVerifyStore | undefined;
+
+/** `resolveToken: resolveKey` — on the mount, and on `defineAppMcp()`. */
+export const resolveKey = apiKeyResolver(() => {
+  keys ??= new BuiltinAdapter();
+  return keys;
+});
+```
+
+| Presented | Answer |
+|---|---|
+| a live key | `{ actor, scopes }` — the agent actor for the key's org, and the scopes that actor carries as a `Set` |
+| malformed, unknown, wrong secret, revoked, expired, or owned by a user who is gone or disabled | `null`, all alike: the mount answers one indistinguishable 401 |
+| a store that FAILS | the throw, untouched — a database that is down is not a wrong key |
+
+The store is a THUNK, read when a token is presented: a mount is declared when its module is
+evaluated, and `new BuiltinAdapter()` takes the process's database client, which boot installs
+later. In a test the store is `new MemoryAdapter()` — every `AuthAdapter` is an
+`ApiKeyVerifyStore` (an `ApiKeyStore` that can also `findUserById`).
 
 ## Errors
 
@@ -670,6 +795,7 @@ An api key's scopes become **exactly** the agent actor's scopes — never the ow
 | `X_UNAUTHENTICATED` | no actor, unknown session, or any failed credential path |
 | `X_SESSION_EXPIRED` | idle or absolute expiry, named in `cause` |
 | `X_MFA_REQUIRED` | password proven, second factor outstanding |
+| `X_MFA_SECRET_UNSEALED` | a stored `mfa_secret` is not sealed; it is refused, never read. `x auth seal-mfa --json` |
 | `X_OAUTH_STATE_INVALID` | state, nonce or PKCE verifier did not match |
 | `X_OAUTH_EXCHANGE_FAILED` | the provider refused the exchange, or returned no usable identity |
 | `X_OAUTH_TOKEN_INVALID` | the id token failed its signature, issuer, audience or expiry check, or no key in the published set matched its `kid` |
@@ -677,10 +803,10 @@ An api key's scopes become **exactly** the agent actor's scopes — never the ow
 | `X_OAUTH_PROVIDER_DUPLICATE` | two `registerOAuthProvider` calls claimed one id — at boot, never at a login |
 | `X_OAUTH_DENIED` | the user pressed Cancel, or the provider declined — `403`, never a `502` |
 | `X_PASSWORD_WEAK` | strength check rejected the password |
-| `X_ACCOUNT_LOCKED` | the per-ip, per-account or per-org bucket is inside its lockout |
-| `X_API_KEY_INVALID` | key unknown, revoked, expired or wrong |
+| `X_ACCOUNT_LOCKED` | the per-ip, per-account or per-org bucket is inside its lockout. The cause names the caller's own address or email, never an org |
+| `X_API_KEY_INVALID` | key unknown, revoked, expired, wrong, or owned by a user who is gone or disabled |
 | `X_ENV_MISSING` | `oauthCredentials()` found no client id or secret for an enabled provider |
-| `X_NOT_IMPLEMENTED` | an `AuthAdapter` has not implemented an optional seam member (`revokeOrgSessions`, `listOrgUsers`, …), or lost a write it accepted — `emailVerifiedNotStored(provider, userId)` when `updateUser` drops the OAuth verified stamp |
+| `X_AUTH_WRITE_FAILED` | an `AuthAdapter` lost a write it accepted — `emailVerifiedNotStored(provider, userId)` when `updateUser` drops the OAuth verified stamp |
 
 ```bash
 bun test packages/auth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,8 +32,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/db": "22.15.0",
-    "@ultimat3/schema": "22.15.0"
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/db": "24.0.0",
+    "@ultimat3/schema": "24.0.0"
   }
 }