security: implement tickets #28-#35 + architecture decision #30

#28 - TOTP rate limiting (verifyTotp): added totpRateLimiter (10 req/30s),
  throws TOO_MANY_REQUESTS before DB hit; 16 unit tests including rate-limit
  exceeded + userId key isolation.

#29 - /api/reports/allocations role check: only ADMIN/MANAGER/CONTROLLER may
  access; returns 403 otherwise; 9 unit tests (401 unauthenticated, 403 for
  USER/VIEWER, 200 for allowed roles + xlsx format).

#31 - pgAdmin credentials moved out of docker-compose.yml into env vars;
  PGADMIN_PASSWORD is now required (:?) to prevent accidental plaintext
  exposure in committed files.

#34 - Server-side HTML sanitization for comment bodies via stripHtml():
  strips all tags + decodes safe entities before persistence; 16 unit tests
  covering passthrough, injection patterns, entity decoding.

#35 - MFA setup prompt banner (MfaPromptBanner): shown to ADMIN/MANAGER users
  without TOTP enabled; user-scoped localStorage snooze (7 days); links to
  /account/security; accessibility role=alert; 7 structural unit tests.

#33 - Auth anomaly alerting cron (/api/cron/auth-anomaly-check): detects
  HIGH_GLOBAL_FAILURE_RATE and CONCENTRATED_FAILURES in 30-minute window;
  CRITICAL notification to ADMINs; fail-closed via verifyCronSecret;
  10 unit tests.

#32 - MFA enforcement policy: added requireMfaForRoles field to SystemSettings
  schema + Prisma migration; auth.ts blocks login with MFA_REQUIRED_SETUP
  signal if role is enforced but TOTP not set up; signin page redirects to
  /account/security?mfa_required=1; settings schema + view model updated;
  11 unit tests.

#30 - API keys architecture decision documented in LEARNINGS.md; no code
  written — product decision required before implementation.

Co-Authored-By: claude-flow <ruv@ruv.net>

packages/api/src/__tests__/mfa-enforcement.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Unit tests for MFA enforcement via SystemSettings.requireMfaForRoles.
+ *
+ * Tests cover:
+ *   - requireMfaForRoles is returned by buildSystemSettingsViewModel
+ *   - buildSettingsUpdatePayload includes requireMfaForRoles in the DB payload
+ *   - buildSettingsUpdatePayload handles null (clear enforcement)
+ *   - Schema validation: valid roles accepted, invalid roles rejected
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  buildSettingsUpdatePayload,
+  buildSystemSettingsViewModel,
+  settingsUpdateInputSchema,
+} from "../router/settings-support.js";
+import type { RuntimeSecretField, RuntimeSecretStatus } from "../lib/system-settings-runtime.js";
+import { RUNTIME_SECRET_FIELDS } from "../lib/system-settings-runtime.js";
+
+const emptyRuntimeSecrets = Object.fromEntries(
+  RUNTIME_SECRET_FIELDS.map((field) => [
+    field,
+    { configured: false, activeSource: "none", hasStoredValue: false, envVarNames: [] } satisfies RuntimeSecretStatus,
+  ]),
+) as Record<RuntimeSecretField, RuntimeSecretStatus>;
+
+// Minimal stubs for required inputs
+function makeViewModelInput(
+  requireMfaForRoles: string[] | null | undefined = undefined,
+) {
+  return {
+    settings: {
+      requireMfaForRoles,
+    },
+    runtimeSettings: null,
+    runtimeSecrets: emptyRuntimeSecrets,
+    defaultSummaryPrompt: "",
+  };
+}
+
+describe("buildSystemSettingsViewModel — requireMfaForRoles", () => {
+  it("returns null when requireMfaForRoles is not set in DB", () => {
+    const vm = buildSystemSettingsViewModel(makeViewModelInput(undefined));
+    expect(vm.requireMfaForRoles).toBeNull();
+  });
+
+  it("returns null when requireMfaForRoles is explicitly null", () => {
+    const vm = buildSystemSettingsViewModel(makeViewModelInput(null));
+    expect(vm.requireMfaForRoles).toBeNull();
+  });
+
+  it("returns the configured roles array", () => {
+    const vm = buildSystemSettingsViewModel(makeViewModelInput(["ADMIN", "MANAGER"]));
+    expect(vm.requireMfaForRoles).toEqual(["ADMIN", "MANAGER"]);
+  });
+});
+
+describe("buildSettingsUpdatePayload — requireMfaForRoles", () => {
+  it("includes requireMfaForRoles in DB payload when provided", () => {
+    const { data } = buildSettingsUpdatePayload({ requireMfaForRoles: ["ADMIN"] });
+    expect(data.requireMfaForRoles).toEqual(["ADMIN"]);
+  });
+
+  it("sets requireMfaForRoles to null when explicitly cleared", () => {
+    const { data } = buildSettingsUpdatePayload({ requireMfaForRoles: null });
+    expect(data.requireMfaForRoles).toBeNull();
+  });
+
+  it("omits requireMfaForRoles from payload when not provided (no change)", () => {
+    const { data } = buildSettingsUpdatePayload({});
+    expect("requireMfaForRoles" in data).toBe(false);
+  });
+});
+
+describe("settingsUpdateInputSchema — requireMfaForRoles validation", () => {
+  it("accepts a valid array of system roles", () => {
+    const result = settingsUpdateInputSchema.safeParse({ requireMfaForRoles: ["ADMIN", "MANAGER"] });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts an empty array (disable enforcement)", () => {
+    const result = settingsUpdateInputSchema.safeParse({ requireMfaForRoles: [] });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts null (clear enforcement)", () => {
+    const result = settingsUpdateInputSchema.safeParse({ requireMfaForRoles: null });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects an invalid role string", () => {
+    const result = settingsUpdateInputSchema.safeParse({ requireMfaForRoles: ["SUPERUSER"] });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts omitted field (no change)", () => {
+    const result = settingsUpdateInputSchema.safeParse({});
+    expect(result.success).toBe(true);
+    expect(result.data?.requireMfaForRoles).toBeUndefined();
+  });
+});