@ultimat3/auth 29.3.2 → 30.0.0

package/CLAUDE.md

@@ -21,9 +21,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `idleSlideMs`, `password.minLength`, the two argon2 costs, every `rateLimit` number), and every
   runtime one through `assertFiniteAuthCount` — `jwks.ttlMs`, the three OAuth legs' `timeoutMs`
   (screened OUTSIDE each leg's `try`), the limiter's `maxKeys`, `mfa.drift`,
-  `oauth.handshake.ttlMs`, `session.cookie.maxAgeSeconds`, `kdf.maxConcurrent`/`maxQueued`. A `NaN`
-  makes every comparison false: no expiry, the empty password accepted, a year-old handshake
-  opened. **`mfa.drift` and the KDF gate are the two that HANG** — mutate `verifyTotp` with the
+  `oauth.handshake.ttlMs`, `session.cookie.maxAgeSeconds`, `kdf.maxConcurrent`/`maxQueued`.
+  **`mfa.drift` and the KDF gate are the two that HANG** — mutate `verifyTotp` with the
   `NaN` case, never by deleting the screen (that wedges `mfa.test.ts`).
 - **A number is screened ABOVE the write it feeds.** `issueVerification` screens its TTL before
   `putVerification` (which upserts on `(purpose, identifier)`); `verify.test.ts` asserts no row
@@ -49,7 +48,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   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.
+  compared.
 - **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
@@ -58,9 +57,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 - **`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:
+  and never a second table: only the row the statement locks is re-read after a wait. No row back is never an
+  admission; a live lockout is never rewritten. Full rule: `docs/history/auth.md`. `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:
@@ -83,15 +81,12 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 - **`oauthProviderUnknown(provider, supported)` scopes its list to its reader**: the route passes
   `BUILTIN_OAUTH_PROVIDER_IDS` (an anonymous caller), `providerFor()` passes `oauthProviderIds()`.
 - **`verifyIdToken({ keys })` is required, with no default.** `'token-endpoint-tls'` is the OIDC
-  Core 3.1.3.7 exemption and `exchangeOAuthCode` is its only entitled caller — and since 26.0.0
-  it defaults to the provider's `providerJwks` whenever there is a `jwksUri`, using the exemption
-  only for a provider with none or when the caller names it (`idTokenKeys`). `HS256` and
+  Core 3.1.3.7 exemption and `exchangeOAuthCode` is its only entitled caller; it defaults to
+  `providerJwks` whenever there is a `jwksUri`. `HS256` and
   `alg: none` are refused in `decodeJwtHeader`. It checks `nbf` and `azp` too.
 - **`resolveGrants` is a seam, never a group-to-role table**, called on EVERY login. Absent leaves
-  the row alone. A user created with no roles and no org logs a warning.
-  Its second argument (`OAuthGrantContext`, `oauth-grant-context.ts`, #670) is the token set, the
-  whole verified id-token payload and a LAZY, once-per-login, `sub`-checked `userinfo()` — read
-  through `oauth-profile.ts`'s `userinfoBody`, never a second userinfo reader.
+  the row alone. A user created with no roles and no org logs a warning. Its second argument is
+  `OAuthGrantContext`; never a second userinfo reader. Full rule: `docs/history/auth.md`.
 - **`verifySession` writes at most once per `idleSlideMs`** (default `idleTtlMs / 20`). Never cache
   the USER row — `authenticate` re-reads it every request so a revoked role bites on the next one.
   In `observed`, `null` is an ANSWER (clears the stored value) and `undefined` is silence.
@@ -108,14 +103,8 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `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` (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.
+  `renderFixLiteral`, and in a shell `fix:` through `renderFixShellArg`.** A line that would
+  not run degrades to prose (core's `isFixShellSafe`); `oauth-discovery.ts` still owes it. Full rule: `docs/history/auth.md`.
 - Cookies are read through `@ultimat3/core`'s `readCookie` (`readSessionCookie`, the oauth
   handshake), which never throws on a malformed value (`decodeURIComponent('%')`).
   They are WRITTEN through its `serializeSetCookie`, never a literal (`bun run set-cookie-literals`,
@@ -143,15 +132,14 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `providerDetail(response, 'coded-only')` (that request carries `client_secret`).
 - **`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).
+  recognise (`X_MFA_SECRET_UNSEALED`, fix `x auth seal-mfa --json`). No plaintext fallback, ever. Full rule: `docs/history/auth.md`.
 - **`providerJwks` memoises only the DEFAULT client**; a caller supplying options gets its own.
 - **A JWKS refresh is single-flighted through core's `singleFlight` with
   `deadlineMs = timeoutMs * 2`**; eviction frees the key, never the work, and a `generationFence`
   generation check (read, never `guard`) stops a superseded refresh overwriting the cache.
   `schedule` is injectable.
+- **A failed JWKS refresh is rated and survivable, in `keyFor`, above the transport** (`JWKS_FAILURE_COOLDOWN_MS`,
+  `JWKS_STALE_IF_ERROR_MS`; constants, no option). Full rule: `docs/history/auth.md`.
 - **A success clears the ACCOUNT bucket and nothing else** — clearing the address bucket made the
   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.
@@ -178,6 +166,9 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `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: `MemoryAuthAdapter` IS an `ApiKeyStore`.
+- **`jwtBearerResolver` is its twin for an external JWT**: `checkWorkloadToken`'s checks, then
+  scope, then `accept(raw)`. Every refusal — a throwing key source too — is `null` plus one
+  `auth.jwt_bearer.refused` line naming the check, never a claim. `keys` is a thunk.
 - Rotate the session id on any privilege change (`rotateSession`, called by `updatePrivileges` in
   `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.
@@ -188,26 +179,27 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   (borrowed from http, in `AUTH_BORROWED_ERROR_CODES`). The pool is core's `flightGate`, the
   refusal auth's own through core's `overflow:` seam. `configureKdfGate()` is the ONE install point
   and deliberately not a `defineAuth` key.
-- **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 })`.
+- **MFA's second leg is `completeMfa(auth, challenge, code)`** (`mfa-challenge.ts`). `X_MFA_REQUIRED`'s
+  `meta.challenge` is a `seal()` value, never a bare user id; the code is reserved against the three
+  buckets before it is compared; a recovery code is consumed by one conditional UPDATE. Full rule: `docs/history/auth.md`.
+- **`mfa.required` is the literal `false`, and `defineAuth` refuses a `true`** (`X_CONFIG_INVALID`).
+  `mfa.issuer` is read by `enrolTotp(auth, { account })`.
 - **A TOTP secret that decodes to zero bytes is NO key**: `verifyTotp` returns the generic failure
   (`{ ok: false, step: null }`), `totpCode` and `enrolTotp` throw `X_MFA_SECRET_INVALID`. The secret
   never reaches `cause:`/`fix:`. No length floor beyond one byte.
+- **`TotpReplayGuard` is one atomic `claim(subject, step, at): Promise<boolean>`**; a rejection is
+  no verdict (`attempt.release()`, rethrown). Precedence: `config.totpReplay` →
+  `configureTotpReplay`'s factory → memory. `postgresTotpReplayGuard`: `x_totp_steps`, one
+  `on conflict do nothing`; `purgeExpired(nowMs)` keeps slack past the drift.
 - **`memoryTotpReplayGuard`'s table is bounded and the eviction ORDER is the guarantee**: subjects
   whose steps are all below the drift floor are forgotten first; past `DEFAULT_MAX_TOTP_SUBJECTS`,
   evict by newest spent step ascending, least-recently-seen tie-break. `maxSubjects` is normalised
   first (`boundedSubjects`): anything not a positive finite integer takes the default.
+- **Passkeys are verified by hand** (`passkey-*.ts`, `cbor.ts`, `cose-key.ts`, `webauthn-data.ts`):
+  UV required, origin exact, the key's alg (never the assertion's), counter non-regression by
+  compare-and-set, challenges single-use in `x_passkey_challenges` (never a process map). A step-up
+  challenge is DERIVED (`stepUpChallenge`), never supplied. Browser half: `./client`, two modules
+  (`client-bundle.test.ts`); never import the barrel there. `docs/history/auth.md`.
 - SAML is out of scope permanently (XML-DSig canonicalisation has no Bun native). Put an
   OIDC-speaking bridge in front and register that.
 
@@ -223,36 +215,38 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `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 |
+| `limiter-install.ts` | the host's one install point for that limiter — the factory, what it built, and the purge over it, and the TOTP guard's |
 | `oauth.ts` | `OAuthProvider`, PKCE, `beginOAuth`, the callback gate. No I/O, no env |
 | `oauth-builtins.ts` | the two shipped IdPs (`github`, `google`), as data. Imports only the type, so no cycle |
 | `oauth-registry.ts` | the registry: `registerOAuthProvider`, `providerFor`, `oauthProviderIds` |
 | `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` |
+| `workload.ts` | a workload JWT (K8s SA / SPIFFE / IMDS / RFC 8693) → a `ServiceIdentity`; `checkWorkloadToken`, the verdict form |
+| `jwt-bearer-resolver.ts` | an external bearer JWT → `{ actor, scopes } \| null` |
 | `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-replay-postgres.ts` | the shared replay guard: one table, the claim, the sweep |
 | `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, 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 |
-| `id-token-fixture.ts` | the one string-input JWT builder the OAuth tests share. Off `index.ts` |
-| `auth-fixture.ts` | the KDF parameters, the password and the `AuthError` catcher the three `auth*.test.ts` suites share. Off `index.ts` |
+| `*-fixture.ts` | test-only, off `index.ts`: `id-token-` (the string-input JWT builder), `auth-` (KDF params, password, `AuthError` catcher for `auth*.test.ts`), `oauth-login-` (adapter, clock, profile) |
 | `oauth-profile.ts` | claims or userinfo → one `OAuthProfile`; `userinfoBody`, the one userinfo reader |
 | `oauth-grant-context.ts` | `resolveGrants`' second argument: tokens, every id-token claim, a lazy subject-checked `userinfo()` |
 | `oauth-login.ts` | profile → account link → session. `completeOAuthLogin` is the entry point |
-| `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 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 `flightGate` with auth's own refusal injected |
+| `kdf-gate.ts` | the one bound on concurrent argon2 work: core's `flightGate`, auth's `X_OVERLOADED` |
 | `email.ts` | `normaliseEmail` — the one normalisation an address gets before it is an identity key |
 | `json.ts` | reading untrusted JSON: `isRecord`, and a base64url JWT segment as an object or `null` |
-| `sign-out.ts` | `signOutHeaders({ session? })` — the expired session cookie plus `Clear-Site-Data: "cache", "storage"` (`SIGN_OUT_CLEAR_SITE_DATA`), never `"cookies"`. A PWA's offline cache does not survive a sign-out, by decision (a cached private page IS the previous principal's data); the page boot's rescope wipe is the second line. Secure contexts only |
-| `client-scope.ts` | `clientScopeOf(actor)` — the OPAQUE per-principal id for `<meta name="ultimate-scope">`: keyed SHA-256 (`SESSION_SECRET`) over kind, id and impersonator, 32 hex; `''` for anonymous. Without `SESSION_SECRET`, a random per-process key and one `auth.client_scope.process_key` warning (rescopes, never leaks) |
+| `sign-out.ts` | `signOutHeaders({ session? })` — the expired session cookie plus `Clear-Site-Data: "cache", "storage"` (`SIGN_OUT_CLEAR_SITE_DATA`), never `"cookies"`. Secure contexts only |
+| `subject-target.ts` | `authSubjectTarget({ executor, user })`: the identity tables as a `defineSubject({ targets })` entry, structural (`@ultimat3/jobs` imports nothing from here). Export = `AUTH_SUBJECT_COLUMNS` (never `password_hash`, `mfa_secret`, a recovery digest); erase = api keys, pending verifications, then the user (sessions, accounts cascade). Three idempotent statements, no transaction of its own |
+| `passkey-login.ts` / `passkey-step-up.ts` / `passkey-evidence.ts` | the factories; the offline re-check. `passkey-verify.ts` + `passkey-assertion.ts` are every check; `*-postgres`/`*-memory` the store; `soft-authenticator.ts` (`./soft-authenticator`) the WebCrypto authenticator tests sign with |
+| `client-scope.ts` | `clientScopeOf(actor)`, the OPAQUE id for `<meta name="ultimate-scope">`: keyed SHA-256 (`SESSION_SECRET`, else a per-process key and one warning) over kind, id, impersonator; `''` anonymous |
 
 ```bash
 bun test packages/auth
@@ -262,16 +256,10 @@ bun run --filter @ultimat3/auth typecheck
 Gotchas:
 - `exactOptionalPropertyTypes` — declare optional fields as `x?: T | undefined`.
 - `noUncheckedIndexedAccess` — index a `Record` into a local before narrowing it.
-- `X_NOT_IMPLEMENTED` is core's, `X_FORBIDDEN` is policy's. `errors.ts` registers only the codes
-  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 `MemoryAuthAdapter`; 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
-  same pairing `@ultimat3/http`'s rate-limit store and `@ultimat3/realtime`'s Postgres files
-  use. A limiter whose statements were never executed is a credential control nobody has run.
+- `errors.ts` registers only the codes this package **owns**, unconditionally; borrowed ones
+  (`X_FORBIDDEN`, `X_NOT_IMPLEMENTED`, …) sit untitled in `AUTH_BORROWED_ERROR_CODES`. Never a
+  `hasErrorCode()` guard.
+- Tests run against `MemoryAuthAdapter`; `adapter-parity-identity.test.ts` boots PGlite. The two
+  Postgres guards pair a scripted twin with a `*.live.test.ts` (skips without `TEST_DATABASE_URL`).
 
 Why each rule above is shaped the way it is: [`docs/history/auth.md`](../../docs/history/auth.md).

package/README.md

@@ -4,6 +4,8 @@
 authorizes on a session row, a user row or an api key — http, actions, jobs and MCP all read
 `ctx.actor` and hand it to `@ultimat3/policy`. One authz system, never two.
 
+`bun add @ultimat3/auth` · guide: [Auth](https://github.com/developerz-ai/ultimate/wiki/Auth)
+
 ```ts
 import { defineAuth, login, oauthLogin, postgresAuthAdapter } from '@ultimat3/auth';
 
@@ -108,7 +110,41 @@ const actor = actorFromService(identity);   // kind: 'service', id: the caller's
 
 Signature first, then issuer, audience, `exp` and `nbf`. `scope` (space-delimited) or `scp` (an
 array) become the actor's scopes; a token with neither carries none. There is no trusted-channel
-exemption here — the token arrived in a header.
+exemption here — the token arrived in a header. The `WorkloadToken` also carries `raw`, the whole
+decoded payload, read only after every check held — an issuer's own claim (`tid`, `groups`) is the
+app's to judge. `checkWorkloadToken` is the same checks as a verdict naming the one that refused.
+
+### An external issuer's bearer, as a `resolveToken`
+
+`jwtBearerResolver` is `apiKeyResolver`'s twin for a JWT some other issuer minted — an IdP's token
+an agent presents to the app's MCP endpoint or a bearer mount:
+
+```ts
+import { actorFromService, jwksClient, jwtBearerResolver } from '@ultimat3/auth';
+
+const ISSUER = 'https://login.example.com/tenant-a/v2.0';
+const keys = jwksClient({ provider: 'idp', jwksUri: `${ISSUER}/discovery/v2.0/keys` });
+
+/** `resolveToken: resolveAgent` — on the mount, and on `defineAppMcp()`. */
+export const resolveAgent = jwtBearerResolver({
+  keys: () => keys,
+  issuers: [ISSUER],
+  audience: 'api://ledger',
+  requiredScope: 'ledger.agent',
+  accept: (raw) => raw['tid'] === 'tenant-a',
+  actorOf: (token) => actorFromService(token.identity),
+});
+```
+
+| Presented | Answer |
+|---|---|
+| a token every check accepts | `{ actor: actorOf(token), scopes }` — the token's `scope`/`scp` as a `Set` |
+| bad signature or `alg: none`, wrong issuer or audience, expired, not yet valid, without `requiredScope`, refused by `accept` | `null`, plus one `auth.jwt_bearer.refused` log line naming the check — never a claim's value, never the token |
+| a key set that cannot be read, or an unknown `kid` | `null` (`check: 'key-set'`): fail closed, and the two look the same |
+| an `accept` or `actorOf` that throws | the throw — the app's bug, not a verdict |
+
+`keys` is a THUNK read when a token arrives, so discovery opens no network at import; hold the
+client and return it. The mount answers `null` as `401 X_UNAUTHENTICATED`.
 
 **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
@@ -301,6 +337,11 @@ a `jwksUri` — Google and every discovered provider do; GitHub issues no id tok
 exemption trusts every hop the response crossed (a TLS-inspecting proxy, a bad DNS answer); a
 signature trusts only the provider. A bad signature is `X_OAUTH_TOKEN_INVALID` (400) and no session.
 
+**An IdP outage does not end every login.** A failed refresh leaves a key already held answering for
+one more hour past its TTL (`JWKS_STALE_IF_ERROR_MS`), logged `auth.jwks.stale_served`; past it,
+`X_OAUTH_EXCHANGE_FAILED`. No fetch runs within 30 s of a failed one (`JWKS_FAILURE_COOLDOWN_MS`),
+so a forged `kid` costs no request during an outage. Both are constants, not options.
+
 | Where | Option | Default |
 |---|---|---|
 | `exchangeOAuthCode(handshake, callback, { keys })` | `keys?: IdTokenKeys` | the provider's key set, else `'token-endpoint-tls'` |
@@ -370,7 +411,7 @@ export const { start, callback } = oauthLogin(auth, {
   resolveGrants: async (_profile, context) => {
     const claims = await context.userinfo();
     const apps = Array.isArray(claims['allowed_oauth_apps']) ? claims['allowed_oauth_apps'] : [];
-    return apps.includes('bank-integrations') ? { roles: ['member'] } : { roles: [] };
+    return apps.includes('ledger') ? { roles: ['member'] } : { roles: [] };
   },
 });
 ```
@@ -419,7 +460,10 @@ every enrolled user's second factor.
 |---|---|
 | `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 |
-| `memoryTotpReplayGuard(drift?, maxSubjects?)` | the in-process `{ isUsed, remember, size }`; a fleet passes a Redis-backed pair of the same two methods |
+| `TotpReplayGuard` | one atomic method, `claim(subject, step, at): Promise<boolean>`: `true` the first time, `false` for a replay. A store that cannot answer rejects: a down database is a fault, never a wrong code |
+| `memoryTotpReplayGuard(drift?, maxSubjects?)` | the in-process guard, `{ claim, isUsed, size }`; `isUsed` is for a test. The default only where no host installed one |
+| `postgresTotpReplayGuard({ executor })` | the shared guard: `x_totp_steps` (`SQL_TOTP_REPLAY_TABLE`), one `insert … on conflict do nothing` per claim, `purgeExpired(nowMs)` for the sweep. A framework boot installs it |
+| `configureTotpReplay(() => guard)` / `resetTotpReplay()` | the host's install point, beside `configureAuthLimiters`. Precedence: `defineAuth({ totpReplay })` → the installed factory → memory |
 | `generateRecoveryCodes(count = 10)` | `{ codes, hashes }`. `codes` is shown once and is never re-derivable |
 | `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 |
@@ -499,8 +543,11 @@ export const secondFactor = (challenge: string, code: string, ip: string) =>
 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.
+claimed through `auth.totpReplay`, once the code has verified, so a wrong guess never writes and a
+lost claim is the same refusal. A booted process holds `postgresTotpReplayGuard`, so a code is good
+once across every replica; with no host, the default is one process' memory. A guard that rejects is
+a fault: it propagates, and the guess is not counted. `defineAuth` refuses a `totpReplay` with no
+`claim` (`X_CONFIG_INVALID`). 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
@@ -543,17 +590,91 @@ const verification = await consumeVerification(runtime, {
 
 | Name | Is |
 |---|---|
-| `VERIFICATION_PURPOSES` | `['email-verify', 'password-reset']` — the whole set, and `VerificationPurpose` is derived from it |
+| `VERIFICATION_PURPOSES` | `['email-verify', 'password-reset']` — the two built in. `VerificationPurpose` is `string` (`As of 2026-11`): any declared name |
+| `defineVerificationPurpose({ name, template, ttlMs, identifier? })` | `{ name, issue, consume }` on the same code path — an invite, an email change, an account deletion. Twice or with no template: `X_VERIFICATION_PURPOSE_INVALID`. `emailVerification` and `passwordReset` are the built-in instances |
 | `VERIFICATION_TEMPLATES` | purpose → **catalog key** (`auth.email-verify`, `auth.password-reset`), never copy: the body lives in the app's i18n catalog |
 | `DEFAULT_VERIFICATION_TTL_MS` | 24 h for `email-verify`, 1 h for `password-reset` — a reset link is a password |
 | `MailSender` | the injected port: `send(template, to, data, locale)`. `@ultimat3/mail` is tier 4 and this package is tier 2, so the app wires it |
 | `issueVerification(runtime, input)` | `{ token, expiresAt }`. The token comes back for a test or a CLI; production only ever mails it |
-| `consumeVerification(runtime, input)` | the `AuthVerification` row, or `X_UNAUTHENTICATED`. Unknown, spent, expired and mismatched are one answer |
+| `consumeVerification(runtime, input)` | the `AuthVerification` row, or `X_UNAUTHENTICATED`. Unknown, spent, expired and mismatched are one answer. An undeclared purpose on either door is `X_VERIFICATION_PURPOSE_UNKNOWN` |
 
 One live token per `(purpose, identifier)`. A wrong guess destroys nothing: the store's
 `takeVerification(purpose, identifier, tokenHash)` matches before it consumes, so an
 unauthenticated POST with any token cannot kill the victim's live link.
 
+## Passkeys — WebAuthn sign-in and digest-bound step-up
+
+`As of 2026-11`. Verified by hand on Bun's WebCrypto — CBOR, COSE (ES256, RS256) and DER parsed in
+this package, no WebAuthn dependency. Declared once: `defineAuth({ passkeys: { rpId, origins } })`
+(`X_CONFIG_INVALID` at definition for an rp id that is not a bare host, or an origin not on it).
+
+```ts
+import { defineAuth, memoryAuthAdapter, passkeyLogin, passkeyStepUp } from '@ultimat3/auth';
+import { newPasskey, getPasskey } from '@ultimat3/auth/client';
+
+const auth = defineAuth({
+  adapter: memoryAuthAdapter(),
+  passkeys: { rpId: 'localhost', origins: ['http://localhost:3000'] },
+});
+const passkeys = passkeyLogin(auth);
+declare const userId: string;
+
+// Each server call sits in one of the app's own actions; its options travel to the browser as
+// JSON, where the browser half (`@ultimat3/auth/client`, in an island) answers them.
+const created = await newPasskey(await passkeys.registerOptions({ userId }));
+if (created.status === 'ok') await passkeys.register({ userId, response: created.response });
+const asserted = await getPasskey(await passkeys.loginOptions());
+if (asserted.status === 'ok') {
+  const { actor, cookie } = await passkeys.login({ response: asserted.response });
+}
+
+// Step-up: the WebAuthn challenge is derived from a nonce, the user and a digest the SERVER
+// computes from the action's input — a caller can only present what was asked for.
+const erase = passkeyStepUp<{ readonly memberId: string }>(auth, {
+  ttlMs: 60_000,
+  digest: ({ input }) => `erase-member:v1:${input.memberId}`,
+});
+```
+
+| Export | What |
+|---|---|
+| `passkeyLogin(auth)` | `{ registerOptions({ userId }), register({ userId, response }), loginOptions(), login({ response, ip?, userAgent? }) }` — `login` answers `login()`'s `LoginResult`, MFA-satisfied |
+| `passkeyStepUp(auth, { digest, ttlMs? })` | `{ options({ userId, input }), verify({ userId, input, response }) }`; `verify` answers the stored `PasskeyEvidence` or throws `X_PASSKEY_STEP_UP_REQUIRED` (no proof, a proof for other bytes, no passkey registered) |
+| `verifyPasskeyEvidence(evidence, { rpId, origins })` | `true` only when the row is a user-verified signature, by its own key, over the challenge its nonce, digest and user derive — no adapter, no clock: a separate process re-checks it |
+| `@ultimat3/auth/client` | `newPasskey`, `getPasskey`, `passkeysSupported`: outcomes `ok` / `cancelled` / `unsupported` / `failed`, never a throw. Two modules, ~2.3 kB minified (`client-bundle.test.ts`) |
+| testing a ceremony | `softAuthenticator({ origin })` from `@ultimat3/auth/soft-authenticator`: real WebCrypto keys answering `create` / `get` — this package's own suites and an app's share the one implementation and the one path |
+| `PasskeyStore` | the nine `AuthAdapter` members over `x_passkeys`, `x_passkey_challenges` (sha256 of the challenge, TTL, taken by `DELETE … RETURNING`) and `x_passkey_evidence`; both adapters, one suite (`passkey-store.test.ts`, PGlite) |
+
+Every ceremony checks `clientDataJSON`'s type, the origin exactly, `rpIdHash`, UP **and** UV, the
+signature under the stored key's algorithm, and a counter that must move forward unless both are
+zero. Registration asks `attestation: 'none'` and trusts no statement. Which check failed is the
+`auth.passkey.refused` log line; the code is `X_PASSKEY_INVALID`, `X_PASSKEY_CHALLENGE_EXPIRED`
+(unknown, spent or late — one answer) or `X_PASSKEY_STEP_UP_REQUIRED`.
+
+## Authorization server
+
+`authorizationServer({ issuer, store, consentPath, lifetimes, scopes, … })` (`As of 2026-11`) — an
+OAuth 2.1 server: authorization code + PKCE (S256 only), refresh rotation with replay revocation,
+`client_credentials`, the device grant, RFC 7009/7662/7591/8414/8707/9207. `routes` go in
+`runtime.routes`; the consent and device pages are the app's (`readRequest`/`approve`/`deny`,
+`readDevice`/`approveDevice`/`denyDevice`). `oauthBearerResolver(server, { actor, resource? })` is
+the `resolveToken`. Stores: `memoryAuthServerStore()`, `postgresAuthServerStore({ executor })`
+over `SQL_AUTH_SERVER_TABLES`, which the boot applies. Full table and the rule each test holds:
+[wiki Auth](https://github.com/developerz-ai/ultimate/wiki/Auth#authorization-server).
+
+| File | Job |
+|---|---|
+| `authorization-server.ts` | the factory and the consent calls |
+| `authorization-server-config.ts` | options, screened once (`X_AUTH_SERVER_INVALID`) |
+| `authorization-server-request.ts` | screening an authorize request — pure |
+| `authorization-server-clients.ts` · `-register.ts` | metadata-document and registered clients, secrets · RFC 7591 |
+| `authorization-server-tokens.ts` | opaque hashed tokens, PKCE, `resolve` |
+| `grant-authorization-code.ts` · `grant-client-credentials.ts` · `grant-device.ts` | the grants |
+| `token-endpoints.ts` | revocation, introspection |
+| `authorization-server-routes.ts` · `-wire.ts` | the routes · the structural `Route` shape, forms, client auth, RFC 6749 JSON |
+| `authorization-server-store.ts` · `-postgres*.ts` · `-schema.ts` | the contract + memory · Postgres · DDL |
+| `oauth-bearer-resolver.ts` | grant → `{ actor, scopes }`, per call |
+
 ## Revocation, offboarding and access review
 
 | Call | Blast radius |
@@ -895,10 +1016,20 @@ export const resolveKey = apiKeyResolver(() => {
 | 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 `postgresAuthAdapter()` takes the process's database client, which boot installs
-later. In a test the store is `memoryAuthAdapter()` — every `AuthAdapter` is an
+evaluated, and which store serves (memory or Postgres) is often decided at boot.
+`postgresAuthAdapter()` with no client reads the ambient `db()` on every call, so the instance can
+be built before boot installs the client, and joins an open `withTransaction`. In a test the store is `memoryAuthAdapter()` — every `AuthAdapter` is an
 `ApiKeyVerifyStore` (an `ApiKeyStore` that can also `findUserById`).
 
+## A person's identity, for a subject export or erase
+
+`authSubjectTarget({ executor, user })` is the identity tables as a `defineSubject({ targets })`
+entry (`@ultimat3/jobs`). `user(subject)` names the `x_users.id` the subject is
+(`({ row }) => String(row.userId)`), or `undefined` for none. The export carries the `x_users` row
+(`AUTH_SUBJECT_COLUMNS`) — never `password_hash`, `mfa_secret` or a recovery digest; the erase
+deletes the user (sessions and accounts cascade), their API keys and pending verifications. A
+user in several orgs is erased from all of them: list it `{ target, retain }` when that is wrong.
+
 ## Errors
 
 | Code | When |
@@ -918,6 +1049,10 @@ later. In a test the store is `memoryAuthAdapter()` — every `AuthAdapter` is a
 | `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_AUTH_WRITE_FAILED` | an `AuthAdapter` lost a write it accepted — `emailVerifiedNotStored(provider, userId)` when `updateUser` drops the OAuth verified stamp |
+| `X_PASSKEY_INVALID` | a passkey response failed its signature, origin, rp id, UP/UV flag, owner or counter check |
+| `X_PASSKEY_CHALLENGE_EXPIRED` | a passkey ceremony named a challenge that is unknown, already used or past its TTL |
+| `X_PASSKEY_STEP_UP_REQUIRED` | a step-up `verify` with no proof, a proof for other bytes, or a user with no passkey |
+| `X_AUTH_SIGN_IN_UNCONFIGURED` | `signInUnconfigured(role, missing)`, thrown by the boot guard `x g sign-in` writes into the app: a `web` or `sync` role outside development and test with sign-in keys unset. Off the socket — a boot refusal, never a response |
 
 ```bash
 bun test packages/auth
@@ -932,3 +1067,21 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | Class | Code | Declared in |
 |---|---|---|
 | `AuthError` | any `AuthErrorCode` — `AUTH_ERROR_CODES` | `src/errors.ts` |
+
+## Supporting exports
+
+`As of 2026-11-02`.
+
+| Name | What |
+|---|---|
+| `JwtBearerCaller` | what `jwtBearerResolver` answers: `{ actor, scopes }`, structurally `ApiKeyCaller` |
+| `JwtBearerResolverOptions` | what `jwtBearerResolver` takes |
+| `JwtBearerCheck` | the check a refusal's log line names: a `WorkloadCheck`, or `key-set`, `scope`, `accept` |
+| `WorkloadCheck` · `WorkloadTokenCheck` | `checkWorkloadToken`'s verdict: the token, or the check that refused it |
+| `PostgresTotpReplayGuard` | the `TotpReplayGuard` `postgresTotpReplayGuard` returns |
+| `PostgresTotpReplayGuardOptions` | what `postgresTotpReplayGuard` takes |
+| `TotpReplayFactory` | `() => TotpReplayGuard`: what `configureTotpReplay` takes |
+| `PasskeyPolicy` · `PasskeyPolicyInput` · `PasskeyRelyingParty` · `DEFAULT_PASSKEY_CHALLENGE_TTL_MS` | the `passkeys` block, resolved and as written; the `{ rpId, origins }` a verifier needs |
+| `PasskeyCredential` · `PasskeyChallengeRecord` · `PasskeyEvidence` · `PasskeyCeremony` · `PasskeyStore` | the passkey rows and the adapter slice that stores them |
+| `PasskeyCreationOptions` · `PasskeyRequestOptions` · `PasskeyRegistrationResponse` · `PasskeyAssertionResponse` · `PasskeyCredentialDescriptor` | the JSON wire of a ceremony (WebAuthn L3's `*JSON` dictionaries) |
+| `PasskeyLogin` · `PasskeyStepUp` · `PasskeyStepUpOptions` | what the two factories answer and take |

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@ultimat3/auth",
-  "version": "29.3.2",
+  "version": "30.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "auth",
+    "sessions",
+    "oauth",
+    "mfa",
+    "api-keys",
+    "passkeys",
+    "webauthn"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Auth",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -14,7 +27,9 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts",
+    "./soft-authenticator": "./src/soft-authenticator.ts"
   },
   "files": [
     "src",
@@ -32,8 +47,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.2",
-    "@ultimat3/db": "29.3.2",
-    "@ultimat3/schema": "29.3.2"
+    "@ultimat3/core": "30.0.0",
+    "@ultimat3/db": "30.0.0",
+    "@ultimat3/schema": "30.0.0"
   }
 }

package/src/adapter.ts

@@ -178,7 +178,7 @@ export interface AccountStore {
 
 export interface AuthVerification {
   readonly id: string;
-  /** `email-verify` | `password-reset` — see `verify.ts`. */
+  /** A declared purpose's name — `email-verify`, `password-reset` or any `defineVerificationPurpose`. */
   readonly purpose: string;
   /** The email address the token was issued for. */
   readonly identifier: string;
@@ -230,6 +230,91 @@ export interface ApiKeyStore {
   revokeApiKey(id: string, at: Date): Promise<boolean>;
 }
 
+/** Which ceremony a stored challenge was issued for; a challenge redeems only for its own. */
+export type PasskeyCeremony = 'register' | 'login' | 'step-up';
+
+/**
+ * One registered passkey. Every byte field is base64url TEXT, so both adapters store and compare
+ * the same string and a row is readable in a SQL console.
+ */
+export interface PasskeyCredential {
+  /** The credential id the authenticator minted — globally unique, the lookup key. */
+  readonly id: string;
+  readonly userId: string;
+  /** The COSE_Key exactly as registered; `importCoseKey` turns it back into a verifying key. */
+  readonly publicKey: string;
+  /** COSE algorithm: `-7` (ES256) or `-257` (RS256). */
+  readonly algorithm: number;
+  /** The last signature counter seen. `0` forever for an authenticator that keeps none. */
+  readonly signCount: number;
+  readonly transports: readonly string[];
+  readonly createdAt: Date;
+  readonly lastUsedAt: Date | null;
+}
+
+/** An issued, not yet redeemed ceremony challenge. Never the challenge itself: its digest. */
+export interface PasskeyChallengeRecord {
+  /** `sha256Hex` of the base64url challenge — what `clientDataJSON` echoes, hashed. */
+  readonly id: string;
+  readonly ceremony: PasskeyCeremony;
+  /** The user it was issued to; `null` for a usernameless sign-in. */
+  readonly userId: string | null;
+  /** Step-up only: the server digest and the nonce the challenge was derived from, base64url. */
+  readonly digest: string | null;
+  readonly nonce: string | null;
+  readonly expiresAt: Date;
+  readonly createdAt: Date;
+}
+
+/**
+ * A verified step-up assertion, kept whole: everything `verifyPasskeyEvidence` needs to check it
+ * again later, in another process, with no other row — the key included, so deleting the passkey
+ * does not un-prove what it approved.
+ */
+export interface PasskeyEvidence {
+  readonly id: string;
+  readonly userId: string;
+  readonly credentialId: string;
+  /** The bytes the person approved, base64url. */
+  readonly digest: string;
+  readonly nonce: string;
+  readonly authenticatorData: string;
+  readonly clientDataJSON: string;
+  readonly signature: string;
+  readonly publicKey: string;
+  readonly algorithm: number;
+  readonly createdAt: Date;
+}
+
+export interface PasskeyStore {
+  /** A credential id already stored — any user's — is `X_AUTH_WRITE_FAILED` (§7.1 step 22). */
+  putPasskey(credential: PasskeyCredential): Promise<PasskeyCredential>;
+  findPasskey(id: string): Promise<PasskeyCredential | null>;
+  /** Oldest first. */
+  listPasskeys(userId: string): Promise<readonly PasskeyCredential[]>;
+  /**
+   * Compare-and-set on the counter: write `next` (and `at` as last use) only while the row still
+   * holds `expected`, in ONE atomic step. Two assertions racing on one counter value must not
+   * both advance it — that is the cloned-authenticator signal.
+   */
+  advancePasskeyCounter(id: string, expected: number, next: number, at: Date): Promise<boolean>;
+  /** Scoped to the owner: one user cannot delete another's passkey by naming its id. */
+  deletePasskey(userId: string, id: string): Promise<boolean>;
+  /** Also drops every challenge that expired before `record.createdAt`, so the table stays bounded. */
+  putPasskeyChallenge(record: PasskeyChallengeRecord): Promise<void>;
+  /**
+   * Read AND delete in one atomic step, only for its own ceremony: two concurrent redemptions of
+   * one challenge must not both find it. Expiry is the caller's to judge, on its clock.
+   */
+  takePasskeyChallenge(
+    id: string,
+    ceremony: PasskeyCeremony,
+  ): Promise<PasskeyChallengeRecord | null>;
+  putPasskeyEvidence(evidence: PasskeyEvidence): Promise<void>;
+  /** Every stored approval of one digest, oldest first. */
+  listPasskeyEvidence(digest: string): Promise<readonly PasskeyEvidence[]>;
+}
+
 /**
  * The full seam. One blessed implementation ships (`PostgresAuthAdapter`); Better Auth, or any
  * other identity backend, binds by implementing this and nothing else changes upstream.
@@ -239,7 +324,8 @@ export interface AuthAdapter
     SessionStore,
     AccountStore,
     VerificationStore,
-    ApiKeyStore {
+    ApiKeyStore,
+    PasskeyStore {
   /** Reported by `Auth.adapter.name` so the driver in use is never a guess. */
   readonly name: string;
   /**