@ultimat3/auth 22.15.0 → 24.0.0

package/src/adapter.ts

@@ -22,7 +22,10 @@ export interface AuthUser {
    * the operator's identity away. Empty for almost every account.
    */
   readonly scopes: readonly string[];
-  /** Base32 TOTP secret, or `null` when MFA is not enrolled. */
+  /**
+   * The TOTP secret AS STORED — sealed (`mfa-secret.ts`), never base32 — or `null` when MFA is
+   * not enrolled. Only `openTotpSecret` turns it into something a code can be checked against.
+   */
   readonly mfaSecret: string | null;
   readonly recoveryCodeHashes: readonly string[];
   /**
@@ -71,14 +74,40 @@ export interface UserStore {
   createUser(input: CreateUserInput): Promise<AuthUser>;
   updateUser(id: string, patch: UserPatch): Promise<AuthUser | null>;
   /**
-   * Optional so an adapter written against 1.2's seam still compiles; both shipped adapters
-   * implement it, and `directory.ts` answers `X_NOT_IMPLEMENTED` with the method name when one
-   * does not. The alternative was a required member, which is a breaking change to every
-   * third-party `AuthAdapter` for a capability most of them will never be asked for.
+   * Required, like every member of the seam: an adapter that lacks one is a compile error at the
+   * `defineAuth({ adapter })` it is handed to, never an `X_NOT_IMPLEMENTED` at the first SCIM
+   * lookup in production. Exact match on the stored string, `null` when nobody carries it.
+   */
+  findUserByExternalId(externalId: string): Promise<AuthUser | null>;
+  /**
+   * Enumeration — a quarterly access review needs it. Ordered by email ascending; disabled members
+   * are left out unless `query.includeDisabled` is `true`.
    */
-  findUserByExternalId?(externalId: string): Promise<AuthUser | null>;
-  /** Enumeration, which nothing in the seam could do — a quarterly access review needs it. */
-  listUsersByOrg?(orgId: string, query?: UserQuery): Promise<readonly AuthUser[]>;
+  listUsersByOrg(orgId: string, query?: UserQuery): Promise<readonly AuthUser[]>;
+  /**
+   * Every user holding a second-factor secret, with the value exactly as stored, ordered by id.
+   * The one enumeration `sealMfaSecrets` needs: it cannot seal what it cannot find, and whether a
+   * stored value is sealed is core's `isSealed` to say — never a `like` in an adapter.
+   */
+  listUsersWithMfaSecret(): Promise<readonly StoredMfaSecret[]>;
+  /**
+   * Compare-and-set on one user's stored secret: write `next` only while the row still holds
+   * `expected`, in ONE atomic step, and answer whether it did. What `sealMfaSecrets` writes
+   * through — a user who re-enrolled since the value was read must keep the NEW secret, and a
+   * plain write would put the old one back, sealed.
+   */
+  replaceMfaSecret(userId: string, expected: string, next: string): Promise<boolean>;
+  /**
+   * Remove one recovery-code hash from one user, and answer whether it was there — in ONE atomic
+   * step. Single-use is a storage guarantee, exactly as `takeVerification`'s is: two concurrent
+   * redemptions of one code must not both find it, which a read followed by a write lets happen.
+   */
+  consumeRecoveryCode(userId: string, codeHash: string): Promise<boolean>;
+}
+
+export interface StoredMfaSecret {
+  readonly userId: string;
+  readonly mfaSecret: string;
 }
 
 export interface AuthSession {
@@ -115,17 +144,15 @@ export interface SessionStore {
   /**
    * Every session this user holds, including the caller's own. `deleteOtherSessions` cannot
    * express it — there is no session id to keep — and a password change or a disable has to.
-   *
-   * Optional for the reason `findUserByExternalId` is: adding a required member to a shipped
-   * seam breaks every third-party adapter. `revocation.ts` refuses with `X_NOT_IMPLEMENTED` and
-   * names the method when an adapter has not got it.
+   * Returns how many were killed.
    */
-  deleteSessionsForUser?(userId: string): Promise<number>;
+  deleteSessionsForUser(userId: string): Promise<number>;
   /**
    * Everything issued before an instant. The credential-compromise sweep: rotate the secret,
-   * then kill everything minted under the old one, without enumerating users.
+   * then kill everything minted under the old one, without enumerating users. Strictly before:
+   * a session created AT the instant survives.
    */
-  deleteSessionsCreatedBefore?(before: Date): Promise<number>;
+  deleteSessionsCreatedBefore(before: Date): Promise<number>;
 }
 
 export interface AuthAccount {
@@ -218,5 +245,5 @@ export interface AuthAdapter
    * exactly the sessions it was run for. So it joins through `x_users`, which is why it sits on
    * the full adapter rather than on `SessionStore`.
    */
-  deleteSessionsForOrg?(orgId: string): Promise<number>;
+  deleteSessionsForOrg(orgId: string): Promise<number>;
 }

package/src/api-key-resolver.ts

@@ -0,0 +1,55 @@
+// Single responsibility: a presented API key → who is calling, in the shape a bearer mount and an
+// MCP endpoint both take as `resolveToken`. `verifyApiKey` answers a record or throws; this is the
+// one place that turns its ONE rejection into the `null` those surfaces answer 401 for — and
+// leaves everything else a throw, because "the database is down" is not "your key is wrong".
+
+import { type Clock, isUltimateError, systemClock } from '@ultimat3/core';
+import {
+  type ApiKeyActorOptions,
+  type ApiKeyVerifyStore,
+  apiKeyActor,
+  verifyApiKey,
+} from './api-keys';
+import type { PolicyActor } from './policy-bridge';
+
+/**
+ * What a verified key resolves to. Structurally `@ultimat3/http`'s `BearerCaller` and
+ * `@ultimat3/mcp`'s `ResolvedToken` — declared here because this tier can import neither.
+ */
+export interface ApiKeyCaller {
+  /** The agent actor: the key's org, and its scopes as the permissions a policy reads. */
+  readonly actor: PolicyActor;
+  /** The scopes the ACTOR carries — the key's, cut by its owner's grants. The mount's scope map is cut by these. */
+  readonly scopes: ReadonlySet<string>;
+}
+
+export interface ApiKeyResolverOptions extends ApiKeyActorOptions {
+  readonly clock?: Clock | undefined;
+}
+
+/**
+ * `resolveToken: apiKeyResolver(() => keys)` on `defineApi({ http: { mounts } })` and on
+ * `defineAppMcp()` — one resolver for both.
+ *
+ * `store` is a THUNK, read when a token is presented and never captured: a mount is declared when
+ * its module is evaluated, and `new BuiltinAdapter()` takes the process's database client, which
+ * boot installs later. `() => new MemoryAdapter()` would be a new, empty store per request — hold
+ * the instance and return it.
+ */
+export function apiKeyResolver(
+  store: () => ApiKeyVerifyStore,
+  options: ApiKeyResolverOptions = {},
+): (token: string) => Promise<ApiKeyCaller | null> {
+  return async (token) => {
+    try {
+      const verified = await verifyApiKey(store(), token, options.clock ?? systemClock);
+      const actor = apiKeyActor(verified, options);
+      return { actor, scopes: new Set(actor.scopes) };
+    } catch (thrown) {
+      // Every way a key can be wrong is this one code, by `verifyApiKey`'s own design: a caller
+      // that could tell "revoked" from "unknown" could enumerate ids.
+      if (isUltimateError(thrown) && thrown.code === 'X_API_KEY_INVALID') return null;
+      throw thrown;
+    }
+  };
+}

package/src/api-keys.ts

@@ -5,10 +5,10 @@
 // lookup happens by the non-secret id so the secret never appears in a query, an index or a log.
 
 import { type Clock, randomHex, systemClock } from '@ultimat3/core';
-import type { ApiKeyStore, AuthApiKeyRecord } from './adapter';
-import { apiKeyEnvInvalid, apiKeyInvalid } from './errors';
+import type { ApiKeyStore, AuthApiKeyRecord, AuthUser, UserStore } from './adapter';
+import { apiKeyEnvInvalid, apiKeyInvalid, apiKeyScopeWildcard } from './errors';
 import type { PolicyActor } from './policy-bridge';
-import { actorFromApiKey } from './policy-bridge';
+import { actorFromApiKey, isWildcardScope } from './policy-bridge';
 import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
 
 export const API_KEY_NAMESPACE = 'ult';
@@ -63,6 +63,8 @@ const API_KEY_ENV = /^[a-z0-9-]+$/;
 
 export function issueApiKey(input: IssueApiKeyInput): IssuedApiKey {
   if (!API_KEY_ENV.test(input.env)) throw apiKeyEnvInvalid(input.env);
+  const wildcard = input.scopes.find(isWildcardScope);
+  if (wildcard !== undefined) throw apiKeyScopeWildcard(wildcard);
   const clock = input.clock ?? systemClock;
   // Hex, not base64url: the id sits between two `_` delimiters and must not contain one.
   const id = randomHex(8);
@@ -85,16 +87,31 @@ export function issueApiKey(input: IssueApiKeyInput): IssuedApiKey {
   };
 }
 
+/** What verification reads: the key, and the user row of whoever owns it. */
+export type ApiKeyVerifyStore = ApiKeyStore & Pick<UserStore, 'findUserById'>;
+
+export interface VerifiedApiKey {
+  readonly record: AuthApiKeyRecord;
+  /** The user the key was issued to, as the row reads NOW. `null` for a key no user owns. */
+  readonly owner: AuthUser | null;
+}
+
 /**
- * Every rejection — malformed, unknown, revoked, expired, wrong secret — throws the same
- * `X_API_KEY_INVALID`. A caller that can tell "revoked" from "unknown" can enumerate ids.
+ * Every rejection — malformed, unknown, revoked, expired, wrong secret, an owner who is gone or
+ * disabled — throws the same `X_API_KEY_INVALID`. A caller that can tell "revoked" from "unknown"
+ * can enumerate ids.
+ *
+ * The owner is re-read on every verification, for the reason `authenticate` re-reads the user on
+ * every request: a key is the owner's credential, so disabling the owner has to stop it on its
+ * next use — not whenever somebody remembers to revoke it. The read happens only after the secret
+ * matched, so an unauthenticated guess costs no second lookup.
  */
 export async function verifyApiKey(
-  store: ApiKeyStore,
+  store: ApiKeyVerifyStore,
   plaintext: string,
   clock: Clock = systemClock,
-): Promise<AuthApiKeyRecord> {
-  const parsed = parseApiKey(plaintext);
+): Promise<VerifiedApiKey> {
+  const parsed = typeof plaintext === 'string' ? parseApiKey(plaintext) : null;
   if (parsed === null) throw apiKeyInvalid();
   const record = await store.findApiKeyById(parsed.id);
   if (record === null) throw apiKeyInvalid();
@@ -104,8 +121,12 @@ export async function verifyApiKey(
     throw apiKeyInvalid();
   }
   if (!timingSafeEqual(sha256Hex(parsed.secret), record.keyHash)) throw apiKeyInvalid();
+  const owner = record.userId === null ? null : await store.findUserById(record.userId);
+  if (record.userId !== null && (owner === null || owner.disabledAt !== null)) {
+    throw apiKeyInvalid();
+  }
   await store.touchApiKey(record.id, now);
-  return record;
+  return { record, owner };
 }
 
 export async function revokeApiKey(
@@ -116,9 +137,35 @@ export async function revokeApiKey(
   return await store.revokeApiKey(id, clock.now());
 }
 
-/** The agent actor for a verified key. Scopes in, scopes out — nothing is added. */
-export function apiKeyActor(record: AuthApiKeyRecord): PolicyActor {
-  return actorFromApiKey(record);
+/**
+ * What an owner may do, as far as this package can read it: the row's direct `permissions` and
+ * `scopes`. ROLES are not here — expanding a role to permissions is `@ultimat3/policy`'s, which
+ * this tier cannot import — so an app whose users hold roles passes `grantsOf` and expands them.
+ */
+export const directGrants = (owner: AuthUser): readonly string[] => [
+  ...owner.permissions,
+  ...owner.scopes,
+];
+
+export interface ApiKeyActorOptions {
+  /**
+   * The owner's effective grants, which a key's scopes are cut down to. Defaults to
+   * `directGrants`. A role-based app passes its own expansion, e.g.
+   * `(owner) => [...directGrants(owner), ...owner.roles.flatMap((role) => ROLE_GRANTS[role] ?? [])]`.
+   */
+  readonly grantsOf?: ((owner: AuthUser) => readonly string[]) | undefined;
+}
+
+/**
+ * The agent actor for a verified key. Nothing is added: the key's scopes, minus any wildcard,
+ * minus — for a key a user owns — whatever that user could not do themselves.
+ */
+export function apiKeyActor(
+  verified: VerifiedApiKey,
+  options: ApiKeyActorOptions = {},
+): PolicyActor {
+  const { record, owner } = verified;
+  return actorFromApiKey(record, owner === null ? null : (options.grantsOf ?? directGrants)(owner));
 }
 
 /** Safe to render in a dashboard or return from an MCP tool: no hash, no secret. */

package/src/auth.ts

@@ -7,8 +7,11 @@ import { type Clock, systemClock, uuid } from '@ultimat3/core';
 import { t } from '@ultimat3/schema';
 import type { AuthAdapter, AuthSession, AuthUser } from './adapter';
 import { normaliseEmail } from './email';
-import { mfaRequired, mfaRequiredUnenforceable, sessionUnknown } from './errors';
+import { mfaRequiredUnenforceable, sessionUnknown } from './errors';
 import { installedAuthLimiter } from './limiter-install';
+import { openLoginAttempt } from './login-attempt';
+import { createTotpReplayGuard, type TotpReplayGuard } from './mfa';
+import { mfaChallengeRequired } from './mfa-challenge';
 import type { OAuthProviderId } from './oauth';
 import {
   checkPasswordStrength,
@@ -26,9 +29,7 @@ import {
   assertAuthLimiterPolicy,
   createAuthLimiter,
   DEFAULT_AUTH_RATE_LIMIT,
-  ipKey,
   loginFailed,
-  orgKey,
   orgRateLimit,
 } from './rate-limit';
 import {
@@ -147,6 +148,12 @@ export interface AuthConfigInput {
    */
   readonly orgLimiter?: AuthLimiter | undefined;
   readonly mfa?: Partial<AuthMfaPolicy> | undefined;
+  /**
+   * Which TOTP steps have been spent, read and written by `completeMfa`. Omitted means
+   * `createTotpReplayGuard()` — one process' worth of memory, so a code is single-use per replica;
+   * a fleet that needs it single-use everywhere passes a shared guard with the same two methods.
+   */
+  readonly totpReplay?: TotpReplayGuard | undefined;
   /**
    * The OAuth providers this app serves login routes for. Defaults to `[]` — an empty list is
    * "no OAuth", and every `/auth/oauth/<id>` answers `X_OAUTH_PROVIDER_UNKNOWN`. Never the live
@@ -168,6 +175,7 @@ export interface Auth {
   readonly orgRateLimit: AuthRateLimitPolicy;
   readonly orgLimiter: AuthLimiter;
   readonly mfa: AuthMfaPolicy;
+  readonly totpReplay: TotpReplayGuard;
   readonly providers: readonly OAuthProviderId[];
   readonly link: OAuthLinkPolicy;
 }
@@ -224,6 +232,7 @@ export function defineAuth(config: AuthConfigInput): Auth {
     orgRateLimit: orgLimiter.policy,
     orgLimiter,
     mfa,
+    totpReplay: config.totpReplay ?? createTotpReplayGuard(),
     // BREAKING (majors only): the default is `[]`, never the live registry.
     //
     // It was `oauthProviderIds()`, so `defineAuth({ providers })`'s own documented purpose — the
@@ -278,50 +287,46 @@ export interface LoginResult {
  * Every failure path here throws `loginFailed()` — unknown address, wrong password and
  * disabled account are indistinguishable in both message and duration. The only paths that
  * throw something else are lockout (before any work) and MFA (after the password is proven).
+ *
+ * The attempt is RESERVED against every bucket before the KDF and settled after it: a burst of
+ * concurrent guesses spends the allowance as it arrives, so at most `maxAttempts` of them ever
+ * reach the hash. A failure leaves its reservations standing — they are the recorded failure.
  */
 export async function login(auth: Auth, input: LoginInput): Promise<LoginResult> {
-  const account = accountKey(input.email);
   const ip = input.ip ?? null;
-  await auth.limiter.assertAllowed(account);
-  if (ip !== null) await auth.limiter.assertAllowed(ipKey(ip));
+  const attempt = await openLoginAttempt(auth, accountKey(input.email), ip);
 
-  const user = await auth.adapter.findUserByEmail(normaliseEmail(input.email));
-  // The tenant bucket can only be consulted once the address resolves to an org, which is still
-  // before the KDF runs — the expensive half of this function — so it costs one map lookup and
-  // caps a spray that per-IP and per-account buckets both let through.
-  const org = user?.orgId ?? null;
-  if (org !== null) await auth.orgLimiter.assertAllowed(orgKey(org));
-
-  const usable = user !== null && user.disabledAt === null;
-  const verification = await verifyPassword({
-    hash: usable ? user.passwordHash : null,
-    password: input.password,
-    params: auth.password.params,
-  });
-
-  if (!verification.ok || user === null) {
-    await auth.limiter.recordFailure(account);
-    if (ip !== null) await auth.limiter.recordFailure(ipKey(ip));
-    if (org !== null) await auth.orgLimiter.recordFailure(orgKey(org));
-    throw loginFailed();
+  let user: AuthUser | null;
+  let verification: Awaited<ReturnType<typeof verifyPassword>>;
+  try {
+    user = await auth.adapter.findUserByEmail(normaliseEmail(input.email));
+    // The tenant bucket can only be joined once the address resolves to an org, which is still
+    // before the KDF runs — the expensive half of this function — and it caps a spray that
+    // per-IP and per-account buckets both let through.
+    await attempt.reserveOrg(user?.orgId ?? null);
+    verification = await verifyPassword({
+      hash: user !== null && user.disabledAt === null ? user.passwordHash : null,
+      password: input.password,
+      params: auth.password.params,
+    });
+  } catch (thrown) {
+    // No verdict — a shed KDF, a store that is down, a tenant cap — is not a failed guess.
+    await attempt.release();
+    throw thrown;
   }
 
-  await auth.limiter.recordSuccess(account);
-  // ONLY the account bucket is cleared. The ACCOUNT window belongs to one person, so a success
-  // proves the typos before it were theirs and clearing it is what stops a typo costing a lockout.
-  //
-  // Neither the IP nor the tenant bucket is cleared, and it is the same argument for both: they
-  // count traffic from a SHARED source, so a success is not evidence the failures beside it were
-  // benign. `recordSuccess(ipKey(ip))` used to run here and deleted the whole address bucket —
-  // which made it inert against the attack it exists for. A credential-stuffing run never spends
-  // `maxAttempts` guesses on one account, so the per-account bucket never fires; the address
-  // bucket is the only one that sees the pattern, and `4 wrong guesses + 1 login to an account
-  // the attacker owns, repeat` wiped it every fifth request. Measured: 5 guesses to
-  // `X_ACCOUNT_LOCKED` without the reset, 160 and never locked with it.
+  if (!verification.ok || user === null) throw loginFailed();
+
+  // ONLY the account bucket is cleared, and only once nothing more is owed. The ACCOUNT window
+  // belongs to one person, so a success proves the typos before it were theirs. The address and
+  // the tenant count traffic from a SHARED source, so a success is not evidence the failures
+  // beside it were benign — clearing the address bucket made it inert against stuffing (`4 wrong
+  // guesses + 1 login to an account the attacker owns, repeat` never locked).
   //
-  // The cost is a shared NAT accumulating failures from unrelated people, which is exactly what
-  // `windowMs` bounds — and `X_ACCOUNT_LOCKED`'s `fix:` already names `recordSuccess(<key>)` as
-  // the deliberate manual escape for that case.
+  // With a second factor still owed NOTHING is cleared: a caller holding the password would
+  // otherwise wipe the count of wrong codes with every repeat of this first leg.
+  if (user.mfaSecret === null) await attempt.succeed();
+  else await attempt.release();
 
   // Parameters were raised since this hash was written: upgrade it now, while we hold the
   // plaintext. This is the only moment it is possible without asking the user for anything.
@@ -331,11 +336,9 @@ export async function login(auth: Auth, input: LoginInput): Promise<LoginResult>
     });
   }
 
-  // Password proven, second factor not. No half-authenticated session is written here and nothing
-  // is persisted to correlate the two legs — finishing MFA is the app's, and `X_MFA_REQUIRED`'s
-  // `fix:` is the instruction. The framework's own second leg is blocked on a sealed pending-MFA
-  // credential; the constraint is written down in `packages/auth/CLAUDE.md`.
-  if (user.mfaSecret !== null) throw mfaRequired(user.id);
+  // Password proven, second factor not. No half-authenticated session is written: the sealed
+  // challenge in the error is the only thing that carries the first leg to `completeMfa`.
+  if (user.mfaSecret !== null) throw await mfaChallengeRequired(auth, user.id);
 
   const issued = await createSession(auth.sessions, {
     userId: user.id,

package/src/builtin-adapter-violation.ts

@@ -0,0 +1,43 @@
+// Single responsibility: an `x_users` unique violation as the code `MemoryAdapter` answers. One
+// duplicate signup must not be `X_AUTH_WRITE_FAILED` under `x dev` and `X_DB_UNIQUE_VIOLATION` in
+// production: an app that branches on the code passes its tests and misses on Postgres.
+
+import { stringField } from '@ultimat3/core';
+import { SQLSTATE, sqlState } from '@ultimat3/db';
+import { type AuthError, authUniqueViolation } from './errors';
+
+/**
+ * The constraints `tables.ts` declares on `x_users`, by the names Postgres gives them. Closed: a
+ * unique index an app added to the table is the app's, and its violation travels on as the
+ * database error it is rather than being reported as a column it does not cover.
+ */
+const X_USERS_UNIQUE_COLUMNS: ReadonlyMap<string, string> = new Map([
+  ['x_users_email_key', 'email'],
+  ['x_users_external_id_key', 'external_id'],
+  ['x_users_pkey', 'id'],
+]);
+
+/** How deep `DbError.sourceError` may nest before the read stops — db's own bound. */
+const MAX_WRAPS = 4;
+
+/** The constraint the server named. db's wrap keeps the driver error on `sourceError`. */
+function violatedConstraint(error: unknown): string | undefined {
+  let value = error;
+  for (let depth = 0; depth < MAX_WRAPS && value !== undefined && value !== null; depth += 1) {
+    const constraint = stringField(value, 'constraint');
+    if (constraint !== undefined) return constraint;
+    value = typeof value === 'object' ? (value as { sourceError?: unknown }).sourceError : null;
+  }
+  return undefined;
+}
+
+/**
+ * `undefined` for everything that is not one of `x_users`' own unique constraints, so the caller
+ * rethrows what it caught. The SQLSTATE is read through db's `sqlState`, which decides by where
+ * the error came from, never by the shape of a `code` field.
+ */
+export function usersUniqueViolation(operation: string, error: unknown): AuthError | undefined {
+  if (sqlState(error) !== SQLSTATE.uniqueViolation) return undefined;
+  const column = X_USERS_UNIQUE_COLUMNS.get(violatedConstraint(error) ?? '');
+  return column === undefined ? undefined : authUniqueViolation(operation, 'x_users', column);
+}

package/src/builtin-adapter.ts

@@ -3,6 +3,7 @@
 // drive it without a database. Rows arrive as `unknown` and are read through the small typed
 // readers below — no `any`, and a column rename fails loudly instead of producing `undefined`.
 
+import { type Clock, systemClock } from '@ultimat3/core';
 import { type DbClient, db, sql } from '@ultimat3/db';
 import type {
   AuthAccount,
@@ -13,9 +14,11 @@ import type {
   AuthVerification,
   CreateUserInput,
   SessionPatch,
+  StoredMfaSecret,
   UserPatch,
   UserQuery,
 } from './adapter';
+import { usersUniqueViolation } from './builtin-adapter-violation';
 import { authWriteFailed } from './errors';
 
 type Row = Readonly<Record<string, unknown>>;
@@ -117,9 +120,24 @@ const toApiKey = (row: Row): AuthApiKeyRecord => ({
 export class BuiltinAdapter implements AuthAdapter {
   readonly name = 'builtin-postgres';
   readonly #db: DbClient;
+  readonly #clock: Clock;
 
-  constructor(client: DbClient = db()) {
+  /**
+   * `clock` is the one `MemoryAdapter` takes, for the same stamp: hand over the clock
+   * `defineAuth` was given, so a redemption is dated by the clock that judged its expiry.
+   */
+  constructor(client: DbClient = db(), clock: Clock = systemClock) {
     this.#db = client;
+    this.#clock = clock;
+  }
+
+  /** A write to `x_users`, with the table's own unique violations answered as this package's. */
+  async #writeUser(operation: string, statement: Parameters<DbClient['one']>[0]) {
+    try {
+      return await this.#db.one<Row>(statement);
+    } catch (error) {
+      throw usersUniqueViolation(operation, error) ?? error;
+    }
   }
 
   async findUserByEmail(email: string): Promise<AuthUser | null> {
@@ -133,13 +151,16 @@ export class BuiltinAdapter implements AuthAdapter {
   }
 
   async createUser(input: CreateUserInput): Promise<AuthUser> {
-    const row = await this.#db.one<Row>(sql`
+    const row = await this.#writeUser(
+      'createUser',
+      sql`
       insert into x_users (id, email, password_hash, org_id, roles, scopes, external_id,
                            created_at)
       values (${input.id}, ${input.email}, ${input.passwordHash}, ${input.orgId},
               ${[...input.roles]}, ${[...(input.scopes ?? [])]}, ${input.externalId ?? null},
               ${input.createdAt})
-      returning *`);
+      returning *`,
+    );
     // An empty `returning` means no row landed. A user fabricated from `{}` would travel back
     // out of `register()` as a successful registration with no identity in it.
     if (row === null) throw authWriteFailed('createUser', 'x_users');
@@ -147,7 +168,9 @@ export class BuiltinAdapter implements AuthAdapter {
   }
 
   async updateUser(id: string, patch: UserPatch): Promise<AuthUser | null> {
-    const row = await this.#db.one<Row>(sql`
+    const row = await this.#writeUser(
+      'updateUser',
+      sql`
       update x_users set
         password_hash = case when ${patch.passwordHash !== undefined}
           then ${patch.passwordHash ?? null} else password_hash end,
@@ -170,10 +193,39 @@ export class BuiltinAdapter implements AuthAdapter {
         external_id = case when ${patch.externalId !== undefined}
           then ${patch.externalId ?? null} else external_id end
       where id = ${id}
-      returning *`);
+      returning *`,
+    );
     return row === null ? null : toUser(row);
   }
 
+  async listUsersWithMfaSecret(): Promise<readonly StoredMfaSecret[]> {
+    const rows = await this.#db.query<Row>(
+      sql`select id, mfa_secret from x_users where mfa_secret is not null order by id`,
+    );
+    return rows.map((row) => ({ userId: text(row, 'id'), mfaSecret: text(row, 'mfa_secret') }));
+  }
+
+  async replaceMfaSecret(userId: string, expected: string, next: string): Promise<boolean> {
+    const row = await this.#db.one<Row>(sql`
+      update x_users set mfa_secret = ${next}
+       where id = ${userId} and mfa_secret = ${expected}
+      returning id`);
+    return row !== null;
+  }
+
+  /**
+   * One conditional UPDATE: the row is locked, and the `where` is re-checked against the version
+   * a concurrent redemption just committed, so the second of two finds the hash already gone.
+   */
+  async consumeRecoveryCode(userId: string, codeHash: string): Promise<boolean> {
+    const row = await this.#db.one<Row>(sql`
+      update x_users
+         set recovery_code_hashes = array_remove(recovery_code_hashes, ${codeHash})
+       where id = ${userId} and ${codeHash} = any(recovery_code_hashes)
+      returning id`);
+    return row !== null;
+  }
+
   async findUserByExternalId(externalId: string): Promise<AuthUser | null> {
     const row = await this.#db.one<Row>(
       sql`select * from x_users where external_id = ${externalId}`,
@@ -308,6 +360,9 @@ export class BuiltinAdapter implements AuthAdapter {
   }
 
   /**
+   * `consumed_at` is the injected clock's instant, bound — never the server's `now()`, which made
+   * the stamp the one instant in this package no test could move and no `Clock` agreed with.
+   *
    * One conditional UPDATE, and every part of the predicate is load-bearing. `consumed_at is null`
    * on the UPDATE itself is what makes redemption single-use under concurrency — inside the
    * subselect alone, two racing redemptions both pick the row and both consume it. `token_hash`
@@ -324,7 +379,7 @@ export class BuiltinAdapter implements AuthAdapter {
     tokenHash: string,
   ): Promise<AuthVerification | null> {
     const row = await this.#db.one<Row>(sql`
-      update x_verifications set consumed_at = now()
+      update x_verifications set consumed_at = ${this.#clock.now()}
       where consumed_at is null and id = (
         select id from x_verifications
         where purpose = ${purpose} and identifier = ${identifier}

package/src/client-scope.ts

@@ -5,7 +5,7 @@
 
 import type { Actor } from '@ultimat3/core';
 import { logger } from '@ultimat3/core';
-import { clientScopeSecretShort } from './errors';
+import { AuthError } from './errors';
 
 /** 128 bits: a scope only has to differ between principals, never to authenticate anyone. */
 const SCOPE_HEX_CHARS = 32;
@@ -46,7 +46,13 @@ function scopeKey(options: ClientScopeOptions): string {
     // The same floor as the env path below: an explicit key is a caller's value, so a short one is
     // refused rather than silently swapped for the process key.
     if (options.secret.length < MIN_SECRET_LENGTH) {
-      throw clientScopeSecretShort(options.secret.length, MIN_SECRET_LENGTH);
+      // Never its length: how long the key handed over is narrows a guess at it.
+      throw new AuthError({
+        code: 'X_CONFIG_INVALID',
+        cause: `clientScopeOf({ secret }) was passed a key shorter than the ${String(MIN_SECRET_LENGTH)} characters required, so the scope id would be keyed by a guessable secret`,
+        fix: 'omit secret so clientScopeOf reads SESSION_SECRET, or pass one generated with: openssl rand -hex 32',
+        meta: { option: 'secret', minLength: MIN_SECRET_LENGTH },
+      });
     }
     return options.secret;
   }

package/src/directory.ts

@@ -6,7 +6,6 @@
 
 import type { AuthUser, UserQuery } from './adapter';
 import type { Auth } from './auth';
-import { authNotImplemented } from './errors';
 
 /** Safe to render in an admin page, return from an MCP tool, or paste into a review ticket. */
 export interface AuthUserSummary {
@@ -45,21 +44,13 @@ export function describeUser(user: AuthUser): AuthUserSummary {
   };
 }
 
-const unsupported = (method: string, adapterName: string) =>
-  authNotImplemented(
-    `${adapterName}.${method}()`,
-    `implement ${method}() on your AuthAdapter — BuiltinAdapter (Postgres) and MemoryAdapter are the two reference implementations, in packages/auth/src`,
-  );
-
 /** Every member of one org, as summaries. `query.role` narrows it to one role's holders. */
 export async function listOrgUsers(
   auth: Auth,
   orgId: string,
   query?: UserQuery,
 ): Promise<readonly AuthUserSummary[]> {
-  const list = auth.adapter.listUsersByOrg?.bind(auth.adapter);
-  if (list === undefined) throw unsupported('listUsersByOrg', auth.adapter.name);
-  return (await list(orgId, query)).map(describeUser);
+  return (await auth.adapter.listUsersByOrg(orgId, query)).map(describeUser);
 }
 
 /**
@@ -71,7 +62,5 @@ export async function findUserByExternalId(
   auth: Auth,
   externalId: string,
 ): Promise<AuthUser | null> {
-  const find = auth.adapter.findUserByExternalId?.bind(auth.adapter);
-  if (find === undefined) throw unsupported('findUserByExternalId', auth.adapter.name);
-  return await find(externalId);
+  return await auth.adapter.findUserByExternalId(externalId);
 }