@cosmicdrift/kumiko-framework 0.304.0 → 0.305.0

package/src/pipeline/dispatch-write.ts

@@ -22,7 +22,7 @@ import {
   writeFailure,
 } from "../errors";
 import { assertNoSecretLeak } from "../secrets";
-import type { DispatchContext } from "./dispatch-shared";
+import type { DispatchContext, WriteOrigin } from "./dispatch-shared";
 import {
   buildHandlerContext,
   CONFIG_WRITE_RESET_TYPE,
@@ -129,6 +129,7 @@ async function runLifecycle(
   data: unknown,
   handlerContext: HandlerContext,
   user: SessionUser,
+  origin: WriteOrigin,
   afterCommitHooks: AfterCommitHook[],
   runner: DbRunner | undefined,
 ): Promise<void> {
@@ -156,6 +157,7 @@ async function runLifecycle(
         ctx,
         type,
         user,
+        origin,
         undefined,
         afterCommitHooks,
       );
@@ -169,6 +171,7 @@ async function runLifecycle(
         ctx,
         type,
         user,
+        origin,
         undefined,
         afterCommitHooks,
       );
@@ -192,11 +195,12 @@ export async function executeWrite(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
   tx: DbTx | undefined,
   afterCommitHooks: AfterCommitHook[],
 ): Promise<WriteResult> {
   return runHandlerInstrumented(ctx, type, "write", user, () =>
-    executeWriteInner(ctx, type, payload, user, tx, afterCommitHooks),
+    executeWriteInner(ctx, type, payload, user, origin, tx, afterCommitHooks),
   );
 }
 
@@ -227,12 +231,13 @@ export async function executeNestedWrite(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
   tx: DbTx | undefined,
   afterCommitHooks: AfterCommitHook[],
 ): Promise<WriteResult> {
   const { registry } = ctx;
   const nested = extractNestedSpecs(type, payload, registry);
-  if (!nested) return executeWrite(ctx, type, payload, user, tx, afterCommitHooks);
+  if (!nested) return executeWrite(ctx, type, payload, user, origin, tx, afterCommitHooks);
 
   // Pre-flight client-shape checks. Merge non-array issues (collected up
   // front by extractNestedSpecs) with fk-injection issues into one error
@@ -264,6 +269,7 @@ export async function executeNestedWrite(
     type,
     nested.cleanPayload,
     user,
+    origin,
     tx,
     afterCommitHooks,
   );
@@ -339,6 +345,7 @@ export async function executeNestedWrite(
         spec.subType,
         subPayload,
         user,
+        origin,
         tx,
         afterCommitHooks,
       );
@@ -363,6 +370,7 @@ async function executeWriteInner(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
   tx: DbTx | undefined,
   afterCommitHooks: AfterCommitHook[],
 ): Promise<WriteResult> {
@@ -461,7 +469,7 @@ async function executeWriteInner(
     }
   }
 
-  const handlerContext = await buildHandlerContext(ctx, type, user, tx, afterCommitHooks);
+  const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks);
 
   // Auto transition guard: if entity has transitions and handler doesn't skip it.
   // Reads via the guard's own db handle — for r.systemScope() handlers
@@ -553,7 +561,16 @@ async function executeWriteInner(
   if (result.isSuccess) {
     try {
       const runner = resolveDbSource(ctx, tx);
-      await runLifecycle(ctx, type, result.data, handlerContext, user, afterCommitHooks, runner);
+      await runLifecycle(
+        ctx,
+        type,
+        result.data,
+        handlerContext,
+        user,
+        origin,
+        afterCommitHooks,
+        runner,
+      );
     } catch (e) {
       return writeFailure(wrapToKumiko(e));
     }

package/src/pipeline/dispatcher.ts

@@ -32,6 +32,7 @@ import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
 import { createMemberReaderFn } from "./member-reader";
 import { createTenantTimezoneCache } from "./tenant-timezone-cache";
+import { rootWriteOrigin } from "./write-origin";
 
 // Re-export for callers that reach for dispatcher-adjacent types (tests,
 // HTTP-layer stubs) — dispatch consumes these, grouping the type-surface
@@ -182,9 +183,15 @@ export function createDispatcher(
 
     batch: (commands, user, requestId?) => runBatch(ctx, commands, user, requestId),
 
-    query: (typeOrRef, payload, user) => executeQuery(ctx, resolveType(typeOrRef), payload, user),
+    query: (typeOrRef, payload, user) => {
+      const type = resolveType(typeOrRef);
+      return executeQuery(ctx, type, payload, user, rootWriteOrigin(registry, type, user));
+    },
 
-    stream: (typeOrRef, payload, user) => executeStream(ctx, resolveType(typeOrRef), payload, user),
+    stream: (typeOrRef, payload, user) => {
+      const type = resolveType(typeOrRef);
+      return executeStream(ctx, type, payload, user, rootWriteOrigin(registry, type, user));
+    },
 
     async command(typeOrRef, payload, user) {
       const type = resolveType(typeOrRef);

package/src/pipeline/member-reader.ts

@@ -15,6 +15,7 @@ import {
 import { executeQuery } from "./dispatch-query";
 import { type DispatchContext, resolveAuthClaimsFn, resolveDbSource } from "./dispatch-shared";
 import { isSystemIdentity } from "./system-identity-switch";
+import { rootWriteOrigin } from "./write-origin";
 
 // Stricter than interactive sign-in: an unknown principal or a tenant
 // mid-teardown must not resolve — there is no user-facing flow to recover.
@@ -103,6 +104,7 @@ export function createMemberReaderFn(
 
   return async (userId, qn, payload) => {
     const user = await resolve(userId);
-    return executeQuery(ctx, qn, payload, user, tx);
+    // A resolved member is never anonymous and read-only, so it may start its own root.
+    return executeQuery(ctx, qn, payload, user, rootWriteOrigin(ctx.registry, qn, user), tx);
   };
 }

package/src/pipeline/write-origin.ts

@@ -0,0 +1,107 @@
+// The static check in boot-validator/access-declarations.ts only sees a handler's own
+// input schema; writes reached via ctx.write/writeAs/queryAs, hooks or foreign-feature
+// tables are only visible at the actual write, so the gate runs there at runtime.
+import { buildEntityTable } from "../db/table-builder";
+import { type PersonalDataGate, tableNameOf } from "../db/tenant-db";
+import {
+  accessAllowsAnonymous,
+  declaredPersonalData,
+  personalFieldNames,
+} from "../engine/personal-data-fields";
+import { ANONYMOUS_ROLE } from "../engine/system-user";
+import type { AccessRule, Registry, SessionUser } from "../engine/types";
+import type { EntityDefinition } from "../engine/types/fields";
+import { AccessDeniedError } from "../errors";
+import { FrameworkReasons } from "../errors/reasons";
+import { toSnakeCase } from "../utils/case";
+
+export type WriteOrigin = {
+  readonly rootHandler: string;
+  readonly anonymousRoot: boolean;
+  // Only a write-handler root can declare public-intake; a query/stream root never does.
+  readonly publicIntake: boolean;
+};
+
+function declaresPublicIntake(access: AccessRule): boolean {
+  return accessAllowsAnonymous(access) && declaredPersonalData(access) === "public-intake";
+}
+
+// Only the public dispatcher entry points compute a root; every nested call inherits
+// it, so switching identity via ctx.writeAs(SYSTEM, ...) cannot shed an anonymous root.
+export function rootWriteOrigin(registry: Registry, type: string, user: SessionUser): WriteOrigin {
+  const writeHandler = registry.getWriteHandler(type);
+  return {
+    rootHandler: type,
+    anonymousRoot: user.roles.includes(ANONYMOUS_ROLE),
+    publicIntake: writeHandler !== undefined && declaresPublicIntake(writeHandler.access),
+  };
+}
+
+// Owner binding is ignored (honorOwnerBinding=false): all anonymous callers share one
+// user id, so from("user:id", ...) vouches for nobody.
+const personalDataTableMaps = new WeakMap<Registry, ReadonlyMap<string, ReadonlySet<string>>>();
+
+function personalColumnNames(entity: EntityDefinition): ReadonlySet<string> {
+  return new Set([...personalFieldNames(entity, false)].map(toSnakeCase));
+}
+
+function buildPersonalDataTableMap(registry: Registry): ReadonlyMap<string, ReadonlySet<string>> {
+  const map = new Map<string, ReadonlySet<string>>();
+  for (const [entityName, entity] of registry.getAllEntities()) {
+    const columns = personalColumnNames(entity);
+    if (columns.size === 0) continue;
+    const table = buildEntityTable(entityName, entity, {
+      relations: registry.getRelations(entityName),
+    });
+    map.set(tableNameOf(table), columns);
+  }
+  return map;
+}
+
+function personalDataTableMap(registry: Registry): ReadonlyMap<string, ReadonlySet<string>> {
+  const cached = personalDataTableMaps.get(registry);
+  if (cached) return cached;
+  const built = buildPersonalDataTableMap(registry);
+  personalDataTableMaps.set(registry, built);
+  return built;
+}
+
+// Names fields only, never values: the error reaches the anonymous HTTP caller.
+function publicIntakeRequiredError(
+  origin: WriteOrigin,
+  target: string,
+  fields: readonly string[],
+): AccessDeniedError {
+  return new AccessDeniedError({
+    message:
+      `Anonymous root handler "${origin.rootHandler}" wrote personal-data field(s) ` +
+      `${fields.map((f) => `"${f}"`).join(", ")} on "${target}". Declare ` +
+      'access: { roles: [..., "anonymous"], personalData: "public-intake" } on ' +
+      `"${origin.rootHandler}" to allow anonymous callers to write personal data.`,
+    details: {
+      reason: FrameworkReasons.publicIntakeRequired,
+      rootHandler: origin.rootHandler,
+      target,
+      fields,
+    },
+  });
+}
+
+// Without an entity the table name is looked up in the registry map; tables outside it
+// (unmanaged stores, hand-built tables) carry no personal-data annotations and pass.
+export function buildPersonalDataGate(
+  registry: Registry,
+  origin: WriteOrigin,
+): PersonalDataGate | undefined {
+  if (!origin.anonymousRoot || origin.publicIntake) return undefined;
+  const map = personalDataTableMap(registry);
+  return (tableName, keys, entity) => {
+    const personalFields = entity ? personalColumnNames(entity) : map.get(tableName);
+    // skip: table carries no personal-data annotations
+    if (!personalFields) return;
+    const offending = [...new Set(keys.map(toSnakeCase))].filter((k) => personalFields.has(k));
+    // skip: write touches no personal-data field
+    if (offending.length === 0) return;
+    throw publicIntakeRequiredError(origin, tableName, offending);
+  };
+}

package/src/rate-limit/__tests__/middleware.integration.test.ts

@@ -186,4 +186,44 @@ describe("authEndpointRateLimit (L2)", () => {
     const otherAcc = await reqA("user-b");
     expect(otherAcc.status).toBe(200);
   });
+
+  test("GET /api/auth/tenants is exempt (session read), but POST on the same path is not", async () => {
+    const app = new Hono();
+    app.use(
+      "/api/auth/*",
+      authEndpointRateLimit({ resolver, limit: 2, windowSeconds: 60, onFailClosed: () => {} }),
+    );
+    app.get("/api/auth/tenants", (c) => c.text("ok"));
+    app.post("/api/auth/tenants", (c) => c.text("ok"));
+    app.post("/api/auth/login", (c) => c.text("ok"));
+
+    const ipHeader = { "x-forwarded-for": "10.0.2.1" };
+
+    // 10 GETs — none consume the l2:ip:/api/auth/tenants bucket.
+    for (let i = 0; i < 10; i++) {
+      const res = await app.request("/api/auth/tenants", { headers: ipHeader });
+      expect(res.status).toBe(200);
+      // Exempt requests skip the resolver entirely — no rate-limit headers.
+      expect(res.headers.get("X-RateLimit-Limit")).toBeNull();
+    }
+
+    // A separate credential-endpoint bucket is untouched by the above.
+    await app.request("/api/auth/login", { method: "POST", headers: ipHeader });
+    await app.request("/api/auth/login", { method: "POST", headers: ipHeader });
+    const loginBlocked = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: ipHeader,
+    });
+    expect(loginBlocked.status).toBe(429);
+
+    // POST on the exempt path is method-exact, not path-exact — it still
+    // shares the ordinary ip+path bucket and trips at the same limit.
+    await app.request("/api/auth/tenants", { method: "POST", headers: ipHeader });
+    await app.request("/api/auth/tenants", { method: "POST", headers: ipHeader });
+    const postTenantsBlocked = await app.request("/api/auth/tenants", {
+      method: "POST",
+      headers: ipHeader,
+    });
+    expect(postTenantsBlocked.status).toBe(429);
+  });
 });

package/src/rate-limit/middleware.ts

@@ -1,4 +1,5 @@
 import type { Context, MiddlewareHandler } from "hono";
+import { isAuthRateLimitExempt } from "../api/api-constants";
 import { requestContext } from "../api/request-context";
 import { RateLimitError, serializeError } from "../errors";
 import type { RateLimitDecision, RateLimitResolver } from "./resolver";
@@ -84,6 +85,8 @@ export function authEndpointRateLimit(opts: AuthEndpointRateLimitOptions): Middl
   const onFailClosed = opts.onFailClosed ?? defaultOnFailClosed("l2-auth-endpoints");
 
   return async (c, next) => {
+    if (isAuthRateLimitExempt(c.req.method, c.req.path)) return next();
+
     const ip = extractIp(c);
     if (!ip) return next();
 

package/src/stack/__tests__/setup-test-stack-metrics.integration.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../engine";
+import { resolveObservabilityWiring } from "../../observability/metrics-wiring";
+import { setupTestStack, type TestStack } from "../test-stack";
+import { TestUsers } from "../test-users";
+
+const METRICS_TOKEN = "setup-test-stack-metrics-token-minimum-32-chars!!";
+
+const pingFeature = defineFeature("stmetrics", (r) => {
+  r.writeHandler(
+    "ping",
+    z.object({}),
+    async () => ({ isSuccess: true as const, data: { ok: true } }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+});
+
+let stack: TestStack | undefined;
+
+afterEach(async () => {
+  await stack?.cleanup();
+  stack = undefined;
+});
+
+describe("setupTestStack metrics option (integration)", () => {
+  test("mirrors runProdApp wiring: /metrics scrapes after a real request, token-gated", async () => {
+    stack = await setupTestStack({
+      features: [pingFeature],
+      ...resolveObservabilityWiring(METRICS_TOKEN),
+    });
+
+    // kumiko_http_requests_total is only recorded by the http middleware, so scrape after a real request.
+    await stack.http.command("stmetrics:write:ping", {}, TestUsers.admin);
+
+    const noAuth = await stack.app.request("/metrics");
+    expect(noAuth.status).toBe(401);
+
+    const wrongToken = await stack.app.request("/metrics", {
+      headers: { Authorization: "Bearer wrong-token" },
+    });
+    expect(wrongToken.status).toBe(401);
+
+    const scraped = await stack.app.request("/metrics", {
+      headers: { Authorization: `Bearer ${METRICS_TOKEN}` },
+    });
+    expect(scraped.status).toBe(200);
+    expect(scraped.headers.get("Content-Type")).toMatch(/openmetrics-text/);
+    const body = await scraped.text();
+    expect(body).toMatch(/kumiko_http_requests_total\{[^}]*route="\/api\/command"[^}]*\} 1/);
+  });
+
+  test("no metrics option: /metrics is unmounted (404)", async () => {
+    stack = await setupTestStack({ features: [pingFeature] });
+
+    const res = await stack.app.request("/metrics");
+    expect(res.status).toBe(404);
+  });
+
+  test("custom path override: mounts only at the overridden path", async () => {
+    const wiring = resolveObservabilityWiring(METRICS_TOKEN);
+    if (!("metrics" in wiring)) throw new Error("resolveObservabilityWiring did not wire metrics");
+
+    stack = await setupTestStack({
+      features: [pingFeature],
+      ...wiring,
+      metrics: { ...wiring.metrics, path: "/internal/metrics" },
+    });
+
+    const atDefault = await stack.app.request("/metrics");
+    expect(atDefault.status).toBe(404);
+
+    const atCustom = await stack.app.request("/internal/metrics", {
+      headers: { Authorization: `Bearer ${METRICS_TOKEN}` },
+    });
+    expect(atCustom.status).toBe(200);
+    expect(atCustom.headers.get("Content-Type")).toMatch(/openmetrics-text/);
+  });
+});

package/src/stack/test-stack.ts

@@ -110,6 +110,10 @@ export type TestStackOptions = {
    *  MUST go through here (real HTTP via `stack.http`/`stack.app.fetch`),
    *  never `createTestDispatcher`. */
   extraRoutes?: import("../api/server").ServerOptions["extraRoutes"];
+  /** Forwarded to buildServer like runProdApp. Without a PrometheusMeter-backed
+   *  `observability` the route answers 503, so spread `resolveObservabilityWiring(token)`
+   *  rather than setting `metrics` alone. */
+  metrics?: import("../api/server").ServerOptions["metrics"];
   /** Inject a MasterKeyProvider for secrets-backed tests. Lands typed in
    *  AppContext — set/delete/get + rotation job pick it up. Omit for
    *  suites that don't touch secrets. */
@@ -410,6 +414,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       eventDedup,
       sseBroker,
       ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
+      ...(options.metrics && { metrics: options.metrics }),
       // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for
       // deterministic drains — no timer-induced flakiness. pollIntervalMs
       // stays short anyway in case a test opts into `.start()`. pgClient