@oracle-agent/oracle 0.11.0 → 0.13.0

package/src/approval-guard.mjs

@@ -1,282 +0,0 @@
-import { Interface, MaxUint256, isAddress, keccak256, toUtf8Bytes } from "ethers";
-import { venuesFor } from "./venues.mjs";
-import { assertVaultApprovalAttestation } from "./vault-attestation.mjs";
-import { assertGmxApprovalAttestation } from "./gmx-attestation.mjs";
-import { exactBigInt } from "./exact-integer.mjs";
-import { assertFreshWindow } from "./fresh-window.mjs";
-
-const DEFAULT_APPROVAL_TTL_MS = 20_000;
-
-const ERC20 = new Interface(["function approve(address spender,uint256 amount) returns (bool)"]);
-
-function normalAddress(value, label) {
-  const text = String(value || "").trim();
-  if (!isAddress(text)) throw new Error(`${label} must be an address`);
-  return text.toLowerCase();
-}
-
-function amountString(value, label = "approval amount", { allowZero = false } = {}) {
-  // Unsafe JS numbers round UP above 2^53, which would widen the allowance past
-  // what the caller wrote. Same class already fixed for ERC-20 transfers.
-  const amount = exactBigInt(value, label);
-  if (allowZero ? amount < 0n : amount <= 0n) throw new Error(`${label} must be positive`);
-  if (amount >= MaxUint256) throw new Error("unlimited approvals are refused; use an exact bounded amount");
-  return amount.toString();
-}
-
-function canonicalJson(value) {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  if (value && typeof value === "object") {
-    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-/**
- * Selectors that grant or increase an allowance.
- *
- * Gating only on `approve()` meant every other allowance-granting entrypoint
- * skipped the guard entirely: `increaseAllowance` raises the same allowance,
- * SafeERC20's `forceApprove`/`safeApprove` set one on the caller's behalf,
- * Permit2's `approve`/`permit` grant spend rights, and DAI-style `permit` sets
- * an allowance from a signature. A guard that covers one selector is a guard
- * an attacker routes around.
- *
- * Every value here was computed from its signature with keccak256, not copied
- * from memory — an incorrect selector in this list is a silent hole.
- */
-const ALLOWANCE_SELECTORS = new Set([
-  "0x095ea7b3", // approve(address,uint256)
-  "0x39509351", // increaseAllowance(address,uint256)
-  "0x61f49ed6", // forceApprove(address,address,uint256)          [SafeERC20]
-  "0xeb5625d9", // safeApprove(address,address,uint256)           [SafeERC20]
-  "0xf9255c1f", // safeIncreaseAllowance(address,address,uint256) [SafeERC20]
-  "0x87517c45", // approve(address,address,uint160,uint48)        [Permit2]
-  "0xd505accf", // permit(address,address,uint256,uint256,uint8,bytes32,bytes32)      [EIP-2612]
-  "0x8fcbaf0c", // permit(address,address,uint256,uint256,bool,uint8,bytes32,bytes32) [DAI]
-  "0x2b67b570", // permit(address,PermitSingle,bytes)             [Permit2]
-  "0x2a2d80d1", // permitBatch                                    [Permit2]
-]);
-
-export function isApprovalCall(data) {
-  const hex = String(data || "").toLowerCase();
-  if (hex.length < 10) return false;
-  return ALLOWANCE_SELECTORS.has(hex.slice(0, 10));
-}
-
-export { ALLOWANCE_SELECTORS };
-
-export function decodeApproveCalldata(data) {
-  if (!isApprovalCall(data)) throw new Error("approval calldata required");
-  const hex = String(data || "").toLowerCase();
-  const selector = hex.slice(0, 10);
-  const words = hex.slice(10).match(/.{1,64}/g) || [];
-  const wordAddr = (i) => (words[i] ? "0x" + words[i].slice(24) : null);
-  const wordBig = (i) => (words[i] ? BigInt("0x" + words[i]) : null);
-
-  // Each allowance-granting shape puts (spender, amount) in different slots.
-  // Detecting a selector without being able to decode it made every non-approve
-  // allowance call unsignable — the guard recognised the tx, demanded a bound
-  // guard, then threw "invalid approve calldata" because it only knew how to
-  // read approve(). Recognition and decoding must cover the same set.
-  let spenderRaw = null;
-  let amountRaw = null;
-
-  switch (selector) {
-    // approve(address spender, uint256 value)
-    // increaseAllowance(address spender, uint256 addedValue)
-    case "0x095ea7b3":
-    case "0x39509351":
-      spenderRaw = wordAddr(0);
-      amountRaw = wordBig(1);
-      break;
-    // SafeERC20 helpers: (IERC20 token, address spender, uint256 value)
-    case "0x61f49ed6": // forceApprove
-    case "0xeb5625d9": // safeApprove
-    case "0xf9255c1f": // safeIncreaseAllowance
-      spenderRaw = wordAddr(1);
-      amountRaw = wordBig(2);
-      break;
-    // EIP-2612 permit(owner, spender, value, deadline, v, r, s)
-    case "0xd505accf":
-      spenderRaw = wordAddr(1);
-      amountRaw = wordBig(2);
-      break;
-    // DAI permit(holder, spender, nonce, expiry, allowed, v, r, s) — `allowed`
-    // is a boolean, so an unlimited allowance is expressed as true.
-    case "0x8fcbaf0c": {
-      spenderRaw = wordAddr(1);
-      const allowed = wordBig(4);
-      amountRaw = allowed === 0n ? 0n : (1n << 256n) - 1n;
-      break;
-    }
-    // Permit2 approve(token, spender, uint160 amount, uint48 expiration)
-    case "0x87517c45":
-      spenderRaw = wordAddr(1);
-      amountRaw = wordBig(2);
-      break;
-    default:
-      // A selector we recognise but cannot decode must FAIL, not silently pass:
-      // an undecodable allowance cannot be bounded.
-      throw new Error(`approval selector ${selector} is recognised but not decodable; refusing to bound it`);
-  }
-
-  if (spenderRaw == null || amountRaw == null) throw new Error("invalid approve calldata");
-  return {
-    spender: normalAddress(spenderRaw, "approval spender"),
-    amount: amountString(amountRaw, "approval amount", { allowZero: true }),
-    selector,
-  };
-}
-
-export function normalizeApprovalRequests(value) {
-  if (!value) return [];
-  const raw = Array.isArray(value) ? value : [value];
-  return raw
-    .filter(Boolean)
-    .map((approval) => ({
-      token: normalAddress(approval.token, "approval token"),
-      spender: normalAddress(approval.spender, "approval spender"),
-      amount: amountString(approval.amount, "approval amount"),
-    }));
-}
-
-export function createApprovalGuard({
-  chainId,
-  token,
-  spender,
-  amount,
-  provider,
-  routeVenue,
-  routeGuard,
-  purpose,
-  nowMs = Date.now(),
-  ttlMs = DEFAULT_APPROVAL_TTL_MS,
-} = {}) {
-  const approvalPurpose = String(purpose || "").trim();
-  const guard = {
-    mode: "approval",
-    chainId: Number(chainId),
-    token: normalAddress(token, "approval token"),
-    spender: normalAddress(spender, "approval spender"),
-    amount: amountString(amount, "approval amount", { allowZero: approvalPurpose === "revoke" }),
-    provider: String(provider || "").trim() || "unknown",
-    routeVenue: routeVenue ? normalAddress(routeVenue, "approval route venue") : normalAddress(spender, "approval route venue"),
-    issuedAtMs: Number(nowMs),
-    expiresAtMs: Number(nowMs) + Number(ttlMs || DEFAULT_APPROVAL_TTL_MS),
-  };
-  if (approvalPurpose) guard.purpose = approvalPurpose;
-  if (!Number.isFinite(guard.chainId)) throw new Error("approval chainId required");
-  if (!Number.isFinite(guard.issuedAtMs) || !Number.isFinite(guard.expiresAtMs) || guard.expiresAtMs <= guard.issuedAtMs) {
-    throw new Error("approval guard expiry invalid");
-  }
-  if (routeGuard) {
-    guard.routeGuardHash = keccak256(toUtf8Bytes(canonicalJson(routeGuard)));
-  }
-  return guard;
-}
-
-export function buildApprovalTransaction(approval, {
-  chainId,
-  provider,
-  routeTransaction,
-  routeGuard,
-  nowMs = Date.now(),
-  ttlMs = DEFAULT_APPROVAL_TTL_MS,
-} = {}) {
-  const [req] = normalizeApprovalRequests(approval);
-  if (!req) throw new Error("approval request required");
-  const madApproval = createApprovalGuard({
-    chainId,
-    token: req.token,
-    spender: req.spender,
-    amount: req.amount,
-    provider,
-    routeVenue: routeTransaction?.to || req.spender,
-    routeGuard,
-    nowMs,
-    ttlMs,
-  });
-  return {
-    chainId: Number(chainId),
-    to: req.token,
-    data: ERC20.encodeFunctionData("approve", [req.spender, req.amount]),
-    value: "0x0",
-    madApproval,
-  };
-}
-
-export function buildApprovalRevokeTransaction(approval, {
-  chainId,
-  provider,
-  nowMs = Date.now(),
-  ttlMs = DEFAULT_APPROVAL_TTL_MS,
-} = {}) {
-  const token = normalAddress(approval?.token, "approval token");
-  const spender = normalAddress(approval?.spender, "approval spender");
-  const madApproval = createApprovalGuard({
-    chainId,
-    token,
-    spender,
-    amount: "0",
-    provider,
-    routeVenue: spender,
-    purpose: "revoke",
-    nowMs,
-    ttlMs,
-  });
-  return {
-    chainId: Number(chainId),
-    to: token,
-    data: ERC20.encodeFunctionData("approve", [spender, "0"]),
-    value: "0x0",
-    madApproval,
-  };
-}
-
-export function assertApprovalGuard(guard, tx = {}, { chainId, nowMs = Date.now() } = {}) {
-  if (!guard || guard.mode !== "approval") throw new Error("approval guard required");
-  const txChainId = Number(tx.chainId ?? chainId);
-  if (Number(guard.chainId) !== txChainId) throw new Error(`approval chain mismatch: expected ${txChainId}, got ${guard.chainId}`);
-  const token = normalAddress(tx.to, "approval token");
-  if (normalAddress(guard.token, "approval token") !== token) throw new Error("approval token mismatch");
-  const decoded = decodeApproveCalldata(tx.data);
-  if (normalAddress(guard.spender, "approval spender") !== decoded.spender) throw new Error("approval spender mismatch");
-  const isRevoke = String(guard.purpose || "") === "revoke";
-  if (decoded.amount === "0" && !isRevoke) throw new Error("zero approval amount requires revoke purpose");
-  if (amountString(guard.amount, "approval amount", { allowZero: isRevoke }) !== decoded.amount) throw new Error("approval amount mismatch");
-  const value = tx.value == null ? 0n : BigInt(String(tx.value).startsWith("0x") ? String(tx.value) : String(tx.value));
-  if (value !== 0n) throw new Error("approval tx value must be zero");
-  // Same clock fail-closed as every other guard. A missing expiresAtMs used to
-  // make Number(undefined) <= now evaluate false, turning a captured approval
-  // into a permanent re-grant. NaN/null/"later" clocks had the same effect.
-  const { now } = assertFreshWindow(guard, nowMs, "approval guard");
-  if (Number(guard.issuedAtMs) > now + 5_000) throw new Error("approval guard issued in the future");
-  const allowedSpenders = venuesFor(txChainId);
-  if (!allowedSpenders.has(decoded.spender)) {
-    if (String(guard.provider || "") === "morpho") {
-      assertVaultApprovalAttestation(tx.madVault || tx.vaultGuard, tx, guard, { chainId: txChainId, nowMs });
-      return {
-        chainId: txChainId,
-        token,
-        spender: decoded.spender,
-        amount: decoded.amount,
-        provider: guard.provider || null,
-      };
-    }
-    throw new Error(`approval spender ${decoded.spender} not allowlisted for chain ${txChainId}`);
-  }
-  if (String(guard.provider || "") === "gmx") {
-    assertGmxApprovalAttestation(tx.madGmx || tx.gmxGuard, tx, guard, { chainId: txChainId, nowMs });
-  }
-  if (guard.routeVenue && !allowedSpenders.has(normalAddress(guard.routeVenue, "approval route venue"))) {
-    throw new Error(`approval route venue ${guard.routeVenue} not allowlisted for chain ${txChainId}`);
-  }
-  return {
-    chainId: txChainId,
-    token,
-    spender: decoded.spender,
-    amount: decoded.amount,
-    provider: guard.provider || null,
-  };
-}

package/src/attestation-secret.mjs

@@ -1,88 +0,0 @@
-// Shared secret resolution for attestation modules.
-//
-// Attestations are minted inside the trusted boundary to bind a dynamic execution
-// target (a route, a vault, a GMX order) so that model-authored JSON cannot become
-// authorization on its own. That makes the secret's LOOKUP path security-relevant:
-// reading it from a wrong or attacker-writable location is as bad as leaking it.
-//
-// Extracted here because three modules had drifted into three near-identical copies,
-// each carrying a hardcoded operator home directory -- which is both a leak of the
-// author's environment and simply broken for anyone else, since a public user has no
-// matching private home path.
-
-import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-/**
- * Candidate env-file locations, in priority order.
- *
- * Resolved from the CURRENT user's home, never a baked-in absolute path.
- */
-function envFileCandidates() {
-  // Under test, do NOT read the developer's real ~/.config secrets. A suite
-  // that silently picks up a secret on the maintainer's box and finds none on a
-  // contributor's machine is not reproducible, and the difference shows up as
-  // mysterious pass/fail drift rather than an honest failure.
-  if (process.env.ORACLE_TEST_ISOLATE_SECRETS === "1") {
-    const explicitOnly = (process.env.ORACLE_EXEC_ENV_FILE || "").trim();
-    return explicitOnly ? [explicitOnly] : [];
-  }
-
-  const explicit = (
-    process.env.ORACLE_EXEC_ENV_FILE ||
-    process.env.MAD_EXEC_ENV_FILE || // legacy name, kept for existing deployments
-    ""
-  ).trim();
-
-  const home = homedir();
-  return [
-    explicit,
-    join(home, ".config", "oracle", "exec.env"),
-    join(home, ".config", "mad-desk", "exec.env"), // legacy dir
-  ].filter(Boolean);
-}
-
-/**
- * Resolve an attestation secret.
- *
- * Order: explicit argument, then env var, then an env FILE. The file fallback exists
- * so a long-lived deployment can keep the secret out of the process environment
- * (where it would show up in `ps` output and child processes).
- *
- * @param {string|undefined} secret explicit override
- * @param {string} primaryEnv e.g. "ORACLE_ROUTE_ATTESTATION_SECRET"
- * @param {string} legacyEnv e.g. "MAD_ROUTE_ATTESTATION_SECRET"
- * @returns {string}
- * @throws when no secret can be found -- fail closed, never mint unsigned
- */
-export function resolveAttestationSecret(secret, primaryEnv, legacyEnv) {
-  let value = secret ?? process.env[primaryEnv] ?? process.env[legacyEnv];
-
-  if (!String(value || "").trim()) {
-    for (const envFile of envFileCandidates()) {
-      try {
-        const txt = readFileSync(envFile, "utf8");
-        // Accept either name in the file, primary winning.
-        const m =
-          txt.match(new RegExp(`^${primaryEnv}=(.*)$`, "m")) ||
-          txt.match(new RegExp(`^${legacyEnv}=(.*)$`, "m"));
-        if (m) {
-          value = m[1].trim();
-          if (value) break;
-        }
-      } catch {
-        // Unreadable or absent: try the next candidate. A missing optional file is
-        // not an error; running out of candidates is, and that is handled below.
-      }
-    }
-  }
-
-  if (!String(value || "").trim()) {
-    throw new Error(
-      `${primaryEnv} required for attestation. Set it in the environment, or place ` +
-        `${primaryEnv}=<value> in ~/.config/oracle/exec.env`,
-    );
-  }
-  return value;
-}

package/src/audit-log.mjs

@@ -1,196 +0,0 @@
-// Tamper-evident, append-only audit hash-chain for the Oracle exec layer.
-//
-// Adapted from block/buzz `buzz-audit` (Rust + Postgres, multi-tenant) to Oracle's
-// single-process, file-backed model. Fills the gap the custody review found:
-// the armed executor had a rolling daily-spend counter and NO tamper-evident
-// record of what it prepared / signed / broadcast. This is the compliance/trust
-// spine the non-custodial agency product needs, shared by every oracle-<chain>
-// worker that routes through the exec-server.
-//
-// Each entry chains to the previous via SHA-256 over a FIXED field order that
-// includes `prev_hash`, so deleting, editing, or reordering any entry breaks
-// verification of every entry after it. `detail` is folded in via canonical
-// JSON (recursively sorted keys) so the hash is stable across Arch/VPS/Mac.
-//
-// SECURITY: `detail` is persisted verbatim and included in the hash. NEVER write
-// bearer tokens, private keys, passwords, or keystore passphrases into it. Log
-// outcome metadata (chainId, to, value, hash, reason) only.
-
-import { createHash } from "node:crypto";
-import { readFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-import { configPath, env } from "./oracle-env.mjs";
-
-/** 32-byte sentinel (hex) hashed in place of prev_hash for the first entry. */
-export const GENESIS_HASH = "0".repeat(64);
-
-/** Actions the exec layer records. Unknown actions are allowed (forward-compat)
- *  but this set documents the vocabulary and lets tests assert coverage. */
-export const AUDIT_ACTIONS = Object.freeze({
-  PREPARE: "exec.prepare",
-  SIGN: "exec.sign",
-  BROADCAST: "exec.broadcast",
-  POLICY_REJECT: "policy.reject",
-  AUTH_GRANT: "auth.grant",
-  AUTH_OK: "auth.verify.ok",
-  AUTH_FAIL: "auth.verify.fail",
-});
-
-function defaultPath() {
-  return configPath("audit-log.jsonl", "ORACLE_AUDIT_LOG", "MAD_AUDIT_LOG");
-}
-
-/** Deterministic JSON: object keys sorted recursively. Matches buzz-audit's
- *  canonical_json so the same detail hashes identically everywhere. */
-export function canonicalJson(value) {
-  if (value === null || value === undefined) return "null";
-  if (typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return "[" + value.map(canonicalJson).join(",") + "]";
-  const keys = Object.keys(value).sort();
-  return (
-    "{" +
-    keys.map((k) => JSON.stringify(k) + ":" + canonicalJson(value[k])).join(",") +
-    "}"
-  );
-}
-
-// Fixed field order — changing it invalidates every existing chain. `stream`
-// leads the hash so an entry cannot be lifted out of one stream's chain and
-// re-verified inside another (the tenant-binding property buzz-audit gets from
-// hashing community_id first). Presence tags (\x00 / \x01) distinguish a null
-// field from an empty-string field so they can't collide.
-export function computeHash(entry) {
-  const h = createHash("sha256");
-  h.update(String(entry.stream), "utf8");
-  h.update(String(entry.seq), "utf8");
-  h.update(String(entry.ts), "utf8");
-  h.update(String(entry.action), "utf8");
-  h.update(entry.actor == null ? "\x00" : "\x01" + entry.actor, "utf8");
-  h.update(entry.objectId == null ? "\x00" : "\x01" + entry.objectId, "utf8");
-  h.update(canonicalJson(entry.detail ?? null), "utf8");
-  h.update(entry.prevHash ?? GENESIS_HASH, "utf8");
-  return h.digest("hex");
-}
-
-function readAll(path) {
-  if (!existsSync(path)) return [];
-  const raw = readFileSync(path, "utf8");
-  const out = [];
-  for (const line of raw.split("\n")) {
-    const s = line.trim();
-    if (!s) continue;
-    try {
-      out.push(JSON.parse(s));
-    } catch {
-      // A corrupt/partial trailing line is surfaced by verifyChain, not silently
-      // healed. Skip it here so the head lookup uses the last *valid* record.
-    }
-  }
-  return out;
-}
-
-// Serialize appends within this process so read-head → append is atomic even
-// under concurrent exec-server requests (mirrors buzz-audit's per-chain lock).
-let appendQueue = Promise.resolve();
-
-/**
- * Append one entry to the chain. Returns the full stored record.
- * @param {object} opts
- * @param {string} opts.action    one of AUDIT_ACTIONS (or a custom string)
- * @param {string} [opts.actor]   signer/owner address or agent id
- * @param {string} [opts.objectId] tx hash, chainId:to, grant id, ...
- * @param {object} [opts.detail]  hashed outcome metadata (NO secrets)
- * @param {string} [opts.stream]  logical chain label (default "mad-exec")
- * @param {string} [opts.path]    override log path (tests)
- */
-export function appendAudit({ action, actor = null, objectId = null, detail = null, stream, path } = {}) {
-  if (!action) throw new Error("audit: action required");
-  const p = path || defaultPath();
-  const strm = stream || env("ORACLE_AUDIT_STREAM", "MAD_AUDIT_STREAM", "oracle-exec");
-
-  const run = appendQueue.then(() => {
-    const existing = readAll(p).filter((e) => e.stream === strm);
-    const head = existing.length ? existing[existing.length - 1] : null;
-    const seq = head ? head.seq + 1 : 1;
-    const prevHash = head ? head.hash : null;
-
-    const entry = {
-      stream: strm,
-      seq,
-      ts: new Date().toISOString(),
-      action: String(action),
-      actor: actor == null ? null : String(actor),
-      objectId: objectId == null ? null : String(objectId),
-      detail: detail ?? null,
-      prevHash,
-    };
-    entry.hash = computeHash(entry);
-
-    mkdirSync(dirname(p), { recursive: true });
-    appendFileSync(p, JSON.stringify(entry) + "\n", { mode: 0o600 });
-    return entry;
-  });
-
-  // Keep the queue alive even if one append throws.
-  appendQueue = run.catch(() => {});
-  return run;
-}
-
-/**
- * Best-effort append that NEVER throws into the caller. Use on the live exec
- * path: a broken/unwritable log must not brick a signing operation, and every
- * entry that DID get written stays verifiable. Failures go to stderr.
- */
-export async function recordAudit(opts) {
-  try {
-    return await appendAudit(opts);
-  } catch (e) {
-    try {
-      process.stderr.write(
-        JSON.stringify({ auditError: String(e?.message || e), action: opts?.action }) + "\n"
-      );
-    } catch {
-      /* ignore */
-    }
-    return null;
-  }
-}
-
-/**
- * Verify a stream's chain end-to-end.
- * @returns {{ ok: boolean, count: number, reason?: string, seq?: number }}
- */
-export function verifyChain({ stream, path } = {}) {
-  const p = path || defaultPath();
-  const strm = stream || env("ORACLE_AUDIT_STREAM", "MAD_AUDIT_STREAM", "oracle-exec");
-  const rows = readAll(p).filter((e) => e.stream === strm);
-  if (rows.length === 0) return { ok: false, count: 0, reason: "empty" };
-
-  let expectedPrev = null;
-  let expectedSeq = 1;
-  for (const row of rows) {
-    if (row.seq !== expectedSeq) {
-      return { ok: false, count: rows.length, reason: "seq-gap", seq: row.seq };
-    }
-    const wantPrev = expectedSeq === 1 ? null : expectedPrev;
-    if ((row.prevHash ?? null) !== (wantPrev ?? null)) {
-      return { ok: false, count: rows.length, reason: "prev-hash-mismatch", seq: row.seq };
-    }
-    const { hash, ...bare } = row;
-    if (computeHash(bare) !== hash) {
-      return { ok: false, count: rows.length, reason: "hash-mismatch", seq: row.seq };
-    }
-    expectedPrev = hash;
-    expectedSeq += 1;
-  }
-  return { ok: true, count: rows.length };
-}
-
-/** Read up to `limit` entries from `fromSeq` for a stream (newest-truncated). */
-export function getEntries({ stream, fromSeq = 1, limit = 100, path } = {}) {
-  const p = path || defaultPath();
-  const strm = stream || env("ORACLE_AUDIT_STREAM", "MAD_AUDIT_STREAM", "oracle-exec");
-  return readAll(p)
-    .filter((e) => e.stream === strm && e.seq >= fromSeq)
-    .slice(0, limit);
-}