@oracle-agent/oracle 0.13.1 → 0.14.0

package/src/public-api/metering.mjs

@@ -0,0 +1,111 @@
+/**
+ * Metered API access for the public data plane.
+ *
+ * The plane already serves portfolio, approvals and NFTs across 14 chains
+ * including Solana and Bitcoin. That is the product Zerion and Zapper charge
+ * for, and Oracle gives it away to anyone who can reach the port. Per-IP rate
+ * limiting stops abuse but cannot tell a paying integrator from a stranger.
+ *
+ * Design constraints, inherited from the modules this sits next to:
+ *
+ *   - No database. Keys are self-describing and HMAC-signed, so verification
+ *     needs only the secret.
+ *   - No secrets in the key. A key names a tier and an expiry, nothing else.
+ *   - Injected clock and store. Same-inputs-same-output, like grants.mjs.
+ *   - Fails CLOSED on a bad signature, OPEN on no key at all — an unkeyed
+ *     request is the existing free tier, not an error, so this cannot break
+ *     the current public plane.
+ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export const TIERS = Object.freeze({
+  // Requests per minute. `free` mirrors today's unauthenticated behaviour so
+  // adding this layer changes nothing for existing callers.
+  free: Object.freeze({ name: "free", rpm: 30, chains: 14, history: false }),
+  build: Object.freeze({ name: "build", rpm: 300, chains: 14, history: true }),
+  scale: Object.freeze({ name: "scale", rpm: 3000, chains: 14, history: true }),
+});
+
+export const DEFAULT_TIER = "free";
+
+function sign(payload, secret) {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+/**
+ * Mint a key. Operator-side only — this is never called from a request path.
+ */
+export function issueKey({ subject, tier = "build", secret, ttlMs = 365 * 24 * 60 * 60 * 1000, now = Date.now() }) {
+  if (!TIERS[tier]) throw new Error(`unknown tier: ${tier}`);
+  if (!subject) throw new Error("subject required");
+  if (!secret) throw new Error("secret required");
+  const payload = Buffer.from(
+    JSON.stringify({ sub: String(subject), tier, exp: now + ttlMs }),
+  ).toString("base64url");
+  return `ok_${payload}.${sign(payload, secret)}`;
+}
+
+/**
+ * Verify a key. Returns the resolved tier record, never throws on bad input.
+ *
+ * An absent key resolves to the free tier: the public plane must keep working
+ * for anonymous callers. A PRESENT but invalid key resolves to `null` so the
+ * caller can 401 — silently downgrading a forged key to free would let an
+ * attacker probe for which keys exist.
+ */
+export function readKey(raw, { secret, now = Date.now() } = {}) {
+  const token = String(raw || "").trim();
+  if (!token) return { tier: TIERS[DEFAULT_TIER], subject: null, anonymous: true };
+  if (!token.startsWith("ok_")) return null;
+  try {
+    const [payload, signature] = token.slice(3).split(".");
+    if (!payload || !signature) return null;
+    const expected = Buffer.from(sign(payload, secret));
+    const supplied = Buffer.from(signature);
+    // Length first: timingSafeEqual throws on a length mismatch.
+    if (expected.length !== supplied.length || !timingSafeEqual(expected, supplied)) return null;
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (!claims?.sub || !TIERS[claims.tier]) return null;
+    if (!Number.isFinite(claims.exp) || claims.exp < now) return null;
+    return { tier: TIERS[claims.tier], subject: claims.sub, anonymous: false, expiresAt: claims.exp };
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve the effective tier for a request. NFT status never changes access. */
+export function resolveAccess({ key, secret, now = Date.now() } = {}) {
+  const read = readKey(key, { secret, now });
+  if (read === null) return { ok: false, reason: "invalid-key" };
+  return { ok: true, tier: read.tier, subject: read.subject, anonymous: read.anonymous };
+}
+
+/**
+ * Usage accounting over an injected store, so the caller owns persistence.
+ * Store shape: Map<subject, { windowStart, count }>.
+ */
+export function meter({ store, subject, rpm, now = Date.now(), windowMs = 60_000 }) {
+  const id = subject || "anonymous";
+  const entry = store.get(id);
+  if (!entry || now - entry.windowStart >= windowMs) {
+    store.set(id, { windowStart: now, count: 1 });
+    return { allowed: true, remaining: rpm - 1, resetInMs: windowMs };
+  }
+  if (entry.count >= rpm) {
+    return { allowed: false, remaining: 0, resetInMs: entry.windowStart + windowMs - now };
+  }
+  entry.count += 1;
+  return { allowed: true, remaining: rpm - entry.count, resetInMs: entry.windowStart + windowMs - now };
+}
+
+/** Public, non-secret description of the plans. Safe to serve from the API. */
+export function describePlans() {
+  return Object.values(TIERS).map((t) => ({
+    tier: t.name,
+    requestsPerMinute: t.rpm,
+    chains: t.chains,
+    history: t.history,
+    price: t.name === "free" ? 0 : null,
+  }));
+}

package/src/public-control/aa-adapter.mjs

@@ -0,0 +1,402 @@
+// Oracle Control — ERC-4337 session-key on-chain adapter (Slice E).
+//
+// Wires the provider-neutral session grant produced by session-key-model.mjs
+// to a real account-abstraction encoding stack (viem) so a grant can be
+// turned into:
+//   1. install calldata  — enable a scoped session key on the owner's smart
+//      account (encodeSessionKeyInstall)
+//   2. an unsigned ERC-4337 UserOperation envelope that carries that calldata
+//      (buildUserOperation)
+//   3. revoke calldata   — disable a session key on the smart account
+//      (revokeSessionKey)
+//
+// Hard boundaries (same posture as session-key-model.mjs / policy-schema.mjs):
+//   - No wallet/AA SDK holds or requests the owner's main key here. This
+//     module only ASSEMBLES UNSIGNED data. Signing is the user's wallet,
+//     off-infrastructure — never this adapter, never a server, never a log.
+//   - No live RPC/bundler calls. Any chain read this adapter needs (the
+//     account's current ERC-4337 nonce) goes through a caller-injected
+//     `client` object (duck-typed to viem's PublicClient.readContract shape)
+//     so tests can supply a fully offline mock and production code can pass
+//     a real viem PublicClient without this file changing.
+//   - Import ONLY from ./session-key-model.mjs (grant shape/lifecycle) and
+//     ./policy-schema.mjs (not currently needed here, left available) plus
+//     viem and node builtins. NEVER from the private executor stack
+//     (get-signer.mjs, keystore.mjs, exec-policy.mjs, local-signer/*,
+//     adapters/*, mint-capability.mjs) — this module must never be wired to
+//     private operator wallet.
+//   - Fail-closed: a grant that is not ACTIVE (per session-key-model's own
+//     sessionStatus — expired, revoked, or malformed) is refused BEFORE any
+//     calldata is computed. A tampered "grant-shaped" object whose id does
+//     not match its own fields is refused for the same reason.
+//
+// Session-key module ABI note: real deployed session-key modules differ
+// per AA stack (Safe allowance/session module, Kernel/ZeroDev session
+// validator, Biconomy Nexus session module, a bespoke
+// permissionless/viem session account). This adapter defines the ERC-4337
+// envelope and a documented, generic "install/revoke a scoped session key"
+// function interface (DEFAULT_SESSION_MODULE_ABI) that mirrors the common
+// shape those modules expose. Wiring to one specific deployed module is a
+// matter of passing that module's real `abi`/`moduleAddress` via opts — the
+// grant validation, determinism, and unsigned-userOp assembly below do not
+// change. This file never invents a contract address: `moduleAddress` is a
+// required caller-supplied parameter, not a hardcoded guess.
+
+import {
+  encodeFunctionData,
+  keccak256,
+  stringToHex,
+  numberToHex,
+  isAddress,
+  isHex,
+  getAddress,
+} from "viem";
+
+import {
+  canonicalJson,
+  computeSessionId,
+  sessionStatus,
+  SESSION_STATUS,
+} from "./session-key-model.mjs";
+
+/** Canonical ERC-4337 EntryPoint v0.7 address (public, chain-agnostic
+ *  constant — not private infrastructure). Callers may override
+ *  via opts.entryPoint for a different EntryPoint version/deployment. */
+export const ENTRYPOINT_V07 = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
+
+/** Minimal EntryPoint ABI slice this adapter needs (nonce read only — this
+ *  adapter never calls the EntryPoint's mutating methods). */
+export const ENTRYPOINT_ABI = [
+  {
+    type: "function",
+    name: "getNonce",
+    stateMutability: "view",
+    inputs: [
+      { name: "sender", type: "address" },
+      { name: "key", type: "uint192" },
+    ],
+    outputs: [{ name: "nonce", type: "uint256" }],
+  },
+];
+
+/**
+ * Generic "session-key module" interface most ERC-4337 session-key
+ * validators expose in one shape or another. This is the DEFAULT abi used
+ * when the caller does not supply a provider-specific one via opts.abi — see
+ * the module-level doc comment above for why the exact selector is left
+ * swappable rather than hardcoded per provider.
+ */
+export const DEFAULT_SESSION_MODULE_ABI = [
+  {
+    type: "function",
+    name: "installSessionKey",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "sessionId", type: "bytes32" },
+      { name: "agent", type: "address" },
+      { name: "validAfter", type: "uint48" },
+      { name: "validUntil", type: "uint48" },
+      { name: "actionsHash", type: "bytes32" },
+      { name: "targets", type: "address[]" },
+      { name: "maxValueWei", type: "uint256" },
+      { name: "maxGasWei", type: "uint256" },
+    ],
+    outputs: [],
+  },
+  {
+    type: "function",
+    name: "revokeSessionKey",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "sessionId", type: "bytes32" }],
+    outputs: [],
+  },
+];
+
+function fail(message) {
+  throw new Error(`aa-adapter: ${message}`);
+}
+
+function requireModuleAddress(moduleAddress) {
+  if (typeof moduleAddress !== "string" || !isAddress(moduleAddress)) {
+    fail(
+      "opts.moduleAddress is required and must be a valid 0x address of the " +
+        "deployed session-key module on the owner's smart account (this " +
+        "adapter never guesses/hardcodes a contract address)"
+    );
+  }
+  return getAddress(moduleAddress);
+}
+
+/** Re-derive a grant's identity fields (everything except `id`) and confirm
+ *  they hash to the grant's own `id`, defending against a hand-crafted
+ *  "grant-shaped" object that never went through createSessionGrant(). */
+function assertGrantIntegrity(grant) {
+  if (!grant || grant.mode !== "oracle-session-grant") {
+    fail("input is not a valid session-key-model grant (missing/wrong mode)");
+  }
+  const { id, ...identity } = grant;
+  const recomputed = computeSessionId(identity);
+  if (recomputed !== id) {
+    fail("grant integrity check failed: id does not match grant fields (tampered or hand-built object)");
+  }
+}
+
+/** Refuse to touch out-of-policy grants (expired/revoked/invalid) before any
+ *  calldata is computed. `opts` is forwarded to session-key-model's
+ *  sessionStatus() (nowMs, revocation registry/Set/array). */
+function assertGrantEncodable(grant, opts = {}) {
+  assertGrantIntegrity(grant);
+  const status = sessionStatus(grant, opts);
+  if (status !== SESSION_STATUS.ACTIVE) {
+    fail(`refusing to encode calldata for a ${status} session (${grant.id})`);
+  }
+}
+
+function msToSecondsUint48(ms, label) {
+  const seconds = Math.floor(Number(ms) / 1000);
+  if (!Number.isFinite(seconds) || seconds < 0 || seconds > 0xffffffffffff) {
+    fail(`${label} does not fit a uint48 seconds timestamp`);
+  }
+  return BigInt(seconds);
+}
+
+/**
+ * Deterministic install calldata for enabling a session-key-model grant as a
+ * scoped session key on the owner's ERC-4337 smart account.
+ *
+ * Refuses (throws, no calldata returned) when the grant is not ACTIVE —
+ * expired, revoked, or fails its own integrity check — per assertGrantEncodable.
+ *
+ * @param {object} grant  output of session-key-model.createSessionGrant()
+ * @param {object} opts
+ * @param {string} opts.moduleAddress  REQUIRED — deployed session-key module address
+ * @param {Array}  [opts.abi]          override for DEFAULT_SESSION_MODULE_ABI
+ * @param {number} [opts.nowMs]        forwarded to sessionStatus() for the active check
+ * @param {object|Set|string[]} [opts.revocation]  forwarded to sessionStatus()
+ * @returns {{ to: string, data: `0x${string}`, value: string }}
+ */
+export function encodeSessionKeyInstall(grant, opts = {}) {
+  assertGrantEncodable(grant, opts);
+  const moduleAddress = requireModuleAddress(opts.moduleAddress);
+  const abi = opts.abi ?? DEFAULT_SESSION_MODULE_ABI;
+
+  const agent = getAddress(grant.agent);
+  const targets = grant.targets.map((t) => getAddress(t));
+  const validAfter = msToSecondsUint48(grant.issuedAtMs, "issuedAtMs");
+  const validUntil = msToSecondsUint48(grant.expiresAtMs, "expiresAtMs");
+  // actionsHash: keccak256 over the canonical (already-sorted, deduped) JSON
+  // of the granted action ids — same convention session-key-model.mjs uses
+  // for computeSessionId, so it hashes identically everywhere.
+  const actionsHash = keccak256(stringToHex(canonicalJson(grant.actions)));
+  const maxValueWei = BigInt(grant.maxValueWei);
+  // grant.maxGasWei may be null (no independent gas cap set at the
+  // session-key-model layer); encoded as 0. The deployed module's own
+  // convention decides how 0 is interpreted (commonly "not independently
+  // capped here" — see docs/public-self-custody-aa-adapter.md).
+  const maxGasWei = grant.maxGasWei == null ? 0n : BigInt(grant.maxGasWei);
+
+  const data = encodeFunctionData({
+    abi,
+    functionName: "installSessionKey",
+    args: [grant.id, agent, validAfter, validUntil, actionsHash, targets, maxValueWei, maxGasWei],
+  });
+
+  return { to: moduleAddress, data, value: "0x0" };
+}
+
+/**
+ * Deterministic revoke calldata for disabling a session key on the owner's
+ * smart account. Accepts either a full grant object (its `.id` is used) or
+ * a raw session id string. Unlike install, revoke is allowed even for a
+ * grant that is already expired/revoked (revocation is idempotent per
+ * session-key-model's own createRevocationRegistry) — the only hard refusal
+ * here is a malformed session id.
+ *
+ * @param {object|string} grantOrSessionId
+ * @param {object} opts
+ * @param {string} opts.moduleAddress  REQUIRED — deployed session-key module address
+ * @param {Array}  [opts.abi]          override for DEFAULT_SESSION_MODULE_ABI
+ * @returns {{ to: string, data: `0x${string}`, value: string }}
+ */
+export function revokeSessionKey(grantOrSessionId, opts = {}) {
+  let sessionId;
+  if (typeof grantOrSessionId === "string") {
+    sessionId = grantOrSessionId;
+  } else if (grantOrSessionId && grantOrSessionId.mode === "oracle-session-grant") {
+    assertGrantIntegrity(grantOrSessionId);
+    sessionId = grantOrSessionId.id;
+  } else {
+    fail("revokeSessionKey requires a session-key-model grant object or a raw session id string");
+  }
+  if (!isHex(sessionId) || sessionId.length !== 66) {
+    fail("session id must be a 0x-prefixed 32-byte hash (as produced by computeSessionId)");
+  }
+
+  const moduleAddress = requireModuleAddress(opts.moduleAddress);
+  const abi = opts.abi ?? DEFAULT_SESSION_MODULE_ABI;
+
+  const data = encodeFunctionData({
+    abi,
+    functionName: "revokeSessionKey",
+    args: [sessionId],
+  });
+
+  return { to: moduleAddress, data, value: "0x0" };
+}
+
+const REQUIRED_GAS_FIELDS = [
+  "callGasLimit",
+  "verificationGasLimit",
+  "preVerificationGas",
+  "maxFeePerGas",
+  "maxPriorityFeePerGas",
+];
+
+function toBigIntField(value, label) {
+  if (value == null) fail(`${label} is required`);
+  let n;
+  try {
+    n = typeof value === "bigint" ? value : BigInt(value);
+  } catch {
+    fail(`${label} must be an integer, bigint, or 0x-hex string`);
+  }
+  if (n < 0n) fail(`${label} must not be negative`);
+  return n;
+}
+
+/**
+ * Assemble an UNSIGNED ERC-4337 v0.7 UserOperation envelope carrying the
+ * given callData (typically the output of encodeSessionKeyInstall /
+ * revokeSessionKey, but this function accepts any calldata — it does not
+ * re-check grant policy itself).
+ *
+ * This function never estimates gas and never fabricates fee data: every
+ * gas/fee field is a required, explicit caller input. The only chain read it
+ * performs is the ERC-4337 account nonce, and ONLY when `nonce` is not
+ * supplied directly — in that case it calls `client.readContract(...)`,
+ * duck-typed to viem's PublicClient shape, so:
+ *   - production code passes a real viem PublicClient and gets a real nonce
+ *   - tests pass a plain object with an async readContract() mock and NO
+ *     network call ever happens
+ *
+ * The returned object always has signature: "0x" (empty) and carries no key
+ * material of any kind — signing happens in the user's own wallet, off this
+ * adapter.
+ *
+ * @param {object} params
+ * @param {object} [params.client]  duck-typed viem PublicClient (readContract) — only used if nonce is omitted
+ * @param {string} [params.entryPoint]  defaults to ENTRYPOINT_V07
+ * @param {string} params.sender  smart account address
+ * @param {string} params.callData  0x-prefixed calldata to execute
+ * @param {string|number|bigint} [params.nonce]  explicit nonce override (skips client read)
+ * @param {string|number|bigint} [params.nonceKey]  EntryPoint nonce key (default 0)
+ * @param {string} [params.factory]  smart-account factory address (counterfactual deploy)
+ * @param {string} [params.factoryData]  factory calldata (required if factory is set)
+ * @param {string|number|bigint} params.callGasLimit
+ * @param {string|number|bigint} params.verificationGasLimit
+ * @param {string|number|bigint} params.preVerificationGas
+ * @param {string|number|bigint} params.maxFeePerGas
+ * @param {string|number|bigint} params.maxPriorityFeePerGas
+ * @param {string} [params.paymaster]
+ * @param {string|number|bigint} [params.paymasterVerificationGasLimit]  required if paymaster is set
+ * @param {string|number|bigint} [params.paymasterPostOpGasLimit]  required if paymaster is set
+ * @param {string} [params.paymasterData]  defaults to "0x"
+ */
+export async function buildUserOperation(params = {}) {
+  const {
+    client,
+    entryPoint = ENTRYPOINT_V07,
+    sender,
+    callData,
+    nonce,
+    nonceKey = 0n,
+    factory,
+    factoryData,
+    paymaster,
+    paymasterVerificationGasLimit,
+    paymasterPostOpGasLimit,
+    paymasterData = "0x",
+  } = params;
+
+  if (typeof sender !== "string" || !isAddress(sender)) fail("params.sender must be a valid 0x address");
+  if (typeof callData !== "string" || !isHex(callData)) fail("params.callData must be 0x-prefixed hex");
+  if (typeof entryPoint !== "string" || !isAddress(entryPoint)) fail("params.entryPoint must be a valid 0x address");
+
+  const normalizedSender = getAddress(sender);
+  const normalizedEntryPoint = getAddress(entryPoint);
+
+  for (const field of REQUIRED_GAS_FIELDS) {
+    if (params[field] == null) fail(`params.${field} is required (this adapter does not estimate gas)`);
+  }
+  const callGasLimit = toBigIntField(params.callGasLimit, "callGasLimit");
+  const verificationGasLimit = toBigIntField(params.verificationGasLimit, "verificationGasLimit");
+  const preVerificationGas = toBigIntField(params.preVerificationGas, "preVerificationGas");
+  const maxFeePerGas = toBigIntField(params.maxFeePerGas, "maxFeePerGas");
+  const maxPriorityFeePerGas = toBigIntField(params.maxPriorityFeePerGas, "maxPriorityFeePerGas");
+
+  if ((factory == null) !== (factoryData == null)) {
+    fail("factory and factoryData must both be set (counterfactual deploy) or both omitted");
+  }
+  if (factory != null && (typeof factory !== "string" || !isAddress(factory))) {
+    fail("params.factory must be a valid 0x address");
+  }
+  if (factoryData != null && (typeof factoryData !== "string" || !isHex(factoryData))) {
+    fail("params.factoryData must be 0x-prefixed hex");
+  }
+
+  const hasPaymaster = paymaster != null;
+  if (hasPaymaster) {
+    if (typeof paymaster !== "string" || !isAddress(paymaster)) fail("params.paymaster must be a valid 0x address");
+    if (paymasterVerificationGasLimit == null || paymasterPostOpGasLimit == null) {
+      fail("paymasterVerificationGasLimit and paymasterPostOpGasLimit are required when paymaster is set");
+    }
+  }
+  if (paymasterData != null && (typeof paymasterData !== "string" || !isHex(paymasterData))) {
+    fail("params.paymasterData must be 0x-prefixed hex");
+  }
+
+  let resolvedNonce;
+  if (nonce != null) {
+    resolvedNonce = toBigIntField(nonce, "nonce");
+  } else {
+    if (!client || typeof client.readContract !== "function") {
+      fail(
+        "params.nonce was omitted and no usable client was provided — pass an explicit nonce or a " +
+          "client with an async readContract({address, abi, functionName, args}) method (a real viem " +
+          "PublicClient in production, a mock in tests; this adapter makes no network call itself)"
+      );
+    }
+    const key = toBigIntField(nonceKey, "nonceKey");
+    resolvedNonce = await client.readContract({
+      address: normalizedEntryPoint,
+      abi: ENTRYPOINT_ABI,
+      functionName: "getNonce",
+      args: [normalizedSender, key],
+    });
+    resolvedNonce = toBigIntField(resolvedNonce, "resolved nonce");
+  }
+
+  const userOp = {
+    sender: normalizedSender,
+    nonce: numberToHex(resolvedNonce),
+    factory: factory != null ? getAddress(factory) : null,
+    factoryData: factoryData ?? null,
+    callData,
+    callGasLimit: numberToHex(callGasLimit),
+    verificationGasLimit: numberToHex(verificationGasLimit),
+    preVerificationGas: numberToHex(preVerificationGas),
+    maxFeePerGas: numberToHex(maxFeePerGas),
+    maxPriorityFeePerGas: numberToHex(maxPriorityFeePerGas),
+    paymaster: hasPaymaster ? getAddress(paymaster) : null,
+    paymasterVerificationGasLimit: hasPaymaster ? numberToHex(toBigIntField(paymasterVerificationGasLimit, "paymasterVerificationGasLimit")) : null,
+    paymasterPostOpGasLimit: hasPaymaster ? numberToHex(toBigIntField(paymasterPostOpGasLimit, "paymasterPostOpGasLimit")) : null,
+    paymasterData: hasPaymaster ? paymasterData : null,
+    // Always empty: this adapter assembles UNSIGNED user operations only.
+    // No signature is computed, requested, or accepted here.
+    signature: "0x",
+  };
+
+  return Object.freeze(userOp);
+}
+
+export const _internal = { requireModuleAddress, assertGrantIntegrity, assertGrantEncodable, msToSecondsUint48 };