admin
7fb20d5fb0
Records the settled transport decisions (plain WG, host-side agent-managed pilot, one hub-driven endpoint VM running WG+PBS, hub source-of-truth over WireDesiredState, one datastore + per-customer namespaces, relay-through-DooPlex rejected). Grounded at file:line vs felhom.eu@bf099f6 + felhom-agent@4ba1b14. Backlog line resolved to cite spike + design doc. Docs-only; slices are separate future tasks. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6
63 lines
4.1 KiB
Markdown
63 lines
4.1 KiB
Markdown
# felhom.eu — task reports
|
||
|
||
> **Overwrite** this file with a summary of the most recent task only (uniform with the other repos; not cumulative). The cumulative hub history lives in [hub/CHANGELOG.md](hub/CHANGELOG.md); the scripts history lives in [scripts/CHANGELOG.md](scripts/CHANGELOG.md).
|
||
|
||
---
|
||
|
||
# REPORT — architecture Part 06: offsite-connectivity design-of-record (2026-07-03)
|
||
|
||
Docs-only. Created `documentation/architecture/06-offsite-connectivity.md` (design-of-record for
|
||
the offsite-backup transport); resolved the `day0-install.md` backlog line to cite spike + design
|
||
doc; CONTEXT + scripts/CHANGELOG updated. No code, no version bump, no deploy, no endpoint
|
||
provisioning.
|
||
|
||
## Baselines (verified fresh-pulled before writing)
|
||
|
||
- felhom.eu @ `bf099f6` (spike doc commit; this task's commit lands on top)
|
||
- felhom-agent @ `4ba1b14` (v0.63.0, read-only grounding)
|
||
|
||
## Grounding citations used (for reviewer validation against Gitea)
|
||
|
||
| Claim in the doc | Cited at |
|
||
|---|---|
|
||
| Backup = outbound push; PBS at LAN address | `01-topology-and-trust.md` §7; `felhom-agent/internal/pbs/client.go:25-26` (`Server` documented as `"192.168.0.180"`, port default 8007) |
|
||
| Public edge HTTP-only, no public UDP | `felhom.eu/manifests/hub.yaml:233` (`ingressClassName: nginx-internal`) |
|
||
| TLS pin above WG, unchanged through tunnel | `felhom-agent/internal/pbs/pin.go:17-35` (exact-cert `VerifyPeerCertificate`); spike P2b (positive + negative through-tunnel proof) |
|
||
| Desired-state channel + generation gate | `felhom-agent/internal/hub/report.go:270` (`DesiredGeneration`), `report.go:289-296` (`WireDesiredState` + forward-compat siblings), `internal/desired/syncer.go:44-61` (fetch only on generation advance) |
|
||
| IdentityBundle to extend | `felhom-agent/internal/escrow/identity.go:24-27` (`{TunnelToken, PBSToken}`) |
|
||
| Agent already installs+enables host units | `felhom-agent/configs/felhom-agent.sudoers:16-18` (`install … /etc/systemd/system/*.mount`, `systemctl enable --now`) |
|
||
| Hub drives external infra via held token | `felhom.eu/hub/internal/cloudflare/unblock.go` (CF token, WAF mutation) |
|
||
| cloudflared = later adopter of the S3 pattern | `felhom-agent/internal/hub/cloudflared.go:9-12` (read-only prober, self-described "seam for the tunnel-management slice") |
|
||
| All measurements | `documentation/audits/SPIKE-connectivity-wireguard-2026-07-03.md` (P0–P7) |
|
||
|
||
## What the doc marks DECIDED (recorded, not re-litigated)
|
||
|
||
D1 plain WG (no Headscale for traversal — separable future fleet layer); D2 host-side
|
||
**agent-managed** `wg-felhom` (pilot for agent-managed host services; install-script placement
|
||
rejected as one-shot; in-guest rejected on trust grounds — spike P7 shows it *works*, so the
|
||
refutation is architectural); D3 one shared dumb hub-driven endpoint VM (WG + PBS, no agent);
|
||
D4 hub = source of truth, `wireguard` block on the existing desired-state channel; D5 one
|
||
datastore + per-customer namespaces; D6 PBS ON the VM — relay-through-DooPlex rejected
|
||
(non-scaling through the ~40 Mbit home uplink, couples all DR to home uptime; DooPlex PBS =
|
||
dev/demo only).
|
||
|
||
## What the doc marks DEFERRED / OPEN (honest ledger, §7)
|
||
|
||
- **Open validation (one):** true-CGNAT traversal — unmeasured (operator line = plain-NAT, spike
|
||
P0); closure = mobile-hotspot smoke test, thorough = Peti VM 110; does not block S1/S2.
|
||
- Endpoint peer-sync mechanism (push-API vs signed-manifest pull) — slice-1 design point.
|
||
- WG key-rotation mechanics; endpoint scaling/sharding/HU-hosting; endpoint-VM self-DR depth.
|
||
|
||
## Slice roadmap set (each a future task)
|
||
|
||
S1 endpoint provisioning + peer-sync surface → S2 hub schema + desired-state → S3 agent WG
|
||
service (**risky/supervised**: sudoers + host service + escrow change) → S4 PBS-over-tunnel →
|
||
S5 DR re-establishment (merges with DR-completeness) → S6 monitoring/hardening.
|
||
**MVP = S1→S2→S3, then S4.**
|
||
|
||
## Author notes
|
||
|
||
None — no §2 decision looked wrong while writing; the one place the task's own earlier framing
|
||
was contradicted by evidence (guest-WG infeasibility) was already resolved by the spike and is
|
||
recorded as an architectural (not technical) refutation in D2.
|