@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/protocol-execution.mjs

@@ -0,0 +1,84 @@
+import { isAddress } from "ethers";
+import { assertAutoSlippageGuard } from "./auto-slippage.mjs";
+
+export const EXECUTABLE_PROTOCOL_PROVIDERS = Object.freeze([
+  "lifi",
+  "relay",
+  "uniswap-v3",
+  "aerodrome",
+  "zerox",
+  "paraswap",
+  "odos",
+  "oneinch",
+  "pendle",
+  "balancer",
+  "curve",
+]);
+
+function hexData(value) {
+  const data = String(value || "");
+  return /^0x(?:[0-9a-fA-F]{2})*$/.test(data);
+}
+
+function sameAddress(left, right) {
+  return String(left || "").toLowerCase() === String(right || "").toLowerCase();
+}
+
+/**
+ * Validate a provider-produced executable route before it may cross into the
+ * generic signer. This function accepts no caller-supplied destination/calldata;
+ * those must come from the provider's freshly generated route.
+ */
+export function assertPreparedProtocolRoute(
+  route,
+  { provider, chainId, from, nowMs = Date.now() } = {}
+) {
+  // `calldataReady` means the provider assembled real calldata from a fresh
+  // quote. It deliberately does NOT mean "cleared to execute" — the user's
+  // wallet is still the only authority. The old flag name was `executionReady`,
+  // which read as permission and trained agents to treat a quote as authority.
+  const prepared = route && (route.calldataReady === true || route.executionReady === true);
+  if (!prepared) {
+    throw new Error(`${provider || "protocol"}: executable provider preparation required`);
+  }
+  if (provider && route.provider !== provider) {
+    throw new Error(`protocol provider mismatch: expected ${provider}, got ${route.provider || "unknown"}`);
+  }
+  if (Number(route.chainId) !== Number(chainId)) {
+    throw new Error(`protocol route chain mismatch: expected ${chainId}, got ${route.chainId}`);
+  }
+  const raw = Array.isArray(route.transactions) ? route.transactions : [route.transaction];
+  if (!raw.length || raw.some((tx) => !tx)) throw new Error("protocol route has no executable transaction");
+
+  return raw.map((tx, index) => {
+    if (Number(tx.chainId ?? route.chainId) !== Number(chainId)) {
+      throw new Error(`protocol transaction ${index} chain mismatch`);
+    }
+    if (!isAddress(String(tx.to || ""))) throw new Error(`protocol transaction ${index} target must be an address`);
+    if (!hexData(tx.data) || String(tx.data).length < 10) {
+      throw new Error(`protocol transaction ${index} requires non-empty hex calldata`);
+    }
+    if (from && tx.from && !sameAddress(tx.from, from)) {
+      throw new Error(`protocol transaction ${index} sender mismatch`);
+    }
+    const guard = tx.slippageGuard || tx.madSlippage || route.autoSlippage || route.quote?.autoSlippage;
+    // Same bar as enforceTxPolicy sign/broadcast: a prepare helper must not
+    // become a second, softer gate that trusts caller-bound unsigned guards.
+    assertAutoSlippageGuard(guard, {
+      nowMs,
+      chainId,
+      venue: tx.to,
+      tx: { ...tx, chainId: Number(chainId), to: tx.to, data: tx.data },
+      requireSigned: true,
+    });
+    return {
+      chainId: Number(chainId),
+      to: tx.to,
+      data: tx.data,
+      value: tx.value == null ? "0x0" : String(tx.value),
+      ...(tx.gasLimit != null || tx.gas != null ? { gasLimit: String(tx.gasLimit ?? tx.gas) } : {}),
+      ...(tx.nonce != null ? { nonce: Number(tx.nonce) } : {}),
+      slippageGuard: guard,
+    };
+  });
+}

package/src/protocol-templates/gate.mjs

@@ -0,0 +1,179 @@
+// Protocol template security gate.
+// Refuse prepare-deploy unless Foundry tests are green.
+// Static analysis (slither) is required when available; otherwise documented skip.
+// This is NOT a substitute for a paid Solidity firm audit.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+
+const HERE = fileURLToPath(new URL(".", import.meta.url));
+const PKG_ROOT = resolve(HERE, "../..");
+const TEMPLATES_ROOT = join(PKG_ROOT, "protocols", "templates");
+
+export const TEMPLATE_AUDIT_DISCLAIMER =
+  "Template + Foundry tests + optional static analysis. NOT a paid security-firm audit. Do not put mainnet TVL on forks without an independent Solidity audit.";
+
+export function listProtocolTemplates() {
+  if (!existsSync(TEMPLATES_ROOT)) return [];
+  return readdirSync(TEMPLATES_ROOT)
+    .filter((name) => statSync(join(TEMPLATES_ROOT, name)).isDirectory())
+    .map((id) => {
+      const dir = join(TEMPLATES_ROOT, id);
+      const security = join(dir, "SECURITY.md");
+      return {
+        id,
+        path: dir,
+        securityNotice: existsSync(security) ? readFileSync(security, "utf8").slice(0, 500) : null,
+        disclaimer: TEMPLATE_AUDIT_DISCLAIMER,
+      };
+    });
+}
+
+function forgeBin() {
+  if (process.env.FORGE_BIN) return process.env.FORGE_BIN;
+  const home = process.env.HOME || "";
+  const candidates = ["forge", join(home, ".foundry/bin/forge")];
+  for (const c of candidates) {
+    const r = spawnSync(c, ["--version"], { encoding: "utf8" });
+    if (r.status === 0) return c;
+  }
+  return null;
+}
+
+function slitherBin() {
+  if (process.env.SLITHER_BIN) return process.env.SLITHER_BIN;
+  const r = spawnSync("slither", ["--version"], { encoding: "utf8" });
+  return r.status === 0 ? "slither" : null;
+}
+
+function run(cmd, args, cwd) {
+  const r = spawnSync(cmd, args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, PATH: `${process.env.HOME || ""}/.foundry/bin:${process.env.PATH || ""}` },
+    timeout: 120_000,
+  });
+  return {
+    ok: r.status === 0,
+    status: r.status,
+    stdout: r.stdout || "",
+    stderr: r.stderr || "",
+  };
+}
+
+function hashTree(dir) {
+  const h = createHash("sha256");
+  function walk(p) {
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      if (["lib", "out", "cache", ".git"].includes(p.split("/").pop())) return;
+      for (const name of readdirSync(p).sort()) walk(join(p, name));
+    } else if (st.isFile() && (p.endsWith(".sol") || p.endsWith(".toml") || p.endsWith(".md"))) {
+      h.update(p);
+      h.update(readFileSync(p));
+    }
+  }
+  walk(dir);
+  return h.digest("hex");
+}
+
+/**
+ * Run security gate on a template id.
+ * @param {string} templateId e.g. "safe-erc20"
+ * @param {{ allowSkipStatic?: boolean }} opts
+ */
+export function runProtocolTemplateGate(templateId, opts = {}) {
+  const allowSkipStatic = opts.allowSkipStatic !== false; // default allow skip if no slither
+  const dir = join(TEMPLATES_ROOT, templateId);
+  if (!existsSync(dir)) {
+    throw new Error(`protocol-templates: unknown template "${templateId}"`);
+  }
+
+  const forge = forgeBin();
+  if (!forge) {
+    throw new Error(
+      "protocol-templates: forge not found. Install Foundry (https://getfoundry.sh) then: cd protocols/templates/" +
+        templateId +
+        " && forge install && forge test"
+    );
+  }
+
+  // ensure libs (not vendored in git)
+  if (!existsSync(join(dir, "lib", "forge-std"))) {
+    const a = run(forge, ["install", "foundry-rs/forge-std", "--no-git"], dir);
+    if (!a.ok) throw new Error(`protocol-templates: forge install forge-std failed\n${a.stderr}`);
+  }
+  if (!existsSync(join(dir, "lib", "openzeppelin-contracts"))) {
+    const b = run(forge, ["install", "OpenZeppelin/openzeppelin-contracts@v5.0.2", "--no-git"], dir);
+    if (!b.ok) throw new Error(`protocol-templates: forge install openzeppelin failed\n${b.stderr}`);
+  }
+
+  const tests = run(forge, ["test", "-q"], dir);
+  if (!tests.ok) {
+    throw new Error(
+      `protocol-templates: forge test FAILED for ${templateId}\n${tests.stdout}\n${tests.stderr}`.slice(0, 2000)
+    );
+  }
+
+  let staticAnalysis = { tool: null, ok: true, skipped: true, reason: "slither not installed" };
+  const slither = slitherBin();
+  if (slither) {
+    const s = run(slither, [".", "--filter-paths", "lib", "--exclude-dependencies"], dir);
+    staticAnalysis = {
+      tool: "slither",
+      ok: s.ok,
+      skipped: false,
+      stdout: (s.stdout || "").slice(0, 1500),
+      stderr: (s.stderr || "").slice(0, 500),
+    };
+    if (!s.ok && !opts.allowStaticFail) {
+      throw new Error(`protocol-templates: slither FAILED for ${templateId}\n${s.stdout}\n${s.stderr}`.slice(0, 2000));
+    }
+  } else if (!allowSkipStatic) {
+    throw new Error("protocol-templates: slither required (allowSkipStatic=false) but not installed");
+  }
+
+  const sourceHash = hashTree(dir);
+  return {
+    ok: true,
+    templateId,
+    path: dir,
+    forgeTests: { ok: true, tool: "forge", summary: "forge test passed" },
+    staticAnalysis,
+    sourceHash,
+    disclaimer: TEMPLATE_AUDIT_DISCLAIMER,
+    firmAudit: false,
+  };
+}
+
+/**
+ * Build artifact after gate. Returns bytecode for unsigned deploy prepare.
+ */
+export function buildProtocolTemplate(templateId, opts = {}) {
+  const gate = runProtocolTemplateGate(templateId, opts);
+  const forge = forgeBin();
+  const dir = gate.path;
+  const build = run(forge, ["build", "-q"], dir);
+  if (!build.ok) {
+    throw new Error(`protocol-templates: forge build failed\n${build.stderr}`.slice(0, 1500));
+  }
+  // default contract name heuristic
+  const contractName = opts.contractName || (templateId === "safe-erc20" ? "SafeERC20" : null);
+  if (!contractName) throw new Error("protocol-templates: contractName required");
+  const artifactPath = join(dir, "out", `${contractName}.sol`, `${contractName}.json`);
+  if (!existsSync(artifactPath)) {
+    throw new Error(`protocol-templates: artifact missing at ${artifactPath}`);
+  }
+  const artifact = JSON.parse(readFileSync(artifactPath, "utf8"));
+  return {
+    gate,
+    contractName,
+    abi: artifact.abi,
+    bytecode: artifact.bytecode?.object || artifact.bytecode,
+    deployedBytecode: artifact.deployedBytecode?.object || artifact.deployedBytecode,
+    artifactPath,
+  };
+}

package/src/protocol-templates/prepare-deploy.mjs

@@ -0,0 +1,81 @@
+// Prepare unsigned deploy for a gated protocol template.
+// Never signs. Never broadcasts. Requires green forge tests first.
+
+import { ContractFactory, isAddress } from "ethers";
+import { stampPrepared } from "../prepare-envelope.mjs";
+import { buildProtocolTemplate, listProtocolTemplates, TEMPLATE_AUDIT_DISCLAIMER } from "./gate.mjs";
+
+export { listProtocolTemplates, TEMPLATE_AUDIT_DISCLAIMER };
+
+/**
+ * @param {object} args
+ * @param {string} args.templateId - e.g. safe-erc20
+ * @param {number} args.chainId
+ * @param {string[]} [args.constructorArgs] - ABI-encoded via ethers from values
+ * @param {any[]} [args.args] - constructor JS values (preferred)
+ * @param {string} [args.contractName]
+ */
+export async function prepareTemplateDeploy(args = {}, opts = {}) {
+  const templateId = String(args.templateId || "").trim();
+  if (!templateId) throw new Error("prepareTemplateDeploy: templateId required");
+  const chainId = Number(args.chainId);
+  if (!Number.isInteger(chainId) || chainId <= 0) {
+    throw new Error("prepareTemplateDeploy: chainId required");
+  }
+
+  const built = buildProtocolTemplate(templateId, {
+    contractName: args.contractName,
+    allowSkipStatic: opts.allowSkipStatic !== false,
+    allowStaticFail: opts.allowStaticFail === true,
+  });
+
+  if (!built.bytecode || built.bytecode === "0x") {
+    throw new Error("prepareTemplateDeploy: empty bytecode");
+  }
+
+  const bc = built.bytecode.startsWith("0x") ? built.bytecode : `0x${built.bytecode}`;
+  const ctorArgs = args.args ?? args.constructorArgs ?? [];
+  const factory = new ContractFactory(built.abi, bc);
+  const deployTx = await factory.getDeployTransaction(...(Array.isArray(ctorArgs) ? ctorArgs : []));
+  const data = deployTx.data;
+
+  // validate SafeERC20 constructor shape if applicable
+  if (templateId === "safe-erc20" && Array.isArray(ctorArgs)) {
+    const [name, symbol, supply, holder, owner] = ctorArgs;
+    if (!name || !symbol) throw new Error("safe-erc20: name/symbol required");
+    if (supply == null || BigInt(supply) <= 0n) throw new Error("safe-erc20: supply must be > 0");
+    if (!isAddress(String(holder))) throw new Error("safe-erc20: initialHolder must be address");
+    if (!isAddress(String(owner))) throw new Error("safe-erc20: initialOwner must be address");
+  }
+
+  return stampPrepared(
+    {
+      provider: "protocol-templates",
+      kind: "template-deploy",
+      templateId,
+      contractName: built.contractName,
+      chainId,
+      transaction: {
+        chainId,
+        to: null, // creation
+        data,
+        value: "0x0",
+      },
+      abi: built.abi,
+      bytecodeHash: built.gate.sourceHash,
+      gate: {
+        forgeTests: built.gate.forgeTests,
+        staticAnalysis: {
+          tool: built.gate.staticAnalysis.tool,
+          ok: built.gate.staticAnalysis.ok,
+          skipped: built.gate.staticAnalysis.skipped,
+        },
+        firmAudit: false,
+        disclaimer: TEMPLATE_AUDIT_DISCLAIMER,
+      },
+      requiresUserSignature: true,
+      note: "Unsigned deploy. User wallet signs. Template tests passed; not a firm audit.",
+    },
+    { provider: "protocol-templates", kind: "template-deploy" }
+  );
+}

package/src/public-api/agent-grants.mjs

@@ -0,0 +1,57 @@
+/**
+ * Agent grants — the embeddable entry point.
+ *
+ * Bounded, revocable, time-boxed permission for an agent to act for a user,
+ * where the user signs the grant and nobody ever holds their key. The pieces
+ * were already here but spread across public-control and public-api, reachable
+ * only by deep-importing internal paths. That is not something another team can
+ * build against, so this is the seam: one import, one documented surface.
+ *
+ * What makes it worth extracting rather than reimplementing per project:
+ *
+ *   - The owner signs a rendered, human-readable policy. Not an opaque hash.
+ *   - Every read is pure over an INJECTED store with an EXPLICIT clock, so the
+ *     same inputs always produce the same answer and it is testable without a
+ *     chain or a database.
+ *   - Revocation is first-class, not an afterthought bolted on later.
+ *   - `scanPublicReturn` enforces the no-secret invariant on anything that
+ *     leaves this layer, so a refactor cannot quietly start returning a key.
+ *
+ * Custody: this module prepares and validates. It never signs, never
+ * broadcasts, and never stores a private key. The custody boundary test walks
+ * the real import graph to keep it that way.
+ */
+
+export {
+  GRANT_STATUS,
+  classifyGrant,
+  listActiveGrants,
+  getGrant,
+} from "./grants.mjs";
+
+export {
+  ORCHESTRATOR_KINDS,
+  scanPublicReturn,
+  planConnection,
+  activateSession,
+  createSessionOrchestrator,
+  revokeSession,
+  describeActive,
+} from "../public-control/session-orchestrator.mjs";
+
+export * as policy from "../public-control/policy-schema.mjs";
+export * as render from "../public-control/policy-render.mjs";
+
+/**
+ * Human summary of what this layer guarantees. Safe to serve publicly; used by
+ * the docs gate to keep the claim and the code from drifting apart.
+ */
+export const GRANTS_POSTURE = Object.freeze({
+  userSigns: true,
+  houseCustody: false,
+  storesPrivateKeys: false,
+  revocable: true,
+  timeBoxed: true,
+  deterministicReads: true,
+  note: "Oracle prepares and validates grants. The user signs; Oracle never holds a key.",
+});

package/src/public-api/buzz-integration.mjs

@@ -0,0 +1,267 @@
+// Oracle ↔ Buzz integration API (public plane).
+//
+// Buzz should integrate Oracle **via HTTP**, not by embedding our private
+// executor. This module is the contract Buzz (or any partner) can call:
+//
+//   1) Discovery     GET  /public/buzz
+//   2) Grants        existing /public/connect/* + /public/grants/*
+//   3) Shared auth   POST /public/buzz/auth/verify   (capability tokens)
+//   4) Shared audit  POST /public/buzz/audit/{append,verify,entries}
+//
+// Hard boundaries (same as the rest of the public plane):
+//   - No private keys, no bearer mint, no broadcast.
+//   - Minting capabilities stays client-side (owner wallet signs).
+//   - Audit detail is scanned for secret shapes before append/response.
+//   - Fail closed on unknown fields / bad capability tags.
+
+import {
+  verifyCapability,
+  authPreimage,
+  AUTH_DOMAIN,
+} from "../agent-auth.mjs";
+import {
+  appendAudit,
+  verifyChain,
+  getEntries,
+  AUDIT_ACTIONS,
+  GENESIS_HASH,
+} from "../audit-log.mjs";
+import { assertNoSecretMaterial, SecretLeakError } from "./connect-agent.mjs";
+
+export const BUZZ_API_VERSION = 1;
+export const BUZZ_INTEGRATION_ID = "oracle-buzz-http-v1";
+
+/** Public-safe audit actions partners may append. */
+export const BUZZ_PUBLIC_AUDIT_ACTIONS = Object.freeze([
+  AUDIT_ACTIONS.AUTH_GRANT,
+  AUDIT_ACTIONS.AUTH_OK,
+  AUDIT_ACTIONS.AUTH_FAIL,
+  "connect.assemble",
+  "connect.bound",
+  "grant.revoke",
+  "grant.active",
+  "buzz.ping",
+]);
+
+export function buildBuzzCatalog({ baseUrl = null, plans = null } = {}) {
+  const base = baseUrl || "";
+  return Object.freeze({
+    ok: true,
+    integration: BUZZ_INTEGRATION_ID,
+    version: BUZZ_API_VERSION,
+    plane: "public",
+    unsigned: true,
+    custody: "user-signs",
+    defaultPosture: "DISARMED",
+    summary:
+      "Oracle exposes grants, capability verify, and audit over HTTP so Buzz (or any client) can integrate without house keys.",
+    doAll: {
+      api: true,
+      sharedAuth: true,
+      sharedAudit: true,
+      note: "One surface — not three separate products. Buzz calls these routes; user still signs grants/capabilities.",
+    },
+    // Access tiers are published in the discovery document so an integrator
+    // can see the ceiling before writing code against it. Anonymous access
+    // keeps working; a key raises the limit. NFT status never changes access.
+    access: plans
+      ? Object.freeze({
+          anonymous: true,
+          keyHeader: "authorization: Bearer <key>",
+          plans: Object.freeze(plans),
+          note: "Unkeyed requests are served at the free tier. Keys never carry secrets or grant custody.",
+        })
+      : undefined,
+    endpoints: Object.freeze([
+      {
+        method: "GET",
+        path: `${base}/public/buzz`,
+        purpose: "Discovery catalog for Buzz integrators",
+      },
+      {
+        method: "GET",
+        path: `${base}/public/health`,
+        purpose: "Liveness",
+      },
+      {
+        method: "GET",
+        path: `${base}/public/config`,
+        purpose: "Public custody config (Privy flags, no secrets)",
+      },
+      {
+        method: "POST",
+        path: `${base}/public/connect/request`,
+        purpose: "Build human-readable connect request",
+      },
+      {
+        method: "POST",
+        path: `${base}/public/connect/assemble`,
+        purpose: "Assemble unsigned grant for user personal_sign",
+      },
+      {
+        method: "POST",
+        path: `${base}/public/grants/active`,
+        purpose: "List active grants from injected store",
+      },
+      {
+        method: "POST",
+        path: `${base}/public/grants/get`,
+        purpose: "Get one grant by id",
+      },
+      {
+        method: "POST",
+        path: `${base}/public/buzz/auth/verify`,
+        purpose: "Verify owner-signed capability token (shared auth)",
+      },
+      {
+        method: "POST",
+        path: `${base}/public/buzz/auth/preimage`,
+        purpose: "Build exact capability signing preimage (client mints)",
+      },
+      {
+        method: "POST",
+        path: `${base}/public/buzz/audit/append`,
+        purpose: "Append public audit event to shared hash chain",
+      },
+      {
+        method: "POST",
+        path: `${base}/public/buzz/audit/verify`,
+        purpose: "Verify audit chain integrity",
+      },
+      {
+        method: "POST",
+        path: `${base}/public/buzz/audit/entries`,
+        purpose: "Read audit entries (paginated)",
+      },
+    ]),
+    auth: Object.freeze({
+      domain: AUTH_DOMAIN,
+      format: '["auth", ownerAddress, conditions, signature]',
+      mint: "client-side only — owner wallet personal_sign(preimage)",
+      verify: "POST /public/buzz/auth/verify",
+      clauses: ["chain=<id>", "action=<scope>", "expires<unix", "notbefore>unix"],
+    }),
+    audit: Object.freeze({
+      model: "sha256 hash-chain",
+      genesis: GENESIS_HASH,
+      publicActions: BUZZ_PUBLIC_AUDIT_ACTIONS,
+      streamDefault: "buzz-public",
+    }),
+    never: Object.freeze([
+      "private-executor-broadcast",
+      "server-side-capability-mint-with-house-key",
+      "raw-private-keys-in-responses",
+    ]),
+  });
+}
+
+export function handleBuzzAuthPreimage(body = {}) {
+  const agentAddress = body.agentAddress;
+  const conditions = body.conditions == null ? "" : String(body.conditions);
+  if (!agentAddress || typeof agentAddress !== "string") {
+    const err = new Error("agentAddress required");
+    err.code = "invalid-auth-preimage";
+    throw err;
+  }
+  const preimage = authPreimage(agentAddress, conditions);
+  return {
+    ok: true,
+    domain: AUTH_DOMAIN,
+    agentAddress,
+    conditions,
+    preimage,
+    note: "Owner personal_sign(preimage). Server never mints with a house key.",
+  };
+}
+
+export function handleBuzzAuthVerify(body = {}) {
+  const tag = body.capability ?? body.tag ?? body.auth;
+  const agentAddress = body.agentAddress;
+  if (tag == null) {
+    const err = new Error("capability tag required");
+    err.code = "invalid-capability";
+    throw err;
+  }
+  if (!agentAddress) {
+    const err = new Error("agentAddress required");
+    err.code = "invalid-capability";
+    throw err;
+  }
+  const result = verifyCapability(tag, {
+    agentAddress,
+    chainId: body.chainId ?? null,
+    action: body.action ?? null,
+    now: body.now ?? null,
+  });
+  if (!result || result.ok !== true) {
+    return {
+      ok: false,
+      valid: false,
+      reason: (result && (result.reason || result.error)) || "invalid",
+      result,
+    };
+  }
+  return {
+    ok: true,
+    valid: true,
+    result,
+  };
+}
+
+function assertPublicAuditAction(action) {
+  if (!BUZZ_PUBLIC_AUDIT_ACTIONS.includes(action)) {
+    const err = new Error(
+      `action not allowed on public buzz audit: ${action}`
+    );
+    err.code = "audit-action-forbidden";
+    throw err;
+  }
+}
+
+export async function handleBuzzAuditAppend(body = {}, { path } = {}) {
+  const action = body.action;
+  if (!action) {
+    const err = new Error("action required");
+    err.code = "invalid-audit";
+    throw err;
+  }
+  assertPublicAuditAction(action);
+  const detail = body.detail ?? null;
+  try {
+    assertNoSecretMaterial(detail);
+  } catch (e) {
+    if (e instanceof SecretLeakError || e?.name === "SecretLeakError") {
+      const err = new Error("audit detail blocked: secret-shaped material");
+      err.code = "secret-leak-blocked";
+      throw err;
+    }
+    throw e;
+  }
+  const entry = await appendAudit({
+    action,
+    actor: body.actor ?? null,
+    objectId: body.objectId ?? null,
+    detail,
+    stream: body.stream || "buzz-public",
+    path,
+  });
+  return { ok: true, entry };
+}
+
+export function handleBuzzAuditVerify(body = {}, { path } = {}) {
+  const out = verifyChain({
+    stream: body.stream || "buzz-public",
+    path,
+  });
+  return { ok: true, ...out };
+}
+
+export function handleBuzzAuditEntries(body = {}, { path } = {}) {
+  const entries = getEntries({
+    stream: body.stream || "buzz-public",
+    fromSeq: body.fromSeq ?? 1,
+    limit: Math.min(Number(body.limit || 100), 500),
+    path,
+  });
+  return { ok: true, count: entries.length, entries };
+}