@ultimat3/auth 23.0.0 → 25.0.0

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,8 +61,7 @@ export {
   UserSchema,
   VerificationSchema,
 } from './auth';
-
-export { BuiltinAdapter } from './builtin-adapter';
+export { type PostgresAuthAdapter, postgresAuthAdapter } from './builtin-adapter';
 /** The opaque per-principal id a per-request document hands the page's client store. */
 export type { ClientScopeOptions } from './client-scope';
 export { clientScopeOf } from './client-scope';
@@ -68,20 +78,19 @@ export {
   AuthError,
   accountLocked,
   apiKeyInvalid,
+  authForbidden,
   authLimiterNotShared,
   authLimiterPolicyMismatch,
-  authNotImplemented,
+  authUnauthenticated,
   authUniqueViolation,
   authWriteFailed,
-  forbidden,
   kdfOverloaded,
-  mfaRequired,
   mfaRequiredUnenforceable,
   mfaSecretInvalid,
+  mfaSecretUnsealed,
   passwordWeak,
   sessionExpired,
   sessionUnknown,
-  unauthenticated,
 } from './errors';
 export { currentActor, requireActor } from './guards';
 export type { IdTokenClaims, VerifyIdTokenInput } from './id-token';
@@ -99,22 +108,22 @@ export type {
   JwtHeader,
 } from './jwks';
 export {
-  createJwksClient,
   decodeJwtHeader,
+  jwksClient,
   providerJwks,
   verifyJwtSignature,
 } from './jwks';
 export type { KdfGate, KdfLimits } from './kdf-gate';
 export {
+  boundedKdfGate,
   configureKdfGate,
-  createKdfGate,
   kdfGate,
 } from './kdf-gate';
 export type { AuthLimiterFactory } from './limiter-install';
 // `installedAuthLimiter` is deliberately absent: `defineAuth` is the one reader, and a second
 // caller building limiters out of band would be a second answer to where failures are counted.
 export { configureAuthLimiters, purgeAuthLimits, resetAuthLimiters } from './limiter-install';
-export { MemoryAdapter } from './memory-adapter';
+export { type MemoryAuthAdapter, memoryAuthAdapter } from './memory-adapter';
 export type {
   EnrolTotpInput,
   MemoryTotpReplayGuard,
@@ -127,12 +136,12 @@ export type {
 export {
   base32Decode,
   base32Encode,
-  createTotpReplayGuard,
   DEFAULT_MAX_TOTP_SUBJECTS,
   enrolTotp,
   generateRecoveryCodes,
   generateTotpSecret,
-  redeemRecoveryCode,
+  memoryTotpReplayGuard,
+  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,
@@ -148,7 +174,7 @@ export type {
   OAuthProviderId,
   PkcePair,
 } from './oauth';
-export { assertOAuthCallback, beginOAuth, createPkce } from './oauth';
+export { assertOAuthCallback, beginOAuth, pkcePair } from './oauth';
 export {
   APPLE_PROVIDER,
   BUILTIN_OAUTH_PROVIDER_IDS,
@@ -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,
@@ -191,13 +212,20 @@ export type {
   OAuthTokens,
 } from './oauth-exchange';
 export { exchangeOAuthCode, oauthCredentials } from './oauth-exchange';
+export type { OAuthGrantContext } from './oauth-grant-context';
 export type {
   CompleteOAuthLoginInput,
   OAuthGrants,
   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 +237,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 +269,8 @@ export {
   actorFromApiKey,
   actorFromService,
   actorFromUser,
+  apiKeyScopes,
+  isWildcardScope,
   resolveActor,
 } from './policy-bridge';
 export type { UpdatePrivilegesResult } from './privileges';
@@ -248,24 +279,21 @@ export type {
   AuthLimiter,
   AuthLimiterScope,
   AuthRateLimitPolicy,
+  AuthReservation,
   MemoryAuthLimiter,
 } from './rate-limit';
 export {
   accountKey,
   assertAuthLimiterPolicy,
-  createAuthLimiter,
   DEFAULT_AUTH_RATE_LIMIT,
   DEFAULT_MAX_AUTH_LIMIT_KEYS,
   ipKey,
   loginFailed,
+  memoryAuthLimiter,
   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,8 +323,8 @@ export {
   DEFAULT_SESSION_POLICY,
   idleSlideMs,
   listDevices,
-  readCookie,
   readSessionCookie,
+  remainingMaxAgeSeconds,
   revokeOtherSessions,
   revokeSession,
   rotateSession,
@@ -315,7 +343,6 @@ export {
 export {
   randomToken,
   sha256Hex,
-  timingSafeEqual,
 } from './tokens';
 export type {
   ConsumeVerificationInput,

package/src/jwks.ts

@@ -8,11 +8,11 @@
 
 import type { Clock, Scheduler } from '@ultimat3/core';
 import {
-  createFence,
-  createSingleFlight,
+  generationFence,
   isFixShellSafe,
   renderFixShellArg,
   renderThrowable,
+  singleFlight,
   systemClock,
 } from '@ultimat3/core';
 import { decodeJwtSegment, isRecord } from './json';
@@ -117,7 +117,7 @@ const algorithmOf = (jwk: Record<string, unknown>): JwtAlgorithm | null => {
  * become an unbounded outbound request per attempt, so the refresh is rate-limited by the same
  * TTL as the ordinary one.
  */
-export function createJwksClient(options: JwksClientOptions): JwksKeySource {
+export function jwksClient(options: JwksClientOptions): JwksKeySource {
   const clock = options.clock ?? systemClock;
   const ttlMs = options.ttlMs ?? DEFAULT_JWKS_TTL_MS;
   assertFiniteAuthCount(
@@ -144,7 +144,7 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
   // already gave up on could drop a pre-rotation key set on top of the live one, and every login
   // against the new `kid` would start missing again. Read, never `guard`: a superseded refresh is
   // still the honest answer for the callers holding it, and only the shared cache is fenced.
-  const fence = createFence('the published jwks key set');
+  const fence = generationFence('the published jwks key set');
   // All three refusals below put this URI in a COMMAND position, and it came out of the ISSUER's
   // own discovery document — `jwks_uri` is remote text, and `new URL()` keeps `$`, `(`, `)` and a
   // backtick in a path. `renderFixLiteral` is the wrong tool here, because its double quotes leave
@@ -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();
@@ -224,7 +235,7 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
   // running, its own callers keep their promise, and the fence above stops its late answer from
   // landing in the cache. So the worst case is one duplicate JWKS fetch, never a failed
   // verification — which is what makes a deadline here a fix rather than a risk.
-  const flight = createSingleFlight({
+  const flight = singleFlight({
     deadlineMs: timeoutMs * JWKS_DEADLINE_FACTOR,
     schedule: options.schedule,
   });
@@ -284,7 +295,7 @@ const clients = new Map<string, JwksKeySource>();
  *
  * Not cached by option identity, deliberately: `fetch` and `clock` are functions and objects, so
  * any canonical key over them either collides (two different proxies, one entry) or never hits.
- * A bespoke client is a bespoke client; `createJwksClient` is what it is, and its own cache still
+ * A bespoke client is a bespoke client; `jwksClient` is what it is, and its own cache still
  * works for as long as the caller holds it.
  */
 export function providerJwks(
@@ -301,7 +312,7 @@ export function providerJwks(
   const bespoke = options !== undefined && Object.keys(options).length > 0;
   const existing = bespoke ? undefined : clients.get(provider.id);
   if (existing !== undefined) return existing;
-  const client = createJwksClient({ ...options, provider: provider.id, jwksUri: provider.jwksUri });
+  const client = jwksClient({ ...options, provider: provider.id, jwksUri: provider.jwksUri });
   if (!bespoke) clients.set(provider.id, client);
   return client;
 }

package/src/kdf-gate.ts

@@ -6,7 +6,7 @@
 // what argon2id costs is MEMORY — 19 MiB per hash at the OWASP floor. The only remaining backstop
 // was `http.maxInflight` (1000), i.e. roughly 19 GB of arenas queued on one box.
 
-import { createFlightGate } from '@ultimat3/core';
+import { flightGate } from '@ultimat3/core';
 import { kdfOverloaded } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
 
@@ -43,7 +43,7 @@ export interface KdfGate {
  * The declared return type stays `KdfGate` rather than core's `FlightGate`: `active` and `queued`
  * are observations no caller here has ever had, and widening a public signature is not a refactor.
  */
-export function createKdfGate(limits: KdfLimits = DEFAULT_KDF_LIMITS): KdfGate {
+export function boundedKdfGate(limits: KdfLimits = DEFAULT_KDF_LIMITS): KdfGate {
   // Screened at the CONSTRUCTOR, because this pair WEDGES rather than fails: core asks
   // `active < maxConcurrent` and then `waiters.length >= maxQueued`, and both are false for `NaN`,
   // so every hash on the box parks in a queue with no bound and nothing to release it — login
@@ -66,12 +66,12 @@ export function createKdfGate(limits: KdfLimits = DEFAULT_KDF_LIMITS): KdfGate {
     '`waiters.length >= NaN` is false, so the queue this gate exists to bound has no bound at all',
     0,
   );
-  return createFlightGate(limits, {
+  return flightGate(limits, {
     overflow: (state) => kdfOverloaded(state.active, state.queued),
   });
 }
 
-let gate = createKdfGate();
+let gate = boundedKdfGate();
 
 /** The process-wide gate every `hashPassword`/`verifyPassword` passes through. */
 export const kdfGate = (): KdfGate => gate;
@@ -83,10 +83,10 @@ export const kdfGate = (): KdfGate => gate;
  * runs on a 512 MiB PaaS dyno and a 64 GiB node.
  */
 export function configureKdfGate(limits: KdfLimits): void {
-  gate = createKdfGate(limits);
+  gate = boundedKdfGate(limits);
 }
 
 /** Back to the shipped defaults. Tests that call `configureKdfGate` must call this in cleanup. */
 export function resetKdfGate(): void {
-  gate = createKdfGate();
+  gate = boundedKdfGate();
 }

package/src/limiter-install.ts

@@ -52,7 +52,7 @@ export function configureAuthLimiters(next: AuthLimiterFactory): void {
   built = new Map();
 }
 
-/** Back to `createAuthLimiter`, the per-process default. A host that installs one calls this on stop. */
+/** Back to `memoryAuthLimiter`, the per-process default. A host that installs one calls this on stop. */
 export function resetAuthLimiters(): void {
   factory = undefined;
   built = new Map();

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

@@ -2,7 +2,7 @@
 // database exists and the one every test in this package runs against — the same interface
 // Postgres and Better Auth implement, so a flow that works here works there or the seam is wrong.
 
-import { type Clock, systemClock } from '@ultimat3/core';
+import { type Clock, systemClock, timingSafeEqual } from '@ultimat3/core';
 import type {
   AuthAccount,
   AuthAdapter,
@@ -12,15 +12,33 @@ import type {
   AuthVerification,
   CreateUserInput,
   SessionPatch,
+  StoredMfaSecret,
   UserPatch,
   UserQuery,
 } from './adapter';
 import { authUniqueViolation } from './errors';
-import { timingSafeEqual } from './tokens';
 
 const verificationKey = (purpose: string, identifier: string): string => `${purpose}:${identifier}`;
 
-export class MemoryAdapter implements AuthAdapter {
+/**
+ * `PostgresAuthAdapter`'s `order by email collate "C"`: byte order over UTF-8, which is CODE-POINT order
+ * — never `localeCompare` (the machine's locale) and never `<` on strings, whose UTF-16 code units
+ * put an astral character (a lead surrogate, 0xD8xx) ahead of U+E000–U+FFFF.
+ */
+const byCodePoint = (a: string, b: string): number => {
+  const left = a[Symbol.iterator]();
+  const right = b[Symbol.iterator]();
+  for (;;) {
+    const x = left.next();
+    const y = right.next();
+    if (x.done === true || y.done === true)
+      return (x.done === true ? 0 : 1) - (y.done === true ? 0 : 1);
+    const delta = (x.value.codePointAt(0) ?? 0) - (y.value.codePointAt(0) ?? 0);
+    if (delta !== 0) return delta;
+  }
+};
+
+export class MemoryAuthAdapter implements AuthAdapter {
   readonly name = 'memory';
   readonly #clock: Clock;
   readonly #users = new Map<string, AuthUser>();
@@ -32,14 +50,14 @@ export class MemoryAdapter implements AuthAdapter {
   /**
    * The clock every instant this adapter stamps comes from — one argument, because a stamp is a
    * fact about WHEN a call happened and a test that cannot move it can only assert a range.
-   * Defaults to `systemClock`, so `new MemoryAdapter()` is what it always was.
+   * Defaults to `systemClock`, so `memoryAuthAdapter()` is what it always was.
    */
   constructor(clock: Clock = systemClock) {
     this.#clock = clock;
   }
 
   /**
-   * Exact match, because `BuiltinAdapter` issues `where email = $1` against a plain `text ...
+   * Exact match, because `PostgresAuthAdapter` issues `where email = $1` against a plain `text ...
    * unique` column and nothing folds case there. Normalising here instead made this the ONE
    * adapter that found an account Postgres would not, which is a linked account under `x dev` and
    * a duplicate one in production. `normaliseEmail` is the caller's, above the seam.
@@ -56,7 +74,7 @@ export class MemoryAdapter implements AuthAdapter {
   }
 
   /**
-   * The two UNIQUE constraints `x_users` declares, enforced here because `BuiltinAdapter` LEANS on
+   * The two UNIQUE constraints `x_users` declares, enforced here because `PostgresAuthAdapter` LEANS on
    * them: `email text not null unique` and `external_id text unique` (`tables.ts`). Without them
    * this adapter — the one `x new` scaffolds and every test runs against — accepted two rows at one
    * address, and the second was unreachable forever, since `findUserByEmail` returns the first.
@@ -66,6 +84,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 +127,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 +154,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;
@@ -137,7 +195,7 @@ export class MemoryAdapter implements AuthAdapter {
       .filter((user) => user.orgId === orgId)
       .filter((user) => query?.includeDisabled === true || user.disabledAt === null)
       .filter((user) => query?.role === undefined || user.roles.includes(query.role))
-      .sort((a, b) => a.email.localeCompare(b.email));
+      .sort((a, b) => byCodePoint(a.email, b.email));
   }
 
   async getSession(id: string): Promise<AuthSession | null> {
@@ -289,3 +347,11 @@ export class MemoryAdapter implements AuthAdapter {
     return true;
   }
 }
+
+/**
+ * The one way to build the in-memory adapter — the twin of `postgresAuthAdapter()`. The class is a
+ * type in the barrel only (`X_FACTORY_NAME_SPELLING`), so `new` is never a second spelling.
+ */
+export function memoryAuthAdapter(clock: Clock = systemClock): MemoryAuthAdapter {
+  return new MemoryAuthAdapter(clock);
+}