@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/fresh-window.mjs

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

package/src/gmx-attestation.mjs

@@ -0,0 +1,176 @@
+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

@@ -0,0 +1,107 @@
+// 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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,139 @@
+// 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

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