diff --git a/documentation/architecture/03-host-agent.md b/documentation/architecture/03-host-agent.md index 644864d..a6ef56b 100644 --- a/documentation/architecture/03-host-agent.md +++ b/documentation/architecture/03-host-agent.md @@ -192,38 +192,114 @@ per Part 1: **snapshot** (LVM-thin, transient, whole-guest rollback — not a ba necessity, not just convenience. Integrity-verify (cheap, ciphertext-level) runs more often as the lighter check. +### 8a. PBS recovery-code escrow (zero-knowledge offsite-key recovery) + +The DR substrate is the PBS offsite tier, and it is client-side encrypted (zero-knowledge): if the +box dies, restoring the offsite backups requires the **PBS client encryption key `K`**, which died +with the box. The escrow is how `K` comes back **without** Felhom ever being able to read customer +data. Design (decisions, with the rationale that pins them): + +- **Live key unencrypted on the box** (`0600`, root): the agent backs up *and* runs restore-tests + unattended — no passphrase prompt on the management path. The privilege concentration this + implies is the whole argument for §3 root-minimization + a small auditable agent. +- **Wrap mechanism — PBS-native, not custom crypto.** At enrollment the agent generates a + high-entropy **recovery code `R`** and produces a **passphrase-protected copy of `K` under `R`** + using PBS's own key passphrase KDF (`proxmox-backup-client key` family). *Decision: lean on PBS's + documented, battle-tested key+passphrase path; do not roll a bespoke AEAD wrap.* Host/customer + binding is provided at the hub-storage layer (blob keyed by host-id), not by custom crypto. +- **Agent-side generation.** `R` is generated **on the box** (it already holds `K` and does the + wrapping), so `R` never touches the hub even in transit — zero-knowledge by construction. +- **Escrow = the `R`-wrapped blob → hub.** The hub stores opaque ciphertext bound to the + host/customer. Without `R` it is undecryptable; the operator cannot read customer data. (Hub-side + storage schema for the blob is a slice-10 / doc-05 item.) +- **Recovery code custody.** `R` is shown to the customer **once** at enrollment (printed/displayed) + and **never stored by Felhom in recoverable form**. Format: a grouped/word-list code (≥128-bit + entropy) — it is transcribed off paper by a non-technical household, so raw base32 invites typos. +- **Consumption (slice 10, host-loss).** New box re-enrolls in restore mode → hub ships the escrow + blob → customer enters `R` → box unwraps `K` → PBS restores proceed. +- **Optional belt-and-suspenders (product decision, default OFF).** A PBS **paperkey** (the raw key, + for a safe) gives the customer a recovery path that survives *both* box loss *and* recovery-code + loss, at the cost of a higher-value secret (raw key on paper, no second factor). Default is + hub-escrow + `R` only; offer the paperkey as an opt-in "advanced" path. + +**Properties stated for honesty (these go to the customer at enrollment):** +- **Irreducible residual:** losing `R` *and* the box (and, if not opted in, having no paperkey) = + the offsite backups are **unrecoverable, by anyone, including Felhom.** This is the cost of + genuine zero-knowledge and must be communicated, not buried. +- **Rotation ≠ key rotation:** rotating `R` re-wraps the escrow blob (and re-shows the customer a + new code) but does **not** re-encrypt existing PBS data — that data stays keyed by `K`. Changing + `K` itself is a separate, heavier operation (new key → new backups; old backups still need old + `K`) and is out of scope for routine recovery-code rotation. + ## 9. Provisioning & DR flows **Provisioning (reconcile-driven, by restore).** Fresh creation of a Docker-capable LXC needs the `keyctl=1` feature flag, which Proxmox permits only for `root@pam` (Phase 3, B3) — not the -scoped token. But a token-authorized **restore preserves `keyctl`** (Phase 3, B3), so the agent -provisions **by restoring a golden base image**, never by `pct create` on the per-customer path: +scoped token. But a token-authorized **restore preserves `keyctl`** (Phase 3, B3, empirically: +a token `vzrestore` of a keyctl archive produced a guest that kept `features: +nesting=1,keyctl=1,unprivileged:1`), so the agent provisions **by restoring a golden base +image**, never by `pct create` on the per-customer path. -- A **golden base archive** — minimal Debian + Docker, `nesting=1,keyctl=1`, overlayfs — is - built once as `root@pam` **at enrollment** (when the agent legitimately holds root to mint its - Proxmox token) and refreshed on a maintenance cadence. This is the one place `keyctl`/root - provisioning lives — off the per-customer path. -- To provision guest G: restore the golden archive → new VMID (token-covered: `VM.Allocate` + - `Datastore.AllocateSpace`; `keyctl` preserved) → reset identity (MAC/hostname) → size the guest - (CPU/mem config + `pct resize` rootfs, token-covered) → attach storage mounts per the manifest - → deploy the controller → hand it bootstrap config. A mid-flight failure is journaled and - compensating-rolled-back (destroy the just-restored guest — allowed without a signature per §4, - same-transaction provenance). +**Golden base image.** A **golden base archive** — minimal Debian + Docker, `nesting=1,keyctl=1`, +overlayfs — is built once as `root@pam` **at enrollment** (when the agent legitimately holds root +to mint its Proxmox token) and refreshed on a maintenance cadence. This is the one place +`keyctl`/root provisioning lives — off the per-customer path. Refresh cadence + fleet versioning +remain an operational open item (§13). -**Unified bring-up primitive.** Provisioning and DR-restore share the same token-covered front -half — *restore an archive → reset identity* — and differ only in the archive and the back half: -provisioning restores the **golden base** then deploys a fresh controller; DR-restore restores -the **customer's backup** (already containing controller + data), brings it up, and reattaches -external storage. One code path, exercised by every restore-test (§8). +**Unified bring-up primitive (shared *front half* — NOT shared identity policy).** Provisioning +and DR-restore share one token-covered front-half code path: -**Guest loss.** Agent restores G from the fastest surviving tier and resets identity -(MAC/hostname) so the restored guest rejoins cleanly — this *is* the unified restore primitive -above (customer-backup archive, DR back half). +> restore an archive → **reset identity** → size the guest (CPU/mem config + `pct resize` +> rootfs, token-covered) → attach storage mounts per the manifest -**Host/hardware loss.** Re-enroll the new host in **restore mode**; the hub — the durable -source of truth that survives box death — hands the new agent the existing identity, PBS -namespace, tunnel token, storage manifest, and a restore directive. Tunnel is reused from -the hub record, so DNS stays intact. +run as a **journaled reconcile job**; a mid-flight failure is compensating-rolled-back (destroy +the just-restored guest — allowed unsigned per §4, same-transaction provenance). They diverge in +the *archive* and the *back half*, **and in identity policy** (below). + +**Identity reset is scenario-specific — this is a correctness boundary, not a detail.** "Reset +identity" is shorthand for two different operations: + +- **Provision (golden base) → fresh identity, everything.** A provisioned guest is new: regenerate + MAC, hostname, **`/etc/machine-id`** (a duplicate breaks journald/DHCP/systemd), **SSH host + keys**, and it receives a **fresh** controller identity (host-id, local token, hub channel), + **fresh restic repo identity**, and a fresh tunnel association — all minted in the back half. +- **Guest-loss DR (customer backup) → preserve continuity identity, reset only what would + collide.** The restored guest must *continue* the customer's world: **keep** the restic repo + identity (resetting it orphans the existing backup chain — a silent data-continuity bug), the + tunnel/DNS association, and the hub host/customer binding. Reset only collision-prone host-local + identity (`machine-id`, SSH host keys, hostname as needed). **MAC is reset only when a source + guest may still be live** (e.g. partial loss, or the restore-*test* which boots link-down for + exactly this reason); in a true total guest-loss the original is gone, so the MAC can be kept to + preserve DHCP reservations. The agent decides MAC handling from the scenario, not a fixed rule. + +The exact reset set is being pinned empirically by the slice-7 bring-up spike (live, link-up, +which the slice-6 restore-test never did — it boots link-down precisely because identity reset is +slice 7). + +**Guest loss (slice 7).** Agent restores G from the fastest surviving tier (snapshot → local → +PBS) and applies the **DR identity policy** above so the restored guest rejoins cleanly. The +customer backup already contains the controller + data, so there is **no controller deploy** in +this path — bring up + reattach external storage and it is whole. This is fully in slice 7. + +### Slice mapping (what is built where — keep this current) + +| Capability | Slice | Status | +|---|---|---| +| Golden base image build (root@pam, at enrollment) | **7** | spike → build | +| Unified bring-up **front half** (restore→reset identity→size→attach storage), journaled + compensating rollback | **7** | spike → spec → implement | +| **Guest-loss DR** (front half + DR identity policy; no controller deploy) | **7** | in scope | +| PBS recovery-code escrow **creation** (§8a) | **7** | designed (§8a); implement | +| Provisioning **back half** — deploy controller, hand bootstrap config, mint per-guest local token | **8** | deferred — needs the controller-deploy path + agent↔controller local API (§6) | +| **Host/hardware loss** DR — re-enroll in "restore mode"; hub serves identity / PBS namespace / tunnel token / storage manifest / restore directive | **10** | deferred — needs hub desired-state serving; hub store today holds only `{host_id, customer_id, api_key}` (slice 3) | +| PBS escrow **consumption** (recover `K` on a new box) | **10** | deferred — exercised by host-loss DR | +| Golden base refresh cadence + fleet versioning | post-launch | operational, non-blocking (§13) | + +**Host/hardware loss (design intent — slice 10).** Re-enroll the new host in **restore mode**; +the hub — the durable source of truth that survives box death — hands the new agent the existing +identity, PBS namespace, tunnel token, storage manifest, a restore directive, and the **escrow +blob** (§8a) for the customer to unlock with their recovery code. Tunnel is reused from the hub +record, so DNS stays intact. This depends on hub desired-state serving (slice 10) and is not +buildable until then; recorded here so the front-half built in slice 7 lands ready for it. ## 10. Concurrency, crash-safety, idempotency @@ -263,15 +339,21 @@ argument for §3's root-minimization and a small, auditable agent. Resolved here: tunnel placement (host, agent-managed, own systemd service), the reconcile-vs-jobs fork (hybrid, gated by reversibility), agent process model, self-update -ownership, the local-API surface, the storage-manifest schema, **provision-by-restore**, and -the **root-vs-API boundary** (Phase 3, B3). +ownership, the local-API surface, the storage-manifest schema, **provision-by-restore**, the +**provision/DR slice boundary** (7 front-half + guest-loss DR + escrow creation; 8 provisioning +back-half; 10 host-loss DR + escrow consumption — §9 table), the **PBS recovery-code escrow +design** (§8a), and the **root-vs-API boundary** (Phase 3, B3). Still open: - Multi-tenant **resource fairness** on a shared host (per-guest cgroup limits, noisy-neighbor) — deferred to the company-case pass. - Operator-side **signing tooling** — where the operator signing key lives operationally and how a destructive op gets signed without undue friction (offline key vs. a small signing service; the security floor is "not in the hub"). - Hub-side **desired-state editing UX** and the host-domain report schema details — belong to the hub architecture doc. -- **Golden base image** refresh cadence + fleet versioning — who triggers a rebuild, how the per-host image version is tracked (operational detail, not blocking; §9). +- **Golden base image** refresh cadence + fleet versioning — operational, non-blocking (§9). +- **Identity-reset set** (live, link-up) — pinned empirically by the slice-7 bring-up spike; the + scenario-specific policy is settled in §9, the exact field list is the spike's deliverable. +- **Hub-side escrow storage + restore-mode serving** — the blob's hub schema and the restore-mode + desired-state handover are slice-10 / doc-05 (§8a, §9 host-loss). This doc hands the implementation three contracts it was waiting on: @@ -283,6 +365,17 @@ This doc hands the implementation three contracts it was waiting on: ## Changelog — design-review + Phase-3 fold-in (2026-06-08) +### Slice-7 scope + escrow design (2026-06-09) +- §9 rewritten: the bring-up primitive is a **shared front half only** — identity-reset policy is + **scenario-specific** (provision = fresh everything; guest-loss DR = preserve restic/tunnel/hub + continuity identity, reset only collision-prone host-local identity). Added the **slice 7/8/10 + mapping table** (front half + guest-loss DR + escrow creation in 7; provisioning back-half in 8; + host-loss DR + escrow consumption in 10). +- NEW §8a: **PBS recovery-code escrow** — live key unencrypted on box for unattended ops; agent + generates recovery code `R`; PBS-native passphrase-wrap of `K` under `R` escrowed to the hub + (zero-knowledge); consumption is slice 10. Irreducible-residual + rotation≠key-rotation stated. +- §13 updated accordingly. + - **NEW provision-by-restore** (§9): the agent provisions by **restoring a golden base image** (token-covered, preserves `keyctl`), never `pct create` on the per-customer path; one unified restore primitive shared with DR. §2 responsibility + §3 boundary updated.