# 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`