@saadnvd1/agent-os 0.3.694 → 0.3.698

package/lib/peer/client.ts

@@ -0,0 +1,188 @@
+/**
+ * hostApi's transport for a machine linked through Connect: each call is a
+ * fresh envelope (envelope.ts) to POST https://<its m- name>/api/peer/rpc,
+ * and the answer only counts if it is signed by the pinned key and bound to
+ * this request's nonce. No token is ever sent or stored.
+ */
+
+import { matchPeerRoute } from "./allowlist";
+import { recordPeerCall, type AuditEntry, type Outcome } from "./audit";
+import {
+  MAX_REQUEST_BODY,
+  MAX_RESPONSE_ENVELOPE,
+  RPC_PATH,
+  openResponse,
+  sealRequest,
+} from "./envelope";
+import { boxPublic, currentIdentity, signPublic, type Identity } from "./keys";
+import { notePinResult } from "./links";
+import type { HostLink } from "../hosts/remote-api";
+import { readCappedBytes } from "../hosts/read-capped-bytes";
+
+/**
+ * A failed peer call. `refused`: the other machine (or this one, before
+ * sending) said no, so nothing happened there.
+ */
+export class PeerCallError extends Error {
+  constructor(
+    message: string,
+    readonly refused: boolean,
+    readonly status?: number
+  ) {
+    super(message);
+  }
+}
+
+const DOMAIN = /^[a-z0-9-]+(\.[a-z0-9-]+)+$/;
+
+/**
+ * Only a Connect machine's own name, so a lying account list can't aim this
+ * machine at an internal address. AGENTOS_CONNECT_PEER_DOMAIN is for a
+ * staging service.
+ */
+export function peerHostAllowed(hostname: string, env = process.env): boolean {
+  const configured = env.AGENTOS_CONNECT_PEER_DOMAIN ?? "";
+  const domain = DOMAIN.test(configured) ? configured : "runagentos.com";
+  const escaped = domain.replace(/\./g, "\\.");
+  return new RegExp(`^m-[0-9a-f]{16}\\.${escaped}$`).test(hostname);
+}
+
+// The fixed refusals rpc-server.ts sends before anything is decrypted.
+const REFUSALS: Record<string, Outcome> = {
+  "bad signature": "bad_sig",
+  "bad envelope": "bad_sig",
+  stale: "stale",
+  replay: "replay",
+  busy: "replay",
+  "too large": "bad_sig",
+};
+
+const HINTS: Record<string, string> = {
+  "bad signature":
+    "it doesn't know this machine, the link is suspended there, or the keys don't match",
+  stale: "the clocks on the two machines differ by more than 2 minutes",
+};
+
+export interface ClientDeps {
+  identity: () => Identity | null;
+  audit: (e: AuditEntry) => void;
+  noteResult: (hostId: string, error: string | null) => void;
+}
+
+const realDeps: ClientDeps = {
+  identity: () => currentIdentity(),
+  audit: recordPeerCall,
+  noteResult: notePinResult,
+};
+
+export async function peerCall(
+  link: HostLink,
+  target: string,
+  opts: { method?: string; body?: unknown; timeout?: number },
+  deps: ClientDeps = realDeps
+): Promise<{ status: number; text: string }> {
+  const peer = link.connect;
+  const refuse = (msg: string): never => {
+    throw new PeerCallError(msg, true);
+  };
+  if (!peer) return refuse("isn't linked through Connect");
+  if (peer.state !== "active")
+    return refuse(
+      `the link is suspended (${peer.suspendedReason ?? "no reason given"})`
+    );
+  if (!peerHostAllowed(peer.hostname))
+    return refuse("its address isn't a Connect machine's");
+  const method = (
+    opts.method ?? (opts.body === undefined ? "GET" : "POST")
+  ).toUpperCase();
+  const q = target.indexOf("?");
+  const match = matchPeerRoute(
+    method,
+    q < 0 ? target : target.slice(0, q),
+    q < 0 ? "" : target.slice(q + 1)
+  );
+  if (!match.ok) return refuse("that call isn't open to linked machines");
+  const identity = deps.identity();
+  if (!identity)
+    return refuse("this machine isn't connected to AgentOS Connect");
+  const body =
+    opts.body === undefined
+      ? Buffer.alloc(0)
+      : Buffer.from(JSON.stringify(opts.body));
+  if (body.length > MAX_REQUEST_BODY) return refuse("the request is too large");
+
+  const started = Date.now();
+  const audit = (outcome: Outcome, status: number, bytes: number) =>
+    deps.audit({
+      hostId: link.hostId,
+      machineId: peer.machineId,
+      direction: "out",
+      method,
+      route: match.route,
+      status,
+      ms: Date.now() - started,
+      bytes,
+      outcome,
+    });
+  const sealed = sealRequest({
+    from: identity.machineId,
+    to: peer.machineId,
+    signKey: identity.signKey,
+    peerBox: boxPublic(peer.boxPub),
+    request: {
+      method,
+      path: match.path,
+      query: match.query,
+      contentType: body.length ? "application/json" : "",
+      body,
+    },
+  });
+  let res: Response;
+  let raw: Buffer;
+  try {
+    res = await fetch(`https://${peer.hostname}${RPC_PATH}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/octet-stream" },
+      body: new Uint8Array(sealed.envelope),
+      signal: AbortSignal.timeout(opts.timeout ?? 15000),
+      redirect: "error",
+    });
+    raw = await readCappedBytes(res, MAX_RESPONSE_ENVELOPE);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    deps.noteResult(link.hostId, message);
+    throw new PeerCallError(message, false);
+  }
+  if (res.status !== 200) {
+    const text = raw.subarray(0, 64).toString("utf8").trim();
+    const outcome = REFUSALS[text];
+    if (outcome && res.status >= 400 && res.status < 500) {
+      audit(outcome, res.status, sealed.envelope.length);
+      const message = HINTS[text] ? `${text}: ${HINTS[text]}` : text;
+      deps.noteResult(link.hostId, message);
+      // A refusal is unsigned: anyone on the path could forge one. A read
+      // changes nothing either way, but a write may have happened.
+      throw new PeerCallError(message, method === "GET", res.status);
+    }
+    deps.noteResult(link.hostId, `HTTP ${res.status}`);
+    throw new PeerCallError(`HTTP ${res.status}`, false, res.status);
+  }
+  let answer;
+  try {
+    answer = openResponse({
+      envelope: raw,
+      nonce: sealed.nonce,
+      resKey: sealed.resKey,
+      peerSign: signPublic(peer.signPub),
+    });
+  } catch (err) {
+    // It may have run there; the answer just can't be trusted.
+    const message = err instanceof Error ? err.message : String(err);
+    audit("bad_sig", 200, sealed.envelope.length + raw.length);
+    deps.noteResult(link.hostId, message);
+    throw new PeerCallError(message, false);
+  }
+  audit("ok", answer.status, body.length + answer.body.length);
+  deps.noteResult(link.hostId, null);
+  return { status: answer.status, text: answer.body.toString("utf8") };
+}

package/lib/peer/envelope.ts

@@ -0,0 +1,424 @@
+/**
+ * The signed, encrypted envelope linked machines call each other with
+ * (Node's crypto only).
+ *
+ * Request body: u32 header length ‖ header JSON ‖ hsig ‖ ciphertext ‖ sig.
+ *   header  {v:1, from, to, ts, nonce, epk}, epk a fresh X25519 key per call
+ *   hsig    Ed25519_A("agentos-peer-hdr-v1" ‖ header), so the receiver can
+ *           prove the sender before it holds any of the body
+ *   keys    HKDF-SHA256(X25519(epk, B_box), salt=nonce,
+ *                       info="agentos-peer-v1|from|to") → k_req ‖ k_res
+ *   ct      ChaCha20-Poly1305(k_req, AAD=header) over the inner request
+ *   sig     Ed25519_A("agentos-peer-req-v1" ‖ header ‖ SHA256(ct))
+ *
+ * Response body: iv ‖ ct ‖ sig, where iv is 12 fresh random bytes, ct =
+ * ChaCha20-Poly1305(k_res, iv) over the inner response and sig =
+ * Ed25519_B("agentos-peer-res-v1" ‖ request nonce ‖ iv ‖ SHA256(ct)), so it
+ * only opens for the request it answers.
+ *
+ * k_req seals exactly one message, so the request uses a fixed all-zero IV.
+ * The response doesn't rely on that: should a request ever be answered twice,
+ * a fresh IV keeps the two answers from sharing a keystream.
+ */
+
+import crypto, { type KeyObject } from "crypto";
+import { MACHINE_ID } from "../connect/control-api";
+import { rawPublic } from "./keys";
+import { type ReplayGuard } from "./replay";
+
+export const RPC_PATH = "/api/peer/rpc";
+export const MAX_REQUEST_BODY = 100 * 1024 * 1024;
+export const MAX_RESPONSE_BODY = 80 * 1024 * 1024;
+const OVERHEAD = 64 * 1024;
+export const MAX_REQUEST_ENVELOPE = MAX_REQUEST_BODY + OVERHEAD;
+export const MAX_RESPONSE_ENVELOPE = MAX_RESPONSE_BODY + OVERHEAD;
+export const SKEW_MS = 120_000;
+
+export const MAX_HEADER = 1024;
+const MAX_META = 16 * 1024;
+const SIG = 64;
+const TAG = 16;
+const ZERO_IV = Buffer.alloc(12);
+const IV_LEN = 12;
+export const HEADER_SIG = SIG;
+const HDR_DOMAIN = Buffer.from("agentos-peer-hdr-v1");
+const REQ_DOMAIN = Buffer.from("agentos-peer-req-v1");
+const RES_DOMAIN = Buffer.from("agentos-peer-res-v1");
+const B64_16 = /^[A-Za-z0-9_-]{22}$/;
+const B64_32 = /^[A-Za-z0-9_-]{43}$/;
+
+export interface PeerRequest {
+  method: string;
+  path: string;
+  /** URL query without the "?"; checked against the route's keys. */
+  query: string;
+  contentType: string;
+  body: Buffer;
+}
+
+export interface PeerResponse {
+  status: number;
+  contentType: string;
+  body: Buffer;
+}
+
+export interface RequestHeader {
+  v: 1;
+  from: string;
+  to: string;
+  ts: number;
+  nonce: string;
+  epk: string;
+}
+
+/** Why an envelope was refused before anything inside it was trusted. */
+export type Refusal =
+  | "bad_envelope"
+  | "wrong_machine"
+  | "unknown_peer"
+  | "suspended"
+  | "bad_sig"
+  | "stale"
+  | "replay"
+  | "busy";
+
+const sha256 = (b: Buffer) => crypto.createHash("sha256").update(b).digest();
+
+function frame(meta: object, body: Buffer): Buffer {
+  const m = Buffer.from(JSON.stringify(meta));
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(m.length);
+  return Buffer.concat([len, m, body]);
+}
+
+function unframe(buf: Buffer, max: number): { meta: unknown; rest: Buffer } {
+  if (buf.length < 4) throw new Error("short");
+  const len = buf.readUInt32BE(0);
+  if (len > max || 4 + len > buf.length) throw new Error("bad length");
+  return {
+    meta: JSON.parse(buf.subarray(4, 4 + len).toString("utf8")),
+    rest: buf.subarray(4 + len),
+  };
+}
+
+function keysFor(
+  shared: Buffer,
+  nonce: Buffer,
+  from: string,
+  to: string
+): { req: Buffer; res: Buffer } {
+  const okm = Buffer.from(
+    crypto.hkdfSync(
+      "sha256",
+      shared,
+      nonce,
+      `agentos-peer-v1|${from}|${to}`,
+      64
+    )
+  );
+  return { req: okm.subarray(0, 32), res: okm.subarray(32) };
+}
+
+function seal(
+  key: Buffer,
+  plain: Buffer,
+  o: { aad?: Buffer; iv?: Buffer } = {}
+): Buffer {
+  const { aad, iv = ZERO_IV } = o;
+  const c = crypto.createCipheriv("chacha20-poly1305", key, iv, {
+    authTagLength: TAG,
+  });
+  if (aad) c.setAAD(aad, { plaintextLength: plain.length });
+  return Buffer.concat([c.update(plain), c.final(), c.getAuthTag()]);
+}
+
+function unseal(
+  key: Buffer,
+  ct: Buffer,
+  o: { aad?: Buffer; iv?: Buffer } = {}
+): Buffer {
+  const { aad, iv = ZERO_IV } = o;
+  if (ct.length < TAG) throw new Error("short");
+  const d = crypto.createDecipheriv("chacha20-poly1305", key, iv, {
+    authTagLength: TAG,
+  });
+  d.setAuthTag(ct.subarray(ct.length - TAG));
+  if (aad) d.setAAD(aad, { plaintextLength: ct.length - TAG });
+  return Buffer.concat([d.update(ct.subarray(0, ct.length - TAG)), d.final()]);
+}
+
+export interface Sealed {
+  envelope: Buffer;
+  nonce: Buffer;
+  /** Opens the answer to this request, and nothing else. */
+  resKey: Buffer;
+}
+
+export function sealRequest(o: {
+  from: string;
+  to: string;
+  signKey: KeyObject;
+  peerBox: KeyObject;
+  request: PeerRequest;
+  now?: number;
+}): Sealed {
+  const nonce = crypto.randomBytes(16);
+  const eph = crypto.generateKeyPairSync("x25519");
+  const header: RequestHeader = {
+    v: 1,
+    from: o.from,
+    to: o.to,
+    ts: o.now ?? Date.now(),
+    nonce: nonce.toString("base64url"),
+    epk: rawPublic(eph.publicKey),
+  };
+  const headerBytes = Buffer.from(JSON.stringify(header));
+  const shared = crypto.diffieHellman({
+    privateKey: eph.privateKey,
+    publicKey: o.peerBox,
+  });
+  const keys = keysFor(shared, nonce, o.from, o.to);
+  const { body, ...meta } = o.request;
+  const ct = seal(keys.req, frame(meta, body), { aad: headerBytes });
+  const sig = crypto.sign(
+    null,
+    Buffer.concat([REQ_DOMAIN, headerBytes, sha256(ct)]),
+    o.signKey
+  );
+  const hsig = crypto.sign(
+    null,
+    Buffer.concat([HDR_DOMAIN, headerBytes]),
+    o.signKey
+  );
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(headerBytes.length);
+  return {
+    envelope: Buffer.concat([len, headerBytes, hsig, ct, sig]),
+    nonce,
+    resKey: keys.res,
+  };
+}
+
+function parseHeader(raw: unknown): RequestHeader | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const h = raw as Record<string, unknown>;
+  const keys = Object.keys(h).sort().join(",");
+  if (keys !== "epk,from,nonce,to,ts,v") return null;
+  if (h.v !== 1) return null;
+  if (typeof h.from !== "string" || !MACHINE_ID.test(h.from)) return null;
+  if (typeof h.to !== "string" || !MACHINE_ID.test(h.to)) return null;
+  if (typeof h.ts !== "number" || !Number.isSafeInteger(h.ts)) return null;
+  if (typeof h.nonce !== "string" || !B64_16.test(h.nonce)) return null;
+  if (typeof h.epk !== "string" || !B64_32.test(h.epk)) return null;
+  return h as unknown as RequestHeader;
+}
+
+/** The header alone, as soon as it has arrived (to refuse early). */
+export function parseHeaderBytes(bytes: Buffer): RequestHeader | null {
+  try {
+    return parseHeader(JSON.parse(bytes.toString("utf8")));
+  } catch {
+    return null;
+  }
+}
+
+/** Whether the header alone is signed by `signKey`. */
+export function verifyHeader(
+  headerBytes: Buffer,
+  hsig: Buffer,
+  signKey: KeyObject
+): boolean {
+  try {
+    return crypto.verify(
+      null,
+      Buffer.concat([HDR_DOMAIN, headerBytes]),
+      signKey,
+      hsig
+    );
+  } catch {
+    return false;
+  }
+}
+
+export interface ParsedRequest {
+  header: RequestHeader;
+  headerBytes: Buffer;
+  hsig: Buffer;
+  ct: Buffer;
+  sig: Buffer;
+}
+
+/** The envelope's parts, or null when it isn't shaped like one. */
+export function parseRequest(envelope: Buffer): ParsedRequest | null {
+  try {
+    if (envelope.length > MAX_REQUEST_ENVELOPE) return null;
+    const { meta, rest } = unframe(envelope, MAX_HEADER);
+    const header = parseHeader(meta);
+    if (!header || rest.length < SIG + TAG + SIG) return null;
+    const headerLen = envelope.readUInt32BE(0);
+    return {
+      header,
+      headerBytes: envelope.subarray(4, 4 + headerLen),
+      hsig: rest.subarray(0, SIG),
+      ct: rest.subarray(SIG, rest.length - SIG),
+      sig: rest.subarray(rest.length - SIG),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export interface OpenDeps {
+  /** This machine's Connect id: an envelope for any other is refused. */
+  self: string;
+  boxKey: KeyObject;
+  /** The pinned signing key for a peer, or why there isn't one. */
+  signKeyFor: (machineId: string) => KeyObject | "unknown_peer" | "suspended";
+  replay: ReplayGuard;
+  now?: number;
+}
+
+export type Opened =
+  | {
+      ok: true;
+      header: RequestHeader;
+      request: PeerRequest;
+      nonce: Buffer;
+      resKey: Buffer;
+    }
+  | { ok: false; refusal: Refusal; header?: RequestHeader };
+
+/**
+ * Checks, in order: shape, addressed to this machine, a pinned peer, its
+ * signature, the clock, a fresh nonce; then decrypts. A nonce is remembered
+ * only once the signature holds, so nobody else can burn a peer's nonces.
+ */
+export function openRequest(envelope: Buffer, deps: OpenDeps): Opened {
+  const parsed = parseRequest(envelope);
+  if (!parsed) return { ok: false, refusal: "bad_envelope" };
+  const { header, headerBytes, hsig, ct, sig } = parsed;
+  const fail = (refusal: Refusal): Opened => ({ ok: false, refusal, header });
+  if (header.to !== deps.self) return fail("wrong_machine");
+  const signKey = deps.signKeyFor(header.from);
+  if (typeof signKey === "string") return fail(signKey);
+  let verified = verifyHeader(headerBytes, hsig, signKey);
+  try {
+    verified &&= crypto.verify(
+      null,
+      Buffer.concat([REQ_DOMAIN, headerBytes, sha256(ct)]),
+      signKey,
+      sig
+    );
+  } catch {
+    verified = false;
+  }
+  if (!verified) return fail("bad_sig");
+  const now = deps.now ?? Date.now();
+  const fresh = deps.replay.check(header.from, header.nonce, header.ts, now);
+  if (fresh !== "ok") return fail(fresh);
+  try {
+    const nonce = Buffer.from(header.nonce, "base64url");
+    const epk = crypto.createPublicKey({
+      key: { kty: "OKP", crv: "X25519", x: header.epk },
+      format: "jwk",
+    });
+    const shared = crypto.diffieHellman({
+      privateKey: deps.boxKey,
+      publicKey: epk,
+    });
+    const keys = keysFor(shared, nonce, header.from, header.to);
+    const { meta, rest } = unframe(
+      unseal(keys.req, ct, { aad: headerBytes }),
+      MAX_META
+    );
+    const request = parseInner(meta, rest);
+    if (!request) return fail("bad_envelope");
+    return { ok: true, header, request, nonce, resKey: keys.res };
+  } catch {
+    return fail("bad_envelope");
+  }
+}
+
+function parseInner(meta: unknown, body: Buffer): PeerRequest | null {
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return null;
+  const m = meta as Record<string, unknown>;
+  if (
+    typeof m.method !== "string" ||
+    typeof m.path !== "string" ||
+    typeof m.query !== "string" ||
+    typeof m.contentType !== "string" ||
+    body.length > MAX_REQUEST_BODY
+  )
+    return null;
+  return {
+    method: m.method,
+    path: m.path,
+    query: m.query,
+    contentType: m.contentType,
+    body,
+  };
+}
+
+export function sealResponse(o: {
+  resKey: Buffer;
+  nonce: Buffer;
+  signKey: KeyObject;
+  response: PeerResponse;
+}): Buffer {
+  const { body, ...meta } = o.response;
+  const iv = crypto.randomBytes(IV_LEN);
+  const ct = seal(o.resKey, frame(meta, body), { iv });
+  const sig = crypto.sign(
+    null,
+    Buffer.concat([RES_DOMAIN, o.nonce, iv, sha256(ct)]),
+    o.signKey
+  );
+  return Buffer.concat([iv, ct, sig]);
+}
+
+/** The answer to the request sealed with this nonce and key, from that peer. */
+export function openResponse(o: {
+  envelope: Buffer;
+  nonce: Buffer;
+  resKey: Buffer;
+  peerSign: KeyObject;
+}): PeerResponse {
+  const { envelope } = o;
+  if (
+    envelope.length < IV_LEN + TAG + SIG ||
+    envelope.length > MAX_RESPONSE_ENVELOPE
+  )
+    throw new Error("its answer isn't an envelope");
+  const iv = envelope.subarray(0, IV_LEN);
+  const ct = envelope.subarray(IV_LEN, envelope.length - SIG);
+  const sig = envelope.subarray(envelope.length - SIG);
+  let ok = false;
+  try {
+    ok = crypto.verify(
+      null,
+      Buffer.concat([RES_DOMAIN, o.nonce, iv, sha256(ct)]),
+      o.peerSign,
+      sig
+    );
+  } catch {
+    ok = false;
+  }
+  if (!ok) throw new Error("its answer isn't signed by the linked machine");
+  let meta: unknown;
+  let body: Buffer;
+  try {
+    ({ meta, rest: body } = unframe(unseal(o.resKey, ct, { iv }), MAX_META));
+  } catch {
+    throw new Error("its answer doesn't decrypt");
+  }
+  const m = (meta ?? {}) as Record<string, unknown>;
+  if (
+    typeof m.status !== "number" ||
+    !Number.isInteger(m.status) ||
+    m.status < 100 ||
+    m.status > 599 ||
+    typeof m.contentType !== "string"
+  )
+    throw new Error("its answer is malformed");
+  return { status: m.status, contentType: m.contentType, body };
+}

package/lib/peer/internal.ts

@@ -0,0 +1,22 @@
+/**
+ * The per-boot secret the rpc server's loopback hop carries, so the gate
+ * knows a request is a verified peer call and not this machine itself.
+ * Held on globalThis: server.ts and the gate must share one value.
+ */
+
+import crypto from "crypto";
+
+const g = globalThis as unknown as { __agentosPeerSecret?: string };
+
+export function peerSecret(): string {
+  g.__agentosPeerSecret ??= crypto.randomBytes(32).toString("hex");
+  return g.__agentosPeerSecret;
+}
+
+/** Constant-time: how much of the secret matched never shows in timing. */
+export function secretMatches(given: unknown, secret: string): boolean {
+  if (typeof given !== "string" || !secret) return false;
+  const a = Buffer.from(given);
+  const b = Buffer.from(secret);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}