@cosmicdrift/kumiko-framework 0.200.1 → 0.202.0

package/src/api/route-registrars.ts

@@ -11,7 +11,7 @@ import type { Lifecycle } from "../lifecycle";
 import type { Meter, PrometheusMeter } from "../observability";
 import { serializeOpenMetrics } from "../observability";
 import type { EventConsumer } from "../pipeline/event-dispatcher";
-import { Routes } from "./api-constants";
+import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "./api-constants";
 import {
   createReadinessProbe,
   dbPingCheck,
@@ -22,27 +22,26 @@ import {
 
 // --- Body size limit ------------------------------------------------------
 
-const BODY_LIMIT_PATHS = [
-  `/api${Routes.write}`,
-  `/api${Routes.batch}`,
-  `/api${Routes.query}`,
-  `/api${Routes.command}`,
-  `/api${Routes.auth}/*`,
-] as const;
-
 export const DEFAULT_MAX_REQUEST_BYTES = 1_048_576;
 
-// Cap JSON bodies on /api/write + /api/batch + /api/query + /api/command
-// + /api/auth/*. File uploads keep their own per-field maxSize. `0`
-// disables the limit entirely — only useful when a reverse-proxy caps
-// upstream or tests want raw passthrough.
+// Cap every /api/* request body by default — a new route needs no entry
+// anywhere to be covered, it inherits the limit from being registered under
+// /api at all. Routes with their own size contract (currently just uploads)
+// opt out explicitly via BODY_LIMIT_OPT_OUT_PATHS in api-constants.ts;
+// forgetting an opt-out entry only over-limits a route, forgetting to add a
+// new route to an allowlist used to leave it unlimited — that inversion is
+// the point. `maxBytes <= 0` disables the limit entirely — only useful when
+// a reverse-proxy caps upstream or tests want raw passthrough.
 export function registerBodyLimit(app: Hono, maxBytes: number): void {
   // skip: opt-out path — caller passed `maxBytes: 0`, so no middleware
   // is attached (upstream cap via reverse-proxy is expected). Not a bug
   // suppression, an intentional disable.
   if (maxBytes <= 0) return;
   const limit = bodyLimit({ maxSize: maxBytes });
-  for (const path of BODY_LIMIT_PATHS) app.use(path, limit);
+  app.use("/api/*", async (c, next) => {
+    if (BODY_LIMIT_OPT_OUT_PATHS.has(c.req.path)) return next();
+    return limit(c, next);
+  });
 }
 
 // --- /metrics (Prometheus scrape) -----------------------------------------
@@ -100,14 +99,13 @@ export function registerMetricsRoute(app: Hono, meter: Meter, options: MetricsRo
 
 // --- /version ---------------------------------------------------------------
 
-// Anonymous endpoint that returns build-identity. Used by ops-tooling
-// (prod-version.sh) und Telegram-deploy-Notification damit man nicht
-// kubectl + crictl auf den Master braucht um die deployed-Version zu
-// sehen.
+// Anonymous endpoint that returns build-identity. Used by ops tooling
+// (prod-version.sh) and the Telegram deploy notification so nobody needs
+// kubectl + crictl on the master to see the deployed version.
 //
-// BUILD_VERSION + BUILD_TIME werden vom Dockerfile (ARG → ENV)
-// durchgereicht — fallen zurück auf "dev" / "unknown" wenn lokal ohne
-// Build-args gebaut.
+// BUILD_VERSION + BUILD_TIME are passed through from the Dockerfile
+// (ARG → ENV) — fall back to "dev" / "unknown" when built locally
+// without build-args.
 export function registerVersionRoute(app: Hono): void {
   const version = process.env["BUILD_VERSION"] ?? "dev";
   const buildTime = process.env["BUILD_TIME"] ?? "unknown";

package/src/api/routes.ts

@@ -45,6 +45,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     const body = await c.req.json<{ type: string; payload: unknown; requestId?: string }>();
 
     try {
+      assertPayloadDepthAllowed(body.payload);
       assertPatAllowed(user, body.type);
       const result = await dispatcher.write(body.type, body.payload, user, body.requestId);
       if (!result.isSuccess) {
@@ -83,6 +84,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     }
 
     try {
+      for (const cmd of body.commands) assertPayloadDepthAllowed(cmd.payload);
       if (user.pat) {
         for (const cmd of body.commands) assertPatAllowed(user, cmd.type);
       }
@@ -120,6 +122,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
+      assertPayloadDepthAllowed(body.payload);
       assertPatAllowed(user, body.type);
       const result = await dispatcher.query(body.type, body.payload, user);
       return jsonResponse(c, { data: result });
@@ -133,6 +136,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
+      assertPayloadDepthAllowed(body.payload);
       assertPatAllowed(user, body.type);
       await dispatcher.command(body.type, body.payload, user);
       return c.json({ ok: true }, 202);
@@ -156,9 +160,11 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     const body = await c.req.json<{ type: string; payload: unknown }>();
     const requestId = requestContext.get()?.requestId;
 
-    const generator = dispatcher.stream(body.type, body.payload, user);
+    let generator: AsyncGenerator<unknown>;
     try {
+      assertPayloadDepthAllowed(body.payload);
       assertPatAllowed(user, body.type);
+      generator = dispatcher.stream(body.type, body.payload, user);
     } catch (e) {
       return queryErrorResponse(c, toKumiko(e), body.type);
     }
@@ -274,6 +280,46 @@ function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode =
 
 const toKumiko = toKumikoError;
 
+// Nesting cap for request payloads — an object-walk, not a string/byte
+// check, since an attacker fully controls whitespace/formatting and a
+// minified deeply-nested payload can stay well under the byte limit while
+// still blowing the stack on recursive Zod parsing / jsonb serialization.
+export const MAX_PAYLOAD_DEPTH = 20;
+
+function payloadDepth(value: unknown, depth: number): number {
+  if (depth > MAX_PAYLOAD_DEPTH || value === null || typeof value !== "object") {
+    return depth;
+  }
+  const children = Array.isArray(value) ? value : Object.values(value);
+  let max = depth;
+  for (const child of children) {
+    const childDepth = payloadDepth(child, depth + 1);
+    if (childDepth > max) max = childDepth;
+    if (max > MAX_PAYLOAD_DEPTH) break;
+  }
+  return max;
+}
+
+// Rejects payloads nested deeper than MAX_PAYLOAD_DEPTH before they reach
+// per-handler Zod validation — recursive Zod parsing (and any downstream
+// jsonb serialization of custom-fields payloads) walks the same object
+// graph an attacker controls, so an uncapped depth is a stack-overflow /
+// CPU-DoS vector even under the 1MB body-byte limit.
+function assertPayloadDepthAllowed(payload: unknown): void {
+  if (payloadDepth(payload, 0) > MAX_PAYLOAD_DEPTH) {
+    throw new ValidationError({
+      fields: [
+        {
+          path: "payload",
+          code: "too_deep",
+          i18nKey: "errors.validation.payload_too_deep",
+          params: { maxDepth: MAX_PAYLOAD_DEPTH },
+        },
+      ],
+    });
+  }
+}
+
 // PAT scope enforcement at the API boundary. No-op for cookie/JWT users
 // (user.pat undefined → unrestricted). For a PAT-authenticated request the
 // dispatch type must match one of the token's granted-scope QN globs, else

package/src/api/server.ts

@@ -310,7 +310,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // Stateless JWTs (no sessionChecker → no revocation) default to a shorter
   // TTL than session-backed ones, since a leaked stateless token can't be
   // revoked and stays valid until it expires. Explicit jwtTtl always wins.
-  const defaultJwtTtl = options.auth?.sessionChecker ? 24 * 60 * 60 : 60 * 60;
+  const defaultJwtTtl = options.auth?.sessionChecker ? 8 * 60 * 60 : 60 * 60;
   const jwt = createJwtHelper(
     options.jwtSecret,
     options.jwtIssuer,

package/src/db/__tests__/unchecked-system-db.test.ts

@@ -114,4 +114,70 @@ describe("createUncheckedSystemDb", () => {
       expect(() => unchecked.acknowledgeCrossTenant("   ")).toThrow(/non-empty reason/);
     });
   });
+
+  describe("outsideTransaction", () => {
+    describe("assertTenantMatch", () => {
+      test("returns the outside-transaction TenantDb, not the in-tx one, when the tenantId matches", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb);
+
+        const result = unchecked.outsideTransaction.assertTenantMatch(own);
+        expect(result).toBe(outsideTxDb);
+        expect(result).not.toBe(systemDb);
+      });
+
+      test("throws AccessDeniedError when the tenantId doesn't match", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb);
+
+        expect(() => unchecked.outsideTransaction.assertTenantMatch(foreign)).toThrow(
+          /outsideTransaction tenant self-check failed/,
+        );
+      });
+
+      test("throws when no outside-transaction db was configured, even for a matching tenantId", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb);
+
+        expect(() => unchecked.outsideTransaction.assertTenantMatch(own)).toThrow(
+          /no outside-transaction database source is configured/,
+        );
+      });
+    });
+
+    describe("acknowledgeCrossTenant", () => {
+      test("returns the outside-transaction TenantDb without comparing tenants when given a reason", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb);
+
+        const result = unchecked.outsideTransaction.acknowledgeCrossTenant(
+          "durability write is cross-tenant by design",
+        );
+        expect(result).toBe(outsideTxDb);
+        expect(result).not.toBe(systemDb);
+      });
+
+      test("throws on an empty reason", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb);
+
+        expect(() => unchecked.outsideTransaction.acknowledgeCrossTenant("")).toThrow(
+          /non-empty reason/,
+        );
+      });
+
+      test("throws when no outside-transaction db was configured, even with a valid reason", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb);
+
+        expect(() => unchecked.outsideTransaction.acknowledgeCrossTenant("valid reason")).toThrow(
+          /no outside-transaction database source is configured/,
+        );
+      });
+    });
+  });
 });

package/src/db/tenant-db.ts

@@ -17,7 +17,7 @@ import {
   type WhereObject,
 } from "../db/query";
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
-import { AccessDeniedError } from "../errors";
+import { AccessDeniedError, InternalError } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import type { DbRunner } from "./connection";
 
@@ -32,9 +32,35 @@ export {
 
 // buildHandlerContext (pipeline/dispatch-shared.ts) always builds "system"
 // mode from the caller's own tenantId, never a foreign one.
-export function createUncheckedSystemDb(db: TenantDb): UncheckedSystemDb {
+//
+// dbOutsideTransaction is optional so every existing single-arg call site
+// (jobs, tests, delivery-service.ts) keeps compiling — those callers have no
+// outside-tx source to hand in and never needed one. Only
+// buildHandlerContext passes it, which is also the only place `.outsideTransaction`
+// is reachable through `ctx.systemDb`.
+export function createUncheckedSystemDb(
+  db: TenantDb,
+  dbOutsideTransaction?: TenantDb,
+): UncheckedSystemDb {
   const allowedTenantIds: readonly TenantId[] = [db.tenantId, SYSTEM_TENANT_ID];
 
+  // Fails closed instead of falling back to the in-tx `db` — a silent
+  // fallback would defeat the point of a durability write that must survive
+  // a rollback of the handler's own transaction. InternalError (not
+  // AccessDeniedError) because this is a dispatch wiring fault, not a
+  // tenant-access denial — mirrors the "no database connection configured"
+  // case in dispatch-shared.ts's appendDomainEvent.
+  function requireOutsideTransactionDb(): TenantDb {
+    if (!dbOutsideTransaction) {
+      throw new InternalError({
+        message:
+          "systemScope() outsideTransaction check failed: no outside-transaction database " +
+          "source is configured for this dispatch.",
+      });
+    }
+    return dbOutsideTransaction;
+  }
+
   return {
     [SYSTEM_SCOPE_CHECK_BRAND]: true,
 
@@ -68,6 +94,24 @@ export function createUncheckedSystemDb(db: TenantDb): UncheckedSystemDb {
       }
       return db;
     },
+
+    outsideTransaction: {
+      assertTenantMatch(tenantId) {
+        if (tenantId !== db.tenantId) {
+          throw new AccessDeniedError({
+            message: `systemScope() outsideTransaction tenant self-check failed: expected "${db.tenantId}", got "${tenantId}"`,
+          });
+        }
+        return requireOutsideTransactionDb();
+      },
+
+      acknowledgeCrossTenant(reason) {
+        if (reason.trim().length === 0) {
+          throw new Error("acknowledgeCrossTenant requires a non-empty reason");
+        }
+        return requireOutsideTransactionDb();
+      },
+    },
   };
 }
 

package/src/engine/__tests__/boot-validator-detail-for.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+describe("validateBoot — detailFor screens (fw#2163)", () => {
+  test("two screens with the same detailFor fail boot, naming both screen ids", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-detail-a",
+        type: "custom",
+        renderer: { react: "stub" },
+        detailFor: "item",
+      });
+      r.screen({
+        id: "item-detail-b",
+        type: "custom",
+        renderer: { react: "stub" },
+        detailFor: "item",
+      });
+      r.translations({
+        keys: {
+          "screen:item-detail-a.title": { de: "A", en: "A" },
+          "screen:item-detail-b.title": { de: "B", en: "B" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/detailFor: "item"/);
+    expect(() => validateBoot([feature])).toThrow(/demo:screen:item-detail-a/);
+    expect(() => validateBoot([feature])).toThrow(/demo:screen:item-detail-b/);
+  });
+
+  test("detailFor on an unknown entity fails boot", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-detail",
+        type: "custom",
+        renderer: { react: "stub" },
+        detailFor: "ghost",
+      });
+      r.translations({
+        keys: {
+          "screen:item-detail.title": { de: "Detail", en: "Detail" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/"ghost"/);
+  });
+
+  test("a valid detailFor on a custom screen passes boot", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-detail",
+        type: "custom",
+        renderer: { react: "stub" },
+        detailFor: "item",
+      });
+      r.translations({
+        keys: {
+          "screen:item-detail.title": { de: "Detail", en: "Detail" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("an entity without any detail screen passes boot", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.translations({
+        keys: { "demo:entity:item:field:name": { de: "Name", en: "Name" } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});

package/src/engine/__tests__/build-app-schema.test.ts

@@ -91,6 +91,31 @@ describe("buildAppSchema", () => {
     expect(screen).toMatchObject({ id: "privacy-center", dormant: true });
   });
 
+  // fw#2163: resolveTarget (renderer) reads screen.detailFor + screen.id
+  // (short, unqualified) off the client FeatureSchema — this pins that both
+  // survive the server→client projection verbatim, on a real registry-built
+  // schema rather than a hand-rolled FeatureSchema literal.
+  test("custom screen's `detailFor` survives the buildAppSchema projection, screen id stays unqualified (#2163)", () => {
+    const propertyFeature = defineFeature("property", (r) => {
+      r.entity("lease", {
+        table: "leases",
+        fields: { name: { type: "text" } },
+      } as unknown as EntityDefinition);
+      r.screen({
+        id: "lease-detail",
+        type: "custom",
+        renderer: { react: { __component: "LeaseDetailScreen" } },
+        detailFor: "lease",
+      });
+      r.translations({ keys: { "screen:lease-detail.title": { de: "Detail", en: "Detail" } } });
+    });
+
+    const app = buildAppSchema(createRegistry([propertyFeature]));
+    const screen = app.features.find((f) => f.featureName === "property")?.screens[0];
+
+    expect(screen).toMatchObject({ id: "lease-detail", detailFor: "lease" });
+  });
+
   test("Feature ohne r.translations lässt das Feld weg (omit-undefined-Pattern)", () => {
     const f = defineFeature("bare", (r) => {
       r.nav({ id: "x", label: "X" });

package/src/engine/boot-validator/detail-screens.ts

@@ -0,0 +1,35 @@
+import { qualifyEntityName } from "../qualified-name";
+import type { FeatureDefinition } from "../types";
+import { findEntityFeature } from "./screens";
+
+export function validateDetailForScreens(
+  features: readonly FeatureDefinition[],
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  const screenQnByEntity = new Map<string, string>();
+
+  for (const feature of features) {
+    for (const [screenId, screen] of Object.entries(feature.screens)) {
+      const detailFor = screen.detailFor;
+      if (detailFor === undefined) continue;
+
+      const qualified = qualifyEntityName(feature.name, "screen", screenId);
+
+      const existingQn = screenQnByEntity.get(detailFor);
+      if (existingQn !== undefined) {
+        throw new Error(
+          `[detailFor] Screens "${existingQn}" and "${qualified}" both declare ` +
+            `detailFor: "${detailFor}" — only one screen may be the detail view for an entity.`,
+        );
+      }
+      screenQnByEntity.set(detailFor, qualified);
+
+      if (findEntityFeature(detailFor, featureMap) === undefined) {
+        throw new Error(
+          `[detailFor] Screen "${qualified}" declares detailFor: "${detailFor}", ` +
+            `but no feature registers an entity with that name.`,
+        );
+      }
+    }
+  }
+}

package/src/engine/boot-validator/index.ts

@@ -16,6 +16,7 @@ import {
   validateConfigReads,
   warnOnToggleableDependencies,
 } from "./config-deps";
+import { validateDetailForScreens } from "./detail-screens";
 import {
   validateDerivedFieldCollisions,
   validateEmbeddedFields,
@@ -208,6 +209,7 @@ export function validateBoot(
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateI18nSurfaceKeys(features);
   validateEntityListScreens(features);
+  validateDetailForScreens(features, featureMap);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateFeatureBootChecks(features);

package/src/engine/entity-handlers.ts

@@ -102,9 +102,16 @@ type ListPayload = {
 };
 
 const idSchema = z.object({ id: z.uuid() });
+
+// Upper bound on entity-list `limit`: unbounded/fractional values ran
+// straight into the raw `LIMIT ${limit}` SQL string (event-store-executor-
+// read.ts), letting a client demand a full-table materialisation or trip a
+// Postgres syntax error on a non-integer literal.
+export const MAX_LIST_LIMIT = 200;
+
 export const entityListSchema = z.object({
   cursor: z.string().optional(),
-  limit: z.number().optional(),
+  limit: z.number().int().nonnegative().max(MAX_LIST_LIMIT).optional(),
   search: z.string().optional(),
   sort: z.string().optional(),
   sortDirection: z.enum(["asc", "desc"]).optional(),

package/src/engine/feature-ast/__tests__/fixtures/cross-file-patch-const/constants.ts

@@ -0,0 +1,2 @@
+export const EXT_TENANT_DATA = "tenant-data" as const;
+export const ENTITY_ITEM = "item" as const;

package/src/engine/feature-ast/__tests__/fixtures/cross-file-patch-const/feature.ts

@@ -0,0 +1,8 @@
+import { ENTITY_ITEM, EXT_TENANT_DATA } from "./constants";
+
+// biome-ignore lint/suspicious/noExplicitAny: structural parser test fixture, never executed or type-checked at runtime
+declare function defineFeature(name: string, setup: (r: any) => void): void;
+
+defineFeature("cross-file-patch-const", (r) => {
+  r.useExtension(EXT_TENANT_DATA, ENTITY_ITEM);
+});