@cosmicdrift/kumiko-framework 0.201.0 → 0.202.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.201.0",
+  "version": "0.202.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -87,6 +87,10 @@
       "types": "./src/i18n/index.ts",
       "default": "./src/i18n/index.ts"
     },
+    "./http": {
+      "types": "./src/http/index.ts",
+      "default": "./src/http/index.ts"
+    },
     "./auth": {
       "types": "./src/auth/index.ts",
       "default": "./src/auth/index.ts"
@@ -186,7 +190,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.201.0",
+    "@cosmicdrift/kumiko-types": "0.202.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +206,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.201.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.202.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/api-constants-completeness.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { NON_PUBLIC_API_PATHS, PUBLIC_API_PATHS, Routes } from "../api-constants";
+
+// PUBLIC_API_PATHS is an allowlist: a missing entry (typo, forgotten route)
+// fails CLOSED — the route stays behind auth, never accidentally public.
+// But the classification itself must be total, or a route silently falls
+// into a third, unchecked state that nobody notices until it's either
+// exploited (should've been non-public) or reported broken by a client
+// (should've been public). This test forces every `Routes` entry into
+// exactly one of the two sets, in both directions:
+//   - every Routes entry has a classification (no silent gap)
+//   - every classified path still corresponds to a real Routes entry (no
+//     stale/typo'd literal drifting out of sync with Routes)
+function classifyRoutes(routes: Record<string, string>): {
+  unclassified: string[];
+  classifiedInBoth: string[];
+} {
+  const unclassified: string[] = [];
+  const classifiedInBoth: string[] = [];
+
+  for (const routePath of Object.values(routes)) {
+    const apiPath = `/api${routePath}`;
+    const isPublic = PUBLIC_API_PATHS.has(apiPath);
+    const isNonPublic = NON_PUBLIC_API_PATHS.has(apiPath);
+    if (isPublic && isNonPublic) classifiedInBoth.push(apiPath);
+    else if (!isPublic && !isNonPublic) unclassified.push(apiPath);
+  }
+
+  return { unclassified, classifiedInBoth };
+}
+
+describe("Routes / PUBLIC_API_PATHS classification completeness", () => {
+  test("every Routes entry is classified as exactly public XOR non-public", () => {
+    const { unclassified, classifiedInBoth } = classifyRoutes(Routes);
+
+    expect(unclassified).toEqual([]);
+    expect(classifiedInBoth).toEqual([]);
+  });
+
+  test("every PUBLIC_API_PATHS / NON_PUBLIC_API_PATHS entry maps back to a real Routes value", () => {
+    const knownApiPaths = new Set(Object.values(Routes).map((routePath) => `/api${routePath}`));
+
+    const stalePublic = [...PUBLIC_API_PATHS].filter((path) => !knownApiPaths.has(path));
+    const staleNonPublic = [...NON_PUBLIC_API_PATHS].filter((path) => !knownApiPaths.has(path));
+
+    expect(stalePublic).toEqual([]);
+    expect(staleNonPublic).toEqual([]);
+  });
+
+  // Regression guard for the mechanism itself: proves the completeness
+  // check actually fails when a route is added without a classification,
+  // rather than the two tests above being vacuously true by construction.
+  test("regression: an unclassified route is detected", () => {
+    const routesWithGap = {
+      ...Routes,
+      newFeature: "/new-feature-without-classification",
+    };
+
+    const { unclassified } = classifyRoutes(routesWithGap);
+
+    expect(unclassified).toEqual(["/api/new-feature-without-classification"]);
+  });
+});

package/src/api/__tests__/body-limit.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "../api-constants";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
@@ -86,10 +87,12 @@ describe("request body limit", () => {
     expect(res.status).toBe(401); // passes body-limit, reaches auth
   });
 
-  // Security regression (2026-08-13 audit, Finding 2): /api/stream was
-  // missing from BODY_LIMIT_PATHS, so it dispatched to the dispatcher
-  // without ever hitting the same 1MB cap /api/write enforces. Mirrors the
-  // /api/write cases above.
+  // Security regression (2026-08-13 audit, Finding 2): /api/stream used to be
+  // missing from the old BODY_LIMIT_PATHS allowlist, so it dispatched to the
+  // dispatcher without ever hitting the same 1MB cap /api/write enforces.
+  // Mirrors the /api/write cases above. Now covered structurally (see
+  // "default coverage sweep" below), kept as its own test for the historical
+  // regression it documents.
   test("rejects POST /api/stream with body larger than maxRequestBytes with 413 (mirrors /api/write)", async () => {
     const app = buildApp(1024);
     const res = await postJson(app, "/api/stream", 2048);
@@ -102,3 +105,74 @@ describe("request body limit", () => {
     expect(res.status).toBe(401); // no JWT → 401, but size is fine
   });
 });
+
+// fw#2145: BODY_LIMIT_PATHS inverted from an opt-in allowlist to an opt-out
+// list — registerBodyLimit now mounts on /api/* by construction, and only
+// BODY_LIMIT_OPT_OUT_PATHS (api-constants.ts) escapes it. These tests prove
+// that inversion rather than re-testing individual paths.
+describe("body-limit opt-out completeness", () => {
+  test("every opt-out entry resolves to a real Routes constant (no stale/typo'd paths)", () => {
+    for (const optOutPath of BODY_LIMIT_OPT_OUT_PATHS) {
+      const matchesKnownRoute = Object.values(Routes).some(
+        (route) => `/api${route}` === optOutPath,
+      );
+      expect(matchesKnownRoute).toBe(true);
+    }
+  });
+
+  test("the opt-out list is pinned to its reviewed members — a new exception must touch this test", () => {
+    expect([...BODY_LIMIT_OPT_OUT_PATHS]).toEqual([`/api${Routes.files}`]);
+  });
+});
+
+describe("default coverage sweep — proves the default, not a hand-maintained list", () => {
+  const OVERSIZED_BYTES = 2_000_000; // exceeds the default 1 MiB cap
+
+  // Derived from Routes itself (minus opt-out) rather than a hand-picked
+  // list — a route added to Routes tomorrow lands in this sweep
+  // automatically, with no test file to remember to update. Includes routes
+  // this test app never mounts (e.g. authLogin, no `auth` option passed to
+  // buildServer) and routes whose GET handler is mounted outside /api/*
+  // (health, healthReady, version — registerHealthRoutes/registerVersionRoute
+  // mount at the bare path, not under /api). Both still 413 on an oversized
+  // POST here: the /api/* body-limit middleware matches on path prefix
+  // before Hono resolves a handler, so it runs whether or not a route
+  // answers underneath. Verified directly: `POST /api/health` 413s even
+  // though the only real handler lives at `GET /health`.
+  const defaultLimitedRoutes = Object.values(Routes).filter(
+    (route) => !BODY_LIMIT_OPT_OUT_PATHS.has(`/api${route}`),
+  );
+
+  for (const route of defaultLimitedRoutes) {
+    test(`POST /api${route} 413s on an oversized body without needing its own list entry`, async () => {
+      const app = buildApp();
+      const res = await postJson(app, `/api${route}`, OVERSIZED_BYTES);
+      expect(res.status).toBe(413);
+    });
+  }
+
+  test("POST /api/files does not 413 on an oversized JSON body (explicit opt-out)", async () => {
+    const app = buildApp();
+    const res = await postJson(app, "/api/files", OVERSIZED_BYTES);
+    expect(res.status).not.toBe(413);
+  });
+
+  // Regression for the DoD: "neue Route ohne Eintrag in irgendeiner Liste
+  // bekommt automatisch ein Limit". Mounts a route the same way an app-owner's
+  // `extraRoutes` callback would — after buildServer, with zero Routes/
+  // opt-out entries — and proves it inherits the cap AND still serves a
+  // small body correctly (not an accidental always-413).
+  test("a route mounted after buildServer with no list entry anywhere still inherits the default limit", async () => {
+    const app = buildApp();
+    app.post("/api/totally-new-route-nobody-listed", async (c) => c.json({ ok: true }));
+
+    const oversized = await postJson(app, "/api/totally-new-route-nobody-listed", OVERSIZED_BYTES);
+    expect(oversized.status).toBe(413);
+
+    // Small body passes the size cap and reaches the auth guard (401, no
+    // JWT) — proves the 413 above is the size cap doing its job, not the
+    // route being unreachable for some unrelated reason.
+    const small = await postJson(app, "/api/totally-new-route-nobody-listed", 10);
+    expect(small.status).toBe(401);
+  });
+});

package/src/api/__tests__/server-jwt-ttl.test.ts

@@ -21,7 +21,7 @@ describe("buildServer — jwtTtl default depends on sessionChecker wiring", () =
     expect(jwt.ttlSeconds).toBe(60 * 60);
   });
 
-  test("auth with sessionChecker → session-backed default (24h)", () => {
+  test("auth with sessionChecker → session-backed default (8h)", () => {
     const { jwt } = buildServer({
       registry,
       context: {},
@@ -31,7 +31,7 @@ describe("buildServer — jwtTtl default depends on sessionChecker wiring", () =
         sessionChecker: async () => "live",
       },
     });
-    expect(jwt.ttlSeconds).toBe(24 * 60 * 60);
+    expect(jwt.ttlSeconds).toBe(8 * 60 * 60);
   });
 
   test("explicit jwtTtl wins regardless of sessionChecker wiring", () => {

package/src/api/api-constants.ts

@@ -27,10 +27,10 @@ export const Routes = {
   authConfirmAccountUnlock: "/auth/confirm-account-unlock",
   authSignupRequest: "/auth/signup-request",
   authSignupConfirm: "/auth/signup-confirm",
-  // Tenant-Invite (Magic-Link): 3 separate accept-Endpoints für klare
-  // Branch-Separation. Plus invite-info als public-readable details
-  // damit das Frontend "Du wirst eingeladen zu Tenant X als Role Y"
-  // anzeigen kann bevor der User submitted.
+  // Tenant invite (magic link): 3 separate accept endpoints for clear
+  // branch separation. Plus invite-info as public-readable details so
+  // the frontend can show "You're invited to tenant X as role Y" before
+  // the user submits.
   authInviteAccept: "/auth/invite-accept",
   authInviteAcceptWithLogin: "/auth/invite-accept-with-login",
   authInviteSignupComplete: "/auth/invite-signup-complete",
@@ -53,9 +53,9 @@ export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.authConfirmAccountUnlock}`,
   `/api${Routes.authSignupRequest}`,
   `/api${Routes.authSignupConfirm}`,
-  // invite-accept braucht JWT (logged-in User, Branch 1) — NICHT public.
-  // invite-accept-with-login (Branch 2) und invite-signup-complete
-  // (Branch 3) sind anonymous, brauchen public-skip.
+  // invite-accept requires a JWT (logged-in user, branch 1) — NOT public.
+  // invite-accept-with-login (branch 2) and invite-signup-complete
+  // (branch 3) are anonymous and need the public skip.
   `/api${Routes.authInviteAcceptWithLogin}`,
   `/api${Routes.authInviteSignupComplete}`,
   `/api${Routes.authInviteInfo}`,
@@ -64,6 +64,43 @@ export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.version}`,
 ]);
 
+// Every other route in `Routes` — explicit, so a route can never fall
+// through to "public" by simply being absent from PUBLIC_API_PATHS. A
+// completeness test checks every `Routes` entry against the union of this
+// set and PUBLIC_API_PATHS, so a new route with neither entry fails CI
+// instead of shipping open.
+export const NON_PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
+  `/api${Routes.write}`,
+  `/api${Routes.batch}`,
+  `/api${Routes.query}`,
+  `/api${Routes.command}`,
+  `/api${Routes.sse}`,
+  `/api${Routes.stream}`,
+  // Namespace prefix used only for body-limit registration
+  // (`/api/auth/*` in route-registrars.ts) — never dispatched as its own
+  // route, so it carries no auth bypass either way. Classified non-public
+  // to keep the completeness check total.
+  `/api${Routes.auth}`,
+  `/api${Routes.authLogout}`,
+  `/api${Routes.authTenants}`,
+  `/api${Routes.authSwitchTenant}`,
+  // invite-accept requires a JWT (Branch 1, see PUBLIC_API_PATHS above).
+  `/api${Routes.authInviteAccept}`,
+  `/api${Routes.files}`,
+]);
+
+// Opt-out from the default request-body-size cap (registerBodyLimit applies
+// it to all of /api/* by construction — a new route needs no entry here to
+// be covered). Only routes with their own, deliberately different size
+// contract belong on this list; forgetting an entry is safe (over-limited,
+// not unlimited), so keep it as short as the actual exceptions.
+export const BODY_LIMIT_OPT_OUT_PATHS: ReadonlySet<string> = new Set([
+  // Multipart uploads validate size against `maxUploadSize`/field `maxSize`
+  // (often >1 MiB) after Hono's multipart parse, not before — the generic
+  // JSON cap would reject legitimate uploads before that check ever runs.
+  `/api${Routes.files}`,
+]);
+
 // Methods that can mutate server state. GET/HEAD/OPTIONS are safe under
 // CORS + SameSite-cookie semantics and skip the CSRF / Origin guards entirely.
 export const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set([

package/src/api/auth-middleware.ts

@@ -35,6 +35,17 @@ export type AuthTransport = "cookie" | "bearer";
 // can't keep a locked account authenticated.
 export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing" | "blocked";
 
+// A "live" result may additionally carry roles re-derived fresh from the DB
+// (global user roles + tenant-membership roles, composed via
+// buildSessionRoles) instead of trusting the JWT's roles claim, which was
+// frozen at login/mint time. Bare "live" (no roles) is the fail-open path —
+// a DB throw during role derivation must not turn into a lockout — and the
+// case where no sessionChecker is wired at all; the middleware falls back to
+// payload.roles in both.
+export type AuthSessionCheckResult =
+  | AuthSessionStatus
+  | { readonly status: "live"; readonly roles: readonly string[] };
+
 // Called by the middleware after JWT-verify. Gets the sid AND the expected
 // userId from the JWT's `sub` — the checker MUST confirm the session row
 // both exists + is live AND belongs to expectedUserId. Without the userId
@@ -45,7 +56,7 @@ export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing" | "bl
 export type AuthSessionChecker = (
   sid: string,
   expectedUserId: string,
-) => Promise<AuthSessionStatus>;
+) => Promise<AuthSessionCheckResult>;
 
 // Resolves a raw bearer token into a SessionUser, or null when no registered
 // provider claims it (or the claiming provider rejects it as unknown/revoked/
@@ -276,12 +287,17 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     // token carries a sid.
     // A checker wired without a sid on the token means the token predates
     // session tracking (or the JWT was forged) — reject.
+    let derivedRoles: readonly string[] | undefined;
     if (sessionChecker) {
       if (payload.jti) {
-        const status = await sessionChecker(payload.jti, payload.sub);
+        const result = await sessionChecker(payload.jti, payload.sub);
+        const status = typeof result === "string" ? result : result.status;
         if (status !== "live") {
           return sessionInvalid(c, status);
         }
+        if (typeof result === "object") {
+          derivedRoles = result.roles;
+        }
       } else {
         return sessionInvalid(c, "no_sid");
       }
@@ -306,7 +322,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     const user: SessionUser = {
       id: payload.sub,
       tenantId: payload.tenantId,
-      roles: payload.roles,
+      roles: derivedRoles ?? payload.roles,
       ...(payload.timezone ? { timezone: payload.timezone } : {}),
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),

package/src/api/index.ts

@@ -5,6 +5,7 @@ export type {
   AnonymousAccessResolved,
   AuthMiddlewareOptions,
   AuthSessionChecker,
+  AuthSessionCheckResult,
   AuthSessionStatus,
   TenantExists,
   TenantLifecycleStatusResolver,

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,28 +22,26 @@ import {
 
 // --- Body size limit ------------------------------------------------------
 
-const BODY_LIMIT_PATHS = [
-  `/api${Routes.write}`,
-  `/api${Routes.batch}`,
-  `/api${Routes.query}`,
-  `/api${Routes.command}`,
-  `/api${Routes.stream}`,
-  `/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/stream + /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) -----------------------------------------
@@ -101,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/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/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);