Skip to main content

Audit Chain

See Architecture → Audit Chain for the complete design (append sequence, schema, rules, per-service event catalogs, verification tools, and JCS rationale).

This page surfaces the compliance perspective on why audit chain matters for HIPAA.

What audit chain proves​

HIPAA obligationHow audit chain satisfies
§164.312(b) Audit controls — "implement hardware, software, and/or procedural mechanisms that record and examine activity in information systems"Every read + write + consent event → audit_events row
§164.308(a)(1)(ii)(D) Information system activity review — periodic review of audit logsHourly hash-chain verification (Phase 2) + forensic POST /api/audit/verify
§164.312(c)(1) Integrity — PHI must not be improperly altered or destroyedAppend-only + hash chain makes tamper evidence mechanical, not procedural
§164.308(a)(6) Incident procedures — identify and respondSev 0 alert on hash-chain mismatch auto-triggers hipaa-incident-response runbook
§164.400–§164.414 Breach notification — 60-day timeline, affected-individual lettersAudit chain provides forensic timeline + scope of access

Retention​

  • audit_events — retained forever (no TTL)
  • llm_call_logs content — retained 30 days, anonymized + back-referenced via purge_run_id (FR-023e)
  • Related operational logs (OpenTelemetry traces, Azure Monitor) — 90 days per Azure default

Forensic access​

Admin reads of encrypted llm_call_logs content require:

  1. Captured business justification (text field)
  2. Explicit AdminService audit event with the justification
  3. Justification retained in chain alongside the access

See CLAUDE.md § Audit Trail — DO / DON'T.

Principles​

  • Audit events are append-only. No UPDATE. No DELETE.
  • A bug in a written event is corrected by a compensating event, not a mutation.
  • Payload never contains raw PHI. PHI-adjacent content lives encrypted in llm_call_logs + joins by traceId.
  • Entity-identifier lists use count-only semantics (FR-SPEC-05-015).

See Architecture → Audit Chain for the deep-dive.