diff --git a/docs/roadmap.md b/docs/roadmap.md index d93dd1e..97e38c7 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -9,6 +9,87 @@ Status markers: - `[~]` In progress - `[x]` Done +## Long-Term Goal: Distributed Homelab Overlay + +Goal: evolve geth into a distributed, fault-tolerant homelab overlay runtime in +the spirit of NetBird/Tailscale, while preserving geth's core invariants: Iroh +is the only remote geth transport, discovery is untrusted, SSH keys are trust +anchors rather than transport keys, and authorization remains resource-scoped +and capability-based. + +This is a long-term product direction, not a claim about the current prototype. +The target is a usable personal/family/lab mesh that can survive intermittent +nodes, changing network locations, partial discovery failures, and offline +admin devices without depending on one always-online coordination server. + +- `[ ]` Distributed overlay control plane. + Acceptance criteria: + - `[ ]` Overlay membership, virtual IP assignment, route advertisements, + node capabilities, and revocations are represented as signed replicated + resource data. + - `[ ]` The control plane has documented conflict semantics for concurrent + joins, renames, IP conflicts, route changes, and revocations. + - `[ ]` Nodes can converge from static sigchain publication, peer live-sync, + and Iroh-connected peers without requiring a central coordinator. + - `[ ]` Stale or partitioned nodes are detectable in `geth overlay status` + and `geth sync status --json`. + +- `[ ]` Fault-tolerant peer and path selection. + Acceptance criteria: + - `[ ]` Nodes maintain multiple candidate addresses from Iroh relays, local + discovery, imported peer cards, and static publication. + - `[ ]` Packet routing retries healthy paths and backs off failed paths + without granting trust from discovery metadata. + - `[ ]` Relay use, direct connections, LAN discovery, and path failures are + visible in human and JSON status output. + - `[ ]` Integration tests simulate peer restart, address rotation, relay-only + connectivity, and temporary peer unavailability. + +- `[ ]` Production overlay routing features. + Acceptance criteria: + - `[ ]` Overlay supports stable virtual IPv4 addressing with collision + detection and operator-visible remediation. + - `[ ]` Subnet-router resources can advertise selected LAN routes with + explicit capabilities and revocation behavior. + - `[ ]` Exit-node routing is modeled as an explicit resource and requires + dedicated capabilities. + - `[ ]` MTU selection, packet size limits, and fragmentation/drop behavior + are documented and tested. + +- `[ ]` Homelab DNS and service discovery. + Acceptance criteria: + - `[ ]` Nodes can publish signed names and service records into replicated + resource metadata. + - `[ ]` A local resolver or hosts-file integration can expose overlay names + without requiring global DNS changes. + - `[ ]` DNS/service data is separated from untrusted LAN discovery and can be + explained through auth/keychain state. + - `[ ]` Revoked nodes and stale records disappear from the trusted view after + verified sync. + +- `[ ]` Cross-platform operational polish. + Acceptance criteria: + - `[ ]` Linux TUN setup documents required user-service permissions, + `CAP_NET_ADMIN`, and distro-specific recovery steps. + - `[ ]` macOS release builds document required entitlements and user-service + launch behavior. + - `[ ]` Windows builds package or clearly locate Wintun and install a + per-user daemon task. + - `[ ]` `geth guide overlay` contains an end-to-end two-machine smoke test + for each supported platform class. + +- `[ ]` Security and auditability bar for overlay use. + Acceptance criteria: + - `[ ]` Every packet-forwarding, subnet-routing, exit-node, DNS, and service + discovery operation has an explicit resource/capability check. + - `[ ]` `auth explain` can answer why a node may or may not route packets, + advertise a subnet, use an exit node, or publish a service name. + - `[ ]` Bearer secrets can invite limited overlay access without granting + trust graph mutation rights. + - `[ ]` The docs state what properties geth provides today and avoid claims + equivalent to Keyhive/BeeKEM, WireGuard, NetBird, or Tailscale unless those + properties are actually implemented and tested. + ## Prototype Viability Closure Plan These are the remaining gaps that must close before the prototype is a smooth