40 lines
2.6 KiB
Markdown
40 lines
2.6 KiB
Markdown
# 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. |