agent-comms 8.15.9 → 8.15.11

package/src/core/name-claim.ts

@@ -0,0 +1,145 @@
+/**
+ * A self display name claim (agent-comms#345): the name a key asserts for itself, signed by that key, carried as one line of text beside the proofs in an agent/self advert. The issuer is authentic (the claim carries the public key it verifies under, and that key must hash to the subject's device-id, the same self-certifying check a capability token's issuer-key gets), but the content is whatever the issuer chose, so a receiver shows it as that subject's own claim, never as a fact about it. A machine names itself this way; an agent's name already rides in its own signed advert.
+ *
+ * The claim expires, like the proofs it rides beside, so a renamed machine's old name ages out of every peer's view without anything having to revoke it.
+ */
+
+import type { Clock } from "wire-mesh-core/ports/clock";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import { parseDisplayName } from "./display-name.js";
+
+/** Separates a name claim's signature from every other signature the same key makes, so no other signed payload can be replayed as one. */
+const NAME_CLAIM_CONTEXT = "agent-comms/name-claim/v1";
+
+/** The longest claim text a receiver will look at: a claim is a short name, a public key and a signature, well under a quarter of this, so anything longer is something else. */
+export const MAX_NAME_CLAIM_LENGTH = 2048;
+
+interface NameClaimWire {
+  subject: string;
+  name: string;
+  expires: number;
+  alg: number;
+  publicKey: string;
+  signature: string;
+}
+
+function isNameClaimWire(value: unknown): value is NameClaimWire {
+  if (typeof value !== "object" || value === null) return false;
+  return (
+    "subject" in value &&
+    typeof value.subject === "string" &&
+    "name" in value &&
+    typeof value.name === "string" &&
+    "expires" in value &&
+    typeof value.expires === "number" &&
+    "alg" in value &&
+    typeof value.alg === "number" &&
+    "publicKey" in value &&
+    typeof value.publicKey === "string" &&
+    "signature" in value &&
+    typeof value.signature === "string"
+  );
+}
+
+/** The exact bytes a claim's signature covers: the context, then every signed field, in a fixed order. */
+function signedBytes(
+  claim: Readonly<Pick<NameClaimWire, "subject" | "name" | "expires">>,
+): Uint8Array {
+  return new TextEncoder().encode(
+    JSON.stringify([
+      NAME_CLAIM_CONTEXT,
+      claim.subject,
+      claim.name,
+      claim.expires,
+    ]),
+  );
+}
+
+export interface MintNameClaimOptions {
+  /** The key naming itself: the claim's subject is its device-id. */
+  issuer: IdentityPort;
+  clock: Clock;
+  /** Must already satisfy parseDisplayName. */
+  name: string;
+  lifetimeMs: number;
+}
+
+/** A fresh claim, as one line of text, that options.issuer calls itself options.name. */
+export async function mintNameClaim(
+  options: Readonly<MintNameClaimOptions>,
+): Promise<string> {
+  const unsigned = {
+    subject: deviceIdToHex(options.issuer.deviceId),
+    name: options.name,
+    expires: options.clock.now() + options.lifetimeMs,
+  };
+  const signature = await options.issuer.sign(signedBytes(unsigned));
+  const wire: NameClaimWire = {
+    ...unsigned,
+    alg: options.issuer.identityKey.alg,
+    publicKey: Buffer.from(options.issuer.identityKey["public-key"]).toString(
+      "base64url",
+    ),
+    signature: Buffer.from(signature).toString("base64url"),
+  };
+  return Buffer.from(JSON.stringify(wire), "utf-8").toString("base64url");
+}
+
+export interface VerifyNameClaimOptions {
+  claim: string;
+  /** The device-id (hex) the claim must be about: the machine a proof has already identified. */
+  subject: string;
+  /** The verifying node's own identity (for signature checks) and clock. */
+  identity: IdentityPort;
+  clock: Clock;
+}
+
+export type NameClaimVerdict =
+  { ok: true; name: string; expires: number } | { ok: false; reason: string };
+
+/** Whether options.claim is a current name claim signed by options.subject's own key, and the name it asserts. Never throws for a bad claim: text that is not a claim, one about another subject, one whose key is not the subject's, a bad signature, an expired claim or an unusable name all come back as a refusal. */
+export async function verifyNameClaim(
+  options: Readonly<VerifyNameClaimOptions>,
+): Promise<NameClaimVerdict> {
+  if (options.claim.length > MAX_NAME_CLAIM_LENGTH) {
+    return { ok: false, reason: "too_long" };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(
+      Buffer.from(options.claim, "base64url").toString("utf-8"),
+    );
+  } catch {
+    return { ok: false, reason: "not_a_claim" };
+  }
+  if (!isNameClaimWire(parsed)) return { ok: false, reason: "not_a_claim" };
+  if (parsed.subject !== options.subject.toLowerCase()) {
+    return { ok: false, reason: "wrong_subject" };
+  }
+  if (parsed.expires <= options.clock.now()) {
+    return { ok: false, reason: "expired" };
+  }
+  const name = parseDisplayName(parsed.name);
+  if (name === undefined || name !== parsed.name) {
+    return { ok: false, reason: "unusable_name" };
+  }
+  const publicKey = Uint8Array.from(Buffer.from(parsed.publicKey, "base64url"));
+  const keyOwner = deviceIdToHex(
+    await options.identity.deriveDeviceId(publicKey),
+  );
+  if (keyOwner !== parsed.subject) return { ok: false, reason: "wrong_key" };
+  let signed: boolean;
+  try {
+    signed = await options.identity.verify(
+      { alg: parsed.alg, "public-key": publicKey },
+      signedBytes(parsed),
+      Uint8Array.from(Buffer.from(parsed.signature, "base64url")),
+    );
+  } catch {
+    // An algorithm the verifier does not support, or key bytes it cannot import: either way the claim cannot be checked, which is a refusal.
+    return { ok: false, reason: "unusable_key" };
+  }
+  if (!signed) return { ok: false, reason: "bad_signature" };
+  return { ok: true, name, expires: parsed.expires };
+}

package/src/core/naming-actions.ts

@@ -0,0 +1,90 @@
+/**
+ * CommsTool's naming actions (agent-comms#345): setting, clearing and listing the viewer's petnames, naming this machine and naming this account. Split out of tool.ts to keep that file under the repo's max-lines cap, as gateway-trust-actions.ts is.
+ */
+
+import type { CommsAction } from "./types.js";
+import type { CommsResult } from "./tool.js";
+import { idWithNames, type Namer, type Naming } from "./naming.js";
+
+/** The result for a bridge constructed without naming wired. */
+function namingUnavailable(): CommsResult {
+  return {
+    content: "Naming is not available on this bridge.",
+    isError: true,
+  };
+}
+
+/** Labels action.device with the viewer's own petname. */
+export function petnameSet(
+  naming: Naming | undefined,
+  action: CommsAction & { action: "petname_set" },
+): CommsResult {
+  if (naming === undefined) return namingUnavailable();
+  const label = naming.setPetname(action.device, action.name);
+  return {
+    content: `You now call ${action.device} "${label}". Only you see this name.`,
+    isError: false,
+  };
+}
+
+/** Removes the viewer's petname for action.device. */
+export function petnameClear(
+  naming: Naming | undefined,
+  action: CommsAction & { action: "petname_clear" },
+): CommsResult {
+  if (naming === undefined) return namingUnavailable();
+  return {
+    content: naming.clearPetname(action.device)
+      ? `Cleared your name for ${action.device}.`
+      : `You had no name for ${action.device}.`,
+    isError: false,
+  };
+}
+
+/** Every petname the viewer has set, each with its full id and the display name it now produces. */
+export function petnameList(
+  naming: Naming | undefined,
+  namer: Namer,
+): CommsResult {
+  if (naming === undefined) return namingUnavailable();
+  const petnames = [...naming.listPetnames().keys()];
+  if (petnames.length === 0) {
+    return { content: "You have not named anything.", isError: false };
+  }
+  return {
+    content: `Your names:\n${petnames.map((id) => `  ${idWithNames(id, namer)}`).join("\n")}`,
+    isError: false,
+  };
+}
+
+/** Names this machine, or clears its name when action.name is omitted. */
+export async function machineName(
+  naming: Naming | undefined,
+  action: CommsAction & { action: "machine_name" },
+): Promise<CommsResult> {
+  if (naming === undefined) return namingUnavailable();
+  const name = await naming.setMachineName(action.name);
+  return {
+    content:
+      name === undefined
+        ? "This machine no longer asserts a name."
+        : `This machine now calls itself "${name}"; peers see it as its own claim, beside any name they gave it.`,
+    isError: false,
+  };
+}
+
+/** Names this account (the user principal every one of its machines shares), or clears its name when action.name is omitted. */
+export async function principalName(
+  naming: Naming | undefined,
+  action: CommsAction & { action: "principal_name" },
+): Promise<CommsResult> {
+  if (naming === undefined) return namingUnavailable();
+  const name = await naming.setPrincipalName(action.name);
+  return {
+    content:
+      name === undefined
+        ? "This account no longer asserts a name."
+        : `This account now calls itself "${name}"; peers see it as its own claim, beside any name they gave it.`,
+    isError: false,
+  };
+}

package/src/core/naming.ts

@@ -0,0 +1,138 @@
+/**
+ * Naming (agent-comms#345): the viewer's petnames, the machine's and the account's own self display names, and the one namer every surface formats an id with. A MeshStore collaborator handed to CommsTool the way discovery is, so the tool's naming actions and every listing read through the same object.
+ *
+ * Nothing here is gossiped by this module. Petnames never leave the viewer's storage; the machine's and the account's names reach peers only as the claims GroupProofs signs and puts in the advert.
+ */
+
+import {
+  formatDisplayName,
+  formatNames,
+  type DisplayNameParts,
+} from "./display-name.js";
+import type { Petnames } from "./petnames.js";
+import { requireDisplayName } from "./store.js";
+
+export interface NameOptions {
+  /** The name the caller already knows the subject asserts (an agent's registered name); otherwise the namer supplies the one it knows, if any. */
+  selfName?: string | undefined;
+  /** The surface prints the full id beside the name, so the short id is left out (formatNames rather than formatDisplayName), and an id with no name gives the empty string. */
+  besideFullId?: boolean | undefined;
+}
+
+/** Formats one id by the display convention. */
+export type Namer = (id: string, options?: Readonly<NameOptions>) => string;
+
+/** Formats parts by options: formatNames beside a full id, formatDisplayName otherwise. */
+function formatFor(
+  parts: Readonly<DisplayNameParts>,
+  options: Readonly<NameOptions> | undefined,
+): string {
+  return options?.besideFullId === true
+    ? formatNames(parts)
+    : formatDisplayName(parts);
+}
+
+/** The namer for a surface with no naming wired: no petnames and no known self names, only what the caller passes. */
+export const plainNamer: Namer = (id, options) =>
+  formatFor({ id, selfName: options?.selfName }, options);
+
+/** id followed by its names, the form every listing whose entries are acted on by full id prints: two spaces between them, and the id alone when it has no name. */
+export function idWithNames(id: string, namer: Namer): string {
+  const names = namer(id, { besideFullId: true });
+  return names === "" ? id : `${id}  ${names}`;
+}
+
+export interface NamingDeps {
+  petnames: Petnames;
+  /** Every machine's and user principal's verified self display name, keyed by issuer id. */
+  issuerNames: () => Promise<Map<string, string>>;
+  /** The agents requesterId may see, whose registered names are their self-asserted names. */
+  listAgents: (
+    requesterId: string,
+  ) => Promise<readonly Readonly<{ id: string; name: string }>[]>;
+  /** Persists this machine's own name (undefined clears it) and re-signs its claim. */
+  saveMachineName: (name: string | undefined) => Promise<void>;
+  /** Persists this account's own name (undefined clears it) and re-signs its claim. */
+  saveUserName: (name: string | undefined) => Promise<void>;
+}
+
+export class Naming {
+  constructor(private readonly deps: Readonly<NamingDeps>) {}
+
+  /** Labels deviceHex as name in the viewer's own petnames. Throws INVALID_NAME for an unusable name. Returns the label as stored. */
+  setPetname(deviceHex: string, name: string): string {
+    return this.deps.petnames.set(deviceHex, name);
+  }
+
+  /** Removes the viewer's label for deviceHex. Returns whether there was one. */
+  clearPetname(deviceHex: string): boolean {
+    return this.deps.petnames.clear(deviceHex);
+  }
+
+  /** Every label the viewer has set, keyed by device-id. */
+  listPetnames(): Map<string, string> {
+    return this.deps.petnames.list();
+  }
+
+  /** Names this machine (undefined clears the name). Throws INVALID_NAME for an unusable name. Returns the name as stored. */
+  async setMachineName(name: string | undefined): Promise<string | undefined> {
+    if (name === undefined) {
+      await this.deps.saveMachineName(undefined);
+      return undefined;
+    }
+    const parsed = requireDisplayName(name, "A machine name");
+    await this.deps.saveMachineName(parsed);
+    return parsed;
+  }
+
+  /** Names this account (undefined clears the name). Throws INVALID_NAME for an unusable name. Returns the name as stored. */
+  async setPrincipalName(
+    name: string | undefined,
+  ): Promise<string | undefined> {
+    if (name === undefined) {
+      await this.deps.saveUserName(undefined);
+      return undefined;
+    }
+    const parsed = requireDisplayName(name, "An account name");
+    await this.deps.saveUserName(parsed);
+    return parsed;
+  }
+
+  /** Every id requesterId has a name for, a petname or a known self name, with those names: the parts a surface outside this process (the dashboard) formats with formatDisplayName. */
+  async nameParts(requesterId: string): Promise<DisplayNameParts[]> {
+    const petnames = this.deps.petnames.list();
+    const selfNames = await this.selfNames(requesterId);
+    const ids = new Set([...petnames.keys(), ...selfNames.keys()]);
+    return [...ids].map((id) => ({
+      id,
+      ...(petnames.has(id) ? { petname: petnames.get(id) } : {}),
+      ...(selfNames.has(id) ? { selfName: selfNames.get(id) } : {}),
+    }));
+  }
+
+  /** Every self-asserted name this store knows, keyed by device-id: verified machine and principal names and the registered names of the agents requesterId may see. */
+  private async selfNames(requesterId: string): Promise<Map<string, string>> {
+    const names = await this.deps.issuerNames();
+    for (const agent of await this.deps.listAgents(requesterId)) {
+      names.set(agent.id, agent.name);
+    }
+    return names;
+  }
+
+  /** The namer for requesterId's view right now: the viewer's petnames, then the self names this store knows, then the short id. */
+  async namer(requesterId: string): Promise<Namer> {
+    const petnames = this.deps.petnames.list();
+    const selfNames = await this.selfNames(requesterId);
+    return (id, options) => {
+      const key = id.toLowerCase();
+      return formatFor(
+        {
+          id,
+          petname: petnames.get(key),
+          selfName: options?.selfName ?? selfNames.get(key),
+        },
+        options,
+      );
+    };
+  }
+}

package/src/core/nanoid.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal nanoid — URL-safe alphanumeric, no dependencies.
+ * Uses crypto.getRandomValues for cryptographic randomness.
+ */
+
+const ALPHABET =
+  "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_-";
+const SIZE = 21;
+
+export function nanoid(size: number = SIZE): string {
+  const bytes = new Uint8Array(size);
+  crypto.getRandomValues(bytes);
+  let id = "";
+  for (let i = 0; i < size; i++) {
+    const byte = bytes[i];
+    if (byte === undefined) continue;
+    id += ALPHABET.charAt(byte % ALPHABET.length);
+  }
+  return id;
+}

package/src/core/network-interfaces.ts

@@ -0,0 +1,24 @@
+/**
+ * This host's network interfaces in the provider-neutral shape the mesh_interfaces action reports (MeshStore.getNetworkInterfaces's body, split out to keep mesh-store.ts under the repo's max-lines cap).
+ */
+
+import * as os from "node:os";
+import type { NetworkInterface } from "./types.js";
+
+/** Every address on every interface of this host, as os.networkInterfaces reports them. */
+export function listNetworkInterfaces(): NetworkInterface[] {
+  const interfaces = os.networkInterfaces();
+  const result: NetworkInterface[] = [];
+  for (const [name, addrs] of Object.entries(interfaces)) {
+    if (addrs === undefined) continue;
+    for (const addr of addrs) {
+      result.push({
+        name,
+        address: addr.address,
+        family: addr.family,
+        internal: addr.internal,
+      });
+    }
+  }
+  return result;
+}

package/src/core/package-version.ts

@@ -0,0 +1,34 @@
+/**
+ * This package's own version, read once from its own package.json and cached -- the single source of truth whoami/update output (see tool.ts) and the npm version-drift check (see version-check.ts) both read from, rather than each independently locating and parsing the file.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+/** Narrows a parsed package.json into the shape every caller here needs -- shared by getOwnPackageVersion and wire-mesh-core-version.ts's getWireMeshCoreVersion, which reads a dependency's installed package.json the identical way. */
+export function isVersionedPackageJson(
+  value: unknown,
+): value is { version: string } {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("version" in value)) return false;
+  return typeof value.version === "string";
+}
+
+let cachedVersion: string | undefined;
+
+/** This package's own version, read from the package.json two directories up from this file -- tsconfig's rootDir/outDir mirror src/dist at the same depth, so the relative path resolves identically whether this runs from source or from the compiled dist output. Cached after the first successful read. */
+export function getOwnPackageVersion(): string {
+  if (cachedVersion !== undefined) return cachedVersion;
+  const packageJsonPath = path.join(moduleDir, "..", "..", "package.json");
+  const parsed: unknown = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+  if (!isVersionedPackageJson(parsed)) {
+    throw new Error(
+      `package.json at ${packageJsonPath} has no "version" string`,
+    );
+  }
+  cachedVersion = parsed.version;
+  return cachedVersion;
+}