# Sprint 0510 · Ops & Offline · AirGap (190.E)

## Topic & Scope
- Implement air-gap controller/importer/time components: seal/unseal state machine, status APIs, importer verification, and time-anchor telemetry for offline bundles.
- Align with platform sealed-mode posture and ensure deterministic verification paths for offline kits.
- **Working directory:** `src/AirGap`. 

## Dependencies & Concurrency
- Upstream: Attestor/Authority scopes for `airgap:*`, Offline Kit bundle formats, DevOps sealed-mode pipeline outputs.
- AirGap Importer depends on Bundle trust roots and TUF metadata from release pipelines.

## Documentation Prerequisites
- docs/07_HIGH_LEVEL_ARCHITECTURE.md
- docs/modules/platform/architecture-overview.md
- docs/modules/devops/architecture.md
- docs/modules/airgap/airgap-mode.md (if present)

> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.

## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| P1 | PREP-AIRGAP-CTL-56-001-CONTROLLER-PROJECT-SCA | DONE (2025-11-20) | Prep note at `docs/airgap/prep/2025-11-20-controller-scaffold-prep.md`; scaffold details in `docs/airgap/controller-scaffold.md`. | AirGap Controller Guild | Controller project scaffold missing; need baseline service skeleton. <br><br> Document artefact/deliverable for AIRGAP-CTL-56-001 and publish location so downstream tasks can proceed. |
| P2 | PREP-AIRGAP-CTL-56-002-BLOCKED-ON-56-001-SCAF | DONE (2025-11-20) | Prep note at `docs/airgap/prep/2025-11-20-controller-scaffold-prep.md`; status endpoint sketch included. | AirGap Controller Guild · DevOps Guild | Blocked on 56-001 scaffolding. <br><br> Document artefact/deliverable for AIRGAP-CTL-56-002 and publish location so downstream tasks can proceed. |
| P3 | PREP-AIRGAP-CTL-57-001-BLOCKED-ON-56-002 | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Controller Guild | AirGap Controller Guild | Blocked on 56-002. <br><br> Deliverable: sealed-mode startup diagnostics spec at `docs/airgap/sealed-startup-diagnostics.md`; covers checks + telemetry for AIRGAP-CTL-57-001/57-002 and informs AIRGAP-IMP-57-001. |
| P4 | PREP-AIRGAP-CTL-57-002-BLOCKED-ON-57-001 | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Controller Guild · Observability Guild | AirGap Controller Guild · Observability Guild | Blocked on 57-001. <br><br> Deliverable: sealed-mode startup diagnostics + telemetry/timeline hooks defined in `docs/airgap/sealed-startup-diagnostics.md`; includes events `airgap.sealed`/`airgap.unsealed` and counters for anchor staleness. |
| P5 | PREP-AIRGAP-CTL-58-001-BLOCKED-ON-57-002 | DONE (2025-11-20) | Prep note at `docs/airgap/prep/2025-11-20-staleness-drift-prep.md`; ties to time anchor data. | AirGap Controller Guild · AirGap Time Guild | Blocked on 57-002. <br><br> Document artefact/deliverable for AIRGAP-CTL-58-001, AIRGAP-IMP-58-001, AIRGAP-TIME-58-001 and publish location so downstream tasks can proceed. |
| P6 | PREP-AIRGAP-IMP-56-001-IMPORTER-PROJECT-SCAFF | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Importer Guild | AirGap Importer Guild | Importer project scaffold missing; need trust-root inputs. <br><br> Deliverable: scaffold + doc at `docs/airgap/importer-scaffold.md`; project + tests under `src/AirGap/StellaOps.AirGap.Importer` and `tests/AirGap/StellaOps.AirGap.Importer.Tests`. |
| P7 | PREP-AIRGAP-IMP-56-002-BLOCKED-ON-56-001 | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Importer Guild · Security Guild | AirGap Importer Guild · Security Guild | Blocked on 56-001. <br><br> Deliverable shares scaffold above; downstream tasks now have deterministic plan and trust-root contract. |
| P8 | PREP-AIRGAP-IMP-58-002-BLOCKED-ON-58-001 | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Importer Guild · Observability Guild | AirGap Importer Guild · Observability Guild | Blocked on 58-001. <br><br> Deliverable shares scaffold above; includes plan steps + validation envelope for import timeline events. |
| P9 | PREP-AIRGAP-TIME-57-001-TIME-COMPONENT-SCAFFO | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Time Guild | AirGap Time Guild | Time component scaffold missing; need token format decision. <br><br> Deliverable: `src/AirGap/StellaOps.AirGap.Time` project + tests and doc `docs/airgap/time-anchor-scaffold.md` covering Roughtime/RFC3161 stub parser. |
| 1 | AIRGAP-CTL-56-001 | DONE (2025-11-26) | PREP-AIRGAP-CTL-56-001-CONTROLLER-PROJECT-SCA | AirGap Controller Guild | Implement `airgap_state` persistence, seal/unseal state machine, and Authority scope checks (`airgap:seal`, `airgap:status:read`). |
| 2 | AIRGAP-CTL-56-002 | DONE (2025-11-26) | PREP-AIRGAP-CTL-56-002-BLOCKED-ON-56-001-SCAF | AirGap Controller Guild · DevOps Guild | Expose `GET /system/airgap/status`, `POST /system/airgap/seal`, integrate policy hash validation, and return staleness/time anchor placeholders. |
| 3 | AIRGAP-CTL-57-001 | DONE (2025-11-26) | PREP-AIRGAP-CTL-57-001-BLOCKED-ON-56-002 | AirGap Controller Guild | Add startup diagnostics that block application run when sealed flag set but egress policies missing; emit audit + telemetry. |
| 4 | AIRGAP-CTL-57-002 | DONE (2025-11-26) | PREP-AIRGAP-CTL-57-002-BLOCKED-ON-57-001 | AirGap Controller Guild · Observability Guild | Instrument seal/unseal events with trace/log fields and timeline emission (`airgap.sealed`, `airgap.unsealed`). |
| 5 | AIRGAP-CTL-58-001 | DONE (2025-11-26) | PREP-AIRGAP-CTL-58-001-BLOCKED-ON-57-002 | AirGap Controller Guild · AirGap Time Guild | Persist time anchor metadata, compute drift seconds, and surface staleness budgets in status API. |
| 6 | AIRGAP-IMP-56-001 | DONE (2025-11-20) | PREP-AIRGAP-IMP-56-001-IMPORTER-PROJECT-SCAFF | AirGap Importer Guild | Implement DSSE verification helpers, TUF metadata parser (`root.json`, `snapshot.json`, `timestamp.json`), and Merkle root calculator. |
| 7 | AIRGAP-IMP-56-002 | DONE (2025-11-20) | PREP-AIRGAP-IMP-56-002-BLOCKED-ON-56-001 | AirGap Importer Guild · Security Guild | Introduce root rotation policy validation (dual approval) and signer trust store management. |
| 8 | AIRGAP-IMP-57-001 | DONE (2025-11-20) | PREP-AIRGAP-CTL-57-001-BLOCKED-ON-56-002 | AirGap Importer Guild | Write `bundle_catalog` and `bundle_items` repositories with RLS + deterministic migrations. Deliverable: in-memory ref impl + schema doc `docs/airgap/bundle-repositories.md`; tests cover RLS and deterministic ordering. |
| 9 | AIRGAP-IMP-57-002 | TODO | ✅ Unblocked (2025-12-06): `sealed-mode.schema.json` + `time-anchor.schema.json` available | AirGap Importer Guild · DevOps Guild | Implement object-store loader storing artifacts under tenant/global mirror paths with Zstandard decompression and checksum validation. |
| 10 | AIRGAP-IMP-58-001 | TODO | ✅ Unblocked (2025-12-06): Schemas available at `docs/schemas/` | AirGap Importer Guild · CLI Guild | Implement API (`POST /airgap/import`, `/airgap/verify`) and CLI commands wiring verification + catalog updates, including diff preview. |
| 11 | AIRGAP-IMP-58-002 | TODO | ✅ Unblocked (2025-12-06): Timeline event schema available | AirGap Importer Guild · Observability Guild | Emit timeline events (`airgap.import.started`, `airgap.import.completed`) with staleness metrics. |
| 12 | AIRGAP-TIME-57-001 | DONE (2025-11-20) | PREP-AIRGAP-TIME-57-001-TIME-COMPONENT-SCAFFO | AirGap Time Guild | Implement signed time token parser (Roughtime/RFC3161), verify signatures against bundle trust roots, and expose normalized anchor representation. Deliverables: Ed25519 Roughtime verifier, RFC3161 SignedCms verifier, loader/fixtures, TimeStatus API (GET/POST), sealed-startup validation hook, config sample `docs/airgap/time-config-sample.json`, tests passing. |
| 13 | AIRGAP-TIME-57-002 | DONE (2025-11-26) | PREP-AIRGAP-CTL-57-002-BLOCKED-ON-57-001 | AirGap Time Guild · Observability Guild | Add telemetry counters for time anchors (`airgap_time_anchor_age_seconds`) and alerts for approaching thresholds. |
| 14 | AIRGAP-TIME-58-001 | TODO | ✅ Unblocked (2025-12-06): `time-anchor.schema.json` with TUF trust + staleness models available | AirGap Time Guild | Persist drift baseline, compute per-content staleness (advisories, VEX, policy) based on bundle metadata, and surface through controller status API. |
| 15 | AIRGAP-TIME-58-002 | TODO | ✅ Unblocked (2025-12-06): Schemas and timeline event models available | AirGap Time Guild · Notifications Guild | Emit notifications and timeline events when staleness budgets breached or approaching. |
| 16 | AIRGAP-GAPS-510-009 | DONE (2025-12-01) | None; informs tasks 1–15. | Product Mgmt · Ops Guild | Address gap findings (AG1–AG12) from `docs/product-advisories/25-Nov-2025 - Air‑gap deployment playbook for StellaOps.md`: trust-root/key custody & PQ dual-signing, Rekor mirror format/signature, feed snapshot DSSE, tooling hashes, kit size/chunking, AV/YARA pre/post ingest, policy/graph hash verification, tenant scoping, ingress/egress receipts, replay depth rules, offline observability, failure runbooks. |
| 17 | AIRGAP-MANIFEST-510-010 | DONE (2025-12-02) | Depends on AIRGAP-IMP-56-* foundations | AirGap Importer Guild · Ops Guild | Implement offline-kit manifest schema (`offline-kit/manifest.schema.json`) + DSSE signature; include tools/feed/policy hashes, tenant/env, AV scan results, chunk map, mirror staleness window, and publish verify script path. |
| 18 | AIRGAP-AV-510-011 | DONE (2025-12-02) | Depends on AIRGAP-MANIFEST-510-010 | Security Guild · AirGap Importer Guild | Add AV/YARA pre-publish and post-ingest scans with signed reports; enforce in importer pipeline; document in `docs/airgap/runbooks/import-verify.md`. |
| 19 | AIRGAP-RECEIPTS-510-012 | DONE (2025-12-02) | Depends on AIRGAP-MANIFEST-510-010 | AirGap Controller Guild · Platform Guild | Emit ingress/egress DSSE receipts (hash, operator, time, decision) and store in Proof Graph; expose verify CLI hook. |
| 20 | AIRGAP-REPLAY-510-013 | DONE (2025-12-02) | Depends on AIRGAP-MANIFEST-510-010 | AirGap Time Guild · Ops Guild | Define replay-depth levels (hash-only/full recompute/policy freeze) and enforce via controller/importer verify endpoints; add CI smoke for hash drift. |
| 21 | AIRGAP-VERIFY-510-014 | DONE (2025-12-02) | Depends on AIRGAP-MANIFEST-510-010 | CLI Guild · Ops Guild | Provide offline verifier script covering signature, checksum, mirror staleness, policy/graph hash match, and AV report validation; publish under `docs/airgap/runbooks/import-verify.md`. |

## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-02 | Completed AIRGAP-REPLAY-510-013: added `replayPolicy` to manifest schema/sample, ReplayVerifier + controller `/system/airgap/verify` endpoint, and replay depth smoke tests for hash drift/policy freeze. | Implementer |
| 2025-12-02 | Completed AIRGAP-VERIFY-510-014: introduced `verify-kit.sh` offline verifier (hash/signature/staleness/AV/chunk/policy/receipt) and expanded runbook `docs/airgap/runbooks/import-verify.md`. | Implementer |
| 2025-12-02 | Completed AIRGAP-MANIFEST-510-010: added offline-kit manifest schema + sample (`docs/airgap/manifest.schema.json`, `docs/airgap/samples/offline-kit-manifest.sample.json`) and offline verifier runbook/script (`src/AirGap/scripts/verify-manifest.sh`, `docs/airgap/runbooks/import-verify.md`). | Implementer |
| 2025-12-02 | Completed AIRGAP-AV-510-011: added AV/YARA report schema + sample, AV scan runbook, and manifest integration guidance; AV reports now referenced from verifier runbook. | Implementer |
| 2025-12-02 | Completed AIRGAP-RECEIPTS-510-012: published receipt schema + sample and receipt verifier script; receipts now tie bundle/manifest hashes with optional DSSE digest. | Implementer |
| 2025-11-26 | Added time telemetry (AIRGAP-TIME-57-002): metrics counters/gauges for anchor age + warnings/breaches; status service now emits telemetry. Full time test suite now passing after aligning tests to stub verifiers. | AirGap Time Guild |
| 2025-11-26 | Completed AIRGAP-CTL-58-001: status response now includes drift + remaining budget seconds; staleness evaluation exposes seconds_remaining; partial test run (AirGapStateServiceTests) passed. | AirGap Controller Guild |
| 2025-11-26 | Implemented controller startup diagnostics + telemetry (AIRGAP-CTL-57-001/57-002): AirGap:Startup config, trust-root and rotation validation, metrics/log hooks; ran filtered tests `AirGapStartupDiagnosticsHostedServiceTests` (pass). Full suite not run in this session. | AirGap Controller Guild |
| 2025-11-26 | Resumed AIRGAP-CTL-57-001/57-002 (startup diagnostics + telemetry) after freeing disk space; proceeding with implementation. | AirGap Controller Guild |
| 2025-11-26 | Added Mongo2Go-backed controller store tests (index uniqueness, parallel upserts, staleness round-trip) and test README covering OpenSSL shim. | AirGap Controller Guild |
| 2025-11-26 | Documented test shim note in `tests/AirGap/README.md` and linked controller scaffold to Mongo test guidance. | AirGap Controller Guild |
| 2025-11-26 | Added Mongo-backed controller state store (opt-in via `AirGap:Mongo:*`), DI wiring, and scaffold doc note; controller tests still passing. | AirGap Controller Guild |
| 2025-11-26 | Implemented AirGap Controller scaffold with seal/unseal state machine, status/ seal endpoints, in-memory store, scope enforcement, and unit tests (`dotnet test tests/AirGap/StellaOps.AirGap.Controller.Tests`). | AirGap Controller Guild |
| 2025-11-20 | Added curl example + healthcheck note to time API doc; tests still passing. | Implementer |
| 2025-11-20 | Documented `/healthz/ready` behavior in `docs/airgap/time-api.md`; health depends on anchor presence/staleness. | Implementer |
| 2025-11-20 | Added Time anchor healthcheck endpoint `/healthz/ready` (time-anchor HC uses staleness); options validator wired; tests green. | Implementer |
| 2025-11-20 | Loader now rejects missing/incompatible trust roots; controller logs failures/success for POST /api/v1/time/anchor; tests remain passing. | Implementer |
| 2025-11-20 | Added AirGap options validator tests (tenant/budget guardrails); test suite remains passing. | Implementer |
| 2025-11-20 | Added AirGap options validator (tenant + staleness budgets) and kept Time tests passing. | Implementer |
| 2025-11-20 | Hardened TimeAnchorLoader trust-root checks (format compatibility) and added verifier tests; Time tests still green. | Implementer |
| 2025-11-20 | Added time API doc (`docs/airgap/time-api.md`) and AirGap docs index; tests still passing after doc updates. | Implementer |
| 2025-11-20 | Added budget-mismatch guard test for sealed startup validator; Time tests remain passing. | Implementer |
| 2025-11-20 | Added crypto-backed tests for Roughtime (Ed25519) and RFC3161 (SignedCms) verifiers; Time test suite still green. | Implementer |
| 2025-11-20 | Wired config-driven tenant/staleness budgets into Time host; verifiers now real (Roughtime Ed25519, RFC3161 SignedCms); config sample added (`docs/airgap/time-config-sample.json`); tests remain green. | Implementer |
| 2025-11-20 | Upgraded time verifiers: Roughtime Ed25519 signature check and RFC3161 SignedCms verification; docs updated. | Implementer |
| 2025-11-20 | Added sealed startup validator hook; API POST `/api/v1/time/anchor`/GET `/api/v1/time/status` now exercised by tests; Time project builds standalone. | Implementer |
| 2025-11-20 | Added sealed-startup validator for time anchors; POST `/api/v1/time/anchor` persists anchor + budgets, GET `/api/v1/time/status` returns staleness; tests passing. | Implementer |
| 2025-11-20 | Added TimeStatusController + web host; exposed `/api/v1/time/status` and POST `/api/v1/time/anchor` using trust-root verified loader; tests still passing. | Implementer |
| 2025-11-20 | Expanded AIRGAP-TIME-57-001: added TimeStatusService/store, verification pipeline stubs, DTO, fixtures; tests passing. Added API surface `/api/v1/time/status`. | Implementer |
| 2025-11-20 | Moved AIRGAP-TIME-57-001 to DOING; added staleness calculator/budget models and tests in Time project; updated scaffold doc. | Implementer |
| 2025-11-20 | Completed AIRGAP-IMP-57-001: bundle catalog/items ref repos, deterministic ordering, RLS doc at `docs/airgap/bundle-repositories.md`; tests passing. | Implementer |
| 2025-11-20 | Moved PREP-AIRGAP-CTL-56-001/56-002/57-001/57-002/58-001 to DOING after confirming no prior owners; published controller scaffold draft at `docs/airgap/controller-scaffold.md`. | Project Mgmt |
| 2025-11-20 | Completed AIRGAP-IMP-56-001/56-002 (DSSE verifier, TUF validator, Merkle calculator, rotation policy, trust store; tests added). | Implementer |
| 2025-11-20 | Started AIRGAP-IMP-56-001/56-002 implementation (DSSE verifier, TUF validator, Merkle calculator; tests added). | Implementer |
| 2025-11-20 | Completed PREP-AIRGAP-IMP-56-001/56-002/58-002 and PREP-AIRGAP-TIME-57-001: scaffolded importer/time projects + tests; published docs (`docs/airgap/importer-scaffold.md`, `docs/airgap/time-anchor-scaffold.md`). | Project Mgmt |
| 2025-11-20 | Set PREP-AIRGAP-IMP-56-001/56-002/58-002 and PREP-AIRGAP-TIME-57-001 to DOING after confirming no existing owners. | Project Mgmt |
| 2025-11-20 | Published prep notes for controller scaffold and staleness enrichment (`docs/airgap/prep/2025-11-20-controller-scaffold-prep.md`, `docs/airgap/prep/2025-11-20-staleness-drift-prep.md`); marked PREP-AIRGAP-CTL-56-001/56-002/58-001 DONE. | Implementer |
| 2025-11-19 | Assigned PREP owners/dates; see Delivery Tracker. | Planning |
| 2025-11-18 | Marked all AIRGAP controller/importer/time tasks BLOCKED: no project scaffolds exist under src/AirGap; need baseline service skeletons and token format decisions before implementation. | Ops/Docs |
| 2025-11-18 | Normalised sprint to standard template; renamed from SPRINT_510_airgap.md. | Ops/Docs |
| 2025-11-25 | Created module charter `src/AirGap/AGENTS.md`; controller tasks unblocked from AGENTS gap. | Implementer |
| 2025-11-25 | Local environment out of disk space (`No space left on device`); controller tasks moved to BLOCKED until workspace is cleaned. | Implementer |
| 2025-11-25 | Blocked controller chain (tasks 1–5): module-level `src/AirGap/AGENTS.md` missing; cannot proceed per working agreements until charter exists. Added status notes. | Implementer |
| 2025-12-01 | Added AIRGAP-GAPS-510-009 to track remediation of AG1–AG12 from `docs/product-advisories/25-Nov-2025 - Air‑gap deployment playbook for StellaOps.md`. | Product Mgmt |
| 2025-12-01 | AIRGAP-GAPS-510-009 DONE: drafted remediation plan `docs/airgap/gaps/AG1-AG12-remediation.md` covering trust roots, Rekor mirror, feed freezing, tool hashes, chunked kits, AV/YARA, policy/graph hashes, tenant scoping, ingress/egress receipts, replay levels, observability, and runbooks. | Implementer |
| 2025-12-02 | Added implementation tasks 510-010…014 for manifest schema + DSSE, AV/YARA scans, ingress/egress receipts, replay-depth enforcement, and offline verifier script per `docs/product-advisories/25-Nov-2025 - Air‑gap deployment playbook for StellaOps.md`. | Project Mgmt |
| 2025-12-06 | ✅ **5 tasks UNBLOCKED**: Created `docs/schemas/sealed-mode.schema.json` (AirGap state, egress policy, bundle verification) and `docs/schemas/time-anchor.schema.json` (TUF trust roots, time anchors, validation). Tasks AIRGAP-IMP-57-002, 58-001, 58-002 and AIRGAP-TIME-58-001, 58-002 moved from BLOCKED to TODO. | System |

## Decisions & Risks
- Seal/unseal + importer rely on release pipeline outputs (trust roots, manifests); delays there delay this sprint.
- Time anchor parsing depends on chosen token format (Roughtime vs RFC3161); must be confirmed with AirGap Time Guild.
- Offline posture: ensure all verification runs without egress; CMK/KMS access must have offline-friendly configs.
- Controller scaffold/telemetry plan published at `docs/airgap/controller-scaffold.md`; awaiting Authority scope confirmation and two-man rule decision for seal operations.
- Repo integrity risk: current git index appears corrupted (phantom deletions across repo). Requires repair before commit/merge to avoid data loss.
- Local execution risk: runner reports “No space left on device”; cannot run builds/tests until workspace is cleaned. Mitigation: purge transient artefacts or expand volume before proceeding.
- Test coverage note: only `AirGapStartupDiagnosticsHostedServiceTests` executed after telemetry/diagnostics changes; rerun full controller test suite when feasible.
- Time telemetry change: full `StellaOps.AirGap.Time.Tests` now passing after updating stub verifier tests and JSON expectations.
- Manifest schema + verifier scripts added; downstream tasks 18–21 should reuse `docs/airgap/manifest.schema.json`, `src/AirGap/scripts/verify-manifest.sh`, and `src/AirGap/scripts/verify-kit.sh` for AV receipts and replay verification.
- AV runbook/report schema added; importer pipeline must generate `av-report.json` (see `docs/airgap/av-report.schema.json`) and update manifest `avScan` fields; bundles with findings must be rejected before import.
- Replay depth enforcement added: manifest now requires `replayPolicy`; offline verifier `verify-kit.sh` and controller `/system/airgap/verify` must be used (policy-freeze demands sealed policy hash) to block hash drift and stale bundles.

## Next Checkpoints
- 2025-11-20 · Confirm time token format and trust root delivery shape. Owner: AirGap Time Guild.
- 2025-11-22 · Align on seal/unseal Authority scopes and baseline policy hash inputs. Owner: AirGap Controller Guild.
- 2025-11-25 · Verify release pipeline exposes TUF metadata paths for importer (AIRGAP-IMP-56-001). Owner: AirGap Importer Guild.