agent-comms 9.1.1 → 9.1.2

package/src/bridges/user/web/request-handling.ts

@@ -0,0 +1,118 @@
+/**
+ * How the web bridge reads a request body and answers a route whose work fails: every body has a maximum size, every failure of a route's asynchronous work becomes a response, and nothing a client sends can end the process.
+ */
+
+import type * as http from "node:http";
+import { MAX_MESSAGE_BYTES } from "../../../core/message-limits.js";
+import { CommsError } from "../../../core/store.js";
+
+const HTTP_BAD_REQUEST = 400;
+const BYTES_PER_KIB = 1024;
+const HTTP_PAYLOAD_TOO_LARGE = 413;
+const HTTP_INTERNAL_SERVER_ERROR = 500;
+
+const MS_PER_SECOND = 1000;
+/** The slowest rate at which a client is still given time to send a body: 32 KiB a second, about a hundredth of a modest uplink, so a slow but moving client is served and one that sends a few bytes and stops is not. */
+const MIN_BODY_RATE_KIB_PER_SECOND = 32;
+const MIN_BODY_RATE_BYTES_PER_SECOND =
+  MIN_BODY_RATE_KIB_PER_SECOND * BYTES_PER_KIB;
+
+/** A request the bridge refuses with a specific status and message, rather than failing it as a server fault. */
+export class RequestRefusedError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "RequestRefusedError";
+  }
+}
+
+/** A body that is not valid JSON, or not a JSON object. */
+export function invalidJsonBody(): RequestRefusedError {
+  return new RequestRefusedError(HTTP_BAD_REQUEST, "Invalid JSON");
+}
+
+/**
+ * Reads a request body of at most MAX_MESSAGE_BYTES. Rejects with RequestRefusedError (413) as soon as the declared length, or the bytes actually received, pass the limit, without reading on: the caller answers and the connection is closed, so the rest of an oversized body is never buffered.
+ */
+export async function readBoundedBody(
+  req: http.IncomingMessage,
+): Promise<string> {
+  const declared = Number(req.headers["content-length"]);
+  if (Number.isFinite(declared) && declared > MAX_MESSAGE_BYTES) {
+    throw tooLarge();
+  }
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let received = 0;
+    req.on("data", (chunk: Buffer) => {
+      received += chunk.length;
+      if (received > MAX_MESSAGE_BYTES) {
+        chunks.length = 0;
+        reject(tooLarge());
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      resolve(Buffer.concat(chunks).toString());
+    });
+    req.on("error", reject);
+  });
+}
+
+/**
+ * How long a client has to send a whole request, headers and body: the time a body of the largest size takes at the slowest accepted rate. A request not complete by then is answered 408 and its connection closed, so a client that declares a body and stops sending cannot hold a handler and its buffered bytes for Node's default of five minutes.
+ */
+export const REQUEST_TIMEOUT_MS =
+  (MAX_MESSAGE_BYTES / MIN_BODY_RATE_BYTES_PER_SECOND) * MS_PER_SECOND;
+
+function tooLarge(): RequestRefusedError {
+  return new RequestRefusedError(
+    HTTP_PAYLOAD_TOO_LARGE,
+    `Request body exceeds ${String(MAX_MESSAGE_BYTES)} bytes`,
+  );
+}
+
+/**
+ * Runs a route's asynchronous work and answers the request with its failure, so no rejection is left unhandled. A refusal keeps its status and message; anything else is a 500 with a fixed message (the error itself goes to `report`), since an unexpected error's text is not for the client. An answer that has already begun is ended, not started again. A refusal for size also closes the connection, so the rest of the body is not read.
+ */
+export function serveRoute(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  work: () => Promise<void>,
+  report: (error: Error) => void = reportToStderr,
+): void {
+  work().catch((err: unknown) => {
+    const refused = err instanceof RequestRefusedError ? err : undefined;
+    if (refused === undefined) {
+      report(err instanceof Error ? err : new Error(String(err)));
+    }
+    if (res.headersSent || res.writableEnded) {
+      res.end();
+      return;
+    }
+    res.writeHead(refused?.status ?? HTTP_INTERNAL_SERVER_ERROR, {
+      "Content-Type": "application/json",
+      ...(refused?.status === HTTP_PAYLOAD_TOO_LARGE
+        ? { Connection: "close" }
+        : {}),
+    });
+    res.end(
+      JSON.stringify({ error: refused?.message ?? "Internal server error" }),
+      () => {
+        if (refused?.status === HTTP_PAYLOAD_TOO_LARGE) req.destroy();
+      },
+    );
+  });
+}
+
+function reportToStderr(error: Error): void {
+  process.stderr.write(`agent-comms web UI: ${error.message}\n`);
+}
+
+/** The message of a failure a client may be told: a CommsError states what was refused and why, so it is shown. Anything else can quote a path or an address, so a client gets fixed text. */
+export function meshErrorMessage(err: unknown): string {
+  return err instanceof CommsError ? err.message : "Internal server error";
+}

package/src/bridges/user/web/server.ts

@@ -18,6 +18,7 @@ import type { MeshStore } from "../../../core/mesh-store.js";
 import { CommsError } from "../../../core/store.js";
 import type { MeshStatePatch } from "../../../core/wire-protocol.js";
 import type { WebUrlStatus } from "../../../core/tool.js";
+import { MAX_MESSAGE_BYTES } from "../../../core/message-limits.js";
 import {
   createRoomAction,
   declineInviteAction,
@@ -59,6 +60,13 @@ import {
 } from "./web-access.js";
 import { bridgePortRange } from "./bridge-port-range.js";
 import { startWebBeacon } from "./web-beacon.js";
+import {
+  REQUEST_TIMEOUT_MS,
+  meshErrorMessage,
+  invalidJsonBody,
+  readBoundedBody,
+  serveRoute,
+} from "./request-handling.js";
 import {
   createFrontendAssetLoader,
   FrontendNotBuiltError,
@@ -81,6 +89,10 @@ const frontendAssets = createFrontendAssetLoader(
   fileURLToPath(new URL("./dist", import.meta.url)),
 );
 
+/** The body of the 503 for a frontend that was never built. */
+const FRONTEND_NOT_BUILT_BODY =
+  "The web frontend is not built. A git checkout does not include the build output; install the npm package, or run `pnpm build:frontend` in a checkout with its development dependencies installed.";
+
 /**
  * The frontend build output, or undefined after answering 503 because the build is absent. The server module is imported by every bridge, so a checkout without the build must still start; only the routes that serve the frontend are unavailable.
  */
@@ -94,7 +106,8 @@ function frontendOrUnavailable(
     res.writeHead(HTTP_SERVICE_UNAVAILABLE, {
       "Content-Type": "text/plain; charset=utf-8",
     });
-    res.end(error.message);
+    // Fixed text: the error's own message names the install path of this machine, which is not for a client.
+    res.end(FRONTEND_NOT_BUILT_BODY);
     return undefined;
   }
 }
@@ -244,6 +257,10 @@ export async function createWebServer(options?: {
   firstContactPort?: number | undefined;
   /** Overrides the hub a fresh controller's own coordinator role dials on takeover -- ChatController's own hubUrl, ignored when existingController is supplied since that controller already made its own choice. See ChatController's own hubUrl doc comment. */
   hubUrl?: string | undefined;
+  /** Overrides REQUEST_TIMEOUT_MS, the time a client has to send a whole request. A test sets it small to see the 408. */
+  requestTimeoutMs?: number | undefined;
+  /** Overrides how often Node checks connections against that timeout (its default is thirty seconds, so a timeout takes effect up to that much after it is due). A test sets it small. */
+  connectionsCheckingIntervalMs?: number | undefined;
 }): Promise<WebServerHandle> {
   const {
     port,
@@ -255,6 +272,8 @@ export async function createWebServer(options?: {
     coordinatorPort,
     firstContactPort,
     hubUrl,
+    requestTimeoutMs = REQUEST_TIMEOUT_MS,
+    connectionsCheckingIntervalMs,
   } = options ?? {};
   const controller =
     existingController ??
@@ -282,10 +301,33 @@ export async function createWebServer(options?: {
     localClientAddresses,
   };
 
-  const server = http.createServer((req, res) => {
-    if (!admitRequest(accessPolicy, req, res)) return;
-    handleRequest(req, res, controller, webConsoleDist);
-  });
+  const server = http.createServer(
+    {
+      requestTimeout: requestTimeoutMs,
+      headersTimeout: requestTimeoutMs,
+      ...(connectionsCheckingIntervalMs !== undefined && {
+        connectionsCheckingInterval: connectionsCheckingIntervalMs,
+      }),
+    },
+    (req, res) => {
+      // Every response, the fixed routes and the operator's web-console files alike, forbids a browser to guess a type other than the one declared.
+      res.setHeader("X-Content-Type-Options", "nosniff");
+      try {
+        if (!admitRequest(accessPolicy, req, res)) return;
+        handleRequest(req, res, controller, webConsoleDist);
+      } catch (err) {
+        // A request the synchronous routing cannot handle is answered, not thrown: an exception out of this listener would end the process.
+        process.stderr.write(
+          `agent-comms web UI: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+        if (!res.headersSent) {
+          jsonError(res, "Internal server error", HTTP_INTERNAL_SERVER_ERROR);
+        } else {
+          res.end();
+        }
+      }
+    },
+  );
 
   let boundPort: number;
   try {
@@ -308,10 +350,15 @@ export async function createWebServer(options?: {
     publisher.publish({ kind: "delivery", event });
   });
 
-  const wss = new WebSocketServer({ noServer: true });
+  const wss = new WebSocketServer({
+    noServer: true,
+    maxPayload: MAX_MESSAGE_BYTES,
+  });
   const rpcHandler = new RPCHandler(meshRouter);
 
   server.on("upgrade", (req, socket, head) => {
+    // A socket error before or after the upgrade (a peer that resets, say) is that connection's alone.
+    socket.on("error", reportSocketError);
     const decision = authorise(accessPolicy, requestOf(req));
     if (decision.kind !== "allow") {
       const status =
@@ -333,6 +380,8 @@ export async function createWebServer(options?: {
   });
 
   wss.on("connection", (ws) => {
+    // A socket error (a message over the size limit closes the socket with code 1009 and raises one) is handled here: an error event with no listener would end the process.
+    ws.on("error", reportSocketError);
     // RPCHandler.upgrade() wants a DOM-shaped WebSocket (addEventListener's overload set), which "ws"'s own type declarations don't structurally satisfy (its addEventListener options param is narrower than DOM's) -- .message()/.close() accept the looser { send } shape "ws" does satisfy, and are the documented manual equivalent to .upgrade().
     const context = { controller, publisher };
     ws.on("message", (data, isBinary) => {
@@ -341,10 +390,10 @@ export async function createWebServer(options?: {
       const bytes = raw instanceof ArrayBuffer ? Buffer.from(raw) : raw;
       // Buffer's .buffer is typed ArrayBufferLike (Buffer can wrap a SharedArrayBuffer); RPCHandler.message() wants the narrower Uint8Array<ArrayBuffer> -- a fresh Uint8Array.from() copy is always backed by a plain ArrayBuffer, satisfying that exactly.
       const payload = isBinary ? Uint8Array.from(bytes) : bytes.toString();
-      void rpcHandler.message(ws, payload, { context });
+      rpcHandler.message(ws, payload, { context }).catch(reportSocketError);
     });
     ws.on("close", () => {
-      void rpcHandler.close(ws);
+      rpcHandler.close(ws).catch(reportSocketError);
     });
   });
 
@@ -362,6 +411,13 @@ export async function createWebServer(options?: {
   return { server, controller, wss, publisher, host, accessToken };
 }
 
+/** Reports a failure of one WebSocket connection to stderr: it only ever affects that connection. */
+function reportSocketError(err: unknown): void {
+  process.stderr.write(
+    `agent-comms web UI: socket error: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+}
+
 function requestOf(req: http.IncomingMessage): {
   method: string;
   url: string;
@@ -454,12 +510,16 @@ export async function runWeb(userName: string, port?: number): Promise<void> {
     process.exit(0);
   };
 
-  process.on("SIGINT", () => {
-    void cleanup();
-  });
-  process.on("SIGTERM", () => {
-    void cleanup();
-  });
+  const shutDown = (): void => {
+    cleanup().catch((err: unknown) => {
+      process.stderr.write(
+        `agent-comms web UI: shutdown failed: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+      process.exit(1);
+    });
+  };
+  process.on("SIGINT", shutDown);
+  process.on("SIGTERM", shutDown);
 }
 
 // ---------------------------------------------------------------------------
@@ -472,7 +532,14 @@ function handleRequest(
   controller: ChatController,
   webConsoleDist: string | undefined,
 ): void {
-  const url = new URL(req.url ?? "/", `http://localhost`);
+  let url: URL;
+  try {
+    url = new URL(req.url ?? "/", `http://localhost`);
+  } catch {
+    // A request target that names no URL (an empty authority, say) is a bad request, not a fault.
+    jsonError(res, "Bad request", HTTP_BAD_REQUEST);
+    return;
+  }
 
   // wire-mesh's web-console — an alternate, generic reference-client UI, served only when AGENT_COMMS_WEB_CONSOLE_DIST resolves to a real build.
   if (
@@ -550,8 +617,8 @@ function handleRequest(
     const filename = url.pathname.slice("/icons/".length);
     const assets = frontendOrUnavailable(res);
     if (assets === undefined) return;
-    const icon = assets.icons[filename];
-    if (icon) {
+    const icon = assets.icons.get(filename);
+    if (icon !== undefined) {
       res.writeHead(HTTP_OK, {
         "Content-Type": "image/svg+xml",
         "Cache-Control": "public, max-age=604800",
@@ -563,18 +630,16 @@ function handleRequest(
 
   // API routes
   if (url.pathname === "/api/agents" && req.method === "GET") {
-    void (async () => {
-      const agents = await controller.getAgents();
-      json(res, agents);
-    })();
+    serveRoute(req, res, async () => {
+      json(res, await controller.getAgents());
+    });
     return;
   }
 
   if (url.pathname === "/api/rooms" && req.method === "GET") {
-    void (async () => {
-      const rooms = await controller.getRooms();
-      json(res, rooms);
-    })();
+    serveRoute(req, res, async () => {
+      json(res, await controller.getRooms());
+    });
     return;
   }
 
@@ -583,7 +648,7 @@ function handleRequest(
     url.pathname.endsWith("/messages") &&
     req.method === "GET"
   ) {
-    void (async () => {
+    serveRoute(req, res, async () => {
       const roomId = url.pathname.split("/")[3];
       if (roomId === undefined || roomId === "") {
         jsonError(res, "Room ID required", HTTP_BAD_REQUEST);
@@ -595,7 +660,7 @@ function handleRequest(
         since,
       });
       json(res, messages);
-    })();
+    });
     return;
   }
 
@@ -613,7 +678,7 @@ function handleRequest(
   }
 
   if (url.pathname === "/api/mesh/trace" && req.method === "GET") {
-    void (async () => {
+    serveRoute(req, res, async () => {
       const target = url.searchParams.get("target");
       if (target === null || target === "") {
         jsonError(res, "target query parameter required", HTTP_BAD_REQUEST);
@@ -635,23 +700,31 @@ function handleRequest(
           meshErrorStatus(err, HTTP_BAD_REQUEST),
         );
       }
-    })();
+    });
     return;
   }
 
   if (url.pathname === "/api/action" && req.method === "POST") {
-    void (async () => {
-      const body = await readBody(req);
-      const parsed: unknown = JSON.parse(body);
-      if (typeof parsed !== "object" || parsed === null) {
-        jsonError(res, "Invalid JSON", HTTP_BAD_REQUEST);
-        return;
+    serveRoute(req, res, async () => {
+      const body = await readBoundedBody(req);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(body);
+      } catch {
+        throw invalidJsonBody();
+      }
+      if (
+        typeof parsed !== "object" ||
+        parsed === null ||
+        Array.isArray(parsed)
+      ) {
+        throw invalidJsonBody();
       }
       const params = Object.fromEntries(Object.entries(parsed));
 
       const result = await executeAction(controller, params);
       json(res, result);
-    })();
+    });
     return;
   }
 
@@ -791,11 +864,6 @@ function jsonError(
   res.end(JSON.stringify({ error: message }));
 }
 
-/** Extracts a reportable message from whatever meshGraph()/meshTrace() threw -- a CommsError has a real message, anything else is reported generically rather than leaking an unexpected error shape to the client. */
-function meshErrorMessage(err: unknown): string {
-  return err instanceof Error ? err.message : "Unknown error";
-}
-
 /** A transport that doesn't support mesh_graph/mesh_trace (CommsError code NOT_SUPPORTED, e.g. this bridge is running on FileStore rather than a real mesh) is a client-visible "this endpoint isn't available here" rather than a server fault. Any other error falls back to `otherwise` -- HTTP_BAD_REQUEST for mesh_trace, since its only other realistic failure is a malformed client-supplied target; HTTP_INTERNAL_SERVER_ERROR for mesh_graph, which takes no client input at all. */
 function meshErrorStatus(err: unknown, otherwise: number): number {
   if (err instanceof CommsError && err.code === "NOT_SUPPORTED") {
@@ -803,16 +871,3 @@ function meshErrorStatus(err: unknown, otherwise: number): number {
   }
   return otherwise;
 }
-
-async function readBody(req: http.IncomingMessage): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    req.on("data", (chunk: Buffer) => {
-      chunks.push(chunk);
-    });
-    req.on("end", () => {
-      resolve(Buffer.concat(chunks).toString());
-    });
-    req.on("error", reject);
-  });
-}

package/src/bridges/user/web/web-access.ts

@@ -32,6 +32,7 @@ const ACCESS_TOKEN_BYTES = 32;
 /** The port a Host header with no explicit port names (HTTP). */
 const HTTP_DEFAULT_PORT = 80;
 
+const HTTP_BAD_REQUEST = 400;
 const HTTP_UNAUTHORIZED = 401;
 const HTTP_FORBIDDEN = 403;
 const HTTP_FOUND = 302;
@@ -360,7 +361,10 @@ export function authorise(
     return { kind: "allow" };
   }
   if (request.method === "GET") {
-    const url = new URL(request.url, "http://placeholder");
+    const url = parseRequestUrl(request.url);
+    if (url === undefined) {
+      return { kind: "deny", status: HTTP_BAD_REQUEST, message: "Bad request" };
+    }
     const offered = url.searchParams.get(ACCESS_QUERY_PARAM);
     if (offered !== null && tokensMatch(offered, token)) {
       url.searchParams.delete(ACCESS_QUERY_PARAM);
@@ -375,6 +379,15 @@ export function authorise(
   return { kind: "deny", status: HTTP_UNAUTHORIZED, message: "Unauthorized" };
 }
 
+/** The URL a request line names, or undefined when it names none: a request target that cannot be parsed is refused, never thrown out of the request listener, which would end the process. */
+function parseRequestUrl(target: string): URL | undefined {
+  try {
+    return new URL(target, "http://placeholder");
+  } catch {
+    return undefined;
+  }
+}
+
 /** The URLs an operator can open on the LAN, each carrying the token for the one-time exchange. A wildcard bind lists every external, non-link-local address of this machine that the bind family can reach (IPv6 bracketed, and only under `::`, since `0.0.0.0` accepts IPv4 alone); a specific bind lists that address. The list is empty when a wildcard bind finds no such address. */
 export function accessUrls(
   policy: Readonly<AccessPolicy> & { readonly token: string },

package/src/bridges/user/web/web-assets.ts

@@ -21,7 +21,8 @@ export interface FrontendAssets {
   meshWorkerJs: string;
   swJs: string;
   manifestJson: string;
-  icons: Readonly<Record<string, Buffer>>;
+  /** The PWA icons by file name. A map, not an object: the name comes from the request path, and an object would also answer a name that is a member of every object (`constructor`, `toString`). */
+  icons: ReadonlyMap<string, Buffer>;
 }
 
 /** The frontend build output is absent from the directory it should be in. */
@@ -56,9 +57,12 @@ export function loadFrontendAssets(assetDir: string): FrontendAssets {
   const indexHtml = readIfPresent(path.join(assetDir, "index.html"));
   if (indexHtml === undefined) throw new FrontendNotBuiltError(assetDir);
 
-  const icons: Record<string, Buffer> = {};
+  const icons = new Map<string, Buffer>();
   for (const filename of ICON_FILENAMES) {
-    icons[filename] = fs.readFileSync(path.join(assetDir, "icons", filename));
+    icons.set(
+      filename,
+      fs.readFileSync(path.join(assetDir, "icons", filename)),
+    );
   }
 
   return {

package/src/bridges/user/web/web-console-static.ts

@@ -14,21 +14,22 @@ export const WEB_CONSOLE_MOUNT = "/web-console";
 const HTTP_OK = 200;
 const HTTP_NOT_FOUND = 404;
 
-const CONTENT_TYPES: Record<string, string> = {
-  ".html": "text/html; charset=utf-8",
-  ".js": "application/javascript; charset=utf-8",
-  ".mjs": "application/javascript; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".map": "application/json; charset=utf-8",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".ico": "image/x-icon",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".txt": "text/plain; charset=utf-8",
-  ".wasm": "application/wasm",
-};
+/** Content type by extension. A map: the extension comes from the requested name, and an object would also answer a name that is a member of every object. */
+const CONTENT_TYPES: ReadonlyMap<string, string> = new Map([
+  [".html", "text/html; charset=utf-8"],
+  [".js", "application/javascript; charset=utf-8"],
+  [".mjs", "application/javascript; charset=utf-8"],
+  [".css", "text/css; charset=utf-8"],
+  [".json", "application/json; charset=utf-8"],
+  [".map", "application/json; charset=utf-8"],
+  [".svg", "image/svg+xml"],
+  [".png", "image/png"],
+  [".ico", "image/x-icon"],
+  [".woff", "font/woff"],
+  [".woff2", "font/woff2"],
+  [".txt", "text/plain; charset=utf-8"],
+  [".wasm", "application/wasm"],
+]);
 
 const DEFAULT_CONTENT_TYPE = "application/octet-stream";
 
@@ -45,6 +46,20 @@ export function resolveWebConsoleDist(): string | undefined {
   return dist;
 }
 
+/**
+ * The real path of `file`, when it is a regular file that lies inside `dist` once every symbolic link in both paths has been followed, and undefined for anything else: a missing file, a directory, a name that cannot be resolved, or a link, anywhere along the path, that leads outside the directory. The name is checked after resolution, never before, so a link inside the directory cannot be used to read a file outside it.
+ */
+function realFileWithin(dist: string, file: string): string | undefined {
+  try {
+    const realDist = fs.realpathSync(dist);
+    const realFile = fs.realpathSync(file);
+    const inside = realFile.startsWith(`${realDist}${path.sep}`);
+    return inside && fs.statSync(realFile).isFile() ? realFile : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Serves a request under the web-console mount from a resolved dist directory.
  *
@@ -68,23 +83,16 @@ export function serveWebConsole(
 
   const resolvedDist = path.resolve(distDir);
   const resolvedFile = path.resolve(resolvedDist, relative);
-  const withinDist =
-    resolvedFile === resolvedDist ||
-    resolvedFile.startsWith(`${resolvedDist}${path.sep}`);
-
-  if (
-    !withinDist ||
-    !fs.existsSync(resolvedFile) ||
-    !fs.statSync(resolvedFile).isFile()
-  ) {
+  const servable = realFileWithin(resolvedDist, resolvedFile);
+  if (servable === undefined) {
     res.writeHead(HTTP_NOT_FOUND);
     res.end("Not found");
     return true;
   }
 
   const contentType =
-    CONTENT_TYPES[path.extname(resolvedFile)] ?? DEFAULT_CONTENT_TYPE;
+    CONTENT_TYPES.get(path.extname(servable)) ?? DEFAULT_CONTENT_TYPE;
   res.writeHead(HTTP_OK, { "Content-Type": contentType });
-  res.end(fs.readFileSync(resolvedFile));
+  res.end(fs.readFileSync(servable));
   return true;
 }

package/src/core/detached-work.ts

@@ -0,0 +1,55 @@
+/**
+ * Work started and not awaited, which must never end the process by rejecting: a peer decides what its messages contain, so an exception while handling one is reported, not left as an unhandled rejection.
+ */
+
+/**
+ * Attaches a rejection handler to `work`. A rejection goes to the error handler `getOnError` returns when it settles (read then, not now, so a handler assigned after the work started is the one used), and to stderr when there is none, so it is never silent.
+ */
+export function reportRejection(
+  work: Readonly<Promise<unknown>>,
+  getOnError: () => ((error: Error) => void) | undefined,
+): void {
+  work.catch((error: unknown) => {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    const onError = getOnError();
+    if (onError !== undefined) {
+      onError(failure);
+      return;
+    }
+    process.stderr.write(`agent-comms: ${failure.message}\n`);
+  });
+}
+
+function report(
+  error: unknown,
+  getOnError: () => ((error: Error) => void) | undefined,
+): void {
+  reportRejection(
+    Promise.reject(error instanceof Error ? error : new Error(String(error))),
+    getOnError,
+  );
+}
+
+/** What a handler of consumeEach answers: read the next item, or end the loop here. */
+export type ConsumeStep = "continue" | "stop";
+
+/**
+ * Reads `items` until the stream ends, handing each to `handle` in arrival order, one at a time. A failure of `handle` is reported through `getOnError` (see reportRejection) and the loop carries on: one item a peer sent that cannot be handled must not stop every later one on the same session. A handler that returns "stop" ends the loop at once, as `break` would. A failure of the stream itself ends the loop and is reported the same way. Never rejects.
+ */
+export async function consumeEach<T>(
+  items: Readonly<AsyncIterable<T>>,
+  handle: (item: T) => Promise<ConsumeStep> | ConsumeStep,
+  getOnError: () => ((error: Error) => void) | undefined,
+): Promise<void> {
+  try {
+    for await (const item of items) {
+      try {
+        if ((await handle(item)) === "stop") return;
+      } catch (error) {
+        report(error, getOnError);
+      }
+    }
+  } catch (error) {
+    report(error, getOnError);
+  }
+}

package/src/core/election-sessions.ts

@@ -8,6 +8,7 @@
 
 import type { AcceptedMeshSession } from "wire-mesh-core/domain/mesh-session";
 import type { CoordinatorFrame } from "wire-mesh-core/generated/protocol";
+import { consumeEach } from "./detached-work.js";
 import type { ConnectionHandle, TransportEvents } from "./transport.js";
 
 /** Where a session's outbound claims stand: whether a send is unresolved, and the newest claim that arrived meanwhile. */
@@ -39,13 +40,16 @@ export class ElectionSessions {
     session: AcceptedMeshSession,
     handle: Readonly<ConnectionHandle>,
   ): void {
-    void (async () => {
-      for await (const frame of session.coordinatorFrames) {
+    void consumeEach(
+      session.coordinatorFrames,
+      (frame) => {
         if (this.enrolled.has(session)) {
           this.events.onCoordinatorClaim(handle, frame);
         }
-      }
-    })();
+        return "continue";
+      },
+      () => this.events.onError,
+    );
   }
 
   /** Enrols a trusted machine-local session, then fires onElectionSessionEnrolled so this side tells the peer which claim it accepts. Both ends of every machine-local session enrol it, so each tells the other. */