up

docs/airgap/mirror-bundles.md

@@ -0,0 +1,28 @@
+# Mirror Bundles (Airgap 56-003)
+
+Defines the mirror bundle format and validation workflow for sealed deployments.
+
+## Contents
+- Images/charts: OCI artifacts exported with digests + SBOMs.
+- Manifests: `manifest.json` with entries:
+  - `bundleId`, `mirrorGeneration`, `createdAt`, `producer` (export center), `hashes` (sha256 list)
+  - `dsseEnvelopeHash` for signed manifest (if available)
+  - `files[]`: path, sha256, size, mediaType
+- Transparency: optional TUF metadata (`timestamp.json`, `snapshot.json`) for replay protection.
+
+## Validation steps
+1. Verify `manifest.json` sha256 matches provided hash.
+2. If DSSE present, verify signature against offline trust roots.
+3. Validate Merkle root (if included) over `files[]` hashes.
+4. For each OCI artifact, confirm digest matches and SBOM present.
+5. Record `mirrorGeneration` and manifest hash; store in audit log and timeline event.
+
+## Workflow
+- Export Center produces bundle + manifest; Attestor/Excititor importers validate before ingest.
+- Bundle consumers must refuse imports if any hash/signature fails.
+- Keep format stable; any schema change bumps `manifestVersion` in `manifest.json`.
+
+## Determinism
+- Sort `files[]` by path; compute hashes with UTF-8 canonical paths.
+- Use ISO-8601 UTC timestamps in manifests.
+- Do not include host-specific paths or timestamps in tar layers.