@ultimat3/auth 29.4.0 → 30.1.0

package/src/index.ts

@@ -12,6 +12,11 @@ export type {
   AuthUser,
   AuthVerification,
   CreateUserInput,
+  PasskeyCeremony,
+  PasskeyChallengeRecord,
+  PasskeyCredential,
+  PasskeyEvidence,
+  PasskeyStore,
   SessionPatch,
   SessionStore,
   StoredMfaSecret,
@@ -61,6 +66,47 @@ export {
   UserSchema,
   VerificationSchema,
 } from './auth';
+export type { AuthorizationServer } from './authorization-server';
+export { AUTH_CODE_TTL_MS, authorizationServer } from './authorization-server';
+export type {
+  RegisterClientInput,
+  RegisteredClient,
+} from './authorization-server-clients';
+export type {
+  AuthorizationServerOptions,
+  AuthServerEvent,
+  AuthServerLifetimes,
+} from './authorization-server-config';
+export type { PostgresAuthServerStoreOptions } from './authorization-server-postgres';
+export { postgresAuthServerStore } from './authorization-server-postgres';
+export type { ReadRequestResult } from './authorization-server-request';
+export { AUTH_SERVER_METADATA_WELL_KNOWN } from './authorization-server-routes';
+export { AUTH_SERVER_TABLES, SQL_AUTH_SERVER_TABLES } from './authorization-server-schema';
+export type {
+  AuthServerStore,
+  DeviceDecision,
+  RefreshRotation,
+} from './authorization-server-store';
+export { memoryAuthServerStore } from './authorization-server-store';
+export type {
+  AuthCodeRecord,
+  AuthGrantRecord,
+  AuthorizationRequest,
+  AuthServerClient,
+  AuthServerGrant,
+  AuthTokenKind,
+  AuthTokenRecord,
+  ClientAuthMethod,
+  DeviceCodeRecord,
+  DeviceStatus,
+  ResolvedGrant,
+} from './authorization-server-types';
+export { DEVICE_GRANT } from './authorization-server-types';
+export type {
+  AuthServerHttpContext,
+  AuthServerHttpRequest,
+  AuthServerRoute,
+} from './authorization-server-wire';
 export { type PostgresAuthAdapter, postgresAuthAdapter } from './builtin-adapter';
 /** The opaque per-principal id a per-request document hands the page's client store. */
 export type { ClientScopeOptions } from './client-scope';
@@ -91,7 +137,9 @@ export {
   passwordWeak,
   sessionExpired,
   sessionUnknown,
+  signInUnconfigured,
 } from './errors';
+export type { DeviceReading } from './grant-device';
 export { currentActor, requireActor } from './guards';
 export type { IdTokenClaims, VerifyIdTokenInput } from './id-token';
 export {
@@ -113,16 +161,28 @@ export {
   providerJwks,
   verifyJwtSignature,
 } from './jwks';
+export type {
+  JwtBearerCaller,
+  JwtBearerCheck,
+  JwtBearerResolverOptions,
+} from './jwt-bearer-resolver';
+export { jwtBearerResolver } from './jwt-bearer-resolver';
 export type { KdfGate, KdfLimits } from './kdf-gate';
 export {
   boundedKdfGate,
   configureKdfGate,
   kdfGate,
 } from './kdf-gate';
-export type { AuthLimiterFactory } from './limiter-install';
+export type { AuthLimiterFactory, TotpReplayFactory } from './limiter-install';
 // `installedAuthLimiter` is deliberately absent: `defineAuth` is the one reader, and a second
 // caller building limiters out of band would be a second answer to where failures are counted.
-export { configureAuthLimiters, purgeAuthLimits, resetAuthLimiters } from './limiter-install';
+export {
+  configureAuthLimiters,
+  configureTotpReplay,
+  purgeAuthLimits,
+  resetAuthLimiters,
+  resetTotpReplay,
+} from './limiter-install';
 export type { HandleDirectory } from './login-identity';
 export { normaliseHandle } from './login-identity';
 export { type MemoryAuthAdapter, memoryAuthAdapter } from './memory-adapter';
@@ -160,6 +220,11 @@ export {
   MFA_CHALLENGE_TTL_MS,
   mfaChallengeRequired,
 } from './mfa-challenge';
+export type {
+  PostgresTotpReplayGuard,
+  PostgresTotpReplayGuardOptions,
+} from './mfa-replay-postgres';
+export { postgresTotpReplayGuard, SQL_TOTP_REPLAY_TABLE } from './mfa-replay-postgres';
 export type { MfaSecretStore, SealMfaSecretsReport } from './mfa-secret';
 export {
   countUnsealedMfaSecrets,
@@ -178,6 +243,12 @@ export type {
   TokenEndpointAuth,
 } from './oauth';
 export { assertOAuthCallback, beginOAuth, pkcePair } from './oauth';
+export type {
+  OAuthBearerCaller,
+  OAuthBearerResolverOptions,
+  OAuthTokenSource,
+} from './oauth-bearer-resolver';
+export { oauthBearerResolver } from './oauth-bearer-resolver';
 export {
   BUILTIN_OAUTH_PROVIDER_IDS,
   BUILTIN_OAUTH_PROVIDERS,
@@ -246,6 +317,25 @@ export {
 } from './oauth-registry';
 export type { AuthRouteDescriptor, OAuthLoginOptions, OAuthLoginRoutes } from './oauth-route';
 export { OAUTH_ROUTE_STATUS, oauthDenied, oauthLogin } from './oauth-route';
+// Passkeys (WebAuthn): sign-in and digest-bound step-up. The browser half is `@ultimat3/auth/client`.
+export type {
+  PasskeyPolicy,
+  PasskeyPolicyInput,
+  PasskeyRelyingParty,
+} from './passkey-config';
+export { DEFAULT_PASSKEY_CHALLENGE_TTL_MS } from './passkey-config';
+export { verifyPasskeyEvidence } from './passkey-evidence';
+export type { PasskeyLogin } from './passkey-login';
+export { passkeyLogin } from './passkey-login';
+export type { PasskeyStepUp, PasskeyStepUpOptions } from './passkey-step-up';
+export { passkeyStepUp } from './passkey-step-up';
+export type {
+  PasskeyAssertionResponse,
+  PasskeyCreationOptions,
+  PasskeyCredentialDescriptor,
+  PasskeyRegistrationResponse,
+  PasskeyRequestOptions,
+} from './passkey-wire';
 export type {
   PasswordParams,
   PasswordPolicy,
@@ -337,6 +427,12 @@ export {
 /** A sign-out response's headers: the session cookie expired, and `Clear-Site-Data`. */
 export type { SignOutHeadersOptions } from './sign-out';
 export { SIGN_OUT_CLEAR_SITE_DATA, signOutHeaders } from './sign-out';
+export type {
+  AuthSubjectRef,
+  AuthSubjectTarget,
+  AuthSubjectTargetOptions,
+} from './subject-target';
+export { AUTH_SUBJECT_COLUMNS, authSubjectTarget } from './subject-target';
 
 export {
   AUTH_TABLE_NAMES,
@@ -346,24 +442,33 @@ export {
   randomToken,
   sha256Hex,
 } from './tokens';
+export type { VerificationPurposeDef } from './verification-purposes';
+export { verificationPurposeNames } from './verification-purposes';
 export type {
   ConsumeVerificationInput,
+  DefineVerificationPurposeInput,
   IssuedVerification,
   IssueVerificationInput,
   MailSender,
   VerificationPurpose,
+  VerificationPurposeHandle,
   VerificationRuntime,
 } from './verify';
 export {
   consumeVerification,
   DEFAULT_VERIFICATION_TTL_MS,
+  defineVerificationPurpose,
+  emailVerification,
   issueVerification,
+  passwordReset,
   VERIFICATION_PURPOSES,
   VERIFICATION_TEMPLATES,
 } from './verify';
 export type {
   VerifyWorkloadTokenInput,
+  WorkloadCheck,
   WorkloadClaims,
   WorkloadToken,
+  WorkloadTokenCheck,
 } from './workload';
-export { verifyWorkloadToken } from './workload';
+export { checkWorkloadToken, verifyWorkloadToken } from './workload';

package/src/jwks.ts

@@ -10,11 +10,13 @@ import type { Clock, Scheduler } from '@ultimat3/core';
 import {
   generationFence,
   isFixShellSafe,
+  logger,
   renderFixShellArg,
   renderThrowable,
   singleFlight,
   systemClock,
 } from '@ultimat3/core';
+import { outboundResponse } from '@ultimat3/core/outbound';
 import { decodeJwtSegment, isRecord } from './json';
 import type { OAuthProvider } from './oauth';
 import { oauthExchangeFailed, oauthTokenInvalid } from './oauth-errors';
@@ -51,6 +53,16 @@ export type IdTokenKeys = 'token-endpoint-tls' | JwksKeySource;
 /** Short enough that a rotated key set is picked up on its own; a new `kid` refreshes early. */
 export const DEFAULT_JWKS_TTL_MS = 10 * 60 * 1000;
 
+/**
+ * How long past its TTL a key already held still answers while the key set cannot be read. An IdP
+ * outage otherwise ends every login with the verifying key in memory. Past it, the refusal: a key
+ * may have been withdrawn during the outage, and nothing here can tell.
+ */
+export const JWKS_STALE_IF_ERROR_MS = 60 * 60 * 1000;
+
+/** No fetch this soon after a failed one, on either path: an outage costs no request per token. */
+export const JWKS_FAILURE_COOLDOWN_MS = 30 * 1000;
+
 /** One client is one key set, so the flight has exactly one key and its name is never read. */
 const REFRESH_KEY = 'jwks';
 
@@ -110,12 +122,16 @@ const algorithmOf = (jwk: Record<string, unknown>): JwtAlgorithm | null => {
   return null;
 };
 
+/** Where a key published with no `kid` is filed: no name a token could mean starts with NUL. */
+const KID_LESS = '\u0000';
+
 /**
  * Caches by `kid` with a TTL, and refetches once when a token names a `kid` the cache has never
  * seen — which is what makes a key rotation heal itself instead of failing every login until the
  * TTL runs out. One refetch, not one per token: an unknown `kid` an attacker invents must not
  * become an unbounded outbound request per attempt, so the refresh is rate-limited by the same
- * TTL as the ordinary one.
+ * TTL as the ordinary one. A failed fetch is rated too (`JWKS_FAILURE_COOLDOWN_MS`), and leaves a
+ * key already held answering for `JWKS_STALE_IF_ERROR_MS`.
  */
 export function jwksClient(options: JwksClientOptions): JwksKeySource {
   const clock = options.clock ?? systemClock;
@@ -139,6 +155,9 @@ export function jwksClient(options: JwksClientOptions): JwksKeySource {
   // is reset by every fetch, ordinary ones included — so gating the early refresh on it would let
   // an attacker's own refresh authorise the next one.
   let lastMissRefreshMs = Number.NEGATIVE_INFINITY;
+  // The last failed fetch, kept so a caller inside the cooldown gets its refusal without a request.
+  let lastFailure: { readonly atMs: number; readonly error: unknown } | null = null;
+  let staleAnnounced = false;
   // Two refreshes can overlap once the deadline below can evict one, and BOTH end by installing
   // what they read. Without this, the later-settling of the two wins — so a refresh the client
   // already gave up on could drop a pre-rotation key set on top of the live one, and every login
@@ -165,14 +184,27 @@ export function jwksClient(options: JwksClientOptions): JwksKeySource {
 
   const fetchKeys = async (): Promise<Map<string, CryptoKey>> => {
     const issued = fence.bump();
-    const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    const doFetch: OAuthFetch =
+      options.fetch ??
+      ((input, init) => globalThis.fetch(input, { ...init, signal: init.signal ?? null }));
     let response: Response;
     try {
-      response = await doFetch(options.jwksUri, {
-        method: 'GET',
-        headers: { Accept: 'application/json' },
-        signal: AbortSignal.timeout(timeoutMs),
-      });
+      // Through core's `outbound()`: `timeoutMs` bounds the whole call, the ambient request's signal
+      // ends it, a GET's 5xx is retried inside that bound (a POST never is), a 3xx is never followed.
+      response = await outboundResponse(
+        {
+          url: options.jwksUri,
+          vendor: options.provider,
+          dial: 'named',
+          deadlineMs: timeoutMs,
+          // One attempt: this file's own fence and cooldown are its retry discipline (one fetch per
+          // outage), and a login waiting on a key must not wait out a backoff.
+          retry: { attempts: 1, base: 0, max: 0, jitter: 'none' },
+          method: 'GET',
+          headers: { Accept: 'application/json' },
+        },
+        { fetch: doFetch },
+      );
     } catch (error) {
       throw oauthExchangeFailed({
         provider: options.provider,
@@ -199,13 +231,16 @@ export function jwksClient(options: JwksClientOptions): JwksKeySource {
       if (!isRecord(entry)) continue;
       const alg = algorithmOf(entry);
       const kid = entry['kid'];
-      if (alg === null || typeof kid !== 'string' || kid === '') continue;
+      const named = typeof kid === 'string' && kid !== '';
+      // RFC 7517: `kid` is optional. An absent one is filed by position, so two such keys stay two
+      // and `lookup` sees the ambiguity; a present one that is no name is a malformed entry.
+      if (alg === null || (kid !== undefined && !named)) continue;
       // A key the runtime cannot import is skipped rather than fatal: one malformed entry in a
       // published set must not take down every login the other keys would still have verified.
       const key = await crypto.subtle
         .importKey('jwk', entry as JsonWebKey, importParams(alg), false, ['verify'])
         .catch(() => null);
-      if (key !== null) next.set(`${kid}:${alg}`, key);
+      if (key !== null) next.set(`${named ? kid : `${KID_LESS}${next.size}`}:${alg}`, key);
     }
     // A 200 with nothing importable in it is a failed fetch, not a rotation to zero keys. Adopted,
     // it replaced a working cache with an empty one stamped fresh for a whole TTL.
@@ -244,7 +279,9 @@ export function jwksClient(options: JwksClientOptions): JwksKeySource {
     await flight.run(REFRESH_KEY, fetchKeys);
 
   const lookup = (current: Map<string, CryptoKey>, kid: string | null, alg: JwtAlgorithm) => {
-    if (kid !== null) return current.get(`${kid}:${alg}`) ?? null;
+    // A token naming a `kid` needs that key: its text is the caller's, so it never spells a filing.
+    if (kid !== null)
+      return kid.startsWith(KID_LESS) ? null : (current.get(`${kid}:${alg}`) ?? null);
     // No `kid`: unambiguous only when the set holds exactly one key for this algorithm.
     const matches = [...current.entries()].filter(([id]) => id.endsWith(`:${alg}`));
     return matches.length === 1 ? (matches[0]?.[1] ?? null) : null;
@@ -265,10 +302,42 @@ export function jwksClient(options: JwksClientOptions): JwksKeySource {
       // early refresh is rate-limited by the same TTL as the ordinary one — which is what the
       // docstring above always promised. Set BEFORE the await so concurrent callers that pass the
       // gate together still coalesce into the one shared refresh.
-      const earlyRefresh = !known && !stale && nowMs >= lastMissRefreshMs + ttlMs;
+      const cooling = lastFailure !== null && nowMs < lastFailure.atMs + JWKS_FAILURE_COOLDOWN_MS;
+      const earlyRefresh = !known && !stale && !cooling && nowMs >= lastMissRefreshMs + ttlMs;
+      const missGateWas = lastMissRefreshMs;
       if (earlyRefresh) lastMissRefreshMs = nowMs;
-      if (stale || earlyRefresh) current = await load();
+      let failure = cooling ? lastFailure : null;
+      if (!cooling && (stale || earlyRefresh)) {
+        try {
+          current = await load();
+          lastFailure = null;
+        } catch (error) {
+          // Every joiner of one failed fetch lands here holding the same error: one announcement.
+          if (lastFailure?.error !== error) staleAnnounced = false;
+          failure = { atMs: clock.now().getTime(), error };
+          lastFailure = failure;
+          // A fetch that read nothing proved nothing about this `kid`. The cooldown rates failures,
+          // so the gate is given back, or a rotated key misses for a whole TTL after the issuer heals.
+          if (earlyRefresh) lastMissRefreshMs = missGateWas;
+        }
+      }
       const key = lookup(current, kid, alg);
+      if (failure !== null) {
+        // Measured from the set's own age, so a flapping issuer cannot extend the window by failing
+        // again: a key this old is refused however recently the last fetch was tried.
+        const usable =
+          key !== null && (!stale || nowMs < fetchedAtMs + ttlMs + JWKS_STALE_IF_ERROR_MS);
+        if (!usable) throw failure.error;
+        // Once per failed fetch, not per token: an outage at login volume is one line per cooldown.
+        if (stale && !staleAnnounced) {
+          staleAnnounced = true;
+          logger.warn('auth.jwks.stale_served', {
+            provider: options.provider,
+            staleForMs: nowMs - (fetchedAtMs + ttlMs),
+          });
+        }
+        return key;
+      }
       if (key === null) {
         throw oauthTokenInvalid(
           options.provider,

package/src/jwt-bearer-resolver.ts

@@ -0,0 +1,80 @@
+// Single responsibility: an external issuer's bearer JWT → who is calling, in the `resolveToken`
+// shape a bearer mount and an MCP endpoint take. `apiKeyResolver`'s twin for tokens: the checks are
+// `verifyWorkloadToken`'s, and every refusal — a key set that cannot be read included — is `null`
+// plus one log line naming the check, never a claim's value and never the token.
+
+import { type Clock, logger, systemClock } from '@ultimat3/core';
+import type { JwksKeySource } from './jwks';
+import type { PolicyActor } from './policy-bridge';
+import { checkWorkloadToken, type WorkloadCheck, type WorkloadToken } from './workload';
+
+/** Structurally `ApiKeyCaller`: http's `BearerCaller` and mcp's `ResolvedToken`. */
+export interface JwtBearerCaller {
+  readonly actor: PolicyActor;
+  /** The scopes the token carries (`scope` or `scp`). The mount's scope map is cut by these. */
+  readonly scopes: ReadonlySet<string>;
+}
+
+export interface JwtBearerResolverOptions {
+  /**
+   * A THUNK, read when a token arrives: discovery opens no network at import, and a mount is
+   * declared before boot. Hold the client and return it — a new one per call has an empty cache.
+   */
+  readonly keys: () => JwksKeySource | Promise<JwksKeySource>;
+  /** Every issuer accepted. A list, never a wildcard. */
+  readonly issuers: readonly string[];
+  /** This app's own audience. */
+  readonly audience: string;
+  /** A scope the token must carry, when the mount needs one. The name is the app's. */
+  readonly requiredScope?: string | undefined;
+  /** The app's own claim check, after the signature held (`tid`, `azp`, `groups`). */
+  readonly accept?: ((raw: Readonly<Record<string, unknown>>) => boolean) | undefined;
+  /** Builds the actor. Roles and org are the app's decision, never guessed from a claim here. */
+  readonly actorOf: (token: WorkloadToken) => PolicyActor;
+  readonly clock?: Clock | undefined;
+}
+
+/** Every check a refusal can name: the token's own, then the three this resolver adds. */
+export type JwtBearerCheck = WorkloadCheck | 'key-set' | 'scope' | 'accept';
+
+const refuse = (check: JwtBearerCheck): null => {
+  // The check's NAME only: a claim's value is the caller's text, and the token is a credential.
+  logger.warn('auth.jwt_bearer.refused', { check });
+  return null;
+};
+
+/**
+ * `resolveToken: jwtBearerResolver({ keys, issuers, audience, actorOf })` on a bearer mount or
+ * `defineAppMcp()`. A thrown `accept` or `actorOf` is the app's bug and propagates; a key source
+ * that throws or rejects — discovery down, an unknown `kid` — fails closed as `null`.
+ */
+export function jwtBearerResolver(
+  options: JwtBearerResolverOptions,
+): (token: string) => Promise<JwtBearerCaller | null> {
+  return async (token) => {
+    let checked: Awaited<ReturnType<typeof checkWorkloadToken>>;
+    try {
+      checked = await checkWorkloadToken({
+        token,
+        keys: await options.keys(),
+        issuers: options.issuers,
+        audience: options.audience,
+        clock: options.clock ?? systemClock,
+      });
+    } catch {
+      // Deliberately unrendered: the throw may quote the issuer's response, and an unreadable key
+      // set and an unknown `kid` must read the same to whoever is probing.
+      return refuse('key-set');
+    }
+    if (!checked.ok) return refuse(checked.check);
+    const verified = checked.token;
+    if (
+      options.requiredScope !== undefined &&
+      !verified.claims.scopes.includes(options.requiredScope)
+    ) {
+      return refuse('scope');
+    }
+    if (options.accept !== undefined && !options.accept(verified.raw)) return refuse('accept');
+    return { actor: options.actorOf(verified), scopes: new Set(verified.claims.scopes) };
+  };
+}

package/src/limiter-install.ts

@@ -1,5 +1,6 @@
-// Single responsibility: the ONE ambient install point for where failed credential attempts are
-// counted, plus the purge over whatever it built.
+// Single responsibility: the ONE ambient install point for the credential state a fleet has to
+// share — where failed attempts are counted, with the purge over whatever it built, and where spent
+// TOTP steps are kept.
 //
 // WHY a seam and not a `defineAuth` argument: `defineAuth` is the APP's call, and the app is not
 // the thing that knows which database this process opened. A host boot resolves the pool long
@@ -14,6 +15,7 @@
 // make every app that tunes its own numbers fail at boot with `X_AUTH_LIMITER_POLICY_MISMATCH`.
 // The factory is called WITH the resolved policy, so the two halves cannot disagree.
 
+import type { TotpReplayGuard } from './mfa';
 import type { AuthLimiter, AuthRateLimitPolicy } from './rate-limit';
 
 /**
@@ -110,3 +112,30 @@ export async function purgeAuthLimits(): Promise<number> {
   }
   return widest === undefined ? 0 : await widest.purgeExpired();
 }
+
+/** Build the guard an `Auth` keeps its spent TOTP steps in. Called once per `defineAuth`. */
+export type TotpReplayFactory = () => TotpReplayGuard;
+
+let replayFactory: TotpReplayFactory | undefined;
+
+/**
+ * The host's install point for where spent steps are kept, for the limiter's reason: `defineAuth`
+ * is the app's call and the app does not know which database this process opened. Until a boot
+ * filled this, one code signed in once per replica. A second install replaces the first.
+ */
+export function configureTotpReplay(next: TotpReplayFactory): void {
+  replayFactory = next;
+}
+
+/** Back to `memoryTotpReplayGuard`, the per-process default. A host that installs one calls this on stop. */
+export function resetTotpReplay(): void {
+  replayFactory = undefined;
+}
+
+/**
+ * `defineAuth`'s reader, deliberately NOT exported from `src/index.ts` for `installedAuthLimiter`'s
+ * reason. `undefined` means no host installed one, and the caller falls back to memory.
+ */
+export function installedTotpReplay(): TotpReplayGuard | undefined {
+  return replayFactory?.();
+}

package/src/memory-adapter.ts

@@ -11,12 +11,14 @@ import type {
   AuthUser,
   AuthVerification,
   CreateUserInput,
+  PasskeyStore,
   SessionPatch,
   StoredMfaSecret,
   UserPatch,
   UserQuery,
 } from './adapter';
 import { authUniqueViolation } from './errors';
+import { memoryPasskeyStore } from './passkey-memory';
 
 const verificationKey = (purpose: string, identifier: string): string => `${purpose}:${identifier}`;
 
@@ -46,6 +48,22 @@ export class MemoryAuthAdapter implements AuthAdapter {
   readonly #accounts = new Map<string, AuthAccount>();
   readonly #verifications = new Map<string, AuthVerification>();
   readonly #apiKeys = new Map<string, AuthApiKeyRecord>();
+  readonly #passkeys: PasskeyStore = memoryPasskeyStore();
+  // The passkey members are `passkey-memory.ts`'s, bound once: closures over the store, no `this`.
+  readonly putPasskey: PasskeyStore['putPasskey'] = this.#passkeys.putPasskey;
+  readonly findPasskey: PasskeyStore['findPasskey'] = this.#passkeys.findPasskey;
+  readonly listPasskeys: PasskeyStore['listPasskeys'] = this.#passkeys.listPasskeys;
+  readonly advancePasskeyCounter: PasskeyStore['advancePasskeyCounter'] =
+    this.#passkeys.advancePasskeyCounter;
+  readonly deletePasskey: PasskeyStore['deletePasskey'] = this.#passkeys.deletePasskey;
+  readonly putPasskeyChallenge: PasskeyStore['putPasskeyChallenge'] =
+    this.#passkeys.putPasskeyChallenge;
+  readonly takePasskeyChallenge: PasskeyStore['takePasskeyChallenge'] =
+    this.#passkeys.takePasskeyChallenge;
+  readonly putPasskeyEvidence: PasskeyStore['putPasskeyEvidence'] =
+    this.#passkeys.putPasskeyEvidence;
+  readonly listPasskeyEvidence: PasskeyStore['listPasskeyEvidence'] =
+    this.#passkeys.listPasskeyEvidence;
 
   /**
    * The clock every instant this adapter stamps comes from — one argument, because a stamp is a

package/src/mfa-challenge.ts

@@ -90,8 +90,8 @@ const TOTP_SHAPE = new RegExp(`^[0-9]{${TOTP_DIGITS}}$`);
  * The guess is RESERVED before the code is looked at, against the account, the address and the
  * tenant — the buckets a password guess spends — so six digits are worth `maxAttempts` tries per
  * window and no more, and a wrong code is followed by `X_ACCOUNT_LOCKED`. A code is good once:
- * a TOTP step is remembered in `auth.totpReplay`, and a recovery code is consumed by the adapter
- * in one atomic step, so two requests carrying one code cannot both finish.
+ * a TOTP step is claimed in `auth.totpReplay` and a recovery code is consumed by the adapter, each
+ * in one atomic step, so two requests carrying one code cannot both finish, on any replica.
  */
 export async function completeMfa(
   auth: Auth,
@@ -117,12 +117,18 @@ export async function completeMfa(
   if (TOTP_SHAPE.test(presented)) {
     const now = auth.clock.now();
     const verdict = verifyTotp({ secret, code: presented, at: now });
-    // Checked and remembered with no `await` between them: two concurrent completions carrying
-    // one code cannot both find the step unspent.
-    if (!verdict.ok || verdict.step === null || auth.totpReplay.isUsed(user.id, verdict.step)) {
-      throw mfaCodeRejected();
+    // Only a code that verified claims its step, so a wrong guess never writes.
+    if (!verdict.ok || verdict.step === null) throw mfaCodeRejected();
+    let claimed: boolean;
+    try {
+      claimed = await auth.totpReplay.claim(user.id, verdict.step, now);
+    } catch (thrown) {
+      // A store that is down reached no verdict, so the guess is not counted as a wrong one.
+      await attempt.release();
+      throw thrown;
     }
-    auth.totpReplay.remember(user.id, verdict.step, now);
+    // `=== true`: an answer that is anything else is not evidence the step was unspent.
+    if (claimed !== true) throw mfaCodeRejected();
   } else {
     let consumed: boolean;
     try {

package/src/mfa-replay-postgres.ts

@@ -0,0 +1,71 @@
+// The shared replay guard: one Postgres table, so a TOTP code spent on one replica is spent on all
+// of them. A claim is one `insert … on conflict do nothing`, because a read and a write are two
+// round trips and two replicas fit between them; the primary key is what decides the race.
+import type { PgExecutor } from '@ultimat3/core';
+import { TOTP_DRIFT_STEPS, type TotpReplayGuard, totpStep } from './mfa';
+
+/** Applied by the boot, never by an app migration: `SQL_AUTH_LIMIT_TABLES`' rule. */
+export const SQL_TOTP_REPLAY_TABLE = `
+create table if not exists x_totp_steps (
+  subject text        not null,
+  step    bigint      not null,
+  used_at timestamptz not null,
+  primary key (subject, step)
+);
+
+create index if not exists x_totp_steps_step_idx on x_totp_steps (step);
+`;
+
+/** `$1` subject, `$2` step, `$3` the caller's clock. A row back is the first use; none, a replay. */
+export const SQL_TOTP_CLAIM = `
+insert into x_totp_steps (subject, step, used_at)
+values ($1, $2::bigint, $3::timestamptz)
+on conflict (subject, step) do nothing
+returning 1 as claimed
+`;
+
+/** `$1` the lowest step still kept, computed from the CALLER's clock and never `now()`. */
+export const SQL_TOTP_PURGE = `
+with dropped as (
+  delete from x_totp_steps where step < $1::bigint returning 1
+)
+select count(*) as removed from dropped
+`;
+
+/**
+ * A minute past the drift window. `verifyTotp` reads its replica's own clock, so a replica running
+ * behind the sweep's still offers a step the sweep's clock has written off; a row kept a little
+ * longer costs nothing and a row taken early reopens a spent code.
+ */
+const SWEEP_SLACK_STEPS = 2;
+
+export interface PostgresTotpReplayGuardOptions {
+  readonly executor: PgExecutor;
+}
+
+export interface PostgresTotpReplayGuard extends TotpReplayGuard {
+  /**
+   * Drop every step no replica can offer again, and answer how many rows went. The table takes one
+   * row per second factor and does not bound itself; `@ultimat3/cli`'s hourly sweep calls this.
+   */
+  purgeExpired(nowMs: number): Promise<number>;
+}
+
+export function postgresTotpReplayGuard(
+  options: PostgresTotpReplayGuardOptions,
+): PostgresTotpReplayGuard {
+  const exec = options.executor;
+  return {
+    // A rejection from the executor passes through on purpose: `completeMfa` reads it as no verdict.
+    async claim(subject, step, at): Promise<boolean> {
+      const rows = await exec.query(SQL_TOTP_CLAIM, [subject, step, at.toISOString()]);
+      return rows.length > 0;
+    },
+
+    async purgeExpired(nowMs): Promise<number> {
+      const floor = totpStep(new Date(nowMs)) - TOTP_DRIFT_STEPS - SWEEP_SLACK_STEPS;
+      const rows = await exec.query<{ readonly removed: number | string }>(SQL_TOTP_PURGE, [floor]);
+      return Number(rows[0]?.removed ?? 0);
+    },
+  };
+}