@cosmicdrift/kumiko-bundled-features 0.221.0 → 0.222.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.221.0",
+  "version": "0.222.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>",
@@ -71,6 +71,7 @@
     "./file-derivatives": "./src/file-derivatives/index.ts",
     "./derivatives-sharp": "./src/derivatives-sharp/index.ts",
     "./files": "./src/files/index.ts",
+    "./files-tenant-data": "./src/files-tenant-data/index.ts",
     "./user-data-rights": "./src/user-data-rights/index.ts",
     "./user-data-rights/web": "./src/user-data-rights/web/index.ts",
     "./user-data-rights-defaults": "./src/user-data-rights-defaults/index.ts",
@@ -126,12 +127,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.221.0",
-    "@cosmicdrift/kumiko-framework": "0.221.0",
-    "@cosmicdrift/kumiko-headless": "0.221.0",
-    "@cosmicdrift/kumiko-renderer": "0.221.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.221.0",
-    "@cosmicdrift/kumiko-types": "0.221.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.222.0",
+    "@cosmicdrift/kumiko-framework": "0.222.0",
+    "@cosmicdrift/kumiko-headless": "0.222.0",
+    "@cosmicdrift/kumiko-renderer": "0.222.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.222.0",
+    "@cosmicdrift/kumiko-types": "0.222.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -160,7 +161,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.221.0",
-    "@cosmicdrift/kumiko-locale-es": "0.221.0"
+    "@cosmicdrift/kumiko-locale-de": "0.222.0",
+    "@cosmicdrift/kumiko-locale-es": "0.222.0"
   }
 }

package/src/audit/__tests__/audit-log-screen.test.tsx

@@ -218,14 +218,14 @@ describe("AuditLogScreen — actor name resolution", () => {
     expect(view.getByTestId("cell-2-actor").textContent).toBe("bob@example.com");
   });
 
-  test("createdBy not in members list → cell is empty, never the raw id", async () => {
+  test("createdBy not in members list → cell shows Unknown actor, never the raw id", async () => {
     const view = renderScreen();
     await waitFor(() => {
       const cell = view.queryByTestId("cell-3-actor");
       if (cell === null) throw new Error("actor cell not rendered yet");
     });
     const cell = view.getByTestId("cell-3-actor");
-    expect(cell.textContent).toBe("");
+    expect(cell.textContent).toBe("Unknown actor");
     expect(cell.textContent).not.toBe("user-missing");
   });
 
@@ -248,14 +248,14 @@ describe("AuditLogScreen — actor name resolution", () => {
     expect(view.getByTestId("cell-4-actor").textContent).toBe("System");
   });
 
-  test("createdBy is an unresolvable UUID → cell stays empty, raw UUID never rendered", async () => {
+  test("createdBy is an unresolvable UUID → Unknown actor label, raw UUID never rendered", async () => {
     const view = renderScreen();
     await waitFor(() => {
       const cell = view.queryByTestId("cell-5-actor");
       if (cell === null) throw new Error("actor cell not rendered yet");
     });
     const cell = view.getByTestId("cell-5-actor");
-    expect(cell.textContent).toBe("");
+    expect(cell.textContent).toBe("Unknown actor");
     expect(view.container.textContent).not.toContain("3f2504e0-4f89-11d3-9a0c-0305e82c3301");
   });
 });
@@ -271,7 +271,7 @@ describe("AuditLogScreen — members query failure", () => {
       if (cell === null) throw new Error("table not rendered yet");
     });
     expect(view.getByTestId("cell-1-type").textContent).toBe("widget.created");
-    expect(view.getByTestId("cell-1-actor").textContent).toBe("");
+    expect(view.getByTestId("cell-1-actor").textContent).toBe("Unknown actor");
   });
 });
 

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

@@ -2,11 +2,12 @@ import { describe, expect, test } from "bun:test";
 import { access, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config/feature";
+import { createTenantFeature } from "../../tenant/feature";
 import { AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID, AuditQueries } from "../constants";
 import { createAuditFeature } from "../feature";
 
 describe("audit log screen + handler access alignment", () => {
-  const features = [createConfigFeature(), createAuditFeature()];
+  const features = [createConfigFeature(), createTenantFeature(), createAuditFeature()];
 
   test("boot-validates with audit-log screen registered", () => {
     expect(() => validateBoot(features)).not.toThrow();

package/src/audit/__tests__/audit.integration.test.ts

@@ -21,6 +21,8 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { withoutAmbientTemporal } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant";
 import { AuditQueries } from "../constants";
 import { createAuditFeature } from "../feature";
 
@@ -59,7 +61,7 @@ const otherTenantAdmin: SessionUser = createTestUser({
 
 beforeAll(async () => {
   stack = await setupTestStack({
-    features: [widgetFeature, createAuditFeature()],
+    features: [widgetFeature, createConfigFeature(), createTenantFeature(), createAuditFeature()],
   });
   await unsafeCreateEntityTable(stack.db, widgetEntity);
 });

package/src/audit/__tests__/constants.test.ts

@@ -1,8 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { SYSTEM_ACTOR_ID } from "../constants";
+import { SYSTEM_ACTOR_ID, SYSTEM_ACTOR_IDS } from "../constants";
 
 describe("audit constants", () => {
   test("SYSTEM_ACTOR_ID matches the event-store system user id", () => {
     expect(SYSTEM_ACTOR_ID).toBe("system");
   });
+
+  test("SYSTEM_ACTOR_IDS includes createSystemUser nil UUID", () => {
+    expect(SYSTEM_ACTOR_IDS.has(SYSTEM_ACTOR_ID)).toBe(true);
+    expect(SYSTEM_ACTOR_IDS.has("00000000-0000-0000-0000-000000000000")).toBe(true);
+  });
 });

package/src/audit/constants.ts

@@ -2,9 +2,18 @@
 // Qualified handler names + screen ids — shared by server feature and web client.
 export const AUDIT_FEATURE = "audit" as const;
 
-/** Literal `createdBy` written by system-authored events (e.g. delivery attempts). */
+/** Literal `createdBy` written by hand-built system actors (secrets/jobs/…). */
 export const SYSTEM_ACTOR_ID = "system" as const;
 
+/** Literal `createdBy` for anonymous / unauthenticated actors. */
+export const ANONYMOUS_USER_ID = "anonymous" as const;
+
+/** All `createdBy` values that mean "system" in the audit UI (nil-UUID from createSystemUser + literal). */
+export const SYSTEM_ACTOR_IDS: ReadonlySet<string> = new Set([
+  SYSTEM_ACTOR_ID,
+  "00000000-0000-0000-0000-000000000000",
+]);
+
 export const AuditQueries = {
   list: "audit:query:list",
   details: "audit:query:details",

package/src/audit/feature.ts

@@ -31,6 +31,8 @@ export function createAuditFeature(): FeatureDefinition {
       recommended: false,
     });
     r.translations({ keys: AUDIT_I18N });
+    // Screens resolve actor names via tenant:query:members.
+    r.requires("tenant");
 
     const queries = {
       list: r.queryHandler(listQuery),

package/src/audit/i18n.ts

@@ -17,6 +17,8 @@ export const AUDIT_I18N: Readonly<Record<string, LocalizedString>> = {
   "audit.log.col.aggregate": { en: "Aggregate" },
   "audit.log.col.actor": { en: "Actor" },
   "audit.log.actor.system": { en: "System" },
+  "audit.log.actor.anonymous": { en: "Anonymous" },
+  "audit.log.actor.unknown": { en: "Unknown actor" },
   "audit.log.filter.eventType": { en: "Event type" },
   "audit.log.filter.aggregateType": { en: "Aggregate type" },
   "audit.log.filter.from": { en: "From" },

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

@@ -11,7 +11,7 @@ import {
 import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
 import { type ReactNode, useCallback, useEffect, useState } from "react";
 import { TenantQueries } from "../../tenant/constants";
-import { AuditQueries, SYSTEM_ACTOR_ID } from "../constants";
+import { ANONYMOUS_USER_ID, AuditQueries, SYSTEM_ACTOR_IDS } from "../constants";
 
 type AuditDetail = {
   readonly id: string;
@@ -68,7 +68,7 @@ export function AuditLogDetailScreen(): ReactNode {
       return;
     }
     const event = res.data;
-    if (event.createdBy === SYSTEM_ACTOR_ID) {
+    if (SYSTEM_ACTOR_IDS.has(event.createdBy)) {
       setState({ kind: "ready", event, memberLabel: "", isSystemActor: true });
       return;
     }
@@ -117,7 +117,11 @@ export function AuditLogDetailScreen(): ReactNode {
   }
 
   const { event, memberLabel, isSystemActor } = state;
-  const actorName = isSystemActor ? t("audit.log.actor.system") : memberLabel;
+  const actorName = isSystemActor
+    ? t("audit.log.actor.system")
+    : event.createdBy === ANONYMOUS_USER_ID
+      ? t("audit.log.actor.anonymous")
+      : memberLabel || t("audit.log.actor.unknown");
 
   return (
     <FormScreenShell

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

@@ -14,7 +14,12 @@ import {
 import { Filter, RotateCcw } from "lucide-react";
 import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
 import { TenantQueries } from "../../tenant/constants";
-import { AUDIT_LOG_DETAIL_SCREEN_ID, AuditQueries, SYSTEM_ACTOR_ID } from "../constants";
+import {
+  ANONYMOUS_USER_ID,
+  AUDIT_LOG_DETAIL_SCREEN_ID,
+  AuditQueries,
+  SYSTEM_ACTOR_IDS,
+} from "../constants";
 
 type AuditRow = {
   readonly id: string;
@@ -36,7 +41,6 @@ type MemberRow = {
 
 type Filters = {
   readonly eventType: string;
-  readonly aggregateType: string;
   readonly from: string;
   readonly to: string;
 };
@@ -51,7 +55,17 @@ type State =
       readonly names: ReadonlyMap<string, string>;
     };
 
-const EMPTY_FILTERS: Filters = { eventType: "", aggregateType: "", from: "", to: "" };
+const EMPTY_FILTERS: Filters = { eventType: "", from: "", to: "" };
+
+function actorLabel(
+  createdBy: string,
+  names: ReadonlyMap<string, string>,
+  t: (key: string) => string,
+): string {
+  if (SYSTEM_ACTOR_IDS.has(createdBy)) return t("audit.log.actor.system");
+  if (createdBy === ANONYMOUS_USER_ID) return t("audit.log.actor.anonymous");
+  return names.get(createdBy) ?? t("audit.log.actor.unknown");
+}
 
 export function AuditLogScreen(): ReactNode {
   const t = useTranslation();
@@ -71,10 +85,11 @@ export function AuditLogScreen(): ReactNode {
   const membersRef = useRef<Promise<ReadonlyMap<string, string>> | null>(null);
 
   // Tenant/dispatcher identity can change without remounting — drop the cache.
-  // biome-ignore lint/correctness/useExhaustiveDependencies: reset is keyed on dispatcher identity, not a read inside the effect
-  useEffect(() => {
+  const dispatcherIdentityRef = useRef(dispatcher);
+  if (dispatcherIdentityRef.current !== dispatcher) {
+    dispatcherIdentityRef.current = dispatcher;
     membersRef.current = null;
-  }, [dispatcher]);
+  }
 
   const load = useCallback(
     async (cursor?: string, overrideFilters?: Filters): Promise<void> => {
@@ -100,9 +115,6 @@ export function AuditLogScreen(): ReactNode {
           limit: 50,
           ...(cursor !== undefined && { before: cursor }),
           ...(f.eventType.trim() !== "" && { eventType: f.eventType.trim() }),
-          ...(f.aggregateType.trim() !== "" && {
-            aggregateType: f.aggregateType.trim(),
-          }),
           ...(f.from !== "" && { from: toIsoStart(f.from) }),
           ...(f.to !== "" && { to: toIsoEnd(f.to) }),
         }),
@@ -144,7 +156,7 @@ export function AuditLogScreen(): ReactNode {
   return (
     <div className="w-full" data-testid="audit-log-screen">
       <div className="flex flex-wrap items-end gap-4 px-6 pt-6">
-        <div className="min-w-40 flex-1">
+        <div className="min-w-40 max-w-64 flex-1">
           <Field id="audit-filter-event" label={t("audit.log.filter.eventType")}>
             <Input
               kind="text"
@@ -155,18 +167,7 @@ export function AuditLogScreen(): ReactNode {
             />
           </Field>
         </div>
-        <div className="min-w-40 flex-1">
-          <Field id="audit-filter-aggregate" label={t("audit.log.filter.aggregateType")}>
-            <Input
-              kind="text"
-              id="audit-filter-aggregate"
-              name="audit-filter-aggregate"
-              value={filters.aggregateType}
-              onChange={(v) => setFilters((f) => ({ ...f, aggregateType: v }))}
-            />
-          </Field>
-        </div>
-        <div className="min-w-40 flex-1">
+        <div className="min-w-40 max-w-64 flex-1">
           <Field id="audit-filter-from" label={t("audit.log.filter.from")}>
             <Input
               kind="date"
@@ -177,7 +178,7 @@ export function AuditLogScreen(): ReactNode {
             />
           </Field>
         </div>
-        <div className="min-w-40 flex-1">
+        <div className="min-w-40 max-w-64 flex-1">
           <Field id="audit-filter-to" label={t("audit.log.filter.to")}>
             <Input
               kind="date"
@@ -198,7 +199,7 @@ export function AuditLogScreen(): ReactNode {
             }}
             testId="audit-log-apply-filters"
           >
-            <Filter className="h-4 w-4" />
+            <Filter className="h-4 w-4" aria-hidden="true" />
             <span>{t("audit.log.filter.apply")}</span>
           </Button>
           <Button
@@ -211,7 +212,7 @@ export function AuditLogScreen(): ReactNode {
             }}
             testId="audit-log-reset-filters"
           >
-            <RotateCcw className="h-4 w-4" />
+            <RotateCcw className="h-4 w-4" aria-hidden="true" />
             <span>{t("audit.log.filter.reset")}</span>
           </Button>
         </div>
@@ -231,10 +232,7 @@ export function AuditLogScreen(): ReactNode {
           values: {
             when: formatWhen(row.createdAt),
             type: row.type,
-            actor:
-              row.createdBy === SYSTEM_ACTOR_ID
-                ? t("audit.log.actor.system")
-                : (state.names.get(row.createdBy) ?? ""),
+            actor: actorLabel(row.createdBy, state.names, t),
           },
         }))}
         onRowClick={(row) => openDetail(row.id)}

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

@@ -77,6 +77,9 @@ export type InviteCreateOptions = {
   // roles, and cannot raise above the inviter's max framework rank — only
   // further restrict assignable ranked roles.
   readonly canAssignRole?: (inviterRoles: readonly string[], targetRole: string) => boolean;
+  /** Opt-in allow-list for app-defined (unranked) roles the elevation guard
+   *  would otherwise reject with unassignable_membership_role (fw#2398). */
+  readonly additionalAssignableRoles?: readonly string[];
 };
 
 const executor = createEventStoreExecutor(tenantInvitationsTable, tenantInvitationEntity, {
@@ -108,7 +111,10 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
         [event.payload.role],
         [],
       );
-      if (elevationForbidden !== undefined) {
+      if (
+        elevationForbidden !== undefined &&
+        !opts.additionalAssignableRoles?.includes(elevationForbidden)
+      ) {
         return writeFailure(unassignableMembershipRoleError(elevationForbidden));
       }
 

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

@@ -108,7 +108,9 @@ export async function seedUserWithPassword(
  *  (SessionUser-Konstruktion für JWT-Mint) — sonst hätten zwei
  *  Stellen unabhängig "TenantAdmin" hardcoded und würden bei einem
  *  Refactor zu role-mismatch zwischen DB und Session leiden. */
-export const INITIAL_SIGNUP_ROLES = ["TenantAdmin"] as const;
+// TenantAdmin is the canonical owner role; Admin stays for handlers that still
+// gate on the legacy literal until those call sites move to access.admin.
+export const INITIAL_SIGNUP_ROLES = ["TenantAdmin", "Admin"] as const;
 
 export type ProvisionSignupAccountOptions = {
   readonly email: string;

package/src/auth-mfa/hmac-token-codec.ts

@@ -0,0 +1,75 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Temporal } from "temporal-polyfill";
+
+function hmacSign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+export type HmacTokenVerifyResult<TPayload> =
+  | { readonly ok: true; readonly payload: TPayload; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+export function createHmacTokenCodec<
+  TPayload extends { readonly userId: string; readonly tenantId: string },
+>(domain: string, isPayload: (value: unknown) => value is TPayload) {
+  type EncodedBody = TPayload & { readonly expiresAtMs: number };
+
+  function isEncodedBody(value: unknown): value is EncodedBody {
+    if (typeof value !== "object" || value === null) return false;
+    const v = value as Record<string, unknown>;
+    const expiresAtMs = v["expiresAtMs"];
+    if (typeof expiresAtMs !== "number") return false;
+    const { expiresAtMs: _drop, ...rest } = v;
+    return isPayload(rest);
+  }
+
+  return {
+    sign(
+      payload: TPayload,
+      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 = hmacSign(`${domain}:${bodyB64}`, secret);
+      return { token: `${bodyB64}.${signature}`, expiresAt };
+    },
+
+    verify(
+      token: string,
+      secret: string,
+      now: Temporal.Instant = Temporal.Now.instant(),
+    ): HmacTokenVerifyResult<TPayload> {
+      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 = hmacSign(`${domain}:${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: payload as unknown as TPayload, expiresAtMs };
+    },
+  };
+}

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

@@ -1,90 +1,35 @@
-// 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";
+import { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec";
 
 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");
+function isPayload(value: unknown): value is MfaChallengePayload {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v["userId"] === "string" && typeof v["tenantId"] === "string";
 }
 
+const codec = createHmacTokenCodec("mfa-challenge", isPayload);
+
 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 };
+  return codec.sign(payload, ttlMinutes, secret, now);
 }
 
-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 type VerifyMfaChallengeResult = HmacTokenVerifyResult<MfaChallengePayload>;
 
 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 };
+  return codec.verify(token, secret, now);
 }

package/src/auth-mfa/mfa-preauth-setup-token.ts

@@ -1,86 +1,35 @@
-// 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";
+import { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec";
 
 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");
+function isPayload(value: unknown): value is MfaPreauthSetupPayload {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v["userId"] === "string" && typeof v["tenantId"] === "string";
 }
 
+const codec = createHmacTokenCodec("mfa-preauth-setup", isPayload);
+
 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 };
+  return codec.sign(payload, ttlMinutes, secret, now);
 }
 
-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 type VerifyMfaPreauthSetupResult = HmacTokenVerifyResult<MfaPreauthSetupPayload>;
 
 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 };
+  return codec.verify(token, secret, now);
 }

package/src/cap-counter/stock-cap-guard.ts

@@ -49,7 +49,7 @@ export function createStockCapGuard<TCaps>(
     return writeFailure(
       new UnprocessableError(spec.code, {
         i18nKey: spec.i18nKey,
-        details: { field: spec.field, reason: spec.code, current, limit },
+        details: { field: spec.field, current, limit },
       }),
     );
   }