66 lines
2.2 KiB
Markdown
66 lines
2.2 KiB
Markdown
|
# ADR 0017: Optional Iroh Overlay Network
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
Accepted for prototype scaffolding.
|
||
|
|
|
||
|
|
## 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 a
|
||
|
|
future Iroh-carried packet overlay. The initial implementation is a typed model
|
||
|
|
and CLI/control planning surface:
|
||
|
|
|
||
|
|
- `geth overlay status`
|
||
|
|
- `geth overlay plan <name> [--cidr <cidr>]`
|
||
|
|
- `geth overlay join <name> --secret <resource-secret> [--cidr <cidr>]`
|
||
|
|
- `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.
|
||
|
|
|
||
|
|
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 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.
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
No current code claims VPN-grade isolation, forward secrecy, or automatic host
|
||
|
|
network security.
|