agent-comms 9.1.3 → 10.0.1

package/src/bridges/user/web/dist/sw.js

@@ -1 +1 @@
-(function(){var e=`agent-comms-v2`,t=[{"revision":"fa356ca4b2a4b6ec4a929516b593a3e4","url":"mesh-worker.js"},{"revision":"053013aa131ee0e62e4492d27f4beb90","url":"index.html"},{"revision":"acb589210914ac93762291f24b3f6492","url":"bundle.js"}].map(e=>e.url);self.addEventListener(`install`,n=>{n.waitUntil(self.caches.open(e).then(async e=>e.addAll(t)).then(async()=>self.skipWaiting()))});var n=`agent-comms-`;self.addEventListener(`activate`,t=>{t.waitUntil(self.caches.keys().then(async t=>Promise.all(t.filter(t=>t.startsWith(n)&&t!==e).map(async e=>self.caches.delete(e)))))});var r=200,i=300;function a(e,t){return e.method===`GET`&&t.status>=r&&t.status<i}function o(e){return e.type===`basic`&&e.status>=r&&e.status<i&&(e.headers.get(`content-type`)??``).startsWith(`text/html`)}var s=500,c=new URL(`index.html`,self.location.href).href;self.addEventListener(`fetch`,t=>{let n=new URL(t.request.url);if(t.request.mode===`navigate`){t.respondWith(fetch(t.request,{cache:`no-cache`}).then(n=>{if(t.request.method===`GET`&&o(n)){let t=n.clone();self.caches.open(e).then(async e=>e.put(c,t))}return n}).then(async t=>t.status<s?t:await(await self.caches.open(e)).match(c)??t).catch(async()=>self.caches.open(e).then(async e=>e.match(c)).then(e=>e??new Response(`Offline`,{status:503}))));return}if(n.pathname.startsWith(`/api/`)){t.respondWith(fetch(t.request).then(n=>{if(a(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n}).catch(async()=>self.caches.open(e).then(async e=>e.match(t.request)).then(e=>e??new Response(`Offline`,{status:503}))));return}t.respondWith(self.caches.open(e).then(async e=>e.match(t.request)).then(async n=>n||fetch(t.request).then(n=>{if(a(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n})))})})();
+(function(){var e=`agent-comms-v2`,t=[{"revision":"a59c45daf71f1675523250b8117860fd","url":"mesh-worker.js"},{"revision":"053013aa131ee0e62e4492d27f4beb90","url":"index.html"},{"revision":"7b6bc3ecb738c654599a1ee5336ed192","url":"bundle.js"}].map(e=>e.url);self.addEventListener(`install`,n=>{n.waitUntil(self.caches.open(e).then(async e=>e.addAll(t)).then(async()=>self.skipWaiting()))});var n=`agent-comms-`;self.addEventListener(`activate`,t=>{t.waitUntil(self.caches.keys().then(async t=>Promise.all(t.filter(t=>t.startsWith(n)&&t!==e).map(async e=>self.caches.delete(e)))))});var r=200,i=300;function a(e,t){return e.method===`GET`&&t.status>=r&&t.status<i}function o(e){return e.type===`basic`&&e.status>=r&&e.status<i&&(e.headers.get(`content-type`)??``).startsWith(`text/html`)}var s=500,c=new URL(`index.html`,self.location.href).href;self.addEventListener(`fetch`,t=>{let n=new URL(t.request.url);if(t.request.mode===`navigate`){t.respondWith(fetch(t.request,{cache:`no-cache`}).then(n=>{if(t.request.method===`GET`&&o(n)){let t=n.clone();self.caches.open(e).then(async e=>e.put(c,t))}return n}).then(async t=>t.status<s?t:await(await self.caches.open(e)).match(c)??t).catch(async()=>self.caches.open(e).then(async e=>e.match(c)).then(e=>e??new Response(`Offline`,{status:503}))));return}if(n.pathname.startsWith(`/api/`)){t.respondWith(fetch(t.request).then(n=>{if(a(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n}).catch(async()=>self.caches.open(e).then(async e=>e.match(t.request)).then(e=>e??new Response(`Offline`,{status:503}))));return}t.respondWith(self.caches.open(e).then(async e=>e.match(t.request)).then(async n=>n||fetch(t.request).then(n=>{if(a(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n})))})})();

package/src/bridges/user/web/pairing-handshake.ts

@@ -0,0 +1,170 @@
+/**
+ * The dashboard's half of the proof exchange with a bridge (see web-pairing.ts for the design), run in the browser and using only the `WebSocket` and Web Crypto globals the browser and Node both have, so it imports nothing from either: before the dashboard sends a listener anything, it asks it to prove it holds the secret this browser was paired with, checks that proof, and only then proves it holds the secret too. The secret is the key of both proofs and is never sent.
+ */
+
+import {
+  HELLO_PATH,
+  HEX_32_PATTERN,
+  NONCE_BYTES,
+  isHelloReply,
+  isHelloTicket,
+  parseHelloMessage,
+  proofInput,
+  type HelloAuth,
+  type HelloRequest,
+  type ProofTranscript,
+} from "./pairing-protocol.js";
+
+/** How long the whole exchange may take before the port counts as no bridge. A bridge answers three small frames on loopback well inside this. */
+export const HANDSHAKE_TIMEOUT_MS = 2000;
+
+const HEX_RADIX = 16;
+const HEX_DIGITS_PER_BYTE = 2;
+
+function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) =>
+    byte.toString(HEX_RADIX).padStart(HEX_DIGITS_PER_BYTE, "0"),
+  ).join("");
+}
+
+function fromHex(hex: string): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(hex.length / HEX_DIGITS_PER_BYTE);
+  for (let index = 0; index < bytes.length; index++) {
+    bytes[index] = Number.parseInt(
+      hex.slice(index * HEX_DIGITS_PER_BYTE, (index + 1) * HEX_DIGITS_PER_BYTE),
+      HEX_RADIX,
+    );
+  }
+  return bytes;
+}
+
+async function hmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    fromHex(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"],
+  );
+}
+
+/** The proof a holder of `secret` gives for this exchange, as hex. */
+export async function proofFor(
+  secret: string,
+  transcript: Readonly<ProofTranscript>,
+): Promise<string> {
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    await hmacKey(secret),
+    proofInput(transcript),
+  );
+  return toHex(new Uint8Array(signature));
+}
+
+/** Whether `presented` is the proof for this exchange under `secret`. The comparison is the platform's own `verify`, which is constant time. */
+export async function proofChecks(
+  presented: string,
+  secret: string,
+  transcript: Readonly<ProofTranscript>,
+): Promise<boolean> {
+  if (!HEX_32_PATTERN.test(presented)) return false;
+  return crypto.subtle.verify(
+    "HMAC",
+    await hmacKey(secret),
+    fromHex(presented),
+    proofInput(transcript),
+  );
+}
+
+/** The address of the exchange's socket on `port`. */
+export function helloUrl(port: number): string {
+  return `ws://127.0.0.1:${String(port)}${HELLO_PATH}`;
+}
+
+function newNonce(): string {
+  return toHex(crypto.getRandomValues(new Uint8Array(NONCE_BYTES)));
+}
+
+/**
+ * Runs the exchange with whatever listens on `port` and resolves with the single-use ticket for one mesh socket, or undefined when the listener is not a bridge that holds `secret`, or does not answer in time. What the listener is sent before it has proved itself is one nonce.
+ */
+export async function acquireTicket(
+  port: number,
+  secret: string,
+  timeoutMs: number = HANDSHAKE_TIMEOUT_MS,
+): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    let socket: WebSocket;
+    try {
+      socket = new WebSocket(helloUrl(port));
+    } catch {
+      resolve(undefined);
+      return;
+    }
+    const clientNonce = newNonce();
+    let bridgeNonce: string | undefined;
+    let settled = false;
+    const timer: { handle?: ReturnType<typeof setTimeout> } = {};
+    const settle = (ticket: string | undefined): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer.handle);
+      socket.close();
+      resolve(ticket);
+    };
+    timer.handle = setTimeout(() => {
+      settle(undefined);
+    }, timeoutMs);
+    socket.addEventListener("error", () => {
+      settle(undefined);
+    });
+    socket.addEventListener("close", () => {
+      settle(undefined);
+    });
+    socket.addEventListener("open", () => {
+      const request: HelloRequest = { type: "hello", nonce: clientNonce };
+      socket.send(JSON.stringify(request));
+    });
+    socket.addEventListener("message", (event: MessageEvent) => {
+      if (typeof event.data !== "string") {
+        settle(undefined);
+        return;
+      }
+      const message = parseHelloMessage(event.data);
+      if (bridgeNonce === undefined) {
+        if (!isHelloReply(message)) {
+          settle(undefined);
+          return;
+        }
+        bridgeNonce = message.nonce;
+        void proofChecks(message.proof, secret, {
+          role: "bridge",
+          clientNonce,
+          bridgeNonce: message.nonce,
+          port,
+        })
+          .then(async (genuine) => {
+            if (!genuine) {
+              settle(undefined);
+              return;
+            }
+            const auth: HelloAuth = {
+              type: "auth",
+              proof: await proofFor(secret, {
+                role: "client",
+                clientNonce,
+                bridgeNonce: message.nonce,
+                port,
+              }),
+            };
+            socket.send(JSON.stringify(auth));
+          })
+          .catch(() => {
+            settle(undefined);
+          });
+        return;
+      }
+      settle(isHelloTicket(message) ? message.ticket : undefined);
+    });
+  });
+}

package/src/bridges/user/web/pairing-protocol.ts

@@ -0,0 +1,122 @@
+/**
+ * What the hosted dashboard and the bridge agree on for pairing (web-pairing.ts describes the design): the fragment parameter the pairing page hands the secret over in, the paths and subprotocols of the proof exchange, the shape of its messages, and the bytes each side keys its proof over. Shared by the Node server and the browser frontend, so it imports nothing from either.
+ *
+ * The secret never crosses a socket. Before the dashboard sends anything to a listener it asks the listener to prove it holds the secret, and only then proves it holds it too (see `proofInput`); the bridge answers with a single-use ticket that admits one mesh socket.
+ */
+
+/** The name of the fragment parameter the pairing page opens the dashboard with. */
+export const PAIRING_FRAGMENT_PARAM = "pair";
+
+/** The path of the mesh socket the dashboard's own traffic runs over. */
+export const MESH_PATH = "/ws/mesh";
+
+/** The path of the socket the proof exchange runs over. It carries nothing but the exchange, and a page of the hosted origin may open it without a ticket. */
+export const HELLO_PATH = "/ws/hello";
+
+/** The subprotocol a server selects for every mesh upgrade that offers the dashboard's protocols, so the offered ticket is never echoed back. */
+export const MESH_SUBPROTOCOL = "agent-comms";
+
+/** The prefix of the subprotocol that carries a ticket on a mesh upgrade, because the browser's WebSocket API cannot set headers and a query string would put the ticket in logs and history. */
+export const TICKET_SUBPROTOCOL_PREFIX = "agent-comms-ticket.";
+
+/** What a secret looks like: exactly 32 bytes in lower-case hex. */
+export const PAIRING_SECRET_PATTERN = /^[0-9a-f]{64}$/;
+
+/** What a nonce, a proof and a ticket look like: 32 bytes in lower-case hex. */
+export const HEX_32_PATTERN = /^[0-9a-f]{64}$/;
+
+/** Random bytes in a nonce, and in a ticket. */
+export const NONCE_BYTES = 32;
+
+/** The role label a proof is keyed over: the bridge proving it holds the secret, and the dashboard proving it. Different labels and a different order of the two nonces keep one proof from standing in for the other. */
+export type ProofRole = "bridge" | "client";
+
+/** The dashboard's first message: its fresh nonce. */
+export interface HelloRequest {
+  type: "hello";
+  nonce: string;
+}
+
+/** The bridge's answer: its own fresh nonce and its proof over both. */
+export interface HelloReply {
+  type: "hello-ok";
+  nonce: string;
+  proof: string;
+}
+
+/** The dashboard's proof, sent only after the bridge's checked out. */
+export interface HelloAuth {
+  type: "auth";
+  proof: string;
+}
+
+/** The bridge's last message: the single-use ticket for one mesh socket. */
+export interface HelloTicket {
+  type: "ticket";
+  ticket: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hex32(value: unknown): value is string {
+  return typeof value === "string" && HEX_32_PATTERN.test(value);
+}
+
+/** Reads one JSON message of the exchange, or undefined for text that is not JSON. The caller narrows the result with the guards below. */
+export function parseHelloMessage(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+export function isHelloRequest(value: unknown): value is HelloRequest {
+  return isRecord(value) && value.type === "hello" && hex32(value.nonce);
+}
+
+export function isHelloReply(value: unknown): value is HelloReply {
+  return (
+    isRecord(value) &&
+    value.type === "hello-ok" &&
+    hex32(value.nonce) &&
+    hex32(value.proof)
+  );
+}
+
+export function isHelloAuth(value: unknown): value is HelloAuth {
+  return isRecord(value) && value.type === "auth" && hex32(value.proof);
+}
+
+export function isHelloTicket(value: unknown): value is HelloTicket {
+  return isRecord(value) && value.type === "ticket" && hex32(value.ticket);
+}
+
+/** What a proof is made over: whose proof it is, the two nonces in the order the exchange sent them (the dashboard's, then the bridge's) and the port the dashboard dialled. */
+export interface ProofTranscript {
+  role: ProofRole;
+  clientNonce: string;
+  bridgeNonce: string;
+  port: number;
+}
+
+/**
+ * The bytes a proof is keyed over, with the secret as the key. A proof for one port is not one for another, so a listener that relays the dashboard's challenge to the real bridge on a different port cannot pass the answer off as its own.
+ */
+export function proofInput(
+  transcript: Readonly<ProofTranscript>,
+): Uint8Array<ArrayBuffer> {
+  const { role, clientNonce, bridgeNonce, port } = transcript;
+  return new TextEncoder().encode(
+    [role, clientNonce, bridgeNonce, String(port)].join("\0"),
+  );
+}
+
+/** The subprotocols the dashboard offers when it opens a mesh socket: the fixed one, and the one carrying its ticket when it has one. */
+export function meshSocketProtocols(ticket: string | undefined): string[] {
+  return ticket === undefined
+    ? [MESH_SUBPROTOCOL]
+    : [MESH_SUBPROTOCOL, `${TICKET_SUBPROTOCOL_PREFIX}${ticket}`];
+}

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

@@ -8,7 +8,6 @@
  * When AGENT_COMMS_WEB_CONSOLE_DIST points at a built wire-mesh web-console (see web-console-static.ts), GET /web-console/* also serves that as an alternate, generic reference-client UI alongside the frontend above.
  */
 
-import { once } from "node:events";
 import * as http from "node:http";
 import { fileURLToPath } from "node:url";
 import { WebSocketServer } from "ws";
@@ -50,6 +49,8 @@ import {
   ACCESS_QUERY_PARAM,
   accessUrls,
   authorise,
+  isHostedDashboardOrigin,
+  isOwnClient,
   generateAccessToken,
   localWebUrl,
   ownInterfaceAddresses,
@@ -59,6 +60,8 @@ import {
   type AccessPolicy,
 } from "./web-access.js";
 import { bridgePortRange } from "./bridge-port-range.js";
+import { listen } from "./web-listen.js";
+import { HOSTED_DASHBOARD_ORIGIN } from "./hosted-dashboard.js";
 import { startWebBeacon } from "./web-beacon.js";
 import {
   REQUEST_TIMEOUT_MS,
@@ -67,6 +70,24 @@ import {
   readBoundedBody,
   serveRoute,
 } from "./request-handling.js";
+import {
+  PAIRING_PAGE_HEADERS,
+  PAIRING_PAGE_PATH,
+  openPairingSecret,
+  watchPairingSecret,
+  pairingPageHtml,
+  selectMeshSubprotocol,
+  type PairingSecretStore,
+} from "./web-pairing.js";
+import {
+  MAX_HELLO_MESSAGE_BYTES,
+  MAX_HELLO_SOCKETS,
+  ROTATION_SWEEP_MS,
+  createHostedSocketGuard,
+  createTicketBook,
+  serveHello,
+} from "./web-pairing-exchange.js";
+import { HELLO_PATH, MESH_PATH } from "./pairing-protocol.js";
 import {
   createFrontendAssetLoader,
   FrontendNotBuiltError,
@@ -76,6 +97,7 @@ import {
 const HTTP_OK = 200;
 const HTTP_BAD_REQUEST = 400;
 const HTTP_UNAUTHORIZED = 401;
+const HTTP_FORBIDDEN = 403;
 const HTTP_NOT_FOUND = 404;
 const HTTP_INTERNAL_SERVER_ERROR = 500;
 const HTTP_NOT_IMPLEMENTED = 501;
@@ -168,68 +190,6 @@ export async function tryStartBridgeWebServer(
   });
 }
 
-/** Whether a listen failure means the port is already taken. */
-function isAddressInUse(error: unknown): boolean {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    "code" in error &&
-    error.code === "EADDRINUSE"
-  );
-}
-
-/** Binds `server` to `port` on `host`; true once listening, false when the port is taken, and rejects on any other failure. */
-async function tryListen(
-  server: http.Server,
-  port: number,
-  host: string,
-): Promise<boolean> {
-  // once() rejects when the server emits "error" before "listening", and removes both of its listeners either way.
-  const listening = once(server, "listening");
-  server.listen(port, host);
-  try {
-    await listening;
-    return true;
-  } catch (error) {
-    if (isAddressInUse(error)) return false;
-    throw error;
-  }
-}
-
-/**
- * Binds `server` to the first of `ports` that is free, in order, and returns the port it holds.
- *
- * Each port is bound for real, so a port another process takes between two attempts is simply skipped, where a test-then-bind would hand two processes the same port. Only "already in use" moves on to the next port: any other bind error rejects with that error. When `fallBackToAnyPort` is set and every port is taken the operating system picks one; when nothing could be bound the error names every port tried.
- */
-async function listen(
-  server: http.Server,
-  host: string,
-  ports: readonly number[],
-  fallBackToAnyPort: boolean,
-): Promise<number> {
-  for (const port of ports) {
-    if (await tryListen(server, port, host)) return boundPortOf(server);
-  }
-  if (fallBackToAnyPort && (await tryListen(server, 0, host))) {
-    return boundPortOf(server);
-  }
-  const tried = fallBackToAnyPort
-    ? [...ports.map(String), "an operating-system port"]
-    : ports.map(String);
-  throw new Error(
-    `Agent Comms web UI: every port tried is already in use on ${host}: ${tried.join(", ")}`,
-  );
-}
-
-/** The port a listening server holds. */
-function boundPortOf(server: http.Server): number {
-  const addr = server.address();
-  if (typeof addr !== "object" || addr === null) {
-    throw new Error("Agent Comms web UI: the listening server has no address");
-  }
-  return addr.port;
-}
-
 /**
  * Create the web server and resolve once it is listening.
  *
@@ -251,6 +211,12 @@ export async function createWebServer(options?: {
   localClientAddresses?: (() => ReadonlySet<string>) | undefined;
   /** The UDP port the LAN beacon advertises on when the bind is beyond loopback. Defaults to the first-contact port; tests pass an OS-assigned free port. */
   beaconPort?: number | undefined;
+  /** The directory the pairing secret is kept in. Defaults to the bridge's data directory; tests pass one of their own. */
+  pairingDir?: string | undefined;
+  /** Whether to watch the pairing secret file and act on a rotation the moment it is reported. Defaults to true; a test turns it off to see what the periodic sweep and the next message do alone. */
+  watchPairingFile?: boolean | undefined;
+  /** How often sockets admitted under a replaced pairing secret are looked for and closed. Defaults to ROTATION_SWEEP_MS; a test sets it long to see that a message alone ends such a socket. */
+  pairingSweepMs?: number | undefined;
   existingController?: ChatController | undefined;
   coordinatorPort?: number | undefined;
   /** Overrides the first-contact UDP port a fresh controller's store runs presence on (ChatController's own firstContactPort); ignored when existingController is supplied. */
@@ -268,6 +234,9 @@ export async function createWebServer(options?: {
     host: requestedHost,
     localClientAddresses = ownInterfaceAddresses,
     beaconPort,
+    pairingDir,
+    watchPairingFile = true,
+    pairingSweepMs = ROTATION_SWEEP_MS,
     existingController,
     coordinatorPort,
     firstContactPort,
@@ -294,11 +263,23 @@ export async function createWebServer(options?: {
     : undefined;
 
   // The port is only known once the server listens (port 0 asks the OS), so the policy's port is filled in once the server is bound, before any request can arrive.
+  const pairing = openPairingSecret({
+    dir: pairingDir,
+    onReplaced: (file) => {
+      process.stderr.write(
+        `agent-comms: ${file} was missing or unusable and has been replaced, so browsers paired with the hosted dashboard must pair again\n`,
+      );
+    },
+  });
+  const tickets = createTicketBook(pairing);
+  const hostedSockets = createHostedSocketGuard(pairing);
   const accessPolicy: AccessPolicy = {
     token: accessToken,
     bindHost: host,
     port: port ?? 0,
     localClientAddresses,
+    // Tickets are only accepted under the secret in force, so `agent-comms pairing rotate` refuses every ticket issued before it without a restart.
+    tickets,
   };
 
   const server = http.createServer(
@@ -314,7 +295,11 @@ export async function createWebServer(options?: {
       res.setHeader("X-Content-Type-Options", "nosniff");
       try {
         if (!admitRequest(accessPolicy, req, res)) return;
-        handleRequest(req, res, controller, webConsoleDist);
+        handleRequest(req, res, controller, {
+          pairing,
+          isOwnClient: isOwnClient(accessPolicy, req.socket.remoteAddress),
+          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(
@@ -353,8 +338,40 @@ export async function createWebServer(options?: {
   const wss = new WebSocketServer({
     noServer: true,
     maxPayload: MAX_MESSAGE_BYTES,
+    // The dashboard offers the mesh subprotocol beside its ticket; selecting only the fixed name keeps the ticket from being echoed.
+    handleProtocols: selectMeshSubprotocol,
+  });
+  // The proof exchange's own socket: tiny messages only, and a handful at a time.
+  const helloWss = new WebSocketServer({
+    noServer: true,
+    maxPayload: MAX_HELLO_MESSAGE_BYTES,
   });
   const rpcHandler = new RPCHandler(meshRouter);
+  // A socket admitted under a secret that has since been replaced is ended, also when it is idle.
+  const rotationSweep = setInterval(() => {
+    hostedSockets.sweep();
+  }, pairingSweepMs);
+  rotationSweep.unref();
+  // The sweep is the backstop. A rotation is acted on the moment the secret file changes, so a revoked socket does not stay open for the length of a poll.
+  // Opening the secret creates its directory, which the watch needs to exist.
+  pairing.current();
+  const stopWatching = (
+    watchPairingFile ? watchPairingSecret : () => () => undefined
+  )({
+    dir: pairingDir,
+    onChange: () => {
+      hostedSockets.sweep();
+    },
+    onError: (error) => {
+      process.stderr.write(
+        `agent-comms: cannot watch the pairing secret, so a rotation ends hosted sockets at the next sweep: ${error.message}\n`,
+      );
+    },
+  });
+  server.once("close", () => {
+    clearInterval(rotationSweep);
+    stopWatching();
+  });
 
   server.on("upgrade", (req, socket, head) => {
     // A socket error before or after the upgrade (a peer that resets, say) is that connection's alone.
@@ -369,22 +386,35 @@ export async function createWebServer(options?: {
       socket.destroy();
       return;
     }
-    if (req.url === "/ws/mesh") {
+    if (req.url === MESH_PATH) {
       wss.handleUpgrade(req, socket, head, (ws) => {
         wss.emit("connection", ws, req);
       });
+    } else if (
+      req.url === HELLO_PATH &&
+      helloWss.clients.size < MAX_HELLO_SOCKETS
+    ) {
+      helloWss.handleUpgrade(req, socket, head, (ws) => {
+        serveHello(ws, {
+          secret: pairing,
+          tickets,
+          port: () => accessPolicy.port,
+        });
+      });
     } else {
       socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
       socket.destroy();
     }
   });
 
-  wss.on("connection", (ws) => {
+  wss.on("connection", (ws, req) => {
     // 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);
+    if (isHostedDashboardOrigin(req.headers.origin)) hostedSockets.track(ws);
     // 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) => {
+      if (!hostedSockets.check(ws)) return;
       // "ws" types incoming data as Buffer | ArrayBuffer | Buffer[] regardless of frame type; normalise to a real Buffer first so both branches below have a type they can trust rather than calling .toString()/Uint8Array.from() on a union that could be an ArrayBuffer.
       const raw = Array.isArray(data) ? Buffer.concat(data) : data;
       const bytes = raw instanceof ArrayBuffer ? Buffer.from(raw) : raw;
@@ -399,6 +429,9 @@ export async function createWebServer(options?: {
 
   // stderr, not stdout: a stdio MCP bridge owns stdout for JSON-RPC, so any other line there is protocol noise to a strictly framed client.
   console.error(`Agent Comms web UI: ${localWebUrl(host, boundPort)}`);
+  console.error(
+    `To pair the hosted dashboard with this bridge, open ${localWebUrl(host, boundPort)}${PAIRING_PAGE_PATH} in the browser you use`,
+  );
   if (accessToken !== undefined) {
     announceLanAccess(
       server,
@@ -526,11 +559,41 @@ export async function runWeb(userName: string, port?: number): Promise<void> {
 // HTTP handler
 // ---------------------------------------------------------------------------
 
+/** What a request handler knows about the request beyond its parts: the pairing secret store, and whether the client is on this machine. */
+interface RequestContext {
+  pairing: PairingSecretStore;
+  isOwnClient: boolean;
+  webConsoleDist: string | undefined;
+}
+
+/** The `Sec-Fetch-Site` values of a request a person started from the address bar or a bookmark (`none`), or that this server's own page made. A link or a script on another site sends `cross-site` or `same-site`. */
+const PERSON_INITIATED_FETCH_SITES = new Set(["none", "same-origin"]);
+
+/** Serves the pairing page to a person at this machine: a client on this machine, no Origin of another site and no cross-site fetch metadata. Anything else is a 403, answered without the secret. */
+function servePairingPage(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  context: Readonly<RequestContext>,
+): void {
+  const site = req.headers["sec-fetch-site"];
+  const fromAnotherSite =
+    typeof site === "string" && !PERSON_INITIATED_FETCH_SITES.has(site);
+  // A page of the hosted dashboard, paired or not, is never the person this page is for.
+  const fromHostedDashboard = req.headers.origin === HOSTED_DASHBOARD_ORIGIN;
+  if (!context.isOwnClient || fromAnotherSite || fromHostedDashboard) {
+    res.writeHead(HTTP_FORBIDDEN, { "Content-Type": "text/plain" });
+    res.end("Forbidden");
+    return;
+  }
+  res.writeHead(HTTP_OK, PAIRING_PAGE_HEADERS);
+  res.end(pairingPageHtml(context.pairing.current()));
+}
+
 function handleRequest(
   req: http.IncomingMessage,
   res: http.ServerResponse,
   controller: ChatController,
-  webConsoleDist: string | undefined,
+  context: Readonly<RequestContext>,
 ): void {
   let url: URL;
   try {
@@ -543,13 +606,18 @@ function handleRequest(
 
   // 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 (
-    webConsoleDist !== undefined &&
+    context.webConsoleDist !== undefined &&
     req.method === "GET" &&
-    serveWebConsole(webConsoleDist, url.pathname, res)
+    serveWebConsole(context.webConsoleDist, url.pathname, res)
   ) {
     return;
   }
 
+  if (url.pathname === PAIRING_PAGE_PATH && req.method === "GET") {
+    servePairingPage(req, res, context);
+    return;
+  }
+
   // Frontend HTML -- also served at the literal /index.html path (not just
   // /) because vite-plugin-pwa's injectManifest precache list references
   // the build output's own filename, index.html, and precaches it by