git.stella-ops.org/docs/modules/evidence-locker/portable-audit-pack-contract.md

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-archived/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)

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.

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.
• 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.
  • 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