audit-core/docs/integrity.md

Integrity contract (AUDIT-WP-0007)

Operational custody already stores payload_hash and rejects UPDATE/DELETE for the runtime role. That is not tamper evidence: a database owner can drop the trigger and rewrite rows. This contract says what the hash chain proves, and what it does not.

Chain

Each accepted event stores:

• payload_hash — SHA-256 of the canonical event record (already stored)
• chain_prev — the previous event's chain_hash, or genesis
• chain_hash — SHA-256(chain_prev | payload_hash | event_id)

Genesis is 64 ASCII zeros (audit_core.integrity.GENESIS). The delimiter is |. The chain is one stream per schema, not per tenant. A per-tenant chain would hide a cross-tenant rewrite.

The first accept of an empty store uses genesis as chain_prev. A duplicate accept must not mint a second link. A conflict must not advance the head. Concurrent first-accepts of different events take an advisory lock (CHAIN_LOCK_KEY) so they cannot fork.

Verify walks ORDER BY accepted_at, event_id, recomputes every link, and reports the first event id whose stored hashes do not match. A break is a custody defect, not a sender error. Retrying the event will not repair it.

Proof bound

A chain inside the same database detects a rewritten payload_hash if the attacker does not also recompute the suffix. A database owner can. Tamper evidence against that class of attacker requires a chain-head attestation stored outside platform-pg.

tamper_evidence=True is allowed only when:

1. verify exists and fails on a rewritten row
2. an external head attestation exists and verify-against-attestation reports a missing cited head as a break
3. that attestation is fresh — its observed_at is within the freshness window below

It still does not mean WORM, object lock, or ITC-CAP data.archive. It does not raise provision maturity to D5.

Attestation cadence and freshness window

An attestation dated once is not a live precondition. The claim is derived from the mounted attestation on every read, not declared:

Setting	Value
Intended attestation cadence	daily
Freshness window	168 hours (7 days)
Mount path	AUDIT_CORE_ATTESTATION_PATH

The window is seven times the cadence so that a handful of missed runs degrade the claim rather than a single one flapping it. Widening the window without shortening the cadence weakens the claim and is a change to this contract, not a tuning knob.

tamper_evidence degrades to False, with the reason recorded, when the attestation is absent, unreadable, undated, older than the window, or cites a head the live chain does not carry — and when the chain itself is broken or cannot be walked. Unreadable is treated as absent deliberately: a malformed file must not hold up a claim that a missing file would drop.

Until AUDIT-WP-0009-T02 schedules the attestation job, no attestation is mounted in production and /readyz reports tamper_evidence: false. That is the honest reading of the current state, not a regression.

Do not write the attestation into the Barman prefix (platform-pg/ on resource:platform:audit-storage). That copy is restored with the table. A second copy may follow the logical-offsite path already used by RESOURCE-WP-0002-T06 (rapp-postgres / Nextcloud + age); cite it, do not invent a new bucket.

Tests this contract names

Test	What it asserts
test_first_accept_sets_genesis	First chain_prev is genesis
test_second_accept_links	Second chain_prev is the first chain_hash
test_duplicate_does_not_fork	Replay does not add a link
test_verify_clean_on_fresh_store	Empty and two-event stores verify
test_rewritten_payload_fails_verify	Superuser rewrite of payload_hash is a break
test_attestation_mismatch	Cited head absent from the live chain is a break

Operator surface

python -m audit_core verify-chain
python -m audit_core verify-chain --against docs/evidence/chain-head-<ts>.json
python -m audit_core attest-chain --output docs/evidence/chain-head-<ts>.json

GET /v1/integrity (may_read) returns {intact, events, head, head_event_id, first_break, attestation_match} and never event payloads.