77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# 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.
|