Close Phase 4 overlay and Unix forwarding gaps

docs/architecture.md

@@ -271,7 +271,9 @@ peer card against the observed EndpointID and requires `overlay.route` on
 interface; if no runtime is active, the packet is persisted for `geth overlay
 recv`. Interface setup may require `CAP_NET_ADMIN`, sudo, a preconfigured
 `/dev/net/tun`, Wintun availability, or platform-specific network entitlements.
-Overlay discovery can use mDNS, peer exchange, and resource metadata, but
+Release artifacts include `docs/overlay-platforms.md` so operators have the
+current Linux TUN, macOS entitlement, and Windows Wintun guidance with the
+binary. Overlay discovery can use mDNS, peer exchange, and resource metadata, but
 discovery remains untrusted and cannot grant overlay access.
 
 `geth-pipe` currently supports `pipe listen/connect/send/recv` against a

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.

docs/roadmap.md

@@ -729,7 +729,7 @@ Goal: add authorized stream-oriented management workflows over Iroh.
     request/response forwarding exchange when local Iroh endpoint binding is
     available in the test environment.
 
-- `[~]` Optional Iroh overlay network.
+- `[x]` Optional Iroh overlay network.
   Acceptance criteria:
   - `[x]` Add a focused `geth-overlay` crate for overlay names, CIDRs,
     resource IDs, capabilities, status, and plan models.
@@ -762,12 +762,12 @@ Goal: add authorized stream-oriented management workflows over Iroh.
     remote packets back into the device.
   - `[x]` Runtime activation surfaces privilege/setup errors clearly instead of
     silently falling back to a non-overlay transport.
-  - `[ ]` Add live peer/IP coordination over trusted resource metadata and
+  - `[x]` Add live peer/IP coordination over trusted resource metadata and
     untrusted discovery candidates.
-  - `[ ]` Add packaged Windows Wintun deployment and macOS entitlement guidance
-    for release builds.
+  - `[x]` Add release-packaged Windows Wintun deployment notes and macOS
+    entitlement guidance for release builds.
 
-- `[~]` Unix socket forwarding where supported.
+- `[x]` Unix socket forwarding where supported.
   Acceptance criteria:
   - `[x]` Unix socket forwarding is available on Unix platforms through
     `geth pipe forward-unix`.
@@ -776,7 +776,7 @@ Goal: add authorized stream-oriented management workflows over Iroh.
   - `[x]` Unix socket paths must be absolute and reject parent-directory
     components.
   - `[x]` Tests cover Unix path validation and pipe wire request serialization.
-  - `[ ]` Unsupported platforms return clear errors.
+  - `[x]` Unsupported platforms return clear errors.
   - `[x]` Tests cover a full two-node Unix socket forwarding exchange.
 
 - `[x]` SSH proxy over Iroh.