@saadnvd1/agent-os 0.3.697 → 0.3.700

package/lib/peer/rpc-intake.ts

@@ -0,0 +1,258 @@
+/**
+ * Reading an envelope off the wire: how much memory envelopes may hold
+ * before and after their sender is proven, and how slowly one may arrive.
+ * The sender is proven by the header's own signature, before any of the
+ * body is held for it. Every sender, linked or not, goes through exactly
+ * this, so neither the time to a refusal nor a `busy` says whether a machine
+ * is linked here.
+ */
+
+import type { IncomingMessage } from "http";
+import { isIP } from "net";
+import { isTunnelSocket } from "../security/auth";
+import {
+  HEADER_SIG,
+  MAX_HEADER,
+  MAX_REQUEST_ENVELOPE,
+  type Refusal,
+} from "./envelope";
+
+/**
+ * One request's share of the budget. Bytes are held against its source until
+ * prove() names the sender whose header signature held, then against that
+ * sender; close() gives back everything it took.
+ */
+export interface Ticket {
+  take(bytes: number): boolean;
+  prove(peer: string): boolean;
+  close(): void;
+}
+
+/**
+ * Bytes held by envelopes still arriving. Before the header's signature is
+ * checked they count against the source address, in a small pool of their
+ * own, so strangers can't touch what linked machines get; after, against
+ * the proven sender. Each share is well below its total, and one source may
+ * have only a few requests open.
+ */
+export interface BodyBudget {
+  open(source: string): Ticket | null;
+}
+
+export interface BudgetLimits {
+  /** Bytes of proven senders' envelopes, in all and per sender. */
+  total: number;
+  perPeer: number;
+  /** Bytes not yet proven, in all and per source. */
+  unverifiedTotal: number;
+  perSource: number;
+  requestsPerSource: number;
+}
+
+export const DEFAULT_BUDGET: BudgetLimits = {
+  total: 4 * MAX_REQUEST_ENVELOPE,
+  perPeer: MAX_REQUEST_ENVELOPE,
+  unverifiedTotal: 4 * 1024 * 1024,
+  perSource: 256 * 1024,
+  requestsPerSource: 4,
+};
+
+export function createBodyBudget(o: Partial<BudgetLimits> = {}): BodyBudget {
+  const lim = { ...DEFAULT_BUDGET, ...o };
+  let proven = 0;
+  let unproven = 0;
+  const byPeer = new Map<string, number>();
+  const bySource = new Map<string, number>();
+  const open = new Map<string, number>();
+  const add = (m: Map<string, number>, k: string, n: number) => {
+    const v = (m.get(k) ?? 0) + n;
+    if (v > 0) m.set(k, v);
+    else m.delete(k);
+  };
+  return {
+    open(source) {
+      if ((open.get(source) ?? 0) >= lim.requestsPerSource) return null;
+      add(open, source, 1);
+      let peer: string | null = null;
+      let held = 0;
+      let closed = false;
+      const fits = (who: string | null, bytes: number) =>
+        who === null
+          ? unproven + bytes <= lim.unverifiedTotal &&
+            (bySource.get(source) ?? 0) + bytes <= lim.perSource
+          : proven + bytes <= lim.total &&
+            (byPeer.get(who) ?? 0) + bytes <= lim.perPeer;
+      const charge = (who: string | null, bytes: number) => {
+        if (who === null) {
+          unproven += bytes;
+          add(bySource, source, bytes);
+        } else {
+          proven += bytes;
+          add(byPeer, who, bytes);
+        }
+      };
+      return {
+        take(bytes) {
+          if (closed || !fits(peer, bytes)) return false;
+          charge(peer, bytes);
+          held += bytes;
+          return true;
+        },
+        prove(who) {
+          if (closed || peer !== null || !fits(who, held)) return false;
+          charge(null, -held);
+          charge(who, held);
+          peer = who;
+          return true;
+        },
+        close() {
+          if (closed) return;
+          closed = true;
+          charge(peer, -held);
+          add(open, source, -1);
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Where a request came from: the visitor's address Cloudflare stamps on a
+ * tunnel request (the socket there is always cloudflared), else the socket's.
+ * An IPv6 address counts by its /64: one host is usually handed a whole one.
+ */
+export function sourceOf(req: IncomingMessage): string {
+  let addr = req.socket.remoteAddress ?? "unknown";
+  if (isTunnelSocket(req.socket)) {
+    const cf = String(req.headers["cf-connecting-ip"] ?? "").trim();
+    if (isIP(cf)) addr = cf;
+  }
+  return isIP(addr) === 6 ? ipv6Prefix64(addr) : addr;
+}
+
+/** The first four groups of an IPv6 address, expanded: its /64. */
+export function ipv6Prefix64(addr: string): string {
+  const plain = addr.split("%")[0].toLowerCase();
+  if (/^::ffff:\d+\.\d+\.\d+\.\d+$/.test(plain)) return plain.slice(7);
+  const [head, tail = ""] = plain.split("::");
+  const a = head ? head.split(":") : [];
+  const b = plain.includes("::") && tail ? tail.split(":") : [];
+  // An embedded IPv4 tail takes two groups; it never reaches the first four
+  // unless the address is mostly zeros, which then pads them.
+  const fill = Array(Math.max(0, 8 - a.length - b.length)).fill("0");
+  const groups = [...a, ...fill, ...b].slice(0, 4);
+  return `${groups.map((g) => g.replace(/^0+(?=.)/, "")).join(":")}::/64`;
+}
+
+export interface Pace {
+  /** How long the header and its signature may take: they fit in the
+   * first packet, so a sender that holds them back is stalling. */
+  headerMs: number;
+  /** How long the first bytes may take before a rate is required. */
+  graceMs: number;
+  /** Bytes per second the body must keep up after the grace period, */
+  minRate: number;
+  /** measured over each window this long, so a burst can't bank time. */
+  windowMs: number;
+}
+
+export const DEFAULT_PACE: Pace = {
+  headerMs: 3_000,
+  graceMs: 10_000,
+  minRate: 512 * 1024,
+  windowMs: 5_000,
+};
+
+export type Read =
+  | { body: Buffer }
+  | { refusal: Refusal }
+  | { tooLarge: true }
+  | { tooSlow: true };
+
+/**
+ * The body, at most MAX_REQUEST_ENVELOPE bytes. `early` sees the header and
+ * its signature as soon as they've arrived, and returns the proven sender or
+ * a refusal. Every byte held must be granted by the ticket, or reading stops
+ * as busy; a body slower than `pace` stops as too slow.
+ */
+export function readEnvelope(
+  req: IncomingMessage,
+  o: {
+    early: (
+      headerBytes: Buffer,
+      headerSig: Buffer
+    ) => { peer: string } | { refusal: Refusal };
+    ticket: Ticket;
+    pace: Pace;
+  }
+): Promise<Read> {
+  return new Promise((resolve, reject) => {
+    if (Number(req.headers["content-length"]) > MAX_REQUEST_ENVELOPE)
+      return resolve({ tooLarge: true });
+    const chunks: Buffer[] = [];
+    const started = Date.now();
+    let total = 0;
+    let proven = false;
+    let done = false;
+    const finish = (v: Read | Error) => {
+      if (done) return;
+      done = true;
+      clearInterval(timer);
+      // An unread rest is dropped with the connection (Connection: close).
+      req.removeAllListeners("data");
+      if (v instanceof Error) reject(v);
+      else resolve(v);
+    };
+    const { headerMs, graceMs, minRate, windowMs } = o.pace;
+    // (time, bytes so far), back to the start of the current window.
+    const samples = [{ t: started, total: 0 }];
+    const timer = setInterval(
+      () => {
+        const now = Date.now();
+        samples.push({ t: now, total });
+        while (samples.length > 1 && samples[1].t <= now - windowMs)
+          samples.shift();
+        if (!proven && now - started > headerMs)
+          return finish({ tooSlow: true });
+        if (now - started <= graceMs) return;
+        const base = samples[0];
+        if (total - base.total < ((now - base.t) / 1000) * minRate)
+          finish({ tooSlow: true });
+      },
+      Math.max(25, Math.min(1000, headerMs / 4, graceMs / 4, windowMs / 4))
+    );
+    req.on("data", (chunk: Buffer) => {
+      if (done) return;
+      total += chunk.length;
+      if (total > MAX_REQUEST_ENVELOPE) return finish({ tooLarge: true });
+      if (!o.ticket.take(chunk.length)) return finish({ refusal: "busy" });
+      chunks.push(chunk);
+      if (proven || total < 4) return;
+      const head = chunks.length === 1 ? chunks[0] : Buffer.concat(chunks);
+      chunks.splice(0, chunks.length, head);
+      const len = head.readUInt32BE(0);
+      if (len > MAX_HEADER) return finish({ refusal: "bad_envelope" });
+      if (head.length < 4 + len + HEADER_SIG) return;
+      let seen;
+      try {
+        seen = o.early(
+          head.subarray(4, 4 + len),
+          head.subarray(4 + len, 4 + len + HEADER_SIG)
+        );
+      } catch {
+        // A throw here would escape the 'data' handler and take the server
+        // down; whatever failed (the database, say), the caller is told busy.
+        return finish({ refusal: "busy" });
+      }
+      if ("refusal" in seen) return finish({ refusal: seen.refusal });
+      if (!o.ticket.prove(seen.peer)) return finish({ refusal: "busy" });
+      proven = true;
+    });
+    req.on("end", () => {
+      if (total >= 4 && !proven && !done)
+        return finish({ refusal: "bad_envelope" });
+      finish({ body: Buffer.concat(chunks) });
+    });
+    req.on("error", (err) => finish(err));
+  });
+}

package/lib/peer/rpc-server.ts

@@ -0,0 +1,369 @@
+/**
+ * POST /api/peer/rpc: a linked machine's call, served before Next on any
+ * listener (the envelope is the authentication, not where it came from).
+ *
+ *  0. with no active link, refuse before reading anything;
+ *  1. read the envelope under a byte budget and a minimum transfer rate
+ *     (rpc-intake.ts), proving the sender from the header's own signature
+ *     before any of the body is held for it;
+ *  2. verify and decrypt it against the sender's pinned keys (envelope.ts);
+ *  3. match the inner method, path and query against the allowlist;
+ *  4. re-issue it to this machine's own loopback listener with the per-boot
+ *     secret, so the gate stamps `peer` trust and every route and guard runs
+ *     exactly as it does for any other caller.
+ *
+ * Refusals before decryption are plain and fixed (`bad envelope`, `bad
+ * signature`, `stale`, `replay`, `busy`). An unknown sender, a suspended one
+ * and a bad signature all read `bad signature`, so a stranger can't tell
+ * which machines are linked here; the audit keeps the difference. Everything
+ * after is inside the envelope,
+ * always HTTP 200, so whoever carries the traffic never learns the route or
+ * its status.
+ */
+
+import crypto from "crypto";
+import http, { type IncomingMessage, type ServerResponse } from "http";
+import { PEER_HEADER, PEER_INTERNAL_HEADER } from "../security/auth";
+import { matchPeerRoute } from "./allowlist";
+import { recordPeerCall, type AuditEntry, type Outcome } from "./audit";
+import {
+  MAX_RESPONSE_BODY,
+  RPC_PATH,
+  SKEW_MS,
+  openRequest,
+  parseHeaderBytes,
+  sealResponse,
+  type PeerResponse,
+  type Refusal,
+  verifyHeader,
+} from "./envelope";
+import { peerSecret } from "./internal";
+import {
+  currentIdentity,
+  loadBoxKey,
+  signPublic,
+  type BoxKey,
+  type Identity,
+} from "./keys";
+import { hasActivePin, pinForMachine, type PeerPin } from "./links";
+import { sqliteNonceStore } from "./nonce-store";
+import { createReplayGuard, type ReplayGuard } from "./replay";
+import {
+  DEFAULT_PACE,
+  createBodyBudget,
+  readEnvelope,
+  sourceOf,
+  type BodyBudget,
+  type Pace,
+} from "./rpc-intake";
+
+export { createBodyBudget };
+
+export { RPC_PATH };
+const DISPATCH_TIMEOUT_MS = 10 * 60_000;
+
+export interface Dispatch {
+  hostId: string;
+  method: string;
+  path: string;
+  query: string;
+  contentType: string;
+  body: Buffer;
+}
+
+export interface RpcDeps {
+  identity: () => Identity | null;
+  boxKey: () => BoxKey;
+  pinForMachine: (machineId: string) => PeerPin | null;
+  /** False while no link is active: the route is closed to everyone. */
+  anyActive: () => boolean;
+  replay: ReplayGuard;
+  dispatch: (d: Dispatch) => Promise<PeerResponse>;
+  audit: (e: AuditEntry) => void;
+  budget: BodyBudget;
+  pace?: Pace;
+  now?: () => number;
+}
+
+// Stands in for an unknown or suspended sender's key, so its envelope takes
+// the same path, and the same time, to the same refusal as a bad signature.
+const DECOY_KEY = crypto.generateKeyPairSync("ed25519").publicKey;
+
+export const isPeerRpc = (req: IncomingMessage) =>
+  (req.url ?? "").split("?")[0] === RPC_PATH;
+
+const REFUSED: Record<Refusal, [number, string, Outcome]> = {
+  bad_envelope: [400, "bad envelope", "bad_envelope"],
+  wrong_machine: [401, "bad signature", "bad_sig"],
+  unknown_peer: [401, "bad signature", "unknown_peer"],
+  suspended: [401, "bad signature", "suspended"],
+  bad_sig: [401, "bad signature", "bad_sig"],
+  stale: [401, "stale", "stale"],
+  replay: [401, "replay", "replay"],
+  busy: [429, "busy", "busy"],
+};
+
+function plain(res: ServerResponse, status: number, text: string) {
+  if (res.headersSent) return;
+  res.statusCode = status;
+  res.setHeader("Content-Type", "text/plain");
+  res.setHeader("Cache-Control", "no-store");
+  res.setHeader("Connection", "close");
+  res.end(text);
+}
+
+export async function handlePeerRpc(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: RpcDeps
+): Promise<void> {
+  const started = Date.now();
+  if (req.method !== "POST") {
+    res.setHeader("Allow", "POST");
+    return plain(res, 405, "method not allowed");
+  }
+  const self = deps.identity();
+  let fromMachine: string | null = null;
+  let pin: PeerPin | null = null;
+  const audit = (
+    outcome: Outcome,
+    status: number,
+    route = RPC_PATH,
+    method = "POST",
+    bytes = 0
+  ) =>
+    deps.audit({
+      hostId: pin?.hostId ?? null,
+      machineId: fromMachine,
+      direction: "in",
+      method,
+      route,
+      status,
+      ms: Date.now() - started,
+      bytes,
+      outcome,
+    });
+  const refuse = (refusal: Refusal): null => {
+    const [status, text, outcome] = REFUSED[refusal];
+    audit(outcome, status);
+    plain(res, status, text);
+    return null;
+  };
+  // The sender's pinned signing key, or a decoy that verifies nothing for an
+  // unknown or suspended one, so its refusal takes the same path and time
+  // as a bad signature; `hidden` keeps what the check would have said.
+  let hidden: "unknown_peer" | "suspended" | null = null;
+  const signKeyFor = (machineId: string) => {
+    fromMachine = machineId;
+    const found = (pin = deps.pinForMachine(machineId));
+    hidden = !found
+      ? "unknown_peer"
+      : found.state !== "active"
+        ? "suspended"
+        : null;
+    if (!found || hidden) return DECOY_KEY;
+    try {
+      return signPublic(found.signPub);
+    } catch {
+      hidden = "unknown_peer";
+      return DECOY_KEY;
+    }
+  };
+  const refuseHidden = (refusal: Refusal): null =>
+    refuse(refusal === "bad_sig" && hidden ? hidden : refusal);
+  const drop = (status: number, text: string, outcome: Outcome): null => {
+    audit(outcome, status);
+    plain(res, status, text);
+    return null;
+  };
+
+  // The one nonce the header claimed: the whole envelope must carry it.
+  let claimed: string | null = null;
+  const spent: ReplayGuard = {
+    check: (peer, nonce) =>
+      claimed !== null && claimed === `${peer}:${nonce}` ? "ok" : "replay",
+  };
+
+  if (!deps.anyActive()) return plain(res, 404, "not found");
+  const ticket = deps.budget.open(sourceOf(req));
+  if (!ticket) return void refuse("busy");
+  const readAndOpen = async () => {
+    let read;
+    try {
+      read = await readEnvelope(req, {
+        early: (headerBytes, headerSig) => {
+          const header = parseHeaderBytes(headerBytes);
+          if (!header) return { refusal: "bad_envelope" };
+          if (!self || header.to !== self.machineId)
+            return { refusal: "wrong_machine" };
+          if (!verifyHeader(headerBytes, headerSig, signKeyFor(header.from)))
+            return { refusal: "bad_sig" };
+          const now = deps.now?.() ?? Date.now();
+          if (Math.abs(now - header.ts) > SKEW_MS) return { refusal: "stale" };
+          // The nonce is spent the moment its header is proven, so a header
+          // seen on the wire can't be sent again with junk bodies to hold
+          // the sender's share while the first is still arriving.
+          const fresh = deps.replay.check(
+            header.from,
+            header.nonce,
+            header.ts,
+            now
+          );
+          if (fresh !== "ok") return { refusal: fresh };
+          claimed = `${header.from}:${header.nonce}`;
+          return { peer: header.from };
+        },
+        ticket,
+        pace: deps.pace ?? DEFAULT_PACE,
+      });
+    } catch {
+      return drop(400, "bad envelope", "bad_envelope");
+    }
+    if ("tooLarge" in read) return drop(413, "too large", "too_large");
+    if ("tooSlow" in read) return drop(408, "too slow", "too_slow");
+    if ("refusal" in read) return refuseHidden(read.refusal);
+    if (!self) return refuse("wrong_machine");
+    return openRequest(read.body, {
+      self: self.machineId,
+      boxKey: deps.boxKey().privateKey,
+      signKeyFor,
+      replay: spent,
+      now: deps.now?.(),
+    });
+  };
+  let opened;
+  try {
+    opened = await readAndOpen();
+  } finally {
+    ticket.close();
+  }
+  if (!opened || !self) return;
+  if (!opened.ok) return void refuseHidden(opened.refusal);
+  const host = pin as PeerPin | null;
+  if (!host) return void refuse("unknown_peer");
+
+  const answer = (response: PeerResponse, outcome: Outcome, route: string) => {
+    const sealed = sealResponse({
+      resKey: opened.resKey,
+      nonce: opened.nonce,
+      signKey: self.signKey,
+      response,
+    });
+    audit(
+      outcome,
+      response.status,
+      route,
+      opened.request.method.slice(0, 10),
+      opened.request.body.length + response.body.length
+    );
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "application/octet-stream");
+    res.setHeader("Cache-Control", "no-store");
+    res.end(sealed);
+  };
+
+  const { request } = opened;
+  const match = matchPeerRoute(request.method, request.path, request.query);
+  if (!match.ok)
+    return answer(
+      jsonResponse(403, { error: "That route isn't open to linked machines." }),
+      "denied_route",
+      "(denied)"
+    );
+  let response: PeerResponse;
+  try {
+    response = await deps.dispatch({
+      hostId: host.hostId,
+      method: request.method,
+      path: match.path,
+      query: match.query,
+      contentType: request.contentType,
+      body: request.body,
+    });
+  } catch (err) {
+    response = jsonResponse(502, {
+      error:
+        `Couldn't run that here: ${err instanceof Error ? err.message : String(err)}`.slice(
+          0,
+          300
+        ),
+    });
+  }
+  answer(response, "ok", match.route);
+}
+
+const jsonResponse = (status: number, body: object): PeerResponse => ({
+  status,
+  contentType: "application/json",
+  body: Buffer.from(JSON.stringify(body)),
+});
+
+const CONTENT_TYPE = /^[\w.+-]+\/[\w.+-]+(;[ \w.+=\-"]*)?$/;
+
+/** Re-issues a verified call to this machine's own loopback listener. */
+export function loopbackDispatch(
+  port: number,
+  secret: () => string = peerSecret
+): (d: Dispatch) => Promise<PeerResponse> {
+  return (d) =>
+    new Promise((resolve, reject) => {
+      const contentType =
+        d.contentType.length <= 200 && CONTENT_TYPE.test(d.contentType)
+          ? d.contentType
+          : "application/octet-stream";
+      const out = http.request(
+        {
+          host: "127.0.0.1",
+          port,
+          method: d.method,
+          path: d.query ? `${d.path}?${d.query}` : d.path,
+          headers: {
+            host: `127.0.0.1:${port}`,
+            ...(d.body.length > 0 && { "content-type": contentType }),
+            "content-length": String(d.body.length),
+            [PEER_INTERNAL_HEADER]: secret(),
+            [PEER_HEADER]: d.hostId,
+          },
+          timeout: DISPATCH_TIMEOUT_MS,
+        },
+        (res) => {
+          const chunks: Buffer[] = [];
+          let total = 0;
+          res.on("data", (c: Buffer) => {
+            total += c.length;
+            if (total > MAX_RESPONSE_BODY) {
+              res.destroy();
+              return reject(new Error("its answer is too large"));
+            }
+            chunks.push(c);
+          });
+          res.on("end", () =>
+            resolve({
+              status: res.statusCode ?? 502,
+              contentType: String(res.headers["content-type"] ?? ""),
+              body: Buffer.concat(chunks),
+            })
+          );
+          res.on("error", reject);
+        }
+      );
+      out.on("timeout", () => out.destroy(new Error("timed out")));
+      out.on("error", reject);
+      out.end(d.body);
+    });
+}
+
+/** The real dependencies: this machine's keys, its pins and its listener. */
+export function rpcDeps(port: number): RpcDeps {
+  let box: BoxKey | null = null;
+  return {
+    identity: () => currentIdentity(),
+    boxKey: () => (box ??= loadBoxKey()),
+    pinForMachine,
+    anyActive: hasActivePin,
+    replay: createReplayGuard({ store: sqliteNonceStore() }),
+    dispatch: loopbackDispatch(port),
+    audit: recordPeerCall,
+    budget: createBodyBudget(),
+  };
+}

package/lib/schedules/when.ts

@@ -26,7 +26,7 @@ const UNIT_MS: Record<string, number> = {
   d: 86_400_000,
 };
 
-function duration(text: string): number | null {
+export function duration(text: string): number | null {
   let total = 0;
   const rest = text.replace(
     /(\d+(?:\.\d+)?|an?)\s*(minutes?|mins?|m|hours?|hrs?|h|days?|d)\b/g,