agent-comms 8.15.9 → 8.15.11

package/src/core/gossip-directory.ts

@@ -0,0 +1,276 @@
+/**
+ * gossip-directory — the mesh-wide gossip-directory aggregation WireMeshTransport's own listKnownDevices reads from, plus per-event directory lookups (a specific peer's presence advert). Split out purely to keep wire-mesh-transport.ts under the repo's max-lines cap, the same reason connection-approval.ts, room-router.ts, hub-session.ts, and peer-lifecycle.ts were each split from their own owning file.
+ */
+
+import type { TransportEvents } from "./transport.js";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type {
+  AcceptedMeshSession,
+  DirectoryEntry,
+} from "wire-mesh-core/domain/mesh-session";
+import type { PeerAdvert } from "wire-mesh-core/generated/protocol";
+import { buildRelayOfferExtension } from "wire-mesh-core/domain/relay-advert";
+import { AgentStatus } from "./types.js";
+import { getOwnPackageVersion } from "./package-version.js";
+import {
+  AGENT_SELF_GOSSIP_KEY,
+  HOSTED_ROOMS_GOSSIP_KEY,
+  PRESENCE_GOSSIP_KEY,
+  summariseAgentSelfAdvert,
+  summariseHostedRooms,
+  type AgentSelfAdvert,
+  type HostedRoomAdvert,
+} from "./gossip-extensions.js";
+import {
+  AGENT_COMMS_VERSION_GOSSIP_KEY,
+  type AgentCommsVersionsAdvert,
+} from "./peer-versions.js";
+import type { HubSession } from "./hub-session.js";
+
+/** Merges one session event's own directory into the mesh-wide knownDevices view (mutated in place), keeping the newer advert (by snapshot-seconds) whenever a device-id is already known from an earlier event or a different session. An equal snapshot replaces the held advert, unlike the relay hub, which lets an advert take a device's registration over from a different connection only when it is strictly newer: the hub is guarding a route against a replayed advert, whereas every entry here has already been verified by the session that produced it, so an equal one carries the same content and the freshest copy is the one to keep. */
+export function mergeKnownDevices(
+  knownDevices: Map<string, PeerAdvert>,
+  directory: readonly DirectoryEntry[],
+): void {
+  for (const entry of directory) {
+    const deviceIdHex = deviceIdToHex(entry.device);
+    const existing = knownDevices.get(deviceIdHex);
+    if (
+      existing === undefined ||
+      entry.advert["snapshot-seconds"] >= existing["snapshot-seconds"]
+    ) {
+      knownDevices.set(deviceIdHex, entry.advert);
+    }
+  }
+}
+
+/**
+ * The mesh-wide gossip directory a transport reads (agent-comms#48): the latest advert of every device it has heard of, from its local peer sessions and from the hub, kept across disconnects so a device's last-known advert stays queryable while its session is down.
+ *
+ * A device heard of through a local peer session is kept for good, since the local mesh admits its peers by its own approval rather than by gateway trust. A device heard of only through the hub is kept only while the hub would still admit it (admitted, the same decision directoryAdmission makes), and that is checked on every read (agent-comms#343): withdrawing trust from a device, principal or machine, in this process or in another that shares the trust file, removes from the view every device that trust alone let in, and so does a membership proof lapsing. Nothing re-adds such a device unless the hub admits it again.
+ */
+export class KnownDevices {
+  private readonly adverts = new Map<string, PeerAdvert>();
+  private readonly heardLocally = new Set<string>();
+
+  /** admitted answers whether the hub would still admit the device (hex) today. */
+  constructor(private readonly admitted: (deviceHex: string) => boolean) {}
+
+  /** Merges a local peer session's directory (see mergeKnownDevices). */
+  mergeLocal(directory: readonly DirectoryEntry[]): void {
+    mergeKnownDevices(this.adverts, directory);
+    for (const entry of directory) {
+      this.heardLocally.add(deviceIdToHex(entry.device));
+    }
+  }
+
+  /** Merges the hub session's admitted directory (see mergeKnownDevices). */
+  mergeHub(directory: readonly DirectoryEntry[]): void {
+    mergeKnownDevices(this.adverts, directory);
+  }
+
+  /** The current view, keyed by device-id hex, after dropping every hub-only device the hub would no longer admit. */
+  current(): ReadonlyMap<string, Readonly<PeerAdvert>> {
+    for (const deviceHex of [...this.adverts.keys()]) {
+      if (!this.heardLocally.has(deviceHex) && !this.admitted(deviceHex)) {
+        this.adverts.delete(deviceHex);
+      }
+    }
+    return this.adverts;
+  }
+}
+
+/** Merges a hub session's own admitted directory into knownDevices and announces each device in it as reachable. Every entry the hub hands over here has already passed admitEntries, so a device named in one is both present on the hub and trusted or vouched for by this side: exactly the moment a request queued for it becomes worth retrying, and the only such moment for a device that has no local peer session of its own to connect. */
+export function mergeAndAnnounceReachable(
+  knownDevices: KnownDevices,
+  directory: readonly DirectoryEntry[],
+  events: Readonly<Pick<TransportEvents, "onDeviceReachable">>,
+): void {
+  knownDevices.mergeHub(directory);
+  for (const entry of directory) {
+    events.onDeviceReachable(deviceIdToHex(entry.device));
+  }
+}
+
+/** Every device this side has ever heard gossip from, mesh-wide -- not just its own directly-connected peers -- with each one's own latest full advert (addresses, snapshot-seconds, and every open-extension field such as presence/status). The trivial array-conversion half of WireMeshTransport's own listKnownDevices, split out purely to keep that file under the repo's max-lines cap, the same reason mergeKnownDevices above already lives here rather than there. */
+export function listKnownDevicesEntries(
+  knownDevices: ReadonlyMap<string, Readonly<PeerAdvert>>,
+): readonly { deviceId: string; advert: Readonly<PeerAdvert> }[] {
+  return Array.from(knownDevices, ([deviceId, advert]) => ({
+    deviceId,
+    advert,
+  }));
+}
+
+/** Reads a presence extension from one specific device's own gossiped self-advert, if this event's directory carries a fresh one for exactly that device-id -- never for any other device-id a multi-hop directory might mention, since only the session's own authenticated peer's advert is that session's business to report. Returns undefined for a missing presence/status key, or a value that isn't a recognised AgentStatus -- an advert simply not participating in this convention, not an error (the same verifier obligation peer-advert's own open extension tail is documented under). */
+export function findPresenceAdvert(
+  deviceIdHex: string,
+  directory: readonly DirectoryEntry[],
+): AgentStatus | undefined {
+  const entry = directory.find(
+    (candidate) => deviceIdToHex(candidate.device) === deviceIdHex,
+  );
+  if (entry === undefined) return undefined;
+  const status: unknown = entry.advert[PRESENCE_GOSSIP_KEY];
+  return AgentStatus.is(status) ? status : undefined;
+}
+
+/** Which agent/self field carries which issuer's proof: `membership` the user principal's, `machine` the machine's. */
+export type MembershipProofField = "membership" | "machine";
+
+/** The membership proof a peer gossiped in its agent/self advert under field, or undefined when it carries none. The advert is self-asserted by whichever peer sent it, so this only reads it; nothing about the proof is believed until it is verified. */
+export function readMembershipProof(
+  advert: Readonly<Record<string, unknown>>,
+  field: MembershipProofField,
+): string | undefined {
+  const self: unknown = advert[AGENT_SELF_GOSSIP_KEY];
+  if (typeof self !== "object" || self === null) return undefined;
+  if (field === "membership") {
+    return "membership" in self && typeof self.membership === "string"
+      ? self.membership
+      : undefined;
+  }
+  return "machine" in self && typeof self.machine === "string"
+    ? self.machine
+    : undefined;
+}
+
+/** Which agent/self field carries which issuer's name claim: `machineName` the machine's, `principalName` the user principal's. */
+export type NameClaimField = "machineName" | "principalName";
+
+/** The name claim a peer gossiped in its agent/self advert under field (name-claim.ts), or undefined when it carries none. Only read here; nothing it says is believed until it is verified against the issuer its proof names. */
+export function readNameClaim(
+  advert: Readonly<Record<string, unknown>>,
+  field: NameClaimField,
+): string | undefined {
+  const self: unknown = advert[AGENT_SELF_GOSSIP_KEY];
+  if (typeof self !== "object" || self === null) return undefined;
+  const claim: unknown = field in self ? Reflect.get(self, field) : undefined;
+  return typeof claim === "string" ? claim : undefined;
+}
+
+/** The one thing gossip re-advertisement needs from a session: somewhere to send the extension bag. */
+export type GossipSession = Pick<AcceptedMeshSession, "sendGossipUpdate">;
+
+/** Which session, if any, is the hub's. */
+export interface HubOwnership {
+  ownsSession: (session: Readonly<GossipSession>) => boolean;
+}
+
+/** Re-sends this side's own current presence status, currently-hosted rooms, self-agent identity, and package versions, together, onto every live session's gossip self-advert -- one gossip frame per tick carrying whichever facts are actually known, rather than a separate frame per fact. Split out of wire-mesh-transport.ts's own WireMeshTransport class purely to keep that file under the repo's max-lines cap, the same reason mergeKnownDevices/findPresenceAdvert above already live here rather than there. A session that fails to send (mid-disconnect, most likely -- watchForDisconnect will independently notice and clean it up) is reported via onError and skipped, not allowed to stop the tick from reaching the rest of allSessions: a periodic broadcast to N peers is N independent operations, not one atomic unit. Unlike presence/hostedRooms/selfAgentAdvert, the versions extension is never actually absent (this side's own agent-comms package version is always known), so every tick this function is called for sends at least that one fact -- there is no "nothing to report" case left to short-circuit on. The hub's own session (agent-comms#156) is gated separately from every ordinary local-peer session in allSessions: local mesh trust is a different layer (connect_request/introduce approval already gated it before it ever joined allSessions), but the hub session is a broadcast to every connected hub peer, trusted or not, and would otherwise leak this side's own presence/hosted-rooms/self-agent/versions advert onto the hub regardless of GatewayTrust -- so this side's own advert waits on the same hasAny gate. It also waits for a visible agent (selfAgentAdvert is only ever defined for one): presence, hosted rooms and versions describe the agent and its process, so a hidden or unregistered store puts none of them on the hub, and a hidden agent is left with only the device advert every session opens with, which is what lets it be reached by device id. What the hub session does carry is reduced to what is safe to hand to strangers (presence, the agent's name, harness and membership proof, the public rooms it hosts by path and name, and the package versions): the hub relays it to every client that connects, so the working directory, process id, tags and rooms go only to peers this side is connected to directly (agent-comms#322). */
+export function readvertiseGossip(options: {
+  allSessions: ReadonlySet<GossipSession>;
+  hub: Readonly<HubOwnership>;
+  hasAnyTrustedGateway: () => boolean;
+  onError: ((error: Error) => void) | undefined;
+  getCurrentPresence: (() => AgentStatus | undefined) | undefined;
+  getHostedRooms: (() => readonly HostedRoomAdvert[]) | undefined;
+  getSelfAgentAdvert: (() => AgentSelfAdvert | undefined) | undefined;
+  /** Reads this side's own currently-running cc-peer version, when this process is fronting/bridging one -- folded into the same AGENT_COMMS_VERSION_GOSSIP_KEY advert as this side's own always-known agent-comms package version (agent-comms#198). Unlike presence/hostedRooms/selfAgentAdvert, agent-comms' own version is never genuinely absent (getOwnPackageVersion() always answers), so the versions extension is built and included unconditionally whenever this function runs at all -- there is no "no version to report" case the way there is for the other three optional facts. */
+  getCcPeerVersion: (() => string | undefined) | undefined;
+  /** The addresses this side serves a relay at (agent-comms#342), undefined while it serves none. */
+  getRelayOffer: () => readonly string[] | undefined;
+}): void {
+  const {
+    allSessions,
+    hub,
+    hasAnyTrustedGateway,
+    onError,
+    getCurrentPresence,
+    getHostedRooms,
+    getSelfAgentAdvert,
+    getCcPeerVersion,
+    getRelayOffer,
+  } = options;
+  const status = getCurrentPresence?.();
+  const selfAgentAdvert = getSelfAgentAdvert?.();
+  const ccPeerVersion = getCcPeerVersion?.();
+  const versionsAdvert: AgentCommsVersionsAdvert = {
+    agentComms: getOwnPackageVersion(),
+    ...(ccPeerVersion !== undefined ? { ccPeer: ccPeerVersion } : {}),
+  };
+  // A hub relays whatever it is given to every client that connects, so a hub session carries only what is safe for strangers: presence, the agent's summary, the public rooms it hosts (without their descriptions) and the package versions. Directly connected peers are ones this side deals with itself, and get everything.
+  const hubExtensions: Record<string, unknown> = {};
+  if (status !== undefined) hubExtensions[PRESENCE_GOSSIP_KEY] = status;
+  if (selfAgentAdvert !== undefined)
+    hubExtensions[AGENT_SELF_GOSSIP_KEY] =
+      summariseAgentSelfAdvert(selfAgentAdvert);
+  hubExtensions[AGENT_COMMS_VERSION_GOSSIP_KEY] = versionsAdvert;
+  const hostedRooms = getHostedRooms?.();
+  if (hostedRooms !== undefined)
+    hubExtensions[HOSTED_ROOMS_GOSSIP_KEY] = summariseHostedRooms(hostedRooms);
+  // Offered to hub clients as well as peers, since a trusted device on another machine learns the offer through the hub; that exposes the relay's addresses to every hub client, part of the metadata a relay's operator accepts in serving one.
+  const relayOffer = getRelayOffer();
+  if (relayOffer !== undefined) {
+    for (const [key, value] of Object.entries(
+      buildRelayOfferExtension(relayOffer),
+    )) {
+      hubExtensions[key] = value;
+    }
+  }
+  const peerExtensions: Record<string, unknown> = { ...hubExtensions };
+  if (hostedRooms !== undefined)
+    peerExtensions[HOSTED_ROOMS_GOSSIP_KEY] = hostedRooms;
+  if (selfAgentAdvert !== undefined)
+    peerExtensions[AGENT_SELF_GOSSIP_KEY] = selfAgentAdvert;
+  for (const session of allSessions) {
+    const viaHub = hub.ownsSession(session);
+    if (viaHub && (!hasAnyTrustedGateway() || selfAgentAdvert === undefined)) {
+      continue;
+    }
+    session
+      .sendGossipUpdate(viaHub ? hubExtensions : peerExtensions)
+      .catch((error: unknown) => {
+        onError?.(error instanceof Error ? error : new Error(String(error)));
+      });
+  }
+}
+
+/** Arms readvertiseGossip's own periodic tick, or does nothing at all when neither presence, hosted-rooms, nor self-agent-identity has a source -- WireMeshTransport's own constructor logic, split out here purely to keep that file under the repo's max-lines cap, the same reason mergeKnownDevices/findPresenceAdvert/readvertiseGossip above already live here rather than there. getCcPeerVersion never gates whether the interval starts at all (unlike the other three): it is only ever wired alongside getSelfAgentAdvert in real use (bridge-mesh.ts always supplies that one), so a construction site relying on getCcPeerVersion alone to start ticking isn't a real scenario worth its own branch. Unref'd immediately, matching every other timer this transport owns, so it never keeps the process alive on its own. */
+export function startGossipInterval(options: {
+  allSessions: ReadonlySet<GossipSession>;
+  hub: Readonly<Pick<HubSession, "ownsSession">>;
+  hasAnyTrustedGateway: () => boolean;
+  onError: ((error: Error) => void) | undefined;
+  getCurrentPresence: (() => AgentStatus | undefined) | undefined;
+  getHostedRooms: (() => readonly HostedRoomAdvert[]) | undefined;
+  getSelfAgentAdvert: (() => AgentSelfAdvert | undefined) | undefined;
+  getCcPeerVersion: (() => string | undefined) | undefined;
+  getRelayOffer: () => readonly string[] | undefined;
+  intervalMs: number;
+}): ReturnType<typeof setInterval> | undefined {
+  const {
+    allSessions,
+    hub,
+    hasAnyTrustedGateway,
+    onError,
+    getCurrentPresence,
+    getHostedRooms,
+    getSelfAgentAdvert,
+    getCcPeerVersion,
+    getRelayOffer,
+    intervalMs,
+  } = options;
+  if (
+    getCurrentPresence === undefined &&
+    getHostedRooms === undefined &&
+    getSelfAgentAdvert === undefined
+  ) {
+    return undefined;
+  }
+  const interval = setInterval(() => {
+    readvertiseGossip({
+      allSessions,
+      hub,
+      hasAnyTrustedGateway,
+      onError,
+      getCurrentPresence,
+      getHostedRooms,
+      getSelfAgentAdvert,
+      getCcPeerVersion,
+      getRelayOffer,
+    });
+  }, intervalMs);
+  interval.unref();
+  return interval;
+}

package/src/core/gossip-extensions.ts

@@ -0,0 +1,123 @@
+/**
+ * The domain-qualified gossip extension keys this package reads and writes on a peer's own gossiped advert, and the gossip-safe shapes two of them carry -- split out of wire-mesh-transport.ts (which writes them) so gossip-directory.ts, agent-registry.ts, room-lifecycle.ts, mesh-store.ts and hub-forwarding.ts (which read or merge them) no longer import their own vocabulary from the transport that depends on them, and to keep that file under the repo's max-lines cap. Also the shared home for the re-advertise cadence itself and the staleness window agent-registry.ts derives from it (agent-comms#301): both sides of "how fresh must a gossiped fact be to trust it" belong together, not split across the file that writes the cadence and the file that judges freshness against it.
+ */
+
+import type { Room } from "./types.js";
+
+const MS_PER_SECOND = 1000;
+
+/** How often a live device re-sends its own self-advert (WireMeshTransport's own presence-readvertisement timer) -- the producer half of agent-comms#301's own liveness signal. Chosen generously enough to avoid chattiness on an idle mesh while still keeping a remote peer's own picture of this device fresh well within the tens-of-minutes staleness window a status change is actually meaningful over. */
+const PRESENCE_READVERTISE_INTERVAL_SECONDS = 20;
+export const PRESENCE_READVERTISE_INTERVAL_MS =
+  PRESENCE_READVERTISE_INTERVAL_SECONDS * MS_PER_SECOND;
+
+/** Missed re-advertise ticks tolerated before a gossip-discovered device (one this side has never held a live session with, only ever heard about through the hub's directory) is presumed offline rather than trusted at whatever presence value its own last-heard advert happened to carry. 3 is the conventional "missed heartbeats" threshold distributed liveness checks converge on (enough to absorb one dropped gossip tick and one slow one without a false positive, not so many that a genuinely departed device is still reported reachable for minutes). There is no push notice of a device's own departure to react to instead (wire-mesh#230 covers the relay-pairing half of that; the hub's directory carries no equivalent for a lost connection) -- see agent-registry.ts's own listDiscoverableAgents for where this is applied. */
+const PRESENCE_STALE_MISSED_TICKS = 3;
+/** Default staleness window agent-comms#301's own check uses: agent-registry.ts's caller may override it (MeshStoreOptions.presenceStaleAfterMs), but every real construction site gets this unless it deliberately asks for something else. */
+export const DEFAULT_PRESENCE_STALE_AFTER_MS =
+  PRESENCE_READVERTISE_INTERVAL_MS * PRESENCE_STALE_MISSED_TICKS;
+
+/** The domain-qualified gossip extension key this transport reads/writes presence under, per wire-mesh's own gossip-extension-namespacing convention (spec/CONVENTIONS.md): `<domain>/<field>`, never a bare name a second application's own extension could collide with. */
+export const PRESENCE_GOSSIP_KEY = "presence/status";
+
+/** The domain-qualified gossip extension key this transport writes this side's own currently-hosted public/private rooms under -- the write half of P3.8's room-discovery replacement for createRoom's own broadcastPatch (agent-comms#48). Same namespacing convention as PRESENCE_GOSSIP_KEY. */
+export const HOSTED_ROOMS_GOSSIP_KEY = "room/hosted";
+
+/** The lightweight, gossip-safe shape a room advertises itself under: enough for a peer to display "this device hosts a discoverable room here" without exposing anything membership- or grant-related. Deliberately excludes secret rooms (never worth advertising at all) and every CRDT membership field a real Room carries -- a gossip-discovered entry is a hint pointing at a room to join, not a substitute for the real Room object join/admission still produces. */
+export interface HostedRoomAdvert {
+  path: string;
+  name: string;
+  type: "public" | "private";
+  description: string;
+}
+
+/** The rooms ownerId itself owns that are worth advertising, in the shape HostedRoomAdvert gives them: only its own public and private rooms. */
+export function hostedRoomAdverts(
+  rooms: ReadonlyMap<string, Room>,
+  ownerId: string,
+): HostedRoomAdvert[] {
+  const result: HostedRoomAdvert[] = [];
+  for (const room of rooms.values()) {
+    if (room.owner !== ownerId) continue;
+    if (room.type !== "public" && room.type !== "private") continue;
+    result.push({
+      path: room.id,
+      name: room.name,
+      type: room.type,
+      description: room.description,
+    });
+  }
+  return result;
+}
+
+/** What a hub is told about a room: where it is and what it is called, for a public room only. The description is left out because a project room's default one names the directory it was made for. */
+export type HostedRoomSummary = Pick<
+  HostedRoomAdvert,
+  "path" | "name" | "type"
+>;
+
+/** A hosted-room advert as read off the wire: the summary always, the description only when the sender shared it. */
+export type ReceivedHostedRoomAdvert = HostedRoomSummary &
+  Partial<Pick<HostedRoomAdvert, "description">>;
+
+/** The rooms that may be advertised through a hub: public ones, reduced to their summary. */
+export function summariseHostedRooms(
+  rooms: readonly HostedRoomAdvert[],
+): HostedRoomSummary[] {
+  return rooms
+    .filter((room) => room.type === "public")
+    .map(({ path, name, type }) => ({ path, name, type }));
+}
+
+/** The domain-qualified gossip extension key this transport writes this side's own agent identity facts under -- the write half of P3.8's eventual agent register/update/offline retirement (agent-comms#48). Same namespacing convention as PRESENCE_GOSSIP_KEY/HOSTED_ROOMS_GOSSIP_KEY. */
+export const AGENT_SELF_GOSSIP_KEY = "agent/self";
+
+/** What an agent advertises about itself to any peer, a hub included: enough for a peer with no prior record of this device to list it, and nothing about where or how it runs. */
+export interface AgentSelfSummary {
+  name: string;
+  harness: string;
+  /** A proof that this device's user principal vouches for it (membership-proof.ts), so a peer that trusts that principal trusts this device without it being listed individually. Absent until the first proof has been minted. */
+  membership?: string;
+  /** A proof that this device's machine vouches for it (membership-proof.ts, agent-comms#343), so a peer can tell which devices run on the same host and one that trusts the machine trusts this device. Absent until the first proof has been minted. Like membership, it names its issuer in the clear, so it is only ever sent in this advert, which a hidden or ghost agent never sends. */
+  machine?: string;
+  /** This device's machine's self display name claim (name-claim.ts, agent-comms#345), signed by the machine key, so a peer can show the name the machine chose for itself. Absent while the machine has no name. Travels with the machine proof, under the same visibility rule. */
+  machineName?: string;
+  /** This device's user principal's self display name claim (name-claim.ts, agent-comms#359), signed by the user key, so a peer can show the name the account chose for itself. Absent while the account has no name. Travels with the membership proof, under the same visibility rule. */
+  principalName?: string;
+}
+
+/** What a bridge knows about itself beyond its summary, and shares only with peers it deals with directly: a hub relays what it is given to every client that connects, so none of this goes to one. */
+export interface AgentSelfDetails {
+  cwd: string;
+  pid: number;
+  startedAt: string;
+  tags: string[];
+  subscribedRooms: string[];
+}
+
+/** The lightweight, gossip-safe shape an agent advertises itself under: enough for a peer with no prior local record of this device to construct a real AgentIdentity-shaped discovery entry. Deliberately excludes status (already carried separately under presence/status, no need to duplicate it here) and visibility (this field is only ever populated for a "visible" agent in the first place -- see MeshStore's own selfAgentAdvert getter -- so a discovered entry's visibility is always exactly "visible" by construction, never something this advert needs to assert itself). */
+export interface AgentSelfAdvert extends AgentSelfSummary, AgentSelfDetails {}
+
+/** An agent advert as read off the wire: the summary always, the details only when the sender chose to share them. */
+export type ReceivedAgentSelfAdvert = AgentSelfSummary &
+  Partial<AgentSelfDetails>;
+
+/** The part of an advert that is safe to publish through a hub. */
+export function summariseAgentSelfAdvert(
+  advert: Readonly<AgentSelfAdvert>,
+): AgentSelfSummary {
+  return {
+    name: advert.name,
+    harness: advert.harness,
+    ...(advert.membership !== undefined
+      ? { membership: advert.membership }
+      : {}),
+    ...(advert.machine !== undefined ? { machine: advert.machine } : {}),
+    ...(advert.machineName !== undefined
+      ? { machineName: advert.machineName }
+      : {}),
+    ...(advert.principalName !== undefined
+      ? { principalName: advert.principalName }
+      : {}),
+  };
+}

package/src/core/group-proofs.ts

@@ -0,0 +1,205 @@
+/**
+ * This device's membership proofs under both of its grouping issuers, its user principal (agent-comms#266) and its machine (agent-comms#343), and the self display name claims of both (agent-comms#345 for the machine, agent-comms#359 for the principal), with the checks for other devices' proofs and claims and the machine grouping and names list_agents shows. Split out of MeshStore, which hands it its identity, peer id, transport and error sink.
+ */
+
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type { MeshStoreIdentity } from "./mesh-store-shared.js";
+import type { MeshTransport } from "./transport.js";
+import { MembershipProofs } from "./membership-proofs.js";
+import { IssuerGrouping } from "./issuer-grouping.js";
+import { SelfNameClaim } from "./self-name-claim.js";
+import {
+  loadMachineDisplayName,
+  saveMachineDisplayName,
+} from "./machine-identity.js";
+import { readNameClaim } from "./gossip-directory.js";
+import { verifyNameClaim } from "./name-claim.js";
+import { loadUserDisplayName, saveUserDisplayName } from "./user-identity.js";
+import type { AgentSelfSummary } from "./gossip-extensions.js";
+import type {
+  IdentifiedMembershipProof,
+  MembershipProofVerdict,
+} from "./membership-proof.js";
+
+export interface GroupProofsDeps {
+  /** Throws if the store has no identity yet. */
+  getIdentity: () => MeshStoreIdentity;
+  /** This store's identity, or undefined before it is attached. */
+  peekIdentity: () => MeshStoreIdentity | undefined;
+  /** This device's own id (hex). */
+  getPeerId: () => string;
+  /** Throws if the store has no transport yet. */
+  requireTransport: () => MeshTransport;
+  onError: (error: Error) => void;
+}
+
+export class GroupProofs {
+  private readonly principal: MembershipProofs;
+  private readonly machine: MembershipProofs;
+  private readonly machineGrouping: IssuerGrouping;
+  private readonly principalGrouping: IssuerGrouping;
+  private readonly machineName: SelfNameClaim;
+  private readonly principalName: SelfNameClaim;
+  private readonly getIdentity: () => MeshStoreIdentity;
+
+  constructor(deps: Readonly<GroupProofsDeps>) {
+    this.getIdentity = deps.getIdentity;
+    const shared = {
+      getIdentity: deps.getIdentity,
+      getPeerId: deps.getPeerId,
+      onError: deps.onError,
+    };
+    this.principal = new MembershipProofs({
+      ...shared,
+      issuerOf: (identity) => identity.userIdentity,
+    });
+    this.machine = new MembershipProofs({
+      ...shared,
+      issuerOf: (identity) => identity.machineIdentity,
+    });
+    const grouping = {
+      listKnownDevices: () =>
+        deps.requireTransport().listKnownDevices?.() ?? [],
+      identify: async (claim: Readonly<{ proof: string; deviceHex: string }>) =>
+        this.identify(claim),
+      getPeerId: deps.getPeerId,
+      onError: deps.onError,
+      verifyName: async (
+        claim: Readonly<{ claim: string; subject: string }>,
+      ) => {
+        const { identity, clock } = deps.getIdentity();
+        return verifyNameClaim({
+          claim: claim.claim,
+          subject: claim.subject,
+          identity,
+          clock,
+        });
+      },
+    };
+    this.machineGrouping = new IssuerGrouping({
+      ...grouping,
+      field: "machine",
+      readNameClaim: (advert) => readNameClaim(advert, "machineName"),
+      getOwnIssuerId: () => {
+        const identity = deps.peekIdentity();
+        return identity === undefined
+          ? undefined
+          : deviceIdToHex(identity.machineIdentity.deviceId);
+      },
+      getOwnName: () => {
+        const identity = deps.peekIdentity();
+        return identity === undefined
+          ? undefined
+          : loadMachineDisplayName(identity.machineIdentityOptions);
+      },
+    });
+    this.principalGrouping = new IssuerGrouping({
+      ...grouping,
+      field: "membership",
+      readNameClaim: (advert) => readNameClaim(advert, "principalName"),
+      getOwnIssuerId: () => {
+        const identity = deps.peekIdentity();
+        return identity === undefined
+          ? undefined
+          : deviceIdToHex(identity.userIdentity.deviceId);
+      },
+      getOwnName: () => {
+        const identity = deps.peekIdentity();
+        return identity === undefined
+          ? undefined
+          : loadUserDisplayName(identity.userIdentityOptions);
+      },
+    });
+    this.machineName = new SelfNameClaim({
+      getIdentity: deps.getIdentity,
+      issuerOf: (identity) => identity.machineIdentity,
+      loadName: (identity) =>
+        loadMachineDisplayName(identity.machineIdentityOptions),
+      onError: deps.onError,
+    });
+    this.principalName = new SelfNameClaim({
+      getIdentity: deps.getIdentity,
+      issuerOf: (identity) => identity.userIdentity,
+      loadName: (identity) => loadUserDisplayName(identity.userIdentityOptions),
+      onError: deps.onError,
+    });
+  }
+
+  /** Whether a gossiped proof shows that deviceHex belongs to the account this store holds, judged against the user principal's own proofs (MembershipProofs.isAccountMember). */
+  async isAccountMember(
+    claim: Readonly<{ proof: string; deviceHex: string }>,
+  ): Promise<boolean> {
+    return this.principal.isAccountMember(claim);
+  }
+
+  /** The agent/self advert fields carrying this device's current proofs, each absent until it has first been minted. */
+  advertFields(): Pick<
+    AgentSelfSummary,
+    "membership" | "machine" | "machineName" | "principalName"
+  > {
+    const membership = this.principal.current();
+    const machine = this.machine.current();
+    const machineName = this.machineName.current();
+    const principalName = this.principalName.current();
+    return {
+      ...(membership !== undefined ? { membership } : {}),
+      ...(machine !== undefined ? { machine } : {}),
+      ...(machineName !== undefined ? { machineName } : {}),
+      ...(principalName !== undefined ? { principalName } : {}),
+    };
+  }
+
+  /** Starts keeping both proofs and both name claims fresh; called once the store's identity is attached. */
+  start(): void {
+    this.principal.start();
+    this.machine.start();
+    this.machineName.start();
+    this.principalName.start();
+  }
+
+  stop(): void {
+    this.principal.stop();
+    this.machine.stop();
+    this.machineName.stop();
+    this.principalName.stop();
+  }
+
+  /** Sets (or, given undefined, clears) this machine's self display name and re-mints its claim now rather than on the next refresh. Throws if the store has no identity yet. */
+  async saveMachineName(name: string | undefined): Promise<void> {
+    saveMachineDisplayName(this.getIdentity().machineIdentityOptions, name);
+    return this.machineName.refresh();
+  }
+
+  /** Sets (or, given undefined, clears) this account's self display name and re-mints its claim now rather than on the next refresh. Throws if the store has no identity yet. */
+  async saveUserName(name: string | undefined): Promise<void> {
+    saveUserDisplayName(this.getIdentity().userIdentityOptions, name);
+    return this.principalName.refresh();
+  }
+
+  /** Whether a gossiped proof shows that issuerHex, a principal or a machine, vouches for deviceHex. */
+  async verify(
+    claim: Readonly<{ proof: string; deviceHex: string; issuerHex: string }>,
+  ): Promise<MembershipProofVerdict> {
+    return this.principal.verify(claim);
+  }
+
+  /** Which issuer a gossiped proof shows vouching for deviceHex. Verification does not depend on which issuer an instance mints under, so the principal's instance serves for both. */
+  async identify(
+    claim: Readonly<{ proof: string; deviceHex: string }>,
+  ): Promise<IdentifiedMembershipProof> {
+    return this.principal.identify(claim);
+  }
+
+  /** The machine (hex) of each device this side can place on one, keyed by device id. */
+  async machinesByDevice(): Promise<Map<string, string>> {
+    return this.machineGrouping.issuersByDevice();
+  }
+
+  /** The self display name of each grouping issuer this side can place a device under, machines and user principals together, keyed by issuer id. The two kinds of id never collide, since each is the hash of a different key. */
+  async issuerNames(): Promise<Map<string, string>> {
+    return new Map([
+      ...(await this.machineGrouping.issuerNames()),
+      ...(await this.principalGrouping.issuerNames()),
+    ]);
+  }
+}