@ultimat3/auth 29.3.2 → 30.0.0

package/src/passkey-step-up.ts

@@ -0,0 +1,135 @@
+// Single responsibility: `passkeyStepUp(auth, { digest })` — a fresh, user-verified assertion
+// bound to bytes the SERVER computed from the action's input, so the stored assertion proves a
+// person approved exactly those bytes. The WebAuthn challenge is derived (nonce + digest), never
+// supplied: a caller cannot choose what is signed, only present what the server asked for.
+
+import { timingSafeEqual, uuidV7 } from '@ultimat3/core';
+import type { PasskeyEvidence } from './adapter';
+import type { Auth } from './auth';
+import { base64Url } from './base64url';
+import { acceptAssertion } from './passkey-assertion';
+import { issuePasskeyChallenge, redeemPasskeyChallenge } from './passkey-challenge';
+import { passkeyPolicyOf } from './passkey-config';
+import {
+  MAX_STEP_UP_DIGEST_BYTES,
+  passkeyStepUpRequired,
+  refusePasskey,
+  stepUpDigestInvalid,
+} from './passkey-errors';
+import { stepUpChallenge } from './passkey-evidence';
+import { readEnvelope } from './passkey-verify';
+import type { PasskeyRequestOptions } from './passkey-wire';
+import { assertFiniteAuthCount } from './policy-numbers';
+import { randomBytes } from './tokens';
+
+export interface PasskeyStepUpOptions<I> {
+  /**
+   * The bytes the person approves, computed on the server from what the action will act on —
+   * `({ input }) => sha256Hex(canonicalJson(input))`. Text is taken as UTF-8. 1 to 1024 bytes.
+   */
+  readonly digest: (args: {
+    readonly input: I;
+    readonly userId: string;
+  }) => string | Uint8Array | Promise<string | Uint8Array>;
+  /** How long a proof may wait for its action. Defaults to `passkeys.challengeTtlMs`. */
+  readonly ttlMs?: number | undefined;
+}
+
+export interface PasskeyStepUp<I> {
+  /** For the user about to act: hand the result to `getPasskey` in the browser. */
+  options(args: { readonly userId: string; readonly input: I }): Promise<PasskeyRequestOptions>;
+  /**
+   * Inside the sensitive action, before it acts: the proof for THIS input, or
+   * `X_PASSKEY_STEP_UP_REQUIRED`. The answer is stored and returned as evidence.
+   */
+  verify(args: {
+    readonly userId: string;
+    readonly input: I;
+    readonly response: unknown;
+  }): Promise<PasskeyEvidence>;
+}
+
+export function passkeyStepUp<I>(auth: Auth, declared: PasskeyStepUpOptions<I>): PasskeyStepUp<I> {
+  const policy = passkeyPolicyOf(auth, 'passkeyStepUp');
+  const ttlMs = assertFiniteAuthCount(
+    'passkeyStepUp.ttlMs',
+    declared.ttlMs ?? policy.challengeTtlMs,
+    'a step-up proof would never expire',
+    1,
+  );
+  const digestOf = async (input: I, userId: string): Promise<Uint8Array> => {
+    const value = await declared.digest({ input, userId });
+    const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
+    if (bytes.length === 0 || bytes.length > MAX_STEP_UP_DIGEST_BYTES) {
+      throw stepUpDigestInvalid(bytes.length);
+    }
+    return bytes;
+  };
+
+  return {
+    async options({ userId, input }) {
+      const digest = await digestOf(input, userId);
+      const passkeys = await auth.adapter.listPasskeys(userId);
+      if (passkeys.length === 0) throw passkeyStepUpRequired('no-passkey');
+      const nonce = randomBytes(32);
+      const { challenge } = await issuePasskeyChallenge(auth, 'step-up', {
+        userId,
+        digest: base64Url(digest),
+        nonce: base64Url(nonce),
+        challenge: await stepUpChallenge(nonce, digest, userId),
+        ttlMs,
+      });
+      return {
+        challenge,
+        rpId: policy.rpId,
+        timeout: ttlMs,
+        userVerification: 'required',
+        allowCredentials: passkeys.map((row) => ({
+          type: 'public-key' as const,
+          id: row.id,
+          transports: row.transports,
+        })),
+      };
+    },
+
+    async verify({ userId, input, response }) {
+      if (response === undefined || response === null) throw passkeyStepUpRequired('no-proof');
+      const envelope = readEnvelope(policy, response, 'webauthn.get');
+      if (!envelope.ok) throw refusePasskey('step-up', envelope.check);
+      const digest = base64Url(await digestOf(input, userId));
+      const issued = await redeemPasskeyChallenge(auth, 'step-up', envelope.value.challenge);
+      if (issued.userId !== userId) throw refusePasskey('step-up', 'user');
+      // The proof is real and fresh, and for other bytes: the action this call carries was not
+      // the one approved. A step-up for THIS input is still owed.
+      if (
+        issued.digest === null ||
+        !timingSafeEqual(issued.digest, digest) ||
+        issued.nonce === null
+      ) {
+        throw passkeyStepUpRequired('other-digest');
+      }
+      const { credential, assertion } = await acceptAssertion(
+        auth,
+        policy,
+        'step-up',
+        envelope.value,
+        userId,
+      );
+      const evidence: PasskeyEvidence = {
+        id: uuidV7(auth.clock),
+        userId,
+        credentialId: credential.id,
+        digest,
+        nonce: issued.nonce,
+        authenticatorData: base64Url(assertion.authenticatorData),
+        clientDataJSON: base64Url(envelope.value.clientDataJSON),
+        signature: base64Url(assertion.signature),
+        publicKey: credential.publicKey,
+        algorithm: credential.algorithm,
+        createdAt: auth.clock.now(),
+      };
+      await auth.adapter.putPasskeyEvidence(evidence);
+      return evidence;
+    },
+  };
+}

package/src/passkey-verify.ts

@@ -0,0 +1,180 @@
+// Single responsibility: the WebAuthn checks (L3 §7.1 registration, §7.2 assertion) over a
+// response the browser forwarded — envelope, `clientDataJSON` type and origin, rp id hash, the UP
+// and UV flags, the attested key, the signature. Pure: no store, no clock. Every refusal answers
+// `null` plus the name of the check, which the caller logs; the challenge is the caller's to match.
+
+import { base64Url, canonicalBase64UrlBytes } from './base64url';
+import { importCoseKey, PASSKEY_ALGORITHMS, verifyCoseSignature } from './cose-key';
+import { isRecord } from './json';
+import type { PasskeyRelyingParty } from './passkey-config';
+import {
+  type AuthenticatorData,
+  FLAG_AT,
+  FLAG_UP,
+  FLAG_UV,
+  parseAttestationObject,
+  parseAuthenticatorData,
+  parseClientData,
+} from './webauthn-data';
+
+/** Which check refused — a log field, never a `cause:`. */
+export type PasskeyCheck =
+  | 'envelope'
+  | 'client-data'
+  | 'type'
+  | 'origin'
+  | 'attestation'
+  | 'rp-id'
+  | 'user-present'
+  | 'user-verified'
+  | 'credential-id'
+  | 'key'
+  | 'signature';
+
+export type Checked<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly check: PasskeyCheck };
+
+const refuse = (check: PasskeyCheck): { readonly ok: false; readonly check: PasskeyCheck } => ({
+  ok: false,
+  check,
+});
+
+/** The parts of a response every ceremony reads before it knows which challenge it answers. */
+export interface CeremonyEnvelope {
+  readonly credentialId: string;
+  readonly challenge: string;
+  readonly clientDataJSON: Uint8Array;
+  readonly response: Readonly<Record<string, unknown>>;
+}
+
+const sha256 = async (bytes: Uint8Array): Promise<Uint8Array> =>
+  new Uint8Array(await crypto.subtle.digest('SHA-256', new Uint8Array(bytes)));
+
+const equalBytes = (a: Uint8Array, b: Uint8Array): boolean =>
+  a.length === b.length && a.every((byte, index) => byte === b[index]);
+
+export const rpIdHash = (rpId: string): Promise<Uint8Array> =>
+  sha256(new TextEncoder().encode(rpId));
+
+/** `id === rawId`, both canonical base64url; `type` is `public-key`; the client data is ours. */
+export function readEnvelope(
+  policy: PasskeyRelyingParty,
+  raw: unknown,
+  type: 'webauthn.create' | 'webauthn.get',
+): Checked<CeremonyEnvelope> {
+  if (!isRecord(raw) || raw['type'] !== 'public-key' || !isRecord(raw['response'])) {
+    return refuse('envelope');
+  }
+  const id = raw['id'];
+  if (canonicalBase64UrlBytes(id) === null || raw['rawId'] !== id || typeof id !== 'string') {
+    return refuse('envelope');
+  }
+  const response = raw['response'];
+  const clientDataJSON = canonicalBase64UrlBytes(response['clientDataJSON']);
+  const clientData = clientDataJSON === null ? null : parseClientData(clientDataJSON);
+  if (clientDataJSON === null || clientData === null) return refuse('client-data');
+  if (clientData.type !== type) return refuse('type');
+  // An exact match against the declared list — never a prefix, never a host compare — and never
+  // from inside a cross-origin iframe, which the declaration did not name.
+  if (!policy.origins.includes(clientData.origin) || clientData.crossOrigin) {
+    return refuse('origin');
+  }
+  return {
+    ok: true,
+    value: { credentialId: id, challenge: clientData.challenge, clientDataJSON, response },
+  };
+}
+
+/** Checked once per ceremony: our rp, a person present, and that person verified. */
+async function checkFlags(
+  policy: PasskeyRelyingParty,
+  data: AuthenticatorData,
+): Promise<PasskeyCheck | null> {
+  if (!equalBytes(data.rpIdHash, await rpIdHash(policy.rpId))) return 'rp-id';
+  if ((data.flags & FLAG_UP) === 0) return 'user-present';
+  if ((data.flags & FLAG_UV) === 0) return 'user-verified';
+  return null;
+}
+
+export interface AttestedPasskey {
+  readonly credentialId: string;
+  readonly publicKey: string;
+  readonly algorithm: number;
+  readonly signCount: number;
+  readonly transports: readonly string[];
+}
+
+const TRANSPORT = /^[a-z-]{1,32}$/;
+
+/** §7.1 steps 7-27 that need no store. The attestation STATEMENT is not verified: we asked for none. */
+export async function verifyAttestation(
+  policy: PasskeyRelyingParty,
+  envelope: CeremonyEnvelope,
+): Promise<Checked<AttestedPasskey>> {
+  const attestation = canonicalBase64UrlBytes(envelope.response['attestationObject']);
+  const parsed = attestation === null ? null : parseAttestationObject(attestation);
+  const data = parsed === null ? null : parseAuthenticatorData(parsed.authData);
+  if (data === null) return refuse('attestation');
+  const flags = await checkFlags(policy, data);
+  if (flags !== null) return refuse(flags);
+  if ((data.flags & FLAG_AT) === 0 || data.attested === null) return refuse('attestation');
+  if (base64Url(data.attested.credentialId) !== envelope.credentialId)
+    return refuse('credential-id');
+  const key = await importCoseKey(data.attested.publicKey);
+  if (key === null || !PASSKEY_ALGORITHMS.includes(key.algorithm)) return refuse('key');
+  const declared = envelope.response['transports'];
+  const transports = Array.isArray(declared)
+    ? declared.filter((item): item is string => typeof item === 'string' && TRANSPORT.test(item))
+    : [];
+  return {
+    ok: true,
+    value: {
+      credentialId: envelope.credentialId,
+      publicKey: base64Url(data.attested.publicKey),
+      algorithm: key.algorithm,
+      signCount: data.signCount,
+      transports: transports.slice(0, 8),
+    },
+  };
+}
+
+export interface VerifiedAssertion {
+  readonly signCount: number;
+  /** The `userHandle` the authenticator returned, decoded as text; `null` when it sent none. */
+  readonly userHandle: string | null;
+  readonly authenticatorData: Uint8Array;
+  readonly signature: Uint8Array;
+}
+
+/** §7.2 steps 11-21 that need no store, against the key `publicKey` (stored COSE, base64url). */
+export async function verifyAssertion(
+  policy: PasskeyRelyingParty,
+  envelope: CeremonyEnvelope,
+  publicKey: string,
+): Promise<Checked<VerifiedAssertion>> {
+  const authenticatorData = canonicalBase64UrlBytes(envelope.response['authenticatorData']);
+  const signature = canonicalBase64UrlBytes(envelope.response['signature']);
+  const data = authenticatorData === null ? null : parseAuthenticatorData(authenticatorData);
+  if (authenticatorData === null || signature === null || data === null) return refuse('envelope');
+  const flags = await checkFlags(policy, data);
+  if (flags !== null) return refuse(flags);
+  const cose = canonicalBase64UrlBytes(publicKey);
+  const key = cose === null ? null : await importCoseKey(cose);
+  if (key === null) return refuse('key');
+  const signed = new Uint8Array(authenticatorData.length + 32);
+  signed.set(authenticatorData);
+  signed.set(await sha256(envelope.clientDataJSON), authenticatorData.length);
+  if (!(await verifyCoseSignature(key, signature, signed))) return refuse('signature');
+  const handle = envelope.response['userHandle'];
+  let userHandle: string | null = null;
+  if (handle !== undefined && handle !== null) {
+    const bytes = canonicalBase64UrlBytes(handle);
+    if (bytes === null) return refuse('envelope');
+    userHandle = new TextDecoder().decode(bytes);
+  }
+  return {
+    ok: true,
+    value: { signCount: data.signCount, userHandle, authenticatorData, signature },
+  };
+}

package/src/passkey-wire.ts

@@ -0,0 +1,61 @@
+// Single responsibility: the JSON shapes a passkey ceremony crosses the wire in — the options the
+// server hands the browser and the credential the browser hands back — as TYPES only, so the
+// browser entry (`client.ts`) and the server share one declaration and the client pays no bytes.
+// Every binary field is base64url; the names are WebAuthn L3's `*JSON` dictionaries (§5.1.8).
+
+export type PasskeyCredentialDescriptor = {
+  readonly type: 'public-key';
+  readonly id: string;
+  readonly transports: readonly string[];
+};
+
+/** `PublicKeyCredentialCreationOptionsJSON`, as `passkeyLogin(auth).registerOptions` issues it. */
+export type PasskeyCreationOptions = {
+  readonly challenge: string;
+  readonly rp: { readonly id: string; readonly name: string };
+  readonly user: { readonly id: string; readonly name: string; readonly displayName: string };
+  readonly pubKeyCredParams: readonly { readonly type: 'public-key'; readonly alg: number }[];
+  readonly timeout: number;
+  readonly attestation: 'none';
+  readonly authenticatorSelection: {
+    readonly residentKey: 'required';
+    readonly requireResidentKey: true;
+    readonly userVerification: 'required';
+  };
+  readonly excludeCredentials: readonly PasskeyCredentialDescriptor[];
+};
+
+/** `PublicKeyCredentialRequestOptionsJSON`, for sign-in and for step-up. */
+export type PasskeyRequestOptions = {
+  readonly challenge: string;
+  readonly rpId: string;
+  readonly timeout: number;
+  readonly userVerification: 'required';
+  /** Empty for a usernameless sign-in; the user's own passkeys for a step-up. */
+  readonly allowCredentials: readonly PasskeyCredentialDescriptor[];
+};
+
+/** `RegistrationResponseJSON`: what `newPasskey(options)` answers and `register` reads. */
+export type PasskeyRegistrationResponse = {
+  readonly id: string;
+  readonly rawId: string;
+  readonly type: 'public-key';
+  readonly response: {
+    readonly clientDataJSON: string;
+    readonly attestationObject: string;
+    readonly transports: readonly string[];
+  };
+};
+
+/** `AuthenticationResponseJSON`: what `getPasskey(options)` answers and `login`/`verify` read. */
+export type PasskeyAssertionResponse = {
+  readonly id: string;
+  readonly rawId: string;
+  readonly type: 'public-key';
+  readonly response: {
+    readonly clientDataJSON: string;
+    readonly authenticatorData: string;
+    readonly signature: string;
+    readonly userHandle: string | null;
+  };
+};

package/src/soft-authenticator.ts

@@ -0,0 +1,208 @@
+// Single responsibility: a SOFTWARE authenticator on WebCrypto — it mints real ES256 / RS256
+// credentials and signs real assertions, the bytes a platform authenticator sends, so a test runs
+// a passkey ceremony end to end against the real verifier. Public as `@ultimat3/auth/soft-authenticator`, the one
+// path an app's test and this package's own suites share.
+
+import { base64Url, base64UrlBytes } from './base64url';
+import type { CborValue } from './cbor';
+import { cborEncode } from './cbor-encode';
+import type {
+  PasskeyAssertionResponse,
+  PasskeyCreationOptions,
+  PasskeyRegistrationResponse,
+  PasskeyRequestOptions,
+} from './passkey-wire';
+import { FLAG_AT, FLAG_UP, FLAG_UV } from './webauthn-data';
+
+const concat = (...parts: readonly Uint8Array[]): Uint8Array<ArrayBuffer> => {
+  const out = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+};
+
+const sha256 = async (bytes: Uint8Array): Promise<Uint8Array> =>
+  new Uint8Array(await crypto.subtle.digest('SHA-256', new Uint8Array(bytes)));
+
+const u32 = (value: number): Uint8Array => {
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setUint32(0, value);
+  return out;
+};
+
+/** Raw `r || s` → strict DER, as an authenticator encodes an ES256 signature. */
+export function ecdsaRawToDer(raw: Uint8Array): Uint8Array {
+  const integer = (bytes: Uint8Array): Uint8Array => {
+    let start = 0;
+    while (start < bytes.length - 1 && bytes[start] === 0) start += 1;
+    const trimmed = bytes.subarray(start);
+    const padded = (trimmed[0] ?? 0) & 0x80 ? concat(Uint8Array.of(0), trimmed) : trimmed;
+    return concat(Uint8Array.of(0x02, padded.length), padded);
+  };
+  const body = concat(integer(raw.subarray(0, 32)), integer(raw.subarray(32)));
+  return concat(Uint8Array.of(0x30, body.length), body);
+}
+
+/**
+ * One knob per check the verifier makes, so a test breaks exactly one: the origin or the
+ * `clientDataJSON` type a phishing page would send, another rp id, flags without UV, a counter that
+ * went backwards, another ceremony's challenge, a user handle the credential was not made for.
+ */
+export interface SoftCeremonyOverrides {
+  readonly origin?: string | undefined;
+  readonly type?: string | undefined;
+  readonly rpId?: string | undefined;
+  readonly flags?: number | undefined;
+  readonly signCount?: number | undefined;
+  readonly challenge?: string | undefined;
+  readonly userHandle?: string | null | undefined;
+  readonly crossOrigin?: boolean | undefined;
+}
+
+/** A passkey: `create` answers `newPasskey`'s response, `get` answers `getPasskey`'s. */
+export interface SoftAuthenticator {
+  /** base64url, as the server stores it. */
+  readonly credentialId: string;
+  create(
+    options: PasskeyCreationOptions,
+    overrides?: SoftCeremonyOverrides,
+  ): Promise<PasskeyRegistrationResponse>;
+  get(
+    options: PasskeyRequestOptions,
+    overrides?: SoftCeremonyOverrides,
+  ): Promise<PasskeyAssertionResponse>;
+}
+
+export interface SoftAuthenticatorInput {
+  /** The page origin the browser would report: one of `passkeys.origins`, or the test fails. */
+  readonly origin: string;
+  /** `ES256` by default. */
+  readonly algorithm?: 'ES256' | 'RS256' | undefined;
+  /** Where the counter starts; `null` is an authenticator that keeps none (always 0). */
+  readonly counter?: number | null | undefined;
+}
+
+/** A fresh key pair and credential id: one passkey, on no device. */
+export async function softAuthenticator(init: SoftAuthenticatorInput): Promise<SoftAuthenticator> {
+  const rsa = init.algorithm === 'RS256';
+  const pair = rsa
+    ? await crypto.subtle.generateKey(
+        {
+          name: 'RSASSA-PKCS1-v1_5',
+          modulusLength: 2048,
+          publicExponent: Uint8Array.of(1, 0, 1),
+          hash: 'SHA-256',
+        },
+        true,
+        ['sign', 'verify'],
+      )
+    : await crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, [
+        'sign',
+        'verify',
+      ]);
+  const jwk = await crypto.subtle.exportKey('jwk', pair.publicKey);
+  const bytesOf = (field: string | undefined): Uint8Array =>
+    base64UrlBytes(field ?? '') ?? new Uint8Array();
+  const cose = rsa
+    ? cborEncode(
+        new Map<number, CborValue>([
+          [1, 3],
+          [3, -257],
+          [-1, bytesOf(jwk.n)],
+          [-2, bytesOf(jwk.e)],
+        ]),
+      )
+    : cborEncode(
+        new Map<number, CborValue>([
+          [1, 2],
+          [3, -7],
+          [-1, 1],
+          [-2, bytesOf(jwk.x)],
+          [-3, bytesOf(jwk.y)],
+        ]),
+      );
+  const rawId = crypto.getRandomValues(new Uint8Array(16));
+  const credentialId = base64Url(rawId);
+  let counter = init.counter === undefined ? 0 : init.counter;
+  let userHandle: string | null = null;
+
+  const clientData = (type: string, challenge: string, o: SoftCeremonyOverrides): Uint8Array =>
+    new TextEncoder().encode(
+      JSON.stringify({
+        type: o.type ?? type,
+        challenge: o.challenge ?? challenge,
+        origin: o.origin ?? init.origin,
+        crossOrigin: o.crossOrigin ?? false,
+      }),
+    );
+  const nextCount = (o: SoftCeremonyOverrides): number => {
+    if (o.signCount !== undefined) return o.signCount;
+    if (counter === null) return 0;
+    counter += 1;
+    return counter;
+  };
+
+  return {
+    credentialId,
+    async create(options, o = {}) {
+      userHandle = options.user.id;
+      const authData = concat(
+        await sha256(new TextEncoder().encode(o.rpId ?? options.rp.id)),
+        Uint8Array.of(o.flags ?? FLAG_UP | FLAG_UV | FLAG_AT),
+        u32(o.signCount ?? counter ?? 0),
+        new Uint8Array(16),
+        Uint8Array.of(rawId.length >> 8, rawId.length & 0xff),
+        rawId,
+        cose,
+      );
+      const attestationObject = cborEncode(
+        new Map<string, CborValue>([
+          ['fmt', 'none'],
+          ['attStmt', new Map()],
+          ['authData', authData],
+        ]),
+      );
+      return {
+        id: credentialId,
+        rawId: credentialId,
+        type: 'public-key',
+        response: {
+          clientDataJSON: base64Url(clientData('webauthn.create', options.challenge, o)),
+          attestationObject: base64Url(attestationObject),
+          transports: ['internal', 'hybrid'],
+        },
+      };
+    },
+    async get(options, o = {}) {
+      const authData = concat(
+        await sha256(new TextEncoder().encode(o.rpId ?? options.rpId)),
+        Uint8Array.of(o.flags ?? FLAG_UP | FLAG_UV),
+        u32(nextCount(o)),
+      );
+      const data = clientData('webauthn.get', options.challenge, o);
+      const signed = concat(authData, await sha256(data));
+      const signature = rsa
+        ? new Uint8Array(await crypto.subtle.sign('RSASSA-PKCS1-v1_5', pair.privateKey, signed))
+        : ecdsaRawToDer(
+            new Uint8Array(
+              await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, pair.privateKey, signed),
+            ),
+          );
+      const handle = o.userHandle === undefined ? userHandle : o.userHandle;
+      return {
+        id: credentialId,
+        rawId: credentialId,
+        type: 'public-key',
+        response: {
+          clientDataJSON: base64Url(data),
+          authenticatorData: base64Url(authData),
+          signature: base64Url(signature),
+          userHandle: handle,
+        },
+      };
+    },
+  };
+}

package/src/subject-target.ts

@@ -0,0 +1,73 @@
+// `authSubjectTarget()`: the identity tables this package owns, as a subject target a
+// `defineSubject({ targets })` lists — structural, so `@ultimat3/jobs` imports nothing from here.
+// Exports the `x_users` row (never a digest or the sealed TOTP seed); erases the user, which
+// cascades their sessions and linked accounts, plus their API keys and pending verifications.
+
+import type { PgExecutor } from '@ultimat3/core';
+
+/** The subject as a target is handed it: the key asked for, and the subject's row read fresh. */
+export interface AuthSubjectRef {
+  readonly key: string;
+  readonly row: Readonly<Record<string, unknown>>;
+}
+
+export interface AuthSubjectTargetOptions {
+  readonly executor: PgExecutor;
+  /**
+   * The `x_users.id` the subject is: `({ row }) => String(row.userId)` for a membership row that
+   * carries it. `undefined` is a subject with no identity here, and touches nothing.
+   */
+  readonly user: (subject: AuthSubjectRef) => string | undefined;
+}
+
+type Cell = string | number | boolean | null;
+
+export interface AuthSubjectTarget {
+  readonly name: 'x_users';
+  readonly columns: readonly string[];
+  exportPage(
+    subject: AuthSubjectRef,
+    cursor: string | null,
+    size: number,
+  ): Promise<{ readonly rows: readonly Readonly<Record<string, Cell>>[]; readonly cursor: null }>;
+  erase(subject: AuthSubjectRef, size: number): Promise<number>;
+}
+
+/** What leaves in an export. `password_hash`, `mfa_secret` and the recovery digests never do. */
+export const AUTH_SUBJECT_COLUMNS = [
+  'id',
+  'email',
+  'email_verified_at',
+  'roles',
+  'created_at',
+] as const;
+
+const SQL_USER = `select id::text as id, email, email_verified_at::text as email_verified_at,
+  array_to_string(roles, ',') as roles, created_at::text as created_at
+  from x_users where id = $1::uuid`;
+const SQL_API_KEYS = 'delete from x_api_keys where user_id = $1::uuid';
+const SQL_VERIFICATIONS = `delete from x_verifications
+  where identifier = (select email from x_users where id = $1::uuid)`;
+// Sessions and accounts reference the user `on delete cascade` (`tables.ts`): one statement.
+const SQL_USER_DELETE = 'delete from x_users where id = $1::uuid returning id';
+
+export function authSubjectTarget(options: AuthSubjectTargetOptions): AuthSubjectTarget {
+  const { executor } = options;
+  return {
+    name: 'x_users',
+    columns: AUTH_SUBJECT_COLUMNS,
+    async exportPage(subject) {
+      const id = options.user(subject);
+      if (id === undefined) return { rows: [], cursor: null };
+      const rows = await executor.query<Record<string, Cell>>(SQL_USER, [id]);
+      return { rows, cursor: null };
+    },
+    async erase(subject) {
+      const id = options.user(subject);
+      if (id === undefined) return 0;
+      await executor.query(SQL_API_KEYS, [id]);
+      await executor.query(SQL_VERIFICATIONS, [id]);
+      return (await executor.query(SQL_USER_DELETE, [id])).length;
+    },
+  };
+}