How the hash chain proves tamper-evidence

Every fasten audit row carries a SHA-256 hash chained to the row before it. Rewriting any earlier row breaks the chain at that point, and verify_chain() returns the position deterministically. This page walks the primitives and a worked example an auditor can reproduce.

The four primitives

The chain property: any row's hash is a deterministic function of every anchor plus the previous row's hash. Rewrite any earlier row and its hash changes; the next row's prev_hash no longer matches; verify_chain() stops at that row and reports its monotonic_seq.

Worked example · modify a row, watch verify_chain catch it

Reproducible in Python. Create three rows, tamper with the middle one directly in the SQL store, then verify.

from fasten import emit, audit_store, verify_chain, register, Domain, Meta, Severity, RetentionClass

register(Domain("demo"), {"NOTE_WRITTEN": Meta(summary="A note was written.", severity=Severity.INFO, retention_class=RetentionClass.SHORT)})

for i in range(3):
    emit(code="NOTE_WRITTEN", target=f"note_{i}", actor="demo", actor_kind="service", detail={"i": i})

rows = audit_store().query(limit=10); rows.reverse()  # oldest-first
print(verify_chain(rows).ok)                          # → True

# Simulate tampering: change the middle row's detail directly in SQL
audit_store()._conn.execute("UPDATE audit_log SET detail = '{\"i\": 99}' WHERE monotonic_seq = 2")

rows = audit_store().query(limit=10); rows.reverse()
result = verify_chain(rows)
print(result.ok, result.first_break_at, result.reason)
# → False 2 chain hash mismatch at seq=2

The auditor gets three verifiable facts from one call: (1) the chain broke, (2) the exact row (monotonic_seq = 2), (3) the reason (hash mismatch). No log analysis, no forensic reconstruction, no vendor tooling required.

What this catches

• Any row content change after write (SQL UPDATE, file edit, application-level rewrite).
• Any row deletion in the middle of the chain (breaks monotonic_seq continuity).
• Any row insertion between two committed rows (the inserted row's prev_hash won't match the surrounding chain).
• Reordering of rows within a chain (SEQ mismatch).
• Backup-restore that reverts recent rows (older chain state; hash of last-verified boundary changes).

What this does NOT catch

• Rows never emitted. If your application chose not to emit() a decision, no chain integrity check can surface that gap. Audit-code review + registered-code enforcement is the compensating control.
• Rows emitted with the wrong content. The chain proves the row wasn't altered after write. It doesn't prove the row was correct at write time. That is application-level correctness, not the substrate's job.
• Deletion of the entire chain. If an attacker drops the whole audit database, there is nothing left to verify. Compensating controls: signed evidence pack (P1-33) shipped to an independent verifier; replication to a store the operator does not control.
• Attacks against the verifier. If the verifier binary or the SHA-256 implementation is compromised, results are unreliable. Compensating control: verifier runs from an independent build, e.g. the auditor's own machine.

Reading more

See the auditor's runbook for reproducible scripts (Python one-liner, reusable script with exit codes, CI job template, break-recovery playbook, and the full threat-model table).