@cosmicdrift/kumiko-framework 0.263.0 → 0.264.0

package/src/engine/registry-validate.ts

@@ -1,4 +1,5 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
+import { bindHookIdentitySwitchGrant } from "../pipeline/system-identity-switch";
 import { resolveName } from "./handler-helpers";
 import type {
   RegistryState,
@@ -14,7 +15,16 @@ import {
   SOFT_DELETE_GRACE_DAYS_KEY,
   softDeleteGraceDaysConfig,
 } from "./soft-delete-cleanup";
-import type { EventPiiFields, EventUpcastFn, FeatureDefinition, ReferenceFieldDef } from "./types";
+import type {
+  EventPiiFields,
+  EventUpcastFn,
+  FeatureDefinition,
+  PostDeleteHookFn,
+  PostSaveHookFn,
+  PreDeleteHookFn,
+  PreSaveHookFn,
+  ReferenceFieldDef,
+} from "./types";
 import { HookPhases } from "./types";
 
 function allHandlerQns(state: RegistryState): ReadonlySet<string> {
@@ -115,29 +125,46 @@ export function applyExtensionUsages(state: RegistryState): void {
     // to also be gated, store the registering-feature on
     // RegistrarExtensionRegistration and use that here.
     const extOwner = "*";
+    // Extensions have no declaration site for escapeHatch, so SYSTEM is always denied
+    // (system-identity-switch.ts) — bindHookIdentitySwitchGrant(..., undefined) below.
     if (ext.hooks) {
       if (ext.hooks.postSave) {
+        const wrapped = bindHookIdentitySwitchGrant(
+          ext.hooks.postSave,
+          `postSave hook of extension "${usage.extensionName}"`,
+          undefined,
+        ) as PostSaveHookFn; // @cast-boundary engine-bridge
         const existing = state.entityPostSaveHooks.get(usage.entityName) ?? [];
         existing.push({
-          fn: ext.hooks.postSave,
+          fn: wrapped,
           phase: HookPhases.afterCommit,
           featureName: extOwner,
         });
         state.entityPostSaveHooks.set(usage.entityName, existing);
       }
       if (ext.hooks.preDelete) {
+        const wrapped = bindHookIdentitySwitchGrant(
+          ext.hooks.preDelete,
+          `preDelete hook of extension "${usage.extensionName}"`,
+          undefined,
+        ) as PreDeleteHookFn; // @cast-boundary engine-bridge
         const existing = state.entityPreDeleteHooks.get(usage.entityName) ?? [];
         existing.push({
-          fn: ext.hooks.preDelete,
+          fn: wrapped,
           phase: HookPhases.afterCommit,
           featureName: extOwner,
         });
         state.entityPreDeleteHooks.set(usage.entityName, existing);
       }
       if (ext.hooks.postDelete) {
+        const wrapped = bindHookIdentitySwitchGrant(
+          ext.hooks.postDelete,
+          `postDelete hook of extension "${usage.extensionName}"`,
+          undefined,
+        ) as PostDeleteHookFn; // @cast-boundary engine-bridge
         const existing = state.entityPostDeleteHooks.get(usage.entityName) ?? [];
         existing.push({
-          fn: ext.hooks.postDelete,
+          fn: wrapped,
           phase: HookPhases.afterCommit,
           featureName: extOwner,
         });
@@ -145,11 +172,15 @@ export function applyExtensionUsages(state: RegistryState): void {
       }
       // preSave on extensions: store as handler hook for all CRUD handlers of this entity
       if (ext.hooks.preSave) {
-        // Find all write handlers that belong to this entity via state.handlerEntityMap
+        const wrapped = bindHookIdentitySwitchGrant(
+          ext.hooks.preSave,
+          `preSave hook of extension "${usage.extensionName}"`,
+          undefined,
+        ) as PreSaveHookFn; // @cast-boundary engine-bridge
         for (const qualifiedHandler of state.writeHandlerMap.keys()) {
           if (state.handlerEntityMap.get(qualifiedHandler) === usage.entityName) {
             const existing = state.preSaveHooks.get(qualifiedHandler) ?? [];
-            existing.push({ fn: ext.hooks.preSave, featureName: extOwner });
+            existing.push({ fn: wrapped, featureName: extOwner });
             state.preSaveHooks.set(qualifiedHandler, existing);
           }
         }

package/src/errors/i18n/de.yaml

@@ -84,6 +84,19 @@ feature_disabled:
     Aktiviere das Feature via Feature-Toggle oder Routing-Config (siehe
     [Feature-Toggles](/en/feature-reference/feature-toggles/)).
 
+system_identity_switch_denied:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: ein Handler oder Hook hat `ctx.queryAs`/`ctx.writeAs`
+    mit einer SYSTEM-Identität aufgerufen, ohne `r.systemScope()`-Handler, Job
+    zu sein oder `escapeHatch: { reason }` zu deklarieren.
+
+    Deklariere `escapeHatch: { reason: "..." }` am Write- oder Query-Handler
+    (oder am `r.hook(...)`-Aufruf, wenn der Wechsel in einem Hook passiert),
+    oder verlagere die Logik in ein `r.systemScope()`-Feature oder einen Job.
+
 agent.tool_not_allowed:
   endUser: |
     Dieses Tool ist im aktuellen Modus nicht verfügbar.

package/src/errors/i18n/en.yaml

@@ -81,6 +81,19 @@ feature_disabled:
     handler. Enable the feature via feature toggle or routing config (see
     [Feature Toggles](/en/feature-reference/feature-toggles/)).
 
+system_identity_switch_denied:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: a handler or hook called `ctx.queryAs`/`ctx.writeAs`
+    with a SYSTEM identity without being an `r.systemScope()` handler, a job,
+    or declaring `escapeHatch: { reason }`.
+
+    Declare `escapeHatch: { reason: "..." }` on the write or query handler
+    (or on the `r.hook(...)` call, if the switch happens inside a hook), or
+    move the logic into an `r.systemScope()` feature or a job.
+
 agent.tool_not_allowed:
   endUser: |
     This tool is not available in the current mode.

package/src/errors/reasons.ts

@@ -38,6 +38,10 @@ export const FrameworkReasons = {
   // Distinct from access-denied — clients should surface "feature X is
   // currently unavailable" not "you don't have permission".
   featureDisabled: "feature_disabled",
+
+  // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
+  // SYSTEM identity without an r.systemScope() feature or a declared escapeHatch.
+  systemIdentitySwitchDenied: "system_identity_switch_denied",
 } as const;
 
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];

package/src/jobs/__tests__/job-write-as.integration.test.ts

@@ -13,7 +13,13 @@ import { z } from "zod";
 import { ROLES } from "../../auth/roles";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
 import { asRawClient } from "../../db/query";
-import { createRegistry, defineFeature, type SessionUser, type WriteResult } from "../../engine";
+import {
+  createRegistry,
+  createSystemUser,
+  defineFeature,
+  type SessionUser,
+  type WriteResult,
+} from "../../engine";
 import { createWorkerEntrypoint } from "../../entrypoint";
 import { createArchivedStreamsTable, createEventsTable } from "../../event-store";
 import { createEventConsumerStateTable } from "../../pipeline";
@@ -28,6 +34,7 @@ type ProbeOutcome = { readonly isSuccess: boolean; readonly errorCode: string |
 const writeOutcomes: ProbeOutcome[] = [];
 const writeAsOutcomes: ProbeOutcome[] = [];
 const writeAsFailures: string[] = [];
+const jobQueryAsSystemResults: Array<{ readonly roles: readonly string[] }> = [];
 
 function recordOutcome(sink: ProbeOutcome[], result: WriteResult): void {
   sink.push({
@@ -57,6 +64,10 @@ const writeAsProbeFeature = defineFeature("writeAsProbe", (r) => {
     { access: { roles: [ROLES.TenantAdmin] } },
   );
 
+  r.queryHandler("whoami", z.object({}), async (query) => ({ roles: query.user.roles }), {
+    access: { roles: ["system"] },
+  });
+
   r.job("writeAsSystem", { trigger: { manual: true }, retries: 0 }, async (payload, ctx) => {
     const result = await ctx.write("write-as-probe:write:admin-note", {
       note: payload["note"] as string, // @cast-boundary dynamic-key
@@ -64,6 +75,16 @@ const writeAsProbeFeature = defineFeature("writeAsProbe", (r) => {
     recordOutcome(writeOutcomes, result);
   });
 
+  // fw#2859 — JobContext.queryAs stays UNgated by the SYSTEM identity-switch gate.
+  r.job("queryAsSystemWhoami", { trigger: { manual: true }, retries: 0 }, async (_payload, ctx) => {
+    const result = (await ctx.queryAs(
+      createSystemUser(ctx.systemUser.tenantId),
+      "write-as-probe:query:whoami",
+      {},
+    )) as { roles: readonly string[] }; // @cast-boundary engine-payload
+    jobQueryAsSystemResults.push(result);
+  });
+
   r.job("writeAsActor", { trigger: { manual: true }, retries: 0 }, async (payload, ctx) => {
     const actor: SessionUser = {
       id: payload["actorId"] as string, // @cast-boundary dynamic-key
@@ -204,3 +225,28 @@ describe("JobContext.writeAs before attachDispatcher()", () => {
     }
   });
 });
+
+describe("JobContext.queryAs stays ungated by the SYSTEM identity-switch gate (framework#2859)", () => {
+  test("ctx.queryAs(createSystemUser(...), whoami) succeeds from inside a job", async () => {
+    jobQueryAsSystemResults.length = 0;
+    const worker = createWorkerEntrypoint({
+      registry: createRegistry([writeAsProbeFeature]),
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl: redisUrl(),
+      queueNamePrefix: uniquePrefix("job-query-as-system"),
+    });
+
+    await worker.start();
+    try {
+      await worker.jobRunner.dispatch("write-as-probe:job:query-as-system-whoami", {});
+
+      await waitFor(() => {
+        expect(jobQueryAsSystemResults.length).toBe(1);
+      });
+      expect(jobQueryAsSystemResults[0]?.roles).toContain("system");
+    } finally {
+      await worker.stop();
+    }
+  });
+});

package/src/pipeline/__tests__/ctx-bridge.integration.test.ts

@@ -135,7 +135,10 @@ const bridgeFeature = defineFeature("ctxbridge", (r) => {
 
       return created;
     },
-    { access: { roles: ["Admin"] } },
+    {
+      access: { roles: ["Admin"] },
+      escapeHatch: { reason: "test fixture: writeAs(SYSTEM) creates the secret for the caller" },
+    },
   );
 
   // Two inserts, one via ctx.db (tx-bound) and one via ctx.dbOutsideTransaction
@@ -168,7 +171,10 @@ const bridgeFeature = defineFeature("ctxbridge", (r) => {
         owner: query.payload.owner,
       });
     },
-    { access: { roles: ["Admin"] } },
+    {
+      access: { roles: ["Admin"] },
+      escapeHatch: { reason: "test fixture: queryAs(SYSTEM) reads the privileged token field" },
+    },
   );
 
   // Records whether ctx.db threw (should, once the request signal is

package/src/pipeline/__tests__/system-identity-switch.integration.test.ts

@@ -0,0 +1,352 @@
+// fw#2859 — ctx.queryAs/ctx.writeAs to SYSTEM needs r.systemScope() or { escapeHatch }; a
+// non-SYSTEM switch is ungated. Real HTTP calls + setupTestStack — never createTestDispatcher.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildEntityTable } from "../../db/table-builder";
+import {
+  createEntity,
+  createSystemUser,
+  createTextField,
+  defineFeature,
+  HookPhases,
+} from "../../engine";
+import type { HandlerContext, SessionUser } from "../../engine/types";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "../../stack";
+
+const user = TestUsers.user;
+const otherUserNoRole: SessionUser = createTestUser({
+  id: 50,
+  tenantId: user.tenantId,
+  roles: ["User"],
+});
+const otherUserWithAdminRole: SessionUser = createTestUser({
+  id: 51,
+  tenantId: user.tenantId,
+  roles: ["Admin"],
+});
+
+const hookThingEntity = createEntity({
+  table: "idswitch_hook_things",
+  fields: {
+    label: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+const hookThingTable = buildEntityTable("hookThing", hookThingEntity);
+const hookThingExecutor = createEventStoreExecutor(hookThingTable, hookThingEntity, {
+  entityName: "hookThing",
+});
+
+const hookNoEscapeHatchOutcomes: Array<{ readonly threw: boolean }> = [];
+const hookWithEscapeHatchOutcomes: Array<{ readonly ok: boolean }> = [];
+
+const probeFeature = defineFeature("idswitch-probe", (r) => {
+  r.entity("hookThing", hookThingEntity);
+
+  // --- Targets ---
+  r.queryHandler(
+    "whoami",
+    z.object({}),
+    async (query) => ({
+      roles: query.user.roles,
+      tenantId: query.user.tenantId,
+    }),
+    { access: { roles: ["system", "User"] } },
+  );
+
+  r.writeHandler(
+    "whoami-write",
+    z.object({}),
+    async (event) => ({
+      isSuccess: true as const,
+      data: { roles: event.user.roles, tenantId: event.user.tenantId },
+    }),
+    { access: { roles: ["system", "User"] } },
+  );
+
+  r.queryHandler("admin-only", z.object({}), async () => ({ ok: true }), {
+    access: { roles: ["Admin"] },
+  });
+
+  // --- Direct SYSTEM switch: gated by the CALLING handler's own escapeHatch ---
+  r.writeHandler(
+    "write-as-system-no-hatch",
+    z.object({}),
+    async (event, ctx) =>
+      ctx.writeAs(createSystemUser(event.user.tenantId), "idswitch-probe:write:whoami-write", {}),
+    { access: { roles: ["User"] } },
+  );
+
+  r.writeHandler(
+    "write-as-system-with-hatch",
+    z.object({}),
+    async (event, ctx) =>
+      ctx.writeAs(createSystemUser(event.user.tenantId), "idswitch-probe:write:whoami-write", {}),
+    {
+      access: { roles: ["User"] },
+      escapeHatch: { reason: "test: needs SYSTEM to look itself up" },
+    },
+  );
+
+  r.queryHandler(
+    "query-as-system-no-hatch",
+    z.object({}),
+    async (query, ctx) =>
+      ctx.queryAs(createSystemUser(query.user.tenantId), "idswitch-probe:query:whoami", {}),
+    { access: { roles: ["User"] } },
+  );
+
+  r.queryHandler(
+    "query-as-system-with-hatch",
+    z.object({}),
+    async (query, ctx) =>
+      ctx.queryAs(createSystemUser(query.user.tenantId), "idswitch-probe:query:whoami", {}),
+    {
+      access: { roles: ["User"] },
+      escapeHatch: { reason: "test: needs SYSTEM to look itself up" },
+    },
+  );
+
+  // --- Non-SYSTEM switch: never gated by this feature, only the target's own access rule ---
+  r.queryHandler(
+    "query-as-normal-user",
+    z.object({ granted: z.boolean() }),
+    async (query, ctx) =>
+      ctx.queryAs(
+        query.payload.granted ? otherUserWithAdminRole : otherUserNoRole,
+        "idswitch-probe:query:admin-only",
+        {},
+      ),
+    { access: { roles: ["User"] } },
+  );
+
+  // --- Nested: no transitive grant ---
+  r.writeHandler(
+    "inner-no-hatch",
+    z.object({}),
+    async (event, ctx) =>
+      ctx.writeAs(createSystemUser(event.user.tenantId), "idswitch-probe:write:whoami-write", {}),
+    { access: { roles: ["system"] } },
+  );
+
+  r.writeHandler(
+    "inner-with-hatch",
+    z.object({}),
+    async (event, ctx) =>
+      ctx.writeAs(createSystemUser(event.user.tenantId), "idswitch-probe:write:whoami-write", {}),
+    { access: { roles: ["system"] }, escapeHatch: { reason: "test: inner needs SYSTEM" } },
+  );
+
+  r.writeHandler(
+    "outer-with-hatch",
+    z.object({ innerHasHatch: z.boolean() }),
+    async (event, ctx) =>
+      ctx.writeAs(
+        createSystemUser(event.user.tenantId),
+        event.payload.innerHasHatch
+          ? "idswitch-probe:write:inner-with-hatch"
+          : "idswitch-probe:write:inner-no-hatch",
+        {},
+      ),
+    { access: { roles: ["User"] }, escapeHatch: { reason: "test: outer needs SYSTEM" } },
+  );
+
+  // --- Hooks: gated independently of the handler they fire on ---
+  r.writeHandler(
+    "hook-target-with-hatch",
+    z.object({ label: z.string() }),
+    async (event, ctx) => hookThingExecutor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["User"] }, escapeHatch: { reason: "test: handler needs SYSTEM" } },
+  );
+
+  r.writeHandler(
+    "hook-target-without-hatch",
+    z.object({ label: z.string() }),
+    async (event, ctx) => hookThingExecutor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["User"] } },
+  );
+
+  // Hook on the WITH-hatch handler, but the hook itself declares NO
+  // escapeHatch — must NOT inherit the handler's grant.
+  r.hook(
+    "postSave",
+    "hook-target-with-hatch",
+    async (_result, ctx) => {
+      const handlerCtx = ctx as unknown as HandlerContext;
+      try {
+        await handlerCtx.writeAs(
+          createSystemUser(user.tenantId),
+          "idswitch-probe:write:whoami-write",
+          {},
+        );
+        hookNoEscapeHatchOutcomes.push({ threw: false });
+      } catch (err) {
+        hookNoEscapeHatchOutcomes.push({ threw: true });
+        throw err;
+      }
+    },
+    { phase: HookPhases.inTransaction },
+  );
+
+  // Hook on the WITHOUT-hatch handler, but the hook itself DOES declare
+  // escapeHatch — must reach SYSTEM even though the handler can't.
+  r.hook(
+    "postSave",
+    "hook-target-without-hatch",
+    async (_result, ctx) => {
+      const handlerCtx = ctx as unknown as HandlerContext;
+      const res = await handlerCtx.writeAs(
+        createSystemUser(user.tenantId),
+        "idswitch-probe:write:whoami-write",
+        {},
+      );
+      hookWithEscapeHatchOutcomes.push({ ok: res.isSuccess });
+    },
+    { phase: HookPhases.inTransaction, escapeHatch: { reason: "test: hook needs SYSTEM" } },
+  );
+});
+
+const systemScopeFeature = defineFeature("idswitch-probe-system", (r) => {
+  r.systemScope();
+
+  r.writeHandler(
+    "write-as-system",
+    z.object({}),
+    async (event, ctx) =>
+      ctx.writeAs(createSystemUser(event.user.tenantId), "idswitch-probe:write:whoami-write", {}),
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [probeFeature, systemScopeFeature] });
+  await unsafeCreateEntityTable(stack.db, hookThingEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("ctx.writeAs(SYSTEM, ...) — gated by the calling handler's escapeHatch", () => {
+  test("WITHOUT escapeHatch: fails with access_denied", async () => {
+    const err = await stack.http.writeErr(
+      "idswitch-probe:write:write-as-system-no-hatch",
+      {},
+      user,
+    );
+    expect(err.code).toBe("access_denied");
+  });
+
+  test("WITH escapeHatch: succeeds", async () => {
+    const result = await stack.http.writeOk<{ roles: readonly string[] }>(
+      "idswitch-probe:write:write-as-system-with-hatch",
+      {},
+      user,
+    );
+    expect(result.roles).toContain("system");
+  });
+});
+
+describe("ctx.queryAs(SYSTEM, ...) — gated by the calling handler's escapeHatch", () => {
+  test("WITHOUT escapeHatch: fails with access_denied", async () => {
+    const err = await stack.http.queryErr(
+      "idswitch-probe:query:query-as-system-no-hatch",
+      {},
+      user,
+    );
+    expect(err.code).toBe("access_denied");
+  });
+
+  test("WITH escapeHatch: succeeds", async () => {
+    const result = await stack.http.queryOk<{ roles: readonly string[] }>(
+      "idswitch-probe:query:query-as-system-with-hatch",
+      {},
+      user,
+    );
+    expect(result.roles).toContain("system");
+  });
+});
+
+describe("ctx.queryAs(nonSystemUser, ...) — never gated by this feature", () => {
+  test("delegates to the target's own access check: denied when the target user lacks the role", async () => {
+    const err = await stack.http.queryErr(
+      "idswitch-probe:query:query-as-normal-user",
+      { granted: false },
+      user,
+    );
+    expect(err.code).toBe("access_denied");
+  });
+
+  test("delegates to the target's own access check: allowed when the target user has the role", async () => {
+    const result = await stack.http.queryOk<{ ok: boolean }>(
+      "idswitch-probe:query:query-as-normal-user",
+      { granted: true },
+      user,
+    );
+    expect(result.ok).toBe(true);
+  });
+});
+
+describe("r.systemScope() feature — no escapeHatch needed", () => {
+  test("writeAs(SYSTEM) succeeds from a systemScope handler", async () => {
+    const result = await stack.http.writeOk<{ roles: readonly string[] }>(
+      "idswitch-probe-system:write:write-as-system",
+      {},
+      TestUsers.admin,
+    );
+    expect(result.roles).toContain("system");
+  });
+});
+
+describe("nested identity switches — no transitive grant", () => {
+  test("outer-with-hatch -> inner-no-hatch -> target: overall fails with access_denied", async () => {
+    const err = await stack.http.writeErr(
+      "idswitch-probe:write:outer-with-hatch",
+      { innerHasHatch: false },
+      user,
+    );
+    expect(err.code).toBe("access_denied");
+  });
+
+  test("outer-with-hatch -> inner-with-hatch -> target: succeeds (control)", async () => {
+    const result = await stack.http.writeOk<{ roles: readonly string[] }>(
+      "idswitch-probe:write:outer-with-hatch",
+      { innerHasHatch: true },
+      user,
+    );
+    expect(result.roles).toContain("system");
+  });
+});
+
+describe("hooks are gated independently of the handler they fire on", () => {
+  test("hook WITHOUT escapeHatch does not inherit the handler's grant: overall write fails", async () => {
+    hookNoEscapeHatchOutcomes.length = 0;
+    const err = await stack.http.writeErr(
+      "idswitch-probe:write:hook-target-with-hatch",
+      { label: "should-roll-back" },
+      user,
+    );
+    expect(err.code).toBe("access_denied");
+    expect(hookNoEscapeHatchOutcomes).toEqual([{ threw: true }]);
+  });
+
+  test("hook WITH escapeHatch reaches SYSTEM even when the handler itself has none", async () => {
+    hookWithEscapeHatchOutcomes.length = 0;
+    const result = await stack.http.writeOk<{ id: string }>(
+      "idswitch-probe:write:hook-target-without-hatch",
+      { label: "should-commit" },
+      user,
+    );
+    expect(result.id).toBeDefined();
+    expect(hookWithEscapeHatchOutcomes).toEqual([{ ok: true }]);
+  });
+});