git.stella-ops.org/docs/implplan/SPRINT_0510_0001_0001_airgap.md

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)

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. 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. 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. 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. 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. 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. 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. 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. 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. 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	BLOCKED	PREP-AIRGAP-CTL-57-002-BLOCKED-ON-57-001	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	BLOCKED	PREP-AIRGAP-CTL-58-001-BLOCKED-ON-57-002	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	BLOCKED	PREP-AIRGAP-IMP-58-002-BLOCKED-ON-58-001	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	BLOCKED	PREP-AIRGAP-CTL-58-001-BLOCKED-ON-57-002	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	BLOCKED	PREP-AIRGAP-IMP-58-002-BLOCKED-ON-58-001	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	TODO	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	TODO	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	TODO	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	TODO	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-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-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

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 script added; downstream tasks 18–21 should reuse docs/airgap/manifest.schema.json and src/AirGap/scripts/verify-manifest.sh for AV receipts and replay verification.

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.