@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/auth-mfa/handlers/reencrypt.job.ts

@@ -0,0 +1,223 @@
+// KEK-rotation job for userMfa.totpSecret + recoveryCodes (entity-field
+// encryption, same MasterKeyProvider as secrets/config — see
+// schema/user-mfa.ts). Modeled directly on config/handlers/reencrypt.job.ts:
+// entity-field encryption stores a StoredEnvelope JSON string per value (no
+// separate kekVersion column, unlike secrets' DEK-wrap model), so rotation
+// means decrypt under the OLD key, then let the executor's own write-path
+// re-encrypt under provider.currentVersion() — the same auto-encrypt every
+// enable-confirm write already goes through (see enable-confirm.write.ts: it
+// passes PLAINTEXT to executor.create, never a manually-built envelope).
+//
+// Both fields also carry `userOwned` — the executor's own encryptForStorage
+// wraps them PII(envelope(plaintext)) (see event-store-executor-context.ts).
+// This job reads raw rows via selectMany (bypassing the executor's
+// decryptForRead), so it must peel that PII layer itself before the envelope
+// cipher ever sees the value, mirroring decryptForRead's PII-then-envelope
+// order — an envelope decrypt on a still-PII-wrapped string throws
+// "[envelope-cipher] stored value is not valid JSON" instead of rotating anything.
+//
+// Idempotent: re-running skips rows already on the current kekVersion.
+// Every write is a normal executor.update — after a full run even a
+// from-scratch projection rebuild only ever sees the current-KEK envelope
+// (the very risk this job's plan entry called out: a rebuild resurrecting
+// an old-KEK wrap would happen if rotation only touched the read-side
+// projection instead of appending a real `.updated` event).
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  collectPiiSubjectFields,
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  configuredEntityFieldEncryption,
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { JobContext, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  type ChunkedMigrationStopReason,
+  classifyStoredEnvelope,
+  runChunkedMigration,
+} from "../../shared/index.js";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa.js";
+
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_MAX_FAILURES = 10;
+const SYSTEM_ROLES = ["system"] as const;
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+const piiFieldNames = collectPiiSubjectFields(userMfaEntity);
+
+export type MfaReencryptJobPayload = {
+  readonly batchSize?: number;
+  readonly maxDurationMs?: number;
+  readonly maxFailures?: number;
+};
+
+export type MfaReencryptJobResult = {
+  readonly migrated: number;
+  readonly failed: number;
+  readonly alreadyCurrent: number;
+  readonly batchesProcessed: number;
+  readonly stoppedReason: ChunkedMigrationStopReason;
+};
+
+export async function mfaReencryptJob(
+  rawPayload: Record<string, unknown>,
+  ctx: JobContext,
+  db: DbConnection,
+): Promise<void> {
+  const payload = rawPayload as MfaReencryptJobPayload; // @cast-boundary engine-payload
+  const maybeCipher = configuredEntityFieldEncryption();
+  if (!maybeCipher) {
+    throw new InternalError({
+      message:
+        "[auth-mfa:reencrypt] entity-field encryption is not configured — provide a master key " +
+        "(KUMIKO_SECRETS_MASTER_KEY_V<n>); run{Prod,Dev}App wire this automatically, custom boots " +
+        "call configureEntityFieldEncryption(cipher).",
+    });
+  }
+  // hoisted function declarations below capture this — pin the narrowed
+  // type explicitly so TS keeps it inside the closures.
+  const cipher: EnvelopeCipher = maybeCipher;
+  if (!ctx.masterKeyProvider) {
+    throw new InternalError({
+      message:
+        "[auth-mfa:reencrypt] ctx.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
+    });
+  }
+  const provider = ctx.masterKeyProvider;
+  // Undefined = per-subject crypto-shredding isn't configured for this app —
+  // both fields are then plain envelope strings, no PII layer to peel.
+  const piiKms = configuredPiiSubjectKms();
+
+  const batchSize = payload.batchSize ?? DEFAULT_BATCH_SIZE;
+  const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
+  const deadline = payload.maxDurationMs
+    ? Date.now() + payload.maxDurationMs
+    : Number.POSITIVE_INFINITY;
+
+  const tdbCache = new Map<TenantId, TenantDb>();
+  function tdbFor(tenantId: TenantId): TenantDb {
+    let existing = tdbCache.get(tenantId);
+    if (!existing) {
+      existing = createTenantDb(db, tenantId, "system");
+      tdbCache.set(tenantId, existing);
+    }
+    return existing;
+  }
+
+  type UserMfaRow = {
+    id: string;
+    tenantId: string;
+    version: number;
+    totpSecret: string;
+    recoveryCodes: string;
+  };
+
+  let alreadyCurrent = 0;
+  const targetVersion = provider.currentVersion();
+
+  // ponytail: one full candidate scan — MFA rows are user-scale, not
+  // tenant-scale like config; cursor pagination when that ever matters.
+  // Served in slices so runChunkedMigration's deadline/signal/failure
+  // checks run between chunks, not only once.
+  let pending: UserMfaRow[] | undefined;
+  async function nextBatch(): Promise<readonly UserMfaRow[]> {
+    if (pending === undefined) {
+      pending = [...(await selectMany<UserMfaRow>(db, userMfaTable, {}))];
+    }
+    return pending.splice(0, batchSize);
+  }
+
+  async function migrateRow(row: UserMfaRow): Promise<"migrated" | "skipped" | "failed"> {
+    const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
+
+    // Peel the PII layer first (if active) so classifyEnvelope/cipher.decrypt
+    // below only ever see envelope strings, same order as decryptForRead.
+    let envelopeValues: { totpSecret: string; recoveryCodes: string } = row;
+    if (piiKms) {
+      const unwrapped = await decryptPiiFieldValues(row, piiFieldNames, piiKms, {
+        requestId: "auth-mfa-reencrypt-job",
+        tenantId,
+      });
+      envelopeValues = unwrapped as { totpSecret: string; recoveryCodes: string }; // @cast-boundary engine-payload
+    }
+
+    // After PII peel (when configured), values must be current-cipher
+    // envelopes — non-JSON/non-envelope is not a supported legacy decrypt
+    // path (#1541, mirrors config #1513).
+    const totpClass = classifyStoredEnvelope(envelopeValues.totpSecret, targetVersion);
+    const recoveryClass = classifyStoredEnvelope(envelopeValues.recoveryCodes, targetVersion);
+    if (totpClass === "unrecognized" || recoveryClass === "unrecognized") {
+      ctx.log?.warn?.(
+        `[auth-mfa:reencrypt] row ${row.id} has a field that is not a current-cipher envelope, not re-encryptable`,
+      );
+      return "failed";
+    }
+    if (totpClass === "current" && recoveryClass === "current") {
+      alreadyCurrent++;
+      return "skipped";
+    }
+
+    // decrypt failure (unknown kekVersion, tamper) throws → counted as
+    // failed via onRowError; the row stays untouched.
+    const changes: Record<string, string> = {};
+    if (totpClass === "rotate") {
+      changes["totpSecret"] = await cipher.decrypt(envelopeValues.totpSecret, { tenantId });
+    }
+    if (recoveryClass === "rotate") {
+      changes["recoveryCodes"] = await cipher.decrypt(envelopeValues.recoveryCodes, { tenantId });
+    }
+
+    const actor: SessionUser = { id: "system", tenantId, roles: SYSTEM_ROLES };
+    // PLAINTEXT here, not a manually-built envelope — the executor's own
+    // write-path (encryptForStorage) re-encrypts under the CURRENT
+    // injected cipher/KEK (and re-wraps the PII layer under the same,
+    // unrotated subject DEK), exactly like every other write to this field.
+    const result = await executor.update(
+      { id: row.id, version: row.version, changes },
+      actor,
+      tdbFor(tenantId),
+    );
+
+    // version_conflict == a concurrent enable/disable/regenerate beat us;
+    // the row now holds a fresh write, already fine.
+    if (!result.isSuccess) {
+      if (result.error.code === "version_conflict") return "skipped";
+      ctx.log?.warn?.(`[auth-mfa:reencrypt] executor rejected row ${row.id}`, {
+        code: result.error.code,
+      });
+      return "failed";
+    }
+    return "migrated";
+  }
+
+  const outcome = await runChunkedMigration<UserMfaRow>({
+    nextBatch,
+    migrateRow,
+    maxFailures,
+    deadlineAt: deadline,
+    signal: ctx.signal,
+    onRowError: (row, err) => {
+      ctx.log?.warn?.(`[auth-mfa:reencrypt] failed to re-encrypt row ${row.id}`, { err });
+    },
+  });
+
+  const result: MfaReencryptJobResult = {
+    migrated: outcome.migrated,
+    failed: outcome.failed,
+    alreadyCurrent,
+    batchesProcessed: outcome.batchesProcessed,
+    stoppedReason: outcome.stoppedReason,
+  };
+  ctx.log?.info?.(`[auth-mfa:reencrypt] complete: ${JSON.stringify(result)}`);
+}

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

@@ -0,0 +1,88 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { findUserMfaRow } from "../db/queries.js";
+import { invalidTotpCode, mfaNotEnabled } from "../errors.js";
+import { generateRecoveryCodes, hashRecoveryCodes } from "../recovery-codes.js";
+import { encodeRecoveryCodes, userMfaEntity, userMfaTable } from "../schema/user-mfa.js";
+import { verifyMfaFactor } from "../verify-factor.js";
+
+export type RegenerateRecoveryOptions = {
+  readonly revokeAllOtherSessions?: (
+    userId: string,
+    currentSid: string | undefined,
+  ) => Promise<number>;
+};
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+// Invalidates ALL existing recovery codes (even unused ones) and issues a
+// fresh set of 8 — the standard response to "I think my recovery codes
+// leaked" without having to disable+re-enable TOTP itself.
+export function createRegenerateRecoveryHandler(opts: RegenerateRecoveryOptions) {
+  return defineWriteHandler({
+    name: "regenerate-recovery",
+    schema: z.object({ code: z.string().min(6).max(9) }),
+    access: {
+      openToAll: {
+        reason:
+          "each signed-in user may regenerate only their own recovery codes after proving " +
+          "possession of a TOTP or recovery code; the handler looks up the caller's own user-mfa row",
+      },
+    },
+    description:
+      "Destroys every existing recovery code of the caller, including unused ones, and returns a fresh set once in plaintext; use it when recovery codes may have leaked but TOTP itself should stay enrolled.",
+    // Returns a fresh set of plaintext recovery codes — same transcript leak as
+    // enable-start.
+    agent: { expose: false },
+    handler: async (event, ctx) => {
+      const row = await findUserMfaRow(ctx.db, event.user);
+      if (!row) return mfaNotEnabled();
+
+      // Proof of possession before wiping the old codes — a TOTP code or
+      // (deliberately) one of the very codes about to be replaced both
+      // count, since either way the presented code is consumed/irrelevant
+      // afterward.
+      //
+      // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts
+      // (#1467): without ctx.redis, verifyMfaFactor's TOTP-replay burn is
+      // skipped, letting an observed code be replayed within the ±1-step
+      // window to regenerate (and thus invalidate) recovery codes — a
+      // session-authed route, so pre-unwiring JWTs stay a valid attack path.
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({
+            message: "regenerate-recovery (mfa) requires ctx.redis for TOTP replay protection",
+          }),
+        );
+      }
+      const replay = { redis: ctx.redis, userId: event.user.id };
+      const verify = await verifyMfaFactor(row, event.payload.code, replay);
+      if (!verify.ok) return invalidTotpCode();
+
+      const newCodes = generateRecoveryCodes();
+      const newHashes = await hashRecoveryCodes(newCodes);
+
+      const result = await executor.update(
+        {
+          id: row.id,
+          version: row.version,
+          changes: { recoveryCodes: encodeRecoveryCodes(newHashes) },
+        },
+        event.user,
+        ctx.db,
+      );
+      if (!result.isSuccess) return result;
+
+      if (opts.revokeAllOtherSessions) {
+        await opts.revokeAllOtherSessions(event.user.id, event.user.sid);
+      }
+
+      // Plaintext — shown once, same as the initial enable-flow codes.
+      return { isSuccess: true, data: { recoveryCodes: newCodes } };
+    },
+  });
+}

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

@@ -0,0 +1,32 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { userMfaTable } from "../schema/user-mfa.js";
+
+// "Is MFA enabled for me" — the one thing a settings screen needs before it
+// can decide whether to show the enrollment flow or the disable/regenerate
+// actions. No client-side signal (session/JWT) carries this today, so
+// without this query every app builds its own row-existence check via a
+// side channel. Plain fetchOne — no need for the entity's decrypting
+// executor.detail() (see db/queries.ts's findUserMfaRow), existence is all
+// the caller wants.
+export const mfaStatusQuery = defineQueryHandler({
+  name: "user-mfa:status",
+  schema: z.object({}),
+  outputSchema: z.object({ enabled: z.boolean() }),
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user reads only their own MFA status; the query filters " +
+        "userMfaTable by the caller's own id",
+    },
+  },
+  description:
+    "Reports whether the calling user has TOTP two-factor authentication enrolled; use it before offering either the enrollment flow or the disable and recovery-code actions.",
+  handler: async (query, ctx) => {
+    const row = await fetchOne<{ id: string }>(ctx.db, userMfaTable, {
+      userId: query.user.id,
+    });
+    return { enabled: row !== undefined };
+  },
+});

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

@@ -0,0 +1,203 @@
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  buildSessionRoles,
+  createSystemUser,
+  defineWriteHandler,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { burnToken, sessionLocaleField, sessionTimezoneField } from "../../shared/index.js";
+import { USER_STATUS, UserQueries } from "../../user/index.js";
+import { MFA_VERIFY_LOCKOUT_MINUTES, MFA_VERIFY_MAX_ATTEMPTS } from "../constants.js";
+import { findUserMfaRow } from "../db/queries.js";
+import { invalidChallengeToken, invalidTotpCode, tooManyAttempts } from "../errors.js";
+import { verifyMfaChallengeToken } from "../mfa-challenge-token.js";
+import {
+  clearMfaVerifyAttempts,
+  getMfaVerifyLockoutState,
+  recordFailedMfaVerifyAttempt,
+} from "../mfa-verify-attempts.js";
+import { encodeRecoveryCodes, userMfaEntity, userMfaTable } from "../schema/user-mfa.js";
+import { verifyMfaFactor } from "../verify-factor.js";
+
+export type MfaVerifyOptions = {
+  // Must match the secret the login handler signs mfa-challenge tokens
+  // with — distinct from setupTokenSecret (different token purpose).
+  readonly challengeTokenSecret: string;
+  readonly maxAttempts?: number;
+  readonly lockoutMinutes?: number;
+};
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+// Completes the two-step login. Runs pre-session (dispatched by the
+// framework's /auth/mfa/verify route with the anonymous identity, same as
+// login.write.ts) — everything it needs (which user, which tenant) comes
+// from the challenge token, not from an authenticated caller.
+export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
+  const maxAttempts = opts.maxAttempts ?? MFA_VERIFY_MAX_ATTEMPTS;
+  const lockoutMinutes = opts.lockoutMinutes ?? MFA_VERIFY_LOCKOUT_MINUTES;
+
+  return defineWriteHandler({
+    name: "verify",
+    schema: z.object({ challengeToken: z.string().min(1), code: z.string().min(6).max(9) }),
+    access: { roles: ["anonymous"], personalData: "public-intake" },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
+    escapeHatch: {
+      reason:
+        "Pre-auth MFA step has no session yet — re-derives it via ctx.queryAs(SYSTEM, " +
+        "user:findForAuth) and ctx.resolveActiveMembership for the user the challenge token names. " +
+        "Also reads the MFA enrollment of the tenant named in the signed login/setup token, not the " +
+        "guest dispatch tenant.",
+    },
+    // Payload carries the TOTP/recovery code and the challenge token.
+    agent: { expose: false },
+    description:
+      "Finishes a two-step sign-in by checking a TOTP or recovery code against the challenge token that login handed back, under a per-account attempt cap, and derives the resulting session.",
+    handler: async (event, ctx) => {
+      const verified = verifyMfaChallengeToken(
+        event.payload.challengeToken,
+        opts.challengeTokenSecret,
+      );
+      if (!verified.ok) return invalidChallengeToken();
+      const { userId, tenantId } = verified.payload;
+
+      // Fail closed, matching enable-confirm-preauth.write.ts (#1467):
+      // this route sits behind a challenge token from a successful login,
+      // but its own secret is still just a short TOTP/recovery code —
+      // silently skipping the brute-force cap and single-use burn when
+      // ctx.redis is absent would let a stolen challenge token be guessed
+      // against unboundedly, and let a recovery code be replayed via a
+      // reissued challenge (mfa-verify-attempts.ts's counter is deliberately
+      // NOT reset by reissuance, precisely to survive this).
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({
+            message: "verify (mfa) requires ctx.redis for the brute-force cap and single-use burn",
+          }),
+        );
+      }
+
+      // Per-account brute-force cap — survives challenge-token reissuance
+      // on purpose (see mfa-verify-attempts.ts header). Checked BEFORE the
+      // TOTP/recovery verify so a locked account can't be guessed against.
+      const state = await getMfaVerifyLockoutState(ctx.redis, userId);
+      if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
+        const now = Date.now();
+        if (state.lockedUntil > now) {
+          const retryAfterSeconds = Math.max(1, Math.ceil((state.lockedUntil - now) / 1000));
+          return tooManyAttempts(retryAfterSeconds);
+        }
+      }
+
+      // "system" mode: this handler runs with a guest identity whose own
+      // tenantId is meaningless here — the challenge token is the source
+      // of truth for which tenant's row to read.
+      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);
+      // MFA got disabled between login and verify (race, or a stale
+      // challenge token from before a disable) — same generic error as a
+      // bad code, no detail leak about account state.
+      if (!row) return invalidChallengeToken();
+
+      const replay = { redis: ctx.redis, userId };
+      const verify = await verifyMfaFactor(row, event.payload.code, replay);
+      if (!verify.ok) {
+        await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
+        return invalidTotpCode();
+      }
+
+      // Burn the challenge token only after a successful code check — a
+      // still-failing attempt (wrong code) must not consume it, so a
+      // fat-fingered retry on the same token still works. The TOTP-counter
+      // burn inside verifyMfaFactor already rejects an exact-duplicate
+      // replay (same token + same code) with invalid_totp_code before this
+      // is reached, so this burn only needs to guard a DIFFERENT code
+      // (recovery, or a still-valid-but-not-yet-burned TOTP step) reused
+      // against the same challenge token.
+      const burnResult = await burnToken(ctx.redis, "mfa-challenge", userId, verified.expiresAtMs);
+      if (burnResult === "already-used") return invalidChallengeToken();
+
+      // Recovery-code use consumes the code — persist the reduced hash-list
+      // immediately so it can't be replayed. Without this a recovery code
+      // would work forever instead of being single-use.
+      if (verify.method === "recovery") {
+        const updateResult = await executor.update(
+          {
+            id: row.id,
+            version: row.version,
+            changes: { recoveryCodes: encodeRecoveryCodes(verify.remainingHashes) },
+          },
+          scopedUser,
+          scopedDb,
+        );
+        if (!updateResult.isSuccess) return updateResult;
+      }
+
+      await clearMfaVerifyAttempts(ctx.redis, userId);
+
+      // Re-derive the full session the way login.write.ts would have, for
+      // the SAME tenant the challenge token already committed to (no
+      // "pick a tenant" step here — that already happened at login time).
+      const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
+      const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+        id: userId,
+      })) as {
+        roles?: string | null;
+        status?: string;
+        timezone?: string | null;
+        locale?: string | null;
+      } | 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) return invalidChallengeToken();
+      if (
+        userRow?.status === USER_STATUS.Restricted ||
+        userRow?.status === USER_STATUS.DeletionRequested ||
+        userRow?.status === USER_STATUS.Deleted
+      ) {
+        return invalidChallengeToken();
+      }
+
+      const globalRoles = parseRoles(userRow?.roles ?? null);
+
+      // Membership revoked or principal blocked between login and verify —
+      // mirror login.write.ts's refusal instead of falling back to globalRoles only.
+      const active = await ctx.resolveActiveMembership(userId, tenantId);
+      if (active.kind === "rejected") 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, active.membership.roles);
+
+      const baseSession: SessionUser = {
+        id: userId,
+        tenantId,
+        roles: mergedRoles,
+        ...sessionTimezoneField(userRow?.timezone),
+        ...sessionLocaleField(userRow?.locale),
+      };
+      const claims = await ctx.resolveAuthClaims(baseSession);
+      const session: SessionUser =
+        Object.keys(claims).length > 0 ? { ...baseSession, claims } : baseSession;
+
+      return { isSuccess: true, data: { kind: "mfa-verify-success", session } };
+    },
+  });
+}

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

@@ -0,0 +1,79 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Temporal } from "temporal-polyfill";
+
+function hmacSign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+export type HmacTokenVerifyResult<TPayload> =
+  | { readonly ok: true; readonly payload: TPayload; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+// `domain` is part of the signed input: it is the only thing that stops a token
+// minted for one MFA step from verifying as another (e.g. a preauth-setup token
+// replayed as a challenge token), since both share the same secret and payload shape.
+export function createHmacTokenCodec<
+  TPayload extends { readonly userId: string; readonly tenantId: string },
+>(domain: string, isPayload: (value: unknown) => value is TPayload) {
+  type EncodedBody = TPayload & { readonly expiresAtMs: number };
+
+  function splitEncodedBody(
+    value: unknown,
+  ): { readonly payload: TPayload; readonly expiresAtMs: number } | null {
+    if (typeof value !== "object" || value === null) return null;
+    const v = value as Record<string, unknown>;
+    const expiresAtMs = v["expiresAtMs"];
+    if (typeof expiresAtMs !== "number") return null;
+    const { expiresAtMs: _drop, ...rest } = v;
+    return isPayload(rest) ? { payload: rest, expiresAtMs } : null;
+  }
+
+  return {
+    sign(
+      payload: TPayload,
+      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 = hmacSign(`${domain}:${bodyB64}`, secret);
+      return { token: `${bodyB64}.${signature}`, expiresAt };
+    },
+
+    verify(
+      token: string,
+      secret: string,
+      now: Temporal.Instant = Temporal.Now.instant(),
+    ): HmacTokenVerifyResult<TPayload> {
+      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 = hmacSign(`${domain}:${bodyB64}`, secret);
+      const expectedBuf = Buffer.from(expected, "base64url");
+      const providedBuf = Buffer.from(providedSig, "base64url");
+      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" };
+      }
+      const body = splitEncodedBody(parsed);
+      if (!body) return { ok: false, reason: "malformed" };
+
+      if (
+        Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(body.expiresAtMs)) > 0
+      ) {
+        return { ok: false, reason: "expired" };
+      }
+
+      return { ok: true, payload: body.payload, expiresAtMs: body.expiresAtMs };
+    },
+  };
+}

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

@@ -0,0 +1,50 @@
+// Server-side, boot-validated i18n keys — screen titles/descriptions the
+// engine requires every registered r.screen to declare. Distinct from
+// web/i18n.ts (the client's free-form UI-string bundle) — see
+// personal-access-tokens/i18n.ts for the same split.
+type LocalizedString = { readonly en: string };
+
+export const AUTH_MFA_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:auth-mfa-enable.title": {
+    en: "Two-factor authentication",
+  },
+
+  "auth-mfa.screen.auth-mfa-enable.subtitle": {
+    en: "Protect your account with a code from an authenticator app.",
+  },
+  "auth-mfa.screen.auth-mfa-disable.subtitle": {
+    en: "Turn off two-factor authentication. Other sessions and access tokens are signed out.",
+  },
+  "auth-mfa.screen.auth-mfa-regenerate-recovery.subtitle": {
+    en: "Replace all recovery codes. The new codes are shown only once.",
+  },
+
+  "mfa.enable.start": { en: "Start setup" },
+
+  "mfa.enable.reveal.title": { en: "Set up your authenticator app" },
+  "mfa.enable.reveal.warning": {
+    en: "Save your recovery codes now — for security everything on this screen is shown only this once.",
+  },
+  "mfa.enable.reveal.qr": { en: "Scan this QR code" },
+  "mfa.enable.reveal.secret": { en: "Or enter this code manually" },
+  "mfa.enable.reveal.recoveryCodes": { en: "Recovery codes" },
+
+  "mfa.enable.confirm.submit": { en: "Enable" },
+  "mfa.enable.confirm.done": { en: "Two-factor authentication is now enabled." },
+
+  "screen:auth-mfa-disable.title": { en: "Disable two-factor authentication" },
+  "mfa.disable.submit": { en: "Disable" },
+
+  "screen:auth-mfa-regenerate-recovery.title": { en: "Generate new recovery codes" },
+  "mfa.regenerate.submit": { en: "Generate new codes" },
+  "mfa.regenerate.reveal.title": { en: "Your new recovery codes" },
+  "mfa.regenerate.reveal.warning": {
+    en: "Save these codes now — they are shown only this once, and your previous codes no longer work.",
+  },
+
+  // Field label for the confirm step's pseudo-entity (`__action-form__`, see
+  // action-form-shim.ts) — required by the i18n boot-validator
+  // (requiredKeysFromScreen); the declarative renderer resolves this through
+  // the schema payload, not a client component's t().
+  "auth-mfa:entity:__action-form__:field:code": { en: "Code from your authenticator app" },
+};