Fixing Hash Chain Breaks in Audit Trails

A hash chain break means that a receipt's recorded previous hash does not match the actual hash of the preceding receipt. This breaks the tamper-evidence guarantee. The chain no longer proves that records have not been modified. Identifying and addressing the break is critical for maintaining audit trail integrity and regulatory compliance.

Detecting the Break

Run the chain verification command:

npx authensor verify-chain --from <start-id> --to <end-id>

The verifier walks the chain forward, computing each receipt's hash and comparing it to the previous_hash field of the next receipt. When it finds a mismatch, it reports the exact position: the last valid receipt and the first invalid receipt.

Common Causes

Database corruption. If a receipt record is modified directly in PostgreSQL (whether intentionally or accidentally), its hash no longer matches what the next receipt references.

Concurrent write race. If two receipts are created simultaneously and both reference the same previous receipt, the chain forks. One branch is valid; the other breaks the sequence.

Backup restoration. Restoring a database backup that does not include the most recent receipts creates a gap. New receipts reference a predecessor that no longer exists in the database.

Application bug. A code change that modifies the receipt serialization format changes the computed hash without changing the stored data.

Recovery Steps

1. Document the break. Record the break position, the time it occurred (if determinable), and the suspected cause. This documentation is required for compliance.

2. Preserve the evidence. Export both the valid and broken chain segments. Do not modify or delete any records.

3. Determine the scope. How many receipts are in the broken segment? Are those receipts otherwise valid (correct data, just wrong chain linkage)?

4. Start a new chain. The simplest recovery is to start a new chain segment from the current point. The first receipt in the new segment references itself as the genesis receipt.

5. Create a bridge record. Document the relationship between the old chain segment and the new one. Record the last valid receipt of the old chain and the first receipt of the new chain.

6. Investigate the root cause. Fix whatever caused the break to prevent recurrence.

A hash chain break does not invalidate the data in the receipts. The individual records may still be accurate. What is lost is the mathematical proof that no records have been inserted, deleted, or modified. Document this distinction clearly in any compliance reporting.