@cosmicdrift/kumiko-framework 0.262.0 → 0.264.0

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

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

@@ -0,0 +1,195 @@
+import { describe, expect, mock, test } from "bun:test";
+import { createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID } from "../../engine";
+import type { SessionUser } from "../../engine/types";
+import type { TenantId } from "../../engine/types/identifiers";
+import { AccessDeniedError, FrameworkReasons } from "../../errors";
+import {
+  createGatedIdentitySwitch,
+  type IdentitySwitch,
+  isSystemIdentity,
+  isSystemIdentitySwitchAllowed,
+  withHookIdentitySwitchGrant,
+} from "../system-identity-switch";
+
+const TENANT = "00000000-0000-4000-8000-00000000ab01" as TenantId;
+
+const normalUser: SessionUser = { id: crypto.randomUUID(), tenantId: TENANT, roles: ["User"] };
+const systemUserById: SessionUser = { id: SYSTEM_USER_ID, tenantId: TENANT, roles: ["User"] };
+const systemUserByRole: SessionUser = {
+  id: crypto.randomUUID(),
+  tenantId: TENANT,
+  roles: [SYSTEM_ROLE],
+};
+
+function makeUngated(): {
+  readonly ungated: IdentitySwitch;
+  readonly queryAsMock: ReturnType<typeof mock>;
+  readonly writeAsMock: ReturnType<typeof mock>;
+} {
+  const queryAsMock = mock(async (_user: SessionUser, _qn: string, _payload: unknown) => ({
+    ok: true,
+  }));
+  const writeAsMock = mock(async (_user: SessionUser, _qn: string, _payload: unknown) => ({
+    isSuccess: true as const,
+    data: { ok: true },
+  }));
+  return {
+    ungated: { queryAs: queryAsMock, writeAs: writeAsMock },
+    queryAsMock,
+    writeAsMock,
+  };
+}
+
+describe("isSystemIdentity", () => {
+  test("SYSTEM_USER_ID alone counts as SYSTEM", () => {
+    expect(isSystemIdentity(systemUserById)).toBe(true);
+  });
+
+  test("SYSTEM_ROLE alone counts as SYSTEM", () => {
+    expect(isSystemIdentity(systemUserByRole)).toBe(true);
+  });
+
+  test("a normal user is not SYSTEM", () => {
+    expect(isSystemIdentity(normalUser)).toBe(false);
+  });
+
+  test("createSystemUser(...) is SYSTEM", () => {
+    expect(isSystemIdentity(createSystemUser(TENANT))).toBe(true);
+  });
+});
+
+describe("isSystemIdentitySwitchAllowed", () => {
+  test("SYSTEM target requires allowSystemIdentity=true", () => {
+    expect(isSystemIdentitySwitchAllowed(systemUserById, false)).toBe(false);
+    expect(isSystemIdentitySwitchAllowed(systemUserById, true)).toBe(true);
+  });
+
+  test("a non-SYSTEM target is always allowed", () => {
+    expect(isSystemIdentitySwitchAllowed(normalUser, false)).toBe(true);
+    expect(isSystemIdentitySwitchAllowed(normalUser, true)).toBe(true);
+  });
+});
+
+describe("createGatedIdentitySwitch", () => {
+  test("queryAs to SYSTEM throws AccessDeniedError with the reason code, no asUser/tenantId/payload leak", async () => {
+    const { ungated } = makeUngated();
+    const gated = createGatedIdentitySwitch('handler "x"', false, ungated);
+
+    let caught: unknown;
+    try {
+      await gated.queryAs(systemUserById, "some:target", { secret: "payload-value" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    const error = caught as AccessDeniedError;
+    expect(error.details).toEqual({ reason: FrameworkReasons.systemIdentitySwitchDenied });
+    expect(error.message).not.toContain(systemUserById.id);
+    expect(error.message).not.toContain(TENANT);
+    expect(error.message).not.toContain("payload-value");
+  });
+
+  test("writeAs to SYSTEM throws the same way (never falls back to a WriteResult failure)", async () => {
+    const { ungated } = makeUngated();
+    const gated = createGatedIdentitySwitch('handler "x"', false, ungated);
+
+    await expect(gated.writeAs(systemUserById, "some:target", {})).rejects.toBeInstanceOf(
+      AccessDeniedError,
+    );
+  });
+
+  test("allowSystemIdentity=true lets a SYSTEM switch pass through to the ungated pair", async () => {
+    const { ungated, queryAsMock, writeAsMock } = makeUngated();
+    const gated = createGatedIdentitySwitch('handler "x"', true, ungated);
+
+    await gated.queryAs(systemUserById, "q", { a: 1 });
+    await gated.writeAs(systemUserById, "w", { b: 2 });
+
+    expect(queryAsMock).toHaveBeenCalledWith(systemUserById, "q", { a: 1 });
+    expect(writeAsMock).toHaveBeenCalledWith(systemUserById, "w", { b: 2 });
+  });
+
+  test("a non-system asUser always passes through, regardless of allowSystemIdentity", async () => {
+    const { ungated, queryAsMock } = makeUngated();
+    const deniedByDefault = createGatedIdentitySwitch('handler "x"', false, ungated);
+
+    await deniedByDefault.queryAs(normalUser, "q", {});
+
+    expect(queryAsMock).toHaveBeenCalledWith(normalUser, "q", {});
+  });
+});
+
+describe("withHookIdentitySwitchGrant", () => {
+  test("hook without escapeHatch does NOT inherit the handler's SYSTEM grant", async () => {
+    const { ungated } = makeUngated();
+    // Simulates dispatch-shared.ts's buildHandlerContext for a handler that
+    // itself declared escapeHatch / is systemScope (allowSystemIdentity=true).
+    const handlerCtx = { ...createGatedIdentitySwitch('handler "outer"', true, ungated) };
+
+    const hookCtx = withHookIdentitySwitchGrant(
+      handlerCtx,
+      'postSave hook of feature "f"',
+      undefined,
+    );
+
+    await expect(hookCtx.queryAs(systemUserById, "q", {})).rejects.toBeInstanceOf(
+      AccessDeniedError,
+    );
+  });
+
+  test("hook WITH escapeHatch is allowed even when the handler's own grant was false", async () => {
+    const { ungated, queryAsMock } = makeUngated();
+    // Handler itself has NO escapeHatch (allowSystemIdentity=false).
+    const handlerCtx = { ...createGatedIdentitySwitch('handler "outer"', false, ungated) };
+
+    const hookCtx = withHookIdentitySwitchGrant(handlerCtx, 'postSave hook of feature "f"', {
+      reason: "test hook needs SYSTEM",
+    });
+
+    await hookCtx.queryAs(systemUserById, "q", { a: 1 });
+    // Reaches the REAL ungated fn — not the handler's own (still-denying) gate.
+    expect(queryAsMock).toHaveBeenCalledWith(systemUserById, "q", { a: 1 });
+  });
+
+  test("a non-system asUser is always allowed through the hook's own gate", async () => {
+    const { ungated, queryAsMock } = makeUngated();
+    const handlerCtx = { ...createGatedIdentitySwitch('handler "outer"', false, ungated) };
+    const hookCtx = withHookIdentitySwitchGrant(handlerCtx, "hook", undefined);
+
+    await hookCtx.queryAs(normalUser, "q", {});
+    expect(queryAsMock).toHaveBeenCalledWith(normalUser, "q", {});
+  });
+
+  test("spreading the context ({...ctx}) still resolves back to the ungated pair", async () => {
+    const { ungated, queryAsMock } = makeUngated();
+    const handlerCtx = { ...createGatedIdentitySwitch('handler "outer"', true, ungated), extra: 1 };
+    const spread = { ...handlerCtx };
+
+    const hookCtx = withHookIdentitySwitchGrant(spread, "hook", { reason: "needs system" });
+    await hookCtx.queryAs(systemUserById, "q", {});
+
+    expect(queryAsMock).toHaveBeenCalledWith(systemUserById, "q", {});
+  });
+
+  test("a context without queryAs/writeAs is returned unchanged", () => {
+    const plainContext = { db: {} };
+    const result = withHookIdentitySwitchGrant(plainContext, "hook", { reason: "x" });
+    expect(result).toBe(plainContext);
+  });
+
+  test("an ungated context not built by the dispatcher bridge fails closed (unit-test stub)", async () => {
+    const stubQueryAs = mock(async (_user: SessionUser, _qn: string, _payload: unknown) => "ok");
+    const stubContext = { queryAs: stubQueryAs };
+
+    const hookCtx = withHookIdentitySwitchGrant(stubContext, "hook", undefined);
+    await expect(hookCtx.queryAs(systemUserById, "q", {})).rejects.toBeInstanceOf(
+      AccessDeniedError,
+    );
+    expect(stubQueryAs).not.toHaveBeenCalled();
+
+    const allowedHookCtx = withHookIdentitySwitchGrant(stubContext, "hook", { reason: "x" });
+    await allowedHookCtx.queryAs(systemUserById, "q", {});
+    expect(stubQueryAs).toHaveBeenCalledWith(systemUserById, "q", {});
+  });
+});