@teamscala/service-boot 0.23.299 → 0.23.300

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.299",
+  "version": "0.23.300",
   "sideEffects": false,
   "files": [
     "src"
@@ -970,6 +970,14 @@
       "types": "./src/serve/serve.d.ts",
       "default": "./src/serve/serve.ts"
     },
+    "./serve/stamp-transport-identity": {
+      "types": "./src/serve/stamp-transport-identity.d.ts",
+      "default": "./src/serve/stamp-transport-identity.ts"
+    },
+    "./serve/stamp-transport-identity.ts": {
+      "types": "./src/serve/stamp-transport-identity.d.ts",
+      "default": "./src/serve/stamp-transport-identity.ts"
+    },
     "./server-error-page": {
       "types": "./src/server-error-page.d.ts",
       "default": "./src/server-error-page.ts"

package/src/mutable-app-ref.d.ts

@@ -34,5 +34,11 @@ export declare function swapApp(newApp: Hono, newLabel: string): string;
 /**
  * Fetch handler that routes through the mutable app reference.
  * This replaces the direct app.fetch call in the serve layer.
+ *
+ * Stamps transport-derived identity (x-caller-remote-address/-port + the
+ * loopback local-caller comm) via the SAME stampTransportIdentity helper as
+ * direct mode, so two-phase-boot (mutable-ref) UI services carry identical
+ * identity on every request — closing the gap where the mutable-ref path
+ * previously served requests with no transport headers stamped at all.
  */
 export declare function fetchWithMutableApp(req: Request, server: ReturnType<typeof Bun.serve>): Promise<Response>;

package/src/mutable-app-ref.ts

@@ -14,6 +14,7 @@
  */
 
 import type { Hono } from "hono";
+import { stampTransportIdentity } from "./serve/stamp-transport-identity.ts";
 
 let currentApp: Hono | null = null;
 let appLabel = "initial";
@@ -58,11 +59,17 @@ export function swapApp(newApp: Hono, newLabel: string): string {
 /**
  * Fetch handler that routes through the mutable app reference.
  * This replaces the direct app.fetch call in the serve layer.
+ *
+ * Stamps transport-derived identity (x-caller-remote-address/-port + the
+ * loopback local-caller comm) via the SAME stampTransportIdentity helper as
+ * direct mode, so two-phase-boot (mutable-ref) UI services carry identical
+ * identity on every request — closing the gap where the mutable-ref path
+ * previously served requests with no transport headers stamped at all.
  */
 export function fetchWithMutableApp(
 	req: Request,
 	server: ReturnType<typeof Bun.serve>,
 ): Promise<Response> {
 	const app = getApp();
-	return Promise.resolve(app.fetch(req, { server }));
+	return Promise.resolve(app.fetch(stampTransportIdentity(req, server), { server }));
 }

package/src/serve/serve.ts

@@ -10,7 +10,7 @@
 
 import type { Hono } from "hono";
 import { createBunWebSocket } from "hono/bun";
-import { resolveSocketPeer } from "@teamscala/proc-walker/socket-peer";
+import { stampTransportIdentity } from "./stamp-transport-identity.ts";
 
 const _bunWs = createBunWebSocket();
 
@@ -38,105 +38,20 @@ export interface ServeHandle {
 }
 
 /**
- * Create the fetch handler with peer-port injection. This function is
- * shared between both the direct and mutable-ref modes.
+ * Create the fetch handler with transport-identity stamping. Used in direct
+ * mode (mutable-ref mode uses fetchWithMutableApp, which also stamps via the
+ * same stampTransportIdentity helper — one stamp point for every request).
  */
-function createFetchHandler(
-	app: Hono,
-	serviceSlug: string,
-	logger: { info(msg: string): void; warn(msg: string): void },
-) {
-	let peerPortFailures = 0;
+function createFetchHandler(app: Hono) {
 	return async (
 		req: Request,
 		server: ReturnType<typeof Bun.serve>,
 	) => {
 		// app.fetch's second arg becomes c.env. Hono's bun WebSocket upgrade
-		// adapter checks `"server" in c.env` to find the Bun server reference;
-		// without { server }, /api/rpc/ws upgrade throws TypeError and the
-		// fleet relay can never subscribe.
-		//
-		// WebSocket upgrade requests MUST NOT be cloned — Bun's server.upgrade()
-		// tracks pending upgrades by Request identity, so a cloned Request can
-		// never upgrade. For WS requests we skip the peer-port clone and pass
-		// the original Request through.
-		const isUpgrade = req.headers.get("upgrade")?.toLowerCase() === "websocket";
-		if (isUpgrade) {
-			return app.fetch(req, { server });
-		}
-		try {
-			const peer = (
-				server as unknown as {
-					requestIP(r: Request): { port?: number; address?: string } | null;
-				}
-			).requestIP?.(req);
-			const port = peer?.port;
-			// x-caller-remote-address: the unforgeable transport-origin trust
-			// signal (no-client-controlled-trust-signals). server.requestIP is the
-			// ONE reliable address source (Hono's getConnInfo does not expose
-			// address on Bun). ALWAYS sanitize (delete any client-supplied spoof)
-			// then set the verified socket peer — the @teamscala/mcp-tool-runtime
-			// /mcp discriminator reads this to gate the bearer on loopback-only.
-			const address = peer?.address ?? null;
-			const needsPort =
-				typeof port === "number" &&
-				port > 0 &&
-				!req.headers.has("x-caller-remote-port");
-			if (needsPort || address !== null) {
-				const headers = new Headers(req.headers);
-				if (needsPort) headers.set("x-caller-remote-port", String(port));
-				if (address) {
-					headers.delete("x-caller-remote-address");
-					headers.set("x-caller-remote-address", String(address));
-				}
-				// Local-caller attribution: a local `fetch` carries no forwarding
-				// header, so for a loopback peer (no CF-Connecting-IP / X-Forwarded-
-				// For) resolve the owning local PROCESS from the socket + stamp it for
-				// the access log. Names the daemon behind every local request —
-				// including an unidentified sweeper keeping scale-to-zero apps awake.
-				// Trust stays transport-derived (no-client-controlled-trust-signals);
-				// the comm is attribution only. resolveSocketPeer is TTL-cached + never
-				// throws (returns null on any miss); skipped for external callers.
-				if (
-					address &&
-					(address === "127.0.0.1" ||
-						address === "::1" ||
-						address === "::ffff:127.0.0.1") &&
-					!headers.has("cf-connecting-ip") &&
-					!headers.get("x-forwarded-for") &&
-					typeof port === "number" &&
-					port > 0
-				) {
-					const owner = resolveSocketPeer(port);
-					if (owner) {
-						headers.set("x-caller-local-comm", owner.comm);
-						const cmd = owner.cmdline.join(" ").trim();
-						if (cmd) headers.set("x-caller-local-cmd", cmd.slice(0, 160));
-					}
-				}
-				const cloned = new Request(req.url, {
-					method: req.method,
-					headers,
-					body: req.body,
-					signal: req.signal,
-					// @ts-expect-error duplex required by spec when body is a stream
-					duplex: "half",
-				});
-				return app.fetch(cloned, { server });
-			}
-		} catch (err) {
-			// Fail-open NOISY (protective-layers-fail-explicitly): the request
-			// must always be served, but a broken peer-port resolution degrades
-			// caller-identity to baked-stale headers. Aggregated: first +
-			// every 1000th, never per-request spam.
-			peerPortFailures++;
-			if (peerPortFailures === 1 || peerPortFailures % 1000 === 0) {
-				logger.warn(
-					`[boot-serve:${serviceSlug}] peer-port resolution failed ${peerPortFailures}x — caller-identity degrades to header fallback: ${err instanceof Error ? err.message : String(err)}`,
-				);
-			}
-		}
-		return app.fetch(req, { server });
+		// adapter checks `"server" in c.env` for the Bun server reference (WS
+		// upgrade throws TypeError without it). stampTransportIdentity handles
+		// the WS-upgrade no-clone rule + best-effort identity stamping internally.
+		return app.fetch(stampTransportIdentity(req, server), { server });
 	};
 }
 
@@ -211,6 +126,6 @@ export function serveStart(
 	}
 
 	// Direct mode: use the app directly
-	const fetchHandler = createFetchHandler(app, options.serviceSlug, log);
+	const fetchHandler = createFetchHandler(app);
 	return serveStartInternal(fetchHandler, options, log, "direct");
 }

package/src/serve/stamp-transport-identity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Stamp transport-derived identity onto a request — the single shared stamp
+ * point used by BOTH serve paths (direct `createFetchHandler` + mutable-ref
+ * `fetchWithMutableApp`), so every request on every UI service carries the
+ * same identity regardless of boot mode.
+ *
+ * Two identity layers, both transport-derived (no-client-controlled-trust-
+ * signals — never from a client-controllable header):
+ *   1. `x-caller-remote-address` / `-port` — the unforgeable socket peer, from
+ *      `Bun.serve.requestIP`. ALWAYS sanitised (any client-supplied spoof
+ *      deleted) then set to the verified peer. The /mcp + fleet loopback gates
+ *      read this.
+ *   2. `x-caller-local-comm` / `-cmd` — for a LOOPBACK peer with no forwarding
+ *      header (a local `fetch` carries no CF-Connecting-IP), the owning local
+ *      PROCESS resolved via /proc (@teamscala/proc-walker). Names the daemon
+ *      behind every local request on the access log — including an unidentified
+ *      sweeper. Attribution only (trust stays transport-derived).
+ *
+ * Best-effort + never throws: a resolution miss returns the original request
+ * unchanged (the request is always served; identity degrades to address-only).
+ * WebSocket upgrades are returned untouched (Bun tracks upgrades by Request
+ * identity — a clone can never upgrade).
+ */
+/**
+ * Return a Request with transport-identity headers stamped, or the original
+ * `req` when no stamping is needed/possible. Never throws.
+ */
+export declare function stampTransportIdentity(req: Request, server: ReturnType<typeof Bun.serve>): Request;

package/src/serve/stamp-transport-identity.ts

@@ -0,0 +1,96 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Stamp transport-derived identity onto a request — the single shared stamp
+ * point used by BOTH serve paths (direct `createFetchHandler` + mutable-ref
+ * `fetchWithMutableApp`), so every request on every UI service carries the
+ * same identity regardless of boot mode.
+ *
+ * Two identity layers, both transport-derived (no-client-controlled-trust-
+ * signals — never from a client-controllable header):
+ *   1. `x-caller-remote-address` / `-port` — the unforgeable socket peer, from
+ *      `Bun.serve.requestIP`. ALWAYS sanitised (any client-supplied spoof
+ *      deleted) then set to the verified peer. The /mcp + fleet loopback gates
+ *      read this.
+ *   2. `x-caller-local-comm` / `-cmd` — for a LOOPBACK peer with no forwarding
+ *      header (a local `fetch` carries no CF-Connecting-IP), the owning local
+ *      PROCESS resolved via /proc (@teamscala/proc-walker). Names the daemon
+ *      behind every local request on the access log — including an unidentified
+ *      sweeper. Attribution only (trust stays transport-derived).
+ *
+ * Best-effort + never throws: a resolution miss returns the original request
+ * unchanged (the request is always served; identity degrades to address-only).
+ * WebSocket upgrades are returned untouched (Bun tracks upgrades by Request
+ * identity — a clone can never upgrade).
+ */
+
+import { resolveSocketPeer } from "@teamscala/proc-walker/socket-peer";
+
+const LOOPBACK = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+
+/**
+ * Return a Request with transport-identity headers stamped, or the original
+ * `req` when no stamping is needed/possible. Never throws.
+ */
+export function stampTransportIdentity(
+	req: Request,
+	server: ReturnType<typeof Bun.serve>,
+): Request {
+	// WebSocket upgrade requests MUST NOT be cloned — Bun's server.upgrade()
+	// tracks pending upgrades by Request identity, so a cloned Request can
+	// never upgrade.
+	if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+		return req;
+	}
+	try {
+		const peer = (
+			server as unknown as {
+				requestIP(r: Request): { port?: number; address?: string } | null;
+			}
+		).requestIP?.(req);
+		const port = peer?.port;
+		const address = peer?.address ?? null;
+		const needsPort =
+			typeof port === "number" && port > 0 && !req.headers.has("x-caller-remote-port");
+		// Nothing to stamp when there is no peer address and no port to add.
+		if (!needsPort && address === null) return req;
+
+		const headers = new Headers(req.headers);
+		if (needsPort) headers.set("x-caller-remote-port", String(port));
+		if (address) {
+			headers.delete("x-caller-remote-address");
+			headers.set("x-caller-remote-address", String(address));
+		}
+		// Local-caller attribution: loopback peer + no forwarding header => a
+		// direct local fetch whose owning process we can name via /proc.
+		if (
+			address &&
+			LOOPBACK.has(address) &&
+			!headers.has("cf-connecting-ip") &&
+			!headers.get("x-forwarded-for") &&
+			typeof port === "number" &&
+			port > 0
+		) {
+			const owner = resolveSocketPeer(port);
+			if (owner) {
+				headers.set("x-caller-local-comm", owner.comm);
+				const cmd = owner.cmdline.join(" ").trim();
+				if (cmd) headers.set("x-caller-local-cmd", cmd.slice(0, 160));
+			}
+		}
+		return new Request(req.url, {
+			method: req.method,
+			headers,
+			body: req.body,
+			signal: req.signal,
+			// @ts-expect-error duplex is required by spec when body is a stream
+			duplex: "half",
+		});
+	} catch {
+		// A broken peer resolution must never block serving — degrade to the
+		// original request (identity is best-effort, the request always served).
+		return req;
+	}
+}