MnemoPay
How-to · TypeScript

Build a tamper-evident audit log for an AI agent (runnable, verified on 1.15.2)

Published 2026-11-04 · J&B Enterprise LLC · Apache-2.0 project

Record agent actions, export a bundle, verify it from disk, then edit, delete and duplicate events to see what is caught and what is not.

This is a complete, runnable example against the published package. Every command and output below was produced with @mnemopay/sdk@1.15.2 from npm on Node v25.9.0 on 2026-11-04.

Setup

mkdir audit-demo && cd audit-demo
npm init -y
npm install @mnemopay/sdk@1.15.2
# save the script below as audit.mjs

The SDK is ESM-first; the governance subpath is @mnemopay/sdk/governance (it also works with require since 1.15.1). The audit chain needs no API key and makes no network calls.

The script

import { AuditChain, verifyBundle } from "@mnemopay/sdk/governance";
import { readFileSync } from "node:fs";

// 1. Record events. Each emit() is also appended to a JSONL file as it happens.
const chain = new AuditChain({ path: "./agent-audit.jsonl" });
chain.emit("action.proposed", { agent: "refund-bot", action: "refund", amountUsd: 40, orderId: "A-1001" });
chain.emit("approval.granted", { approver: "ops@example.com" });
chain.emit("action.executed", { txId: "tx-1001", amountUsd: 40 });

// 2. Export a bundle (events + Merkle root) to disk.
const bundle = chain.rollAndExport({ pathOut: "./bundle.json", meta: { system: "refund-bot" } });
console.log("root:", bundle.merkle_root.slice(0, 16) + "...");

// 3. Verify what is on disk, not what is in memory.
const verify = (b) => {
  const base = verifyBundle(b);
  if (!base.ok) return base;
  // verifyBundle recomputes the root; it does not check these two things, so check them yourself.
  const ids = new Set(b.events.map((e) => e.id));
  if (ids.size !== b.events.length) return { ok: false, reason: "duplicate_event_id" };
  for (let i = 0; i < b.events.length; i++) {
    if (b.events[i].sequence !== b.events[0].sequence + i) return { ok: false, reason: "sequence_gap" };
  }
  return { ok: true };
};
const onDisk = JSON.parse(readFileSync("./bundle.json", "utf8"));
console.log("untouched:      ", verify(onDisk));

// 4. Tamper in three ways.
const edited = structuredClone(onDisk);
edited.events[2].payload.amountUsd = 4;
console.log("edited event:   ", verify(edited));

const deleted = structuredClone(onDisk);
deleted.events.splice(1, 1);
console.log("deleted event:  ", verify(deleted));

const dup = structuredClone(onDisk);
dup.events.push(structuredClone(onDisk.events[2]));
console.log("verifyBundle alone on a duplicated last event:", verifyBundle(dup));
console.log("verify() with the extra checks:                ", verify(dup));

What it prints

root: 025f9f80c313fab5...
untouched:       { ok: true }
edited event:    { ok: false, reason: 'root_mismatch' }
deleted event:   { ok: false, reason: 'root_mismatch' }
verifyBundle alone on a duplicated last event: { ok: true }
verify() with the extra checks:                 { ok: false, reason: 'duplicate_event_id' }

The root differs on every run because event ids and timestamps are generated. The verdicts are stable.

How it works

What this does not prove

1. Someone holding the whole bundle can rewrite it. An editor who changes an event and also recomputes merkle_root produces a bundle that verifies. Tamper-evidence only bites if the root (or the JSONL stream) is stored somewhere the editor cannot reach: a separate system, a signed message to a third party, or an external anchor. The SDK has an OnChainAnchorSink interface and a mock for that; no production MnemoPay deployment anchors on chain yet, and the one real anchor so far is a test bundle (on Base mainnet, 2026-11-01).

2. Time. The timestamps are written by the process that emits the events. They are not proof of when the event happened.

3. A known gap in verifyBundle (1.15.2). The Merkle tree pairs an odd last node with itself, so appending an exact copy of the final event to an odd-length bundle leaves the root unchanged and verifyBundle still returns ok: true. The script above adds two checks (unique event ids, contiguous sequence numbers) that catch it. This should be fixed in the library itself; until then, keep the extra checks. Edits and deletions are caught by verifyBundle itself, as shown.

4. Hardware-backed signing has not been tested; the SDK takes an injected signer and has only been exercised with software keys.

Next steps

Related

Want help wiring this into a real agent workflow? We run a small number of design-partner pilots. The SDK itself stays free and open source.