prep docs and service updates

docs/airgap/README.md

@@ -0,0 +1,8 @@
+# AirGap Docs Index
+
+- Time anchors & staleness: `time-anchor-scaffold.md`, `staleness-and-time.md`, `time-config-sample.json`, `time-api.md`, `time-anchor-verification-gap.md`.
+- Importer scaffolds: `importer-scaffold.md`, `bundle-repositories.md`.
+- Controller/diagnostics: `controller-scaffold.md`, `sealed-startup-diagnostics.md`.
+- Portable evidence flows: `portable-evidence.md`.
+
+Use these as the front door for AirGap module work; update alongside code changes.

docs/airgap/prep/2025-11-20-controller-scaffold-prep.md

@@ -0,0 +1,20 @@
+# Controller Scaffold Prep — PREP-AIRGAP-CTL-56-001 / 56-002
+
+Status: Draft (2025-11-20)
+Owners: AirGap Controller Guild · DevOps Guild
+Scope: Provide the controller scaffold + status API contract so AIRGAP-CTL-56-001/56-002 can proceed.
+
+## Deliverables included
+- Service scaffold described in `docs/airgap/controller-scaffold.md` (project layout, DI wiring, config keys, auth scopes).
+- Baseline status/seal endpoints sketch:
+  - `GET /system/airgap/status` → `{sealed, policy_hash?, staleness_seconds?, time_anchor_id?, bundle_id?}`
+  - `POST /system/airgap/seal` (body: `{policy_hash, reason}`) → returns new state; requires `airgap:seal` scope.
+- Determinism & offline posture: no external calls; state persisted via `airgap_state` store; timestamps UTC; subject ordering deterministic.
+
+## Next steps for implementation
+- Generate controller project under `src/AirGap/StellaOps.AirGap.Controller` per scaffold.
+- Wire Authority scope checks (`airgap:seal`, `airgap:status:read`).
+- Add sealed-mode guard middleware and timeline events per `docs/airgap/sealed-startup-diagnostics.md` once integrated.
+
+## Handoff
+Use this prep doc to satisfy PREP-AIRGAP-CTL-56-001 and PREP-AIRGAP-CTL-56-002. Update if scope changes; otherwise move tasks to DONE.

docs/airgap/prep/2025-11-20-staleness-drift-prep.md

@@ -0,0 +1,25 @@
+# Staleness & Drift Prep — PREP-AIRGAP-CTL-58-001-BLOCKED-ON-57-002
+
+Status: Draft (2025-11-20)
+Owners: AirGap Controller Guild · AirGap Time Guild
+Scope: Capture the staleness/drift requirements for controller status once seal/unseal telemetry (57-002) is available.
+
+## Inputs
+- Time anchor ingestion from Time service (Roughtime/RFC3161) via `time_anchor_id`, `drift_seconds`, `staleness_budget_seconds`.
+- Bundle metadata from importer (bundle_id, manifest hash, generated_at).
+
+## Proposed status enrichments
+- Add fields to `GET /system/airgap/status`:
+  - `staleness_seconds_remaining`
+  - `bundle_id`
+  - `time_anchor_id`
+  - `drift_seconds`
+- Compute `staleness_seconds_remaining = staleness_budget_seconds - drift_seconds` (floor at 0).
+- Determinism: calculations purely from stored numbers; no wall-clock calls beyond persisted anchor timestamps.
+
+## Observability
+- Metrics: `airgap_staleness_seconds{tenant}` (gauge), `airgap_drift_seconds{tenant}`.
+- Timeline events emitted when budgets breached: `airgap.staleness.threshold`.
+
+## Handoff
+Use this prep note to satisfy PREP-AIRGAP-CTL-58-001. After integrating sealed-startup telemetry and time anchor verification, implement the above fields and metrics, then mark the implementation task DOING.

docs/airgap/time-anchor-scaffold.md

@@ -16,6 +16,12 @@
 - Added `TimeStatusService` + `InMemoryTimeAnchorStore` for per-tenant anchor/budget status + staleness; tests in `TimeStatusServiceTests`.
 - Added verification pipeline (`TimeVerificationService`) with stub Roughtime/RFC3161 verifiers requiring trust roots; loader now verifies using trust roots.
 - Added API surface `/api/v1/time/status` (plus POST `/api/v1/time/anchor`) via `TimeStatusController` and web host wiring.
+- Added sealed startup hook (`StartupValidationExtensions`) to block app start when anchor missing/stale; uses budgets and returns structured reasons.
+- Upgraded Roughtime verifier to real Ed25519 signature check + RFC3161 verifier using SignedCms; failures now return `roughtime-*` / `rfc3161-*` reasons.
+- Added config binding (`AirGap:*`) for tenant and staleness budgets; startup validation pulls from config.
+- Added config sample at `docs/airgap/time-config-sample.json` for sealed-mode deployments.
+- Documented endpoints and payloads at `docs/airgap/time-api.md`.
+- Health check: `/healthz/ready` reports degraded/healthy based on staleness; consumers should scrape for sealed-mode readiness.
 
 ## Next implementation hooks
 - Plug real Roughtime and RFC3161 decoders, verifying against trust roots supplied via sealed-mode config.

docs/airgap/time-anchor-verification-gap.md

@@ -1,9 +1,9 @@
 # Time Anchor Verification Gap (AIRGAP-TIME-57-001 follow-up)
 
 ## Status (2025-11-20)
-- Parser: stubbed for Roughtime/RFC3161 with deterministic digest + derived anchor time.
+- Parser: Roughtime verifier now checks Ed25519 signature; RFC3161 verifier uses SignedCms signature validation and signing time attribute. Still needs final trust root bundle + fixture alignment.
 - Staleness: calculator + budgets landed; loader accepts hex fixtures.
-- Verification: pipeline exists (`TimeVerificationService`) with stub verifiers; still needs real crypto using guild-provided trust roots.
+- Verification: pipeline (`TimeVerificationService`) active; awaiting guild-provided trust roots (format + key IDs) for production readiness and to update tests/fixtures.
 
 ## What’s missing
 - Roughtime parser: parse signed responses, extract `timestamp`, `radius`, `verifier` public key; verify signature.

docs/airgap/time-api.md

@@ -0,0 +1,60 @@
+# AirGap Time API (status + anchor ingest)
+
+## Endpoints
+
+- `POST /api/v1/time/anchor`
+  - Body (JSON):
+    - `tenantId` (string, required)
+    - `hexToken` (string, required) — hex-encoded Roughtime or RFC3161 token.
+    - `format` (string, required) — `Roughtime` or `Rfc3161`.
+    - `trustRootKeyId` (string, required)
+    - `trustRootAlgorithm` (string, required)
+    - `trustRootPublicKeyBase64` (string, required) — pubkey (Ed25519 for Roughtime, RSA for RFC3161).
+    - `warningSeconds` (number, optional)
+    - `breachSeconds` (number, optional)
+  - Response: `TimeStatusDto` (anchor + staleness snapshot) or 400 with reason (`token-hex-invalid`, `roughtime-signature-invalid`, `rfc3161-verify-failed:*`, etc.).
+  - Example:
+    ```bash
+    curl -s -X POST http://localhost:5000/api/v1/time/anchor \
+      -H 'content-type: application/json' \
+      -d '{
+        "tenantId":"tenant-default",
+        "hexToken":"01020304deadbeef",
+        "format":"Roughtime",
+        "trustRootKeyId":"root-1",
+        "trustRootAlgorithm":"ed25519",
+        "trustRootPublicKeyBase64":"<base64-ed25519-public-key>",
+        "warningSeconds":3600,
+        "breachSeconds":7200
+      }'
+    ```
+
+- `GET /api/v1/time/status?tenantId=<id>`
+  - Returns `TimeStatusDto` with anchor metadata and staleness flags. 400 if `tenantId` missing.
+
+- `GET /healthz/ready`
+  - Health check: `Healthy` when anchor present and not stale; `Degraded` when warning threshold crossed; `Unhealthy` when missing/stale. Uses configured tenant/budgets.
+
+## Config
+
+`appsettings.json` (see `docs/airgap/time-config-sample.json`):
+```json
+{
+  "AirGap": {
+    "TenantId": "tenant-default",
+    "Staleness": {
+      "WarningSeconds": 3600,
+      "BreachSeconds": 7200
+    }
+  }
+}
+```
+
+## Startup validation
+- The host runs sealed-mode validation at startup using the configured tenant and budgets.
+- Fails closed with `sealed-startup-blocked:<reason>` if anchor is missing/stale or budgets mismatch.
+
+## Notes
+- Roughtime verifier checks Ed25519 signatures (message||signature framing).
+- RFC3161 verifier uses SignedCms signature verification and signing-time attribute for anchor time.
+- DTO serialization is stable (ISO-8601 UTC timestamps, fields fixed).

docs/airgap/time-config-sample.json

@@ -0,0 +1,9 @@
+{
+  "AirGap": {
+    "TenantId": "tenant-default",
+    "Staleness": {
+      "WarningSeconds": 3600,
+      "BreachSeconds": 7200
+    }
+  }
+}