@cosmicdrift/kumiko-bundled-features 0.147.1 → 0.147.3

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

@@ -0,0 +1,90 @@
+// Redis-backed brute-force cap for `/auth/mfa/verify`, keyed by userId (NOT
+// by challenge token). Modeled on auth-email-password/lockout-store.ts.
+//
+// Why keyed by userId, not challengeToken: a challenge token is reissued on
+// every successful password login (see mfa-challenge-token.ts) — a fresh
+// token would reset a token-keyed counter to zero, letting an attacker who
+// already has the password just re-login repeatedly to get unlimited TOTP
+// guesses. A 6-digit code with a ±1-step window has 3 valid values out of
+// 10^6; without a cap that survives across challenge reissuance, online
+// brute-force is practical. The counter's lifetime crosses token
+// boundaries on purpose.
+//
+// This is INDEPENDENT of the AuthRoutesConfig.mfaVerifyRateLimit on the
+// framework route (IP-scoped abuse protection for the endpoint itself) —
+// both are needed, neither substitutes for the other.
+
+import type Redis from "ioredis";
+
+export type MfaVerifyLockoutState = {
+  readonly failureCount: number;
+  readonly lockedUntil: number | null;
+};
+
+const COUNT_KEY_PREFIX = "kumiko:auth:mfa-verify:count:";
+const UNTIL_KEY_PREFIX = "kumiko:auth:mfa-verify:until:";
+
+function countKey(userId: string): string {
+  return `${COUNT_KEY_PREFIX}${userId}`;
+}
+function untilKey(userId: string): string {
+  return `${UNTIL_KEY_PREFIX}${userId}`;
+}
+
+export async function getMfaVerifyLockoutState(
+  redis: Redis,
+  userId: string,
+): Promise<MfaVerifyLockoutState | null> {
+  const [countRaw, untilRaw] = await redis.mget(countKey(userId), untilKey(userId));
+  if (countRaw === null) return null;
+  const failureCount = Number(countRaw);
+  if (!Number.isFinite(failureCount)) return null;
+  const lockedUntil = untilRaw !== null ? Number(untilRaw) : null;
+  return {
+    failureCount,
+    lockedUntil: lockedUntil !== null && Number.isFinite(lockedUntil) ? lockedUntil : null,
+  };
+}
+
+// Race-free: INCR is atomic, NX on the until-key means only the attempt
+// that first crosses the threshold anchors the lock window — see
+// lockout-store.ts's recordFailedAttempt for the identical reasoning.
+export async function recordFailedMfaVerifyAttempt(
+  redis: Redis,
+  userId: string,
+  maxAttempts: number,
+  lockoutMinutes: number,
+): Promise<MfaVerifyLockoutState> {
+  const lockDurationMs = lockoutMinutes * 60 * 1000;
+  const ttlSec = Math.max(lockoutMinutes * 60, 24 * 3600);
+
+  const count = await redis.incr(countKey(userId));
+  if (count === 1) {
+    await redis.expire(countKey(userId), ttlSec);
+  }
+
+  let lockedUntil: number | null = null;
+  if (count >= maxAttempts) {
+    const computedUntil = Date.now() + lockDurationMs;
+    const setOk = await redis.set(
+      untilKey(userId),
+      String(computedUntil),
+      "PX",
+      lockDurationMs,
+      "NX",
+    );
+    if (setOk === "OK") {
+      lockedUntil = computedUntil;
+    } else {
+      const existing = await redis.get(untilKey(userId));
+      lockedUntil = existing !== null ? Number(existing) : null;
+    }
+  }
+
+  return { failureCount: count, lockedUntil };
+}
+
+// Called on a successful verify. The only path that resets the streak.
+export async function clearMfaVerifyAttempts(redis: Redis, userId: string): Promise<void> {
+  await redis.del(countKey(userId), untilKey(userId));
+}

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

@@ -0,0 +1,44 @@
+import { randomInt } from "node:crypto";
+import { hashPassword, verifyPassword } from "../shared";
+
+const RECOVERY_CODE_COUNT = 8;
+// No ambiguous chars (0/O, 1/I) — these get read aloud or copy-typed from a
+// screen during account-recovery, a context where a misread costs a support
+// ticket, not just a retry.
+const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+
+function randomCodeGroup(): string {
+  let out = "";
+  for (let i = 0; i < 4; i++) {
+    out += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
+  }
+  return out;
+}
+
+function generateRecoveryCode(): string {
+  return `${randomCodeGroup()}-${randomCodeGroup()}`;
+}
+
+export function generateRecoveryCodes(count: number = RECOVERY_CODE_COUNT): string[] {
+  return Array.from({ length: count }, generateRecoveryCode);
+}
+
+// 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)));
+}
+
+// Sequential (not Promise.all) — recovery-code lists are ≤8 entries, and a
+// user typing a wrong code should not pay 8x argon2 cost when the first
+// hash already matches.
+export async function findMatchingRecoveryCodeIndex(
+  code: string,
+  hashes: readonly string[],
+): Promise<number> {
+  for (let i = 0; i < hashes.length; i++) {
+    const hash = hashes[i];
+    if (hash !== undefined && (await verifyPassword(hash, code))) return i;
+  }
+  return -1;
+}

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

@@ -0,0 +1,40 @@
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createJsonbField,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// One row per (userId, tenantId) — presence of a row IS "MFA enabled" for
+// that user. Event-sourced (not unmanagedTable): enable/disable/regenerate
+// are rare, auditable state changes, not a hot-path lookup like sessions —
+// mfa.enabled/disabled fall out of the event stream instead of being
+// manually emitted.
+export const userMfaEntity = createEntity({
+  table: "read_user_mfa",
+  fields: {
+    // FK to the user row, not content — PII-naming heuristic would flag
+    // "userId" as content; it's a pseudonymous reference, matching the same
+    // annotation `config`'s userId column uses.
+    userId: createTextField({ required: true, allowPlaintext: "pseudonymous-fk" }),
+    // Envelope-encrypted via the same MasterKeyProvider as secrets/config
+    // (entity-field-encryption.ts) — no manual wrapDek/unwrapDek needed.
+    // userOwned: crypto-shredding this field is exactly "revoke this
+    // user's 2FA on GDPR forget", which is the correct behavior anyway.
+    totpSecret: createTextField({
+      required: true,
+      encrypted: true,
+      userOwned: { ownerField: "userId" },
+    }),
+    // { hashes: string[] } — argon2id hashes of unredeemed recovery codes.
+    // A redeemed code's hash is removed from the array (see disable/regen
+    // handlers), so array length also IS the remaining-codes count.
+    recoveryCodes: createJsonbField({ userOwned: { ownerField: "userId" } }),
+    enabledAt: createTimestampField({ required: true }),
+    lastUsedAt: createTimestampField(),
+  },
+  indexes: [{ unique: true, columns: ["userId", "tenantId"], name: "read_user_mfa_user_unique" }],
+});
+
+export const userMfaTable = buildEntityTable("user-mfa", userMfaEntity);

package/src/auth-mfa/totp.ts

@@ -27,6 +27,14 @@ function hotp(secret: Buffer, counter: number): string {
   return String(truncated % 10 ** DIGITS).padStart(DIGITS, "0");
 }
 
+// Exposed for callers that need to derive "the code right now" — the
+// enable-confirm/verify UI flows show a live-updating code client-side
+// (via their own TOTP lib or a countdown), and tests need a code to submit
+// without hand-rolling the HMAC math again.
+export function currentTotpCode(secret: Buffer, nowMs: number = Date.now()): string {
+  return totpAt(secret, Math.floor(nowMs / 1000));
+}
+
 function totpAt(secret: Buffer, epochSeconds: number): string {
   return hotp(secret, Math.floor(epochSeconds / STEP_SECONDS));
 }

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

@@ -0,0 +1,30 @@
+import { base32Decode } from "./base32";
+import type { UserMfaRow } from "./db/queries";
+import { findMatchingRecoveryCodeIndex } from "./recovery-codes";
+import { verifyTotp } from "./totp";
+
+export type MfaFactorVerifyResult =
+  | { readonly ok: true; readonly method: "totp" }
+  | { readonly ok: true; readonly method: "recovery"; readonly remainingHashes: readonly string[] }
+  | { readonly ok: false };
+
+// Shared by disable/regenerate-recovery (and later /auth/mfa/verify): tries
+// TOTP first (cheap HMAC), falls back to recovery codes (argon2, slower —
+// this is the rare path) only when the code isn't a valid TOTP. Callers
+// 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.
+export async function verifyMfaFactor(
+  row: UserMfaRow,
+  code: string,
+): Promise<MfaFactorVerifyResult> {
+  const secret = base32Decode(row.totpSecret);
+  if (verifyTotp(secret, code)) return { ok: true, method: "totp" };
+
+  const hashes = row.recoveryCodes.hashes;
+  const matchIndex = await findMatchingRecoveryCodeIndex(code, hashes);
+  if (matchIndex === -1) return { ok: false };
+
+  const remainingHashes = hashes.filter((_, i) => i !== matchIndex);
+  return { ok: true, method: "recovery", remainingHashes };
+}

package/src/auth-mfa/web/client-plugin.ts

@@ -0,0 +1,37 @@
+// @runtime client
+// Client-Feature-Factory für auth-mfa — mirrors emailPasswordClient()'s
+// shape so apps register both the same way:
+// createKumikoApp({ clientFeatures: [emailPasswordClient(), authMfaClient()] }).
+// No gates: MfaVerifyScreen isn't a route gate, it's a state swap wired
+// via EmailPasswordClientOptions.mfaVerifyScreen. This factory merges the
+// default de/en translations and maps MFA_ENABLE_SCREEN_ID to
+// MfaEnableScreen (same "components" convention as personal-access-tokens).
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ComponentType, ReactNode } from "react";
+import { MFA_ENABLE_SCREEN_ID } from "../constants";
+import { defaultTranslations, mergeTranslations } from "./i18n";
+import { MfaEnableScreen } from "./mfa-enable-screen";
+
+export type AuthMfaClientOptions = {
+  /** Key-Overrides pro Locale, gemerged mit den Default-Bundles (de/en). */
+  readonly translations?: TranslationsByLocale;
+};
+
+export type AuthMfaClientFeature = {
+  readonly name: "auth-mfa";
+  readonly providers: readonly ComponentType<{ children: ReactNode }>[];
+  readonly gates: readonly ComponentType<{ children: ReactNode }>[];
+  readonly translations: TranslationsByLocale;
+  readonly components: Readonly<Record<string, ComponentType>>;
+};
+
+export function authMfaClient(options: AuthMfaClientOptions = {}): AuthMfaClientFeature {
+  return {
+    name: "auth-mfa",
+    providers: [],
+    gates: [],
+    translations: mergeTranslations(defaultTranslations, options.translations ?? {}),
+    components: { [MFA_ENABLE_SCREEN_ID]: MfaEnableScreen },
+  };
+}

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

@@ -0,0 +1,69 @@
+// @runtime client
+// Default-Bundles für die auth-mfa Feature-UI. Merged in mit
+// authMfaClient() analog zu emailPasswordClient() aus auth-email-password.
+// Keys folgen `auth.mfa.<area>.<slug>`.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "auth.mfa.verify.title": "Zwei-Faktor-Bestätigung",
+    "auth.mfa.verify.subtitle": "Gib den 6-stelligen Code aus deiner Authenticator-App ein.",
+    "auth.mfa.verify.code": "Code",
+    "auth.mfa.verify.submit": "Bestätigen",
+    "auth.mfa.verify.submitting": "…",
+    "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.",
+    "auth.mfa.errors.verifyFailed": "Bestätigung fehlgeschlagen.",
+    "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.invalidRecoveryCode": "Ungültiger Recovery-Code.",
+    "auth.mfa.enable.title": "Zwei-Faktor-Authentifizierung",
+    "auth.mfa.enable.intro":
+      "Schütze dein Konto zusätzlich mit einer Authenticator-App (z.B. Google Authenticator, 1Password).",
+    "auth.mfa.enable.start": "Einrichtung starten",
+    "auth.mfa.enable.scanTitle": "QR-Code scannen",
+    "auth.mfa.enable.manualEntry": "Oder manuell eingeben:",
+    "auth.mfa.enable.recoveryTitle": "Recovery-Codes",
+    "auth.mfa.enable.recoveryHint":
+      "Speichere diese Codes an einem sicheren Ort. Sie werden nur dieses eine Mal angezeigt und erlauben dir den Zugriff, falls du dein Gerät verlierst.",
+    "auth.mfa.enable.acknowledge": "Ich habe die Recovery-Codes gespeichert.",
+    "auth.mfa.enable.code": "Code aus der Authenticator-App",
+    "auth.mfa.enable.cancel": "Abbrechen",
+    "auth.mfa.enable.confirm": "Aktivieren",
+    "auth.mfa.enable.success": "Zwei-Faktor-Authentifizierung ist jetzt aktiv.",
+  },
+  en: {
+    "auth.mfa.verify.title": "Two-factor verification",
+    "auth.mfa.verify.subtitle": "Enter the 6-digit code from your authenticator app.",
+    "auth.mfa.verify.code": "Code",
+    "auth.mfa.verify.submit": "Verify",
+    "auth.mfa.verify.submitting": "…",
+    "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.",
+    "auth.mfa.errors.verifyFailed": "Verification failed.",
+    "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.invalidRecoveryCode": "Invalid recovery code.",
+    "auth.mfa.enable.title": "Two-factor authentication",
+    "auth.mfa.enable.intro":
+      "Add an extra layer of protection with an authenticator app (e.g. Google Authenticator, 1Password).",
+    "auth.mfa.enable.start": "Start setup",
+    "auth.mfa.enable.scanTitle": "Scan the QR code",
+    "auth.mfa.enable.manualEntry": "Or enter manually:",
+    "auth.mfa.enable.recoveryTitle": "Recovery codes",
+    "auth.mfa.enable.recoveryHint":
+      "Save these codes somewhere safe. They're shown only this once and let you back in if you lose your device.",
+    "auth.mfa.enable.acknowledge": "I've saved my recovery codes.",
+    "auth.mfa.enable.code": "Code from your authenticator app",
+    "auth.mfa.enable.cancel": "Cancel",
+    "auth.mfa.enable.confirm": "Enable",
+    "auth.mfa.enable.success": "Two-factor authentication is now enabled.",
+  },
+};
+
+export { mergeTranslations } from "@cosmicdrift/kumiko-renderer";

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

@@ -0,0 +1,15 @@
+// @runtime client
+// Public exports für die Browser-Seite des auth-mfa Features. Sub-Path-
+// Export `@cosmicdrift/kumiko-bundled-features/auth-mfa/web` — Server-Seite
+// (defineFeature) bleibt frei von React-/DOM-Deps, siehe auth-email-
+// password/web/index.ts für die selbe Trennung.
+
+export type { AuthMfaClientFeature, AuthMfaClientOptions } from "./client-plugin";
+export { authMfaClient } from "./client-plugin";
+export { defaultTranslations, mergeTranslations } from "./i18n";
+export type { MfaVerifyResult } from "./mfa-client";
+export { verifyMfaChallenge } from "./mfa-client";
+export type { MfaEnableScreenProps } from "./mfa-enable-screen";
+export { MfaEnableScreen } from "./mfa-enable-screen";
+export type { MfaVerifyScreenProps } from "./mfa-verify-screen";
+export { MfaVerifyScreen } from "./mfa-verify-screen";

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

@@ -0,0 +1,60 @@
+// @runtime client
+// Browser-Seite von POST /api/auth/mfa/verify — completes the two-step
+// login LoginScreen started when the server responded mfaRequired. Same
+// fetch/CSRF pattern as auth-email-password's login() (pre-session, no
+// csrfHeader() — there's no session yet to protect). Response shape is
+// byte-identical to /auth/login's ({isSuccess, token, user} | {isSuccess:
+// false, error}) since auth-routes.ts mints via the same
+// mintSessionAndRespond() for both routes.
+
+// kumiko-lint-ignore cross-feature-import client-only types, the feature's server barrel has no web/ re-export
+import type { LoginFailure, LoginResponse } from "../../auth-email-password/web";
+
+export type MfaVerifyResult =
+  | { readonly kind: "success"; readonly data: LoginResponse }
+  | { readonly kind: "failure"; readonly error: LoginFailure };
+
+export async function verifyMfaChallenge(
+  challengeToken: string,
+  code: string,
+): Promise<MfaVerifyResult> {
+  const res = await fetch("/api/auth/mfa/verify", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ challengeToken, code }),
+  });
+  if (res.status === 429) {
+    return { kind: "failure", error: { reason: "rate_limited" } };
+  }
+  // @cast-boundary engine-payload — HTTP-API contract, server-side schema-validated
+  const body = (await res.json().catch(() => ({}))) as {
+    isSuccess?: boolean;
+    token?: string;
+    user?: LoginResponse["user"];
+    error?:
+      | {
+          code?: string;
+          message?: string;
+          details?: { reason?: string; retryAfterSeconds?: number };
+        }
+      | string;
+  };
+  if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
+    return { kind: "success", data: { token: body.token, user: body.user } };
+  }
+  const err = body.error;
+  if (typeof err === "string") {
+    return { kind: "failure", error: { reason: err } };
+  }
+  const reason = err?.details?.reason ?? err?.code ?? "mfa_verify_failed";
+  const retry = err?.details?.retryAfterSeconds;
+  return {
+    kind: "failure",
+    error: {
+      reason,
+      ...(err?.message !== undefined && { message: err.message }),
+      ...(retry !== undefined && { retryAfterSeconds: retry }),
+    },
+  };
+}

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

@@ -0,0 +1,187 @@
+// @runtime client
+// MfaEnableScreen — logged-in self-service TOTP-Enrollment. Kein Dialog:
+// DefaultDialog schließt nach JEDEM onConfirm (siehe renderer-web/src/
+// primitives/dialog.tsx — onOpenChange(false) im finally-Block), das passt
+// nicht zu einem Mehrschritt-Flow (Secret zeigen → Recovery-Codes zeigen →
+// Code bestätigen). Folgt stattdessen pat-tokens-screen.tsx's embedded-
+// Screen-Konvention: Feature registriert das dormant via r.screen, App
+// platziert es via r.nav.
+
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
+import QRCode from "qrcode";
+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";
+import { AuthMfaHandlers } from "../constants";
+
+type EnableStartResponse = {
+  readonly setupToken: string;
+  readonly otpauthUri: string;
+  readonly recoveryCodes: readonly string[];
+};
+
+type SetupState = {
+  readonly setupToken: string;
+  readonly secretParam: string;
+  readonly recoveryCodes: readonly string[];
+  readonly qrSvg: string;
+};
+
+// otpauth:// URIs put the secret in the query string — extract it for the
+// manual-entry fallback (authenticator apps without a camera / desktop use).
+function extractSecret(otpauthUri: string): string {
+  const query = otpauthUri.split("?")[1] ?? "";
+  return new URLSearchParams(query).get("secret") ?? "";
+}
+
+export type MfaEnableScreenProps = { readonly embedded?: boolean };
+
+export function MfaEnableScreen({ embedded = false }: MfaEnableScreenProps = {}): ReactNode {
+  const t = useTranslation();
+  const { Button, Banner, Field, Input, Card, Heading } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const session = useSession();
+
+  const [setup, setSetup] = useState<SetupState | null>(null);
+  const [acknowledged, setAcknowledged] = useState(false);
+  const [code, setCode] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [enabled, setEnabled] = useState(false);
+
+  const startSetup = async (): Promise<void> => {
+    setBusy(true);
+    setError(null);
+    const res = await dispatcher.write<EnableStartResponse>(AuthMfaHandlers.enableStart, {
+      accountLabel: session.user?.email ?? "",
+    });
+    if (!res.isSuccess) {
+      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;
+    }
+    setEnabled(true);
+    setSetup(null);
+  };
+
+  const content = (
+    <div className="flex flex-col gap-6">
+      <Heading>{t("auth.mfa.enable.title")}</Heading>
+
+      {enabled && <Banner variant="info">{t("auth.mfa.enable.success")}</Banner>}
+      {error !== null && <Banner variant="error">{t(`auth.mfa.errors.${error}`)}</Banner>}
+
+      {!setup && !enabled && (
+        <Card options={{ padded: true }} className="flex flex-col gap-3">
+          <span className="text-sm text-muted-foreground">{t("auth.mfa.enable.intro")}</span>
+          <Button
+            variant="primary"
+            onClick={() => void startSetup()}
+            loading={busy}
+            disabled={busy}
+          >
+            {t("auth.mfa.enable.start")}
+          </Button>
+        </Card>
+      )}
+
+      {setup && (
+        <Card options={{ padded: true }} className="flex flex-col gap-4">
+          <div className="flex flex-col gap-2">
+            <span className="text-sm font-semibold">{t("auth.mfa.enable.scanTitle")}</span>
+            {/* qrcode's own SVG string output, not user input — safe to inline */}
+            <div
+              className="h-40 w-40"
+              // biome-ignore lint/security/noDangerouslySetInnerHtml: qrcode-generated SVG, no user input
+              dangerouslySetInnerHTML={{ __html: setup.qrSvg }}
+            />
+            <span className="text-xs text-muted-foreground">
+              {t("auth.mfa.enable.manualEntry")}
+            </span>
+            <code className="block break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+              {setup.secretParam}
+            </code>
+          </div>
+
+          <div className="flex flex-col gap-2">
+            <span className="text-sm font-semibold">{t("auth.mfa.enable.recoveryTitle")}</span>
+            <span className="text-xs text-muted-foreground">
+              {t("auth.mfa.enable.recoveryHint")}
+            </span>
+            <code className="block whitespace-pre-wrap break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+              {setup.recoveryCodes.join("\n")}
+            </code>
+            <Field id="mfa-enable-ack" label={t("auth.mfa.enable.acknowledge")}>
+              <Input
+                kind="boolean"
+                id="mfa-enable-ack"
+                name="mfa-enable-ack"
+                value={acknowledged}
+                onChange={setAcknowledged}
+              />
+            </Field>
+          </div>
+
+          <Field id="mfa-enable-code" label={t("auth.mfa.enable.code")} required>
+            <Input
+              kind="text"
+              id="mfa-enable-code"
+              name="mfa-enable-code"
+              value={code}
+              onChange={setCode}
+              disabled={busy || !acknowledged}
+              autoComplete="one-time-code"
+            />
+          </Field>
+
+          <div className="flex justify-end gap-2">
+            <Button variant="secondary" onClick={() => setSetup(null)} disabled={busy}>
+              {t("auth.mfa.enable.cancel")}
+            </Button>
+            <Button
+              variant="primary"
+              onClick={() => void confirmSetup()}
+              loading={busy}
+              disabled={busy || !acknowledged || code.length < 6}
+            >
+              {t("auth.mfa.enable.confirm")}
+            </Button>
+          </div>
+        </Card>
+      )}
+    </div>
+  );
+
+  if (embedded) return content;
+  return (
+    <FormScreenShell testId="mfa-enable-screen" maxWidth="3xl">
+      {content}
+    </FormScreenShell>
+  );
+}