@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/auth-mfa/handlers/enable-start.write.ts

@@ -0,0 +1,66 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { base32Encode } from "../base32";
+import { MFA_SETUP_TOKEN_TTL_MINUTES } from "../constants";
+import { findUserMfaRow } from "../db/queries";
+import { mfaAlreadyEnabled } from "../errors";
+import { signMfaSetupToken } from "../mfa-setup-token";
+import { buildOtpauthUri } from "../otpauth-uri";
+import { generateRecoveryCodes, hashRecoveryCodes } from "../recovery-codes";
+import { generateTotpSecret } from "../totp";
+
+export type EnableStartOptions = {
+  readonly setupTokenSecret: string;
+  readonly issuer: string;
+};
+
+// Stateless setup: no `userMfa` row is created here. The generated secret +
+// recovery-code hashes are signed into a short-lived `setupToken` (see
+// mfa-setup-token.ts) that `enable-confirm` verifies. An abandoned setup
+// (user closes the tab without entering a code) leaves zero trace — no
+// cleanup job needed for orphaned "pending MFA" rows.
+export function createEnableStartHandler(opts: EnableStartOptions) {
+  return defineWriteHandler({
+    name: "enable-start",
+    schema: z.object({
+      // Client-supplied label for the otpauth:// URI / authenticator-app
+      // entry (typically the user's own email) — avoids an extra DB lookup
+      // for something the already-authenticated client already knows about
+      // itself.
+      accountLabel: z.string().min(1).max(200),
+    }),
+    access: { openToAll: true },
+    handler: async (event, ctx) => {
+      const existing = await findUserMfaRow(ctx.db, event.user);
+      if (existing) return mfaAlreadyEnabled();
+
+      const secret = generateTotpSecret();
+      const recoveryCodes = generateRecoveryCodes();
+      const recoveryCodeHashes = await hashRecoveryCodes(recoveryCodes);
+
+      const { token: setupToken } = signMfaSetupToken(
+        {
+          userId: event.user.id,
+          totpSecretBase32: base32Encode(secret),
+          recoveryCodeHashes,
+        },
+        MFA_SETUP_TOKEN_TTL_MINUTES,
+        opts.setupTokenSecret,
+      );
+
+      return {
+        isSuccess: true,
+        data: {
+          setupToken,
+          otpauthUri: buildOtpauthUri({
+            issuer: opts.issuer,
+            accountLabel: event.payload.accountLabel,
+            secret,
+          }),
+          // Plaintext — this is the one and only time these are shown.
+          recoveryCodes,
+        },
+      };
+    },
+  });
+}

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

@@ -0,0 +1,234 @@
+// 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 { 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",
+});
+
+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;
+};
+
+type EnvelopeClassification = "rotate" | "current" | "unrecognized";
+
+// After PII peel (when configured), values must be current-cipher envelopes.
+// Non-JSON / non-envelope is not a supported legacy decrypt path — fail the
+// row instead of treating it as "needs rotate" (#1541, mirrors config #1513).
+function classifyEnvelope(value: string, targetVersion: number): EnvelopeClassification {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return "unrecognized";
+  }
+  if (!isStoredEnvelope(parsed)) return "unrecognized";
+  return parsed.kekVersion === targetVersion ? "current" : "rotate";
+}
+
+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
+  // 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
+    }
+
+    const totpClass = classifyEnvelope(envelopeValues.totpSecret, targetVersion);
+    const recoveryClass = classifyEnvelope(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/src/auth-mfa/handlers/regenerate-recovery.write.ts

@@ -0,0 +1,77 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { findUserMfaRow } from "../db/queries";
+import { invalidTotpCode, mfaNotEnabled } from "../errors";
+import { generateRecoveryCodes, hashRecoveryCodes } from "../recovery-codes";
+import { encodeRecoveryCodes, 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.
+      //
+      // 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/src/auth-mfa/handlers/status.query.ts

@@ -0,0 +1,23 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { userMfaTable } from "../schema/user-mfa";
+
+// "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({}),
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const row = await fetchOne<{ id: string }>(ctx.db, userMfaTable, {
+      userId: query.user.id,
+    });
+    return { enabled: row !== undefined };
+  },
+});

package/src/auth-mfa/handlers/verify.write.ts

@@ -0,0 +1,179 @@
+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 { z } from "zod";
+import { burnToken } from "../../shared";
+import { USER_STATUS, 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 { encodeRecoveryCodes, 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;
+
+      // 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.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 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 } | 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);
+
+      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);
+      // Membership revoked between login and verify (race, or a stale
+      // challenge token from before removal) — login.write.ts would have
+      // refused with noMembership() at the same juncture; mirror it here
+      // instead of silently falling back to globalRoles only.
+      if (!membership) 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, 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,19 @@
+export { base32Decode } from "./base32";
+export { type MfaRequiredPolicy, mfaRequiredConfigHandle } from "./config";
+export {
+  AUTH_MFA_FEATURE,
+  AuthMfaHandlers,
+  AuthMfaQueries,
+  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";