Air-Gap Sealed-Mode Startup Diagnostics

Audience: AirGap Controller and Observability engineers.
Purpose: define the startup guardrails that stop Stella Ops services from running when sealed-mode requirements are unmet, and the diagnostics and telemetry they emit.

When a deployment is sealed, services must fail closed at startup rather than run in a partially-trusted state. This guide specifies the pre-flight checks, the structured failure signals, and the telemetry hooks the controller and importer wire together.

Pre-flight checks

airgap_state indicates sealed=true.
Egress allowlist configured (non-empty or explicitly []).
Trust root bundle + TUF metadata present and unexpired.
Time anchor available (see TimeAnchor schema) and staleness budget not exceeded.
Pending root rotations either applied or flagged with approver IDs.

On failure

Abort host startup with structured error code: AIRGAP_STARTUP_MISSING_<ITEM> (implemented as sealed-startup-blocked:<reason> in controller host).
Emit structured log fields: airgap.startup.check, status=failure, reason, bundlePath, trustRootVersion, timeAnchorDigest.
Increment counter airgap_startup_blocked_total{reason} and gauge airgap_time_anchor_age_seconds if anchor missing/stale.

Telemetry hooks

Trace event airgap.startup.validation with attributes: sealed, allowlist.count, trust_roots.count, time_anchor.age_seconds, rotation.pending.
Timeline events airgap.sealed and airgap.unsealed include startup validation results and pending rotations.

Integration points

Controller: run checks during IHostApplicationLifetime.ApplicationStarted before exposing endpoints.
Importer: reuse ImportValidator to ensure bundles + trust rotation are valid before proceeding.
Time component: provide anchor + staleness calculations to the controller checks.

Code references

src/AirGap/StellaOps.AirGap.Importer/Validation/* — trust and bundle validation primitives.
src/AirGap/StellaOps.AirGap.Time/* — time anchors and staleness calculations.
src/AirGap/StellaOps.AirGap.Controller/* — startup lifecycle and seal/unseal transitions.

Owners

AirGap Controller Guild · Observability Guild