agent-comms 8.15.9 → 8.15.10

package/src/core/device-membership-verification.ts

@@ -0,0 +1,125 @@
+/**
+ * Device group membership (agent-comms#161, widened to machines by agent-comms#343): the token a bridge device holds proving a grouping issuer admitted it, either its user principal (core/user-identity.ts, "this device speaks for me") or its machine (core/machine-identity.ts, "this device runs on me"). Layered on verifyCapabilityToken exactly the way room-token-verification.ts layers core/room's own obligations on top of it: a token bearing the right capability, scoped to the right group, whose delegation chain actually roots at the claimed issuer, never merely one that happens to carry a superficially matching scope.path. Unlike a room, a group:member token has only one acceptable chain root ever, the group's issuer itself; there is no room-style "owner-named vs DM" distinction to branch on.
+ */
+
+import {
+  verifyCapabilityToken,
+  type TokenVerdictReason,
+  type VerifyCapabilityTokenOptions,
+} from "wire-mesh-core/domain/tokens";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type {
+  CapabilityToken,
+  DeviceId,
+  TokenClaims,
+} from "wire-mesh-core/generated/protocol";
+
+/** The one capability a device presents to prove a grouping issuer admitted it, mirroring room:member's own "one resource, one verb" shape, scoped to tokens.cddl's `group` kind (a person's, team's, or organisation's own set of owned devices) rather than `room`. Registered at wire-mesh's spec/registry/core-capabilities.md as `group:member`, scope kind `group`, domain `core/management`. */
+export const DEVICE_MEMBER_CAPABILITY = "group:member";
+
+/** A grouping issuer's own group scope path: every group:member token's scope.path, and the group every one of that issuer's admission grants roots at. The issuer is a user principal (user-identity.ts) or a machine (machine-identity.ts, agent-comms#343); either way the path is just the issuer's own device-id in hex, since tokens.cddl's `group` scope kind has no identifier of its own separate from the device-id of the key the group is rooted at. */
+export function groupPath(issuerDeviceId: Readonly<DeviceId>): string {
+  return deviceIdToHex(issuerDeviceId);
+}
+
+export type DeviceMembershipVerdictReason =
+  | TokenVerdictReason
+  | "wrong_capability"
+  | "wrong_scope_kind"
+  | "wrong_scope_path"
+  | "wrong_chain_root";
+
+export type DeviceMembershipVerdict =
+  | { ok: true; claims: TokenClaims; depth: number }
+  | { ok: false; reason: DeviceMembershipVerdictReason };
+
+/** What identifyGroupIssuer reports: the verdict of verifyDeviceMembership, plus the issuer (hex) the token turned out to be rooted at. */
+export type GroupIssuerVerdict =
+  | { ok: true; issuerHex: string; claims: TokenClaims; depth: number }
+  | { ok: false; reason: DeviceMembershipVerdictReason };
+
+export interface VerifyGroupTokenOptions extends Omit<
+  VerifyCapabilityTokenOptions,
+  "expectedBearer"
+> {
+  /** The device actually authenticated on the arriving connection (or otherwise known out of band), never a relay-asserted or gossip-derived value, whenever the result is used to authorise something. Mandatory here, unlike verifyCapabilityToken's own optional field for a caller presenting a token to authorise itself. The callers that pass a gossip-derived id (directory-admission.ts and the machine grouping in list_agents, for a proof read off a gossiped advert) deliberately treat the result as a claim about that id and nothing more. */
+  expectedBearer: DeviceId;
+}
+
+export interface VerifyDeviceMembershipOptions extends VerifyGroupTokenOptions {
+  /** The grouping issuer (a user principal or a machine) this membership is claimed to belong to. Determines both the expected scope.path (groupPath) and the delegation chain's only acceptable root: a group:member token minted by anyone other than this issuer must never verify, regardless of what its scope claims. */
+  groupIssuerId: DeviceId;
+}
+
+type GroupTokenVerdict =
+  | { ok: true; claims: TokenClaims; depth: number; rootHex: string }
+  | { ok: false; reason: DeviceMembershipVerdictReason };
+
+/** The checks every group:member token passes whoever its issuer is: verifyCapabilityToken's own obligations (signature, expiry, revocation, bearer match), the group:member capability (a token minted for some other capability that happens to be scoped to a group path must not pass just because scope.kind and path line up), and a group scope. */
+async function verifyGroupToken(
+  token: CapabilityToken,
+  options: Readonly<VerifyGroupTokenOptions>,
+): Promise<GroupTokenVerdict> {
+  const verdict = await verifyCapabilityToken(token, {
+    identity: options.identity,
+    clock: options.clock,
+    revocation: options.revocation,
+    expectedBearer: options.expectedBearer,
+    ...(options.extraPredicateResolvers !== undefined
+      ? { extraPredicateResolvers: options.extraPredicateResolvers }
+      : {}),
+  });
+  if (!verdict.ok) {
+    return verdict;
+  }
+
+  if (verdict.claims.capability !== DEVICE_MEMBER_CAPABILITY) {
+    return { ok: false, reason: "wrong_capability" };
+  }
+  if (verdict.claims.scope.kind !== "group") {
+    return { ok: false, reason: "wrong_scope_kind" };
+  }
+  return {
+    ok: true,
+    claims: verdict.claims,
+    depth: verdict.depth,
+    rootHex: deviceIdToHex(verdict.rootIssuer),
+  };
+}
+
+/**
+ * Verifies a `group:member` capability token against a known issuer: verifyGroupToken's checks, then that its scope is the claimed issuer's own group and its delegation chain roots at that issuer's own device-id, never at the bearer itself or any other device, since only the issuer may admit a device to its own group.
+ */
+export async function verifyDeviceMembership(
+  token: CapabilityToken,
+  options: Readonly<VerifyDeviceMembershipOptions>,
+): Promise<DeviceMembershipVerdict> {
+  const verdict = await verifyGroupToken(token, options);
+  if (!verdict.ok) return verdict;
+  const expectedGroupPath = groupPath(options.groupIssuerId);
+  if (verdict.claims.scope.path !== expectedGroupPath) {
+    return { ok: false, reason: "wrong_scope_path" };
+  }
+  if (verdict.rootHex !== expectedGroupPath) {
+    return { ok: false, reason: "wrong_chain_root" };
+  }
+  return { ok: true, claims: verdict.claims, depth: verdict.depth };
+}
+
+/** Verifies a `group:member` token without knowing its issuer beforehand, and reports which issuer it is rooted at: verifyGroupToken's checks, then that the group it names is the one its chain roots at. Used to group devices by the machine that vouches for them, where the machine is learned from the proof rather than looked up. Anything it reports is still only what that issuer claims about the bearer. */
+export async function identifyGroupIssuer(
+  token: CapabilityToken,
+  options: Readonly<VerifyGroupTokenOptions>,
+): Promise<GroupIssuerVerdict> {
+  const verdict = await verifyGroupToken(token, options);
+  if (!verdict.ok) return verdict;
+  if (verdict.claims.scope.path !== verdict.rootHex) {
+    return { ok: false, reason: "wrong_chain_root" };
+  }
+  return {
+    ok: true,
+    issuerHex: verdict.rootHex,
+    claims: verdict.claims,
+    depth: verdict.depth,
+  };
+}

package/src/core/device-membership.ts

@@ -0,0 +1,130 @@
+/**
+ * Device-to-user membership admission and removal (agent-comms#161): mints and revokes a device's own group:member grant from the user principal, the same "ordinary mint and revoke" mechanism room-lifecycle.ts's own kickFromRoom already uses for room-membership exclusion, rooted at the principal (core/user-identity.ts) rather than a room owner. Orchestrates mintCapabilityToken/mintRevocationEntry together with the principal's own issued-grant bookkeeping (user-identity.ts) so a later removal can find the right token-id to revoke -- the same tight coupling room-lifecycle.ts's own admission methods already have with identity-store.ts's issuedGrants, just here as plain functions rather than class methods, since there is no MeshStore-equivalent orchestrator for device membership yet.
+ *
+ * Deliberately does not touch the admitted device's own identity-store.ts slot (its saveGroupToken/loadGroupTokens/deleteGroupToken): whether an admission happens entirely locally (the same process holding both the principal's key and the device's own slot) or needs to reach a different bridge process is a routing question this module makes no assumption about, so persisting the granted token into the recipient's own slot -- and broadcasting a removal's revocation entry to the mesh -- is left to the caller, which has that context.
+ */
+
+import {
+  mintCapabilityToken,
+  mintRevocationEntry,
+  type MintVerdict,
+} from "wire-mesh-core/domain/tokens";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type { RevocationView } from "wire-mesh-core/domain/revocation-view";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import type { Clock } from "wire-mesh-core/ports/clock";
+import type {
+  DeviceId,
+  RevocationEntry,
+} from "wire-mesh-core/generated/protocol";
+import {
+  DEVICE_MEMBER_CAPABILITY,
+  groupPath,
+} from "./device-membership-verification.js";
+import type { AccountLedger } from "./account-ledger.js";
+
+/** delegationsRemaining for every device-membership grant -- deliberately non-delegable: a device that could re-mint membership for another device would let any admitted device silently admit others, defeating the point of the principal being the one place admission is decided (the same reasoning room-lifecycle.ts's own mintOwnerRootGrant already documents for a room owner's self-grant). */
+const NOT_DELEGABLE = 0;
+
+export interface AdmitDeviceOptions {
+  /** The user principal's own identity -- signs the membership grant. */
+  userIdentity: IdentityPort;
+  /** The account's replicated grant ledger, which records the admission so any machine holding the account key can revoke it. */
+  accountLedger: AccountLedger;
+  clock: Clock;
+  tokenId: Uint8Array<ArrayBuffer>;
+  /** The device being admitted. */
+  deviceId: DeviceId;
+  expires: number;
+}
+
+export interface MintGroupMembershipOptions {
+  /** The grouping issuer signing the grant: a user principal (user-identity.ts) or a machine (machine-identity.ts). The grant is scoped to this issuer's own group (groupPath). */
+  issuer: IdentityPort;
+  clock: Clock;
+  tokenId: Uint8Array<ArrayBuffer>;
+  /** The device being admitted: the grant's bearer. */
+  deviceId: DeviceId;
+  expires: number;
+}
+
+/** The group:member token itself, with no record kept of having issued it: a root-level, non-delegable grant bearing options.deviceId and scoped to the issuer's own group (groupPath). admitDevice adds the issued-grant bookkeeping a later removeDevice needs; a caller that only needs a short-lived proof (membership-proof.ts) uses this directly, so the shared identity file is not rewritten every time one of its many bridges refreshes its proof. */
+export async function mintGroupMembership(
+  options: Readonly<MintGroupMembershipOptions>,
+): Promise<MintVerdict> {
+  return mintCapabilityToken({
+    identity: options.issuer,
+    clock: options.clock,
+    tokenId: options.tokenId,
+    bearer: options.deviceId,
+    capability: DEVICE_MEMBER_CAPABILITY,
+    scope: {
+      kind: "group",
+      path: groupPath(options.issuer.deviceId),
+    },
+    expires: options.expires,
+    delegationsRemaining: NOT_DELEGABLE,
+  });
+}
+
+/**
+ * Mints deviceId's own group:member grant from the user principal: a root-level, non-delegable token scoped to the principal's own group (groupPath). On success, records the grant's token-id in the account's replicated ledger so a later removeDevice, on this machine or any other holding the account key, can find it to revoke. An admission without that record would leave removal permanently unable to find what to revoke, so it is what makes revocation possible at all.
+ */
+export async function admitDevice(
+  options: Readonly<AdmitDeviceOptions>,
+): Promise<MintVerdict> {
+  const verdict = await mintGroupMembership({
+    ...options,
+    issuer: options.userIdentity,
+  });
+  if (!verdict.ok) return verdict;
+
+  await options.accountLedger.recordGrant(
+    "device",
+    deviceIdToHex(options.deviceId),
+    options.tokenId,
+  );
+  return verdict;
+}
+
+export interface RemoveDeviceOptions {
+  /** The user principal's own identity -- only the principal that issued a device's membership may revoke it. */
+  userIdentity: IdentityPort;
+  accountLedger: AccountLedger;
+  clock: Clock;
+  /** Recorded locally immediately, so this principal's own future verifications see the removal without waiting on gossip -- mirrors room-lifecycle.ts's own revokeMemberGrant ordering (record before broadcast). */
+  revocation: RevocationView;
+  deviceId: DeviceId;
+}
+
+/**
+ * Revokes every group:member grant for deviceId that the account's ledger holds as outstanding, whichever machine of the account minted it: mints a revocation-entry for each token-id, records it in the given RevocationView immediately, and appends it to the ledger, so every other machine of the account sees the grant as revoked and a later re-admission starts from nothing outstanding. Returns no entries for a device the account never admitted.
+ *
+ * Returns the minted entries so the caller can broadcast them to the mesh (this module has no MeshTransport dependency to do so itself, mirroring the module-level "no assumption about locality" boundary documented above): every other device that might hold one of this device's grants needs the entry to independently start refusing it.
+ */
+export async function removeDevice(
+  options: Readonly<RemoveDeviceOptions>,
+): Promise<RevocationEntry[]> {
+  const deviceHex = deviceIdToHex(options.deviceId);
+  const outstanding = await options.accountLedger.outstandingGrants(
+    "device",
+    deviceHex,
+  );
+  const entries: RevocationEntry[] = [];
+  for (const { tokenId } of outstanding) {
+    const entry = await mintRevocationEntry({
+      identity: options.userIdentity,
+      tokenId,
+      revokedAt: options.clock.now(),
+    });
+    await options.revocation.record(entry, { identity: options.userIdentity });
+    await options.accountLedger.recordRevocation(
+      "device",
+      deviceHex,
+      tokenId,
+      entry,
+    );
+    entries.push(entry);
+  }
+  return entries;
+}

package/src/core/directory-admission.ts

@@ -0,0 +1,155 @@
+/**
+ * Which gossiped directory entries from the hub a gateway merges (agent-comms#156, widened by #187, #266 and #343). Split out of WireMeshTransport, which hands it the two collaborators it needs.
+ *
+ * A membership proof shows that a trusted principal or machine vouches for a device id. It does not show that whoever sent the advert is that device: the id and the proof both arrive in the same unauthenticated advert, and anyone who has read one can repeat it. So it earns only what GatewayTrust.isReachable grants (a directory entry and a route), never isTrusted, and everything a request to such a device carries is authenticated by the end-to-end session inside the relay. Verifying a proof is cryptography, so the work is bounded here: verdicts are remembered, a batch verifies only so many new proofs, and a verifier that throws refuses the entry rather than breaking the merge.
+ */
+
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type { DirectoryEntry } from "wire-mesh-core/domain/mesh-session";
+import type { GatewayTrustReader, GroupKind } from "./gateway-trust.js";
+import {
+  readMembershipProof,
+  type MembershipProofField,
+} from "./gossip-directory.js";
+import type { WireMeshTransportOptions } from "./wire-mesh-transport-options.js";
+
+/** How many new proofs one batch of entries may verify. Trusted devices and proofs already judged cost nothing against it, so a flood of fresh adverts costs a bounded amount of work per batch and the rest wait for the next. */
+export const MAX_VERIFICATIONS_PER_BATCH = 8;
+
+const MS_PER_SECOND = 1000;
+const NEGATIVE_VERDICT_TTL_SECONDS = 60;
+/** How long a refused proof is remembered before it is worth checking again: long enough that a repeated bad proof is not re-verified on every frame, short enough that a principal trusted a moment later takes effect promptly. */
+export const NEGATIVE_VERDICT_TTL_MS =
+  NEGATIVE_VERDICT_TTL_SECONDS * MS_PER_SECOND;
+
+/** The most proofs whose last verdict is remembered. */
+const VERDICT_CACHE_LIMIT = 1024;
+
+/** Each advert field that can carry a proof, and the kind of issuer whose trusted set it is checked against. */
+const PROOF_SOURCES: readonly {
+  field: MembershipProofField;
+  kind: GroupKind;
+}[] = [
+  { field: "membership", kind: "principal" },
+  { field: "machine", kind: "machine" },
+];
+
+export interface DirectoryAdmissionDeps {
+  gatewayTrust: Readonly<GatewayTrustReader>;
+  /** Absent when this side cannot verify proofs, in which case a proof is never enough. */
+  verifyMembership: WireMeshTransportOptions["verifyMembership"];
+}
+
+interface Verdict {
+  ok: boolean;
+  /** When a refusal stops being remembered (epoch ms). */
+  until: number;
+}
+
+/** Whether an entry this side has already merged from the hub would still be admitted now, with no new proof to judge: its device is reachable (trusted by id, or vouched for by a proof that has not lapsed from an issuer still trusted) or is itself a trusted principal's own device. The read-time counterpart of directoryAdmission, which KnownDevices uses to drop a device as soon as the trust that let it in is withdrawn or lapses. */
+export function staysAdmitted(
+  gatewayTrust: Readonly<
+    Pick<GatewayTrustReader, "isReachable" | "isTrustedPrincipal">
+  >,
+  deviceHex: string,
+): boolean {
+  return (
+    gatewayTrust.isReachable(deviceHex) ||
+    gatewayTrust.isTrustedPrincipal(deviceHex)
+  );
+}
+
+/** Builds the admission check for a transport's directory merge: given a batch of entries, the ones to merge. An entry is merged if its device is trusted by id, is itself a trusted principal's own device, or carries a proof that a trusted principal or machine vouches for it; each proof an entry carries is judged on its own, and every one that verifies records the device in gatewayTrust under that kind until the proof lapses or its issuer stops being trusted. A remembered good verdict is reused only while that kind's record is still live, and a device's newer proof is verified as it arrives, which is how its trust is renewed before the old one lapses. */
+export function directoryAdmission(
+  deps: Readonly<DirectoryAdmissionDeps>,
+): (entries: readonly DirectoryEntry[]) => Promise<DirectoryEntry[]> {
+  const { gatewayTrust, verifyMembership } = deps;
+  /** Keyed by kind, device and proof. A directory event can carry several proofs for one device at once, a stale copy beside a fresh one, so a slot per device would be overwritten by each in turn and every event would verify them all again. */
+  const verdicts = new Map<string, Verdict>();
+
+  const remember = (key: string, verdict: Readonly<Verdict>): void => {
+    verdicts.delete(key);
+    verdicts.set(key, verdict);
+    if (verdicts.size > VERDICT_CACHE_LIMIT) {
+      const oldest = verdicts.keys().next();
+      if (oldest.done !== true) verdicts.delete(oldest.value);
+    }
+  };
+
+  const trustedIssuers = (kind: GroupKind): string[] =>
+    kind === "principal"
+      ? gatewayTrust.listPrincipals()
+      : gatewayTrust.listMachines();
+
+  /** The first trusted issuer of the given kind that vouches for the proof, with the proof's expiry, or undefined. An issuer the verifier throws on (a malformed id, or no identity attached yet) is skipped, so one bad issuer never blocks the others. */
+  const vouchedFor = async (
+    proof: string,
+    deviceHex: string,
+    kind: GroupKind,
+  ): Promise<{ issuer: string; expires: number } | undefined> => {
+    if (verifyMembership === undefined) return undefined;
+    for (const issuer of trustedIssuers(kind)) {
+      try {
+        const verdict = await verifyMembership({
+          proof,
+          deviceHex,
+          issuerHex: issuer,
+        });
+        if (verdict.ok) return { issuer, expires: verdict.expires };
+      } catch {
+        continue;
+      }
+    }
+    return undefined;
+  };
+
+  return async (entries) => {
+    const admitted: DirectoryEntry[] = [];
+    let budget = MAX_VERIFICATIONS_PER_BATCH;
+    for (const entry of entries) {
+      const deviceHex = deviceIdToHex(entry.device);
+      if (
+        gatewayTrust.isTrusted(deviceHex) ||
+        gatewayTrust.isTrustedPrincipal(deviceHex)
+      ) {
+        admitted.push(entry);
+        continue;
+      }
+      if (verifyMembership === undefined) continue;
+      // Every proof the entry carries is judged, not just the first that passes, so a device vouched for by both a trusted principal and a trusted machine holds a record of each and stays reachable when either issuer is untrusted.
+      let vouched = false;
+      for (const { field, kind } of PROOF_SOURCES) {
+        const proof = readMembershipProof(entry.advert, field);
+        if (proof === undefined) continue;
+
+        const key = `${kind}:${deviceHex}:${proof}`;
+        const known = verdicts.get(key);
+        if (known !== undefined) {
+          if (known.ok && gatewayTrust.isVouchedBy(deviceHex, kind)) {
+            vouched = true;
+            continue;
+          }
+          if (!known.ok && known.until > Date.now()) continue;
+        }
+        if (budget === 0) continue;
+        budget -= 1;
+
+        const vouch = await vouchedFor(proof, deviceHex, kind);
+        remember(key, {
+          ok: vouch !== undefined,
+          until: Date.now() + NEGATIVE_VERDICT_TTL_MS,
+        });
+        if (vouch !== undefined) {
+          gatewayTrust.noteVerifiedMember(
+            deviceHex,
+            { kind, issuer: vouch.issuer },
+            vouch.expires,
+          );
+          vouched = true;
+        }
+      }
+      if (vouched) admitted.push(entry);
+    }
+    return admitted;
+  };
+}

package/src/core/discovery-mdns.ts

@@ -0,0 +1,247 @@
+/**
+ * mDNS discovery backend — UDP broadcast beacon fallback.
+ *
+ * Since the `multicast-dns` package is not a dependency, this backend
+ * uses a simple UDP broadcast beacon instead:
+ *   - Sends a UDP broadcast to port 19877 every 30 seconds
+ *   - Listens for beacons from other peers on the same port
+ *   - discover() listens for one beacon cycle and returns results
+ *
+ * If multicast-dns is added as a dependency in the future, a proper
+ * mDNS implementation can replace this with _agent-comms._tcp service
+ * broadcast and query/response.
+ */
+
+import * as dgram from "node:dgram";
+import type {
+  DiscoveredMesh,
+  DiscoveryBackend,
+  AdvertiseOptions,
+} from "./discovery.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const BEACON_PORT = 19877;
+const BEACON_INTERVAL_MS = 30_000;
+const DEFAULT_DISCOVER_TIMEOUT_MS = 5_000;
+
+interface BeaconPayload {
+  type: "agent-comms-beacon";
+  name: string;
+  port: number;
+  agents?: number;
+  policies?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// mDNS (UDP beacon) backend
+// ---------------------------------------------------------------------------
+
+export class MdnsDiscoveryBackend implements DiscoveryBackend {
+  readonly name = "mdns";
+
+  private socket: dgram.Socket | undefined;
+  private beaconTimer: ReturnType<typeof setInterval> | undefined;
+  private currentPayload: BeaconPayload | undefined;
+  private isListening = false;
+
+  async startAdvertising(opts: Readonly<AdvertiseOptions>): Promise<string> {
+    const id = `mdns-${String(opts.port)}`;
+
+    this.currentPayload = {
+      type: "agent-comms-beacon",
+      name: opts.name,
+      port: opts.port,
+      policies: opts.policy === "name-only" ? ["name-only"] : ["full"],
+    };
+
+    await this.ensureListening();
+    this.startBeacon();
+
+    return id;
+  }
+
+  async stopAdvertising(): Promise<void> {
+    if (this.beaconTimer !== undefined) {
+      clearInterval(this.beaconTimer);
+      this.beaconTimer = undefined;
+    }
+
+    this.currentPayload = undefined;
+
+    // Only close the socket if we're not also discovering
+    if (this.socket && !this.hasActiveListeners()) {
+      await this.closeSocket();
+    }
+  }
+
+  /** Stop all beacon activity and close the socket. */
+  async stop(): Promise<void> {
+    if (this.beaconTimer !== undefined) {
+      clearInterval(this.beaconTimer);
+      this.beaconTimer = undefined;
+    }
+
+    this.currentPayload = undefined;
+
+    if (this.socket) {
+      await this.closeSocket();
+    }
+  }
+
+  /** Close the UDP socket and wait for the underlying handle to actually release before resolving. */
+  private async closeSocket(): Promise<void> {
+    const socket = this.socket;
+    if (!socket) return;
+
+    await new Promise<void>((resolve) => {
+      socket.close(() => {
+        resolve();
+      });
+    });
+
+    this.socket = undefined;
+    this.isListening = false;
+  }
+
+  async discover(
+    timeout: number = DEFAULT_DISCOVER_TIMEOUT_MS,
+  ): Promise<DiscoveredMesh[]> {
+    const discovered = new Map<string, DiscoveredMesh>();
+
+    await this.ensureListening();
+
+    const socket = this.socket;
+    if (socket === undefined) return [];
+
+    // Collect beacons for the specified duration
+    const handler = (msg: Buffer, rinfo: dgram.RemoteInfo) => {
+      const mesh = this.parseBeacon(msg, rinfo);
+      if (mesh) {
+        const key = `${mesh.host}:${String(mesh.port)}`;
+        discovered.set(key, mesh);
+      }
+    };
+
+    socket.on("message", handler);
+
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, timeout);
+    });
+
+    socket.off("message", handler);
+    this.cleanupSocket();
+
+    return [...discovered.values()];
+  }
+
+  // -----------------------------------------------------------------------
+  // Internals
+  // -----------------------------------------------------------------------
+
+  private async ensureListening(): Promise<void> {
+    if (this.isListening && this.socket) return;
+
+    const socket = dgram.createSocket({
+      type: "udp4",
+      reuseAddr: true,
+    });
+
+    socket.on("error", () => {
+      // Binding errors are non-fatal for discovery — the beacon simply
+      // won't reach anyone on this interface.
+      this.isListening = false;
+    });
+
+    await new Promise<void>((resolve) => {
+      socket.bind(BEACON_PORT, () => {
+        socket.setBroadcast(true);
+        this.isListening = true;
+        resolve();
+      });
+    });
+
+    this.socket = socket;
+  }
+
+  private startBeacon(): void {
+    if (this.beaconTimer !== undefined) {
+      clearInterval(this.beaconTimer);
+    }
+
+    // Send immediately, then on interval
+    this.sendBeacon();
+    this.beaconTimer = setInterval(() => {
+      this.sendBeacon();
+    }, BEACON_INTERVAL_MS);
+  }
+
+  private sendBeacon(): void {
+    if (!this.currentPayload || !this.socket) return;
+
+    const payload = Buffer.from(JSON.stringify(this.currentPayload));
+    // Broadcast to the beacon port on the standard broadcast address
+    this.socket.send(payload, BEACON_PORT, "255.255.255.255", (err) => {
+      if (err) {
+        // Broadcast failures are non-fatal — the network may not
+        // support broadcast (e.g. some cloud environments).
+      }
+    });
+  }
+
+  private parseBeacon(
+    msg: Buffer,
+    rinfo: dgram.RemoteInfo,
+  ): DiscoveredMesh | undefined {
+    try {
+      const parsed: unknown = JSON.parse(msg.toString());
+
+      if (
+        typeof parsed !== "object" ||
+        parsed === null ||
+        !("type" in parsed) ||
+        typeof parsed.type !== "string" ||
+        parsed.type !== "agent-comms-beacon"
+      ) {
+        return undefined;
+      }
+
+      if (!("port" in parsed) || typeof parsed.port !== "number")
+        return undefined;
+      if (!("name" in parsed) || typeof parsed.name !== "string")
+        return undefined;
+      const result: DiscoveredMesh = {
+        host: rinfo.address,
+        port: parsed.port,
+        name: parsed.name,
+      };
+      if ("agents" in parsed && typeof parsed.agents === "number")
+        result.agentCount = parsed.agents;
+      if (
+        "policies" in parsed &&
+        Array.isArray(parsed.policies) &&
+        parsed.policies.every((v) => typeof v === "string")
+      )
+        result.policies = parsed.policies;
+      return result;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private hasActiveListeners(): boolean {
+    // Check if there are message listeners beyond our own
+    if (!this.socket) return false;
+    return this.socket.listenerCount("message") > 0;
+  }
+
+  private cleanupSocket(): void {
+    if (this.socket && !this.currentPayload && !this.hasActiveListeners()) {
+      this.socket.close();
+      this.socket = undefined;
+      this.isListening = false;
+    }
+  }
+}