@oracle-agent/oracle 0.13.1 → 0.14.0

package/src/address-book.mjs

@@ -0,0 +1,208 @@
+/**
+ * Durable labeled address book for owner/agent/counterparty wallets.
+ *
+ * On by default: remembering who an address belongs to is a read/annotate
+ * concern, not an execution one. Nothing here signs, and no private key,
+ * passphrase, or seed is ever accepted or stored.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ORACLE_CONFIG_DIR, env } from "./oracle-env.mjs";
+
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/;
+const FORBIDDEN_KEYS = new Set([
+  "privatekey", "private_key", "secret", "seed", "mnemonic", "passphrase", "signature", "keystore",
+]);
+
+// Exact-name matching missed obvious aliases (secretKey, seedPhrase, wif,
+// keyMaterial, xprv...). Match on a normalized key instead: strip separators,
+// lowercase, then look for any secret-ish token as a substring. A label store
+// has no legitimate field containing these words.
+const FORBIDDEN_TOKENS = [
+  "privatekey", "privkey", "secretkey", "secret", "seedphrase", "seed", "mnemonic",
+  "passphrase", "password", "keystore", "keymaterial", "signature", "wif",
+  "xprv", "xpriv", "apikey", "bearer", "credential",
+];
+
+// Key-shaped values must not be persisted even in a free-text field. WIF, xprv,
+// and BIP39 shapes are unambiguous. A bare 64-hex string is NOT — a raw EVM
+// private key and a bytes32 tx hash are byte-identical — so that rule matches
+// only when the WHOLE field is the hex blob. "paid via tx 0xabc..." is a note,
+// not a leaked key.
+const KEY_SHAPED_VALUE = [
+  /\b[5KL][1-9A-HJ-NP-Za-km-z]{50,51}\b/,
+  /\bxprv[0-9A-Za-z]{50,}\b/,
+  /\b(?:[a-z]{3,8}\s+){11,}[a-z]{3,8}\b/i,
+];
+
+const BARE_32_BYTE_HEX = /^\s*(?:0x)?[0-9a-fA-F]{64}\s*$/;
+
+function normalizeKeyName(key) {
+  return String(key).toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function assertNoSecretKeyName(key, path) {
+  const normalized = normalizeKeyName(key);
+  if (FORBIDDEN_KEYS.has(String(key).toLowerCase()) || FORBIDDEN_TOKENS.some((t) => normalized.includes(t))) {
+    throw new Error(`address-book: ${path} is forbidden; the book stores labels, never key material`);
+  }
+}
+
+function assertNoSecretValue(value, path) {
+  if (typeof value !== "string") return;
+  if (KEY_SHAPED_VALUE.some((re) => re.test(value)) || BARE_32_BYTE_HEX.test(value)) {
+    throw new Error(`address-book: ${path} looks like key material; the book stores labels, never key material`);
+  }
+}
+
+export function addressBookPath() {
+  const override = env("ORACLE_ADDRESS_BOOK", "MAD_ADDRESS_BOOK", "");
+  if (override) return path.resolve(override);
+  const dir = env("ORACLE_CONFIG_DIR", "MAD_CONFIG_DIR", ORACLE_CONFIG_DIR);
+  return path.join(dir, "address-book.json");
+}
+
+function assertNoSecrets(input, path = "field") {
+  if (Array.isArray(input)) {
+    input.forEach((item, i) => assertNoSecrets(item, `${path}[${i}]`));
+    return;
+  }
+  if (!input || typeof input !== "object") {
+    assertNoSecretValue(input, path);
+    return;
+  }
+  for (const [key, value] of Object.entries(input)) {
+    assertNoSecretKeyName(key, key);
+    assertNoSecrets(value, key);
+  }
+}
+
+function normalizeAddress(value) {
+  const address = String(value || "").trim();
+  if (!ADDR_RE.test(address)) throw new Error("address-book: address must be 0x + 40 hex characters");
+  return address.toLowerCase();
+}
+
+function text(value, max) {
+  if (value == null || value === "") return null;
+  return String(value).slice(0, max);
+}
+
+function emptyBook() {
+  return { version: 1, updatedAt: null, entries: [] };
+}
+
+function normalizeEntry(entry) {
+  return {
+    address: String(entry.address).toLowerCase(),
+    label: text(entry.label, 80) || "unknown",
+    who: text(entry.who, 120),
+    role: text(entry.role, 40),
+    chainIds: Array.isArray(entry.chainIds) ? entry.chainIds.map(Number).filter(Number.isFinite) : [],
+    notes: text(entry.notes, 500),
+    source: text(entry.source, 80),
+    firstSeenAt: entry.firstSeenAt || null,
+    lastSeenAt: entry.lastSeenAt || null,
+  };
+}
+
+export function readAddressBook() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(addressBookPath(), "utf8"));
+    if (!raw || typeof raw !== "object") return emptyBook();
+    const entries = Array.isArray(raw.entries) ? raw.entries : [];
+    return {
+      version: 1,
+      updatedAt: raw.updatedAt || null,
+      entries: entries
+        .filter((entry) => entry && typeof entry === "object" && ADDR_RE.test(String(entry.address || "")))
+        .map(normalizeEntry),
+    };
+  } catch {
+    return emptyBook();
+  }
+}
+
+function writeBook(book) {
+  const file = addressBookPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const payload = { ...book, version: 1, updatedAt: new Date().toISOString() };
+  const tmp = path.join(path.dirname(file), `.address-book.${process.pid}.tmp`);
+  fs.writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    /* best effort on platforms without chmod semantics */
+  }
+  return payload;
+}
+
+export function listAddresses(filter = {}) {
+  const book = readAddressBook();
+  let entries = book.entries;
+  if (filter.role) entries = entries.filter((entry) => entry.role === String(filter.role));
+  if (filter.who) {
+    const query = String(filter.who).toLowerCase();
+    entries = entries.filter(
+      (entry) => (entry.who || "").toLowerCase().includes(query) || (entry.label || "").toLowerCase().includes(query),
+    );
+  }
+  if (filter.q) {
+    const query = String(filter.q).toLowerCase();
+    entries = entries.filter(
+      (entry) =>
+        entry.address.includes(query) ||
+        (entry.label || "").toLowerCase().includes(query) ||
+        (entry.who || "").toLowerCase().includes(query) ||
+        (entry.notes || "").toLowerCase().includes(query),
+    );
+  }
+  return { updatedAt: book.updatedAt, count: entries.length, entries };
+}
+
+export function lookupAddress(address) {
+  const normalized = normalizeAddress(address);
+  const entries = readAddressBook().entries.filter((entry) => entry.address === normalized);
+  return { address: normalized, found: entries.length > 0, entries };
+}
+
+export function rememberAddress(input = {}) {
+  assertNoSecrets(input);
+  const address = normalizeAddress(input.address);
+  const label = text(input.label ?? input.role, 80) || "wallet";
+  const now = new Date().toISOString();
+  const book = readAddressBook();
+  const index = book.entries.findIndex((entry) => entry.address === address && entry.label === label);
+  const entry = normalizeEntry({
+    address,
+    label,
+    who: input.who,
+    role: input.role,
+    chainIds: input.chainIds,
+    notes: input.notes,
+    source: input.source || "agent",
+    firstSeenAt: index >= 0 ? book.entries[index].firstSeenAt || now : now,
+    lastSeenAt: now,
+  });
+  if (index >= 0) book.entries[index] = entry;
+  else book.entries.push(entry);
+  const rank = (role) => (role === "agent" ? 0 : role === "owner" ? 1 : 2);
+  book.entries.sort(
+    (a, b) => rank(a.role) - rank(b.role) || a.label.localeCompare(b.label) || a.address.localeCompare(b.address),
+  );
+  const saved = writeBook(book);
+  return { ok: true, entry, count: saved.entries.length };
+}
+
+export function forgetAddress(address, label = null) {
+  const normalized = normalizeAddress(address);
+  const book = readAddressBook();
+  const before = book.entries.length;
+  book.entries = book.entries.filter((entry) => {
+    if (entry.address !== normalized) return true;
+    return label == null ? false : entry.label !== String(label);
+  });
+  writeBook(book);
+  return { ok: true, removed: before - book.entries.length, count: book.entries.length };
+}

package/src/agent-auth.mjs

@@ -0,0 +1,206 @@
+// 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 = "") {
+  // Hardening: never accept a raw key string/hex. Real ethers Wallet/Signer objects are OK
+  // (they may expose .privateKey internally — that is the wallet, not a mistaken string).
+  if (typeof ownerSigner === "string" || typeof ownerSigner === "number") {
+    throw new Error("mintCapability refuses raw key material — pass an ethers Signer from the owner wallet");
+  }
+  if (!ownerSigner || typeof ownerSigner.signMessage !== "function" || typeof ownerSigner.getAddress !== "function") {
+    throw new Error("mintCapability: ownerSigner must implement getAddress() and signMessage()");
+  }
+  // Bare POJO that only carries a key field (no prototype signer) — refuse.
+  const proto = Object.getPrototypeOf(ownerSigner);
+  if (proto === Object.prototype || proto === null) {
+    if (ownerSigner.privateKey || ownerSigner.mnemonic) {
+      throw new Error("mintCapability refuses plain objects that only carry privateKey/mnemonic");
+    }
+  }
+  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 };
+}