Ledger record format#

The audit ledger is an append-only list of JSON records, one per line (JSONL), each linked to the previous one by a SHA-256 hash. The format is defined in pkg/audit and is the same for the file ledger and for PostgreSQL (audit_chain.line holds the exact line). This page is precise enough to write an independent verifier.

Record fields#

Reserved ext keys#

ext values are strings and never contain argument values, prompts or matched secrets: DLP records detector IDs and counts (iban:2,email:1).

The hash#

flowchart LR
    R["Record without hash"] --> C["Canonical JSON<br/>sorted keys, no whitespace,<br/>no HTML escaping, every member present"]
    C --> H["SHA-256, hex"]
    H --> REC["record.hash"]
    PREV["previous record.hash<br/>(genesis: 64 zeros)"] --> R
    REC --> NEXT["next record.prevHash"]

1. Take the record and drop hash.
2. Encode it as canonical JSON: object keys sorted by byte order, no insignificant whitespace, no HTML escaping, times as RFC 3339 UTC with nanoseconds, numbers in shortest round-trip form, and every member present (empty strings included).
3. For schema 2 and above, schema and ext are part of the canonical form (ext is {} when empty). Records without schema hash exactly as schema 1, so a ledger may mix both.
4. hash = lowercase hex SHA-256 of those bytes.
5. Verification walks the chain: seq must be the expected number, prevHash must equal the previous hash, and the recomputed hash must equal hash. The first failure is firstBadSeq.

The ledger's canonical JSON is its own encoder in pkg/audit, not RFC 8785 (JCS); JCS (pkg/jcs) is used for A2A card signatures and usage reports.

Golden vectors#

Record seq=1, time=2026-09-30T12:00:00Z, session=s1, namespace=team-a, agent=coder, user=alice@acme.eu, server=echo, tool=echo, decision=allow, rule=p/r, latencyMs=1.5, costUsd=0.01, prevHash=<genesis> (pkg/audit/schema_test.go). The v1 canonical form is:

{"agent":"coder","approver":"","argsSha256":"","costUsd":0.01,"decision":"allow","latencyMs":1.5,"namespace":"team-a","prevHash":"0000000000000000000000000000000000000000000000000000000000000000","reason":"","rule":"p/r","seq":1,"server":"echo","session":"s1","time":"2026-09-30T12:00:00Z","tool":"echo","user":"alice@acme.eu"}

Checkpoints#

A hash chain alone does not stop someone who rewrites the whole file and recomputes every hash. Checkpoints anchor the head with a key the forger does not hold.

Signed checkpoints are verifiable by anyone with the public keys from GET /v1/audit/jwks (no secret needed): maqpna audit verify LEDGER --jwks jwks.json.

Intent records (closed mode)#

With auditFailurePolicy: closed, an allowed call gets two records: an intent record (ext.phase=intent) written and made durable before the call is forwarded, and the usual completion record afterwards. If the intent append fails, the call is refused (audit_unavailable). Intent records are not shown as timeline steps.

Evidence bundle#

maqpna audit export and GET /v1/audit/export produce a bundle with schema maqpna.io/audit-evidence/v1 and the members generatedAt, frameworks, filter, range, recordCount, recordSchemas, ledgerRecordCount, chainHead {seq, hash}, verified, verifyError?, firstBadSeq?, decisionsByAction, toolsUsed, approvals, totalCostUsd, records, and with signed checkpoints signedCheckpoints and checkpointJwks.

What you see#

One schema 2 record, as stored (values illustrative):

{"seq":1042,"time":"2026-10-02T12:03:11.204518Z","session":"fix-4821","namespace":"team-a","agent":"coder","user":"alice@acme.eu","server":"kubernetes","tool":"delete_pod","argsSha256":"9f2c41d0…","decision":"allow","rule":"prod-guard/k8s-delete","reason":"destructive","approver":"bob@acme.eu","latencyMs":412.7,"costUsd":0.0004,"prevHash":"ab31f0c2…","hash":"77e0a9d4…","schema":2,"ext":{"approverIss":"https://idp.acme.eu/realms/ops","approvers":"bob@acme.eu","traceId":"4bf92f3577b34da6a3ce929d0e0e4736"}}

$ maqpna audit verify audit.jsonl
OK: 1042 records, hash chain intact

See maqpna audit verify and maqpna audit export.

Related#

• Audit ledger
• Audit ledger flow
• State backend schema
• Key management