@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,30 @@
+export { base32Decode } from "./base32.js";
+export { type MfaRequiredPolicy, mfaRequiredConfigHandle } from "./config.js";
+export {
+  AUTH_MFA_FEATURE,
+  AuthMfaHandlers,
+  AuthMfaQueries,
+  MFA_DISABLE_SCREEN_ID,
+  MFA_ENABLE_SCREEN_ID,
+  MFA_REGENERATE_RECOVERY_SCREEN_ID,
+} from "./constants.js";
+export type {
+  AuthMfaFeatureOptions,
+  BindMfaRevokeAllOtherSessions,
+  BindRevokeAllPatTokens,
+} from "./feature.js";
+export {
+  bindMfaRevokeAllOtherSessionsFromFeature,
+  bindRevokeAllPatTokensFromFeature,
+  createAuthMfaFeature,
+  mfaStatusCheckerFromFeature,
+  mfaVerifierFromFeature,
+} from "./feature.js";
+export type { MfaCodeVerifier, MfaCodeVerifyResult } from "./mfa-code-verifier.js";
+export type { MfaStatusChecker, MfaStatusCheckResult } from "./mfa-status-checker.js";
+export { userMfaEntity, userMfaTable } from "./schema/user-mfa.js";
+export {
+  type MfaTokenSecretOverrides,
+  type ResolvedMfaTokenSecrets,
+  resolveMfaTokenSecrets,
+} from "./token-secrets.js";

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

@@ -0,0 +1,39 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+import { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec.js";
+
+export type MfaChallengePayload = {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+};
+
+function isPayload(value: unknown): value is MfaChallengePayload {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v["userId"] === "string" && typeof v["tenantId"] === "string";
+}
+
+// Domain-separated from mfa-preauth-setup (see hmac-token-codec). Single-use is
+// enforced by the consumer via burnToken (purpose "mfa-challenge"); this codec
+// only signs and verifies. Brute-forcing the code behind a valid token is
+// limited separately in mfa-verify-attempts.ts.
+const codec = createHmacTokenCodec("mfa-challenge", isPayload);
+
+export function signMfaChallengeToken(
+  payload: MfaChallengePayload,
+  ttlMinutes: number,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): { token: string; expiresAt: Temporal.Instant } {
+  return codec.sign(payload, ttlMinutes, secret, now);
+}
+
+export type VerifyMfaChallengeResult = HmacTokenVerifyResult<MfaChallengePayload>;
+
+export function verifyMfaChallengeToken(
+  token: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyMfaChallengeResult {
+  return codec.verify(token, secret, now);
+}

package/packages/bundled-features/src/auth-mfa/mfa-code-verifier.ts

@@ -0,0 +1,45 @@
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  declareEscapeHatch,
+  type HandlerContext,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { findUserMfaRow } from "./db/queries.js";
+import { verifyMfaFactor } from "./verify-factor.js";
+
+export type MfaCodeVerifyResult = { readonly enrolled: boolean; readonly ok: boolean };
+
+export type MfaCodeVerifier = (
+  ctx: HandlerContext,
+  userId: string,
+  tenantId: TenantId,
+  code: string | undefined,
+) => Promise<MfaCodeVerifyResult>;
+
+// Re-auth-only primitive (personal-access-tokens' currentPassword+mfaCode
+// gate), distinct from login's mfaStatusChecker (enrollment/policy only, no
+// code) and from verify.write.ts (full login-completion flow). TOTP-only —
+// a recovery code accepted here without persisting single-use consumption
+// (verify.write.ts's remainingHashes update) would become infinitely
+// reusable, and a re-auth gate is not the account-recovery flow recovery
+// codes exist for.
+export function createMfaCodeVerifier(): MfaCodeVerifier {
+  return async (ctx, userId, tenantId, code) => {
+    declareEscapeHatch({
+      reason:
+        "reads the MFA enrollment of the user being re-authenticated on the caller's handler context; the calling handler declares its own escapeHatch",
+    });
+    const scopedDb = createTenantDb(
+      ctx.db.unsafeRaw("reads the MFA enrollment of the user being re-authenticated"),
+      tenantId,
+      "system",
+    );
+    const row = await findUserMfaRow(scopedDb, { id: userId, tenantId, roles: [] });
+    if (!row) return { enrolled: false, ok: false };
+    // Fail closed without ctx.redis, matching disable.write.ts/verify.write.ts —
+    // skipping the TOTP-replay burn would let an observed code be replayed.
+    if (!code || !ctx.redis) return { enrolled: true, ok: false };
+    const verify = await verifyMfaFactor(row, code, { redis: ctx.redis, userId });
+    return { enrolled: true, ok: verify.ok && verify.method === "totp" };
+  };
+}

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

@@ -0,0 +1,38 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+import { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec.js";
+
+export type MfaPreauthSetupPayload = {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+};
+
+function isPayload(value: unknown): value is MfaPreauthSetupPayload {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v["userId"] === "string" && typeof v["tenantId"] === "string";
+}
+
+// Domain "mfa-preauth-setup" must never equal the challenge domain: a setup
+// token has to fail verification as a challenge token and vice versa. The
+// challenge token secret is reused deliberately; the domain carries the separation.
+const codec = createHmacTokenCodec("mfa-preauth-setup", isPayload);
+
+export function signMfaPreauthSetupToken(
+  payload: MfaPreauthSetupPayload,
+  ttlMinutes: number,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): { token: string; expiresAt: Temporal.Instant } {
+  return codec.sign(payload, ttlMinutes, secret, now);
+}
+
+export type VerifyMfaPreauthSetupResult = HmacTokenVerifyResult<MfaPreauthSetupPayload>;
+
+export function verifyMfaPreauthSetupToken(
+  token: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyMfaPreauthSetupResult {
+  return codec.verify(token, secret, now);
+}

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

@@ -0,0 +1,96 @@
+// HMAC-signed token carrying the pending MFA setup state between
+// `mfa.enable.start` and `mfa.enable.confirm` — no DB row exists until
+// confirm succeeds, so an abandoned setup leaves no trace. The token embeds
+// the TOTP secret and recovery-code hashes; this is not a confidentiality
+// leak because the client already displayed the same secret as a QR code in
+// the same response — the token exists to avoid a second round-trip to
+// regenerate it, not to hide it.
+//
+// Format: <base64url(JSON body)>.<hmac-base64url>. Distinct from
+// signed-token.ts (userId-only payload) because setup needs to carry
+// generated secret material, not just re-derive it from a lookup.
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Temporal } from "temporal-polyfill";
+
+export type MfaSetupPayload = {
+  readonly userId: string;
+  readonly totpSecretBase32: string;
+  readonly recoveryCodeHashes: readonly string[];
+  // Set only by enable-start-preauth.write.ts — the session-authed
+  // enable-start.write.ts has no tenantId to carry (event.user.tenantId
+  // already covers that path). The pre-auth confirm handler has no session
+  // to fall back on, so this is the only source of which tenant to scope to.
+  readonly tenantId?: string;
+};
+
+type EncodedBody = MfaSetupPayload & { readonly expiresAtMs: number };
+
+function sign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+export function signMfaSetupToken(
+  payload: MfaSetupPayload,
+  ttlMinutes: number,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): { token: string; expiresAt: Temporal.Instant } {
+  const expiresAt = now.add({ minutes: ttlMinutes });
+  const body: EncodedBody = { ...payload, expiresAtMs: expiresAt.epochMilliseconds };
+  const bodyB64 = Buffer.from(JSON.stringify(body)).toString("base64url");
+  const signature = sign(`mfa-setup:${bodyB64}`, secret);
+  return { token: `${bodyB64}.${signature}`, expiresAt };
+}
+
+export type VerifyMfaSetupResult =
+  | { readonly ok: true; readonly payload: MfaSetupPayload; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+function isEncodedBody(value: unknown): value is EncodedBody {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["userId"] === "string" &&
+    typeof v["totpSecretBase32"] === "string" &&
+    Array.isArray(v["recoveryCodeHashes"]) &&
+    v["recoveryCodeHashes"].every((h) => typeof h === "string") &&
+    typeof v["expiresAtMs"] === "number" &&
+    (v["tenantId"] === undefined || typeof v["tenantId"] === "string")
+  );
+}
+
+export function verifyMfaSetupToken(
+  token: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyMfaSetupResult {
+  const parts = token.split(".");
+  if (parts.length !== 2) return { ok: false, reason: "malformed" };
+  const [bodyB64, providedSig] = parts;
+  if (!bodyB64 || !providedSig) return { ok: false, reason: "malformed" };
+
+  const expected = sign(`mfa-setup:${bodyB64}`, secret);
+  const expectedBuf = Buffer.from(expected, "base64url");
+  const providedBuf = Buffer.from(providedSig, "base64url");
+  // Length check before timingSafeEqual — a length mismatch throws inside
+  // timingSafeEqual, and that throw is itself a timing signal.
+  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
+  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.from(bodyB64, "base64url").toString("utf8"));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (!isEncodedBody(parsed)) return { ok: false, reason: "malformed" };
+
+  if (
+    Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(parsed.expiresAtMs)) > 0
+  ) {
+    return { ok: false, reason: "expired" };
+  }
+
+  const { expiresAtMs, ...payload } = parsed;
+  return { ok: true, payload, expiresAtMs };
+}

package/packages/bundled-features/src/auth-mfa/mfa-status-checker.ts

@@ -0,0 +1,98 @@
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  declareEscapeHatch,
+  type HandlerContext,
+  type SessionUser,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { type MfaRequiredPolicy, mfaRequiredConfigHandle, mfaRequiredConfigKey } from "./config.js";
+import {
+  MFA_CHALLENGE_TOKEN_TTL_MINUTES,
+  MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES,
+} from "./constants.js";
+import { findUserMfaRow } from "./db/queries.js";
+import { signMfaChallengeToken } from "./mfa-challenge-token.js";
+import { signMfaPreauthSetupToken } from "./mfa-preauth-setup-token.js";
+
+export type MfaStatusCheckResult =
+  | { readonly required: false }
+  | { readonly required: true; readonly challengeToken: string }
+  // Enforcement policy demands MFA for this user, but they haven't enrolled
+  // yet. Distinct from `required: true` (which means "enrolled, prove it
+  // now") — see config.ts's ponytail note on why this hard-blocks login
+  // with no in-band recovery until PR3's enrollment-during-login UI ships.
+  | { readonly setupRequired: true; readonly preauthSetupToken: string };
+
+// Consumed by auth-email-password's login.write.ts via `mfaStatusChecker`
+// (a generic callback type declared THERE, not here — auth-email-password
+// must not import auth-mfa's config, only the shape).
+export type MfaStatusChecker = (
+  ctx: HandlerContext,
+  userId: string,
+  tenantId: TenantId,
+  // Merged global+tenant roles — needed to evaluate the "admins" policy
+  // value. Must be the MERGED set (see login.write.ts caller): a
+  // SystemAdmin whose admin-ness lives only in global roles would be
+  // missed if the caller passed tenant-membership roles alone.
+  roles: readonly string[],
+) => Promise<MfaStatusCheckResult>;
+
+export function createMfaStatusChecker(opts: {
+  readonly challengeTokenSecret: string;
+}): MfaStatusChecker {
+  return async (ctx, userId, tenantId, roles) => {
+    declareEscapeHatch({
+      reason:
+        "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant, on the caller's handler context; the calling handler declares its own escapeHatch",
+    });
+    const scopedDb = createTenantDb(
+      ctx.db.unsafeRaw(
+        "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant",
+      ),
+      tenantId,
+      "system",
+    );
+    const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
+    const row = await findUserMfaRow(scopedDb, scopedUser);
+
+    if (row) {
+      // Enrolled — always enforce regardless of policy. The user opted in
+      // themselves; policy only governs whether enrollment is MANDATORY
+      // for those who haven't.
+      const { token } = signMfaChallengeToken(
+        { userId, tenantId },
+        MFA_CHALLENGE_TOKEN_TTL_MINUTES,
+        opts.challengeTokenSecret,
+      );
+      return { required: true, challengeToken: token };
+    }
+
+    // ctx.config is bound to the CALLING user's tenant (the anonymous
+    // identity's tenant for login) — wrong tenant here. ctx.configResolver takes tenantId
+    // explicitly, which is what a pre-session check against the LOGGING-IN
+    // user's tenant needs.
+    // @cast-boundary engine-payload — "select" config values are validated
+    // against the declared `options` at write-time by the config feature.
+    const policy = ((await ctx.configResolver?.get(
+      mfaRequiredConfigHandle.name,
+      mfaRequiredConfigKey(),
+      tenantId,
+      userId,
+      scopedDb,
+    )) ?? "optional") as MfaRequiredPolicy | "optional";
+    if (policy === "optional") return { required: false };
+    const buildSetupToken = (): string =>
+      signMfaPreauthSetupToken(
+        { userId, tenantId },
+        MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES,
+        opts.challengeTokenSecret,
+      ).token;
+    if (policy === "all") return { setupRequired: true, preauthSetupToken: buildSetupToken() };
+    // policy === "admins"
+    const isAdmin = roles.some((role) => access.admin.includes(role));
+    return isAdmin
+      ? { setupRequired: true, preauthSetupToken: buildSetupToken() }
+      : { required: false };
+  };
+}

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

@@ -0,0 +1,32 @@
+// 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.
+//
+// The counter mechanics (race-free INCR/NX, TTL rules, monotonic-counter
+// semantics) live in shared/lockout-counter.ts — this file only wires the
+// mfa-verify key prefixes onto it.
+
+import { createLockoutCounter, type LockoutCounterState } from "../shared/index.js";
+
+export type MfaVerifyLockoutState = LockoutCounterState;
+
+const COUNT_KEY_PREFIX = "kumiko:auth:mfa-verify:count:";
+const UNTIL_KEY_PREFIX = "kumiko:auth:mfa-verify:until:";
+
+const counter = createLockoutCounter(COUNT_KEY_PREFIX, UNTIL_KEY_PREFIX);
+
+export const getMfaVerifyLockoutState = counter.getState;
+export const recordFailedMfaVerifyAttempt = counter.recordFailedAttempt;
+export const clearMfaVerifyAttempts = counter.clearState;

package/packages/bundled-features/src/auth-mfa/otpauth-uri.ts

@@ -0,0 +1,21 @@
+import { base32Encode } from "./base32.js";
+
+// otpauth:// URI per Google Authenticator's key-uri-format (the de facto
+// standard every authenticator app implements). The client renders this as
+// a QR code (or lets the user type the secret manually) — the server never
+// touches QR rendering.
+export function buildOtpauthUri(opts: {
+  readonly issuer: string;
+  readonly accountLabel: string;
+  readonly secret: Buffer;
+}): string {
+  const label = encodeURIComponent(`${opts.issuer}:${opts.accountLabel}`);
+  const params = new URLSearchParams({
+    secret: base32Encode(opts.secret),
+    issuer: opts.issuer,
+    algorithm: "SHA1",
+    digits: "6",
+    period: "30",
+  });
+  return `otpauth://totp/${label}?${params.toString()}`;
+}

package/packages/bundled-features/src/auth-mfa/recovery-codes.ts

@@ -0,0 +1,54 @@
+import { randomInt } from "node:crypto";
+import { hashPassword, verifyPassword } from "../shared/index.js";
+
+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";
+
+// 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 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, "");
+}
+
+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(normalizeRecoveryCode(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> {
+  const normalized = normalizeRecoveryCode(code);
+  for (let i = 0; i < hashes.length; i++) {
+    const hash = hashes[i];
+    if (hash !== undefined && (await verifyPassword(hash, normalized))) return i;
+  }
+  return -1;
+}

package/packages/bundled-features/src/auth-mfa/schema/user-mfa.ts

@@ -0,0 +1,65 @@
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  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({
+  description:
+    "One user's TOTP two-factor enrollment: the encrypted shared secret, the hashed recovery codes and when the factor was enabled and last used; the row exists only while the user has MFA on.",
+  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, personal: false, reason: "pseudonymous_fk" }),
+    // Envelope-encrypted via the same MasterKeyProvider as secrets/config
+    // (entity-field-encryption.ts) — no manual wrapDek/unwrapDek needed.
+    // `personal: { of: "userId" }`: 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,
+      personal: { of: "userId" },
+      find: "none",
+    }),
+    // JSON-stringified `{ hashes: string[] }` (argon2id hashes of unredeemed
+    // recovery codes) — both encryption layers (entity-field envelope +
+    // per-subject crypto-shred, same as totpSecret above) require a string
+    // value, so callers JSON.stringify on write and JSON.parse on read
+    // (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,
+      personal: { of: "userId" },
+      find: "none",
+    }),
+    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);
+
+// 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/packages/bundled-features/src/auth-mfa/screens.ts

@@ -0,0 +1,124 @@
+import {
+  type ActionFormScreenDefinition,
+  i18nKey,
+  type SecretMintScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AuthMfaHandlers,
+  MFA_DISABLE_SCREEN_ID,
+  MFA_ENABLE_SCREEN_ID,
+  MFA_REGENERATE_RECOVERY_SCREEN_ID,
+} from "./constants.js";
+
+// Declarative TOTP-enrollment screen: mint (no input) -> reveal QR/secret/
+// recovery-codes -> confirm with a 6-digit code. `setupToken` is carried
+// from the mint payload into the confirm payload but never listed in
+// `reveal.fields` — it is threaded through, not shown.
+export const mfaEnableScreen: SecretMintScreenDefinition = {
+  id: MFA_ENABLE_SCREEN_ID,
+  type: "secretMint",
+  handler: AuthMfaHandlers.enableStart,
+  fields: {},
+  layout: { sections: [] },
+  submitLabel: i18nKey("mfa.enable.start"),
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user may enroll their own account in MFA, mirroring the enable-start handler",
+    },
+  },
+  // Reached only via a direct link from account settings, never from a
+  // list — no nav area to resolve in isolation.
+  dormant: true,
+  description: "auth-mfa.screen.auth-mfa-enable.subtitle",
+  reveal: {
+    title: i18nKey("mfa.enable.reveal.title"),
+    warning: i18nKey("mfa.enable.reveal.warning"),
+    fields: [
+      {
+        field: "otpauthUri",
+        label: i18nKey("mfa.enable.reveal.qr"),
+        display: "qr",
+        copyable: false,
+      },
+      {
+        field: "totpSecret",
+        label: i18nKey("mfa.enable.reveal.secret"),
+        display: "code",
+        copyable: true,
+      },
+      {
+        field: "recoveryCodes",
+        label: i18nKey("mfa.enable.reveal.recoveryCodes"),
+        display: "list",
+        copyable: true,
+      },
+    ],
+  },
+  confirm: {
+    handler: AuthMfaHandlers.enableConfirm,
+    fields: {
+      code: { type: "text", required: true, maxLength: 6 },
+    },
+    layout: { sections: [{ fields: ["code"] }] },
+    carry: ["setupToken"],
+    submitLabel: i18nKey("mfa.enable.confirm.submit"),
+    doneMessage: i18nKey("mfa.enable.confirm.done"),
+  },
+};
+
+// Either a 6-digit TOTP code or a 9-char recovery code proves possession —
+// same bounds as the disable/regenerate-recovery handler schemas.
+const possessionCodeField = { type: "text", required: true, maxLength: 9 } as const;
+
+export const mfaDisableScreen: ActionFormScreenDefinition = {
+  id: MFA_DISABLE_SCREEN_ID,
+  type: "actionForm",
+  handler: AuthMfaHandlers.disable,
+  fields: { code: possessionCodeField },
+  layout: { sections: [{ fields: ["code"] }] },
+  submitLabel: i18nKey("mfa.disable.submit"),
+  submitStyle: "danger",
+  cancelTarget: false,
+  access: {
+    openToAll: {
+      reason: "each signed-in user may turn off their own MFA, mirroring the disable handler",
+    },
+  },
+  // Reached only via a direct link from account settings, never from a
+  // list — no nav area to resolve in isolation.
+  dormant: true,
+  description: "auth-mfa.screen.auth-mfa-disable.subtitle",
+};
+
+export const mfaRegenerateRecoveryScreen: SecretMintScreenDefinition = {
+  id: MFA_REGENERATE_RECOVERY_SCREEN_ID,
+  type: "secretMint",
+  handler: AuthMfaHandlers.regenerateRecovery,
+  fields: { code: possessionCodeField },
+  layout: { sections: [{ fields: ["code"] }] },
+  submitLabel: i18nKey("mfa.regenerate.submit"),
+  cancelTarget: false,
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user may regenerate their own recovery codes, mirroring the regenerate-recovery handler",
+    },
+  },
+  // Reached only via a direct link from account settings, never from a
+  // list — no nav area to resolve in isolation.
+  dormant: true,
+  description: "auth-mfa.screen.auth-mfa-regenerate-recovery.subtitle",
+  reveal: {
+    title: i18nKey("mfa.regenerate.reveal.title"),
+    warning: i18nKey("mfa.regenerate.reveal.warning"),
+    fields: [
+      {
+        field: "recoveryCodes",
+        label: i18nKey("mfa.enable.reveal.recoveryCodes"),
+        display: "list",
+        copyable: true,
+      },
+    ],
+  },
+};

package/packages/bundled-features/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.js";