npm - @cosmicdrift/kumiko-server-runtime - Versions diffs - 0.220.0 → 0.221.0 - Mend

@cosmicdrift/kumiko-server-runtime 0.220.0 → 0.221.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/package.json +3 -3
package/src/__tests__/run-prod-app-static-files.test.ts +40 -6
package/src/__tests__/run-prod-app.integration.test.ts +91 -0
package/src/__tests__/try-hono-first.test.ts +66 -21
package/src/boot/job-run-logger.ts +2 -2
package/src/run-prod-app-static-files.ts +6 -3
package/src/run-prod-app.ts +14 -5
package/src/try-hono-first.ts +58 -27

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.220.0",
+  "version": "0.221.0",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -80,8 +80,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.220.0",
-    "@cosmicdrift/kumiko-framework": "0.220.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.221.0",
+    "@cosmicdrift/kumiko-framework": "0.221.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/run-prod-app-static-files.test.ts CHANGED Viewed

@@ -4,6 +4,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { NO_ROUTE_MATCH_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
 import {
   buildStaticFallback,
   mimeTypeFor,
@@ -11,6 +12,15 @@ import {
   serveDiskFile,
 } from "../run-prod-app-static-files";
+// Stand-in for a real Hono app's fetch when the test wants "no route
+// matched" — must carry NO_ROUTE_MATCH_HEADER_NAME, same as buildServer's
+// app.notFound() (framework/api/server.ts), otherwise tryHonoFirst treats
+// the fake apiHandler's 404 as a matched route's own deliberate 404 (see
+// kumiko-framework#2435) and never falls through to disk/SPA.
+function noRouteMatchedResponse(): Response {
+  return new Response("404", { status: 404, headers: { [NO_ROUTE_MATCH_HEADER_NAME]: "1" } });
+}
 describe("mimeTypeFor", () => {
   const cases: ReadonlyArray<readonly [string, string]> = [
     ["x.html", "text/html; charset=utf-8"],
@@ -94,7 +104,7 @@ describe("buildStaticFallback hostDispatch", () => {
   test("hostDispatch html pointing at missing file → 500", async () => {
     const handler = buildStaticFallback(
-      () => new Response("api-404", { status: 404 }),
+      () => noRouteMatchedResponse(),
       tmp,
       "{}",
       () => ({ kind: "html", file: "gone.html" }),
@@ -106,7 +116,7 @@ describe("buildStaticFallback hostDispatch", () => {
   test("hostDispatch not-found → 404; redirect → 302", async () => {
     const notFound = buildStaticFallback(
-      () => new Response("x", { status: 404 }),
+      () => noRouteMatchedResponse(),
       tmp,
       "{}",
       () => ({ kind: "not-found" }),
@@ -114,7 +124,7 @@ describe("buildStaticFallback hostDispatch", () => {
     expect((await notFound(new Request("http://t/"))).status).toBe(404);
     const redirect = buildStaticFallback(
-      () => new Response("x", { status: 404 }),
+      () => noRouteMatchedResponse(),
       tmp,
       "{}",
       () => ({ kind: "redirect", to: "https://example.com/", status: 301 }),
@@ -133,7 +143,7 @@ describe("buildStaticFallback hostDispatch", () => {
   test("serves disk asset under staticDir", async () => {
     await writeFile(join(tmp, "logo.png"), "PNGDATA");
-    const handler = buildStaticFallback(() => new Response("404", { status: 404 }), tmp, "{}");
+    const handler = buildStaticFallback(() => noRouteMatchedResponse(), tmp, "{}");
     const res = await handler(new Request("http://t/logo.png"));
     expect(res.status).toBe(200);
     expect(res.headers.get("content-type")).toBe("image/png");
@@ -143,7 +153,7 @@ describe("buildStaticFallback hostDispatch", () => {
   test("a request for a directory copied verbatim from public/ falls back to index.html instead of 500ing", async () => {
     await mkdir(join(tmp, "sub"));
     await writeFile(join(tmp, "index.html"), "<!doctype html><html><body>spa-shell</body></html>");
-    const handler = buildStaticFallback(() => new Response("404", { status: 404 }), tmp, "{}");
+    const handler = buildStaticFallback(() => noRouteMatchedResponse(), tmp, "{}");
     const res = await handler(new Request("http://t/sub"));
     expect(res.status).toBe(200);
     expect(await res.text()).toContain("spa-shell");
@@ -152,7 +162,7 @@ describe("buildStaticFallback hostDispatch", () => {
   test("hostDispatch html with CSP + Vary: Host", async () => {
     await writeFile(join(tmp, "tenant.html"), "<!doctype html><html><body>ok</body></html>");
     const handler = buildStaticFallback(
-      () => new Response("404", { status: 404 }),
+      () => noRouteMatchedResponse(),
       tmp,
       '{"screens":[]}',
       () => ({
@@ -168,4 +178,28 @@ describe("buildStaticFallback hostDispatch", () => {
     expect(res.headers.get("content-security-policy")).toBe("default-src 'self'");
     expect(await res.text()).toContain("ok");
   });
+  test("a matched route's own deliberate 404 stays 404, not masked as the SPA shell (#2435)", async () => {
+    // An index.html exists on disk, so the OLD status-only heuristic would
+    // have served it with status 200 for ANY 404 — including one from a
+    // matched route (e.g. file-derivatives' public-variant default-deny)
+    // that never carries NO_ROUTE_MATCH_HEADER_NAME.
+    await writeFile(join(tmp, "index.html"), "<!doctype html><html><body>spa-shell</body></html>");
+    const handler = buildStaticFallback(
+      () => new Response("not found", { status: 404 }),
+      tmp,
+      "{}",
+    );
+    const res = await handler(new Request("http://t/files/deadbeef/thumb"));
+    expect(res.status).toBe(404);
+    expect(await res.text()).toBe("not found");
+  });
+  test("an unknown SPA route with no matching handler still gets the SPA shell", async () => {
+    await writeFile(join(tmp, "index.html"), "<!doctype html><html><body>spa-shell</body></html>");
+    const handler = buildStaticFallback(() => noRouteMatchedResponse(), tmp, "{}");
+    const res = await handler(new Request("http://t/some/client-side/route"));
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("spa-shell");
+  });
 });

package/src/__tests__/run-prod-app.integration.test.ts CHANGED Viewed

@@ -20,6 +20,7 @@ import {
   userSessionEntity,
 } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { userEntity } from "@cosmicdrift/kumiko-bundled-features/user";
+import { NO_ROUTE_MATCH_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { InMemoryKmsAdapter, type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import { createDbConnection } from "@cosmicdrift/kumiko-framework/db";
@@ -412,6 +413,96 @@ describe("runProdApp", () => {
     expect(res.headers.get("etag")).toBeTruthy();
   });
+  test("static-fallback: a matched extraRoute's own deliberate 404 stays 404, not masked as the SPA shell (#2435)", async () => {
+    // kumiko-framework#2435: tryHonoFirst used to treat ANY 404 as "no
+    // route matched" and fall through to index.html with status 200 —
+    // masking a matched route's intentional 404 (e.g. default-deny reads
+    // like file-derivatives' public-variant route). An index.html exists
+    // here specifically to prove the SPA-fallback does NOT win.
+    const tmpStaticDir = await createTempStaticDir({
+      "index.html": "<html>SPA shell</html>",
+    });
+    const handle = await boot(undefined, {
+      staticDir: tmpStaticDir,
+      extraRoutes: (app) => {
+        app.get("/probe/:id", (c) => {
+          if (c.req.param("id") === "missing") return c.text("not found", 404);
+          return c.text(`probe:${c.req.param("id")}`, 200);
+        });
+      },
+    });
+    const res = await handle.fetch(new Request("http://test/probe/missing"));
+    expect(res.status).toBe(404);
+    expect(await res.text()).toBe("not found");
+    expect(res.headers.get("content-type") ?? "").not.toMatch(/text\/html/);
+    expect(res.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
+  });
+  test("static-fallback: an unknown SPA route still gets the SPA shell alongside a route that 404s (#2435)", async () => {
+    const tmpStaticDir = await createTempStaticDir({
+      "index.html": "<html>SPA shell</html>",
+    });
+    const handle = await boot(undefined, {
+      staticDir: tmpStaticDir,
+      extraRoutes: (app) => {
+        app.get("/probe/:id", (c) => c.text("not found", 404));
+      },
+    });
+    const res = await handle.fetch(new Request("http://test/some/client-route"));
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("SPA shell");
+    expect(res.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
+  });
+  test("static-fallback: an unmatched /api/* path stays a plain 404, no marker leak (#2435)", async () => {
+    // /api/* is a passthrough in buildStaticFallback (always Hono, never
+    // the SPA shell) — bypasses tryHonoFirst entirely, so the strip at
+    // that passthrough site is what's under test here. anonymousAccess is
+    // wired so this anonymous GET clears the auth middleware and actually
+    // reaches Hono's router (unauthenticated /api/* requests get a plain
+    // 401 from the auth guard before routing is even attempted, which
+    // would test the auth guard instead of the router-miss path).
+    const tmpStaticDir = await createTempStaticDir({
+      "index.html": "<html>SPA shell</html>",
+    });
+    const handle = await boot(undefined, {
+      staticDir: tmpStaticDir,
+      anonymousAccess: { defaultTenantId: TENANT_ID },
+    });
+    const res = await handle.fetch(new Request("http://test/api/totally-unknown-route"));
+    expect(res.status).toBe(404);
+    expect(await res.text()).not.toContain("SPA shell");
+    expect(res.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
+  });
+  test("no staticDir (split-deploy/API-only boot): a router-miss never leaks the internal marker header to the client (#2435)", async () => {
+    // Without staticDir, fetchHandler is app.fetch directly — it never goes
+    // through buildStaticFallback/tryHonoFirst, so the strip has to happen
+    // at this bypass site too (run-prod-app.ts's fetchHandler assembly).
+    const handle = await boot(undefined, {
+      extraRoutes: (app) => {
+        app.get("/probe/:id", (c) => {
+          if (c.req.param("id") === "missing") return c.text("not found", 404);
+          return c.text(`probe:${c.req.param("id")}`, 200);
+        });
+      },
+    });
+    const routerMiss = await handle.fetch(new Request("http://test/totally/unknown/path"));
+    expect(routerMiss.status).toBe(404);
+    expect(routerMiss.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
+    const deliberate404 = await handle.fetch(new Request("http://test/probe/missing"));
+    expect(deliberate404.status).toBe(404);
+    expect(await deliberate404.text()).toBe("not found");
+    expect(deliberate404.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
+  });
   test("static-fallback: If-None-Match → 304 on disk file", async () => {
     const tmpStaticDir = await createTempStaticDir({
       "robots.txt": "User-agent: *\nAllow: /",

package/src/__tests__/try-hono-first.test.ts CHANGED Viewed

@@ -1,12 +1,19 @@
-// Pure-function pin für tryHonoFirst. Trivial aber load-bearing:
-// Drift zwischen dev (createKumikoServer) und prod (runProdApp) hat
-// schon einen Bug verursacht (legal-pages funktionierten in prod aber
-// nicht in dev). Beide nutzen jetzt diesen helper — wenn die Semantik
-// sich ändert (z.B. "matched" auch für 4xx anders als 404), MÜSSEN
-// beide Pfade synchron updaten.
+// Pure-function pin for tryHonoFirst. Trivial but load-bearing: drift
+// between dev (createKumikoServer) and prod (runProdApp) has already
+// caused a bug before (legal-pages worked in prod but not in dev). Both
+// now use this helper — if the semantics change (e.g. "matched" treating
+// other 4xx differently than 404), both paths MUST update in sync.
+//
+// kumiko-framework#2435: "matched" used to depend ONLY on the status code
+// (404 = no match) — that masked any matched route's deliberate 404 as the
+// SPA shell with status 200. The contract now: a router-miss is ONLY a 404
+// that ADDITIONALLY carries NO_ROUTE_MATCH_HEADER_NAME (set by buildServer's
+// app.notFound(), see framework/api/server.ts). A plain 404 without the
+// marker counts as matched — the route answered deliberately.
 import { describe, expect, test } from "bun:test";
-import { type HonoLikeApp, tryHonoFirst } from "../try-hono-first";
+import { NO_ROUTE_MATCH_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
+import { type HonoLikeApp, stripNoRouteMatchHeader, tryHonoFirst } from "../try-hono-first";
 function makeApp(response: Response): HonoLikeApp {
   return { fetch: () => response };
@@ -16,28 +23,47 @@ function makeAsyncApp(response: Response): HonoLikeApp {
   return { fetch: async () => response };
 }
+function routerMissResponse(): Response {
+  return new Response("Not Found", {
+    status: 404,
+    headers: { [NO_ROUTE_MATCH_HEADER_NAME]: "1" },
+  });
+}
 describe("tryHonoFirst", () => {
-  test("matched=true bei 200 (Hono-route greift)", async () => {
+  test("matched=true on 200 (a Hono route handled it)", async () => {
     const app = makeApp(new Response("ok", { status: 200 }));
     const res = await tryHonoFirst(app, new Request("http://test/foo"));
     expect(res.matched).toBe(true);
     expect(res.response.status).toBe(200);
   });
-  test("matched=false bei 404 (keine Route — caller fällt auf SPA-fallback)", async () => {
-    const app = makeApp(new Response("not found", { status: 404 }));
+  test("matched=false on a router-miss (404 + NO_ROUTE_MATCH_HEADER_NAME — caller falls back to the SPA)", async () => {
+    const app = makeApp(routerMissResponse());
     const res = await tryHonoFirst(app, new Request("http://test/unknown"));
     expect(res.matched).toBe(false);
-    // response wird trotzdem zurückgegeben — caller kann den 404 als
-    // letztes Sicherheitsnetz nutzen wenn auch SPA-fallback nichts liefert.
+    // response is still returned — caller can use the 404 as a last-resort
+    // safety net if the SPA fallback doesn't deliver anything either.
+    expect(res.response.status).toBe(404);
+  });
+  test("matched=true for a matched route that deliberately answers 404 (no marker — bug #2435)", async () => {
+    // The actual bug: file-derivatives' public-variant route matches and
+    // answers `c.text("not found", 404)` for default-deny — NOT a
+    // router-miss. Without the marker header this used to be
+    // misinterpreted as "no match" and the caller would have served the
+    // SPA shell with status 200 instead of passing the real 404 through.
+    const app = makeApp(new Response("not found", { status: 404 }));
+    const res = await tryHonoFirst(app, new Request("http://test/files/x/thumb"));
+    expect(res.matched).toBe(true);
     expect(res.response.status).toBe(404);
   });
-  test("matched=true bei 401/403/500 (Hono hat geantwortet — kein SPA-fallback)", async () => {
-    // Bug-Pin: matched darf NUR bei status=404 false sein. Wenn Hono
-    // 401 (auth required) returnt, war die Route klar gefunden + hat
-    // bewusst rejected — SPA-fallback würde das überschreiben und den
-    // User auf eine SPA leiten statt die 401-message zu zeigen.
+  test("matched=true on 401/403/500 (Hono answered — no SPA fallback)", async () => {
+    // Bug pin: matched may ONLY be false on a router-miss. When Hono
+    // returns 401 (auth required), the route was clearly found and
+    // deliberately rejected — an SPA fallback would override that and
+    // redirect the user into the SPA instead of showing the 401 message.
     for (const status of [401, 403, 422, 500] as const) {
       const app = makeApp(new Response(null, { status }));
       const res = await tryHonoFirst(app, new Request("http://test/x"));
@@ -45,10 +71,10 @@ describe("tryHonoFirst", () => {
     }
   });
-  test("akzeptiert sowohl sync als auch async fetch (Hono-Variation)", async () => {
-    // Hono.app.fetch returnt Response | Promise<Response> abhängig vom
-    // handler-mix. createApiEntrypoint's apiHandler dasselbe. Helper
-    // muss beide schluckable.
+  test("accepts both sync and async fetch (Hono variation)", async () => {
+    // Hono.app.fetch returns Response | Promise<Response> depending on the
+    // handler mix. createApiEntrypoint's apiHandler does the same. The
+    // helper must accept both.
     const sync = await tryHonoFirst(
       makeApp(new Response("s", { status: 200 })),
       new Request("http://t/"),
@@ -60,4 +86,23 @@ describe("tryHonoFirst", () => {
     expect(sync.matched).toBe(true);
     expect(asyncRes.matched).toBe(true);
   });
+  test("strips NO_ROUTE_MATCH_HEADER_NAME from the returned response (never leaks to the client)", async () => {
+    const app = makeApp(routerMissResponse());
+    const res = await tryHonoFirst(app, new Request("http://test/unknown"));
+    expect(res.response.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
+  });
+});
+describe("stripNoRouteMatchHeader", () => {
+  test("removes the header when present", () => {
+    const res = stripNoRouteMatchHeader(routerMissResponse());
+    expect(res.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
+  });
+  test("is a no-op when the header is absent", () => {
+    const res = stripNoRouteMatchHeader(new Response("ok", { status: 200 }));
+    expect(res.status).toBe(200);
+    expect(res.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
+  });
 });

package/src/boot/job-run-logger.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 import { createJobRunLogger } from "@cosmicdrift/kumiko-bundled-features/jobs";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
-import type { JobRunIn } from "@cosmicdrift/kumiko-framework/engine/types";
+import type { AppContext, JobRunIn } from "@cosmicdrift/kumiko-framework/engine/types";
 import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 export function jobRunLoggerCallbacks(
@@ -16,7 +16,7 @@ export function jobRunLoggerCallbacks(
 export async function startDevJobRunners(opts: {
   readonly registry: Registry;
   readonly db: DbConnection;
-  readonly context: Record<string, unknown>;
+  readonly context: AppContext;
   readonly redisUrl: string;
 }): Promise<{ readonly runners: readonly JobRunner[]; readonly stop: () => Promise<void> }> {
   const jobs = [...opts.registry.getAllJobs().values()];

package/src/run-prod-app-static-files.ts CHANGED Viewed

@@ -7,7 +7,7 @@ import {
 import { ASSETS_DIR } from "./build-prod-bundle";
 import { injectSchema } from "./inject-schema";
 import type { HostDispatchFn } from "./run-prod-app";
-import { tryHonoFirst } from "./try-hono-first";
+import { stripNoRouteMatchHeader, tryHonoFirst } from "./try-hono-first";
 // Static-asset + SPA-fallback serving for runProdApp's HTTP handler. Split
 // out of run-prod-app.ts (#1005, Welle 2) — mechanical relocation, these
@@ -201,9 +201,12 @@ export function buildStaticFallback(
   return async (req: Request): Promise<Response> => {
     const url = new URL(req.url);
-    // /api/* and /health → always Hono (Dispatcher + Health-Probe).
+    // /api/* and /health → always Hono (Dispatcher + Health-Probe). Bypasses
+    // tryHonoFirst entirely, so the router-miss marker must be stripped
+    // here too — otherwise an unmatched /api/* path would leak it straight
+    // to the client (see try-hono-first.ts's header-hygiene note).
     if (url.pathname.startsWith("/api/") || url.pathname === "/health") {
-      return apiHandler(req);
+      return stripNoRouteMatchHeader(await apiHandler(req));
     }
     // Hono-First für andere Pfade: extraRoutes (z.B. /feed.xml,

package/src/run-prod-app.ts CHANGED Viewed

@@ -154,6 +154,7 @@ import { buildStaticFallback } from "./run-prod-app-static-files";
 import { type SecurityHeadersOption, withSecurityHeaders } from "./security-headers";
 import { assertSessionBootInvariants } from "./session-boot-gate";
 import { shouldWireProdSessions } from "./session-wiring";
+import { stripNoRouteMatchHeader } from "./try-hono-first";
 export { buildBunServeOptions } from "./bun-serve-options";
 export {
@@ -492,6 +493,9 @@ export type RunProdAppOptions = {
    *  `({db, redis, registry}) => Record<string, unknown>` — gleiches
    *  Pattern wie `anonymousAccess`. Eine App die einen dieser Keys selbst
    *  setzt (z.B. eigener configResolver) überschreibt den Default. */
+  /** Boot default locale (BCP-47) for ctx.locale when the request carries
+   *  no locale signal. Merged into AppContext before extraContext (app wins). */
+  readonly defaultLocale?: string;
   readonly extraContext?: ExtraContextOption;
   /** MasterKeyProvider für die auto-verdrahtete `ctx.secrets`. Default:
    *  `createEnvMasterKeyProvider` (KEK aus `KUMIKO_SECRETS_MASTER_KEY_V<n>`).
@@ -927,10 +931,10 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     crypto: bootCrypto,
     ...(options.kms && { kms: options.kms }),
   });
-  const extraContext = addConfigAccessorFactory(
-    { ...autoExtraContext, ...resolvedExtraContext },
-    registry,
-  );
+  const extraContext = {
+    ...addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry),
+    ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
+  };
   // @cast-boundary engine-bridge — searchAdapter is an optional context-extension
   // (SharedContextFields.searchAdapter), invisible to extraContext's loose
   // Record<string, unknown>-based typing. Presence check only, no need to
@@ -1237,7 +1241,12 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
           appSchemaJson,
           options.hostDispatch,
         )
-      : entrypoint.app.fetch.bind(entrypoint.app),
+      : // No staticDir (split-deploy / API-only container) → app.fetch's
+        // response goes straight to the client, bypassing buildStaticFallback
+        // (and with it tryHonoFirst) entirely. Must strip the router-miss
+        // marker here too, same reason as the /api/* passthrough in
+        // run-prod-app-static-files.ts (see try-hono-first.ts).
+        async (req: Request) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req)),
     options.securityHeaders,
   );

package/src/try-hono-first.ts CHANGED Viewed

@@ -1,46 +1,77 @@
-// Shared helper für die "Hono-first, SPA-fallback wenn 404"-Strategie.
-// Wird von dev (createKumikoServer.handleFetch) UND prod (runProdApp's
-// fetch-handler) verwendet — identische Semantik, ein helper. Ohne den
-// shared-Helper drifteten die beiden Pfade silent (genau der Bug der
-// legal-pages im dev-server geshadowed hat — runProdApp's docs sagten
-// "Hono matched VOR fallback", dev-server tat das NICHT).
+// Shared helper for the "Hono-first, SPA-fallback on 404" strategy. Used by
+// both dev (createKumikoServer.handleFetch) AND prod (runProdApp's fetch
+// handler) — identical semantics, one helper. Without the shared helper the
+// two paths drifted silently before (the same bug class that shadowed
+// legal-pages in the dev server — runProdApp's docs said "Hono matches
+// BEFORE fallback", the dev server didn't).
 //
 // Pattern:
-//   1. Try app.fetch(req) — wenn Hono eine route matcht, greift sie.
-//   2. 404 vom Hono-stack → null returnen, caller macht SPA-fallback.
-//   3. Sonstige status (200, 401, 500, ...) → response durchreichen.
+//   1. Try app.fetch(req) — if Hono matches a route, it wins.
+//   2. Router-miss (404 WITH NO_ROUTE_MATCH_HEADER_NAME) → matched=false,
+//      caller does the SPA fallback.
+//   3. Any other status (200, 401, 500, ...) OR a matched route's own 404
+//      WITHOUT the marker → response passes through as-is.
 //
-// req.clone() weil downstream der req body nochmal lesbar sein muss
-// (POST/PUT/PATCH future-proof — heute nur GET-routes betroffen).
+// The status code alone used to be the only signal ("404 = no match") —
+// that masked any matched route's deliberate 404 (e.g. default-deny reads)
+// as the SPA shell with status 200 (kumiko-framework#2435). buildServer
+// (framework/api/server.ts) registers app.notFound() LAST on the app object
+// and marks exactly the "no handler found" case with
+// NO_ROUTE_MATCH_HEADER_NAME — a handler that builds its own
+// `c.text(..., 404)` never routes through this code path. The marker is
+// process-internal only: stripNoRouteMatchHeader removes it from EVERY
+// response before it leaves the process, otherwise a caller could
+// distinguish "unknown path" from "known path, access denied" via the
+// header's presence — exactly what routes like file-derivatives'
+// public-variant deliberately hide behind a single status code.
+//
+// req.clone() because downstream needs to read the request body again
+// (future-proofing for POST/PUT/PATCH — only GET routes today).
+import { NO_ROUTE_MATCH_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
 export type HonoLikeApp = {
-  // Hono.app.fetch ist `(req) => Response | Promise<Response>` (sync wenn
-  // alle Handler sync sind, sonst Promise). createApiEntrypoint's
-  // apiHandler matcht dieselbe shape. Union accepts both — wir await
-  // unten, das funktioniert für beide Fälle.
+  // Hono.app.fetch is `(req) => Response | Promise<Response>` (sync if all
+  // handlers are sync, otherwise a Promise). createApiEntrypoint's
+  // apiHandler matches the same shape. The union accepts both — we await
+  // below, which works for either case.
   readonly fetch: (req: Request) => Response | Promise<Response>;
 };
 export type HonoFirstResult = {
-  /** True wenn Hono eine matchende Route hat (status !== 404).
-   *  Caller returnt dann response direkt.
-   *  False wenn keine Route matcht (status === 404). Caller macht den
-   *  SPA-/static-fallback; response enthält den 404 als final-fallback
-   *  falls auch der SPA-Pfad nichts liefert. */
+  /** True when Hono has a matching route (no router-miss).
+   *  Caller returns the response directly.
+   *  False when no route matches (router-miss, detected via 404 +
+   *  NO_ROUTE_MATCH_HEADER_NAME). Caller does the SPA/static fallback;
+   *  the response still carries the 404 as a final fallback in case the
+   *  SPA path doesn't deliver anything either. */
   readonly matched: boolean;
   readonly response: Response;
 };
+// Removes the internal router-miss marker from a response before it leaves
+// the process. Needed at EVERY site that potentially passes app.fetch()'s
+// response through to a real client — including the passthrough paths that
+// never call tryHonoFirst at all (e.g. /api/* in runProdApp, dotted-paths/
+// non-GET in the dev server). No no-op check needed: Headers.delete() on a
+// missing key is harmless.
+export function stripNoRouteMatchHeader(response: Response): Response {
+  response.headers.delete(NO_ROUTE_MATCH_HEADER_NAME);
+  return response;
+}
 /**
- * Hono-first try: app.fetch ZUERST. Wenn matched (status !== 404), gibt
- * der caller den response direkt zurück. Wenn nicht matched, fällt der
- * caller in den eigenen SPA-/static-fallback zurück — der response (404)
- * bleibt verfügbar als letztes Sicherheitsnetz.
+ * Hono-first try: app.fetch FIRST. If matched (no router-miss), the caller
+ * returns the response directly. If not matched, the caller falls back to
+ * its own SPA/static fallback — the response (404) stays available as a
+ * last-resort safety net.
  *
- * req.clone() weil downstream der req body nochmal lesbar sein muss
- * (POST/PUT/PATCH future-proof — heute nur GET-routes betroffen).
+ * req.clone() because downstream needs to read the request body again
+ * (future-proofing for POST/PUT/PATCH — only GET routes today).
  */
 export async function tryHonoFirst(app: HonoLikeApp, req: Request): Promise<HonoFirstResult> {
   const response = await app.fetch(req.clone());
-  return { matched: response.status !== 404, response };
+  const isRouterMiss = response.status === 404 && response.headers.has(NO_ROUTE_MATCH_HEADER_NAME);
+  stripNoRouteMatchHeader(response);
+  return { matched: !isRouterMiss, response };
 }