eric/geth
Watch
1
0
Fork
You've already forked geth
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Implement opt-in overlay TUN runtime

Browse source
This commit is contained in:
Eric Wendland 2026-05-23 02:08:51 +02:00
commit d9728a326d
15 changed files with 2315 additions and 84 deletions
Download patch file Download diff file Expand all files Collapse all files

39
docs/adr/0017-optional-iroh-overlay-network.md
View file

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