stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
7f865d7bc7f38a5ba17f2557580d8db9c8893bd7
git.stella-ops.org/docs/modules/evidence-locker/portable-audit-pack-compatibility.md
master cf5b72974f save checkpoint
2026-02-11 01:32:14 +02:00

2.6 KiB
Raw Blame History

Portable Audit Pack Compatibility Mapping

Status: Draft frozen for implementation handoff (2026-02-10).

Purpose

Map current StellaOps evidence bundle contracts to the portable audit pack profile so writer/reader implementations use one required field model.

Canonical contract source

  • Manifest schema: docs/modules/evidence-locker/schemas/portable-audit-pack-manifest.v1.schema.json
  • Profile contract: docs/modules/evidence-locker/portable-audit-pack-contract.md

Required field mapping

Portable field Existing source contract Notes
spec_version bundle.manifest.schema.json manifestVersion Portable uses fixed 1.0.
artifact.digest.sha256 evidence-bundle-v1.md subject digest Required, lowercase hex without sha256: prefix in manifest payload fields.
files[*].sha256 checksums.schema.json + bundle manifest entries Portable stores per-file metadata directly in files map.
digests.canonical_bom_sha256 stellaops-evidence-pack.v1.schema.json digest fields New explicit top-level binding for BOM canonical bytes.
digests.dsse_payload_digest.sha256 attestation-contract.md producer bundle digest linkage Required preimage binding for DSSE payload verification.
rekor.tile_refs[] attestor/transparency.md + Rekor receipt inputs Portable requires deterministic path references under rekor/.
rekor.root_hash Attestor checkpoint verification contract Captured at inclusion checkpoint used by offline verifier.
verifiers.pubkeys[] Existing key bundle references Portable manifest contains verifier key references used by CLI/offline verifier.

Legacy bundle compatibility

  • Legacy evidence-bundle-<id>.tar.gz and portable-bundle-v1.tgz remain valid for existing tooling.
  • Portable audit pack profile is additive and must not reinterpret legacy fields silently.
  • Readers should apply this precedence:
    1. If spec_version exists and equals 1.0, validate against portable schema.
    2. Else if manifestVersion exists, validate against legacy bundle.manifest.schema.json.
    3. Else fail closed with ERR_MANIFEST_PROFILE_UNKNOWN.

Writer/reader alignment rules

  • Writers MUST populate every required portable field in schema v1.
  • Readers MUST reject packs missing any required portable field.
  • Writers/readers MUST share the same portable schema artifact ID and hash in release notes.

Migration notes

  • Maintain both parsers during transition.
  • Export paths should emit explicit profile indicator in logs and operator output.
  • Verification output should identify which profile was validated.