@ultimat3/auth 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -18,6 +18,18 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 
 - Every credential failure throws `loginFailed()` — one code, one cause, one fix. Adding a
   parameter to it re-opens account enumeration.
+- **A stored hash Bun cannot read is the generic failure, and it burns the same KDF** (`As of
+  2026-08`). `Bun.password.verify` THROWS rather than answering `false` on an unsupported algorithm
+  (a Django `pbkdf2_sha256$…` row: `UnsupportedAlgorithm`) or a malformed PHC string
+  (`InvalidEncoding`), so `verifyPassword` catching nothing was two faults at once: a bare `Error`
+  out of `login()` — a 500 where `loginFailed()`'s `X_UNAUTHENTICATED` belongs — and an enumeration
+  oracle on exactly the rows that have not migrated off the legacy scheme, which is the normal
+  state of a table mid-migration. `verifyAgainst` (`password.ts`) answers `null` there, and `null`
+  joins the no-user branch, `''` with it. Nothing is logged: the algorithm of an unreadable hash is
+  the same oracle one layer down. An `AuthError` out of the gate (`X_OVERLOADED`) is **re-thrown**,
+  never folded into the failure — a shed is load, not a verdict. Supported-but-old stays a verdict:
+  bcrypt verifies natively and `needsRehash` flags it, which is the rehash-on-login lever a legacy
+  migration rewrites rows with, and `password.test.ts` pins both halves.
 - The limiter's table is **bounded**, and the eviction order is part of the guarantee. `ipKey`
   mints one entry per source address, so half the keys are attacker-chosen and a spray from an
   IPv6 /64 is a fresh key per attempt. Every bucket carries `forgetAtMs` — window emptied *and*
@@ -182,6 +194,38 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `auth.limiter` around `verifyTotp` — today it is wired only into `login`, so a six-digit code
   would be the one credential in this package with no lockout. `TotpReplayGuard` is already built
   and must be the completion's, not a second one.
+- **`mfa.required` is the literal `false`, and `defineAuth` refuses a `true` that reaches it
+  anyway** (`X_CONFIG_INVALID`, borrowed from core), `As of 2026-08`. It resolved onto the frozen
+  `Auth` and **nothing read it** — `login()` and `signInWithOAuth()` branch on `user.mfaSecret`
+  alone and mint `mfaSatisfied: true` otherwise, so `required: true` handed a user who had never
+  enrolled a fully-privileged session while reading as "this deployment requires a second factor".
+  Enforcing it was the tempting fix and is a **lockout**: `actorFromUser` degrades a session only
+  when `mfaSecret !== null`, so an un-enrolled user has no half-authenticated actor to enrol
+  through, this package ships no enrolment route to send them to, and `mfaRequired()`'s own `fix:`
+  (`verifyTotp({ secret: user.mfaSecret, … })`) cannot be followed with a null secret — a dead
+  `fix:`, the defect `oauth-paths.ts` exists to stop. So the unenforceable declaration is refused
+  where it is written, exactly as `assertAuthLimiterPolicy` refuses a per-process limiter under a
+  fleet-wide lockout. The literal type is the build error and the runtime check is for the JS
+  caller and the JSON config the type cannot reach, the split `invariantColumns()`'s Proxy keeps.
+  `mfa.issuer` is the half that stayed, and it now has a reader: `enrolTotp(auth, { account })`
+  takes the `Auth` every other entry point takes, so the product name an authenticator app shows
+  is declared once at `defineAuth` instead of restated at every enrolment.
+- **`createTotpReplayGuard`'s table is bounded, and the eviction ORDER is the guarantee.** It
+  pruned steps inside one subject's `Set` and never revisited a subject who stopped signing in, so
+  the map carried one permanent entry per user for the life of the process. Evicting a subject
+  makes a step they have already spent replayable again, so the order cannot be recency of
+  insertion: a subject whose every step has fallen below the drift floor is **forgotten** (nothing
+  outside ±drift is ever offered to `verifyTotp`, so that entry answers exactly as a missing one),
+  and only if that is not enough does `DEFAULT_MAX_TOTP_SUBJECTS` evict live state, sorted by
+  newest spent step ascending with a least-recently-seen tie-break — the subject who just proved a
+  code is always the last one out. Same shape as the limiter's "a live lockout outranks its own
+  deadline". `remember` re-files its subject so the map's iteration order IS that tie-break.
+  `maxSubjects` is **normalised before any of that arithmetic runs** (`boundedSubjects`): the cap
+  ran on the caller's number unchecked, so `Infinity` left the table exactly as unbounded as it was
+  before it was capped, and `NaN` — every comparison against which is false — made the eviction
+  loop's `used.size <= evictTo` never true, emptying the table on the first sweep and handing back
+  a replay of the code the subject had just spent. Anything that is not a positive finite integer
+  takes `DEFAULT_MAX_TOTP_SUBJECTS`; a fraction still floors.
 - SAML is out of scope permanently: XML-DSig canonicalisation has no Bun native and would need a
   real dependency. Put an OIDC-speaking bridge in front and register that.
 

package/README.md

@@ -11,7 +11,7 @@ export const auth = defineAuth({
   adapter: new BuiltinAdapter(),          // or MemoryAdapter, or your Better Auth binding
   session: { absoluteTtlMs: 30 * 864e5, idleTtlMs: 7 * 864e5 },
   password: { minLength: 12 },
-  mfa: { issuer: 'Acme' },
+  mfa: { issuer: 'Acme' },                // the authenticator app's name; `required` only as `false`
   providers: ['github', 'google'],
   link: 'verified-email',                 // the default; `'never'` is the only other value
 });
@@ -215,10 +215,13 @@ rows, because `AuthAdapter` has no MFA member and adding one would break every t
 adapter.
 
 ```ts
+import type { Auth } from '@ultimat3/auth';
 import { createTotpReplayGuard, enrolTotp, generateRecoveryCodes, verifyTotp } from '@ultimat3/auth';
 import { systemClock } from '@ultimat3/core';
 
-const enrolment = enrolTotp({ issuer: 'Acme', account: 'ada@example.com' });
+declare const auth: Auth;   // the `defineAuth` at the top — `enrolTotp` reads `auth.mfa.issuer`
+
+const enrolment = enrolTotp(auth, { account: 'ada@example.com' });   // issuer: auth.mfa.issuer
 // enrolment.uri  -> otpauth://…  the QR code
 // enrolment.secret -> base32, store it against the user
 
@@ -236,9 +239,9 @@ export function secondFactorHolds(userId: string, secret: string, code: string):
 
 | Call | Answers |
 |---|---|
-| `enrolTotp({ issuer, account, secret? })` | `{ secret, uri, digits, periodSeconds }` — `secret` omitted mints one |
+| `enrolTotp(auth, { account, issuer?, secret? })` | `{ secret, uri, digits, periodSeconds }` — `issuer` omitted is `auth.mfa.issuer`, `secret` omitted mints one |
 | `verifyTotp({ secret, code, at, drift?, usedSteps? })` | `{ ok, step }`. `step` is the window the code belonged to, `null` on no match |
-| `createTotpReplayGuard(drift?)` | the in-process `{ isUsed, remember }`; a fleet passes a Redis-backed pair of the same two methods |
+| `createTotpReplayGuard(drift?, maxSubjects?)` | the in-process `{ isUsed, remember, size }`; a fleet passes a Redis-backed pair of the same two methods |
 | `generateRecoveryCodes(count = 10)` | `{ codes, hashes }`. `codes` is shown once and is never re-derivable |
 | `redeemRecoveryCode(code, hashes)` | the **remaining** hashes, or `null`. Persisting that array is what makes a code single-use |
 | `totpStep(at, stepSeconds?)` / `totpCode(secret, step, digits?)` | the RFC 6238 halves, for a test that has to mint a valid code |
@@ -251,6 +254,24 @@ side of now, so without the guard the same six digits log in twice inside a minu
 answers `{ ok: false, step }` — the step still named — when `usedSteps` already holds it, which is
 how a replay is told apart from a wrong code.
 
+The guard's table is **bounded** (`DEFAULT_MAX_TOTP_SUBJECTS`, 10,000), because a per-subject map
+that only ever grows is one process' lifetime away from an OOM. A subject whose every remembered
+step has fallen below the drift floor is *forgotten* — `verifyTotp` can never offer that step
+again, so the entry answers exactly as a missing one — and only if that is not enough does the cap
+evict live state, furthest from the live window first. The order is the guarantee: evicting a
+subject makes a step they have already spent replayable, so the subject who just authenticated is
+always the last one out.
+
+**`mfa.required` is accepted only as `false`, and that is deliberate.** The field exists and is
+typed as the literal `false`, so `required: true` is a compile error; a `true` that reaches
+`defineAuth` from JavaScript or from JSON — where the type cannot — is refused at boot with
+`X_CONFIG_INVALID` naming the key, never an unknown-key error and never a silent accept. Nothing
+read it: both credential paths branch on `user.mfaSecret` alone, so an un-enrolled user was handed
+a full session under a config that read as "this deployment requires a second factor". Enforcing it
+at `login()` instead is a lockout — `actorFromUser` degrades only a user who HAS a secret, and this
+package ships no enrolment route to send the rest to. Gate it in your own sign-in handler —
+`if (user.mfaSecret === null)` send them to `enrolTotp` before you call `createSession`.
+
 **The second leg of login is the app's, `As of 2026-08`.** `login()` and `completeOAuthLogin()`
 throw `X_MFA_REQUIRED` before any session exists; finishing the flow is `verifyTotp` followed by
 `createSession({ mfaSatisfied: true })` in the app's own route. The framework ships no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -31,8 +31,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/db": "2.0.0",
-    "@ultimat3/schema": "2.0.0"
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/db": "3.0.0",
+    "@ultimat3/schema": "3.0.0"
   }
 }

package/src/auth.ts

@@ -7,7 +7,7 @@ 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, sessionUnknown } from './errors';
+import { mfaRequired, mfaRequiredUnenforceable, sessionUnknown } from './errors';
 import type { OAuthProviderId } from './oauth';
 import { oauthProviderIds } from './oauth-registry';
 import {
@@ -106,10 +106,25 @@ export const VerificationSchema = t.object({
  */
 export type OAuthLinkPolicy = 'verified-email' | 'never';
 
+/** The product name an authenticator app shows when the app declared none. */
+export const DEFAULT_MFA_ISSUER = 'Ultimate';
+
 export interface AuthMfaPolicy {
-  /** Shown in the authenticator app. Usually the product name. */
+  /**
+   * Shown in the authenticator app. Usually the product name, and `enrolTotp(auth, …)` reads it
+   * from here so it is written once — a call may still name its own for the one enrolment.
+   */
   readonly issuer: string;
-  readonly required: boolean;
+  /**
+   * The literal `false`, so `required: true` is a type error rather than a comment — the shape
+   * `OAuthProvider.usesPkce` has, and for the same reason: the value nothing enforces has to be
+   * unrepresentable, not discouraged. This package cannot make a second factor mandatory. Both
+   * credential paths branch on `user.mfaSecret` alone and `actorFromUser` degrades only a user
+   * who HAS a secret, so a user who never enrolled has no half-authenticated actor to enrol
+   * through and no enrolment route to reach — refusing them at `login()` locks them out for good.
+   * `defineAuth` refuses the declaration outright; the app gates its own sign-in handler.
+   */
+  readonly required: false;
 }
 
 export interface AuthConfigInput {
@@ -166,6 +181,13 @@ export function defineAuth(config: AuthConfigInput): Auth {
   const orgLimits = orgRateLimit(rateLimit);
   const orgLimiter = config.orgLimiter ?? createAuthLimiter(clock, orgLimits);
   if (config.orgLimiter !== undefined) assertAuthLimiterPolicy(orgLimits, config.orgLimiter);
+  // 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
+  // parsed out of JSON — the same split `invariantColumns()` keeps its Proxy behind a compile
+  // error for. A declaration this package cannot enforce is refused where it is written.
+  const declaredMfa: { readonly required?: unknown } = config.mfa ?? {};
+  if (declaredMfa.required === true) throw mfaRequiredUnenforceable();
+  const mfa: AuthMfaPolicy = { issuer: config.mfa?.issuer ?? DEFAULT_MFA_ISSUER, required: false };
   return Object.freeze({
     adapter: config.adapter,
     clock,
@@ -177,7 +199,7 @@ export function defineAuth(config: AuthConfigInput): Auth {
     // exactly when the app declared 'shared' and left this limiter to the default.
     orgRateLimit: orgLimiter.policy,
     orgLimiter,
-    mfa: { issuer: config.mfa?.issuer ?? 'Ultimate', required: config.mfa?.required ?? false },
+    mfa,
     providers: config.providers ?? oauthProviderIds(),
     link: config.link ?? 'verified-email',
   });

package/src/errors.ts

@@ -174,6 +174,26 @@ export const mfaRequired = (userId: string): AuthError =>
     meta: { userId },
   });
 
+/**
+ * `defineAuth({ mfa: { required: true } })`, refused where it is declared. The option read as a
+ * security guarantee — "this deployment requires a second factor" — and nothing in this package
+ * could make it true: `login()` and `signInWithOAuth()` branch on `user.mfaSecret` alone, so a
+ * user who never enrolled was handed a fully-privileged session under it, and `actorFromUser`
+ * strips privileges only for a user who HAS a secret, so there is no half-authenticated actor to
+ * hand them instead. Enforcing it inside `login()` would refuse exactly the people with nothing to
+ * offer, with no enrolment route shipped to send them to — a permanent lockout, not a second
+ * factor. So the declaration is refused at boot, exactly as `assertAuthLimiterPolicy` refuses a
+ * per-process limiter under a fleet-wide lockout: a guarantee this package cannot show holds is
+ * never assumed. `X_CONFIG_INVALID` is core's code, borrowed rather than re-declared.
+ */
+export const mfaRequiredUnenforceable = (): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause:
+      'defineAuth({ mfa: { required: true } }) declares a second factor this package does not enforce: login() mints a full session for any user whose mfaSecret is null',
+    fix: 'drop required from defineAuth({ mfa }) and gate it in your own sign-in handler, which is where the enrolment route lives: if (user.mfaSecret === null) send them to enrolTotp(auth, { account: user.email }) instead of createSession(auth.sessions, ...)',
+  });
+
 /**
  * The `fix:` quotes `oauthStartPath` rather than a hand-written path. That is not tidiness: this
  * line shipped naming `GET /auth/oauth/<provider>` while `@ultimat3/auth` mounted no route at all,

package/src/index.ts

@@ -41,6 +41,7 @@ export type {
 export {
   AccountSchema,
   authenticate,
+  DEFAULT_MFA_ISSUER,
   defineAuth,
   login,
   logout,
@@ -72,6 +73,7 @@ export {
   forbidden,
   kdfOverloaded,
   mfaRequired,
+  mfaRequiredUnenforceable,
   oauthAccountNotLinked,
   oauthDenied,
   oauthExchangeFailed,
@@ -120,6 +122,7 @@ export {
 export { MemoryAdapter } from './memory-adapter';
 export type {
   EnrolTotpInput,
+  MemoryTotpReplayGuard,
   RecoveryCodeSet,
   TotpEnrolment,
   TotpReplayGuard,
@@ -130,6 +133,7 @@ export {
   base32Decode,
   base32Encode,
   createTotpReplayGuard,
+  DEFAULT_MAX_TOTP_SUBJECTS,
   enrolTotp,
   generateRecoveryCodes,
   generateTotpSecret,

package/src/mfa.ts

@@ -3,6 +3,7 @@
 // phishing page stays valid for the rest of its 30 seconds. Recovery codes are hashed at rest
 // and single-use, so a database dump is not a permanent MFA bypass.
 
+import type { Auth } from './auth';
 import { randomBytes, sha256Hex, timingSafeEqual } from './tokens';
 
 const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
@@ -63,17 +64,28 @@ export interface TotpEnrolment {
 }
 
 export interface EnrolTotpInput {
-  readonly issuer: string;
+  /**
+   * Omitted, the issuer is `auth.mfa.issuer` — one declaration, at `defineAuth`, so the product
+   * name an authenticator app shows is not restated at every enrolment. Named here only when one
+   * call needs a different one (a separate admin console entry, say).
+   */
+  readonly issuer?: string | undefined;
   readonly account: string;
   readonly secret?: string | undefined;
 }
 
-export function enrolTotp(input: EnrolTotpInput): TotpEnrolment {
+/**
+ * Takes the `Auth` every other entry point in this package takes, and for the same reason: the
+ * issuer is configuration, and a pure function that could not read the configuration is what made
+ * `defineAuth({ mfa: { issuer } })` a string the framework wrote down and never read.
+ */
+export function enrolTotp(auth: Auth, input: EnrolTotpInput): TotpEnrolment {
   const secret = input.secret ?? generateTotpSecret();
-  const label = `${encodeURIComponent(input.issuer)}:${encodeURIComponent(input.account)}`;
+  const issuer = input.issuer ?? auth.mfa.issuer;
+  const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(input.account)}`;
   const query = new URLSearchParams({
     secret,
-    issuer: input.issuer,
+    issuer,
     algorithm: 'SHA1',
     digits: String(TOTP_DIGITS),
     period: String(TOTP_STEP_SECONDS),
@@ -148,23 +160,106 @@ export interface TotpReplayGuard {
   remember(subject: string, step: number, at: Date): void;
 }
 
+/** What `createTotpReplayGuard` returns: the interface, plus the bound it keeps, observable. */
+export interface MemoryTotpReplayGuard extends TotpReplayGuard {
+  readonly size: number;
+}
+
+/**
+ * Hard bound on tracked subjects. One entry is one user who has completed a TOTP check inside the
+ * last drift window, so the natural cardinality is far below this — the cap is the backstop, the
+ * same one `DEFAULT_MAX_AUTH_LIMIT_KEYS` is for the limiter's table.
+ */
+export const DEFAULT_MAX_TOTP_SUBJECTS = 10_000;
+
+/** An idle guard still sweeps this often, so one burst's subjects do not sit until the next. */
+const SWEEP_EVERY_STEPS = 2;
+
+/**
+ * The cap arithmetic ran on the caller's number unchecked, and the two values a misread config
+ * hands you each defeated the bound in their own way: `Infinity` makes `used.size > cap` never
+ * true, so the table is exactly as unbounded as before it was capped; `NaN` makes EVERY comparison
+ * false, so `used.size <= evictTo` never stops the eviction loop and one sweep empties the table —
+ * including the subject who just authenticated, whose step is then replayable. Anything that is
+ * not a positive finite integer is a config the caller did not mean, so it takes the default
+ * rather than a bound derived from it. A fraction still floors: `2.5` is a caller who meant 2.
+ */
+function boundedSubjects(maxSubjects: number): number {
+  if (!Number.isFinite(maxSubjects) || maxSubjects < 1) return DEFAULT_MAX_TOTP_SUBJECTS;
+  return Math.floor(maxSubjects);
+}
+
+/** The last step this subject has spent — how close their entry still is to the live window. */
+const newestStep = (steps: ReadonlySet<number>): number => {
+  let newest = Number.NEGATIVE_INFINITY;
+  for (const step of steps) newest = Math.max(newest, step);
+  return newest;
+};
+
 /**
  * In-memory by default because a single web process is the common case; a multi-process
  * deployment passes a Redis-backed guard with the same two methods. Steps older than the
  * drift window are dropped — nothing outside it can be replayed anyway.
+ *
+ * Bounded, because the subject map only ever grew: pruning happened inside one subject's `Set`
+ * and never revisited a subject who stopped signing in, so the table carried one permanent entry
+ * per user for the life of the process. Two rules keep it flat, and the ORDER is the guarantee —
+ * evicting a subject makes a step they have already spent replayable again, so it may never be
+ * the subject who just authenticated. A subject whose every step has fallen below the drift floor
+ * is *forgotten*, not evicted: `verifyTotp` only ever offers a step within ±drift of now, so that
+ * entry answers exactly as a missing one and dropping it changes no decision. Only if forgetting
+ * is not enough does the cap evict live state, furthest from the live window first — the shape
+ * `createAuthLimiter` evicts by, where a live lockout is the last bucket to go.
  */
-export function createTotpReplayGuard(drift: number = TOTP_DRIFT_STEPS): TotpReplayGuard {
+export function createTotpReplayGuard(
+  drift: number = TOTP_DRIFT_STEPS,
+  maxSubjects: number = DEFAULT_MAX_TOTP_SUBJECTS,
+): MemoryTotpReplayGuard {
   const used = new Map<string, Set<number>>();
+  const cap = boundedSubjects(maxSubjects);
+  // Batched down to 90% of the cap so the sort below is paid once per 10% of it, not per check.
+  const evictTo = Math.max(1, Math.floor(cap * 0.9));
+  let lastSweepStep = Number.NEGATIVE_INFINITY;
+
+  const prune = (steps: Set<number>, floor: number): void => {
+    for (const known of steps) {
+      if (known < floor) steps.delete(known);
+    }
+  };
+
+  const sweep = (now: number, floor: number): void => {
+    lastSweepStep = now;
+    for (const [subject, steps] of used) {
+      prune(steps, floor);
+      if (steps.size === 0) used.delete(subject);
+    }
+    if (used.size <= cap) return;
+    // Map iteration is insertion order and `remember` re-files the subject it touches, so this
+    // sort — stable by specification — breaks a tie on the newest step by least recently seen.
+    // Both keys point the same way: the subject who just proved a code is the last one out.
+    const furthest = [...used.entries()].sort((a, b) => newestStep(a[1]) - newestStep(b[1]));
+    for (const [subject] of furthest) {
+      if (used.size <= evictTo) break;
+      used.delete(subject);
+    }
+  };
+
   return {
+    get size() {
+      return used.size;
+    },
     isUsed: (subject, step) => used.get(subject)?.has(step) === true,
     remember: (subject, step, at) => {
+      const now = totpStep(at);
+      const floor = now - drift;
       const steps = used.get(subject) ?? new Set<number>();
-      const floor = totpStep(at) - drift;
-      for (const known of steps) {
-        if (known < floor) steps.delete(known);
-      }
+      prune(steps, floor);
       steps.add(step);
+      // Deleted before it is set, so this subject moves to the back of the iteration order and
+      // that order is least-recently-remembered first. Nothing else observes it.
+      used.delete(subject);
       used.set(subject, steps);
+      if (used.size > cap || now - lastSweepStep >= SWEEP_EVERY_STEPS) sweep(now, floor);
     },
   };
 }

package/src/password.ts

@@ -3,7 +3,7 @@
 // a migration. Verification always burns a full KDF even when the user does not exist —
 // otherwise response time answers "is this email registered?" for free.
 
-import { passwordWeak } from './errors';
+import { AuthError, passwordWeak } from './errors';
 import { kdfGate } from './kdf-gate';
 
 export interface PasswordParams {
@@ -100,12 +100,51 @@ export function needsRehash(
 }
 
 export interface VerifyPasswordInput {
-  /** `null` when no user matched. The KDF still runs, on a throwaway hash. */
+  /**
+   * `null` when no user matched. The KDF still runs, on a throwaway hash — and a stored hash Bun
+   * cannot read takes that same branch, so neither is separable from a wrong password.
+   */
   readonly hash: string | null;
   readonly password: string;
   readonly params?: PasswordParams | undefined;
 }
 
+/** The KDF the happy path would have burnt, then the one failure shape. Never a cheap answer. */
+async function burnAndFail(
+  password: string,
+  params: PasswordParams,
+): Promise<PasswordVerification> {
+  await hashPassword(password, params);
+  return FAILED;
+}
+
+/**
+ * `false` is a wrong password, `null` is a stored hash Bun cannot read at all.
+ *
+ * `Bun.password.verify` THROWS rather than answering on a hash it cannot parse — measured, bun
+ * 1.3.14: a Django `pbkdf2_sha256$...` row is `UnsupportedAlgorithm`, a truncated bcrypt string is
+ * `InvalidEncoding`. Letting that escape was two faults. A bare `Error` reached `login()`, so the
+ * caller answered 500 instead of the one credential failure; and it landed on exactly the rows
+ * that have not migrated off the legacy scheme, which makes "has this account been migrated" —
+ * and therefore "does this account exist" — readable from the outside. That is the enumeration
+ * oracle the whole file is built to close, on the one table where a foreign hash is normal.
+ *
+ * Supported-but-old is a different thing and stays a verdict: bcrypt verifies natively here and
+ * `needsRehash` flags it, which is the lever a legacy migration rewrites rows with.
+ *
+ * Nothing is logged. The algorithm of an unreadable hash is the oracle again, one layer down.
+ */
+async function verifyAgainst(password: string, hash: string): Promise<boolean | null> {
+  try {
+    return await kdfGate().run(async () => await Bun.password.verify(password, hash));
+  } catch (error) {
+    // The gate shedding (`X_OVERLOADED`) is load, never a verdict on the credential: swallowing it
+    // would answer "wrong password" for a request this process refused to do the work for.
+    if (error instanceof AuthError) throw error;
+    return null;
+  }
+}
+
 /**
  * Never short-circuits on a missing user: the `hashPassword` call in the `null` branch costs
  * the same order of magnitude as the verify in the happy branch, so the two are not separable
@@ -113,13 +152,14 @@ export interface VerifyPasswordInput {
  */
 export async function verifyPassword(input: VerifyPasswordInput): Promise<PasswordVerification> {
   const params = input.params ?? DEFAULT_PASSWORD_PARAMS;
-  // Read into a local so the closure below narrows without a cast.
+  // Read into a local so the two branches below narrow it without a cast.
   const hash = input.hash;
-  if (hash === null) {
-    await hashPassword(input.password, params);
-    return FAILED;
-  }
-  const ok = await kdfGate().run(async () => await Bun.password.verify(input.password, hash));
+  // `''` joins the no-user branch rather than reaching the KDF: an account with no password
+  // credential (oauth-only) answers `false` from Bun for free, and a failure that costs nothing
+  // is a stopwatch away from "this address exists but has never set a password".
+  if (hash === null || hash === '') return await burnAndFail(input.password, params);
+  const ok = await verifyAgainst(input.password, hash);
+  if (ok === null) return await burnAndFail(input.password, params);
   if (!ok) return FAILED;
   return { ok: true, needsRehash: needsRehash(hash, params) };
 }