Build a tamper-evident audit log for an AI agent (runnable, verified on 1.15.2)
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
chain.emit(kind, payload)adds an event with a UUID, a sequence number and an ISO timestamp. With thepathoption each event is also appended to a JSONL file as it happens, so a crash does not lose the tail.- Each event is canonicalised (sorted keys, no whitespace) and hashed with SHA-256. Hashes are paired up the tree to a single Merkle root. Change any byte of any event and the root changes.
verifyBundle(bundle)recomputes the root from the events and compares it withbundle.merkle_root. It can also call your signature check per event (verifyEventSignature) if you pass asignerwhen creating the chain.
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
- Add a human gate before risky actions: policy checks and approvals with the SDK and the MCP server.
- Understand the regulatory backdrop: EU AI Act Article 12, with sources.
- Package a finished run as an Article 12-shaped bundle:
buildArticle12Bundle(see the demo bundle).
Related
- EU AI Act Article 12 logging for AI agents
- Human approval for agent actions: SDK and MCP
- Audit trail vs observability logs