Portable Audit Pack Contract (v1 Draft)

Purpose

Define a deterministic, offline-verifiable portable audit pack contract that unifies Stella Ops evidence export semantics across Attestor, EvidenceLocker, AuditPack, and CLI verification flows.

Contract status

• Status: Draft for implementation.
• Source sprint: docs-archive/implplan/2026-02-10-completed-sprints/SPRINT_20260210_003_DOCS_portable_audit_pack_translation.md
• Canonical schema: docs/modules/evidence-locker/schemas/portable-audit-pack-manifest.v1.schema.json

Companion profile documents

• Compatibility mapping: docs/modules/evidence-locker/portable-audit-pack-compatibility.md
• Determinism profile: docs/modules/evidence-locker/portable-audit-pack-determinism.md
• Rekor offline verification profile: docs/modules/evidence-locker/portable-audit-pack-rekor-offline.md
• CLI runbook (target behavior): docs/modules/evidence-locker/portable-audit-pack-cli-runbook.md
• Optional Parquet profile: docs/modules/evidence-locker/portable-audit-pack-parquet-profile.md
• Verification test matrix: docs/modules/evidence-locker/portable-audit-pack-test-matrix.md

Target bundle profile

Required artifacts

• manifest.json (JCS canonical JSON)
• manifest.sig (DSSE envelope over canonical manifest, detached file)
• canonical_bom.json (canonicalized BOM snapshot)
• dsse_envelope.json (attestation envelope bound to BOM/subject)
• rekor/ proof material:
  • checkpoint note/signature
  • inclusion proof data
  • tile bundle reference material (tile.tar or equivalent deterministic bundle)

Optional artifacts

• merged_vex.json (canonical merged VEX view)
• components.parquet (optional analytics profile)
• checksums.txt / replay helper assets for operational workflows

Manifest contract (portable profile)

Core fields

• spec_version
• created_utc
• artifact (name, version, digest, media_type)
• files map with per-file:
  • sha256
  • size
  • content_type
  • profile-specific metadata (for example compression, schema_fingerprint)
• digests:
  • canonical_bom_sha256
  • dsse_payload_digest
• rekor:
  • log_id
  • api_version
  • tile_refs
  • root_hash
• timestamps
• verifiers (key references and trust metadata)
• compliance_controls / implementation profile complianceControls:
  • framework (for example NIS2, DORA, CRA)
  • control_id / implementation profile controlId
  • status using readiness language, not legal-compliance claims
  • evidence_paths / implementation profile evidencePaths, each path covered by the manifest checksum inventory
  • optional review_status / implementation profile reviewStatus
  • optional blocker_reason / implementation profile blockerReason

Schema note:

• Required field set and allowed optional fields are frozen in portable-audit-pack-manifest.v1.schema.json.

Determinism rules

• JSON canonicalization MUST use RFC 8785/JCS-compatible canonical output.
• Manifest signing input MUST be the canonical bytes of manifest.json.
• File inventory MUST be sorted lexicographically by canonical path.
• Archive metadata MUST be deterministic (mtime, uid/gid, mode, ordering).
• Digests MUST be lowercase SHA-256 hex unless profile explicitly states otherwise.

Verification contract

1. Verify manifest.sig against canonical manifest.json.
2. Verify every file digest/size in manifest.files.
3. Verify DSSE envelope signature(s) and payload digest binding.
4. Verify Rekor inclusion proof against checkpoint root using bundled proof/tile data.
5. Verify artifact/BOM subject digest consistency.
6. If components.parquet is present, validate schema fingerprint metadata.
7. Verify every compliance control evidence path is present in the checksum inventory and that the referenced file verifies. Missing or tampered compliance evidence fails closed; it is not a reviewer warning.
8. Verify all manifest-declared artifact, SBOM, provenance, attestation, and Rekor proof references are covered by the checksum inventory. Digest disagreement between a reference and its checksum entry fails closed.

Default policy is fail-closed for missing or invalid required verification inputs.

Current state vs target (gap summary)

• Implemented:
  • Detached manifest.sig support in audit bundle paths.
  • Rekor offline proof verification primitives.
  • EvidenceLocker fields for canonical BOM/payload digest and Rekor refs.
  • EvidenceLocker local portable-bundle-v1.tgz verifier (EvidencePortableBundleOfflineVerifier) checks the archive checksum inventory, manifest-declared file digests/sizes, manifest signature payload binding, DSSE payload digest binding, Rekor tile coverage for artifact and canonical BOM digests, and portable metadata redaction. Sprint SPRINT_20260516_004_Findings_production_alert_evidence_seed.md includes a seeded production alert/evidence fixture and tamper-negative test.
  • Attestor release evidence packs carry compliance control mappings and a network-independent directory verifier for manifest hash, file checksum, size, declared reference coverage, Rekor proof inventory coverage, and control evidence coverage checks (src/Attestor/__Libraries/StellaOps.Attestor.EvidencePack/ReleaseEvidencePackOfflineVerifier.cs, Sprint SPRINT_20260516_006_Attestor_evidence_pack_offline_verification.md).
• Gaps:
  • No single unified portable manifest schema with full required field set.
  • Non-uniform canonicalization implementations across pack writers.
  • Determinism not fully enforced across all packaging flows.
  • EvidenceLocker portable verification still stops at local structural and digest binding checks; public-key signature validation and Rekor Merkle/checkpoint signature validation require bundled trust-root follow-up.
  • Optional Parquet profile not defined in portable pack contract.

Ownership map

• Attestor: DSSE/Rekor proof verification contract and tile/checkpoint binding.
• EvidenceLocker: persistence/export schema and portable bundle profile publication.
• StellaOps.AuditPack: deterministic pack write/read/sign/verify implementation.
• CLI: pack generation and offline verification UX parity.
• QA: deterministic fixtures, tamper matrix, replay verification.

Implementation notes

• Keep compatibility mapping for legacy bundle manifests; do not silently reinterpret fields.
• Keep offline posture: no mandatory network calls in verification.
• Prefer shared canonicalization libraries over local ad hoc JSON serializers.

References

• docs/modules/attestor/repro-bundle-profile.md
• docs/modules/attestor/transparency.md
• docs/modules/evidence-locker/export-format.md
• docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json
• docs/modules/evidence-locker/schemas/stellaops-evidence-pack.v1.schema.json