# 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.