agent-comms 8.15.9 → 8.15.11

package/src/bridges/user/web/vite.config.ts

@@ -0,0 +1,71 @@
+/**
+ * Vite build config for the web bridge frontend.
+ *
+ * Builds main.tsx (React) into dist/bundle.js, injects the precache manifest into a hand-written service worker, and copies the PWA manifest + icons from frontend/public/ into dist/.
+ *
+ * Usage: pnpm build:frontend
+ */
+
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { build as viteBuild, defineConfig, type Plugin } from "vite";
+import react from "@vitejs/plugin-react";
+import { VitePWA } from "vite-plugin-pwa";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FRONTEND_DIR = path.join(__dirname, "frontend");
+const DIST_DIR = path.join(__dirname, "dist");
+
+/**
+ * Builds the mesh SharedWorker as a separate, non-hashed bundle and writes it directly into the main build's outDir on Rollup's writeBundle hook -- after Vite's own emptyOutDir and after the main chunk is written to disk, but before vite-plugin-pwa's closeBundle hook globs the outDir for its precache manifest, so mesh-worker.js is present when the PWA plugin scans for files to precache. mesh-client.ts creates this SharedWorker from a runtime string literal ("./mesh-worker.js"), invisible to Rollup's module graph, which is why it must stay a fixed-filename artifact built outside the main bundle rather than an ordinary import.
+ */
+function meshWorkerPlugin(): Plugin {
+  return {
+    name: "agent-comms-mesh-worker",
+    async writeBundle() {
+      await viteBuild({
+        configFile: false,
+        logLevel: "warn",
+        build: {
+          outDir: DIST_DIR,
+          emptyOutDir: false,
+          minify: true,
+          lib: {
+            entry: path.join(FRONTEND_DIR, "mesh-worker.ts"),
+            formats: ["iife"],
+            name: "AgentCommsMeshWorker",
+            fileName: () => "mesh-worker.js",
+          },
+        },
+      });
+    },
+  };
+}
+
+export default defineConfig({
+  root: FRONTEND_DIR,
+  plugins: [
+    react(),
+    meshWorkerPlugin(),
+    VitePWA({
+      strategies: "injectManifest",
+      srcDir: ".",
+      filename: "sw.ts",
+      injectRegister: false,
+      manifest: false,
+      // vite-plugin-pwa builds the service worker in its own nested build. For the default "es" format it hard-codes Rollup's inlineDynamicImports: true, which Rolldown (Vite 8) deprecates in favour of codeSplitting: false and warns about on every build. The "iife" format takes the plugin's library-mode path, which sets no such option. The service worker has no imports or exports, so the only change to sw.js is an immediately-invoked function wrapper around the same code.
+      injectManifest: { rollupFormat: "iife" },
+    }),
+  ],
+  build: {
+    outDir: DIST_DIR,
+    emptyOutDir: true,
+    rollupOptions: {
+      // No dynamic import() anywhere in this codebase (banned outright by eslint.config.ts's no-restricted-syntax rule) and exactly one HTML entry point, so Rollup/Rolldown can never produce more than the one chunk named here -- no code-splitting option is needed to force it.
+      output: {
+        entryFileNames: "bundle.js",
+        assetFileNames: "assets/[name][extname]",
+      },
+    },
+  },
+});

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

@@ -0,0 +1,404 @@
+/**
+ * Network exposure policy for the bridge web server (agent-comms#346).
+ *
+ * The default is loopback only, with no token. Setting AGENT_COMMS_WEB_HOST to a non-loopback address is the explicit opt-in to LAN reachability. Because the server exposes every mutating action (POST /api/action and the /ws/mesh oRPC socket), a non-loopback bind always comes with a per-process secret token. Every request, from any client, must carry a Host header naming this server (the DNS rebinding defence: a rebound name resolves here but arrives with the attacker's name in Host), and any Origin it carries must be this server over http (the cross-site defence: a page open in the operator's own browser reaches loopback as readily as a LAN page does, so the check cannot be limited to remote clients). The one other origin admitted, and only from a client on this machine, is the hosted dashboard (see HOSTED_DASHBOARD_ORIGIN). A client on this machine (loopback, or one of this machine's own interface addresses) needs nothing more. Any other client must also present the token, as a bearer token or as the cookie a one-time `?token=` URL exchange sets.
+ */
+
+import * as crypto from "node:crypto";
+import * as net from "node:net";
+import * as os from "node:os";
+
+/** The environment variable that opts the web server into binding beyond loopback. Its value is an IP address literal to bind: `0.0.0.0` or `::` for every interface, or one interface's own address. */
+export const WEB_HOST_ENV = "AGENT_COMMS_WEB_HOST";
+
+/** The default bind address, reachable from this machine only. */
+export const LOOPBACK_HOST = "127.0.0.1";
+
+/** The prefix of the cookie a `?token=` exchange sets. Cookies are scoped to a host and not to a port (RFC 6265 section 8.5), and every bridge on a machine runs its own server on its own port with its own token, so the name carries the port to keep one browser's cookies for two bridges from overwriting each other. */
+export const ACCESS_COOKIE_PREFIX = "agent_comms_web_token";
+
+/** The name of the cookie a server listening on `port` sets and reads. */
+export function accessCookieName(port: number): string {
+  return `${ACCESS_COOKIE_PREFIX}_${String(port)}`;
+}
+
+/** The query parameter a one-time URL exchange carries the token in. */
+export const ACCESS_QUERY_PARAM = "token";
+
+/** Random bytes in the access token: 256 bits, so guessing is infeasible however many requests a LAN peer can send. */
+const ACCESS_TOKEN_BYTES = 32;
+
+/** The port a Host header with no explicit port names (HTTP). */
+const HTTP_DEFAULT_PORT = 80;
+
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_FORBIDDEN = 403;
+const HTTP_FOUND = 302;
+
+/** The authentication scheme of an `Authorization` header carrying the token. Scheme names are case-insensitive (RFC 9110 section 11.1). */
+const BEARER_SCHEME = "bearer";
+
+/** The origin of the dashboard deployed to GitHub Pages. It discovers a bridge's server by probing loopback ports and then opens its `/ws/mesh` socket cross-origin, so its Origin is admitted from a client on this machine; every other foreign origin is refused. */
+export const HOSTED_DASHBOARD_ORIGIN = "https://exadev.github.io";
+
+/** How long the address sets derived from the machine's interfaces and hostname are reused. Reading them costs a system call per interface, which every request would otherwise pay; this bounds how long a newly attached interface waits to be recognised. */
+const INTERFACE_CACHE_MS = 5000;
+
+const LINK_LOCAL_V6 = /^fe[89ab]/i;
+
+const LOOPBACK_V4_PREFIX = "127.";
+const IPV4_MAPPED_PREFIX = "::ffff:";
+const LOOPBACK_V6 = "::1";
+const IPV4_WILDCARD = "0.0.0.0";
+const IPV6_WILDCARD = "::";
+
+/** The names a client on this machine uses for loopback, always accepted in Host whatever the bind. */
+const LOOPBACK_HOSTNAMES = ["localhost", LOOPBACK_HOST, LOOPBACK_V6];
+
+/** The radix IPv6 groups are written in, and the bits and mask of one byte of the IPv4 address a mapped group pair spells. */
+const HEX_RADIX = 16;
+const BYTE_BITS = 8;
+const BYTE_MASK = 0xff;
+
+/** True for any address in 127.0.0.0/8, for ::1, and for an IPv4-mapped form of either (what a dual-stack socket reports for an IPv4 client). */
+export function isLoopbackAddress(address: string): boolean {
+  const unmapped = address.startsWith(IPV4_MAPPED_PREFIX)
+    ? address.slice(IPV4_MAPPED_PREFIX.length)
+    : address;
+  return unmapped === LOOPBACK_V6 || unmapped.startsWith(LOOPBACK_V4_PREFIX);
+}
+
+/**
+ * The canonical spelling of an IP address literal: IPv6 in its compressed form, and an IPv4-mapped IPv6 address as plain IPv4. Every spelling of one address (`::0`, `0:0:0:0:0:0:0:0`, `::ffff:0.0.0.0`) then compares equal, which classification and the Host allow-list rely on. A scoped address (`fe80::1%en0`) is returned unchanged: it is neither a wildcard nor a loopback.
+ */
+export function canonicalAddress(address: string): string {
+  if (net.isIPv4(address) || address.includes("%")) return address;
+  const compressed = new URL(`http://[${address}]`).hostname.slice(1, -1);
+  if (!compressed.startsWith(IPV4_MAPPED_PREFIX)) return compressed;
+  const tail = compressed.slice(IPV4_MAPPED_PREFIX.length);
+  if (net.isIPv4(tail)) return tail;
+  return tail
+    .split(":")
+    .flatMap((group) => {
+      const value = Number.parseInt(group, HEX_RADIX);
+      return [value >> BYTE_BITS, value & BYTE_MASK];
+    })
+    .join(".");
+}
+
+/** True when `host` binds every interface, in any spelling (see canonicalAddress). */
+export function isWildcardHost(host: string): boolean {
+  const canonical = canonicalAddress(host);
+  return canonical === IPV4_WILDCARD || canonical === IPV6_WILDCARD;
+}
+
+/** The host part of an `http` URL for `address`: IPv6 literals are bracketed. */
+export function urlHost(address: string): string {
+  return net.isIPv6(address) ? `[${address}]` : address;
+}
+
+/** The URL a client on this machine opens for a server bound to `bindHost` on `port`. A wildcard bind is reached on loopback, which needs no token. */
+export function localWebUrl(bindHost: string, port: number): string {
+  const host = isWildcardHost(bindHost) ? LOOPBACK_HOST : bindHost;
+  return `http://${urlHost(host)}:${String(port)}`;
+}
+
+/**
+ * Resolves the address the web server binds. An explicit `host` option wins, then the environment variable, then loopback. The result is the canonical spelling of the address. Anything that is not an IP address literal throws: a typo must not silently fall back to a different exposure than the operator asked for.
+ */
+export function resolveWebBindHost(
+  explicit: string | undefined,
+  env: NodeJS.ProcessEnv,
+): string {
+  const requested = explicit ?? env[WEB_HOST_ENV];
+  if (requested === undefined || requested === "") return LOOPBACK_HOST;
+  if (net.isIP(requested) === 0) {
+    throw new Error(
+      `${WEB_HOST_ENV} must be an IP address (for example 0.0.0.0), received "${requested}"`,
+    );
+  }
+  return canonicalAddress(requested);
+}
+
+/** True when binding `host` makes the server reachable from another machine, so the access token applies. */
+export function requiresAccessToken(host: string): boolean {
+  return !isLoopbackAddress(host);
+}
+
+export function generateAccessToken(): string {
+  return crypto.randomBytes(ACCESS_TOKEN_BYTES).toString("hex");
+}
+
+/**
+ * Constant-time token comparison. Both sides are hashed to a fixed length first, because crypto.timingSafeEqual requires equal-length inputs and comparing lengths directly would leak the expected token's length.
+ */
+export function tokensMatch(presented: string, expected: string): boolean {
+  const digest = (value: string): Buffer =>
+    crypto.createHash("sha256").update(value).digest();
+  return crypto.timingSafeEqual(digest(presented), digest(expected));
+}
+
+/** Returns `compute()`, reusing the previous result for INTERFACE_CACHE_MS. */
+function cachedFor<T>(compute: () => T): () => T {
+  let cached: { readonly value: T; readonly expires: number } | undefined;
+  return () => {
+    const now = Date.now();
+    if (cached === undefined || now >= cached.expires) {
+      cached = { value: compute(), expires: now + INTERFACE_CACHE_MS };
+    }
+    return cached.value;
+  };
+}
+
+function readInterfaceAddresses(): ReadonlySet<string> {
+  const addresses = new Set<string>();
+  for (const entries of Object.values(os.networkInterfaces())) {
+    for (const entry of entries ?? []) {
+      addresses.add(canonicalAddress(entry.address));
+    }
+  }
+  return addresses;
+}
+
+/** The addresses of this machine's own network interfaces, as of at most INTERFACE_CACHE_MS ago. */
+export const ownInterfaceAddresses: () => ReadonlySet<string> = cachedFor(
+  readInterfaceAddresses,
+);
+
+/** The exposure a running server is under. */
+export interface AccessPolicy {
+  /** The token every client not on this machine must present. Undefined for a loopback bind, which no such client can reach. */
+  readonly token: string | undefined;
+  readonly bindHost: string;
+  /** The port the server listens on; assigned once it is listening when the OS chose it. */
+  port: number;
+  /** The addresses whose clients count as on this machine besides loopback, read per request. A client connecting to this machine's own LAN address arrives from that address and not from loopback, so without this the `web_url` of a server bound to one interface address would answer 401 to the operator. Tests replace it to stand in for a remote client. */
+  readonly localClientAddresses: () => ReadonlySet<string>;
+}
+
+/** The parts of an incoming request the gate looks at. Shared by HTTP requests and WebSocket upgrades (an upgrade is an HTTP request). */
+export interface AccessRequest {
+  readonly method: string;
+  readonly url: string;
+  readonly remoteAddress: string | undefined;
+  readonly headers: Readonly<Record<string, string | string[] | undefined>>;
+}
+
+export type AccessDecision =
+  | { readonly kind: "allow" }
+  | { readonly kind: "deny"; readonly status: number; readonly message: string }
+  | {
+      /** The one-time URL exchange: set the cookie and redirect to a URL without the token, so it does not stay in the address bar or history. */
+      readonly kind: "exchange";
+      readonly status: number;
+      readonly cookie: string;
+      readonly location: string;
+    };
+
+function headerValue(
+  headers: AccessRequest["headers"],
+  name: string,
+): string | undefined {
+  const value = headers[name];
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function readAllowedHostnames(bindHost: string): Set<string> {
+  const names = new Set<string>(LOOPBACK_HOSTNAMES);
+  if (isWildcardHost(bindHost)) {
+    for (const address of ownInterfaceAddresses()) names.add(address);
+  } else {
+    names.add(bindHost.toLowerCase());
+  }
+  const machine = os
+    .hostname()
+    .toLowerCase()
+    .replace(/\.local$/, "");
+  names.add(machine);
+  names.add(`${machine}.local`);
+  return names;
+}
+
+const hostnameSets = new Map<string, () => ReadonlySet<string>>();
+
+/** Every hostname a client may legitimately use to reach this server: loopback names, the addresses it is bound to and this machine's own name (plus its `.local` mDNS form). Never a name an outside party could make resolve here, which is what DNS rebinding relies on, and never the wildcard address itself, which a page in a local browser can also reach. Reused for INTERFACE_CACHE_MS per bind address. */
+function allowedHostnames(bindHost: string): ReadonlySet<string> {
+  let read = hostnameSets.get(bindHost);
+  if (read === undefined) {
+    read = cachedFor(() => readAllowedHostnames(bindHost));
+    hostnameSets.set(bindHost, read);
+  }
+  return read();
+}
+
+/** A Host header names either an IP literal (compared in canonical form) or a DNS name (compared as is). */
+function canonicalAddressOrName(hostname: string): string {
+  return net.isIP(hostname) === 0 ? hostname : canonicalAddress(hostname);
+}
+
+function parseAuthority(
+  authority: string,
+): { hostname: string; port: number } | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(`http://${authority}`);
+  } catch {
+    return undefined;
+  }
+  const hostname = canonicalAddressOrName(
+    parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase(),
+  );
+  const port = parsed.port === "" ? HTTP_DEFAULT_PORT : Number(parsed.port);
+  return { hostname, port };
+}
+
+function hostHeaderAllowed(
+  policy: Readonly<AccessPolicy>,
+  headers: AccessRequest["headers"],
+): boolean {
+  const host = headerValue(headers, "host");
+  if (host === undefined) return false;
+  const authority = parseAuthority(host);
+  if (authority === undefined) return false;
+  if (authority.port !== policy.port) return false;
+  return allowedHostnames(policy.bindHost).has(authority.hostname);
+}
+
+/** An Origin, when the browser sends one, must be this very server over http: otherwise a page from anywhere (on the LAN, or open in the operator's own browser) could drive it. The hosted dashboard is the one other origin, and only for a client on this machine. */
+function originAllowed(
+  policy: Readonly<AccessPolicy>,
+  headers: AccessRequest["headers"],
+  ownClient: boolean,
+): boolean {
+  const origin = headerValue(headers, "origin");
+  if (origin === undefined) return true;
+  let parsed: URL;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    return false;
+  }
+  if (ownClient && parsed.origin === HOSTED_DASHBOARD_ORIGIN) return true;
+  if (parsed.protocol !== "http:") return false;
+  const authority = parseAuthority(parsed.host);
+  if (authority?.port !== policy.port) return false;
+  return allowedHostnames(policy.bindHost).has(authority.hostname);
+}
+
+function cookieToken(
+  headers: AccessRequest["headers"],
+  cookieName: string,
+): string | undefined {
+  const cookies = headerValue(headers, "cookie");
+  if (cookies === undefined) return undefined;
+  for (const part of cookies.split(";")) {
+    const [name, ...rest] = part.trim().split("=");
+    if (name === cookieName) return rest.join("=");
+  }
+  return undefined;
+}
+
+function bearerToken(headers: AccessRequest["headers"]): string | undefined {
+  const authorization = headerValue(headers, "authorization");
+  if (authorization === undefined) return undefined;
+  const separator = authorization.indexOf(" ");
+  if (separator === -1) return undefined;
+  const scheme = authorization.slice(0, separator).toLowerCase();
+  return scheme === BEARER_SCHEME
+    ? authorization.slice(separator + 1).trim()
+    : undefined;
+}
+
+function presentedCredential(
+  policy: Readonly<AccessPolicy>,
+  token: string,
+  headers: AccessRequest["headers"],
+): boolean {
+  const presented = [
+    bearerToken(headers),
+    cookieToken(headers, accessCookieName(policy.port)),
+  ];
+  return presented.some(
+    (candidate) => candidate !== undefined && tokensMatch(candidate, token),
+  );
+}
+
+/** True for a client on this machine: loopback, or one of this machine's own interface addresses. */
+function isOwnClient(
+  policy: Readonly<AccessPolicy>,
+  remoteAddress: string | undefined,
+): boolean {
+  if (remoteAddress === undefined) return false;
+  return (
+    isLoopbackAddress(remoteAddress) ||
+    policy.localClientAddresses().has(canonicalAddress(remoteAddress))
+  );
+}
+
+/**
+ * Decides whether a request may proceed. The Host header must name this server and any Origin must be this server, for every client. A client on this machine is then allowed. Any other client needs the token (a bearer token or the cookie); a GET carrying the right `?token=` instead exchanges it for the cookie.
+ */
+export function authorise(
+  policy: Readonly<AccessPolicy>,
+  request: AccessRequest,
+): AccessDecision {
+  if (!hostHeaderAllowed(policy, request.headers)) {
+    return { kind: "deny", status: HTTP_FORBIDDEN, message: "Forbidden host" };
+  }
+  const ownClient = isOwnClient(policy, request.remoteAddress);
+  if (!originAllowed(policy, request.headers, ownClient)) {
+    return {
+      kind: "deny",
+      status: HTTP_FORBIDDEN,
+      message: "Forbidden origin",
+    };
+  }
+  if (ownClient) return { kind: "allow" };
+  const { token } = policy;
+  if (token === undefined) {
+    return { kind: "deny", status: HTTP_UNAUTHORIZED, message: "Unauthorized" };
+  }
+  if (presentedCredential(policy, token, request.headers)) {
+    return { kind: "allow" };
+  }
+  if (request.method === "GET") {
+    const url = new URL(request.url, "http://placeholder");
+    const offered = url.searchParams.get(ACCESS_QUERY_PARAM);
+    if (offered !== null && tokensMatch(offered, token)) {
+      url.searchParams.delete(ACCESS_QUERY_PARAM);
+      return {
+        kind: "exchange",
+        status: HTTP_FOUND,
+        cookie: `${accessCookieName(policy.port)}=${token}; HttpOnly; SameSite=Lax; Path=/`,
+        location: `${url.pathname}${url.search}`,
+      };
+    }
+  }
+  return { kind: "deny", status: HTTP_UNAUTHORIZED, message: "Unauthorized" };
+}
+
+/** 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 },
+  interfaces: () => NodeJS.Dict<
+    os.NetworkInterfaceInfo[]
+  > = os.networkInterfaces,
+): string[] {
+  const hosts: string[] = [];
+  if (isWildcardHost(policy.bindHost)) {
+    const ipv4Only = canonicalAddress(policy.bindHost) === IPV4_WILDCARD;
+    for (const addresses of Object.values(interfaces())) {
+      for (const entry of addresses ?? []) {
+        if (entry.internal || LINK_LOCAL_V6.test(entry.address)) continue;
+        if (ipv4Only && entry.family !== "IPv4") continue;
+        hosts.push(urlHost(entry.address));
+      }
+    }
+  } else {
+    hosts.push(urlHost(policy.bindHost));
+  }
+  return hosts.map(
+    (host) =>
+      `http://${host}:${String(policy.port)}/?${ACCESS_QUERY_PARAM}=${policy.token}`,
+  );
+}

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

@@ -0,0 +1,90 @@
+/**
+ * The built web frontend the dashboard server serves: index.html, the JS bundle, the service worker, the mesh worker, the manifest and the PWA icons.
+ *
+ * These are build output (`build:frontend`), so a source checkout that was never built, such as a `pi install git:` clone whose install omits the development dependencies, does not have them. They are read on first use rather than when the server module is imported, so a missing frontend costs the routes that serve it and nothing else: the bridge still starts, and every API, WebSocket and mesh feature still works.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** The PWA icon files, all required alongside index.html. */
+const ICON_FILENAMES = [
+  "icon-96x96.svg",
+  "icon-192x192.svg",
+  "icon-512x512.svg",
+] as const;
+
+export interface FrontendAssets {
+  indexHtml: string;
+  bundleJs: string;
+  /** Optional in the build: a placeholder stands in when it was not produced. */
+  meshWorkerJs: string;
+  swJs: string;
+  manifestJson: string;
+  icons: Readonly<Record<string, Buffer>>;
+}
+
+/** The frontend build output is absent from the directory it should be in. */
+export class FrontendNotBuiltError extends Error {
+  constructor(public readonly assetDir: string) {
+    super(
+      `The web frontend is not built: ${path.join(assetDir, "index.html")} is missing. 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.`,
+    );
+    this.name = "FrontendNotBuiltError";
+  }
+}
+
+function readIfPresent(file: string): string | undefined {
+  try {
+    return fs.readFileSync(file, "utf-8");
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Reads the frontend build output from `assetDir` into memory. Throws FrontendNotBuiltError when `index.html` is absent, the marker that the build never ran; any other filesystem error, including a missing required file beside a present `index.html`, propagates, since that is a partial build and not an unbuilt checkout.
+ */
+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> = {};
+  for (const filename of ICON_FILENAMES) {
+    icons[filename] = fs.readFileSync(path.join(assetDir, "icons", filename));
+  }
+
+  return {
+    indexHtml,
+    bundleJs: fs.readFileSync(path.join(assetDir, "bundle.js"), "utf-8"),
+    meshWorkerJs:
+      readIfPresent(path.join(assetDir, "mesh-worker.js")) ??
+      "/* mesh-worker not built */",
+    swJs: fs.readFileSync(path.join(assetDir, "sw.js"), "utf-8"),
+    manifestJson: fs.readFileSync(
+      path.join(assetDir, "manifest.json"),
+      "utf-8",
+    ),
+    icons,
+  };
+}
+
+/**
+ * A loader over `assetDir` that reads the build output on first call and returns the same assets afterwards. A failed load is not remembered, so a build that finishes while the server runs is picked up by the next request.
+ */
+export function createFrontendAssetLoader(
+  assetDir: string,
+): () => FrontendAssets {
+  let loaded: FrontendAssets | undefined;
+  return () => {
+    loaded ??= loadFrontendAssets(assetDir);
+    return loaded;
+  };
+}

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

@@ -0,0 +1,69 @@
+/**
+ * LAN advertisement of a bridge's web UI (agent-comms#346).
+ *
+ * A send-only UDP beacon on the first-contact port announcing where this bridge's web UI listens. It carries the peer id and the web port and nothing else: the receiver learns the host from the datagram's source address, and the access token is never advertised, so seeing the beacon grants no access. The type is distinct from first-contact's own `agent-comms-beacon`, which peers parse for a data port to dial; first-contact ignores any other type, so the two never interfere.
+ */
+
+import * as dgram from "node:dgram";
+import {
+  BROADCAST_ADDRESS,
+  FIRST_CONTACT_INTERVAL_MS,
+  FIRST_CONTACT_PORT,
+} from "../../../core/first-contact.js";
+
+/** The beacon type, distinct from first-contact's `agent-comms-beacon`. */
+export const WEB_BEACON_TYPE = "agent-comms-web-beacon";
+
+export interface WebBeaconPayload {
+  type: typeof WEB_BEACON_TYPE;
+  peerId: string;
+  webPort: number;
+}
+
+export interface WebBeaconOptions {
+  peerId: string;
+  webPort: number;
+  /** The UDP port beacons are sent to. Defaults to the first-contact port; tests pass an OS-assigned free port. */
+  port?: number | undefined;
+  /** The destination address. Defaults to limited broadcast; tests pass a loopback address so no real network is needed. */
+  address?: string;
+  onError?: (error: Error) => void;
+}
+
+export interface WebBeacon {
+  stop: () => void;
+}
+
+/** Starts beaconing immediately and on first-contact's interval. A send failure (broadcast unavailable on this network) is reported through onError and never fatal. */
+export function startWebBeacon(options: Readonly<WebBeaconOptions>): WebBeacon {
+  const socket = dgram.createSocket({ type: "udp4" });
+  const destinationPort = options.port ?? FIRST_CONTACT_PORT;
+  const address = options.address ?? BROADCAST_ADDRESS;
+  const payload: WebBeaconPayload = {
+    type: WEB_BEACON_TYPE,
+    peerId: options.peerId,
+    webPort: options.webPort,
+  };
+  const message = JSON.stringify(payload);
+  const reportError = (error: Error): void => {
+    options.onError?.(error);
+  };
+  socket.on("error", reportError);
+  const send = (): void => {
+    socket.send(message, destinationPort, address, (error) => {
+      if (error) reportError(error);
+    });
+  };
+  socket.bind(0, () => {
+    if (address === BROADCAST_ADDRESS) socket.setBroadcast(true);
+    send();
+  });
+  const timer = setInterval(send, FIRST_CONTACT_INTERVAL_MS);
+  timer.unref();
+  return {
+    stop(): void {
+      clearInterval(timer);
+      socket.close();
+    },
+  };
+}