@omegaengine/audit

Tamper-evident audit + provenance for AI agents — prove what your agent did, hash-chained, verifiable, auditor-ready.

Wrap your agent's tool calls. Every call is appended to a local, append-only, SHA-256 hash-chained ledger. Later, anyone can recompute the chain and detect any edit, reorder, insertion, or deletion — offline, in one command, with no signup and no trust in us.

• Zero runtime dependencies. Node's built-in crypto only. No SDK, no account — and no network, except the optional anchor command, which is online by definition.
• Offline and local. The ledger is a plain JSONL file on your disk. You own it.
• Framework-agnostic. Wrap any async function — plain tools, OpenAI/LangChain/Vercel-AI tool defs, MCP handlers.
• Independently verifiable. omega-audit verify recomputes the whole chain. Break one byte and it fails.
• Apache-2.0.

Why now

The EU AI Act's record-keeping obligation (Article 12) applies from December 2, 2027 for standalone (Annex III) high-risk AI systems — the EU Digital Omnibus, adopted June 29, 2026, deferred it from the original August 2, 2026 date (embedded Annex I systems follow on August 2, 2028; the Act's transparency obligations — chatbot disclosure, synthetic-content labeling — still apply from August 2, 2026). When it applies, providers must ensure their systems automatically record events (logs) over their lifetime, to a degree appropriate to the system's purpose.

The deadline moved; the ask didn't. Regulators and enterprise buyers already ask for tamper-evident logs — in procurement questionnaires, vendor security reviews, and incident post-mortems — and an audit trail is only convincing if it was accumulating before anyone asked for it. A policy document that says "we log agent actions" is not evidence. Evidence is a log you can hand an auditor that provably has not been altered — and the way to have years of verifiable history when auditors do ask is to start appending now, not to race a deadline.

Append-only, cryptographically hash-chained logs are the well-established way to make an audit trail tamper-evident: each record commits to the one before it, so the chain itself proves nothing was quietly changed after the fact. That's the same construction behind Git commit history and RFC 6962 Certificate Transparency. This package gives you that construction for your agent's actions, in about twenty minutes.

This is honest scope: @omegaengine/audit produces tamper-evident local logs — you can detect tampering by recomputing the chain. It is not, by itself, a certification, a signature from us, or proof to a third party who doesn't have your file. For cross-organization, independently-anchored proof, see Anchoring to the transparency log below.

20-minute quickstart

1. Install

npm i @omegaengine/audit

2. Wrap a tool

import { createLedger, wrapTool } from "@omegaengine/audit";

// One local, append-only ledger file. Offline — no signup, no network.
const ledger = createLedger("ledger.jsonl");

// Your existing tool — any async function.
async function sendEmail(to: string, subject: string) {
  // ... your real implementation ...
  return { delivered: true };
}

// Wrap it. Same signature, same return value — it just records every call.
const trackedSendEmail = wrapTool(ledger, "send_email", sendEmail);

await trackedSendEmail("[email protected]", "Q3 evidence");

Each call appends one record: { tool, args, ok, result | error, durationMs }. Errors are recorded too (with ok: false and the message) and then re-thrown unchanged, so wrapping never swallows a failure.

This composes with agent frameworks: an OpenAI or LangChain tool is just an async function with a schema, so wrap its implementation and register the wrapped version. Nothing about your agent loop changes.

3. Look at the ledger

ledger.jsonl is one JSON object per line — readable, greppable, diffable:

{"seq":0,"ts":"2026-08-02T09:00:00.000Z","action":{"tool":"send_email","args":["[email protected]","Q3 evidence"],"ok":true,"result":{"delivered":true},"durationMs":501},"prevHash":"0000…0000","hash":"a1b2…"}

Every record's hash is sha256(canonicalJson({ seq, ts, action, prevHash })), and its prevHash is the previous record's hash (the first record links to 64 zeros). That chain is what makes tampering detectable.

4. Verify it

npx omega-audit verify ledger.jsonl

✓ 3 records — chain intact & tamper-evident

Exit code 0 when intact, 1 when tampered. Drop it in CI to fail a build if an agent's audit trail was touched.

You can also verify in code:

import { verify } from "@omegaengine/audit";

const result = verify("ledger.jsonl");
// { valid: true, records: 3 }
// or { valid: false, records: 3, brokenAt: 2, reason: "record 2 was edited — …" }

See it break: the tamper demo

One command builds a small ledger, tampers a record, and shows verification catch it:

npx omega-audit demo

omega-audit demo — tamper-evident agent audit in one command

1. An agent runs three tool calls. Each one is appended to a hash-chained ledger:

   #0  search_web  hash=c3343c18c991…  prev=000000000000…
   #1  read_file  hash=ec5b3670856a…  prev=c3343c18c991…
   #2  send_email  hash=63f0f3d4c2ca…  prev=ec5b3670856a…

2. Verify the untouched ledger:

   $ omega-audit verify ledger.jsonl
   ✓ 3 records — chain intact & tamper-evident

3. Now someone quietly edits record #2 to hide who the email went to:

   before:  send_email → [email protected]
   after:   send_email → [email protected]   (hash left unchanged to hide the edit)

4. Verify again — the chain no longer recomputes:

   $ omega-audit verify ledger.jsonl
   ✗ TAMPER DETECTED at record 2: record 2 was edited — its stored hash 63f0f3d4…4e40 ≠ the recomputed hash 6c8791fd…ae2e

That ✗ is the whole point: the record was changed, and verification proved it.
Nothing here touched the network. You can run the same check on your own ledger.

The demo command exits 1 — its whole job is to prove that a tampered ledger fails verification.

Enforce vs. prove

These are two different jobs, and you want both:

• A policy layer enforces — it decides, at run time, whether an action is allowed and blocks the ones that aren't.
• @omegaengine/audit proves — it produces the independent, tamper-evident evidence trail of what actually happened, which you can verify after the fact.

Enforcement without evidence is a claim. Evidence without enforcement is a bystander. Run your guardrails to stop bad actions; run @omegaengine/audit to prove — to yourself, to an auditor, to a customer — exactly what your agent did and that the record wasn't altered.

Anchor to the transparency log (optional)

Your local ledger is tamper-evident to anyone who has the file. To make it verifiable across organizations — so a customer or auditor who does not have your machine can still confirm the record — you anchor the ledger's root to a public, append-only transparency log. This is the one online command in the package; everything else stays offline.

export OMEGA_API_KEY=...   # your org API key — anchoring writes to the hosted log
npx omega-audit anchor ledger.jsonl --api https://omegaengine.ai

What it does, in order (and it fails closed at every step):

1. Verifies the ledger locally first. An invalid ledger is refused — anchoring is a claim of integrity, and this tool will not make that claim about a broken chain.
2. Computes an RFC 6962 Merkle root over the entries' record hashes (0x00/0x01 leaf/node domain separation, byte-identical to the hosted log's own implementation).
3. Checks consistency with your previous anchor. Anchor state lives in a sidecar file next to the ledger (ledger.jsonl.anchor.json, storing { ledgerId, anchors: [...] }). On every anchor after the first, the tool recomputes the previously anchored prefix — if your history was rewritten (even re-hashed into a chain that verifies again), that's reported as a fork and refused — and submits an RFC 6962 §2.1.2 consistency proof alongside the new root.
4. POSTs to /api/v2/anchor, records the accepted anchor in the sidecar, and prints the inclusion proof the log returned.

What an anchor proves — and what it doesn't

An accepted anchor proves: this exact prefix of this ledger existed, unaltered, no later than the log's signed-tree-head (STH) timestamp. That's the whole claim. It does not prove:

• completeness — entries your agent never wrote (or wrote to a second, unanchored ledger) are invisible to the anchor; omission within the window since the previous anchor is likewise undetectable;
• truth — that the recorded events actually happened as described;
• anything about entries appended after the anchored prefix — those are unanchored until the next omega-audit anchor run.

The STH timestamp is currently operator-attested (you trust the log operator's clock until external STH witnessing ships). Anchoring often is how you shrink the unverified window.

Beyond anchoring, OmegaEngine offers long-retention storage for multi-year record-keeping regimes (for example SEC Rule 17a-4 or HIPAA retention) and auditor exports — signed bundles checkable with the open-source @omegaengine/verify tool, no OmegaEngine account required.

The local package is fully useful on its own and stays free and open source. The hosted log is the optional upgrade when "verifiable on my disk" needs to become "verifiable by someone else."

Two-sided evidence: counterparty exchange

When two agents transact — a buyer agent and a seller agent, say — each one's ledger records only its own side of the story. The exchange verbs let the two ledgers mutually reference each other's pre-exchange chain tips, turning two one-sided logs into a tamper-evident pair. No signing keys required: the evidence is the hash chains themselves.

# Agent A pins its current chain tip into a compact token (offline):
npx omega-audit exchange a.jsonl --tx deal-4711
# → {"transactionId":"deal-4711","tipHash":"9f2c…","treeSize":42}

# A sends that token to B out of band (over the transaction rail, email, anything).
# B appends it as a NORMAL hash-chained ledger entry:
npx omega-audit record-counterparty b.jsonl --token '{"transactionId":"deal-4711",…}'

# …and vice versa: B runs `exchange`, A runs `record-counterparty` with B's token.

# Later, anyone holding both files can check the pair:
npx omega-audit verify-exchange a.jsonl b.jsonl --tx deal-4711
# ✓ MUTUAL — exit 0. one_way / invalid exit 1 (fail-closed).

The counterparty record is an ordinary entry — { tool: "omega.counterparty", args: { transactionId, counterpartyTipHash, counterpartyTreeSize } } — so it is covered by omega-audit verify like everything else and anchorable via the existing omega-audit anchor verb, which adds an independent time of existence to the mutual reference.

Verdicts:

• mutual — both ledgers verify, and each contains a counterparty entry for the transaction whose recorded tip matches the other ledger's chain, recomputed from entry content at the stated size.
• one_way — exactly one ledger references the other. This is an asymmetric one-shot reference, and the tool names it that — it is never presented as mutual.
• invalid — anything else: a ledger fails verification, a reference doesn't match (which is exactly what post-exchange tampering looks like), or neither side recorded the exchange.

What a mutual result proves — and what it doesn't

It proves mutual attestation and (once anchored) time of existence: both ledgers existed in the referenced states and referenced each other by the time they were anchored. It does not prove:

• truth — that the recorded transaction actually happened as described. A ledger is testimony with tamper-evidence, not ground truth.
• independence — that the two ledgers belong to two independent parties. One operator holding two ledgers can always manufacture a "mutual" pair with itself. Collusion resistance is not a property of this construction — it comes only from identity cost, external rails, or graph analysis, which live outside this package.

The TypeScript package only, for now: the Python twin (pip install omega-audit) does not yet include the exchange verbs — parity is deferred.

API

createLedger(path: string): Ledger
  ledger.append(action): LedgerEntry   // append one record; returns it
  ledger.size(): number
  ledger.tipHash(): string             // hash of the last record (chain tip)

wrapTool(ledger, name, fn): fn         // wrap a named async tool; records every call
capture(ledger, fn): fn                // like wrapTool, using fn.name

verify(path: string): VerifyResult
  // { valid, records, brokenAt?, reason? }

readLedger(path): LedgerEntry[]        // parse JSONL into typed records (no chain check)
verifyEntries(entries): VerifyResult   // verify already-parsed records
canonicalJson(value): string           // the deterministic serializer used for hashing
sha256hex(s): string

// Anchoring (the one online call — everything above is offline)
anchorLedger(path, { apiBase, ledgerId?, apiKey? }): Promise<AnchorResult>
  // verify → merkle root → consistency vs prior anchor → POST /api/v2/anchor
  // → append to <ledger>.anchor.json; throws (fail-closed) on any refusal/failure
readAnchorSidecar(path): AnchorSidecar | null   // { ledgerId, anchors: [...] }

// Two-sided evidence (offline, no keys) — mutual attestation, never ground truth
proposeExchange(ledgerPath, transactionId): ExchangeToken
  // { transactionId, tipHash, treeSize } — refuses invalid/empty ledgers
recordCounterparty(ledgerPath, theirToken, myNote?): LedgerEntry
  // appends { tool: "omega.counterparty", args: { transactionId,
  // counterpartyTipHash, counterpartyTreeSize } } — a normal, anchorable entry
verifyExchange(aPath, bPath, transactionId): ExchangeVerification
  // { status: "mutual" | "one_way" | "invalid", reason, a, b }
parseExchangeToken(json): ExchangeToken        // strict, fail-closed
recomputeTipAt(entries, size): string          // chain tip recomputed from content

// RFC 6962 Merkle tree over record hashes (offline; byte-identical to the hosted log)
merkleRoot(hashes): string
inclusionProof(index, hashes): string[]
verifyInclusion(leafIndex, treeSize, leafHashHex, auditPath): string | null
consistencyProof(firstSize, hashes): string[]
verifyConsistency(first, second, firstRoot, secondRoot, proof): boolean

A LedgerEntry is { seq, ts, action, prevHash, hash }.

Design partners

We're looking for teams putting agents in front of real users or real money who need to prove what those agents did. If you're wiring agent actions into an audit or compliance story — EU AI Act, financial record-keeping, healthcare — we'd like to build with you. Open an issue on github.com/TheArkhitect/Omegaengine or reach out via omegaengine.ai.

License

Apache-2.0. See the repository root for the full text.