@cosmicdrift/kumiko-framework 0.268.0 → 0.269.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.268.0",
+  "version": "0.269.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.268.0",
+    "@cosmicdrift/kumiko-types": "0.269.1",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.268.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.269.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/stream-escape-hatch.integration.test.ts

@@ -0,0 +1,203 @@
+// fw#(stream escapeHatch) — mirrors system-identity-switch.integration.test.ts's
+// coverage of ctx.queryAs(SYSTEM, ...) gating, but for stream handlers: a
+// StreamHandlerDef can now declare `escapeHatch: { reason }` to switch
+// identity to SYSTEM. Real HTTP calls (SSE POST /api/stream via Hono's
+// in-memory app.request) + setupTestStack — never createTestDispatcher.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
+import { z } from "zod";
+import { generateToken } from "../../api/tokens";
+import { createSystemUser, defineFeature } from "../../engine";
+import type { SessionUser } from "../../engine/types";
+import { createTestUser, setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+const user = TestUsers.user;
+const otherUserNoRole: SessionUser = createTestUser({
+  id: 60,
+  tenantId: user.tenantId,
+  roles: ["User"],
+});
+const otherUserWithAdminRole: SessionUser = createTestUser({
+  id: 61,
+  tenantId: user.tenantId,
+  roles: ["Admin"],
+});
+
+const streamProbeFeature = defineFeature("stream-idswitch-probe", (r) => {
+  r.queryHandler(
+    "whoami",
+    z.object({}),
+    async (query) => ({ roles: query.user.roles, tenantId: query.user.tenantId }),
+    { access: { roles: ["system", "User"] } },
+  );
+
+  r.queryHandler("admin-only", z.object({}), async () => ({ ok: true }), {
+    access: { roles: ["Admin"] },
+  });
+
+  // --- ctx.queryAs(SYSTEM, ...) from a stream handler: gated by the
+  // stream handler's own escapeHatch, same contract as write/query. ---
+  r.streamHandler(
+    "query-as-system-no-hatch",
+    z.object({}),
+    async function* (query, ctx) {
+      const result = await ctx.queryAs(
+        createSystemUser(query.user.tenantId),
+        "stream-idswitch-probe:query:whoami",
+        {},
+      );
+      yield result;
+    },
+    { access: { roles: ["User"] } },
+  );
+
+  r.streamHandler(
+    "query-as-system-with-hatch",
+    z.object({}),
+    async function* (query, ctx) {
+      const result = await ctx.queryAs(
+        createSystemUser(query.user.tenantId),
+        "stream-idswitch-probe:query:whoami",
+        {},
+      );
+      yield result;
+    },
+    {
+      access: { roles: ["User"] },
+      escapeHatch: { reason: "test: stream needs SYSTEM to look itself up" },
+    },
+  );
+
+  // --- ctx.queryAs(nonSystemUser, ...) from a stream handler (fw#2876): a foreign
+  // user needs the stream handler's escapeHatch; the target's own access rule still applies. ---
+  r.streamHandler(
+    "query-as-normal-user-no-hatch",
+    z.object({}),
+    async function* (_query, ctx) {
+      yield await ctx.queryAs(otherUserWithAdminRole, "stream-idswitch-probe:query:admin-only", {});
+    },
+    { access: { roles: ["User"] } },
+  );
+
+  r.streamHandler(
+    "query-as-normal-user",
+    z.object({ granted: z.boolean() }),
+    async function* (query, ctx) {
+      const result = await ctx.queryAs(
+        query.payload.granted ? otherUserWithAdminRole : otherUserNoRole,
+        "stream-idswitch-probe:query:admin-only",
+        {},
+      );
+      yield result;
+    },
+    {
+      access: { roles: ["User"] },
+      escapeHatch: { reason: "test: stream reads admin-only data as a named colleague" },
+    },
+  );
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [streamProbeFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function buildDispatcherFor(asUser: SessionUser) {
+  const authJwt = await stack.jwt.sign(asUser);
+  const csrfToken = generateToken();
+  const cookieHeader = `kumiko_auth=${authJwt}; kumiko_csrf=${csrfToken}`;
+  const fetchImpl = (async (url: unknown, init: RequestInit | undefined) => {
+    return stack.app.request(String(url), {
+      ...(init ?? {}),
+      headers: { ...(init?.headers ?? {}), Cookie: cookieHeader },
+    });
+  }) as unknown as typeof fetch;
+  return createLiveDispatcher({ fetch: fetchImpl, readCsrf: () => csrfToken });
+}
+
+async function collectAll<T>(gen: AsyncGenerator<T>): Promise<T[]> {
+  const chunks: T[] = [];
+  for await (const chunk of gen) chunks.push(chunk);
+  return chunks;
+}
+
+describe("ctx.queryAs(SYSTEM, ...) from a stream handler — gated by the handler's own escapeHatch", () => {
+  test("WITHOUT escapeHatch: fails with access_denied", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream(
+        "stream-idswitch-probe:stream:query-as-system-no-hatch",
+        {},
+      )) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "access_denied" });
+  });
+
+  test("WITH escapeHatch: succeeds", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    const chunks = await collectAll(
+      dispatcher.stream<{ roles: readonly string[] }>(
+        "stream-idswitch-probe:stream:query-as-system-with-hatch",
+        {},
+      ),
+    );
+    expect(chunks[0]?.roles).toContain("system");
+  });
+});
+
+describe("ctx.queryAs(nonSystemUser, ...) from a stream handler — gated like write/query (fw#2876)", () => {
+  test("WITHOUT escapeHatch: a foreign user fails with identity_switch_denied", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream(
+        "stream-idswitch-probe:stream:query-as-normal-user-no-hatch",
+        {},
+      )) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({
+      code: "access_denied",
+      details: { reason: "identity_switch_denied" },
+    });
+  });
+
+  test("WITH escapeHatch, delegates to the target's own access check: denied when the target user lacks the role", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream("stream-idswitch-probe:stream:query-as-normal-user", {
+        granted: false,
+      })) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "access_denied" });
+  });
+
+  test("WITH escapeHatch, delegates to the target's own access check: allowed when the target user has the role", async () => {
+    const dispatcher = await buildDispatcherFor(user);
+    const chunks = await collectAll(
+      dispatcher.stream<{ ok: boolean }>("stream-idswitch-probe:stream:query-as-normal-user", {
+        granted: true,
+      }),
+    );
+    expect(chunks[0]?.ok).toBe(true);
+  });
+});

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.269.0",
+    "type": "breaking",
+    "title": "ctx.queryAs/ctx.writeAs to any identity other than the caller itself need r.systemScope() or escapeHatch (fw#2876).",
+    "detail": "The identity-switch gate from fw#2859 now applies to every target, not only SYSTEM (`isSystemIdentitySwitchAllowed` is replaced by `isIdentitySwitchAllowed(caller, asUser, hasGrant)` in `pipeline/system-identity-switch.ts`; `createGatedIdentitySwitch` takes the caller as second argument). Without a grant, `HandlerContext.queryAs`/`writeAs` only accept the caller itself: same `id`, same `tenantId`, same `origin`, equal `claims`, and roles that are a subset of the caller's roles (`sid`, `pat`, `timezone`, `locale` may differ). Any other target — a different user id, a different tenant, extra roles, changed claims, a stripped `origin` — throws `AccessDeniedError` (code `access_denied`, `details.reason` `identity_switch_denied`, no target id/tenant in the error); SYSTEM targets keep `system_identity_switch_denied`. The grant is the same as before: the calling handler's `r.systemScope()` feature or `escapeHatch: { reason }` on the write/query/stream handler, or the hook's own `r.hook(..., { escapeHatch })`. It stays non-transitive, hooks never inherit it, extension hooks and `r.authClaims` hooks have no declaration site (their `queryAs` only reaches the caller itself), and a hook's caller is taken from the dispatcher-built gate, never from `ctx.user`. `JobContext.queryAs`/`writeAs`, top-level `dispatcher.write`/`query`, `ctx.queryAsMember` and `ctx.resolveActiveMembership` are unchanged. `r.step.callFeature({ as })` goes through the gated `ctx.writeAs` and needs the handler's `escapeHatch` for a foreign `as`.",
+    "migration": "Find every `ctx.queryAs(user, ...)`/`ctx.writeAs(user, ...)` (also via helpers that receive `ctx`, and `r.step.callFeature({ as })`) whose user is not `createSystemUser(...)`. If the user is `event.user`/`query.user` or a copy with fewer roles, nothing to do. If it is another user, another tenant (e.g. `{ ...event.user, tenantId: other }`) or adds roles, declare `escapeHatch: { reason: \"<why this handler acts as that identity>\" }` on the write, query or stream handler (or on the `r.hook(...)` call), move the call into an `r.systemScope()` feature or a job, or use `ctx.queryAsMember(userId, ...)` for reads as a stored tenant member. Code branching on `details.reason` for these denials must also accept `identity_switch_denied`. Audit at release: bundled-features 0 sites, solon 0, offlot-app 0, kumiko-enterprise 0 (ai-agent tool dispatcher passes the caller itself)."
+  },
+  {
+    "version": "0.269.0",
+    "type": "improvement",
+    "title": "escapeHatch is now also accepted on stream handlers, gating a SYSTEM identity switch via ctx.queryAs the same way it does for write/query handlers.",
+    "detail": "StreamHandlerDef/StreamHandlerDefinition and the r.streamHandler options param accept escapeHatch: { reason }, same contract as WriteHandlerDef/QueryHandlerDef: a stream handler that switches identity to SYSTEM via ctx.queryAs now needs its own escapeHatch declaration (or its feature must be r.systemScope()), same as ctx.writeAs/queryAs already require for write and query handlers. Stream handlers still cannot reach db.global() (globalWrites stays write-only) but do get the same SYSTEM-identity-switch and ctx.db.unsafeRaw(reason) grant a query-handler escapeHatch already unlocks. The boot validator rejects an empty reason on a stream handler's escapeHatch the same way it does for write/query handlers."
+  },
   {
     "version": "0.267.0",
     "type": "breaking",

package/src/engine/__tests__/extends-registrar.test.ts

@@ -242,6 +242,7 @@ describe("extendsRegistrar", () => {
     // systemScope) — the extension hook must not inherit this.
     const handlerCtx = createGatedIdentitySwitch(
       'handler "fleet:write:vehicle:create"',
+      undefined,
       true,
       ungated,
     );

package/src/engine/__tests__/hook-identity-switch-grant.test.ts

@@ -34,6 +34,7 @@ describe("r.hook({ allOf }, ...) identity-switch gate", () => {
     // escapeHatch or is systemScope) — the hook must not inherit this.
     const handlerCtx = createGatedIdentitySwitch(
       'handler "test:write:thing:create"',
+      undefined,
       true,
       ungated,
     );
@@ -70,6 +71,7 @@ describe("r.hook({ allOf }, ...) identity-switch gate", () => {
     };
     const handlerCtx = createGatedIdentitySwitch(
       'handler "test:write:thing:create"',
+      undefined,
       false,
       ungated,
     );
@@ -114,7 +116,7 @@ describe("r.hook({ allOf }, ...) identity-switch gate", () => {
     };
     const ungatedResolveActiveMembership = mock(async () => activeResult);
     const handlerCtx = {
-      ...createGatedIdentitySwitch('handler "test:write:thing:create"', true, {
+      ...createGatedIdentitySwitch('handler "test:write:thing:create"', undefined, true, {
         queryAs: mock(async () => "ok") as QueryAsFn,
         writeAs: async () => ({ isSuccess: true as const, data: null }),
       }),
@@ -155,7 +157,7 @@ describe("r.hook({ allOf }, ...) identity-switch gate", () => {
     };
     const ungatedResolveActiveMembership = mock(async () => activeResult);
     const handlerCtx = {
-      ...createGatedIdentitySwitch('handler "test:write:thing:create"', false, {
+      ...createGatedIdentitySwitch('handler "test:write:thing:create"', undefined, false, {
         queryAs: mock(async () => "ok") as QueryAsFn,
         writeAs: async () => ({ isSuccess: true as const, data: null }),
       }),

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

@@ -144,6 +144,43 @@ describe("validateAccessDeclarations", () => {
     expect(() => validateAccessDeclarations(feature)).not.toThrow();
   });
 
+  // 2c. escapeHatch reason must be non-empty on a stream handler too — same
+  // contract as write/query: streams can't reach db.global(), but they can
+  // still declare escapeHatch to switch identity to SYSTEM via ctx.queryAs.
+  test("stream handler escapeHatch with an empty reason throws, naming the handler", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.streamHandler(
+        "note:tail",
+        z.object({}),
+        async function* () {
+          yield {};
+        },
+        { access: { roles: ["Admin"] }, escapeHatch: { reason: "" } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:tail"/);
+  });
+
+  test("stream handler escapeHatch with a non-empty reason boots fine", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.streamHandler(
+        "note:tail",
+        z.object({}),
+        async function* () {
+          yield {};
+        },
+        {
+          access: { roles: ["Admin"] },
+          escapeHatch: { reason: "cross-tenant note tail for auth" },
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
   // 3. openToAll write handler accepting an unbound personal-data field needs personalData.
   test("openToAll write handler accepting a personal-data field without personalData throws", () => {
     const feature = defineFeature("notes", (r) => {

package/src/engine/boot-validator/access-declarations.ts

@@ -4,6 +4,7 @@ import type {
   OwnershipMap,
   OwnershipRule,
   QueryHandlerDef,
+  StreamHandlerDef,
   WriteHandlerDef,
 } from "../types";
 import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
@@ -133,7 +134,10 @@ function validateEscapeHatchReason(
   feature: FeatureDefinition,
   kind: HandlerKind,
   handlerName: string,
-  escapeHatch: WriteHandlerDef["escapeHatch"] | QueryHandlerDef["escapeHatch"],
+  escapeHatch:
+    | WriteHandlerDef["escapeHatch"]
+    | QueryHandlerDef["escapeHatch"]
+    | StreamHandlerDef["escapeHatch"],
 ): void {
   // skip: no escapeHatch declared, or its reason is already non-empty
   if (!escapeHatch || escapeHatch.reason.trim().length > 0) return;
@@ -212,6 +216,7 @@ export function validateAccessDeclarations(feature: FeatureDefinition): void {
   }
   for (const [handlerName, handler] of Object.entries(feature.streamHandlers)) {
     validateOpenToAllReason(feature, "stream", handlerName, handler.access);
+    validateEscapeHatchReason(feature, "stream", handlerName, handler.escapeHatch);
     validatePersonalDataOnlyOnWrite(feature, "stream", handlerName, handler.access);
   }
 }

package/src/engine/feature-entity-handlers.ts

@@ -228,7 +228,11 @@ export function buildEntityHandlerMethods<TName extends string>(
       nameOrDef: string | StreamHandlerDefinition<TName, TSchema>,
       schema?: TSchema,
       handler?: StreamHandlerFn<z.infer<TSchema>>,
-      options?: { access: AccessRule; rateLimit?: RateLimitOption },
+      options?: {
+        access: AccessRule;
+        rateLimit?: RateLimitOption;
+        escapeHatch?: EscapeHatchDeclaration;
+      },
     ): HandlerRef {
       if (typeof nameOrDef === "object") {
         const def = nameOrDef;
@@ -239,6 +243,7 @@ export function buildEntityHandlerMethods<TName extends string>(
           handler: def.handler as StreamHandlerFn, // @cast-boundary engine-bridge
           access: def.access,
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
+          ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
         };
         return { name: def.name };
       }
@@ -249,6 +254,7 @@ export function buildEntityHandlerMethods<TName extends string>(
         handler: inline.handler as StreamHandlerFn, // @cast-boundary engine-bridge
         access: inline.options.access,
         ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
+        ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
       };
       return { name: nameOrDef };
     },

package/src/engine/steps/call-feature.ts

@@ -1,6 +1,6 @@
 // r.step.callFeature — typed sub-command on another Kumiko feature.
 // Tier-2: requires r.requires.step("callFeature"). Sync (no dispatcher).
-// Cross-tenant via opts.as (Sysadmin-role-checked at the dispatcher layer).
+// opts.as other than the caller itself needs escapeHatch on the handler (system-identity-switch.ts).
 
 import { defineStep } from "../define-step";
 import type { SessionUser } from "../types";

package/src/errors/i18n/de.yaml

@@ -97,6 +97,22 @@ system_identity_switch_denied:
     (oder am `r.hook(...)`-Aufruf, wenn der Wechsel in einem Hook passiert),
     oder verlagere die Logik in ein `r.systemScope()`-Feature oder einen Job.
 
+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 anderen Identität als dem eigenen Caller aufgerufen — andere
+    User-ID, anderer Tenant, andere Claims oder Origin, oder Rollen, die der
+    Caller nicht hat — ohne `r.systemScope()`-Handler, Job zu sein oder
+    `escapeHatch: { reason }` zu deklarieren. Der Wechsel auf den Caller selbst
+    oder eine Teilmenge seiner Rollen bleibt frei.
+
+    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.
+
 member_resolution_denied:
   endUser: |
     Diese Aktion ist nicht erlaubt.

package/src/errors/i18n/en.yaml

@@ -94,6 +94,21 @@ system_identity_switch_denied:
     (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.
 
+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 an identity other than its own caller — a different user id, tenant,
+    claims or origin, or roles the caller does not have — without being an
+    `r.systemScope()` handler, a job, or declaring `escapeHatch: { reason }`.
+    Switching to the caller itself or to a subset of its roles stays free.
+
+    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.
+
 member_resolution_denied:
   endUser: |
     This action isn't allowed.

package/src/errors/reasons.ts

@@ -43,6 +43,11 @@ export const FrameworkReasons = {
   // SYSTEM identity without an r.systemScope() feature or a declared escapeHatch.
   systemIdentitySwitchDenied: "system_identity_switch_denied",
 
+  // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
+  // non-SYSTEM identity other than its own caller (different user, tenant,
+  // claims, origin or extra roles) without r.systemScope() or escapeHatch.
+  identitySwitchDenied: "identity_switch_denied",
+
   // AccessDeniedError: ctx.queryAsMember's userId is not an active member of
   // ctx's tenant. Deliberately generic — a caller can't probe which check failed.
   memberResolutionDenied: "member_resolution_denied",

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

@@ -8,8 +8,8 @@ import { AccessDeniedError, FrameworkReasons } from "../../errors";
 import {
   createGatedIdentitySwitch,
   type IdentitySwitch,
+  isIdentitySwitchAllowed,
   isSystemIdentity,
-  isSystemIdentitySwitchAllowed,
   type WriteAsFn,
   withHookEscapeHatchGrant,
 } from "../system-identity-switch";
@@ -61,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("a non-SYSTEM target is always allowed", () => {
-    expect(isSystemIdentitySwitchAllowed(normalUser, false)).toBe(true);
-    expect(isSystemIdentitySwitchAllowed(normalUser, 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("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 {
@@ -95,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,
@@ -104,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 });
@@ -113,14 +180,48 @@ 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("withHookEscapeHatchGrant", () => {
@@ -128,7 +229,9 @@ describe("withHookEscapeHatchGrant", () => {
     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 = withHookEscapeHatchGrant(handlerCtx, 'postSave hook of feature "f"', undefined);
 
@@ -140,7 +243,9 @@ describe("withHookEscapeHatchGrant", () => {
   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 = withHookEscapeHatchGrant(handlerCtx, 'postSave hook of feature "f"', {
       reason: "test hook needs SYSTEM",
@@ -151,18 +256,65 @@ describe("withHookEscapeHatchGrant", () => {
     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 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 = withHookEscapeHatchGrant(spread, "hook", { reason: "needs system" });
@@ -180,7 +332,12 @@ describe("withHookEscapeHatchGrant", () => {
   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"', true, ungated);
+    const gatedIdentitySwitch = createGatedIdentitySwitch(
+      'handler "outer"',
+      normalUser,
+      true,
+      ungated,
+    );
     const denyStubWriteAs: WriteAsFn = async () => {
       throw new AccessDeniedError({
         message: "read-only",
@@ -207,6 +364,15 @@ describe("withHookEscapeHatchGrant", () => {
     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 = withHookEscapeHatchGrant(stubContext, "hook", { reason: "x" });

package/src/pipeline/dispatch-shared.ts

@@ -274,10 +274,13 @@ export async function buildHandlerContext(
   // but at this point we're the root of the pipeline — cast is safe.
   const dbSource = resolveDbSource(ctx, tx);
   const reqCtx = requestContext.get();
-  // global() writes are write-handler-only; SYSTEM identity switch and unsafeRaw accept write or query escapeHatch.
+  // global() writes are write-handler-only; SYSTEM identity switch and unsafeRaw accept write, query or stream escapeHatch.
   const writeEscapeHatch = registry.getWriteHandler(type)?.escapeHatch;
-  const handlerEscapeHatch = writeEscapeHatch ?? registry.getQueryHandler(type)?.escapeHatch;
-  const allowSystemIdentity = isSystem || handlerEscapeHatch !== undefined;
+  const handlerEscapeHatch =
+    writeEscapeHatch ??
+    registry.getQueryHandler(type)?.escapeHatch ??
+    registry.getStreamHandler(type)?.escapeHatch;
+  const hasIdentitySwitchGrant = isSystem || handlerEscapeHatch !== undefined;
   const buildTenantScopedDb = (source: DbConnection | DbTx, signal: AbortSignal | undefined) =>
     createTenantDb(
       source,
@@ -375,23 +378,28 @@ export async function buildHandlerContext(
     : () => createNoopMetricsHandle();
 
   // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
-  // queryAs/writeAs switch identity; SYSTEM needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
+  // queryAs/writeAs to anyone but the caller itself needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
   const bridgeSink = afterCommitHooks ?? [];
   const scheduleAfterCommit = (hook: AfterCommitHook): void => {
     bridgeSink.push(hook);
   };
-  const identitySwitch = createGatedIdentitySwitch(`handler "${type}"`, allowSystemIdentity, {
-    queryAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
-      executeQuery(ctx, targetType, payload, asUser, tx), // @wrapper-known semantic-alias
-    writeAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
-      executeWrite(ctx, targetType, payload, asUser, tx, bridgeSink),
-  });
+  const identitySwitch = createGatedIdentitySwitch(
+    `handler "${type}"`,
+    user,
+    hasIdentitySwitchGrant,
+    {
+      queryAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
+        executeQuery(ctx, targetType, payload, asUser, tx), // @wrapper-known semantic-alias
+      writeAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
+        executeWrite(ctx, targetType, payload, asUser, tx, bridgeSink),
+    },
+  );
   // Lazy — creates the reader (which fails closed on SYSTEM_TENANT_ID) only
   // on first actual use, not on every HandlerContext build.
   let ungatedMemberReader: MemberReader | undefined;
   const queryAsMember = createGatedMemberReader(
     `handler "${type}"`,
-    allowSystemIdentity,
+    hasIdentitySwitchGrant,
     (userId, qn, payload) => {
       ungatedMemberReader ??= createMemberReaderFn(ctx, user.tenantId, tx);
       return ungatedMemberReader(userId, qn, payload);
@@ -671,7 +679,7 @@ export async function buildHandlerContext(
     // Internally queries memberships as SYSTEM, so it needs the same grant
     // as a SYSTEM queryAs/writeAs (r.systemScope() or escapeHatch).
     resolveActiveMembership: (userId: string, tenantId: TenantId) => {
-      if (!allowSystemIdentity) throw systemIdentitySwitchDenied(`handler "${type}"`);
+      if (!hasIdentitySwitchGrant) throw systemIdentitySwitchDenied(`handler "${type}"`);
       return resolveActiveMembershipFn(ctx, userId, tenantId, INTERACTIVE_SIGN_IN_POLICY); // @wrapper-known semantic-alias
     },
 
@@ -1046,7 +1054,7 @@ export async function enforceRateLimit(
 // hooks run OUTSIDE any request transaction (login is itself the root
 // operation, not a nested call) and read-only — so the TenantDb is
 // scoped as "tenant" and no tx is threaded through. Cross-tenant lookups
-// go through queryAs(otherUser, ...); SYSTEM is always denied (no escapeHatch declaration site here).
+// are denied: queryAs only reaches the claims user itself (no escapeHatch declaration site here).
 function buildAuthClaimsContext(ctx: DispatchContext, user: SessionUser): AuthClaimsContext {
   const { appContext: context } = ctx;
   const dbSource = resolveDbSource(ctx, undefined);
@@ -1063,7 +1071,7 @@ function buildAuthClaimsContext(ctx: DispatchContext, user: SessionUser): AuthCl
         secrets: context.secrets,
       })
     : undefined;
-  const identitySwitch = createGatedIdentitySwitch("r.authClaims hook", false, {
+  const identitySwitch = createGatedIdentitySwitch("r.authClaims hook", user, false, {
     queryAs: (asUser: SessionUser, qn: string, payload: unknown) =>
       executeQuery(ctx, qn, payload, asUser), // @wrapper-known semantic-alias
     writeAs: async () => {

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

@@ -23,11 +23,38 @@ export function isSystemIdentity(user: SessionUser): boolean {
   return user.id === SYSTEM_USER_ID || user.roles.includes(SYSTEM_ROLE);
 }
 
-export function isSystemIdentitySwitchAllowed(
+function hasSameClaims(caller: SessionUser, asUser: SessionUser): boolean {
+  if (caller.claims === asUser.claims) return true;
+  const callerClaims = caller.claims ?? {};
+  const asUserClaims = asUser.claims ?? {};
+  const keys = Object.keys(callerClaims);
+  if (keys.length !== Object.keys(asUserClaims).length) return false;
+  return keys.every(
+    (key) =>
+      Object.hasOwn(asUserClaims, key) &&
+      JSON.stringify(callerClaims[key]) === JSON.stringify(asUserClaims[key]),
+  );
+}
+
+// claims drive ownership row filters and origin makes a ctx read-only, so both must match exactly.
+export function isSelfDelegation(caller: SessionUser, asUser: SessionUser): boolean {
+  return (
+    asUser.id === caller.id &&
+    asUser.tenantId === caller.tenantId &&
+    asUser.origin === caller.origin &&
+    asUser.roles.every((role) => caller.roles.includes(role)) &&
+    hasSameClaims(caller, asUser)
+  );
+}
+
+export function isIdentitySwitchAllowed(
+  caller: SessionUser | undefined,
   asUser: SessionUser,
-  allowSystemIdentity: boolean,
+  hasGrant: boolean,
 ): boolean {
-  return !isSystemIdentity(asUser) || allowSystemIdentity;
+  if (hasGrant) return true;
+  if (isSystemIdentity(asUser) || caller === undefined) return false;
+  return isSelfDelegation(caller, asUser);
 }
 
 export function systemIdentitySwitchDenied(callerLabel: string): AccessDeniedError {
@@ -39,31 +66,48 @@ export function systemIdentitySwitchDenied(callerLabel: string): AccessDeniedErr
   });
 }
 
-// Reverse-lookup so withHookEscapeHatchGrant can re-gate the SAME ungated pair under a narrower grant.
-const ungatedByGated = new WeakMap<QueryAsFn | WriteAsFn, IdentitySwitch>();
+export function identitySwitchDenied(callerLabel: string, asUser: SessionUser): AccessDeniedError {
+  if (isSystemIdentity(asUser)) return systemIdentitySwitchDenied(callerLabel);
+  return new AccessDeniedError({
+    message:
+      `${callerLabel} may only switch identity to its own caller (same user, tenant, claims and ` +
+      "a subset of its roles) — declare r.systemScope() or escapeHatch: { reason } on it",
+    details: { reason: FrameworkReasons.identitySwitchDenied },
+  });
+}
+
+type GatedIdentitySwitchSource = {
+  readonly ungated: IdentitySwitch;
+  readonly caller: SessionUser | undefined;
+};
+
+// Reverse-lookup so withHookEscapeHatchGrant can re-gate the SAME ungated pair (and caller) under a narrower grant.
+const sourceByGated = new WeakMap<QueryAsFn | WriteAsFn, GatedIdentitySwitchSource>();
 // Same idea, for ctx.queryAsMember — a single function rather than a pair.
 const ungatedMemberReaderByGated = new WeakMap<MemberReader, MemberReader>();
 
 export function createGatedIdentitySwitch(
   callerLabel: string,
-  allowSystemIdentity: boolean,
+  caller: SessionUser | undefined,
+  hasGrant: boolean,
   ungated: IdentitySwitch,
 ): IdentitySwitch {
   const queryAs: QueryAsFn = async (asUser, qn, payload) => {
-    if (!isSystemIdentitySwitchAllowed(asUser, allowSystemIdentity)) {
-      throw systemIdentitySwitchDenied(callerLabel);
+    if (!isIdentitySwitchAllowed(caller, asUser, hasGrant)) {
+      throw identitySwitchDenied(callerLabel, asUser);
     }
     return ungated.queryAs(asUser, qn, payload);
   };
   const writeAs: WriteAsFn = async (asUser, qn, payload) => {
-    if (!isSystemIdentitySwitchAllowed(asUser, allowSystemIdentity)) {
-      throw systemIdentitySwitchDenied(callerLabel);
+    if (!isIdentitySwitchAllowed(caller, asUser, hasGrant)) {
+      throw identitySwitchDenied(callerLabel, asUser);
     }
     return ungated.writeAs(asUser, qn, payload);
   };
   const gated: IdentitySwitch = { queryAs, writeAs };
-  ungatedByGated.set(queryAs, ungated);
-  ungatedByGated.set(writeAs, ungated);
+  const source: GatedIdentitySwitchSource = { ungated, caller };
+  sourceByGated.set(queryAs, source);
+  sourceByGated.set(writeAs, source);
   return gated;
 }
 
@@ -126,6 +170,16 @@ function fallbackUngatedIdentitySwitch(
   };
 }
 
+// Only a dispatcher-registered gate names the caller; ctx.user is never trusted, and two
+// gates for different callers (a hand-mixed ctx) yield none, so only a grant passes.
+function resolveDispatcherCaller(
+  querySource: GatedIdentitySwitchSource | undefined,
+  writeSource: GatedIdentitySwitchSource | undefined,
+): SessionUser | undefined {
+  if (querySource && writeSource && querySource.caller !== writeSource.caller) return undefined;
+  return (querySource ?? writeSource)?.caller;
+}
+
 // Resolved per function: a shared ungated pair would revive a member-resolution
 // ctx's deny-stubbed writeAs through its still-registered queryAs.
 function gatedIdentitySwitchFields(
@@ -135,10 +189,13 @@ function gatedIdentitySwitchFields(
   ctxWriteAs: WriteAsFn | undefined,
 ): Partial<IdentitySwitch> {
   if (!ctxQueryAs && !ctxWriteAs) return {};
-  const ungatedQueryAs = ctxQueryAs && (ungatedByGated.get(ctxQueryAs)?.queryAs ?? ctxQueryAs);
-  const ungatedWriteAs = ctxWriteAs && (ungatedByGated.get(ctxWriteAs)?.writeAs ?? ctxWriteAs);
+  const querySource = ctxQueryAs && sourceByGated.get(ctxQueryAs);
+  const writeSource = ctxWriteAs && sourceByGated.get(ctxWriteAs);
+  const ungatedQueryAs = ctxQueryAs && (querySource?.ungated.queryAs ?? ctxQueryAs);
+  const ungatedWriteAs = ctxWriteAs && (writeSource?.ungated.writeAs ?? ctxWriteAs);
   const ungated = fallbackUngatedIdentitySwitch(callerLabel, ungatedQueryAs, ungatedWriteAs);
-  const gated = createGatedIdentitySwitch(callerLabel, escapeHatch !== undefined, ungated);
+  const caller = resolveDispatcherCaller(querySource, writeSource);
+  const gated = createGatedIdentitySwitch(callerLabel, caller, escapeHatch !== undefined, ungated);
   return {
     ...(ctxQueryAs && { queryAs: gated.queryAs }),
     ...(ctxWriteAs && { writeAs: gated.writeAs }),