@cosmicdrift/kumiko-bundled-features 0.146.4 → 0.147.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.146.4",
+  "version": "0.147.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -111,11 +111,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.146.4",
-    "@cosmicdrift/kumiko-framework": "0.146.4",
-    "@cosmicdrift/kumiko-headless": "0.146.4",
-    "@cosmicdrift/kumiko-renderer": "0.146.4",
-    "@cosmicdrift/kumiko-renderer-web": "0.146.4",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.147.0",
+    "@cosmicdrift/kumiko-framework": "0.147.0",
+    "@cosmicdrift/kumiko-headless": "0.147.0",
+    "@cosmicdrift/kumiko-renderer": "0.147.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.147.0",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

package/src/admin-shell/__tests__/overview-allowlist.test.ts

@@ -38,5 +38,6 @@ describe("overview query allowlist", () => {
   test("platform queries are not tenant-allowlisted", () => {
     expect(isOverviewQueryAllowed("tenant", TenantQueries.list)).toBe(false);
     expect(isOverviewQueryAllowed("tenant", JobQueries.list)).toBe(false);
+    expect(isOverviewQueryAllowed("tenant", UserQueries.list)).toBe(false);
   });
 });

package/src/admin-shell/overview-allowlist.ts

@@ -25,6 +25,7 @@ export const TENANT_OVERVIEW_FORBIDDEN_QUERIES = [
   "jobs:query:list",
   "feature-toggles:query:list",
   "feature-toggles:query:registered",
+  "user:query:user:list",
 ] as const;
 
 export function overviewAllowedQueries(kind: OverviewWorkspaceKind): readonly string[] {

package/src/admin-shell/web/platform-overview-screen.tsx

@@ -16,11 +16,11 @@ export function PlatformOverviewScreen(): ReactNode {
   useEffect(() => {
     let cancelled = false;
     void (async (): Promise<void> => {
-      const tenantsRes = await overviewQuery<{ readonly rows: readonly unknown[] }>(
+      const tenantsRes = await overviewQuery<{ readonly total: number }>(
         "platform",
         dispatcher,
         TenantQueries.list,
-        {},
+        { totalCount: true },
       );
       if (cancelled) return;
       if (!tenantsRes.isSuccess) {
@@ -28,11 +28,11 @@ export function PlatformOverviewScreen(): ReactNode {
         return;
       }
 
-      const usersRes = await overviewQuery<{ readonly rows: readonly unknown[] }>(
+      const usersRes = await overviewQuery<{ readonly total: number }>(
         "platform",
         dispatcher,
         UserQueries.list,
-        {},
+        { totalCount: true },
       );
       if (cancelled) return;
       if (!usersRes.isSuccess) {
@@ -40,11 +40,11 @@ export function PlatformOverviewScreen(): ReactNode {
         return;
       }
 
-      const failedJobsRes = await overviewQuery<{ readonly rows: readonly unknown[] }>(
+      const failedJobsRes = await overviewQuery<{ readonly total: number }>(
         "platform",
         dispatcher,
         JobQueries.list,
-        { status: "failed", limit: 50 },
+        { status: "failed", totalCount: true },
       );
       if (cancelled) return;
       if (!failedJobsRes.isSuccess) {
@@ -57,20 +57,18 @@ export function PlatformOverviewScreen(): ReactNode {
         cards: [
           {
             label: t("admin-shell:overview.tenants"),
-            value: String(tenantsRes.data.rows.length),
+            value: String(tenantsRes.data.total),
           },
           {
             label: t("admin-shell:overview.users"),
-            value: String(usersRes.data.rows.length),
+            value: String(usersRes.data.total),
           },
           {
             label: t("admin-shell:overview.failedJobs"),
-            value: String(failedJobsRes.data.rows.length),
+            value: String(failedJobsRes.data.total),
             hint:
-              failedJobsRes.data.rows.length > 0
-                ? t("admin-shell:overview.failedJobsHint")
-                : undefined,
-            attention: failedJobsRes.data.rows.length > 0,
+              failedJobsRes.data.total > 0 ? t("admin-shell:overview.failedJobsHint") : undefined,
+            attention: failedJobsRes.data.total > 0,
           },
         ],
       });

package/src/audit/__tests__/audit-screens.boot.test.ts

@@ -15,22 +15,31 @@ describe("audit log screen + handler access alignment", () => {
   test("audit-log screen is custom, access.admin-gated", () => {
     const audit = createAuditFeature();
     const screen = audit.screens[AUDIT_LOG_SCREEN_ID];
-    expect(screen?.type).toBe("custom");
-    if (screen && "access" in screen && screen.access && "roles" in screen.access) {
-      expect(screen.access.roles).toEqual(access.admin);
+    if (!screen || screen.type !== "custom") {
+      throw new Error(`expected a custom screen for ${AUDIT_LOG_SCREEN_ID}, got ${screen?.type}`);
     }
+    if (!("access" in screen) || !screen.access || !("roles" in screen.access)) {
+      throw new Error(`expected role-gated access on ${AUDIT_LOG_SCREEN_ID}`);
+    }
+    expect(screen.access.roles).toEqual(access.admin);
   });
 
   test("audit-log-detail screen is custom, admin-gated, breadcrumb-linked to list", () => {
     const audit = createAuditFeature();
     const screen = audit.screens[AUDIT_LOG_DETAIL_SCREEN_ID];
-    expect(screen?.type).toBe("custom");
-    if (screen && "listScreenId" in screen) {
-      expect(screen.listScreenId).toBe(AUDIT_LOG_SCREEN_ID);
+    if (!screen || screen.type !== "custom") {
+      throw new Error(
+        `expected a custom screen for ${AUDIT_LOG_DETAIL_SCREEN_ID}, got ${screen?.type}`,
+      );
+    }
+    if (!("listScreenId" in screen)) {
+      throw new Error(`expected listScreenId on ${AUDIT_LOG_DETAIL_SCREEN_ID}`);
     }
-    if (screen && "access" in screen && screen.access && "roles" in screen.access) {
-      expect(screen.access.roles).toEqual(access.admin);
+    expect(screen.listScreenId).toBe(AUDIT_LOG_SCREEN_ID);
+    if (!("access" in screen) || !screen.access || !("roles" in screen.access)) {
+      throw new Error(`expected role-gated access on ${AUDIT_LOG_DETAIL_SCREEN_ID}`);
     }
+    expect(screen.access.roles).toEqual(access.admin);
   });
 
   test("audit queries use access.admin (screen ⊆ handler)", () => {

package/src/audit/handlers/details.query.ts

@@ -10,7 +10,7 @@ import { z } from "zod";
 export const detailsQuery = defineQueryHandler({
   name: "details",
   schema: z.object({
-    id: z.string().regex(/^\d+$/, "id must be a positive integer"),
+    id: z.string().regex(/^[1-9]\d*$/, "id must be a positive integer"),
   }),
   access: { roles: access.admin },
   handler: async (query, ctx) => {

package/src/audit/web/audit-log-detail-screen.tsx

@@ -1,7 +1,13 @@
 // @runtime client
 // Single audit event detail. Route entityId = event-store id (bigint string).
 
-import { useDispatcher, useNav, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import {
+  formatWhen,
+  useDispatcher,
+  useNav,
+  usePrimitives,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
 import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
 import { type ReactNode, useCallback, useEffect, useState } from "react";
 import { AuditQueries } from "../constants";
@@ -123,11 +129,3 @@ export function AuditLogDetailScreen(): ReactNode {
     </FormScreenShell>
   );
 }
-
-function formatWhen(value: string): string {
-  try {
-    return new Date(value).toLocaleString();
-  } catch {
-    return value;
-  }
-}

package/src/audit/web/audit-log-screen.tsx

@@ -4,12 +4,14 @@
 
 import {
   type DataTableSort,
+  formatWhen,
+  sortByAccessor,
   useDispatcher,
   useNav,
   usePrimitives,
   useTranslation,
 } from "@cosmicdrift/kumiko-renderer";
-import { type ReactNode, useCallback, useEffect, useState } from "react";
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
 import { AUDIT_LOG_DETAIL_SCREEN_ID, AuditQueries } from "../constants";
 
 type AuditRow = {
@@ -52,18 +54,22 @@ export function AuditLogScreen(): ReactNode {
   const [filters, setFilters] = useState<Filters>(EMPTY_FILTERS);
   const [sort, setSort] = useState<DataTableSort | null>(null);
 
+  const filtersRef = useRef(filters);
+  filtersRef.current = filters;
+
   const load = useCallback(
-    async (cursor?: string): Promise<void> => {
+    async (cursor?: string, overrideFilters?: Filters): Promise<void> => {
       setState({ kind: "loading" });
+      const f = overrideFilters ?? filtersRef.current;
       const res = await dispatcher.query<AuditResponse>(AuditQueries.list, {
         limit: 50,
         ...(cursor !== undefined && { before: cursor }),
-        ...(filters.eventType.trim() !== "" && { eventType: filters.eventType.trim() }),
-        ...(filters.aggregateType.trim() !== "" && {
-          aggregateType: filters.aggregateType.trim(),
+        ...(f.eventType.trim() !== "" && { eventType: f.eventType.trim() }),
+        ...(f.aggregateType.trim() !== "" && {
+          aggregateType: f.aggregateType.trim(),
         }),
-        ...(filters.from !== "" && { from: toIsoStart(filters.from) }),
-        ...(filters.to !== "" && { to: toIsoEnd(filters.to) }),
+        ...(f.from !== "" && { from: toIsoStart(f.from) }),
+        ...(f.to !== "" && { to: toIsoEnd(f.to) }),
       });
       if (!res.isSuccess) {
         setState({ kind: "error", message: res.error.message });
@@ -71,7 +77,7 @@ export function AuditLogScreen(): ReactNode {
       }
       setState({ kind: "ready", rows: res.data.rows, nextBefore: res.data.nextBefore });
     },
-    [dispatcher, filters],
+    [dispatcher],
   );
 
   useEffect(() => {
@@ -156,6 +162,7 @@ export function AuditLogScreen(): ReactNode {
             onClick={() => {
               setFilters(EMPTY_FILTERS);
               setBefore(undefined);
+              void load(undefined, EMPTY_FILTERS);
             }}
             testId="audit-log-reset-filters"
           >
@@ -179,7 +186,7 @@ export function AuditLogScreen(): ReactNode {
         ]}
         sort={sort}
         onSortChange={setSort}
-        rows={sortAudit(state.rows, sort).map((row) => ({
+        rows={sortByAccessor(state.rows, sort, SORT_ACCESSORS).map((row) => ({
           id: row.id,
           values: {
             when: formatWhen(row.createdAt),
@@ -234,26 +241,6 @@ const SORT_ACCESSORS: Record<string, (r: AuditRow) => string> = {
   type: (r) => r.type,
 };
 
-function sortAudit(rows: readonly AuditRow[], sort: DataTableSort | null): readonly AuditRow[] {
-  if (sort === null) return rows;
-  const accessor = SORT_ACCESSORS[sort.field];
-  if (accessor === undefined) return rows;
-  const factor = sort.dir === "asc" ? 1 : -1;
-  return [...rows].sort((a, b) => {
-    const av = accessor(a);
-    const bv = accessor(b);
-    return av < bv ? -factor : av > bv ? factor : 0;
-  });
-}
-
-function formatWhen(value: string): string {
-  try {
-    return new Date(value).toLocaleString();
-  } catch {
-    return value;
-  }
-}
-
 function toIsoStart(date: string): string {
   return new Date(`${date}T00:00:00.000Z`).toISOString();
 }

package/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -20,10 +20,10 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
+  buildSessionRoles,
   createSystemUser,
   defineWriteHandler,
   type SessionUser,
-  stripForbiddenMembershipRoles,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
@@ -169,7 +169,9 @@ export function createInviteAcceptWithLoginHandler() {
         const session: SessionUser = {
           id: userId,
           tenantId: invitationTenantId,
-          roles: stripForbiddenMembershipRoles([invitationRole]),
+          // buildSessionRoles calls stripForbiddenMembershipRoles internally —
+          // a reserved role on the invitation itself must never reach the session.
+          roles: buildSessionRoles([], [invitationRole]),
         };
 
         committed = true;

package/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -24,10 +24,10 @@ import {
   type DbConnection,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
+  buildSessionRoles,
   createSystemUser,
   defineWriteHandler,
   type SessionUser,
-  stripForbiddenMembershipRoles,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
@@ -165,7 +165,9 @@ export function createInviteSignupCompleteHandler() {
         const session: SessionUser = {
           id: userId,
           tenantId: invitationTenantId,
-          roles: stripForbiddenMembershipRoles([invitationRole]),
+          // buildSessionRoles calls stripForbiddenMembershipRoles internally —
+          // a reserved role on the invitation itself must never reach the session.
+          roles: buildSessionRoles([], [invitationRole]),
         };
 
         committed = true;

package/src/auth-email-password/password-hashing.ts

@@ -1,55 +1,4 @@
-import { hash as argonHash, verify as argonVerify } from "@node-rs/argon2";
-import { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
-
-// OWASP-recommended argon2id parameters (2024 guidance):
-//   memoryCost: 19 MiB, timeCost: 2, parallelism: 1
-// These strike a balance between login latency (~20ms on typical hardware)
-// and brute-force resistance. If hashing becomes a bottleneck, tune memoryCost
-// before parallelism — memory hardness is what defeats GPU attacks.
-//
-// algorithm: 2 = Argon2id (best of argon2i + argon2d).
-// We inline the numeric value instead of importing Algorithm because the
-// @node-rs/argon2 enum is const and breaks verbatimModuleSyntax imports.
-const HASH_OPTIONS = {
-  algorithm: 2,
-  memoryCost: 19456,
-  timeCost: 2,
-  parallelism: 1,
-} as const;
-
-// @wrapper-known semantic-alias
-export async function hashPassword(password: string): Promise<string> {
-  return argonHash(password, HASH_OPTIONS);
-}
-
-// Returns true if the password matches. Never throws on wrong passwords —
-// only on malformed hash strings (which would be a bug, not a login attempt).
-//
-// Two verifier paths:
-//   - argon2id (default, what `hashPassword` produces)
-//   - ASP.NET Core Identity V3 (verify-only, for legacy migrations from .NET
-//     stacks). Sniffed via the format marker; on a successful match the
-//     application can rehash to argon2 at the next password-change event.
-export async function verifyPassword(hashString: string, password: string): Promise<boolean> {
-  if (isIdentityV3Hash(hashString)) {
-    return verifyIdentityV3Hash(password, hashString);
-  }
-  try {
-    return await argonVerify(hashString, password);
-  } catch {
-    // argon2 throws on unparseable hash — treat as mismatch rather than 500
-    // to avoid revealing which accounts have corrupted stored hashes.
-    return false;
-  }
-}
-
-// Anti-enumeration timing equaliser (#774). The login handler runs this on
-// the no-user / no-hash path so a missing account costs the same argon2
-// latency as a real verify — otherwise response timing leaks whether an
-// email is registered. Derived from hashPassword once and cached, so it
-// always tracks HASH_OPTIONS; the password never matches, result discarded.
-let dummyHash: Promise<string> | undefined;
-export async function verifyDummyPassword(password: string): Promise<void> {
-  dummyHash ??= hashPassword("anti-enumeration-dummy");
-  await verifyPassword(await dummyHash, password);
-}
+// Moved to shared/ — reused across admin-shell, audit, sessions, tenant,
+// user-data-rights, user-profile, and now auth-mfa. Re-exported here for the
+// existing call sites within this feature that import via "./password-hashing".
+export { hashPassword, verifyDummyPassword, verifyPassword } from "../shared/password-hashing";

package/src/auth-email-password/web/user-menu.tsx

@@ -34,7 +34,7 @@ export type UserMenuProps = {
   readonly children?: ReactNode;
   /** "pill" (Default) = kompakter Topbar-Trigger; "sidebar" = volle NavUser-
    *  Row (Avatar + Name + Email) für den `sidebarFooter`-Slot der App-Shell.
-   *  Requires a `SidebarProvider` ancestor (547/3) — the default App-Shell
+   *  Requires a `SidebarProvider` ancestor — the default App-Shell
    *  `sidebarFooter` slot already provides one. */
   readonly variant?: UserMenuVariant;
 };

package/src/auth-mfa/__tests__/totp.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import { createHmac } from "node:crypto";
+import { base32Decode, base32Encode } from "../base32";
+import { buildOtpauthUri } from "../otpauth-uri";
+import { generateTotpSecret, verifyTotp } from "../totp";
+
+// RFC 6238 Appendix B test vectors use the ASCII secret "12345678901234567890"
+// (20 bytes) with SHA1 — the same algorithm this implementation hardcodes
+// (RFC 6238's SHA256/SHA512 variants are out of scope, matching every real
+// authenticator app which only speaks SHA1).
+const RFC_SECRET = Buffer.from("12345678901234567890", "ascii");
+
+// RFC 6238 Appendix B, SHA1 column: T=59s → code "94287082" (8-digit RFC
+// vector). This codebase computes 6-digit codes (Google Authenticator
+// convention) — take the last 6 digits, which is truncation-equivalent
+// since dynamic truncation just modulos a wider range.
+function rfcVectorCode8Digit(epochSeconds: number): string {
+  // Precomputed from RFC 6238 Appendix B for T=59.
+  if (epochSeconds === 59) return "94287082";
+  throw new Error("no precomputed vector for this timestamp");
+}
+
+describe("TOTP — RFC 6238 vectors", () => {
+  test("6-digit code at T=59 matches the last 6 digits of the RFC 8-digit vector", () => {
+    const expected8 = rfcVectorCode8Digit(59);
+    const expected6 = expected8.slice(-6);
+    expect(verifyTotp(RFC_SECRET, expected6, 59_000)).toBe(true);
+  });
+
+  test("rejects a code from a different time window (>±1 step)", () => {
+    const expected8 = rfcVectorCode8Digit(59);
+    const expected6 = expected8.slice(-6);
+    // 59s + 3 steps (90s) is outside the ±1 (±30s) window.
+    expect(verifyTotp(RFC_SECRET, expected6, 59_000 + 3 * 30_000)).toBe(false);
+  });
+
+  test("accepts a code one step in the past or future (clock drift)", () => {
+    const secret = generateTotpSecret();
+    const now = 1_700_000_000_000;
+    // Derive the code for now, then verify it's still accepted 25s later —
+    // same 30s step, no window needed, sanity check for the step math.
+    const codeAtNow = deriveCodeForTest(secret, now);
+    expect(verifyTotp(secret, codeAtNow, now + 25_000)).toBe(true);
+  });
+
+  test("rejects wrong-length or non-numeric input without throwing", () => {
+    const secret = generateTotpSecret();
+    expect(verifyTotp(secret, "12345")).toBe(false);
+    expect(verifyTotp(secret, "1234567")).toBe(false);
+    expect(verifyTotp(secret, "abcdef")).toBe(false);
+    expect(verifyTotp(secret, "")).toBe(false);
+  });
+
+  test("generateTotpSecret returns 20 random, non-zero bytes", () => {
+    const a = generateTotpSecret();
+    const b = generateTotpSecret();
+    expect(a.length).toBe(20);
+    expect(a.equals(b)).toBe(false);
+  });
+});
+
+describe("base32", () => {
+  test("round-trips arbitrary byte buffers", () => {
+    for (const input of [
+      Buffer.from([]),
+      Buffer.from([0]),
+      Buffer.from([255]),
+      generateTotpSecret(),
+      Buffer.from("hello world", "ascii"),
+    ]) {
+      expect(base32Decode(base32Encode(input)).equals(input)).toBe(true);
+    }
+  });
+
+  test("decode is case-insensitive and tolerates stray whitespace", () => {
+    const encoded = base32Encode(Buffer.from("test-secret-bytes!!"));
+    expect(base32Decode(encoded.toLowerCase()).equals(base32Decode(encoded))).toBe(true);
+    expect(base32Decode(` ${encoded} `).equals(base32Decode(encoded))).toBe(true);
+  });
+
+  test("decode throws on a genuinely invalid character (e.g. punctuation)", () => {
+    expect(() => base32Decode("!!!not-valid-base32!!!")).toThrow();
+  });
+});
+
+describe("otpauth URI", () => {
+  test("builds a well-formed otpauth://totp URI with the expected params", () => {
+    const secret = generateTotpSecret();
+    const uri = buildOtpauthUri({
+      issuer: "Kumiko",
+      accountLabel: "acme:jane@example.com",
+      secret,
+    });
+    expect(uri).toStartWith("otpauth://totp/Kumiko%3Aacme%3Ajane%40example.com?");
+    const query = new URLSearchParams(uri.split("?")[1]);
+    expect(query.get("issuer")).toBe("Kumiko");
+    expect(query.get("algorithm")).toBe("SHA1");
+    expect(query.get("digits")).toBe("6");
+    expect(query.get("period")).toBe("30");
+    expect(base32Decode(query.get("secret") ?? "").equals(secret)).toBe(true);
+  });
+});
+
+// Internal helper mirroring the private `hotp`/`totpAt` math in totp.ts, kept
+// test-local so we don't have to export internals just for round-trip tests.
+function deriveCodeForTest(secret: Buffer, epochMs: number): string {
+  const step = Math.floor(epochMs / 1000 / 30);
+  // Re-implements the exact truncation from totp.ts's hotp() — duplicated
+  // deliberately: verifyTotp is the thing under test, so this must NOT call
+  // through it to derive its own expectation.
+  const counterBuf = Buffer.alloc(8);
+  counterBuf.writeUInt32BE(Math.floor(step / 2 ** 32), 0);
+  counterBuf.writeUInt32BE(step % 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 ** 6).padStart(6, "0");
+}

package/src/auth-mfa/base32.ts

@@ -0,0 +1,45 @@
+// RFC 4648 Base32 (no padding) — the encoding TOTP secrets and otpauth://
+// URIs use. No external dependency: the alphabet lookup is ~20 lines and every
+// authenticator app (Google/Microsoft/Authy) expects exactly this variant.
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+export function base32Encode(bytes: Buffer): string {
+  let bits = 0;
+  let value = 0;
+  let output = "";
+  for (const byte of bytes) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      output += ALPHABET[(value >>> (bits - 5)) & 0x1f];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    output += ALPHABET[(value << (5 - bits)) & 0x1f];
+  }
+  return output;
+}
+
+// Accepts lowercase and stray whitespace (authenticator apps and users
+// copy-pasting secrets are inconsistent about casing) — normalizes case and
+// strips whitespace before decoding, but throws on a genuinely invalid
+// character so a corrupted stored secret fails loud at read time instead of
+// silently producing wrong codes.
+export function base32Decode(encoded: string): Buffer {
+  const clean = encoded.trim().toUpperCase().replace(/\s+/g, "");
+  let bits = 0;
+  let value = 0;
+  const bytes: number[] = [];
+  for (const char of clean) {
+    const index = ALPHABET.indexOf(char);
+    if (index === -1) throw new Error(`base32Decode: invalid character "${char}"`);
+    value = (value << 5) | index;
+    bits += 5;
+    if (bits >= 8) {
+      bytes.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(bytes);
+}

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/totp.ts

@@ -0,0 +1,47 @@
+// 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";
+
+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");
+}
+
+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.
+export function verifyTotp(secret: Buffer, code: string, nowMs: number = Date.now()): boolean {
+  if (!/^\d{6}$/.test(code)) return false;
+  const codeBuf = Buffer.from(code);
+  const nowSeconds = Math.floor(nowMs / 1000);
+  let matched = false;
+  for (let w = -WINDOW; w <= WINDOW; w++) {
+    const candidate = Buffer.from(totpAt(secret, nowSeconds + w * STEP_SECONDS));
+    if (timingSafeEqual(candidate, codeBuf)) matched = true;
+  }
+  return matched;
+}

package/src/billing-foundation/events.ts

@@ -51,10 +51,10 @@ const statusEnum = z.enum([
 // payload — payload ist domain-clean, metadata ist provider-truth).
 export const subscriptionEventPayloadSchema = z.object({
   providerName: z.string().min(1).max(50),
-  // 1000, not 200: these two are `encrypted: true` on the entity (see
-  // entities.ts) — process-event.write.ts stores the envelope-cipher
-  // ciphertext here, not the raw provider id. A 200-char plaintext id
-  // becomes ~460+ chars of JSON envelope; 1000 leaves headroom.
+  // 1000, not 200: these two are `tenantOwned: true` on the entity (see
+  // entities.ts — crypto-shreds on tenant-destroy, unlike `encrypted`).
+  // process-event.write.ts stores the PII-ciphertext here, not the raw
+  // provider id. A 200-char plaintext id becomes ~300+ chars of ciphertext.
   providerCustomerId: z.string().min(1).max(1000),
   providerSubscriptionId: z.string().min(1).max(1000),
   status: statusEnum,