@saadnvd1/agent-os 0.3.697 → 0.3.700

package/lib/peer/hello.ts

@@ -0,0 +1,346 @@
+/**
+ * The pairing messages between two machines, and the code both show.
+ * Everything here is public data, signed by its sender with its Connect
+ * machine key; each signature covers a domain string, both machine ids, a
+ * timestamp and a nonce, so no message stands in for another or for another
+ * pair of machines.
+ *
+ *   A → B  hello   {from, to, ts, nonce, sign_pub, box_pub, commit}
+ *          commit = SHA-256(a_box ‖ a_sign ‖ a_nonce)
+ *   B → A  ack     {request_id, sign_pub, box_pub, b_nonce}   (bound to the hello)
+ *   A → B  reveal  {request_id, a_nonce}
+ *   A → B  status  {request_id}
+ *   B → A  answer  {state}                          (bound to that call's nonce)
+ *
+ * The code is HKDF over both machines' keys and both nonces. A has fixed
+ * its keys and nonce before it sees b_nonce, and B's nonce is fresh, so
+ * whoever substitutes keys gets one guess in a million per attempt.
+ *
+ * Two codes come from that transcript. A shows the first and a person types
+ * it on B, which proves to B that A's keys are the ones it holds. B then
+ * shows the second (a different HKDF info) and the person types it on A:
+ * that proves B's keys to A, so a control plane that lists a key of its own
+ * for B gets nothing pinned on either side.
+ */
+
+import crypto, { type KeyObject } from "crypto";
+import { MACHINE_ID } from "../connect/control-api";
+import { SKEW_MS } from "./envelope";
+import { signPublic } from "./keys";
+
+export const HELLO_MAX_BYTES = 4096;
+export { SKEW_MS };
+
+const B64_16 = /^[A-Za-z0-9_-]{22}$/;
+const B64_32 = /^[A-Za-z0-9_-]{43}$/;
+const B64_SIG = /^[A-Za-z0-9_-]{86}$/;
+
+export type LinkState = "pending" | "accepted" | "declined" | "expired";
+const STATES: readonly LinkState[] = [
+  "pending",
+  "accepted",
+  "declined",
+  "expired",
+];
+
+const D = {
+  hello: "agentos-peer-hello-v1",
+  ack: "agentos-peer-hello-ack-v1",
+  reveal: "agentos-peer-reveal-v1",
+  status: "agentos-peer-status-v1",
+  answer: "agentos-peer-answer-v1",
+} as const;
+
+const b64 = (b: Buffer) => b.toString("base64url");
+const raw = (s: string) => Buffer.from(s, "base64url");
+export const randomNonce = (bytes: 16 | 32) => b64(crypto.randomBytes(bytes));
+
+// Every field is checked against a pattern with no newline before it's
+// signed or verified, so joining with "\n" is unambiguous.
+const message = (domain: string, fields: (string | number)[]) =>
+  Buffer.from([domain, ...fields.map(String)].join("\n"));
+
+const signFields = (
+  key: KeyObject,
+  domain: string,
+  fields: (string | number)[]
+) => b64(crypto.sign(null, message(domain, fields), key));
+
+function verifyFields(
+  pub: string,
+  sig: string,
+  domain: string,
+  fields: (string | number)[]
+): boolean {
+  if (!B64_SIG.test(sig)) return false;
+  try {
+    return crypto.verify(
+      null,
+      message(domain, fields),
+      signPublic(pub),
+      raw(sig)
+    );
+  } catch {
+    return false;
+  }
+}
+
+export const commitTo = (boxPub: string, signPub: string, nonce: string) =>
+  b64(
+    crypto
+      .createHash("sha256")
+      .update(Buffer.concat([raw(boxPub), raw(signPub), raw(nonce)]))
+      .digest()
+  );
+
+export interface Transcript {
+  from: string;
+  to: string;
+  aSign: string;
+  aBox: string;
+  bSign: string;
+  bBox: string;
+  aNonce: string;
+  bNonce: string;
+}
+
+const INFO = { sas: "agentos-peer-sas-v1", confirm: "agentos-peer-confirm-v1" };
+
+/**
+ * Six digits from both sides' keys and nonces: `sas` is shown on A and typed
+ * on B, `confirm` is shown on B once that matched and typed on A.
+ */
+export function deriveCode(
+  o: Transcript,
+  purpose: keyof typeof INFO = "sas"
+): string {
+  const ikm = Buffer.concat(
+    [o.aSign, o.aBox, o.bSign, o.bBox, o.aNonce, o.bNonce].map(raw)
+  );
+  const okm = Buffer.from(
+    crypto.hkdfSync(
+      "sha256",
+      ikm,
+      Buffer.alloc(0),
+      `${INFO[purpose]}|${o.from}|${o.to}`,
+      8
+    )
+  );
+  return (okm.readBigUInt64BE(0) % BigInt(1_000_000))
+    .toString()
+    .padStart(6, "0");
+}
+
+export { showCode } from "./code";
+
+/** What a person typed, as six digits, or null. */
+export function typedCode(input: unknown): string | null {
+  if (typeof input !== "string" || input.length > 32) return null;
+  const digits = input.replace(/[\s-]/g, "");
+  return /^\d{6}$/.test(digits) ? digits : null;
+}
+
+export const sameCode = (a: string, b: string) =>
+  a.length === b.length &&
+  crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+
+// ----- the messages -----
+
+interface Signed {
+  from: string;
+  to: string;
+  ts: number;
+  nonce: string;
+  sig: string;
+}
+
+export interface Hello extends Signed {
+  v: 1;
+  sign_pub: string;
+  box_pub: string;
+  commit: string;
+}
+
+export interface Ack {
+  request_id: string;
+  sign_pub: string;
+  box_pub: string;
+  b_nonce: string;
+  sig: string;
+}
+
+export interface Reveal extends Signed {
+  v: 1;
+  request_id: string;
+  a_nonce: string;
+}
+
+export interface StatusAsk extends Signed {
+  v: 1;
+  request_id: string;
+}
+
+export interface Answer {
+  state: LinkState;
+  sig: string;
+}
+
+const obj = (v: unknown): Record<string, unknown> | null =>
+  v && typeof v === "object" && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : null;
+
+function parseSigned(v: unknown): (Record<string, unknown> & Signed) | null {
+  const o = obj(v);
+  if (!o || o.v !== 1) return null;
+  if (typeof o.from !== "string" || !MACHINE_ID.test(o.from)) return null;
+  if (typeof o.to !== "string" || !MACHINE_ID.test(o.to)) return null;
+  if (typeof o.ts !== "number" || !Number.isSafeInteger(o.ts)) return null;
+  if (typeof o.nonce !== "string" || !B64_16.test(o.nonce)) return null;
+  if (typeof o.sig !== "string" || !B64_SIG.test(o.sig)) return null;
+  return o as Record<string, unknown> & Signed;
+}
+
+const is32 = (v: unknown): v is string =>
+  typeof v === "string" && B64_32.test(v);
+const is16 = (v: unknown): v is string =>
+  typeof v === "string" && B64_16.test(v);
+
+export function parseHello(v: unknown): Hello | null {
+  const o = parseSigned(v);
+  if (!o || !is32(o.sign_pub) || !is32(o.box_pub) || !is32(o.commit))
+    return null;
+  return o as unknown as Hello;
+}
+
+export function parseReveal(v: unknown): Reveal | null {
+  const o = parseSigned(v);
+  if (!o || !is16(o.request_id) || !is32(o.a_nonce)) return null;
+  return o as unknown as Reveal;
+}
+
+export function parseStatusAsk(v: unknown): StatusAsk | null {
+  const o = parseSigned(v);
+  if (!o || !is16(o.request_id)) return null;
+  return o as unknown as StatusAsk;
+}
+
+export function parseAck(v: unknown): Ack | null {
+  const o = obj(v);
+  if (!o || !is16(o.request_id) || !is32(o.sign_pub) || !is32(o.box_pub))
+    return null;
+  if (!is32(o.b_nonce) || typeof o.sig !== "string" || !B64_SIG.test(o.sig))
+    return null;
+  return o as unknown as Ack;
+}
+
+export function parseAnswer(v: unknown): Answer | null {
+  const o = obj(v);
+  if (!o || !STATES.includes(o.state as LinkState)) return null;
+  if (typeof o.sig !== "string" || !B64_SIG.test(o.sig)) return null;
+  return o as unknown as Answer;
+}
+
+const helloFields = (h: Omit<Hello, "sig" | "v">) => [
+  h.from,
+  h.to,
+  h.ts,
+  h.nonce,
+  h.sign_pub,
+  h.box_pub,
+  h.commit,
+];
+
+export function signHello(key: KeyObject, h: Omit<Hello, "sig" | "v">): Hello {
+  return { v: 1, ...h, sig: signFields(key, D.hello, helloFields(h)) };
+}
+
+export const verifyHello = (h: Hello) =>
+  verifyFields(h.sign_pub, h.sig, D.hello, helloFields(h));
+
+// The ack names both machines and the hello it answers.
+const ackFields = (a: Omit<Ack, "sig">, hello: Hello) => [
+  hello.to,
+  hello.from,
+  hello.nonce,
+  a.request_id,
+  a.sign_pub,
+  a.box_pub,
+  a.b_nonce,
+];
+
+export function signAck(
+  key: KeyObject,
+  a: Omit<Ack, "sig">,
+  hello: Hello
+): Ack {
+  return { ...a, sig: signFields(key, D.ack, ackFields(a, hello)) };
+}
+
+export const verifyAck = (a: Ack, hello: Hello, bSign: string) =>
+  a.sign_pub === bSign &&
+  verifyFields(bSign, a.sig, D.ack, ackFields(a, hello));
+
+const revealFields = (r: Omit<Reveal, "sig" | "v">) => [
+  r.from,
+  r.to,
+  r.ts,
+  r.nonce,
+  r.request_id,
+  r.a_nonce,
+];
+
+export function signReveal(
+  key: KeyObject,
+  r: Omit<Reveal, "sig" | "v">
+): Reveal {
+  return { v: 1, ...r, sig: signFields(key, D.reveal, revealFields(r)) };
+}
+
+export const verifyReveal = (r: Reveal, aSign: string) =>
+  verifyFields(aSign, r.sig, D.reveal, revealFields(r));
+
+const statusFields = (s: Omit<StatusAsk, "sig" | "v">) => [
+  s.from,
+  s.to,
+  s.ts,
+  s.nonce,
+  s.request_id,
+];
+
+export function signStatusAsk(
+  key: KeyObject,
+  s: Omit<StatusAsk, "sig" | "v">
+): StatusAsk {
+  return { v: 1, ...s, sig: signFields(key, D.status, statusFields(s)) };
+}
+
+export const verifyStatusAsk = (s: StatusAsk, aSign: string) =>
+  verifyFields(aSign, s.sig, D.status, statusFields(s));
+
+/** B's answer to a reveal or a status call, bound to that call. */
+const answerFields = (state: LinkState, ask: Reveal | StatusAsk) => [
+  ask.to,
+  ask.from,
+  ask.request_id,
+  ask.nonce,
+  state,
+];
+
+export const signAnswer = (
+  key: KeyObject,
+  state: LinkState,
+  ask: Reveal | StatusAsk
+): Answer => ({
+  state,
+  sig: signFields(key, D.answer, answerFields(state, ask)),
+});
+
+export const verifyAnswer = (
+  a: Answer,
+  ask: Reveal | StatusAsk,
+  bSign: string
+) => verifyFields(bSign, a.sig, D.answer, answerFields(a.state, ask));
+
+export const withinSkew = (ts: number, now: number) =>
+  Math.abs(now - ts) <= SKEW_MS;

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);
+}

package/lib/peer/keys.ts

@@ -0,0 +1,122 @@
+/**
+ * The keys a machine uses with its linked peers. The signing key is
+ * Connect's machine.key (Ed25519); the box key (X25519) is peer.key next to
+ * it, made on first use, owner-only, and never sent to the Connect service.
+ * Public keys travel as base64url of their 32 raw bytes.
+ */
+
+import crypto, { type KeyObject } from "crypto";
+import fs from "fs";
+import path from "path";
+import { connectDir, readConnect } from "../connect/config";
+
+const RAW = /^[A-Za-z0-9_-]{43}$/;
+
+export const rawPublic = (key: KeyObject): string => {
+  const jwk = key.export({ format: "jwk" });
+  if (typeof jwk.x !== "string") throw new Error("not an OKP key");
+  return jwk.x;
+};
+
+function publicFromRaw(raw: string, crv: "Ed25519" | "X25519"): KeyObject {
+  if (!RAW.test(raw)) throw new Error(`bad ${crv} public key`);
+  const key = crypto.createPublicKey({
+    key: { kty: "OKP", crv, x: raw },
+    format: "jwk",
+  });
+  if (key.asymmetricKeyType !== crv.toLowerCase())
+    throw new Error(`bad ${crv} public key`);
+  return key;
+}
+
+export const signPublic = (raw: string) => publicFromRaw(raw, "Ed25519");
+export const boxPublic = (raw: string) => publicFromRaw(raw, "X25519");
+
+export interface BoxKey {
+  privateKey: KeyObject;
+  publicRaw: string;
+}
+
+/**
+ * Makes sure `p` is this user's and nobody else's: repairs group or other
+ * access, refuses one owned by someone else.
+ */
+function ownerOnly(p: string, mode: number) {
+  if (process.platform === "win32") return;
+  const st = fs.lstatSync(p);
+  if (st.isSymbolicLink()) throw new Error(`${p} is a symlink`);
+  if (typeof process.getuid === "function" && st.uid !== process.getuid())
+    throw new Error(`${p} belongs to another user`);
+  if (st.mode & 0o077) fs.chmodSync(p, mode);
+}
+
+/** peer.key, created owner-only if it isn't there yet. */
+export function loadBoxKey(dir = connectDir()): BoxKey {
+  const file = path.join(dir, "peer.key");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  ownerOnly(dir, 0o700);
+  if (!fs.existsSync(file)) {
+    const { privateKey } = crypto.generateKeyPairSync("x25519");
+    const pem = privateKey.export({ format: "pem", type: "pkcs8" });
+    // Written whole under a temp name, then linked in: a crash never leaves
+    // a half-written key, and two starts racing keep whichever came first.
+    const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}`;
+    fs.writeFileSync(tmp, pem, { mode: 0o600, flag: "wx" });
+    try {
+      fs.linkSync(tmp, file);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    } finally {
+      fs.rmSync(tmp, { force: true });
+    }
+  }
+  ownerOnly(file, 0o600);
+  const privateKey = crypto.createPrivateKey(fs.readFileSync(file, "utf8"));
+  if (privateKey.asymmetricKeyType !== "x25519")
+    throw new Error(`${file} is not an X25519 key`);
+  return {
+    privateKey,
+    publicRaw: rawPublic(crypto.createPublicKey(privateKey)),
+  };
+}
+
+export interface Identity {
+  machineId: string;
+  signKey: KeyObject;
+  signPub: string;
+}
+
+/** This machine as Connect knows it, or null when it isn't enrolled. */
+export function loadIdentity(dir = connectDir()): Identity | null {
+  const read = readConnect(dir);
+  if (!read.ok) return null;
+  const signKey = crypto.createPrivateKey(read.files.machineKey);
+  if (signKey.asymmetricKeyType !== "ed25519") return null;
+  return {
+    machineId: read.files.config.machineId,
+    signKey,
+    signPub: rawPublic(crypto.createPublicKey(signKey)),
+  };
+}
+
+const g = globalThis as unknown as {
+  __agentosPeerIdentity?: {
+    at: number;
+    dir: string;
+    identity: Identity | null;
+  };
+};
+
+/** loadIdentity, re-read at most every 30 s (it's on every peer call). */
+export function currentIdentity(dir = connectDir()): Identity | null {
+  const c = g.__agentosPeerIdentity;
+  if (c && c.dir === dir && Date.now() - c.at < 30_000) return c.identity;
+  let identity: Identity | null = null;
+  try {
+    identity = loadIdentity(dir);
+  } catch {
+    identity = null;
+  }
+  g.__agentosPeerIdentity = { at: Date.now(), dir, identity };
+  return identity;
+}