privateer-agent 0.3.6 → 0.4.0

package/src/crypto/accountTrust.ts

@@ -0,0 +1,113 @@
+/**
+ * Pinned account signing key — TERMINAL side (Phase 4 TOFU, mirror of the app's
+ * terminalTrustService).
+ *
+ * At link time the app hands this terminal the account's Ed25519 signing public key
+ * (bound into the device-code grant, delivered in the /auth/device/token response). We
+ * pin it here. Every app channel-save is then verified against this key
+ * (accountVerify.ts): only the account master-key holder can sign, so a hostile relay
+ * can neither forge a channel config nor inject an admin.
+ *
+ * The pinned value is a PUBLIC key, but its INTEGRITY is the security property — a
+ * local attacker who could swap it would defeat verification — so it's written 0600
+ * beside the other machine trust roots (terminal-key.json, config.json). A server
+ * malicious at the single link moment could substitute it (the accepted TOFU limit,
+ * symmetric with the app-side pin); a server that turns malicious later cannot.
+ */
+
+import { readFileSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "../config/paths.ts";
+
+interface AccountTrustFile {
+  v: 1;
+  accountSignPub: string; // base64 Ed25519 public key
+}
+
+function trustPath(): string {
+  return join(globalDir(), "account-trust.json");
+}
+
+/** Pin the account signing public key (idempotent). A blank/absent value is ignored
+ *  (an older app or a locked vault simply doesn't establish the pin). */
+export function pinAccountSignKey(pub: string | undefined | null): void {
+  const value = (pub ?? "").trim();
+  if (!value) return;
+  try {
+    const file: AccountTrustFile = { v: 1, accountSignPub: value };
+    writeFileSync(trustPath(), JSON.stringify(file), { mode: 0o600 });
+    try { chmodSync(trustPath(), 0o600); } catch { /* non-POSIX FS */ }
+  } catch {
+    /* best effort — a missing pin just means channel-saves fail-closed until re-link */
+  }
+}
+
+/** The pinned account signing public key (base64), or undefined if none is pinned. */
+export function loadAccountSignKey(): string | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(trustPath(), "utf8")) as AccountTrustFile;
+    return parsed?.v === 1 && typeof parsed.accountSignPub === "string" ? parsed.accountSignPub : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Drop the pin — called when local credentials are cleared (logout / session revoke),
+ *  since it belongs to the signed-in account.
+ *
+ *  We deliberately do NOT clear the anti-replay watermark (control-sig.json) here.
+ *  Resetting it to 0 on logout would let a hostile relay replay a previously-captured,
+ *  validly-signed channel-save after a re-link (its ts > 0 ≥ 0), rolling config back to
+ *  an earlier account-authored state — e.g. re-adding a removed admin (M1). The
+ *  watermark is safe to persist across a re-link: it's monotonic wall-clock ms, and a
+ *  DIFFERENT account that links later gets a different signing key, so its saves are
+ *  gated by signature (not by ts) and its own ts values only ever move forward. */
+export function clearAccountSignKey(): void {
+  try { rmSync(trustPath(), { force: true }); } catch { /* nothing to remove */ }
+}
+
+// ── Anti-replay watermark for signed control frames (per terminal) ───────────────
+// The highest `ts` we've applied, keyed by termId. A signed control frame (channel
+// save, routine save/run, extension add, skill create, …) whose ts is BELOW the
+// watermark for its terminal is a replay/rollback of an older signed envelope and is
+// refused; at-or-above is accepted (an idempotent replay of the latest is harmless).
+//
+// Keyed by termId — NOT global — so the always-on daemon (stable routines-… id) and
+// each interactive terminal (its own id) don't cross-reject each other's frames when
+// the app drives them near-simultaneously with independent ts streams. Each signed
+// frame binds its termId (see accountVerify.controlMessage), so a per-terminal
+// watermark is the matching granularity. Persisted so it survives a daemon restart;
+// deliberately NOT cleared on logout (see clearAccountSignKey — M1).
+function tsPath(): string {
+  return join(globalDir(), "control-sig.json");
+}
+
+interface ControlSigFile {
+  v: 1;
+  byTerm: Record<string, number>;
+}
+
+function loadControlSig(): ControlSigFile {
+  try {
+    const parsed = JSON.parse(readFileSync(tsPath(), "utf8")) as ControlSigFile;
+    if (parsed?.v === 1 && parsed.byTerm && typeof parsed.byTerm === "object") return parsed;
+  } catch {
+    /* missing/malformed → fresh */
+  }
+  return { v: 1, byTerm: {} };
+}
+
+export function loadLastControlTs(termId: string): number {
+  const ts = loadControlSig().byTerm[termId];
+  return typeof ts === "number" ? ts : 0;
+}
+
+export function saveLastControlTs(termId: string, ts: number): void {
+  try {
+    const file = loadControlSig();
+    file.byTerm[termId] = Math.max(file.byTerm[termId] ?? 0, ts);
+    writeFileSync(tsPath(), JSON.stringify(file), { mode: 0o600 });
+  } catch {
+    /* best effort */
+  }
+}

package/src/crypto/accountVerify.ts

@@ -0,0 +1,138 @@
+/**
+ * Account signature verification — TERMINAL side.
+ *
+ * Phase 4 closes the authenticity gap in app→terminal channel config (review finding
+ * F7/F8): a sealed box gives confidentiality but NOT sender authenticity, so a hostile
+ * relay/server — which knows this terminal's public key — could forge a channel-save
+ * (attacker's token + injected admins). To stop that, the app SIGNS every channel-save
+ * with an Ed25519 key derived from the account master key, and the terminal verifies
+ * that signature against the account's signing public key it PINNED at link time
+ * (accountTrust.ts). Only the master-key holder can produce a valid signature, so the
+ * server can neither forge config nor alter the admin list undetected.
+ *
+ * The canonical message construction MUST stay byte-for-byte in sync with the signer:
+ *   treeview/client/services/accountSign.ts
+ * Domain prefix "privateer-channel-cfg-v1" + canonical JSON (recursively key-sorted).
+ */
+
+import { ed25519 } from "@noble/curves/ed25519";
+
+const enc = new TextEncoder();
+const DOMAIN = "privateer-channel-cfg-v1";
+
+// Deterministic JSON: object keys sorted recursively, arrays kept in order. MUST match
+// treeview/client/services/accountSign.ts canonicalize() exactly.
+function canonicalize(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return "[" + value.map(canonicalize).join(",") + "]";
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k])).join(",") + "}";
+}
+
+// The signed envelope. `termId` binds the intended recipient terminal (so a signature
+// for terminal X can't be replayed against Y — verification uses OUR termId). `ts`
+// binds freshness (the daemon rejects a ts it has already applied → no replay/rollback).
+export interface ChannelSaveEnvelope {
+  termId: string;
+  ts: number;
+  draft: Record<string, unknown>;
+  sealedSecrets?: string;
+}
+
+export function channelSaveMessage(env: ChannelSaveEnvelope): Uint8Array {
+  return enc.encode(
+    DOMAIN +
+      canonicalize({
+        termId: env.termId,
+        ts: env.ts,
+        draft: env.draft,
+        sealedSecrets: env.sealedSecrets ?? null,
+      }),
+  );
+}
+
+/** Verify an Ed25519 signature (base64) over the canonical envelope against the pinned
+ *  account signing public key (base64). Returns false on ANY malformation — the caller
+ *  fail-closes (rejects the save) on false. */
+export function verifyChannelSave(accountSignPubB64: string, env: ChannelSaveEnvelope, sigB64: string): boolean {
+  try {
+    const pub = new Uint8Array(Buffer.from(accountSignPubB64, "base64"));
+    const sig = new Uint8Array(Buffer.from(sigB64, "base64"));
+    if (pub.length !== 32) return false;
+    return ed25519.verify(sig, channelSaveMessage(env), pub);
+  } catch {
+    return false;
+  }
+}
+
+// The outbox recipient key (X25519) is fetched live from the UNTRUSTED server, so a
+// malicious server could otherwise substitute a key it controls and read every sealed
+// result (the terminal holds no master key and can't derive the real one itself). To
+// stop that, the app signs the published outbox public key with the same account
+// Ed25519 key the terminal already pinned at link, and the terminal verifies that
+// signature here before sealing to the key. A server that turns malicious AFTER link
+// can no longer swap the key — it can't forge this signature. Residual: the F1
+// link-moment window, identical to the channel-config path.
+//
+// Message construction MUST stay byte-for-byte in sync with the signer:
+//   treeview/client/services/accountSign.ts signOutboxKey()
+const OUTBOX_KEY_DOMAIN = "privateer-outbox-key-v1";
+
+/** Verify the account's Ed25519 signature (base64) over the base64 outbox public key
+ *  against the pinned account signing public key (base64). Returns false on ANY
+ *  malformation — the caller fail-closes (refuses to seal) on false. */
+export function verifyOutboxKey(accountSignPubB64: string, outboxPubB64: string, sigB64: string): boolean {
+  try {
+    const pub = new Uint8Array(Buffer.from(accountSignPubB64, "base64"));
+    const sig = new Uint8Array(Buffer.from(sigB64, "base64"));
+    if (pub.length !== 32) return false;
+    return ed25519.verify(sig, enc.encode(OUTBOX_KEY_DOMAIN + outboxPubB64), pub);
+  } catch {
+    return false;
+  }
+}
+
+// ── Generic signed control frames (H2) ──────────────────────────────────────────
+// channels_save is signed (F7/F8), but every OTHER app→terminal mutation
+// (routines_*, extensions_*, skills_*, channels_remove) was sent over the untrusted
+// relay UNSIGNED — so a malicious server could forge them, and several have severe
+// local side effects (a forged routine runs a headless bypass-mode session → RCE; a
+// forged extensions_add installs an npm package → RCE; a forged skills_create injects
+// an auto-invoked system-prompt skill). This closes that: the app signs every mutating
+// control frame with the account key the terminal pinned at link, and the terminal
+// verifies it here (fail-closed) before acting. `termId` binds the recipient (a
+// signature for terminal X won't verify against Y) and `ts` binds freshness (the caller
+// rejects a ts at/below the last it applied → no replay).
+//
+// The canonical message construction MUST stay byte-for-byte in sync with the signer:
+//   treeview/client/services/accountSign.ts signControl()
+const CONTROL_DOMAIN = "privateer-control-v1";
+
+export interface ControlEnvelope {
+  termId: string;
+  ts: number;
+  action: string; // the frame type, e.g. "routines_save", "extensions_add"
+  args: Record<string, unknown>; // the operation's parameters
+}
+
+export function controlMessage(env: ControlEnvelope): Uint8Array {
+  return enc.encode(
+    CONTROL_DOMAIN +
+      canonicalize({ action: env.action, args: env.args, termId: env.termId, ts: env.ts }),
+  );
+}
+
+/** Verify an Ed25519 signature (base64) over a control envelope against the pinned
+ *  account signing public key (base64). Returns false on ANY malformation — the caller
+ *  fail-closes (refuses the mutation) on false. */
+export function verifyControl(accountSignPubB64: string, env: ControlEnvelope, sigB64: string): boolean {
+  try {
+    const pub = new Uint8Array(Buffer.from(accountSignPubB64, "base64"));
+    const sig = new Uint8Array(Buffer.from(sigB64, "base64"));
+    if (pub.length !== 32) return false;
+    return ed25519.verify(sig, controlMessage(env), pub);
+  } catch {
+    return false;
+  }
+}

package/src/crypto/terminalKey.ts

@@ -0,0 +1,95 @@
+/**
+ * Terminal identity keypair — the RECIPIENT side of app→terminal sealing.
+ *
+ * The outbox (crypto/outboxSeal.ts) is one-directional: a terminal seals results TO
+ * the account and holds no openable key. This is the mirror: a persistent X25519
+ * keypair whose PUBLIC half the app pins at link time (device-code approval) and
+ * whose PRIVATE half never leaves this machine — so the app can seal secrets (Phase
+ * 3: channel bot tokens) that ONLY this terminal can open, with the server unable to
+ * read them even though it forwards the ciphertext.
+ *
+ * Trust model (TOFU, SSH known_hosts style): the pubkey is delivered to the app once,
+ * bound into the device-authorization grant, and pinned on approval. A later key swap
+ * over the relay is rejected because it isn't in the pinned set. This does NOT defend
+ * against a malicious server at the single link moment — that narrow window is the
+ * accepted TOFU limitation (fingerprint verification is the future hardening).
+ *
+ * Construction matches outboxSeal.ts so Phase 3's open() is the exact inverse of the
+ * app's seal(): X25519 → HKDF-SHA256 → AES-256-GCM.
+ */
+
+import { readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { x25519 } from "@noble/curves/ed25519";
+import { globalDir } from "../config/paths.ts";
+
+interface TerminalKeyFile {
+  v: 1;
+  publicKey: string; // base64, 32 raw bytes
+  secretKey: string; // base64, 32 raw bytes — never leaves this machine
+}
+
+function keyPath(): string {
+  return join(globalDir(), "terminal-key.json");
+}
+
+// Cache the loaded/created keypair for the process lifetime so we don't re-read the
+// file (or, worse, regenerate) on every device-code request.
+let cached: { publicKey: Uint8Array; secretKey: Uint8Array } | undefined;
+
+function b64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64");
+}
+
+function fromB64(s: string, label: string): Uint8Array {
+  const buf = Buffer.from(s, "base64");
+  if (buf.length !== 32) throw new Error(`${label} must be 32 bytes`);
+  return new Uint8Array(buf);
+}
+
+// Load the persisted keypair, or mint + persist a fresh one on first use. The file is
+// written 0600 (owner-only) — this machine's private key protects every future sealed
+// message to this terminal, so it's as sensitive as the config.json tokens beside it.
+function loadOrCreate(): { publicKey: Uint8Array; secretKey: Uint8Array } {
+  if (cached) return cached;
+  try {
+    const parsed = JSON.parse(readFileSync(keyPath(), "utf8")) as TerminalKeyFile;
+    if (parsed?.v === 1 && parsed.publicKey && parsed.secretKey) {
+      cached = {
+        publicKey: fromB64(parsed.publicKey, "terminal public key"),
+        secretKey: fromB64(parsed.secretKey, "terminal secret key"),
+      };
+      return cached;
+    }
+  } catch {
+    /* missing or malformed → mint a fresh keypair below */
+  }
+  const secretKey = x25519.utils.randomPrivateKey();
+  const publicKey = x25519.getPublicKey(secretKey);
+  const file: TerminalKeyFile = { v: 1, publicKey: b64(publicKey), secretKey: b64(secretKey) };
+  // Create 0600 from the start — passing `mode` to writeFileSync avoids the TOCTOU
+  // window where a fresh file briefly carries umask perms (group/world-readable)
+  // before a follow-up chmod. `mode` only applies on CREATE, so also chmod to fix an
+  // OVERWRITTEN pre-existing (malformed) file, whose perms writeFileSync leaves as-is.
+  writeFileSync(keyPath(), JSON.stringify(file), { mode: 0o600 });
+  try {
+    chmodSync(keyPath(), 0o600);
+  } catch {
+    /* best effort — e.g. non-POSIX FS */
+  }
+  cached = { publicKey, secretKey };
+  return cached;
+}
+
+/** This terminal's public key, base64 (32 raw bytes). Sent in the device-code grant
+ *  so the app can pin it; safe to expose (it's public). Mints the keypair on first
+ *  call. */
+export function terminalPublicKeyBase64(): string {
+  return b64(loadOrCreate().publicKey);
+}
+
+/** This terminal's private key (raw 32 bytes) — for Phase 3's unseal(). Never send,
+ *  log, or persist anywhere but the 0600 key file. */
+export function terminalSecretKey(): Uint8Array {
+  return loadOrCreate().secretKey;
+}

package/src/crypto/terminalUnseal.ts

@@ -0,0 +1,62 @@
+/**
+ * App→terminal sealed-box crypto — RECIPIENT (terminal) side.
+ *
+ * The inverse of the outbox: here the APP is the sender and this terminal is the
+ * recipient. The app seals a secret (a channel bot token) to this terminal's pinned
+ * public key (see terminalKey.ts); only this terminal — holder of the matching
+ * private key — can open it. The server forwards the ciphertext over the relay and
+ * cannot read it, which is the whole point of Phase 3.
+ *
+ * Construction MUST stay byte-for-byte in sync with the sender:
+ *   treeview/client/services/terminalSeal.ts
+ *   X25519 → HKDF-SHA256 → AES-256-GCM. Wire: epk(32) ‖ iv(12) ‖ ct‖tag, base64.
+ *   salt = epk ‖ recipientPub ; HKDF info = "privateer-channel-seal-v1".
+ *
+ * Domain separation: the "channel-seal" HKDF label is DISTINCT from the outbox's
+ * "privateer-outbox-seal-v1", so a blob from one protocol can never be opened as the
+ * other even though both are X25519 sealed boxes to the same curve.
+ */
+
+import { x25519 } from "@noble/curves/ed25519";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+import { gcm } from "@noble/ciphers/aes.js";
+import { terminalSecretKey } from "./terminalKey.ts";
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+// MUST match treeview/client/services/terminalSeal.ts.
+const KDF_SEAL = enc.encode("privateer-channel-seal-v1");
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+/**
+ * Open a base64 wire string the app sealed to THIS terminal's public key. Returns the
+ * plaintext bytes; throws on tamper, a wrong recipient, or a malformed blob (the GCM
+ * tag check is the integrity guarantee). Uses this terminal's private key — which
+ * never leaves the 0600 key file.
+ */
+export function openFromApp(wireB64: string): Uint8Array {
+  const sk = terminalSecretKey();
+  const recipientPub = x25519.getPublicKey(sk);
+  const wire = new Uint8Array(Buffer.from(wireB64, "base64"));
+  if (wire.length < 32 + 12 + 16) throw new Error("sealed blob too short");
+  const epk = wire.subarray(0, 32);
+  const iv = wire.subarray(32, 44);
+  const ct = wire.subarray(44);
+  const shared = x25519.getSharedSecret(sk, epk);
+  const salt = concat(epk, recipientPub); // binds ephemeral + this recipient
+  const key = hkdf(sha256, shared, salt, KDF_SEAL, 32);
+  return gcm(key, iv).decrypt(ct); // throws if the tag doesn't verify
+}
+
+/** Open + JSON-parse. Throws on tamper/wrong-key/invalid JSON. */
+export function openJsonFromApp<T = unknown>(wireB64: string): T {
+  return JSON.parse(dec.decode(openFromApp(wireB64))) as T;
+}