agent-comms 8.15.9 → 8.15.10

package/src/core/web-push.ts

@@ -0,0 +1,322 @@
+/**
+ * Web Push encryption and VAPID JWT signing (RFC 8291 + RFC 8292).
+ *
+ * Implements the Web Push protocol using only Node.js built-in `crypto`
+ * and `https` — no external dependencies.
+ *
+ * Encryption flow (RFC 8291):
+ *   1. Derive a shared ECDH secret from the subscription's p256dh key
+ *   2. HKDF-derive the encryption key and nonce from the shared secret + auth
+ *   3. Encrypt the payload with AES-128-GCM
+ *   4. Prepend the sender's public key (65 bytes) to the ciphertext
+ *
+ * VAPID signing (RFC 8292):
+ *   1. Build a JWT with sub, exp, and aud claims
+ *   2. Sign with ES256 (ECDSA + P-256 + SHA-256)
+ *   3. Append the public key and token to the Crypto-Key header
+ */
+
+import * as crypto from "node:crypto";
+import * as https from "node:https";
+import * as http from "node:http";
+import { URL } from "node:url";
+
+import type { VapidKeys } from "./vapid.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PushSubscription {
+  endpoint: string;
+  keys: { p256dh: string; auth: string };
+}
+
+export interface PushPayload {
+  title: string;
+  body: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CONTENT_ENCODING = "aes128gcm";
+const KEY_LENGTH = 16;
+const NONCE_LENGTH = 12;
+const SALT_LENGTH = 16;
+const MAX_PAYLOAD_SIZE = 4078;
+const EC_UNCOMPRESSED_POINT_LENGTH = 65;
+const RECORD_SIZE = 4096;
+const RECORD_SIZE_FIELD_LENGTH = 4;
+const VAPID_JWT_EXPIRY_HOURS = 12;
+const MINUTES_PER_HOUR = 60;
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+const HTTPS_DEFAULT_PORT = 443;
+const HTTP_DEFAULT_PORT = 80;
+const HTTP_STATUS_OK_MIN = 200;
+const HTTP_STATUS_OK_MAX = 299;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a Web Push notification.
+ *
+ * Encrypts the payload per RFC 8291, signs with VAPID per RFC 8292,
+ * and POSTs to the push service endpoint.
+ */
+export async function sendWebPush(
+  subscription: PushSubscription,
+  payload: Readonly<PushPayload>,
+  vapidKeys: Readonly<VapidKeys>,
+  subject: string,
+): Promise<void> {
+  const plaintext = JSON.stringify(payload);
+  const plaintextBuf = Buffer.from(plaintext, "utf-8");
+
+  if (plaintextBuf.length > MAX_PAYLOAD_SIZE) {
+    throw new Error(
+      `Payload too large: ${String(plaintextBuf.length)} bytes (max ${String(MAX_PAYLOAD_SIZE)})`,
+    );
+  }
+
+  const encrypted = encrypt(plaintextBuf, subscription.keys);
+  const headers = buildHeaders(
+    encrypted,
+    subscription.endpoint,
+    vapidKeys,
+    subject,
+  );
+
+  await post(subscription.endpoint, headers, encrypted);
+}
+
+// ---------------------------------------------------------------------------
+// Encryption (RFC 8291)
+// ---------------------------------------------------------------------------
+
+function encrypt(plaintext: Buffer, keys: PushSubscription["keys"]): Buffer {
+  // Decode the subscription's p256dh and auth keys
+  const recipientPubKey = base64urlDecode(keys.p256dh);
+  const authKey = base64urlDecode(keys.auth);
+
+  // Generate an ephemeral ECDH key pair for this message
+  const ecdh = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+  const senderPrivateKey = crypto.createPrivateKey({
+    key: ecdh.privateKey.export({ type: "pkcs8", format: "der" }),
+    format: "der",
+    type: "pkcs8",
+  });
+  const senderPublicDer = ecdh.publicKey.export({
+    type: "spki",
+    format: "der",
+  });
+  const senderPublicKey = senderPublicDer.subarray(
+    senderPublicDer.length - EC_UNCOMPRESSED_POINT_LENGTH,
+  );
+
+  // Derive the shared secret via ECDH
+  const sharedSecret = crypto.diffieHellman({
+    privateKey: senderPrivateKey,
+    publicKey: crypto.createPublicKey({
+      key: concat(
+        Buffer.from(
+          "3059301306072a8648ce3d020106082a8648ce3d030107034200",
+          "hex",
+        ),
+        recipientPubKey,
+      ),
+      format: "der",
+      type: "spki",
+    }),
+  });
+
+  // Derive the pseudo-random key (PRK) using HKDF with auth
+  const prk = hkdfExtract(authKey, sharedSecret);
+
+  // Derive the encryption key and nonce
+  const keyInfo = concat(
+    Buffer.from("Content-Encoding: aes128gcm\0", "utf-8"),
+    senderPublicKey,
+  );
+  const nonceInfo = Buffer.from("Content-Encoding: nonce\0", "utf-8");
+
+  const encryptionKey = hkdfExpand(prk, keyInfo, KEY_LENGTH);
+  const nonce = hkdfExpand(prk, nonceInfo, NONCE_LENGTH);
+
+  // Generate a random salt
+  const salt = crypto.randomBytes(SALT_LENGTH);
+
+  // Pad the plaintext: plaintext + 2-byte padding delimiter (0x02 0x00 for no padding)
+  // RFC 8291 §4: record is plaintext || 0x02 || padding zeros
+  const padded = concat(plaintext, Buffer.from([0x02]));
+
+  // Encrypt with AES-128-GCM
+  const cipher = crypto.createCipheriv("aes-128-gcm", encryptionKey, nonce);
+  const ciphertext = cipher.update(padded);
+  const authTag = cipher.getAuthTag();
+
+  // RFC 8291 §4: salt (16) || rs (4, big-endian, 4096) || sender pubkey (65) || ciphertext || tag
+  const rs = Buffer.alloc(RECORD_SIZE_FIELD_LENGTH);
+  rs.writeUInt32BE(RECORD_SIZE);
+
+  return concat(salt, rs, senderPublicKey, ciphertext, authTag);
+}
+
+// ---------------------------------------------------------------------------
+// HKDF helpers
+// ---------------------------------------------------------------------------
+
+function hkdfExtract(salt: Buffer, ikm: Buffer): Buffer {
+  const hmac = crypto.createHmac("sha256", salt);
+  hmac.update(ikm);
+  return hmac.digest();
+}
+
+function hkdfExpand(prk: Buffer, info: Buffer, length: number): Buffer {
+  const hmac = crypto.createHmac("sha256", prk);
+  hmac.update(concat(info, Buffer.from([0x01])));
+  const t = hmac.digest();
+  return t.subarray(0, length);
+}
+
+// ---------------------------------------------------------------------------
+// VAPID JWT signing (RFC 8292)
+// ---------------------------------------------------------------------------
+
+function buildVapidJwt(
+  audience: string,
+  vapidKeys: Readonly<VapidKeys>,
+  subject: string,
+): string {
+  const header = base64url(Buffer.from('{"alg":"ES256","typ":"JWT"}', "utf-8"));
+
+  const exp =
+    Math.floor(Date.now() / MS_PER_SECOND) +
+    VAPID_JWT_EXPIRY_HOURS * MINUTES_PER_HOUR * SECONDS_PER_MINUTE;
+  const claims = JSON.stringify({ aud: audience, exp, sub: subject });
+  const payload = base64url(Buffer.from(claims, "utf-8"));
+
+  const signInput = `${header}.${payload}`;
+
+  // Reconstruct the private key from the raw 32-byte scalar
+  // P-256 PKCS8 DER wrapper: 39 bytes header + 32 bytes scalar (with 0x00 prefix)
+  const privScalar = base64urlDecode(vapidKeys.privateKey);
+  // Build the EC private key in SEC1 DER format
+  const sec1Der = concat(
+    Buffer.from("30770201010420", "hex"),
+    privScalar,
+    Buffer.from("a00a06082a8648ce3d030107a14403420004", "hex"),
+    base64urlDecode(vapidKeys.publicKey),
+  );
+  const privateKey = crypto.createPrivateKey({
+    key: sec1Der,
+    format: "der",
+    type: "sec1",
+  });
+
+  const signature = crypto.sign("sha256", Buffer.from(signInput), privateKey);
+  // ECDSA signature is a DER-encoded SEQUENCE of two INTEGERs.
+  // Web Push requires base64url encoding of the raw DER.
+  const sigB64 = base64url(signature);
+
+  return `${signInput}.${sigB64}`;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP headers
+// ---------------------------------------------------------------------------
+
+function buildHeaders(
+  encrypted: Buffer,
+  endpoint: string,
+  vapidKeys: Readonly<VapidKeys>,
+  subject: string,
+): Record<string, string> {
+  const audience = new URL(endpoint).origin;
+  const jwt = buildVapidJwt(audience, vapidKeys, subject);
+
+  return {
+    "Content-Type": "application/octet-stream",
+    "Content-Encoding": CONTENT_ENCODING,
+    "Content-Length": String(encrypted.length),
+    Authorization: `vapid t=${jwt}, k=${vapidKeys.publicKey}`,
+    TTL: "86400",
+    Urgency: "high",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// HTTP POST
+// ---------------------------------------------------------------------------
+
+async function post(
+  endpoint: string,
+  headers: Readonly<Record<string, string>>,
+  body: Buffer,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const url = new URL(endpoint);
+    const isHttps = url.protocol === "https:";
+    const mod = isHttps ? https : http;
+    const port =
+      url.port !== ""
+        ? url.port
+        : String(isHttps ? HTTPS_DEFAULT_PORT : HTTP_DEFAULT_PORT);
+
+    const req = mod.request(
+      {
+        hostname: url.hostname,
+        port,
+        path: url.pathname + url.search,
+        method: "POST",
+        headers,
+      },
+      (res) => {
+        // Drain the response body
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => {
+          chunks.push(chunk);
+        });
+        res.on("end", () => {
+          if (
+            res.statusCode !== undefined &&
+            (res.statusCode < HTTP_STATUS_OK_MIN ||
+              res.statusCode > HTTP_STATUS_OK_MAX)
+          ) {
+            const responseBody = Buffer.concat(chunks).toString("utf-8");
+            reject(
+              new Error(
+                `Push service returned ${String(res.statusCode)}: ${responseBody}`,
+              ),
+            );
+          } else {
+            resolve();
+          }
+        });
+      },
+    );
+
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function base64urlDecode(input: string): Buffer {
+  return Buffer.from(input, "base64url");
+}
+
+function base64url(input: Buffer): string {
+  return input.toString("base64url");
+}
+
+function concat(...buffers: readonly Buffer[]): Buffer {
+  return Buffer.concat(buffers);
+}

package/src/core/wire-mesh-core-version.ts

@@ -0,0 +1,25 @@
+/**
+ * This process's own installed wire-mesh-core dependency version, read directly from its package.json rather than duplicated as a hand-maintained constant -- the local fallback agent-comms#198 calls for once wire-mesh#179 (wire-mesh-core self-advertising CORE_VERSION_GOSSIP_KEY on every self-advert) makes the value moot for a REMOTE peer. own-version.ts (wire-mesh-core's own internal module producing that gossiped value) is not exported as a package subpath, so this side cannot import its OWN_VERSION constant directly -- but it is exactly this side's own installed wire-mesh-core/package.json version, which is exported ("./package.json") and is what own-version.ts itself reads to produce OWN_VERSION in the first place.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { isVersionedPackageJson } from "./package-version.js";
+
+let cachedVersion: string | undefined;
+
+/** This process's own installed wire-mesh-core version. Resolved via import.meta.resolve (Node's own module resolver) rather than a static JSON import, so it always reads whatever wire-mesh-core is actually installed at runtime -- immune to any bundler that might otherwise inline a JSON import at agent-comms' own build time. Cached after the first successful read, matching getOwnPackageVersion's own convention. */
+export function getWireMeshCoreVersion(): string {
+  if (cachedVersion !== undefined) return cachedVersion;
+  const packageJsonUrl = import.meta.resolve("wire-mesh-core/package.json");
+  const parsed: unknown = JSON.parse(
+    readFileSync(fileURLToPath(packageJsonUrl), "utf-8"),
+  );
+  if (!isVersionedPackageJson(parsed)) {
+    throw new Error(
+      `wire-mesh-core's package.json at ${packageJsonUrl} has no "version" string`,
+    );
+  }
+  cachedVersion = parsed.version;
+  return cachedVersion;
+}

package/src/core/wire-mesh-identity.ts

@@ -0,0 +1,36 @@
+/**
+ * Adapts agent-comms' own PeerIdentity (a PEM-encoded ECDSA P-256 keypair plus a self-signed X.509 certificate, identity.ts's own concern) into wire-mesh-core's IdentityPort -- the shape MeshSession and createTlsTransport both expect. Both sides wrap the exact same keypair; only the envelope differs. The certificate itself plays no part here -- IdentityPort's own device-id is derived straight from the raw public key, identically to how identity.ts's own deriveDeviceId already works, so the two stay consistent by construction rather than by convention.
+ */
+
+import { webcrypto } from "node:crypto";
+import { createNodeIdentity } from "wire-mesh-core/adapters/node-identity";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import type { PeerIdentity } from "./identity.js";
+import { rawPublicKeyFromPrivateKey } from "./identity.js";
+
+/** COSE algorithm identifier for ES256 (P-256 + SHA-256) -- wire-mesh's own identity-key.alg convention. */
+const ES256 = -7;
+
+/** Strips a PEM envelope down to its raw DER bytes, copied into a fresh, non-shared, whole-buffer Uint8Array -- Web Crypto's BufferSource parameters reject a view over a SharedArrayBuffer or a sub-range view, neither of which Buffer.from's return type is guaranteed not to be. */
+function pemToDer(pem: string, label: string): Uint8Array<ArrayBuffer> {
+  const b64 = pem
+    .replace(new RegExp(`-----BEGIN ${label}-----`), "")
+    .replace(new RegExp(`-----END ${label}-----`), "")
+    .replace(/\s/g, "");
+  return Uint8Array.from(Buffer.from(b64, "base64"));
+}
+
+export async function toIdentityPort(
+  identity: Readonly<PeerIdentity>,
+): Promise<IdentityPort> {
+  const privateKeyDer = pemToDer(identity.privateKey, "PRIVATE KEY");
+  const privateKey = await webcrypto.subtle.importKey(
+    "pkcs8",
+    privateKeyDer,
+    { name: "ECDSA", namedCurve: "P-256" },
+    true,
+    ["sign"],
+  );
+  const publicKeyBytes = rawPublicKeyFromPrivateKey(identity.privateKey);
+  return createNodeIdentity(privateKey, publicKeyBytes, ES256);
+}

package/src/core/wire-mesh-transport-options.ts

@@ -0,0 +1,82 @@
+/**
+ * WireMeshTransport's own constructor options, 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, peer-lifecycle.ts, gossip-directory.ts, and listener-registry.ts were each split from that file.
+ */
+
+import type { KeyValueStorage } from "wire-mesh-core/ports/storage";
+import type { AccountLedgerReplica } from "./account-ledger.js";
+import type { GatewayTrustReader } from "./gateway-trust.js";
+import type { RoomVerbHandler } from "./room-router.js";
+import type { AgentStatus } from "./types.js";
+import type { AgentSelfAdvert, HostedRoomAdvert } from "./gossip-extensions.js";
+import type { ListenerPolicy } from "./transport.js";
+
+/** roomVerbHandlers, getCurrentPresence, getHostedRooms, dataStorage, getSelfAgentAdvert, and gatewayTrust each match the field-level doc comment on the WireMeshTransport field they back; accountReplication, verifyMembership and roomJoinApprovalTimeoutMs are described by their own doc comments below. pendingConnectionTimeoutMs and presenceReadvertiseIntervalMs default to DEFAULT_PENDING_CONNECTION_TIMEOUT_MS and PRESENCE_READVERTISE_INTERVAL_MS. Every field is optional and they are bundled into this one options type, so a caller needing only one of them never passes `undefined` for the rest. */
+export interface WireMeshTransportOptions {
+  roomVerbHandlers?: Partial<Record<string, RoomVerbHandler>>;
+  pendingConnectionTimeoutMs?: number | undefined;
+  /** How long a room.join this transport sends may await a human decision at the receiving end. Defaults to ROOM_JOIN_APPROVAL_TIMEOUT_MS; a test shortens it. */
+  roomJoinApprovalTimeoutMs?: number | undefined;
+  getCurrentPresence?: () => AgentStatus | undefined;
+  presenceReadvertiseIntervalMs?: number | undefined;
+  getHostedRooms?: () => readonly HostedRoomAdvert[];
+  dataStorage?: KeyValueStorage;
+  getSelfAgentAdvert?: () => AgentSelfAdvert | undefined;
+  /** Replicates the account's grant ledger (agent-comms#344) with peers holding the same account: the ledger, read when a data frame for one of its writer logs arrives and on each re-advertise tick, and the check of a peer's gossiped membership proof against this machine's own principal that decides which peers those are. Absent for a caller with no account ledger. */
+  accountReplication?: Readonly<{
+    getLedger: () => AccountLedgerReplica | undefined;
+    isAccountMember: (
+      claim: Readonly<{ proof: string; deviceHex: string }>,
+    ) => Promise<boolean>;
+  }>;
+  gatewayTrust?: Readonly<GatewayTrustReader>;
+  /** The interface the relay this transport serves listens on (agent-comms#342). Defaults to every interface (ALL_INTERFACES_HOST), so the relay reaches the local network; a test serves loopback only. */
+  relayListenHost?: string | undefined;
+  /** Checks a gossiped membership proof against a principal or machine this side trusts (MembershipProofs.verify). Without it, a directory entry from a device not trusted by id is refused even when it carries a proof. */
+  verifyMembership?: (
+    claim: Readonly<{ proof: string; deviceHex: string; issuerHex: string }>,
+  ) => Promise<{ ok: true; expires: number } | { ok: false; reason: string }>;
+}
+
+/** WireMeshTransport.connectToRemote's own bundled parameters: see MeshTransport's own connectToRemote doc comment (transport.ts) for what each one means. */
+export interface ConnectToRemoteOptions {
+  host: string;
+  port: number;
+  peerId: string;
+  dataPort: number;
+  name: string;
+  fingerprint: string;
+}
+
+/** How an accepted connection is treated, set by the listener that accepted it. fireOnPeerConnected is true only for the data server, whose connections are a known peer's own data dial; requiresApproval quarantines a listener a stranger can dial cold; machineLocal marks a loopback-only listener, whose sessions take part in the coordinator election (election-sessions.ts). */
+export interface AcceptOptions {
+  policy: ListenerPolicy | undefined;
+  fireOnPeerConnected: boolean;
+  requiresApproval: boolean;
+  machineLocal: boolean;
+}
+
+/** The data server: bound on loopback, dialled only by peers that already know its port. */
+export const DATA_SERVER_ACCEPT: Readonly<AcceptOptions> = {
+  policy: undefined,
+  fireOnPeerConnected: true,
+  requiresApproval: false,
+  machineLocal: true,
+};
+
+/** The default well-known port listener: bound on loopback, but dialled cold, so quarantined until an introduce or an approved connect_request. */
+export const DEFAULT_LISTENER_ACCEPT: Readonly<AcceptOptions> = {
+  policy: "full",
+  fireOnPeerConnected: false,
+  requiresApproval: true,
+  machineLocal: true,
+};
+
+/** A listener an operator added with addListener: on whatever interface they chose, so it may cross machines and never carries coordinator claims. */
+export function operatorListenerAccept(policy: ListenerPolicy): AcceptOptions {
+  return {
+    policy,
+    fireOnPeerConnected: false,
+    requiresApproval: true,
+    machineLocal: false,
+  };
+}