@cosmicdrift/kumiko-server-runtime 0.326.1 → 0.328.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.326.1",
+  "version": "0.328.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>",
@@ -62,6 +62,10 @@
       "types": "./src/extra-routes-deps.ts",
       "default": "./src/extra-routes-deps.ts"
     },
+    "./renderer-web-fonts": {
+      "types": "./src/renderer-web-fonts.ts",
+      "default": "./src/renderer-web-fonts.ts"
+    },
     "./resolve-tailwind-cli": {
       "types": "./src/resolve-tailwind-cli.ts",
       "default": "./src/resolve-tailwind-cli.ts"
@@ -76,9 +80,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.326.1",
-    "@cosmicdrift/kumiko-framework": "0.326.1",
-    "@cosmicdrift/kumiko-headless": "0.326.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.328.0",
+    "@cosmicdrift/kumiko-framework": "0.328.0",
+    "@cosmicdrift/kumiko-headless": "0.328.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/build-prod-bundle.inprocess.test.ts

@@ -118,6 +118,46 @@ describe("buildProdBundle in-process (Bun.build)", () => {
     }
   });
 
+  test("renderer-web stylesheet → woff2 files land where the CSS points, no external font URL", async () => {
+    const dir = await mkdtemp(join(REPO_ROOT, ".inproc-fonts-"));
+    const cwd = join(dir, "app");
+    try {
+      await mkdir(join(cwd, "src"), { recursive: true });
+      await writeFile(
+        join(cwd, "src/client.ts"),
+        `const root = document.getElementById("root"); if (root) root.textContent = "hi";`,
+      );
+      await writeFile(
+        join(cwd, "src/styles.css"),
+        `@import "@cosmicdrift/kumiko-renderer-web/styles.css";\n`,
+      );
+      await mkdir(join(cwd, "public"), { recursive: true });
+      await writeFile(
+        join(cwd, "public/index.html"),
+        `<!doctype html><html><head><link rel="stylesheet" href="/styles.css" /></head><body><div id="root"></div><script type="module" src="/client.js"></script></body></html>`,
+      );
+      await writeFile(join(cwd, "package.json"), `{"name":"inproc-fonts","private":true}`);
+
+      const result = await buildProdBundle({ cwd, stylesheet: "src/styles.css" });
+
+      const css = await readFile(join(cwd, "dist", result.manifest["styles.css"] ?? ""), "utf8");
+      const referenced = [
+        ...css.matchAll(/url\("?(\/assets\/kumiko\/fonts\/[a-z0-9-]+\.woff2)"?\)/g),
+      ].map((m) => m[1] ?? "");
+      expect(referenced.length).toBeGreaterThanOrEqual(10);
+      for (const url of referenced) {
+        const file = join(cwd, "dist", url);
+        expect(existsSync(file)).toBe(true);
+        // woff2 magic number
+        expect((await readFile(file)).subarray(0, 4).toString("latin1")).toBe("wOF2");
+      }
+      expect(css).not.toMatch(/url\(\s*["']?(https?:)?\/\//);
+      expect(css).not.toContain("data:font");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
   test("missing stylesheet override → tailwind rejects", async () => {
     const dir = await mkdtemp(join(REPO_ROOT, ".inproc-styles-miss-"));
     const cwd = join(dir, "app");

package/src/__tests__/renderer-web-theme-plugin.integration.test.ts

@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
 import { runTailwindOnce } from "../build-prod-bundle";
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
-const FRAMEWORK_LIGHT_PRIMARY = "--color-primary:#171717";
+const FRAMEWORK_LIGHT_PRIMARY = "--color-primary:#1a1c1e";
 
 function bunAvailable(): boolean {
   try {

package/src/__tests__/run-prod-app-spec.test.ts

@@ -5,7 +5,14 @@
 // Tweaks.
 
 import { describe, expect, test } from "bun:test";
-import { SSE_HEARTBEAT_INTERVAL_MS } from "@cosmicdrift/kumiko-framework/api";
+import {
+  type KumikoServeEnv,
+  type KumikoWebSocketData,
+  SSE_HEARTBEAT_INTERVAL_MS,
+  WEBSOCKET_BACKPRESSURE_LIMIT_BYTES,
+  WEBSOCKET_HEARTBEAT_INTERVAL_MS,
+  WEBSOCKET_MAX_PAYLOAD_BYTES,
+} from "@cosmicdrift/kumiko-framework/api";
 import {
   createEntity,
   createFileField,
@@ -30,6 +37,56 @@ describe("Bun.serve options for production", () => {
     expect(opts.idleTimeout).toBe(0);
   });
 
+  test("websocket payload cap is 1 MiB and the ping cadence stays under nginx's 60 s", () => {
+    // ingress-nginx's default proxy-read-timeout is 60 s: a quiet socket needs a server ping below it.
+    const opts = buildBunServeOptions(0, () => new Response("ok"));
+    expect(opts.websocket.maxPayloadLength).toBe(1024 * 1024);
+    expect(WEBSOCKET_MAX_PAYLOAD_BYTES).toBe(1024 * 1024);
+    expect(WEBSOCKET_HEARTBEAT_INTERVAL_MS).toBeLessThan(60_000);
+  });
+
+  test("a stalled reader is cut off: 4 MiB backpressure limit, close on limit", () => {
+    const opts = buildBunServeOptions(0, () => new Response("ok"));
+    expect(opts.websocket.backpressureLimit).toBe(4 * 1024 * 1024);
+    expect(WEBSOCKET_BACKPRESSURE_LIMIT_BYTES).toBe(4 * 1024 * 1024);
+    expect(opts.websocket.closeOnBackpressureLimit).toBe(true);
+  });
+
+  test("upgrade requests go to webSocketUpgradeFetch with the server handle, others to fetchHandler", async () => {
+    const plain: string[] = [];
+    const upgraded: KumikoServeEnv[] = [];
+    const opts = buildBunServeOptions(
+      0,
+      (_req, socketAddress) => {
+        plain.push(socketAddress ?? "none");
+        return new Response("plain");
+      },
+      undefined,
+      {
+        upgradeFetch: (_req, serveEnv) => {
+          upgraded.push(serveEnv);
+          return new Response("upgrade");
+        },
+      },
+    );
+    const fakeServer = { requestIP: () => ({ address: "203.0.113.9", port: 1, family: "IPv4" }) };
+    const server = fakeServer as unknown as Bun.Server<KumikoWebSocketData>;
+    await opts.fetch(new Request("http://localhost/api/x"), server);
+    await opts.fetch(
+      new Request("http://localhost/api/ws/x", { headers: { Upgrade: "WebSocket" } }),
+      server,
+    );
+    // An upgrade outside /api/ws/ (dev HMR etc.) stays on the normal fetch path.
+    await opts.fetch(
+      new Request("http://localhost/__hmr", { headers: { Upgrade: "websocket" } }),
+      server,
+    );
+    expect(plain).toEqual(["203.0.113.9", "203.0.113.9"]);
+    expect(upgraded).toHaveLength(1);
+    expect(upgraded[0]?.socketAddress).toBe("203.0.113.9");
+    expect(upgraded[0]?.server).toBe(server);
+  });
+
   test("port wird 1:1 durchgereicht, fetch reicht req + Socket-Adresse an den Handler weiter", async () => {
     let received: [Request, string | undefined] | undefined;
     const fetchHandler = (req: Request, socketAddress?: string) => {

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

@@ -1097,6 +1097,35 @@ describe("runProdApp — real Bun.serve socket resolves the client IP (fw#3260 a
   });
 });
 
+describe("runProdApp — rejected WebSocket upgrades carry the security headers", () => {
+  const wsProbeFeature = defineFeature("ws-probe", (r) => {
+    r.webSocketRoute({ path: "/api/ws/probe", connect: () => ({}) });
+  });
+
+  test("a real upgrade request refused by the route (no session) still gets nosniff", async () => {
+    const handle = await boot(undefined, {
+      features: [widgetFeature, wsProbeFeature],
+      autoListen: true,
+      anonymousAccess: { defaultTenantId: TENANT_ID },
+    });
+    const port = handle.server?.port;
+    if (port === undefined) throw new Error("expected handle.server to be listening");
+
+    const res = await fetch(`http://127.0.0.1:${port}/api/ws/probe`, {
+      headers: {
+        Connection: "Upgrade",
+        Upgrade: "websocket",
+        "Sec-WebSocket-Version": "13",
+        "Sec-WebSocket-Key": Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString(
+          "base64",
+        ),
+      },
+    });
+    expect(res.status).toBe(401);
+    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+  });
+});
+
 describe("runProdApp: lokaler Event-Dispatcher (MSP-Anwendung im Single-Container)", () => {
   // Regression für den 2026-06-11-Incident: runProdApp baute den
   // Event-Dispatcher nie ({disabled:true} im API-Entrypoint) — jede

package/src/__tests__/websocket-route.integration.test.ts

@@ -0,0 +1,580 @@
+// r.webSocketRoute over a real Bun.serve socket: upgrade guards (origin,
+// session, upgrade header), connect-time rejection, and the live message
+// path (text/binary echo, size cap, handler failure). anonymousAccess is wired
+// on purpose (see http-route-entry.integration.test.ts): without it a route
+// mounted behind the wrong guard would 401 on a missing token too, masking the
+// bug the "no session" test exists to catch.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { AUTH_COOKIE_NAME, type KumikoWebSocketData } from "@cosmicdrift/kumiko-framework/api";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { buildBunServeOptions } from "../bun-serve-options";
+
+const APP_ORIGIN = "https://app.example";
+const EVIL_ORIGIN = "https://evil.example";
+const MAX_MESSAGE_BYTES = 1024;
+const membershipQuery = "tenant:query:memberships";
+
+type Deferred = { readonly promise: Promise<void>; readonly resolve: () => void };
+
+function deferred(): Deferred {
+  let resolve: () => void = () => {};
+  const promise = new Promise<void>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+
+// Per-test gates the routes below wait on, so ordering and slot release are
+// driven by explicit signals instead of timers.
+let orderedGate = deferred();
+let hangingClosed = deferred();
+let hangingSignal: AbortSignal | undefined;
+const hangingStarted: string[] = [];
+// A function read keeps TS from narrowing the module-level `let` to its last assignment.
+const heldSignal = (): AbortSignal | undefined => hangingSignal;
+let limitedClosed = deferred();
+let limitedConnectCalls = 0;
+let gatedRejects = true;
+
+const wsFeature = defineFeature("ws-test", (r) => {
+  r.webSocketRoute({
+    path: "/api/ws/ordered",
+    connect: () => ({
+      onMessage: async (data, connection) => {
+        if (data === "slow") await orderedGate.promise;
+        connection.send(data);
+      },
+    }),
+  });
+  r.webSocketRoute({
+    path: "/api/ws/hanging",
+    connect: () => ({
+      onMessage: (data, connection) => {
+        hangingStarted.push(String(data));
+        hangingSignal = connection.signal;
+        return new Promise<void>(() => {});
+      },
+      onClose: (_code, _reason, connection) => {
+        hangingSignal = connection.signal;
+        hangingClosed.resolve();
+      },
+    }),
+  });
+  r.webSocketRoute({
+    path: "/api/ws/limited",
+    maxConnectionsPerUser: 2,
+    connect: () => {
+      limitedConnectCalls += 1;
+      return { onClose: () => limitedClosed.resolve() };
+    },
+  });
+  r.webSocketRoute({
+    path: "/api/ws/gated",
+    maxConnectionsPerUser: 1,
+    connect: () => (gatedRejects ? new Response(null, { status: 409 }) : {}),
+  });
+  r.webSocketRoute({
+    path: "/api/ws/echo",
+    maxMessageBytes: MAX_MESSAGE_BYTES,
+    connect: (_c, { user }) => ({
+      onOpen: (connection) => connection.send(JSON.stringify({ userId: user.id })),
+      onMessage: (data, connection) => connection.send(data),
+    }),
+  });
+  r.webSocketRoute({
+    path: "/api/ws/rejected",
+    connect: () => new Response(null, { status: 409 }),
+  });
+  r.webSocketRoute({
+    path: "/api/ws/explosive",
+    connect: () => ({
+      onMessage: () => {
+        throw new Error("handler failure");
+      },
+    }),
+  });
+});
+
+function upgradeHeaders(extra: Record<string, string>): Record<string, string> {
+  return {
+    Connection: "Upgrade",
+    Upgrade: "websocket",
+    "Sec-WebSocket-Version": "13",
+    "Sec-WebSocket-Key": Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString("base64"),
+    ...extra,
+  };
+}
+
+async function errorCode(res: Response): Promise<string | undefined> {
+  const body: unknown = await res.json();
+  if (typeof body !== "object" || body === null || !("error" in body)) return undefined;
+  const { error } = body;
+  if (typeof error !== "object" || error === null || !("code" in error)) return undefined;
+  return typeof error.code === "string" ? error.code : undefined;
+}
+
+// Bun's WebSocket accepts request headers (needed for Cookie/Origin), which lib.dom's typing omits.
+const BunWebSocket = WebSocket as unknown as new (
+  url: string,
+  options: { headers: Record<string, string> },
+) => WebSocket;
+
+type ClientSocket = {
+  readonly opened: Promise<void>;
+  readonly closed: Promise<CloseEvent>;
+  readonly next: () => Promise<unknown>;
+  readonly send: (data: string | Uint8Array<ArrayBuffer>) => void;
+  readonly close: () => void;
+};
+
+// Listeners attach at construction so a message sent during the upgrade
+// (onOpen) is never lost between "open" and the test's first await.
+function connectSocket(url: string, headers: Record<string, string>): ClientSocket {
+  const ws = new BunWebSocket(url, { headers });
+  ws.binaryType = "arraybuffer";
+  const inbox: unknown[] = [];
+  const waiters: ((value: unknown) => void)[] = [];
+  ws.addEventListener("message", (event) => {
+    const waiter = waiters.shift();
+    if (waiter) waiter(event.data);
+    else inbox.push(event.data);
+  });
+  return {
+    opened: new Promise<void>((resolve, reject) => {
+      ws.addEventListener("open", () => resolve());
+      ws.addEventListener("error", () => reject(new Error(`WebSocket to ${url} failed`)));
+    }),
+    closed: new Promise<CloseEvent>((resolve) => ws.addEventListener("close", resolve)),
+    next: () =>
+      inbox.length > 0
+        ? Promise.resolve(inbox.shift())
+        : new Promise((resolve) => waiters.push(resolve)),
+    send: (data) => ws.send(data),
+    close: () => ws.close(),
+  };
+}
+
+type Harness = {
+  readonly stack: TestStack;
+  readonly server: Bun.Server<KumikoWebSocketData>;
+  readonly httpOrigin: string;
+  readonly url: (path: string) => string;
+  readonly cookie: (sid?: string) => Promise<string>;
+  /** Call before sending: resolves once Bun's websocket message callback has run `count` more times. */
+  readonly nextMessages: (count: number) => Promise<void>;
+};
+
+async function startHarness(
+  authConfig: Parameters<typeof setupTestStack>[0]["authConfig"],
+  heartbeatIntervalMs?: number,
+): Promise<Harness> {
+  const stack = await setupTestStack({
+    features: [wsFeature],
+    anonymousAccess: { defaultTenantId: TestUsers.user.tenantId },
+    ...(authConfig ? { authConfig } : {}),
+  });
+  const options = buildBunServeOptions(
+    0,
+    (req, socketAddress) => stack.app.fetch(req, socketAddress),
+    undefined,
+    {
+      upgradeFetch: (req, serveEnv) => stack.app.fetch(req, serveEnv),
+      ...(heartbeatIntervalMs !== undefined ? { heartbeatIntervalMs } : {}),
+    },
+  );
+  let received = 0;
+  const receivedWaiters: { readonly count: number; readonly resolve: () => void }[] = [];
+  const server = Bun.serve<KumikoWebSocketData>({
+    ...options,
+    websocket: {
+      ...options.websocket,
+      message: (ws, message) => {
+        options.websocket.message?.(ws, message);
+        received += 1;
+        for (const waiter of receivedWaiters) if (received >= waiter.count) waiter.resolve();
+      },
+    },
+  });
+  return {
+    nextMessages: (count) =>
+      new Promise<void>((resolve) => receivedWaiters.push({ count: received + count, resolve })),
+    stack,
+    server,
+    httpOrigin: `http://localhost:${server.port}`,
+    url: (path) => `ws://localhost:${server.port}${path}`,
+    cookie: async (sid) =>
+      `${AUTH_COOKIE_NAME}=${await stack.jwt.sign(sid ? { ...TestUsers.user, sid } : TestUsers.user)}`,
+  };
+}
+
+async function stopHarness(harness: Harness): Promise<void> {
+  await harness.server.stop(true);
+  await harness.stack.cleanup();
+}
+
+async function upgradeAttempt(
+  harness: Harness,
+  path: string,
+  headers: Record<string, string>,
+): Promise<Response> {
+  return fetch(`${harness.httpOrigin}${path}`, { headers: upgradeHeaders(headers) });
+}
+
+describe("r.webSocketRoute (integration) — same-host origin, no allowlist", () => {
+  let harness: Harness;
+  let cookie: string;
+
+  beforeAll(async () => {
+    harness = await startHarness({ membershipQuery });
+    cookie = await harness.cookie();
+  });
+  afterAll(() => stopHarness(harness));
+
+  test("no session → 401", async () => {
+    const res = await upgradeAttempt(harness, "/api/ws/echo", { Origin: harness.httpOrigin });
+    expect(res.status).toBe(401);
+    expect(await errorCode(res)).toBe("unauthenticated");
+  });
+
+  test("valid cookie + foreign Origin → 403 origin_not_allowed", async () => {
+    const res = await upgradeAttempt(harness, "/api/ws/echo", {
+      Cookie: cookie,
+      Origin: EVIL_ORIGIN,
+    });
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("origin_not_allowed");
+  });
+
+  test("valid cookie + no Origin → 403 origin_not_allowed", async () => {
+    const res = await upgradeAttempt(harness, "/api/ws/echo", { Cookie: cookie });
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("origin_not_allowed");
+  });
+
+  test("plain GET (no upgrade headers) → 426", async () => {
+    const res = await fetch(`${harness.httpOrigin}/api/ws/echo`, {
+      headers: { Cookie: cookie, Origin: harness.httpOrigin },
+    });
+    expect(res.status).toBe(426);
+    expect(await errorCode(res)).toBe("websocket_upgrade_required");
+  });
+
+  test("upgrade request on a server without the upgrade wiring → 501 websocket_upgrade_not_wired", async () => {
+    const res = await harness.stack.app.request(`${harness.httpOrigin}/api/ws/echo`, {
+      headers: upgradeHeaders({
+        Cookie: cookie,
+        Origin: harness.httpOrigin,
+        Host: new URL(harness.httpOrigin).host,
+      }),
+    });
+    expect(res.status).toBe(501);
+    expect(await errorCode(res)).toBe("websocket_upgrade_not_wired");
+  });
+
+  test("connect() returning a Response rejects the upgrade with it", async () => {
+    const res = await upgradeAttempt(harness, "/api/ws/rejected", {
+      Cookie: cookie,
+      Origin: harness.httpOrigin,
+    });
+    expect(res.status).toBe(409);
+  });
+
+  test("same-host Origin + valid cookie opens and greets with the user id", async () => {
+    const socket = connectSocket(harness.url("/api/ws/echo"), {
+      Cookie: cookie,
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    expect(JSON.parse(String(await socket.next()))).toEqual({ userId: TestUsers.user.id });
+    socket.close();
+    await socket.closed;
+  });
+
+  test("echoes text and binary messages unchanged", async () => {
+    const socket = connectSocket(harness.url("/api/ws/echo"), {
+      Cookie: cookie,
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    await socket.next();
+
+    socket.send("hello ä");
+    expect(await socket.next()).toBe("hello ä");
+
+    const bytes = new Uint8Array([0, 1, 2, 253, 254, 255]);
+    socket.send(bytes);
+    const echoed = await socket.next();
+    if (!(echoed instanceof ArrayBuffer)) throw new Error("expected binary echo");
+    expect(Array.from(new Uint8Array(echoed))).toEqual(Array.from(bytes));
+
+    socket.close();
+    await socket.closed;
+  });
+
+  test("async handlers run in arrival order even when an earlier one is slower", async () => {
+    orderedGate = deferred();
+    const socket = connectSocket(harness.url("/api/ws/ordered"), {
+      Cookie: cookie,
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    const bothReceived = harness.nextMessages(2);
+    socket.send("slow");
+    socket.send("fast");
+    // Both frames reached the server; unserialized handlers would now answer "fast" first.
+    await bothReceived;
+    orderedGate.resolve();
+    expect(await socket.next()).toBe("slow");
+    expect(await socket.next()).toBe("fast");
+    socket.close();
+    await socket.closed;
+  });
+
+  test("onClose runs and the signal aborts while onMessage hangs; queued messages never start", async () => {
+    hangingClosed = deferred();
+    hangingStarted.length = 0;
+    hangingSignal = undefined;
+    const socket = connectSocket(harness.url("/api/ws/hanging"), {
+      Cookie: cookie,
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    const bothReceived = harness.nextMessages(2);
+    socket.send("hangs");
+    socket.send("queued");
+    await bothReceived;
+    socket.close();
+    await socket.closed;
+    await hangingClosed.promise;
+    expect(heldSignal()?.aborted).toBe(true);
+    expect(hangingStarted).toEqual(["hangs"]);
+  });
+
+  test("a message above maxMessageBytes closes the socket with 1009", async () => {
+    const socket = connectSocket(harness.url("/api/ws/echo"), {
+      Cookie: cookie,
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    await socket.next();
+
+    socket.send("x".repeat(MAX_MESSAGE_BYTES * 2));
+    expect((await socket.closed).code).toBe(1009);
+  });
+
+  test("a throwing handler closes the socket with 1011", async () => {
+    const socket = connectSocket(harness.url("/api/ws/explosive"), {
+      Cookie: cookie,
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    socket.send("trigger");
+    expect((await socket.closed).code).toBe(1011);
+  });
+});
+
+describe("r.webSocketRoute (integration) — origin allowlist and session checker", () => {
+  const revokedSessions = new Set<string>();
+  let harness: Harness;
+
+  beforeAll(async () => {
+    harness = await startHarness({
+      membershipQuery,
+      allowedOrigins: [APP_ORIGIN],
+      sessionChecker: async (sid) => (revokedSessions.has(sid) ? "revoked" : "live"),
+    });
+  });
+  afterAll(() => stopHarness(harness));
+
+  test("an allowlisted Origin opens", async () => {
+    const socket = connectSocket(harness.url("/api/ws/echo"), {
+      Cookie: await harness.cookie("sid-live"),
+      Origin: APP_ORIGIN,
+    });
+    await socket.opened;
+    expect(JSON.parse(String(await socket.next()))).toEqual({ userId: TestUsers.user.id });
+    socket.close();
+    await socket.closed;
+  });
+
+  test("the request's own host is NOT enough once an allowlist exists → 403", async () => {
+    const res = await upgradeAttempt(harness, "/api/ws/echo", {
+      Cookie: await harness.cookie("sid-live"),
+      Origin: harness.httpOrigin,
+    });
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("origin_not_allowed");
+  });
+
+  test("a revoked session is rejected at the upgrade with 401", async () => {
+    revokedSessions.add("sid-revoked");
+    const res = await upgradeAttempt(harness, "/api/ws/echo", {
+      Cookie: await harness.cookie("sid-revoked"),
+      Origin: APP_ORIGIN,
+    });
+    expect(res.status).toBe(401);
+  });
+});
+
+describe("r.webSocketRoute (integration) — tenant lifecycle", () => {
+  const lifecycle = { status: "active" };
+  let harness: Harness;
+
+  beforeAll(async () => {
+    harness = await startHarness({
+      membershipQuery,
+      resolveTenantLifecycleStatus: async () => ({ status: lifecycle.status }),
+    });
+  });
+  afterAll(() => stopHarness(harness));
+
+  test("a serving tenant opens", async () => {
+    lifecycle.status = "active";
+    const socket = connectSocket(harness.url("/api/ws/echo"), {
+      Cookie: await harness.cookie(),
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    expect(JSON.parse(String(await socket.next()))).toEqual({ userId: TestUsers.user.id });
+    socket.close();
+    await socket.closed;
+  });
+
+  test("a tenant in teardown is rejected at the upgrade with 410, like HTTP", async () => {
+    lifecycle.status = "destroying";
+    const res = await upgradeAttempt(harness, "/api/ws/echo", {
+      Cookie: await harness.cookie(),
+      Origin: harness.httpOrigin,
+    });
+    expect(res.status).toBe(410);
+    expect(await errorCode(res)).toBe("tenant_unavailable");
+  });
+});
+
+describe("r.webSocketRoute (integration) — per-user connection cap", () => {
+  let harness: Harness;
+  let cookie: string;
+
+  beforeAll(async () => {
+    harness = await startHarness({ membershipQuery });
+    cookie = await harness.cookie();
+  });
+  afterAll(() => stopHarness(harness));
+
+  test("the third socket gets 429; closing one frees a slot", async () => {
+    limitedClosed = deferred();
+    const headers = { Cookie: cookie, Origin: harness.httpOrigin };
+    const first = connectSocket(harness.url("/api/ws/limited"), headers);
+    const second = connectSocket(harness.url("/api/ws/limited"), headers);
+    await first.opened;
+    await second.opened;
+
+    limitedConnectCalls = 0;
+    const rejected = await upgradeAttempt(harness, "/api/ws/limited", headers);
+    expect(rejected.status).toBe(429);
+    expect(await errorCode(rejected)).toBe("websocket_connection_limit");
+    // The slot is taken before connect, so a refused attempt never runs it.
+    expect(limitedConnectCalls).toBe(0);
+
+    first.close();
+    // The route's onClose runs after the slot is released.
+    await limitedClosed.promise;
+    const third = connectSocket(harness.url("/api/ws/limited"), headers);
+    await third.opened;
+
+    second.close();
+    third.close();
+    await Promise.all([second.closed, third.closed]);
+  });
+});
+
+describe("r.webSocketRoute (integration) — connect rejection frees the slot", () => {
+  let harness: Harness;
+  let cookie: string;
+
+  beforeAll(async () => {
+    harness = await startHarness({ membershipQuery });
+    cookie = await harness.cookie();
+  });
+  afterAll(() => stopHarness(harness));
+
+  test("a connect() Response does not leak the single slot", async () => {
+    const headers = { Cookie: cookie, Origin: harness.httpOrigin };
+    gatedRejects = true;
+    // With a cap of 1, a leaked slot would turn the second refusal into a 429.
+    expect((await upgradeAttempt(harness, "/api/ws/gated", headers)).status).toBe(409);
+    expect((await upgradeAttempt(harness, "/api/ws/gated", headers)).status).toBe(409);
+
+    gatedRejects = false;
+    const socket = connectSocket(harness.url("/api/ws/gated"), headers);
+    await socket.opened;
+    socket.close();
+    await socket.closed;
+  });
+});
+
+describe("r.webSocketRoute (integration) — revalidation on an open socket", () => {
+  const HEARTBEAT_MS = 20;
+  const revokedSessions = new Set<string>();
+  const hangingSessions = new Set<string>();
+  let currentRoles: readonly string[] = TestUsers.user.roles;
+  let harness: Harness;
+
+  beforeAll(async () => {
+    harness = await startHarness(
+      {
+        membershipQuery,
+        // In-memory checker: only a session listed in hangingSessions ever stalls.
+        sessionChecker: (sid) =>
+          hangingSessions.has(sid)
+            ? new Promise(() => {})
+            : Promise.resolve(
+                revokedSessions.has(sid) ? "revoked" : { status: "live", roles: currentRoles },
+              ),
+      },
+      HEARTBEAT_MS,
+    );
+  });
+  afterAll(() => stopHarness(harness));
+
+  test("a session revoked while the socket is open closes it with 1008", async () => {
+    const socket = connectSocket(harness.url("/api/ws/echo"), {
+      Cookie: await harness.cookie("sid-revoked-live"),
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    await socket.next();
+    revokedSessions.add("sid-revoked-live");
+    const closed = await socket.closed;
+    expect(closed.code).toBe(1008);
+    expect(closed.reason).toBe("session changed");
+  });
+
+  test("changed roles close an open socket with 1008", async () => {
+    currentRoles = TestUsers.user.roles;
+    const socket = connectSocket(harness.url("/api/ws/echo"), {
+      Cookie: await harness.cookie("sid-roles"),
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    await socket.next();
+    currentRoles = [...TestUsers.user.roles, "ExtraRole"];
+    expect((await socket.closed).code).toBe(1008);
+    currentRoles = TestUsers.user.roles;
+  });
+
+  test("a session store that stops answering closes the socket with 1013", async () => {
+    const socket = connectSocket(harness.url("/api/ws/echo"), {
+      Cookie: await harness.cookie("sid-hang"),
+      Origin: harness.httpOrigin,
+    });
+    await socket.opened;
+    await socket.next();
+    hangingSessions.add("sid-hang");
+    const closed = await socket.closed;
+    expect(closed.code).toBe(1013);
+    expect(closed.reason).toBe("try again later");
+  });
+});

package/src/boot/pii-event-backfill-on-boot.ts

@@ -0,0 +1,43 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { runPiiEventBackfill } from "@cosmicdrift/kumiko-framework/migrations";
+
+export const SKIP_PII_BACKFILL_ENV = "KUMIKO_SKIP_PII_BACKFILL";
+
+type ShutdownRegistry = {
+  registerShutdownHook(name: string, fn: () => Promise<void>): void;
+};
+
+// Runs in the background instead of blocking boot: the first run after a bump
+// scans the whole store and would delay readiness in proportion to its size.
+// Every batch is its own transaction, so an abort at any point is safe.
+export function startPiiEventBackfillOnBoot(opts: {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly lifecycle: ShutdownRegistry;
+  readonly envSource: Readonly<Record<string, string | undefined>>;
+}): void {
+  if (opts.envSource[SKIP_PII_BACKFILL_ENV] === "1") {
+    // skip: operator opted out via KUMIKO_SKIP_PII_BACKFILL
+    return;
+  }
+
+  const log = createFallbackLogger("pii-event-backfill");
+  const abortController = new AbortController();
+  const run = runPiiEventBackfill(opts.db, opts.registry, {
+    signal: abortController.signal,
+  }).then(
+    () => undefined,
+    (e: unknown) => {
+      log.error("PII event backfill crashed; it will be retried on the next boot", {
+        error: e instanceof Error ? e.message : String(e),
+      });
+    },
+  );
+
+  opts.lifecycle.registerShutdownHook("piiEventBackfill", async () => {
+    abortController.abort();
+    await run;
+  });
+}

package/src/build-prod-bundle.ts

@@ -53,6 +53,11 @@ import { tmpdir } from "node:os";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isPlainObject, parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
+import {
+  RENDERER_WEB_FONT_FILE_PATTERN,
+  RENDERER_WEB_FONTS_DIST_DIR,
+  resolveRendererWebFontsDir,
+} from "./renderer-web-fonts";
 import { canResolveTailwindStylesheet, resolveTailwindCli } from "./resolve-tailwind-cli";
 
 // Bun-Runtime-Check als module-level Konstante: alle Build-Schritte
@@ -186,6 +191,7 @@ export async function buildProdBundle(options: BuildProdBundleOptions = {}): Pro
     const filename = `styles-${hash}.css`;
     await writeFile(join(assetsDir, filename), css);
     manifest["styles.css"] = `/${ASSETS_DIR}/${filename}`;
+    await copyRendererWebFonts(cwd, outDir);
   }
 
   // 4. Bun.build pro Entry (multi-entry produces N bundles + shared chunks).
@@ -641,6 +647,22 @@ export function assertRendererWebShellPresent(css: string, stylesheet: ResolvedS
   );
 }
 
+// The compiled CSS points at absolute /assets/kumiko/fonts/<file>.woff2 URLs
+// (see renderer-web-fonts.ts), so the files have to sit at exactly that path in
+// dist. Skipped when renderer-web isn't resolvable — then no such CSS exists.
+async function copyRendererWebFonts(cwd: string, outDir: string): Promise<void> {
+  const fontsDir = resolveRendererWebFontsDir([cwd]);
+  // skip: renderer-web not resolvable, so no font-referencing CSS exists.
+  if (fontsDir === undefined || !existsSync(fontsDir)) return;
+  const target = join(outDir, RENDERER_WEB_FONTS_DIST_DIR);
+  await mkdir(target, { recursive: true });
+  for (const file of readdirSync(fontsDir)) {
+    if (RENDERER_WEB_FONT_FILE_PATTERN.test(file)) {
+      await cp(join(fontsDir, file), join(target, file));
+    }
+  }
+}
+
 // @internal — exported nur für Unit-Tests.
 export function discoverHtmlTemplate(cwd: string): string | undefined {
   for (const candidate of ["index.html", "public/index.html"]) {

package/src/bun-serve-options.ts

@@ -1,4 +1,13 @@
-import { DEFAULT_MAX_REQUEST_BYTES } from "@cosmicdrift/kumiko-framework/api";
+import {
+  createKumikoWebSocketHandler,
+  DEFAULT_MAX_REQUEST_BYTES,
+  isWebSocketUpgradeRequest,
+  type KumikoServeEnv,
+  type KumikoWebSocketData,
+  WEBSOCKET_BACKPRESSURE_LIMIT_BYTES,
+  WEBSOCKET_MAX_PAYLOAD_BYTES,
+  WEBSOCKET_ROUTE_PATH_PREFIX,
+} from "@cosmicdrift/kumiko-framework/api";
 import type { Registry } from "@cosmicdrift/kumiko-framework/engine/types";
 import {
   readFilesRouteOptions,
@@ -26,35 +35,76 @@ export function resolveDerivedMaxRequestBodySize(registry: Registry): number {
   );
 }
 
+// Other upgrades (dev HMR, ...) keep going through fetchHandler.
+function isKumikoWebSocketUpgrade(req: Request): boolean {
+  return (
+    isWebSocketUpgradeRequest(req) &&
+    new URL(req.url).pathname.startsWith(WEBSOCKET_ROUTE_PATH_PREFIX)
+  );
+}
+
 /**
- * Bun.serve-Options für Production.
+ * Bun.serve options for production.
+ *
+ * idleTimeout: 0 (disabled): SSE streams stay alive through their own
+ * heartbeat (SSE_HEARTBEAT_INTERVAL_MS in framework/api/sse-route.ts). With
+ * Bun's 10 s default, every heartbeat gap killed the connection with a half
+ * HTTP/2 RST_STREAM, which browsers report as ERR_HTTP2_PROTOCOL_ERROR.
  *
- * Spec: idleTimeout: 0 (= disabled). SSE-Streams werden via Heartbeat
- * lebend gehalten (siehe SSE_HEARTBEAT_INTERVAL_MS in framework/api/
- * sse-route.ts), kein Bun-side Idle-Cleanup nötig. Mit dem Default
- * von 10 s killt Bun nach jedem Heartbeat-Gap die Connection mit
- * halbem HTTP/2-RST_STREAM → Browser ERR_HTTP2_PROTOCOL_ERROR.
+ * __tests__/run-prod-app-spec.test.ts pins the 0 against "looks like a
+ * leak" reverts.
  *
- * Spec-Test in __tests__/run-prod-app-spec.test.ts pinst die 0 gegen
- * "looks like a leak"-Reverts.
+ * WebSocket: upgrade requests are branched off here, before `fetchHandler`
+ * (whose static/SPA layers clone the request, which `server.upgrade` can't
+ * use), into `webSocketOptions.upgradeFetch` with the original Request.
+ * `heartbeatIntervalMs` overrides the 25 s ping/revalidation cadence.
  */
+export type WebSocketServeOptions = {
+  readonly upgradeFetch: (req: Request, env: KumikoServeEnv) => Response | Promise<Response>;
+  readonly heartbeatIntervalMs?: number;
+};
+
 export function buildBunServeOptions(
   port: number,
   fetchHandler: (req: Request, socketAddress?: string) => Response | Promise<Response>,
   maxRequestBodySize: number = DEFAULT_MAX_REQUEST_BODY_SIZE_BYTES,
+  webSocketOptions?: WebSocketServeOptions,
 ): {
   readonly port: number;
-  readonly fetch: (req: Request, server: Bun.Server<unknown>) => Response | Promise<Response>;
+  readonly fetch: (
+    req: Request,
+    server: Bun.Server<KumikoWebSocketData>,
+  ) => Response | Promise<Response>;
   readonly idleTimeout: number;
   readonly maxRequestBodySize: number;
+  readonly websocket: Bun.WebSocketHandler<KumikoWebSocketData>;
 } {
   // `server.requestIP(req)` only resolves for the exact Request instance
   // Bun created — extracted here, once, before any downstream req.clone()
   // (tryHonoFirst et al.) can invalidate it.
   return {
     port,
-    fetch: (req, server) => fetchHandler(req, server.requestIP(req)?.address),
+    fetch: (req, server) => {
+      const socketAddress = server.requestIP(req)?.address;
+      if (webSocketOptions && isKumikoWebSocketUpgrade(req)) {
+        return webSocketOptions.upgradeFetch(req, {
+          ...(socketAddress !== undefined ? { socketAddress } : {}),
+          server,
+        });
+      }
+      return fetchHandler(req, socketAddress);
+    },
     idleTimeout: 0,
     maxRequestBodySize,
+    websocket: {
+      ...createKumikoWebSocketHandler(
+        webSocketOptions?.heartbeatIntervalMs !== undefined
+          ? { heartbeatIntervalMs: webSocketOptions.heartbeatIntervalMs }
+          : {},
+      ),
+      maxPayloadLength: WEBSOCKET_MAX_PAYLOAD_BYTES,
+      backpressureLimit: WEBSOCKET_BACKPRESSURE_LIMIT_BYTES,
+      closeOnBackpressureLimit: true,
+    },
   };
 }

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "Production build copies the renderer-web fonts",
+    "detail": "`buildProdBundle` copies the IBM Plex woff2 files to `dist/assets/kumiko/fonts/`, where the compiled CSS expects them. The new export `@cosmicdrift/kumiko-server-runtime/renderer-web-fonts` holds the URL prefix, the file name allowlist and the resolver, and the woff2 MIME type is known to the static file server."
+  },
   {
     "version": "0.323.0",
     "type": "breaking",

package/src/renderer-web-fonts.ts

@@ -0,0 +1,33 @@
+// The renderer-web stylesheet references its IBM Plex woff2 files by absolute
+// same-origin URL. Relative url() would 404: the CSS is compiled into a temp
+// dir (dev) or hashed into dist/assets (prod), away from the source fonts.
+// data: URIs are out because apps run with `font-src 'self'`.
+
+import { dirname, join } from "node:path";
+
+export const RENDERER_WEB_FONTS_URL_PREFIX = "/assets/kumiko/fonts/";
+
+/** dist-relative folder the prod build copies the fonts into. */
+export const RENDERER_WEB_FONTS_DIST_DIR = "assets/kumiko/fonts";
+
+/** Allowlist for servable font file names; also rules out path segments. */
+export const RENDERER_WEB_FONT_FILE_PATTERN = /^[a-z0-9-]+\.woff2$/;
+
+const hasBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+
+/** Directory of the woff2 files next to renderer-web's styles.css, or
+ *  undefined when the package can't be resolved from any `searchFrom` dir
+ *  (or outside Bun, which does the package-exports resolution). */
+export function resolveRendererWebFontsDir(searchFrom: readonly string[]): string | undefined {
+  if (!hasBun) return undefined;
+  const bun = (globalThis as { Bun: { resolveSync: (id: string, from: string) => string } }).Bun;
+  for (const from of searchFrom) {
+    try {
+      const stylesheet = bun.resolveSync("@cosmicdrift/kumiko-renderer-web/styles.css", from);
+      return join(dirname(stylesheet), "fonts");
+    } catch {
+      // try the next search root
+    }
+  }
+  return undefined;
+}

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

@@ -110,6 +110,8 @@ export function mimeTypeFor(filePath: string): string {
       return "application/xml; charset=utf-8";
     case "webmanifest":
       return "application/manifest+json";
+    case "woff2":
+      return "font/woff2";
     default:
       return "application/octet-stream";
   }

package/src/run-prod-app.ts

@@ -74,6 +74,7 @@ import {
   createDefaultSseBroker,
   createRedisLoginRateLimiter,
   type ExtraRouteDefinition,
+  type KumikoServeEnv,
   type LoginRateLimiter,
   loadJwtSecretOrKeyring,
   type PostAuthLandingResolver,
@@ -148,6 +149,7 @@ import Redis from "ioredis";
 import { applyBootSeeds } from "./boot/apply-boot-seeds";
 import { resolveBootCrypto } from "./boot/boot-crypto";
 import { jobRunLoggerCallbacks } from "./boot/job-run-logger";
+import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot";
 import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-serve-options";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
 import { makeDispatchSystemWrite, type SystemWireDeps } from "./extra-routes-deps";
@@ -246,6 +248,7 @@ function makeDryRunHandle(): ProdAppHandle {
     // entrypoint is never reached by callers in dry-run.
     entrypoint: undefined as unknown as ApiEntrypoint,
     fetch: () => new Response("dry-run", { status: 503 }),
+    webSocketUpgradeFetch: async () => new Response("dry-run", { status: 503 }),
     listen: noop,
     stop: noop,
   };
@@ -711,6 +714,11 @@ export type ProdAppHandle = {
    *  outermost Bun fetch callback — `requestIP` only resolves for Bun's
    *  original Request instance, never a cloned/rebuilt one. */
   readonly fetch: (req: Request, socketAddress?: string) => Promise<Response> | Response;
+  /** Serves WebSocket-upgrade requests (r.webSocketRoute) with Bun's original
+   *  Request. Apps with `autoListen: false` that run their own `Bun.serve`
+   *  must pass it as `{ upgradeFetch }` in the 4th argument of `buildBunServeOptions` to get
+   *  WebSockets; `listen()` already wires it. */
+  readonly webSocketUpgradeFetch: (req: Request, env: KumikoServeEnv) => Promise<Response>;
   /** Active Bun-server (only set when listen() was called — tests skip
    *  listen() because Bun.serve isn't available under vitest/node). */
   server?: ReturnType<typeof Bun.serve>;
@@ -1294,6 +1302,12 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   }
 
   await entrypoint.start();
+  startPiiEventBackfillOnBoot({
+    db,
+    registry,
+    lifecycle: entrypoint.lifecycle,
+    envSource,
+  });
 
   // 11. Build the fetch-handler. Static-fallback for non-/api/ paths
   //     wired via a wrapper so Hono owns /api/* + extraRoutes and disk
@@ -1324,9 +1338,18 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // 11. Mark lifecycle ready — health/ready flips to 200 after this.
   entrypoint.lifecycle.markReady();
 
+  // Upgrade rejections (401/403/426...) are ordinary responses and get the same headers as fetchHandler.
+  const securedUpgradeFetch = withSecurityHeaders<KumikoServeEnv>(
+    async (req, env) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, env)),
+    options.securityHeaders,
+  );
+  const webSocketUpgradeFetch = async (req: Request, env: KumikoServeEnv): Promise<Response> =>
+    securedUpgradeFetch(req, env);
+
   const handle: ProdAppHandle = {
     entrypoint,
     fetch: fetchHandler,
+    webSocketUpgradeFetch,
     listen: async (listenPort = port) => {
       // Bun.serve is the production HTTP. Tests don't call listen()
       // because vitest runs under Node where Bun.serve doesn't exist.
@@ -1347,6 +1370,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
           listenPort,
           fetchHandler,
           options.maxRequestBodySize ?? resolveDerivedMaxRequestBodySize(registry),
+          { upgradeFetch: webSocketUpgradeFetch },
         ),
       );
 

package/src/run-worker-app.ts

@@ -60,6 +60,7 @@ import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import Redis from "ioredis";
 import { resolveBootCrypto } from "./boot/boot-crypto";
 import { jobRunLoggerCallbacks } from "./boot/job-run-logger";
+import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot";
 import { composeFeatures } from "./compose-features";
 import { makeDispatchSystemWrite, type SystemWireDeps } from "./extra-routes-deps";
 import { assertPiiBootInvariants } from "./pii-boot-gate";
@@ -320,6 +321,12 @@ export async function runWorkerApp(options: RunWorkerAppOptions): Promise<Worker
   };
 
   await entrypoint.start();
+  startPiiEventBackfillOnBoot({
+    db,
+    registry,
+    lifecycle: entrypoint.lifecycle,
+    envSource,
+  });
 
   if (options.wireComponents) {
     await options.wireComponents({

package/src/security-headers.ts

@@ -42,14 +42,14 @@ export function resolveSecurityHeaders(
 
 // Sets each header only when absent so per-response values (e.g. the
 // per-host CSP from hostDispatch) always win over the runtime default.
-export function withSecurityHeaders(
-  handler: (req: Request, socketAddress?: string) => Response | Promise<Response>,
+export function withSecurityHeaders<TServeArg = string>(
+  handler: (req: Request, serveArg?: TServeArg) => Response | Promise<Response>,
   option: SecurityHeadersOption | undefined,
-): (req: Request, socketAddress?: string) => Response | Promise<Response> {
+): (req: Request, serveArg?: TServeArg) => Response | Promise<Response> {
   const defaults = resolveSecurityHeaders(option);
   if (defaults.length === 0) return handler;
-  return async (req: Request, socketAddress?: string): Promise<Response> => {
-    const res = await handler(req, socketAddress);
+  return async (req: Request, serveArg?: TServeArg): Promise<Response> => {
+    const res = await handler(req, serveArg);
     try {
       for (const [name, value] of defaults) {
         if (!res.headers.has(name)) res.headers.set(name, value);