@ultimat3/auth 23.0.0 → 24.0.0

package/src/errors.ts

@@ -29,6 +29,7 @@ export const AUTH_OWNED_ERROR_CODES = [
   'X_AUTH_WRITE_FAILED',
   'X_AUTH_LIMITER_NOT_SHARED',
   'X_AUTH_LIMITER_POLICY_MISMATCH',
+  'X_MFA_SECRET_UNSEALED',
 ] as const;
 
 /**
@@ -74,6 +75,7 @@ export const AUTH_ERROR_TITLES: Readonly<Record<AuthOwnedErrorCode, string>> = {
   X_AUTH_WRITE_FAILED: 'an adapter write returned no row, so it cannot be confirmed',
   X_AUTH_LIMITER_NOT_SHARED: 'the lockout is declared fleet-wide and the limiter is per-process',
   X_AUTH_LIMITER_POLICY_MISMATCH: 'the limiter in use enforces other numbers than the app declared',
+  X_MFA_SECRET_UNSEALED: 'a stored totp secret is not sealed, so it is never read as one',
 };
 
 // Registered unconditionally, in one call: a second package claiming a code auth owns has to fail
@@ -162,23 +164,41 @@ export const kdfOverloaded = (active: number, queued: number): AuthError =>
   });
 
 /**
- * The second leg is the APP's, and this line says so — it named `POST /auth/mfa/verify` for a
- * release while no such route, no `completeMfa()` and no pending-MFA credential existed anywhere,
- * the same dead-`fix:` defect `oauth-paths.ts` exists to stop. Shipping that route from here would
- * be worse than saying nothing: the only correlation value this error carries is a user id, so the
- * route would be unauthenticated by construction and MFA would become the ONLY factor. The design
- * constraint for the real second leg is in `packages/auth/CLAUDE.md`.
+ * The second leg is `completeMfa(auth, challenge, code)` (`mfa-challenge.ts`), and the only thing
+ * that correlates it with a passed first leg is `meta.challenge`: a sealed, short-lived value the
+ * sign-in handler carries to the caller and back. It replaces a bare user id, which made any
+ * second leg built on it unauthenticated by construction.
  *
- * `userId` is `meta`, never `cause`: both surfaces that render this code to an anonymous caller
- * (`oauth-route.ts`'s `publicBody`, `@ultimat3/http`'s problem document) publish `cause` and drop
- * `meta`, and a user id handed to whoever typed the URL is what feeds the attack above.
+ * The challenge is `meta`, never `cause`: both surfaces that render this code to an anonymous
+ * caller (`oauth-route.ts`'s `publicBody`, `@ultimat3/http`'s problem document) publish `cause`
+ * and drop `meta`, so the handler decides where it travels — a cookie or its own response body.
  */
-export const mfaRequired = (userId: string): AuthError =>
+export const mfaRequired = (challenge: string): AuthError =>
   new AuthError({
     code: 'X_MFA_REQUIRED',
     cause: 'this account has TOTP enrolled and the second factor has not been satisfied',
-    fix: 'no second-factor route ships yet — catch X_MFA_REQUIRED in your sign-in handler, check the code with verifyTotp({ secret: user.mfaSecret, code, at }), then mint the session with createSession(auth.sessions, { userId, mfaSatisfied: true })',
-    meta: { userId },
+    fix: 'catch X_MFA_REQUIRED in your sign-in handler, hand error.meta.challenge to the caller, and finish with: await completeMfa(auth, challenge, code)',
+    meta: { challenge },
+  });
+
+/**
+ * A challenge `completeMfa` will not act on: not one this app sealed, past its expiry, or naming
+ * an account that can no longer finish (deleted, disabled, or no longer enrolled). One refusal
+ * for all of them — which it was is not the caller's to learn.
+ */
+export const mfaChallengeInvalid = (): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: 'the second-factor challenge is not one this app issued, or it is no longer usable',
+    fix: 'sign in again for a fresh challenge: await login(auth, { email, password })',
+  });
+
+/** A wrong or already-spent code. The attempt it cost stays counted against the account. */
+export const mfaCodeRejected = (): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: 'the second-factor code did not match, or it was already used',
+    fix: 'read the current code from the authenticator app and retry: await completeMfa(auth, challenge, code)',
   });
 
 /**
@@ -201,6 +221,19 @@ export const mfaSecretInvalid = (surface: string): AuthError =>
     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',
   });
 
+/**
+ * A stored secret that is not sealed. It is refused rather than read: the plaintext path is the
+ * thing sealing removes, and a reader that fell back to it would keep it alive for good. The fix
+ * is the one-shot that seals every such row; `x doctor` reports the count before a user does.
+ */
+export const mfaSecretUnsealed = (): AuthError =>
+  new AuthError({
+    code: 'X_MFA_SECRET_UNSEALED',
+    cause:
+      'x_users.mfa_secret holds a value that is not sealed — written before second-factor secrets were sealed at rest, or written past saveTotpSecret — and a plaintext secret is never read as one',
+    fix: 'x auth seal-mfa --json',
+  });
+
 /**
  * `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
@@ -246,23 +279,10 @@ export const authPolicyNumberInvalid = (
     meta: { option: key, value: String(value) },
   });
 
-/**
- * An explicit key for `clientScopeOf` under the floor `SESSION_SECRET` is held to. The env path
- * already refused a short secret; the option skipped the screen, so `{ secret: 'x' }` keyed every
- * page's scope id with one character. `X_CONFIG_INVALID`, borrowed like the two above.
- */
-export const clientScopeSecretShort = (length: number, minLength: number): AuthError =>
-  new AuthError({
-    code: 'X_CONFIG_INVALID',
-    cause: `clientScopeOf({ secret }) was passed a key of ${String(length)} characters and at least ${String(minLength)} are required, so the scope id would be keyed by a guessable secret`,
-    fix: 'omit secret so clientScopeOf reads SESSION_SECRET, or pass one generated with: openssl rand -hex 32',
-    meta: { option: 'secret', minLength },
-  });
-
 /**
  * An api key `env` the parser cannot read back. `parseApiKey` splits `ult_<env>_<id>_<secret>` on
  * `_`, so `issueApiKey({ env: 'live_eu' })` minted a key its own verifier refused. Refused at
- * issue — `X_CONFIG_INVALID`, borrowed like the three above — never at first use.
+ * issue — `X_CONFIG_INVALID`, borrowed like the two above — never at first use.
  */
 export const apiKeyEnvInvalid = (env: string): AuthError =>
   new AuthError({
@@ -274,6 +294,19 @@ export const apiKeyEnvInvalid = (env: string): AuthError =>
     meta: { option: 'env' },
   });
 
+/**
+ * A wildcard scope on an api key. `*` and `<resource>:*` are how a ROLE is granted everything; on
+ * a key they are a credential that silently grows with every permission the app adds later.
+ * Refused at issue — `X_CONFIG_INVALID`, borrowed like the ones above.
+ */
+export const apiKeyScopeWildcard = (scope: string): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause: `api key scope ${renderCauseValue(scope)} is a wildcard, and a key carries exactly the permissions it names`,
+    fix: "pass each permission by name to issueApiKey({ scopes }) — e.g. scopes: ['post:read', 'post:publish']",
+    meta: { option: 'scopes' },
+  });
+
 export const passwordWeak = (reasons: readonly string[]): AuthError =>
   new AuthError({
     code: 'X_PASSWORD_WEAK',
@@ -281,28 +314,35 @@ export const passwordWeak = (reasons: readonly string[]): AuthError =>
     fix: 'choose a longer, uncommon password — or relax defineAuth({ password: { minLength } })',
   });
 
+/** The tenant bucket's key prefix. Declared here because the refusal below must recognise it. */
+export const ORG_KEY_PREFIX = 'org:';
+
 /**
  * The escape is `recordSuccess(key)`, which is what a successful login already calls: it deletes
  * the bucket, so it clears exactly this one key and nothing else. `reset()` exists too and is the
  * wrong reach — it drops every bucket in the table, including the spray this lockout is holding.
  *
- * `key` carries an address or an email the caller chose, so it goes through `renderFixLiteral`:
- * a fix line has to still parse after a hostile value lands in it.
+ * An `ip:` or `account:` key is the caller's own input, so it is echoed (escaped). A tenant key is
+ * NOT: the org id was looked up from the address the caller typed, and naming it — or even saying
+ * "an organisation" — confirms to an anonymous caller that the address belongs to a member.
  */
-export const accountLocked = (key: string, retryAfterSeconds: number): AuthError =>
-  new AuthError({
+export const accountLocked = (key: string, retryAfterSeconds: number): AuthError => {
+  const tenant = key.startsWith(ORG_KEY_PREFIX);
+  return new AuthError({
     code: 'X_ACCOUNT_LOCKED',
-    // `renderCauseValue`, matching `oauthDenied`: `ipKey(ip)` builds this key from whatever address
-    // string its caller passed, so a newline in it writes a second log line an operator reads as
-    // genuine. The value is `string` by type — the static scan only sees `unknown`/`any`, so this
-    // one was never going to be caught for us — and rendering it as a JSON string literal is
-    // escaping, not throw-safety.
-    cause: `${renderCauseValue(key)} is locked out for another ${retryAfterSeconds}s after repeated failures`,
-    fix: `wait ${retryAfterSeconds}s — or clear this one bucket: auth.limiter.recordSuccess(${renderFixLiteral(key, '<key>')}), auth.orgLimiter for an org: key — or raise defineAuth({ rateLimit })`,
+    // `renderCauseValue`: `ipKey(ip)` builds the key from whatever address string its caller
+    // passed, so a newline in it would write a second log line an operator reads as genuine.
+    cause: tenant
+      ? `sign-in is locked out for another ${retryAfterSeconds}s after repeated failures`
+      : `${renderCauseValue(key)} is locked out for another ${retryAfterSeconds}s after repeated failures`,
+    fix: tenant
+      ? `wait ${retryAfterSeconds}s — or clear the one bucket that is holding: await auth.orgLimiter.recordSuccess(orgKey(user.orgId)) — or raise defineAuth({ rateLimit })`
+      : `wait ${retryAfterSeconds}s — or clear this one bucket: await auth.limiter.recordSuccess(${renderFixLiteral(key, '<key>')}) — or raise defineAuth({ rateLimit })`,
     // `kdfOverloaded`'s shape: `@ultimat3/http`'s `retryAfterOf` reads exactly this field. `key`
     // stays out — `cause`/`fix` escape it on purpose and `meta` is read by surfaces that do not.
     meta: { retryAfterSeconds },
   });
+};
 
 /** One shape for every api-key rejection: unknown, revoked, expired and wrong all look alike. */
 export const apiKeyInvalid = (): AuthError =>
@@ -376,11 +416,3 @@ export const authLimiterPolicyMismatch = (
     fix: `construct the limiter with ${field}: ${declared} — defineAuth({ rateLimit, limiter }) compares the two, and the declaration is what Auth.rateLimit reports`,
     meta: { field, declared, enforced },
   });
-
-/** For a custom `AuthAdapter` that implements part of the seam. Nothing shipped throws it. */
-export const authNotImplemented = (feature: string, fix: string): AuthError =>
-  new AuthError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `${feature} is not implemented by the built-in driver`,
-    fix,
-  });

package/src/index.ts

@@ -1,6 +1,7 @@
 // Single responsibility: the public API of @ultimat3/auth. Explicit named exports only — this
 // list is what the http pipeline, the MCP surface and generated apps are allowed to depend on.
 
+export type { PgExecutor } from '@ultimat3/core';
 export type {
   AccountStore,
   ApiKeyStore,
@@ -13,17 +14,27 @@ export type {
   CreateUserInput,
   SessionPatch,
   SessionStore,
+  StoredMfaSecret,
   UserPatch,
   UserStore,
   VerificationStore,
 } from './adapter';
 export type { ApiKeyCaller, ApiKeyResolverOptions } from './api-key-resolver';
 export { apiKeyResolver } from './api-key-resolver';
-export type { ApiKeySummary, IssueApiKeyInput, IssuedApiKey, ParsedApiKey } from './api-keys';
+export type {
+  ApiKeyActorOptions,
+  ApiKeySummary,
+  ApiKeyVerifyStore,
+  IssueApiKeyInput,
+  IssuedApiKey,
+  ParsedApiKey,
+  VerifiedApiKey,
+} from './api-keys';
 export {
   API_KEY_NAMESPACE,
   apiKeyActor,
   describeApiKey,
+  directGrants,
   issueApiKey,
   parseApiKey,
   revokeApiKey,
@@ -50,7 +61,6 @@ export {
   UserSchema,
   VerificationSchema,
 } from './auth';
-
 export { BuiltinAdapter } from './builtin-adapter';
 /** The opaque per-principal id a per-request document hands the page's client store. */
 export type { ClientScopeOptions } from './client-scope';
@@ -70,14 +80,13 @@ export {
   apiKeyInvalid,
   authLimiterNotShared,
   authLimiterPolicyMismatch,
-  authNotImplemented,
   authUniqueViolation,
   authWriteFailed,
   forbidden,
   kdfOverloaded,
-  mfaRequired,
   mfaRequiredUnenforceable,
   mfaSecretInvalid,
+  mfaSecretUnsealed,
   passwordWeak,
   sessionExpired,
   sessionUnknown,
@@ -132,7 +141,7 @@ export {
   enrolTotp,
   generateRecoveryCodes,
   generateTotpSecret,
-  redeemRecoveryCode,
+  recoveryCodeHash,
   TOTP_DIGITS,
   TOTP_DRIFT_STEPS,
   TOTP_STEP_SECONDS,
@@ -140,6 +149,23 @@ export {
   totpStep,
   verifyTotp,
 } from './mfa';
+export type { CompleteMfaOptions } from './mfa-challenge';
+// `mfaRequired` itself is deliberately absent: the only X_MFA_REQUIRED worth throwing carries a
+// challenge this package sealed, and `mfaChallengeRequired` is what seals one.
+export {
+  completeMfa,
+  MFA_CHALLENGE_PURPOSE,
+  MFA_CHALLENGE_TTL_MS,
+  mfaChallengeRequired,
+} from './mfa-challenge';
+export type { MfaSecretStore, SealMfaSecretsReport } from './mfa-secret';
+export {
+  countUnsealedMfaSecrets,
+  MFA_SECRET_PURPOSE,
+  openTotpSecret,
+  saveTotpSecret,
+  sealMfaSecrets,
+} from './mfa-secret';
 export type {
   BeginOAuthInput,
   OAuthCallback,
@@ -169,16 +195,11 @@ export {
 } from './oauth-cookie';
 export type { DiscoverOAuthProviderInput } from './oauth-discovery';
 export { discoverOAuthProvider, discoveryUrl } from './oauth-discovery';
-// The OAuth half of the same contract, split out of `errors.ts` at the 500-line ceiling. Every
-// name below was exported from `./errors` before the split and is exported here after it.
+// The OAuth refusals more than one OAuth module raises. A refusal with one thrower is exported
+// from that module, below.
 export type { OAuthExchangeFailure } from './oauth-errors';
 export {
-  emailVerifiedNotStored,
-  oauthAccountNotLinked,
-  oauthDenied,
   oauthExchangeFailed,
-  oauthLinkingDisabled,
-  oauthProviderDuplicate,
   oauthProviderUnknown,
   oauthStateInvalid,
   oauthTokenInvalid,
@@ -197,7 +218,13 @@ export type {
   OAuthSignInInput,
   ResolveOAuthGrants,
 } from './oauth-login';
-export { completeOAuthLogin, signInWithOAuth } from './oauth-login';
+export {
+  completeOAuthLogin,
+  emailVerifiedNotStored,
+  oauthAccountNotLinked,
+  oauthLinkingDisabled,
+  signInWithOAuth,
+} from './oauth-login';
 export {
   OAUTH_BASE_PATH,
   OAUTH_CALLBACK_ROUTE_PATH,
@@ -209,12 +236,13 @@ export type { OAuthProfile, OAuthProfileOptions } from './oauth-profile';
 export { oauthProfile } from './oauth-profile';
 export {
   hasOAuthProvider,
+  oauthProviderDuplicate,
   oauthProviderIds,
   providerFor,
   registerOAuthProvider,
 } from './oauth-registry';
 export type { AuthRouteDescriptor, OAuthLoginOptions, OAuthLoginRoutes } from './oauth-route';
-export { OAUTH_ROUTE_STATUS, oauthLogin } from './oauth-route';
+export { OAUTH_ROUTE_STATUS, oauthDenied, oauthLogin } from './oauth-route';
 export type {
   PasswordParams,
   PasswordPolicy,
@@ -240,6 +268,8 @@ export {
   actorFromApiKey,
   actorFromService,
   actorFromUser,
+  apiKeyScopes,
+  isWildcardScope,
   resolveActor,
 } from './policy-bridge';
 export type { UpdatePrivilegesResult } from './privileges';
@@ -248,6 +278,7 @@ export type {
   AuthLimiter,
   AuthLimiterScope,
   AuthRateLimitPolicy,
+  AuthReservation,
   MemoryAuthLimiter,
 } from './rate-limit';
 export {
@@ -261,11 +292,7 @@ export {
   orgKey,
   orgRateLimit,
 } from './rate-limit';
-export type {
-  PgExecutor,
-  PostgresAuthLimiter,
-  PostgresAuthLimiterOptions,
-} from './rate-limit-postgres';
+export type { PostgresAuthLimiter, PostgresAuthLimiterOptions } from './rate-limit-postgres';
 export {
   postgresAuthLimiter,
   SQL_AUTH_LIMIT_TABLES,
@@ -295,7 +322,6 @@ export {
   DEFAULT_SESSION_POLICY,
   idleSlideMs,
   listDevices,
-  readCookie,
   readSessionCookie,
   revokeOtherSessions,
   revokeSession,

package/src/jwks.ts

@@ -207,6 +207,17 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
         .catch(() => null);
       if (key !== null) next.set(`${kid}:${alg}`, key);
     }
+    // A 200 with nothing importable in it is a failed fetch, not a rotation to zero keys. Adopted,
+    // it replaced a working cache with an empty one stamped fresh for a whole TTL.
+    if (next.size === 0) {
+      throw oauthExchangeFailed({
+        provider: options.provider,
+        stage: 'jwks',
+        detail: 'the key set held no key this runtime can import, so the cached keys were kept',
+        status: response.status,
+        fix: readTheKeySet(''),
+      });
+    }
     if (fence.generation() === issued) {
       keys = next;
       fetchedAtMs = clock.now().getTime();

package/src/login-attempt.ts

@@ -0,0 +1,70 @@
+// Single responsibility: one credential attempt's reservations across the three buckets — account,
+// source address, tenant — taken BEFORE the expensive check and settled after it. `login` and
+// `completeMfa` both run through this, so a password guess and a code guess are metered alike.
+
+import type { Auth } from './auth';
+import { type AuthLimiter, type AuthReservation, ipKey, orgKey } from './rate-limit';
+
+export interface LoginAttempt {
+  /**
+   * The tenant bucket, joined once the address has resolved to an org — still before the KDF. A
+   * refusal here gives back what this attempt already took: an attempt the tenant cap turned
+   * away never tested a credential, so it must not also count against the account or address.
+   */
+  reserveOrg(orgId: string | null): Promise<void>;
+  /**
+   * No verdict was reached, or the factor checked was proven and another is still owed: every
+   * reservation is given back and nothing is cleared.
+   */
+  release(): Promise<void>;
+  /**
+   * The credential is fully proven. Clears the ACCOUNT bucket — the typos before it were this
+   * person's — and only refunds the shared ones: an address and a tenant count traffic from many
+   * people, so one success is not evidence the failures beside it were benign.
+   */
+  succeed(): Promise<void>;
+}
+
+interface Taken {
+  readonly limiter: AuthLimiter;
+  readonly reservation: AuthReservation;
+}
+
+/**
+ * Reserves account → ip, in that fixed order (and `reserveOrg` after both), so two concurrent
+ * sign-ins never hold two of a shared limiter's rows in opposite orders. A failed attempt calls
+ * nothing further: the reservations ARE the recorded failure.
+ */
+export async function openLoginAttempt(
+  auth: Auth,
+  account: string,
+  ip: string | null,
+): Promise<LoginAttempt> {
+  const taken: Taken[] = [];
+  const release = async (): Promise<void> => {
+    for (const { limiter, reservation } of taken.splice(0)) await limiter.refund(reservation);
+  };
+  const take = async (limiter: AuthLimiter, key: string): Promise<void> => {
+    try {
+      taken.push({ limiter, reservation: await limiter.reserve(key) });
+    } catch (refused) {
+      await release();
+      throw refused;
+    }
+  };
+
+  await take(auth.limiter, account);
+  if (ip !== null) await take(auth.limiter, ipKey(ip));
+
+  return {
+    reserveOrg: async (orgId) => {
+      if (orgId !== null) await take(auth.orgLimiter, orgKey(orgId));
+    },
+    release,
+    succeed: async () => {
+      const [own, ...shared] = taken.splice(0);
+      if (own !== undefined) await own.limiter.recordSuccess(own.reservation.key);
+      for (const { limiter, reservation } of shared) await limiter.refund(reservation);
+    },
+  };
+}

package/src/memory-adapter.ts

@@ -12,6 +12,7 @@ import type {
   AuthVerification,
   CreateUserInput,
   SessionPatch,
+  StoredMfaSecret,
   UserPatch,
   UserQuery,
 } from './adapter';
@@ -66,6 +67,8 @@ export class MemoryAdapter implements AuthAdapter {
    * what makes two spellings one address.
    */
   async createUser(input: CreateUserInput): Promise<AuthUser> {
+    // `id uuid primary key`: a `Map.set` over an existing id REPLACED the first account.
+    if (this.#users.has(input.id)) throw authUniqueViolation('createUser', 'x_users', 'id');
     for (const existing of this.#users.values()) {
       if (existing.email === input.email) {
         throw authUniqueViolation('createUser', 'x_users', 'email');
@@ -107,6 +110,15 @@ export class MemoryAdapter implements AuthAdapter {
   async updateUser(id: string, patch: UserPatch): Promise<AuthUser | null> {
     const user = this.#users.get(id);
     if (user === undefined) return null;
+    // `external_id text unique`, on the UPDATE as on the INSERT: every OTHER row, and only a
+    // value — NULLS DISTINCT, so clearing it never collides. `UserPatch` carries no `email`.
+    if (patch.externalId !== undefined && patch.externalId !== null) {
+      for (const other of this.#users.values()) {
+        if (other.id !== id && other.externalId === patch.externalId) {
+          throw authUniqueViolation('updateUser', 'x_users', 'external_id');
+        }
+      }
+    }
     const next: AuthUser = {
       ...user,
       passwordHash: patch.passwordHash === undefined ? user.passwordHash : patch.passwordHash,
@@ -125,6 +137,35 @@ export class MemoryAdapter implements AuthAdapter {
     return next;
   }
 
+  async listUsersWithMfaSecret(): Promise<readonly StoredMfaSecret[]> {
+    const stored: StoredMfaSecret[] = [];
+    for (const user of this.#users.values()) {
+      if (user.mfaSecret !== null) stored.push({ userId: user.id, mfaSecret: user.mfaSecret });
+    }
+    return stored.sort((a, b) => (a.userId < b.userId ? -1 : a.userId > b.userId ? 1 : 0));
+  }
+
+  // No `await` between the check and the write: the two are one step, as the UPDATE is.
+  async replaceMfaSecret(userId: string, expected: string, next: string): Promise<boolean> {
+    const user = this.#users.get(userId);
+    if (user === undefined || user.mfaSecret === null) return false;
+    if (!timingSafeEqual(user.mfaSecret, expected)) return false;
+    this.#users.set(userId, { ...user, mfaSecret: next });
+    return true;
+  }
+
+  // No `await` between the check and the write: the two are one step, as the UPDATE is.
+  async consumeRecoveryCode(userId: string, codeHash: string): Promise<boolean> {
+    const user = this.#users.get(userId);
+    const held = (stored: string): boolean => timingSafeEqual(stored, codeHash);
+    if (user === undefined || !user.recoveryCodeHashes.some(held)) return false;
+    this.#users.set(userId, {
+      ...user,
+      recoveryCodeHashes: user.recoveryCodeHashes.filter((stored) => !held(stored)),
+    });
+    return true;
+  }
+
   async findUserByExternalId(externalId: string): Promise<AuthUser | null> {
     for (const user of this.#users.values()) {
       if (user.externalId === externalId) return user;