agent-comms 8.15.8 → 8.15.10

package/src/core/relay-selection.ts

@@ -0,0 +1,120 @@
+/**
+ * Relay selection (agent-comms#342): which relay a store's one hub session is held over. The hub is a set rather than a single URL: every relay offer this store has heard (wire-mesh-core's relay-offer gossip extension) plus the configured public hub, ranked by a fixed policy.
+ *
+ * A direct connection always comes first, and needs nothing here: MeshTransport.sendRoomRequest reaches a device over its direct session whenever one exists and only falls back to the hub session for a device it has no session with. Among relays the order is: a relay served on this machine (offered by a peer this store holds a machine-local session with), then a relay on the local network (a trusted device offering a private or link-local address), then any trusted relay-offering device, then the configured public hub as the fallback.
+ *
+ * Trust stays deny-by-default: an offer from a device reached only through a hub is considered only when gateway trust admits that device (by id, or through a principal it proves membership of), exactly the check that already decides whether a hub-learned device is reachable at all. A machine-local peer's offer needs no separate trust decision, since that peer is already a full member of this store's local mesh. Relay payloads stay end-to-end encrypted between the two devices using it, so trusting a relay is a decision about availability and metadata, never content. A relay forwards between its own directly connected clients, one hop; nothing here routes through a chain of relays.
+ */
+
+import { BlockList, isIPv4, isIPv6 } from "node:net";
+
+/** A relay offer this store has heard, with what it knows about the device making it. */
+export interface RelayOffer {
+  deviceHex: string;
+  /** The ws:// or wss:// URLs the device offers relay service at. */
+  addresses: readonly string[];
+  /** Whether this store holds a machine-local session with the offering device. */
+  machineLocal: boolean;
+}
+
+/** Which tier of the policy a selected relay came from, most preferred first. */
+export type RelayTier = "machine" | "lan" | "trusted" | "public";
+
+export interface SelectedRelay {
+  url: string;
+  tier: RelayTier;
+  /** The offering device, absent for the configured public hub. */
+  deviceHex?: string;
+}
+
+export interface RelaySelectionInput {
+  offers: readonly RelayOffer[];
+  /** Gateway trust's reachability check for a device learned only through a hub. */
+  isTrusted: (deviceHex: string) => boolean;
+  /** This store's own device-id: it never relays through its own offer. */
+  ownDeviceHex: string;
+  /** The configured public hub, the fallback when no offer qualifies. */
+  publicHubUrl: string;
+}
+
+/** The private (RFC 1918), IPv4 link-local (RFC 3927), IPv6 unique-local (RFC 4193) and IPv6 link-local ranges: addresses reachable on the local network and nowhere else. */
+const LOCAL_NETWORK_RANGES = new BlockList();
+LOCAL_NETWORK_RANGES.addRange("10.0.0.0", "10.255.255.255", "ipv4");
+LOCAL_NETWORK_RANGES.addRange("172.16.0.0", "172.31.255.255", "ipv4");
+LOCAL_NETWORK_RANGES.addRange("192.168.0.0", "192.168.255.255", "ipv4");
+LOCAL_NETWORK_RANGES.addRange("169.254.0.0", "169.254.255.255", "ipv4");
+LOCAL_NETWORK_RANGES.addRange(
+  "fc00::",
+  "fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff",
+  "ipv6",
+);
+LOCAL_NETWORK_RANGES.addRange(
+  "fe80::",
+  "febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff",
+  "ipv6",
+);
+
+/** Whether a host names a loopback address, which only reaches a relay on this machine. */
+function isLoopbackHost(host: string): boolean {
+  return host === "localhost" || host === "::1" || host.startsWith("127.");
+}
+
+/** Whether a host literal is a private or link-local address: reachable on the local network and nowhere else. A host name is neither, since what it resolves to is not known here. */
+function isPrivateHost(host: string): boolean {
+  if (isIPv4(host)) return LOCAL_NETWORK_RANGES.check(host, "ipv4");
+  if (isIPv6(host)) return LOCAL_NETWORK_RANGES.check(host, "ipv6");
+  return false;
+}
+
+/** The host a relay URL names, or undefined for an address that is not a ws:// or wss:// URL (which is never dialled). */
+function relayHost(address: string): string | undefined {
+  if (!/^wss?:\/\//.test(address)) return undefined;
+  try {
+    // URL keeps an IPv6 literal's brackets in hostname; strip them so isIP recognises it.
+    return new URL(address).hostname.replace(/^\[(.*)\]$/, "$1");
+  } catch {
+    return undefined;
+  }
+}
+
+/** The best address an offer has for a tier, or undefined when it has none that tier accepts. */
+function addressFor(
+  offer: Readonly<RelayOffer>,
+  tier: RelayTier,
+): string | undefined {
+  for (const address of offer.addresses) {
+    const host = relayHost(address);
+    if (host === undefined) continue;
+    if (tier === "machine" && isLoopbackHost(host)) return address;
+    if (tier === "lan" && isPrivateHost(host)) return address;
+    if (tier === "trusted" && !isLoopbackHost(host)) return address;
+  }
+  return undefined;
+}
+
+const OFFER_TIERS: readonly Exclude<RelayTier, "public">[] = [
+  "machine",
+  "lan",
+  "trusted",
+];
+
+/** Picks the relay to hold this store's hub session over. Within a tier the lowest device-id wins, so every store that hears the same offers makes the same choice. */
+export function selectRelay(
+  input: Readonly<RelaySelectionInput>,
+): SelectedRelay {
+  const eligible = input.offers
+    .filter((offer) => offer.deviceHex !== input.ownDeviceHex)
+    .toSorted((a, b) => a.deviceHex.localeCompare(b.deviceHex));
+  for (const tier of OFFER_TIERS) {
+    for (const offer of eligible) {
+      const admitted =
+        tier === "machine"
+          ? offer.machineLocal
+          : input.isTrusted(offer.deviceHex);
+      if (!admitted) continue;
+      const url = addressFor(offer, tier);
+      if (url !== undefined) return { url, tier, deviceHex: offer.deviceHex };
+    }
+  }
+  return { url: input.publicHubUrl, tier: "public" };
+}

package/src/core/relay-server.ts

@@ -0,0 +1,198 @@
+/**
+ * RelayServer: the relay role a bridge serves to its machine and local network (agent-comms#342), wire-mesh-core's transport-agnostic relay-hub domain logic (the same createRelayHub the public hub runs) behind a WebSocket listener. It forwards between its own directly connected clients and, when given an uplink, carries them over it to the upstream hub and back (attachUplink), so a device on the upstream hub and a client of this relay reach each other with each end's own device-id intact. It never routes beyond that: relay payloads are end-to-end encrypted between the two devices using it, so what the relay learns is who talks to whom, never what they say.
+ *
+ * Admission is deny-by-default, like every other cross-machine decision here: a connection is registered with the hub only once it gossips an advert for a device isAdmitted accepts, and every gossiped advert naming a device it does not accept is dropped before the hub sees it. A connection that never gossips an admitted device can neither be named by a relay-connect nor relay anything, and learns nothing, since the hub's catch-up is sent only in answer to a registered connection's gossip.
+ */
+
+import { createServer, type Server } from "node:http";
+import * as os from "node:os";
+import { WebSocketServer } from "ws";
+import { createRelayHub, type RelayHub } from "wire-mesh-core/domain/relay-hub";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import {
+  deriveDeviceId,
+  verifyWithPublicKey,
+} from "wire-mesh-core/adapters/node-identity";
+import type { Frame } from "wire-mesh-core/generated/protocol";
+import type { Connection } from "wire-mesh-core/ports/transport";
+import { wrapWsSocket } from "./ws-dial.js";
+import { createUplink, type UplinkFeed } from "./relay-uplink.js";
+
+/** The wildcard IPv4 address: listening on it serves every interface, loopback and the local network alike. */
+export const ALL_INTERFACES_HOST = "0.0.0.0";
+
+/** The loopback address every relay also offers, so a peer on the same machine reaches it without leaving the host. */
+const LOOPBACK_HOST = "127.0.0.1";
+
+export interface RelayServerOptions {
+  /** The interface to listen on: ALL_INTERFACES_HOST to serve the local network, or a single address (a test serves loopback only). */
+  host: string;
+  /** Whether a device (hex) may use this relay. */
+  isAdmitted: (deviceHex: string) => boolean;
+  /** Reports a failure of the uplink, which is otherwise detached from any caller. */
+  onError: (error: Error) => void;
+}
+
+export class RelayServer {
+  private readonly hub: RelayHub = createRelayHub({
+    identity: { verify: verifyWithPublicKey, deriveDeviceId },
+  });
+  /** The devices (hex) each connected client has registered, so an advert for one of them arriving from upstream never displaces the client's own registration. */
+  private readonly clientDevices = new Map<Readonly<Connection>, Set<string>>();
+  private readonly http: Server = createServer();
+  private readonly wss = new WebSocketServer({ server: this.http });
+  private port = 0;
+  /** Settles once the previous uplink has been forgotten by the hub, which refuses a second while one is attached. */
+  private uplinkDone: Promise<void> = Promise.resolve();
+
+  constructor(private readonly options: Readonly<RelayServerOptions>) {
+    this.wss.on("connection", (socket) => {
+      socket.binaryType = "arraybuffer";
+      void this.serve(wrapWsSocket(socket));
+    });
+  }
+
+  /** Binds an OS-assigned port and resolves once listening. */
+  async start(): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      this.http.once("error", reject);
+      this.http.listen(0, this.options.host, () => {
+        this.http.off("error", reject);
+        resolve();
+      });
+    });
+    const address = this.http.address();
+    if (address === null || typeof address === "string") {
+      throw new Error("RelayServer: expected a TCP listen address");
+    }
+    this.port = address.port;
+    // Never what keeps a process alive: the bridge that serves the relay decides when it exits.
+    this.http.unref();
+  }
+
+  /** Takes the connection to the upstream hub as this relay's uplink (wire-mesh-core's relay-hub fronting, wire-mesh#311): the clients registered here become reachable through the upstream hub and can reach the devices registered there, each end keeping its own device-id. The upstream connection belongs to the caller's own session, so the frames it reads are fed in through the returned feed, and ending the feed detaches the uplink. */
+  attachUplink(upstream: Readonly<Connection>): UplinkFeed {
+    const uplink = createUplink(upstream);
+    this.uplinkDone = this.uplinkDone
+      .then(async () => this.hub.handleUplink(uplink.connection))
+      .catch((error: unknown) => {
+        this.options.onError(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      });
+    return {
+      feed: (frame) => {
+        const local = this.withoutClientDevices(frame);
+        if (local !== undefined) uplink.feed.feed(local);
+      },
+      end: () => {
+        uplink.feed.end();
+      },
+    };
+  }
+
+  /** The URLs this relay is reachable at, for its relay offer: loopback always, and each external IPv4 interface too when it listens on every interface. */
+  addresses(): string[] {
+    const hosts =
+      this.options.host === ALL_INTERFACES_HOST
+        ? [LOOPBACK_HOST, ...externalIpv4Addresses()]
+        : [this.options.host];
+    return hosts.map((host) => `ws://${host}:${String(this.port)}/`);
+  }
+
+  /** How many clients are connected, admitted or not. */
+  connectionCount(): number {
+    return this.wss.clients.size;
+  }
+
+  /** How many clients the hub can route to: those whose advert it has accepted. A client that has only just connected is not one until it gossips an advert the hub takes over any fresher one it already holds for that device, which a device moving here from another hub within the same second does not do until its next gossip. */
+  routableClientCount(): number {
+    let routable = 0;
+    for (const connection of this.clientDevices.keys()) {
+      if (this.hub.exportConnection(connection) !== undefined) routable += 1;
+    }
+    return routable;
+  }
+
+  /** Closes every client and the listener. */
+  async stop(): Promise<void> {
+    this.hub.stop();
+    for (const client of this.wss.clients) client.terminate();
+    await new Promise<void>((resolve) => {
+      this.wss.close(() => {
+        resolve();
+      });
+    });
+    await new Promise<void>((resolve) => {
+      this.http.close(() => {
+        resolve();
+      });
+    });
+  }
+
+  /** Drives one connection: filters its gossip to admitted devices, registers it with the hub on its first admitted advert, and hands the hub every frame from then on. */
+  private async serve(connection: Readonly<Connection>): Promise<void> {
+    let registered = false;
+    const devices = new Set<string>();
+    this.clientDevices.set(connection, devices);
+    try {
+      for await (const frame of connection.receive()) {
+        const admitted = this.admit(frame);
+        if (admitted?.type === "gossip") {
+          for (const advert of admitted.peers) {
+            devices.add(deviceIdToHex(advert.device));
+          }
+        }
+        if (admitted === undefined) continue;
+        if (!registered) {
+          if (admitted.type !== "gossip") continue;
+          this.hub.registerConnection(connection);
+          registered = true;
+        }
+        await this.hub.onFrame(connection, admitted);
+      }
+    } catch {
+      // A connection that fails mid-stream is simply gone; its registration is cleaned up below.
+    } finally {
+      this.clientDevices.delete(connection);
+      if (registered) this.hub.onDisconnect(connection);
+    }
+  }
+
+  /** The frame from upstream without the adverts of devices a client of this relay has registered, or undefined when nothing is left of it. An advert that came back round through the upstream hub would otherwise displace the client's own registration whenever it was the fresher, and a relay-connect naming the client would then find no route to it. */
+  private withoutClientDevices(frame: Readonly<Frame>): Frame | undefined {
+    if (frame.type !== "gossip") return frame;
+    const peers = frame.peers.filter((advert) => {
+      const deviceHex = deviceIdToHex(advert.device);
+      for (const devices of this.clientDevices.values()) {
+        if (devices.has(deviceHex)) return false;
+      }
+      return true;
+    });
+    if (peers.length === 0) return undefined;
+    return { ...frame, peers };
+  }
+
+  /** The frame to pass on, or undefined to drop it: gossip keeps only admitted adverts, and nothing else passes before the connection has gossiped one. */
+  private admit(frame: Frame): Frame | undefined {
+    if (frame.type !== "gossip") return frame;
+    const peers = frame.peers.filter((advert) =>
+      this.options.isAdmitted(deviceIdToHex(advert.device)),
+    );
+    if (peers.length === 0) return undefined;
+    return { ...frame, peers };
+  }
+}
+
+function externalIpv4Addresses(): string[] {
+  const result: string[] = [];
+  for (const addresses of Object.values(os.networkInterfaces())) {
+    if (addresses === undefined) continue;
+    for (const address of addresses) {
+      if (address.family === "IPv4" && !address.internal) {
+        result.push(address.address);
+      }
+    }
+  }
+  return result;
+}

package/src/core/relay-uplink.ts

@@ -0,0 +1,78 @@
+/**
+ * The connection a relay hub takes to its upstream hub as its uplink (agent-comms#342), built over a hub session that already owns that connection.
+ *
+ * A HubSession drives the connection to the public hub through wire-mesh-core's session, whose own receive loop is the one consumer of the connection's frames. The relay hub's handleUplink needs a frame stream of its own, so the session's per-frame observer feeds each frame it reads into this uplink as well, and sends from the hub go out over the same underlying connection. Closing the uplink ends the stream the hub reads and leaves the underlying connection to the session that owns it.
+ */
+
+import type { Frame } from "wire-mesh-core/generated/protocol";
+import type { Connection } from "wire-mesh-core/ports/transport";
+
+/** What the owner of the upstream connection drives: each frame it reads from upstream, and the end of the connection. */
+export interface UplinkFeed {
+  /** Hands the hub one frame read from upstream. Ignored once the uplink has ended. */
+  feed: (frame: Readonly<Frame>) => void;
+  /** Ends the stream the hub reads, which makes it forget the uplink. Idempotent. */
+  end: () => void;
+}
+
+export interface Uplink {
+  /** The connection handed to the relay hub's handleUplink. */
+  connection: Connection;
+  feed: UplinkFeed;
+}
+
+/** Builds the uplink over an upstream connection some other session owns: sends go to it directly, receives come from what the owner feeds in. */
+export function createUplink(upstream: Readonly<Connection>): Uplink {
+  const backlog: Frame[] = [];
+  const waiters: ((result: IteratorResult<Frame>) => void)[] = [];
+  let ended = false;
+
+  const feed: UplinkFeed = {
+    feed(frame) {
+      if (ended) return;
+      const waiter = waiters.shift();
+      if (waiter === undefined) {
+        backlog.push(frame);
+      } else {
+        waiter({ value: frame, done: false });
+      }
+    },
+    end() {
+      if (ended) return;
+      ended = true;
+      for (const waiter of waiters.splice(0)) {
+        waiter({ value: undefined, done: true });
+      }
+    },
+  };
+
+  const stream: AsyncIterable<Frame> = {
+    [Symbol.asyncIterator]() {
+      return {
+        next: async (): Promise<IteratorResult<Frame>> =>
+          new Promise((resolve) => {
+            const next = backlog.shift();
+            if (next !== undefined) {
+              resolve({ value: next, done: false });
+            } else if (ended) {
+              resolve({ value: undefined, done: true });
+            } else {
+              waiters.push(resolve);
+            }
+          }),
+      };
+    },
+  };
+
+  return {
+    connection: {
+      send: async (frame) => upstream.send(frame),
+      receive: () => stream,
+      close: async () => {
+        feed.end();
+        return Promise.resolve();
+      },
+    },
+    feed,
+  };
+}

package/src/core/request-timeouts.ts

@@ -0,0 +1,37 @@
+/**
+ * Deadlines for manage-requests sent to another device. A request that waits on a human decision needs a far longer window than one answered by code, and every request needs some bound: wire-mesh-core waits forever for a response unless it is given a timeout.
+ */
+
+import type { ManageCommand } from "wire-mesh-core/generated/protocol";
+
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+
+const ROOM_REQUEST_TIMEOUT_SECONDS = 15;
+/** How long a request answered by code (room.send, room.read, room.members, ...) may take before the sender gives up. */
+export const ROOM_REQUEST_TIMEOUT_MS =
+  ROOM_REQUEST_TIMEOUT_SECONDS * MS_PER_SECOND;
+
+const ROOM_JOIN_APPROVAL_TIMEOUT_MINUTES = 5;
+/** How long a room.join (which includes a first-contact DM request) may sit awaiting a human decision before the receiving side expires it. Generous on purpose: this bounds a human approval window, not a network timeout, the same reasoning that gives a connect_request its own five minutes. */
+export const ROOM_JOIN_APPROVAL_TIMEOUT_MS =
+  ROOM_JOIN_APPROVAL_TIMEOUT_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+const APPROVAL_RESPONSE_GRACE_SECONDS = 10;
+/** Extra time the requester waits beyond the receiver's approval window, so the receiver's own definitive timeout answer is normally the one the requester sees. The requester's deadline is the backstop for a receiver that never answers at all, such as one running a version without the expiry. */
+export const APPROVAL_RESPONSE_GRACE_MS =
+  APPROVAL_RESPONSE_GRACE_SECONDS * MS_PER_SECOND;
+
+/** The room verb whose response is a human's accept or reject decision. */
+const ROOM_JOIN_VERB = "room.join";
+
+/** The deadline the sender should give this request. A room.join waits on a human, so it gets the receiver's approval window plus the response grace; every other request gets the short network deadline. */
+export function manageRequestTimeoutMs(
+  command: Readonly<ManageCommand>,
+  approvalWindowMs: number,
+): number {
+  const waitsOnHuman = command.params.verb === ROOM_JOIN_VERB;
+  return waitsOnHuman
+    ? approvalWindowMs + APPROVAL_RESPONSE_GRACE_MS
+    : ROOM_REQUEST_TIMEOUT_MS;
+}

package/src/core/room-discovery.ts

@@ -0,0 +1,48 @@
+/**
+ * Reads the rooms other devices advertise as hosted from the transport's gossip aggregation -- the one source of room discovery that list_rooms and bare-name room resolution (room-lookup.ts) both need to agree on.
+ */
+
+import { HOSTED_ROOMS_GOSSIP_KEY } from "./gossip-extensions.js";
+import type { ReceivedHostedRoomAdvert } from "./gossip-extensions.js";
+import type { MeshTransport } from "./transport.js";
+
+/** A hosted room together with the device that advertised it. */
+export type DiscoveredRoom = ReceivedHostedRoomAdvert & {
+  ownerDeviceId: string;
+};
+
+/** Narrows an untrusted gossiped value (a peer's own self-asserted `room/hosted` entry) into a ReceivedHostedRoomAdvert. A malformed or non-conforming entry is skipped by the caller rather than treated as an error: this is a discovery hint over self-asserted data, not a security check. */
+export function isHostedRoomAdvert(
+  value: unknown,
+): value is ReceivedHostedRoomAdvert {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("path" in value) || typeof value.path !== "string") return false;
+  if (!("name" in value) || typeof value.name !== "string") return false;
+  if (
+    !("type" in value) ||
+    (value.type !== "public" && value.type !== "private")
+  )
+    return false;
+  if ("description" in value && typeof value.description !== "string")
+    return false;
+  return true;
+}
+
+/**
+ * Every public/private room another device has gossiped as hosted, each tagged with the advertising device. Empty for a transport with no `listKnownDevices` capability (WireMeshTransport is the only implementation that has one). Secret rooms never appear: HostedRoomAdvert's own type field excludes them at the source, so a secret room is never gossiped under this key at all.
+ */
+export function listDiscoveredRooms(
+  transport: Readonly<MeshTransport>,
+): readonly DiscoveredRoom[] {
+  if (transport.listKnownDevices === undefined) return [];
+  const result: DiscoveredRoom[] = [];
+  for (const { deviceId, advert } of transport.listKnownDevices()) {
+    const hosted = advert[HOSTED_ROOMS_GOSSIP_KEY];
+    if (!Array.isArray(hosted)) continue;
+    for (const candidate of hosted) {
+      if (!isHostedRoomAdvert(candidate)) continue;
+      result.push({ ...candidate, ownerDeviceId: deviceId });
+    }
+  }
+  return result;
+}