@oracle-agent/oracle 0.1.0

package/src/gmx-attestation.mjs

@@ -0,0 +1,175 @@
+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");
+  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,50 @@
+// 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 { 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 { 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 {
+  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";

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,157 @@
+// 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";
+
+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 };

package/src/onboarding/index.mjs

@@ -0,0 +1,18 @@
+export {
+  createAgentKey,
+  listAgentKeys,
+  revokeAgentKey,
+  authenticateAgentKey,
+  defaultStorePath,
+  __resetAgentKeysForTest,
+} from "./agent-keys.mjs";
+
+export {
+  TIERS,
+  listTiers,
+  getTier,
+  onboardUser,
+  onboardAuthenticate,
+  onboardListKeys,
+  onboardRevoke,
+} from "./tiers.mjs";

package/src/onboarding/tiers.mjs

@@ -0,0 +1,139 @@
+// Product onboarding tiers — multi-user, non-custodial.
+// Tier chooses default scopes. Higher tiers never put user private keys on our box.
+
+import { DEFAULT_SCOPES, EXECUTE_SCOPE } from "../scopes.mjs";
+import { createAgentKey, listAgentKeys, revokeAgentKey, authenticateAgentKey } from "./agent-keys.mjs";
+
+/**
+ * Tier catalog (product story):
+ * - observer:   read-only market/position data
+ * - preparer:   can prepare trades/mints (unsigned / advisory)
+ * - shadow:     paper/shadow agent loops
+ * - executor:   live agent:execute — ONLY if owner is on controller allowlist
+ * - local_signer: no API key needed for signing; user signs off-infra (docs only)
+ */
+export const TIERS = {
+  observer: {
+    id: "observer",
+    label: "Observer",
+    description: "Read markets, NFTs, positions. No prepare/execute.",
+    scopes: ["read:markets", "read:nfts", "read:positions"],
+    custody: "none",
+    canExecute: false,
+  },
+  preparer: {
+    id: "preparer",
+    label: "Preparer",
+    description: "Prepare trades/mints; user or operator co-signs. No live execute scope.",
+    scopes: [...DEFAULT_SCOPES].filter((s) => s !== "agent:shadow"),
+    custody: "none",
+    canExecute: false,
+  },
+  shadow: {
+    id: "shadow",
+    label: "Shadow agent",
+    description: "Full prepare + agent:shadow paper loops. Still no live execute.",
+    scopes: [...DEFAULT_SCOPES],
+    custody: "none",
+    canExecute: false,
+  },
+  executor: {
+    id: "executor",
+    label: "Executor (controller)",
+    description:
+      "Live agent:execute on the owner's own wallet only. Owner must be an executor controller. Key is NOT a wallet key.",
+    scopes: [...DEFAULT_SCOPES, EXECUTE_SCOPE],
+    custody: "none — scoped API key only; user wallet key never stored",
+    canExecute: true,
+  },
+  local_signer: {
+    id: "local_signer",
+    label: "Local signer",
+    description:
+      "User keeps keys on their device. Desk issues prepare-only key; signing happens off our infra.",
+    scopes: ["read:markets", "read:positions", "prepare:trade", "prepare:mint"],
+    custody: "none — signing off-box",
+    canExecute: false,
+    mintKey: true,
+  },
+};
+
+export function listTiers() {
+  return Object.values(TIERS).map((t) => ({
+    id: t.id,
+    label: t.label,
+    description: t.description,
+    scopes: t.scopes,
+    custody: t.custody,
+    canExecute: t.canExecute,
+  }));
+}
+
+export function getTier(id) {
+  const t = TIERS[id];
+  if (!t) throw new Error(`Unknown tier: ${id}`);
+  return t;
+}
+
+/**
+ * Onboard a user wallet onto a tier. Returns one-time raw API key (except pure docs).
+ * NEVER accepts or stores a private key.
+ */
+export function onboardUser({
+  owner,
+  tier = "observer",
+  name,
+  controllerAllowlist = [],
+  storePath,
+  scopes, // optional override
+} = {}) {
+  if (owner && typeof owner === "object" && owner.privateKey) {
+    throw new Error("Refusing privateKey — non-custodial onboarding accepts owner address only");
+  }
+  const t = getTier(tier);
+  const finalScopes = scopes || t.scopes;
+  const result = createAgentKey({
+    owner,
+    name: name || `${t.label} key`,
+    scopes: finalScopes,
+    tier: t.id,
+    controllerAllowlist,
+    storePath,
+  });
+  return {
+    tier: t.id,
+    custody: t.custody,
+    canExecute: t.canExecute && finalScopes.includes(EXECUTE_SCOPE),
+    key: result.key, // show once
+    record: result.record,
+    nextSteps:
+      t.id === "local_signer"
+        ? [
+            "Store the API key for prepare/read calls only",
+            "Keep your wallet key on your device / hardware signer",
+            "Submit prepared payloads to your local signer — never upload the key here",
+          ]
+        : t.canExecute
+          ? [
+              "Store the API key securely",
+              "Live execute still requires MAD_EXECUTE_ENABLED=1 on the operator side",
+              "This key can only act on YOUR owner wallet (custody firewall)",
+            ]
+          : [
+              "Store the API key securely",
+              "Use with getSigner({ identity: auth.identity, venue }) after authenticateAgentKey",
+            ],
+  };
+}
+
+export function onboardAuthenticate(rawKey, opts) {
+  return authenticateAgentKey(rawKey, opts);
+}
+
+export function onboardListKeys(owner, opts) {
+  return listAgentKeys(owner, opts);
+}
+
+export function onboardRevoke(opts) {
+  return revokeAgentKey(opts);
+}