# Repro Bundle Profile (SLSA v1 + in-toto + DSSE)

## Status
- Planned contract (gap-closure track).
- Implementation sprint: `docs/implplan/SPRINT_20260209_001_DOCS_repro_bundle_gap_closure.md`.

## Purpose
- Define the minimum reproducibility evidence required for release promotion.
- Standardize canonicalization rules so rebuild and verification outcomes are deterministic.
- Preserve online and offline parity for transparency verification workflows.

## Required bundle contents (per artifact)
1. `build_provenance.json` with SLSA v1 predicate fields:
   - `builder.id` and `builder.version`
   - source binding (`invocation` and commit)
   - `materials[]` with pinned digests
   - canonicalized build command representation
   - pinned toolchain digest (`@sha256:...`)
2. `in_toto.link` mapping materials to products with deterministic digests.
3. DSSE signatures/envelopes for provenance and link payloads.
4. Transparency evidence:
   - Online mode: Rekor entry metadata.
   - Offline mode: local checkpoint/tile bundle and verification metadata, including Rekor leaf hash (`leafHash`), path hashes, and checkpoint root.

## Canonicalization policy (fail-closed)
- Paths and filenames must be Unicode NFC.
- JSON payloads must be canonicalized with sorted keys and deterministic encoding.
- PURLs/material references must be pinned, digest-backed, and deterministically ordered.
- Archive outputs must use deterministic metadata/order:
  - fixed timestamps (policy default: zero epoch)
  - stable uid/gid and owner names
  - fixed mode policy
- Line endings must be normalized (policy default: LF).
- Build environments must pin deterministic settings:
  - `LC_ALL=C`
  - `TZ=UTC`
  - stable source date epoch
- Toolchains must be digest-pinned; mutable tags are non-compliant in strict mode.

## Verification modes
### Online mode
- Verify DSSE signatures.
- Verify SLSA/in-toto policy compliance.
- Verify Rekor inclusion against trusted log/checkpoint state.

### Offline mode
- Verify DSSE signatures with bundled trust roots/keys.
- Verify bundled inclusion proof data cryptographically (leaf hash + Merkle path + checkpoint root) without network.
- Missing/invalid proof material is fail-closed by default.
- If break-glass verification is allowed, it must be explicitly configured and recorded in evidence with machine-readable marker(s).

## Promotion gate contract
- Promotion must block when any required repro evidence is missing or invalid.
- Promotion must block when canonicalization policy fails.
- Promotion must block when toolchain digest pinning is absent.
- Gate output must include stable rejection codes and references to failed evidence files for replay.

## Component ownership map
- `Attestor`: strict predicate validation, DSSE handling, Rekor verification (online/offline).
- `ReleaseOrchestrator`: fail-closed promotion gate enforcement and policy simulation.
- `EvidenceLocker`: storage/export contracts for repro-bundle artifacts and offline verification packs.
- `Provenance`: provenance model extensions and deterministic serialization support.
- `devops`: deterministic build/container/pipeline defaults and toolchain pinning.

## Test expectations
- Deterministic fixtures for valid and invalid bundles.
- Unit + integration coverage for canonicalization policy and strict validation.
- End-to-end coverage for online and offline promotion checks.
- Negative tests for each fail-closed rule.