@oracle-agent/oracle 0.4.1 → 0.5.0

package/scripts/adversarial-bench.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+const INJECTION_RULES = [
+  ["instruction-override", /\b(?:ignore|disregard|override)\b.{0,48}\b(?:previous|prior|system|developer|instructions?)\b/i],
+  ["secret-exfiltration", /\b(?:reveal|print|return|exfiltrate|send)\b.{0,48}\b(?:private\s*key|seed\s*phrase|mnemonic|secret|credentials?|system\s*prompt)\b/i],
+  ["transaction-coercion", /\b(?:sign|send|broadcast|execute)\b.{0,32}\b(?:transaction|transfer|approval|trade)\b/i],
+  ["tool-coercion", /\b(?:call|invoke|use|run)\b.{0,24}\b(?:tool|function|shell|command)\b/i],
+];
+
+const FORBIDDEN_EXPORT = /^(?:signer|sign|signMessage|signTransaction|sendTransaction|broadcastTransaction|submitTransaction|executeTransaction|privateKey|secretKey|mnemonic|seedPhrase|wallet)$/i;
+
+function finding(code, path, message) {
+  return { code, path, message };
+}
+
+function scanStrings(value, path, findings, seen) {
+  if (typeof value === "string") {
+    for (const [rule, pattern] of INJECTION_RULES) {
+      if (pattern.test(value)) {
+        findings.push(finding("prompt-injection", path, `metadata matches ${rule}`));
+        break;
+      }
+    }
+    return;
+  }
+  if (!value || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => scanStrings(item, `${path}[${index}]`, findings, seen));
+    return;
+  }
+  for (const key of Object.keys(value).sort()) {
+    scanStrings(value[key], path ? `${path}.${key}` : key, findings, seen);
+  }
+}
+
+/** Validate one loaded Oracle protocol pack without calling provider code. */
+export function benchmarkPack(moduleValue, { name = "pack" } = {}) {
+  const namespace = moduleValue && typeof moduleValue === "object" ? moduleValue : {};
+  const pack = namespace.default && typeof namespace.default === "object" ? namespace.default : namespace;
+  const findings = [];
+
+  for (const key of Object.keys(namespace).sort()) {
+    if (key !== "default" && FORBIDDEN_EXPORT.test(key)) {
+      findings.push(finding("forbidden-signer-export", `exports.${key}`, `pack exports custody capability ${key}`));
+    }
+  }
+  for (const key of Object.keys(pack).sort()) {
+    if (FORBIDDEN_EXPORT.test(key)) {
+      findings.push(finding("forbidden-signer-export", `pack.${key}`, `pack exports custody capability ${key}`));
+    }
+  }
+
+  if (!pack.provider || typeof pack.provider !== "object") {
+    findings.push(finding("missing-provider", "pack.provider", "provider metadata is required"));
+  }
+  if (typeof pack.prepare !== "function") {
+    findings.push(finding("missing-prepare", "pack.prepare", "prepare must be a function"));
+  }
+  if (typeof pack.decode !== "function") {
+    findings.push(finding("missing-decoder", "pack.decode", "decode must be a function"));
+  }
+  if (!(Array.isArray(pack.riskRules) || typeof pack.riskRules === "function")) {
+    findings.push(finding("missing-risk-rules", "pack.riskRules", "riskRules must be an array or function"));
+  }
+  if (!pack.tests || typeof pack.tests !== "object" || Array.isArray(pack.tests) || Object.keys(pack.tests).length === 0) {
+    findings.push(finding("missing-tests", "pack.tests", "non-empty tests metadata is required"));
+  }
+
+  // Metadata is untrusted even when nested below token/NFT records. Scan data only;
+  // functions are deliberately never invoked by this local harness.
+  scanStrings(pack.metadata, "pack.metadata", findings, new Set());
+  scanStrings(pack.provider, "pack.provider", findings, new Set());
+
+  findings.sort((a, b) => `${a.code}\0${a.path}\0${a.message}`.localeCompare(`${b.code}\0${b.path}\0${b.message}`));
+  return { name, ok: findings.length === 0, findings };
+}
+
+/** Run a stable summary over already-loaded fixture/module records. */
+export function runAdversarialBenchmark(entries) {
+  const results = entries
+    .map((entry, index) => benchmarkPack(entry.module ?? entry, { name: entry.name ?? `pack-${index + 1}` }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  return {
+    ok: results.every((result) => result.ok),
+    packs: results.length,
+    passed: results.filter((result) => result.ok).length,
+    failed: results.filter((result) => !result.ok).length,
+    findings: results.reduce((count, result) => count + result.findings.length, 0),
+    results,
+  };
+}
+
+async function main(paths) {
+  if (paths.length === 0) throw new Error("usage: node scripts/adversarial-bench.mjs <pack.mjs> [...]");
+  const entries = [];
+  for (const input of paths) {
+    const absolute = resolve(input);
+    entries.push({ name: input, module: await import(pathToFileURL(absolute).href) });
+  }
+  const summary = runAdversarialBenchmark(entries);
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+  if (!summary.ok) process.exitCode = 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stdout.write(`${JSON.stringify({ ok: false, error: String(error.message || error) }, null, 2)}\n`);
+    process.exitCode = 2;
+  });
+}

package/scripts/check-doc-drift.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Release gate: shipped prose must not contradict shipped behavior.
+//
+// Why this exists. The 2026-08-01 four-model audit found the same stale claim
+// in 20 places across both packages: docs said the unattended signer was
+// limited to `hl` and `poly` long after six bounded surfaces had shipped. The
+// worst instances were not READMEs — they were `profiles/oracle/SOUL.md` and
+// `skills/oracle-action-semantics/SKILL.md`, which are read by the MODEL. An
+// agent told that EVM daemon execution is impossible reasons incorrectly about
+// its own authority, and no test suite can see a false sentence.
+//
+// This scans every doc surface that ships in the tarball, including model-facing
+// SOUL and skill text, which is exactly where drift hides longest.
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+const failures = [];
+
+// Claims that shipped in a real release and are now false.
+const STALE_CLAIMS = [
+  { re: /limited\s+to\s+`?hl`?\s+and\s+`?poly`?/i, why: "says the unattended signer is limited to hl+poly" },
+  { re: /only\s+`?hl`?\s+and\s+`?poly`?\s+are\s+enabled/i, why: "says only hl+poly are daemon-enabled" },
+  { re: /daemon\s+surfaces\s+remain\s+`?hl`?\s+and\s+`?poly`?/i, why: "freezes the surface list at hl+poly" },
+  { re: /policy-bounded\s+`?hl`?\s+and\s+`?poly`?\s+only/i, why: "restricts the daemon to hl+poly" },
+  { re: /agent-facing\s+daemon\s+supports\s+only\s+policy-bounded\s+Hyperliquid\s+and\s+Polymarket\s+execution/i, why: "says the agent-facing daemon supports only Hyperliquid+Polymarket" },
+  { re: /`?evm`?,?\s+`?btc`?,?\s+and\s+`?sol`?\s+fail\s+closed\s+at\s+the\s+daemon/i, why: "claims evm/btc/sol are refused at the daemon" },
+  { re: /EVM,\s*BTC,?\s*and\s+Solana\s+are\s+not\s+daemon\s+surfaces/i, why: "denies evm/btc/sol are daemon surfaces" },
+  { re: /companion\s+daemon\s+is\s+`?hl`?\s*\/\s*`?poly`?[- ]only/i, why: "describes the companion daemon as hl/poly-only" },
+  { re: /daemon\s+supports\s+only\s+policy-bounded\s+Hyperliquid\s+and\s+Polymarket/i, why: "describes the daemon as Hyperliquid/Polymarket-only" },
+  { re: /unattended\s+signer\s+remains\s+`?hl`?\s*\/\s*`?poly`?/i, why: "freezes the generic signer at hl/poly" },
+  { re: /supports\s+autonomous\s+Hyperliquid\s+and\s+Polymarket\s+execution/i, why: "describes the daemon as Hyperliquid/Polymarket-only" },
+  { re: /\(HL\s*\+\s*Poly,\s*capped\)/i, why: "documents autosign as hl/poly-only" },
+  { re: /policy-bounded\s+HL\s*\/\s*Polymarket\s+exec/i, why: "documents the signer daemon as hl/poly-only" },
+  { re: /policy-bounded\s+daemon\s+surfaces:\s*hl\s*\|\s*poly\s*$/i, why: "documents only two of six daemon surfaces" },
+  { re: /ORACLE_SIGNER_SURFACES=hl,poly\s*$/i, why: "quickstart freezes ORACLE_SIGNER_SURFACES at hl,poly" },
+  { re: /ORACLE_AUTONOMOUS_TRADING=1.*(?:or\s+run\s+the\s+signer\s+daemon|same(?:-tier)?).*oracle-signer/i, why: "frames direct exec and oracle-signer as equivalent agent paths" },
+  { re: /(?:or\s+run\s+the\s+signer\s+daemon|same(?:-tier)?).*oracle-signer.*ORACLE_AUTONOMOUS_TRADING=1/i, why: "frames direct exec and oracle-signer as equivalent agent paths" },
+];
+
+// Version pins that go stale the moment a release ships. The audit found the
+// quickstart advertising 0.3.6/0.6.1 inside a 0.4.0 tarball, so a copy-paste
+// install handed users an older wall set.
+function checkVersionPins(rel, text) {
+  const lines = text.split("\n");
+  lines.forEach((line, i) => {
+    const pin = line.match(/@oracle-agent\/oracle@(\d+\.\d+\.\d+)/);
+    if (pin && pin[1] !== pkg.version) {
+      failures.push(
+        `${rel}:${i + 1} pins @oracle-agent/oracle@${pin[1]} but this package is ${pkg.version}\n    ${line.trim().slice(0, 120)}`,
+      );
+    }
+    const latest = line.match(/Latest:.*oracle\s+`(\d+\.\d+\.\d+)`/i);
+    if (latest && latest[1] !== pkg.version) {
+      failures.push(
+        `${rel}:${i + 1} advertises oracle ${latest[1]} as latest but this package is ${pkg.version}\n    ${line.trim().slice(0, 120)}`,
+      );
+    }
+  });
+}
+
+// Every markdown surface that ships to a user or a model.
+function docFiles() {
+  const out = [];
+  for (const rel of ["README.md", "SETUP.md", "SECURITY.md"]) {
+    if (existsSync(path.join(root, rel))) out.push(rel);
+  }
+  for (const dir of ["docs", "profiles", "skills"]) {
+    const abs = path.join(root, dir);
+    if (!existsSync(abs)) continue;
+    const walk = (d) => {
+      for (const entry of readdirSync(d)) {
+        const full = path.join(d, entry);
+        if (statSync(full).isDirectory()) walk(full);
+        else if (entry.endsWith(".md")) out.push(path.relative(root, full));
+      }
+    };
+    walk(abs);
+  }
+  return out;
+}
+
+const files = docFiles();
+for (const rel of files) {
+  const text = readFileSync(path.join(root, rel), "utf8");
+  text.split("\n").forEach((line, i) => {
+    for (const claim of STALE_CLAIMS) {
+      if (claim.re.test(line)) {
+        failures.push(`${rel}:${i + 1} ${claim.why}\n    ${line.trim().slice(0, 140)}`);
+      }
+    }
+  });
+  checkVersionPins(rel, text);
+}
+
+console.log(`package version: ${pkg.version}`);
+console.log(`doc surfaces scanned: ${files.length} (README/SETUP/SECURITY + docs/ + profiles/ + skills/)`);
+console.log("");
+
+if (failures.length) {
+  console.error(`FAIL — ${failures.length} doc/code drift finding(s):\n`);
+  for (const f of failures) console.error(`  ${f}\n`);
+  console.error("Shipped prose contradicts shipped behavior. Model-facing SOUL/skill text counts:");
+  console.error("an agent that reads a false capability claim reasons wrongly about its own authority.");
+  process.exit(1);
+}
+
+console.log("PASS — no stale capability claims or version pins in shipped docs");

package/skills/oracle-action-semantics/SKILL.md

@@ -8,7 +8,7 @@ description: Use for watch, ping, prepare, arm, sign, send, or execution-capabil
 Keep these planes distinct:
 
 1. **Public prepare plane**: reads, quotes, simulates, and prepares unsigned artifacts. It never signs or broadcasts.
-2. **Generic Oracle signer**: the unattended daemon surfaces remain `hl` and `poly`. This does not grant EVM authority.
+2. **Generic Oracle signer**: the unattended daemon exposes six *bounded* surfaces — `hl`, `poly`, `evm-swap`, `evm-bridge`, `btc`, `sol`. Bounded is not generic chain authority: each surface decodes and validates its own envelope shape and refuses while its allowlists are empty. Enablement is never authority; every signature still needs one exact owner-confirmed grant.
 3. **User-wallet EVM**: ordinary EVM preparations require the user's wallet signature.
 4. **Optional bounded EVM execution**: a deployment may expose a separate same-host, owner-gated EVM executor such as MAD. Verify its status and policy before saying it is available. Never infer it from the public package or the generic signer.
 

package/src/action-receipts.mjs

@@ -0,0 +1,168 @@
+// Deterministic, public-only receipts for prepared and executed actions.
+//
+// This module deliberately has no authority and no I/O: it does not authorize,
+// sign, broadcast, or fetch. It only records facts supplied by its caller.
+
+import { createHash } from "node:crypto";
+
+export const ACTION_RECEIPT_VERSION = 1;
+
+const SECRET_KEYS = new Set([
+  "privatekey",
+  "mnemonic",
+  "bearer",
+  "authorization",
+  "signature",
+]);
+
+export class ActionReceiptSecretError extends Error {
+  constructor(path) {
+    super(`action receipt refused: secret-bearing field at ${path}`);
+    this.name = "ActionReceiptSecretError";
+    this.code = "ACTION_RECEIPT_SECRET";
+  }
+}
+
+function normalizedKey(key) {
+  return String(key).replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+
+function isSecretKey(key) {
+  const normalized = normalizedKey(key);
+  return [...SECRET_KEYS].some((secret) => normalized.includes(secret));
+}
+
+function publicValue(value, path = "$") {
+  if (value == null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError(`action receipt: non-finite number at ${path}`);
+    return value;
+  }
+  if (typeof value === "bigint") return value.toString();
+  if (Array.isArray(value)) return value.map((item, index) => publicValue(item, `${path}[${index}]`));
+  if (typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new TypeError(`action receipt: JSON-like value required at ${path}`);
+  }
+
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    const childPath = `${path}.${key}`;
+    if (isSecretKey(key)) throw new ActionReceiptSecretError(childPath);
+    if (value[key] !== undefined) out[key] = publicValue(value[key], childPath);
+  }
+  return out;
+}
+
+/** Recursively reject secret-bearing fields and return a detached public copy. */
+export function assertNoReceiptSecrets(value) {
+  return publicValue(value);
+}
+
+/** Canonical JSON with recursively sorted object keys. */
+export function canonicalReceiptJson(value) {
+  const safe = publicValue(value);
+  if (safe === null || typeof safe !== "object") return JSON.stringify(safe);
+  if (Array.isArray(safe)) return `[${safe.map(canonicalReceiptJson).join(",")}]`;
+  return `{${Object.keys(safe).map((key) => `${JSON.stringify(key)}:${canonicalReceiptJson(safe[key])}`).join(",")}}`;
+}
+
+/** Hash exactly the public receipt fields, excluding the self-referential id. */
+export function computeReceiptId(receipt) {
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+    throw new TypeError("action receipt: object required");
+  }
+  const { receiptId: _ignored, summary: _derived, ...publicFields } = receipt;
+  return createHash("sha256").update(canonicalReceiptJson(publicFields)).digest("hex");
+}
+
+function supplied(input, ...keys) {
+  for (const key of keys) if (input[key] !== undefined) return input[key];
+  return undefined;
+}
+
+function required(input, keys, label) {
+  const value = supplied(input, ...keys);
+  if (value === undefined || value === null) throw new TypeError(`action receipt: ${label} required`);
+  return value;
+}
+
+function balanceFields(input) {
+  const balances = supplied(input, "balances", "balanceChanges");
+  const before = supplied(input, "beforeBalances", "balancesBefore", "before");
+  const after = supplied(input, "afterBalances", "balancesAfter", "after");
+  if (balances !== undefined) return { balances };
+  if (before === undefined && after === undefined) return {};
+  return { balances: { ...(before === undefined ? {} : { before }), ...(after === undefined ? {} : { after }) } };
+}
+
+/**
+ * Normalize caller-supplied prepare/execute facts into the versioned schema.
+ * Unknown input fields are intentionally omitted from the receipt.
+ */
+export function normalizeActionReceipt(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("action receipt: input object required");
+  }
+  // Scan the complete input before selecting fields so a secret cannot be
+  // hidden in an otherwise unknown property and accidentally appear later.
+  publicValue(input);
+
+  const txHash = supplied(input, "txHash", "transactionHash");
+  const phase = supplied(input, "phase", "stage", "resultType") ?? (txHash == null ? "prepare" : "execute");
+  if (phase !== "prepare" && phase !== "execute") {
+    throw new TypeError('action receipt: phase must be "prepare" or "execute"');
+  }
+
+  const fields = {
+    receiptVersion: ACTION_RECEIPT_VERSION,
+    phase,
+    intent: required(input, ["intent"], "intent"),
+    route: required(input, ["route"], "route"),
+    decodedAction: required(input, ["decodedAction", "action"], "decodedAction"),
+    policyChecks: required(input, ["policyChecks", "checks"], "policyChecks"),
+    allowlistHits: required(input, ["allowlistHits", "allowlistMatches"], "allowlistHits"),
+    prepareHash: required(input, ["prepareHash"], "prepareHash"),
+    ...(txHash == null ? {} : { txHash }),
+    ...balanceFields(input),
+  };
+  const receipt = publicValue(fields);
+  return Object.freeze({ ...receipt, receiptId: computeReceiptId(receipt) });
+}
+
+export const createActionReceipt = normalizeActionReceipt;
+
+function label(value, preferred = []) {
+  if (typeof value === "string" || typeof value === "number") return String(value);
+  for (const key of preferred) if (value?.[key] != null) return String(value[key]);
+  return "recorded";
+}
+
+function checkResult(check) {
+  if (typeof check === "boolean") return check;
+  if (check && typeof check === "object") {
+    if (typeof check.ok === "boolean") return check.ok;
+    if (typeof check.allowed === "boolean") return check.allowed;
+    if (typeof check.passed === "boolean") return check.passed;
+  }
+  return null;
+}
+
+/** Produce a compact human-readable statement without changing the receipt. */
+export function summarizeActionReceipt(receipt) {
+  if (!receipt || typeof receipt !== "object") throw new TypeError("action receipt: object required");
+  const action = label(receipt.decodedAction, ["type", "action", "method", "name"]);
+  const route = label(receipt.route, ["name", "provider", "venue", "id"]);
+  const checks = Array.isArray(receipt.policyChecks)
+    ? receipt.policyChecks
+    : Object.values(receipt.policyChecks || {});
+  const passed = checks.filter((check) => checkResult(check) === true).length;
+  const failed = checks.filter((check) => checkResult(check) === false).length;
+  const hits = Array.isArray(receipt.allowlistHits)
+    ? receipt.allowlistHits.length
+    : Object.keys(receipt.allowlistHits || {}).length;
+  const tx = receipt.txHash == null ? "no transaction hash" : `tx ${receipt.txHash}`;
+  const balances = receipt.balances == null ? "balances not provided" : "before/after balances recorded";
+  return `${receipt.phase} ${action} via ${route}; policy ${passed} passed, ${failed} failed; ${hits} allowlist hit${hits === 1 ? "" : "s"}; ${tx}; ${balances}; receipt ${receipt.receiptId}`;
+}
+
+export const formatActionReceipt = summarizeActionReceipt;

package/src/address-book.mjs

@@ -14,6 +14,47 @@ const FORBIDDEN_KEYS = new Set([
   "privatekey", "private_key", "secret", "seed", "mnemonic", "passphrase", "signature", "keystore",
 ]);
 
+// Exact-name matching missed obvious aliases (secretKey, seedPhrase, wif,
+// keyMaterial, xprv...). Match on a normalized key instead: strip separators,
+// lowercase, then look for any secret-ish token as a substring. A label store
+// has no legitimate field containing these words.
+const FORBIDDEN_TOKENS = [
+  "privatekey", "privkey", "secretkey", "secret", "seedphrase", "seed", "mnemonic",
+  "passphrase", "password", "keystore", "keymaterial", "signature", "wif",
+  "xprv", "xpriv", "apikey", "bearer", "credential",
+];
+
+// Key-shaped values must not be persisted even in a free-text field. WIF, xprv,
+// and BIP39 shapes are unambiguous. A bare 64-hex string is NOT — a raw EVM
+// private key and a bytes32 tx hash are byte-identical — so that rule matches
+// only when the WHOLE field is the hex blob. "paid via tx 0xabc..." is a note,
+// not a leaked key.
+const KEY_SHAPED_VALUE = [
+  /\b[5KL][1-9A-HJ-NP-Za-km-z]{50,51}\b/,
+  /\bxprv[0-9A-Za-z]{50,}\b/,
+  /\b(?:[a-z]{3,8}\s+){11,}[a-z]{3,8}\b/i,
+];
+
+const BARE_32_BYTE_HEX = /^\s*(?:0x)?[0-9a-fA-F]{64}\s*$/;
+
+function normalizeKeyName(key) {
+  return String(key).toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function assertNoSecretKeyName(key, path) {
+  const normalized = normalizeKeyName(key);
+  if (FORBIDDEN_KEYS.has(String(key).toLowerCase()) || FORBIDDEN_TOKENS.some((t) => normalized.includes(t))) {
+    throw new Error(`address-book: ${path} is forbidden; the book stores labels, never key material`);
+  }
+}
+
+function assertNoSecretValue(value, path) {
+  if (typeof value !== "string") return;
+  if (KEY_SHAPED_VALUE.some((re) => re.test(value)) || BARE_32_BYTE_HEX.test(value)) {
+    throw new Error(`address-book: ${path} looks like key material; the book stores labels, never key material`);
+  }
+}
+
 export function addressBookPath() {
   const override = env("ORACLE_ADDRESS_BOOK", "MAD_ADDRESS_BOOK", "");
   if (override) return path.resolve(override);
@@ -21,11 +62,18 @@ export function addressBookPath() {
   return path.join(dir, "address-book.json");
 }
 
-function assertNoSecrets(input) {
-  for (const key of Object.keys(input || {})) {
-    if (FORBIDDEN_KEYS.has(key.toLowerCase())) {
-      throw new Error(`address-book: ${key} is forbidden; the book stores labels, never key material`);
-    }
+function assertNoSecrets(input, path = "field") {
+  if (Array.isArray(input)) {
+    input.forEach((item, i) => assertNoSecrets(item, `${path}[${i}]`));
+    return;
+  }
+  if (!input || typeof input !== "object") {
+    assertNoSecretValue(input, path);
+    return;
+  }
+  for (const [key, value] of Object.entries(input)) {
+    assertNoSecretKeyName(key, key);
+    assertNoSecrets(value, key);
   }
 }
 

package/src/cli/commands/credential.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "credential",
+  summary: "OS credential store glue",
+  group: "sign",
+  usage: "oracle credential <get|set|delete> ...",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-credential", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/data-mcp.mjs

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { spawnChild } from "../spawn-child.mjs";
+
+export default {
+  name: "data-mcp",
+  summary: "start the read-only data MCP server",
+  group: "read",
+  usage: "oracle data-mcp",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-data-mcp.mjs");
+    return spawnChild(
+      process.execPath,
+      [bin, ...ctx.argv],
+      { stdio: "inherit", env: process.env },
+      "oracle-data-mcp",
+    );
+  },
+};

package/src/cli/commands/data.mjs

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { spawnChild } from "../spawn-child.mjs";
+
+const DEFAULT_DATA_URL = "http://127.0.0.1:8787";
+
+function usage() {
+  process.stderr.write(
+    "usage: oracle data <serve|call|catalog|health> [args]\n" +
+      "  oracle data serve [--port N]\n" +
+      "  oracle data call <provider> <op> [--args '<json>']\n" +
+      "  oracle data catalog\n" +
+      "  oracle data health\n",
+  );
+}
+
+async function dataFetch(pathname, { method = "GET", body } = {}) {
+  const base = (process.env.ORACLE_DATA_URL || DEFAULT_DATA_URL).replace(/\/$/, "");
+  const url = base + pathname;
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: body ? { "content-type": "application/json" } : undefined,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    process.stdout.write(text.endsWith("\n") ? text : text + "\n");
+    return res.ok ? 0 : 1;
+  } catch (err) {
+    if (err && (err.code === "ECONNREFUSED" || /fetch failed|ECONNREFUSED/i.test(String(err)))) {
+      process.stderr.write("oracle: data server not running — start it with 'oracle data serve'\n");
+      return 4;
+    }
+    process.stderr.write(`oracle data: ${err.message || err}\n`);
+    return 1;
+  }
+}
+
+export default {
+  name: "data", summary: "desk data plane", group: "read",
+  usage: "oracle data serve|call|catalog|health",
+  async run(ctx) {
+    const verb = ctx.argv[0];
+    if (!verb || verb === "--help" || verb === "-h") { usage(); return verb ? 0 : 1; }
+    if (verb === "serve") {
+      let port = null;
+      try {
+        const { values } = parseArgs({ args: ctx.argv.slice(1), options: { port: { type: "string" } }, allowPositionals: true, strict: false });
+        port = values.port || null;
+      } catch {}
+      const env = { ...process.env };
+      if (port) env.ORACLE_DATA_PORT = String(port);
+      const bin = path.join(ctx.root, "bin", "desk-server.mjs");
+      return spawnChild(process.execPath, [bin], { stdio: "inherit", env }, "desk-server");
+    }
+    if (verb === "health") return dataFetch("/");
+    if (verb === "catalog") return dataFetch("/data/catalog");
+    if (verb === "call") {
+      const provider = ctx.argv[1];
+      const op = ctx.argv[2];
+      if (!provider || !op) { usage(); return 1; }
+      let argsObj = {};
+      const i = ctx.argv.indexOf("--args");
+      if (i >= 0) {
+        try { argsObj = JSON.parse(ctx.argv[i + 1] || "{}"); }
+        catch (err) { process.stderr.write(`oracle data call: invalid --args JSON: ${err.message}\n`); return 1; }
+      }
+      return dataFetch("/data/call", { method: "POST", body: { provider, op, args: argsObj } });
+    }
+    usage();
+    return 1;
+  },
+};