@oracle-agent/oracle 0.13.1 → 0.14.0

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,94 @@
+// 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();
+  // The packaged public desktop owns its own config root and must never inherit
+  // a private operator/desk env file that happens to exist on the host.
+  if (process.env.ORACLE_PUBLIC_DESKTOP === "1") {
+    const owned = (process.env.ORACLE_CONFIG_DIR || join(home, ".config", "oracle")).trim();
+    return [explicit, join(owned, "exec.env")].filter(Boolean);
+  }
+  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;
+}

package/src/audit-log.mjs

@@ -0,0 +1,196 @@
+// Tamper-evident, append-only audit hash-chain for the Oracle exec layer.
+//
+// Adapted from block/buzz `buzz-audit` (Rust + Postgres, multi-tenant) to Oracle's
+// single-process, file-backed model. Fills the gap the custody review found:
+// the armed executor had a rolling daily-spend counter and NO tamper-evident
+// record of what it prepared / signed / broadcast. This is the compliance/trust
+// spine the non-custodial agency product needs, shared by every oracle-<chain>
+// worker that routes through the exec-server.
+//
+// Each entry chains to the previous via SHA-256 over a FIXED field order that
+// includes `prev_hash`, so deleting, editing, or reordering any entry breaks
+// verification of every entry after it. `detail` is folded in via canonical
+// JSON (recursively sorted keys) so the hash is stable across Arch/VPS/Mac.
+//
+// SECURITY: `detail` is persisted verbatim and included in the hash. NEVER write
+// bearer tokens, private keys, passwords, or keystore passphrases into it. Log
+// outcome metadata (chainId, to, value, hash, reason) only.
+
+import { createHash } from "node:crypto";
+import { readFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { configPath, env } from "./oracle-env.mjs";
+
+/** 32-byte sentinel (hex) hashed in place of prev_hash for the first entry. */
+export const GENESIS_HASH = "0".repeat(64);
+
+/** Actions the exec layer records. Unknown actions are allowed (forward-compat)
+ *  but this set documents the vocabulary and lets tests assert coverage. */
+export const AUDIT_ACTIONS = Object.freeze({
+  PREPARE: "exec.prepare",
+  SIGN: "exec.sign",
+  BROADCAST: "exec.broadcast",
+  POLICY_REJECT: "policy.reject",
+  AUTH_GRANT: "auth.grant",
+  AUTH_OK: "auth.verify.ok",
+  AUTH_FAIL: "auth.verify.fail",
+});
+
+function defaultPath() {
+  return configPath("audit-log.jsonl", "ORACLE_AUDIT_LOG", "MAD_AUDIT_LOG");
+}
+
+/** Deterministic JSON: object keys sorted recursively. Matches buzz-audit's
+ *  canonical_json so the same detail hashes identically everywhere. */
+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(",") +
+    "}"
+  );
+}
+
+// Fixed field order — changing it invalidates every existing chain. `stream`
+// leads the hash so an entry cannot be lifted out of one stream's chain and
+// re-verified inside another (the tenant-binding property buzz-audit gets from
+// hashing community_id first). Presence tags (\x00 / \x01) distinguish a null
+// field from an empty-string field so they can't collide.
+export function computeHash(entry) {
+  const h = createHash("sha256");
+  h.update(String(entry.stream), "utf8");
+  h.update(String(entry.seq), "utf8");
+  h.update(String(entry.ts), "utf8");
+  h.update(String(entry.action), "utf8");
+  h.update(entry.actor == null ? "\x00" : "\x01" + entry.actor, "utf8");
+  h.update(entry.objectId == null ? "\x00" : "\x01" + entry.objectId, "utf8");
+  h.update(canonicalJson(entry.detail ?? null), "utf8");
+  h.update(entry.prevHash ?? GENESIS_HASH, "utf8");
+  return h.digest("hex");
+}
+
+function readAll(path) {
+  if (!existsSync(path)) return [];
+  const raw = readFileSync(path, "utf8");
+  const out = [];
+  for (const line of raw.split("\n")) {
+    const s = line.trim();
+    if (!s) continue;
+    try {
+      out.push(JSON.parse(s));
+    } catch {
+      // A corrupt/partial trailing line is surfaced by verifyChain, not silently
+      // healed. Skip it here so the head lookup uses the last *valid* record.
+    }
+  }
+  return out;
+}
+
+// Serialize appends within this process so read-head → append is atomic even
+// under concurrent exec-server requests (mirrors buzz-audit's per-chain lock).
+let appendQueue = Promise.resolve();
+
+/**
+ * Append one entry to the chain. Returns the full stored record.
+ * @param {object} opts
+ * @param {string} opts.action    one of AUDIT_ACTIONS (or a custom string)
+ * @param {string} [opts.actor]   signer/owner address or agent id
+ * @param {string} [opts.objectId] tx hash, chainId:to, grant id, ...
+ * @param {object} [opts.detail]  hashed outcome metadata (NO secrets)
+ * @param {string} [opts.stream]  logical chain label (default "mad-exec")
+ * @param {string} [opts.path]    override log path (tests)
+ */
+export function appendAudit({ action, actor = null, objectId = null, detail = null, stream, path } = {}) {
+  if (!action) throw new Error("audit: action required");
+  const p = path || defaultPath();
+  const strm = stream || env("ORACLE_AUDIT_STREAM", "MAD_AUDIT_STREAM", "oracle-exec");
+
+  const run = appendQueue.then(() => {
+    const existing = readAll(p).filter((e) => e.stream === strm);
+    const head = existing.length ? existing[existing.length - 1] : null;
+    const seq = head ? head.seq + 1 : 1;
+    const prevHash = head ? head.hash : null;
+
+    const entry = {
+      stream: strm,
+      seq,
+      ts: new Date().toISOString(),
+      action: String(action),
+      actor: actor == null ? null : String(actor),
+      objectId: objectId == null ? null : String(objectId),
+      detail: detail ?? null,
+      prevHash,
+    };
+    entry.hash = computeHash(entry);
+
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, JSON.stringify(entry) + "\n", { mode: 0o600 });
+    return entry;
+  });
+
+  // Keep the queue alive even if one append throws.
+  appendQueue = run.catch(() => {});
+  return run;
+}
+
+/**
+ * Best-effort append that NEVER throws into the caller. Use on the live exec
+ * path: a broken/unwritable log must not brick a signing operation, and every
+ * entry that DID get written stays verifiable. Failures go to stderr.
+ */
+export async function recordAudit(opts) {
+  try {
+    return await appendAudit(opts);
+  } catch (e) {
+    try {
+      process.stderr.write(
+        JSON.stringify({ auditError: String(e?.message || e), action: opts?.action }) + "\n"
+      );
+    } catch {
+      /* ignore */
+    }
+    return null;
+  }
+}
+
+/**
+ * Verify a stream's chain end-to-end.
+ * @returns {{ ok: boolean, count: number, reason?: string, seq?: number }}
+ */
+export function verifyChain({ stream, path } = {}) {
+  const p = path || defaultPath();
+  const strm = stream || env("ORACLE_AUDIT_STREAM", "MAD_AUDIT_STREAM", "oracle-exec");
+  const rows = readAll(p).filter((e) => e.stream === strm);
+  if (rows.length === 0) return { ok: false, count: 0, reason: "empty" };
+
+  let expectedPrev = null;
+  let expectedSeq = 1;
+  for (const row of rows) {
+    if (row.seq !== expectedSeq) {
+      return { ok: false, count: rows.length, reason: "seq-gap", seq: row.seq };
+    }
+    const wantPrev = expectedSeq === 1 ? null : expectedPrev;
+    if ((row.prevHash ?? null) !== (wantPrev ?? null)) {
+      return { ok: false, count: rows.length, reason: "prev-hash-mismatch", seq: row.seq };
+    }
+    const { hash, ...bare } = row;
+    if (computeHash(bare) !== hash) {
+      return { ok: false, count: rows.length, reason: "hash-mismatch", seq: row.seq };
+    }
+    expectedPrev = hash;
+    expectedSeq += 1;
+  }
+  return { ok: true, count: rows.length };
+}
+
+/** Read up to `limit` entries from `fromSeq` for a stream (newest-truncated). */
+export function getEntries({ stream, fromSeq = 1, limit = 100, path } = {}) {
+  const p = path || defaultPath();
+  const strm = stream || env("ORACLE_AUDIT_STREAM", "MAD_AUDIT_STREAM", "oracle-exec");
+  return readAll(p)
+    .filter((e) => e.stream === strm && e.seq >= fromSeq)
+    .slice(0, limit);
+}