@oracle-agent/oracle 0.11.0 → 0.13.0

package/src/data/http.mjs

@@ -1,253 +0,0 @@
-// Tiny HTTP helpers for the read-only data plane. No signing. No secrets logged.
-//
-// Optimizations that matter for a self-hoster hitting public rate limits:
-//   - bounded retry with Retry-After support on 429 / 502 / 503 / 504
-//   - single-flight dedupe so N concurrent identical GETs cost ONE upstream call
-//   - both are opt-out via opts.retries = 0 / opts.dedupe = false
-//
-// SECURITY: the dedupe key binds the FULL credential (hashed), not merely whether
-// one was present. Keying on presence alone lets two callers with different API
-// keys collapse into one upstream request, so the second caller receives data
-// fetched with the first caller's credential. Found in pre-public red team.
-
-import { createHash } from "node:crypto";
-
-const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
-// Methods safe to replay when the transport failed and we cannot know whether
-// the server already applied the request.
-const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]);
-const DEFAULT_RETRIES = 2;
-const MAX_BACKOFF_MS = 4_000;
-
-// Headers that identify the CALLER. Two requests may only share a deduped
-// in-flight response when every one of these matches exactly.
-// Any header that distinguishes one caller's credentials from another's. If a
-// credential header is MISSING from this list, two different users' requests
-// hash identically and the in-flight dedupe collapses them into one — user B
-// receives a response fetched with user A's key. Enumerating providers here is
-// fragile, so the matcher below also treats anything key/token/secret-shaped as
-// identity-bearing.
-const IDENTITY_HEADERS = [
-  "authorization",
-  "x-api-key",
-  "x-tensor-api-key",
-  "0x-api-key",
-  "api-key",
-  "cookie",
-  "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();
-
-/**
- * Derive a dedupe key that is safe to hold in memory: credential material is
- * hashed, never stored raw, so the cache cannot become a secret-disclosure
- * surface (heap dump, debugger, accidental log of the map).
- */
-function dedupeKey(method, url, headers) {
-  const lower = {};
-  for (const [k, v] of Object.entries(headers || {})) lower[k.toLowerCase()] = v;
-
-  // Structural, not just the known list: ANY header whose name looks like it
-  // carries a credential participates in the fingerprint. A fixed enumeration
-  // silently fails the moment a provider uses a new header name — that is how
-  // `0x-api-key` was omitted, which collapsed two users' 0x requests into one
-  // and served user B a response fetched with user A's key.
-  const credentialShaped = Object.keys(lower).filter((h) =>
-    /(^|-)(api[-_]?key|key|token|secret|auth|authorization|session|cookie|signature|access)(-|$)/.test(h)
-  );
-  const names = [...new Set([...IDENTITY_HEADERS, ...credentialShaped])].sort();
-  const identity = names.map((h) => `${h}=${lower[h] ?? ""}`).join("\n");
-  const fingerprint = createHash("sha256").update(identity).digest("hex").slice(0, 32);
-  return `${method} ${url} ${fingerprint}`;
-}
-
-function backoffMs(attempt, retryAfterHeader) {
-  const retryAfter = Number(retryAfterHeader);
-  if (Number.isFinite(retryAfter) && retryAfter > 0) {
-    return Math.min(retryAfter * 1000, MAX_BACKOFF_MS);
-  }
-  const base = Math.min(250 * 2 ** attempt, MAX_BACKOFF_MS);
-  return base + Math.floor(Math.random() * 100);
-}
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-async function once(url, { fetchImpl, method, headers, body, timeoutMs }) {
-  const ac = new AbortController();
-  const t = setTimeout(() => ac.abort(), timeoutMs);
-  try {
-    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;
-    }
-    throw new Error(`HTTP redirect loop for ${url}`);
-  } finally {
-    clearTimeout(t);
-  }
-}
-
-/**
- * @param {string} url
- * @param {{ method?: string, headers?: Record<string,string>, body?: any, timeoutMs?: number, fetchImpl?: typeof fetch, retries?: number, dedupe?: boolean }} [opts]
- */
-export async function httpJson(url, opts = {}) {
-  const fetchImpl = opts.fetchImpl || globalThis.fetch;
-  if (typeof fetchImpl !== "function") {
-    throw new Error("fetch unavailable — pass opts.fetchImpl");
-  }
-  const timeoutMs = opts.timeoutMs ?? 12_000;
-  const method = (opts.method || "GET").toUpperCase();
-  const headers = { Accept: "application/json", ...(opts.headers || {}) };
-  let body = opts.body;
-  if (body != null && typeof body !== "string") {
-    headers["Content-Type"] = headers["Content-Type"] || "application/json";
-    body = JSON.stringify(body);
-  }
-  const retries = Number.isInteger(opts.retries) ? Math.max(opts.retries, 0) : DEFAULT_RETRIES;
-
-  const attempt = async () => {
-    let lastError;
-    for (let i = 0; i <= retries; i++) {
-      try {
-        return await once(url, { fetchImpl, method, headers, body, timeoutMs });
-      } catch (error) {
-        lastError = error;
-        const status = error?.status;
-        const abortLike = error?.name === "AbortError";
-        // A response with a status means the SERVER answered and refused to
-        // process the request, so replaying it is safe. A transport-level
-        // failure (no status) is ambiguous: the server may have already applied
-        // the request and only the response was lost. Never replay a
-        // non-idempotent method on an ambiguous failure.
-        // A retryable STATUS is not on its own a licence to replay: a 500 or
-        // 503 can be returned after the server already applied the request, so
-        // replaying a POST can place a second order or submit a second
-        // transaction. 429/408/425 mean "not processed", so those stay
-        // retryable for every method; genuine server errors only replay for
-        // idempotent methods.
-        const ALWAYS_SAFE_STATUS = new Set([408, 425, 429]);
-        const retryable =
-          status != null
-            ? ALWAYS_SAFE_STATUS.has(status) ||
-              (RETRYABLE_STATUS.has(status) && IDEMPOTENT_METHODS.has(method))
-            : !abortLike && IDEMPOTENT_METHODS.has(method);
-        if (i === retries || !retryable) throw error;
-        await sleep(backoffMs(i, error?.retryAfter));
-      }
-    }
-    throw lastError;
-  };
-
-  // Single-flight only for idempotent GETs with no body.
-  const dedupe = opts.dedupe !== false && method === "GET" && body == null;
-  if (!dedupe) return attempt();
-
-  const key = dedupeKey(method, url, headers);
-  const existing = inflight.get(key);
-  if (existing) return existing;
-  const p = attempt().finally(() => inflight.delete(key));
-  inflight.set(key, p);
-  return p;
-}
-
-export async function timed(fn) {
-  const t0 = Date.now();
-  try {
-    const data = await fn();
-    return { ok: true, ms: Date.now() - t0, data };
-  } catch (e) {
-    return {
-      ok: false,
-      ms: Date.now() - t0,
-      error: String(e.message || e),
-      status: e.status ?? null,
-    };
-  }
-}
-
-/**
- * Run async tasks with a hard concurrency ceiling. Public health sweeps fan out
- * across ~30 providers; unbounded Promise.all trips public rate limits.
- */
-export async function mapLimit(items, limit, fn) {
-  const list = Array.from(items);
-  const cap = Math.max(1, Math.min(Number(limit) || 1, list.length || 1));
-  const out = new Array(list.length);
-  let cursor = 0;
-  await Promise.all(
-    Array.from({ length: cap }, async () => {
-      while (cursor < list.length) {
-        const index = cursor++;
-        out[index] = await fn(list[index], index);
-      }
-    })
-  );
-  return out;
-}

package/src/data/provider-endpoint.mjs

@@ -1,94 +0,0 @@
-// Provider endpoint pinning.
-//
-// Every keyed provider had the same shape: `baseUrl` came from caller-supplied
-// opts, and headers() attached the operator's API key unconditionally. One
-// hostile opts object — from a prompt-injected model, a malicious skill, or a
-// config someone pasted — ships the credential to an arbitrary host. That is
-// credential exfiltration and SSRF wearing a configuration costume.
-//
-// The rule here: a credential is attached ONLY when the resolved host is one
-// the provider is pinned to. Overriding the URL is still allowed (local mocks,
-// self-hosted proxies, testing) but doing so DROPS the key rather than
-// forwarding it somewhere new.
-
-const OVERRIDE_ENV = "ORACLE_ALLOW_CUSTOM_PROVIDER_URL";
-
-/**
- * @param {object} spec
- * @param {string} spec.provider   provider id, for error messages
- * @param {string} spec.defaultUrl the pinned default endpoint
- * @param {string[]} spec.hosts    hostnames allowed to receive the credential
- * @param {string} [spec.url]      caller/env supplied override
- * @param {boolean} [spec.strict]  throw instead of dropping the key
- */
-export function resolveProviderEndpoint({ provider, defaultUrl, hosts = [], url, strict = false }) {
-  // An empty/blank override means "not configured", not "call the empty
-  // string". Treat it as absent so callers can pass `opts.baseUrl` straight
-  // through without pre-checking it.
-  const override = String(url ?? "").trim();
-  const raw = (override || String(defaultUrl)).replace(/\/$/, "");
-  if (raw === String(defaultUrl).replace(/\/$/, "")) {
-    return { baseUrl: raw, trusted: true, host: hostOf(defaultUrl) };
-  }
-
-  let parsed;
-  try {
-    parsed = new URL(raw);
-  } catch {
-    throw new Error(`${provider}: baseUrl must be an absolute http(s) URL`);
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error(`${provider}: baseUrl must be an absolute http(s) URL`);
-  }
-  const host = parsed.host;
-  if (!host) {
-    throw new Error(`${provider}: baseUrl must be an absolute http(s) URL`);
-  }
-
-  const allowed = new Set([hostOf(defaultUrl), ...hosts]);
-  if (allowed.has(host)) {
-    // A protocol downgrade to plaintext would put the pinned credential on the
-    // wire in cleartext, so an allowlisted HOST over http:// is still not a
-    // trusted destination for a secret. Loopback is exempt: there is no wire.
-    const loopback = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i.test(host);
-    if (parsed.protocol === "http:" && !loopback) {
-      return { baseUrl: raw, trusted: false, host, reason: "plaintext http downgrade" };
-    }
-    return { baseUrl: raw, trusted: true, host };
-  }
-
-  if (String(process.env[OVERRIDE_ENV] || "") === "1") {
-    // Explicit operator opt-in. Still untrusted: the caller asked for a
-    // different host, so the key does not travel there.
-    return { baseUrl: raw, trusted: false, host };
-  }
-
-  if (strict) {
-    throw new Error(
-      `${provider}: refusing to call non-allowlisted host ${host} (set ${OVERRIDE_ENV}=1 to permit it)`
-    );
-  }
-  return { baseUrl: raw, trusted: false, host };
-}
-
-function hostOf(url) {
-  const u = new URL(String(url));
-  if (u.protocol !== "http:" && u.protocol !== "https:") throw new Error("unsupported protocol");
-  return u.host;
-}
-
-/**
- * Attach credential headers only to a trusted endpoint.
- *
- * @param {object} baseHeaders  headers safe for any host (accept, user-agent)
- * @param {object} credentials  header name -> secret value
- * @param {boolean} trusted     from resolveProviderEndpoint
- */
-export function credentialedHeaders(baseHeaders, credentials, trusted) {
-  const h = { ...baseHeaders };
-  if (!trusted) return h;
-  for (const [name, value] of Object.entries(credentials || {})) {
-    if (value) h[name] = value;
-  }
-  return h;
-}

package/src/data/providers/aerodrome.mjs

@@ -1,245 +0,0 @@
-// Aerodrome Slipstream (Base) — QuoterV2 + SwapRouter exact-input.
-// Official deployments: aerodrome-finance/slipstream README (Base).
-// Quoter/router use tickSpacing (not Uniswap fee tiers). No API key.
-// Read/quote/prepare only — never signs or broadcasts.
-
-import { Interface, getAddress, isAddress } from "ethers";
-import { rpcCall } from "./evm-rpc.mjs";
-import { attachAutoSlippage, bindAutoSlippageGuardToCall } from "../../auto-slippage.mjs";
-import { stampPrepared } from "../../prepare-envelope.mjs";
-
-/** @type {Record<number, { name: string, quoter: string, router: string, factory: string, weth: string, usdc: string }>} */
-export const AERODROME_CHAINS = {
-  8453: {
-    name: "base",
-    // Verified 2026-07-24: slipstream README initial deployment + eth_getCode + live quote.
-    quoter: "0x254cF9E1E6e233aa1AC962CB9B05b2cfeAaE15b0",
-    router: "0xBE6D8f0d05cC4be24d5167a3eF062215bE6D18a5",
-    factory: "0x5e7BB104d84c7CB9B682AaC2F3d509f5F406809A",
-    weth: "0x4200000000000000000000000000000000000006",
-    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-  },
-};
-
-// Common Slipstream tick spacings on Base.
-export const AERODROME_TICK_SPACINGS = [1, 50, 100, 200, 2000];
-
-const QUOTER_IFACE = new Interface([
-  "function quoteExactInputSingle((address tokenIn, address tokenOut, uint256 amountIn, int24 tickSpacing, uint160 sqrtPriceLimitX96) params) returns (uint256 amountOut, uint160 sqrtPriceX96After, uint32 initializedTicksCrossed, uint256 gasEstimate)",
-]);
-
-const ROUTER_IFACE = new Interface([
-  "function exactInputSingle((address tokenIn, address tokenOut, int24 tickSpacing, address recipient, uint256 deadline, uint256 amountIn, uint256 amountOutMinimum, uint160 sqrtPriceLimitX96) params) payable returns (uint256 amountOut)",
-]);
-
-const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
-const ZERO = "0x0000000000000000000000000000000000000000";
-
-function chainMeta(chainId) {
-  const id = Number(chainId);
-  const m = AERODROME_CHAINS[id];
-  if (!m) {
-    throw new Error(
-      `aerodrome: unsupported chainId ${chainId} (supported: ${Object.keys(AERODROME_CHAINS).join(", ")})`
-    );
-  }
-  return { chainId: id, ...m };
-}
-
-function normalizeToken(addr, chainId) {
-  const meta = AERODROME_CHAINS[Number(chainId)];
-  if (!addr || addr === NATIVE || addr === ZERO || /^eth$/i.test(String(addr))) {
-    return getAddress(meta.weth);
-  }
-  const s = String(addr);
-  if (/^weth$/i.test(s)) return getAddress(meta.weth);
-  if (/^usdc$/i.test(s)) return getAddress(meta.usdc);
-  if (!isAddress(s)) throw new Error(`invalid token address: ${addr}`);
-  return getAddress(s);
-}
-
-/**
- * Quote exact-input single hop via Aerodrome Slipstream QuoterV2.
- * @param {object} q
- * @param {number} [q.chainId=8453]
- * @param {string} [q.tokenIn] default WETH
- * @param {string} [q.tokenOut] default USDC
- * @param {string|number|bigint} q.amountIn raw base units
- * @param {number} [q.tickSpacing] if omitted, tries common spacings for best-out
- */
-export async function aerodromeQuoteExactIn(q = {}, opts = {}) {
-  const { chainId, quoter, router } = chainMeta(q.chainId ?? 8453);
-  const tokenIn = normalizeToken(q.tokenIn || "WETH", chainId);
-  const tokenOut = normalizeToken(q.tokenOut || AERODROME_CHAINS[chainId].usdc, chainId);
-  const amountIn = BigInt(q.amountIn ?? 0);
-  if (amountIn <= 0n) throw new Error("amountIn required (raw base units)");
-
-  const spacings =
-    q.tickSpacing != null
-      ? [Number(q.tickSpacing)]
-      : q.tryTickSpacings === false
-        ? [100]
-        : [...AERODROME_TICK_SPACINGS];
-
-  const results = [];
-  let best = null;
-
-  for (const tickSpacing of spacings) {
-    const data = QUOTER_IFACE.encodeFunctionData("quoteExactInputSingle", [
-      {
-        tokenIn,
-        tokenOut,
-        amountIn,
-        tickSpacing,
-        sqrtPriceLimitX96: 0n,
-      },
-    ]);
-    try {
-      const raw = await rpcCall(chainId, "eth_call", [{ to: quoter, data }, "latest"], opts);
-      if (!raw || raw === "0x") {
-        results.push({ tickSpacing, ok: false, error: "empty result" });
-        continue;
-      }
-      const decoded = QUOTER_IFACE.decodeFunctionResult("quoteExactInputSingle", raw);
-      const row = {
-        tickSpacing,
-        ok: true,
-        amountOut: decoded[0].toString(),
-        sqrtPriceX96After: decoded[1].toString(),
-        initializedTicksCrossed: Number(decoded[2]),
-        gasEstimate: decoded[3].toString(),
-      };
-      results.push(row);
-      if (!best || BigInt(row.amountOut) > BigInt(best.amountOut)) best = row;
-    } catch (e) {
-      results.push({ tickSpacing, ok: false, error: String(e.message || e).slice(0, 160) });
-    }
-  }
-
-  if (!best) {
-    const err = results.map((r) => `${r.tickSpacing}:${r.error || "fail"}`).join("; ");
-    throw new Error(`aerodrome quote failed chain=${chainId}: ${err}`);
-  }
-
-  return attachAutoSlippage(
-    {
-      venue: "aerodrome",
-      chainId,
-      chain: AERODROME_CHAINS[chainId].name,
-      quoter,
-      router,
-      tokenIn,
-      tokenOut,
-      amountIn: amountIn.toString(),
-      tickSpacing: best.tickSpacing,
-      amountOut: best.amountOut,
-      gasEstimate: best.gasEstimate,
-      sqrtPriceX96After: best.sqrtPriceX96After,
-      initializedTicksCrossed: best.initializedTicksCrossed,
-      triedTickSpacings: results,
-      best: true,
-    },
-    {
-      chainId,
-      venue: router,
-      amountOut: best.amountOut,
-      liquidityUsd: q.liquidityUsd,
-      priceChange5m: q.priceChange5m,
-      requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
-    }
-  );
-}
-
-export async function aerodromePrepareExactIn(q = {}, opts = {}) {
-  const chainId = Number(q.chainId ?? 8453);
-  const meta = chainMeta(chainId);
-  const recipient = getAddress(q.recipient || q.from || q.userAddress);
-  const inputRaw = String(q.tokenIn || "WETH");
-  const nativeInput =
-    !q.tokenIn || inputRaw === NATIVE || inputRaw === ZERO || /^eth$/i.test(inputRaw);
-  const quote = await aerodromeQuoteExactIn(q, opts);
-  const deadlineWindow = Math.min(600, Math.max(30, Number(q.deadlineSeconds ?? 300)));
-  const nowSeconds = Number(opts.nowSeconds ?? Math.floor(Date.now() / 1000));
-  const deadline = nowSeconds + deadlineWindow;
-  const data = ROUTER_IFACE.encodeFunctionData("exactInputSingle", [
-    {
-      tokenIn: quote.tokenIn,
-      tokenOut: quote.tokenOut,
-      tickSpacing: quote.tickSpacing,
-      recipient,
-      deadline,
-      amountIn: BigInt(quote.amountIn),
-      amountOutMinimum: BigInt(quote.amountOutMinimum),
-      sqrtPriceLimitX96: 0n,
-    },
-  ]);
-  return stampPrepared({
-    provider: "aerodrome",
-    calldataReady: true,
-    // NOT executable authority. The bytes are assembled but nothing is signed:
-    // the user's wallet is still the only thing that can authorize this. The
-    // previous `executionReady: true` read as "cleared to execute" and trained
-    // agents to treat a quote as permission.
-    requiresUserSignature: true,
-    signingReady: false,
-    broadcastReady: false,
-    chainId,
-    deadline,
-    quote,
-    autoSlippage: quote.autoSlippage,
-    requiresApproval: nativeInput
-      ? null
-      : {
-          token: quote.tokenIn,
-          spender: meta.router,
-          amount: quote.amountIn,
-        },
-    transaction: {
-      chainId,
-      from: recipient,
-      to: meta.router,
-      data,
-      value: nativeInput ? quote.amountIn : "0",
-      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: meta.router, data }),
-    },
-  }, { provider: "aerodrome", kind: "aerodrome-exact-in" });
-}
-
-export async function aerodromeHealth(opts = {}) {
-  const chainId = Number(opts.chainId ?? 8453);
-  try {
-    const q = await aerodromeQuoteExactIn(
-      {
-        chainId,
-        tokenIn: "WETH",
-        tokenOut: "USDC",
-        amountIn: "1000000000000000",
-      },
-      opts
-    );
-    const usdc = Number(q.amountOut) / 1e6;
-    return {
-      ok: true,
-      chainId,
-      tickSpacing: q.tickSpacing,
-      amountOutUsdc: usdc,
-      midPxHint: usdc / 0.001,
-      router: AERODROME_CHAINS[chainId]?.router,
-      quoter: AERODROME_CHAINS[chainId]?.quoter,
-    };
-  } catch (e) {
-    return { ok: false, chainId, error: String(e.message || e).slice(0, 200) };
-  }
-}
-
-export async function aerodromeChains() {
-  return Object.entries(AERODROME_CHAINS).map(([id, m]) => ({
-    chainId: Number(id),
-    name: m.name,
-    quoter: m.quoter,
-    router: m.router,
-    factory: m.factory,
-    weth: m.weth,
-    usdc: m.usdc,
-  }));
-}