@cohortapp/agent-sdk 2.3.0

package/lib/secrets/providers.mjs

@@ -0,0 +1,461 @@
+/**
+ * lib/secrets/providers.mjs — pluggable secret providers for the maestro
+ * secrets lifecycle (gaps-enterprise-ops G12 + G16 DR-config).
+ *
+ * At 40-60 machines, rotating a shared secret is an O(fleet) manual chore.
+ * This module gives every agent one uniform `get(name)/set(name,value)/list()`
+ * interface over four backends, so the broker layer (lib/secrets/broker.mjs)
+ * and the CLI (`maestro secrets …`) never special-case where a secret lives:
+ *
+ *   • env       — process.env, READ-ONLY (writes fail-closed: env is ambient).
+ *   • file      — an AES-256-GCM-sealed `.secrets` store under state/, keyed
+ *                 like crypto-box (a 32-byte master key, per-write random IV,
+ *                 GCM auth tag). Ciphertext on disk never equals plaintext.
+ *   • keychain  — macOS `security` via execFile (best-effort; non-mac is inert).
+ *   • broker    — an Infisical/OpenBao-style HTTP client over an INJECTED fetch
+ *                 (never a live network call in tests).
+ *
+ * Reads fail OPEN (a backend that errors returns null so a chain can fall
+ * through — matches the project audit's fail-open posture). Writes fail CLOSED
+ * (a failed `set` throws so a botched rotation surfaces loudly).
+ *
+ * `selectProvider(cfg)` resolves the active local provider from
+ * config/secrets.yaml (`provider: file|env|keychain`); the broker is selected
+ * separately by the broker layer because it carries network identity.
+ *
+ * Pure node:crypto + node:fs + node:child_process. The only ambient inputs are
+ * process.env (env provider) and the master key file; everything else is
+ * injected, so the whole module is unit-testable without a network or a Mac.
+ *
+ * @module lib/secrets/providers
+ */
+
+"use strict";
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+  createHash,
+} from "node:crypto";
+import { existsSync, readFileSync, chmodSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+import { writeFileAtomic } from "../fs-atomic.mjs";
+
+// ---------------------------------------------------------------------------
+// Crypto — AES-256-GCM sealed store (crypto-box style)
+// ---------------------------------------------------------------------------
+
+const ALGO = "aes-256-gcm";
+const IV_LEN = 12; // 96-bit nonce — the GCM standard.
+const KEY_LEN = 32; // 256-bit key.
+const STORE_VERSION = 1;
+
+/** Relative location of the sealed store + its master key under the agent root. */
+const SECRETS_DIR = join("state", "secrets");
+const STORE_FILE = ".secrets.json";
+const KEY_FILE = ".secrets.key";
+
+function storePath(agentRoot) {
+  return join(String(agentRoot || "."), SECRETS_DIR, STORE_FILE);
+}
+function keyPath(agentRoot) {
+  return join(String(agentRoot || "."), SECRETS_DIR, KEY_FILE);
+}
+
+/**
+ * Load (or first-time create) the 32-byte master key for the file store.
+ * Stored hex, 0600. Created lazily so a fresh agent self-bootstraps a key.
+ * Pure-ish: the only side effect is writing the key file when absent.
+ *
+ * @param {string} agentRoot
+ * @returns {Buffer} 32-byte key
+ */
+export function loadOrCreateMasterKey(agentRoot) {
+  const p = keyPath(agentRoot);
+  if (existsSync(p)) {
+    const hex = readFileSync(p, "utf-8").trim();
+    const buf = Buffer.from(hex, "hex");
+    if (buf.length === KEY_LEN) return buf;
+    // Corrupt/short key — fall through and regenerate (old store becomes
+    // unreadable, which surfaces on the next get as a fail-open null).
+  }
+  const key = randomBytes(KEY_LEN);
+  writeFileAtomic(p, key.toString("hex") + "\n", { mode: 0o600 });
+  try { chmodSync(p, 0o600); } catch { /* best-effort on non-posix */ }
+  return key;
+}
+
+/**
+ * Seal one plaintext value into an envelope `{ iv, tag, ct }` (all base64).
+ * A fresh random IV per call means the same plaintext never seals to the same
+ * ciphertext. Pure over (key, plaintext).
+ *
+ * @param {Buffer} key 32-byte master key
+ * @param {string} plaintext
+ * @returns {{iv:string, tag:string, ct:string}}
+ */
+export function seal(key, plaintext) {
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv(ALGO, key, iv);
+  const ct = Buffer.concat([cipher.update(String(plaintext), "utf-8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return { iv: iv.toString("base64"), tag: tag.toString("base64"), ct: ct.toString("base64") };
+}
+
+/**
+ * Open a sealed envelope. Throws on a bad key / tampered ciphertext (GCM auth
+ * failure) — callers in the read path swallow that into a fail-open null.
+ *
+ * @param {Buffer} key
+ * @param {{iv:string, tag:string, ct:string}} env
+ * @returns {string} plaintext
+ */
+export function open(key, env) {
+  const iv = Buffer.from(env.iv, "base64");
+  const tag = Buffer.from(env.tag, "base64");
+  const ct = Buffer.from(env.ct, "base64");
+  const decipher = createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Provider: env (read-only)
+// ---------------------------------------------------------------------------
+
+/**
+ * The ambient-environment provider. Reads from a process.env-shaped object;
+ * writes fail closed because the environment is not ours to mutate durably.
+ */
+export class EnvProvider {
+  /** @param {object} [opts] @param {Record<string,string>} [opts.env] */
+  constructor(opts = {}) {
+    this.name = "env";
+    this.readonly = true;
+    this._env = opts.env || process.env;
+  }
+
+  get(name) {
+    const v = this._env[name];
+    return v === undefined ? null : v;
+  }
+
+  /** Writes fail-closed: env secrets are ambient, not durable. */
+  set(name) {
+    throw new Error(`env provider is read-only — cannot set "${name}"`);
+  }
+
+  list() {
+    // Only surface UPPER_SNAKE names — the env is full of unrelated noise.
+    return Object.keys(this._env).filter((k) => /^[A-Z][A-Z0-9_]*$/.test(k)).sort();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Provider: file (AES-256-GCM sealed store)
+// ---------------------------------------------------------------------------
+
+/**
+ * The encrypted-at-rest local store. The on-disk JSON holds only sealed
+ * envelopes; the master key lives in a sibling 0600 file. Read errors
+ * (missing store, bad key, tampered value) fail open to null; writes are
+ * atomic and fail closed.
+ */
+export class FileProvider {
+  /** @param {object} opts @param {string} opts.agentRoot @param {Buffer} [opts.key] */
+  constructor(opts = {}) {
+    this.name = "file";
+    this.readonly = false;
+    this.agentRoot = opts.agentRoot || ".";
+    this._key = opts.key || null; // lazily loaded
+  }
+
+  _key32() {
+    if (!this._key) this._key = loadOrCreateMasterKey(this.agentRoot);
+    return this._key;
+  }
+
+  _read() {
+    const p = storePath(this.agentRoot);
+    if (!existsSync(p)) return { version: STORE_VERSION, secrets: {} };
+    try {
+      const doc = JSON.parse(readFileSync(p, "utf-8"));
+      if (!doc || typeof doc !== "object" || typeof doc.secrets !== "object") {
+        return { version: STORE_VERSION, secrets: {} };
+      }
+      return doc;
+    } catch {
+      // Corrupt store — fail open to empty so a read returns null, not a crash.
+      return { version: STORE_VERSION, secrets: {} };
+    }
+  }
+
+  get(name) {
+    try {
+      const doc = this._read();
+      const env = doc.secrets[name];
+      if (!env) return null;
+      return open(this._key32(), env);
+    } catch {
+      return null; // fail open
+    }
+  }
+
+  set(name, value) {
+    if (!name || typeof name !== "string") {
+      throw new Error("file provider: secret name is required");
+    }
+    // Read-modify-write the whole store atomically. Fail closed: any IO or
+    // crypto error propagates so a failed rotation is never silent.
+    const doc = this._read();
+    doc.version = STORE_VERSION;
+    doc.secrets[name] = seal(this._key32(), value);
+    writeFileAtomic(storePath(this.agentRoot), JSON.stringify(doc, null, 2) + "\n", { mode: 0o600 });
+    try { chmodSync(storePath(this.agentRoot), 0o600); } catch { /* best-effort */ }
+    return true;
+  }
+
+  list() {
+    try {
+      return Object.keys(this._read().secrets).sort();
+    } catch {
+      return [];
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Provider: keychain (macOS `security`, best-effort)
+// ---------------------------------------------------------------------------
+
+/**
+ * The macOS Keychain provider via the `security` CLI. Best-effort: on a
+ * non-Mac host (or when `security` is absent) reads fail open to null and
+ * `list()` returns []. Writes still fail closed so a rotation onto a host
+ * that can't persist surfaces. execFile (never a shell) — no injection.
+ */
+export class KeychainProvider {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.service] keychain service/label prefix
+   * @param {string} [opts.account] keychain account (the agent identity)
+   * @param {(file:string,args:string[],opts?:object)=>Buffer|string} [opts.exec] injected execFileSync (tests)
+   */
+  constructor(opts = {}) {
+    this.name = "keychain";
+    this.readonly = false;
+    this.service = opts.service || "maestro";
+    this.account = opts.account || "maestro-agent";
+    this._exec = opts.exec || execFileSync;
+    // Index of known names — `security` has no "list items by service" that is
+    // portable, so we track names we've written in the file store's sibling.
+    this._namesFile = join(String(opts.agentRoot || "."), SECRETS_DIR, ".keychain-names.json");
+  }
+
+  _label(name) {
+    return `${this.service}.${name}`;
+  }
+
+  get(name) {
+    try {
+      const out = this._exec(
+        "security",
+        ["find-generic-password", "-s", this._label(name), "-a", this.account, "-w"],
+        { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
+      );
+      const v = String(out).replace(/\n$/, "");
+      return v.length ? v : null;
+    } catch {
+      return null; // fail open (not on a Mac, or item not found)
+    }
+  }
+
+  set(name, value) {
+    if (!name || typeof name !== "string") {
+      throw new Error("keychain provider: secret name is required");
+    }
+    // -U updates in place if the item already exists. Fail closed.
+    this._exec(
+      "security",
+      [
+        "add-generic-password",
+        "-s", this._label(name),
+        "-a", this.account,
+        "-w", String(value),
+        "-U",
+      ],
+      { stdio: ["ignore", "ignore", "pipe"] }
+    );
+    this._recordName(name);
+    return true;
+  }
+
+  _recordName(name) {
+    try {
+      let names = [];
+      if (existsSync(this._namesFile)) {
+        names = JSON.parse(readFileSync(this._namesFile, "utf-8"));
+        if (!Array.isArray(names)) names = [];
+      }
+      if (!names.includes(name)) {
+        names.push(name);
+        writeFileAtomic(this._namesFile, JSON.stringify(names.sort()) + "\n", { mode: 0o600 });
+      }
+    } catch { /* best-effort name index */ }
+  }
+
+  list() {
+    try {
+      if (!existsSync(this._namesFile)) return [];
+      const names = JSON.parse(readFileSync(this._namesFile, "utf-8"));
+      return Array.isArray(names) ? names.slice().sort() : [];
+    } catch {
+      return [];
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Provider: broker (remote HTTP via INJECTED fetch)
+// ---------------------------------------------------------------------------
+
+/**
+ * The remote-broker client — an Infisical/OpenBao-shaped HTTP secrets store.
+ * The fetch implementation is INJECTED; tests pass a stub and there is never a
+ * live network call. One identity per agent: the agent token, sent as a Bearer
+ * header. Reads fail open (null) so the broker can be one link in a chain;
+ * writes fail closed.
+ *
+ * Wire shape (deliberately minimal, maps onto Infisical's REST + OpenBao KV):
+ *   GET  {baseUrl}/secrets/{name}  → 200 { value } | 404
+ *   GET  {baseUrl}/secrets         → 200 { secrets: [{ name }, …] }
+ *   PUT  {baseUrl}/secrets/{name}  → 2xx (body { value })
+ */
+export class BrokerProvider {
+  /**
+   * @param {object} opts
+   * @param {string} opts.baseUrl broker base URL
+   * @param {string} opts.token agent token (Bearer)
+   * @param {typeof fetch} opts.fetch INJECTED fetch (required — no implicit global)
+   */
+  constructor(opts = {}) {
+    this.name = "broker";
+    this.readonly = false;
+    this.baseUrl = (opts.baseUrl || "").replace(/\/$/, "");
+    this.token = opts.token || "";
+    this._fetch = opts.fetch; // never default to global fetch — keep tests offline
+  }
+
+  _headers() {
+    return {
+      authorization: `Bearer ${this.token}`,
+      "content-type": "application/json",
+    };
+  }
+
+  async get(name) {
+    if (!this._fetch || !this.baseUrl) return null;
+    try {
+      const res = await this._fetch(`${this.baseUrl}/secrets/${encodeURIComponent(name)}`, {
+        method: "GET",
+        headers: this._headers(),
+      });
+      if (!res || !res.ok) return null;
+      const body = await res.json();
+      const v = body && (body.value ?? body.secret ?? null);
+      return v == null ? null : String(v);
+    } catch {
+      return null; // fail open
+    }
+  }
+
+  async set(name, value) {
+    if (!this._fetch || !this.baseUrl) {
+      throw new Error("broker provider: no fetch/baseUrl configured — cannot write");
+    }
+    if (!name || typeof name !== "string") {
+      throw new Error("broker provider: secret name is required");
+    }
+    const res = await this._fetch(`${this.baseUrl}/secrets/${encodeURIComponent(name)}`, {
+      method: "PUT",
+      headers: this._headers(),
+      body: JSON.stringify({ value: String(value) }),
+    });
+    if (!res || !res.ok) {
+      const status = res ? res.status : "no-response";
+      throw new Error(`broker provider: write of "${name}" failed (status ${status})`);
+    }
+    return true;
+  }
+
+  async list() {
+    if (!this._fetch || !this.baseUrl) return [];
+    try {
+      const res = await this._fetch(`${this.baseUrl}/secrets`, {
+        method: "GET",
+        headers: this._headers(),
+      });
+      if (!res || !res.ok) return [];
+      const body = await res.json();
+      const arr = Array.isArray(body) ? body : Array.isArray(body && body.secrets) ? body.secrets : [];
+      return arr
+        .map((s) => (typeof s === "string" ? s : s && s.name))
+        .filter((n) => typeof n === "string")
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// selectProvider — pick the local provider from config
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the active LOCAL provider from a parsed config/secrets.yaml object.
+ * The broker is constructed separately (it needs network identity); this is
+ * the on-disk authority for `set`/rotate when no explicit override is given.
+ *
+ * cfg shape (config/secrets.yaml):
+ *   provider: file | env | keychain      # default: file
+ *   keychain: { service, account }
+ *
+ * Unknown providers fall back to `file` (the safe encrypted default) rather
+ * than throwing — a typo in config should never strand an agent without a
+ * place to read secrets.
+ *
+ * @param {object} cfg parsed config/secrets.yaml (may be null/empty)
+ * @param {object} [ctx] @param {string} [ctx.agentRoot] @param {Record<string,string>} [ctx.env]
+ * @returns {EnvProvider|FileProvider|KeychainProvider}
+ */
+export function selectProvider(cfg, ctx = {}) {
+  const agentRoot = ctx.agentRoot || ".";
+  const kind = (cfg && typeof cfg.provider === "string" ? cfg.provider : "file").toLowerCase();
+  switch (kind) {
+    case "env":
+      return new EnvProvider({ env: ctx.env });
+    case "keychain": {
+      const kc = (cfg && cfg.keychain) || {};
+      return new KeychainProvider({ service: kc.service, account: kc.account, agentRoot });
+    }
+    case "file":
+    default:
+      return new FileProvider({ agentRoot });
+  }
+}
+
+/**
+ * Stable fingerprint of a secret's NAME (never its value) for audit linkage.
+ * Lets the audit prove "the secret called X was rotated" without ever logging
+ * X's contents or even X itself if a caller prefers the hash.
+ *
+ * @param {string} name
+ * @returns {string} 16-hex-char sha256 prefix
+ */
+export function nameFingerprint(name) {
+  return createHash("sha256").update(String(name)).digest("hex").slice(0, 16);
+}