@cosmicdrift/kumiko-framework 0.266.0 → 0.269.0

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

@@ -1,5 +1,5 @@
-// 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.
+// fw#2859/#2876 — ctx.queryAs/ctx.writeAs to anyone but the caller itself (or a role subset) needs
+// r.systemScope() or { escapeHatch }. Real HTTP calls + setupTestStack — never createTestDispatcher.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { z } from "zod";
@@ -33,6 +33,21 @@ const otherUserWithAdminRole: SessionUser = createTestUser({
   roles: ["Admin"],
 });
 
+const multiRoleUser: SessionUser = createTestUser({
+  id: 52,
+  tenantId: user.tenantId,
+  roles: ["User", "Editor"],
+});
+
+function foreignTenantTwin(caller: SessionUser): SessionUser {
+  return { ...caller, tenantId: TestUsers.otherTenant.tenantId };
+}
+
+function errorReason(details: unknown): string | undefined {
+  if (!details || typeof details !== "object" || !("reason" in details)) return undefined;
+  return typeof details.reason === "string" ? details.reason : undefined;
+}
+
 const hookThingEntity = createEntity({
   table: "idswitch_hook_things",
   fields: {
@@ -46,6 +61,7 @@ const hookThingExecutor = createEventStoreExecutor(hookThingTable, hookThingEnti
 
 const hookNoEscapeHatchOutcomes: Array<{ readonly threw: boolean }> = [];
 const hookWithEscapeHatchOutcomes: Array<{ readonly ok: boolean }> = [];
+const hookForeignNoEscapeHatchOutcomes: Array<{ readonly threw: boolean }> = [];
 
 const probeFeature = defineFeature("idswitch-probe", (r) => {
   r.entity("hookThing", hookThingEntity);
@@ -132,9 +148,29 @@ const probeFeature = defineFeature("idswitch-probe", (r) => {
     },
   );
 
-  // --- Non-SYSTEM switch: never gated by this feature, only the target's own access rule ---
+  // --- Non-SYSTEM switch (fw#2876): only the caller itself (or a role subset) is free ---
+  r.queryHandler(
+    "query-as-self",
+    z.object({ roles: z.array(z.string()).optional() }),
+    async (query, ctx) =>
+      ctx.queryAs(
+        query.payload.roles ? { ...query.user, roles: query.payload.roles } : query.user,
+        "idswitch-probe:query:whoami",
+        {},
+      ),
+    { access: { roles: ["User"] } },
+  );
+
   r.queryHandler(
     "query-as-normal-user",
+    z.object({}),
+    async (_query, ctx) =>
+      ctx.queryAs(otherUserWithAdminRole, "idswitch-probe:query:admin-only", {}),
+    { access: { roles: ["User"] } },
+  );
+
+  r.queryHandler(
+    "query-as-normal-user-with-hatch",
     z.object({ granted: z.boolean() }),
     async (query, ctx) =>
       ctx.queryAs(
@@ -142,9 +178,48 @@ const probeFeature = defineFeature("idswitch-probe", (r) => {
         "idswitch-probe:query:admin-only",
         {},
       ),
+    {
+      access: { roles: ["User"] },
+      escapeHatch: { reason: "test: reads admin-only data as a named colleague" },
+    },
+  );
+
+  r.writeHandler(
+    "write-as-foreign-tenant",
+    z.object({}),
+    async (event, ctx) =>
+      ctx.writeAs(foreignTenantTwin(event.user), "idswitch-probe:write:whoami-write", {}),
     { access: { roles: ["User"] } },
   );
 
+  r.writeHandler(
+    "write-as-foreign-tenant-with-hatch",
+    z.object({}),
+    async (event, ctx) =>
+      ctx.writeAs(foreignTenantTwin(event.user), "idswitch-probe:write:whoami-write", {}),
+    {
+      access: { roles: ["User"] },
+      escapeHatch: { reason: "test: acts for the same user inside a second tenant" },
+    },
+  );
+
+  // Reached through outer-with-hatch as a colleague — must not inherit the outer grant.
+  r.writeHandler(
+    "inner-foreign-no-hatch",
+    z.object({}),
+    async (event, ctx) =>
+      ctx.writeAs(foreignTenantTwin(event.user), "idswitch-probe:write:whoami-write", {}),
+    { access: { roles: ["User"] } },
+  );
+
+  r.writeHandler(
+    "outer-as-colleague-with-hatch",
+    z.object({}),
+    async (_event, ctx) =>
+      ctx.writeAs(otherUserNoRole, "idswitch-probe:write:inner-foreign-no-hatch", {}),
+    { access: { roles: ["User"] }, escapeHatch: { reason: "test: outer acts as a colleague" } },
+  );
+
   // --- Nested: no transitive grant ---
   r.writeHandler(
     "inner-no-hatch",
@@ -229,6 +304,29 @@ const probeFeature = defineFeature("idswitch-probe", (r) => {
     },
     { phase: HookPhases.inTransaction, escapeHatch: { reason: "test: hook needs SYSTEM" } },
   );
+
+  r.writeHandler(
+    "hook-foreign-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 acts cross-tenant" } },
+  );
+
+  r.hook(
+    "postSave",
+    "hook-foreign-target-with-hatch",
+    async (_result, ctx) => {
+      const handlerCtx = ctx as unknown as HandlerContext;
+      try {
+        await handlerCtx.writeAs(foreignTenantTwin(user), "idswitch-probe:write:whoami-write", {});
+        hookForeignNoEscapeHatchOutcomes.push({ threw: false });
+      } catch (err) {
+        hookForeignNoEscapeHatchOutcomes.push({ threw: true });
+        throw err;
+      }
+    },
+    { phase: HookPhases.inTransaction },
+  );
 });
 
 const systemScopeFeature = defineFeature("idswitch-probe-system", (r) => {
@@ -241,6 +339,18 @@ const systemScopeFeature = defineFeature("idswitch-probe-system", (r) => {
       ctx.writeAs(createSystemUser(event.user.tenantId), "idswitch-probe:write:whoami-write", {}),
     { access: { roles: ["Admin"] } },
   );
+
+  r.writeHandler(
+    "write-as-foreign-tenant",
+    z.object({}),
+    async (event, ctx) =>
+      ctx.writeAs(
+        { ...foreignTenantTwin(event.user), roles: ["User"] },
+        "idswitch-probe:write:whoami-write",
+        {},
+      ),
+    { access: { roles: ["Admin"] } },
+  );
 });
 
 let stack: TestStack;
@@ -314,27 +424,110 @@ describe("ctx.resolveActiveMembership — gated like a SYSTEM queryAs/writeAs",
   });
 });
 
-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 () => {
+describe("ctx.queryAs/writeAs to a non-SYSTEM identity (fw#2876)", () => {
+  test("switching to the caller itself is free", async () => {
+    const result = await stack.http.queryOk<{ roles: readonly string[]; tenantId: string }>(
+      "idswitch-probe:query:query-as-self",
+      {},
+      multiRoleUser,
+    );
+    expect(result.roles).toEqual(["User", "Editor"]);
+    expect(result.tenantId).toBe(multiRoleUser.tenantId);
+  });
+
+  test("a subset of the caller's roles is free", async () => {
+    const result = await stack.http.queryOk<{ roles: readonly string[] }>(
+      "idswitch-probe:query:query-as-self",
+      { roles: ["User"] },
+      multiRoleUser,
+    );
+    expect(result.roles).toEqual(["User"]);
+  });
+
+  test("an additional role without escapeHatch is denied", async () => {
     const err = await stack.http.queryErr(
-      "idswitch-probe:query:query-as-normal-user",
+      "idswitch-probe:query:query-as-self",
+      { roles: ["User", "Admin"] },
+      multiRoleUser,
+    );
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("identity_switch_denied");
+  });
+
+  test("a foreign user id without escapeHatch is denied, even when that user could read the target", async () => {
+    const err = await stack.http.queryErr("idswitch-probe:query:query-as-normal-user", {}, user);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("identity_switch_denied");
+  });
+
+  test("writeAs with a foreign tenantId without escapeHatch answers 403 access_denied", async () => {
+    const err = await stack.http.writeErr("idswitch-probe:write:write-as-foreign-tenant", {}, user);
+    expect(err.httpStatus).toBe(403);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("identity_switch_denied");
+    expect(JSON.stringify(err)).not.toContain(TestUsers.otherTenant.tenantId);
+  });
+
+  test("writeAs with a foreign tenantId WITH escapeHatch runs in that tenant", async () => {
+    const result = await stack.http.writeOk<{ tenantId: string }>(
+      "idswitch-probe:write:write-as-foreign-tenant-with-hatch",
+      {},
+      user,
+    );
+    expect(result.tenantId).toBe(TestUsers.otherTenant.tenantId);
+  });
+
+  test("WITH escapeHatch the target's own access check still applies: denied when the target user lacks the role", async () => {
+    const err = await stack.http.queryErr(
+      "idswitch-probe:query:query-as-normal-user-with-hatch",
       { granted: false },
       user,
     );
     expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).not.toBe("identity_switch_denied");
   });
 
-  test("delegates to the target's own access check: allowed when the target user has the role", async () => {
+  test("WITH escapeHatch: allowed when the target user has the role", async () => {
     const result = await stack.http.queryOk<{ ok: boolean }>(
-      "idswitch-probe:query:query-as-normal-user",
+      "idswitch-probe:query:query-as-normal-user-with-hatch",
       { granted: true },
       user,
     );
     expect(result.ok).toBe(true);
   });
+
+  test("no transitive grant: outer-with-hatch -> colleague -> inner-no-hatch cross-tenant writeAs is denied", async () => {
+    const err = await stack.http.writeErr(
+      "idswitch-probe:write:outer-as-colleague-with-hatch",
+      {},
+      user,
+    );
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("identity_switch_denied");
+  });
+
+  test("hook without escapeHatch does not inherit the handler's grant for a cross-tenant writeAs", async () => {
+    hookForeignNoEscapeHatchOutcomes.length = 0;
+    const err = await stack.http.writeErr(
+      "idswitch-probe:write:hook-foreign-target-with-hatch",
+      { label: "should-roll-back" },
+      user,
+    );
+    expect(err.code).toBe("access_denied");
+    expect(hookForeignNoEscapeHatchOutcomes).toEqual([{ threw: true }]);
+  });
 });
 
 describe("r.systemScope() feature — no escapeHatch needed", () => {
+  test("writeAs with a foreign tenantId succeeds from a systemScope handler", async () => {
+    const result = await stack.http.writeOk<{ tenantId: string }>(
+      "idswitch-probe-system:write:write-as-foreign-tenant",
+      {},
+      TestUsers.admin,
+    );
+    expect(result.tenantId).toBe(TestUsers.otherTenant.tenantId);
+  });
+
   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",

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

@@ -1,4 +1,6 @@
 import { describe, expect, mock, test } from "bun:test";
+import type { DbRunner } from "../../db/connection";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
 import { createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID } from "../../engine";
 import type { SessionUser } from "../../engine/types";
 import type { TenantId } from "../../engine/types/identifiers";
@@ -6,9 +8,10 @@ import { AccessDeniedError, FrameworkReasons } from "../../errors";
 import {
   createGatedIdentitySwitch,
   type IdentitySwitch,
+  isIdentitySwitchAllowed,
   isSystemIdentity,
-  isSystemIdentitySwitchAllowed,
-  withHookIdentitySwitchGrant,
+  type WriteAsFn,
+  withHookEscapeHatchGrant,
 } from "../system-identity-switch";
 
 const TENANT = "00000000-0000-4000-8000-00000000ab01" as TenantId;
@@ -58,22 +61,89 @@ describe("isSystemIdentity", () => {
   });
 });
 
-describe("isSystemIdentitySwitchAllowed", () => {
-  test("SYSTEM target requires allowSystemIdentity=true", () => {
-    expect(isSystemIdentitySwitchAllowed(systemUserById, false)).toBe(false);
-    expect(isSystemIdentitySwitchAllowed(systemUserById, true)).toBe(true);
+const OTHER_TENANT = "00000000-0000-4000-8000-00000000ab02" as TenantId;
+const multiRoleCaller: SessionUser = {
+  id: crypto.randomUUID(),
+  tenantId: TENANT,
+  roles: ["User", "Editor"],
+  claims: { "teams:teamId": "team-1" },
+  sid: "session-1",
+};
+
+describe("isIdentitySwitchAllowed", () => {
+  test("SYSTEM target requires a grant, even when the caller is SYSTEM itself", () => {
+    expect(isIdentitySwitchAllowed(normalUser, systemUserById, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(systemUserById, systemUserById, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(normalUser, systemUserByRole, true)).toBe(true);
+  });
+
+  test("switching to the caller itself is free", () => {
+    expect(isIdentitySwitchAllowed(multiRoleCaller, multiRoleCaller, false)).toBe(true);
+    expect(isIdentitySwitchAllowed(multiRoleCaller, { ...multiRoleCaller }, false)).toBe(true);
+  });
+
+  test("a subset of the caller's roles is free; sid/locale may differ", () => {
+    const narrowed: SessionUser = {
+      ...multiRoleCaller,
+      roles: ["User"],
+      claims: { "teams:teamId": "team-1" },
+      sid: undefined,
+      locale: "de",
+    };
+    expect(isIdentitySwitchAllowed(multiRoleCaller, narrowed, false)).toBe(true);
+    expect(isIdentitySwitchAllowed(multiRoleCaller, { ...multiRoleCaller, roles: [] }, false)).toBe(
+      true,
+    );
+  });
+
+  test("an additional role without a grant is denied", () => {
+    const escalated: SessionUser = { ...multiRoleCaller, roles: ["User", "TenantAdmin"] };
+    expect(isIdentitySwitchAllowed(multiRoleCaller, escalated, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(multiRoleCaller, escalated, true)).toBe(true);
+  });
+
+  test("the same id in a foreign tenant without a grant is denied, even with a role subset", () => {
+    const foreignTenant: SessionUser = { ...multiRoleCaller, tenantId: OTHER_TENANT, roles: [] };
+    expect(isIdentitySwitchAllowed(multiRoleCaller, foreignTenant, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(multiRoleCaller, foreignTenant, true)).toBe(true);
+  });
+
+  test("a foreign id in the same tenant without a grant is denied, even with a role subset", () => {
+    const foreignUser: SessionUser = {
+      ...multiRoleCaller,
+      id: crypto.randomUUID(),
+      roles: ["User"],
+    };
+    expect(isIdentitySwitchAllowed(multiRoleCaller, foreignUser, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(multiRoleCaller, foreignUser, true)).toBe(true);
   });
 
-  test("a non-SYSTEM target is always allowed", () => {
-    expect(isSystemIdentitySwitchAllowed(normalUser, false)).toBe(true);
-    expect(isSystemIdentitySwitchAllowed(normalUser, true)).toBe(true);
+  test("changed claims or origin without a grant are denied", () => {
+    const forgedClaim: SessionUser = { ...multiRoleCaller, claims: { "teams:teamId": "team-2" } };
+    const droppedClaims: SessionUser = { ...multiRoleCaller, claims: undefined };
+    const extraClaim: SessionUser = {
+      ...multiRoleCaller,
+      claims: { "teams:teamId": "team-1", "billing:plan": "enterprise" },
+    };
+    const memberCaller: SessionUser = { ...multiRoleCaller, origin: "member-resolution" };
+    const { origin: _origin, ...originStripped } = memberCaller;
+    expect(isIdentitySwitchAllowed(multiRoleCaller, forgedClaim, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(multiRoleCaller, droppedClaims, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(multiRoleCaller, extraClaim, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(memberCaller, originStripped, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(multiRoleCaller, memberCaller, false)).toBe(false);
+  });
+
+  test("without a known caller only a grant lets a switch through", () => {
+    expect(isIdentitySwitchAllowed(undefined, normalUser, false)).toBe(false);
+    expect(isIdentitySwitchAllowed(undefined, 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);
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, false, ungated);
 
     let caught: unknown;
     try {
@@ -92,7 +162,7 @@ describe("createGatedIdentitySwitch", () => {
 
   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);
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, false, ungated);
 
     await expect(gated.writeAs(systemUserById, "some:target", {})).rejects.toBeInstanceOf(
       AccessDeniedError,
@@ -101,7 +171,7 @@ describe("createGatedIdentitySwitch", () => {
 
   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);
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, true, ungated);
 
     await gated.queryAs(systemUserById, "q", { a: 1 });
     await gated.writeAs(systemUserById, "w", { b: 2 });
@@ -110,28 +180,60 @@ describe("createGatedIdentitySwitch", () => {
     expect(writeAsMock).toHaveBeenCalledWith(systemUserById, "w", { b: 2 });
   });
 
-  test("a non-system asUser always passes through, regardless of allowSystemIdentity", async () => {
+  test("switching to the caller itself passes through without a grant", async () => {
     const { ungated, queryAsMock } = makeUngated();
-    const deniedByDefault = createGatedIdentitySwitch('handler "x"', false, ungated);
+    const deniedByDefault = createGatedIdentitySwitch('handler "x"', normalUser, false, ungated);
 
     await deniedByDefault.queryAs(normalUser, "q", {});
 
     expect(queryAsMock).toHaveBeenCalledWith(normalUser, "q", {});
   });
+
+  test("writeAs to a foreign tenant without a grant throws identity_switch_denied, no id/tenant leak", async () => {
+    const { ungated, writeAsMock } = makeUngated();
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, false, ungated);
+    const foreignTenantAdmin: SessionUser = {
+      id: crypto.randomUUID(),
+      tenantId: OTHER_TENANT,
+      roles: ["TenantAdmin"],
+    };
+
+    let caught: unknown;
+    try {
+      await gated.writeAs(foreignTenantAdmin, "billing:write:cancel", {});
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    const error = caught as AccessDeniedError;
+    expect(error.details).toEqual({ reason: FrameworkReasons.identitySwitchDenied });
+    expect(error.message).not.toContain(foreignTenantAdmin.id);
+    expect(error.message).not.toContain(OTHER_TENANT);
+    expect(writeAsMock).not.toHaveBeenCalled();
+  });
+
+  test("a grant lets a foreign identity through", async () => {
+    const { ungated, writeAsMock } = makeUngated();
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, true, ungated);
+    const foreignUser: SessionUser = { id: crypto.randomUUID(), tenantId: OTHER_TENANT, roles: [] };
+
+    await gated.writeAs(foreignUser, "w", {});
+
+    expect(writeAsMock).toHaveBeenCalledWith(foreignUser, "w", {});
+  });
 });
 
-describe("withHookIdentitySwitchGrant", () => {
+describe("withHookEscapeHatchGrant", () => {
   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 handlerCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, true, ungated),
+    };
 
-    const hookCtx = withHookIdentitySwitchGrant(
-      handlerCtx,
-      'postSave hook of feature "f"',
-      undefined,
-    );
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, 'postSave hook of feature "f"', undefined);
 
     await expect(hookCtx.queryAs(systemUserById, "q", {})).rejects.toBeInstanceOf(
       AccessDeniedError,
@@ -141,9 +243,11 @@ describe("withHookIdentitySwitchGrant", () => {
   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 handlerCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, false, ungated),
+    };
 
-    const hookCtx = withHookIdentitySwitchGrant(handlerCtx, 'postSave hook of feature "f"', {
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, 'postSave hook of feature "f"', {
       reason: "test hook needs SYSTEM",
     });
 
@@ -152,44 +256,151 @@ describe("withHookIdentitySwitchGrant", () => {
     expect(queryAsMock).toHaveBeenCalledWith(systemUserById, "q", { a: 1 });
   });
 
-  test("a non-system asUser is always allowed through the hook's own gate", async () => {
+  test("a hook without escapeHatch may still switch to the handler's own caller", async () => {
     const { ungated, queryAsMock } = makeUngated();
-    const handlerCtx = { ...createGatedIdentitySwitch('handler "outer"', false, ungated) };
-    const hookCtx = withHookIdentitySwitchGrant(handlerCtx, "hook", undefined);
+    const handlerCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, false, ungated),
+    };
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", undefined);
 
     await hookCtx.queryAs(normalUser, "q", {});
     expect(queryAsMock).toHaveBeenCalledWith(normalUser, "q", {});
   });
 
+  test("a hook without escapeHatch does NOT inherit the handler's grant for a foreign identity", async () => {
+    const { ungated, writeAsMock } = makeUngated();
+    const handlerCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, true, ungated),
+    };
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", undefined);
+    const foreignUser: SessionUser = { ...normalUser, tenantId: OTHER_TENANT };
+
+    await expect(hookCtx.writeAs(foreignUser, "w", {})).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(writeAsMock).not.toHaveBeenCalled();
+  });
+
+  test("the hook gate takes the caller from the dispatcher, never from a spoofed ctx.user", async () => {
+    const { ungated, writeAsMock } = makeUngated();
+    const foreignUser: SessionUser = {
+      id: crypto.randomUUID(),
+      tenantId: OTHER_TENANT,
+      roles: ["Admin"],
+    };
+    const spoofedCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, false, ungated),
+      user: foreignUser,
+    };
+    const hookCtx = withHookEscapeHatchGrant(spoofedCtx, "hook", undefined);
+
+    await expect(hookCtx.writeAs(foreignUser, "w", {})).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(writeAsMock).not.toHaveBeenCalled();
+  });
+
+  test("queryAs and writeAs gated for different callers yield no caller — only a grant passes", async () => {
+    const { ungated, queryAsMock } = makeUngated();
+    const otherCaller: SessionUser = { ...normalUser, id: crypto.randomUUID() };
+    const mixedCtx = {
+      queryAs: createGatedIdentitySwitch('handler "a"', normalUser, false, ungated).queryAs,
+      writeAs: createGatedIdentitySwitch('handler "b"', otherCaller, false, ungated).writeAs,
+    };
+    const hookCtx = withHookEscapeHatchGrant(mixedCtx, "hook", undefined);
+
+    await expect(hookCtx.queryAs(normalUser, "q", {})).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(queryAsMock).not.toHaveBeenCalled();
+  });
+
   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 handlerCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, true, ungated),
+      extra: 1,
+    };
     const spread = { ...handlerCtx };
 
-    const hookCtx = withHookIdentitySwitchGrant(spread, "hook", { reason: "needs system" });
+    const hookCtx = withHookEscapeHatchGrant(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" });
+  test("a context without queryAs/writeAs/db/dbOutsideTransaction is returned unchanged", () => {
+    const plainContext = { unrelated: 1 };
+    const result = withHookEscapeHatchGrant(plainContext, "hook", { reason: "x" });
     expect(result).toBe(plainContext);
   });
 
+  test("a deny-stubbed writeAs is not revived through a sibling queryAs's registered ungated pair", async () => {
+    // Like a member-resolution ctx: registered gated queryAs next to an unregistered deny-stub writeAs.
+    const { ungated, writeAsMock } = makeUngated();
+    const gatedIdentitySwitch = createGatedIdentitySwitch(
+      'handler "outer"',
+      normalUser,
+      true,
+      ungated,
+    );
+    const denyStubWriteAs: WriteAsFn = async () => {
+      throw new AccessDeniedError({
+        message: "read-only",
+        details: { reason: "member_resolution_read_only" },
+      });
+    };
+    const handlerCtx = { queryAs: gatedIdentitySwitch.queryAs, writeAs: denyStubWriteAs };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", {
+      reason: "test hook needs SYSTEM",
+    });
+
+    await expect(hookCtx.writeAs(systemUserById, "w", {})).rejects.toBeInstanceOf(
+      AccessDeniedError,
+    );
+    expect(writeAsMock).not.toHaveBeenCalled();
+  });
+
   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);
+    const hookCtx = withHookEscapeHatchGrant(stubContext, "hook", undefined);
     await expect(hookCtx.queryAs(systemUserById, "q", {})).rejects.toBeInstanceOf(
       AccessDeniedError,
     );
+    await expect(hookCtx.queryAs(normalUser, "q", {})).rejects.toBeInstanceOf(AccessDeniedError);
+    const stubWithUser = withHookEscapeHatchGrant(
+      { ...stubContext, user: normalUser },
+      "hook",
+      undefined,
+    );
+    await expect(stubWithUser.queryAs(normalUser, "q", {})).rejects.toBeInstanceOf(
+      AccessDeniedError,
+    );
     expect(stubQueryAs).not.toHaveBeenCalled();
 
-    const allowedHookCtx = withHookIdentitySwitchGrant(stubContext, "hook", { reason: "x" });
+    const allowedHookCtx = withHookEscapeHatchGrant(stubContext, "hook", { reason: "x" });
     await allowedHookCtx.queryAs(systemUserById, "q", {});
     expect(stubQueryAs).toHaveBeenCalledWith(systemUserById, "q", {});
   });
+
+  test("hook re-gates ctx.db.unsafeRaw() independently of the handler's own grant", () => {
+    const rawDb: DbRunner = {
+      unsafe: async () => [],
+      begin: async () => {
+        throw new Error("begin not used in this test");
+      },
+    } as DbRunner;
+    // Simulates buildHandlerContext granting the HANDLER its own unsafeRaw escapeHatch.
+    const handlerDb = createTenantDb(rawDb, TENANT, "tenant", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "handler's own grant" },
+    });
+    const handlerCtx = { db: handlerDb };
+
+    const hookCtxWithoutEscapeHatch = withHookEscapeHatchGrant(handlerCtx, "hook", undefined) as {
+      db: TenantDb;
+    };
+    expect(() => hookCtxWithoutEscapeHatch.db.unsafeRaw("test reason")).toThrow(AccessDeniedError);
+
+    const hookCtxWithEscapeHatch = withHookEscapeHatchGrant(handlerCtx, "hook", {
+      reason: "hook's own grant",
+    }) as { db: TenantDb };
+    expect(hookCtxWithEscapeHatch.db.unsafeRaw("test reason")).toBe(rawDb);
+  });
 });