@oracle-agent/oracle 0.1.0

package/src/exec-policy.mjs

@@ -0,0 +1,444 @@
+// Transaction policy layer — enforced INSIDE the exec-server before any sign or
+// broadcast, so token possession alone (stolen from /proc, a peer agent process,
+// an injected subagent, or a tailnet peer) cannot produce an arbitrary drain.
+// This is the belt that bounds the blast radius of every gate/token bypass.
+//
+// All limits are config via exec.env (loaded into the exec-server env):
+//   MAD_ALLOWED_CHAINS      csv chainIds (default: the registered set)
+//   MAD_MAX_TX_VALUE_WEI    max native value per tx (default: 0.05 ETH-scale)
+//   MAD_MAX_DAILY_VALUE_WEI max native value per rolling 24h (default: 0.15)
+//   MAD_MAX_GAS_LIMIT       max gasLimit per signed/broadcast tx (default: 5m)
+//   MAD_MAX_TX_FEE_WEI      max gasLimit*feePerGas when fee fields are present
+//   MAD_DEST_ALLOWLIST      csv lowercased addresses; empty = any dest allowed
+//   MAD_POLICY_STATE        path to the daily-spend ledger (default alongside env)
+//
+// Native-value caps bound native drains. The destination allowlist (when set)
+// is the strong control for arbitrary-contract/ERC20 drains — enable it with the
+// venues you actually trade through for a hard bound.
+
+import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync, rmdirSync, statSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isSwapVenue, venuesFor } from "./venues.mjs";
+import { csvEnv, env, configPath } from "./oracle-env.mjs";
+import { assertAutoSlippageGuard } from "./auto-slippage.mjs";
+import { assertApprovalGuard, isApprovalCall } from "./approval-guard.mjs";
+import { assertTokenTransferGuard, isTokenTransferCall } from "./token-transfer-guard.mjs";
+import { assertRouteAttestation } from "./route-attestation.mjs";
+import { assertVaultAttestation } from "./vault-attestation.mjs";
+import { assertGmxOrderAttestation, isGmxExchangeRouter } from "./gmx-attestation.mjs";
+
+const DEFAULT_CHAINS = [1, 8453, 42161, 137, 10, 56, 43114, 999, 4663, 2741, 988];
+
+function csvSet(primary, legacy) {
+  return new Set(
+    csvEnv(primary, legacy)
+      .split(",")
+      .map((s) => s.trim().toLowerCase())
+      .filter(Boolean)
+  );
+}
+
+function allowedChains() {
+  const raw = String(env("ORACLE_ALLOWED_CHAINS", "MAD_ALLOWED_CHAINS", "")).trim();
+  if (!raw) return new Set(DEFAULT_CHAINS.map(Number));
+  return new Set(raw.split(",").map((s) => Number(s.trim())).filter(Number.isFinite));
+}
+
+function bigEnv(primary, legacy, fallback) {
+  const v = String(env(primary, legacy, "")).trim();
+  try {
+    return v ? BigInt(v) : BigInt(fallback);
+  } catch {
+    return BigInt(fallback);
+  }
+}
+
+// 0.05 / 0.15 in 1e18 units — generous but bounds a catastrophic drain. Tune in exec.env.
+function maxTxValue() {
+  return bigEnv("ORACLE_MAX_TX_VALUE_WEI", "MAD_MAX_TX_VALUE_WEI", "50000000000000000");
+}
+function maxDailyValue() {
+  return bigEnv("ORACLE_MAX_DAILY_VALUE_WEI", "MAD_MAX_DAILY_VALUE_WEI", "150000000000000000");
+}
+function maxGasLimit() {
+  return bigEnv("ORACLE_MAX_GAS_LIMIT", "MAD_MAX_GAS_LIMIT", "5000000");
+}
+function maxTxFeeWei() {
+  return bigEnv("ORACLE_MAX_TX_FEE_WEI", "MAD_MAX_TX_FEE_WEI", "5000000000000000");
+}
+
+function statePath() {
+  return configPath("policy-daily.json", "ORACLE_POLICY_STATE", "MAD_POLICY_STATE");
+}
+
+function toWei(v) {
+  if (v == null) return 0n;
+  // A value this function cannot parse must NOT be treated as zero. Returning
+  // 0n on failure made every native-value cap fail OPEN: a tx carrying
+  // "999999999999999999999999.5" was scored as value=0 and sailed past the
+  // per-tx and daily ceilings. An unparseable amount is a policy error.
+  if (typeof v === "number") {
+    if (!Number.isInteger(v) || !Number.isSafeInteger(v)) {
+      throw new Error(
+        `exec-policy: value ${v} is not an exact integer — pass wei as a decimal string or BigInt`
+      );
+    }
+  }
+  try {
+    if (typeof v === "string" && v.startsWith("0x")) return BigInt(v);
+    return BigInt(v);
+  } catch {
+    throw new Error(`exec-policy: cannot interpret ${JSON.stringify(String(v))} as an integer wei amount`);
+  }
+}
+
+function optionalBig(value, label) {
+  if (value == null || value === "") return null;
+  try {
+    const n = typeof value === "string" && value.startsWith("0x") ? BigInt(value) : BigInt(value);
+    if (n < 0n) throw new Error("negative");
+    return n;
+  } catch {
+    throw new Error(`policy: ${label} must be a non-negative integer`);
+  }
+}
+
+function enforceGasPolicy(tx = {}) {
+  const gasLimit = optionalBig(tx.gasLimit ?? tx.gas, "gasLimit");
+  if (gasLimit != null) {
+    const cap = maxGasLimit();
+    if (gasLimit > cap) {
+      throw new Error(`policy: gasLimit ${gasLimit} exceeds cap ${cap} (ORACLE_MAX_GAS_LIMIT)`);
+    }
+  }
+
+  const feePerGas = optionalBig(tx.maxFeePerGas ?? tx.gasPrice, "maxFeePerGas/gasPrice");
+  if (gasLimit != null && feePerGas != null) {
+    const maxFee = gasLimit * feePerGas;
+    const cap = maxTxFeeWei();
+    if (maxFee > cap) {
+      throw new Error(`policy: gas fee ceiling ${maxFee} exceeds max tx fee ${cap} (ORACLE_MAX_TX_FEE_WEI)`);
+    }
+  }
+}
+
+let ledgerDegraded = false;
+
+function readDaily() {
+  const fresh = () => ({ windowStart: Date.now(), spentWei: "0" });
+  let onDisk;
+  try {
+    onDisk = JSON.parse(readFileSync(statePath(), "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return fresh();
+    ledgerDegraded = true;
+    throw new Error(`policy: daily spend ledger cannot be read or is corrupt: ${error?.message || error}`);
+  }
+  const windowStart = Number(onDisk?.windowStart);
+  let spentWei;
+  try {
+    spentWei = BigInt(onDisk?.spentWei);
+  } catch {
+    ledgerDegraded = true;
+    throw new Error("policy: daily spend ledger is corrupt: invalid spentWei");
+  }
+  if (!Number.isFinite(windowStart) || windowStart <= 0 || spentWei < 0n) {
+    ledgerDegraded = true;
+    throw new Error("policy: daily spend ledger is corrupt: invalid window");
+  }
+  if (Date.now() - windowStart > 24 * 60 * 60 * 1000) return fresh();
+  ledgerDegraded = false;
+  return { windowStart, spentWei: spentWei.toString() };
+}
+
+function writeDaily(d) {
+  const target = statePath();
+  const temp = `${target}.${process.pid}.tmp`;
+  try {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(temp, JSON.stringify(d), { mode: 0o600 });
+    renameSync(temp, target);
+    ledgerDegraded = false;
+  } catch (err) {
+    ledgerDegraded = true;
+    try { unlinkSync(temp); } catch {}
+    throw new Error(`policy: daily spend ledger cannot be written or persisted: ${err?.message || err}`);
+  }
+}
+
+function withDailyLedgerLock(fn) {
+  const target = statePath();
+  const lock = `${target}.lock`;
+  const ownerPath = join(lock, "owner.json");
+  const ttlMs = ledgerLockTtlMs();
+
+  function writeOwner() {
+    writeFileSync(
+      ownerPath,
+      JSON.stringify({ pid: process.pid, createdAtMs: Date.now() }),
+      { mode: 0o600 },
+    );
+  }
+
+  function readOwner() {
+    try {
+      return JSON.parse(readFileSync(ownerPath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  function lockAgeMs() {
+    try {
+      return Date.now() - Number(statSync(lock).mtimeMs);
+    } catch {
+      return Number.POSITIVE_INFINITY;
+    }
+  }
+
+  function pidAlive(pid) {
+    const n = Number(pid);
+    if (!Number.isInteger(n) || n <= 0) return false;
+    try {
+      process.kill(n, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function removeLockTree() {
+    try {
+      rmSync(lock, { recursive: true, force: true });
+    } catch {
+      try { unlinkSync(ownerPath); } catch {}
+      try { rmdirSync(lock); } catch {}
+    }
+  }
+
+  function tryAcquire() {
+    mkdirSync(dirname(target), { recursive: true });
+    mkdirSync(lock, { mode: 0o700 });
+    writeOwner();
+  }
+
+  try {
+    tryAcquire();
+  } catch (error) {
+    if (error?.code !== "EEXIST") {
+      throw new Error(`policy: daily spend ledger lock cannot be acquired: ${error?.message || error}`);
+    }
+    const owner = readOwner();
+    const age = lockAgeMs();
+    const stale =
+      age > ttlMs ||
+      !owner ||
+      !pidAlive(owner.pid);
+    if (!stale) {
+      throw new Error(`policy: daily spend ledger lock is busy at ${lock}`);
+    }
+    removeLockTree();
+    try {
+      tryAcquire();
+    } catch (retryError) {
+      if (retryError?.code === "EEXIST") {
+        throw new Error(`policy: daily spend ledger lock is busy at ${lock}`);
+      }
+      throw new Error(`policy: daily spend ledger lock cannot be acquired: ${retryError?.message || retryError}`);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    try {
+      removeLockTree();
+    } catch (error) {
+      ledgerDegraded = true;
+      throw new Error(`policy: daily spend ledger lock cannot be released: ${error?.message || error}`);
+    }
+  }
+}
+
+function ledgerLockTtlMs() {
+  const raw = Number(process.env.ORACLE_LEDGER_LOCK_TTL_MS || process.env.MAD_LEDGER_LOCK_TTL_MS || 30_000);
+  if (!Number.isFinite(raw) || raw < 1_000) return 30_000;
+  return Math.min(Math.floor(raw), 300_000);
+}
+
+/** True when the on-disk ledger could not be persisted this run. */
+export function dailyLedgerDegraded() {
+  return ledgerDegraded;
+}
+
+/**
+ * When the durable ledger cannot be committed, the daily cap survives only as
+ * long as this process. A restart silently resets it to a fresh zero-spend
+ * window — so "degraded" is a cap that an attacker (or a crash loop) can clear
+ * on demand. Default to REFUSING to sign in that state; an operator who
+ * genuinely wants memory-only accounting must say so explicitly.
+ */
+function assertLedgerDurable(phase) {
+  if (!ledgerDegraded) return;
+  if (String(process.env.ORACLE_ALLOW_EPHEMERAL_CAPS || "") === "1") return;
+  throw new Error(
+    `policy: refusing to ${phase} — the daily spend ledger at ${statePath()} is not writable, ` +
+      `so the daily cap would reset on restart. Fix the path, or set ` +
+      `ORACLE_ALLOW_EPHEMERAL_CAPS=1 to accept memory-only caps.`
+  );
+}
+
+/**
+ * Enforce policy on a would-be sign/broadcast. Throws on violation.
+ * @param {object} tx  { chainId, to, value, data }
+ * @param {"sign"|"broadcast"} phase
+ */
+export function enforceTxPolicy(tx = {}, phase = "broadcast") {
+  assertLedgerDurable(phase);
+  const chainId = Number(tx.chainId);
+  if (!allowedChains().has(chainId)) {
+    throw new Error(`policy: chainId ${chainId} not in ORACLE_ALLOWED_CHAINS`);
+  }
+
+  // Effective destination allowlist = env global allowlist UNION this chain's
+  // vetted venues (venues.mjs). Venues come from a curated, code-reviewed map,
+  // never from the tx itself -- so a new chain "just works" once its venues are
+  // added, without ever auto-trusting an arbitrary destination. If BOTH sources
+  // are empty, no dest restriction applies (env-empty semantics preserved).
+  const to = String(tx.to || "").toLowerCase();
+  const data = String(tx.data || "0x").toLowerCase();
+  const approvalLike = data !== "0x" && isApprovalCall(data);
+
+  // Native tx.value caps are not enough: a malicious signed transaction can try
+  // to drain through oversized gasLimit / fee fields even with value=0.
+  enforceGasPolicy(tx);
+
+  // ERC-20 approvals are value=0 calls to the token contract, not the swap
+  // router. They cannot be authorized by the token destination alone. Require a
+  // bounded approval guard that binds exact token/spender/amount/chain/expiry,
+  // and require the spender/route venue to be in the reviewed venue registry.
+  if (approvalLike) {
+    assertApprovalGuard(tx.madApproval || tx.approvalGuard, { ...tx, chainId, to, data }, { chainId });
+  }
+
+  // ERC-20 transfers are the other value=0 drain path. Native caps never see
+  // them, and a token address in the venue registry is not consent to send its
+  // balance anywhere. Bind the exact recipient + amount at the final policy gate.
+  if (!approvalLike && data !== "0x" && isTokenTransferCall(data)) {
+    assertTokenTransferGuard(tx.madTokenTransfer || tx.tokenTransferGuard, { ...tx, chainId, to, data }, { chainId });
+  }
+
+  // GMX v2 ExchangeRouter orders are asynchronous, keeper-executed intents. The
+  // ExchangeRouter is a vetted destination, but raw multicall calldata there can
+  // create/cancel/update orders with account risk. Require a signer-bound order
+  // attestation that binds the exact multicall hash, account, collateral,
+  // acceptable price, size, execution fee, and chain before signing.
+  if (!approvalLike && to && isGmxExchangeRouter(chainId, to)) {
+    assertGmxOrderAttestation(tx.madGmx || tx.gmxGuard, { ...tx, chainId, to, data }, { chainId });
+  }
+
+  const destAllow = csvSet("ORACLE_DEST_ALLOWLIST", "MAD_DEST_ALLOWLIST");
+  for (const v of venuesFor(chainId)) destAllow.add(v);
+
+  // Contract CREATION (no `to`) has no destination to check, so it fell through
+  // the allowlist entirely — the one shape that skips the strongest control we
+  // have. A deploy can carry native value and, once mined, the resulting
+  // contract is an arbitrary destination that was never reviewed. /exec/prepare
+  // rejects a missing `to`, but /exec/sign and /exec/broadcast accept a raw tx
+  // object, so prepare's check is not a real boundary.
+  //
+  // Deploys are therefore opt-in: ORACLE_ALLOW_CREATE=1 (or MAD_ALLOW_CREATE=1),
+  // and even when allowed they may not carry native value.
+  const isCreate = !tx.to || String(tx.to).trim() === "";
+  if (isCreate) {
+    const createAllowed =
+      String(env("ORACLE_ALLOW_CREATE", "MAD_ALLOW_CREATE", "0")).trim() === "1";
+    if (!createAllowed) {
+      throw new Error(
+        "policy: contract creation (tx without `to`) is disabled — set ORACLE_ALLOW_CREATE=1 to permit deploys"
+      );
+    }
+    if (toWei(tx.value) > 0n) {
+      throw new Error("policy: contract creation may not carry native value");
+    }
+  }
+
+  // Fail CLOSED. README and SECURITY both state that an empty allowlist refuses
+  // everything; the previous "no dest restriction applies" branch made an
+  // unconfigured deployment maximally permissive at exactly the moment the
+  // operator had configured the least. A destination must be positively
+  // allowlisted, or carry a route/vault attestation.
+  //
+  // Approvals used to skip this check (`!approvalLike`). That meant any
+  // unreviewed contract whose calldata started with an allowance selector
+  // bypassed the strongest control in the file — assertApprovalGuard binds the
+  // spender, not the `to` address. The token being approved is a destination
+  // like any other: it must be allowlisted or carry a route/vault attestation.
+  if (to && !destAllow.has(to)) {
+    const madRoute = tx.madRoute || tx.routeAttestation;
+    const madVault = tx.madVault || tx.vaultGuard;
+    if (!madRoute && !madVault) {
+      if (destAllow.size === 0) {
+        throw new Error(
+          `policy: no destination allowlist configured for chain ${chainId} — set ORACLE_DEST_ALLOWLIST or add the chain's venues before sending`
+        );
+      }
+      throw new Error(`policy: destination ${to} not allowlisted for chain ${chainId} (env ORACLE_DEST_ALLOWLIST or venues.mjs)`);
+    }
+    if (madRoute) assertRouteAttestation(madRoute, { ...tx, chainId, to, data }, { chainId });
+    else assertVaultAttestation(madVault, { ...tx, chainId, to, data }, { chainId });
+  }
+
+  // Every market-sensitive contract call must prove that its output floor came
+  // from a fresh automatic quote and is bounded to <= 100 bps. This check runs
+  // at both sign and broadcast, so raw prepared calldata cannot bypass it.
+  if (to && data !== "0x" && isSwapVenue(chainId, to)) {
+    try {
+      // Bind the guard to THIS calldata, not just to the venue. Without the tx
+      // the guard only proved internal consistency, so one correctly signed
+      // guard from a trivial quote authorized a swap of any size with zero
+      // output protection at the same venue.
+      assertAutoSlippageGuard(tx.slippageGuard ?? tx.madSlippage, {
+        chainId,
+        venue: to,
+        tx: { ...tx, chainId, to, data },
+        requireSigned: true,
+      });
+    } catch (error) {
+      const message = String(error?.message || error);
+      if (/required/.test(message)) throw error;
+      throw new Error(`policy: ${message}`);
+    }
+  }
+
+  // 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.
+  const capsOn = String(env("ORACLE_VALUE_CAPS_ENABLED", "MAD_VALUE_CAPS_ENABLED", "1")).trim() !== "0";
+  if (!capsOn) return true;
+
+  const value = toWei(tx.value);
+  const perTx = maxTxValue();
+  if (value > perTx) {
+    throw new Error(
+      `policy: tx value ${value} exceeds per-tx cap ${perTx} (ORACLE_MAX_TX_VALUE_WEI)`
+    );
+  }
+
+  // Daily aggregate only meaningfully applies to actual broadcast.
+  if (phase === "broadcast" && value > 0n) {
+    withDailyLedgerLock(() => {
+      const daily = readDaily();
+      const spent = toWei(daily.spentWei);
+      const cap = maxDailyValue();
+      if (spent + value > cap) {
+        throw new Error(
+          `policy: daily native spend ${spent + value} would exceed cap ${cap} (ORACLE_MAX_DAILY_VALUE_WEI)`
+        );
+      }
+      writeDaily({ windowStart: daily.windowStart, spentWei: (spent + value).toString() });
+    });
+  }
+
+  return true;
+}

package/src/flags.mjs

@@ -0,0 +1,15 @@
+/** Global kill-switch shared by sign adapters + local signer. */
+import { envFlag } from "./oracle-env.mjs";
+
+export function executeGloballyEnabled() {
+  return envFlag("ORACLE_EXECUTE_ENABLED", "MAD_EXECUTE_ENABLED", false);
+}
+
+/**
+ * Separate kill-switch for the BUILD verb (deploying new contracts through
+ * allowlisted factories). Deliberately NOT the same flag as execute: arming
+ * trading must never silently arm contract creation. Off by default.
+ */
+export function deployGloballyEnabled() {
+  return envFlag("ORACLE_DEPLOY_ENABLED", "MAD_DEPLOY_ENABLED", false);
+}

package/src/fresh-window.mjs

@@ -0,0 +1,76 @@
+// One shared freshness check for every time-bounded authorization.
+//
+// This defect class has now been found FIVE separate times by four different
+// auditors, in five different files: token-transfer-guard, auto-slippage,
+// approval-guard, session grants, and the attestation modules. The shape is
+// always the same — `Number(nowMs) > Number(expiresAtMs)` is false when nowMs
+// is NaN, null, a non-numeric string, or -Infinity, so a broken or attacker-
+// influenced clock silently converts a short-lived authorization into a
+// permanent one.
+//
+// Fixing it once per file guarantees the sixth file will have it too. So it
+// lives here, and every guard calls this.
+
+/**
+ * Assert a time-bounded window is present, coherent, and currently open.
+ * Fails CLOSED on any unusable clock or missing bound.
+ *
+ * @param {object} window            { issuedAtMs, expiresAtMs }
+ * @param {number} nowMs             current time
+ * @param {string} label             prefix for error messages
+ */
+export function assertFreshWindow(window, nowMs, label = "guard") {
+  const now = Number(nowMs);
+  // `null` deserves special mention: it slips past a `= Date.now()` default
+  // because it is a *supplied* value, and Number(null) === 0 — which makes
+  // every expiry comparison pass.
+  if (nowMs == null || !Number.isFinite(now)) {
+    throw new Error(`${label}: current time must be a finite number (got ${describe(nowMs)})`);
+  }
+
+  const issuedAtMs = Number(window?.issuedAtMs);
+  const expiresAtMs = Number(window?.expiresAtMs);
+  if (!Number.isFinite(expiresAtMs)) {
+    throw new Error(`${label}: expiresAtMs is required and must be a finite number`);
+  }
+  // Expiry is checked BEFORE coherence: an already-expired window is the more
+  // useful thing to report, and a test (or caller) that hand-builds an expired
+  // window by pulling expiresAtMs back past issuedAtMs still gets "expired"
+  // rather than a shape complaint.
+  if (now > expiresAtMs) {
+    throw new Error(`${label} expired at ${expiresAtMs}, now ${now}`);
+  }
+  if (window?.issuedAtMs != null) {
+    if (!Number.isFinite(issuedAtMs)) {
+      throw new Error(`${label}: issuedAtMs must be a finite number when present`);
+    }
+    if (expiresAtMs <= issuedAtMs) {
+      throw new Error(`${label}: expiry must be after issuance`);
+    }
+  }
+  return { now, issuedAtMs, expiresAtMs };
+}
+
+/**
+ * Non-throwing form for status reporting. Returns false when the clock is
+ * unusable, so a caller asking "is this still live?" gets NO rather than a
+ * confident yes derived from a broken clock.
+ */
+export function isWindowOpen(window, nowMs, { inclusive = false } = {}) {
+  try {
+    const { now, expiresAtMs } = assertFreshWindow(window, nowMs);
+    // `inclusive` treats the expiry instant itself as closed, which is what
+    // session grants mean by "expired at/after expiresAtMs".
+    if (inclusive && now >= expiresAtMs) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function describe(v) {
+  if (v === null) return "null";
+  if (v === undefined) return "undefined";
+  if (typeof v === "number") return String(v);
+  return `${typeof v} ${JSON.stringify(String(v)).slice(0, 24)}`;
+}