@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, no network.
• 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("auditor@example.com", "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":["auditor@example.com","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 → auditor@example.com
   after:   send_email → attacker@evil.example   (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.

The record hashing here is byte-compatible with the OmegaEngine platform's canonical JSON + SHA-256, so your local ledger is already in the shape the hosted log expects. OmegaEngine offers, as a hosted backend:

• Anchoring your ledger root into a public RFC 6962 transparency log for cross-org, independently-checkable proof of inclusion.
• Long-retention storage to support multi-year record-keeping regimes (for example SEC Rule 17a-4 or HIPAA retention).
• Auditor exports — signed, verifiable bundles an auditor can check 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."

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

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.