eric/geth
Watch
1
0
Fork
You've already forked geth
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
geth/docs/adr/0017-optional-iroh-overlay-network.md

2.2 KiB
Raw Blame History

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.