@ultimat3/auth 2.0.0 → 4.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,55 @@ 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.
+- **A TOTP secret that decodes to zero bytes is not a weak key, it is NO key** (`As of 2026-08`).
+  `base32Decode` answers `new Uint8Array(0)` for any character outside the alphabet and for `''`,
+  and `new Bun.CryptoHasher('sha1', new Uint8Array(0))` is a perfectly valid HMAC — so `totpCode`
+  returned a six-digit code derived from nothing, every malformed secret in the table shared that
+  one stream, and `verifyTotp` accepted a code an attacker computes without knowing any secret.
+  Reachable: `enrolTotp(auth, { account, secret })` takes an imported secret, `builtin-adapter.ts`
+  maps the column straight through, and a `mfa_secret text not null default ''` column is not
+  `null`, so `login()` still demanded a second factor and then accepted the empty-key code. The
+  file's own header comment asserted the opposite ("fails the decode closed") for as long as it was
+  wrong. Three answers now, one per caller: `verifyTotp` returns `{ ok: false, step: null }` — the
+  **generic failure**, the same rule `verifyAgainst` follows for a stored hash Bun cannot read, so
+  a broken row is neither a 500 nor an oracle; `totpCode` throws `X_MFA_SECRET_INVALID`, because
+  there is no code an unreadable secret is entitled to; `enrolTotp` throws it too, so the value
+  never reaches the table. The secret never reaches `cause:` or `fix:` — it is a credential and
+  both are logged. No minimum LENGTH is enforced beyond one byte: 10-byte secrets are what several
+  authenticator apps issue, so a 16-byte floor would refuse real enrolments to close nothing the
+  zero-byte rule leaves open.
+- **`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,12 +239,25 @@ 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 |
+| `totpStep(at, stepSeconds?)` / `totpCode(secret, step, digits?)` | the RFC 6238 halves, for a test that has to mint a valid code. `totpCode` throws `X_MFA_SECRET_INVALID` on a secret that decodes to zero bytes |
+
+**A secret the decoder cannot read verifies nothing, `As of 2026-08`.** `base32Decode` answers
+zero bytes for any character outside the alphabet and for `''`, and an HMAC keyed with zero bytes
+is a valid HMAC — so `totpCode` used to hand back a six-digit code derived from no secret at all,
+one stream *every* malformed row in the table verified against, computable by anyone. Three
+answers now, and they differ because their callers do: `verifyTotp` returns `{ ok: false, step:
+null }` (a broken stored credential is the generic failure, the rule `verifyAgainst` follows for a
+hash Bun cannot read — never a throw into the login path, never an oracle); `totpCode` throws
+`X_MFA_SECRET_INVALID`, because there is no code an unreadable secret is entitled to; and
+`enrolTotp` throws the same code on an imported `secret`, so a value nothing can ever check never
+reaches the table. A minted secret is readable by construction. Note the direction of the failure:
+a `mfa_secret text not null default ''` column now locks that account out of its second factor
+instead of accepting a code nobody had to know — re-enrol it with `enrolTotp(auth, { account })`.
 
 `TOTP_DIGITS` (6), `TOTP_STEP_SECONDS` (30) and `TOTP_DRIFT_STEPS` (±1 window) are exported so an
 app's own copy of the parameters cannot disagree with the verifier's.
@@ -251,6 +267,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": "4.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": "4.0.0",
+    "@ultimat3/db": "4.0.0",
+    "@ultimat3/schema": "4.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

@@ -16,6 +16,7 @@ export const AUTH_OWNED_ERROR_CODES = [
   'X_UNAUTHENTICATED',
   'X_SESSION_EXPIRED',
   'X_MFA_REQUIRED',
+  'X_MFA_SECRET_INVALID',
   'X_OAUTH_STATE_INVALID',
   'X_OAUTH_EXCHANGE_FAILED',
   'X_OAUTH_TOKEN_INVALID',
@@ -60,6 +61,7 @@ export const AUTH_ERROR_TITLES: Readonly<Record<AuthOwnedErrorCode, string>> = {
   X_UNAUTHENTICATED: 'no authenticated actor for this request',
   X_SESSION_EXPIRED: 'session passed its idle or absolute expiry',
   X_MFA_REQUIRED: 'a second factor is required before this session is usable',
+  X_MFA_SECRET_INVALID: 'the totp secret is not base32, so it carries no key to check a code with',
   X_OAUTH_STATE_INVALID: 'oauth state, nonce or pkce verifier did not match',
   X_OAUTH_EXCHANGE_FAILED: 'the oauth provider refused the exchange or returned no usable identity',
   X_OAUTH_TOKEN_INVALID: 'id token failed its signature, issuer, audience or expiry check',
@@ -174,6 +176,46 @@ export const mfaRequired = (userId: string): AuthError =>
     meta: { userId },
   });
 
+/**
+ * A stored or imported TOTP secret the decoder cannot read. `base32Decode` answers zero bytes for
+ * any character outside the alphabet AND for `''`, and an HMAC keyed with zero bytes is a valid
+ * HMAC — so `totpCode` was handing out a six-digit code derived from no secret at all, one shared
+ * stream every malformed row in the table verified against. A code nobody had to know a secret to
+ * compute is not a second factor, so there is no code to hand back: this refuses instead.
+ *
+ * `verifyTotp` does NOT throw it. A login checking a broken row is the generic failure, exactly as
+ * `verifyAgainst` treats a stored hash Bun cannot read — a coded throw out of the verify path is a
+ * 500 where a credential refusal belongs, and it answers "this account's secret is malformed" to
+ * whoever asked. The secret itself never reaches `cause:` or `fix:`: it is a credential, and both
+ * are logged.
+ */
+export const mfaSecretInvalid = (surface: string): AuthError =>
+  new AuthError({
+    code: 'X_MFA_SECRET_INVALID',
+    cause: `${surface} was given a totp secret that is not RFC 4648 base32, so it decodes to zero bytes`,
+    fix: 'issue a fresh one and store it: const { secret } = enrolTotp(auth, { account: user.email }) — an imported secret must be base32 (A-Z and 2-7, padding, spaces and dashes ignored) and decode to at least one byte',
+  });
+
+/**
+ * `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/id-token-fixture.ts

@@ -3,6 +3,7 @@
 // chances for one to drift from what `decodeIdToken` actually parses. Not part of the public
 // API — `index.ts` deliberately does not re-export it.
 
+import type { IdTokenClaims } from './id-token';
 import { base64Url } from './tokens';
 
 /** `base64Url` takes bytes because every real secret is bytes; a JWT segment is text. */
@@ -12,5 +13,8 @@ export const base64UrlText = (value: string): string => base64Url(new TextEncode
  * Header, payload, and a signature that is not one. Signatures are never checked here — the
  * token is only ever read straight off the token endpoint — so a fixture needs no signer.
  */
-export const unsignedJwt = (claims: Readonly<Record<string, unknown>>): string =>
+// The union, and not `Record<string, unknown>` alone: `IdTokenClaims` is an `interface`, so it has
+// no implicit index signature and the one shape this fixture exists to serialise was the one shape
+// it refused. The record arm stays for the malformed payloads `id-token.test.ts` builds by hand.
+export const unsignedJwt = (claims: IdTokenClaims | Readonly<Record<string, unknown>>): string =>
   `${base64UrlText('{"alg":"RS256"}')}.${base64UrlText(JSON.stringify(claims))}.signature`;

package/src/index.ts

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

package/src/mfa.ts

@@ -3,6 +3,8 @@
 // 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 { mfaSecretInvalid } from './errors';
 import { randomBytes, sha256Hex, timingSafeEqual } from './tokens';
 
 const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
@@ -29,8 +31,16 @@ export function base32Encode(bytes: Uint8Array): string {
 }
 
 /**
- * Tolerant by design: padding, spaces and the dashes authenticator apps display are skipped,
- * and any other character fails the decode closed (empty output -> no code ever matches).
+ * Tolerant by design: padding, spaces and the dashes authenticator apps display are skipped, and
+ * any other character answers zero bytes.
+ *
+ * Zero bytes is NOT a decode that failed closed — this comment claimed it was, and it was the
+ * whole defect. An HMAC keyed with zero bytes is a perfectly valid HMAC, so `totpCode` derived a
+ * six-digit code from no secret at all and every unreadable secret in the table shared that one
+ * stream: a code an attacker computes without knowing anything verified against all of them.
+ * Zero bytes is therefore refused by both callers that need a key (`totpCode`, `enrolTotp`) and
+ * read as a non-verdict by `verifyTotp`. The decoder itself still answers rather than throwing,
+ * because "can this be read" is a question `enrolTotp` asks about a value it has not accepted yet.
  */
 export function base32Decode(value: string): Uint8Array {
   const bytes: number[] = [];
@@ -63,17 +73,32 @@ 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)}`;
+  // Defence in depth, on the one path that puts a caller's own bytes in front of the table: a
+  // secret nothing can ever derive a code from is refused before it is written, not after a user
+  // is locked out by it. A minted secret is readable by construction, so only an import gets here.
+  if (base32Decode(secret).length === 0) throw mfaSecretInvalid('enrolTotp');
+  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),
@@ -103,6 +128,10 @@ function counterBytes(step: number): Uint8Array {
 /** HMAC-SHA1 + RFC 4226 dynamic truncation. SHA1 here is a spec requirement, not a choice. */
 export function totpCode(secret: string, step: number, digits: number = TOTP_DIGITS): string {
   const key = base32Decode(secret);
+  // A zero-length key is not a weak key, it is no key: the hasher below accepts it and answers a
+  // code every other unreadable secret answers too. There is no code an unreadable secret is
+  // entitled to, so this returns none.
+  if (key.length === 0) throw mfaSecretInvalid('totpCode');
   const mac = Uint8Array.from(
     new Bun.CryptoHasher('sha1', key).update(counterBytes(step)).digest(),
   );
@@ -131,6 +160,12 @@ export interface VerifyTotpInput {
 }
 
 export function verifyTotp(input: VerifyTotpInput): TotpVerification {
+  // A non-verdict, not a verdict and not a throw. It is the rule `verifyAgainst` (`password.ts`)
+  // follows for a stored hash Bun cannot read: a broken stored credential is the generic failure,
+  // because a coded throw out of a verify path is a 500 where a refusal belongs and it answers
+  // "this account's secret is malformed" to whoever asked. It also keeps `totpCode`'s refusal off
+  // the login path entirely — nothing below can reach it with a zero-length key.
+  if (base32Decode(input.secret).length === 0) return { ok: false, step: null };
   const drift = input.drift ?? TOTP_DRIFT_STEPS;
   const current = totpStep(input.at);
   const candidate = input.code.replaceAll(' ', '');
@@ -148,23 +183,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) };
 }