@cosmicdrift/kumiko-bundled-features 0.269.2 → 0.273.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.269.2",
+  "version": "0.273.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>",
@@ -129,12 +129,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.269.2",
-    "@cosmicdrift/kumiko-framework": "0.269.2",
-    "@cosmicdrift/kumiko-headless": "0.269.2",
-    "@cosmicdrift/kumiko-renderer": "0.269.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.269.2",
-    "@cosmicdrift/kumiko-types": "0.269.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.273.0",
+    "@cosmicdrift/kumiko-framework": "0.273.0",
+    "@cosmicdrift/kumiko-headless": "0.273.0",
+    "@cosmicdrift/kumiko-renderer": "0.273.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.273.0",
+    "@cosmicdrift/kumiko-types": "0.273.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -163,7 +163,7 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.269.2",
-    "@cosmicdrift/kumiko-locale-es": "0.269.2"
+    "@cosmicdrift/kumiko-locale-de": "0.273.0",
+    "@cosmicdrift/kumiko-locale-es": "0.273.0"
   }
 }

package/src/__tests__/account-security-composition.boot.test.ts

@@ -40,14 +40,32 @@ describe("account-security composed from bundled screens (fw#2841)", () => {
 
   test("the self-service screens are open to every signed-in user", () => {
     const [, , , , , sessions, mfa] = bootFeatures();
-    const screens = [
-      sessions?.screens[SESSION_MINE_SCREEN_ID],
-      mfa?.screens[MFA_ENABLE_SCREEN_ID],
-      mfa?.screens[MFA_DISABLE_SCREEN_ID],
-      mfa?.screens[MFA_REGENERATE_RECOVERY_SCREEN_ID],
+    const screensWithReason: ReadonlyArray<{
+      readonly screen: { readonly access?: unknown } | undefined;
+      readonly reason: string;
+    }> = [
+      {
+        screen: sessions?.screens[SESSION_MINE_SCREEN_ID],
+        reason:
+          "each signed-in user views and revokes only their own sessions, mirroring the mine/revoke handlers",
+      },
+      {
+        screen: mfa?.screens[MFA_ENABLE_SCREEN_ID],
+        reason:
+          "each signed-in user may enroll their own account in MFA, mirroring the enable-start handler",
+      },
+      {
+        screen: mfa?.screens[MFA_DISABLE_SCREEN_ID],
+        reason: "each signed-in user may turn off their own MFA, mirroring the disable handler",
+      },
+      {
+        screen: mfa?.screens[MFA_REGENERATE_RECOVERY_SCREEN_ID],
+        reason:
+          "each signed-in user may regenerate their own recovery codes, mirroring the regenerate-recovery handler",
+      },
     ];
-    for (const screen of screens) {
-      expect(screen?.access).toEqual({ openToAll: true });
+    for (const { screen, reason } of screensWithReason) {
+      expect(screen?.access).toEqual({ openToAll: { reason } });
     }
   });
 

package/src/__tests__/account-security-composition.integration.test.ts

@@ -114,7 +114,29 @@ describe("account-security dashboard on a real stack", () => {
       "auth-mfa:screen:auth-mfa-disable",
       "sessions:screen:my-sessions",
     ]);
-    for (const qn of targets) expect(embeddedScreen(qn).access).toEqual({ openToAll: true });
+    const expectedReasons: ReadonlyArray<{ readonly qn: string; readonly reason: string }> = [
+      {
+        qn: "auth-mfa:screen:auth-mfa-enable",
+        reason:
+          "each signed-in user may enroll their own account in MFA, mirroring the enable-start handler",
+      },
+      {
+        qn: "auth-mfa:screen:auth-mfa-regenerate-recovery",
+        reason:
+          "each signed-in user may regenerate their own recovery codes, mirroring the regenerate-recovery handler",
+      },
+      {
+        qn: "auth-mfa:screen:auth-mfa-disable",
+        reason: "each signed-in user may turn off their own MFA, mirroring the disable handler",
+      },
+      {
+        qn: "sessions:screen:my-sessions",
+        reason:
+          "each signed-in user views and revokes only their own sessions, mirroring the mine/revoke handlers",
+      },
+    ];
+    for (const { qn, reason } of expectedReasons)
+      expect(embeddedScreen(qn).access).toEqual({ openToAll: { reason } });
   });
 
   test("a plain User gets the flat visibleWhen record and their own sessions over HTTP", async () => {

package/src/__tests__/account-security-fixture.ts

@@ -24,6 +24,9 @@ export const accountSecurityFeature = defineFeature("account-security", (r) => {
   r.screen({
     id: ACCOUNT_SECURITY_SCREEN_ID,
     type: "dashboard",
+    // Test fixture demonstrating composition — a real app would nav this,
+    // but that's out of scope here.
+    dormant: true,
     panels: [
       {
         kind: "screen",

package/src/agent-tools/__tests__/agent-doc-lint.test.ts

@@ -7,7 +7,9 @@ import {
 import { z } from "zod";
 import { AgentDocGapKinds, findAgentDocGaps, formatAgentDocGap } from "../agent-doc-lint";
 
-const OPEN_ACCESS = { openToAll: true } as const;
+const OPEN_ACCESS = {
+  openToAll: { reason: "test handler callable by any signed-in test user" },
+} as const;
 
 async function noopWriteHandler() {
   return { isSuccess: true as const, data: {} };

package/src/agent-tools/__tests__/feature.test.ts

@@ -9,9 +9,15 @@ async function noopWriteHandler() {
 
 function undocumentedHandlersFeature() {
   return defineFeature("doc-gap-demo", (r) => {
-    r.writeHandler("do-a", z.object({}), noopWriteHandler, { access: { openToAll: true } });
-    r.writeHandler("do-b", z.object({}), noopWriteHandler, { access: { openToAll: true } });
-    r.writeHandler("do-c", z.object({}), noopWriteHandler, { access: { openToAll: true } });
+    r.writeHandler("do-a", z.object({}), noopWriteHandler, {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
+    r.writeHandler("do-b", z.object({}), noopWriteHandler, {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
+    r.writeHandler("do-c", z.object({}), noopWriteHandler, {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
   });
 }
 
@@ -41,7 +47,7 @@ describe("createAgentToolsFeature", () => {
   test("boot check stays silent for a fully-described registry", () => {
     const describedFeature = defineFeature("doc-clean-demo", (r) => {
       r.writeHandler("do-a", z.object({}), noopWriteHandler, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         description: "Does A.",
       });
     });

package/src/audit/__tests__/escape-hatch-audit.integration.test.ts

@@ -0,0 +1,96 @@
+// fw#2861 — createEscapeHatchAuditSink persists an escape-hatch-use event as
+// audit:event:escape-hatch-used, visible through the existing audit:query:list
+// handler. Real HTTP calls + setupTestStack — never createTestDispatcher.
+// Modelled on audit.integration.test.ts for users/tenant setup + resetEventStore.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { defineFeature, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant";
+import { AuditQueries } from "../constants";
+import { createEscapeHatchAuditSink, ESCAPE_HATCH_USED_EVENT } from "../escape-hatch-audit-sink";
+import { createAuditFeature } from "../feature";
+
+const UNSAFE_RAW_REASON = "fw#2861 bundled-features integration test — declared unsafeRaw write";
+
+const probeFeature = defineFeature("escape-hatch-audit-sink-probe", (r) => {
+  r.writeHandler(
+    "unsafe-raw-write",
+    z.object({}),
+    async (_event, ctx) => {
+      ctx.db.unsafeRaw(UNSAFE_RAW_REASON);
+      return { isSuccess: true as const, data: { ok: true } };
+    },
+    { access: { roles: ["User"] }, escapeHatch: { reason: UNSAFE_RAW_REASON } },
+  );
+});
+
+let stack: TestStack;
+
+const tenantId = testTenantId(1);
+const user: SessionUser = createTestUser({ id: 9, tenantId, roles: ["User"] });
+const adminOfSameTenant: SessionUser = createTestUser({ id: 10, tenantId, roles: ["Admin"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [probeFeature, createConfigFeature(), createTenantFeature(), createAuditFeature()],
+    extraContext: ({ db }) => ({ _escapeHatchAuditSink: createEscapeHatchAuditSink({ db }) }),
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetEventStore(stack);
+});
+
+type AuditRow = {
+  id: string;
+  type: string;
+  createdBy: string;
+  payload: Record<string, unknown>;
+};
+
+type AuditResponse = { rows: AuditRow[]; nextBefore: string | null };
+
+async function pollForEscapeHatchRow(): Promise<AuditRow> {
+  const deadline = Date.now() + 2000;
+  while (Date.now() < deadline) {
+    const res = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { eventType: ESCAPE_HATCH_USED_EVENT },
+      adminOfSameTenant,
+    );
+    const row = res.rows[0];
+    if (row) return row;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error("escape-hatch-used audit row did not appear within 2s");
+}
+
+describe("createEscapeHatchAuditSink — persists audit:event:escape-hatch-used", () => {
+  test("an unsafeRaw use is queryable via audit:query:list", async () => {
+    await stack.http.writeOk("escape-hatch-audit-sink-probe:write:unsafe-raw-write", {}, user);
+
+    const row = await pollForEscapeHatchRow();
+
+    expect(row.type).toBe(ESCAPE_HATCH_USED_EVENT);
+    expect(row.createdBy).toBe(user.id);
+    expect(row.payload).toEqual({
+      handler: "escape-hatch-audit-sink-probe:write:unsafe-raw-write",
+      kind: "unsafe-raw",
+      reason: UNSAFE_RAW_REASON,
+      actor: user.id,
+    });
+  });
+});

package/src/audit/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.271.0",
+    "type": "improvement",
+    "title": "escapeHatchUsedSchema.kind accepts the new unsafe-all-tenants EscapeHatchKind (fw#2913).",
+    "detail": "`escapeHatchUsedSchema.kind` (`audit/escape-hatch-audit-sink.ts`) now also accepts `\"unsafe-all-tenants\"`, keeping the `satisfies readonly EscapeHatchKind[]` tuple in sync with the framework's new `EscapeHatchKind` member for a granted `ctx.queryProjection(qn, { unsafeAllTenants: true })` call — see the framework changelog for fw#2913. No consumer action needed; existing sinks already accept any `EscapeHatchKind`."
+  },
+  {
+    "version": "0.271.0",
+    "type": "improvement",
+    "title": "New escape-hatch-used audit sink: createEscapeHatchAuditSink records security:escape-hatch-used as audit:event:escape-hatch-used (fw#2861).",
+    "detail": "New `createEscapeHatchAuditSink({ db })` (`@cosmicdrift/kumiko-bundled-features/audit`) implements the framework's `EscapeHatchAuditSink` — it parses each escape-hatch-use event against the new `escapeHatchUsedSchema` and appends it as an `audit:event:escape-hatch-used` event (`r.defineEvent(\"escape-hatch-used\", ...)`, `piiFields: \"none\"`) on the unbound pool, so the entry survives a rollback of the handler that triggered it. `server-runtime`'s `buildBootExtraContext` wires it as `AppContext._escapeHatchAuditSink` automatically whenever the `audit` feature is mounted; without the feature, escape-hatch uses fall back to a structured warn log. Events show up in the existing `audit:query:list`/`audit-log` screen like any other event."
+  },
   {
     "version": "0.241.0",
     "type": "breaking",

package/src/audit/escape-hatch-audit-sink.ts

@@ -0,0 +1,52 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { EscapeHatchAuditSink, EscapeHatchKind } from "@cosmicdrift/kumiko-framework/engine";
+import { append } from "@cosmicdrift/kumiko-framework/event-store";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { z } from "zod";
+
+export const ESCAPE_HATCH_USED_EVENT = "audit:event:escape-hatch-used";
+export const ESCAPE_HATCH_USE_AGGREGATE_TYPE = "escapeHatchUse";
+
+// Kept as a tuple so `satisfies` catches a kind added/removed/renamed on
+// EscapeHatchKind without this schema following along.
+const escapeHatchKinds = [
+  "unsafe-raw",
+  "acknowledge-cross-tenant",
+  "global-write",
+  "identity-switch",
+  "unsafe-all-tenants",
+] as const satisfies readonly EscapeHatchKind[];
+
+export const escapeHatchUsedSchema = z.object({
+  handler: z.string(),
+  kind: z.enum(escapeHatchKinds),
+  reason: z.string(),
+  actor: z.string(),
+  targetUserId: z.string().optional(),
+  targetTenantId: z.string().optional(),
+});
+
+export function createEscapeHatchAuditSink(opts: {
+  readonly db: DbConnection;
+}): EscapeHatchAuditSink {
+  return async (event) => {
+    const payload = escapeHatchUsedSchema.parse({
+      handler: event.handler,
+      kind: event.kind,
+      reason: event.reason,
+      actor: event.actor,
+      ...(event.target && { targetUserId: event.target.id, targetTenantId: event.target.tenantId }),
+    });
+    // Appends on the unbound pool, never the handler tx — an audit entry must
+    // survive a rollback of the handler that used the hatch.
+    await append(opts.db, {
+      aggregateId: generateId(),
+      aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+      tenantId: event.tenantId,
+      expectedVersion: 0,
+      type: ESCAPE_HATCH_USED_EVENT,
+      payload,
+      metadata: { userId: event.actor },
+    });
+  };
+}

package/src/audit/feature.ts

@@ -5,6 +5,7 @@ import {
   i18nKey,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID, AuditQueries } from "./constants";
+import { escapeHatchUsedSchema } from "./escape-hatch-audit-sink";
 import { detailsQuery } from "./handlers/details.query";
 import { listQuery } from "./handlers/list.query";
 import { AUDIT_I18N } from "./i18n";
@@ -24,7 +25,7 @@ import { AUDIT_I18N } from "./i18n";
 export function createAuditFeature(): FeatureDefinition {
   return defineFeature("audit", (r) => {
     r.describe(
-      "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range.",
+      "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
     );
     r.uiHints({
       displayLabel: "Audit Log",
@@ -35,6 +36,9 @@ export function createAuditFeature(): FeatureDefinition {
     // Screens resolve actor names via tenant:query:members.
     r.requires("tenant");
 
+    // Registered so ops tools/MSPs can discover the type — escape-hatch-audit-sink.ts appends it via the low-level event-store API.
+    r.defineEvent("escape-hatch-used", escapeHatchUsedSchema, { piiFields: "none" });
+
     const queries = {
       list: r.queryHandler(listQuery),
       details: r.queryHandler(detailsQuery),

package/src/audit/index.ts

@@ -1,2 +1,3 @@
 export { AUDIT_FEATURE, AuditQueries } from "./constants";
+export { createEscapeHatchAuditSink, ESCAPE_HATCH_USED_EVENT } from "./escape-hatch-audit-sink";
 export { createAuditFeature } from "./feature";