@oracle-agent/oracle 0.1.0

package/skills/oracle-token-research/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: oracle-token-research
+description: Use when researching any token, especially low-cap or newly launched. The sell-side-first checklist that catches honeypots.
+---
+
+# Token research
+
+The default assumption for a new token is **hostile**. Research exists to disprove
+that, not to confirm a story.
+
+## Sell side first
+
+Most losses here are not bad entries. They are tokens that **buy cleanly and cannot
+be sold**. So the first question is never "will it go up" — it is "can I get out."
+
+Run a **round-trip simulation** in one state-free call: wrap native → buy token →
+sell token back → require a minimum return. Treat any of these as FAIL:
+
+- quote failure in either direction
+- transfer failure
+- router revert
+- round-trip return below the no-tax reverse quote by more than a small tolerance
+
+A successful **buy** quote proves nothing about the sell.
+
+## Price against the real pool
+
+A launchpad or bonding-curve token often exposes its **own** `getReserves()`
+returning zero or virtual values. The tradeable market is a *different* pair.
+
+- `blockTimestampLast == 0` → not a live pool. Do not size against it.
+- Find the real pair via `factory.getPair(a, b)` or a live swap's decoded target
+- A pair with `kLast`, `price0CumulativeLast`, `MINIMUM_LIQUIDITY` is standard V2
+  even when the router in front of it is a custom fork
+
+Sizing against stale reserves is how a "0.4% impact" trade becomes 3%.
+
+## Identity before action
+
+Tickers collide and get squatted. A fuzzy name match is a **candidate**, never
+confirmation.
+
+Always surface the **contract address** and require explicit confirmation before
+anything that moves value. `FEFUR` vs `FEFER` is a real class of loss.
+
+## The rest of the checklist
+
+| Check | Red flag |
+|---|---|
+| holder concentration | top 5 hold most of supply |
+| liquidity depth | thin relative to your size |
+| LP status | unlocked or removable |
+| age | hours old with heavy volume |
+| router | non-canonical clone with a familiar name |
+| mint authority | still open |
+| transfer logic | fees or blocks that change post-launch |
+
+## Label your evidence
+
+Mark every finding `LIVE`, `STALE`, `UNKNOWN`, or `UNAVAILABLE` with a timestamp.
+Do not call holder-concentration analysis "bundle detection" — bundles require
+launch-block clustering and common-funder evidence, which is a different query.
+
+## Honest output
+
+`unknown` is a correct and frequent answer about a two-hour-old token. Say it.
+Never let narrative quality substitute for a passing sell simulation.

package/src/agent-auth.mjs

@@ -0,0 +1,191 @@
+// Owner-signed, self-verifying, time-bounded agent capability tokens.
+//
+// Adapted from block/buzz NIP-OA ("Owner Attestation") to MAD's EVM world.
+// NIP-OA is Schnorr/BIP-340 over a nostr event; MAD signs ECDSA/EIP-191 with
+// the same secp256k1 curve, so the credential format ports directly while the
+// signature primitive becomes ethers `verifyMessage` (already used elsewhere).
+//
+// WHY: today MAD proves owner authority ONLY server-side (MAD_EXECUTOR_CONTROLLERS
+// allowlist + key-hash + bearer). That is a denylist the server must carry. A
+// capability is the complement: a self-contained grant the AGENT carries and
+// presents, that the exec layer verifies without consulting a list, and that
+// EXPIRES on its own. Revocation-by-expiry, not just server denial. For the
+// multi-user agency version an owner key mints a scoped, expiring grant per
+// client without the server tracking every delegation.
+//
+// A capability is: ["auth", <ownerAddress>, <conditions>, <signature>]
+//   ownerAddress : 0x EVM address that authorized the agent
+//   conditions   : "" or clause(&clause)*  — clauses below
+//   signature    : owner EIP-191 signature over the preimage
+//
+// Preimage (exact bytes, order-sensitive — the owner signs this string):
+//   "mad:agent-auth:" + <agentAddress-lowercased> + ":" + <conditions>
+//
+// Clauses (case-sensitive, no whitespace, canonical base-10):
+//   chain=<decimal>        agent may act on this EVM chainId
+//   action=<string>        agent may perform this action/scope (e.g. exec.broadcast)
+//   expires<unix>          capability invalid at/after this wall-clock time
+//   notbefore>unix         capability invalid before this wall-clock time
+//
+// Unlike NIP-OA (which constrains an agent-controlled event.created_at and so
+// cannot enforce wall-clock expiry), MAD verifies a capability presented LIVE
+// against real time, so `expires<`/`notbefore>` ARE enforced against the
+// verifier clock here — the wall-clock enforcement NIP-OA defers to the caller.
+
+import { verifyMessage, getAddress, isAddress } from "ethers";
+
+export const AUTH_DOMAIN = "mad:agent-auth:";
+
+/** Build the exact signing preimage. Owner signs this via personal_sign. */
+export function authPreimage(agentAddress, conditions) {
+  const a = String(agentAddress || "").toLowerCase();
+  if (!/^0x[0-9a-f]{40}$/.test(a)) throw new Error("agentAddress must be a 0x 20-byte address");
+  return AUTH_DOMAIN + a + ":" + String(conditions ?? "");
+}
+
+// Parse + validate the conditions string into typed clauses. Throws on any
+// malformed clause (mirrors NIP-OA's strict rejection rules).
+function parseConditions(conditions) {
+  const out = { chains: new Set(), actions: new Set(), expires: null, notbefore: null };
+  const s = String(conditions ?? "");
+  if (s === "") return out; // empty imposes no constraints
+  if (/\s/.test(s)) throw new Error("conditions: whitespace not permitted");
+  if (s.startsWith("&") || s.endsWith("&") || s.includes("&&")) {
+    throw new Error("conditions: empty clause");
+  }
+  const decimal = (v, max) => {
+    if (!/^(0|[1-9][0-9]*)$/.test(v)) throw new Error(`conditions: non-canonical decimal '${v}'`);
+    const n = Number(v);
+    if (!Number.isSafeInteger(n) || n < 0 || n > max) throw new Error(`conditions: out of range '${v}'`);
+    return n;
+  };
+  for (const clause of s.split("&")) {
+    if (clause.startsWith("chain=")) {
+      out.chains.add(decimal(clause.slice(6), 0xffffffff));
+    } else if (clause.startsWith("action=")) {
+      const v = clause.slice(7);
+      if (!v) throw new Error("conditions: empty action");
+      out.actions.add(v);
+    } else if (clause.startsWith("expires<")) {
+      out.expires = decimal(clause.slice(8), 0xffffffff);
+    } else if (clause.startsWith("notbefore>")) {
+      out.notbefore = decimal(clause.slice(10), 0xffffffff);
+    } else {
+      throw new Error(`conditions: unsupported clause '${clause}'`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Verify an owner capability authorizes `agentAddress` for `{ chainId, action }`
+ * right now. Pure + self-contained: no allowlist, no DB. Returns a result object
+ * rather than throwing so the exec path can log a reason and fail closed.
+ *
+ * @param {[string,string,string,string]} tag  ["auth", owner, conditions, sig]
+ * @param {object} ctx
+ * @param {string} ctx.agentAddress  the agent key the capability was signed for
+ * @param {number} [ctx.chainId]     chain the action targets (checked vs chain=)
+ * @param {string} [ctx.action]      action/scope requested (checked vs action=)
+ * @param {number} [ctx.now]         unix seconds override (tests)
+ * @returns {{ ok: boolean, owner?: string, reason?: string }}
+ */
+export function verifyCapability(tag, { agentAddress, chainId = null, action = null, now = null } = {}) {
+  if (!Array.isArray(tag) || tag.length !== 4 || tag[0] !== "auth") {
+    return { ok: false, reason: "malformed-tag" };
+  }
+  const [, ownerRaw, conditions, sig] = tag;
+  if (!isAddress(ownerRaw)) return { ok: false, reason: "bad-owner-address" };
+  if (!isAddress(agentAddress)) return { ok: false, reason: "bad-agent-address" };
+
+  const owner = getAddress(ownerRaw);
+  // Self-attestation is meaningless — an agent can't authorize itself.
+  if (owner.toLowerCase() === String(agentAddress).toLowerCase()) {
+    return { ok: false, reason: "self-attestation" };
+  }
+
+  let parsed;
+  try {
+    parsed = parseConditions(conditions);
+  } catch (e) {
+    return { ok: false, reason: String(e.message || e) };
+  }
+
+  // Recover the signer from the exact preimage. Any tamper to agent/conditions
+  // changes the preimage and the recovered address won't match the owner.
+  let recovered;
+  try {
+    recovered = verifyMessage(authPreimage(agentAddress, conditions), sig);
+  } catch {
+    return { ok: false, reason: "bad-signature" };
+  }
+  if (recovered.toLowerCase() !== owner.toLowerCase()) {
+    return { ok: false, reason: "signature-owner-mismatch" };
+  }
+
+  const t = now == null ? Math.floor(Date.now() / 1000) : Number(now);
+  if (parsed.expires != null && t >= parsed.expires) return { ok: false, reason: "expired", owner };
+  if (parsed.notbefore != null && t <= parsed.notbefore) return { ok: false, reason: "not-yet-valid", owner };
+  if (parsed.chains.size > 0 && chainId != null && !parsed.chains.has(Number(chainId))) {
+    return { ok: false, reason: "chain-not-authorized", owner };
+  }
+  if (parsed.actions.size > 0 && action != null && !parsed.actions.has(String(action))) {
+    return { ok: false, reason: "action-not-authorized", owner };
+  }
+  return { ok: true, owner };
+}
+
+/**
+ * Owner-side helper: given an owner ethers Signer, mint the capability tag for
+ * an agent. Kept dependency-light — caller supplies the signer so the owner key
+ * NEVER touches this module or the exec box.
+ *
+ * @param {import('ethers').Signer} ownerSigner
+ * @param {string} agentAddress
+ * @param {string} [conditions]
+ * @returns {Promise<[string,string,string,string]>}
+ */
+export async function mintCapability(ownerSigner, agentAddress, conditions = "") {
+  parseConditions(conditions); // validate before signing
+  const owner = await ownerSigner.getAddress();
+  if (owner.toLowerCase() === String(agentAddress).toLowerCase()) {
+    throw new Error("owner and agent must differ");
+  }
+  const sig = await ownerSigner.signMessage(authPreimage(agentAddress, conditions));
+  return ["auth", getAddress(owner), String(conditions), sig];
+}
+
+/**
+ * Gate decision: a capability verifies AND its owner is one MAD trusts.
+ *
+ * `verifyCapability` proves *some* owner signed the grant; on its own that is
+ * not authorization — anyone can sign a grant for the agent from a random key.
+ * This adds the missing half: the recovered owner must be in the trusted
+ * `owners` set. BOTH must hold. Fails CLOSED — an empty trusted set denies
+ * every request (so turning the gate on without configuring owners cannot
+ * silently allow-all).
+ *
+ * Pure: no env, no I/O, no clock unless `now` omitted. The exec layer supplies
+ * env-derived `required`/`owners` and records the outcome to the audit chain.
+ *
+ * @param {[string,string,string,string]} tag
+ * @param {object} ctx
+ * @param {string} ctx.agentAddress   agent the capability must authorize
+ * @param {number} [ctx.chainId]      chain the action targets
+ * @param {string} [ctx.action]       action/scope requested
+ * @param {string[]} [ctx.owners]     trusted owner addresses (allowlist)
+ * @param {number} [ctx.now]          unix seconds override (tests)
+ * @returns {{ ok: boolean, owner?: string, reason?: string }}
+ */
+export function requireCapability(tag, { agentAddress, chainId = null, action = null, owners = [], now = null } = {}) {
+  const allow = new Set(
+    (owners || []).map((a) => String(a).toLowerCase()).filter(Boolean)
+  );
+  if (allow.size === 0) return { ok: false, reason: "no-trusted-owners" };
+  const r = verifyCapability(tag, { agentAddress, chainId, action, now });
+  if (!r.ok) return r;
+  if (!allow.has(r.owner.toLowerCase())) {
+    return { ok: false, reason: "owner-not-trusted", owner: r.owner };
+  }
+  return { ok: true, owner: r.owner };
+}

package/src/approval-guard.mjs

@@ -0,0 +1,282 @@
+import { Interface, MaxUint256, isAddress, keccak256, toUtf8Bytes } from "ethers";
+import { venuesFor } from "./venues.mjs";
+import { assertVaultApprovalAttestation } from "./vault-attestation.mjs";
+import { assertGmxApprovalAttestation } from "./gmx-attestation.mjs";
+import { exactBigInt } from "./exact-integer.mjs";
+import { assertFreshWindow } from "./fresh-window.mjs";
+
+const DEFAULT_APPROVAL_TTL_MS = 20_000;
+
+const ERC20 = new Interface(["function approve(address spender,uint256 amount) returns (bool)"]);
+
+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 = "approval amount", { allowZero = false } = {}) {
+  // Unsafe JS numbers round UP above 2^53, which would widen the allowance past
+  // what the caller wrote. Same class already fixed for ERC-20 transfers.
+  const amount = exactBigInt(value, label);
+  if (allowZero ? amount < 0n : amount <= 0n) throw new Error(`${label} must be positive`);
+  if (amount >= MaxUint256) throw new Error("unlimited approvals are refused; use an exact bounded amount");
+  return amount.toString();
+}
+
+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);
+}
+
+/**
+ * Selectors that grant or increase an allowance.
+ *
+ * Gating only on `approve()` meant every other allowance-granting entrypoint
+ * skipped the guard entirely: `increaseAllowance` raises the same allowance,
+ * SafeERC20's `forceApprove`/`safeApprove` set one on the caller's behalf,
+ * Permit2's `approve`/`permit` grant spend rights, and DAI-style `permit` sets
+ * an allowance from a signature. A guard that covers one selector is a guard
+ * an attacker routes around.
+ *
+ * Every value here was computed from its signature with keccak256, not copied
+ * from memory — an incorrect selector in this list is a silent hole.
+ */
+const ALLOWANCE_SELECTORS = new Set([
+  "0x095ea7b3", // approve(address,uint256)
+  "0x39509351", // increaseAllowance(address,uint256)
+  "0x61f49ed6", // forceApprove(address,address,uint256)          [SafeERC20]
+  "0xeb5625d9", // safeApprove(address,address,uint256)           [SafeERC20]
+  "0xf9255c1f", // safeIncreaseAllowance(address,address,uint256) [SafeERC20]
+  "0x87517c45", // approve(address,address,uint160,uint48)        [Permit2]
+  "0xd505accf", // permit(address,address,uint256,uint256,uint8,bytes32,bytes32)      [EIP-2612]
+  "0x8fcbaf0c", // permit(address,address,uint256,uint256,bool,uint8,bytes32,bytes32) [DAI]
+  "0x2b67b570", // permit(address,PermitSingle,bytes)             [Permit2]
+  "0x2a2d80d1", // permitBatch                                    [Permit2]
+]);
+
+export function isApprovalCall(data) {
+  const hex = String(data || "").toLowerCase();
+  if (hex.length < 10) return false;
+  return ALLOWANCE_SELECTORS.has(hex.slice(0, 10));
+}
+
+export { ALLOWANCE_SELECTORS };
+
+export function decodeApproveCalldata(data) {
+  if (!isApprovalCall(data)) throw new Error("approval calldata required");
+  const hex = String(data || "").toLowerCase();
+  const selector = hex.slice(0, 10);
+  const words = hex.slice(10).match(/.{1,64}/g) || [];
+  const wordAddr = (i) => (words[i] ? "0x" + words[i].slice(24) : null);
+  const wordBig = (i) => (words[i] ? BigInt("0x" + words[i]) : null);
+
+  // Each allowance-granting shape puts (spender, amount) in different slots.
+  // Detecting a selector without being able to decode it made every non-approve
+  // allowance call unsignable — the guard recognised the tx, demanded a bound
+  // guard, then threw "invalid approve calldata" because it only knew how to
+  // read approve(). Recognition and decoding must cover the same set.
+  let spenderRaw = null;
+  let amountRaw = null;
+
+  switch (selector) {
+    // approve(address spender, uint256 value)
+    // increaseAllowance(address spender, uint256 addedValue)
+    case "0x095ea7b3":
+    case "0x39509351":
+      spenderRaw = wordAddr(0);
+      amountRaw = wordBig(1);
+      break;
+    // SafeERC20 helpers: (IERC20 token, address spender, uint256 value)
+    case "0x61f49ed6": // forceApprove
+    case "0xeb5625d9": // safeApprove
+    case "0xf9255c1f": // safeIncreaseAllowance
+      spenderRaw = wordAddr(1);
+      amountRaw = wordBig(2);
+      break;
+    // EIP-2612 permit(owner, spender, value, deadline, v, r, s)
+    case "0xd505accf":
+      spenderRaw = wordAddr(1);
+      amountRaw = wordBig(2);
+      break;
+    // DAI permit(holder, spender, nonce, expiry, allowed, v, r, s) — `allowed`
+    // is a boolean, so an unlimited allowance is expressed as true.
+    case "0x8fcbaf0c": {
+      spenderRaw = wordAddr(1);
+      const allowed = wordBig(4);
+      amountRaw = allowed === 0n ? 0n : (1n << 256n) - 1n;
+      break;
+    }
+    // Permit2 approve(token, spender, uint160 amount, uint48 expiration)
+    case "0x87517c45":
+      spenderRaw = wordAddr(1);
+      amountRaw = wordBig(2);
+      break;
+    default:
+      // A selector we recognise but cannot decode must FAIL, not silently pass:
+      // an undecodable allowance cannot be bounded.
+      throw new Error(`approval selector ${selector} is recognised but not decodable; refusing to bound it`);
+  }
+
+  if (spenderRaw == null || amountRaw == null) throw new Error("invalid approve calldata");
+  return {
+    spender: normalAddress(spenderRaw, "approval spender"),
+    amount: amountString(amountRaw, "approval amount", { allowZero: true }),
+    selector,
+  };
+}
+
+export function normalizeApprovalRequests(value) {
+  if (!value) return [];
+  const raw = Array.isArray(value) ? value : [value];
+  return raw
+    .filter(Boolean)
+    .map((approval) => ({
+      token: normalAddress(approval.token, "approval token"),
+      spender: normalAddress(approval.spender, "approval spender"),
+      amount: amountString(approval.amount, "approval amount"),
+    }));
+}
+
+export function createApprovalGuard({
+  chainId,
+  token,
+  spender,
+  amount,
+  provider,
+  routeVenue,
+  routeGuard,
+  purpose,
+  nowMs = Date.now(),
+  ttlMs = DEFAULT_APPROVAL_TTL_MS,
+} = {}) {
+  const approvalPurpose = String(purpose || "").trim();
+  const guard = {
+    mode: "approval",
+    chainId: Number(chainId),
+    token: normalAddress(token, "approval token"),
+    spender: normalAddress(spender, "approval spender"),
+    amount: amountString(amount, "approval amount", { allowZero: approvalPurpose === "revoke" }),
+    provider: String(provider || "").trim() || "unknown",
+    routeVenue: routeVenue ? normalAddress(routeVenue, "approval route venue") : normalAddress(spender, "approval route venue"),
+    issuedAtMs: Number(nowMs),
+    expiresAtMs: Number(nowMs) + Number(ttlMs || DEFAULT_APPROVAL_TTL_MS),
+  };
+  if (approvalPurpose) guard.purpose = approvalPurpose;
+  if (!Number.isFinite(guard.chainId)) throw new Error("approval chainId required");
+  if (!Number.isFinite(guard.issuedAtMs) || !Number.isFinite(guard.expiresAtMs) || guard.expiresAtMs <= guard.issuedAtMs) {
+    throw new Error("approval guard expiry invalid");
+  }
+  if (routeGuard) {
+    guard.routeGuardHash = keccak256(toUtf8Bytes(canonicalJson(routeGuard)));
+  }
+  return guard;
+}
+
+export function buildApprovalTransaction(approval, {
+  chainId,
+  provider,
+  routeTransaction,
+  routeGuard,
+  nowMs = Date.now(),
+  ttlMs = DEFAULT_APPROVAL_TTL_MS,
+} = {}) {
+  const [req] = normalizeApprovalRequests(approval);
+  if (!req) throw new Error("approval request required");
+  const madApproval = createApprovalGuard({
+    chainId,
+    token: req.token,
+    spender: req.spender,
+    amount: req.amount,
+    provider,
+    routeVenue: routeTransaction?.to || req.spender,
+    routeGuard,
+    nowMs,
+    ttlMs,
+  });
+  return {
+    chainId: Number(chainId),
+    to: req.token,
+    data: ERC20.encodeFunctionData("approve", [req.spender, req.amount]),
+    value: "0x0",
+    madApproval,
+  };
+}
+
+export function buildApprovalRevokeTransaction(approval, {
+  chainId,
+  provider,
+  nowMs = Date.now(),
+  ttlMs = DEFAULT_APPROVAL_TTL_MS,
+} = {}) {
+  const token = normalAddress(approval?.token, "approval token");
+  const spender = normalAddress(approval?.spender, "approval spender");
+  const madApproval = createApprovalGuard({
+    chainId,
+    token,
+    spender,
+    amount: "0",
+    provider,
+    routeVenue: spender,
+    purpose: "revoke",
+    nowMs,
+    ttlMs,
+  });
+  return {
+    chainId: Number(chainId),
+    to: token,
+    data: ERC20.encodeFunctionData("approve", [spender, "0"]),
+    value: "0x0",
+    madApproval,
+  };
+}
+
+export function assertApprovalGuard(guard, tx = {}, { chainId, nowMs = Date.now() } = {}) {
+  if (!guard || guard.mode !== "approval") throw new Error("approval guard required");
+  const txChainId = Number(tx.chainId ?? chainId);
+  if (Number(guard.chainId) !== txChainId) throw new Error(`approval chain mismatch: expected ${txChainId}, got ${guard.chainId}`);
+  const token = normalAddress(tx.to, "approval token");
+  if (normalAddress(guard.token, "approval token") !== token) throw new Error("approval token mismatch");
+  const decoded = decodeApproveCalldata(tx.data);
+  if (normalAddress(guard.spender, "approval spender") !== decoded.spender) throw new Error("approval spender mismatch");
+  const isRevoke = String(guard.purpose || "") === "revoke";
+  if (decoded.amount === "0" && !isRevoke) throw new Error("zero approval amount requires revoke purpose");
+  if (amountString(guard.amount, "approval amount", { allowZero: isRevoke }) !== decoded.amount) throw new Error("approval amount mismatch");
+  const value = tx.value == null ? 0n : BigInt(String(tx.value).startsWith("0x") ? String(tx.value) : String(tx.value));
+  if (value !== 0n) throw new Error("approval tx value must be zero");
+  // Same clock fail-closed as every other guard. A missing expiresAtMs used to
+  // make Number(undefined) <= now evaluate false, turning a captured approval
+  // into a permanent re-grant. NaN/null/"later" clocks had the same effect.
+  const { now } = assertFreshWindow(guard, nowMs, "approval guard");
+  if (Number(guard.issuedAtMs) > now + 5_000) throw new Error("approval guard issued in the future");
+  const allowedSpenders = venuesFor(txChainId);
+  if (!allowedSpenders.has(decoded.spender)) {
+    if (String(guard.provider || "") === "morpho") {
+      assertVaultApprovalAttestation(tx.madVault || tx.vaultGuard, tx, guard, { chainId: txChainId, nowMs });
+      return {
+        chainId: txChainId,
+        token,
+        spender: decoded.spender,
+        amount: decoded.amount,
+        provider: guard.provider || null,
+      };
+    }
+    throw new Error(`approval spender ${decoded.spender} not allowlisted for chain ${txChainId}`);
+  }
+  if (String(guard.provider || "") === "gmx") {
+    assertGmxApprovalAttestation(tx.madGmx || tx.gmxGuard, tx, guard, { chainId: txChainId, nowMs });
+  }
+  if (guard.routeVenue && !allowedSpenders.has(normalAddress(guard.routeVenue, "approval route venue"))) {
+    throw new Error(`approval route venue ${guard.routeVenue} not allowlisted for chain ${txChainId}`);
+  }
+  return {
+    chainId: txChainId,
+    token,
+    spender: decoded.spender,
+    amount: decoded.amount,
+    provider: guard.provider || null,
+  };
+}

package/src/attestation-secret.mjs

@@ -0,0 +1,88 @@
+// Shared secret resolution for attestation modules.
+//
+// Attestations are minted inside the trusted boundary to bind a dynamic execution
+// target (a route, a vault, a GMX order) so that model-authored JSON cannot become
+// authorization on its own. That makes the secret's LOOKUP path security-relevant:
+// reading it from a wrong or attacker-writable location is as bad as leaking it.
+//
+// Extracted here because three modules had drifted into three near-identical copies,
+// each carrying a hardcoded operator home directory -- which is both a leak of the
+// author's environment and simply broken for anyone else, since a public user has no
+// matching private home path.
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Candidate env-file locations, in priority order.
+ *
+ * Resolved from the CURRENT user's home, never a baked-in absolute path.
+ */
+function envFileCandidates() {
+  // Under test, do NOT read the developer's real ~/.config secrets. A suite
+  // that silently picks up a secret on the maintainer's box and finds none on a
+  // contributor's machine is not reproducible, and the difference shows up as
+  // mysterious pass/fail drift rather than an honest failure.
+  if (process.env.ORACLE_TEST_ISOLATE_SECRETS === "1") {
+    const explicitOnly = (process.env.ORACLE_EXEC_ENV_FILE || "").trim();
+    return explicitOnly ? [explicitOnly] : [];
+  }
+
+  const explicit = (
+    process.env.ORACLE_EXEC_ENV_FILE ||
+    process.env.MAD_EXEC_ENV_FILE || // legacy name, kept for existing deployments
+    ""
+  ).trim();
+
+  const home = homedir();
+  return [
+    explicit,
+    join(home, ".config", "oracle", "exec.env"),
+    join(home, ".config", "mad-desk", "exec.env"), // legacy dir
+  ].filter(Boolean);
+}
+
+/**
+ * Resolve an attestation secret.
+ *
+ * Order: explicit argument, then env var, then an env FILE. The file fallback exists
+ * so a long-lived deployment can keep the secret out of the process environment
+ * (where it would show up in `ps` output and child processes).
+ *
+ * @param {string|undefined} secret explicit override
+ * @param {string} primaryEnv e.g. "ORACLE_ROUTE_ATTESTATION_SECRET"
+ * @param {string} legacyEnv e.g. "MAD_ROUTE_ATTESTATION_SECRET"
+ * @returns {string}
+ * @throws when no secret can be found -- fail closed, never mint unsigned
+ */
+export function resolveAttestationSecret(secret, primaryEnv, legacyEnv) {
+  let value = secret ?? process.env[primaryEnv] ?? process.env[legacyEnv];
+
+  if (!String(value || "").trim()) {
+    for (const envFile of envFileCandidates()) {
+      try {
+        const txt = readFileSync(envFile, "utf8");
+        // Accept either name in the file, primary winning.
+        const m =
+          txt.match(new RegExp(`^${primaryEnv}=(.*)$`, "m")) ||
+          txt.match(new RegExp(`^${legacyEnv}=(.*)$`, "m"));
+        if (m) {
+          value = m[1].trim();
+          if (value) break;
+        }
+      } catch {
+        // Unreadable or absent: try the next candidate. A missing optional file is
+        // not an error; running out of candidates is, and that is handled below.
+      }
+    }
+  }
+
+  if (!String(value || "").trim()) {
+    throw new Error(
+      `${primaryEnv} required for attestation. Set it in the environment, or place ` +
+        `${primaryEnv}=<value> in ~/.config/oracle/exec.env`,
+    );
+  }
+  return value;
+}