@cosmicdrift/kumiko-framework 0.270.0 → 0.274.0

package/src/pipeline/index.ts

@@ -7,6 +7,14 @@ export type { DistributedLock } from "./distributed-lock";
 export { createDistributedLock } from "./distributed-lock";
 export type { EntityCache, EntityCacheOptions } from "./entity-cache";
 export { createEntityCache } from "./entity-cache";
+export type { EscapeHatchReportWindow } from "./escape-hatch-report";
+export {
+  createEscapeHatchReporter,
+  createEscapeHatchReportWindow,
+  ESCAPE_HATCH_USED_SIGNAL,
+  fallbackEscapeHatchReporter,
+  reportEscapeHatchUse,
+} from "./escape-hatch-report";
 export type { ConsumerStatus } from "./event-consumer-state";
 export {
   ConsumerStatuses,

package/src/pipeline/member-read-only-transaction.ts

@@ -0,0 +1,75 @@
+import type { DbTx } from "../db/connection";
+import { extractPgError } from "../db/pg-error";
+import { asRawClient, runInSavepoint, transaction } from "../db/query";
+import { AccessDeniedError, InternalError } from "../errors";
+import {
+  type DispatchContext,
+  memberResolutionReadOnlyDenied,
+  resolveDbSource,
+} from "./dispatch-shared";
+
+const PG_READ_ONLY_SQLSTATE = "25006";
+
+// Bun.SQL surfaces the PG SQLSTATE as `errno` (code stays "ERR_POSTGRES_SERVER_ERROR");
+// postgres.js surfaces it as `code`, possibly one `.cause` layer down (DrizzleQueryError-style wrapping).
+function isReadOnlyTransactionViolation(e: unknown): boolean {
+  if (extractPgError(e)?.code === PG_READ_ONLY_SQLSTATE) return true;
+  if (typeof e !== "object" || e === null) return false;
+  // @cast-boundary error-details — Bun.SQL error shape (errno)
+  if ((e as { errno?: unknown }).errno === PG_READ_ONLY_SQLSTATE) return true;
+  // @cast-boundary error-details — Bun.SQL error shape (errno) under .cause
+  const cause = (e as { cause?: unknown }).cause;
+  if (typeof cause !== "object" || cause === null) return false;
+  return (cause as { errno?: unknown }).errno === PG_READ_ONLY_SQLSTATE;
+}
+
+async function runInDiscardedReadOnlySavepoint<T>(
+  tx: DbTx,
+  fn: (readOnlyTx: DbTx) => Promise<T>,
+): Promise<T> {
+  const discardMarker = {};
+  const settled: { outcome?: { readonly value: T } } = {};
+  try {
+    await runInSavepoint(tx, async (sp) => {
+      // kumiko-lint-ignore raw-sql transaction characteristic, no query helper
+      await asRawClient(sp).unsafe("SET TRANSACTION READ ONLY");
+      // @cast-boundary driver savepoint handle — structurally a DbTx, same shape runInSavepoint's caller relies on
+      settled.outcome = { value: await fn(sp as DbTx) };
+      // Always discarded: RELEASE SAVEPOINT would leave the outer tx read-only too.
+      throw discardMarker;
+    });
+  } catch (e) {
+    if (e !== discardMarker) throw e;
+  }
+  if (!settled.outcome) {
+    throw new InternalError({
+      message: "runInDiscardedReadOnlySavepoint: savepoint ended without settling — this is a bug.",
+    });
+  }
+  return settled.outcome.value;
+}
+
+export async function runInMemberReadOnlyTransaction<T>(
+  ctx: DispatchContext,
+  tx: DbTx | undefined,
+  fn: (readOnlyTx: DbTx) => Promise<T>,
+): Promise<T> {
+  try {
+    if (tx) return await runInDiscardedReadOnlySavepoint(tx, fn);
+    const pool = resolveDbSource(ctx, undefined);
+    if (!pool) {
+      throw new InternalError({
+        message: "ctx.queryAsMember requires a database connection — none is configured.",
+      });
+    }
+    // Savepoint even on the pool path: Postgres rejects a READ WRITE reset (SQLSTATE 25001) inside a subtransaction.
+    return await transaction(pool, (outer) =>
+      // @cast-boundary driver begin() handle — structurally a DbTx, same shape runInSavepoint's caller relies on
+      runInDiscardedReadOnlySavepoint(outer as DbTx, fn),
+    );
+  } catch (e) {
+    if (e instanceof AccessDeniedError) throw e;
+    if (isReadOnlyTransactionViolation(e)) throw memberResolutionReadOnlyDenied(e);
+    throw e;
+  }
+}

package/src/pipeline/msp-rebuild.ts

@@ -7,6 +7,7 @@ import {
 } from "../db/queries/event-consumer";
 import {
   assertLiveColumnsMatchMeta,
+  assertLiveTableHasNoRowLevelSecurity,
   buildShadowTable,
   ensureRebuildSchema,
   rebuildMetaOrThrow,
@@ -149,6 +150,7 @@ export async function rebuildMultiStreamProjection(
       await selectConsumerForUpdate(tx, mspName, SHARED_INSTANCE_SENTINEL);
 
       await assertLiveColumnsMatchMeta(tx, meta, mspName);
+      await assertLiveTableHasNoRowLevelSecurity(tx, meta.tableName, mspName);
       await buildShadowTable(tx, meta);
 
       const subscribedTypes = Object.keys(msp.apply);

package/src/pipeline/projection-rebuild.ts

@@ -8,6 +8,7 @@ import {
 } from "../db/queries/projection-rebuild";
 import {
   assertLiveColumnsMatchMeta,
+  assertLiveTableHasNoRowLevelSecurity,
   assertNoUnreachableLiveRows,
   buildShadowTable,
   type ColumnDriftResult,
@@ -292,6 +293,7 @@ export async function rebuildProjection(
     await db.begin(async (tx: DbTx) => {
       await markProjectionRebuilding(tx, projectionName);
       await assertLiveColumnsMatchMeta(tx, meta, projectionName);
+      await assertLiveTableHasNoRowLevelSecurity(tx, meta.tableName, projectionName);
       await buildShadowTable(tx, meta);
       deps.__test_onBuildShadowTable?.();
 

package/src/pipeline/projections-runner.ts

@@ -1,5 +1,6 @@
 import type { DbRunner } from "../db";
-import type { HandlerContext, LifecycleResult, Registry } from "../engine/types";
+import type { LifecycleResult, Registry } from "../engine/types";
+import { InternalError } from "../errors";
 import type { StoredEvent } from "../event-store";
 
 // Run custom projections for a save or delete result. Lives INSIDE the
@@ -18,23 +19,24 @@ import type { StoredEvent } from "../event-store";
 //   - Projections receive the exact StoredEvent from the executor. If you
 //     hand-craft a SaveContext (tests, non-executor writes), just don't set
 //     `event` and the runner no-ops.
-//   - `tx`-scoped DbRunner is passed via the registered apply() — we reuse
-//     `ctx.db.raw`, which the dispatcher already scoped to the active tx.
+//   - `runner` is the caller's already-resolved DbRunner — projections-runner
+//     has no TenantDb access of its own to derive one from.
 //   - Apply-function throws bubble up unchanged. The dispatcher wraps the
 //     whole lifecycle in a try/catch that rolls the tx back; the event is
 //     gone from the events table just like a rolled-back state change.
-export async function runProjections(result: LifecycleResult, ctx: HandlerContext): Promise<void> {
+export async function runProjections(
+  result: LifecycleResult,
+  registry: Registry,
+  runner: DbRunner | undefined,
+): Promise<void> {
   // skip: hand-crafted result with no event — nothing to project
   if (!result.event) return;
-  // r.systemScope() handlers: ctx.db is fail-closed — custom projections are
-  // framework-wired, not per-handler opt-in, so this reaches for systemDb
-  // itself rather than pushing the concern onto every r.projection() author.
-  const tx = ctx.systemDb
-    ? ctx.systemDb.acknowledgeCrossTenant(
-        `inline projection apply for r.systemScope() write (${result.event.aggregateType})`,
-      ).raw
-    : ctx.db.raw;
-  await runProjectionsForEvent(result.event, ctx.registry, tx);
+  if (!runner) {
+    throw new InternalError({
+      message: `runProjections("${result.event.aggregateType}") requires a database connection — none is configured.`,
+    });
+  }
+  await runProjectionsForEvent(result.event, registry, runner);
 }
 
 // Fire every projection whose source matches the event's aggregate type AND

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

@@ -3,6 +3,8 @@ import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
 import type {
   ActiveMembershipResult,
   EscapeHatchDeclaration,
+  EscapeHatchReporter,
+  HandlerContext,
   LifecycleHookFn,
   MemberReader,
   SessionUser,
@@ -17,7 +19,12 @@ export type ResolveActiveMembershipFn = (
   userId: string,
   tenantId: TenantId,
 ) => Promise<ActiveMembershipResult>;
+export type ProjectionReader = HandlerContext["queryProjection"];
 export type IdentitySwitch = { readonly queryAs: QueryAsFn; readonly writeAs: WriteAsFn };
+export type IdentitySwitchAudit = {
+  readonly reason: string | undefined;
+  readonly report: EscapeHatchReporter;
+};
 
 export function isSystemIdentity(user: SessionUser): boolean {
   return user.id === SYSTEM_USER_ID || user.roles.includes(SYSTEM_ROLE);
@@ -76,36 +83,69 @@ export function identitySwitchDenied(callerLabel: string, asUser: SessionUser):
   });
 }
 
+export function unsafeAllTenantsDenied(callerLabel: string): AccessDeniedError {
+  return new AccessDeniedError({
+    message:
+      `${callerLabel} may not call ctx.queryProjection(..., { unsafeAllTenants: true }) — declare ` +
+      "r.systemScope() or escapeHatch: { reason } on it",
+    details: { reason: FrameworkReasons.unsafeAllTenantsDenied },
+  });
+}
+
 type GatedIdentitySwitchSource = {
   readonly ungated: IdentitySwitch;
   readonly caller: SessionUser | undefined;
+  readonly report?: EscapeHatchReporter;
+};
+
+type MemberReaderAudit = IdentitySwitchAudit & { readonly tenantId: TenantId };
+
+type GatedMemberReaderSource = {
+  readonly ungated: MemberReader;
+  readonly audit?: MemberReaderAudit;
 };
 
 // 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>();
+const ungatedMemberReaderByGated = new WeakMap<MemberReader, GatedMemberReaderSource>();
+
+function reportGrantedSwitch(
+  caller: SessionUser | undefined,
+  asUser: SessionUser,
+  hasGrant: boolean,
+  audit: IdentitySwitchAudit | undefined,
+): void {
+  // skip: no audit wired, switch wasn't grant-gated, or grant carries no reason to report
+  if (!audit || !hasGrant || audit.reason === undefined) return;
+  // skip: caller switching to themselves isn't a privilege escalation worth auditing
+  if (caller !== undefined && isSelfDelegation(caller, asUser)) return;
+  audit.report("identity-switch", audit.reason, { id: asUser.id, tenantId: asUser.tenantId });
+}
 
 export function createGatedIdentitySwitch(
   callerLabel: string,
   caller: SessionUser | undefined,
   hasGrant: boolean,
   ungated: IdentitySwitch,
+  audit?: IdentitySwitchAudit,
 ): IdentitySwitch {
   const queryAs: QueryAsFn = async (asUser, qn, payload) => {
     if (!isIdentitySwitchAllowed(caller, asUser, hasGrant)) {
       throw identitySwitchDenied(callerLabel, asUser);
     }
+    reportGrantedSwitch(caller, asUser, hasGrant, audit);
     return ungated.queryAs(asUser, qn, payload);
   };
   const writeAs: WriteAsFn = async (asUser, qn, payload) => {
     if (!isIdentitySwitchAllowed(caller, asUser, hasGrant)) {
       throw identitySwitchDenied(callerLabel, asUser);
     }
+    reportGrantedSwitch(caller, asUser, hasGrant, audit);
     return ungated.writeAs(asUser, qn, payload);
   };
   const gated: IdentitySwitch = { queryAs, writeAs };
-  const source: GatedIdentitySwitchSource = { ungated, caller };
+  const source: GatedIdentitySwitchSource = { ungated, caller, report: audit?.report };
   sourceByGated.set(queryAs, source);
   sourceByGated.set(writeAs, source);
   return gated;
@@ -117,20 +157,56 @@ export function createGatedMemberReader(
   callerLabel: string,
   allowSystemIdentity: boolean,
   ungated: MemberReader,
+  audit?: MemberReaderAudit,
 ): MemberReader {
   const gated: MemberReader = async (userId, qn, payload) => {
     if (!allowSystemIdentity) throw systemIdentitySwitchDenied(callerLabel);
+    if (audit?.reason !== undefined) {
+      audit.report("identity-switch", audit.reason, { id: userId, tenantId: audit.tenantId });
+    }
     return ungated(userId, qn, payload);
   };
-  ungatedMemberReaderByGated.set(gated, ungated);
+  ungatedMemberReaderByGated.set(gated, { ungated, audit });
+  return gated;
+}
+
+type GatedProjectionReaderSource = {
+  readonly ungated: ProjectionReader;
+  readonly report?: EscapeHatchReporter;
+};
+
+// Same idea, for ctx.queryProjection — a single function rather than a pair.
+const ungatedProjectionReaderByGated = new WeakMap<ProjectionReader, GatedProjectionReaderSource>();
+
+// ctx.queryProjection's gate: only { unsafeAllTenants: true } is grant-checked —
+// a plain call always passes through, tenant-scoped by the projection's own table.
+export function createGatedProjectionReader(
+  callerLabel: string,
+  hasGrant: boolean,
+  ungated: ProjectionReader,
+  audit?: IdentitySwitchAudit,
+): ProjectionReader {
+  const gated = async <T = Record<string, unknown>>(
+    qualifiedName: string,
+    options?: { readonly unsafeAllTenants?: boolean },
+  ): Promise<readonly T[]> => {
+    if (options?.unsafeAllTenants === true) {
+      if (!hasGrant) throw unsafeAllTenantsDenied(callerLabel);
+      if (audit?.reason !== undefined) {
+        audit.report("unsafe-all-tenants", audit.reason);
+      }
+    }
+    return ungated<T>(qualifiedName, options);
+  };
+  ungatedProjectionReaderByGated.set(gated, { ungated, report: audit?.report });
   return gated;
 }
 
 function readIdentitySwitchFn<
-  TFn extends QueryAsFn | WriteAsFn | ResolveActiveMembershipFn | MemberReader,
+  TFn extends QueryAsFn | WriteAsFn | ResolveActiveMembershipFn | MemberReader | ProjectionReader,
 >(
   context: object,
-  key: "queryAs" | "writeAs" | "resolveActiveMembership" | "queryAsMember",
+  key: "queryAs" | "writeAs" | "resolveActiveMembership" | "queryAsMember" | "queryProjection",
 ): TFn | undefined {
   if (!(key in context)) return undefined;
   const value = (context as Record<string, unknown>)[key];
@@ -195,7 +271,15 @@ function gatedIdentitySwitchFields(
   const ungatedWriteAs = ctxWriteAs && (writeSource?.ungated.writeAs ?? ctxWriteAs);
   const ungated = fallbackUngatedIdentitySwitch(callerLabel, ungatedQueryAs, ungatedWriteAs);
   const caller = resolveDispatcherCaller(querySource, writeSource);
-  const gated = createGatedIdentitySwitch(callerLabel, caller, escapeHatch !== undefined, ungated);
+  const report = (querySource ?? writeSource)?.report;
+  const audit = report ? { reason: escapeHatch?.reason, report } : undefined;
+  const gated = createGatedIdentitySwitch(
+    callerLabel,
+    caller,
+    escapeHatch !== undefined,
+    ungated,
+    audit,
+  );
   return {
     ...(ctxQueryAs && { queryAs: gated.queryAs }),
     ...(ctxWriteAs && { writeAs: gated.writeAs }),
@@ -210,9 +294,34 @@ function gatedMemberReaderField(
   ctxQueryAsMember: MemberReader | undefined,
 ): { queryAsMember?: MemberReader } {
   if (!ctxQueryAsMember) return {};
-  const ungated = ungatedMemberReaderByGated.get(ctxQueryAsMember) ?? ctxQueryAsMember;
+  const source = ungatedMemberReaderByGated.get(ctxQueryAsMember);
+  const ungated = source?.ungated ?? ctxQueryAsMember;
+  const audit = source?.audit
+    ? { reason: escapeHatch?.reason, report: source.audit.report, tenantId: source.audit.tenantId }
+    : undefined;
+  return {
+    queryAsMember: createGatedMemberReader(callerLabel, escapeHatch !== undefined, ungated, audit),
+  };
+}
+
+// Re-gates ctx.queryProjection under the hook's own escapeHatch, same
+// re-gating rule as the other fields below — see withHookEscapeHatchGrant.
+function gatedProjectionReaderField(
+  callerLabel: string,
+  escapeHatch: EscapeHatchDeclaration | undefined,
+  ctxQueryProjection: ProjectionReader | undefined,
+): { queryProjection?: ProjectionReader } {
+  if (!ctxQueryProjection) return {};
+  const source = ungatedProjectionReaderByGated.get(ctxQueryProjection);
+  const ungated = source?.ungated ?? ctxQueryProjection;
+  const audit = source?.report ? { reason: escapeHatch?.reason, report: source.report } : undefined;
   return {
-    queryAsMember: createGatedMemberReader(callerLabel, escapeHatch !== undefined, ungated),
+    queryProjection: createGatedProjectionReader(
+      callerLabel,
+      escapeHatch !== undefined,
+      ungated,
+      audit,
+    ),
   };
 }
 
@@ -228,6 +337,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
     "resolveActiveMembership",
   );
   const ctxQueryAsMember = readIdentitySwitchFn<MemberReader>(context, "queryAsMember");
+  const ctxQueryProjection = readIdentitySwitchFn<ProjectionReader>(context, "queryProjection");
   const ctxDb = readDbLikeValue(context, "db");
   const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
   if (
@@ -235,6 +345,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
     !ctxWriteAs &&
     !ctxResolveActiveMembership &&
     !ctxQueryAsMember &&
+    !ctxQueryProjection &&
     !ctxDb &&
     !ctxDbOutsideTransaction
   ) {
@@ -249,6 +360,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
         resolveActiveMembership: deniedResolveActiveMembership(callerLabel),
       }),
     ...gatedMemberReaderField(callerLabel, escapeHatch, ctxQueryAsMember),
+    ...gatedProjectionReaderField(callerLabel, escapeHatch, ctxQueryProjection),
     // @cast-boundary engine-bridge — withUnsafeRawGrant passes non-TenantDb values (e.g. a guard Proxy) through unchanged.
     ...(ctxDb && { db: withUnsafeRawGrant(ctxDb as TenantDb, escapeHatch) }),
     ...(ctxDbOutsideTransaction && {
@@ -257,7 +369,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
   };
 }
 
-// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.db/ctx.dbOutsideTransaction instead of inheriting the handler's grant.
+// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.queryProjection/ctx.db/ctx.dbOutsideTransaction instead of inheriting the handler's grant.
 export function bindHookEscapeHatchGrant(
   fn: LifecycleHookFn,
   label: string,