save checkpoint

docs/modules/evidence-locker/portable-audit-pack-contract.md

@@ -0,0 +1,106 @@
+# 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`