@cosmicdrift/kumiko-dev-server 0.243.2 → 0.243.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.243.2",
+  "version": "0.243.4",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -59,9 +59,9 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.243.2",
-    "@cosmicdrift/kumiko-framework": "0.243.2",
-    "@cosmicdrift/kumiko-server-runtime": "0.243.2",
+    "@cosmicdrift/kumiko-bundled-features": "0.243.4",
+    "@cosmicdrift/kumiko-framework": "0.243.4",
+    "@cosmicdrift/kumiko-server-runtime": "0.243.4",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/create-kumiko-server.integration.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { NO_ROUTE_MATCH_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
@@ -571,3 +571,96 @@ describe("createKumikoServer — tryHonoFirst 404-vs-router-miss (#2435)", () =>
     expect(deniedRes.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
   });
 });
+
+// A dotted GET path (e.g. /marketing/hero.png) used to fall through the SPA
+// catch-all's "no dot" filter straight to the API stack and 404 — works in
+// prod (buildStaticFallback's disk lookup under staticDir) but not dev,
+// which had no public/-serving at all. publicDir is process.cwd()-relative
+// (same App-Root convention as resolveStylesheet's src/styles.css lookup),
+// so these tests chdir into a fixture directory for the boot.
+describe("createKumikoServer — public/ static files", () => {
+  test("GET on an existing file under public/ → 200, correct content-type + content", async () => {
+    const tmpDir = realpathSync(mkdtempSync(join(tmpdir(), "kumiko-public-")));
+    const publicDir = join(tmpDir, "public");
+    mkdirSync(join(publicDir, "marketing"), { recursive: true });
+    writeFileSync(join(publicDir, "marketing", "hero.png"), "PNGDATA");
+    const cwdBefore = process.cwd();
+    process.chdir(tmpDir);
+    try {
+      handle = await createKumikoServer({
+        features: [probeFeature],
+        port: 0,
+        installSignalHandlers: false,
+      });
+      const res = await handle.fetch(new Request("http://localhost/marketing/hero.png"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("image/png");
+      expect(await res.text()).toBe("PNGDATA");
+    } finally {
+      process.chdir(cwdBefore);
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("traversal attempts never serve a file from outside public/", async () => {
+    const tmpDir = realpathSync(mkdtempSync(join(tmpdir(), "kumiko-public-traversal-")));
+    const publicDir = join(tmpDir, "public");
+    mkdirSync(publicDir, { recursive: true });
+    // Secret sits as a SIBLING of public/ — a traversal that escapes
+    // containment would read this instead of 404ing.
+    writeFileSync(join(tmpDir, "secret.txt"), "TOP-SECRET");
+    const cwdBefore = process.cwd();
+    process.chdir(tmpDir);
+    try {
+      handle = await createKumikoServer({
+        features: [probeFeature],
+        port: 0,
+        installSignalHandlers: false,
+      });
+
+      // WHATWG URL parsing already collapses a literal ".." segment (it's
+      // delimited by a real "/"), so this pins the composed behavior —
+      // request never reaches secret.txt — rather than the guard itself.
+      const literal = await handle.fetch(new Request("http://localhost/../secret.txt"));
+      expect(literal.status).not.toBe(200);
+
+      // %2e%2e%2f is the actual vector the decode+resolve+containment guard
+      // exists for: URL path-parsing only normalizes dot-segments split by a
+      // literal "/", so an encoded slash survives untouched into pathname —
+      // without the explicit decode in resolvePublicFilePath this would
+      // resolve straight to tmpDir/secret.txt.
+      const encoded = await handle.fetch(new Request("http://localhost/%2e%2e%2fsecret.txt"));
+      expect(encoded.status).not.toBe(200);
+
+      // Neither attempt leaked the secret's content through any other path
+      // (e.g. as an error body).
+      expect(await literal.clone().text()).not.toContain("TOP-SECRET");
+      expect(await encoded.clone().text()).not.toContain("TOP-SECRET");
+    } finally {
+      process.chdir(cwdBefore);
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("a dot-less path still hits the SPA catch-all, not the public/-file lookup", async () => {
+    const tmpDir = realpathSync(mkdtempSync(join(tmpdir(), "kumiko-public-spa-")));
+    const publicDir = join(tmpDir, "public");
+    mkdirSync(publicDir, { recursive: true });
+    const cwdBefore = process.cwd();
+    process.chdir(tmpDir);
+    try {
+      handle = await createKumikoServer({
+        features: [probeFeature],
+        port: 0,
+        installSignalHandlers: false,
+      });
+      const res = await handle.fetch(new Request("http://localhost/some/client-route"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toMatch(/text\/html/);
+      expect(await res.text()).toMatch(/<div id="root">/);
+    } finally {
+      process.chdir(cwdBefore);
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/create-kumiko-server.ts

@@ -16,9 +16,9 @@
 
 import { spawn } from "node:child_process";
 import { existsSync, mkdtempSync, statSync } from "node:fs";
-import { readFile, watch } from "node:fs/promises";
+import { readFile, realpath, watch } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { resolveAnonymousAccessFromRegistry } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { type AuthRoutesConfig, generateToken } from "@cosmicdrift/kumiko-framework/api";
 import { buildAppSchema, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
@@ -42,6 +42,7 @@ import {
   resolveTailwindCli,
 } from "@cosmicdrift/kumiko-server-runtime/resolve-tailwind-cli";
 import {
+  type HonoLikeApp,
   stripNoRouteMatchHeader,
   tryHonoFirst,
 } from "@cosmicdrift/kumiko-server-runtime/try-hono-first";
@@ -336,6 +337,118 @@ function injectStylesheet(html: string): string {
     : `${link}${html}`;
 }
 
+// GET/HEAD to a non-API, non-SSE path — the dispatch-worthy set shared by
+// the SPA catch-all and the public/-file lookup below (they split on
+// whether the path has a dot).
+function isRoutableGetOrHead(req: Request, pathname: string): boolean {
+  return (
+    (req.method === "GET" || req.method === "HEAD") &&
+    !pathname.startsWith("/api/") &&
+    !pathname.startsWith("/sse")
+  );
+}
+
+// Resolves a request pathname to a file inside publicDir, or undefined if
+// it isn't one. Two traversal vectors, both must be blocked:
+//   - literal ".." segments (new URL() already collapses these in
+//     `pathname`, but resolve()+containment is checked regardless — no
+//     path-safety may depend on caller behavior upstream).
+//   - percent-encoded slashes (e.g. "%2e%2e%2f"): WHATWG URL parsing only
+//     normalizes dot-segments that are delimited by a literal "/", so an
+//     encoded slash survives into `pathname` untouched. decodeURIComponent
+//     resolves it to "../" before the containment check runs.
+function resolvePublicFilePath(pathname: string, publicDir: string): string | undefined {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return undefined;
+  }
+  const resolved = resolve(publicDir, `.${decoded}`);
+  return resolved === publicDir || resolved.startsWith(publicDir + sep) ? resolved : undefined;
+}
+
+// Same extension → content-type mapping as prod's
+// run-prod-app-static-files.ts#mimeTypeFor — that function isn't part of
+// server-runtime's public exports (its own package.json "exports" map),
+// so this is a small self-contained copy rather than a new cross-package
+// export for one call site.
+const PUBLIC_FILE_MIME_TYPES = new Map<string, string>([
+  ["html", "text/html; charset=utf-8"],
+  ["js", "text/javascript; charset=utf-8"],
+  ["mjs", "text/javascript; charset=utf-8"],
+  ["css", "text/css; charset=utf-8"],
+  ["json", "application/json; charset=utf-8"],
+  ["svg", "image/svg+xml"],
+  ["png", "image/png"],
+  ["jpg", "image/jpeg"],
+  ["jpeg", "image/jpeg"],
+  ["ico", "image/x-icon"],
+  ["txt", "text/plain; charset=utf-8"],
+  ["xml", "application/xml; charset=utf-8"],
+  ["webmanifest", "application/manifest+json"],
+]);
+
+function publicFileMimeType(filePath: string): string {
+  const ext = filePath.toLowerCase().split(".").pop() ?? "";
+  return PUBLIC_FILE_MIME_TYPES.get(ext) ?? "application/octet-stream";
+}
+
+// Reads a file under publicDir for the dev-server's static-asset fallback
+// (dev-parity with prod's disk lookup in buildStaticFallback). undefined
+// means "not a servable file here" — caller treats that as a router miss,
+// same as ENOENT/EISDIR/ENOTDIR further down.
+async function servePublicFile(
+  pathname: string,
+  publicDir: string,
+): Promise<{ readonly bytes: Uint8Array; readonly mime: string } | undefined> {
+  const filePath = resolvePublicFilePath(pathname, publicDir);
+  if (filePath === undefined) return undefined;
+  try {
+    const bytes = await readFile(filePath);
+    // Lexical containment (above) only catches "..", not a symlink inside
+    // publicDir that points outside it on disk — realpath resolves the
+    // actual target and the same containment check runs against it.
+    const real = await realpath(filePath);
+    if (real !== publicDir && !real.startsWith(publicDir + sep)) return undefined;
+    return { bytes, mime: publicFileMimeType(filePath) };
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT" || code === "EISDIR" || code === "ENOTDIR") return undefined;
+    throw err;
+  }
+}
+
+// Static assets under public/ — prod serves these via buildStaticFallback's
+// disk lookup (run-prod-app-static-files.ts), dev previously had no
+// equivalent: a dotted path (e.g. /marketing/hero.png) fell straight
+// through to the API stack and 404ed. Hono still goes first (an
+// r.httpRoute could itself own a dotted path), then the file on disk,
+// then the router-miss 404 — mirrors handleFetch's SPA branch. undefined
+// means "not a static-asset request", caller falls through to the next
+// route.
+async function tryServePublicAsset(
+  req: Request,
+  pathname: string,
+  app: HonoLikeApp,
+  publicDir: string,
+): Promise<Response | undefined> {
+  if (!isRoutableGetOrHead(req, pathname) || !pathname.includes(".")) return undefined;
+  const honoTry = await tryHonoFirst(app, req);
+  if (honoTry.matched) {
+    return honoTry.response;
+  }
+  const file = await servePublicFile(pathname, publicDir);
+  if (file !== undefined) {
+    // @cast-boundary Buffer satisfies BodyInit at runtime, bun-types
+    // just doesn't say so — same cast run-prod-app-static-files.ts uses.
+    return new Response(file.bytes as unknown as BodyInit, {
+      headers: { "Content-Type": file.mime },
+    });
+  }
+  return honoTry.response;
+}
+
 // injectSchema lebt in `./inject-schema.ts` damit dev-server + prod-
 // server denselben Inject-Pfad nutzen.
 
@@ -829,6 +942,10 @@ export async function createKumikoServer(
   const bundleByAssetPath = new Map<string, string>();
   for (const e of entries) bundleByAssetPath.set(assetPathFor(e.name), e.name);
 
+  // App-root convention (same as expandWatchPatterns/resolveStylesheet above):
+  // process.cwd() is the app workspace, so public/ is its static asset dir.
+  const publicDir = resolve(process.cwd(), "public");
+
   const handleFetch = async (req: Request): Promise<Response> => {
     const url = new URL(req.url);
 
@@ -913,9 +1030,7 @@ export async function createKumikoServer(
     if (
       // HEAD mitnehmen — prod (runProdApp) fällt für GET UND HEAD auf die
       // SPA zurück; ohne das liefert dev 404 wo prod 200 liefert.
-      (req.method === "GET" || req.method === "HEAD") &&
-      !url.pathname.startsWith("/api/") &&
-      !url.pathname.startsWith("/sse") &&
+      isRoutableGetOrHead(req, url.pathname) &&
       !url.pathname.includes(".")
     ) {
       const honoTry = await tryHonoFirst(stack.app, req);
@@ -948,10 +1063,15 @@ export async function createKumikoServer(
       return htmlResponse("client", true);
     }
 
-    // Bypasses tryHonoFirst entirely (API paths, dotted paths, /sse,
-    // non-GET/HEAD), so the router-miss marker must be stripped here too —
-    // otherwise an unmatched path would leak it straight to the client
-    // (see try-hono-first.ts's header-hygiene note).
+    // Static assets under public/ — see tryServePublicAsset's own comment
+    // for the Hono → file → router-miss ordering.
+    const staticAsset = await tryServePublicAsset(req, url.pathname, stack.app, publicDir);
+    if (staticAsset !== undefined) return staticAsset;
+
+    // Bypasses tryHonoFirst entirely (API paths, /sse, non-GET/HEAD), so the
+    // router-miss marker must be stripped here too — otherwise an unmatched
+    // path would leak it straight to the client (see try-hono-first.ts's
+    // header-hygiene note).
     return stripNoRouteMatchHeader(await stack.app.fetch(req));
   };