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.

## How the attestation is produced and where it lives

`AUDIT-WP-0009-T02`, `deploy/attest-cronjob.yaml`.

| | |
| --- | --- |
| Cadence | daily, `17 3 * * *` UTC, against the 168h window |
| Producer | CronJob `audit-core-attest-chain`, its own ServiceAccount |
| Published to | ConfigMap `audit-core-chain-head`, mounted read-only by the receiver at `/etc/audit-core/attestation/` |
| Offsite copy | operator step, logical-offsite path (`rapp-postgres` / Nextcloud + age) |

Three properties of that arrangement are load-bearing, not incidental.

**The producer is not the receiver.** A receiver that could rewrite its own
attestation could forge it. So the job runs as a separate workload whose Role
reaches exactly one named ConfigMap, and NetworkPolicy gives the receiver no
API-server egress at all. Asserted in `tests/test_layer_conformance.py`.

**It refuses to publish over a broken chain.** If `verify_chain` reports a
break the job fails and leaves the previous attestation standing. Publishing a
fresh head over a break would replace an honest `chain_break` with a
fresh-looking attestation — a stale attestation degrades the claim visibly, a
false one does not.

**The ConfigMap is mounted as a directory, not with `subPath`.** A `subPath`
ConfigMap mount is resolved once at pod start and never updates, so the daily
attestation would reach the ConfigMap and never the running receiver:
`tamper_evidence` would age out to `false` while the job reported success every
night. That failure is silent in both directions, which is why the mount shape
is part of this contract rather than a deployment detail.

**What this reaches, and what it does not.** The in-cluster copy puts the
attestation outside `platform-pg`, so a database owner who rewrites a suffix
cannot also rewrite the head. It does **not** withstand a cluster owner, who
can edit the ConfigMap. The offsite copy is the one that survives losing the
cluster, and audit-core deliberately does not write it — this repo holds no
Nextcloud credential and should not acquire one to publish a hash. Until an
operator establishes that copy, the delivered control is "defends against a
database owner", and no stronger claim may be made from it.

Before the first run the ConfigMap is empty and `/readyz` reports
`tamper_evidence: false` with reason `no_attestation`. That is the correct
day-one 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

```bash
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.