feat(audit): WORM signed export — AuditExporter + POST /v1/audit/export (Step 6.6b)

[officialCodeWork]

Summary

Completes Step 6.6 — Immutable audit log (6.6a shipped the read API + chain verification in #153). 6.6a's hash chain gives tamper-evidence for the live log; 6.6b adds immutability at rest via a self-verifying signed export.

• AuditExporter (rag_core.audit_export, pure stdlib) builds an AuditExport bundle with two independent integrity checks:
  • content_hash — SHA-256 over the canonical serialisation of the events (pins the exact set + order; recomputed on verify, so any add/remove/edit is caught even without the secret).
  • signature — HMAC-SHA256 over f"{timestamp}.{content_hash}", mirroring the Step 5.1 ProvenanceSigner scheme.
  • verify() → {signed, content_ok, verified, reason} with reason ∈ ok / unsigned / no_secret / content_mismatch / signature_mismatch. chain_verified attests the source log's whole-log chain was intact at export time.
• POST /v1/audit/export is tenant-scoped (the caller's events only — same isolation as GET /v1/audit); ragctl audit exports the whole log in-process. Because integrity is content_hash + HMAC over whatever events are included (not the global chain head), the same verify() works for both, and the bundle verifies offline — the artifact an operator archives to immutable storage (S3 Object Lock).
• Opt-in signing via cfg.audit.export_secret (env-interpolated, mirrors provenance.signing_secret); empty (default) → content-hashed but unsigned bundle.

Scope / deferred: a durable live-store AuditStore backend (Postgres / append-only ledger) and expanding what gets audited beyond corpus.route remain follow-ups.

Tests & gates

• ~23 new tests: exporter unit (tests/audit/test_export.py — content_hash determinism, sign→verify, unsigned, no_secret, wrong-secret, content tamper → content_mismatch, signature tamper → signature_mismatch, empty); gateway (apps/gateway/tests/test_audit.py — tenant-scoped + signed + offline-verifies + cross-tenant isolation + unsigned + disabled→404 + no-auth→401); ragctl audit round-trip + file verify.
• Full tests/ packages/ 2328 passed, 1 skipped; gateway suite 281 (verified +5 vs main, no regression). Green: ruff, mypy --strict (299 files), RAG001, policy-coverage, log-schema, schema-drift + openapi-drift (dist/schemas + dist/openapi.* + dist/rag.schema.* regenerated).

Documentation

• ADR-0038 — the 6.6b decision (content_hash + HMAC; uniform verify for whole-log + tenant-scoped; unsigned degraded mode).
• docs/reference/audit.md + docs/architecture/audit-log.md — export section + design.
• docs/README.md — updated audit rows.

Test plan

• uv run pytest tests/ packages/ -m "not integration" — 2328 passed, 1 skipped
• uv run pytest apps/gateway/tests — 281 passed
• ruff + mypy --strict (299 files) + RAG001 + policy-coverage + log-schema + schema/openapi-drift
• Offline verify of an exported bundle (content + signature); tamper detection both ways

🤖 Generated with Claude Code