felhom.eu/REPORT.md

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; the scripts history lives in 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.