agent-comms 8.15.26 → 9.0.0

package/src/core/push-manager.ts

@@ -1,76 +0,0 @@
-/**
- * Push subscription manager — tracks browser push subscriptions and
- * dispatches Web Push notifications when agents are offline.
- *
- * The PushManager is a standalone module — MeshStore doesn't know about it.
- * The web server bridge checks whether the target agent's WebSocket is
- * disconnected and falls back to push when a subscription exists.
- */
-
-import type { VapidKeys } from "./vapid.js";
-import { generateVapidKeys } from "./vapid.js";
-import {
-  sendWebPush,
-  type PushSubscription,
-  type PushPayload,
-} from "./web-push.js";
-
-// ---------------------------------------------------------------------------
-// PushManager
-// ---------------------------------------------------------------------------
-
-export class PushManager {
-  private readonly vapidKeys: VapidKeys;
-  private readonly subject: string;
-  private readonly subscriptions = new Map<string, PushSubscription>();
-
-  constructor(subject = "mailto:agent-comms@localhost") {
-    this.vapidKeys = generateVapidKeys();
-    this.subject = subject;
-  }
-
-  /**
-   * Register a push subscription for a given agent ID.
-   * Overwrites any existing subscription for the same agent.
-   */
-  addSubscription(agentId: string, subscription: PushSubscription): void {
-    this.subscriptions.set(agentId, subscription);
-  }
-
-  /**
-   * Remove a push subscription.
-   */
-  removeSubscription(agentId: string): void {
-    this.subscriptions.delete(agentId);
-  }
-
-  /**
-   * Check whether a push subscription exists for the given agent.
-   */
-  hasSubscription(agentId: string): boolean {
-    return this.subscriptions.has(agentId);
-  }
-
-  /**
-   * Send a push notification to a subscribed agent.
-   *
-   * No-ops silently if no subscription exists — callers should check
-   * hasSubscription() first if they need to distinguish the two cases.
-   */
-  async sendPush(
-    agentId: string,
-    payload: Readonly<PushPayload>,
-  ): Promise<void> {
-    const subscription = this.subscriptions.get(agentId);
-    if (!subscription) return;
-
-    await sendWebPush(subscription, payload, this.vapidKeys, this.subject);
-  }
-
-  /**
-   * Get the VAPID public key for the PWA to use in `pushManager.subscribe()`.
-   */
-  getPublicKey(): string {
-    return this.vapidKeys.publicKey;
-  }
-}

package/src/core/vapid.ts

@@ -1,81 +0,0 @@
-/**
- * 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/web-push.ts

@@ -1,322 +0,0 @@
-/**
- * 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);
-}