# AirGap

**Status:** Implemented
**Source:** `src/AirGap/`
**Owner:** Platform Team

> **Note:** This is the module dossier with architecture and implementation details. For operational guides and workflows, see [docs/modules/airgap/guides/](./guides/).

## Purpose

AirGap manages sealed knowledge snapshot export and import for offline/air-gapped deployments. Provides time-anchored snapshots with staleness policies, deterministic bundle creation, and secure import validation for complete offline operation.

## Components

**Services:**
- `StellaOps.AirGap.Controller` - Snapshot orchestration and staleness enforcement
- `StellaOps.AirGap.Importer` - Import validation and bundle ingestion

**Libraries:**
- `StellaOps.AirGap.Policy` - Staleness policy evaluation
- `StellaOps.AirGap.Time` - Time anchor validation and trust
- `StellaOps.AirGap.Persistence` - PostgreSQL persistence (EF Core v10)
- `StellaOps.AirGap.Persistence.Tests` - Persistence integration tests

## Configuration

See `etc/airgap.yaml.sample` for configuration options.

Key settings:
- Staleness policy (maxAgeHours, warnAgeHours, staleAction)
- Time anchor requirements (requireTimeAnchor)
- Per-content staleness budgets (advisories, VEX, packages, mitigations)        
- PostgreSQL connection (schema: `airgap`)
- Export/import paths and validation rules

## EF Core Persistence Workflow

AirGap persistence now uses EF Core v10 models generated from the module migration schema.

Scaffold baseline context/models:

```bash
dotnet ef dbcontext scaffold \
  "Host=...;Port=...;Database=...;Username=...;Password=..." \
  Npgsql.EntityFrameworkCore.PostgreSQL \
  --project src/AirGap/__Libraries/StellaOps.AirGap.Persistence/StellaOps.AirGap.Persistence.csproj \
  --startup-project src/AirGap/__Libraries/StellaOps.AirGap.Persistence/StellaOps.AirGap.Persistence.csproj \
  --schema airgap \
  --table state \
  --table bundle_versions \
  --table bundle_version_history \
  --context-dir EfCore/Context \
  --context AirGapDbContext \
  --output-dir EfCore/Models \
  --namespace StellaOps.AirGap.Persistence.EfCore.Models \
  --context-namespace StellaOps.AirGap.Persistence.EfCore.Context \
  --use-database-names
```

Regenerate compiled model artifacts after model updates:

```bash
dotnet ef dbcontext optimize \
  --project src/AirGap/__Libraries/StellaOps.AirGap.Persistence/StellaOps.AirGap.Persistence.csproj \
  --startup-project src/AirGap/__Libraries/StellaOps.AirGap.Persistence/StellaOps.AirGap.Persistence.csproj \
  --context AirGapDbContext \
  --output-dir EfCore/CompiledModels \
  --namespace StellaOps.AirGap.Persistence.EfCore.CompiledModels
```

Runtime behavior:
- The static compiled model is used explicitly for the default `airgap` schema path.
- Non-default schemas (for integration fixtures) use runtime model construction to preserve schema isolation.

## Bundle manifest (v2) additions

- `canonicalManifestHash`: sha256 of canonical JSON for deterministic verification.
- `subject`: sha256 (+ optional sha512) digest of the bundle target.
- `timestamps`: RFC3161/eIDAS timestamp entries with TSA chain/OCSP/CRL refs.
- `rekorProofs`: entry body/inclusion proof paths plus signed entry timestamp for offline verification.
- Inline artifacts (no `path`) are capped at 4 MiB; larger artifacts are written under `artifacts/`.

## Dependencies

- PostgreSQL (schema: `airgap`)
- Authority (authentication)
- ExportCenter (bundle creation)
- Mirror (snapshot sources)
- All data modules (Concelier, VexHub, SbomService, etc.)

## Related Documentation

- Operations: `./operations/` (if exists)
- Offline Kit: `../../OFFLINE_KIT.md`
- Mirror: `../mirror/`
- ExportCenter: `../export-center/`
- Promotion Rekor tile runbook: `./guides/promotion-rekor-tile-verification.md`

## Evidence Bundles for Air-Gapped Verification

The AirGap module supports golden corpus evidence bundles for offline verification of patch provenance. These bundles enable auditors to verify security patch status without network access.

### Bundle Contents

Evidence bundles follow the OCI format and contain:
- Pre/post binaries with debug symbols
- Canonical SBOM for each binary
- DSSE delta-sig predicate proving patch status
- Build provenance (if available from buildinfo)
- RFC 3161 timestamps for each signed artifact
- Validation run results and KPIs

### Bundle Export

```bash
stella groundtruth bundle export \
  --packages openssl,zlib,glibc \
  --distros debian,fedora \
  --output symbol-bundle.tar.gz \
  --sign-with cosign
```

### Bundle Import and Verification

```bash
stella groundtruth bundle import \
  --input symbol-bundle.tar.gz \
  --verify-signature \
  --trusted-keys /etc/stellaops/trusted-keys.pub \
  --output verification-report.md
```

### Standalone Verifier

For air-gapped environments without the full Stella Ops stack, use the standalone verifier:

```bash
stella-verifier verify \
  --bundle evidence-bundle.oci.tar \
  --trusted-keys trusted-keys.pub \
  --trust-profile eu-eidas.trustprofile.json \
  --output report.json
```

Exit codes:
- `0`: All verifications passed
- `1`: One or more verifications failed
- `2`: Invalid input or configuration error

### Related Documentation

- [Golden Corpus Layout](../binary-index/golden-corpus-layout.md)
- [Golden Corpus Maintenance](../binary-index/golden-corpus-maintenance.md)
- [Golden Corpus Operations Runbook](../../runbooks/golden-corpus-operations.md)

## Current Status

Implemented with Controller for snapshot export and Importer for secure ingestion. Staleness policies enforce time-bound validity. Integrated with ExportCenter for bundle packaging and all data modules for content export/import.