@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

package/src/pipeline/dispatch-stream.ts

@@ -44,9 +44,7 @@ async function* executeStreamInner(
 
   await ensureFeatureEnabled(ctx, type, user.tenantId);
 
-  if (handler.rateLimit !== undefined) {
-    await enforceRateLimit(ctx, handler.rateLimit, type, user);
-  }
+  await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
 
   if (!hasAccess(user, handler.access)) {
     throw new AccessDeniedError({

package/src/pipeline/dispatch-write.ts

@@ -1,10 +1,11 @@
-import type { DbRow, DbTx } from "../db/connection";
+import type { DbRow, DbRunner, DbTx } from "../db/connection";
 import { selectRowForUpdateById } from "../db/queries/entity-read";
 import { asEntityTableMeta, selectMany } from "../db/query";
 import { buildEntityTable, toSnakeCase } from "../db/table-builder";
+import { tenantDbRunner } from "../db/tenant-db-runner";
 import { hasAccess } from "../engine/access";
 import { ConfigScopes } from "../engine/constants";
-import { checkWriteFieldRoles } from "../engine/field-access";
+import { checkWriteFieldOwnership, checkWriteFieldRoles } from "../engine/field-access";
 import { defineTransitions, guardTransition } from "../engine/state-machine";
 import type { HandlerContext, SessionUser, WriteResult } from "../engine/types";
 import { HookPhases } from "../engine/types";
@@ -28,6 +29,7 @@ import {
   checkFeatureEnabled,
   enforceRateLimit,
   memberResolutionReadOnlyDenied,
+  resolveDbSource,
   runHandlerInstrumented,
   TENANT_TIMEZONE_CONFIG_KEY,
 } from "./dispatch-shared";
@@ -127,6 +129,7 @@ async function runLifecycle(
   handlerContext: HandlerContext,
   user: SessionUser,
   afterCommitHooks: AfterCommitHook[],
+  runner: DbRunner | undefined,
 ): Promise<void> {
   const { lifecycle } = ctx;
   if (!lifecycle) {
@@ -143,7 +146,7 @@ async function runLifecycle(
   // hooks. If a projection apply() throws, the whole tx rolls back — the
   // event and the auto-projection row go with it. Running before the hooks
   // keeps projection state consistent with what the hooks observe.
-  await runProjections(result, handlerContext);
+  await runProjections(result, handlerContext.registry, runner);
 
   if (result.kind === "save") {
     await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
@@ -196,6 +199,14 @@ export async function executeWrite(
   );
 }
 
+function isForeignTenantParentRow(
+  parentRow: Readonly<Record<string, unknown>>,
+  user: SessionUser,
+): boolean {
+  const rowTenantId = parentRow["tenantId"];
+  return typeof rowTenantId === "string" && rowTenantId !== user.tenantId;
+}
+
 // Nested-write orchestration (v1: depth=1, create-only, hasMany-only).
 //
 // When a parent `:create` handler's payload carries values under keys
@@ -286,6 +297,36 @@ export async function executeNestedWrite(
     );
   }
 
+  // A custom create handler may return an existing foreign row; verify it before attaching children.
+  if (!registry.isHandlerSystemScoped(type) && isForeignTenantParentRow(parentRow, user)) {
+    return writeFailure(
+      new AccessDeniedError({
+        message: `nested-write: parent row belongs to another tenant — refusing to attach children to "${type}"`,
+        details: { reason: FrameworkReasons.fieldAccessDenied, handler: type },
+      }),
+    );
+  }
+  const parentEntityName = registry.getHandlerEntity(type);
+  if (parentEntityName) {
+    const parentEntity = registry.getEntity(parentEntityName);
+    if (parentEntity) {
+      const deniedField = checkWriteFieldOwnership(parentEntity, parentRow, user);
+      if (deniedField) {
+        return writeFailure(
+          new AccessDeniedError({
+            message: `nested-write: parent row ownership check failed on field "${deniedField}" of "${type}" — refusing to attach children to a parent row the caller does not own`,
+            i18nKey: "errors.access.fieldDenied",
+            details: {
+              reason: FrameworkReasons.fieldAccessDenied,
+              field: deniedField,
+              handler: type,
+            },
+          }),
+        );
+      }
+    }
+  }
+
   for (const spec of nested.specs) {
     const subRows: Record<string, unknown>[] = [];
     for (let i = 0; i < spec.items.length; i++) {
@@ -341,15 +382,21 @@ async function executeWriteInner(
 
   // Rate-limit gate before access (same reasoning as in executeQueryInner).
   // Throws RateLimitError; the outer wrapper turns it into a 429
-  // WriteFailure via toWriteErrorInfo. Inline-skip when no opt-in —
-  // hot path stays zero-cost.
-  if (handler.rateLimit !== undefined) {
-    try {
-      await enforceRateLimit(ctx, handler.rateLimit, type, user);
-    } catch (e) {
-      if (isKumikoError(e)) return writeFailure(e);
-      throw e;
-    }
+  // WriteFailure via toWriteErrorInfo. 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.
+  try {
+    await enforceRateLimit(
+      ctx,
+      handler.rateLimit,
+      type,
+      user,
+      registry.isHandlerSystemScoped(type),
+    );
+  } catch (e) {
+    if (isKumikoError(e)) return writeFailure(e);
+    throw e;
   }
 
   // Default-deny: missing access rule is treated as "no one has access".
@@ -447,7 +494,7 @@ async function executeWriteInner(
         // active (tests without a DB connection).
         const tableName = asEntityTableMeta(table)?.tableName ?? "";
         const rows = tx
-          ? await selectRowForUpdateById(transitionGuardDb, tableName, id)
+          ? await selectRowForUpdateById(tenantDbRunner(transitionGuardDb), tableName, id)
           : await selectMany(transitionGuardDb, table, { id });
         const row = rows[0];
 
@@ -504,7 +551,8 @@ async function executeWriteInner(
 
   if (result.isSuccess) {
     try {
-      await runLifecycle(ctx, type, result.data, handlerContext, user, afterCommitHooks);
+      const runner = resolveDbSource(ctx, tx);
+      await runLifecycle(ctx, type, result.data, handlerContext, user, afterCommitHooks, runner);
     } catch (e) {
       return writeFailure(wrapToKumiko(e));
     }

package/src/pipeline/dispatcher.ts

@@ -1,5 +1,9 @@
 import type { SseBroker } from "../api/sse-broker";
 import type { buildEntityTable } from "../db/table-builder";
+import {
+  DEPRECATED_CROSS_TENANT_SIGNAL,
+  isDeprecatedCrossTenantHandler,
+} from "../engine/entity-handlers";
 import { TENANT_MEMBERSHIPS_QUERY } from "../engine/extension-names";
 import type { defineTransitions } from "../engine/state-machine";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
@@ -23,6 +27,7 @@ import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shar
 import { resolveAuthClaimsFn } from "./dispatch-shared";
 import { executeStream } from "./dispatch-stream";
 import { type HandlerType, resolveType } from "./dispatcher-utils";
+import { createEscapeHatchReportWindow } from "./escape-hatch-report";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
 import { createMemberReaderFn } from "./member-reader";
@@ -129,6 +134,7 @@ export function createDispatcher(
   // One per dispatcher instance (not a module-level singleton) so caches
   // never leak across separately-booted apps or test stacks.
   const tenantTimezoneCache = createTenantTimezoneCache();
+  const escapeHatchReportWindow = createEscapeHatchReportWindow();
 
   const dispatcherTracer = context.tracer ?? getFallbackTracer();
   const dispatcherMeter = context.meter ?? getFallbackMeter();
@@ -136,6 +142,19 @@ export function createDispatcher(
   // Idempotent: buildServer may have registered them already.
   registerStandardMetrics(dispatcherMeter);
 
+  for (const def of [
+    ...registry.getAllWriteHandlers().values(),
+    ...registry.getAllQueryHandlers().values(),
+  ]) {
+    if (isDeprecatedCrossTenantHandler(def.handler)) {
+      context.log?.warn(DEPRECATED_CROSS_TENANT_SIGNAL, {
+        handler: def.name,
+        migration:
+          'replace crossTenant: true with escapeHatch: { reason: "<why this operator handler reads/writes every tenant>" } (bun scripts/codemod/migrate-cross-tenant.ts)',
+      });
+    }
+  }
+
   const ctx: DispatchContext = {
     registry,
     appContext: context,
@@ -147,6 +166,7 @@ export function createDispatcher(
     tableCache,
     transitionCache,
     tenantTimezoneCache,
+    escapeHatchReportWindow,
     tracer: dispatcherTracer,
     meter: dispatcherMeter,
     membershipQuery,

package/src/pipeline/escape-hatch-report.ts

@@ -0,0 +1,127 @@
+import type {
+  EscapeHatchAuditSink,
+  EscapeHatchKind,
+  EscapeHatchReporter,
+  EscapeHatchTarget,
+  EscapeHatchUseEvent,
+  TenantId,
+} from "../engine/types";
+import type { Logger } from "../logging/types";
+
+export const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
+
+const DEFAULT_WINDOW_MS = 60_000;
+const DEFAULT_MAX_ENTRIES = 1_000;
+
+export type EscapeHatchReportWindow = {
+  shouldReport(key: string, nowMs: number): boolean;
+};
+
+// Dedups identical (handler,kind,reason,tenant,actor,target) reports within the window so hot systemScope queries don't write one row per request.
+export function createEscapeHatchReportWindow(opts?: {
+  readonly windowMs?: number;
+  readonly maxEntries?: number;
+}): EscapeHatchReportWindow {
+  const windowMs = opts?.windowMs ?? DEFAULT_WINDOW_MS;
+  const maxEntries = opts?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  // Map insertion order doubles as recency order: a re-set moves the key to the end.
+  const entries = new Map<string, number>();
+
+  return {
+    shouldReport(key, nowMs) {
+      const expiresAt = entries.get(key);
+      if (expiresAt !== undefined && expiresAt > nowMs) return false;
+      entries.delete(key);
+      entries.set(key, nowMs + windowMs);
+      while (entries.size > maxEntries) {
+        const oldestKey = entries.keys().next().value;
+        if (oldestKey === undefined) break;
+        entries.delete(oldestKey);
+      }
+      return true;
+    },
+  };
+}
+
+// Default window for createEscapeHatchReporter callers that don't pass their own.
+const fallbackReportWindow = createEscapeHatchReportWindow();
+
+const consoleLogger: Logger = {
+  info() {},
+  warn(msg, data) {
+    console.warn(msg, data);
+  },
+  error(msg, data) {
+    console.error(msg, data);
+  },
+  debug() {},
+  child() {
+    return consoleLogger;
+  },
+};
+
+function eventFields(event: EscapeHatchUseEvent): Record<string, unknown> {
+  return {
+    handler: event.handler,
+    kind: event.kind,
+    reason: event.reason,
+    tenantId: event.tenantId,
+    actor: event.actor,
+    ...(event.target && { targetId: event.target.id, targetTenantId: event.target.tenantId }),
+  };
+}
+
+export function reportEscapeHatchUse(
+  event: EscapeHatchUseEvent,
+  deps: { readonly sink?: EscapeHatchAuditSink; readonly log?: Logger },
+): void {
+  const logger = deps.log ?? consoleLogger;
+  const fields = eventFields(event);
+  if (deps.sink) {
+    void deps.sink(event).catch((err: unknown) => {
+      logger.error(`${ESCAPE_HATCH_USED_SIGNAL}: audit sink failed`, {
+        ...fields,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+    return;
+  }
+  logger.warn(ESCAPE_HATCH_USED_SIGNAL, fields);
+}
+
+export function createEscapeHatchReporter(opts: {
+  readonly handler: string;
+  readonly tenantId: TenantId;
+  readonly actor: string;
+  readonly sink?: EscapeHatchAuditSink;
+  readonly log?: Logger;
+  readonly window?: EscapeHatchReportWindow;
+}): EscapeHatchReporter {
+  const window = opts.window ?? fallbackReportWindow;
+
+  return (kind: EscapeHatchKind, reason: string, target?: EscapeHatchTarget) => {
+    const key = JSON.stringify([
+      opts.handler,
+      kind,
+      reason,
+      opts.tenantId,
+      opts.actor,
+      target?.id ?? null,
+      target?.tenantId ?? null,
+    ]);
+    // skip: same (handler, kind, reason, target) already reported within the window — dedup
+    if (!window.shouldReport(key, Date.now())) return;
+    reportEscapeHatchUse(
+      { handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target },
+      { sink: opts.sink, log: opts.log },
+    );
+  };
+}
+
+export function fallbackEscapeHatchReporter(tenantId: TenantId): EscapeHatchReporter {
+  return createEscapeHatchReporter({
+    handler: "<unattributed>",
+    tenantId,
+    actor: "<unattributed>",
+  });
+}

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