agent-comms 9.1.3 → 10.0.1

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

@@ -1,13 +1,15 @@
 /**
  * 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.
+ * 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 and only on the two sockets of the pairing exchange (web-pairing.ts), 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";
 import { HOSTED_DASHBOARD_ORIGIN } from "./hosted-dashboard.js";
+import { HELLO_PATH, MESH_PATH } from "./pairing-protocol.js";
+import { presentedTicket } from "./web-pairing.js";
 
 /** 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";
@@ -40,6 +42,16 @@ 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";
 
+/** Whether an Origin header names the hosted dashboard's origin. */
+export function isHostedDashboardOrigin(origin: string | undefined): boolean {
+  if (origin === undefined) return false;
+  try {
+    return new URL(origin).origin === HOSTED_DASHBOARD_ORIGIN;
+  } catch {
+    return false;
+  }
+}
+
 /** 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;
 
@@ -173,6 +185,10 @@ export interface AccessPolicy {
   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 tickets that admit the hosted dashboard's mesh socket (web-pairing-exchange.ts). Undefined admits no request from that origin to any path but the exchange's own. */
+  readonly tickets?:
+    | Readonly<{ consume: (presented: string | undefined) => boolean }>
+    | undefined;
 }
 
 /** The parts of an incoming request the gate looks at. Shared by HTTP requests and WebSocket upgrades (an upgrade is an HTTP request). */
@@ -263,12 +279,28 @@ function hostHeaderAllowed(
   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. */
+/** What a page of the hosted dashboard's origin may reach: the exchange's own socket with nothing, and the mesh socket with a ticket the exchange issued, which is spent by being presented. Both only as a WebSocket upgrade, so none of the HTTP routes and no ticket is spent by a plain request. */
+function hostedPageAllowed(
+  policy: Readonly<AccessPolicy>,
+  request: AccessRequest,
+): boolean {
+  if (headerValue(request.headers, "upgrade")?.toLowerCase() !== "websocket") {
+    return false;
+  }
+  if (request.url === HELLO_PATH) return true;
+  return (
+    request.url === MESH_PATH &&
+    policy.tickets?.consume(presentedTicket(request.headers)) === true
+  );
+}
+
+/** 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 that opens the exchange's socket, or the mesh socket with a ticket from it. */
 function originAllowed(
   policy: Readonly<AccessPolicy>,
-  headers: AccessRequest["headers"],
+  request: AccessRequest,
   ownClient: boolean,
 ): boolean {
+  const { headers } = request;
   const origin = headerValue(headers, "origin");
   if (origin === undefined) return true;
   let parsed: URL;
@@ -277,7 +309,9 @@ function originAllowed(
   } catch {
     return false;
   }
-  if (ownClient && parsed.origin === HOSTED_DASHBOARD_ORIGIN) return true;
+  if (parsed.origin === HOSTED_DASHBOARD_ORIGIN) {
+    return ownClient && hostedPageAllowed(policy, request);
+  }
   if (parsed.protocol !== "http:") return false;
   const authority = parseAuthority(parsed.host);
   if (authority?.port !== policy.port) return false;
@@ -323,7 +357,7 @@ function presentedCredential(
 }
 
 /** True for a client on this machine: loopback, or one of this machine's own interface addresses. */
-function isOwnClient(
+export function isOwnClient(
   policy: Readonly<AccessPolicy>,
   remoteAddress: string | undefined,
 ): boolean {
@@ -345,7 +379,7 @@ export function authorise(
     return { kind: "deny", status: HTTP_FORBIDDEN, message: "Forbidden host" };
   }
   const ownClient = isOwnClient(policy, request.remoteAddress);
-  if (!originAllowed(policy, request.headers, ownClient)) {
+  if (!originAllowed(policy, request, ownClient)) {
     return {
       kind: "deny",
       status: HTTP_FORBIDDEN,

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

@@ -0,0 +1,68 @@
+/**
+ * Binding the web server's listening socket: the first free port of a range, each port bound for real, with a fallback to an operating-system port. Split from server.ts to keep that file under the line cap.
+ */
+
+import { once } from "node:events";
+import type * as http from "node:http";
+
+/** 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.
+ */
+export 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;
+}

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

@@ -0,0 +1,292 @@
+/**
+ * The bridge's half of the proof exchange that admits the hosted dashboard (web-pairing.ts describes the design): the keyed proof, the single-use tickets a completed exchange issues, and the handler of one `/ws/hello` socket.
+ *
+ * A listener that does not hold the secret is told nothing and given nothing by this module beyond a nonce: the bridge's proof is keyed with the secret, and the dashboard's proof is checked before any ticket is issued.
+ */
+
+import * as crypto from "node:crypto";
+import {
+  NONCE_BYTES,
+  isHelloAuth,
+  isHelloRequest,
+  parseHelloMessage,
+  proofInput,
+  type HelloReply,
+  type HelloTicket,
+  type ProofTranscript,
+} from "./pairing-protocol.js";
+import type { PairingSecretStore } from "./web-pairing.js";
+
+/** How long a ticket admits a mesh socket after it is issued. The dashboard opens the socket at once, so a few seconds is far above the real delay and keeps an unused ticket from being worth holding. */
+export const TICKET_LIFETIME_MS = 10_000;
+
+/** The most tickets that wait to be used at once: a bridge has one dashboard, so a few is generous, and a client that asks for more is refused rather than served. */
+export const MAX_PENDING_TICKETS = 16;
+
+/** How long one exchange may take from its first byte to the ticket, which is a few small frames over loopback. */
+export const HELLO_TIMEOUT_MS = 5000;
+
+/** The most exchanges in progress at once. */
+export const MAX_HELLO_SOCKETS = 16;
+
+/** The largest message of the exchange: a JSON object of at most two 64-character hex values. */
+export const MAX_HELLO_MESSAGE_BYTES = 1024;
+
+/** WebSocket close code for a message that breaks the endpoint's policy, used for every refusal so none says which check failed. */
+const CLOSE_POLICY_VIOLATION = 1008;
+const CLOSE_NORMAL = 1000;
+
+/** The proof a party holding `secret` gives over this exchange, as hex. */
+export function computeProof(
+  secret: string,
+  transcript: Readonly<ProofTranscript>,
+): string {
+  return crypto
+    .createHmac("sha256", Buffer.from(secret, "hex"))
+    .update(proofInput(transcript))
+    .digest("hex");
+}
+
+/** Whether `presented` is the proof for this exchange under `secret`, compared in constant time. */
+export function proofMatches(
+  presented: string,
+  secret: string,
+  transcript: Readonly<ProofTranscript>,
+): boolean {
+  const expected = Buffer.from(computeProof(secret, transcript), "hex");
+  const given = Buffer.from(presented, "hex");
+  return (
+    given.length === expected.length && crypto.timingSafeEqual(given, expected)
+  );
+}
+
+/** The single-use tickets a completed exchange issues. */
+export interface TicketBook {
+  /** A fresh ticket, or undefined when too many wait to be used. */
+  issue: () => string | undefined;
+  /** Whether `presented` is a ticket that was issued, has not been used or expired, and was issued under the secret still in force. Spends it either way: a ticket is offered once. */
+  consume: (presented: string | undefined) => boolean;
+}
+
+/** A ticket book over a secret store: a ticket issued under a secret that has since been replaced is never accepted. */
+export function createTicketBook(
+  secret: Readonly<PairingSecretStore>,
+  now: () => number = Date.now,
+): TicketBook {
+  const pending = new Map<string, { expires: number; generation: number }>();
+  const prune = (): void => {
+    const current = now();
+    for (const [ticket, entry] of pending) {
+      if (entry.expires <= current) pending.delete(ticket);
+    }
+  };
+  return {
+    issue: () => {
+      prune();
+      if (pending.size >= MAX_PENDING_TICKETS) return undefined;
+      secret.current();
+      const ticket = crypto.randomBytes(NONCE_BYTES).toString("hex");
+      pending.set(ticket, {
+        expires: now() + TICKET_LIFETIME_MS,
+        generation: secret.generation(),
+      });
+      return ticket;
+    },
+    consume: (presented) => {
+      if (presented === undefined) return false;
+      prune();
+      const entry = pending.get(presented);
+      if (entry === undefined) return false;
+      pending.delete(presented);
+      secret.current();
+      return entry.generation === secret.generation();
+    },
+  };
+}
+
+/** What serving a hello socket needs. */
+export interface HelloOptions {
+  secret: Readonly<PairingSecretStore>;
+  tickets: Readonly<TicketBook>;
+  /** The port the server listens on, which both proofs are keyed over. */
+  port: () => number;
+  /** The timer in force for the exchange; tests replace it. */
+  timeoutMs?: number;
+}
+
+/** The text of one WebSocket message as `ws` hands it over. */
+function textOf(data: Buffer | ArrayBuffer | readonly Buffer[]): string {
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString();
+  if (Buffer.isBuffer(data)) return data.toString();
+  return Buffer.concat([...data]).toString();
+}
+
+function newNonce(): string {
+  return crypto.randomBytes(NONCE_BYTES).toString("hex");
+}
+
+/** The parts of a `ws` socket the exchange uses, so a test can stand in for one. */
+export interface HelloSocket {
+  on: ((
+    event: "message",
+    listener: (
+      data: Buffer | ArrayBuffer | readonly Buffer[],
+      isBinary: boolean,
+    ) => void,
+  ) => unknown) &
+    ((event: "close" | "error", listener: () => void) => unknown);
+  send: (data: string, callback?: () => void) => void;
+  close: (code?: number) => void;
+  terminate: () => void;
+}
+
+/**
+ * Runs the bridge's half of the exchange on one `/ws/hello` socket: answers the dashboard's nonce with the bridge's own and a proof, checks the dashboard's proof, and on success sends one ticket and closes. Any other message, a message of the wrong form, a wrong proof, a secret that was replaced meanwhile or silence past the timeout closes the socket with the same status and no explanation.
+ */
+export function serveHello(
+  socket: Readonly<HelloSocket>,
+  options: Readonly<HelloOptions>,
+): void {
+  let stage: "hello" | "auth" | "done" = "hello";
+  let exchange:
+    | {
+        secret: string;
+        clientNonce: string;
+        bridgeNonce: string;
+        generation: number;
+      }
+    | undefined;
+
+  const timer: { handle?: NodeJS.Timeout } = {};
+  const refuse = (): void => {
+    stage = "done";
+    clearTimeout(timer.handle);
+    socket.close(CLOSE_POLICY_VIOLATION);
+  };
+  timer.handle = setTimeout(refuse, options.timeoutMs ?? HELLO_TIMEOUT_MS);
+  timer.handle.unref();
+  socket.on("close", () => {
+    stage = "done";
+    clearTimeout(timer.handle);
+  });
+  // A socket error is that connection's alone; the close that follows ends the exchange.
+  socket.on("error", () => {
+    socket.terminate();
+  });
+
+  socket.on("message", (data, isBinary) => {
+    if (isBinary || stage === "done") {
+      refuse();
+      return;
+    }
+    const message = parseHelloMessage(textOf(data));
+    if (stage === "hello") {
+      if (!isHelloRequest(message)) {
+        refuse();
+        return;
+      }
+      const secret = options.secret.current();
+      const bridgeNonce = newNonce();
+      const port = options.port();
+      exchange = {
+        secret,
+        clientNonce: message.nonce,
+        bridgeNonce,
+        generation: options.secret.generation(),
+      };
+      const reply: HelloReply = {
+        type: "hello-ok",
+        nonce: bridgeNonce,
+        proof: computeProof(secret, {
+          role: "bridge",
+          clientNonce: message.nonce,
+          bridgeNonce,
+          port,
+        }),
+      };
+      stage = "auth";
+      socket.send(JSON.stringify(reply));
+      return;
+    }
+    if (!isHelloAuth(message) || exchange === undefined) {
+      refuse();
+      return;
+    }
+    const { secret, clientNonce, bridgeNonce, generation } = exchange;
+    const proven = proofMatches(message.proof, secret, {
+      role: "client",
+      clientNonce,
+      bridgeNonce,
+      port: options.port(),
+    });
+    options.secret.current();
+    if (!proven || options.secret.generation() !== generation) {
+      refuse();
+      return;
+    }
+    const ticket = options.tickets.issue();
+    if (ticket === undefined) {
+      refuse();
+      return;
+    }
+    stage = "done";
+    clearTimeout(timer.handle);
+    const reply: HelloTicket = { type: "ticket", ticket };
+    socket.send(JSON.stringify(reply), () => {
+      socket.close(CLOSE_NORMAL);
+    });
+  });
+}
+
+/** How often the server looks for sockets admitted under a secret that has been replaced, as a backstop to the watch on the secret file: a file system need not report every change, and the watch can fail to start. A rotation is otherwise acted on at once. */
+export const ROTATION_SWEEP_MS = 1000;
+
+/** WebSocket close code a socket gets when the secret it was admitted under is gone. */
+const CLOSE_REVOKED = 1008;
+
+/** The parts of a `ws` socket the guard uses. */
+export interface AdmittedSocket {
+  close: (code?: number) => void;
+  on: (event: "close", listener: () => void) => unknown;
+}
+
+/** Tracks the mesh sockets admitted to the hosted dashboard, so that replacing the secret ends them. */
+export interface HostedSocketGuard {
+  /** Starts tracking a socket admitted under the secret now in force, and ends it when that secret is replaced. */
+  track: (socket: Readonly<AdmittedSocket>) => void;
+  /** Whether the socket is still admitted; closes it and answers false when its secret has been replaced. */
+  check: (socket: Readonly<AdmittedSocket>) => boolean;
+  /** Closes every tracked socket whose secret has been replaced. Run on a timer, so an idle socket ends too. */
+  sweep: () => void;
+}
+
+export function createHostedSocketGuard(
+  secret: Readonly<PairingSecretStore>,
+): HostedSocketGuard {
+  const admitted = new Map<AdmittedSocket, number>();
+  const revoked = (generation: number): boolean => {
+    secret.current();
+    return secret.generation() !== generation;
+  };
+  const check = (socket: Readonly<AdmittedSocket>): boolean => {
+    const generation = admitted.get(socket);
+    if (generation === undefined) return true;
+    if (!revoked(generation)) return true;
+    admitted.delete(socket);
+    socket.close(CLOSE_REVOKED);
+    return false;
+  };
+  return {
+    track: (socket) => {
+      secret.current();
+      admitted.set(socket, secret.generation());
+      socket.on("close", () => {
+        admitted.delete(socket);
+      });
+    },
+    check,
+    sweep: () => {
+      for (const socket of [...admitted.keys()]) check(socket);
+    },
+  };
+}