agent-comms 8.15.9 → 8.15.11

package/src/core/user-identity.ts

@@ -0,0 +1,290 @@
+/**
+ * Persistent user-principal identity: a single keypair scoped to this machine account rather than any one (harness, cwd) bridge slot, the root issuer agent-comms#160 introduces, so a user principal can mint capability tokens to the devices it owns, independent of which bridge process happens to be running. See identity-store.ts for the per-slot device identity every bridge already has; this is deliberately a separate, shared identity, not a variant of it.
+ *
+ * Stored at ~/.agent-comms/user-identity.json (mode 0600), sibling to but distinct from any identity-<harness>--<cwd>.json slot file and to the machine identity (machine-identity.ts). Loading, creation and renewal are issuer-identity-file.ts's, shared with the machine identity; this module adds the principal's own issued-grant bookkeeping to the same record.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveDataDir } from "./data-directory.js";
+import type { AccountContents } from "./account-bundle.js";
+import { certifyKeyPair } from "./identity.js";
+import type { PeerIdentity } from "./identity.js";
+import { CommsError } from "./store.js";
+import {
+  isStoredIssuerKey,
+  issuerKeyRecord,
+  issuerPeerIdentity,
+  loadOrCreateIssuerIdentity,
+  readIssuerRecord,
+  writeIssuerRecord,
+  type StoredIssuerKey,
+} from "./issuer-identity-file.js";
+
+export interface UserIdentityOptions {
+  /** Directory override for tests; defaults to ~/.agent-comms, the same base directory identity-store.ts's own per-slot files live in. */
+  dir?: string;
+}
+
+interface StoredUserIdentity extends StoredIssuerKey {
+  /** The name the account asserts for itself (agent-comms#359), signed by the user key into every device's advert. Belongs to the account, so it is exported with the key and handed over by a join, unlike the writer nonce. */
+  displayName?: string;
+  /** This machine's writer nonce for the account's replicated grant ledger (account-ledger.ts), base64. Belongs to the machine, not the account: it is never exported with the key, since two machines appending under one nonce would share a writer log and fork it. */
+  ledgerWriter?: string;
+  /** The token-id (base64) of each group:member grant this principal issued, keyed by the admitted device's hex id, as builds before the replicated ledger kept them. Read only to migrate them into the ledger on first start (account-ledger-store.ts), then removed. */
+  issuedDeviceGrants?: Record<string, string>;
+  /** The token-id (base64) of each dm:send grant this principal issued, keyed by the bearer's hex id, as builds before the replicated ledger kept them. Migrated and removed exactly like issuedDeviceGrants. */
+  issuedDmGrants?: Record<string, string>;
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  if (typeof value !== "object" || value === null) return false;
+  return Object.values(value).every((v) => typeof v === "string");
+}
+
+function isStoredUserIdentity(value: unknown): value is StoredUserIdentity {
+  if (!isStoredIssuerKey(value)) return false;
+  if (
+    "issuedDeviceGrants" in value &&
+    !isStringRecord(value.issuedDeviceGrants)
+  )
+    return false;
+  if ("issuedDmGrants" in value && !isStringRecord(value.issuedDmGrants))
+    return false;
+  if ("ledgerWriter" in value && typeof value.ledgerWriter !== "string")
+    return false;
+  if ("displayName" in value && typeof value.displayName !== "string")
+    return false;
+  return true;
+}
+
+/** The directory the user identity and every other per-account file on this machine live in. */
+export function userIdentityDir(
+  options?: Readonly<UserIdentityOptions>,
+): string {
+  return resolveDataDir({ dir: options?.dir });
+}
+
+function userIdentityFile(options?: Readonly<UserIdentityOptions>): string {
+  return path.join(userIdentityDir(options), "user-identity.json");
+}
+
+function writeStoredUserIdentity(
+  file: string,
+  stored: Readonly<StoredUserIdentity>,
+): void {
+  writeIssuerRecord(file, stored);
+}
+
+/** Reads this principal's raw stored record, or undefined if the file is missing; throws if it exists but is unusable (issuer-identity-file.ts). Used by the issued-grant functions below to read-modify-write only their own field, leaving the persisted key material exactly as it is. */
+function readStoredUserIdentity(file: string): StoredUserIdentity | undefined {
+  return readIssuerRecord(file, isStoredUserIdentity);
+}
+
+/**
+ * Loads the persisted user-principal identity, creating it on first use (issuer-identity-file.ts: exclusive create, renewal in place that keeps the issued-grant bookkeeping, an unusable file refused rather than regenerated).
+ */
+export function loadOrCreateUserIdentity(
+  options?: Readonly<UserIdentityOptions>,
+): PeerIdentity {
+  return loadOrCreateIssuerIdentity(
+    userIdentityFile(options),
+    isStoredUserIdentity,
+  );
+}
+
+/** Reads the persisted record, throwing if the principal has never been created: every ledger function below needs the key it belongs to. */
+function requireStoredUserIdentity(file: string): StoredUserIdentity {
+  const stored = readStoredUserIdentity(file);
+  if (stored === undefined) {
+    throw new Error(
+      `no user identity persisted yet; call loadOrCreateUserIdentity first (${file})`,
+    );
+  }
+  return stored;
+}
+
+/** This machine's writer nonce for the account ledger, generated and persisted on first use. Two processes racing to create it can each end up with a different one; that is harmless, since each writes its own writer log and the ledger is the union of every writer log the account key recognises. What must never happen is two machines sharing one, which is why it is not part of an exported account. */
+export function loadOrCreateLedgerWriterNonce(
+  options: Readonly<UserIdentityOptions> | undefined,
+  generate: () => Uint8Array,
+): Uint8Array<ArrayBuffer> {
+  const file = userIdentityFile(options);
+  const stored = requireStoredUserIdentity(file);
+  if (stored.ledgerWriter !== undefined) {
+    return Uint8Array.from(Buffer.from(stored.ledgerWriter, "base64"));
+  }
+  const nonce = Uint8Array.from(generate());
+  writeStoredUserIdentity(file, {
+    ...stored,
+    ledgerWriter: Buffer.from(nonce).toString("base64"),
+  });
+  return nonce;
+}
+
+/** One grant a build before the replicated ledger recorded in user-identity.json. */
+export interface LegacyIssuedGrant {
+  kind: "device" | "dm";
+  subject: string;
+  tokenId: Uint8Array<ArrayBuffer>;
+}
+
+function legacyEntries(
+  kind: LegacyIssuedGrant["kind"],
+  record: Readonly<Record<string, string>> | undefined,
+): LegacyIssuedGrant[] {
+  return Object.entries(record ?? {}).map(([subject, encoded]) => ({
+    kind,
+    subject,
+    tokenId: Uint8Array.from(Buffer.from(encoded, "base64")),
+  }));
+}
+
+/** Every issued grant a pre-ledger build left in user-identity.json, still waiting to be migrated into the replicated ledger. Empty once migrated, or for an identity created by this build. */
+export function readLegacyIssuedGrants(
+  options: Readonly<UserIdentityOptions> | undefined,
+): LegacyIssuedGrant[] {
+  const stored = requireStoredUserIdentity(userIdentityFile(options));
+  return [
+    ...legacyEntries("device", stored.issuedDeviceGrants),
+    ...legacyEntries("dm", stored.issuedDmGrants),
+  ];
+}
+
+function withoutMigrated(
+  record: Readonly<Record<string, string>> | undefined,
+  kind: LegacyIssuedGrant["kind"],
+  migrated: readonly Readonly<LegacyIssuedGrant>[],
+): Record<string, string> | undefined {
+  if (record === undefined) return undefined;
+  const done = new Set(
+    migrated
+      .filter((grant) => grant.kind === kind)
+      .map(
+        (grant) =>
+          `${grant.subject}:${Buffer.from(grant.tokenId).toString("base64")}`,
+      ),
+  );
+  const remaining = Object.entries(record).filter(
+    ([subject, encoded]) => !done.has(`${subject}:${encoded}`),
+  );
+  return remaining.length === 0 ? undefined : Object.fromEntries(remaining);
+}
+
+/** Removes exactly the given legacy grants from user-identity.json once they are in the ledger. The file is re-read first, so a grant written meanwhile by an older build still running on this machine stays for the next migration rather than being lost. */
+export function clearLegacyIssuedGrants(
+  options: Readonly<UserIdentityOptions> | undefined,
+  migrated: readonly Readonly<LegacyIssuedGrant>[],
+): void {
+  const file = userIdentityFile(options);
+  const { issuedDeviceGrants, issuedDmGrants, ...rest } =
+    requireStoredUserIdentity(file);
+  const device = withoutMigrated(issuedDeviceGrants, "device", migrated);
+  const dm = withoutMigrated(issuedDmGrants, "dm", migrated);
+  writeStoredUserIdentity(file, {
+    ...rest,
+    ...(device === undefined ? {} : { issuedDeviceGrants: device }),
+    ...(dm === undefined ? {} : { issuedDmGrants: dm }),
+  });
+}
+
+/** The name this account asserts for itself, or undefined when it has none or the account has not been created yet. Read from disk on every call, so a name set by any bridge on this machine is seen by all of them. */
+export function loadUserDisplayName(
+  options?: Readonly<UserIdentityOptions>,
+): string | undefined {
+  return readStoredUserIdentity(userIdentityFile(options))?.displayName;
+}
+
+/** Sets (or, given undefined, clears) the name this account asserts for itself, keeping the key material and every other field. Throws if the account has not been created yet. */
+export function saveUserDisplayName(
+  options: Readonly<UserIdentityOptions> | undefined,
+  displayName: string | undefined,
+): void {
+  const file = userIdentityFile(options);
+  const next: StoredUserIdentity = { ...requireStoredUserIdentity(file) };
+  if (displayName === undefined) delete next.displayName;
+  else next.displayName = displayName;
+  writeStoredUserIdentity(file, next);
+}
+
+/** What an export or a join carries of the account: its PEM private key and the name it asserts for itself, if any. Throws if the principal has never been created. */
+export function readAccountContents(
+  options: Readonly<UserIdentityOptions> | undefined,
+): AccountContents {
+  const { privateKey, displayName } = requireStoredUserIdentity(
+    userIdentityFile(options),
+  );
+  return {
+    privateKey,
+    ...(displayName === undefined ? {} : { displayName }),
+  };
+}
+
+/** Where a replaced account's record is kept when a different account is imported over it: its key is still the only one that can revoke what it issued, so it is set aside rather than destroyed. */
+export function replacedUserIdentityFile(
+  options: Readonly<UserIdentityOptions> | undefined,
+  replaced: Readonly<PeerIdentity>,
+): string {
+  return path.join(
+    userIdentityDir(options),
+    `user-identity.replaced-${Buffer.from(replaced.deviceId).toString("hex")}.json`,
+  );
+}
+
+/** Keeps `record`, the account being replaced in `currentFile`, at `replacedFile`. A record already there for the same key is from an earlier import that replaced this same account; it is overwritten with the current one, which may carry a renewed certificate, written to a temporary file and renamed into place so the set-aside record is never seen half-written; a file there that does not parse holds no usable record and is overwritten too. A record there holding a different key would be lost by overwriting it, and the file name derives from the key, so that file is damaged: CommsError ACCOUNT_SET_ASIDE_CONFLICT names both files rather than touching either. */
+function setAside(
+  replacedFile: string,
+  record: Readonly<StoredUserIdentity>,
+  currentFile: string,
+): void {
+  const earlier = readStoredUserIdentity(replacedFile);
+  if (earlier !== undefined && earlier.privateKey !== record.privateKey) {
+    throw new CommsError(
+      `Cannot set aside the account in ${currentFile}: ${replacedFile} already exists and holds a different key. Move one of them away and import again.`,
+      "ACCOUNT_SET_ASIDE_CONFLICT",
+    );
+  }
+  writeIssuerRecord(replacedFile, record);
+}
+
+/**
+ * Makes this machine hold the account whose contents are given, the deliberate copy that lets one principal span machines. The key is re-certified here (the device-id, which is the account's identity, depends only on the key). The name the account asserts for itself comes with it; an import carrying none leaves the name of the account already held untouched. This machine's own ledger writer nonce is kept, since it belongs to the machine, not the account. A different account already held here is moved aside to replacedUserIdentityFile first, never overwritten (see setAside for a record already set aside there); importing the account already held changes nothing but that name. Returns the imported identity and, when one was replaced, where the old record now is.
+ */
+export function importAccountKey(
+  options: Readonly<UserIdentityOptions> | undefined,
+  contents: Readonly<AccountContents>,
+): { identity: PeerIdentity; replacedFile?: string } {
+  const file = userIdentityFile(options);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const imported = certifyKeyPair(contents.privateKey);
+  const named = (record: StoredUserIdentity): StoredUserIdentity => ({
+    ...record,
+    ...(contents.displayName === undefined
+      ? {}
+      : { displayName: contents.displayName }),
+  });
+  const existing = readStoredUserIdentity(file);
+  if (existing === undefined) {
+    writeStoredUserIdentity(file, named(issuerKeyRecord(imported)));
+    return { identity: imported };
+  }
+  const current = issuerPeerIdentity(existing);
+  if (Buffer.from(current.deviceId).equals(Buffer.from(imported.deviceId))) {
+    if (contents.displayName !== undefined) {
+      writeStoredUserIdentity(file, named(existing));
+    }
+    return { identity: current };
+  }
+  const replacedFile = replacedUserIdentityFile(options, current);
+  setAside(replacedFile, existing, file);
+  writeStoredUserIdentity(
+    file,
+    named({
+      ...issuerKeyRecord(imported),
+      ...(existing.ledgerWriter === undefined
+        ? {}
+        : { ledgerWriter: existing.ledgerWriter }),
+    }),
+  );
+  return { identity: imported, replacedFile };
+}

package/src/core/vapid.ts

@@ -0,0 +1,81 @@
+/**
+ * VAPID key generation for Web Push (RFC 8292).
+ *
+ * Generates a P-256 EC key pair once per process lifetime and caches it
+ * in memory. The public key is shared with the PWA client so it can
+ * create push subscriptions; the private key signs push requests.
+ */
+
+import * as crypto from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface VapidKeys {
+  /** Base64url-encoded uncompressed P-256 public key (65 bytes). */
+  publicKey: string;
+  /** Base64url-encoded P-256 private key (32 bytes). */
+  privateKey: string;
+}
+
+// ---------------------------------------------------------------------------
+// Cached singleton
+// ---------------------------------------------------------------------------
+
+let cachedKeys: VapidKeys | undefined;
+
+/** Length in bytes of an uncompressed P-256 public key point (0x04 prefix + 32-byte X + 32-byte Y). */
+const P256_PUBLIC_KEY_BYTES = 65;
+
+/** Length in bytes of a P-256 private scalar. */
+const P256_PRIVATE_KEY_BYTES = 32;
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate or return cached VAPID keys.
+ *
+ * Uses Node.js `crypto.generateKeyPairSync` with P-256, extracts the
+ * raw 65-byte uncompressed public point and the 32-byte private scalar,
+ * and base64url-encodes both per RFC 8291.
+ */
+export function generateVapidKeys(): VapidKeys {
+  if (cachedKeys) return cachedKeys;
+
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ec", {
+    namedCurve: "P-256",
+  });
+
+  // Export public key as raw DER, extract the 65-byte uncompressed point.
+  // SPKI DER for P-256 has a 26-byte header before the 65-byte point.
+  const pubDer = publicKey.export({ type: "spki", format: "der" });
+  const publicKeyBuffer = pubDer.subarray(
+    pubDer.length - P256_PUBLIC_KEY_BYTES,
+  );
+
+  // Export private key as PKCS8 DER, extract the 32-byte private scalar.
+  // PKCS8 DER for P-256 has a 39-byte header before the 32-byte scalar.
+  // The scalar is the last 32 bytes (after the leading zero pad byte).
+  const privDer = privateKey.export({ type: "pkcs8", format: "der" });
+  const privateKeyBuffer = privDer.subarray(
+    privDer.length - P256_PRIVATE_KEY_BYTES,
+  );
+
+  cachedKeys = {
+    publicKey: base64url(publicKeyBuffer),
+    privateKey: base64url(privateKeyBuffer),
+  };
+
+  return cachedKeys;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function base64url(buffer: Buffer): string {
+  return buffer.toString("base64url");
+}

package/src/core/version-check.ts

@@ -0,0 +1,147 @@
+/**
+ * Detects when a newer agent-comms release exists on npm than the one currently running -- see issue #166. A stale checkout (e.g. a manually pulled git checkout left behind while npm moves on) surfaces its own drift via CommsTool's whoami/update output (see tool.ts) rather than silently splitting mesh generations. Every failure mode (offline, registry down, timeout, malformed response) is swallowed here: a bridge with no network access behaves exactly as if no newer release were known, never as an error.
+ */
+
+/** Minimal shape of a fetch() call, injectable so tests never need a real network round trip or a global fetch stub. */
+export type FetchLike = (
+  input: string,
+  init?: Readonly<RequestInit>,
+) => Promise<Response>;
+
+const NPM_REGISTRY_LATEST_VERSION_URL =
+  "https://registry.npmjs.org/agent-comms/latest";
+
+/** How long a single npm registry lookup may take before it's treated as a failure -- generous for a slow connection, short enough that a hung request can never pile up across successive interval checks. */
+const REGISTRY_FETCH_TIMEOUT_MS = 5000;
+
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+const CHECK_INTERVAL_HOURS = 6;
+
+/** How often VersionDriftChecker re-checks npm once started. Deliberately slow: this is a background courtesy warning that piggybacks on whoami/update output (see tool.ts), not a thing any caller waits on, so there's no benefit to checking more often than a bridge process is likely to stay running for. */
+export const DEFAULT_CHECK_INTERVAL_MS =
+  CHECK_INTERVAL_HOURS * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+interface NpmRegistryLatestResponse {
+  version: string;
+}
+
+function isNpmRegistryLatestResponse(
+  value: unknown,
+): value is NpmRegistryLatestResponse {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("version" in value)) return false;
+  return typeof value.version === "string";
+}
+
+/** Fetches the "latest" dist-tag version currently published to npm, or undefined on any failure (offline, timeout, non-2xx, malformed body) -- callers never need their own try/catch around this. */
+export async function fetchLatestPublishedVersion(options?: {
+  registryUrl?: string;
+  fetchImpl?: FetchLike;
+}): Promise<string | undefined> {
+  const { registryUrl = NPM_REGISTRY_LATEST_VERSION_URL, fetchImpl = fetch } =
+    options ?? {};
+  try {
+    const response = await fetchImpl(registryUrl, {
+      signal: AbortSignal.timeout(REGISTRY_FETCH_TIMEOUT_MS),
+    });
+    if (!response.ok) return undefined;
+    const body: unknown = await response.json();
+    if (!isNpmRegistryLatestResponse(body)) return undefined;
+    return body.version;
+  } catch {
+    return undefined;
+  }
+}
+
+const VERSION_CORE_PART_COUNT = 3;
+
+/** Parses a "x.y.z[-prerelease][+build]" version string's numeric major/minor/patch parts, ignoring any prerelease/build suffix -- agent-comms releases are always plain x.y.z (semantic-release's own default), so a fuller semver-precedence comparator (prerelease ordering, build-metadata rules) would be speculative generality with no real input that needs it. Returns undefined for a string that isn't three dot-separated non-negative integers. */
+function parseVersionCore(
+  version: string,
+): [number, number, number] | undefined {
+  const core = version.split(/[+-]/, 1)[0] ?? "";
+  const parts = core.split(".");
+  if (parts.length !== VERSION_CORE_PART_COUNT) return undefined;
+  const major = Number(parts[0]);
+  const minor = Number(parts[1]);
+  const patch = Number(parts[2]);
+  const isValid = [major, minor, patch].every(
+    (part) => Number.isInteger(part) && part >= 0,
+  );
+  if (!isValid) return undefined;
+  return [major, minor, patch];
+}
+
+/** True when latest is a strictly greater release than current, by major.minor.patch precedence. Returns false for either string that doesn't parse as a plain x.y.z version -- a malformed comparison has no safe "yes, warn" answer. */
+export function isNewerVersion(current: string, latest: string): boolean {
+  const currentCore = parseVersionCore(current);
+  const latestCore = parseVersionCore(latest);
+  if (currentCore === undefined || latestCore === undefined) return false;
+  const [currentMajor, currentMinor, currentPatch] = currentCore;
+  const [latestMajor, latestMinor, latestPatch] = latestCore;
+  if (latestMajor !== currentMajor) return latestMajor > currentMajor;
+  if (latestMinor !== currentMinor) return latestMinor > currentMinor;
+  return latestPatch > currentPatch;
+}
+
+export interface VersionDriftCheckerOptions {
+  currentVersion: string;
+  intervalMs?: number;
+  fetchLatestVersion?: () => Promise<string | undefined>;
+}
+
+/**
+ * Periodically (and once immediately on start()) compares the running version against npm's published "latest" dist-tag, caching the most recent successful lookup so CommsTool's whoami/update output can surface a "newer release available" note without either of them ever waiting on a network call. A failed check leaves the previously cached result untouched -- see this file's own header for why a failure is never surfaced as an error.
+ */
+export class VersionDriftChecker {
+  private readonly currentVersion: string;
+  private readonly intervalMs: number;
+  private readonly fetchLatestVersion: () => Promise<string | undefined>;
+  private latestKnownVersion: string | undefined;
+  private timer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(options: Readonly<VersionDriftCheckerOptions>) {
+    this.currentVersion = options.currentVersion;
+    this.intervalMs = options.intervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
+    this.fetchLatestVersion =
+      options.fetchLatestVersion ?? (async () => fetchLatestPublishedVersion());
+  }
+
+  /** Runs one check immediately (fire-and-forget -- start() itself never waits on the network) and schedules a recurring check every intervalMs. The interval is unref'd so it can never keep a bridge process alive on its own. No-op if already started. */
+  start(): void {
+    if (this.timer !== undefined) return;
+    void this.check();
+    this.timer = setInterval(() => {
+      void this.check();
+    }, this.intervalMs);
+    this.timer.unref();
+  }
+
+  /** Stops the recurring check, if running. Safe to call even if start() was never called. */
+  stop(): void {
+    if (this.timer !== undefined) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  /** The most recently observed newer release, or undefined when none is known -- either no successful check has completed yet, or the running version is already current (or ahead). */
+  getNewerVersionIfAny(): string | undefined {
+    if (this.latestKnownVersion === undefined) return undefined;
+    return isNewerVersion(this.currentVersion, this.latestKnownVersion)
+      ? this.latestKnownVersion
+      : undefined;
+  }
+
+  /** Runs a single check, tolerating a rejection from a caller-supplied fetchLatestVersion as well as the soft-failure (undefined) contract fetchLatestPublishedVersion's own default already guarantees -- start()'s own fire-and-forget call, and the recurring interval callback, both rely on this never throwing regardless of which fetch implementation is wired in. */
+  private async check(): Promise<void> {
+    try {
+      const latest = await this.fetchLatestVersion();
+      if (latest !== undefined) this.latestKnownVersion = latest;
+    } catch {
+      // Swallowed deliberately -- see this file's own header on failing soft.
+    }
+  }
+}

package/src/core/version-report-actions.ts

@@ -0,0 +1,79 @@
+/**
+ * CommsTool's version-reporting formatting and the query_version action handler (agent-comms#198) -- split out of tool.ts purely to keep that file under the repo's max-lines cap, the same reason gateway-trust-actions.ts and its siblings were split out before it. Free functions over MeshOnlyFeatures's own version methods rather than class methods, since CommsTool owns no state of its own for this concern -- every one of these is a pure translation from whatever the store/local process knows into either a CommsResult or a formatted line, mirroring gateway-trust-actions.ts's own shape.
+ */
+import type { CommsAction } from "./types.js";
+import type { CommsResult, MeshOnlyFeatures } from "./tool.js";
+import { notMeshBacked } from "./tool.js";
+import { getOwnPackageVersion } from "./package-version.js";
+import { getWireMeshCoreVersion } from "./wire-mesh-core-version.js";
+
+/** The slice of MeshOnlyFeatures the functions below actually need. */
+export type VersionReportStore = Pick<
+  MeshOnlyFeatures,
+  | "queryVersion"
+  | "getPeerAgentCommsVersion"
+  | "getPeerWireMeshCoreVersion"
+  | "getPeerCcPeerVersion"
+>;
+
+/** Answers query_version by asking the target device for its own, currently-running wire-mesh-core version live, right now -- the cache-bust counterpart to whatever it last gossiped. */
+export async function handleQueryVersion(
+  store: Readonly<VersionReportStore>,
+  action: CommsAction & { action: "query_version" },
+): Promise<CommsResult> {
+  if (!store.queryVersion) return notMeshBacked("query_version");
+  const result = await store.queryVersion(action.device);
+  if ("error" in result) {
+    return {
+      content: `Failed to query ${action.device}'s version: ${result.error}`,
+      isError: true,
+    };
+  }
+  return {
+    content: `${action.device} is running wire-mesh-core ${result.version}.`,
+    isError: false,
+  };
+}
+
+/** This process's own wire-mesh-core version line, plus a cc-peer version line when getCcPeerVersion answers one -- whoami's own trailing version lines, appended after its existing "Version: ..." line. */
+export function formatSelfVersionLines(
+  getCcPeerVersion: (() => string | undefined) | undefined,
+): string[] {
+  const lines = [`Wire-mesh-core: ${getWireMeshCoreVersion()}`];
+  const ccPeerVersion = getCcPeerVersion?.();
+  if (ccPeerVersion !== undefined) lines.push(`Cc-peer: ${ccPeerVersion}`);
+  return lines;
+}
+
+/** The trailing ", wireMeshCore=..., ccPeer=..." fragment update's own single summary line appends after its existing "version=..." field. */
+export function formatSelfVersionSuffix(
+  getCcPeerVersion: (() => string | undefined) | undefined,
+): string {
+  const ccPeerVersion = getCcPeerVersion?.();
+  const ccPeerSuffix =
+    ccPeerVersion !== undefined ? `, ccPeer=${ccPeerVersion}` : "";
+  return `, wireMeshCore=${getWireMeshCoreVersion()}${ccPeerSuffix}`;
+}
+
+/** One listed agent's own "agent-comms X, wire-mesh-core Y[, cc-peer Z]" summary for list_agents -- read locally (this process's own installed versions) for the requester's own entry, or from whatever deviceId last gossiped for every other listed agent. "unknown" stands in for a value neither source has (a peer that hasn't gossiped yet, or is running an agent-comms/wire-mesh-core predating this feature) -- cc-peer is omitted entirely rather than shown as "unknown", since it is only ever present at all while that specific device is actually fronting/bridging cc-peer. */
+export function formatListedAgentVersions(
+  store: Readonly<VersionReportStore>,
+  deviceId: string,
+  isSelf: boolean,
+  getCcPeerVersion: (() => string | undefined) | undefined,
+): string {
+  const agentCommsVersion = isSelf
+    ? getOwnPackageVersion()
+    : store.getPeerAgentCommsVersion?.(deviceId);
+  const wireMeshCoreVersion = isSelf
+    ? getWireMeshCoreVersion()
+    : store.getPeerWireMeshCoreVersion?.(deviceId);
+  const ccPeerVersion = isSelf
+    ? getCcPeerVersion?.()
+    : store.getPeerCcPeerVersion?.(deviceId);
+  return [
+    `agent-comms ${agentCommsVersion ?? "unknown"}`,
+    `wire-mesh-core ${wireMeshCoreVersion ?? "unknown"}`,
+    ...(ccPeerVersion !== undefined ? [`cc-peer ${ccPeerVersion}`] : []),
+  ].join(", ");
+}

package/src/core/web-beacon.ts

@@ -0,0 +1,31 @@
+/**
+ * The LAN web UI beacon's own type and payload (agent-comms#346, receiving side agent-comms#353): the one datagram shape both the sender (bridges/user/web/web-beacon.ts) and every listener on the first-contact port agree on, kept in core so first-contact can recognise it without depending on a bridge.
+ */
+
+/** The beacon type, distinct from first-contact's own `agent-comms-beacon`. */
+export const WEB_BEACON_TYPE = "agent-comms-web-beacon";
+
+/** What a beacon carries: the broadcasting bridge's peer id and the port its web UI listens on, and nothing else. The receiver learns the host from the datagram's source address, and the access token is never advertised, so seeing the beacon grants no access. */
+export interface WebBeaconPayload {
+  type: typeof WEB_BEACON_TYPE;
+  peerId: string;
+  webPort: number;
+}
+
+/** The exclusive upper bound of the UDP port space: a port is a 16-bit integer. */
+const MAX_UDP_PORT = 0x10000;
+
+/** Narrows an untrusted datagram body into a WebBeaconPayload. */
+export function isWebBeaconPayload(
+  value: unknown,
+): value is Readonly<WebBeaconPayload> {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("type" in value) || value.type !== WEB_BEACON_TYPE) return false;
+  if (!("peerId" in value) || typeof value.peerId !== "string") return false;
+  if (!("webPort" in value) || typeof value.webPort !== "number") return false;
+  return (
+    Number.isInteger(value.webPort) &&
+    value.webPort > 0 &&
+    value.webPort < MAX_UDP_PORT
+  );
+}