@oracle-agent/oracle 0.14.0 → 0.15.0

package/src/public-control/runtime-config.mjs

@@ -1,275 +0,0 @@
-// Oracle Control — public runtime config: chain/bundler/paymaster registry
-// (Slice K).
-//
-// This module is pure config parsing. It never makes a live network call and
-// never imports the private executor stack — its only job is to turn env
-// vars into a validated, in-memory registry of PUBLIC endpoints (chain
-// metadata, bundler URLs, paymaster URLs, and the public HTTP bind) that the
-// rest of Oracle Control (aa-adapter.mjs, bundler-client.mjs, http.mjs) can
-// read from.
-//
-// Hard boundaries for this file:
-//   - Imports ONLY from ./aa-adapter.mjs (ENTRYPOINT_V07 — the single source
-//     of truth for the deployed EntryPoint address this codebase targets)
-//     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, and holds no secrets of any kind.
-//   - bundlerUrl/paymasterUrl are treated as PUBLIC endpoints (the same way a
-//     public RPC URL is public) — but they are still scanned for anything
-//     secret-SHAPED (a bearer token, an api-key-looking query param, a raw
-//     private-key hex blob, a PEM block) and rejected outright if found.
-//     Fail closed: a config that looks like it's carrying a credential in a
-//     URL must never load.
-//   - resolveChain() fails closed on any chainId not in the registry — no
-//     silent fallback to a made-up chain.
-//   - entryPoint is never read from env or invented; it is always pinned to
-//     aa-adapter.mjs's ENTRYPOINT_V07 and asserted equal for every seeded
-//     chain, so a typo/drift in this file can never point a chain at the
-//     wrong EntryPoint deployment.
-//   - redactedConfig() strips the query string (and any embedded userinfo)
-//     off every bundler/paymaster URL before it is considered "safe to log"
-//     — even though the full URL already passed the secret-shape scan at
-//     load time, a log line is a wider blast radius than an in-memory
-//     config object, so this view is deliberately more conservative.
-
-import { ENTRYPOINT_V07 } from "./aa-adapter.mjs";
-
-export class RuntimeConfigError extends Error {
-  constructor(message) {
-    super(`runtime-config: ${message}`);
-    this.name = "RuntimeConfigError";
-  }
-}
-
-function fail(message) {
-  throw new RuntimeConfigError(message);
-}
-
-// ---------------------------------------------------------------------------
-// Secret-shape guard for public endpoint URLs (fail closed)
-// ---------------------------------------------------------------------------
-
-/** String-value shapes that must never appear in a bundler/paymaster URL.
- *  Mirrors the posture of connect-agent.mjs's FORBIDDEN_VALUE_RULES /
- *  bundler-client.mjs's SecretLeakError checks, scoped to what a URL could
- *  plausibly carry (query-string credentials, embedded key material). */
-const SECRET_URL_RULES = Object.freeze([
-  // 32-byte hex — the shape of a raw EVM private key / session secret.
-  { rule: "raw-32-byte-hex-key", re: /0x[0-9a-fA-F]{64}/ },
-  { rule: "bearer-token", re: /bearer\s+[A-Za-z0-9._~+/=-]+/i },
-  { rule: "pem-private-key", re: /-----BEGIN[A-Z ]*PRIVATE KEY-----/ },
-  { rule: "authorization-header", re: /authorization\s*:/i },
-  // Credential-shaped query/path segment: ?api_key=..., ?token=..., ?secret=...,
-  // ?password=..., ?auth=..., ?access_token=..., ?bearer=..., or userinfo
-  // (user:pass@host) embedded in the URL itself.
-  {
-    rule: "credential-shaped-param",
-    re: /[?&](api[_-]?key|apikey|key|token|access[_-]?token|secret|password|passwd|auth|bearer)=/i,
-  },
-  { rule: "embedded-userinfo", re: /^[a-z][a-z0-9+.-]*:\/\/[^/@\s]+:[^/@\s]+@/i },
-]);
-
-function assertPublicUrlSafe(value, label) {
-  if (typeof value !== "string" || value.trim() === "") {
-    fail(`${label} must be a non-empty string URL`);
-  }
-  let parsed;
-  try {
-    parsed = new URL(value);
-  } catch {
-    fail(`${label} is not a valid URL: ${value}`);
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    fail(`${label} must be an http(s) URL, got scheme ${parsed.protocol}`);
-  }
-  for (const { rule, re } of SECRET_URL_RULES) {
-    if (re.test(value)) {
-      fail(`${label} looks like it carries secret material (rule: ${rule}) — refusing to load a credential-shaped public endpoint`);
-    }
-  }
-  return value;
-}
-
-// ---------------------------------------------------------------------------
-// Chain registry seed
-// ---------------------------------------------------------------------------
-
-/** Base metadata for every chain Oracle Control's public runtime config
- *  knows about out of the box. entryPoint is intentionally NOT stored here —
- *  it is always ENTRYPOINT_V07, asserted below, so there is exactly one
- *  place (aa-adapter.mjs) that can ever define it. */
-const CHAIN_SEEDS = Object.freeze([
-  { chainId: 8453, name: "Base" },
-  { chainId: 42161, name: "Arbitrum" },
-]);
-
-export const DEFAULT_CHAIN_ID = 8453;
-export const DEFAULT_PUBLIC_HOST = "127.0.0.1";
-export const DEFAULT_PUBLIC_PORT = 8799;
-const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
-
-function buildChainEntry(seed, env) {
-  const entry = {
-    name: seed.name,
-    entryPoint: ENTRYPOINT_V07,
-  };
-  // entryPoint must always equal aa-adapter's ENTRYPOINT_V07 for every
-  // supported chain — asserted here (not just "set here") so a future edit
-  // that tries to override it per-chain is caught immediately.
-  if (entry.entryPoint !== ENTRYPOINT_V07) {
-    fail(`chain ${seed.chainId} entryPoint drifted from aa-adapter ENTRYPOINT_V07`);
-  }
-
-  const bundlerVar = `ORACLE_BUNDLER_URL_${seed.chainId}`;
-  const paymasterVar = `ORACLE_PAYMASTER_URL_${seed.chainId}`;
-  const bundlerRaw = env[bundlerVar];
-  const paymasterRaw = env[paymasterVar];
-
-  if (bundlerRaw != null && String(bundlerRaw).trim() !== "") {
-    entry.bundlerUrl = assertPublicUrlSafe(String(bundlerRaw), bundlerVar);
-  }
-  if (paymasterRaw != null && String(paymasterRaw).trim() !== "") {
-    entry.paymasterUrl = assertPublicUrlSafe(String(paymasterRaw), paymasterVar);
-  }
-
-  return entry;
-}
-
-function parsePort(raw, label) {
-  const n = Number(raw);
-  if (!Number.isInteger(n) || n < 0 || n > 65535) {
-    fail(`${label} must be an integer port 0-65535, got ${JSON.stringify(raw)}`);
-  }
-  return n;
-}
-
-function parsePublicHost(raw, label) {
-  const host = String(raw).trim();
-  const normalized = host.toLowerCase().replace(/^\[|\]$/g, "");
-  if (!LOOPBACK_HOSTS.has(normalized)) {
-    fail(`${label} must be a loopback host, got ${JSON.stringify(raw)}`);
-  }
-  return normalized === "::1" ? "::1" : host;
-}
-
-/**
- * Parse the public runtime config (chain/bundler/paymaster registry + public
- * HTTP bind) from an env-like object. Pure function, no I/O, no network.
- *
- * @param {object} [env] defaults to process.env; any plain object of
- *   string-ish values works (this is what makes it deterministically
- *   testable without touching real process.env).
- * @returns {{
- *   chains: Record<string, {name:string, entryPoint:string, bundlerUrl?:string, paymasterUrl?:string}>,
- *   defaultChainId: number,
- *   publicHost: string,
- *   publicPort: number,
- * }}
- */
-export function loadPublicConfig(env = process.env) {
-  if (env == null || typeof env !== "object") {
-    fail("env must be an object");
-  }
-
-  const chains = {};
-  for (const seed of CHAIN_SEEDS) {
-    chains[String(seed.chainId)] = buildChainEntry(seed, env);
-  }
-
-  const rawDefaultChainId = env.ORACLE_DEFAULT_CHAIN_ID;
-  let defaultChainId = DEFAULT_CHAIN_ID;
-  if (rawDefaultChainId != null && String(rawDefaultChainId).trim() !== "") {
-    const n = Number(rawDefaultChainId);
-    if (!Number.isInteger(n)) {
-      fail(`ORACLE_DEFAULT_CHAIN_ID must be an integer chain id, got ${JSON.stringify(rawDefaultChainId)}`);
-    }
-    if (chains[String(n)] == null) {
-      fail(`ORACLE_DEFAULT_CHAIN_ID ${n} is not a registered chain (known: ${Object.keys(chains).join(", ")})`);
-    }
-    defaultChainId = n;
-  }
-
-  const publicHost = (() => {
-    const v = env.ORACLE_PUBLIC_HOST ?? env.MAD_PUBLIC_HOST;
-    return v != null && String(v).trim() !== "" ? parsePublicHost(v, "ORACLE_PUBLIC_HOST") : DEFAULT_PUBLIC_HOST;
-  })();
-
-  const publicPort = (() => {
-    const v = env.ORACLE_PUBLIC_PORT ?? env.MAD_PUBLIC_PORT;
-    if (v == null || String(v).trim() === "") return DEFAULT_PUBLIC_PORT;
-    return parsePort(v, "ORACLE_PUBLIC_PORT");
-  })();
-
-  return Object.freeze({
-    chains: Object.freeze(chains),
-    defaultChainId,
-    publicHost,
-    publicPort,
-  });
-}
-
-/**
- * Resolve a single chain entry from a loaded config. Fails closed on any
- * chainId not present in the registry — never falls back to a guessed/
- * default chain.
- *
- * @param {ReturnType<typeof loadPublicConfig>} config
- * @param {number|string} chainId
- */
-export function resolveChain(config, chainId) {
-  if (config == null || typeof config.chains !== "object") {
-    fail("resolveChain: config must be a loadPublicConfig() result");
-  }
-  const key = String(chainId);
-  const entry = config.chains[key];
-  if (entry == null) {
-    fail(`unsupported chainId ${key} (registered: ${Object.keys(config.chains).join(", ") || "none"})`);
-  }
-  return entry;
-}
-
-/** Drop the query string and any userinfo from a URL, keeping only
- *  scheme://host:port/path — safe to write to a log line even though the
- *  full URL already passed the load-time secret-shape scan. */
-function redactUrl(value) {
-  try {
-    const u = new URL(value);
-    u.search = "";
-    u.username = "";
-    u.password = "";
-    return u.toString();
-  } catch {
-    return "[unparseable-url-redacted]";
-  }
-}
-
-/**
- * Safe-to-log view of a loaded config: chain names/entryPoints/host/port
- * pass through unchanged (none of that is secret-shaped), bundler/paymaster
- * URLs are stripped down to origin+path only.
- *
- * @param {ReturnType<typeof loadPublicConfig>} config
- */
-export function redactedConfig(config) {
-  if (config == null || typeof config.chains !== "object") {
-    fail("redactedConfig: config must be a loadPublicConfig() result");
-  }
-  const chains = {};
-  for (const [chainId, entry] of Object.entries(config.chains)) {
-    chains[chainId] = {
-      name: entry.name,
-      entryPoint: entry.entryPoint,
-      ...(entry.bundlerUrl != null ? { bundlerUrl: redactUrl(entry.bundlerUrl) } : {}),
-      ...(entry.paymasterUrl != null ? { paymasterUrl: redactUrl(entry.paymasterUrl) } : {}),
-    };
-  }
-  return Object.freeze({
-    chains: Object.freeze(chains),
-    defaultChainId: config.defaultChainId,
-    publicHost: config.publicHost,
-    publicPort: config.publicPort,
-  });
-}
-
-export const _internal = { assertPublicUrlSafe, SECRET_URL_RULES, CHAIN_SEEDS };

package/src/public-control/session-key-model.mjs

@@ -1,379 +0,0 @@
-// Oracle Control — provider-neutral account-abstraction session-key model.
-//
-// This is a design spike (Slice B / Phase 2 of the Oracle public release plan,
-// see artifacts/oracle-public-plan.md and docs/public-self-custody-aa.md).
-// It defines the SHAPE of a public self-custody session-key grant and the
-// deterministic policy checks that decide whether a proposed action is
-// authorized by that grant — independent of which account-abstraction stack
-// (Safe, Kernel/ZeroDev, Biconomy/Nexus, permissionless/viem) eventually
-// enforces it on-chain.
-//
-// Hard boundaries for this file:
-//   - No wallet/AA SDK imports. No RPC calls. No live chain integration.
-//   - No import from the private executor stack (get-signer.mjs, keystore.mjs,
-//     exec-policy.mjs, local-signer/*, oracle-env.mjs, adapters/*). This model
-//     must stand alone so it can never be wired to a private operator wallet.
-//   - Deterministic, pure functions only — same input always produces the
-//     same session id and the same authorization verdict.
-//   - `owner` (the user's main wallet / smart-account) never signs a
-//     transaction here. This module only decides whether an already-proposed
-//     action fits inside an already-granted, bounded session.
-//
-// Terminology:
-//   grant   — the bounded permission the owner signed (chain, actions,
-//             targets, value/gas caps, expiry). Provider-neutral; a real
-//             integration maps this onto a Safe allowance module, a ZeroDev
-//             session-key validator, a Biconomy Nexus session module, or a
-//             permissionless/viem session account.
-//   agent   — the session key address the grant authorizes to act. Never the
-//             owner's main key.
-//   request — a single proposed action (action id, target, value, gas) that
-//             is checked against a grant before anything is prepared/signed.
-
-import { createHash } from "node:crypto";
-import { exactBigInt } from "../exact-integer.mjs";
-import { isWindowOpen } from "../fresh-window.mjs";
-
-/** Account-abstraction stacks this model is written to be portable across.
- *  Purely descriptive — no SDK behavior is implied or imported here. */
-export const PROVIDERS = Object.freeze({
-  SAFE: "safe",
-  KERNEL_ZERODEV: "kernel-zerodev",
-  BICONOMY_NEXUS: "biconomy-nexus",
-  PERMISSIONLESS_VIEM: "permissionless-viem",
-});
-
-export const PROVIDER_IDS = Object.freeze(Object.values(PROVIDERS));
-
-/** Session lifecycle states returned by sessionStatus(). */
-export const SESSION_STATUS = Object.freeze({
-  ACTIVE: "active",
-  EXPIRED: "expired",
-  REVOKED: "revoked",
-});
-
-export const MAX_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
-
-/** Action-id prefixes that never move funds or touch a target contract and
- *  therefore never require a non-empty target allowlist. Matches the "empty
- *  target allowlist only allowed for read/simulate scopes" rule in the Oracle
- *  public policy schema (artifacts/oracle-public-plan.md Phase 1). */
-const READ_ONLY_ACTION_PREFIXES = ["read:", "simulate:"];
-
-const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
-const HEX32_RE = /^0x[0-9a-fA-F]{64}$/;
-
-function isReadOnlyAction(action) {
-  const a = String(action || "");
-  return READ_ONLY_ACTION_PREFIXES.some((p) => a.startsWith(p));
-}
-
-function fail(message) {
-  throw new Error(`session: ${message}`);
-}
-
-function normalAddress(value, label) {
-  const text = String(value ?? "").trim().toLowerCase();
-  if (!ADDRESS_RE.test(text)) fail(`${label} must be a 0x-prefixed 20-byte address`);
-  return text;
-}
-
-function normalActionId(value) {
-  const text = String(value ?? "").trim().toLowerCase();
-  if (!text) fail("action ids must be non-empty strings");
-  if (text.length > 128) fail("action id too long");
-  return text;
-}
-
-function normalPositiveInt(value, label) {
-  const n = Number(value);
-  if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) fail(`${label} must be a positive integer`);
-  return n;
-}
-
-function normalBigString(value, label, { allowZero = true } = {}) {
-  if (value == null || value === "") return "0";
-  // Wei caps bound delegated spend. An unsafe JS number rounds UP here and
-  // stores a looser cap than the owner wrote, so refuse rather than coerce.
-  let n;
-  try {
-    n = exactBigInt(value, label);
-  } catch (e) {
-    fail(e.message);
-  }
-  if (n < 0n) fail(`${label} must not be negative`);
-  if (!allowZero && n === 0n) fail(`${label} must be greater than zero`);
-  return n.toString();
-}
-
-/** Deterministic JSON: object keys sorted recursively, matching the
- *  canonicalJson convention already used by audit-log.mjs / vault-attestation.mjs
- *  so the same fields hash identically everywhere. Self-contained here on
- *  purpose (no cross-file import) to keep this design-spike file standalone. */
-export function canonicalJson(value) {
-  if (value === null || value === undefined) return "null";
-  if (typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return "[" + value.map(canonicalJson).join(",") + "]";
-  const keys = Object.keys(value).sort();
-  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJson(value[k])).join(",") + "}";
-}
-
-/**
- * Deterministic session id: sha256 over the canonical JSON of the grant's
- * identity fields, prefixed 0x. Two grants with identical owner/agent/chain/
- * actions/targets/caps/expiry/nonce always produce the same id; changing any
- * field (including the ordering-insensitive actions/targets arrays, which are
- * sorted before hashing) changes the id.
- */
-export function computeSessionId(fields) {
-  const h = createHash("sha256");
-  h.update(canonicalJson(fields), "utf8");
-  return `0x${h.digest("hex")}`;
-}
-
-/**
- * Build and validate a provider-neutral session grant. Throws on any
- * malformed/unsafe input (fail-closed). Returns a deep-frozen record.
- *
- * @param {object} input
- * @param {string} input.provider     one of PROVIDERS (informational; which
- *                                    AA stack is expected to enforce this)
- * @param {string} input.owner        user's main wallet / smart-account address
- * @param {string} input.agent        session key address (must differ from owner)
- * @param {number} input.chainId      positive integer chain id
- * @param {string[]} input.actions    non-empty list of action ids (e.g.
- *                                    "erc20:transfer", "swap:exec", "read:balance")
- * @param {string[]} [input.targets]  allowed destination addresses. May be
- *                                    empty ONLY if every action is read/simulate.
- * @param {string|number|bigint} [input.maxValueWei]  native-value cap (default "0")
- * @param {string|number|bigint} [input.maxGasWei]    optional gas-fee cap (gasLimit*feePerGas)
- * @param {number} input.expiresAtMs  epoch ms the grant stops being valid
- * @param {string|number} [input.nonce] uniqueness salt (default 0)
- * @param {number} [input.issuedAtMs]  epoch ms issuance time (default Date.now())
- */
-export function createSessionGrant({
-  provider,
-  owner,
-  agent,
-  chainId,
-  actions,
-  targets = [],
-  maxValueWei = "0",
-  maxGasWei,
-  expiresAtMs,
-  nonce = 0,
-  issuedAtMs = Date.now(),
-} = {}) {
-  const normalizedProvider = String(provider ?? "").trim().toLowerCase();
-  if (!PROVIDER_IDS.includes(normalizedProvider)) {
-    fail(`provider must be one of ${PROVIDER_IDS.join(", ")}`);
-  }
-
-  const normalizedOwner = normalAddress(owner, "owner");
-  const normalizedAgent = normalAddress(agent, "agent");
-  if (normalizedOwner === normalizedAgent) fail("agent key must differ from owner wallet");
-
-  const normalizedChainId = normalPositiveInt(chainId, "chainId");
-
-  if (!Array.isArray(actions) || actions.length === 0) fail("actions must be a non-empty array");
-  const normalizedActions = [...new Set(actions.map(normalActionId))].sort();
-
-  if (!Array.isArray(targets)) fail("targets must be an array");
-  const normalizedTargets = [...new Set(targets.map((t) => normalAddress(t, "target")))].sort();
-
-  const allActionsReadOnly = normalizedActions.every(isReadOnlyAction);
-  if (normalizedTargets.length === 0 && !allActionsReadOnly) {
-    fail("empty target allowlist is only allowed when every action is read/simulate");
-  }
-
-  const normalizedMaxValueWei = normalBigString(maxValueWei, "maxValueWei");
-  const normalizedMaxGasWei = maxGasWei == null ? null : normalBigString(maxGasWei, "maxGasWei");
-
-  const normalizedIssuedAtMs = Number(issuedAtMs);
-  if (!Number.isFinite(normalizedIssuedAtMs)) fail("issuedAtMs must be a finite number");
-  const normalizedExpiresAtMs = Number(expiresAtMs);
-  if (!Number.isFinite(normalizedExpiresAtMs)) fail("expiresAtMs must be a finite number");
-  if (normalizedExpiresAtMs <= normalizedIssuedAtMs) fail("expiresAtMs must be after issuedAtMs");
-  if (normalizedExpiresAtMs - normalizedIssuedAtMs > MAX_SESSION_TTL_MS) {
-    fail(`session grant exceeds the hard 24-hour TTL (${MAX_SESSION_TTL_MS} ms)`);
-  }
-
-  const normalizedNonce = String(nonce ?? 0);
-
-  const identity = {
-    mode: "oracle-session-grant",
-    version: 1,
-    provider: normalizedProvider,
-    owner: normalizedOwner,
-    agent: normalizedAgent,
-    chainId: normalizedChainId,
-    actions: normalizedActions,
-    targets: normalizedTargets,
-    maxValueWei: normalizedMaxValueWei,
-    maxGasWei: normalizedMaxGasWei,
-    issuedAtMs: normalizedIssuedAtMs,
-    expiresAtMs: normalizedExpiresAtMs,
-    nonce: normalizedNonce,
-  };
-
-  const id = computeSessionId(identity);
-  const grant = { id, ...identity };
-  return Object.freeze(grant);
-}
-
-/** In-memory revocation registry. Deterministic, no chain dependency — a real
- *  integration backs this with an on-chain revoke (Safe module disable,
- *  ZeroDev/Biconomy session revoke) or an off-chain indexer; the interface
- *  here is what Oracle Control's policy check consumes either way. */
-export function createRevocationRegistry() {
-  const revoked = new Map(); // sessionId -> { revokedAtMs, reason }
-  return {
-    revoke(sessionId, { nowMs = Date.now(), reason = null } = {}) {
-      if (!sessionId) fail("revoke requires a sessionId");
-      if (!revoked.has(sessionId)) revoked.set(sessionId, { revokedAtMs: Number(nowMs), reason });
-      return revoked.get(sessionId);
-    },
-    isRevoked(sessionId) {
-      return revoked.has(sessionId);
-    },
-    revokedAt(sessionId) {
-      return revoked.get(sessionId)?.revokedAtMs ?? null;
-    },
-    get size() {
-      return revoked.size;
-    },
-  };
-}
-
-function isRevokedGrant(grant, revocation) {
-  if (!revocation) return false;
-  if (typeof revocation.isRevoked === "function") return revocation.isRevoked(grant.id);
-  if (revocation instanceof Set) return revocation.has(grant.id);
-  if (Array.isArray(revocation)) return revocation.includes(grant.id);
-  return false;
-}
-
-/**
- * Compute a grant's current lifecycle status. Revocation takes precedence
- * over expiry (a revoked-then-expired grant still reports "revoked", which
- * matters for audit trails downstream).
- */
-export function sessionStatus(grant, { nowMs = Date.now(), revocation } = {}) {
-  if (!grant || grant.mode !== "oracle-session-grant") fail("invalid session grant");
-  if (isRevokedGrant(grant, revocation)) return SESSION_STATUS.REVOKED;
-  // Fail CLOSED on an unusable clock. `Number(nowMs) >= expiresAtMs` is false
-  // for NaN / null / "later" / -Infinity, so a long-dead grant reported ACTIVE
-  // and authorized spending at its full cap. `null` is the sharp edge: it slips
-  // past the `= Date.now()` default because it is a supplied value, and
-  // Number(null) === 0.
-  if (!isWindowOpen({ expiresAtMs: grant.expiresAtMs }, nowMs, { inclusive: true })) return SESSION_STATUS.EXPIRED;
-  return SESSION_STATUS.ACTIVE;
-}
-
-export function isSessionActive(grant, opts = {}) {
-  return sessionStatus(grant, opts) === SESSION_STATUS.ACTIVE;
-}
-
-/**
- * Authorize a single proposed action against a session grant. Throws a
- * "session: ..." Error on any violation (fail-closed); returns true only when
- * every check passes. This is a pure policy check — it does not sign,
- * prepare, or broadcast anything.
- *
- * @param {object} grant     output of createSessionGrant()
- * @param {object} request
- * @param {string} request.action    action id being attempted
- * @param {number} request.chainId   chain the action targets
- * @param {string} [request.target]  destination address (required unless read/simulate)
- * @param {string|number|bigint} [request.valueWei] native value moved (default 0)
- * @param {string|number|bigint} [request.gasWei]    gasLimit*feePerGas estimate
- * @param {object} [opts]
- * @param {number} [opts.nowMs]
- * @param {object|Set|string[]} [opts.revocation]  registry / set / array of revoked ids
- */
-export function assertSessionAuthorized(grant, request = {}, opts = {}) {
-  if (!grant || grant.mode !== "oracle-session-grant") fail("invalid session grant");
-
-  const status = sessionStatus(grant, opts);
-  if (status === SESSION_STATUS.REVOKED) fail(`session ${grant.id} is revoked`);
-  if (status === SESSION_STATUS.EXPIRED) fail(`session ${grant.id} expired at ${grant.expiresAtMs}`);
-
-  const requestedChainId = normalPositiveInt(request.chainId, "request.chainId");
-  if (requestedChainId !== grant.chainId) {
-    fail(`chain mismatch: session is scoped to ${grant.chainId}, request is ${requestedChainId}`);
-  }
-
-  const action = normalActionId(request.action);
-  if (!grant.actions.includes(action)) {
-    fail(`action "${action}" not permitted by session ${grant.id}`);
-  }
-
-  const readOnly = isReadOnlyAction(action);
-  if (!readOnly) {
-    if (request.target == null || request.target === "") fail("target required for a non-read action");
-    const target = normalAddress(request.target, "request.target");
-    if (grant.targets.length === 0) fail(`session ${grant.id} has no granted targets (fail-closed)`);
-    if (!grant.targets.includes(target)) {
-      fail(`target ${target} not permitted by session ${grant.id}`);
-    }
-  }
-
-  const valueWei = BigInt(normalBigString(request.valueWei ?? "0", "request.valueWei"));
-  const maxValueWei = BigInt(grant.maxValueWei);
-  if (valueWei > maxValueWei) {
-    fail(`value ${valueWei} exceeds session cap ${maxValueWei}`);
-  }
-
-  // A gas ceiling on the grant is a promise the grant makes. Honouring it only
-  // when the REQUEST volunteers a gasWei made it optional in practice: a
-  // requester could omit the field and satisfy a grant whose explicit ceiling
-  // would otherwise reject the transaction. If the grant bounds gas, the
-  // request must state it.
-  if (grant.maxGasWei != null) {
-    if (request.gasWei == null) {
-      fail("session grant bounds gas but the request omitted gasWei — refusing to authorize unbounded gas");
-    }
-    const gasWei = BigInt(normalBigString(request.gasWei, "request.gasWei"));
-    const maxGasWei = BigInt(grant.maxGasWei);
-    if (gasWei > maxGasWei) {
-      fail(`gas fee ${gasWei} exceeds session cap ${maxGasWei}`);
-    }
-  }
-
-  return true;
-}
-
-/** Convenience non-throwing wrapper: returns { ok, reason }. */
-export function checkSessionAuthorized(grant, request = {}, opts = {}) {
-  try {
-    assertSessionAuthorized(grant, request, opts);
-    return { ok: true };
-  } catch (e) {
-    return { ok: false, reason: String(e?.message || e) };
-  }
-}
-
-/** Redacted view safe to log/index — drops nothing secret today (this model
- *  never carries key material) but exists so callers have one stable place to
- *  serialize a grant for an audit trail without hand-picking fields. */
-export function toAuditRecord(grant) {
-  if (!grant || grant.mode !== "oracle-session-grant") fail("invalid session grant");
-  return {
-    id: grant.id,
-    provider: grant.provider,
-    owner: grant.owner,
-    agent: grant.agent,
-    chainId: grant.chainId,
-    actions: grant.actions,
-    targets: grant.targets,
-    maxValueWei: grant.maxValueWei,
-    maxGasWei: grant.maxGasWei,
-    issuedAtMs: grant.issuedAtMs,
-    expiresAtMs: grant.expiresAtMs,
-    nonce: grant.nonce,
-  };
-}
-
-// Exported for tests / callers that want the raw address/hash validators
-// without re-implementing them.
-export const _internal = { ADDRESS_RE, HEX32_RE, isReadOnlyAction };