git.stella-ops.org/docs/contracts/mirror-bundle.md

# Mirror Bundle Contract (AIRGAP-56)

**Contract ID:** `CONTRACT-MIRROR-BUNDLE-003`
**Version:** 1.0
**Status:** Published
**Last Updated:** 2025-12-05

## Overview

This contract defines the mirror bundle format used for air-gap/offline operation. Mirror bundles package VEX advisories, vulnerability feeds, and policy packs for transport to sealed environments.

## Implementation References

- **JSON Schema:** `docs/schemas/mirror-bundle.schema.json`
- **Documentation:** `docs/airgap/mirror-bundles.md`
- **Importer:** `src/AirGap/StellaOps.AirGap.Importer/`

## Bundle Structure

### MirrorBundle

Top-level bundle object.

```json
{
  "schemaVersion": 1,
  "generatedAt": "2025-12-05T10:00:00Z",
  "targetRepository": "oci://registry.internal/stella/mirrors",
  "domainId": "vex-advisories",
  "displayName": "VEX Advisories",
  "exports": [
    { ... }
  ]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `schemaVersion` | integer | Yes | Bundle schema version (currently 1) |
| `generatedAt` | datetime | Yes | ISO-8601 generation timestamp |
| `targetRepository` | string | No | Target OCI repository |
| `domainId` | string | Yes | Domain identifier |
| `displayName` | string | No | Human-readable name |
| `exports` | array | Yes | Exported data sets |

### BundleExport

Individual export within a bundle.

```json
{
  "key": "vex-openvex-all",
  "format": "openvex",
  "exportId": "550e8400-e29b-41d4-a716-446655440000",
  "querySignature": "abc123def456",
  "createdAt": "2025-12-05T10:00:00Z",
  "artifactSizeBytes": 1048576,
  "artifactDigest": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
  "sourceProviders": ["anchore", "github", "redhat"],
  "consensusRevision": "rev-2025-12-05-001",
  "policyRevisionId": "policy-v1.2.3",
  "policyDigest": "sha256:...",
  "consensusDigest": "sha256:...",
  "scoreDigest": "sha256:...",
  "attestation": {
    "predicateType": "https://stella.ops/attestation/vex-export/v1",
    "signedAt": "2025-12-05T10:00:01Z",
    "envelopeDigest": "sha256:...",
    "rekorLocation": "https://rekor.sigstore.dev/api/v1/log/entries/..."
  }
}
```

### Export Formats

| Format | Description |
|--------|-------------|
| `openvex` | OpenVEX format |
| `csaf` | CSAF VEX format |
| `cyclonedx` | CycloneDX VEX format |
| `spdx` | SPDX format |
| `ndjson` | Newline-delimited JSON |
| `json` | Standard JSON |

### AttestationDescriptor

Attestation metadata for signed exports.

```json
{
  "predicateType": "https://stella.ops/attestation/vex-export/v1",
  "rekorLocation": "https://rekor.sigstore.dev/...",
  "envelopeDigest": "sha256:...",
  "signedAt": "2025-12-05T10:00:01Z"
}
```

### BundleSignature

Signature for bundle integrity.

```json
{
  "path": "bundle.sig",
  "algorithm": "ES256",
  "keyId": "key-2025-001",
  "provider": "default",
  "signedAt": "2025-12-05T10:00:02Z"
}
```

## Domain IDs

Standard domain identifiers:

| Domain ID | Description |
|-----------|-------------|
| `vex-advisories` | VEX advisory documents |
| `vulnerability-feeds` | Vulnerability feed data |
| `policy-packs` | Policy rule packages |
| `sbom-catalog` | SBOM artifacts |

## Validation Requirements

### DSSE Verification

1. Validate DSSE envelope structure
2. Verify RSA-PSS/SHA256 signature
3. Check trusted key fingerprint
4. Validate PAE encoding

### TUF Validation

1. Verify root → snapshot → timestamp chain
2. Check version monotonicity
3. Validate expiry windows
4. Cross-reference hashes

### Merkle Root Verification

1. Compute SHA-256 tree for bundle objects
2. Compare against stored Merkle root
3. Validate staged content integrity

## Import Flow

```
1. Receive bundle package
2. Validate DSSE signature
3. Verify TUF metadata chain
4. Compute and verify Merkle root
5. Register in bundle catalog
6. Apply to sealed environment
```

## Registration API

### Register Bundle

```
POST /api/v1/airgap/bundles
Content-Type: application/json

{
  "bundlePath": "/path/to/bundle.json",
  "trustRootsPath": "/path/to/trust-roots.json"
}

Response: 202 Accepted
{
  "importId": "...",
  "status": "validating"
}
```

### Get Bundle Status

```
GET /api/v1/airgap/bundles/{bundleId}

Response: 200 OK
{
  "bundleId": "...",
  "domainId": "vex-advisories",
  "status": "imported",
  "exportCount": 3
}
```

## Determinism Guarantees

1. **Digest verification:** All artifacts verified by SHA-256 digest
2. **Stable ordering:** Exports ordered deterministically
3. **Immutable content:** Bundle content is immutable once signed
4. **Traceability:** Full provenance chain via attestations

## Unblocks

This contract unblocks the following tasks:

- POLICY-AIRGAP-56-001
- POLICY-AIRGAP-56-002
- EXCITITOR-AIRGAP-56-001
- EXCITITOR-AIRGAP-58-001
- CLI-AIRGAP-56-001
- AIRGAP-TIME-57-001

## Related Contracts

- [Sealed Mode Contract](./sealed-mode.md) - Sealed environment operation
- [Verification Policy Contract](./verification-policy.md) - Attestation verification
- [Export Bundle Contract](./export-bundle.md) - Export job scheduling