Close Phase 4 overlay and Unix forwarding gaps

docs/overlay-platforms.md

@@ -0,0 +1,73 @@
+# Overlay Platform Notes
+
+This document captures prototype release guidance for `geth overlay up`.
+Overlay packets are always carried over Iroh on `/geth/overlay/1`; these notes
+only cover host interface setup for the local TUN/Wintun-style device.
+
+## Linux
+
+`geth overlay up <name>` uses `tun-rs` to create a layer-3 TUN device and assign
+the joined overlay virtual IP.
+
+Operational requirements:
+
+- `/dev/net/tun` must exist and be usable by the daemon process.
+- The user service must have enough privilege to create/configure the device,
+  commonly `CAP_NET_ADMIN`, a helper, or a supervised manual setup step.
+- The daemon should run as a user service; do not install geth as a system
+  service just to gain network privileges.
+
+Recovery checks:
+
+- Run `geth overlay interface-plan <name> --platform linux` to inspect the
+  intended commands.
+- If activation fails, check `/dev/net/tun`, user permissions, and whether the
+  service manager strips required capabilities.
+
+## macOS
+
+macOS uses utun-style devices. Release builds must document that host network
+integration may require user approval and network-extension or entitlement-aware
+packaging depending on the distribution path.
+
+Prototype guidance:
+
+- Run `geth overlay interface-plan <name> --platform macos` before activation.
+- Treat `geth overlay up` failures as host entitlement/setup failures, not as a
+  reason to fall back to another geth transport.
+- Keep the daemon as a LaunchAgent/user service. Do not install a privileged
+  system daemon unless a future signed helper design explicitly requires it.
+
+Release checklist:
+
+- Document required entitlements or helper setup for the chosen signing method.
+- Document how the LaunchAgent is installed and how users approve networking
+  prompts.
+- Include this document in release archives.
+
+## Windows
+
+Windows overlay activation needs a Wintun-compatible adapter path. The release
+artifact does not silently install kernel drivers.
+
+Prototype guidance:
+
+- Run `geth overlay interface-plan <name> --platform windows` before activation.
+- Install or make available Wintun through an operator-approved mechanism before
+  `geth overlay up`.
+- Keep the daemon as a per-user scheduled task. Do not install geth as a system
+  service for the prototype.
+
+Release checklist:
+
+- Either package the Wintun DLL/driver according to its license and installation
+  requirements, or clearly point users to an approved Wintun installation path.
+- Document how the per-user scheduled task is installed.
+- Include this document in release archives.
+
+## Security Boundary
+
+Discovery and peer-card metadata can suggest candidate endpoints and overlay
+virtual IPs, but they do not grant access. Packet injection still requires
+`overlay.route` on `resource:overlay:<name>`, and joining through a bearer token
+must not mutate node identity or grant trust graph permissions.