Get started

Audit and procurement attestation packs

Source

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:

  1. Envelope and claim integrity (envelope): checks schema (vitna-audit-pack-v1), format (vitna.audit-pack.v1), recomputes the canonical SHA-256 digest over all pack fields (with digest and outer signature fields stripped and keys recursively sorted), and checks that claims.citationBoundary matches Witness's published claim boundary verbatim.
  2. Outer pack signature (packSignature): when signed (or when requirePackSignature is set), verifies the Ed25519 signature over vitna-audit-pack-v1\norg=<orgId>\ngeneratedAt=<generatedAt>\nstackfile=<stackfileDigest|none>\ndigest=<digest>\n against a pinned trustedPackPublicKey or the embedded SPKI key.
  3. Stackfile, signed policy, and CI lock (stackfileAndPolicy): validates governance.stackfile via `parseStackfile` and recomputes stackfileDigest; verifies any embedded policy.json envelope signature (vitna-routing-policy-v1) via `verifyPolicy`; and runs verifyPolicyAgainstLock when governance.policyLock (vitna.lock.json) is present so lane drift is caught offline.
  4. Witness RFC 6962 price attestations (witnessPriceAttestations): for every entry in pricingAndProvenance.observationProofs, recomputes the canonical observation string and 0x00-prefixed SHA-256 leaf hash, walks the 0x01-prefixed Merkle inclusion path to the UTC day's Merkle root, and verifies the Ed25519 signature on vitna-attestation-v1\n<coversOn>\n<leafCount>\n<root>. Customer-entered private infrastructure rates stay separated under enteredPrivatePrices and never carry Witness Merkle proofs.
  5. Provider compliance terms and customer evaluations (evidenceAndTerms): recomputes deterministic SHA-256 digests over every providerTerms row (vitna-provider-term-v1) and every customerEvidence row (vitna-evidence-v1).
  6. Operational and FinOps gates (governanceGates): evaluates CI and procurement gates (requirePackSignature, requireAttestedPrices, failOnRollback when rolloutWatchdog.verdict is rollback_recommended, and maxMonthlyCostUsd over summary.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 loadable policy.json envelopes (vitna-routing-policy-v1). Published at GET /api/v1/keys/policy-key.pub.
  • Operator or customer pack key (pack): signs the outer vitna.audit-pack.v1 envelope (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.