@ultimat3/auth 29.4.0 → 30.0.0

package/src/passkey-config.ts

@@ -0,0 +1,92 @@
+// Single responsibility: `defineAuth({ passkeys })` — the relying party every ceremony verifies
+// against, refused where it is written. An rp id no origin sits under, or an origin that is not
+// one, would otherwise surface as every passkey in production failing `X_PASSKEY_INVALID`.
+
+import type { Auth } from './auth';
+import { passkeyConfigInvalid, passkeysUndeclared } from './passkey-errors';
+import { assertFiniteAuthCount } from './policy-numbers';
+
+/** Five minutes: long enough for a person to find their phone, short enough to be single-use. */
+export const DEFAULT_PASSKEY_CHALLENGE_TTL_MS = 5 * 60_000;
+
+export interface PasskeyPolicyInput {
+  /** The bare host the credentials are scoped to — `example.com`, never a URL. */
+  readonly rpId: string;
+  /** Every exact origin a ceremony may arrive from. Each must be on `rpId` or a subdomain of it. */
+  readonly origins: readonly string[];
+  /** Shown by the authenticator at registration. Defaults to `rpId`. */
+  readonly rpName?: string | undefined;
+  /** How long issued options stay redeemable. Defaults to `DEFAULT_PASSKEY_CHALLENGE_TTL_MS`. */
+  readonly challengeTtlMs?: number | undefined;
+}
+
+/** The resolved block, read by `passkeyLogin`, `passkeyStepUp` and `verifyPasskeyEvidence`. */
+export interface PasskeyPolicy {
+  readonly rpId: string;
+  readonly origins: readonly string[];
+  readonly rpName: string;
+  readonly challengeTtlMs: number;
+}
+
+/** What a signature is checked against — all a verifier in another process needs. */
+export type PasskeyRelyingParty = Pick<PasskeyPolicy, 'rpId' | 'origins'>;
+
+/** A DNS name: labels of letters, digits and inner hyphens. An IP address is not an rp id (§5.1.4). */
+const HOST =
+  /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+const IPV4 = /^\d+(?:\.\d+){3}$/;
+
+export function resolvePasskeyPolicy(input: PasskeyPolicyInput): PasskeyPolicy {
+  const declared: { readonly rpId?: unknown; readonly origins?: unknown } = input;
+  const { rpId, origins } = declared;
+  if (typeof rpId !== 'string' || !HOST.test(rpId) || IPV4.test(rpId)) {
+    throw passkeyConfigInvalid('rpId', rpId, 'it is not a bare lowercase host name');
+  }
+  if (!Array.isArray(origins) || origins.length === 0) {
+    throw passkeyConfigInvalid('origins', origins, 'it must list at least one origin');
+  }
+  const checked = origins.map((origin: unknown) => checkOrigin(rpId, origin));
+  const ttl = assertFiniteAuthCount(
+    'passkeys.challengeTtlMs',
+    input.challengeTtlMs ?? DEFAULT_PASSKEY_CHALLENGE_TTL_MS,
+    'an issued passkey challenge would never expire',
+    1,
+  );
+  return Object.freeze({
+    rpId,
+    origins: Object.freeze(checked),
+    rpName: input.rpName ?? rpId,
+    challengeTtlMs: ttl,
+  });
+}
+
+/**
+ * Exactly an origin (`URL.origin` round-trips it), on the rp id or under it, and https — except
+ * `http://localhost`, the one insecure origin browsers run WebAuthn on.
+ */
+function checkOrigin(rpId: string, origin: unknown): string {
+  let url: URL | null = null;
+  try {
+    url = typeof origin === 'string' ? new URL(origin) : null;
+  } catch {
+    url = null;
+  }
+  if (url === null || url.origin !== origin) {
+    throw passkeyConfigInvalid('origins', origin, 'it is not an origin (scheme://host[:port])');
+  }
+  const secure =
+    url.protocol === 'https:' || (url.protocol === 'http:' && url.hostname === 'localhost');
+  if (!secure) {
+    throw passkeyConfigInvalid('origins', origin, 'only https, or http://localhost, runs WebAuthn');
+  }
+  if (url.hostname !== rpId && !url.hostname.endsWith(`.${rpId}`)) {
+    throw passkeyConfigInvalid('origins', origin, `its host is not ${rpId} or a subdomain of it`);
+  }
+  return origin;
+}
+
+/** The resolved block of an `Auth`, or the refusal naming where to declare it. */
+export function passkeyPolicyOf(auth: Auth, factory: string): PasskeyPolicy {
+  if (auth.passkeys === undefined) throw passkeysUndeclared(factory);
+  return auth.passkeys;
+}

package/src/passkey-errors.ts

@@ -0,0 +1,89 @@
+// Single responsibility: the passkey refusals. Three codes, one each for the three things a caller
+// does differently — retry the ceremony (`X_PASSKEY_INVALID`), fetch fresh options
+// (`X_PASSKEY_CHALLENGE_EXPIRED`), or go and get a proof at all (`X_PASSKEY_STEP_UP_REQUIRED`).
+// WHICH check failed is never in `cause:` — it is a log line's, the way `loginFailed()` is.
+
+import { logger, renderCauseValue, renderFixLiteral } from '@ultimat3/core';
+import { AuthError } from './errors';
+
+/** Forged, tampered, wrong origin or rp id, no user verification, a counter that went back. */
+export const passkeyInvalid = (ceremony: 'register' | 'login' | 'step-up'): AuthError =>
+  new AuthError({
+    code: 'X_PASSKEY_INVALID',
+    cause: `the passkey ${ceremony} response did not pass verification`,
+    fix:
+      ceremony === 'register'
+        ? 'x errors explain X_PASSKEY_INVALID --json, then run registration again: newPasskey(await passkeys.registerOptions({ userId }))'
+        : 'x errors explain X_PASSKEY_INVALID --json, then sign in again: getPasskey(await passkeys.loginOptions())',
+    callerFix: 'start the passkey ceremony again from fresh options',
+    meta: { ceremony },
+  });
+
+/** The refusal, with the check that failed in a log line — the only place it is ever named. */
+export const refusePasskey = (
+  ceremony: 'register' | 'login' | 'step-up',
+  check: string,
+): AuthError => {
+  logger.info('auth.passkey.refused', { ceremony, check });
+  return passkeyInvalid(ceremony);
+};
+
+/** Unknown, already consumed, or past its TTL — replay and slowness answer the same. */
+export const passkeyChallengeExpired = (ceremony: 'register' | 'login' | 'step-up'): AuthError =>
+  new AuthError({
+    code: 'X_PASSKEY_CHALLENGE_EXPIRED',
+    cause: `the passkey ${ceremony} challenge is unknown, already used or past its ttl`,
+    fix: 'x errors explain X_PASSKEY_CHALLENGE_EXPIRED --json, then fetch fresh options and run the ceremony once — every challenge is single-use',
+    callerFix: 'fetch fresh options and run the passkey ceremony once',
+    meta: { ceremony },
+  });
+
+export type StepUpMissing = 'no-proof' | 'other-digest' | 'no-passkey';
+
+const STEP_UP_CAUSES: ReadonlyMap<StepUpMissing, string> = new Map([
+  ['no-proof', 'the call carried no passkey assertion'],
+  ['other-digest', 'the passkey assertion approved other bytes than the ones this call acts on'],
+  ['no-passkey', 'this user has registered no passkey, so no step-up proof can be made'],
+]);
+
+export const passkeyStepUpRequired = (missing: StepUpMissing): AuthError =>
+  new AuthError({
+    code: 'X_PASSKEY_STEP_UP_REQUIRED',
+    cause: STEP_UP_CAUSES.get(missing) ?? 'no fresh passkey proof',
+    fix:
+      missing === 'no-passkey'
+        ? 'x errors explain X_PASSKEY_STEP_UP_REQUIRED --json, then register one: newPasskey(await passkeys.registerOptions({ userId }))'
+        : 'x errors explain X_PASSKEY_STEP_UP_REQUIRED --json, then call stepUp.options({ userId, input }), run getPasskey(options) in the browser and resend the call with its response',
+    callerFix: 'approve this action with your passkey, then send it again',
+    meta: { missing },
+  });
+
+/** `defineAuth({ passkeys })` with a value the ceremonies cannot run on. */
+export const passkeyConfigInvalid = (field: string, value: unknown, reason: string): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause: `defineAuth({ passkeys: { ${field}: ${renderCauseValue(value)} } }) is refused: ${reason}`,
+    fix: `defineAuth({ adapter, passkeys: { rpId: 'example.com', origins: ['https://example.com'] } }) — the rp id is the bare host every origin is on, never ${renderFixLiteral(value, 'that value')}`,
+    meta: { option: `passkeys.${field}` },
+  });
+
+/** `passkeyLogin(auth)` / `passkeyStepUp(auth)` on an `Auth` that declared no `passkeys`. */
+export const passkeysUndeclared = (factory: string): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause: `${factory}(auth) was called on an Auth with no passkeys block, so there is no rp id or origin to verify against`,
+    fix: "defineAuth({ adapter, passkeys: { rpId: 'example.com', origins: ['https://example.com'] } })   // in the module that builds this Auth",
+    meta: { factory },
+  });
+
+/** A step-up `digest` callback that answered nothing, or a whole payload rather than a digest. */
+export const stepUpDigestInvalid = (length: number): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause: `passkeyStepUp's digest callback answered ${length} bytes; a digest is 1 to ${MAX_STEP_UP_DIGEST_BYTES}`,
+    fix: 'passkeyStepUp(auth, { digest: ({ input }) => sha256Hex(JSON.stringify(input)) })   // hash what the person approves; never return the payload itself',
+    meta: { length },
+  });
+
+/** A SHA-512 in hex is 128 bytes; this leaves room for a versioned, prefixed one. */
+export const MAX_STEP_UP_DIGEST_BYTES = 1024;

package/src/passkey-evidence.ts

@@ -0,0 +1,74 @@
+// Single responsibility: what a step-up proof IS, checkable by anyone holding the row — the
+// challenge derivation (`stepUpChallenge`) and `verifyPasskeyEvidence`, which re-runs every
+// signature check offline: no adapter, no clock, no session. An auditor's process, a week later,
+// needs the evidence row and the relying party, nothing else.
+
+import { timingSafeEqual } from '@ultimat3/core';
+import type { PasskeyEvidence } from './adapter';
+import { base64Url, canonicalBase64UrlBytes } from './base64url';
+import type { PasskeyRelyingParty } from './passkey-config';
+import { readEnvelope, verifyAssertion } from './passkey-verify';
+
+/** Versioned domain tag: a step-up challenge can never collide with a sign-in one's random bytes. */
+const STEP_UP_TAG = new TextEncoder().encode('ultimate.passkey.step-up.v1\u0000');
+
+/**
+ * `SHA-256(tag || nonce || u16(len digest) || digest || userId)`. The nonce is a fixed 32 bytes
+ * and the digest is length-prefixed, so no two inputs share an encoding. The nonce makes two
+ * approvals of one digest two signatures; the user id makes the row's `userId` part of what was
+ * signed, so re-attributing an approval to someone else breaks it.
+ */
+export async function stepUpChallenge(
+  nonce: Uint8Array,
+  digest: Uint8Array,
+  userId: string,
+): Promise<Uint8Array> {
+  const user = new TextEncoder().encode(userId);
+  const input = new Uint8Array(STEP_UP_TAG.length + nonce.length + 2 + digest.length + user.length);
+  let at = 0;
+  for (const part of [
+    STEP_UP_TAG,
+    nonce,
+    Uint8Array.of(digest.length >> 8, digest.length & 0xff),
+    digest,
+    user,
+  ]) {
+    input.set(part, at);
+    at += part.length;
+  }
+  return new Uint8Array(await crypto.subtle.digest('SHA-256', input));
+}
+
+/**
+ * `true` only when the stored assertion is a user-verified signature, by the stored key, over a
+ * challenge derived from the stored nonce, digest and user, made for this relying party. An edit
+ * to any of those, to the key or to the signed bytes is `false`. What it cannot prove alone is
+ * that the key is the user's: that is `x_passkeys`' row, and the reason the key is stored here.
+ */
+export async function verifyPasskeyEvidence(
+  evidence: PasskeyEvidence,
+  relyingParty: PasskeyRelyingParty,
+): Promise<boolean> {
+  const nonce = canonicalBase64UrlBytes(evidence.nonce);
+  const digest = canonicalBase64UrlBytes(evidence.digest);
+  if (nonce === null || nonce.length !== 32 || digest === null || digest.length === 0) return false;
+  const envelope = readEnvelope(
+    relyingParty,
+    {
+      id: evidence.credentialId,
+      rawId: evidence.credentialId,
+      type: 'public-key',
+      response: {
+        clientDataJSON: evidence.clientDataJSON,
+        authenticatorData: evidence.authenticatorData,
+        signature: evidence.signature,
+      },
+    },
+    'webauthn.get',
+  );
+  if (!envelope.ok) return false;
+  const expected = base64Url(await stepUpChallenge(nonce, digest, evidence.userId));
+  if (!timingSafeEqual(envelope.value.challenge, expected)) return false;
+  const verified = await verifyAssertion(relyingParty, envelope.value, evidence.publicKey);
+  return verified.ok;
+}

package/src/passkey-login.ts

@@ -0,0 +1,127 @@
+// Single responsibility: `passkeyLogin(auth)` — the two WebAuthn ceremonies a person signs in
+// with: registering a passkey onto an account they already hold, and a usernameless sign-in that
+// ends in the same session `login()` mints. Plain functions over `Auth`; the app wraps each in its
+// own action (tier 2 cannot construct one), exactly as it wraps `login` and `completeMfa`.
+
+import type { PasskeyCredential } from './adapter';
+import type { Auth, LoginResult } from './auth';
+import { base64Url } from './base64url';
+import { PASSKEY_ALGORITHMS } from './cose-key';
+import { acceptAssertion } from './passkey-assertion';
+import { issuePasskeyChallenge, redeemPasskeyChallenge } from './passkey-challenge';
+import { passkeyPolicyOf } from './passkey-config';
+import { refusePasskey } from './passkey-errors';
+import { readEnvelope, verifyAttestation } from './passkey-verify';
+import type { PasskeyCreationOptions, PasskeyRequestOptions } from './passkey-wire';
+import { resolveActor } from './policy-bridge';
+import { createSession, sessionCookie } from './session';
+
+export interface PasskeyLogin {
+  /** For a signed-in user adding a passkey: hand the result to `newPasskey` in the browser. */
+  registerOptions(input: { readonly userId: string }): Promise<PasskeyCreationOptions>;
+  /** Verifies `newPasskey`'s answer and stores the credential under `userId`. */
+  register(input: {
+    readonly userId: string;
+    readonly response: unknown;
+  }): Promise<PasskeyCredential>;
+  /** Usernameless: no account is named, so nothing here enumerates one. */
+  loginOptions(): Promise<PasskeyRequestOptions>;
+  /** Verifies `getPasskey`'s answer and mints a session — `login()`'s result shape. */
+  login(input: {
+    readonly response: unknown;
+    readonly ip?: string | null | undefined;
+    readonly userAgent?: string | null | undefined;
+  }): Promise<LoginResult>;
+}
+
+export function passkeyLogin(auth: Auth): PasskeyLogin {
+  const policy = passkeyPolicyOf(auth, 'passkeyLogin');
+  return {
+    async registerOptions({ userId }) {
+      const user = await auth.adapter.findUserById(userId);
+      if (user === null || user.disabledAt !== null) throw refusePasskey('register', 'user');
+      const { challenge } = await issuePasskeyChallenge(auth, 'register', {
+        userId,
+        ttlMs: policy.challengeTtlMs,
+      });
+      const existing = await auth.adapter.listPasskeys(userId);
+      return {
+        challenge,
+        rp: { id: policy.rpId, name: policy.rpName },
+        // The user handle is the auth user's id — opaque, never the address (§14.6.1).
+        user: {
+          id: base64Url(new TextEncoder().encode(userId)),
+          name: user.email,
+          displayName: user.email,
+        },
+        pubKeyCredParams: PASSKEY_ALGORITHMS.map((alg) => ({ type: 'public-key' as const, alg })),
+        timeout: policy.challengeTtlMs,
+        attestation: 'none',
+        authenticatorSelection: {
+          residentKey: 'required',
+          requireResidentKey: true,
+          userVerification: 'required',
+        },
+        excludeCredentials: existing.map((row) => ({
+          type: 'public-key' as const,
+          id: row.id,
+          transports: row.transports,
+        })),
+      };
+    },
+
+    async register({ userId, response }) {
+      const envelope = readEnvelope(policy, response, 'webauthn.create');
+      if (!envelope.ok) throw refusePasskey('register', envelope.check);
+      const issued = await redeemPasskeyChallenge(auth, 'register', envelope.value.challenge);
+      // A challenge issued to one account never registers a key onto another.
+      if (issued.userId !== userId) throw refusePasskey('register', 'user');
+      const attested = await verifyAttestation(policy, envelope.value);
+      if (!attested.ok) throw refusePasskey('register', attested.check);
+      return await auth.adapter.putPasskey({
+        ...attested.value,
+        id: attested.value.credentialId,
+        userId,
+        createdAt: auth.clock.now(),
+        lastUsedAt: null,
+      });
+    },
+
+    async loginOptions() {
+      const { challenge } = await issuePasskeyChallenge(auth, 'login', {
+        userId: null,
+        ttlMs: policy.challengeTtlMs,
+      });
+      return {
+        challenge,
+        rpId: policy.rpId,
+        timeout: policy.challengeTtlMs,
+        userVerification: 'required',
+        allowCredentials: [],
+      };
+    },
+
+    async login({ response, ip, userAgent }) {
+      const envelope = readEnvelope(policy, response, 'webauthn.get');
+      if (!envelope.ok) throw refusePasskey('login', envelope.check);
+      await redeemPasskeyChallenge(auth, 'login', envelope.value.challenge);
+      const { credential } = await acceptAssertion(auth, policy, 'login', envelope.value, null);
+      const user = await auth.adapter.findUserById(credential.userId);
+      if (user === null || user.disabledAt !== null) throw refusePasskey('login', 'user');
+      // A user-verified passkey is two factors in one gesture (possession + the device's PIN or
+      // biometric), so the session is MFA-satisfied even where a TOTP secret is enrolled.
+      const issued = await createSession(auth.sessions, {
+        userId: user.id,
+        ip: ip ?? null,
+        userAgent,
+        mfaSatisfied: true,
+      });
+      return {
+        actor: resolveActor({ kind: 'user', user, session: issued.session }),
+        session: issued.session,
+        token: issued.token,
+        cookie: sessionCookie(issued.token, auth.sessions.policy),
+      };
+    },
+  };
+}

package/src/passkey-memory.ts

@@ -0,0 +1,77 @@
+// Single responsibility: `MemoryAuthAdapter`'s `PasskeyStore` members — the three `x_passkey*`
+// tables as maps, with the same constraints Postgres enforces (a credential id is unique across
+// every user; a take deletes) so a flow that passes here passes there. `passkey-store.test.ts`.
+
+import { timingSafeEqual } from '@ultimat3/core';
+import type {
+  PasskeyChallengeRecord,
+  PasskeyCredential,
+  PasskeyEvidence,
+  PasskeyStore,
+} from './adapter';
+import { authUniqueViolation } from './errors';
+
+const byCreated = <T extends { readonly createdAt: Date; readonly id: string }>(a: T, b: T) =>
+  a.createdAt.getTime() - b.createdAt.getTime() || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+/** The members over three maps, as closures — `MemoryAuthAdapter` binds each one as a field. */
+export function memoryPasskeyStore(): PasskeyStore {
+  const passkeys = new Map<string, PasskeyCredential>();
+  const challenges = new Map<string, PasskeyChallengeRecord>();
+  const evidence = new Map<string, PasskeyEvidence>();
+  return {
+    async putPasskey(credential) {
+      if (passkeys.has(credential.id)) throw authUniqueViolation('putPasskey', 'x_passkeys', 'id');
+      const stored = { ...credential, transports: [...credential.transports] };
+      passkeys.set(credential.id, stored);
+      return stored;
+    },
+    async findPasskey(id) {
+      return passkeys.get(id) ?? null;
+    },
+    async listPasskeys(userId) {
+      return [...passkeys.values()].filter((row) => row.userId === userId).sort(byCreated);
+    },
+    async advancePasskeyCounter(id, expected, next, at) {
+      const row = passkeys.get(id);
+      if (row === undefined || row.signCount !== expected) return false;
+      passkeys.set(id, { ...row, signCount: next, lastUsedAt: at });
+      return true;
+    },
+    async deletePasskey(userId, id) {
+      if (passkeys.get(id)?.userId !== userId) return false;
+      return passkeys.delete(id);
+    },
+    async putPasskeyChallenge(record) {
+      // Swept from the oldest put, stopping at the first live one: insertion order is issue order,
+      // so a put costs the expired rows it removes plus one. A full scan per put made a flood of
+      // unauthenticated `loginOptions` within one TTL quadratic. A live row never goes early; an
+      // expired one behind a longer-lived row waits for it, which bounds memory by the longest TTL.
+      const nowMs = record.createdAt.getTime();
+      for (const [id, row] of challenges) {
+        if (row.expiresAt.getTime() >= nowMs) break;
+        challenges.delete(id);
+      }
+      // Deleted first, so a re-put of one id moves to the end with its new expiry.
+      challenges.delete(record.id);
+      challenges.set(record.id, record);
+    },
+    async takePasskeyChallenge(id, ceremony) {
+      const row = challenges.get(id);
+      if (row === undefined || row.ceremony !== ceremony) return null;
+      challenges.delete(id);
+      return row;
+    },
+    async putPasskeyEvidence(record) {
+      if (evidence.has(record.id)) {
+        throw authUniqueViolation('putPasskeyEvidence', 'x_passkey_evidence', 'id');
+      }
+      evidence.set(record.id, record);
+    },
+    async listPasskeyEvidence(digest) {
+      return [...evidence.values()]
+        .filter((row) => timingSafeEqual(row.digest, digest))
+        .sort(byCreated);
+    },
+  };
+}

package/src/passkey-postgres.ts

@@ -0,0 +1,155 @@
+// Single responsibility: `PostgresAuthAdapter`'s `PasskeyStore` members, as SQL over the three
+// `x_passkey*` tables (`tables.ts`). Split out of `builtin-adapter.ts`, which delegates one line per
+// member; the readers are this file's because a passkey row is the only one with a bigint counter.
+
+import { type DbClient, sql } from '@ultimat3/db';
+import type {
+  PasskeyCeremony,
+  PasskeyChallengeRecord,
+  PasskeyCredential,
+  PasskeyEvidence,
+  PasskeyStore,
+} from './adapter';
+import { usersUniqueViolation } from './builtin-adapter-violation';
+import { authWriteFailed } from './errors';
+
+type Row = Readonly<Record<string, unknown>>;
+
+const str = (row: Row, key: string): string => {
+  const value = row[key];
+  return typeof value === 'string' ? value : '';
+};
+const strOrNull = (row: Row, key: string): string | null => {
+  const value = row[key];
+  return typeof value === 'string' ? value : null;
+};
+/** `bigint` arrives as a string from some drivers and a number from others; NaN is never a count. */
+const int = (row: Row, key: string): number => {
+  const value = Number(row[key]);
+  return Number.isSafeInteger(value) ? value : 0;
+};
+const when = (row: Row, key: string): Date | null => {
+  const value = row[key];
+  if (value instanceof Date) return value;
+  if (typeof value !== 'string' && typeof value !== 'number') return null;
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+};
+const strings = (row: Row, key: string): readonly string[] => {
+  const value = row[key];
+  return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+};
+
+const toCredential = (row: Row): PasskeyCredential => ({
+  id: str(row, 'id'),
+  userId: str(row, 'user_id'),
+  publicKey: str(row, 'public_key'),
+  algorithm: int(row, 'algorithm'),
+  signCount: int(row, 'sign_count'),
+  transports: strings(row, 'transports'),
+  createdAt: when(row, 'created_at') ?? new Date(0),
+  lastUsedAt: when(row, 'last_used_at'),
+});
+
+const toChallenge = (row: Row, ceremony: PasskeyCeremony): PasskeyChallengeRecord => ({
+  id: str(row, 'id'),
+  // The DELETE matched on it, so the row's ceremony IS the one asked for.
+  ceremony,
+  userId: strOrNull(row, 'user_id'),
+  digest: strOrNull(row, 'digest'),
+  nonce: strOrNull(row, 'nonce'),
+  // An unreadable instant is an expired one: fail closed.
+  expiresAt: when(row, 'expires_at') ?? new Date(0),
+  createdAt: when(row, 'created_at') ?? new Date(0),
+});
+
+const toEvidence = (row: Row): PasskeyEvidence => ({
+  id: str(row, 'id'),
+  userId: str(row, 'user_id'),
+  credentialId: str(row, 'credential_id'),
+  digest: str(row, 'digest'),
+  nonce: str(row, 'nonce'),
+  authenticatorData: str(row, 'authenticator_data'),
+  clientDataJSON: str(row, 'client_data_json'),
+  signature: str(row, 'signature'),
+  publicKey: str(row, 'public_key'),
+  algorithm: int(row, 'algorithm'),
+  createdAt: when(row, 'created_at') ?? new Date(0),
+});
+
+/** The members, over a client resolved per call — the adapter's ambient `db()` rule. */
+export function postgresPasskeyStore(client: () => DbClient): PasskeyStore {
+  return {
+    async putPasskey(credential) {
+      let row: Row | null;
+      try {
+        row = await client().one<Row>(sql`
+          insert into x_passkeys (id, user_id, public_key, algorithm, sign_count, transports,
+                                  created_at)
+          values (${credential.id}, ${credential.userId}, ${credential.publicKey},
+                  ${credential.algorithm}, ${credential.signCount}, ${[...credential.transports]},
+                  ${credential.createdAt})
+          returning *`);
+      } catch (error) {
+        throw usersUniqueViolation('putPasskey', error) ?? error;
+      }
+      if (row === null) throw authWriteFailed('putPasskey', 'x_passkeys');
+      return toCredential(row);
+    },
+    async findPasskey(id) {
+      const row = await client().one<Row>(sql`select * from x_passkeys where id = ${id}`);
+      return row === null ? null : toCredential(row);
+    },
+    async listPasskeys(userId) {
+      const rows = await client().query<Row>(sql`
+        select * from x_passkeys where user_id = ${userId} order by created_at asc, id collate "C" asc`);
+      return rows.map(toCredential);
+    },
+    async advancePasskeyCounter(id, expected, next, at) {
+      const row = await client().one<Row>(sql`
+        update x_passkeys set sign_count = ${next}, last_used_at = ${at}
+         where id = ${id} and sign_count = ${expected}
+        returning id`);
+      return row !== null;
+    },
+    async deletePasskey(userId, id) {
+      const removed = await client().execute(
+        sql`delete from x_passkeys where id = ${id} and user_id = ${userId}`,
+      );
+      return removed > 0;
+    },
+    async putPasskeyChallenge(record) {
+      await client().execute(
+        sql`delete from x_passkey_challenges where expires_at < ${record.createdAt}`,
+      );
+      await client().execute(sql`
+        insert into x_passkey_challenges (id, ceremony, user_id, digest, nonce, expires_at,
+                                          created_at)
+        values (${record.id}, ${record.ceremony}, ${record.userId}, ${record.digest},
+                ${record.nonce}, ${record.expiresAt}, ${record.createdAt})`);
+    },
+    async takePasskeyChallenge(id, ceremony) {
+      // DELETE … RETURNING is the take: the row lock makes the second of two racing redemptions
+      // find nothing, and a redeemed challenge leaves nothing behind to sweep.
+      const row = await client().one<Row>(sql`
+        delete from x_passkey_challenges where id = ${id} and ceremony = ${ceremony}
+        returning *`);
+      return row === null ? null : toChallenge(row, ceremony);
+    },
+    async putPasskeyEvidence(evidence) {
+      await client().execute(sql`
+        insert into x_passkey_evidence (id, user_id, credential_id, digest, nonce,
+                                        authenticator_data, client_data_json, signature,
+                                        public_key, algorithm, created_at)
+        values (${evidence.id}, ${evidence.userId}, ${evidence.credentialId}, ${evidence.digest},
+                ${evidence.nonce}, ${evidence.authenticatorData}, ${evidence.clientDataJSON},
+                ${evidence.signature}, ${evidence.publicKey}, ${evidence.algorithm},
+                ${evidence.createdAt})`);
+    },
+    async listPasskeyEvidence(digest) {
+      const rows = await client().query<Row>(sql`
+        select * from x_passkey_evidence where digest = ${digest} order by created_at asc, id collate "C" asc`);
+      return rows.map(toEvidence);
+    },
+  };
+}