Airgapped Updates for Greentic

TL;DR

One refinement over the original proposal: the in-gap server must not be a hard prerequisite. A serverless sneakernet path (export → removable media → op updates import → apply) is a strict subset of the server story, covers single-host installs, and ships first. The fleet-scale in-gap server layers on top, reusing the same envelope file unchanged.

Problem & context

Greentic's update train is live and connected-only: DSSE-signed update plans are published to updates.greentic.cloud, runtimes poll (or receive SSE hints), verify plans against a per-environment local trust-root.json, and apply them through a staging state machine with snapshots and rollback — including binary self-update. Every step of delivery assumes outbound internet.

Enterprise and defense customers run airgapped environments: no outbound network, ever. They still need signed, verifiable, rollback-safe updates. The question assessed here: is "customer boots their own updater server inside the gap + import/export tooling" the right architecture, per industry best practice — or does something better exist?

Industry best practices

Distilled principles

• One self-contained signed archive for export/import — never loose files.
• End-to-end verification inside the gap — the USB stick / diode is never trusted; only signatures and digests are.
• Everything digest-pinned — the signed plan pins the sha256 of every artifact; the export carries the exact pinned bytes.
• Offline trust anchor — trust roots provisioned at install time from files; no network trust resolution at runtime.
• Anti-rollback + explicit freshness policy — monotonicity must survive imports; expiry must not brick long-offline environments.
• Unmodified client protocol — in-gap clients speak the same protocol to the in-gap server; no "airgap mode" fork.

What exists today (verified fact base)

Everything below was verified in code on 2026-07-24. The striking result: verification is already transport-independent, and the offline halves of the pipeline already exist.

The plan-server wire contract is deliberately tiny: anonymous GET plan | plan.sig | plan/meta + optional SSE; authenticated POST …/plan with monotonic-sequence 409; GET /v1/environments for fleet listing. Production runs on a Cloudflare Worker (not airgappable); a private in-memory Rust server and a public wire-compatible demo Worker also exist.

Gaps to close

1. envelope.rs is unimplemented — the pack/unpack/scan library does not exist.
2. In-band artifacts are rejected by every consumer: DistArtifactFetcher hard-errors on source=None ("in-band airgap artifacts are not supported by op updates get", updates.rs:1763-1769); the runtime binary self-update skips source=None ("out of P7d scope", greentic-start/src/revision_serve.rs:2073).
3. No export/import verbs, no in-gap serving story, no CLI surface for offline/insecure-registry modes, and no key-rotation object that can cross the gap.

Architecture

Both delivery paths converge on the same staging FSM and apply pipeline — the client cannot tell (and does not care) whether an update arrived over the internet or on removable media. The transfer medium is untrusted by construction: the vendor's DSSE signature and the plan's per-artifact sha256 pins are the only trust anchors, and both are checked inside the gap against a locally provisioned trust root.

The .gtupdate envelope

A plain tar archive (+zstd) — streamable (written and read sequentially, blobs verified inline, never buffered whole in memory), splittable with standard tools for multi-volume media, and multi-GB-capable. SquashFS was rejected: it suits random-access runtime reads (.gtbundle), but the envelope is read once at import and unpacked into the staging tree.

my-update.gtupdate
├── manifest.json          # content list: plan_id, sequence, created_at, entries[]
├── manifest.json.sig      # DSSE envelope over manifest.json
├── plan.json              # exact signed plan bytes (unchanged from connected lane)
├── plan.json.sig          # DSSE envelope — same sidecar as today
├── blobs/
│   └── sha256-<hex>       # one file per artifact/binary, content-addressed
├── trust-rotation.json    # OPTIONAL: greentic.trust-rotation.v1, DSSE-signed
└── trust-rotation.json.sig

• Binary payload representation (gate finding 2): blobs carry the raw inner executable, content-addressed by the existing BinaryArtifact.digest — which already hashes the inner binary, not the release archive (plan.rs:121-124). Release archives are never carried in-band; manifest entries declare media_type + target triple; consumers (binswap, import) take the executable directly and skip the unpack path.
• Delta exports are inventory-based, not sequence-based (gate finding 3): staged blobs are per-plan and retention-evicted (staging.rs:798-836), so "applied sequence N" proves nothing about possession. Import maintains a durable, refcounted import CAS and writes a signed import receipt (env, root version, held digests); export takes --base-receipt or --base-envelope <digest>. Import preflight resolves every digest the plan references before admission and fails closed listing what's missing — a delta can never verify yet be unapplyable. Import stays idempotent, so a full export is always the safe fallback.
• Target filtering: --targets x86_64-unknown-linux-gnu,… slims binary payload; default is all targets (safe but large).
• Verify-on-import (the "import-side scanner" from the stub): manifest signature, plan signature against the target env's trust root, every blob sha256 — quarantine on any failure. Verify-on-apply is unchanged: the existing staging FSM re-verifies the plan DSSE and every artifact digest again at apply time.
• Strict archive grammar (gate finding 4 — the scanner is a DoS surface: container metadata parses before authentication completes): fixed entry order (manifest first), exact path allowlist, regular files only (no symlinks, hardlinks, sparse files, devices, FIFOs), no duplicate paths, bounded entry count / per-entry size / total expanded bytes / compression ratio, disk-space reservation, extraction into a quarantine directory, atomic commit. Ship-gated test battery: decompression bomb, duplicate entry, hardlink, sparse file, special file, oversized manifest. Precedent in-house: binswap's MAX_UNPACK_BYTES and zip-slip guards.

Design decisions (tension resolutions)

Deployment tiers

Trust & safety model

• The medium is never trusted. USB sticks, DVDs, diodes carry sealed content; the import scanner and the apply path independently verify signatures and digests against the locally provisioned trust root.
• Fail closed. Missing trust root = empty trust root = every plan rejected. Unknown signing keys rejected. Tampered blob = quarantine.
• No downgrades. Plan sequence must be strictly monotonic per environment — enforced client-side, so it survives any import ordering or replayed media.
• No config smuggling. A signed plan can never carry updates channel config or trust-root changes — existing invariants, preserved. Rotation is a separate object requiring a threshold of dedicated rotation-role keys, verified and committed atomically with the rest of the envelope.
• Deny-by-default stands. An environment that never opts into updates contacts nothing and accepts nothing.

Phased roadmap (each phase independently shippable)

Execution steps (this plan's immediate work)

1. Author the design document at greentic-update/docs/airgap-update-delivery.md — it lives with the envelope code it governs. Sections: exec summary · problem · industry landscape · design principles · architecture · .gtupdate spec · tension resolutions · trust model · freshness/anti-rollback · tiers · client-protocol invariant · bootstrap media · roadmap · risks · wire-contract appendix. Every code claim cites file:line.
2. Land via feature branch + PR on greentic-update, base develop. Doc-only change: skip cargo update/coverage; still run bash ci/local_check.sh before the PR.
3. Run the adversarial design gate (Codex review) over the doc before any Phase A implementation planning; fold findings in or reject them explicitly in the risks section.

Design-gate round 1 (Codex adversarial review, 2026-07-28)

All four findings were verified against the code and confirmed; each is folded into the design above.

Risks & open questions

Appendix — wire contracts touched

Plan server (unchanged; what in-gap serving must replicate)

New schemas introduced by this design

Source plan: plans/airgapped-updates-design.md in the Greentic workspace. Industry references: Replicated air-gap install/update flow, Zarf (zarf-dev/zarf), Hauler, TUF/Sigstore offline-root guidance. Code facts verified 2026-07-24 against the develop checkouts of greentic-update, greentic-start, greentic-deployer, greentic-bundle, greentic-distributor-client, greentic-trust.