docs(H1): doc06 §4.5/§4.6 amendment + endpoint runbook §9 + scripts CHANGELOG + REPORT + CONTEXT

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6
2026-07-05 23:03:33 +02:00
parent b70f2d0763
commit 61f4898d30
5 changed files with 113 additions and 49 deletions
@@ -311,3 +311,38 @@ The rebuild is **steps 1–7 on a fresh VM**. What is lost vs regenerable:
  (customers still hold local backups + a re-seedable offsite).
 - The hub's SSH credential + pinned host key must be **rotated on rebuild** (new box = new
  host key): repeat step 6 (`kubectl delete secret wg-endpoint-ssh` first), roll the hub.
+
+## 9. OOB operator forwarding (TASK H1 — 2026-07-05)
+
+The endpoint gains a **per-pair operator→box forward** posture so the operator peer can reach each
+box's `felhom-sshd` (doc 06 §4.5 amended: forwarding ON but per-pair allow-listed; box↔box drop is
+now explicit). Peersync is UNCHANGED — it still manages only the peer *list*; these forward rules are
+STATIC endpoint config.
+
+```sh
+# 1. permanent forwarding
+echo 'net.ipv4.ip_forward = 1' > /etc/sysctl.d/99-felhom-oob.conf
+sysctl -w net.ipv4.ip_forward=1
+
+# 2. forward posture in the STATIC nftables filter forward chain (add to /etc/nftables.conf's
+#    `chain forward` — which keeps `policy drop`). ONE accept rule per (operator, box) pair; the
+#    box↔box drop is explicit. Reload path so replies + the PBS path are unaffected (INPUT hook).
+#    <operator/32> = GET /api/v1/admin/wg/operator-peer ; <box/32> = each host's assigned_ip.
+    ct state established,related accept
+    iifname "wg0" oifname "wg0" ip saddr <operator/32> ip daddr <box/32> counter accept
+    iifname "wg0" oifname "wg0" counter drop
+```
+
+**Register the operator peer** (hub, global key) — it becomes an UNBOUND `wg_peers` row (peersync
+pushes it to wg0) and its `/32` flows to every box as `oob_peer_ip`:
+```sh
+curl -s -X PUT https://hub.felhom.eu/api/v1/admin/wg/operator-peer \
+  -H "Authorization: Bearer <GLOBAL-KEY>" \
+  -d '{"pubkey":"<operator WG pubkey>","assigned_ip":"10.77.0.250","ssh_pubkey":"ssh-ed25519 AAAA… operator"}'
+```
+
+**Box side:** `felhom-host-install … --enable-oob` (static felhom-sshd + belt) + `oob.enabled=true`
+in `agent.json`. The agent renders the config, claims a port, writes `felhom-op`'s authorized_keys
+from `oob_operator_ssh_key`, and fills the belt sets. Verify: from the operator peer,
+`ssh -p <claimed-port> felhom-op@<box tunnel IP>`; the host belt drops any non-operator tunnel source.
+Re-verify PBS (`pvesm status --storage felhom-offsite` on the box) after the forward change.