@ultimat3/auth 23.0.0 → 25.0.0

package/src/adapter.ts

@@ -1,7 +1,7 @@
 // Single responsibility: the persistence seam. `AuthAdapter` is the one interface auth talks
 // to, split into per-concern stores so a test (or a caller) can satisfy just the slice it uses.
 // Better Auth binds here — it is an adapter implementation, not a dependency. The blessed
-// default is `BuiltinAdapter` in `builtin-adapter.ts`; the DDL it expects is in `tables.ts`.
+// default is `PostgresAuthAdapter` in `builtin-adapter.ts`; the DDL it expects is in `tables.ts`.
 
 export interface AuthUser {
   readonly id: string;
@@ -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`.
+   */
+  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.
    */
-  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[]>;
+  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 {
@@ -108,6 +137,10 @@ export interface SessionStore {
   getSession(id: string): Promise<AuthSession | null>;
   createSession(session: AuthSession): Promise<AuthSession>;
   updateSession(id: string, patch: SessionPatch): Promise<AuthSession | null>;
+  /**
+   * Remove one session and answer whether THIS call removed it, in one atomic step: `rotateSession`
+   * treats `true` as its claim on the id, so two concurrent deletes must not both answer `true`.
+   */
   deleteSession(id: string): Promise<boolean>;
   /** Returns how many were killed — the "sign out everywhere else" number shown to the user. */
   deleteOtherSessions(userId: string, keepSessionId: string): Promise<number>;
@@ -115,17 +148,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 {
@@ -200,7 +231,7 @@ export interface ApiKeyStore {
 }
 
 /**
- * The full seam. One blessed implementation ships (`BuiltinAdapter`); Better Auth, or any
+ * The full seam. One blessed implementation ships (`PostgresAuthAdapter`); Better Auth, or any
  * other identity backend, binds by implementing this and nothing else changes upstream.
  */
 export interface AuthAdapter
@@ -218,5 +249,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

@@ -4,8 +4,12 @@
 // 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 { ApiKeyStore } from './adapter';
-import { apiKeyActor, verifyApiKey } from './api-keys';
+import {
+  type ApiKeyActorOptions,
+  type ApiKeyVerifyStore,
+  apiKeyActor,
+  verifyApiKey,
+} from './api-keys';
 import type { PolicyActor } from './policy-bridge';
 
 /**
@@ -15,11 +19,11 @@ import type { PolicyActor } from './policy-bridge';
 export interface ApiKeyCaller {
   /** The agent actor: the key's org, and its scopes as the permissions a policy reads. */
   readonly actor: PolicyActor;
-  /** The key's scopes — what the mount's scope map is cut by. */
+  /** 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 {
+export interface ApiKeyResolverOptions extends ApiKeyActorOptions {
   readonly clock?: Clock | undefined;
 }
 
@@ -28,18 +32,19 @@ export interface ApiKeyResolverOptions {
  * `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
+ * its module is evaluated, and `postgresAuthAdapter()` takes the process's database client, which
+ * boot installs later. `() => memoryAuthAdapter()` would be a new, empty store per request — hold
  * the instance and return it.
  */
 export function apiKeyResolver(
-  store: () => ApiKeyStore,
+  store: () => ApiKeyVerifyStore,
   options: ApiKeyResolverOptions = {},
 ): (token: string) => Promise<ApiKeyCaller | null> {
   return async (token) => {
     try {
-      const record = await verifyApiKey(store(), token, options.clock ?? systemClock);
-      return { actor: apiKeyActor(record), scopes: new Set(record.scopes) };
+      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.

package/src/api-keys.ts

@@ -4,12 +4,12 @@
 // evaluation a human does. The plaintext is shown once; only its SHA-256 is ever stored, and
 // 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 Clock, randomHex, systemClock, timingSafeEqual } from '@ultimat3/core';
+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 { randomToken, sha256Hex, timingSafeEqual } from './tokens';
+import { actorFromApiKey, isWildcardScope } from './policy-bridge';
+import { randomToken, sha256Hex } 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

@@ -3,12 +3,15 @@
 // (http, actions, jobs, MCP) authorizes on that and never on a session row, so there is one
 // identity shape in the framework and `@ultimat3/policy` is the only thing that reads it.
 
-import { type Clock, systemClock, uuid } from '@ultimat3/core';
+import { type Clock, systemClock, timingSafeEqual, uuidV7 } 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 { memoryTotpReplayGuard, type TotpReplayGuard } from './mfa';
+import { mfaChallengeRequired } from './mfa-challenge';
 import type { OAuthProviderId } from './oauth';
 import {
   checkPasswordStrength,
@@ -24,11 +27,9 @@ import {
   type AuthRateLimitPolicy,
   accountKey,
   assertAuthLimiterPolicy,
-  createAuthLimiter,
   DEFAULT_AUTH_RATE_LIMIT,
-  ipKey,
   loginFailed,
-  orgKey,
+  memoryAuthLimiter,
   orgRateLimit,
 } from './rate-limit';
 import {
@@ -40,7 +41,7 @@ import {
   sessionCookie,
   verifySession,
 } from './session';
-import { sha256Hex, timingSafeEqual } from './tokens';
+import { sha256Hex } from './tokens';
 
 // The projections safe to hand to a client or an MCP tool: no password hash, no TOTP secret,
 // no token hash. The private columns live in `adapter.ts` and never leave the server.
@@ -135,7 +136,7 @@ export interface AuthConfigInput {
   readonly password?: Partial<PasswordPolicy> | undefined;
   readonly rateLimit?: Partial<AuthRateLimitPolicy> | undefined;
   /**
-   * Where failed attempts are counted. Omitted means `createAuthLimiter`, which is one process'
+   * Where failed attempts are counted. Omitted means `memoryAuthLimiter`, which is one process'
    * worth of state — correct for dev and tests, and `maxAttempts × N` for N replicas. An app that
    * runs more than one declares `rateLimit.scope: 'shared'` and passes a limiter that says the
    * same, or `defineAuth` refuses here rather than at 3am on the first spray.
@@ -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
+   * `memoryTotpReplayGuard()` — 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;
 }
@@ -189,13 +197,13 @@ export function defineAuth(config: AuthConfigInput): Auth {
   // scaffolded app had to remember to build a shared limiter itself, which is the opposite of
   // what this framework promises — and `x new` scaffolds two replicas.
   const limiter =
-    config.limiter ?? installedAuthLimiter(rateLimit) ?? createAuthLimiter(clock, rateLimit);
+    config.limiter ?? installedAuthLimiter(rateLimit) ?? memoryAuthLimiter(clock, rateLimit);
   assertAuthLimiterPolicy(rateLimit, limiter);
   // The tenant bucket is a noisy-neighbour cap, not a credential-guessing allowance, so an app
   // that declares `scope: 'shared'` for its LOCKOUT is not also required to ship a shared limiter
   // for this one — per replica it approximates to `orgMaxAttempts × replicas`, which is a
   // throughput ceiling and discloses nothing. Only the LOCAL fallback is exempt, and exempting it
-  // is what buys that: `createAuthLimiter` always reports `'process'`, which is the one arm the
+  // is what buys that: `memoryAuthLimiter` always reports `'process'`, which is the one arm the
   // scope check would refuse. A limiter somebody else supplied — injected by the app or built by
   // the host's factory — is compared exactly as the general bucket's is, because a factory that
   // ignores the policy it was handed otherwise enforces numbers the app never declared while
@@ -203,7 +211,7 @@ export function defineAuth(config: AuthConfigInput): Auth {
   // is refused for one bucket and trusted for the other.
   const orgLimits = orgRateLimit(rateLimit);
   const suppliedOrgLimiter = config.orgLimiter ?? installedAuthLimiter(orgLimits);
-  const orgLimiter = suppliedOrgLimiter ?? createAuthLimiter(clock, orgLimits);
+  const orgLimiter = suppliedOrgLimiter ?? memoryAuthLimiter(clock, orgLimits);
   if (suppliedOrgLimiter !== undefined) assertAuthLimiterPolicy(orgLimits, suppliedOrgLimiter);
   // Read through a widened local on purpose: the field's type is the literal `false`, so this
   // branch is unreachable from TypeScript and reachable from every JS caller and every config
@@ -224,6 +232,7 @@ export function defineAuth(config: AuthConfigInput): Auth {
     orgRateLimit: orgLimiter.policy,
     orgLimiter,
     mfa,
+    totpReplay: config.totpReplay ?? memoryTotpReplayGuard(),
     // BREAKING (majors only): the default is `[]`, never the live registry.
     //
     // It was `oauthProviderIds()`, so `defineAuth({ providers })`'s own documented purpose — the
@@ -250,7 +259,7 @@ export interface RegisterInput {
 export async function register(auth: Auth, input: RegisterInput): Promise<AuthUser> {
   checkPasswordStrength(input.password, { policy: auth.password });
   return await auth.adapter.createUser({
-    id: uuid(auth.clock),
+    id: uuidV7(auth.clock),
     email: normaliseEmail(input.email),
     passwordHash: await hashPassword(input.password, auth.password.params),
     orgId: input.orgId ?? null,
@@ -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 `MemoryAuthAdapter` 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);
+}