@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/auth-mfa/token-secrets.ts

@@ -0,0 +1,41 @@
+import { derivePurposeSecret } from "@cosmicdrift/kumiko-framework/secrets";
+
+export type MfaTokenSecretOverrides = {
+  readonly setupTokenSecret?: string;
+  readonly challengeTokenSecret?: string;
+};
+
+export type ResolvedMfaTokenSecrets = {
+  readonly setupTokenSecret: string;
+  readonly challengeTokenSecret: string;
+};
+
+// Shared here (not per call site) so the purpose string can't drift between
+// prod/dev entrypoints. Setup and challenge stay separate: sharing one key
+// would let a setup token be replayed as a login-challenge token.
+const SETUP_TOKEN_PURPOSE = "mfa-setup-token-v1";
+const CHALLENGE_TOKEN_PURPOSE = "mfa-challenge-token-v1";
+
+// A blank or whitespace-only override is treated as absent — an empty env
+// var (MFA_SETUP_TOKEN_SECRET="") must fall back to derivation, not sign
+// tokens with an empty/near-empty HMAC key (fw#1623).
+function resolveSecret(override: string | undefined, fallback: () => string): string {
+  return override !== undefined && override.trim() !== "" ? override : fallback();
+}
+
+/** Derives both MFA token secrets from the app's master secret. Pass explicit
+ *  overrides only when a deployment needs its own key for one of them —
+ *  otherwise deriving keeps a single env var authoritative. */
+export function resolveMfaTokenSecrets(
+  masterSecret: string,
+  overrides: MfaTokenSecretOverrides = {},
+): ResolvedMfaTokenSecrets {
+  return {
+    setupTokenSecret: resolveSecret(overrides.setupTokenSecret, () =>
+      derivePurposeSecret(masterSecret, SETUP_TOKEN_PURPOSE),
+    ),
+    challengeTokenSecret: resolveSecret(overrides.challengeTokenSecret, () =>
+      derivePurposeSecret(masterSecret, CHALLENGE_TOKEN_PURPOSE),
+    ),
+  };
+}

package/packages/bundled-features/src/auth-mfa/totp.ts

@@ -0,0 +1,67 @@
+// RFC 6238 TOTP on top of node:crypto — no otplib/speakeasy dependency. The
+// algorithm is ~20 lines of HMAC-SHA1 + dynamic truncation; pulling in a
+// package for it would be the opposite of lazy.
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+export const STEP_SECONDS = 30;
+const DIGITS = 6;
+const WINDOW = 1; // accept ±1 step (±30s) of clock drift, per the spec's guidance
+
+export function generateTotpSecret(): Buffer {
+  return randomBytes(20); // 160 bits — RFC 4226's recommended HOTP secret length
+}
+
+function hotp(secret: Buffer, counter: number): string {
+  const counterBuf = Buffer.alloc(8);
+  counterBuf.writeUInt32BE(Math.floor(counter / 2 ** 32), 0);
+  counterBuf.writeUInt32BE(counter % 2 ** 32, 4);
+
+  const hmac = createHmac("sha1", secret).update(counterBuf).digest();
+  const offset = (hmac[hmac.length - 1] ?? 0) & 0x0f;
+  const truncated =
+    (((hmac[offset] ?? 0) & 0x7f) << 24) |
+    (((hmac[offset + 1] ?? 0) & 0xff) << 16) |
+    (((hmac[offset + 2] ?? 0) & 0xff) << 8) |
+    ((hmac[offset + 3] ?? 0) & 0xff);
+
+  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));
+}
+
+// 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.
+//
+// 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 matchedCounter: number | false = false;
+  for (let w = -WINDOW; w <= WINDOW; w++) {
+    const stepSeconds = nowSeconds + w * STEP_SECONDS;
+    const candidate = Buffer.from(totpAt(secret, stepSeconds));
+    if (timingSafeEqual(candidate, codeBuf)) {
+      matchedCounter = Math.floor(stepSeconds / STEP_SECONDS);
+    }
+  }
+  return matchedCounter;
+}

package/packages/bundled-features/src/auth-mfa/verify-factor.ts

@@ -0,0 +1,58 @@
+import type { Redis } from "ioredis";
+import { burnToken } from "../shared/index.js";
+import { base32Decode } from "./base32.js";
+import type { UserMfaRow } from "./db/queries.js";
+import { findMatchingRecoveryCodeIndex } from "./recovery-codes.js";
+import { STEP_SECONDS, verifyTotp } from "./totp.js";
+
+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.
+//
+// `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);
+  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);
+  if (matchIndex === -1) return { ok: false };
+
+  const remainingHashes = hashes.filter((_, i) => i !== matchIndex);
+  return { ok: true, method: "recovery", remainingHashes };
+}

package/packages/bundled-features/src/auth-mfa/web/client-plugin.ts

@@ -0,0 +1,36 @@
+// @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 for the Verify/Disable/Regenerate components —
+// the enroll screen is a declarative secretMint (feature.ts's r.screen),
+// no client component of its own.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ComponentType, ReactNode } from "react";
+import { defaultTranslations, mergeTranslations } from "./i18n.js";
+
+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: {},
+  };
+}

package/packages/bundled-features/src/auth-mfa/web/i18n.ts

@@ -0,0 +1,66 @@
+// @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 = {
+  en: {
+    "screen:auth-mfa-enable.title": "Two-factor authentication",
+    "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.verify.backToLogin": "Back to login",
+    "auth.mfa.errors.invalidCode": "Invalid code. Please try again.",
+    "auth.mfa.errors.invalidTotpCode": "Invalid code. Please try again.",
+    "auth.mfa.errors.invalidChallengeToken": "Your sign-in has expired. Please sign in 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.tooManyAttemptsWithSeconds":
+      "Too many failed attempts. Try again in {seconds} seconds, or 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.setupFailed": "Setup failed. Please try again.",
+    "auth.mfa.errors.invalidRecoveryCode": "Invalid recovery code.",
+    "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.setup.title": "Two-factor authentication required",
+    "auth.mfa.setup.subtitle":
+      "Your account requires two-factor authentication. Set it up now to sign in.",
+    "auth.mfa.setup.intro":
+      "Scan the QR code with an authenticator app (e.g. Google Authenticator, 1Password).",
+    "auth.mfa.setup.start": "Start setup",
+    "auth.mfa.setup.confirm": "Complete setup",
+    "auth.mfa.disable.title": "Disable two-factor authentication",
+    "auth.mfa.disable.description":
+      "Confirm with a code from your authenticator app or a recovery code. Your account will then be protected by your password alone.",
+    "auth.mfa.disable.code": "Code from your authenticator app or a recovery code",
+    "auth.mfa.disable.confirm": "Disable",
+    "auth.mfa.disable.cancel": "Cancel",
+    "auth.mfa.disable.trigger": "Disable two-factor authentication",
+    "auth.mfa.regenerate.title": "Generate new recovery codes",
+    "auth.mfa.regenerate.description":
+      "Confirm with a code from your authenticator app. All existing recovery codes stop working immediately.",
+    "auth.mfa.regenerate.code": "Code from your authenticator app",
+    "auth.mfa.regenerate.confirm": "Generate new codes",
+    "auth.mfa.regenerate.cancel": "Cancel",
+    "auth.mfa.regenerate.trigger": "Generate new recovery codes",
+    "auth.mfa.regenerate.newCodesTitle": "Your new recovery codes",
+    "auth.mfa.regenerate.newCodesHint":
+      "Save these codes somewhere safe. The old codes stop working immediately.",
+    "auth.mfa.regenerate.acknowledge": "I've saved my new recovery codes.",
+    "auth.mfa.regenerate.done": "Done",
+  },
+};
+
+export { mergeTranslations } from "@cosmicdrift/kumiko-renderer";

package/packages/bundled-features/src/auth-mfa/web/index.ts

@@ -0,0 +1,25 @@
+// @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.js";
+export { authMfaClient } from "./client-plugin.js";
+export { defaultTranslations, mergeTranslations } from "./i18n.js";
+export type {
+  MfaSetupPreauthStart,
+  MfaSetupPreauthStartResult,
+  MfaVerifyResult,
+} from "./mfa-client.js";
+export { confirmMfaSetupPreauth, startMfaSetupPreauth, verifyMfaChallenge } from "./mfa-client.js";
+export type { MfaDisableDialogProps } from "./mfa-disable-dialog.js";
+export { MfaDisableDialog } from "./mfa-disable-dialog.js";
+export type { MfaRecoveryCodesRevealProps } from "./mfa-recovery-codes-reveal.js";
+export { MfaRecoveryCodesReveal } from "./mfa-recovery-codes-reveal.js";
+export type { MfaRegenerateRecoveryDialogProps } from "./mfa-regenerate-recovery-dialog.js";
+export { MfaRegenerateRecoveryDialog } from "./mfa-regenerate-recovery-dialog.js";
+export type { MfaSetupPreauthScreenProps } from "./mfa-setup-preauth-screen.js";
+export { MfaSetupPreauthScreen } from "./mfa-setup-preauth-screen.js";
+export type { MfaVerifyScreenProps } from "./mfa-verify-screen.js";
+export { MfaVerifyScreen } from "./mfa-verify-screen.js";

package/packages/bundled-features/src/auth-mfa/web/mfa-client.ts

@@ -0,0 +1,196 @@
+// @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,
+  type LoginResponse,
+  toLoginResponse,
+} from "../../auth-email-password/web/index.js";
+
+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"];
+    landingPath?: string;
+    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: toLoginResponse(body.token, body.user, body.landingPath),
+    };
+  }
+  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 }),
+    },
+  };
+}
+
+export type MfaSetupPreauthStart = {
+  readonly setupToken: string;
+  readonly otpauthUri: string;
+  readonly recoveryCodes: readonly string[];
+};
+
+export type MfaSetupPreauthStartResult =
+  | { readonly kind: "success"; readonly data: MfaSetupPreauthStart }
+  | { readonly kind: "failure"; readonly error: LoginFailure };
+
+// Browser-Seite von POST /api/auth/mfa/preauth-enable-start — lets a user
+// blocked at login by MFA enforcement generate a TOTP secret/QR without a
+// session, using the preauthSetupToken login()'s mfa-setup-required result
+// carries. No JWT/cookie here (see auth-routes.ts's route comment) — the
+// response's setupToken is consumed by confirmMfaSetupPreauth below.
+export async function startMfaSetupPreauth(
+  preauthSetupToken: string,
+  accountLabel: string,
+): Promise<MfaSetupPreauthStartResult> {
+  const res = await fetch("/api/auth/mfa/preauth-enable-start", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ preauthSetupToken, accountLabel }),
+  });
+  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;
+    setupToken?: string;
+    otpauthUri?: string;
+    recoveryCodes?: readonly string[];
+    error?:
+      | {
+          code?: string;
+          message?: string;
+          details?: { reason?: string; retryAfterSeconds?: number };
+        }
+      | string;
+  };
+  if (
+    body.isSuccess === true &&
+    body.setupToken !== undefined &&
+    body.otpauthUri !== undefined &&
+    body.recoveryCodes !== undefined
+  ) {
+    return {
+      kind: "success",
+      data: {
+        setupToken: body.setupToken,
+        otpauthUri: body.otpauthUri,
+        recoveryCodes: body.recoveryCodes,
+      },
+    };
+  }
+  const err = body.error;
+  if (typeof err === "string") {
+    return { kind: "failure", error: { reason: err } };
+  }
+  const reason = err?.details?.reason ?? err?.code ?? "setup_failed";
+  const retry = err?.details?.retryAfterSeconds;
+  return {
+    kind: "failure",
+    error: {
+      reason,
+      ...(err?.message !== undefined && { message: err.message }),
+      ...(retry !== undefined && { retryAfterSeconds: retry }),
+    },
+  };
+}
+
+// Browser-Seite von POST /api/auth/mfa/preauth-confirm — completes both
+// the enrollment startMfaSetupPreauth began and the login mfa-setup-
+// required block. Response shape mirrors /auth/mfa/verify's (mints via
+// the same mintSessionAndRespond()), same as verifyMfaChallenge above —
+// kept as its own function rather than a shared helper so this file's
+// two already-tested request shapes stay independently editable.
+export async function confirmMfaSetupPreauth(
+  setupToken: string,
+  code: string,
+): Promise<MfaVerifyResult> {
+  const res = await fetch("/api/auth/mfa/preauth-confirm", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ setupToken, 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"];
+    landingPath?: string;
+    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: toLoginResponse(body.token, body.user, body.landingPath),
+    };
+  }
+  const err = body.error;
+  if (typeof err === "string") {
+    return { kind: "failure", error: { reason: err } };
+  }
+  const reason = err?.details?.reason ?? err?.code ?? "mfa_setup_confirm_failed";
+  const retry = err?.details?.retryAfterSeconds;
+  return {
+    kind: "failure",
+    error: {
+      reason,
+      ...(err?.message !== undefined && { message: err.message }),
+      ...(retry !== undefined && { retryAfterSeconds: retry }),
+    },
+  };
+}

package/packages/bundled-features/src/auth-mfa/web/mfa-disable-dialog.tsx

@@ -0,0 +1,70 @@
+// @runtime client
+// MfaDisableDialog — confirm-with-code before turning MFA off. Uses the
+// generic Dialog primitive (unlike MfaRegenerateRecoveryDialog): disable is
+// single-step, no state to preserve after confirm, so
+// it doesn't hit the "Dialog always closes after onConfirm" problem that
+// ruled Dialog out for the multi-step enable/regenerate flows. Error
+// reporting still has to go through the parent (onError) rather than an
+// inline Banner, because Dialog closes in a `finally` regardless of
+// whether onConfirm's write succeeded — see profile-screen.tsx's
+// delete-account dialog for the same convention (StatusBanner rendered
+// by the caller, not the dialog).
+
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { AuthMfaHandlers } from "../constants.js";
+
+export type MfaDisableDialogProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly onDisabled: () => void;
+  readonly onError: (i18nKey: string) => void;
+};
+
+// kumiko-lint-ignore no-custom-primitives Uses usePrimitives().Dialog internally, name is an MFA domain action, not a primitive reimplementation
+export function MfaDisableDialog({
+  open,
+  onOpenChange,
+  onDisabled,
+  onError,
+}: MfaDisableDialogProps): ReactNode {
+  const t = useTranslation();
+  const { Dialog, Field, Input } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [code, setCode] = useState("");
+
+  const confirm = async (): Promise<void> => {
+    const res = await dispatcher.write<{ disabled: boolean }>(AuthMfaHandlers.disable, { code });
+    setCode("");
+    if (!res.isSuccess) {
+      onError(res.error.i18nKey);
+      return;
+    }
+    onDisabled();
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={onOpenChange}
+      variant="danger"
+      title={t("auth.mfa.disable.title")}
+      description={t("auth.mfa.disable.description")}
+      confirmLabel={t("auth.mfa.disable.confirm")}
+      cancelLabel={t("auth.mfa.disable.cancel")}
+      onConfirm={confirm}
+      testId="mfa-disable-dialog"
+    >
+      <Field id="mfa-disable-code" label={t("auth.mfa.disable.code")} required>
+        <Input
+          kind="text"
+          id="mfa-disable-code"
+          name="mfa-disable-code"
+          value={code}
+          onChange={setCode}
+          autoComplete="one-time-code"
+        />
+      </Field>
+    </Dialog>
+  );
+}

package/packages/bundled-features/src/auth-mfa/web/mfa-recovery-codes-reveal.tsx

@@ -0,0 +1,53 @@
+// @runtime client
+// MfaRecoveryCodesReveal — one-time display of a fresh recovery-code set,
+// with an acknowledge-then-dismiss gate. Standalone so MfaRegenerateRecovery-
+// Dialog's caller can render it after the dialog closes — the codes only
+// exist in memory for this one render, never persisted anywhere the app
+// could show them again.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+
+export type MfaRecoveryCodesRevealProps = {
+  readonly codes: readonly string[];
+  readonly onDismiss: () => void;
+};
+
+export function MfaRecoveryCodesReveal({
+  codes,
+  onDismiss,
+}: MfaRecoveryCodesRevealProps): ReactNode {
+  const t = useTranslation();
+  const { Button, Field, Input, Section } = usePrimitives();
+  const [acknowledged, setAcknowledged] = useState(false);
+
+  return (
+    <Section
+      testId="mfa-regenerate-reveal"
+      actions={
+        <Button variant="primary" onClick={onDismiss} disabled={!acknowledged}>
+          {t("auth.mfa.regenerate.done")}
+        </Button>
+      }
+    >
+      <div className="flex flex-col items-center gap-2 text-center">
+        <span className="text-sm font-semibold">{t("auth.mfa.regenerate.newCodesTitle")}</span>
+        <span className="text-xs text-muted-foreground">
+          {t("auth.mfa.regenerate.newCodesHint")}
+        </span>
+        <code className="inline-block whitespace-pre-wrap break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+          {codes.join("\n")}
+        </code>
+      </div>
+      <Field id="mfa-regenerate-ack" label={t("auth.mfa.regenerate.acknowledge")}>
+        <Input
+          kind="boolean"
+          id="mfa-regenerate-ack"
+          name="mfa-regenerate-ack"
+          value={acknowledged}
+          onChange={setAcknowledged}
+        />
+      </Field>
+    </Section>
+  );
+}