@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

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-preauth-setup-token.ts

@@ -0,0 +1,86 @@
+// HMAC-signed token minted by login.write.ts when enforcement policy blocks
+// an unenrolled user (mfa-setup-required) — proves the password check
+// already succeeded, so a later pre-auth enable-start variant (#1231) can
+// let the user enroll without a full session. No secret material (unlike
+// mfa-setup-token.ts) — just enough to look the user back up.
+//
+// Same domain-separated HMAC shape as mfa-challenge-token.ts, distinct
+// signing string so this can never be replayed as a login challenge or
+// vice versa. Reuses challengeTokenSecret rather than adding a third
+// feature secret: both tokens assert the identical trust boundary
+// ("password already verified, short-lived follow-up allowed").
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+
+export type MfaPreauthSetupPayload = {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+};
+
+type EncodedBody = MfaPreauthSetupPayload & { readonly expiresAtMs: number };
+
+function sign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+export function signMfaPreauthSetupToken(
+  payload: MfaPreauthSetupPayload,
+  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-preauth-setup:${bodyB64}`, secret);
+  return { token: `${bodyB64}.${signature}`, expiresAt };
+}
+
+export type VerifyMfaPreauthSetupResult =
+  | { readonly ok: true; readonly payload: MfaPreauthSetupPayload; 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 verifyMfaPreauthSetupToken(
+  token: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyMfaPreauthSetupResult {
+  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-preauth-setup:${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,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/src/auth-mfa/mfa-status-checker.ts

@@ -0,0 +1,84 @@
+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, MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES } from "./constants";
+import { findUserMfaRow } from "./db/queries";
+import { signMfaChallengeToken } from "./mfa-challenge-token";
+import { signMfaPreauthSetupToken } from "./mfa-preauth-setup-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; 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) => {
+    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 };
+    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/src/auth-mfa/mfa-verify-attempts.ts

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

package/src/auth-mfa/otpauth-uri.ts

@@ -0,0 +1,21 @@
+import { base32Encode } from "./base32";
+
+// 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/src/auth-mfa/recovery-codes.ts

@@ -0,0 +1,54 @@
+import { randomInt } from "node:crypto";
+import { hashPassword, verifyPassword } from "../shared";
+
+const RECOVERY_CODE_COUNT = 8;
+// No ambiguous chars (0/O, 1/I) — these get read aloud or copy-typed from a
+// screen during account-recovery, a context where a misread costs a support
+// ticket, not just a retry.
+const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+
+// 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/src/auth-mfa/schema/user-mfa.ts

@@ -0,0 +1,60 @@
+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({
+  table: "read_user_mfa",
+  fields: {
+    // FK to the user row, not content — PII-naming heuristic would flag
+    // "userId" as content; it's a pseudonymous reference, matching the same
+    // annotation `config`'s userId column uses.
+    userId: createTextField({ required: true, allowPlaintext: "pseudonymous-fk" }),
+    // Envelope-encrypted via the same MasterKeyProvider as secrets/config
+    // (entity-field-encryption.ts) — no manual wrapDek/unwrapDek needed.
+    // userOwned: crypto-shredding this field is exactly "revoke this
+    // user's 2FA on GDPR forget", which is the correct behavior anyway.
+    totpSecret: createTextField({
+      required: true,
+      encrypted: true,
+      userOwned: { ownerField: "userId" },
+    }),
+    // 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,
+      userOwned: { ownerField: "userId" },
+    }),
+    enabledAt: createTimestampField({ required: true }),
+    lastUsedAt: createTimestampField(),
+  },
+  indexes: [{ unique: true, columns: ["userId", "tenantId"], name: "read_user_mfa_user_unique" }],
+});
+
+export const userMfaTable = buildEntityTable("user-mfa", userMfaEntity);
+
+// 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/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";

package/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;
+}