AirGap Controller

Audience: operators and automation authors who query or transition Stella Ops sealed-mode state, plus engineers integrating with the controller’s API.

The AirGap Controller is the tenant-scoped state keeper for sealed-mode operation. It records whether an installation is sealed, what policy hash is active, which time anchor is in force, and what staleness budgets apply.

For workflow context, start at the Air-Gap overview and the Air-Gap Mode Guide.

Responsibilities

Maintain the current AirGap state per tenant (sealed/unsealed, policy hash, time anchor, staleness budgets).
Provide a deterministic, auditable status snapshot for operators and automation.
Enforce sealed/unsealed transitions via Authority scopes.
Emit telemetry signals suitable for dashboards and forensics timelines.

Non-goals:

Bundle signature validation and import staging (owned by the importer; see Importer).
Cryptographic signing (Signer/Attestor).

API

Base route group: /system/airgap (requires authorization).

`GET /system/airgap/status`

Required scope: airgap:status:read

Response: AirGapStatusResponse (current state + staleness evaluation).

Notes:

Tenant routing uses x-tenant-id (defaults to default if absent).
driftSeconds and secondsRemaining are derived from the active time anchor and staleness budget evaluation.
contentStaleness contains per-category staleness evaluations (clients should treat keys as case-insensitive).

`POST /system/airgap/seal`

Required scope: airgap:seal

Body: SealRequest

policyHash (required): binds the sealed state to a specific policy revision.
timeAnchor (optional): time anchor record (from the AirGap Time service).
stalenessBudget (optional): default staleness budget.
contentBudgets (optional): per-category staleness budgets (e.g., advisories, vex, scanner).

Behavior:

Rejects requests missing policyHash with 400 {"error": "policy_hash_required"}.
Records the sealed state and returns an updated status snapshot.

`POST /system/airgap/unseal`

Required scope: airgap:seal

Behavior:

Clears the sealed state and returns an updated status snapshot.
Staleness is returned as Unknown after unseal (clients should treat this as “not applicable”).

`POST /system/airgap/verify`

Required scope: airgap:status:read (policy AirGap.Verify, Program.cs:59-69) — verification is read-only, so it shares the status-read scope. There is no airgap:verify scope in the canonical catalog.

Purpose: verify replay / bundle verification requests against the currently active AirGap state.

State model (per tenant)

Canonical fields captured by the controller (see src/AirGap/StellaOps.AirGap.Controller):

tenantId
sealed
policyHash (nullable)
timeAnchor (TimeAnchor, may be Unknown)
stalenessBudget (StalenessBudget)
contentBudgets (Dictionary<string, StalenessBudget>)
driftBaselineSeconds (baseline used to keep drift evaluation stable across transitions)
lastTransitionAt (UTC)

Determinism requirements:

Use UTC timestamps only.
Use ordinal comparisons for keys and stable serialization settings for JSON responses.
Never infer state from wall-clock behavior other than the injected TimeProvider.

Persistence backend

Controller state persistence is implemented in src/AirGap/__Libraries/StellaOps.AirGap.Persistence using EF Core v10.

PostgresAirGapStateStore and PostgresBundleVersionStore use EF queries/updates with deterministic ordering guarantees preserved from the previous SQL paths.
AirGapDbContextFactory explicitly binds AirGapDbContextModel.Instance for the default airgap schema.
Integration fixtures that provision per-run schemas intentionally use runtime model mapping (no automatic compiled-model discovery) so table resolution stays schema-isolated.

Regeneration commands are documented in the AirGap module README under EF Core Persistence Workflow.

Telemetry

The controller emits:

Structured logs: airgap.status.read, airgap.sealed, airgap.unsealed, airgap.verify (include tenant_id, policy_hash, and drift/staleness).
Metrics: airgap_seal_total, airgap_unseal_total, airgap_status_read_total, and gauges for drift/budget/remaining seconds.
Timeline events (optional): airgap.sealed, airgap.unsealed, airgap.staleness.warning, airgap.staleness.breach.