Tamper-Evidence Chain

Overview

The audit log implements a SHA-256 hash chain for tamper detection. Each event's hash is computed from the event content plus the previous event's hash, forming a linked chain. Any insertion, deletion, or modification of an event breaks the chain and is detectable.

Hash Chain Structure

Each stamped event includes three additional fields:

Stamp Algorithm

Input: AuditEvent, chain head (previous hash + sequence)

1. If no previous event exists:
   previousHash = "genesis"
   sequence = 0
2. Else:
   previousHash = chain_head.hash
   sequence = chain_head.sequence + 1

3. hash = SHA-256(JSON.stringify(event) + previousHash)

4. Return: { ...event, hash, previousHash, sequence }

The chain is maintained per tenant, ensuring that each tenant's audit trail forms an independent, verifiable chain.

Crash Recovery

On service startup, the chain head is recovered from the database by loading the most recent stamped event for each active tenant. This ensures continuity of the hash chain after restarts or failures.

Verification

To verify chain integrity:

1. Load all events for a tenant, ordered by sequence number
2. For each event (starting from sequence 0):
   • Verify previousHash matches the hash of the preceding event
   • Recompute SHA-256(JSON.stringify(event_data) + previousHash)
   • Compare with stored hash
3. Any mismatch indicates tampering

Compliance Alignment

Implemented in packages/audit/src/tamper-evidence.ts at commit 4b572c2.