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

# ADR 0017: Optional Iroh Overlay Network

## Status

Accepted for prototype implementation.

## Context

`iroh-lan` demonstrates a useful pattern for a private packet overlay carried by
Iroh connections. That model is attractive for geth because it could make local
services, scripts, and devices reachable through stable mesh resources without
exposing host networking directly to untrusted discovery.

Geth must keep its core invariants:

- all remote geth communication is over Iroh
- the daemon owns the Iroh endpoint
- discovery is untrusted
- resource authorization gates access
- SSH is not a geth transport

Packet overlays also carry host-network risk. TUN/Wintun setup is
platform-specific, may require privileges, and can route arbitrary traffic if
misconfigured.

## Decision

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>`

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:

- `overlay.join`
- `overlay.route`
- `overlay.admin`

Future overlay implementation must use the shared daemon-owned Iroh endpoint and
must not create a second endpoint or non-Iroh transport.

## Consequences

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:

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