up

docs/modules/attestor/airgap.md

@@ -0,0 +1,42 @@
+# Attestor Air-Gap Guide (DOCS-ATTEST-75-001)
+
+Last updated: 2025-11-25
+
+## Goal
+Run attestation verification entirely offline while keeping determinism and tenant safety intact.
+
+## Inputs & prerequisites
+- **Trust bundle**: DSSE signing keys + certificate chains packaged under `out/offline/attestor/trust-bundle/` (hash manifest included).
+- **Transparency checkpoints (optional)**: Rekor or equivalent checkpoints mirrored to `out/offline/attestor/transparency/`.
+- **Authority scopes**: `attest:verify` and tenant scoping (`X-Stella-Tenant`) are still required even in sealed mode.
+- **No external calls**: Outbound network must be disabled; attestor uses only the provided bundles.
+
+## Configuration (sealed mode)
+Set the following environment flags on WebService/Worker:
+- `Attestor__Offline__Enabled=true`
+- `Attestor__TrustBundlePath=/app/offline/trust-bundle`
+- `Attestor__Transparency__CheckpointPath=/app/offline/transparency` (optional)
+- `Attestor__Verification__DisableHttpFetch=true`
+
+Mount the bundle directories read-only; keep hashes alongside the payloads for audit.
+
+## Verification flow (offline)
+1. Client submits a DSSE envelope to `/api/v1/attestations/verify` with tenant header.
+2. Service loads keys from the offline trust bundle; issuer lookup is strictly local.
+3. If transparency data is present, the server verifies inclusion against the mirrored checkpoint; otherwise it records `transparency=skipped` in the rationale.
+4. Result is returned with deterministic fields: `subject`, `statementDigest`, `verified=true|false`, `transparency=passed|skipped|failed`, `rationale[]`.
+
+## Determinism safeguards
+- All hashes are lowercase hex; timestamps are UTC ISO-8601.
+- Sorting: multiple statements are ordered by `subject` then `statementDigest`.
+- No network retries or clock drift compensation; rely on bundle timestamps.
+
+## Operations checklist
+- [ ] Refresh trust bundle hashes before each deploy; compare against signed manifest.
+- [ ] Rotate keys by replacing the bundle atomically; restart workers to pick up changes.
+- [ ] Record verification results in the delivery ledger for replay/audit.
+
+## Related docs
+- `docs/modules/attestor/overview.md`
+- `docs/modules/attestor/keys-and-issuers.md`
+- `docs/modules/attestor/transparency.md`