@cosmicdrift/kumiko-framework 0.270.0 → 0.274.0

package/src/pipeline/__tests__/search-consumer-named-events.integration.test.ts

@@ -69,13 +69,16 @@ const namedSearchFeature = defineFeature("named-search", (r) => {
       // executor-built table is write-locked to the executor) so the row
       // ends up with a value distinct from the event payload above. Proves
       // the search consumer reads the row, not the payload.
-      await asRawClient(ctx.db).unsafe(
+      await asRawClient(ctx.db.unsafeRaw("test: raw row update bypassing the executor")).unsafe(
         `UPDATE read_named_search_notes SET label = $1 WHERE id = $2`,
         [ROW_LABEL, event.payload.id],
       );
       return { isSuccess: true as const, data: { id: event.payload.id } };
     },
-    { access: { roles: ["Admin"] } },
+    {
+      access: { roles: ["Admin"] },
+      escapeHatch: { reason: "test: raw row update bypassing the executor" },
+    },
   );
 
   r.writeHandler(

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

@@ -2,18 +2,39 @@ 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 {
+  EscapeHatchReporter,
+  EscapeHatchTarget,
+  MemberReader,
+  SessionUser,
+} from "../../engine/types";
 import type { TenantId } from "../../engine/types/identifiers";
 import { AccessDeniedError, FrameworkReasons } from "../../errors";
 import {
   createGatedIdentitySwitch,
+  createGatedMemberReader,
+  createGatedProjectionReader,
   type IdentitySwitch,
   isIdentitySwitchAllowed,
   isSystemIdentity,
+  type ProjectionReader,
   type WriteAsFn,
   withHookEscapeHatchGrant,
 } from "../system-identity-switch";
 
+function recordingReporter(): {
+  readonly report: EscapeHatchReporter;
+  readonly calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }>;
+} {
+  const calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }> = [];
+  return {
+    report: (kind, reason, target) => {
+      calls.push({ kind, reason, target });
+    },
+    calls,
+  };
+}
+
 const TENANT = "00000000-0000-4000-8000-00000000ab01" as TenantId;
 
 const normalUser: SessionUser = { id: crypto.randomUUID(), tenantId: TENANT, roles: ["User"] };
@@ -224,6 +245,69 @@ describe("createGatedIdentitySwitch", () => {
   });
 });
 
+function makeUngatedProjectionReader(): {
+  readonly ungated: ProjectionReader;
+  readonly mockFn: ReturnType<typeof mock>;
+} {
+  const mockFn = mock(async (_qn: string, _options?: { readonly unsafeAllTenants?: boolean }) => [
+    { ok: true },
+  ]);
+  return { ungated: mockFn as unknown as ProjectionReader, mockFn };
+}
+
+describe("createGatedProjectionReader", () => {
+  test("without a grant, unsafeAllTenants: true throws AccessDeniedError and never calls ungated", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const gated = createGatedProjectionReader('handler "x"', false, ungated);
+
+    let caught: unknown;
+    try {
+      await gated("qp:projection:widgets", { unsafeAllTenants: true });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    const error = caught as AccessDeniedError;
+    expect(error.details).toEqual({ reason: FrameworkReasons.unsafeAllTenantsDenied });
+    expect(mockFn).not.toHaveBeenCalled();
+  });
+
+  test("without the unsafeAllTenants option, calls ungated directly with no report", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedProjectionReader('handler "x"', false, ungated, {
+      reason: "escapeHatch reason",
+      report,
+    });
+
+    await gated("qp:projection:widgets");
+
+    expect(mockFn).toHaveBeenCalledWith("qp:projection:widgets", undefined);
+    expect(calls).toEqual([]);
+  });
+
+  test("with a grant, unsafeAllTenants: true calls ungated and reports exactly once", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedProjectionReader('handler "x"', true, ungated, {
+      reason: 'r.systemScope() feature "widgets"',
+      report,
+    });
+
+    await gated("qp:projection:widgets", { unsafeAllTenants: true });
+
+    expect(mockFn).toHaveBeenCalledWith("qp:projection:widgets", { unsafeAllTenants: true });
+    expect(calls).toEqual([
+      {
+        kind: "unsafe-all-tenants",
+        reason: 'r.systemScope() feature "widgets"',
+        target: undefined,
+      },
+    ]);
+  });
+});
+
 describe("withHookEscapeHatchGrant", () => {
   test("hook without escapeHatch does NOT inherit the handler's SYSTEM grant", async () => {
     const { ungated } = makeUngated();
@@ -403,4 +487,159 @@ describe("withHookEscapeHatchGrant", () => {
     }) as { db: TenantDb };
     expect(hookCtxWithEscapeHatch.db.unsafeRaw("test reason")).toBe(rawDb);
   });
+
+  test("handler-granted queryProjection reader: hook without escapeHatch loses the grant for unsafeAllTenants", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const handlerCtx = {
+      queryProjection: createGatedProjectionReader('handler "outer"', true, ungated),
+    };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", undefined) as {
+      queryProjection: ProjectionReader;
+    };
+
+    await expect(
+      hookCtx.queryProjection("qp:projection:widgets", { unsafeAllTenants: true }),
+    ).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(mockFn).not.toHaveBeenCalled();
+  });
+
+  test("hook's own escapeHatch grants queryProjection's unsafeAllTenants and reports with the hook's reason", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const { report, calls } = recordingReporter();
+    const handlerCtx = {
+      queryProjection: createGatedProjectionReader('handler "outer"', false, ungated, {
+        reason: undefined,
+        report,
+      }),
+    };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", {
+      reason: "hook's own grant",
+    }) as { queryProjection: ProjectionReader };
+
+    await hookCtx.queryProjection("qp:projection:widgets", { unsafeAllTenants: true });
+
+    expect(mockFn).toHaveBeenCalledWith("qp:projection:widgets", { unsafeAllTenants: true });
+    expect(calls).toEqual([
+      { kind: "unsafe-all-tenants", reason: "hook's own grant", target: undefined },
+    ]);
+  });
+});
+
+describe("createGatedIdentitySwitch — escape-hatch reporting", () => {
+  test("granted switch to SYSTEM reports identity-switch once with the target", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, true, ungated, {
+      reason: 'r.systemScope() feature "widgets"',
+      report,
+    });
+
+    await gated.queryAs(systemUserById, "q", {});
+
+    expect(calls).toEqual([
+      {
+        kind: "identity-switch",
+        reason: 'r.systemScope() feature "widgets"',
+        target: { id: systemUserById.id, tenantId: systemUserById.tenantId },
+      },
+    ]);
+  });
+
+  test("self-delegation with a grant reports nothing", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, true, ungated, {
+      reason: "escapeHatch reason",
+      report,
+    });
+
+    await gated.queryAs(normalUser, "q", {});
+
+    expect(calls).toEqual([]);
+  });
+
+  test("a denied switch reports nothing", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, false, ungated, {
+      reason: "escapeHatch reason",
+      report,
+    });
+
+    await expect(gated.queryAs(systemUserById, "q", {})).rejects.toBeInstanceOf(AccessDeniedError);
+
+    expect(calls).toEqual([]);
+  });
+
+  test("hook re-gating via withHookEscapeHatchGrant reports with the HOOK's reason", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    const handlerCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, true, ungated, {
+        reason: "handler's own grant",
+        report,
+      }),
+    };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", { reason: "hook's own grant" });
+    await hookCtx.queryAs(systemUserById, "q", {});
+
+    expect(calls).toEqual([
+      {
+        kind: "identity-switch",
+        reason: "hook's own grant",
+        target: { id: systemUserById.id, tenantId: systemUserById.tenantId },
+      },
+    ]);
+  });
+
+  test("hook re-gates and reports even when the handler itself has no grant (reason: undefined)", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    // Handler has NO grant (hasGrant=false, reason: undefined) — the report fn
+    // must still be attached so a hook's own escapeHatch can use it.
+    const handlerCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, false, ungated, {
+        reason: undefined,
+        report,
+      }),
+    };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", { reason: "hook reason" });
+    await hookCtx.queryAs(systemUserById, "q", {});
+
+    expect(calls).toEqual([
+      {
+        kind: "identity-switch",
+        reason: "hook reason",
+        target: { id: systemUserById.id, tenantId: systemUserById.tenantId },
+      },
+    ]);
+  });
+
+  test("queryAsMember hook re-gates and reports even when the handler itself has no grant", async () => {
+    const ungatedReader: MemberReader = mock(async () => ({ ok: true }));
+    const { report, calls } = recordingReporter();
+    const gatedReader = createGatedMemberReader('handler "outer"', false, ungatedReader, {
+      reason: undefined,
+      report,
+      tenantId: TENANT,
+    });
+    const handlerCtx = { queryAsMember: gatedReader };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", { reason: "hook reason" }) as {
+      queryAsMember: MemberReader;
+    };
+    await hookCtx.queryAsMember(systemUserById.id, "q", {});
+
+    expect(calls).toEqual([
+      {
+        kind: "identity-switch",
+        reason: "hook reason",
+        target: { id: systemUserById.id, tenantId: TENANT },
+      },
+    ]);
+  });
 });

package/src/pipeline/dispatch-query.ts

@@ -1,7 +1,7 @@
 import type { DbRow, DbTx } from "../db/connection";
 import { hasAccess } from "../engine/access";
 import { filterReadFields } from "../engine/field-access";
-import type { SessionUser } from "../engine/types";
+import type { QueryHandlerDef, SessionUser } from "../engine/types";
 import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
 import { assertNoSecretLeak } from "../secrets";
 import type { DispatchContext } from "./dispatch-shared";
@@ -11,6 +11,7 @@ import {
   ensureFeatureEnabled,
   runHandlerInstrumented,
 } from "./dispatch-shared";
+import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction";
 
 // Standalone query execution — used by the public dispatcher.query() and
 // by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
@@ -48,12 +49,11 @@ async function executeQueryInner(
   // unauthorized callers must hit the cap too (otherwise the limit
   // would be a free probe-detector for valid credentials). The
   // resolver throws RateLimitError which the dispatcher's outer
-  // wrapper turns into a 429 response. Inline-skip when the handler
-  // didn't opt in — keeps the hot path zero-cost (no await on a
-  // no-op promise).
-  if (handler.rateLimit !== undefined) {
-    await enforceRateLimit(ctx, handler.rateLimit, type, user);
-  }
+  // wrapper turns into a 429 response. Apps that don't use L3 pay zero
+  // cost for non-systemScope handlers with no rateLimit declared;
+  // systemScope handlers pay one isHandlerSystemScoped lookup to check
+  // whether the default per-tenant limit applies.
+  await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
 
   // Default-deny: missing access rule is treated as "no one has access".
   // The registry boot-validator refuses to register handlers without one,
@@ -79,8 +79,27 @@ async function executeQueryInner(
     typeof parsed.data === "object" &&
     parsed.data !== null &&
     (parsed.data as Record<string, unknown>)["includeDeleted"] === true; // @cast-boundary validated-payload
+
+  // A resolved member (ctx.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
+  return user.origin === "member-resolution"
+    ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) =>
+        runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, readOnlyTx),
+      )
+    : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, tx);
+}
+
+async function runQueryHandler(
+  ctx: DispatchContext,
+  type: string,
+  handler: QueryHandlerDef,
+  payload: unknown,
+  includeDeleted: boolean,
+  user: SessionUser,
+  tx: DbTx | undefined,
+): Promise<unknown> {
+  const { registry } = ctx;
   const handlerContext = await buildHandlerContext(ctx, type, user, tx, undefined, includeDeleted);
-  let result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
+  let result = await handler.handler({ type, payload, user }, handlerContext);
 
   // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data
   // and can merge custom-fields/computed-counts/tags/etc. Each hook is