@cosmicdrift/kumiko-framework 0.270.0 → 0.274.0

package/src/engine/__tests__/boot-validator.test.ts

@@ -2306,7 +2306,7 @@ describe("boot-validator", () => {
     function makeFeature(
       filter: {
         readonly field: string;
-        readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+        readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
         readonly value: unknown;
       },
       fields: Record<string, unknown> = {
@@ -2365,6 +2365,25 @@ describe("boot-validator", () => {
       ).not.toThrow();
     });
 
+    test("filter.op=lte/gte auf number-Feld → kein Throw (vergleichbar)", () => {
+      const fields = {
+        name: { type: "text", filterable: true },
+        rank: { type: "number", filterable: true },
+      };
+      expect(() =>
+        validateBoot([makeFeature({ field: "rank", op: "lte", value: 5 }, fields)]),
+      ).not.toThrow();
+      expect(() =>
+        validateBoot([makeFeature({ field: "rank", op: "gte", value: 5 }, fields)]),
+      ).not.toThrow();
+    });
+
+    test("filter.op=lte auf text-Feld → Throw (op-vs-Type-Compat)", () => {
+      expect(() => validateBoot([makeFeature({ field: "status", op: "lte", value: "x" })])).toThrow(
+        /filter\.op "lte" is not allowed on field "status" \(type "text"\)/,
+      );
+    });
+
     test('filter.op="in" mit non-array value → Throw', () => {
       expect(() =>
         validateBoot([makeFeature({ field: "status", op: "in", value: "active" })]),
@@ -2403,6 +2422,10 @@ describe("boot-validator", () => {
       readonly sections?: ReadonlyArray<{
         readonly title: string;
         readonly fields: readonly string[];
+        readonly groups?: ReadonlyArray<{
+          readonly title: string;
+          readonly fields: readonly string[];
+        }>;
       }>;
       readonly redirect?: string | { readonly screen: string; readonly idFrom: string };
       readonly cancelTarget?: string | false;
@@ -2501,6 +2524,53 @@ describe("boot-validator", () => {
       ).toThrow(/layout references unknown field "ghost"/);
     });
 
+    test("section mit fields UND groups → Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature({
+            sections: [
+              {
+                title: "Approval",
+                fields: ["note"],
+                groups: [{ title: "Priority", fields: ["priority"] }],
+              },
+            ],
+          }),
+        ]),
+      ).toThrow(/declares both fields and groups/);
+    });
+
+    test("group referenziert unknown field → Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature({
+            sections: [
+              { title: "Approval", fields: [], groups: [{ title: "Priority", fields: ["ghost"] }] },
+            ],
+          }),
+        ]),
+      ).toThrow(/layout references unknown field "ghost"/);
+    });
+
+    test("valide groups → kein Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature({
+            sections: [
+              {
+                title: "Approval",
+                fields: [],
+                groups: [
+                  { title: "Basics", fields: ["note"] },
+                  { title: "Priority", fields: ["priority"] },
+                ],
+              },
+            ],
+          }),
+        ]),
+      ).not.toThrow();
+    });
+
     test("redirect → existing screen-id im selben feature → kein Throw", () => {
       expect(() =>
         validateBoot([makeFeature({ redirect: "after-form", extraScreens: ["after-form"] })]),

package/src/engine/__tests__/engine.test.ts

@@ -754,6 +754,92 @@ describe("createRegistry", () => {
     expect(() => createRegistry([feature])).toThrow(/multiple/);
   });
 
+  test("throws at boot when a searchable reference targets an encrypted labelField", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({
+          table: "Customers",
+          fields: {
+            name: createTextField({ personal: false, reason: "test_fixture", encrypted: true }),
+          },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            customerId: {
+              type: "reference",
+              entity: "customer",
+              labelField: "name",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/encrypted\/PII/);
+  });
+
+  test('throws at boot when a searchable reference targets a PII labelField without find: "fuzzy" (no plaintext index)', () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "contact",
+        createEntity({
+          table: "Contacts",
+          fields: { displayName: createTextField({ personal: "self", find: "exact" }) },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            contactId: {
+              type: "reference",
+              entity: "contact",
+              labelField: "displayName",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/encrypted\/PII/);
+  });
+
+  test('does not throw when a searchable reference targets a PII labelField with find: "fuzzy" (derived search index)', () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "contact",
+        createEntity({
+          table: "Contacts",
+          fields: { displayName: createTextField({ personal: "self", find: "fuzzy" }) },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            contactId: {
+              type: "reference",
+              entity: "contact",
+              labelField: "displayName",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).not.toThrow();
+  });
+
   test("returns sortable reference fields for entity, without leaking them into getSortableFields (fw#2741)", () => {
     const feature = defineFeature("crm", (r) => {
       r.entity(

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(
@@ -242,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

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));
+  });
 });