@oracle-agent/oracle 0.4.0 → 0.4.2

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/data/http.mjs

@@ -37,6 +37,35 @@ const IDENTITY_HEADERS = [
   "proxy-authorization",
 ];
 
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 3;
+
+function credentialHeaderName(name) {
+  const h = String(name || "").toLowerCase();
+  return IDENTITY_HEADERS.includes(h) || /(^|-)(api[-_]?key|key|token|secret|auth|authorization|session|cookie|signature|access)(-|$)/.test(h);
+}
+
+function stripCredentialHeaders(headers) {
+  const safe = {};
+  for (const [name, value] of Object.entries(headers || {})) {
+    if (!credentialHeaderName(name)) safe[name] = value;
+  }
+  return safe;
+}
+
+function redirectedUrl(location, currentUrl) {
+  if (!location) throw new Error(`HTTP redirect from ${currentUrl} missing Location`);
+  const next = new URL(String(location), String(currentUrl));
+  if (next.protocol !== "http:" && next.protocol !== "https:") {
+    throw new Error(`HTTP redirect from ${currentUrl} used unsupported protocol ${next.protocol}`);
+  }
+  return next.toString();
+}
+
+function sameOrigin(a, b) {
+  return new URL(String(a)).origin === new URL(String(b)).origin;
+}
+
 const inflight = new Map();
 
 /**
@@ -77,24 +106,48 @@ async function once(url, { fetchImpl, method, headers, body, timeoutMs }) {
   const ac = new AbortController();
   const t = setTimeout(() => ac.abort(), timeoutMs);
   try {
-    const res = await fetchImpl(url, { method, headers, body, signal: ac.signal });
-    const text = await res.text();
-    let json = null;
-    if (text) {
-      try {
-        json = JSON.parse(text);
-      } catch {
-        json = null;
+    let currentUrl = String(url);
+    let currentHeaders = { ...(headers || {}) };
+    for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects += 1) {
+      const res = await fetchImpl(currentUrl, {
+        method,
+        headers: currentHeaders,
+        body,
+        signal: ac.signal,
+        redirect: "manual",
+      });
+      const text = await res.text();
+      let json = null;
+      if (text) {
+        try {
+          json = JSON.parse(text);
+        } catch {
+          json = null;
+        }
       }
+      if (REDIRECT_STATUS.has(res.status)) {
+        if (method !== "GET" && method !== "HEAD") {
+          const err = new Error(`HTTP ${res.status} ${method} ${currentUrl} redirected non-idempotent request`);
+          err.status = res.status;
+          err.body = json ?? text.slice(0, 300);
+          throw err;
+        }
+        if (redirects === MAX_REDIRECTS) throw new Error(`HTTP redirect loop for ${url}`);
+        const nextUrl = redirectedUrl(res.headers?.get?.("location"), currentUrl);
+        if (!sameOrigin(nextUrl, currentUrl)) currentHeaders = stripCredentialHeaders(currentHeaders);
+        currentUrl = nextUrl;
+        continue;
+      }
+      if (!res.ok) {
+        const err = new Error(`HTTP ${res.status} ${method} ${currentUrl}`);
+        err.status = res.status;
+        err.retryAfter = res.headers?.get?.("retry-after") ?? null;
+        err.body = json ?? text.slice(0, 300);
+        throw err;
+      }
+      return json ?? text;
     }
-    if (!res.ok) {
-      const err = new Error(`HTTP ${res.status} ${method} ${url}`);
-      err.status = res.status;
-      err.retryAfter = res.headers?.get?.("retry-after") ?? null;
-      err.body = json ?? text.slice(0, 300);
-      throw err;
-    }
-    return json ?? text;
+    throw new Error(`HTTP redirect loop for ${url}`);
   } finally {
     clearTimeout(t);
   }

package/src/data/providers/magiceden-sol.mjs

@@ -90,17 +90,33 @@ function lamports(sol) {
 }
 
 function listingExpiry(value) {
-  if (value == null || value === "") return null;
+  if (value == null || value === "") throw new Error("magiceden: listing expiry is required and must be in the future");
   const expiry = Number(value);
-  if (!Number.isSafeInteger(expiry) || expiry < 0) {
-    throw new Error("magiceden: expiry must be a whole Unix timestamp in seconds or 0");
+  if (!Number.isSafeInteger(expiry) || expiry <= 0) {
+    throw new Error("magiceden: expiry must be a future Unix timestamp in seconds");
   }
-  if (expiry !== 0 && expiry <= Math.floor(Date.now() / 1000)) {
-    throw new Error("magiceden: expiry must be in the future or 0 for no expiry");
+  if (expiry <= Math.floor(Date.now() / 1000)) {
+    throw new Error("magiceden: expiry must be in the future");
   }
   return expiry;
 }
 
+function listConfirmation({ tokenMint, priceSol, expiry }) {
+  return `list ${tokenMint} on magiceden-sol for ${priceSol} SOL until ${expiry}`;
+}
+
+function requireListingConfirmation(args, fields) {
+  if (args.userConfirmed !== true) {
+    throw new Error("magiceden: listing requires userConfirmed=true after reviewing tokenMint, priceSol, and expiry");
+  }
+  const expected = listConfirmation(fields);
+  const actual = String(args.confirmation || args.confirmationPhrase || "").trim();
+  if (actual !== expected) {
+    throw new Error(`magiceden: confirmation must equal ${JSON.stringify(expected)}`);
+  }
+  return expected;
+}
+
 export async function magicEdenSolHealth(opts = {}) {
   try {
     const stats = await magicEdenSolStats({ symbol: "mad_lads" }, opts);
@@ -269,6 +285,7 @@ export async function magicEdenSolPrepareList(args = {}, opts = {}) {
   const auctionHouse = solanaPubkey(args.auctionHouse, "auctionHouse");
   const priceSol = positiveNumber(args.priceSol ?? args.price, "priceSol");
   const expiry = listingExpiry(args.expiry);
+  const confirmation = requireListingConfirmation(args, { tokenMint, priceSol, expiry });
   const url = new URL(`${base(opts)}/instructions/sell`);
   url.searchParams.set("seller", seller);
   url.searchParams.set("auctionHouseAddress", auctionHouse);
@@ -301,6 +318,7 @@ export async function magicEdenSolPrepareList(args = {}, opts = {}) {
     tokenMint,
     priceSol,
     expiry,
+    confirmation,
     transaction,
     transactionEncoding: "base64",
     raw,

package/src/exec-policy.mjs

@@ -419,6 +419,12 @@ export function enforceTxPolicy(tx = {}, phase = "broadcast") {
   // Spending caps toggle. Set MAD_VALUE_CAPS_ENABLED=0 in exec.env to lift the
   // per-tx + daily native caps (chain/dest allowlists still enforced). Flip back
   // to 1 to re-arm the cap wall. Default = ON when unset.
+  //
+  // Deliberately strict: ONLY the literal "0" lifts the caps. This is the
+  // opposite polarity from a kill switch. Disabling a kill switch makes a
+  // deployment safer, so it accepts 0/false/off/no. Disabling THIS makes a
+  // deployment riskier, so a stray "false" must keep the cap wall standing
+  // rather than silently removing it. Do not route this through envEnabled.
   const capsOn = String(env("ORACLE_VALUE_CAPS_ENABLED", "MAD_VALUE_CAPS_ENABLED", "1")).trim() !== "0";
   if (!capsOn) return true;
 

package/src/index.mjs

@@ -67,3 +67,27 @@ export {
   DEFAULT_SCOPES,
   normalizeScopes,
 } from "./scopes.mjs";
+
+export { emitHarnessConfigs, createHarnessConfigs } from "./onboarding/harness-configs.mjs";
+export {
+  ACTION_RECEIPT_VERSION,
+  ActionReceiptSecretError,
+  assertNoReceiptSecrets,
+  canonicalReceiptJson,
+  computeReceiptId,
+  normalizeActionReceipt,
+  createActionReceipt,
+  summarizeActionReceipt,
+  formatActionReceipt,
+} from "./action-receipts.mjs";
+export { DEFAULT_RISK_THRESHOLDS, summarizePortfolioRisk, portfolioRiskSummary } from "./portfolio-risk.mjs";
+export {
+  WATCH_CATEGORIES,
+  defaultPreferences,
+  subscribe,
+  unsubscribe,
+  createWatch,
+  evaluateAlert,
+  shouldDeliverAlert,
+} from "./watch-preferences.mjs";
+export { SIGNAL_TYPES, scoreSignals, createSignalsEngine } from "./signals/index.mjs";

package/src/onboarding/harness-configs.mjs

@@ -0,0 +1,102 @@
+const PACKAGE = "@oracle-agent/oracle";
+const COMMAND = "npx";
+const ARGS = ["-y", "--package", PACKAGE, "oracle-data-mcp"];
+const FORBIDDEN_NAME = /(?:^|_)(?:PRIVATE_KEY|SECRET|TOKEN|PASSWORD|PASSPHRASE|MNEMONIC|SEED)(?:_|$)/i;
+
+function requiredText(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`);
+  if (/\r|\n|\0/.test(value)) throw new TypeError(`${name} must be a single-line string`);
+  return value.trim();
+}
+
+function validateUrl(value) {
+  const text = requiredText(value, "url");
+  let parsed;
+  try { parsed = new URL(text); } catch { throw new TypeError("url must be a valid http(s) URL"); }
+  if (!/^https?:$/.test(parsed.protocol) || parsed.username || parsed.password) {
+    throw new TypeError("url must be a credential-free http(s) URL");
+  }
+  for (const name of parsed.searchParams.keys()) {
+    if (FORBIDDEN_NAME.test(name) || /^(?:key|api[_-]?key|auth)$/i.test(name)) {
+      throw new TypeError(`url must not contain secret-shaped query parameter: ${name}`);
+    }
+  }
+  return parsed.href;
+}
+
+function validateKey(value) {
+  const text = requiredText(value, "key");
+  if (/^[A-Z][A-Z0-9_]*\s*=/.test(text) || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(text)) {
+    throw new TypeError("key must be an Oracle agent key, not an environment assignment or private key");
+  }
+  if (/^(?:0x)?[0-9a-f]{64}$/i.test(text) || text.trim().split(/\s+/).length >= 12) {
+    throw new TypeError("key looks like private signing material");
+  }
+  return text;
+}
+
+function validateLabel(value) {
+  const label = requiredText(value, "label");
+  if (!/^[a-z0-9][a-z0-9_-]{0,62}$/i.test(label)) {
+    throw new TypeError("label must contain only letters, digits, underscores, and hyphens");
+  }
+  if (FORBIDDEN_NAME.test(label)) throw new TypeError("label must not be a secret-shaped environment name");
+  return label;
+}
+
+function json(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function yamlString(value) {
+  return JSON.stringify(value);
+}
+
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+
+/**
+ * Return deterministic, copy-pasteable MCP configuration snippets.
+ * This function performs no I/O and never reads from process.env.
+ */
+export function emitHarnessConfigs({ url, key, label = "oracle-data" } = {}) {
+  const endpoint = validateUrl(url);
+  const agentKey = validateKey(key);
+  const name = validateLabel(label);
+  const server = {
+    command: COMMAND,
+    args: [...ARGS],
+    env: { ORACLE_DATA_URL: endpoint, ORACLE_AGENT_KEY: agentKey },
+  };
+  const mcp = { mcpServers: { [name]: server } };
+
+  return {
+    hermes: [
+      "mcp_servers:",
+      `  ${name}:`,
+      `    command: ${yamlString(COMMAND)}`,
+      "    args:",
+      ...ARGS.map((arg) => `      - ${yamlString(arg)}`),
+      "    env:",
+      `      ORACLE_DATA_URL: ${yamlString(endpoint)}`,
+      `      ORACLE_AGENT_KEY: ${yamlString(agentKey)}`,
+      "",
+    ].join("\n"),
+    claudeCode: json(mcp),
+    codex: [
+      `[mcp_servers.${tomlString(name)}]`,
+      `command = ${tomlString(COMMAND)}`,
+      `args = [${ARGS.map(tomlString).join(", ")}]`,
+      "",
+      `[mcp_servers.${tomlString(name)}.env]`,
+      `ORACLE_DATA_URL = ${tomlString(endpoint)}`,
+      `ORACLE_AGENT_KEY = ${tomlString(agentKey)}`,
+      "",
+    ].join("\n"),
+    cursor: json(mcp),
+    genericMcp: json(mcp),
+  };
+}
+
+export const createHarnessConfigs = emitHarnessConfigs;

package/src/oracle-env.mjs

@@ -20,9 +20,18 @@ export function envFlag(primary, legacy, defaultValue = false) {
   return String(env(primary, legacy, fallback)).trim() === "1";
 }
 
+const DISABLE_WORDS = ["0", "false", "off", "no"];
+
+// Reading a flag that may default ON. Only an explicit disable word turns it
+// off, and an unset value keeps `defaultValue`.
+//
+// The old shape (`!== "0"`) inverted with a false default: ORACLE_ONBOARD_HTTP
+// defaults off, so a user writing `false` to keep it off actually ENABLED it,
+// because "false" is not "0". A disable word must never enable a surface.
 export function envEnabled(primary, legacy, defaultValue = true) {
-  const fallback = defaultValue ? "1" : "0";
-  return String(env(primary, legacy, fallback)).trim() !== "0";
+  const raw = String(env(primary, legacy, "")).trim().toLowerCase();
+  if (raw === "") return defaultValue;
+  return !DISABLE_WORDS.includes(raw);
 }
 
 export function csvEnv(primary, legacy) {