govoplan-audit/docs/EVIDENCE_BUNDLES.md

Audit evidence bundles

Audit evidence bundles are bounded, portable JSON artifacts for independent review. They are not database backups. A bundle contains selected audit facts, trace context, policy and source provenance, external evidence references, and redaction declarations. It never embeds referenced files, raw messages, full recipient lists, credentials, tokens, or arbitrary feature payloads.

Export lifecycle and permissions

Create an export with POST /api/v1/admin/audit/evidence-bundles. A tenant export requires audit:evidence:export and is constrained to the principal's active tenant. system and all scopes require audit:system_evidence:export. Selection is limited to 500 audit records and 200 external references. An over-broad selection is rejected instead of being silently truncated.

The response records the pending, ready, or failed lifecycle state and a canonical bundle SHA-256. Metadata and content are available at:

• GET /api/v1/admin/audit/evidence-bundles/{id}
• GET /api/v1/admin/audit/evidence-bundles/{id}/download

The Audit administration page offers Export page evidence to create an unsigned bundle for the currently displayed records. Use the API when a review needs a broader filtered selection, explicit module references, or signing.

Generation and every download produce separate audit records. Download access is re-authorized against the original scope so a tenant switch cannot expose a bundle from another tenant. Audit also checks the stored bundle against its persisted canonical hash before each download and fails the lifecycle record if storage integrity no longer matches.

Module evidence references

Feature modules keep their evidence and storage ownership. They may record a serialized govoplan_core.core.institutional.EvidenceReference in bounded audit details or supply an external reference in the export request. The Audit module stores only its id, kind, owner module, locator, required flag, and optional content SHA-256. This lets modules participate without importing Audit internals or handing Audit file contents.

External references should include a SHA-256 whenever the referenced artifact can be canonicalized. A missing hash is reported as unverifiable. A required artifact that is not supplied during offline review is reported as missing, and supplied bytes that do not match their hash are reported as tampered.

Signatures

Canonical record and reference hashes are always emitted. Trusted signatures are optional and use Ed25519. To enable signed exports, configure both:

• GOVOPLAN_AUDIT_EVIDENCE_SIGNING_KEY_ID
• GOVOPLAN_AUDIT_EVIDENCE_SIGNING_PRIVATE_KEY (path to a PEM Ed25519 key)

The request must set sign to true; otherwise the bundle remains unsigned. Keep private keys outside the application database and distribute raw, base64-encoded Ed25519 public keys to independent reviewers through a separate trusted channel.

Offline verification

The installed govoplan-audit-verify command requires no source database:

govoplan-audit-verify bundle.json --pretty
govoplan-audit-verify bundle.json \
  --trusted-key institution-2026=BASE64_PUBLIC_KEY \
  --external decision-42=/review/decision-42.json

Output is deterministic and returns one of these states:

• valid: schema, canonical hashes, completeness, redaction declarations, supplied external evidence, and any trusted signatures are valid.
• incomplete: a manifest item or required external artifact is missing.
• unverifiable: a reference lacks a checksum or a signature key is untrusted.
• tampered: a canonical item, manifest, external artifact, or trusted signature does not match.
• invalid: the supported schema or redaction contract is malformed.
• unsupported: the schema or version is not supported by this verifier.

An unsigned bundle can still be valid: the verifier establishes internal hash consistency, while provenance trust must then be established by the review process.