Tamper-evident audit logs without a server farm

Audit trails stand or fall on one question: can someone change something after the fact without it being noticed? For our internal tool tseit we built a log format that answers this question with on-board means — a SHA-256 hash chain over append-only JSONL, lean enough for a single workstation, strict enough for a compliance audit.

The problem

Anyone who records activities, working time or system events — for their own accountability, for GDPR-compliant time tracking or for a compliance audit — has a structural problem with ordinary log files: a text file proves nothing. Anyone with write access can change, delete or reorder entries — and afterwards the result looks exactly as credible as the original. Commercial solutions usually answer this with infrastructure: central servers, WORM storage, signed database appliances. For a project portfolio on a single workstation, that is the wrong weight class.

The design

Each project gets its own chain of event entries, stored as append-only JSONL: one file per recording period, one JSON object per line, exactly seven mandatory fields. Two of them carry the chain: prev_hash and chain_hash.

chain_hash_n  = SHA256( canonical_payload_n || prev_hash_n )
prev_hash_n+1 = chain_hash_n
prev_hash_0   = "0" × 64

The hash runs over a canonical serialisation of the entry: keys sorted lexicographically, the most compact notation (no whitespace), UTF-8 left untouched (umlauts and special characters enter the hash exactly as they sit on disk). That sounds like a detail, but it is the core: only the unambiguous canonical form makes the hash reproducible — and only the reproducible hash makes verification possible.

Verification is correspondingly plain: read all entries, recompute every hash, check every link. It runs in a fraction of a second over months of entries.

What is guaranteed — and where the limit lies

The verifier reliably detects:

• field manipulation — any byte-level change to an entry breaks its hash,
• hash forgery — a recomputed chain_hash exposes the forged one,
• deletion of an entry in the middle of the chain — its successor points into the void,
• reordering — any swap breaks the linkage.

And now the part that separates serious documentation from product brochures: detecting the truncation of the most recent entries at the end of the chain requires an external anchor — a shortened chain is consistent in itself. A signed Git commit pointing at the latest chain_hash closes this gap; we deliberately moved it to a later stage and recorded the limit in the format specification. Precisely this transparency is an asset: whoever knows exactly what the mechanism covers can direct the scarce resource of human review attention at the remaining gap — review work becomes plannable and measurably more productive.

Three decisions that have proven themselves

First: the format module is pure standard library. Anything meant to carry evidential weight deserves a foundation with the half-life of the language itself rather than that of a dependency tree — any Python installation of the coming years can read and verify these files.

Second: confidential areas are separated at the architecture level. Projects with confidentiality requirements write to fully isolated vaults with their own chain. The separation is enforced as a hard invariant in the code — a misconfiguration stops the run with a clear error, and the data stays where it belongs. Isolation as an architectural property rather than a UI hint.

Third: tool choice according to the threat model. Distributed consensus mechanisms solve the problem of mutually distrusting parties having to agree on a shared state. Our scenario is considerably simpler — one party, one workstation. A local hash chain plus, in due course, a signed anchor achieves the same here as a blockchain, at a fraction of the complexity.

Why this is more than a time-tracking feature

Write protection is good — append-only is better. Trust is good — a verifiable hash chain is better. Marketing guarantees are a matter of taste; documented limits are risk management in practice. This way of thinking carries our compliance work in general: auditability is an architectural property that you build in from line one — and that pays off in every later audit. The format is backed by more than 200 tests, including one dedicated test per forensic guarantee — including the cases in which verification must fail.