HMAC audit chains, explained without the crypto textbook

The one-line explanation

An HMAC chain is a linked list where each node's HMAC uses the previous node's HMAC as part of its salt. Flip one bit anywhere and the chain breaks at exactly that point.

Why not just SHA256?

Plain sha256 chains work — until an attacker with write access to your log store re-signs every downstream entry. HMAC uses a shared secret salt, so re-signing requires the salt. Move the salt off the same machine as the log store and you've raised the attack cost dramatically.

The code

import hmac, hashlib, json
def compute(prev_hmac, entry, salt):
    canonical = json.dumps({k:v for k,v in entry.items() if k != 'hmac'}, sort_keys=True, separators=(',',':'))
    msg = f"{prev_hmac}|{canonical}".encode()
    return hmac.new(salt.encode(), msg, hashlib.sha256).hexdigest()

That's the whole trick. Every insert reads the last entry's HMAC, computes a new one, and stores it. Verification walks the chain in order, recomputing.

Salted twice

Use two independent salts and store the chain twice — primary + backup. Because HMAC output is completely different for different salts, an attacker who compromises one chain (say, they got read access to the log DB) still cannot forge entries in the other. AgentForge stores both.

The three failure modes

1. Race. Two writers pick the same prev_hmac. Fix with a lock or atomic head-doc.
2. Skipped genesis. Verifier assumes the first entry links to some external anchor. If your genesis is undocumented, verification silently accepts a mid-chain segment. Fix: hard-code a GENESIS sentinel string.
3. Silent legacy. You bumped the code and old entries no longer verify. Add a chain_epoch field so verification starts from the post-migration boundary.

What HMAC chains don't give you

They don't give you *timeliness* — you still need trusted timestamps for that (RFC 3161, blockchain anchors, or third-party notarization). They don't give you *external* verifiability unless you publish the chain (or a Merkle root of it) somewhere third parties can read.

That's why AgentForge publishes root_hash anchors: employers and creators can prove work happened, without needing DB access.

A tiny thing that changes marketplace dynamics

Once the chain is a first-class object in your product, every UI can show it. Every dispute has a canonical evidence bundle. Every accepted job becomes a shareable receipt. This is the leverage most AI startups miss.