agent-comms 8.15.9 → 8.15.11

package/src/core/petnames.ts

@@ -0,0 +1,121 @@
+/**
+ * Petnames (agent-comms#345): the viewer's own labels for device-ids, the third naming tier beside a subject's self-asserted name and the short id. A petname lives only in the viewer's own storage and is never gossiped, never put in an advert and never sent to a peer, which is why it needs no trust decision and has no collision problem: it is nobody's claim but yours.
+ *
+ * Constructed with an identity location, the map is one JSON file per identity directory (~/.agent-comms/petnames.json by default), shared by every bridge the viewer runs on the machine, like the gateway trust file, and read afresh on every call, so a label set in one bridge is seen by the others at once. Without a location it is in memory only, which is what most tests use.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  resolveDataDir,
+  type DataDirectoryLocation,
+} from "./data-directory.js";
+import { writeFileAtomic } from "./atomic-file.js";
+import { parseDisplayName } from "./display-name.js";
+import { isDeviceIdHex } from "./room-path.js";
+import { CommsError, requireDisplayName } from "./store.js";
+
+/** Owner-only read and write: what a person calls their contacts is theirs. */
+const PETNAMES_FILE_MODE = 0o600;
+/** Owner-only directory, matching identity-store.ts's own base directory. */
+const PETNAMES_DIR_MODE = 0o700;
+
+export interface PetnamesLocation extends DataDirectoryLocation {
+  /** Directory override; defaults to ~/.agent-comms. */
+  dir?: string | undefined;
+}
+
+/** Narrows a caught value to Node's own errno-carrying Error subtype, so ENOENT can be told apart from every other read failure without an `as` assertion. */
+function isErrnoException(value: unknown): value is NodeJS.ErrnoException {
+  return value instanceof Error && "code" in value;
+}
+
+/** The labels in a parsed petnames file: every entry keyed by a full device-id whose label parseDisplayName accepts, stored as it returns it. Any other entry (a hand-edited typo, a damaged value) is left out on its own, so it never costs the valid labels beside it. Throws when the file's top level is not a JSON object, since then no entry in it can be read at all. */
+function labelsIn(file: string, parsed: unknown): Map<string, string> {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${file} does not hold a JSON object of petnames`);
+  }
+  const labels = new Map<string, string>();
+  for (const [device, raw] of Object.entries(parsed)) {
+    if (!isDeviceIdHex(device) || typeof raw !== "string") continue;
+    const label = parseDisplayName(raw);
+    if (label !== undefined) labels.set(device, label);
+  }
+  return labels;
+}
+
+export class Petnames {
+  private readonly file: string | undefined;
+  private readonly memory = new Map<string, string>();
+
+  constructor(location?: Readonly<PetnamesLocation>) {
+    this.file =
+      location === undefined
+        ? undefined
+        : path.join(
+            resolveDataDir({ dir: location.dataDir ?? location.dir }),
+            "petnames.json",
+          );
+  }
+
+  /** Every label the viewer has set, keyed by lowercase device-id. A missing file means nothing is labelled yet. An entry that is not a usable label for a full device-id is left out (labelsIn). Throws when the file exists but cannot be read or is not a JSON object, rather than treating it as empty, since the next set or clear would then write that empty map over every label in it. */
+  list(): Map<string, string> {
+    if (this.file === undefined) return new Map(this.memory);
+    let raw: string;
+    try {
+      raw = fs.readFileSync(this.file, "utf-8");
+    } catch (err) {
+      if (isErrnoException(err) && err.code === "ENOENT") return new Map();
+      throw err;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`${this.file} is not valid JSON`, { cause: err });
+    }
+    return labelsIn(this.file, parsed);
+  }
+
+  /** Labels deviceHex (a full device-id, hex, case-insensitive) as name, replacing any earlier label. Throws INVALID_DEVICE for anything but a full device-id, since a label keyed by a typo or a short id would apply to nothing, and INVALID_NAME for a name parseDisplayName refuses. Returns the label as stored. */
+  set(deviceHex: string, name: string): string {
+    const device = deviceHex.toLowerCase();
+    if (!isDeviceIdHex(device)) {
+      throw new CommsError(
+        `${JSON.stringify(deviceHex)} is not a device-id: pass the full 64-character hex id.`,
+        "INVALID_DEVICE",
+      );
+    }
+    const label = requireDisplayName(name, "A petname");
+    const labels = this.list();
+    labels.set(device, label);
+    this.save(labels);
+    return label;
+  }
+
+  /** Removes deviceHex's label. Returns whether there was one. */
+  clear(deviceHex: string): boolean {
+    const labels = this.list();
+    const removed = labels.delete(deviceHex.toLowerCase());
+    if (removed) this.save(labels);
+    return removed;
+  }
+
+  private save(labels: ReadonlyMap<string, string>): void {
+    if (this.file === undefined) {
+      this.memory.clear();
+      for (const [device, label] of labels) this.memory.set(device, label);
+      return;
+    }
+    fs.mkdirSync(path.dirname(this.file), {
+      recursive: true,
+      mode: PETNAMES_DIR_MODE,
+    });
+    // Atomic, so a bridge reading concurrently sees the old map or the new one, never a partial file.
+    writeFileAtomic(
+      this.file,
+      `${JSON.stringify(Object.fromEntries(labels), null, 2)}\n`,
+      PETNAMES_FILE_MODE,
+    );
+  }
+}

package/src/core/pgp-keyserver.ts

@@ -0,0 +1,32 @@
+/**
+ * Fetches an armored OpenPGP public key from keys.openpgp.org's Verifying Key Server (VKS) HTTPS API by exact fingerprint (agent-comms#188) -- the convenience path a connection-code redeemer takes when they know the signer's fingerprint but weren't handed the armored key block directly.
+ *
+ * The keyserver is never a trust anchor here: the fingerprint the caller supplies is already the thing they independently trust (per connection-code.ts's own doc comment), and this function's only job is turning that fingerprint into bytes. It does not, by itself, prove the fetched key actually has that fingerprint -- ConnectionCodeLedger.redeem's own expectedFingerprint check (comparing the openpgp-computed fingerprint of whatever key actually verifies the signature against what the caller asked for) is what defends against a compromised or buggy keyserver returning the wrong key; this function only saves the caller a manual copy-paste when they already know the fingerprint but not the key text.
+ */
+
+const KEYSERVER_BASE_URL = "https://keys.openpgp.org/vks/v1/by-fingerprint";
+
+/** The minimal fetch shape this module actually calls -- a single URL argument returning a Response -- rather than the full `typeof fetch` (which also carries a `preconnect` static and an overload taking a Request/init object neither caller nor test needs), so a test's fake implementation isn't forced to shim unrelated fetch surface it never exercises. */
+export type FetchLike = (url: string) => Promise<Response>;
+
+/** Strips whitespace/colons and uppercases a fingerprint for the keyserver's own URL path convention -- mirrors connection-code.ts's normalizeFingerprint, kept separate since that one lowercases for comparison rather than uppercasing for a URL. */
+function toKeyserverPathSegment(fingerprint: string): string {
+  return fingerprint.replace(/[\s:]+/g, "").toUpperCase();
+}
+
+/**
+ * Fetches the armored public key for `fingerprint` from keys.openpgp.org. Throws if the lookup fails (not found, network error, non-2xx response) -- there is no fallback value, since a caller who asked for this fingerprint by name needs to know definitively whether it was found, not silently proceed with nothing.
+ */
+export async function fetchPgpPublicKeyByFingerprint(
+  fingerprint: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<string> {
+  const segment = toKeyserverPathSegment(fingerprint);
+  const response = await fetchImpl(`${KEYSERVER_BASE_URL}/${segment}`);
+  if (!response.ok) {
+    throw new Error(
+      `Keyserver lookup for fingerprint ${segment} failed: HTTP ${String(response.status)}`,
+    );
+  }
+  return await response.text();
+}

package/src/core/pid-lock-file.ts

@@ -0,0 +1,122 @@
+/**
+ * A lock file holding the PID of the process that claimed it: the exclusivity guard for a bridge's identity slot (identity-store.ts) and for appends to the machine's account ledger (ledger-lock.ts). A lock whose recorded process has died is stale and may be taken over, so a holder that crashed never wedges the lock.
+ *
+ * Every claim writes the PID plus a random nonce, so two claims never leave identical content even when a PID is reused. Removing a stale lock is the one step that could delete a newer, live claim by mistake (the stale file can be released and re-claimed between reading it and removing it), so it happens only under a second, takeover lock file, and only when the lock still holds exactly the content that was read and judged stale. A live holder releasing its own lock never needs the takeover lock: only its own claim can be at that name while it holds it.
+ */
+
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+
+/** Random bytes in each claim's content, enough that two claims never collide. */
+const CLAIM_NONCE_BYTES = 16;
+
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readLockContent(lockFile: string): string | undefined {
+  try {
+    return fs.readFileSync(lockFile, "utf-8");
+  } catch (err) {
+    if (isErrorCode(err, "ENOENT")) return undefined;
+    throw err;
+  }
+}
+
+function pidOf(content: string): number | undefined {
+  const pid = Number.parseInt(content.trim(), 10);
+  return Number.isInteger(pid) ? pid : undefined;
+}
+
+/** Read the PID holding the lock, or undefined when absent or unreadable. */
+export function readLockPid(lockFile: string): number | undefined {
+  const content = readLockContent(lockFile);
+  return content === undefined ? undefined : pidOf(content);
+}
+
+function isErrorCode(err: unknown, code: string): boolean {
+  if (!(err instanceof Error) || !("code" in err)) return false;
+  return err.code === code;
+}
+
+/**
+ * Atomically claims `file` for this process via write-temp-then-hardlink: link() is POSIX-guaranteed atomic and exclusive (it fails with EEXIST if the target name already exists), and because the temp file's content is fully written before the link is created, the file's content can never be observed incomplete the instant its name exists, unlike a bare open(O_CREAT|O_EXCL) followed by a separate write(). Returns false when the name is already taken.
+ */
+function claimExclusive(file: string): boolean {
+  const tmpFile = `${file}.${String(process.pid)}.tmp`;
+  fs.writeFileSync(
+    tmpFile,
+    `${String(process.pid)}\n${randomBytes(CLAIM_NONCE_BYTES).toString("hex")}\n`,
+    "utf-8",
+  );
+  try {
+    fs.linkSync(tmpFile, file);
+    return true;
+  } catch (err) {
+    if (!isErrorCode(err, "EEXIST")) throw err;
+    return false;
+  } finally {
+    fs.rmSync(tmpFile, { force: true });
+  }
+}
+
+/** Whether content names a process that can no longer be holding the lock: one that has died, this process itself (which claims a lock only after releasing it, so a lock naming it is left over from before), or no readable PID at all. */
+function isStale(content: string): boolean {
+  const pid = pidOf(content);
+  return pid === undefined || pid === process.pid || !isPidAlive(pid);
+}
+
+/** Removes `file` if it still holds exactly `content`, the content a caller read and judged stale. Any newer claim has different content (each carries its own nonce), so it is left alone. */
+function removeIfUnchanged(file: string, content: string): void {
+  if (readLockContent(file) === content) fs.rmSync(file, { force: true });
+}
+
+/**
+ * Removes lockFile when it still holds `staleContent`, under the takeover lock so that no other process removes a stale lock at the same moment, which is what makes reading the content and removing the file one step. Returns false when another process holds the takeover lock: it is removing the same stale lock, and the caller retries afterwards. A takeover lock left behind by a process that died inside this function is itself removed the same way, without a takeover lock of its own, so two processes clearing that doubly crashed state at the same instant could both go on to remove lockFile; both would still see the same stale content there, so neither removes a live claim.
+ */
+function removeStaleLock(lockFile: string, staleContent: string): boolean {
+  const takeoverFile = `${lockFile}.takeover`;
+  if (!claimExclusive(takeoverFile)) {
+    const takeover = readLockContent(takeoverFile);
+    if (takeover !== undefined && isStale(takeover)) {
+      removeIfUnchanged(takeoverFile, takeover);
+    }
+    return false;
+  }
+  try {
+    removeIfUnchanged(lockFile, staleContent);
+    return true;
+  } finally {
+    fs.rmSync(takeoverFile, { force: true });
+  }
+}
+
+/**
+ * Attempts to claim lockFile for this process. Returns the current holder when a different live process holds it. A lock found missing after a failed claim was released in between, so it is claimed again rather than treated as stale; a stale lock (see isStale) is taken over only through removeStaleLock, so a claim another process made after the stale one was read is never deleted. Losing any of these races to another process reports that process as the holder.
+ */
+export function tryAcquireLock(
+  lockFile: string,
+): { acquired: true } | { acquired: false; heldBy: number | undefined } {
+  if (claimExclusive(lockFile)) return { acquired: true };
+  const content = readLockContent(lockFile);
+  if (content !== undefined && !isStale(content)) {
+    return { acquired: false, heldBy: pidOf(content) };
+  }
+  if (content !== undefined && !removeStaleLock(lockFile, content)) {
+    return { acquired: false, heldBy: readLockPid(lockFile) };
+  }
+  if (claimExclusive(lockFile)) return { acquired: true };
+  return { acquired: false, heldBy: readLockPid(lockFile) };
+}
+
+/** Removes lockFile if this process holds it; a lock another PID has since taken over is left alone. The release half of tryAcquireLock. */
+export function releaseLockFile(lockFile: string): void {
+  if (readLockPid(lockFile) === process.pid) {
+    fs.rmSync(lockFile, { force: true });
+  }
+}

package/src/core/push-manager.ts

@@ -0,0 +1,76 @@
+/**
+ * Push subscription manager — tracks browser push subscriptions and
+ * dispatches Web Push notifications when agents are offline.
+ *
+ * The PushManager is a standalone module — MeshStore doesn't know about it.
+ * The web server bridge checks whether the target agent's WebSocket is
+ * disconnected and falls back to push when a subscription exists.
+ */
+
+import type { VapidKeys } from "./vapid.js";
+import { generateVapidKeys } from "./vapid.js";
+import {
+  sendWebPush,
+  type PushSubscription,
+  type PushPayload,
+} from "./web-push.js";
+
+// ---------------------------------------------------------------------------
+// PushManager
+// ---------------------------------------------------------------------------
+
+export class PushManager {
+  private readonly vapidKeys: VapidKeys;
+  private readonly subject: string;
+  private readonly subscriptions = new Map<string, PushSubscription>();
+
+  constructor(subject = "mailto:agent-comms@localhost") {
+    this.vapidKeys = generateVapidKeys();
+    this.subject = subject;
+  }
+
+  /**
+   * Register a push subscription for a given agent ID.
+   * Overwrites any existing subscription for the same agent.
+   */
+  addSubscription(agentId: string, subscription: PushSubscription): void {
+    this.subscriptions.set(agentId, subscription);
+  }
+
+  /**
+   * Remove a push subscription.
+   */
+  removeSubscription(agentId: string): void {
+    this.subscriptions.delete(agentId);
+  }
+
+  /**
+   * Check whether a push subscription exists for the given agent.
+   */
+  hasSubscription(agentId: string): boolean {
+    return this.subscriptions.has(agentId);
+  }
+
+  /**
+   * Send a push notification to a subscribed agent.
+   *
+   * No-ops silently if no subscription exists — callers should check
+   * hasSubscription() first if they need to distinguish the two cases.
+   */
+  async sendPush(
+    agentId: string,
+    payload: Readonly<PushPayload>,
+  ): Promise<void> {
+    const subscription = this.subscriptions.get(agentId);
+    if (!subscription) return;
+
+    await sendWebPush(subscription, payload, this.vapidKeys, this.subject);
+  }
+
+  /**
+   * Get the VAPID public key for the PWA to use in `pushManager.subscribe()`.
+   */
+  getPublicKey(): string {
+    return this.vapidKeys.publicKey;
+  }
+}

package/src/core/random-id.ts

@@ -0,0 +1,9 @@
+/** 16 random bytes (128 bits) is the conventional size for an unguessable identifier, matching a UUIDv4's own random payload. */
+const RANDOM_ID_BYTE_LENGTH = 16;
+
+/** Generates a random identifier: several of core/room's own fields (token-id, message-id) are defined as an arbitrary-length bstr, and {@link RANDOM_ID_BYTE_LENGTH} random bytes is the conventional size for an unguessable identifier, matching a UUIDv4's own random payload. */
+export function randomId(): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(RANDOM_ID_BYTE_LENGTH);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}

package/src/core/receiver-set.ts

@@ -0,0 +1,42 @@
+/**
+ * ReceiverSet: the observers a MeshStore fans one of its events out to (agent-comms#293). A store has a single assignable callback per event (onDelivery, onPatch), so the bridge that owns the store and anything else serving from it, the web UI, would silence each other by assigning last. The callback keeps working, and a ReceiverSet adds any number of observers alongside it.
+ */
+
+/** A callback for an event whose payload is Args. */
+export type Receiver<Args extends unknown[]> = (
+  ...args: Args
+) => void | Promise<void>;
+
+export class ReceiverSet<Args extends unknown[]> {
+  private readonly receivers = new Set<Receiver<Args>>();
+
+  /** Adds an observer and returns a function that removes it. */
+  add(receiver: Receiver<Args>): () => void {
+    this.receivers.add(receiver);
+    return () => {
+      this.receivers.delete(receiver);
+    };
+  }
+
+  /**
+   * The single function to call for an event: the store's own assignable callback, when it has one, and then every observer, or undefined while there is neither, so a caller can still tell nobody is listening. A receiver that throws or rejects is passed to onError and does not stop the others.
+   */
+  handler(
+    primary: Receiver<Args> | undefined,
+    onError: (error: unknown) => void,
+  ): ((...args: Args) => Promise<void>) | undefined {
+    if (primary === undefined && this.receivers.size === 0) return undefined;
+    return async (...args) => {
+      const all = [
+        ...(primary !== undefined ? [primary] : []),
+        ...this.receivers,
+      ];
+      const outcomes = await Promise.allSettled(
+        all.map(async (receive) => receive(...args)),
+      );
+      for (const outcome of outcomes) {
+        if (outcome.status === "rejected") onError(outcome.reason);
+      }
+    };
+  }
+}

package/src/core/relay-role.ts

@@ -0,0 +1,182 @@
+/**
+ * RelayRole: one transport's part in the relay set (agent-comms#342), split out of wire-mesh-transport.ts to keep it under the repo's max-lines cap. It holds the store's one hub session over the relay selection prefers (relay-selection.ts), and serves the relay role itself while it is eligible and holds an upstream session.
+ *
+ * Who serves: the store holding the elected coordinator role (agent-comms#341), and only while its hub session is to the configured public hub, its uplink. Tying serving to that single-holder role is what keeps one relay per machine: if every store holding an upstream session served, each would see the others' offers, move its own session onto one of them, lose its uplink, stop serving, and fall back to the public hub, over and over. For the same reason an eligible store always holds its session to the public hub and never selects another relay, so relays never chain.
+ */
+
+import { readRelayOffer } from "wire-mesh-core/domain/relay-advert";
+import { HubLink } from "./hub-link.js";
+import type { HubSession } from "./hub-session.js";
+import type { KnownDevices } from "./gossip-directory.js";
+import type { ElectionSessions } from "./election-sessions.js";
+import type { GatewayTrustReader } from "./gateway-trust.js";
+import type { TransportEvents } from "./transport.js";
+import { RelayServer } from "./relay-server.js";
+import { selectRelay, type RelayOffer } from "./relay-selection.js";
+
+export interface RelayRoleDeps {
+  /** The interface a served relay listens on (RelayServerOptions.host). */
+  listenHost: string;
+  /** This store's own device-id (hex). */
+  ownDeviceHex: string;
+  /** Every device this store has heard gossip from, with its latest advert: where relay offers are read from. */
+  knownDevices: Readonly<Pick<KnownDevices, "current">>;
+  /** The live machine-local sessions: a device with one is a full member of this store's local mesh. */
+  machineLocalPeers: Readonly<Pick<ElectionSessions, "hasPeer">>;
+  /** Gateway trust, whose reachability check admits a device learned through a hub. */
+  gatewayTrust: Readonly<Pick<GatewayTrustReader, "isReachable">>;
+  /** Re-sends this store's gossip, so the relay offer it carries changes at once and a new hub session is advertised straight away. */
+  readvertise: () => void;
+  events: Readonly<Pick<TransportEvents, "onError">>;
+}
+
+export class RelayRole {
+  private eligible = false;
+  private upstream = false;
+  private server: RelayServer | undefined;
+  /** Serialises start and stop, so a quick eligible/ineligible flip cannot leave two servers, or none where one should exist. */
+  private transition: Promise<void> = Promise.resolve();
+  /** Holds this store's one hub session over the selected relay, once joinHub has named the configured hub. */
+  private hubLink: HubLink | undefined;
+  /** The hub session whose connection a served relay takes as its uplink. */
+  private hub: HubSession | undefined;
+
+  constructor(private readonly deps: Readonly<RelayRoleDeps>) {}
+
+  /** Starts holding the hub session: over the relay selection prefers, with publicHubUrl (the configured hub) as the fallback and as the uplink an eligible store serves from. A second call does nothing. */
+  joinHub(
+    hub: HubSession,
+    publicHubUrl: string,
+    shouldConnect: () => boolean,
+  ): void {
+    if (this.hubLink !== undefined) return;
+    this.hub = hub;
+    this.hubLink = new HubLink({
+      hub,
+      selectUrl: (excluded) => this.selectUrl(publicHubUrl, excluded),
+      shouldConnect,
+      onConnected: (url) => {
+        this.setUpstream(url === publicHubUrl);
+        this.deps.readvertise();
+      },
+      onDisconnected: () => {
+        this.setUpstream(false);
+      },
+      onError: (error) => {
+        this.deps.events.onError?.(error);
+      },
+    });
+    this.hubLink.start();
+  }
+
+  /** Makes the hub session re-evaluate now whether it is wanted, and over which relay. */
+  reconsiderHub(): void {
+    this.hubLink?.reconsider();
+  }
+
+  /** The addresses this store currently offers relay service at, or undefined while it serves none. */
+  offer(): readonly string[] | undefined {
+    return this.server?.addresses();
+  }
+
+  /** How many clients the served relay has, or 0 while none is served. */
+  servedConnectionCount(): number {
+    return this.server === undefined ? 0 : this.server.connectionCount();
+  }
+
+  /** How many clients the served relay can route to, or 0 while none is served. See RelayServer.routableClientCount. */
+  routableClientCount(): number {
+    return this.server === undefined ? 0 : this.server.routableClientCount();
+  }
+
+  /** Whether this store may serve: set from the elected coordinator role. An eligible store moves its hub session back onto the uplink at once. */
+  setEligible(eligible: boolean): void {
+    this.eligible = eligible;
+    this.reconcile();
+    this.hubLink?.reconsider();
+  }
+
+  /** The URL to hold the hub session over: the public hub for an eligible store (its uplink), otherwise the best relay the policy finds, skipping any offer with an address in excluded (dials that just failed). */
+  selectUrl(publicHubUrl: string, excluded: ReadonlySet<string>): string {
+    if (this.eligible) return publicHubUrl;
+    return selectRelay({
+      offers: this.offers().filter((offer) =>
+        offer.addresses.every((address) => !excluded.has(address)),
+      ),
+      isTrusted: (deviceHex) => this.deps.gatewayTrust.isReachable(deviceHex),
+      ownDeviceHex: this.deps.ownDeviceHex,
+      publicHubUrl,
+    }).url;
+  }
+
+  /** Drops the hub session and stops serving, for good. */
+  async stop(): Promise<void> {
+    await this.hubLink?.stop();
+    this.eligible = false;
+    this.reconcile();
+    await this.transition;
+  }
+
+  /** Whether this store's hub session is currently held to the configured public hub. */
+  private setUpstream(upstream: boolean): void {
+    this.upstream = upstream;
+    this.reconcile();
+  }
+
+  private offers(): RelayOffer[] {
+    const offers: RelayOffer[] = [];
+    for (const [deviceHex, advert] of this.deps.knownDevices.current()) {
+      const addresses = readRelayOffer(advert);
+      if (addresses === undefined) continue;
+      offers.push({
+        deviceHex,
+        addresses,
+        machineLocal: this.deps.machineLocalPeers.hasPeer(deviceHex),
+      });
+    }
+    return offers;
+  }
+
+  /** Gives the served relay the hub session's connection as its uplink when it has none, which carries its clients to and from devices on the public hub. A session that was replaced since (the hub dropped it and it was redialled) has no uplink yet, so this runs on every reconcile and not only when the relay starts. */
+  private frontClients(server: RelayServer): void {
+    const hub = this.hub;
+    if (hub === undefined || hub.hasUplink) return;
+    if (hub.attachUplink((connection) => server.attachUplink(connection))) {
+      this.deps.readvertise();
+    }
+  }
+
+  private reconcile(): void {
+    this.transition = this.transition
+      .then(async () => {
+        const wanted = this.eligible && this.upstream;
+        if (wanted && this.server !== undefined) this.frontClients(this.server);
+        if (wanted && this.server === undefined) {
+          const server = new RelayServer({
+            host: this.deps.listenHost,
+            isAdmitted: (deviceHex) =>
+              this.deps.machineLocalPeers.hasPeer(deviceHex) ||
+              this.deps.gatewayTrust.isReachable(deviceHex),
+            onError: (error) => {
+              this.deps.events.onError?.(error);
+            },
+          });
+          await server.start();
+          this.server = server;
+          this.frontClients(server);
+          this.deps.readvertise();
+        } else if (!wanted && this.server !== undefined) {
+          const server = this.server;
+          this.server = undefined;
+          this.hub?.detachUplink();
+          this.deps.readvertise();
+          await server.stop();
+        }
+      })
+      .catch((error: unknown) => {
+        this.deps.events.onError?.(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      });
+  }
+}