@cosmicdrift/kumiko-bundled-features 0.147.1 → 0.147.3

package/src/auth-mfa/handlers/reencrypt.job.ts

@@ -0,0 +1,185 @@
+// KEK-rotation job for userMfa.totpSecret (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).
+//
+// 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 {
+  configuredEntityFieldEncryption,
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { type EnvelopeCipher, isStoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
+import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
+
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_MAX_FAILURES = 10;
+const SYSTEM_ROLES = ["system"] as const;
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+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;
+};
+
+function needsReencrypt(value: string, targetVersion: number): boolean {
+  // legacy single-key format (base64 — can never start with "{")
+  if (!value.startsWith("{")) return true;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!isStoredEnvelope(parsed)) return true;
+    return parsed.kekVersion !== targetVersion;
+  } catch {
+    // malformed JSON — let the decrypt attempt surface the real error
+    return true;
+  }
+}
+
+export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): 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;
+  if (!ctx.db) {
+    throw new InternalError({
+      message: "[auth-mfa:reencrypt] ctx.db missing — job context requires a database connection.",
+    });
+  }
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
+
+  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;
+  };
+
+  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"> {
+    if (!needsReencrypt(row.totpSecret, targetVersion)) {
+      alreadyCurrent++;
+      return "skipped";
+    }
+
+    const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
+    // decrypt failure (missing legacy key, unknown kekVersion, tamper)
+    // throws → counted as failed via onRowError; the row stays untouched.
+    const plaintext = await cipher.decrypt(row.totpSecret, { 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, exactly like every other write to this field.
+    const result = await executor.update(
+      { id: row.id, version: row.version, changes: { totpSecret: plaintext } },
+      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/src/auth-mfa/handlers/regenerate-recovery.write.ts

@@ -0,0 +1,62 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { findUserMfaRow } from "../db/queries";
+import { invalidTotpCode, mfaNotEnabled } from "../errors";
+import { generateRecoveryCodes, hashRecoveryCodes } from "../recovery-codes";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
+import { verifyMfaFactor } from "../verify-factor";
+
+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: true },
+    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.
+      const verify = await verifyMfaFactor(row, event.payload.code);
+      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: { hashes: 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/src/auth-mfa/handlers/verify.write.ts

@@ -0,0 +1,141 @@
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  buildSessionRoles,
+  createSystemUser,
+  defineWriteHandler,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { z } from "zod";
+import { burnToken } from "../../shared";
+import { UserQueries } from "../../user";
+import { MFA_VERIFY_LOCKOUT_MINUTES, MFA_VERIFY_MAX_ATTEMPTS } from "../constants";
+import { findUserMfaRow } from "../db/queries";
+import { invalidChallengeToken, invalidTotpCode, tooManyAttempts } from "../errors";
+import { verifyMfaChallengeToken } from "../mfa-challenge-token";
+import {
+  clearMfaVerifyAttempts,
+  getMfaVerifyLockoutState,
+  recordFailedMfaVerifyAttempt,
+} from "../mfa-verify-attempts";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
+import { verifyMfaFactor } from "../verify-factor";
+
+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 a guest 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: ["all"] },
+    handler: async (event, ctx) => {
+      const verified = verifyMfaChallengeToken(
+        event.payload.challengeToken,
+        opts.challengeTokenSecret,
+      );
+      if (!verified.ok) return invalidChallengeToken();
+      const { userId, tenantId } = verified.payload;
+
+      // 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.
+      if (ctx.redis) {
+        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.raw, 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 verify = await verifyMfaFactor(row, event.payload.code);
+      if (!verify.ok) {
+        if (ctx.redis) {
+          await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
+        }
+        return invalidTotpCode();
+      }
+
+      // 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: { hashes: verify.remainingHashes } },
+          },
+          scopedUser,
+          scopedDb,
+        );
+        if (!updateResult.isSuccess) return updateResult;
+      }
+
+      if (ctx.redis) {
+        // Burn AFTER a successful verify — a still-failing attempt must not
+        // consume the token, or a fat-fingered code would strand the user.
+        const burnResult = await burnToken(
+          ctx.redis,
+          "mfa-challenge",
+          userId,
+          verified.expiresAtMs,
+        );
+        if (burnResult === "already-used") return invalidChallengeToken();
+        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.detail, {
+        id: userId,
+      })) as { roles?: string | null } | null; // @cast-boundary engine-payload
+      const globalRoles = parseRoles(userRow?.roles ?? null);
+
+      const memberships = (await ctx.queryAs(systemUser, "tenant:query:memberships", {
+        userId,
+      })) as ReadonlyArray<{ tenantId: string; roles: readonly string[] }>; // @cast-boundary engine-payload
+      const membership = memberships.find((m) => m.tenantId === tenantId);
+      const mergedRoles = buildSessionRoles(globalRoles, membership?.roles ?? []);
+
+      const baseSession: SessionUser = { id: userId, tenantId, roles: mergedRoles };
+      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/src/auth-mfa/i18n.ts

@@ -0,0 +1,12 @@
+// 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 de: string; readonly en: string };
+
+export const AUTH_MFA_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:auth-mfa-enable.title": {
+    de: "Zwei-Faktor-Authentifizierung",
+    en: "Two-factor authentication",
+  },
+};

package/src/auth-mfa/index.ts

@@ -0,0 +1,15 @@
+export { base32Decode } from "./base32";
+export { type MfaRequiredPolicy, mfaRequiredConfigHandle } from "./config";
+export { AUTH_MFA_FEATURE, AuthMfaHandlers, MFA_ENABLE_SCREEN_ID } from "./constants";
+export type {
+  AuthMfaFeatureOptions,
+  BindMfaRevokeAllOtherSessions,
+} from "./feature";
+export {
+  bindMfaRevokeAllOtherSessionsFromFeature,
+  createAuthMfaFeature,
+  mfaStatusCheckerFromFeature,
+} from "./feature";
+export type { MfaStatusChecker, MfaStatusCheckResult } from "./mfa-status-checker";
+export { userMfaEntity, userMfaTable } from "./schema/user-mfa";
+export { currentTotpCode } from "./totp";

package/src/auth-mfa/mfa-challenge-token.ts

@@ -0,0 +1,90 @@
+// HMAC-signed token minted by the login handler once the password check
+// succeeds but a second factor is still owed. Carries just enough to look
+// the user back up at `/auth/mfa/verify` — no secret material (unlike
+// mfa-setup-token.ts, this token is never shown to the user, only round-
+// tripped by the client between the two login requests).
+//
+// Format: <base64url(JSON body)>.<hmac-base64url> — same shape as
+// mfa-setup-token.ts, distinct HMAC domain-separation string so a setup
+// token can never be replayed as a challenge token or vice versa.
+//
+// Replay protection: burnToken()/unburnToken() from shared/token-burn-store
+// (purpose "mfa-challenge") make the token single-use on a SUCCESSFUL
+// verify. Brute-force protection is a SEPARATE mechanism — see
+// mfa-verify-attempts.ts — because burn-on-success alone doesn't cap wrong
+// guesses against a still-valid token.
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+
+export type MfaChallengePayload = {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+};
+
+type EncodedBody = MfaChallengePayload & { readonly expiresAtMs: number };
+
+function sign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+export function signMfaChallengeToken(
+  payload: MfaChallengePayload,
+  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-challenge:${bodyB64}`, secret);
+  return { token: `${bodyB64}.${signature}`, expiresAt };
+}
+
+export type VerifyMfaChallengeResult =
+  | { readonly ok: true; readonly payload: MfaChallengePayload; 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["tenantId"] === "string" &&
+    typeof v["expiresAtMs"] === "number"
+  );
+}
+
+export function verifyMfaChallengeToken(
+  token: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyMfaChallengeResult {
+  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-challenge:${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" };
+  }
+  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/src/auth-mfa/mfa-setup-token.ts

@@ -0,0 +1,90 @@
+// 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[];
+};
+
+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"
+  );
+}
+
+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/src/auth-mfa/mfa-status-checker.ts

@@ -0,0 +1,75 @@
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  type HandlerContext,
+  type SessionUser,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { type MfaRequiredPolicy, mfaRequiredConfigHandle, mfaRequiredConfigKey } from "./config";
+import { MFA_CHALLENGE_TOKEN_TTL_MINUTES } from "./constants";
+import { findUserMfaRow } from "./db/queries";
+import { signMfaChallengeToken } from "./mfa-challenge-token";
+
+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 };
+
+// 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) => {
+    const scopedDb = createTenantDb(ctx.db.raw, 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 (GUEST_USER 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 };
+    if (policy === "all") return { setupRequired: true };
+    // policy === "admins"
+    const isAdmin = roles.some((role) => access.admin.includes(role));
+    return isAdmin ? { setupRequired: true } : { required: false };
+  };
+}