@oracle-agent/oracle 0.4.2 → 0.5.0

package/src/cli/operator-dispatch.mjs

@@ -0,0 +1,258 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(HERE, "../..");
+
+export const OPERATOR_BIN_NAMES = Object.freeze([
+  "oracle-vault",
+  "oracle-credential",
+  "oracle-signer",
+  "oracle-runner",
+  "oracle-agentic-init",
+  "oracle-agentic-doctor",
+  "oracle-control-mcp",
+  "oracle-operator-caps",
+]);
+
+export const SIGN_NOUNS = Object.freeze([
+  "vault",
+  "credential",
+  "signer",
+  "runner",
+  "sign",
+]);
+
+export const OPERATOR_NOT_INSTALLED_MESSAGE = `oracle: signing lives in @oracle-agent/operator, which is not installed.
+
+  The public 'oracle' package is prepare-only and never handles keys.
+  To enable local signing on THIS machine:
+
+    npm i -g @oracle-agent/operator      # or add it to this project
+    oracle sign init                     # provision keys + policy (interactive)
+
+  Nothing about your read/research setup is affected.
+`;
+
+export const SIGN_HINT =
+  "hint: run 'oracle sign init' to provision keys, or 'oracle sign doctor --json' for detail.";
+
+function whichOnPath(binName) {
+  const pathEnv = process.env.PATH || "";
+  const parts = pathEnv.split(path.delimiter).filter(Boolean);
+  const exts = process.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
+  for (const dir of parts) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, binName + ext);
+      try {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+          return candidate;
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return null;
+}
+
+function binsFromDir(binDir) {
+  const bins = {};
+  for (const name of OPERATOR_BIN_NAMES) {
+    const candidates = [
+      path.join(binDir, name),
+      path.join(binDir, `${name}.mjs`),
+      path.join(binDir, `${name}.js`),
+    ];
+    for (const c of candidates) {
+      if (fs.existsSync(c) && fs.statSync(c).isFile()) {
+        bins[name] = c;
+        break;
+      }
+    }
+  }
+  return bins;
+}
+
+function findPackageRoot(entryPath) {
+  let dir = path.dirname(entryPath);
+  while (dir !== path.dirname(dir)) {
+    const pkgJson = path.join(dir, "package.json");
+    if (fs.existsSync(pkgJson)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf8"));
+        if (pkg.name === "@oracle-agent/operator") return { root: dir, pkg };
+      } catch {
+        // continue upward
+      }
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function tryResolvePackage(fromPaths) {
+  for (const from of fromPaths) {
+    try {
+      const req = createRequire(path.join(from, "package.json"));
+      let found;
+      try {
+        const pkgJson = req.resolve("@oracle-agent/operator/package.json");
+        found = {
+          root: path.dirname(pkgJson),
+          pkg: JSON.parse(fs.readFileSync(pkgJson, "utf8")),
+        };
+      } catch {
+        const entry = req.resolve("@oracle-agent/operator");
+        found = findPackageRoot(entry);
+      }
+      if (!found) continue;
+      const { root, pkg } = found;
+      const binField = pkg.bin || {};
+      const bins = {};
+      for (const [name, rel] of Object.entries(binField)) {
+        bins[name] = path.resolve(root, rel);
+      }
+      const extra = binsFromDir(path.join(root, "bin"));
+      for (const [k, v] of Object.entries(extra)) {
+        if (!bins[k]) bins[k] = v;
+      }
+      return {
+        ok: true,
+        binDir: path.join(root, "bin"),
+        version: pkg.version || "unknown",
+        bins,
+        source: `require:${from}`,
+      };
+    } catch {
+      // continue
+    }
+  }
+  return null;
+}
+
+function tryCapsOnPath() {
+  const capsBin = whichOnPath("oracle-operator-caps");
+  if (!capsBin) return null;
+  const r = spawnSync(capsBin, [], {
+    encoding: "utf8",
+    timeout: 5000,
+    env: process.env,
+  });
+  if (r.status !== 0 || !r.stdout) return null;
+  try {
+    const report = JSON.parse(r.stdout);
+    if (!report || typeof report !== "object" || !report.bins) return null;
+    return {
+      ok: true,
+      binDir: path.dirname(Object.values(report.bins)[0] || capsBin),
+      version: report.version || "unknown",
+      bins: report.bins,
+      source: "caps-path",
+      controlMcp: report.controlMcp,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function tryPathProbe() {
+  const bins = {};
+  for (const name of OPERATOR_BIN_NAMES) {
+    const hit = whichOnPath(name);
+    if (hit) bins[name] = hit;
+  }
+  if (!Object.keys(bins).length) return null;
+  return {
+    ok: true,
+    binDir: path.dirname(Object.values(bins)[0]),
+    version: "unknown",
+    bins,
+    source: "path-probe",
+  };
+}
+
+export function resolveOperator() {
+  const envDir = process.env.ORACLE_OPERATOR_BIN_DIR;
+  if (envDir) {
+    const abs = path.resolve(envDir);
+    if (!fs.existsSync(abs)) return { ok: false };
+    const bins = binsFromDir(abs);
+    if (!Object.keys(bins).length) return { ok: false };
+    let version = "unknown";
+    const pkgCandidate = path.resolve(abs, "../package.json");
+    if (fs.existsSync(pkgCandidate)) {
+      try {
+        version = JSON.parse(fs.readFileSync(pkgCandidate, "utf8")).version || version;
+      } catch {
+        // ignore
+      }
+    }
+    return { ok: true, binDir: abs, version, bins, source: "env:ORACLE_OPERATOR_BIN_DIR" };
+  }
+
+  const fromPkg =
+    tryResolvePackage([process.cwd(), PACKAGE_ROOT]) ||
+    tryCapsOnPath() ||
+    tryPathProbe();
+  return fromPkg || { ok: false };
+}
+
+export function printOperatorNotInstalled(stream = process.stderr) {
+  stream.write(OPERATOR_NOT_INSTALLED_MESSAGE);
+  if (!OPERATOR_NOT_INSTALLED_MESSAGE.endsWith("\n")) stream.write("\n");
+}
+
+export function dispatchOperator(binName, argv = [], opts = {}) {
+  const resolved = resolveOperator();
+  if (!resolved.ok) {
+    printOperatorNotInstalled(opts.stderr || process.stderr);
+    return 3;
+  }
+  const binPath = resolved.bins[binName];
+  if (!binPath) {
+    const err = opts.stderr || process.stderr;
+    err.write(`oracle: operator bin '${binName}' not found in resolved operator (${resolved.source})\n`);
+    return 3;
+  }
+
+  const stdio = opts.stdio || "inherit";
+  const isJs = /\.(mjs|cjs|js)$/.test(binPath);
+  const command = isJs ? process.execPath : binPath;
+  const args = isJs ? [binPath, ...argv] : [...argv];
+  const r = spawnSync(command, args, {
+    stdio,
+    env: opts.env || process.env,
+    cwd: opts.cwd || process.cwd(),
+    encoding: stdio === "pipe" ? "utf8" : undefined,
+  });
+
+  if (r.error) {
+    const err = opts.stderr || process.stderr;
+    err.write(`oracle: failed to spawn ${binName}: ${r.error.message}\n`);
+    return 1;
+  }
+
+  const code = typeof r.status === "number" ? r.status : 1;
+  if (code !== 0 && opts.appendHintOnError) {
+    const err = opts.stderr || process.stderr;
+    err.write(SIGN_HINT + "\n");
+  }
+  if (stdio === "pipe") {
+    return { code, stdout: r.stdout || "", stderr: r.stderr || "" };
+  }
+  return code;
+}
+
+export default {
+  resolveOperator,
+  dispatchOperator,
+  printOperatorNotInstalled,
+  OPERATOR_NOT_INSTALLED_MESSAGE,
+  SIGN_HINT,
+  SIGN_NOUNS,
+  OPERATOR_BIN_NAMES,
+};

package/src/cli/paths.mjs

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_ROOT = path.resolve(HERE, "../..");
+
+export function homeDir() {
+  return process.env.ORACLE_FAKE_HOME || os.homedir();
+}
+
+export function oracleConfigDir() {
+  return path.join(homeDir(), ".config", "oracle");
+}
+
+export function oracleExecEnvPath() {
+  return path.join(oracleConfigDir(), "exec.env");
+}
+
+export function hermesRoot() {
+  if (process.env.HERMES_HOME) return path.resolve(process.env.HERMES_HOME);
+  return path.join(homeDir(), ".hermes");
+}
+
+export function claudeCodeUserConfigPath() {
+  return path.join(homeDir(), ".claude.json");
+}
+
+export function claudeCodeProjectMcpPath(cwd = process.cwd()) {
+  return path.join(cwd, ".mcp.json");
+}
+
+export function claudeDesktopConfigPath() {
+  if (process.platform === "darwin") {
+    return path.join(homeDir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  return path.join(homeDir(), ".config", "Claude", "claude_desktop_config.json");
+}
+
+export function codexConfigPath() {
+  return path.join(homeDir(), ".codex", "config.toml");
+}
+
+export function chatgptConnectorDir() {
+  return path.join(oracleConfigDir(), "connectors");
+}
+
+export function chatgptOpenApiPath() {
+  return path.join(chatgptConnectorDir(), "chatgpt-openapi.json");
+}
+
+export function packageBin(name) {
+  return path.join(PACKAGE_ROOT, "bin", name);
+}
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export const paths = {
+  homeDir,
+  oracleConfigDir,
+  oracleExecEnvPath,
+  hermesRoot,
+  claudeCodeUserConfigPath,
+  claudeCodeProjectMcpPath,
+  claudeDesktopConfigPath,
+  codexConfigPath,
+  chatgptConnectorDir,
+  chatgptOpenApiPath,
+  packageBin,
+  ensureDir,
+  PACKAGE_ROOT,
+};
+
+export default paths;

package/src/cli/spawn-child.mjs

@@ -0,0 +1,43 @@
+import { spawn } from "node:child_process";
+
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+export function spawnChild(command, args = [], options = {}, label = command) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, options);
+    let settled = false;
+    let forwardedSignal = null;
+
+    const handlers = new Map(
+      FORWARDED_SIGNALS.map((signal) => [signal, () => {
+        forwardedSignal ||= signal;
+        if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+      }]),
+    );
+    for (const [signal, handler] of handlers) process.on(signal, handler);
+
+    const cleanup = () => {
+      for (const [signal, handler] of handlers) process.off(signal, handler);
+    };
+
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      process.stderr.write(`oracle: could not start ${label}: ${error.message}\n`);
+      resolve(1);
+    });
+
+    child.once("exit", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      const propagated = forwardedSignal || signal;
+      if (propagated) {
+        process.kill(process.pid, propagated);
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+}

package/src/public-api/connect-agent.mjs

@@ -53,6 +53,18 @@ export class SecretLeakError extends Error {
 const FORBIDDEN_KEY_RE =
   /(private[_-]?key|secret|bearer|keystore|mnemonic|seed[_-]?phrase|passphrase|password|api[_-]?key|access[_-]?token|auth[_-]?token|session[_-]?token|signer[_-]?url|signature)/i;
 
+/** Short wallet-export aliases need exact normalized matching. Substring
+ * matching `wif`, for example, would incorrectly reject an unrelated key such
+ * as `swift`. Removing common separators catches snake/kebab/spaced variants
+ * without widening those short aliases into arbitrary words. */
+const FORBIDDEN_KEY_ALIASES = Object.freeze(["privkey", "wif", "xprv", "seed"]);
+
+function isForbiddenKeyName(key) {
+  const text = String(key);
+  const normalized = text.toLowerCase().replace(/[\s._-]+/g, "");
+  return FORBIDDEN_KEY_RE.test(text) || FORBIDDEN_KEY_ALIASES.includes(normalized);
+}
+
 /** String-value shapes that must never appear in any object we return. */
 const FORBIDDEN_VALUE_RULES = Object.freeze([
   // 32-byte hex — the shape of a raw EVM private key / session secret. Public
@@ -69,8 +81,12 @@ const FORBIDDEN_VALUE_RULES = Object.freeze([
   // gets disabled. Smuggling a key inside a longer string is still caught at
   // the serialized layer for any non-allowlisted field.
   { rule: "raw-32-byte-hex-bare", re: /^[0-9a-fA-F]{64}$/ },
-  // Bitcoin WIF (mainnet 5/K/L, testnet c) — base58, 51-52 chars.
-  { rule: "bitcoin-wif", re: /\b[5KLc][1-9A-HJ-NP-Za-km-z]{50,51}\b/ },
+  // BIP-32 private extended keys. Public xpub/tpub/ypub/zpub identifiers are
+  // intentionally not matched; only their private-key counterparts fail.
+  { rule: "extended-private-key", re: /\b(?:xprv|tprv|yprv|zprv)[1-9A-HJ-NP-Za-km-z]{107}\b/ },
+  // Bitcoin WIF (mainnet 5/K/L, testnet uncompressed 9 or compressed c) —
+  // base58, 51-52 chars.
+  { rule: "bitcoin-wif", re: /\b[59KLc][1-9A-HJ-NP-Za-km-z]{50,51}\b/ },
   // BIP-39 mnemonic: 12/15/18/21/24 lowercase words. Detect a long run of
   // space-separated short alpha words rather than shipping the wordlist.
   { rule: "bip39-mnemonic", re: /\b(?:[a-z]{3,8}\s+){11,23}[a-z]{3,8}\b/ },
@@ -169,12 +185,15 @@ export function assertSerializedNoSecrets(value) {
   if (embedded.test(scanned)) {
     throw new SecretLeakError("$<serialized>", "raw-32-byte-hex-embedded");
   }
-  // Key names are checked against the serialized text too, so a key smuggled
-  // in via toJSON or a getter is still caught.
-  const keyHit = scanned.match(
-    /"([^"]*(?:private[_-]?key|secret|bearer|keystore|mnemonic|seed[_-]?phrase|passphrase|password|api[_-]?key|access[_-]?token|auth[_-]?token|session[_-]?token|signer[_-]?url)[^"]*)"\s*:/i
-  );
-  if (keyHit) throw new SecretLeakError(`$<serialized>.${keyHit[1]}`, "forbidden-key-name");
+  // Parse the exact serialized bytes with a reviver so escaped or toJSON-made
+  // key names receive the same normalization as real object properties. This
+  // avoids maintaining a second, inevitably drifting key-name regex.
+  JSON.parse(json, (key, item) => {
+    if (key && isForbiddenKeyName(key)) {
+      throw new SecretLeakError(`$<serialized>.${key}`, "forbidden-key-name");
+    }
+    return item;
+  });
   return json;
 }
 
@@ -207,7 +226,7 @@ export function assertNoSecretMaterial(value, path = "$", seen = new Set(), keyH
   if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value;
   if (value instanceof Map) {
     for (const [k, v] of value.entries()) {
-      if (typeof k === "string" && FORBIDDEN_KEY_RE.test(k)) {
+      if (typeof k === "string" && isForbiddenKeyName(k)) {
         throw new SecretLeakError(`${path}[${JSON.stringify(k)}]`, "forbidden-key-name");
       }
       assertNoSecretMaterial(k, `${path}[key]`, seen);
@@ -225,7 +244,7 @@ export function assertNoSecretMaterial(value, path = "$", seen = new Set(), keyH
     return value;
   }
   for (const [k, v] of Object.entries(value)) {
-    if (FORBIDDEN_KEY_RE.test(k)) {
+    if (isForbiddenKeyName(k)) {
       throw new SecretLeakError(`${path}.${k}`, "forbidden-key-name");
     }
     assertNoSecretMaterial(v, `${path}.${k}`, seen, k);