@saadnvd1/agent-os 0.3.698 → 0.3.715

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/link-cli.ts

@@ -0,0 +1,248 @@
+/**
+ * agent-os link: link machines on your AgentOS Connect account from a
+ * terminal, for boxes with no browser. Talks to the AgentOS running here
+ * over loopback, which counts as this machine (it may accept a code).
+ *
+ *   agent-os link                     the account's machines and requests waiting here
+ *   agent-os link <machine>           start a link; prints the code to type there,
+ *                                     then asks for the one it shows back
+ *   agent-os link accept <code> [--from <machine>]   prints the code to type back
+ *   agent-os link decline [<machine>]
+ *   agent-os unlink <machine>
+ */
+
+import type { AccountMachines } from "./machines";
+import type { PendingView } from "./pairing";
+import type { Outgoing } from "./pairing-out";
+import { showCode } from "./code";
+
+export interface CliIo {
+  base: string;
+  fetch: typeof fetch;
+  out: (line: string) => void;
+  sleep: (ms: number) => Promise<void>;
+  /** One line typed in the terminal, or null when there's none to read. */
+  ask: (prompt: string) => Promise<string | null>;
+}
+
+class CliError extends Error {}
+
+async function call<T>(
+  io: CliIo,
+  path: string,
+  init?: RequestInit
+): Promise<T> {
+  let res: Response;
+  try {
+    res = await io.fetch(`${io.base}${path}`, {
+      ...init,
+      headers: { "Content-Type": "application/json" },
+    });
+  } catch {
+    throw new CliError(
+      `Can't reach AgentOS at ${io.base}. Is it running? (agent-os status)`
+    );
+  }
+  const data = (await res.json().catch(() => ({}))) as T & { error?: string };
+  if (!res.ok) throw new CliError(data.error ?? `HTTP ${res.status}`);
+  return data;
+}
+
+const same = (a: string, b: string) =>
+  a.trim().toLowerCase() === b.trim().toLowerCase();
+
+function pick<T extends { name: string }>(
+  items: T[],
+  ref: string | undefined,
+  idOf: (t: T) => string,
+  what: string
+): T {
+  if (ref) {
+    const hit = items.filter((i) => same(i.name, ref) || idOf(i) === ref);
+    if (hit.length === 1) return hit[0];
+    throw new CliError(
+      hit.length
+        ? `More than one ${what} is called ${ref}; use its id.`
+        : `No ${what} called ${ref}.`
+    );
+  }
+  if (items.length === 1) return items[0];
+  throw new CliError(
+    items.length
+      ? `Several ${what}s: say which with --from (${items.map((i) => i.name).join(", ")}).`
+      : `No ${what} is waiting.`
+  );
+}
+
+async function list(io: CliIo) {
+  const account = await call<AccountMachines>(
+    io,
+    "/api/peers/account?refresh=1"
+  );
+  const { requests } = await call<{ requests: PendingView[] }>(
+    io,
+    "/api/peers/pending"
+  );
+  if (!account.enrolled) {
+    io.out(
+      "This machine isn't on AgentOS Connect yet: run agent-os connect first."
+    );
+    return;
+  }
+  if (account.entitlements && !account.entitlements.linkMachines)
+    io.out("Linking machines needs Pro: upgrade at runagentos.com.\n");
+  if (account.error) io.out(`${account.error}\n`);
+  if (account.machines.length === 0)
+    io.out("No other machines on your account yet.");
+  for (const m of account.machines)
+    io.out(
+      `  ${m.linkState === "active" ? "linked " : m.linkState === "suspended" ? "paused " : "       "} ${m.name}  (${m.online ? "online" : "offline"}, ${m.id})`
+    );
+  for (const r of requests)
+    io.out(
+      r.state === "accepted"
+        ? `\n${r.name} is linked here. To finish, type this code on ${r.name}: ${r.confirmCode ? showCode(r.confirmCode) : "(see the browser)"}`
+        : `\n${r.name} wants to link here: agent-os link accept <the code it shows>`
+    );
+  if (account.machines.some((m) => !m.linkState))
+    io.out("\nLink one with: agent-os link <name>");
+}
+
+async function start(io: CliIo, ref: string) {
+  const account = await call<AccountMachines>(
+    io,
+    "/api/peers/account?refresh=1"
+  );
+  const target = pick(
+    account.machines,
+    ref,
+    (m) => m.id,
+    "machine on your account"
+  );
+  const { link } = await call<{ link: Outgoing }>(io, "/api/peers/link", {
+    method: "POST",
+    body: JSON.stringify({ machineId: target.id }),
+  });
+  io.out(
+    `\n  Type this code on ${link.name}:\n\n      ${showCode(link.code)}\n`
+  );
+  io.out(
+    `  (its Machines screen, its banner, or agent-os link accept there)\n  Waiting...`
+  );
+  let state: Outgoing = link;
+  while (state.state === "pending") {
+    await io.sleep(1500);
+    state = (await call<{ link: Outgoing }>(io, `/api/peers/link/${link.id}`))
+      .link;
+  }
+  while (state.state === "confirm") {
+    const typed = await io.ask(
+      `\n  The code matched on ${state.name}. Type the code it shows now: `
+    );
+    if (typed === null)
+      throw new CliError("No code typed: nothing was linked.");
+    const res = await io.fetch(`${io.base}/api/peers/link/${link.id}/confirm`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ code: typed }),
+    });
+    const data = (await res.json().catch(() => ({}))) as {
+      link?: Outgoing;
+      error?: string;
+      attemptsLeft?: number;
+    };
+    if (data.link) state = data.link;
+    else if (data.attemptsLeft)
+      io.out(`  ${data.error} ${data.attemptsLeft} left.`);
+    else throw new CliError(data.error ?? `HTTP ${res.status}`);
+  }
+  if (state.state !== "accepted")
+    throw new CliError(
+      state.state === "expired"
+        ? "The code expired. Run agent-os link again."
+        : `Not linked (${state.state}${state.error ? `: ${state.error}` : ""}).`
+    );
+  io.out(`\n  Linked with ${state.name}.\n`);
+}
+
+async function answer(io: CliIo, verb: "accept" | "decline", rest: string[]) {
+  const i = rest.indexOf("--from");
+  const from = i > -1 ? rest[i + 1] : verb === "decline" ? rest[0] : undefined;
+  // "482 913" arrives as two words.
+  const code =
+    verb === "accept"
+      ? rest.filter((_, j) => i < 0 || (j !== i && j !== i + 1)).join("")
+      : undefined;
+  if (verb === "accept" && !code)
+    throw new CliError("Usage: agent-os link accept <code> [--from <machine>]");
+  const { requests } = await call<{ requests: PendingView[] }>(
+    io,
+    "/api/peers/pending"
+  );
+  const req = pick(
+    requests.filter((r) => r.state !== "accepted"),
+    from,
+    (r) => r.machineId,
+    "link request"
+  );
+  if (verb === "decline") {
+    await call(io, `/api/peers/pending/${req.id}/decline`, { method: "POST" });
+    io.out(`Declined ${req.name}.`);
+    return;
+  }
+  const r = await call<{ name: string; confirmCode: string }>(
+    io,
+    `/api/peers/pending/${req.id}/accept`,
+    {
+      method: "POST",
+      body: JSON.stringify({ code }),
+    }
+  );
+  io.out(
+    `Linked with ${r.name}. It can start agents and run code here; unlink with agent-os unlink "${r.name}".`
+  );
+  io.out(
+    `\n  To finish, type this code on ${r.name}:\n\n      ${showCode(r.confirmCode)}\n`
+  );
+}
+
+async function unlink(io: CliIo, ref: string | undefined) {
+  if (!ref) throw new CliError("Usage: agent-os unlink <machine>");
+  const { hosts } = await call<{
+    hosts: { id: string; name: string; kind?: string }[];
+  }>(io, "/api/hosts");
+  const host = pick(
+    hosts.filter((h) => h.kind === "connect"),
+    ref,
+    (h) => h.id,
+    "linked machine"
+  );
+  const r = await call<{ told: boolean; removed: boolean }>(
+    io,
+    `/api/peers/${host.id}`,
+    { method: "DELETE" }
+  );
+  io.out(
+    r.told
+      ? `Unlinked ${host.name}, on both machines.`
+      : `Unlinked ${host.name} here. It couldn't be told now; its next call here is refused and it will show as unlinked.`
+  );
+  if (!r.removed)
+    io.out(`It stays in Machines while it still has projects or sessions.`);
+}
+
+/** Runs one command; returns the exit code. */
+export async function runLinkCli(args: string[], io: CliIo): Promise<number> {
+  try {
+    const [first, ...rest] = args;
+    if (first === "--unlink") await unlink(io, rest[0]);
+    else if (!first) await list(io);
+    else if (first === "accept" || first === "decline")
+      await answer(io, first, rest);
+    else await start(io, args.join(" "));
+    return 0;
+  } catch (err) {
+    io.out(`  link: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}