@oracle-agent/oracle 0.1.0

package/src/audit-log.mjs

@@ -0,0 +1,196 @@
+// 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);
+}

package/src/auto-slippage.mjs

@@ -0,0 +1,378 @@
+// Chain-agnostic bounded automatic slippage policy.
+// Slippage protects fresh quote -> inclusion movement only. Protocol fee and
+// modeled price impact already live in quoteAmountOut and must not be counted a
+// second time. Every executable swap route hard-stops at 100 bps.
+//
+// AUTHENTICATION: the guard is HMAC-signed with the same attestation secret the
+// route/vault/gmx attestations use. Quotes may attach an unsigned bound when no
+// secret is configured (read/prepare UX). Sign and broadcast ALWAYS require a
+// verified signature (requireSigned / enforceTxPolicy) — an unsigned guard is
+// self-attested and must never authorize a swap.
+
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { resolveAttestationSecret } from "./attestation-secret.mjs";
+import { assertFreshWindow } from "./fresh-window.mjs";
+
+export const AUTO_SLIPPAGE_MAX_BPS = 100;
+export const AUTO_SLIPPAGE_DEFAULT_TTL_MS = 20_000;
+
+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 ?? null);
+}
+
+function slippageSecret(secret, { required = false } = {}) {
+  try {
+    return resolveAttestationSecret(secret, "ORACLE_ROUTE_ATTESTATION_SECRET", "MAD_ROUTE_ATTESTATION_SECRET");
+  } catch (error) {
+    if (required) throw error;
+    return null;
+  }
+}
+
+function unsigned(guard) {
+  const { signature: _sig, ...rest } = guard;
+  return rest;
+}
+
+/** Sign a guard so it cannot be forged or re-attached to a different swap. */
+export function signAutoSlippageGuard(guard, { secret } = {}) {
+  const key = slippageSecret(secret);
+  if (!key) return guard;
+  return { ...guard, signature: createHmac("sha256", key).update(canonicalJson(unsigned(guard))).digest("hex") };
+}
+
+function calldataDigest(data) {
+  const hex = String(data || "").toLowerCase();
+  if (!/^0x[0-9a-f]+$/.test(hex) || hex.length < 10 || hex.length % 2 !== 0) {
+    throw new Error("auto-slippage calldata must be even-length hex with a selector");
+  }
+  return createHash("sha256").update(Buffer.from(hex.slice(2), "hex")).digest("hex");
+}
+
+export function bindAutoSlippageGuardToCall(guard, { chainId, venue, data, secret } = {}) {
+  if (!guard || guard.mode !== "auto") throw new Error("bounded auto-slippage guard required");
+  if (Number(guard.chainId) !== Number(chainId)) throw new Error("auto-slippage guard chain mismatch");
+  if (String(guard.venue).toLowerCase() !== String(venue || "").toLowerCase()) {
+    throw new Error("auto-slippage guard venue mismatch");
+  }
+  return signAutoSlippageGuard(
+    { ...unsigned(guard), calldataHash: calldataDigest(data) },
+    { secret },
+  );
+}
+
+function sameSignature(a, b) {
+  const x = Buffer.from(String(a ?? ""), "utf8");
+  const y = Buffer.from(String(b ?? ""), "utf8");
+  if (x.length !== y.length || x.length === 0) return false;
+  return timingSafeEqual(x, y);
+}
+
+function finite(value, fallback = 0) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function integerCap(value) {
+  const n = value == null ? AUTO_SLIPPAGE_MAX_BPS : Number(value);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error("auto-slippage cap must be a non-negative integer bps value");
+  }
+  return Math.min(n, AUTO_SLIPPAGE_MAX_BPS);
+}
+
+export function resolveAutoSlippage({
+  liquidityUsd,
+  priceChange5m = 0,
+  quoteAgeMs = 0,
+  crossChain = false,
+  requestedCapBps,
+} = {}) {
+  const liquidity = finite(liquidityUsd, 0);
+  const depthPenalty = liquidity > 0
+    ? liquidity >= 250_000
+      ? 5
+      : liquidity >= 100_000
+        ? 10
+        : liquidity >= 50_000
+          ? 20
+          : liquidity >= 10_000
+            ? 40
+            : 70
+    : crossChain
+      ? 30
+      : 10;
+  const volatilityPenalty = Math.min(60, Math.abs(finite(priceChange5m, 0)) * 2);
+  const agePenalty = Math.min(40, Math.floor(Math.max(0, finite(quoteAgeMs, 0)) / 5_000) * 5);
+  const requiredBps = Math.max(25, Math.ceil(20 + depthPenalty + volatilityPenalty + agePenalty));
+  const capBps = integerCap(requestedCapBps);
+  return {
+    mode: "auto",
+    requiredBps,
+    selectedBps: Math.min(requiredBps, capBps),
+    capBps,
+    executable: requiredBps <= capBps,
+  };
+}
+
+export function createAutoSlippageGuard({
+  chainId,
+  venue,
+  quoteAmountOut,
+  liquidityUsd,
+  priceChange5m = 0,
+  quoteAgeMs = 0,
+  crossChain = false,
+  requestedCapBps,
+  quotedAtMs = Date.now(),
+  ttlMs = AUTO_SLIPPAGE_DEFAULT_TTL_MS,
+  secret,
+} = {}) {
+  const quote = BigInt(quoteAmountOut ?? 0);
+  if (quote <= 0n) throw new Error("auto-slippage guard requires positive quoteAmountOut");
+  const selected = resolveAutoSlippage({
+    liquidityUsd,
+    priceChange5m,
+    quoteAgeMs,
+    crossChain,
+    requestedCapBps,
+  });
+  if (!selected.executable) {
+    throw new Error(
+      `auto-slippage requires ${selected.requiredBps} bps above hard/requested cap ${selected.capBps}; route blocked`
+    );
+  }
+  const quoted = Number(quotedAtMs);
+  if (!Number.isFinite(quoted)) {
+    throw new Error("auto-slippage: quotedAtMs must be a finite number");
+  }
+  const ttl = Math.min(30_000, Math.max(1_000, Number(ttlMs) || AUTO_SLIPPAGE_DEFAULT_TTL_MS));
+  // BigInt division truncates toward zero, so on small quotes the realised
+  // floor can be far looser than the advertised cap: a 90 bps guard on a quote
+  // of 3 produced minAmountOut=2, i.e. 3333 bps of actual permitted slippage.
+  // Round the floor UP so the executed protection is never weaker than stated,
+  // and refuse outright when the quote is too small to express the bound.
+  const numerator = quote * BigInt(10_000 - selected.selectedBps);
+  let minAmountOut = numerator / 10_000n;
+  if (numerator % 10_000n !== 0n) minAmountOut += 1n; // ceil: favour the user
+  if (minAmountOut > quote) minAmountOut = quote;
+  if (quote > 0n && minAmountOut <= 0n) {
+    throw new Error(
+      `auto-slippage: quote ${quote} is too small to express a ${selected.selectedBps} bps floor without rounding to zero`
+    );
+  }
+  // Verify the realised bound actually honours the cap rather than trusting the
+  // arithmetic above.
+  const realisedBps = Number(((quote - minAmountOut) * 10_000n) / (quote === 0n ? 1n : quote));
+  if (realisedBps > selected.capBps) {
+    throw new Error(
+      `auto-slippage: realised floor implies ${realisedBps} bps, above cap ${selected.capBps} — refusing to issue a guard weaker than advertised`
+    );
+  }
+  // Sign on issue so the guard is verifiable later. A secret is mandatory —
+  // unsigned guards are self-attested and rejected at assert time.
+  return signAutoSlippageGuard(
+    {
+      mode: "auto",
+      chainId: Number(chainId),
+      venue: String(venue || "unknown"),
+      quoteAmountOut: quote.toString(),
+      minAmountOut: minAmountOut.toString(),
+      requiredBps: selected.requiredBps,
+      selectedBps: selected.selectedBps,
+      capBps: selected.capBps,
+      quotedAtMs: quoted,
+      expiresAtMs: quoted + ttl,
+    },
+    { secret }
+  );
+}
+
+/**
+ * Best-effort extraction of the output floor a swap call actually encodes.
+ *
+ * Returns null when the selector is unknown — this binds the common router
+ * shapes without pretending to be a universal ABI decoder. A null result means
+ * "cannot verify from calldata", not "verified safe": the venue allowlist and
+ * the guard's own bounds still apply.
+ */
+function encodedMinOut(data) {
+  const hex = String(data || "");
+  if (!/^0x[0-9a-fA-F]+$/.test(hex) || hex.length < 10 || hex.length % 2 !== 0) return null;
+  const selector = hex.slice(0, 10).toLowerCase();
+  const words = [];
+  for (let i = 10; i + 64 <= hex.length; i += 64) words.push(hex.slice(i, i + 64));
+  const word = (i) => (words[i] == null ? null : BigInt("0x" + words[i]));
+
+  switch (selector) {
+    // Uniswap V3 SwapRouter — exactInputSingle with deadline:
+    //   (tokenIn,tokenOut,fee,recipient,deadline,amountIn,amountOutMinimum,
+    //    sqrtPriceLimitX96) — all static, so amountOutMinimum is word 6.
+    case "0x414bf389":
+      return word(6);
+    // SwapRouter02 — SAME name, NO deadline member:
+    //   (tokenIn,tokenOut,fee,recipient,amountIn,amountOutMinimum,
+    //    sqrtPriceLimitX96) — amountOutMinimum shifts to word 5.
+    // Treating this as the 8-member shape reads sqrtPriceLimitX96 instead.
+    case "0x04e45aaf":
+      return word(5);
+    // exactInput((bytes path,address recipient,uint256 deadline,
+    //   uint256 amountIn,uint256 amountOutMinimum))
+    //
+    // The struct's FIRST member is dynamic (bytes path), so the struct itself
+    // is encoded behind an offset and its members live in a tail:
+    //   head[0]           = offset to the struct
+    //   tail[0] (word 1)  = offset to path
+    //   tail[1] (word 2)  = recipient
+    //   tail[2] (word 3)  = deadline
+    //   tail[3] (word 4)  = amountIn
+    //   tail[4] (word 5)  = amountOutMinimum   <-- the real output floor
+    //
+    // Reading word 4 here checked amountIn, which an attacker simply sets to
+    // the guard's expected value while leaving amountOutMinimum at 0. Follow
+    // the offset instead of assuming a fixed layout.
+    case "0xc04b8d59": {
+      const structOffset = word(0);
+      if (structOffset == null) return null;
+      // Offsets are byte counts from the start of the argument block.
+      const base = Number(structOffset) / 32;
+      if (!Number.isInteger(base) || base < 0) return null;
+      return word(base + 4);
+    }
+    // SwapRouter02 exactInput((bytes path,address recipient,uint256 amountIn,
+    //   uint256 amountOutMinimum)) — no deadline, so the floor is tail word 3.
+    case "0xb858183f": {
+      const structOffset = word(0);
+      if (structOffset == null) return null;
+      const base = Number(structOffset) / 32;
+      if (!Number.isInteger(base) || base < 0) return null;
+      return word(base + 3);
+    }
+    // Aerodrome Slipstream exactInputSingle with tickSpacing and deadline
+    case "0xa026383e":
+      return word(6);
+    // V2 swapExactTokensForTokens(amountIn, amountOutMin, path, to, deadline)
+    case "0x38ed1739":
+    case "0x5c11d795": // ...SupportingFeeOnTransferTokens
+      return word(1);
+    // V2 swapExactETHForTokens(amountOutMin, path, to, deadline)
+    case "0x7ff36ab5":
+    case "0xb6f9de95":
+      return word(0);
+    // V2 swapExactTokensForETH(amountIn, amountOutMin, path, to, deadline)
+    case "0x18cbafe5":
+    case "0x791ac947":
+      return word(1);
+    default:
+      return null;
+  }
+}
+
+
+export function assertAutoSlippageGuard(
+  guard,
+  { nowMs = Date.now(), chainId, venue, secret, tx, requireSigned = false } = {},
+) {
+  if (!guard || guard.mode !== "auto") {
+    throw new Error("bounded auto-slippage guard required");
+  }
+
+  // Verify authenticity FIRST when signing/broadcasting. Quotes may attach an
+  // unsigned bound for display; the policy gate always passes requireSigned=true.
+  const key = slippageSecret(secret, { required: requireSigned });
+  if (requireSigned && !key) {
+    throw new Error("auto-slippage attestation secret required for signing or broadcast");
+  }
+  if (key) {
+    const expected = createHmac("sha256", key).update(canonicalJson(unsigned(guard))).digest("hex");
+    if (!sameSignature(guard.signature, expected)) {
+      throw new Error("auto-slippage guard signature mismatch — the guard was not issued by this Oracle");
+    }
+  } else if (guard.signature) {
+    throw new Error("auto-slippage guard carries a signature but no attestation secret is configured");
+  }
+  const selected = Number(guard.selectedBps);
+  const cap = Number(guard.capBps);
+  if (!Number.isInteger(selected) || selected < 0 || selected > AUTO_SLIPPAGE_MAX_BPS) {
+    throw new Error(`auto-slippage selected tolerance exceeds hard 100 bps cap`);
+  }
+  if (!Number.isInteger(cap) || cap < 0 || cap > AUTO_SLIPPAGE_MAX_BPS || selected > cap) {
+    throw new Error(`auto-slippage cap exceeds hard 100 bps cap`);
+  }
+  // Fail CLOSED on an unusable clock: Number(NaN) > x is false, so a broken or
+  // attacker-influenced clock made an expired quote eternal.
+  try {
+    assertFreshWindow({ expiresAtMs: guard.expiresAtMs, issuedAtMs: guard.quotedAtMs }, nowMs, "auto-slippage quote");
+  } catch (e) {
+    throw new Error(`${e.message}; re-quote before signing`);
+  }
+  if (chainId != null && Number(guard.chainId) !== Number(chainId)) {
+    throw new Error("auto-slippage guard chain mismatch");
+  }
+  if (venue && String(guard.venue).toLowerCase() !== String(venue).toLowerCase()) {
+    throw new Error("auto-slippage guard venue mismatch");
+  }
+  const quote = BigInt(guard.quoteAmountOut ?? 0);
+  const minimum = BigInt(guard.minAmountOut ?? 0);
+  if (quote <= 0n || minimum <= 0n) {
+    throw new Error("auto-slippage guard amounts must be positive");
+  }
+  const protectedFloor = quote * BigInt(10_000 - selected) / 10_000n;
+  if (minimum < protectedFloor) {
+    throw new Error("auto-slippage guard is under-protected relative to its fresh quote");
+  }
+  if (tx?.data && guard.minAmountOut != null) {
+    if (guard.calldataHash != null) {
+      if (String(guard.calldataHash) !== calldataDigest(tx.data)) {
+        throw new Error("auto-slippage guard is not bound to this call: calldata hash mismatch");
+      }
+    } else {
+      const encoded = encodedMinOut(tx.data);
+      if (encoded == null) {
+        const selector = String(tx.data).slice(0, 10);
+        throw new Error(
+          `auto-slippage: cannot verify the output floor encoded by selector ${selector}; ` +
+            "refusing rather than trusting unbound calldata at an allowlisted venue"
+        );
+      }
+      if (encoded !== BigInt(guard.minAmountOut)) {
+        throw new Error(
+          `auto-slippage guard is not bound to this call: guard minAmountOut ${guard.minAmountOut} but calldata encodes ${encoded}`
+        );
+      }
+    }
+  }
+  return true;
+}
+
+export function attachAutoSlippage(result, {
+  chainId,
+  venue,
+  amountOut,
+  liquidityUsd,
+  priceChange5m,
+  crossChain,
+  requestedCapBps,
+  quotedAtMs = Date.now(),
+  ttlMs,
+} = {}) {
+  const autoSlippage = createAutoSlippageGuard({
+    chainId,
+    venue,
+    quoteAmountOut: amountOut,
+    liquidityUsd,
+    priceChange5m,
+    crossChain,
+    requestedCapBps,
+    quotedAtMs,
+    ttlMs,
+  });
+  return { ...result, autoSlippage, amountOutMinimum: autoSlippage.minAmountOut };
+}

package/src/capability-posture.mjs

@@ -0,0 +1,125 @@
+// Oracle capability posture.
+//
+// THE RULE, stated once, in one place:
+//
+//   A capability is ARMED when the user has supplied the credential it needs.
+//   Nothing executes unless the user asks for that specific action.
+//   Autonomous trading is the sole exception: it stays OFF until explicitly
+//   enabled, because it is the only mode where Oracle acts without a request.
+//
+// Why this shape:
+//
+//   The old model ("everything disarmed until N env flags are set") punished
+//   the honest self-hoster. Someone who had already handed Oracle a signing key
+//   still could not buy an NFT without hunting down a second, third, and fourth
+//   feature flag. That is not security — it is friction that teaches people to
+//   set ORACLE_*_ENABLED=1 everywhere, which is strictly worse than a coherent
+//   default.
+//
+//   Supplying a key IS the authorization decision. What actually protects the
+//   user is not a flag; it is that every action is USER-INITIATED and bounded
+//   by caps at the moment it runs.
+//
+//   The one thing a key does NOT authorize is Oracle acting on its own. An
+//   agent that trades while you sleep is a different risk class from an agent
+//   that buys the NFT you just named. So AUTONOMOUS trading — and only that —
+//   requires a separate, explicit opt-in.
+
+export const CAPABILITY_TIERS = Object.freeze({
+  READ: "read",
+  PREPARE: "prepare",
+  EXECUTE: "execute",
+  AUTONOMOUS: "autonomous",
+});
+
+/** Credential each capability needs before it can be armed. */
+const CREDENTIAL_FOR = Object.freeze({
+  "evm:prepare": ["ORACLE_EVM_ADDRESS", "EVM_KEYSTORE_FILE", "ORACLE_SIGNER_ADDRESS"],
+  "evm:execute": ["EVM_KEYSTORE_FILE", "ORACLE_KEYSTORE_FILE"],
+  "btc:execute": ["BTC_WIF_FILE", "ORACLE_BTC_WIF_FILE"],
+  "solana:execute": ["SOLANA_KEYPAIR_FILE", "ORACLE_SOLANA_KEYPAIR_FILE"],
+  "nft:buy": [],
+  "nft:mint": [],
+  "cow:submit": [],
+});
+
+function hasAnyEnv(names, env) {
+  return names.some((n) => String(env[n] ?? "").trim() !== "");
+}
+
+/**
+ * Is autonomous (unattended) trading enabled?
+ *
+ * This is the ONLY capability that a present key does not arm, because it is
+ * the only one where Oracle initiates value movement without the user asking
+ * for that specific action.
+ */
+export function autonomousTradingEnabled(env = process.env) {
+  return String(env.ORACLE_AUTONOMOUS_TRADING ?? "").trim() === "1";
+}
+
+/**
+ * Decide whether a capability may run.
+ *
+ * @param {string} capability   e.g. "nft:buy", "btc:execute"
+ * @param {object} opts
+ * @param {boolean} opts.userInitiated  the user asked for THIS action, now
+ * @param {boolean} opts.autonomous     Oracle initiated it on its own
+ */
+export function capabilityStatus(capability, { env = process.env, userInitiated = false, autonomous = false } = {}) {
+  const needed = CREDENTIAL_FOR[capability] ?? [];
+  const keyPresent = needed.length === 0 || hasAnyEnv(needed, env);
+
+  if (autonomous && !autonomousTradingEnabled(env)) {
+    return {
+      capability,
+      armed: keyPresent,
+      allowed: false,
+      reason:
+        "autonomous trading is off — set ORACLE_AUTONOMOUS_TRADING=1 to let Oracle act without an explicit request",
+    };
+  }
+
+  if (!keyPresent) {
+    return {
+      capability,
+      armed: false,
+      allowed: false,
+      reason: `no credential configured for ${capability} — set one of: ${needed.join(", ")}`,
+    };
+  }
+
+  if (!userInitiated && !autonomous) {
+    return {
+      capability,
+      armed: true,
+      allowed: false,
+      reason: "armed, but nothing runs until you ask for this action",
+    };
+  }
+
+  return { capability, armed: true, allowed: true, reason: null };
+}
+
+/** Throwing form for call sites that should refuse rather than branch. */
+export function assertCapability(capability, opts = {}) {
+  const status = capabilityStatus(capability, opts);
+  if (!status.allowed) {
+    const err = new Error(`oracle: ${capability} not permitted — ${status.reason}`);
+    err.status = status;
+    throw err;
+  }
+  return status;
+}
+
+/** Human-readable posture for a status surface. */
+export function posture(env = process.env) {
+  const caps = Object.keys(CREDENTIAL_FOR);
+  const armed = caps.filter((c) => capabilityStatus(c, { env, userInitiated: true }).allowed);
+  return {
+    model: "key-present = armed; user-initiated = runs; autonomous = opt-in",
+    armed,
+    autonomousTrading: autonomousTradingEnabled(env) ? "ENABLED" : "off",
+    note: "Nothing executes unless you ask for it. Caps and simulation still apply to every action.",
+  };
+}