Audit and procurement attestation packs
Bundle an organisation's declarative Stackfile, standing routing decisions, signed runtime policy envelope, CI policy lock, RFC 6962 Witness price observation Merkle proofs, provider compliance terms, three-provenance SKU capabilities, rollout watchdog status, and compound pipeline Bill of Materials into one self-contained, offline-verifiable vitna.audit-pack.v1 file.
Why an organisation pack exists beside a decision pack
`GET /api/v1/decisions/{id}/pack` seals a single routing decision and the observations cited when that one proposal was taken. Procurement reviews, FinOps sign-offs, and model-risk governance audits ask a wider question: what is the organisation running across every component class today, what list and private rates is it paying, which compliance terms and capabilities make each lane eligible, is any shadow or canary rollout drifting, and can an external reviewer verify every figure offline without database or network access?
buildAuditPack (platform/engine/audit-pack.mjs) assembles that full point-in-time record into one deterministic JSON document (vitna.audit-pack.v1) stamped with a canonical SHA-256 digest and an optional outer Ed25519 signature.
Six-layer offline verification
verifyAuditPack runs with zero database queries and zero outbound sockets across six independent layers:
- Envelope and claim integrity (
envelope): checksschema(vitna-audit-pack-v1),format(vitna.audit-pack.v1), recomputes the canonical SHA-256digestover all pack fields (withdigestand outer signature fields stripped and keys recursively sorted), and checks thatclaims.citationBoundarymatches Witness's published claim boundary verbatim. - Outer pack signature (
packSignature): when signed (or whenrequirePackSignatureis set), verifies the Ed25519 signature overvitna-audit-pack-v1\norg=<orgId>\ngeneratedAt=<generatedAt>\nstackfile=<stackfileDigest|none>\ndigest=<digest>\nagainst a pinnedtrustedPackPublicKeyor the embedded SPKI key. - Stackfile, signed policy, and CI lock (
stackfileAndPolicy): validatesgovernance.stackfilevia `parseStackfile` and recomputesstackfileDigest; verifies any embeddedpolicy.jsonenvelope signature (vitna-routing-policy-v1) via `verifyPolicy`; and runsverifyPolicyAgainstLockwhengovernance.policyLock(vitna.lock.json) is present so lane drift is caught offline. - Witness RFC 6962 price attestations (
witnessPriceAttestations): for every entry inpricingAndProvenance.observationProofs, recomputes the canonical observation string and0x00-prefixed SHA-256 leaf hash, walks the0x01-prefixed Merkle inclusion path to the UTC day's Merkle root, and verifies the Ed25519 signature onvitna-attestation-v1\n<coversOn>\n<leafCount>\n<root>. Customer-entered private infrastructure rates stay separated underenteredPrivatePricesand never carry Witness Merkle proofs. - Provider compliance terms and customer evaluations (
evidenceAndTerms): recomputes deterministic SHA-256 digests over everyproviderTermsrow (vitna-provider-term-v1) and everycustomerEvidencerow (vitna-evidence-v1). - Operational and FinOps gates (
governanceGates): evaluates CI and procurement gates (requirePackSignature,requireAttestedPrices,failOnRollbackwhenrolloutWatchdog.verdictisrollback_recommended, andmaxMonthlyCostUsdoversummary.totalEstimatedMonthlySpendUsd).
When every cryptographic check passes and all present layers are verified against caller-pinned public keys (trustedPackPublicKey, trustedRecordPublicKey, trustedPolicyPublicKey), verifyAuditPack returns verdict: "verified". When signatures verify solely against keys embedded inside the pack (unpinned) or cite observations from an open UTC day before daily root signing, verifyAuditPack returns verdict: "verified_with_warnings" and enumerates each warning. Any tampered byte, forged proof, broken lock invariant, or breached gate returns ok: false and verdict: "failed".
Cryptographic key separation and claim boundaries
Three distinct Ed25519 key roles participate in an audit pack and are never conflated:
- Witness record key (
record): signs daily observation Merkle roots (vitna-attestation-v1). Published at `GET /api/v1/keys`. - Routing policy key (
policy): signs loadablepolicy.jsonenvelopes (vitna-routing-policy-v1). Published atGET /api/v1/keys/policy-key.pub. - Operator or customer pack key (
pack): signs the outervitna.audit-pack.v1envelope (vitna-audit-pack-v1) at export time.
Both signAuditPack and verifyAuditPack refuse key conflation if an outer pack signer public key equals any Witness record attestation key, preserving the boundary between first-party market observations and customer stack configurations. Likewise, claims embeds PROVES, DOES_NOT_PROVE, and CITATION_BOUNDARY verbatim from platform/witness/claims.mjs: Witness proves what a vendor pricing page published when fetched, not what a vendor billed on a private invoice or whether customer-supplied benchmark scores are representative. Stripping or editing claims.citationBoundary fails verification with altered_citation_boundary.
Export, sign, and verify audit packs from the CLI with `aperture:audit:pack`, export an authenticated organisation's pack via `GET /api/v1/org/audit-pack`, or run stateless zero-retention verification and assembly via `POST /api/v1/audit-pack` and MCP vitna_verify_audit_pack.
