@cosmicdrift/kumiko-bundled-features 0.155.1 → 0.156.0

package/src/agent-tools/types.ts

@@ -0,0 +1,38 @@
+import type { EntityDefinition, QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+
+/** Mirrors `ToolDefinition` in `@cosmicdriftgamestudio/kumiko-ai-foundation` (providers/types.ts)
+ *  field-for-field so a generated catalog needs no translation layer at the call site. Kept as
+ *  a local, dependency-free type — agent-tools has no ai-foundation/enterprise dependency. */
+export type ToolDefinition = {
+  readonly name: string;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly description: string;
+};
+
+/** Narrow, handler-first view of `Registry` — iterate query handlers (real, mounted, callable
+ *  QNs) rather than entities, so the catalog never advertises a tool for an entity that has no
+ *  `:list` handler mounted. Small enough that tests pass a plain object instead of a full
+ *  64-getter Registry. */
+export type RegistrySearchView = {
+  getAllQueryHandlers(): ReadonlyMap<string, QueryHandlerDef>;
+  getHandlerEntity(qualifiedHandler: string): string | undefined;
+  getEntity(entityName: string): EntityDefinition | undefined;
+  getSearchableFields(entityName: string): readonly string[];
+};
+
+/** How to actually execute a generated tool — kept out of `ToolDefinition` (which mirrors the
+ *  LLM-facing shape exactly) so dispatch never has to re-parse the tool name back into an entity
+ *  + field. `buildToolCatalog` produces one of these per tool, keyed by tool name. */
+export type ToolDispatchDescriptor =
+  | { readonly kind: "search"; readonly entityName: string; readonly qn: string }
+  | {
+      readonly kind: "findBy";
+      readonly entityName: string;
+      readonly fieldName: string;
+      readonly qn: string;
+    };
+
+export type ToolCatalog = {
+  readonly tools: readonly ToolDefinition[];
+  readonly dispatchTable: ReadonlyMap<string, ToolDispatchDescriptor>;
+};

package/src/auth-email-password/web/__tests__/signup-complete-screen.test.tsx

@@ -3,6 +3,8 @@ import { fireEvent, screen, waitFor } from "@testing-library/react";
 import { SignupCompleteScreen } from "../signup-complete-screen";
 import { renderWithProviders } from "./test-utils";
 
+const realFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () =>
@@ -15,7 +17,9 @@ beforeEach(() => {
       ),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
 
 function fillPasswords(password: string, confirm: string): void {
   fireEvent.change(document.getElementById("signup-password") as HTMLInputElement, {

package/src/auth-email-password/web/__tests__/signup-screen.test.tsx

@@ -3,12 +3,16 @@ import { fireEvent, screen, waitFor } from "@testing-library/react";
 import { SignupScreen } from "../signup-screen";
 import { renderWithProviders } from "./test-utils";
 
+const realFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
 
 function fillEmail(value: string): void {
   fireEvent.change(document.getElementById("signup-email") as HTMLInputElement, {

package/src/auth-email-password/web/auth-gate.tsx

@@ -41,8 +41,11 @@ export type LoginRouteOptions = {
 // apex pages stack providers, not gates — see auth-mount.tsx recipes).
 // Handing an app raw LoginScreen + telling it to hand-roll the challenge-
 // token swap itself is exactly how kumiko-framework#266's login-time MFA
-// step went missing in a real apex surface; this makes that mistake
-// structurally unavailable — there is no lower-level piece left to misuse.
+// step went missing in a real apex surface; this prevents the *most common*
+// version of that mistake. MFA still only actually works once a consumer
+// wires `mfaVerifyScreen` — omitting it is a silent no-MFA fallback, not
+// something this route can catch on its own (auth-mfa is a separate,
+// optional package).
 export function createLoginRoute(
   opts: LoginRouteOptions = {},
 ): ComponentType<Record<string, never>> {
@@ -51,13 +54,14 @@ export function createLoginRoute(
 
   function LoginRoute(): ReactNode {
     const { status } = useSession();
+    const { onAuthenticated } = opts;
     // Pending challenge-token from LoginScreen's onMfaChallenge. Lives here
     // (not in SessionState) because it's a UI-only transition — the server
     // never considers this session authenticated until verify succeeds.
     const [challengeToken, setChallengeToken] = useState<string | null>(null);
 
     useEffect(() => {
-      if (status === "authenticated") opts.onAuthenticated?.();
+      if (status === "authenticated") onAuthenticated?.();
     }, [status]);
 
     if (status === "loading") {
@@ -65,7 +69,13 @@ export function createLoginRoute(
         <div className="min-h-screen flex items-center justify-center text-muted-foreground text-sm" />
       );
     }
-    if (status === "authenticated") return null;
+    // A standalone mount (no parent gate, no onAuthenticated wired — e.g. an
+    // apex/marketing surface that just places <LoginRoute /> directly) has no
+    // way to navigate away once authenticated. Blanking the page there is a
+    // regression against the old raw LoginScreen (which had no session check
+    // at all); fall through to the form instead. A route WITH onAuthenticated
+    // still returns null and trusts the effect above to redirect.
+    if (status === "authenticated" && onAuthenticated) return null;
     if (challengeToken !== null && MfaVerifyComponent) {
       return (
         <MfaVerifyComponent

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

@@ -230,4 +230,93 @@ describe("enable-confirm burns the setup token on first success", () => {
     );
     expectErrorIncludes(second, "invalid_setup_token");
   });
+
+  test("a fresh setup token confirmed while already enabled is rejected as mfa_already_enabled", async () => {
+    const user = createTestUser({ id: "already-enabled-fresh-token-1", roles: ["User"] });
+
+    const firstStart = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: "already-enabled@example.com" },
+      user,
+    );
+    // Requested before the first confirm — enable-start itself rejects with
+    // mfa_already_enabled once a row exists, so a fresh token can only be
+    // minted while the user is still unenrolled. Its expiresAtMs differs
+    // from firstStart's, so burnToken() (keyed on purpose+userId+expiresAtMs)
+    // treats it as fresh rather than a replay when confirmed below — the
+    // only way this confirm reaches findUserMfaRow's existing-row check
+    // (the sole path to mfaAlreadyEnabled()) instead of invalid_setup_token.
+    const secondStart = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: "already-enabled@example.com" },
+      user,
+    );
+    const firstSecret =
+      new URLSearchParams(firstStart.otpauthUri.split("?")[1]).get("secret") ?? "";
+    await stack.http.writeOk(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: firstStart.setupToken, code: currentTotpCode(base32Decode(firstSecret)) },
+      user,
+    );
+
+    const secondSecret =
+      new URLSearchParams(secondStart.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const second = await stack.http.writeErr(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: secondStart.setupToken, code: currentTotpCode(base32Decode(secondSecret)) },
+      user,
+    );
+    expectErrorIncludes(second, "mfa_already_enabled");
+  });
+
+  // Not part of the mfa_already_enabled coverage above — this documents a
+  // separate, already-tracked gap: when both enable-confirms are truly
+  // concurrent, findUserMfaRow's existing-row check can't see the other
+  // request's uncommitted row, so the DB's userId+tenantId unique index
+  // rejects the loser with a raw `unique_violation` instead of the
+  // friendly mfaAlreadyEnabled() error. No duplicate row is ever created
+  // (the invariant this test asserts), but the error surfaced to the
+  // client leaks a DB-internal code. Same class of gap as pr-review
+  // kumiko-framework#952 idx2 (needs-framework-savepoint-primitive) —
+  // tracked there, not fixed here.
+  test("two concurrent enable-confirms for the same user never create two rows, 20x", async () => {
+    for (let i = 0; i < 20; i++) {
+      const user = createTestUser({ id: `concurrent-enable-${i}`, roles: ["User"] });
+
+      const [startA, startB] = await Promise.all([
+        stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+          AuthMfaHandlers.enableStart,
+          { accountLabel: `concurrent-${i}@example.com` },
+          user,
+        ),
+        stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+          AuthMfaHandlers.enableStart,
+          { accountLabel: `concurrent-${i}@example.com` },
+          user,
+        ),
+      ]);
+      const secretA = new URLSearchParams(startA.otpauthUri.split("?")[1]).get("secret") ?? "";
+      const secretB = new URLSearchParams(startB.otpauthUri.split("?")[1]).get("secret") ?? "";
+
+      const [resA, resB] = await Promise.all([
+        stack.http.write(
+          AuthMfaHandlers.enableConfirm,
+          { setupToken: startA.setupToken, code: currentTotpCode(base32Decode(secretA)) },
+          user,
+        ),
+        stack.http.write(
+          AuthMfaHandlers.enableConfirm,
+          { setupToken: startB.setupToken, code: currentTotpCode(base32Decode(secretB)) },
+          user,
+        ),
+      ]);
+      const bodies = (await Promise.all([resA.json(), resB.json()])) as Array<{
+        isSuccess?: boolean;
+        error?: { code?: string };
+      }>;
+
+      expect(bodies.filter((b) => b.isSuccess === true).length).toBe(1);
+      expect(bodies.filter((b) => b.isSuccess !== true).length).toBe(1);
+    }
+  });
 });

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

@@ -24,7 +24,7 @@ describe("TOTP — RFC 6238 vectors", () => {
   test("6-digit code at T=59 matches the last 6 digits of the RFC 8-digit vector", () => {
     const expected8 = rfcVectorCode8Digit(59);
     const expected6 = expected8.slice(-6);
-    expect(verifyTotp(RFC_SECRET, expected6, 59_000)).toBe(true);
+    expect(verifyTotp(RFC_SECRET, expected6, 59_000)).not.toBe(false);
   });
 
   test("rejects a code from a different time window (>±1 step)", () => {
@@ -41,7 +41,7 @@ describe("TOTP — RFC 6238 vectors", () => {
     // 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);
+    expect(verifyTotp(secret, codeAtNow, now + 25_000)).not.toBe(false);
   });
 
   test("rejects a code two steps in the future (outside the ±1 window)", () => {

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

@@ -157,7 +157,7 @@ describe("mfa verify — completes a two-step login", () => {
     expectErrorIncludes(err, "invalid_totp_code");
   });
 
-  test("a challenge token cannot be replayed even with a still-valid TOTP code", async () => {
+  test("an exact-duplicate verify (same challenge token, same code) is rejected", async () => {
     const { user, secret } = await enableMfaFor(4);
     const challengeToken = challengeFor(user.id, user.tenantId);
 
@@ -167,14 +167,39 @@ describe("mfa verify — completes a two-step login", () => {
       GUEST,
     );
 
-    // Same challenge token, same (still time-window-valid) code — must be
-    // rejected because burnToken() marks it used on the first success.
+    // Same challenge token, same (still time-window-valid) code — rejected
+    // by the TOTP-counter burn inside verifyMfaFactor before the challenge-
+    // token burn is even reached (that burn now happens after success).
     const err = await stack.http.writeErr(
       AuthMfaHandlers.verify,
       { challengeToken, code: currentTotpCode(secret) },
       GUEST,
     );
-    expectErrorIncludes(err, "invalid_challenge_token");
+    expectErrorIncludes(err, "invalid_totp_code");
+  });
+
+  test("a TOTP code cannot be replayed across a FRESH challenge token (RFC 6238 §5.2)", async () => {
+    const { user, secret } = await enableMfaFor(105);
+    const code = currentTotpCode(secret);
+
+    const challengeA = challengeFor(user.id, user.tenantId);
+    await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.verify,
+      { challengeToken: challengeA, code },
+      GUEST,
+    );
+
+    // A DIFFERENT challenge token (as a real re-login would mint) but the
+    // SAME still-time-window-valid code — this is the actual attack this
+    // finding is about: a phished/shoulder-surfed code used for a parallel
+    // login, not a naive replay of the whole prior request.
+    const challengeB = challengeFor(user.id, user.tenantId);
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken: challengeB, code },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_totp_code");
   });
 
   test("a malformed challenge token is rejected without leaking account state", async () => {

package/src/auth-mfa/constants.ts

@@ -31,6 +31,10 @@ export const AuthMfaErrorCodes = {
   invalidRecoveryCode: "invalid_recovery_code",
   invalidChallengeToken: "invalid_challenge_token",
   tooManyAttempts: "too_many_attempts",
+  // Client-only: minted by mfa-enable-screen.tsx on a network/QR-render
+  // failure during enrollment, never by errors.ts server-side — kept here
+  // anyway so mfa-error-keys.ts's key-parity test covers it automatically.
+  setupFailed: "setup_failed",
 } as const;
 
 export const MFA_SETUP_TOKEN_TTL_MINUTES = 10;

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

@@ -30,7 +30,8 @@ export function createDisableHandler(opts: DisableOptions) {
       const row = await findUserMfaRow(ctx.db, event.user);
       if (!row) return mfaNotEnabled();
 
-      const verify = await verifyMfaFactor(row, event.payload.code);
+      const replay = ctx.redis ? { redis: ctx.redis, userId: event.user.id } : undefined;
+      const verify = await verifyMfaFactor(row, event.payload.code, replay);
       if (!verify.ok) return invalidTotpCode();
 
       const result = await executor.delete({ id: row.id }, event.user, ctx.db);

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

@@ -7,7 +7,7 @@ import { base32Decode } from "../base32";
 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 { encodeRecoveryCodes, userMfaEntity, userMfaTable } from "../schema/user-mfa";
 import { verifyTotp } from "../totp";
 
 export type EnableConfirmOptions = {
@@ -42,12 +42,18 @@ export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
       if (verify.payload.userId !== event.user.id) return invalidSetupToken();
 
       const secret = base32Decode(verify.payload.totpSecretBase32);
-      if (!verifyTotp(secret, event.payload.code)) return invalidTotpCode();
+      if (verifyTotp(secret, event.payload.code) === false) 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().
+      // ponytail: burned here, not unburned on a later executor.create
+      // failure (unlike login.write.ts's unburnToken pattern) — self-service
+      // enable-start always mints a fresh setup token on demand (no mailed
+      // link to go stale), so the realistic failure path (double-confirm
+      // race sans Redis) is meant to leave the burn standing. Add
+      // unburnToken here if create-failure retries turn out to matter.
       if (ctx.redis) {
         const burnResult = await burnToken(
           ctx.redis,
@@ -67,7 +73,7 @@ export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
           totpSecret: verify.payload.totpSecretBase32,
           // Stored as a JSON string — see schema/user-mfa.ts (recoveryCodes
           // is an encrypted+userOwned text field, both layers need a string).
-          recoveryCodes: JSON.stringify({ hashes: verify.payload.recoveryCodeHashes }),
+          recoveryCodes: encodeRecoveryCodes(verify.payload.recoveryCodeHashes),
           enabledAt: Temporal.Now.instant(),
           lastUsedAt: null,
         },

package/src/auth-mfa/handlers/regenerate-recovery.write.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { findUserMfaRow } from "../db/queries";
 import { invalidTotpCode, mfaNotEnabled } from "../errors";
 import { generateRecoveryCodes, hashRecoveryCodes } from "../recovery-codes";
-import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
+import { encodeRecoveryCodes, userMfaEntity, userMfaTable } from "../schema/user-mfa";
 import { verifyMfaFactor } from "../verify-factor";
 
 export type RegenerateRecoveryOptions = {
@@ -34,7 +34,8 @@ export function createRegenerateRecoveryHandler(opts: RegenerateRecoveryOptions)
       // (deliberately) one of the very codes about to be replaced both
       // count, since either way the presented code is consumed/irrelevant
       // afterward.
-      const verify = await verifyMfaFactor(row, event.payload.code);
+      const replay = ctx.redis ? { redis: ctx.redis, userId: event.user.id } : undefined;
+      const verify = await verifyMfaFactor(row, event.payload.code, replay);
       if (!verify.ok) return invalidTotpCode();
 
       const newCodes = generateRecoveryCodes();
@@ -44,7 +45,7 @@ export function createRegenerateRecoveryHandler(opts: RegenerateRecoveryOptions)
         {
           id: row.id,
           version: row.version,
-          changes: { recoveryCodes: JSON.stringify({ hashes: newHashes }) },
+          changes: { recoveryCodes: encodeRecoveryCodes(newHashes) },
         },
         event.user,
         ctx.db,

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

@@ -18,7 +18,7 @@ import {
   getMfaVerifyLockoutState,
   recordFailedMfaVerifyAttempt,
 } from "../mfa-verify-attempts";
-import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
+import { encodeRecoveryCodes, userMfaEntity, userMfaTable } from "../schema/user-mfa";
 import { verifyMfaFactor } from "../verify-factor";
 
 export type MfaVerifyOptions = {
@@ -78,7 +78,8 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       // bad code, no detail leak about account state.
       if (!row) return invalidChallengeToken();
 
-      const verify = await verifyMfaFactor(row, event.payload.code);
+      const replay = ctx.redis ? { redis: ctx.redis, userId } : undefined;
+      const verify = await verifyMfaFactor(row, event.payload.code, replay);
       if (!verify.ok) {
         if (ctx.redis) {
           await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
@@ -86,6 +87,24 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
         return invalidTotpCode();
       }
 
+      // Burn the challenge token only after a successful code check — a
+      // still-failing attempt (wrong code) must not consume it, so a
+      // fat-fingered retry on the same token still works. The TOTP-counter
+      // burn inside verifyMfaFactor already rejects an exact-duplicate
+      // replay (same token + same code) with invalid_totp_code before this
+      // is reached, so this burn only needs to guard a DIFFERENT code
+      // (recovery, or a still-valid-but-not-yet-burned TOTP step) reused
+      // against the same challenge token.
+      if (ctx.redis) {
+        const burnResult = await burnToken(
+          ctx.redis,
+          "mfa-challenge",
+          userId,
+          verified.expiresAtMs,
+        );
+        if (burnResult === "already-used") return invalidChallengeToken();
+      }
+
       // Recovery-code use consumes the code — persist the reduced hash-list
       // immediately so it can't be replayed. Without this a recovery code
       // would work forever instead of being single-use.
@@ -94,7 +113,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
           {
             id: row.id,
             version: row.version,
-            changes: { recoveryCodes: JSON.stringify({ hashes: verify.remainingHashes }) },
+            changes: { recoveryCodes: encodeRecoveryCodes(verify.remainingHashes) },
           },
           scopedUser,
           scopedDb,
@@ -103,15 +122,6 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       }
 
       if (ctx.redis) {
-        // Burn AFTER a successful verify — a still-failing attempt must not
-        // consume the token, or a fat-fingered code would strand the user.
-        const burnResult = await burnToken(
-          ctx.redis,
-          "mfa-challenge",
-          userId,
-          verified.expiresAtMs,
-        );
-        if (burnResult === "already-used") return invalidChallengeToken();
         await clearMfaVerifyAttempts(ctx.redis, userId);
       }
 

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

@@ -9,8 +9,8 @@ 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
+// sides (hash-time here strips the group separator before hashing, keeping
+// hash and verify identical 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, "");

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

@@ -48,3 +48,13 @@ export const userMfaEntity = createEntity({
 });
 
 export const userMfaTable = buildEntityTable("user-mfa", userMfaEntity);
+
+// Both encryption layers on `recoveryCodes` (entity-field envelope +
+// per-subject crypto-shred) require a string value — every writer
+// stringifies the same `{ hashes }` shape, so it lives here once instead
+// of at each of the three write handlers. Matching read-side helper is
+// `parseJsonOrThrow` in db/queries.ts (parses the full row, not just this
+// field, so it isn't a symmetric pair of this one function).
+export function encodeRecoveryCodes(hashes: readonly string[]): string {
+  return JSON.stringify({ hashes });
+}

package/src/auth-mfa/totp.ts

@@ -3,7 +3,7 @@
 // package for it would be the opposite of lazy.
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 
-const STEP_SECONDS = 30;
+export const STEP_SECONDS = 30;
 const DIGITS = 6;
 const WINDOW = 1; // accept ±1 step (±30s) of clock drift, per the spec's guidance
 
@@ -42,14 +42,26 @@ function totpAt(secret: Buffer, epochSeconds: number): string {
 // Timing-safe across the whole ±WINDOW check, not just the final compare —
 // a TOTP code is the same sensitivity class as a password, brute-forceable
 // over a public /auth/mfa/verify endpoint without it.
-export function verifyTotp(secret: Buffer, code: string, nowMs: number = Date.now()): boolean {
+//
+// Returns the matched HOTP counter (not just true) so callers can burn it —
+// a code accepted once must not verify again within its ±WINDOW validity,
+// per RFC 6238 §5.2. Returns `false` on no match, matching the old boolean
+// contract for callers (like enable-confirm) that don't need replay-burn.
+export function verifyTotp(
+  secret: Buffer,
+  code: string,
+  nowMs: number = Date.now(),
+): number | false {
   if (!/^\d{6}$/.test(code)) return false;
   const codeBuf = Buffer.from(code);
   const nowSeconds = Math.floor(nowMs / 1000);
-  let matched = false;
+  let matchedCounter: number | false = false;
   for (let w = -WINDOW; w <= WINDOW; w++) {
-    const candidate = Buffer.from(totpAt(secret, nowSeconds + w * STEP_SECONDS));
-    if (timingSafeEqual(candidate, codeBuf)) matched = true;
+    const stepSeconds = nowSeconds + w * STEP_SECONDS;
+    const candidate = Buffer.from(totpAt(secret, stepSeconds));
+    if (timingSafeEqual(candidate, codeBuf)) {
+      matchedCounter = Math.floor(stepSeconds / STEP_SECONDS);
+    }
   }
-  return matched;
+  return matchedCounter;
 }

package/src/auth-mfa/verify-factor.ts

@@ -1,7 +1,9 @@
+import type Redis from "ioredis";
+import { burnToken } from "../shared";
 import { base32Decode } from "./base32";
 import type { UserMfaRow } from "./db/queries";
 import { findMatchingRecoveryCodeIndex } from "./recovery-codes";
-import { verifyTotp } from "./totp";
+import { STEP_SECONDS, verifyTotp } from "./totp";
 
 export type MfaFactorVerifyResult =
   | { readonly ok: true; readonly method: "totp" }
@@ -14,12 +16,38 @@ export type MfaFactorVerifyResult =
 // that get `method: "recovery"` must persist `remainingHashes` as the new
 // recoveryCodes.hashes — the matched code is single-use and already
 // excluded from the returned array.
+//
+// `replay` opts into TOTP-counter burn (RFC 6238 §5.2: an accepted code
+// must not verify again within its ±1-step window — otherwise a code an
+// attacker observed once, via phishing proxy or shoulder-surfing, stays
+// usable for ~90s of parallel logins). Omitted where a caller has no
+// ctx.redis available; the code-verify itself still works, just without
+// replay protection for that call.
 export async function verifyMfaFactor(
   row: UserMfaRow,
   code: string,
+  replay?: { readonly redis: Redis; readonly userId: string },
 ): Promise<MfaFactorVerifyResult> {
   const secret = base32Decode(row.totpSecret);
-  if (verifyTotp(secret, code)) return { ok: true, method: "totp" };
+  const counter = verifyTotp(secret, code);
+  if (counter !== false) {
+    if (replay) {
+      // Burn keyed by (userId, row.id, counter) — row.id, not just userId,
+      // because disable+re-enable creates a fresh aggregate with a new
+      // secret: two different secrets can hash to the same counter/step,
+      // and without row.id in the key a burn from the OLD secret would
+      // spuriously reject a fresh code under the NEW one. The counter's
+      // own step-expiry doubles as the burn marker's TTL, so it
+      // self-evicts once the code itself would have expired anyway — same
+      // mechanism as burnToken's HMAC-token callers, just with a synthetic
+      // expiresAtMs.
+      const expiresAtMs = (counter + 1) * STEP_SECONDS * 1000;
+      const burnUserId = `${replay.userId}:${row.id}`;
+      const burned = await burnToken(replay.redis, "mfa-totp", burnUserId, expiresAtMs);
+      if (burned === "already-used") return { ok: false };
+    }
+    return { ok: true, method: "totp" };
+  }
 
   const hashes = row.recoveryCodes.hashes;
   const matchIndex = await findMatchingRecoveryCodeIndex(code, hashes);

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

@@ -21,6 +21,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.mfa.errors.mfaAlreadyEnabled": "Zwei-Faktor-Authentifizierung ist bereits aktiv.",
     "auth.mfa.errors.mfaNotEnabled": "Zwei-Faktor-Authentifizierung ist nicht aktiv.",
     "auth.mfa.errors.invalidSetupToken": "Die Einrichtung ist abgelaufen. Bitte erneut starten.",
+    "auth.mfa.errors.setupFailed": "Einrichtung fehlgeschlagen. Bitte erneut versuchen.",
     "auth.mfa.errors.invalidRecoveryCode": "Ungültiger Recovery-Code.",
     "auth.mfa.enable.title": "Zwei-Faktor-Authentifizierung",
     "auth.mfa.enable.intro":
@@ -71,6 +72,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.mfa.errors.mfaAlreadyEnabled": "Two-factor authentication is already enabled.",
     "auth.mfa.errors.mfaNotEnabled": "Two-factor authentication is not enabled.",
     "auth.mfa.errors.invalidSetupToken": "Setup expired. Please start again.",
+    "auth.mfa.errors.setupFailed": "Setup failed. Please try again.",
     "auth.mfa.errors.invalidRecoveryCode": "Invalid recovery code.",
     "auth.mfa.enable.title": "Two-factor authentication",
     "auth.mfa.enable.intro":

package/src/auth-mfa/web/mfa-enable-screen.tsx

@@ -43,30 +43,6 @@ function extractSecret(otpauthUri: string): string {
   return new URLSearchParams(query).get("secret") ?? "";
 }
 
-// 24x24 viewBox icon paths (Material-style), solid fill. Real SVG paths
-// instead of emoji glyphs — emoji-as-<text> renders inconsistently across
-// font stacks and never centers cleanly (font-specific glyph padding).
-const QR_ICONS = [
-  `<path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z" fill="#ef4444"/>`,
-  `<path d="M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z" fill="#facc15"/>`,
-  `<circle cx="12" cy="12" r="11" fill="#facc15"/><circle cx="8.5" cy="10" r="1.4" fill="#1f2937"/><circle cx="15.5" cy="10" r="1.4" fill="#1f2937"/><path d="M7 14c1 2.2 3 3.4 5 3.4s4-1.2 5-3.4" stroke="#1f2937" stroke-width="1.6" fill="none" stroke-linecap="round"/>`,
-];
-
-// Overlay a random icon in a circle badge over the QR center. cx/cy/r
-// percentages resolve against the SVG viewport regardless of viewBox size,
-// so this string-injection works without parsing qrcode's output dimensions.
-function withIconBadge(svg: string): string {
-  const icon = QR_ICONS[Math.floor(Math.random() * QR_ICONS.length)];
-  const size = Number(svg.match(/viewBox="0 0 (\d+(?:\.\d+)?) /)?.[1] ?? 100);
-  const r = size * 0.16;
-  const iconSize = r * 1.3;
-  const scale = iconSize / 24;
-  const offset = size / 2 - iconSize / 2;
-  // html-ok: icon is one of the fixed QR_ICONS literals above, not user input
-  const badge = `<circle cx="${size / 2}" cy="${size / 2}" r="${r}" fill="#fff" stroke="#e5e7eb" stroke-width="${size * 0.01}"/><g transform="translate(${offset} ${offset}) scale(${scale})">${icon}</g>`;
-  return svg.replace("</svg>", `${badge}</svg>`);
-}
-
 export type MfaEnableScreenProps = {
   readonly embedded?: boolean;
   // Fired once enable-confirm succeeds — MfaEnableScreen has no query of its
@@ -104,11 +80,13 @@ export function MfaEnableScreen({
         setError(res.error.code);
         return;
       }
-      // errorCorrectionLevel "H" (~30% redundancy) so the icon badge overlay
-      // doesn't break scanning.
-      const qrSvg = withIconBadge(
-        await QRCode.toString(res.data.otpauthUri, { type: "svg", errorCorrectionLevel: "H" }),
-      );
+      // errorCorrectionLevel "H" (~30% redundancy) — more resilient to
+      // camera/lighting issues than the default, no downside for a code
+      // this short-lived.
+      const qrSvg = await QRCode.toString(res.data.otpauthUri, {
+        type: "svg",
+        errorCorrectionLevel: "H",
+      });
       setSetup({
         setupToken: res.data.setupToken,
         secretParam: extractSecret(res.data.otpauthUri),

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

@@ -21,6 +21,8 @@ export function mfaManageErrorKey(code: string): string {
       return "auth.mfa.errors.mfaNotEnabled";
     case AuthMfaErrorCodes.invalidSetupToken:
       return "auth.mfa.errors.invalidSetupToken";
+    case AuthMfaErrorCodes.setupFailed:
+      return "auth.mfa.errors.setupFailed";
     default:
       return "auth.mfa.errors.verifyFailed";
   }