Implement opt-in overlay TUN runtime

docs/adr/0017-optional-iroh-overlay-network.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Accepted for prototype scaffolding.
+Accepted for prototype implementation.
 
 ## Context
 
@@ -25,18 +25,32 @@ misconfigured.
 
 ## Decision
 
-Add an optional `overlay` resource kind and reserve `/geth/overlay/1` for a
-future Iroh-carried packet overlay. The initial implementation is a typed model
-and CLI/control planning surface:
+Add an optional `overlay` resource kind and reserve `/geth/overlay/1` for an
+Iroh-carried packet overlay. The prototype implementation is a typed model,
+CLI/control surface, persisted local membership record, and explicit opt-in
+TUN/Wintun-style runtime:
 
 - `geth overlay status`
 - `geth overlay plan <name> [--cidr <cidr>]`
 - `geth overlay join <name> --secret <resource-secret> [--cidr <cidr>]`
+- `geth overlay interface-plan <name>`
+- `geth overlay up <name> [--bearer-secret <route-token>] [--mtu <bytes>]`
+- `geth overlay down <name>`
 - `geth overlay leave <name>`
 
-The prototype does not create TUN/Wintun interfaces, assign virtual IPs, or
-route packets. Join/leave are explicit stubs that describe the intended
-resource, capabilities, ALPN, and security boundaries.
+Join creates or reuses `resource:overlay:<name>`, persists local membership in
+`module_state`, assigns a deterministic virtual IP from the overlay CIDR, and
+stores only a BLAKE3 fingerprint of the supplied secret. If the resource already
+has bearer access with `overlay.join`, join requires a matching bearer token.
+This keeps bearer access resource-scoped and does not enroll the caller as a
+trusted node.
+
+`overlay up` creates a real L3 TUN/Wintun-style device through `tun-rs`, assigns
+the local virtual IP, reads IPv4 packets from the device, maps destination
+overlay IPs to imported peer cards, and routes packets over `/geth/overlay/1`.
+The serving daemon requires `overlay.route` before injecting received packets
+into an active overlay runtime. If no runtime is active, received packets are
+stored for inspection with `overlay recv`.
 
 Overlay resources use capabilities:
 
@@ -49,18 +63,15 @@ must not create a second endpoint or non-Iroh transport.
 
 ## Consequences
 
-The CLI can now document and test the intended overlay shape without changing
-host networking. This keeps the prototype safe to run on development machines
-while preserving a clear path toward an iroh-lan-inspired overlay.
+The CLI can now document, persist, test, and activate overlay membership.
+Activating an overlay mutates host networking and can require privileges, so it
+is never automatic daemon startup behavior.
 
 Future work must add:
 
-- persisted overlay membership/resource metadata
-- resource-secret-backed join authorization
-- platform-specific opt-in TUN/Wintun management
-- packet routing over `/geth/overlay/1`
 - peer/IP coordination through trusted resource metadata and untrusted discovery
   candidates
+- stronger platform packaging for Wintun/macOS entitlements where needed
 
 No current code claims VPN-grade isolation, forward secrecy, or automatic host
 network security.

docs/architecture.md

@@ -253,12 +253,26 @@ TUN/Wintun interface are carried over the daemon-owned Iroh endpoint on
 with `overlay.join`, `overlay.route`, and `overlay.admin` capabilities. The
 prototype exposes `geth overlay status`, `geth overlay plan <name>`,
 `geth overlay join <name> --secret <resource-secret>`, and `geth overlay leave
-<name>` as planning/control stubs only. They validate names, CIDRs, resource
-IDs, capabilities, and security notes, but they do not create host network
-interfaces, assign virtual IPs, or route packets yet. Future implementation must
-remain explicitly opt-in because TUN/Wintun setup may need platform-specific
-privileges. Overlay discovery can use mDNS, peer exchange, and resource
-metadata, but discovery remains untrusted and cannot grant overlay access.
+<name>`. Join creates or reuses `resource:overlay:<name>`, persists local
+membership in `module_state`, assigns a deterministic virtual IP from the CIDR,
+and stores only a BLAKE3 fingerprint of the supplied secret. If bearer access
+already exists for that overlay resource, join requires the supplied secret to
+be a bearer token with `overlay.join`; this lets operators create explicit
+resource-scoped overlay invites through `geth secret bearer create`. The
+`geth overlay interface-plan` generates Linux, macOS, or Windows host-interface
+plans for review. `geth overlay up <name>` is the explicit opt-in that creates a
+real L3 TUN/Wintun-style interface through `tun-rs`, assigns the local
+deterministic overlay IP, reads IPv4 packets from the interface, maps
+destination overlay IPs to imported peer cards, and carries those packets over
+the dedicated `/geth/overlay/1` Iroh ALPN. `geth overlay down <name>` stops the
+runtime and drops the device handle. The serving daemon validates the signed
+peer card against the observed EndpointID and requires `overlay.route` on
+`resource:overlay:<name>` before queuing a received packet into the active
+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
+discovery remains untrusted and cannot grant overlay access.
 
 `geth-pipe` currently supports `pipe listen/connect/send/recv` against a
 daemon-lifetime runtime. `geth pipe connect <name> --node <node-id>` sends an

docs/roadmap.md

@@ -584,19 +584,34 @@ Goal: add authorized stream-oriented management workflows over Iroh.
     `overlay.join`, `overlay.route`, and `overlay.admin`.
   - `[x]` Add CLI/control commands for `geth overlay status`, `plan`, `join`,
     and `leave`.
-  - `[x]` Prototype commands make clear that no TUN/Wintun interface is created
-    and no packets are routed yet.
+  - `[x]` Prototype commands make clear that host networking changes require
+    explicit `overlay up`.
   - `[x]` Tests cover overlay validation and control serialization.
-  - `[ ]` Persist overlay network configuration and membership state as
+  - `[x]` Persist overlay network configuration and membership state as
     resource metadata.
-  - `[ ]` Implement resource-authorized overlay join using resource secrets
+  - `[x]` Implement resource-authorized overlay join using resource secrets
     without granting node identity.
-  - `[ ]` Add platform-specific, opt-in TUN/Wintun interface management with
+  - `[x]` Store only a secret fingerprint in overlay membership state.
+  - `[x]` Tests cover persisted overlay join/status/leave and bearer-token
+    enforcement for `overlay.join`.
+  - `[x]` Add platform-specific, opt-in TUN/Wintun interface plans with
     generated-definition tests and no privileged test requirements.
-  - `[ ]` Route IPv4 packets over `/geth/overlay/1` using the shared daemon
+  - `[x]` Route IPv4 packets over `/geth/overlay/1` using the shared daemon
     Iroh endpoint.
+  - `[x]` Validate overlay packet routing with two-node Iroh tests and
+    `overlay.route` authorization checks.
+  - `[x]` Add candidate peer listing from untrusted peer-card metadata.
+  - `[x]` Implement actual TUN/Wintun-style activation as an explicit user
+    opt-in through `geth overlay up/down`.
+  - `[x]` Runtime reads validated IPv4 packets from the TUN device, routes them
+    to imported peer cards by deterministic overlay IP, and injects authorized
+    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
     untrusted discovery candidates.
+  - `[ ]` Add packaged Windows Wintun deployment and macOS entitlement guidance
+    for release builds.
 
 - `[~]` Unix socket forwarding where supported.
   Acceptance criteria: