@cosmicdrift/kumiko-framework 0.266.0 → 0.268.0

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

@@ -1,8 +1,10 @@
+import { type TenantDb, withUnsafeRawGrant } from "../db/tenant-db";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
 import type {
   ActiveMembershipResult,
   EscapeHatchDeclaration,
   LifecycleHookFn,
+  MemberReader,
   SessionUser,
   WriteResult,
 } from "../engine/types";
@@ -37,8 +39,10 @@ export function systemIdentitySwitchDenied(callerLabel: string): AccessDeniedErr
   });
 }
 
-// Reverse-lookup so withHookIdentitySwitchGrant can re-gate the SAME ungated pair under a narrower grant.
+// Reverse-lookup so withHookEscapeHatchGrant can re-gate the SAME ungated pair under a narrower grant.
 const ungatedByGated = new WeakMap<QueryAsFn | WriteAsFn, IdentitySwitch>();
+// Same idea, for ctx.queryAsMember — a single function rather than a pair.
+const ungatedMemberReaderByGated = new WeakMap<MemberReader, MemberReader>();
 
 export function createGatedIdentitySwitch(
   callerLabel: string,
@@ -63,15 +67,39 @@ export function createGatedIdentitySwitch(
   return gated;
 }
 
-function readIdentitySwitchFn<TFn extends QueryAsFn | WriteAsFn | ResolveActiveMembershipFn>(
+// ctx.queryAsMember's gate: the caller never names the target identity up
+// front (it's resolved internally), so this is a flat allow/deny.
+export function createGatedMemberReader(
+  callerLabel: string,
+  allowSystemIdentity: boolean,
+  ungated: MemberReader,
+): MemberReader {
+  const gated: MemberReader = async (userId, qn, payload) => {
+    if (!allowSystemIdentity) throw systemIdentitySwitchDenied(callerLabel);
+    return ungated(userId, qn, payload);
+  };
+  ungatedMemberReaderByGated.set(gated, ungated);
+  return gated;
+}
+
+function readIdentitySwitchFn<
+  TFn extends QueryAsFn | WriteAsFn | ResolveActiveMembershipFn | MemberReader,
+>(
   context: object,
-  key: "queryAs" | "writeAs" | "resolveActiveMembership",
+  key: "queryAs" | "writeAs" | "resolveActiveMembership" | "queryAsMember",
 ): TFn | undefined {
   if (!(key in context)) return undefined;
   const value = (context as Record<string, unknown>)[key];
   return typeof value === "function" ? (value as TFn) : undefined; // @cast-boundary engine-bridge — checked via typeof above
 }
 
+// context's own keys only — never touch a property of the resolved value, which may be a Proxy that throws on any get.
+function readDbLikeValue(context: object, key: "db" | "dbOutsideTransaction"): object | undefined {
+  if (!(key in context)) return undefined;
+  const value = (context as Record<string, unknown>)[key];
+  return typeof value === "object" && value !== null ? value : undefined;
+}
+
 function unavailableIdentitySwitchFn(callerLabel: string, kind: "queryAs" | "writeAs") {
   return async () => {
     throw new InternalError({
@@ -98,7 +126,8 @@ function fallbackUngatedIdentitySwitch(
   };
 }
 
-// Reuses the ORIGINAL ungated pair when known, so this grant doesn't compose with the caller's.
+// Resolved per function: a shared ungated pair would revive a member-resolution
+// ctx's deny-stubbed writeAs through its still-registered queryAs.
 function gatedIdentitySwitchFields(
   callerLabel: string,
   escapeHatch: EscapeHatchDeclaration | undefined,
@@ -106,10 +135,9 @@ function gatedIdentitySwitchFields(
   ctxWriteAs: WriteAsFn | undefined,
 ): Partial<IdentitySwitch> {
   if (!ctxQueryAs && !ctxWriteAs) return {};
-  const ungated: IdentitySwitch =
-    (ctxQueryAs && ungatedByGated.get(ctxQueryAs)) ??
-    (ctxWriteAs && ungatedByGated.get(ctxWriteAs)) ??
-    fallbackUngatedIdentitySwitch(callerLabel, ctxQueryAs, ctxWriteAs);
+  const ungatedQueryAs = ctxQueryAs && (ungatedByGated.get(ctxQueryAs)?.queryAs ?? ctxQueryAs);
+  const ungatedWriteAs = ctxWriteAs && (ungatedByGated.get(ctxWriteAs)?.writeAs ?? ctxWriteAs);
+  const ungated = fallbackUngatedIdentitySwitch(callerLabel, ungatedQueryAs, ungatedWriteAs);
   const gated = createGatedIdentitySwitch(callerLabel, escapeHatch !== undefined, ungated);
   return {
     ...(ctxQueryAs && { queryAs: gated.queryAs }),
@@ -117,7 +145,21 @@ function gatedIdentitySwitchFields(
   };
 }
 
-export function withHookIdentitySwitchGrant<TContext extends object>(
+// Unlike ctx.resolveActiveMembership (deny-only), a hook's own escapeHatch
+// can grant queryAsMember even when the enclosing handler has none.
+function gatedMemberReaderField(
+  callerLabel: string,
+  escapeHatch: EscapeHatchDeclaration | undefined,
+  ctxQueryAsMember: MemberReader | undefined,
+): { queryAsMember?: MemberReader } {
+  if (!ctxQueryAsMember) return {};
+  const ungated = ungatedMemberReaderByGated.get(ctxQueryAsMember) ?? ctxQueryAsMember;
+  return {
+    queryAsMember: createGatedMemberReader(callerLabel, escapeHatch !== undefined, ungated),
+  };
+}
+
+export function withHookEscapeHatchGrant<TContext extends object>(
   context: TContext,
   callerLabel: string,
   escapeHatch: EscapeHatchDeclaration | undefined,
@@ -128,7 +170,19 @@ export function withHookIdentitySwitchGrant<TContext extends object>(
     context,
     "resolveActiveMembership",
   );
-  if (!ctxQueryAs && !ctxWriteAs && !ctxResolveActiveMembership) return context;
+  const ctxQueryAsMember = readIdentitySwitchFn<MemberReader>(context, "queryAsMember");
+  const ctxDb = readDbLikeValue(context, "db");
+  const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
+  if (
+    !ctxQueryAs &&
+    !ctxWriteAs &&
+    !ctxResolveActiveMembership &&
+    !ctxQueryAsMember &&
+    !ctxDb &&
+    !ctxDbOutsideTransaction
+  ) {
+    return context;
+  }
 
   return {
     ...context,
@@ -137,11 +191,17 @@ export function withHookIdentitySwitchGrant<TContext extends object>(
       escapeHatch === undefined && {
         resolveActiveMembership: deniedResolveActiveMembership(callerLabel),
       }),
+    ...gatedMemberReaderField(callerLabel, escapeHatch, ctxQueryAsMember),
+    // @cast-boundary engine-bridge — withUnsafeRawGrant passes non-TenantDb values (e.g. a guard Proxy) through unchanged.
+    ...(ctxDb && { db: withUnsafeRawGrant(ctxDb as TenantDb, escapeHatch) }),
+    ...(ctxDbOutsideTransaction && {
+      dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction as TenantDb, escapeHatch),
+    }),
   };
 }
 
-// Re-gates a hook's own ctx.queryAs/ctx.writeAs instead of inheriting the handler's grant.
-export function bindHookIdentitySwitchGrant(
+// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.db/ctx.dbOutsideTransaction instead of inheriting the handler's grant.
+export function bindHookEscapeHatchGrant(
   fn: LifecycleHookFn,
   label: string,
   escapeHatch: EscapeHatchDeclaration | undefined,
@@ -149,6 +209,6 @@ export function bindHookIdentitySwitchGrant(
   return ((payload: unknown, context: object) =>
     (fn as (payload: unknown, context: object) => unknown)(
       payload,
-      withHookIdentitySwitchGrant(context, label, escapeHatch),
+      withHookEscapeHatchGrant(context, label, escapeHatch),
     )) as LifecycleHookFn; // @cast-boundary engine-bridge — LifecycleHookFn union, same (payload, context) shape at runtime
 }

package/src/stack/test-stack.ts

@@ -13,7 +13,12 @@ import { createJobRunner, type JobRunner, type JobRunnerOptions } from "../jobs"
 import type { Lifecycle } from "../lifecycle";
 import { createNoopProvider, type ObservabilityProvider } from "../observability";
 import type { Dispatcher, EventDispatcher } from "../pipeline";
-import { createEntityCache, createEventDedup, createIdempotencyGuard } from "../pipeline";
+import {
+  createEntityCache,
+  createEventDedup,
+  createIdempotencyGuard,
+  dispatcherToWriteRef,
+} from "../pipeline";
 import { createInMemorySearchAdapter } from "../search";
 import type { SearchAdapter } from "../search/types";
 import { createTestDb } from "./db";
@@ -446,6 +451,10 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       })()),
     });
 
+    // Mirrors the prod entrypoints — without this, JobContext.write/writeAs/
+    // queryAs/queryAsMember throw on first use inside a test-stack job.
+    if (jobRunner) jobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
+
     const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
 
     // Pre-register consumer state rows so tests can call runOnce() directly

package/src/testing/handler-context.ts

@@ -9,6 +9,7 @@ import type {
   AppendEventArgs,
   FetchForWritingArgs,
   HandlerContext,
+  MemberReader,
   SessionUser,
   WriteResult,
 } from "../engine/types";
@@ -58,6 +59,7 @@ export function bridgeStub(opts?: {
   | "queryProjection"
   | "resolveAuthClaims"
   | "resolveActiveMembership"
+  | "queryAsMember"
   | "hasFeature"
   | "metrics"
   | "metricsFor"
@@ -122,6 +124,7 @@ export function bridgeStub(opts?: {
     resolveActiveMembership: notAvailable(
       "resolveActiveMembership",
     ) as unknown as HandlerContext["resolveActiveMembership"],
+    queryAsMember: notAvailable("queryAsMember") as unknown as MemberReader,
     // Stub defaults to always-enabled — matches the dispatcher's behaviour
     // when no effectiveFeatures resolver is wired (tests without toggles).
     hasFeature: async () => true,