@cosmicdrift/kumiko-bundled-features 0.149.2 → 0.151.0

package/src/auth-mfa/__tests__/enable-flow.integration.test.ts

@@ -14,6 +14,7 @@ import {
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant";
 import { createUserFeature } from "../../user/feature";
 import { userEntity } from "../../user/schema/user";
 import { base32Decode } from "../base32";
@@ -36,6 +37,7 @@ beforeAll(async () => {
     features: [
       createConfigFeature(),
       createUserFeature(),
+      createTenantFeature(),
       createAuthMfaFeature({
         setupTokenSecret: SETUP_TOKEN_SECRET,
         issuer: "Kumiko Test",
@@ -171,3 +173,61 @@ describe("enable-start + enable-confirm round trip", () => {
     expect(after.enabled).toBe(true);
   });
 });
+
+describe("enable-confirm burns the setup token on first success", () => {
+  test("replaying the same setup token after a disable does not silently re-enable MFA", async () => {
+    const user = createTestUser({ id: "setup-token-replay-1", roles: ["User"] });
+
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: "replay@example.com" },
+      user,
+    );
+    const secretParam = new URLSearchParams(start.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const code = currentTotpCode(base32Decode(secretParam));
+
+    await stack.http.writeOk(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code },
+      user,
+    );
+    await stack.http.writeOk(AuthMfaHandlers.disable, { code }, user);
+
+    // Same setupToken + a still-computable code for the disabled secret —
+    // without burning the token on first confirm this would re-create the
+    // row with the secret the user just discarded.
+    const replay = await stack.http.writeErr(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code: currentTotpCode(base32Decode(secretParam)) },
+      user,
+    );
+    expectErrorIncludes(replay, "invalid_setup_token");
+
+    const after = await stack.http.queryOk<{ enabled: boolean }>(AuthMfaQueries.status, {}, user);
+    expect(after.enabled).toBe(false);
+  });
+
+  test("a second confirm of the same setup token (already enabled) is rejected, not a raw db error", async () => {
+    const user = createTestUser({ id: "setup-token-double-confirm-1", roles: ["User"] });
+
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: "double@example.com" },
+      user,
+    );
+    const secretParam = new URLSearchParams(start.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const code = currentTotpCode(base32Decode(secretParam));
+
+    await stack.http.writeOk(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code },
+      user,
+    );
+    const second = await stack.http.writeErr(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code: currentTotpCode(base32Decode(secretParam)) },
+      user,
+    );
+    expectErrorIncludes(second, "invalid_setup_token");
+  });
+});

package/src/auth-mfa/__tests__/pii-subject-encryption.integration.test.ts

@@ -27,6 +27,7 @@ import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing"
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant";
 import { createUserFeature } from "../../user/feature";
 import { userEntity } from "../../user/schema/user";
 import { base32Decode } from "../base32";
@@ -47,6 +48,7 @@ beforeAll(async () => {
     features: [
       createConfigFeature(),
       createUserFeature(),
+      createTenantFeature(),
       createAuthMfaFeature({
         setupTokenSecret: SETUP_TOKEN_SECRET,
         issuer: "Kumiko Test",

package/src/auth-mfa/__tests__/reencrypt-job.integration.test.ts

@@ -32,6 +32,7 @@ import { createMutableMasterKeyProvider } from "@cosmicdrift/kumiko-framework/te
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant";
 import { createUserFeature } from "../../user/feature";
 import { userEntity } from "../../user/schema/user";
 import { base32Decode } from "../base32";
@@ -64,6 +65,7 @@ beforeAll(async () => {
     features: [
       createConfigFeature(),
       createUserFeature(),
+      createTenantFeature(),
       createAuthMfaFeature({
         setupTokenSecret: SETUP_TOKEN_SECRET,
         issuer: "Kumiko Test",

package/src/auth-mfa/__tests__/session-auto-revoke.integration.test.ts

@@ -17,6 +17,7 @@ import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
 import { userSessionEntity, userSessionTable } from "../../sessions/schema/user-session";
 import { createSessionCallbacks } from "../../sessions/session-callbacks";
+import { createTenantFeature } from "../../tenant";
 import { createUserFeature } from "../../user/feature";
 import { userEntity } from "../../user/schema/user";
 import { base32Decode } from "../base32";
@@ -44,7 +45,7 @@ beforeAll(async () => {
     challengeTokenSecret: "test-mfa-challenge-secret-at-least-32-bytes!!",
   });
   stack = await setupTestStack({
-    features: [createConfigFeature(), createUserFeature(), mfaFeature],
+    features: [createConfigFeature(), createUserFeature(), createTenantFeature(), mfaFeature],
     extraContext: { configResolver: resolver, configEncryption: encryption },
   });
 

package/src/auth-mfa/__tests__/totp.test.ts

@@ -37,12 +37,20 @@ describe("TOTP — RFC 6238 vectors", () => {
   test("accepts a code one step in the past or future (clock drift)", () => {
     const secret = generateTotpSecret();
     const now = 1_700_000_000_000;
-    // Derive the code for now, then verify it's still accepted 25s later —
-    // same 30s step, no window needed, sanity check for the step math.
+    // now + 25s crosses the 30s step boundary (deliberately) — this exercises
+    // the ±1 window, not same-step reuse. See the ±2-steps negative test below
+    // for the window's upper bound.
     const codeAtNow = deriveCodeForTest(secret, now);
     expect(verifyTotp(secret, codeAtNow, now + 25_000)).toBe(true);
   });
 
+  test("rejects a code two steps in the future (outside the ±1 window)", () => {
+    const secret = generateTotpSecret();
+    const now = 1_700_000_000_000;
+    const codeAtNow = deriveCodeForTest(secret, now);
+    expect(verifyTotp(secret, codeAtNow, now + 2 * 30_000 + 5_000)).toBe(false);
+  });
+
   test("rejects wrong-length or non-numeric input without throwing", () => {
     const secret = generateTotpSecret();
     expect(verifyTotp(secret, "12345")).toBe(false);
@@ -56,6 +64,7 @@ describe("TOTP — RFC 6238 vectors", () => {
     const b = generateTotpSecret();
     expect(a.length).toBe(20);
     expect(a.equals(b)).toBe(false);
+    expect(a.some((byte) => byte !== 0)).toBe(true);
   });
 });
 

package/src/auth-mfa/__tests__/verify.integration.test.ts

@@ -1,4 +1,5 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -11,6 +12,7 @@ import {
 import {
   createTestEnvelopeCipher,
   expectErrorIncludes,
+  seedRow,
 } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
@@ -18,8 +20,9 @@ import { configValuesTable } from "../../config/table";
 import { createTenantFeature } from "../../tenant";
 import { tenantMembershipsTable } from "../../tenant/membership-table";
 import { tenantEntity } from "../../tenant/schema/tenant";
+import { USER_STATUS } from "../../user";
 import { createUserFeature } from "../../user/feature";
-import { userEntity } from "../../user/schema/user";
+import { userEntity, userTable } from "../../user/schema/user";
 import { base32Decode } from "../base32";
 import { AuthMfaHandlers } from "../constants";
 import { createAuthMfaFeature } from "../feature";
@@ -87,6 +90,15 @@ async function enableMfaFor(idSeed: number): Promise<{
     { setupToken: start.setupToken, code: currentTotpCode(secret) },
     user,
   );
+  // verify.write.ts re-checks tenant membership the same way login.write.ts
+  // does — without a seeded row here every verify would now hit the
+  // membership-revoked gate below instead of the scenario each test means
+  // to exercise.
+  await seedRow(stack.db, tenantMembershipsTable, {
+    userId: user.id,
+    tenantId: user.tenantId,
+    roles: JSON.stringify(["User"]),
+  });
   return { user, secret, recoveryCodes: start.recoveryCodes };
 }
 
@@ -184,3 +196,57 @@ describe("mfa verify — completes a two-step login", () => {
     expectErrorIncludes(err, "invalid_challenge_token");
   });
 });
+
+describe("mfa verify — re-checks account state the way login.write.ts does", () => {
+  test("membership revoked between login and verify → challenge rejected, no fallback to global roles", async () => {
+    const { user, secret } = await enableMfaFor(5);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+
+    // Simulate the membership being pulled after the challenge token was
+    // issued but before verify runs — the exact gap login.write.ts's
+    // noMembership() guards against.
+    await asRawClient(stack.db).unsafe(
+      `DELETE FROM "${tenantMembershipsTable.tableName}" WHERE user_id = $1 AND tenant_id = $2`,
+      [user.id, user.tenantId],
+    );
+
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_challenge_token");
+  });
+
+  test("account restricted between login and verify → challenge rejected", async () => {
+    const { user, secret } = await enableMfaFor(6);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+
+    // auth-mfa never writes a read_users row itself (enableMfaFor only
+    // drives enable-start/enable-confirm) — seed one so the status gate has
+    // a row to actually flip, then flip it to simulate a restriction landing
+    // between login and verify.
+    await seedRow(stack.db, userTable, {
+      id: user.id,
+      tenantId: user.tenantId,
+      email: `user-${user.id}@example.com`,
+      passwordHash: "h",
+      displayName: "Restricted User",
+      locale: "de",
+      emailVerified: true,
+      roles: "[]",
+      status: USER_STATUS.Active,
+    });
+    await asRawClient(stack.db).unsafe(
+      `UPDATE "${userTable.tableName}" SET status = $1 WHERE id = $2`,
+      [USER_STATUS.Restricted, user.id],
+    );
+
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_challenge_token");
+  });
+});

package/src/auth-mfa/base32.ts

@@ -27,7 +27,7 @@ export function base32Encode(bytes: Buffer): string {
 // character so a corrupted stored secret fails loud at read time instead of
 // silently producing wrong codes.
 export function base32Decode(encoded: string): Buffer {
-  const clean = encoded.trim().toUpperCase().replace(/\s+/g, "");
+  const clean = encoded.trim().toUpperCase().replace(/\s+/g, "").replace(/=+$/, "");
   let bits = 0;
   let value = 0;
   const bytes: number[] = [];
@@ -41,5 +41,11 @@ export function base32Decode(encoded: string): Buffer {
       bits -= 8;
     }
   }
+  // Leftover bits must be padding zeros (a canonical-length encoding never
+  // leaves a full byte's worth, i.e. >=5 residual bits) — anything else means
+  // truncated/non-canonical input decoded to the wrong byte count.
+  if (bits >= 5 || (value & ((1 << bits) - 1)) !== 0) {
+    throw new Error("base32Decode: invalid length or non-zero padding bits");
+  }
   return Buffer.from(bytes);
 }

package/src/auth-mfa/constants.ts

@@ -19,6 +19,20 @@ export const AuthMfaQueries = {
   status: "auth-mfa:query:user-mfa:status",
 } as const;
 
+// Write-failure codes shared between errors.ts (server, mints them into
+// UnprocessableError) and web/mfa-error-keys.ts (client, maps them to i18n
+// keys) — one source so a renamed code can't drift out of sync between the
+// two switches.
+export const AuthMfaErrorCodes = {
+  mfaAlreadyEnabled: "mfa_already_enabled",
+  mfaNotEnabled: "mfa_not_enabled",
+  invalidSetupToken: "invalid_setup_token",
+  invalidTotpCode: "invalid_totp_code",
+  invalidRecoveryCode: "invalid_recovery_code",
+  invalidChallengeToken: "invalid_challenge_token",
+  tooManyAttempts: "too_many_attempts",
+} as const;
+
 export const MFA_SETUP_TOKEN_TTL_MINUTES = 10;
 export const MFA_CHALLENGE_TOKEN_TTL_MINUTES = 10;
 export const MFA_VERIFY_MAX_ATTEMPTS = 5;

package/src/auth-mfa/errors.ts

@@ -3,20 +3,13 @@ import {
   type WriteFailure,
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
+import { AuthMfaErrorCodes } from "./constants";
 
-export const AuthMfaErrors = {
-  mfaAlreadyEnabled: "mfa_already_enabled",
-  mfaNotEnabled: "mfa_not_enabled",
-  invalidSetupToken: "invalid_setup_token",
-  invalidTotpCode: "invalid_totp_code",
-  invalidRecoveryCode: "invalid_recovery_code",
-  invalidChallengeToken: "invalid_challenge_token",
-  tooManyAttempts: "too_many_attempts",
-} as const;
+export { AuthMfaErrorCodes as AuthMfaErrors } from "./constants";
 
 export function mfaAlreadyEnabled(): WriteFailure {
   return writeFailure(
-    new UnprocessableError(AuthMfaErrors.mfaAlreadyEnabled, {
+    new UnprocessableError(AuthMfaErrorCodes.mfaAlreadyEnabled, {
       i18nKey: "authMfa.errors.mfaAlreadyEnabled",
     }),
   );
@@ -24,7 +17,7 @@ export function mfaAlreadyEnabled(): WriteFailure {
 
 export function mfaNotEnabled(): WriteFailure {
   return writeFailure(
-    new UnprocessableError(AuthMfaErrors.mfaNotEnabled, {
+    new UnprocessableError(AuthMfaErrorCodes.mfaNotEnabled, {
       i18nKey: "authMfa.errors.mfaNotEnabled",
     }),
   );
@@ -32,7 +25,7 @@ export function mfaNotEnabled(): WriteFailure {
 
 export function invalidSetupToken(): WriteFailure {
   return writeFailure(
-    new UnprocessableError(AuthMfaErrors.invalidSetupToken, {
+    new UnprocessableError(AuthMfaErrorCodes.invalidSetupToken, {
       i18nKey: "authMfa.errors.invalidSetupToken",
     }),
   );
@@ -40,7 +33,7 @@ export function invalidSetupToken(): WriteFailure {
 
 export function invalidTotpCode(): WriteFailure {
   return writeFailure(
-    new UnprocessableError(AuthMfaErrors.invalidTotpCode, {
+    new UnprocessableError(AuthMfaErrorCodes.invalidTotpCode, {
       i18nKey: "authMfa.errors.invalidTotpCode",
     }),
   );
@@ -48,7 +41,7 @@ export function invalidTotpCode(): WriteFailure {
 
 export function invalidRecoveryCode(): WriteFailure {
   return writeFailure(
-    new UnprocessableError(AuthMfaErrors.invalidRecoveryCode, {
+    new UnprocessableError(AuthMfaErrorCodes.invalidRecoveryCode, {
       i18nKey: "authMfa.errors.invalidRecoveryCode",
     }),
   );
@@ -56,7 +49,7 @@ export function invalidRecoveryCode(): WriteFailure {
 
 export function invalidChallengeToken(): WriteFailure {
   return writeFailure(
-    new UnprocessableError(AuthMfaErrors.invalidChallengeToken, {
+    new UnprocessableError(AuthMfaErrorCodes.invalidChallengeToken, {
       i18nKey: "authMfa.errors.invalidChallengeToken",
     }),
   );
@@ -65,7 +58,7 @@ export function invalidChallengeToken(): WriteFailure {
 // retryAfterSeconds drives the login UI countdown — must stay > 0.
 export function tooManyAttempts(retryAfterSeconds: number): WriteFailure {
   return writeFailure(
-    new UnprocessableError(AuthMfaErrors.tooManyAttempts, {
+    new UnprocessableError(AuthMfaErrorCodes.tooManyAttempts, {
       i18nKey: "authMfa.errors.tooManyAttempts",
       details: { retryAfterSeconds },
     }),

package/src/auth-mfa/feature.ts

@@ -80,7 +80,11 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
     });
     r.requires("user");
     r.requires("config");
-    r.config({ keys: { required: mfaRequiredConfigKey() } });
+    // verify.write.ts dispatches "tenant:query:memberships" — without this
+    // the app boots clean and the first MFA login dies at runtime on an
+    // unknown handler instead of failing at mount time.
+    r.requires("tenant");
+    r.configKey("required", mfaRequiredConfigKey());
 
     // Dormant custom-screen — the client maps MFA_ENABLE_SCREEN_ID to
     // MfaEnableScreen (see personal-access-tokens/feature.ts for the same

package/src/auth-mfa/handlers/enable-confirm.write.ts

@@ -2,8 +2,10 @@ import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
+import { burnToken } from "../../shared";
 import { base32Decode } from "../base32";
-import { invalidSetupToken, invalidTotpCode } from "../errors";
+import { findUserMfaRow } from "../db/queries";
+import { invalidSetupToken, invalidTotpCode, mfaAlreadyEnabled } from "../errors";
 import { verifyMfaSetupToken } from "../mfa-setup-token";
 import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
 import { verifyTotp } from "../totp";
@@ -42,6 +44,23 @@ export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
       const secret = base32Decode(verify.payload.totpSecretBase32);
       if (!verifyTotp(secret, event.payload.code)) return invalidTotpCode();
 
+      // Burn the setup token on the first successful confirm — without this
+      // a `disable` doesn't retire it (re-enabling with the secret the user
+      // thinks they discarded), and two parallel confirms both proceed to
+      // executor.create instead of the second seeing mfa_already_enabled().
+      if (ctx.redis) {
+        const burnResult = await burnToken(
+          ctx.redis,
+          "mfa-setup",
+          event.user.id,
+          verify.expiresAtMs,
+        );
+        if (burnResult === "already-used") return invalidSetupToken();
+      }
+
+      const existing = await findUserMfaRow(ctx.db, event.user);
+      if (existing) return mfaAlreadyEnabled();
+
       const result = await executor.create(
         {
           userId: event.user.id,

package/src/auth-mfa/handlers/verify.write.ts

@@ -8,7 +8,7 @@ import {
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
 import { burnToken } from "../../shared";
-import { UserQueries } from "../../user";
+import { USER_STATUS, UserQueries } from "../../user";
 import { MFA_VERIFY_LOCKOUT_MINUTES, MFA_VERIFY_MAX_ATTEMPTS } from "../constants";
 import { findUserMfaRow } from "../db/queries";
 import { invalidChallengeToken, invalidTotpCode, tooManyAttempts } from "../errors";
@@ -121,14 +121,37 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
       const userRow = (await ctx.queryAs(systemUser, UserQueries.detail, {
         id: userId,
-      })) as { roles?: string | null } | null; // @cast-boundary engine-payload
+      })) as { roles?: string | null; status?: string } | null; // @cast-boundary engine-payload
+
+      // Re-check status + membership the way login.write.ts does after its
+      // password check — the challenge token only proves "password was
+      // correct 10 minutes ago", not that the account is still loginable
+      // now. Deliberately NOT re-checking strictEmailVerification here:
+      // MfaVerifyOptions has no such flag, and email verification can't
+      // regress between login and verify within the 10-minute window.
+      if (
+        userRow?.status === USER_STATUS.Restricted ||
+        userRow?.status === USER_STATUS.DeletionRequested ||
+        userRow?.status === USER_STATUS.Deleted
+      ) {
+        return invalidChallengeToken();
+      }
+
       const globalRoles = parseRoles(userRow?.roles ?? null);
 
       const memberships = (await ctx.queryAs(systemUser, "tenant:query:memberships", {
         userId,
       })) as ReadonlyArray<{ tenantId: string; roles: readonly string[] }>; // @cast-boundary engine-payload
       const membership = memberships.find((m) => m.tenantId === tenantId);
-      const mergedRoles = buildSessionRoles(globalRoles, membership?.roles ?? []);
+      // Membership revoked between login and verify (race, or a stale
+      // challenge token from before removal) — login.write.ts would have
+      // refused with noMembership() at the same juncture; mirror it here
+      // instead of silently falling back to globalRoles only.
+      if (!membership) return invalidChallengeToken();
+      // buildSessionRoles calls stripForbiddenMembershipRoles to strip reserved
+      // roles from the membership portion (globalRoles keeps SystemAdmin) —
+      // read-time backstop against a rebuild-resurrected role.
+      const mergedRoles = buildSessionRoles(globalRoles, membership.roles);
 
       const baseSession: SessionUser = { id: userId, tenantId, roles: mergedRoles };
       const claims = await ctx.resolveAuthClaims(baseSession);

package/src/auth-mfa/index.ts

@@ -17,4 +17,3 @@ export {
 } from "./feature";
 export type { MfaStatusChecker, MfaStatusCheckResult } from "./mfa-status-checker";
 export { userMfaEntity, userMfaTable } from "./schema/user-mfa";
-export { currentTotpCode } from "./totp";

package/src/auth-mfa/recovery-codes.ts

@@ -7,6 +7,15 @@ const RECOVERY_CODE_COUNT = 8;
 // ticket, not just a retry.
 const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
 
+// Recovery codes get read aloud or copy-typed from a screen — a user retyping
+// "abcd1234" lowercase or without the dash must still match. Applied on both
+// sides (hash-time here is a no-op on freshly generated codes, but keeps
+// hash and verify deckungsgleich if generation ever changes) so a formatting
+// slip never surfaces as "wrong code" for an otherwise-correct code.
+function normalizeRecoveryCode(code: string): string {
+  return code.toUpperCase().replace(/[^A-Z2-9]/g, "");
+}
+
 function randomCodeGroup(): string {
   let out = "";
   for (let i = 0; i < 4; i++) {
@@ -26,7 +35,7 @@ export function generateRecoveryCodes(count: number = RECOVERY_CODE_COUNT): stri
 // Reuses the same argon2id hashing as passwords — recovery codes are
 // bearer-secrets of comparable sensitivity (whoever has one can log in).
 export async function hashRecoveryCodes(codes: readonly string[]): Promise<string[]> {
-  return Promise.all(codes.map((code) => hashPassword(code)));
+  return Promise.all(codes.map((code) => hashPassword(normalizeRecoveryCode(code))));
 }
 
 // Sequential (not Promise.all) — recovery-code lists are ≤8 entries, and a
@@ -36,9 +45,10 @@ export async function findMatchingRecoveryCodeIndex(
   code: string,
   hashes: readonly string[],
 ): Promise<number> {
+  const normalized = normalizeRecoveryCode(code);
   for (let i = 0; i < hashes.length; i++) {
     const hash = hashes[i];
-    if (hash !== undefined && (await verifyPassword(hash, code))) return i;
+    if (hash !== undefined && (await verifyPassword(hash, normalized))) return i;
   }
   return -1;
 }

package/src/auth-mfa/schema/user-mfa.ts

@@ -33,6 +33,9 @@ export const userMfaEntity = createEntity({
     // (see db/queries.ts's findUserMfaRow) rather than storing jsonb here.
     // A redeemed code's hash is removed from the array (see disable/regen
     // handlers), so array length also IS the remaining-codes count.
+    // No jsonb->text migration: zero-legacy/single-user framework repo, no
+    // production user_mfa rows exist to backfill (delete-and-re-enroll is
+    // the upgrade path for anyone who hit the old jsonb shape locally).
     recoveryCodes: createTextField({
       required: true,
       encrypted: true,

package/src/auth-mfa/testing.ts

@@ -0,0 +1,5 @@
+// Test-only helper — not part of the runtime surface (a real client never
+// derives a code from the raw secret; the authenticator app does that).
+// Kept out of the main "./auth-mfa" barrel so consumers don't see a
+// server-side "valid code now" generator in autocomplete.
+export { currentTotpCode } from "./totp";

package/src/auth-mfa/web/__tests__/mfa-error-keys.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { AuthMfaErrorCodes } from "../../constants";
+import { defaultTranslations } from "../i18n";
+import { mfaManageErrorKey } from "../mfa-error-keys";
+
+describe("mfaManageErrorKey", () => {
+  for (const code of Object.values(AuthMfaErrorCodes)) {
+    test(`${code} maps to a key registered in en/de translations`, () => {
+      const key = mfaManageErrorKey(code);
+      expect(defaultTranslations["en"]?.[key]).toBeDefined();
+      expect(defaultTranslations["de"]?.[key]).toBeDefined();
+    });
+  }
+
+  test("unknown code falls back to the generic verifyFailed key", () => {
+    const key = mfaManageErrorKey("some_future_server_code");
+    expect(key).toBe("auth.mfa.errors.verifyFailed");
+    expect(defaultTranslations["en"]?.[key]).toBeDefined();
+  });
+});

package/src/auth-mfa/web/i18n.ts

@@ -13,6 +13,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.mfa.verify.code": "Code",
     "auth.mfa.verify.submit": "Bestätigen",
     "auth.mfa.verify.submitting": "…",
+    "auth.mfa.verify.backToLogin": "Zurück zum Login",
     "auth.mfa.errors.invalidCode": "Ungültiger Code. Bitte erneut versuchen.",
     "auth.mfa.errors.challengeExpired": "Die Anmeldung ist abgelaufen. Bitte erneut einloggen.",
     "auth.mfa.errors.tooManyAttempts": "Zu viele Fehlversuche. Bitte erneut einloggen.",
@@ -62,6 +63,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.mfa.verify.code": "Code",
     "auth.mfa.verify.submit": "Verify",
     "auth.mfa.verify.submitting": "…",
+    "auth.mfa.verify.backToLogin": "Back to login",
     "auth.mfa.errors.invalidCode": "Invalid code. Please try again.",
     "auth.mfa.errors.challengeExpired": "Your sign-in has expired. Please sign in again.",
     "auth.mfa.errors.tooManyAttempts": "Too many failed attempts. Please sign in again.",