@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/src/engine/__tests__/entity-create-caller-id.integration.test.ts

@@ -0,0 +1,87 @@
+// The schema lets a caller id through, but only a system identity gets it honored; HTTP users
+// can never present one (SYSTEM_ROLE is reserved), so both halves are pinned end to end here.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import {
+  createEntity,
+  createSystemUser,
+  createTextField,
+  defineEntityCreateHandler,
+  defineFeature,
+} from "../index";
+
+const thingEntity = createEntity({
+  table: "callerid_things",
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+  access: { write: { Admin: "all" } },
+});
+const CREATE_QN = "callerid:write:thing:create";
+
+const feature = defineFeature("callerid", (r) => {
+  r.entity("thing", thingEntity);
+  r.writeHandler(defineEntityCreateHandler("thing", thingEntity, { access: { roles: ["Admin"] } }));
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+  await unsafeCreateEntityTable(stack.db, thingEntity, "thing");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("entity create — caller-chosen id", () => {
+  test("system-identity caller: the chosen id is honored", async () => {
+    const chosenId = "00000000-0000-4000-8000-0000000000c1";
+    const systemUser = createSystemUser(admin.tenantId, ["Admin"]);
+    const result = await stack.http.writeOk<{ id: string }>(
+      CREATE_QN,
+      { label: "from a job", id: chosenId },
+      systemUser,
+    );
+    expect(result.id).toBe(chosenId);
+  });
+
+  test("system-identity caller retrying the same id → version_conflict, no duplicate row created", async () => {
+    const chosenId = "00000000-0000-4000-8000-0000000000c2";
+    const systemUser = createSystemUser(admin.tenantId, ["Admin"]);
+    await stack.http.writeOk<{ id: string }>(
+      CREATE_QN,
+      { label: "first attempt", id: chosenId },
+      systemUser,
+    );
+    const retry = await stack.http.writeErr(
+      CREATE_QN,
+      { label: "redelivered event", id: chosenId },
+      systemUser,
+    );
+    expect(retry.code).toBe("version_conflict");
+  });
+
+  test("ordinary end user: the payload id is ignored, a fresh id is minted", async () => {
+    const chosenId = "00000000-0000-4000-8000-0000000000c3";
+    const result = await stack.http.writeOk<{ id: string }>(
+      CREATE_QN,
+      { label: "from a browser", id: chosenId },
+      admin,
+    );
+    expect(result.id).not.toBe(chosenId);
+  });
+
+  test("malformed id → validation error, regardless of caller identity", async () => {
+    const systemUser = createSystemUser(admin.tenantId, ["Admin"]);
+    const err = await stack.http.writeErr(
+      CREATE_QN,
+      { label: "bad id", id: "not-a-uuid" },
+      systemUser,
+    );
+    expect(err.code).toBe("validation_error");
+  });
+});

package/src/engine/__tests__/entity-handlers-escape-hatch.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import {
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  isDeprecatedCrossTenantHandler,
+} from "../entity-handlers";
+import { createEntity, createTextField } from "../factories";
+
+const thingEntity = createEntity({
+  table: "escape_hatch_things",
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+});
+
+const sysadminAccess = { access: { roles: ["SystemAdmin"] } } as const;
+
+describe("entity convention handlers: escapeHatch option", () => {
+  test("throws when both escapeHatch and the deprecated crossTenant are set", () => {
+    expect(() =>
+      defineEntityUpdateHandler("thing", thingEntity, {
+        ...sysadminAccess,
+        escapeHatch: { reason: "operator write" },
+        crossTenant: true,
+      }),
+    ).toThrow(/declare either escapeHatch or the deprecated crossTenant, not both/);
+  });
+
+  test("throws when escapeHatch.reason is empty", () => {
+    expect(() =>
+      defineEntityUpdateHandler("thing", thingEntity, {
+        ...sysadminAccess,
+        escapeHatch: { reason: "" },
+      }),
+    ).toThrow(/non-empty reason/);
+  });
+
+  test("throws when escapeHatch.reason is whitespace-only", () => {
+    expect(() =>
+      defineEntityListHandler("thing", thingEntity, {
+        ...sysadminAccess,
+        escapeHatch: { reason: "   " },
+      }),
+    ).toThrow(/non-empty reason/);
+  });
+
+  test("WriteHandlerDef from an escapeHatch update handler carries no escapeHatch field", () => {
+    const def = defineEntityUpdateHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      escapeHatch: { reason: "operator cross-tenant write" },
+    });
+    expect("escapeHatch" in def).toBe(false);
+  });
+
+  test("QueryHandlerDef from an escapeHatch list handler carries no escapeHatch field", () => {
+    const def = defineEntityListHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      escapeHatch: { reason: "operator cross-tenant list" },
+    });
+    expect("escapeHatch" in def).toBe(false);
+  });
+
+  test("WriteHandlerDef from a legacy crossTenant handler also carries no escapeHatch field", () => {
+    const def = defineEntityUpdateHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      crossTenant: true,
+    });
+    expect("escapeHatch" in def).toBe(false);
+  });
+
+  test("isDeprecatedCrossTenantHandler is true only for handlers built with crossTenant: true", () => {
+    const legacyWrite = defineEntityUpdateHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      crossTenant: true,
+    });
+    const escapeHatchWrite = defineEntityUpdateHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      escapeHatch: { reason: "operator cross-tenant write" },
+    });
+    const plainWrite = defineEntityUpdateHandler("thing", thingEntity, sysadminAccess);
+    const legacyList = defineEntityListHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      crossTenant: true,
+    });
+
+    expect(isDeprecatedCrossTenantHandler(legacyWrite.handler)).toBe(true);
+    expect(isDeprecatedCrossTenantHandler(legacyList.handler)).toBe(true);
+    expect(isDeprecatedCrossTenantHandler(escapeHatchWrite.handler)).toBe(false);
+    expect(isDeprecatedCrossTenantHandler(plainWrite.handler)).toBe(false);
+  });
+});

package/src/engine/__tests__/entity-handlers.test.ts

@@ -72,6 +72,12 @@ describe("defineEntityWriteHandler", () => {
     expect(def.schema.safeParse({}).success).toBe(false);
   });
 
+  test("create: schema accepts an optional caller-chosen id, well-formed UUID only", () => {
+    const def = defineEntityCreateHandler("note", noteEntity, adminAccess);
+    expect(def.schema.safeParse({ title: "x", id: VALID_UUID }).success).toBe(true);
+    expect(def.schema.safeParse({ title: "x", id: "not-a-uuid" }).success).toBe(false);
+  });
+
   test("update: schema requires id + version + changes", () => {
     const def = defineEntityUpdateHandler("note", noteEntity, adminAccess);
     expect(
@@ -149,9 +155,11 @@ describe("defineEntityQueryHandler", () => {
 
   test("access option is forwarded", () => {
     const def = defineEntityListHandler("note", noteEntity, {
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
+    expect(def.access).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
     });
-    expect(def.access).toEqual({ openToAll: true });
   });
 });
 
@@ -180,10 +188,12 @@ describe("defineProjectionQueryHandler", () => {
     const def = defineProjectionQueryHandler(
       "revenue:list",
       "showcase:projection:customer-revenue",
-      { access: { openToAll: true } },
+      { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
     );
     expect(def.name).toBe("revenue:list");
-    expect(def.access).toEqual({ openToAll: true });
+    expect(def.access).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
     // Empty-object schema — handler takes no payload fields.
     expect(def.schema.safeParse({}).success).toBe(true);
   });
@@ -192,7 +202,7 @@ describe("defineProjectionQueryHandler", () => {
     const def = defineProjectionQueryHandler(
       "revenue:list",
       "showcase:projection:customer-revenue",
-      { access: { openToAll: true } },
+      { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
     );
     const fakeRows = [{ customer: "a", totalCents: 100 }];
     const ctx = {
@@ -215,7 +225,10 @@ describe("defineProjectionQueryHandler", () => {
     const def = defineProjectionQueryHandler(
       "revenue:list",
       "showcase:projection:customer-revenue",
-      { access: { openToAll: true }, unsafeAllTenants: true },
+      {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        unsafeAllTenants: true,
+      },
     );
     const ctx = { queryProjection: mock().mockResolvedValue([]) };
     await def.handler(
@@ -235,6 +248,28 @@ describe("defineProjectionQueryHandler", () => {
       defineProjectionQueryHandler("revenue:list", "showcase:projection:customer-revenue"),
     ).toThrow();
   });
+
+  test("escapeHatch is forwarded to the returned def", () => {
+    const def = defineProjectionQueryHandler(
+      "revenue:list",
+      "showcase:projection:customer-revenue",
+      {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        unsafeAllTenants: true,
+        escapeHatch: { reason: "fw#2913 test — cross-tenant revenue analytics" },
+      },
+    );
+    expect(def.escapeHatch).toEqual({ reason: "fw#2913 test — cross-tenant revenue analytics" });
+  });
+
+  test("escapeHatch is omitted from the def when not declared", () => {
+    const def = defineProjectionQueryHandler(
+      "revenue:list",
+      "showcase:projection:customer-revenue",
+      { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+    );
+    expect(def.escapeHatch).toBeUndefined();
+  });
 });
 
 // Verb-spezifische Wrappers — sind dünne Convenience-Layers über
@@ -328,7 +363,9 @@ describe("registerEntityCrud", () => {
     const { r, entities, writes, queries } = createCrudRegistrarMock();
     registerEntityCrud(r, "note", noteEntitySoftDelete, {
       write: { access: { roles: ["Admin"] } },
-      read: { access: { openToAll: true } },
+      read: {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      },
     });
     expect(entities["note"]).toBe(noteEntitySoftDelete);
     expect(writes.map((w) => w.name)).toEqual([
@@ -339,7 +376,9 @@ describe("registerEntityCrud", () => {
     ]);
     expect(queries.map((q) => q.name)).toEqual(["note:list", "note:detail"]);
     expect(writes[0]?.access).toEqual({ roles: ["Admin"] });
-    expect(queries[0]?.access).toEqual({ openToAll: true });
+    expect(queries[0]?.access).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
   });
 
   test("verbs.delete: false skips delete handler", () => {

package/src/engine/__tests__/entity-presave-wiring.integration.test.ts

@@ -50,7 +50,7 @@ const throwOnPreSave: import("../types").PreSaveHookFn = async () => {
 const contactFeature = defineFeature("presave-wiring", (r) => {
   r.crud("contact", contactEntity, {
     write: { access: { roles: ["User"] } },
-    read: { access: { openToAll: true } },
+    read: { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   });
 
   // preSave has no entity-wide `{ allOf }` shorthand (unlike postSave/
@@ -70,7 +70,7 @@ const throwingEntity = createEntity({
 const throwingFeature = defineFeature("presave-wiring-throw", (r) => {
   r.crud("thing", throwingEntity, {
     write: { access: { roles: ["User"] } },
-    read: { access: { openToAll: true } },
+    read: { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   });
   r.hook("preSave", "thing:create", throwOnPreSave);
 });

package/src/engine/__tests__/entity-restore-tenant-isolation.integration.test.ts

@@ -3,11 +3,12 @@
 // a soft-deleted row belonging to another tenant and got the decrypted row back
 // in the response. delete() never had that hole (it goes through the
 // tenant-scoped loadById). These tests pin both halves: the tenant-scoped
-// handler must not reach across, and the crossTenant handler must still be able
-// to.
+// handler must not reach across, and the crossTenant/escapeHatch handlers
+// must still be able to.
 //
-// Two stacks on the SAME Postgres database: one registers the restore handler
-// without `crossTenant`, the other with it — a clean A/B on the one flag.
+// Three stacks on the SAME Postgres database: one registers the restore
+// handler without `crossTenant`/`escapeHatch`, one with the deprecated
+// `crossTenant: true`, one with `escapeHatch: { reason }`.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { selectMany } from "../../db/query";
@@ -39,7 +40,9 @@ const thingEntity = createEntity({
 });
 const thingTable = buildEntityTable("thing", thingEntity);
 
-function buildFeature(crossTenant: boolean) {
+const ESCAPE_HATCH_REASON = "fw#2915 integration test — operator restores a foreign tenant's row";
+
+function buildFeature(crossTenant: boolean, escapeHatch?: boolean) {
   return defineFeature("ctrestore", (r) => {
     r.entity("thing", thingEntity);
     r.writeHandler(
@@ -56,6 +59,7 @@ function buildFeature(crossTenant: boolean) {
       defineEntityRestoreHandler("thing", thingEntity, {
         access: { roles: ["Admin", "SystemAdmin"] },
         ...(crossTenant && { crossTenant: true }),
+        ...(escapeHatch && { escapeHatch: { reason: ESCAPE_HATCH_REASON } }),
       }),
     );
   });
@@ -65,6 +69,7 @@ const dbName = `kumiko_test_ctrestore_${crypto.randomUUID().replace(/-/g, "").sl
 
 let tenantScopedStack: TestStack;
 let crossTenantStack: TestStack;
+let escapeHatchStack: TestStack;
 
 beforeAll(async () => {
   tenantScopedStack = await setupTestStack({ features: [buildFeature(false)], dbName });
@@ -74,9 +79,15 @@ beforeAll(async () => {
     dbName,
     persistentDb: true,
   });
+  escapeHatchStack = await setupTestStack({
+    features: [buildFeature(false, true)],
+    dbName,
+    persistentDb: true,
+  });
 });
 
 afterAll(async () => {
+  await escapeHatchStack.cleanup();
   await crossTenantStack.cleanup();
   await tenantScopedStack.cleanup();
 });
@@ -140,4 +151,18 @@ describe("entity restore: tenant isolation", () => {
     expect(rows[0]?.["isDeleted"]).toBe(false);
     expect(rows[0]?.["tenantId"]).toBe(testTenantId(2));
   });
+
+  test("escapeHatch restore still reaches a foreign tenant's row", async () => {
+    const id = await createDeletedThing("escape-hatch-restore");
+
+    await escapeHatchStack.http.writeOk(
+      "ctrestore:write:thing:restore",
+      { id },
+      TestUsers.systemAdmin,
+    );
+
+    const rows = await selectMany(tenantScopedStack.db, thingTable, { id });
+    expect(rows[0]?.["isDeleted"]).toBe(false);
+    expect(rows[0]?.["tenantId"]).toBe(testTenantId(2));
+  });
 });