@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/src/pipeline/__tests__/query-projection.integration.test.ts

@@ -1,7 +1,8 @@
-// C1 — ctx.queryProjection: read projection tables by qualified name.
+// C1/fw#2913 — ctx.queryProjection: read projection tables by qualified name.
 // Framework-level read surface so features don't have to import projection
 // drizzle-tables directly. Auto-filters by tenant_id when the projection
-// table carries that column.
+// table carries that column; { unsafeAllTenants: true } opts out but needs a
+// grant — r.systemScope() or a declared escapeHatch on the handler.
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
 import { z } from "zod";
@@ -11,10 +12,12 @@ import {
   text as pgText,
   uuid as pgUuid,
 } from "../../db/dialect";
+import { defineUnmanagedTable } from "../../db/entity-table-meta";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { insertOne } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
+import type { EscapeHatchUseEvent, ProjectionTable } from "../../engine/types";
 import {
   resetEventStore,
   setupTestStack,
@@ -43,6 +46,19 @@ const systemScopedTable = pgTable("read_qp_widget_audit", {
   label: pgText("label").notNull(),
 });
 
+// Plain EntityTableMeta table (no SchemaTable symbols) — exercises
+// hasTenantColumn's meta-fallback branch instead of the drizzle-symbol path.
+const entityMetaWidgetTable = defineUnmanagedTable({
+  tableName: "store_qp_widget_meta",
+  columns: [
+    { name: "widget_id", pgType: "uuid", notNull: true, primaryKey: true },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "label", pgType: "text", notNull: true },
+  ],
+});
+
+const UNSAFE_ALL_TENANTS_REASON = "fw#2913 test — cross-tenant widget sweep";
+
 const qpFeature = defineFeature("qp", (r) => {
   r.entity("qp-widget", widgetEntity);
 
@@ -77,6 +93,24 @@ const qpFeature = defineFeature("qp", (r) => {
     },
   });
 
+  r.projection({
+    name: "widget-count-entitymeta",
+    source: "qp-widget",
+    // @cast-boundary test-fixture — a plain EntityTableMeta lacks SchemaTable's
+    // drizzle symbols; asEntityTableMeta()'s fallback branch reads it directly.
+    table: entityMetaWidgetTable as unknown as ProjectionTable,
+    apply: {
+      "qp-widget.created": async (event, tx) => {
+        const p = event.payload as { name?: string };
+        await insertOne(tx, entityMetaWidgetTable, {
+          widgetId: event.aggregateId,
+          tenantId: event.tenantId,
+          label: p.name ?? "?",
+        });
+      },
+    },
+  });
+
   const executor = createEventStoreExecutor(widgetTable, widgetEntity, {
     entityName: "qp-widget",
   });
@@ -92,7 +126,7 @@ const qpFeature = defineFeature("qp", (r) => {
     "widget:list-tenant",
     z.object({}),
     async (_query, ctx) => ctx.queryProjection("qp:projection:widget-count-tenant"),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.queryHandler(
@@ -102,14 +136,56 @@ const qpFeature = defineFeature("qp", (r) => {
       ctx.queryProjection("qp:projection:widget-audit", {
         unsafeAllTenants: query.payload.unsafeAllTenants ?? false,
       }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.queryHandler(
     "widget:list-ghost",
     z.object({}),
     async (_query, ctx) => ctx.queryProjection("qp:projection:does-not-exist"),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+
+  r.queryHandler(
+    "widget:list-tenant-escape-hatch",
+    z.object({}),
+    async (_query, ctx) =>
+      ctx.queryProjection("qp:projection:widget-count-tenant", { unsafeAllTenants: true }),
+    {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      escapeHatch: { reason: UNSAFE_ALL_TENANTS_REASON },
+    },
+  );
+
+  r.queryHandler(
+    "widget:list-entitymeta",
+    z.object({}),
+    async (_query, ctx) => ctx.queryProjection("qp:projection:widget-count-entitymeta"),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+
+  r.queryHandler(
+    "widget:list-tenant-untyped-payload",
+    z.object({ unsafeAllTenants: z.unknown() }),
+    async (query, ctx) =>
+      ctx.queryProjection("qp:projection:widget-count-tenant", {
+        // @cast-boundary test-fixture — deliberately not the literal boolean `true`,
+        // proving a truthy-but-not-strictly-true value still tenant-filters.
+        unsafeAllTenants: query.payload.unsafeAllTenants as boolean,
+      }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+});
+
+const qpSystemFeature = defineFeature("qp-system", (r) => {
+  r.systemScope();
+
+  r.queryHandler(
+    "widget:list-tenant-systemscope",
+    z.object({}),
+    async (_query, ctx) =>
+      ctx.queryProjection("qp:projection:widget-count-tenant", { unsafeAllTenants: true }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 
@@ -120,8 +196,25 @@ const otherTenantAdmin = {
   tenantId: "00000000-0000-4000-8000-0000000000b0" as const,
 };
 
+function errorReason(details: unknown): string | undefined {
+  if (!details || typeof details !== "object" || !("reason" in details)) return undefined;
+  return typeof details.reason === "string" ? details.reason : undefined;
+}
+
+function recordingSink(events: EscapeHatchUseEvent[]) {
+  return async (event: EscapeHatchUseEvent) => {
+    events.push(event);
+  };
+}
+
+const escapeHatchEvents: EscapeHatchUseEvent[] = [];
+
 beforeAll(async () => {
-  stack = await setupTestStack({ features: [qpFeature], systemHooks: [] });
+  stack = await setupTestStack({
+    features: [qpFeature, qpSystemFeature],
+    systemHooks: [],
+    extraContext: { _escapeHatchAuditSink: recordingSink(escapeHatchEvents) },
+  });
   await unsafeCreateEntityTable(stack.db, widgetEntity, "qp-widget");
 });
 
@@ -130,10 +223,12 @@ afterAll(async () => {
 });
 
 afterEach(async () => {
+  escapeHatchEvents.length = 0;
   await resetEventStore(stack, [
     "read_qp_widgets",
     "read_qp_widget_count_tenant",
     "read_qp_widget_audit",
+    "store_qp_widget_meta",
   ]);
 });
 
@@ -173,24 +268,18 @@ describe("ctx.queryProjection", () => {
     expect(rows.map((r) => r.label).sort()).toEqual(["X", "Y"]);
   });
 
-  test("unsafeAllTenants=true bypasses tenant filter on tenant-scoped projection", async () => {
-    // Repurpose list-system by passing unsafeAllTenants=true — but list-system is
-    // already no-tenant-column. The semantic matters when a projection HAS
-    // tenant_id but the handler wants a cross-tenant sweep (audit). We
-    // exercise that contract via a direct queryProjection call here.
+  test("unsafeAllTenants=true without a grant is denied — no cross-tenant read", async () => {
     await stack.http.writeOk("qp:write:widget:create", { name: "AA" }, admin);
     await stack.http.writeOk("qp:write:widget:create", { name: "BB" }, otherTenantAdmin);
 
-    // The server exposes list-tenant with no opt-out, so assert the raw
-    // helper path via a one-shot handler:
-    // (We could add an "override" handler instead, but keeping the feature
-    //  surface small — assert against the two query handlers we have.)
-    const sys = await stack.http.queryOk<Array<{ label: string }>>(
+    const err = await stack.http.queryErr(
       "qp:query:widget:list-system",
       { unsafeAllTenants: true },
       admin,
     );
-    expect(sys).toHaveLength(2);
+    expect(err.httpStatus).toBe(403);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("unsafe_all_tenants_denied");
   });
 
   test("unknown projection name throws with a helpful error", async () => {
@@ -199,4 +288,70 @@ describe("ctx.queryProjection", () => {
     const body = (await res.json()) as { error?: { message?: string } };
     expect(body.error?.message).toMatch(/projection not registered|does-not-exist/);
   });
+
+  test("escapeHatch grant lets unsafeAllTenants=true read cross-tenant, reporting exactly one unsafe-all-tenants event", async () => {
+    await stack.http.writeOk("qp:write:widget:create", { name: "AA" }, admin);
+    await stack.http.writeOk("qp:write:widget:create", { name: "BB" }, otherTenantAdmin);
+
+    const rows = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp:query:widget:list-tenant-escape-hatch",
+      {},
+      admin,
+    );
+    expect(rows.map((r) => r.label).sort()).toEqual(["AA", "BB"]);
+
+    const matches = escapeHatchEvents.filter((e) => e.kind === "unsafe-all-tenants");
+    expect(matches).toEqual([
+      {
+        handler: "qp:query:widget:list-tenant-escape-hatch",
+        kind: "unsafe-all-tenants",
+        reason: UNSAFE_ALL_TENANTS_REASON,
+        tenantId: admin.tenantId,
+        actor: admin.id,
+      },
+    ]);
+  });
+
+  test("r.systemScope() grants unsafeAllTenants=true without a declared escapeHatch", async () => {
+    await stack.http.writeOk("qp:write:widget:create", { name: "CC" }, admin);
+    await stack.http.writeOk("qp:write:widget:create", { name: "DD" }, otherTenantAdmin);
+
+    const rows = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp-system:query:widget:list-tenant-systemscope",
+      {},
+      admin,
+    );
+    expect(rows.map((r) => r.label).sort()).toEqual(["CC", "DD"]);
+  });
+
+  test("a plain EntityTableMeta projection table is tenant-filtered without unsafeAllTenants", async () => {
+    await stack.http.writeOk("qp:write:widget:create", { name: "EE" }, admin);
+    await stack.http.writeOk("qp:write:widget:create", { name: "FF" }, otherTenantAdmin);
+
+    const forAdmin = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp:query:widget:list-entitymeta",
+      {},
+      admin,
+    );
+    expect(forAdmin.map((r) => r.label)).toEqual(["EE"]);
+
+    const forOther = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp:query:widget:list-entitymeta",
+      {},
+      otherTenantAdmin,
+    );
+    expect(forOther.map((r) => r.label)).toEqual(["FF"]);
+  });
+
+  test("a truthy-but-not-true unsafeAllTenants payload still tenant-filters (no bypass, no grant)", async () => {
+    await stack.http.writeOk("qp:write:widget:create", { name: "GG" }, admin);
+    await stack.http.writeOk("qp:write:widget:create", { name: "HH" }, otherTenantAdmin);
+
+    const rows = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp:query:widget:list-tenant-untyped-payload",
+      { unsafeAllTenants: "yes" },
+      admin,
+    );
+    expect(rows.map((r) => r.label)).toEqual(["GG"]);
+  });
 });

package/src/pipeline/__tests__/rate-limit-default.integration.test.ts

@@ -0,0 +1,118 @@
+// fw#2861 — systemScope handlers get a default per-tenant rate limit unless
+// they declare their own or opt out. Full-stack proof via setupTestStack +
+// real HTTP (stack.http.write) — never createTestDispatcher. Modelled on
+// rate-limit/__tests__/dispatcher-l3.integration.test.ts.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { createSystemUser, defineFeature } from "../../engine";
+import type { RateLimitConfig, RateLimitDecision, RateLimitResolver } from "../../rate-limit";
+import { createTestUser, setupTestStack, type TestStack, testTenantId } from "../../stack";
+
+function fakeResolver(): {
+  readonly resolver: RateLimitResolver;
+  readonly calls: Array<{ bucket: string; config: RateLimitConfig }>;
+} {
+  const calls: Array<{ bucket: string; config: RateLimitConfig }> = [];
+  const decision = (config: RateLimitConfig): RateLimitDecision => ({
+    allowed: true,
+    limit: config.limit,
+    remaining: config.limit - 1,
+    retryAfterSeconds: 0,
+    windowSeconds: config.windowSeconds,
+    // @cast-boundary test-fixture — resetAt is never read by the assertions below
+    resetAt: undefined as unknown as RateLimitDecision["resetAt"],
+  });
+  const resolver: RateLimitResolver = {
+    check: async (bucket, config) => {
+      calls.push({ bucket, config });
+      return decision(config);
+    },
+    enforce: async (bucket, config) => {
+      calls.push({ bucket, config });
+      return decision(config);
+    },
+    peek: async (bucket, config) => {
+      calls.push({ bucket, config: { ...config } });
+      return decision({ ...config, cost: undefined });
+    },
+  };
+  return { resolver, calls };
+}
+
+const rlDefaultFeature = defineFeature("rl-default", (r) => {
+  r.systemScope();
+
+  r.writeHandler("explicit", z.object({}), async () => ({ isSuccess: true as const, data: {} }), {
+    access: { roles: ["Admin"] },
+    rateLimit: { per: "tenant", limit: 2, windowSeconds: 60 },
+  });
+
+  r.writeHandler(
+    "implicit-default",
+    z.object({}),
+    async () => ({ isSuccess: true as const, data: {} }),
+    {
+      access: { roles: ["Admin"] },
+    },
+  );
+
+  r.writeHandler(
+    "as-system-probe",
+    z.object({}),
+    async (event, ctx) => {
+      const sysUser = createSystemUser(event.user.tenantId);
+      const res = await ctx.writeAs(sysUser, "rl-default:write:implicit-default", {});
+      return { isSuccess: true as const, data: res };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+let stack: TestStack;
+let calls: Array<{ bucket: string; config: RateLimitConfig }>;
+const TENANT = testTenantId(9201);
+const admin = createTestUser({ tenantId: TENANT, roles: ["Admin"] });
+
+beforeAll(async () => {
+  const { resolver, calls: recorded } = fakeResolver();
+  calls = recorded;
+  stack = await setupTestStack({
+    features: [rlDefaultFeature],
+    extraContext: { rateLimit: resolver },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("systemScope default rate limit (fw#2861)", () => {
+  test("explicit rateLimit still wins over the systemScope default", async () => {
+    calls.length = 0;
+    const res = await stack.http.write("rl-default:write:explicit", {}, admin);
+    expect(res.status).toBe(200);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`tenant:${TENANT}`);
+    expect(calls[0]?.config).toEqual({ limit: 2, windowSeconds: 60, cost: undefined });
+  });
+
+  test("no declared rateLimit on a systemScope handler -> the default {per:tenant+handler,limit:600,windowSeconds:60} fires", async () => {
+    calls.length = 0;
+    const res = await stack.http.write("rl-default:write:implicit-default", {}, admin);
+    expect(res.status).toBe(200);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`tenant+handler:${TENANT}:rl-default:write:implicit-default`);
+    expect(calls[0]?.config).toEqual({ limit: 600, windowSeconds: 60, cost: undefined });
+  });
+
+  test("a SYSTEM-identity caller (ctx.writeAs) never touches the resolver", async () => {
+    calls.length = 0;
+    const res = await stack.http.write("rl-default:write:as-system-probe", {}, admin);
+    expect(res.status).toBe(200);
+    // One call for the probe handler's own dispatch (bucket = admin's tenant+handler),
+    // NONE for the inner SYSTEM-identity writeAs to implicit-default.
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`tenant+handler:${TENANT}:rl-default:write:as-system-probe`);
+  });
+});

package/src/pipeline/__tests__/rate-limit-default.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import type { Temporal } from "temporal-polyfill";
+import { createSystemUser } from "../../engine";
+import type { RateLimitConfig, RateLimitDecision, RateLimitResolver } from "../../rate-limit";
+import { createTestUser, testTenantId } from "../../stack";
+import type { DispatchContext } from "../dispatch-shared";
+import { enforceRateLimit } from "../dispatch-shared";
+
+const TENANT = testTenantId(9001);
+
+function fakeResolver(): {
+  readonly resolver: RateLimitResolver;
+  readonly calls: Array<{ bucket: string; config: RateLimitConfig }>;
+} {
+  const calls: Array<{ bucket: string; config: RateLimitConfig }> = [];
+  const decision: RateLimitDecision = {
+    allowed: true,
+    limit: 0,
+    remaining: 0,
+    retryAfterSeconds: 0,
+    windowSeconds: 0,
+    resetAt: {} as Temporal.Instant,
+  };
+  const resolver: RateLimitResolver = {
+    check: async (bucket, config) => {
+      calls.push({ bucket, config });
+      return { ...decision, limit: config.limit, windowSeconds: config.windowSeconds };
+    },
+    enforce: async (bucket, config) => {
+      calls.push({ bucket, config });
+      return { ...decision, limit: config.limit, windowSeconds: config.windowSeconds };
+    },
+    peek: async (bucket, config) => {
+      calls.push({ bucket, config: { ...config } });
+      return { ...decision, limit: config.limit, windowSeconds: config.windowSeconds };
+    },
+  };
+  return { resolver, calls };
+}
+
+function fakeCtx(rateLimit: RateLimitResolver | undefined): DispatchContext {
+  return {
+    appContext: { rateLimit },
+  } as unknown as DispatchContext; // @cast-boundary test-fixture — enforceRateLimit only reads ctx.appContext
+}
+
+describe("enforceRateLimit — systemScope default", () => {
+  test("systemScope handler, no declared rateLimit, resolver configured, regular user -> enforces the default per-tenant+handler limit", async () => {
+    const { resolver, calls } = fakeResolver();
+    const user = createTestUser({ tenantId: TENANT });
+
+    await enforceRateLimit(fakeCtx(resolver), undefined, "some:write:handler", user, true);
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`tenant+handler:${TENANT}:some:write:handler`);
+    expect(calls[0]?.config).toEqual({ limit: 600, windowSeconds: 60, cost: undefined });
+  });
+
+  test("systemScope handler, SYSTEM-identity caller -> never touches the resolver", async () => {
+    const { resolver, calls } = fakeResolver();
+    const systemUser = createSystemUser(TENANT);
+
+    await enforceRateLimit(fakeCtx(resolver), undefined, "some:write:handler", systemUser, true);
+
+    expect(calls).toHaveLength(0);
+  });
+
+  test("systemScope handler, no resolver configured -> no-op, no throw", async () => {
+    const user = createTestUser({ tenantId: TENANT });
+
+    await expect(
+      enforceRateLimit(fakeCtx(undefined), undefined, "some:write:handler", user, true),
+    ).resolves.toBeUndefined();
+  });
+
+  test("systemScope handler with an explicit rateLimit -> that option is enforced, not the default", async () => {
+    const { resolver, calls } = fakeResolver();
+    const user = createTestUser({ tenantId: TENANT });
+
+    await enforceRateLimit(
+      fakeCtx(resolver),
+      { per: "user", limit: 3, windowSeconds: 10 },
+      "some:write:handler",
+      user,
+      true,
+    );
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`user:${user.id}`);
+    expect(calls[0]?.config).toEqual({ limit: 3, windowSeconds: 10, cost: undefined });
+  });
+
+  test("systemScope handler with rateLimit: { disabled: true, reason } -> never enforced, no error", async () => {
+    const { resolver, calls } = fakeResolver();
+    const user = createTestUser({ tenantId: TENANT });
+
+    await expect(
+      enforceRateLimit(
+        fakeCtx(resolver),
+        { disabled: true, reason: "ops replay path" },
+        "some:write:handler",
+        user,
+        true,
+      ),
+    ).resolves.toBeUndefined();
+    expect(calls).toHaveLength(0);
+  });
+
+  test("non-systemScope handler, no declared rateLimit -> never enforced (unchanged baseline behavior)", async () => {
+    const { resolver, calls } = fakeResolver();
+    const user = createTestUser({ tenantId: TENANT });
+
+    await enforceRateLimit(fakeCtx(resolver), undefined, "some:write:handler", user, false);
+
+    expect(calls).toHaveLength(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(