@oracle-agent/oracle 0.14.1 → 0.16.0

package/src/fresh-window.mjs

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

package/src/gmx-attestation.mjs

@@ -1,176 +0,0 @@
-import { createHmac, timingSafeEqual } from "node:crypto";
-import { Interface, isAddress } from "ethers";
-import { routeCalldataHash } from "./route-attestation.mjs";
-import { resolveAttestationSecret } from "./attestation-secret.mjs";
-import { assertFreshWindow } from "./fresh-window.mjs";
-
-const DEFAULT_GMX_ATTESTATION_TTL_MS = 20_000;
-const ERC20 = new Interface(["function approve(address spender,uint256 amount) returns (bool)"]);
-
-export const GMX_EXCHANGE_ROUTERS = Object.freeze({
-  42161: "0x1c3fa76e6e1088bce750f23a5bfcffa1efef6a41",
-  43114: "0x8f550e53dfe96c055d5bdb267c21f268fcaf63b2",
-});
-
-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);
-}
-
-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 = "gmx amount") {
-  try {
-    const n = BigInt(String(value));
-    if (n <= 0n) throw new Error("nonpositive");
-    return n.toString();
-  } catch {
-    throw new Error(`${label} must be a positive integer string`);
-  }
-}
-
-function boolValue(value) {
-  return Boolean(value);
-}
-
-function hmac(secret, payload) {
-  return `0x${createHmac("sha256", String(secret)).update(payload).digest("hex")}`;
-}
-
-function sameSignature(a, b) {
-  const left = Buffer.from(String(a || "").replace(/^0x/, ""), "hex");
-  const right = Buffer.from(String(b || "").replace(/^0x/, ""), "hex");
-  return left.length === right.length && left.length > 0 && timingSafeEqual(left, right);
-}
-
-function attestationSecret(secret) {
-  return resolveAttestationSecret(
-    secret,
-    "ORACLE_ROUTE_ATTESTATION_SECRET",
-    "MAD_ROUTE_ATTESTATION_SECRET",
-  );
-}
-
-function unsigned(attestation) {
-  const { signature: _signature, ...payload } = attestation;
-  return payload;
-}
-
-function decodeApproveCalldata(data) {
-  const hex = String(data || "").toLowerCase();
-  if (!hex.startsWith("0x095ea7b3")) throw new Error("approval calldata required");
-  const [spender, amount] = ERC20.decodeFunctionData("approve", hex);
-  return { spender: normalAddress(spender, "approval spender"), amount: amountString(amount, "approval amount") };
-}
-
-export function isGmxExchangeRouter(chainId, address) {
-  const router = GMX_EXCHANGE_ROUTERS[Number(chainId)];
-  return !!router && normalAddress(address, "gmx exchange router") === router;
-}
-
-export function createGmxOrderAttestation({
-  provider = "gmx",
-  chainId,
-  account,
-  receiver,
-  exchangeRouter,
-  router,
-  orderVault,
-  orderType,
-  market,
-  initialCollateralToken,
-  initialCollateralDeltaAmount,
-  sizeDeltaUsd,
-  executionFee,
-  acceptablePrice,
-  isLong,
-  data,
-  calldataHash,
-  value,
-  maxSlippageBps,
-  nowMs = Date.now(),
-  ttlMs = DEFAULT_GMX_ATTESTATION_TTL_MS,
-  secret,
-} = {}) {
-  const attestation = {
-    mode: "gmx-order-attestation",
-    version: 1,
-    provider: String(provider || "").trim() || "gmx",
-    chainId: Number(chainId),
-    account: normalAddress(account, "gmx account"),
-    receiver: normalAddress(receiver || account, "gmx receiver"),
-    exchangeRouter: normalAddress(exchangeRouter, "gmx exchangeRouter"),
-    router: normalAddress(router, "gmx router"),
-    orderVault: normalAddress(orderVault, "gmx orderVault"),
-    orderType: String(orderType || "").trim(),
-    market: normalAddress(market, "gmx market"),
-    initialCollateralToken: normalAddress(initialCollateralToken, "gmx initialCollateralToken"),
-    initialCollateralDeltaAmount: amountString(initialCollateralDeltaAmount, "gmx initialCollateralDeltaAmount"),
-    sizeDeltaUsd: amountString(sizeDeltaUsd, "gmx sizeDeltaUsd"),
-    executionFee: amountString(executionFee, "gmx executionFee"),
-    acceptablePrice: amountString(acceptablePrice, "gmx acceptablePrice"),
-    isLong: boolValue(isLong),
-    calldataHash: data ? routeCalldataHash(data) : calldataHash,
-    value: value == null ? amountString(executionFee, "gmx value") : amountString(value, "gmx value"),
-    issuedAtMs: Number(nowMs),
-    expiresAtMs: Number(nowMs) + Number(ttlMs),
-  };
-  if (!Number.isFinite(attestation.chainId)) throw new Error("gmx attestation chainId required");
-  if (!attestation.orderType) throw new Error("gmx orderType required");
-  if (!isGmxExchangeRouter(attestation.chainId, attestation.exchangeRouter)) throw new Error("gmx exchangeRouter mismatch for chain");
-  if (maxSlippageBps != null) attestation.maxSlippageBps = Number(maxSlippageBps);
-  const payload = canonicalJson(attestation);
-  return { ...attestation, signature: hmac(attestationSecret(secret), payload) };
-}
-
-function assertSignature(attestation, secret) {
-  const expected = hmac(attestationSecret(secret), canonicalJson(unsigned(attestation)));
-  if (!sameSignature(attestation.signature, expected)) throw new Error("gmx attestation signature mismatch");
-}
-
-export function assertGmxOrderAttestation(attestation, tx = {}, { chainId, nowMs = Date.now(), secret } = {}) {
-  if (!attestation || attestation.mode !== "gmx-order-attestation") throw new Error("gmx order attestation required");
-  if (Number(attestation.expiresAtMs) <= Number(nowMs)) throw new Error("gmx attestation expired");
-  assertSignature(attestation, secret);
-  const txChainId = Number(chainId ?? tx.chainId);
-  if (Number(attestation.chainId) !== txChainId) throw new Error("gmx attestation chain mismatch");
-  const to = normalAddress(tx.to, "gmx tx.to");
-  if (normalAddress(attestation.exchangeRouter, "gmx exchangeRouter") !== to) throw new Error("gmx attestation destination mismatch");
-  if (!isGmxExchangeRouter(txChainId, to)) throw new Error("gmx exchangeRouter mismatch for chain");
-  if (tx.from && normalAddress(attestation.account, "gmx account") !== normalAddress(tx.from, "gmx tx.from")) {
-    throw new Error("gmx attestation account mismatch");
-  }
-  // Time is a security parameter: an unusable clock must fail CLOSED,
-  // otherwise NaN/null/-Infinity silently makes this attestation eternal.
-  assertFreshWindow(attestation || {}, nowMs, "gmx order attestation");
-  const value = tx.value == null ? "0" : String(BigInt(String(tx.value).startsWith("0x") ? String(tx.value) : String(tx.value)));
-  if (String(attestation.value) !== value || String(attestation.executionFee) !== value) throw new Error("gmx attestation value mismatch");
-  if (attestation.calldataHash !== routeCalldataHash(tx.data || "0x")) throw new Error("gmx attestation calldata mismatch");
-  return true;
-}
-
-export function assertGmxApprovalAttestation(attestation, tx = {}, guard = {}, { chainId, nowMs = Date.now(), secret } = {}) {
-  if (!attestation || attestation.mode !== "gmx-order-attestation") throw new Error("gmx order attestation required");
-  assertFreshWindow(attestation, nowMs, "gmx approval attestation");
-  if (Number(attestation.expiresAtMs) <= Number(nowMs)) throw new Error("gmx attestation expired");
-  assertSignature(attestation, secret);
-  const txChainId = Number(tx.chainId ?? chainId);
-  if (Number(attestation.chainId) !== txChainId) throw new Error("gmx attestation chain mismatch");
-  const decoded = decodeApproveCalldata(tx.data);
-  if (normalAddress(attestation.initialCollateralToken, "gmx collateral") !== normalAddress(tx.to, "approval token")) {
-    throw new Error("gmx attestation collateral mismatch");
-  }
-  if (normalAddress(attestation.router, "gmx router") !== decoded.spender) throw new Error("gmx attestation spender mismatch");
-  if (String(attestation.initialCollateralDeltaAmount) !== decoded.amount || String(guard.amount) !== decoded.amount) {
-    throw new Error("gmx attestation amount mismatch");
-  }
-  if (guard.provider && String(guard.provider) !== String(attestation.provider)) throw new Error("gmx attestation provider mismatch");
-  return true;
-}

package/src/index.mjs

@@ -1,107 +0,0 @@
-// Oracle public package root.
-//
-// Curated exports only: data/read plane, scanner/chain registration, routing,
-// policy schema, and scope constants.
-//
-// Key-material and execution modules are deliberately absent from every
-// public package entrypoint, so importing the package cannot hand a caller a
-// signer.
-
-export {
-  stampPrepared,
-  assertPreparedEnvelope,
-  computePrepareHash,
-  computePrepareMac,
-  resolvePrepareMaxAgeMs,
-  PREPARE_VERSION,
-  PREPARE_MAX_AGE_MS,
-  PREPARE_HARD_MAX_AGE_MS,
-} from "./prepare-envelope.mjs";
-export { data, dataCall, dataHealth, dataCatalog } from "./data/desk-data.mjs";
-export { registerProvider, getProvider, listProviders } from "./data/catalog.mjs";
-
-export { CHAINS, chainById, registerChain, rpcUrlFor, isSupportedChain } from "./chains.mjs";
-
-export {
-  SCANNER_CAPABILITIES,
-  EVIDENCE,
-  RISK,
-  validateScanner,
-  createScanner,
-  registerScanner,
-  getScanner,
-  listScanners,
-  scannerCoverage,
-  CHAIN_CONFIGS,
-  registerBuiltinScanners,
-  registerCustomChain,
-} from "./scanner/index.mjs";
-
-export { bestSwapRoute, bestBridgeRoute, QUALITY } from "./router/index.mjs";
-export {
-  bestEquityRoute,
-  equityVenues,
-  prepareEquityRoute,
-  collectEquityQuotes,
-  toJsonSafe as equityToJsonSafe,
-} from "./equities/index.mjs";
-export {
-  normalizeRfqIntent,
-  normalizeFirmQuote,
-  hashRfqIntent,
-  hashFirmQuote,
-} from "./rfq/intent.mjs";
-export { sourceCandidates, executeRfqCandidates, rankRfqQuotes, requestRfqQuotes } from "./rfq/sources.mjs";
-export { validateNftMintGasWar, assertNftMintGasWar, NftGasWarLimitError } from "./nft-gas-war-guard.mjs";
-export { simulateSell, assertSellable, SELL_SIM } from "./sell-simulation.mjs";
-export { capabilityStatus, assertCapability, autonomousTradingEnabled, posture } from "./capability-posture.mjs";
-export {
-  ACTION_MODES,
-  actionModeForVerb,
-  assertActionRecord,
-  createActionRecord,
-  isActiveAlert,
-  isActiveExecution,
-  migrateLegacyWatchRecord,
-} from "./action-semantics.mjs";
-
-export {
-  GRANT_VERSION,
-  normalizeGrant,
-  validateGrant,
-  canonicalizeGrant,
-  grantId,
-  GrantValidationError,
-} from "./public-control/policy-schema.mjs";
-
-export {
-  ALLOWED_SCOPES,
-  EXECUTE_SCOPE,
-  BUILD_SCOPE,
-  DEFAULT_SCOPES,
-  normalizeScopes,
-} from "./scopes.mjs";
-
-export { emitHarnessConfigs, createHarnessConfigs } from "./onboarding/harness-configs.mjs";
-export {
-  ACTION_RECEIPT_VERSION,
-  ActionReceiptSecretError,
-  assertNoReceiptSecrets,
-  canonicalReceiptJson,
-  computeReceiptId,
-  normalizeActionReceipt,
-  createActionReceipt,
-  summarizeActionReceipt,
-  formatActionReceipt,
-} from "./action-receipts.mjs";
-export { DEFAULT_RISK_THRESHOLDS, summarizePortfolioRisk, portfolioRiskSummary } from "./portfolio-risk.mjs";
-export {
-  WATCH_CATEGORIES,
-  defaultPreferences,
-  subscribe,
-  unsubscribe,
-  createWatch,
-  evaluateAlert,
-  shouldDeliverAlert,
-} from "./watch-preferences.mjs";
-export { SIGNAL_TYPES, scoreSignals, createSignalsEngine } from "./signals/index.mjs";

package/src/licensing/locals-only.mjs

@@ -1,25 +0,0 @@
-import { Contract, JsonRpcProvider } from "ethers";
-
-export const LOCALS_ONLY_CONTRACT = "0x62FCFAf7573AD8B41a0FBF347AfEb85e06599A75";
-export const LOCALS_ONLY_CHAIN_ID = 999;
-export const LOCALS_ONLY_RPC = "https://rpc.hyperliquid.xyz/evm";
-
-const ERC721_BALANCE_ABI = ["function balanceOf(address owner) view returns (uint256)"];
-const ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
-
-export function isAddress(value) {
-  return ADDRESS_RE.test(String(value || ""));
-}
-
-export async function holderBalance(address, {
-  contract = LOCALS_ONLY_CONTRACT,
-  rpc = LOCALS_ONLY_RPC,
-  chainId = LOCALS_ONLY_CHAIN_ID,
-  balanceOf,
-} = {}) {
-  if (!isAddress(address)) throw new Error("invalid-address");
-  if (balanceOf) return BigInt(await balanceOf(address));
-  const provider = new JsonRpcProvider(rpc, chainId, { staticNetwork: true });
-  const erc721 = new Contract(contract, ERC721_BALANCE_ABI, provider);
-  return BigInt(await erc721.balanceOf(address));
-}

package/src/nft-gas-war-guard.mjs

@@ -1,139 +0,0 @@
-// Oracle public NFT mint gas-war guard.
-//
-// Pure, dependency-free policy checks for NFT mint bots across any configured
-// chain. This module does not sign, broadcast, read RPC, or know private keys.
-// It only decides whether a proposed mint transaction's gas envelope fits the
-// user's explicit cap. Missing caps fail closed.
-
-const DECIMAL_RE = /^(0|[1-9][0-9]*)$/;
-
-export class NftGasWarLimitError extends Error {
-  constructor(verdict) {
-    super(`nft gas-war limit: ${verdict.reason}`);
-    this.name = "NftGasWarLimitError";
-    this.verdict = verdict;
-  }
-}
-
-function toBig(value, label, { required = true, allowZero = false } = {}) {
-  if (value == null || value === "") {
-    if (required) throw new Error(`${label} required`);
-    return null;
-  }
-  let n;
-  if (typeof value === "bigint") n = value;
-  else if (typeof value === "number") {
-    if (!Number.isSafeInteger(value)) throw new Error(`${label} must be a safe integer`);
-    n = BigInt(value);
-  } else if (typeof value === "string") {
-    const s = value.trim();
-    if (s.startsWith("0x") || s.startsWith("0X")) n = BigInt(s);
-    else {
-      if (!DECIMAL_RE.test(s)) throw new Error(`${label} must be an integer wei string`);
-      n = BigInt(s);
-    }
-  } else throw new Error(`${label} must be bigint, number, or integer string`);
-  if (n < 0n || (!allowZero && n === 0n)) throw new Error(`${label} must be ${allowZero ? "non-negative" : "positive"}`);
-  return n;
-}
-
-function toChainId(value) {
-  const n = Number(value);
-  if (!Number.isSafeInteger(n) || n <= 0) throw new Error("chainId must be a positive integer");
-  return n;
-}
-
-function readGasPrice(tx = {}) {
-  if (tx.maxFeePerGas != null) return toBig(tx.maxFeePerGas, "maxFeePerGas");
-  if (tx.gasPrice != null) return toBig(tx.gasPrice, "gasPrice");
-  return null;
-}
-
-/**
- * Validate an NFT mint gas envelope against a user/grant gas-war policy.
- *
- * Input accepts either top-level gas fields or a tx object:
- *   validateNftMintGasWar({ chainId, tx, policy })
- *   tx: { gasLimit, maxFeePerGas, maxPriorityFeePerGas } or legacy { gasPrice }
- *   policy: {
- *     maxTotalGasWei,          // required unless grant.maxGasWei provided
- *     maxFeePerGasWei,         // optional per-unit cap
- *     maxPriorityFeePerGasWei, // optional EIP-1559 tip cap
- *     grant                    // optional normalized public grant with maxGasWei
- *   }
- */
-export function validateNftMintGasWar(input = {}) {
-  try {
-    const chainId = toChainId(input.chainId ?? input.tx?.chainId);
-    const tx = input.tx || input;
-    const policy = input.policy || input;
-    const grantMaxGas = policy.grant?.maxGasWei ?? input.grant?.maxGasWei;
-    const maxTotalGasWei = toBig(policy.maxTotalGasWei ?? policy.maxGasWei ?? grantMaxGas, "maxTotalGasWei");
-    const gasLimit = toBig(tx.gasLimit ?? tx.gas, "gasLimit");
-    const unitFee = readGasPrice(tx);
-    if (unitFee == null) throw new Error("maxFeePerGas or gasPrice required");
-    const maxFeePerGasWei = toBig(policy.maxFeePerGasWei, "maxFeePerGasWei", { required: false });
-    const maxPriorityFeePerGasWei = toBig(policy.maxPriorityFeePerGasWei, "maxPriorityFeePerGasWei", { required: false });
-    const priorityFee = tx.maxPriorityFeePerGas == null ? null : toBig(tx.maxPriorityFeePerGas, "maxPriorityFeePerGas");
-    const totalGasWei = gasLimit * unitFee;
-
-    if (totalGasWei > maxTotalGasWei) {
-      return {
-        ok: false,
-        status: "BLOCK",
-        reason: `total gas ${totalGasWei} exceeds cap ${maxTotalGasWei}`,
-        chainId,
-        totalGasWei: totalGasWei.toString(),
-        maxTotalGasWei: maxTotalGasWei.toString(),
-      };
-    }
-    if (maxFeePerGasWei != null && unitFee > maxFeePerGasWei) {
-      return {
-        ok: false,
-        status: "BLOCK",
-        reason: `unit fee ${unitFee} exceeds cap ${maxFeePerGasWei}`,
-        chainId,
-        unitFeeWei: unitFee.toString(),
-        maxFeePerGasWei: maxFeePerGasWei.toString(),
-        totalGasWei: totalGasWei.toString(),
-        maxTotalGasWei: maxTotalGasWei.toString(),
-      };
-    }
-    if (priorityFee != null && maxPriorityFeePerGasWei != null && priorityFee > maxPriorityFeePerGasWei) {
-      return {
-        ok: false,
-        status: "BLOCK",
-        reason: `priority fee ${priorityFee} exceeds cap ${maxPriorityFeePerGasWei}`,
-        chainId,
-        priorityFeeWei: priorityFee.toString(),
-        maxPriorityFeePerGasWei: maxPriorityFeePerGasWei.toString(),
-        totalGasWei: totalGasWei.toString(),
-        maxTotalGasWei: maxTotalGasWei.toString(),
-      };
-    }
-    return {
-      ok: true,
-      status: "PASS",
-      reason: "gas envelope within NFT mint gas-war caps",
-      chainId,
-      totalGasWei: totalGasWei.toString(),
-      maxTotalGasWei: maxTotalGasWei.toString(),
-      unitFeeWei: unitFee.toString(),
-      maxFeePerGasWei: maxFeePerGasWei?.toString() ?? null,
-      priorityFeeWei: priorityFee?.toString() ?? null,
-      maxPriorityFeePerGasWei: maxPriorityFeePerGasWei?.toString() ?? null,
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      status: "BLOCK",
-      reason: String(error?.message || error),
-    };
-  }
-}
-
-export function assertNftMintGasWar(input = {}) {
-  const verdict = validateNftMintGasWar(input);
-  if (!verdict.ok) throw new NftGasWarLimitError(verdict);
-  return verdict;
-}

package/src/onboarding/agent-keys.mjs

@@ -1,161 +0,0 @@
-// File-backed scoped API keys for multi-user onboarding.
-// NON-CUSTODIAL: we store only a HASH of the API key + owner wallet address.
-// We never store the user's private key. agent:execute requires controller allowlist.
-
-import { createHash, randomBytes } from "node:crypto";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { normalizeScopes, EXECUTE_SCOPE, DEFAULT_SCOPES } from "../scopes.mjs";
-
-// API keys are 32+ bytes of CSPRNG output, not user-chosen passwords. SHA-256
-// is the right lookup hash here (same class as GitHub PATs). Slow password
-// KDFs would only add DoS surface on every authenticated request.
-// codeql[js/insufficient-password-hash]
-function hashKey(raw) {
-  return createHash("sha256").update(String(raw), "utf8").digest("hex");
-}
-
-function emptyState() {
-  return { version: 1, keys: [] };
-}
-
-export function defaultStorePath() {
-  if (process.env.ORACLE_AGENT_KEYS_PATH) return process.env.ORACLE_AGENT_KEYS_PATH;
-  if (process.env.MAD_AGENT_KEYS_PATH) return process.env.MAD_AGENT_KEYS_PATH;
-  const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
-  return join(root, "data", "agent-keys.json");
-}
-
-function readState(path) {
-  if (!existsSync(path)) return emptyState();
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!parsed || !Array.isArray(parsed.keys)) return emptyState();
-    return parsed;
-  } catch {
-    return emptyState();
-  }
-}
-
-function writeState(path, state) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, JSON.stringify(state, null, 2), { mode: 0o600 });
-}
-
-function publicRecord(rec) {
-  return {
-    id: rec.id,
-    owner: rec.owner,
-    name: rec.name,
-    scopes: rec.scopes,
-    tier: rec.tier || null,
-    createdAt: rec.createdAt,
-    revokedAt: rec.revokedAt || null,
-    lastUsedAt: rec.lastUsedAt || null,
-  };
-}
-
-/**
- * @param {object} opts
- * @param {string} opts.owner  user wallet address (checksum optional)
- * @param {string} [opts.name]
- * @param {string[]} [opts.scopes]
- * @param {string} [opts.tier]
- * @param {string[]} [opts.controllerAllowlist] required if scopes include agent:execute
- * @param {string} [opts.storePath]
- * @returns {{ key: string, record: object }}  raw key shown ONCE
- */
-export function createAgentKey({
-  owner,
-  name = "Agent key",
-  scopes,
-  tier = null,
-  controllerAllowlist = [],
-  storePath = defaultStorePath(),
-} = {}) {
-  const normalizedOwner = String(owner || "").toLowerCase();
-  if (!/^0x[0-9a-f]{40}$/.test(normalizedOwner)) {
-    throw new Error("owner must be a 0x-prefixed 20-byte address");
-  }
-  const normalizedScopes = normalizeScopes(scopes);
-  if (normalizedScopes.includes(EXECUTE_SCOPE)) {
-    const rawList = controllerAllowlist.length
-      ? controllerAllowlist
-      : String(process.env.MAD_EXECUTOR_CONTROLLERS || "")
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean);
-    const allow = new Set(rawList.map((a) => String(a).toLowerCase()));
-    if (!allow.has(normalizedOwner)) {
-      throw new Error("Wallet is not an executor controller");
-    }
-  }
-
-  const raw = `mad_${randomBytes(24).toString("base64url")}`;
-  const rec = {
-    id: randomBytes(8).toString("hex"),
-    owner: normalizedOwner,
-    name: String(name).slice(0, 80),
-    scopes: normalizedScopes,
-    tier,
-    keyHash: hashKey(raw),
-    createdAt: new Date().toISOString(),
-    revokedAt: null,
-    lastUsedAt: null,
-  };
-
-  const state = readState(storePath);
-  state.keys.push(rec);
-  writeState(storePath, state);
-
-  return { key: raw, record: publicRecord(rec) };
-}
-
-export function listAgentKeys(owner, { storePath = defaultStorePath(), includeRevoked = false } = {}) {
-  const o = String(owner || "").toLowerCase();
-  const state = readState(storePath);
-  return state.keys
-    .filter((k) => k.owner === o)
-    .filter((k) => includeRevoked || !k.revokedAt)
-    .map(publicRecord);
-}
-
-export function revokeAgentKey({ owner, id, storePath = defaultStorePath() } = {}) {
-  const o = String(owner || "").toLowerCase();
-  const state = readState(storePath);
-  const rec = state.keys.find((k) => k.owner === o && k.id === id);
-  if (!rec) throw new Error("key not found");
-  if (rec.revokedAt) return publicRecord(rec);
-  rec.revokedAt = new Date().toISOString();
-  writeState(storePath, state);
-  return publicRecord(rec);
-}
-
-/**
- * Authenticate a raw API key. Returns public record + owner-bound identity
- * suitable for getSigner({ identity: { type: 'scoped-key', ... } }).
- */
-export function authenticateAgentKey(rawKey, { storePath = defaultStorePath() } = {}) {
-  if (!rawKey) throw new Error("key required");
-  const h = hashKey(rawKey);
-  const state = readState(storePath);
-  const rec = state.keys.find((k) => k.keyHash === h && !k.revokedAt);
-  if (!rec) throw new Error("invalid or revoked key");
-  rec.lastUsedAt = new Date().toISOString();
-  writeState(storePath, state);
-  return {
-    ...publicRecord(rec),
-    identity: {
-      type: "scoped-key",
-      owner: rec.owner,
-      scopes: rec.scopes,
-    },
-  };
-}
-
-export function __resetAgentKeysForTest(storePath) {
-  writeState(storePath || defaultStorePath(), emptyState());
-}
-
-export { DEFAULT_SCOPES, EXECUTE_SCOPE };