@cosmicdrift/kumiko-bundled-features 0.149.2 → 0.150.0

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,6 +80,10 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
     });
     r.requires("user");
     r.requires("config");
+    // 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.config({ keys: { required: mfaRequiredConfigKey() } });
 
     // Dormant custom-screen — the client maps MFA_ENABLE_SCREEN_ID to

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.",

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

@@ -9,7 +9,7 @@
 
 import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
-import QRCode from "qrcode";
+import QRCode from "qrcode/lib/browser";
 import { type ReactNode, useState } from "react";
 // kumiko-lint-ignore cross-feature-import client-only hook, the feature's server barrel has no web/ re-export
 import { useSession } from "../../auth-email-password/web";
@@ -65,42 +65,51 @@ export function MfaEnableScreen({
   const startSetup = async (): Promise<void> => {
     setBusy(true);
     setError(null);
-    const res = await dispatcher.write<EnableStartResponse>(AuthMfaHandlers.enableStart, {
-      accountLabel: session.user?.email ?? "",
-    });
-    if (!res.isSuccess) {
+    try {
+      const res = await dispatcher.write<EnableStartResponse>(AuthMfaHandlers.enableStart, {
+        accountLabel: session.user?.email ?? "",
+      });
+      if (!res.isSuccess) {
+        setError(res.error.code);
+        return;
+      }
+      const qrSvg = await QRCode.toString(res.data.otpauthUri, { type: "svg" });
+      setSetup({
+        setupToken: res.data.setupToken,
+        secretParam: extractSecret(res.data.otpauthUri),
+        recoveryCodes: res.data.recoveryCodes,
+        qrSvg,
+      });
+      setAcknowledged(false);
+      setCode("");
+    } catch {
+      setError("setup_failed");
+    } finally {
       setBusy(false);
-      setError(res.error.code);
-      return;
     }
-    const qrSvg = await QRCode.toString(res.data.otpauthUri, { type: "svg" });
-    setBusy(false);
-    setSetup({
-      setupToken: res.data.setupToken,
-      secretParam: extractSecret(res.data.otpauthUri),
-      recoveryCodes: res.data.recoveryCodes,
-      qrSvg,
-    });
-    setAcknowledged(false);
-    setCode("");
   };
 
   const confirmSetup = async (): Promise<void> => {
     if (!setup) return;
     setBusy(true);
     setError(null);
-    const res = await dispatcher.write(AuthMfaHandlers.enableConfirm, {
-      setupToken: setup.setupToken,
-      code,
-    });
-    setBusy(false);
-    if (!res.isSuccess) {
-      setError(res.error.code);
-      return;
+    try {
+      const res = await dispatcher.write(AuthMfaHandlers.enableConfirm, {
+        setupToken: setup.setupToken,
+        code,
+      });
+      if (!res.isSuccess) {
+        setError(res.error.code);
+        return;
+      }
+      setEnabled(true);
+      setSetup(null);
+      onEnabled?.();
+    } catch {
+      setError("setup_failed");
+    } finally {
+      setBusy(false);
     }
-    setEnabled(true);
-    setSetup(null);
-    onEnabled?.();
   };
 
   const content = (

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

@@ -7,17 +7,19 @@
 // each re-deriving the key ad hoc (enable-screen used to template-string
 // the raw snake_case code straight into the key, which never matched the
 // camelCase keys actually registered below).
+import { AuthMfaErrorCodes } from "../constants";
+
 export function mfaManageErrorKey(code: string): string {
   switch (code) {
-    case "invalid_totp_code":
+    case AuthMfaErrorCodes.invalidTotpCode:
       return "auth.mfa.errors.invalidCode";
-    case "invalid_recovery_code":
+    case AuthMfaErrorCodes.invalidRecoveryCode:
       return "auth.mfa.errors.invalidRecoveryCode";
-    case "mfa_already_enabled":
+    case AuthMfaErrorCodes.mfaAlreadyEnabled:
       return "auth.mfa.errors.mfaAlreadyEnabled";
-    case "mfa_not_enabled":
+    case AuthMfaErrorCodes.mfaNotEnabled:
       return "auth.mfa.errors.mfaNotEnabled";
-    case "invalid_setup_token":
+    case AuthMfaErrorCodes.invalidSetupToken:
       return "auth.mfa.errors.invalidSetupToken";
     default:
       return "auth.mfa.errors.verifyFailed";

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

@@ -21,6 +21,11 @@ export type MfaVerifyScreenProps = {
    *  refreshed. Optional — apps that swap this screen back out purely on
    *  session.status changing to "authenticated" don't need it. */
   readonly onSuccess?: () => void;
+  // Some failures (challenge_expired, too_many_attempts) have no retry path —
+  // the challengeToken is dead. Without this, the host has no way back to
+  // login short of a full page reload. Optional: apps that always mount
+  // this screen fresh per challenge can omit it.
+  readonly onCancel?: () => void;
 };
 
 function reasonToKey(reason: string): string {
@@ -47,6 +52,7 @@ export function MfaVerifyScreen({
   subtitle,
   submitLabel,
   onSuccess,
+  onCancel,
 }: MfaVerifyScreenProps): ReactNode {
   const t = useTranslation();
   const { Form, Field, Input, Button, Banner } = usePrimitives();
@@ -99,6 +105,11 @@ export function MfaVerifyScreen({
               ? t("auth.mfa.verify.submitting")
               : (submitLabel ?? t("auth.mfa.verify.submit"))}
           </Button>
+          {onCancel ? (
+            <Button type="button" variant="secondary" onClick={onCancel} disabled={submitting}>
+              {t("auth.mfa.verify.backToLogin")}
+            </Button>
+          ) : null}
         </Form>
       </div>
     </AuthCard>

package/src/auth-mfa/web/qrcode-browser.d.ts

@@ -0,0 +1,7 @@
+// @types/qrcode only declares the main "qrcode" entry, not the browser-only
+// subpath (see mfa-enable-screen.tsx's import — the main entry pulls in
+// Node-only deps like yargs/pngjs via qrcode's own package.json#browser
+// remap, which Metro doesn't honor). Same runtime shape, just re-typed.
+declare module "qrcode/lib/browser" {
+  export * from "qrcode";
+}

package/src/auth-mfa-user-data/__tests__/hooks.integration.test.ts

@@ -20,6 +20,7 @@ import { currentTotpCode } from "../../auth-mfa/totp";
 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 { userMfaDeleteHook, userMfaExportHook } from "../hooks";
@@ -36,6 +37,7 @@ beforeAll(async () => {
     features: [
       createConfigFeature(),
       createUserFeature(),
+      createTenantFeature(),
       createAuthMfaFeature({
         setupTokenSecret: SETUP_TOKEN_SECRET,
         issuer: "Kumiko Test",

package/src/config/handlers/cascade.query.ts

@@ -2,6 +2,7 @@ import {
   type ConfigCascade,
   type ConfigCascadeLevel,
   defineQueryHandler,
+  isEncryptedAtRest,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
@@ -59,7 +60,7 @@ export const cascadeQuery = defineQueryHandler({
 
       // backing="secrets" is masked like encrypted — the resolver revealed the
       // plaintext for internal reads, but it must never reach the cascade UI.
-      if (keyDef.encrypted || keyDef.backing === "secrets") {
+      if (isEncryptedAtRest(keyDef)) {
         const maskedLevels: ConfigCascadeLevel[] = cascade.levels.map((l) => ({
           ...l,
           value: l.hasValue ? MASKED : l.value,

package/src/config/handlers/values.query.ts

@@ -3,6 +3,7 @@ import {
   type ConfigScope,
   type ConfigValueSource,
   defineQueryHandler,
+  isEncryptedAtRest,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
@@ -63,7 +64,7 @@ export const valuesQuery = defineQueryHandler({
       // key so the plaintext (which the resolver revealed for internal reads)
       // never reaches the UI response.
       let value: string | number | boolean | undefined;
-      if (keyDef.encrypted || keyDef.backing === "secrets") {
+      if (isEncryptedAtRest(keyDef)) {
         value = cascade.value !== undefined ? MASKED : undefined;
       } else {
         value = cascade.value;

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -9,7 +9,9 @@
 //   3. PII-Encrypt (from/to/cc/subject/snippet) VOR dem append —
 //      Event-Log UND Projection tragen Ciphertext (#800-Muster).
 //   4. inbound-message-received-append (Inline-Projection schreibt
-//      read_inbound_messages in derselben TX).
+//      read_inbound_messages in derselben TX). Savepoint-scoped
+//      (ctx.tryAppendEvent) — a losing concurrent ingest for the same
+//      messageAggId returns { duplicate: true } instead of failing the TX.
 //   5. Thread-Rollup: mail-thread-updated-append mit neu berechnetem
 //      Snapshot (count+1, max(lastMessageAt)) — die apply ist ein
 //      dummer UPSERT.
@@ -199,13 +201,24 @@ export const ingestMessageHandler: WriteHandlerDef = {
       providerName: payload.providerName,
       providerCursor: payload.providerCursor,
     };
-    await ctx.unsafeAppendEvent({
+    const messageAppend = await ctx.tryAppendEvent({
       aggregateId: messageAggId,
       aggregateType: INBOUND_MESSAGE_AGGREGATE_TYPE,
       type: INBOUND_MESSAGE_RECEIVED_EVENT_QN,
       payload: messageEventPayload,
       headers: messageHeaders,
     });
+    if (!messageAppend.ok) {
+      // Lost the race against a concurrent ingest for the same messageAggId
+      // (Watch-Push vs. Poll-Reconciliation overlap). The winner already
+      // writes thread-rollup + seen-anchor for this message — steps 5+6
+      // skip here. tryAppendEvent's savepoint keeps this TX usable despite
+      // the caught VersionConflictError (see ctx.tryAppendEvent doc).
+      return {
+        isSuccess: true as const,
+        data: { duplicate: true as const, inboundMessageAggregateId: messageAggId },
+      };
+    }
 
     // ---------------------------------------------------------------
     // 5. Thread-Rollup. Der Handler berechnet den NEUEN Snapshot