/opt/splicevpn/README.md
# SpliceVPN
Peer-to-peer, multi-endpoint mesh VPN. Run the agent on each machine, answer a few
questions, and every endpoint is connected to every other endpoint over an encrypted
overlay — with a coordinator/relay you supply as the always-available fallback.
> **Status: MVP foundation.** This is a working control-plane + mesh bring-up built on
> WireGuard. It is *not* production-hardened. See "Security" and "Roadmap" below before
> putting it anywhere real.
---
## Why it's built this way
The product promises encryption and tunnelling. **We do not implement our own crypto or
tunnel transport** — that is the single most dangerous thing a VPN can do. Instead
SpliceVPN rides on **WireGuard**: audited Noise-protocol crypto, a fast in-kernel data
plane (userspace fallback via `wireguard-go`), and roaming endpoints. Everything
SpliceVPN adds is *orchestration around* WireGuard — which is where the actual product
value (mesh, zero-config, supplied relay, bonding) lives.
```
┌──────────────────────────────────────────────┐
│ COORDINATOR (you supply) │
│ • node registry + overlay-IP assignment │
│ • hands every node the full mesh peer list │
│ • observes public src ip:port (STUN-lite) │
│ • runs a WireGuard HUB = relay fallback │
└───────────────▲───────────────▲────────────────┘
│ register/poll │
┌──────────┘ └──────────┐
│ │
┌────────┴────────┐ ┌────────┴────────┐
│ AGENT A │ ◄── direct WG ──► │ AGENT B │
│ host or /24 net │ (falls back to │ host or /24 net │
└────────┬────────┘ hub if blocked) └────────┬────────┘
│ │
└──────────────► AGENT C ◄───────────────┘
full mesh: every node peers with every node
```
## Feature → implementation map
| Promise on the site | Mechanism | State |
|---|---|---|
| Encrypted point-to-point tunnel | WireGuard peer link | MVP |
| Endpoint = a host **or** a whole network | advertised subnets → WireGuard `AllowedIPs` + routes | MVP |
| **Many endpoints all connected (mesh)** | coordinator distributes full peer list; agent configures a peer per node | MVP |
| Always finds a path (direct → … → relay) | direct mesh via discovered endpoints + coordinator-observed public mapping (STUN-lite); catch-all hub peer wired in | MVP = direct + public-mapping assist; **UDP hole-punching and DERP-style relay-on-failure = Phase 2** |
| Zero-config | `agent` wizard: coordinator URL + join key + host/subnet + profile | MVP |
| Bond multiple internet links | `linkmanager` multipath layer | **Phase 2** |
| Any port, UDP/TCP, multi-port | transport wrapper + WG-over-TCP/443 via relay | **Phase 2** |
## Layout
```
splicevpn/
proto/ shared wire types (register, peer, mesh snapshot)
coordinator/ the registry + relay-hub control plane (HTTP API)
agent/ per-endpoint client: keygen, register, render+apply WireGuard mesh
linkmanager/ Phase-2 bonding interface (stub + design notes)
```
## Build
Requires Go 1.22+, and on agents the WireGuard tools (`wg`, `wg-quick`).
```
cd splicevpn
go mod tidy
go build -o bin/splice-coordinator ./coordinator
go build -o bin/splice-agent ./agent
```
## Run
**Coordinator** (on a box with a public/LAN-reachable IP — this is your "supplied gateway"):
```
SPLICE_JOIN_KEY=change-me \
./bin/splice-coordinator --listen :7777 --hub-endpoint <public-ip>:51820 --overlay 100.96.0.0/16
```
**Agent** (on each endpoint; run as root so it can bring up the interface):
```
sudo ./bin/splice-agent
# wizard asks: coordinator URL, join key, "this host only or advertise a subnet?",
# and profile (speed / resilience / both), then brings up wg0 meshed with all peers.
```
Add more endpoints by running the agent on them with the same coordinator + join key —
they auto-join the mesh and every existing node learns about them on its next poll.
## Security (read this)
- MVP **only**. No auth hardening beyond a shared join key, no rotation, no rate limits,
no audit logging, TOFU on the coordinator. Do not expose the coordinator to the
open internet as-is.
- Crypto is delegated to WireGuard. Do not "improve" it.
[REDACTED SECRET-LIKE LINE]
- Before any real use: pin coordinator identity, add per-node auth + revocation,
lock down the relay, and get the design reviewed.
## Roadmap
1. **NAT hole-punching + relay-on-failure** — UDP candidate exchange via the coordinator
(STUN/ICE-style) so most pairs go direct; for pairs that still can't connect, a
DERP-style userspace relay through the hub forwards their traffic. (Vanilla WireGuard
can't auto-fail-over between peers on its own — this needs the userspace decision layer.)
2. **Link bonding** (`linkmanager`) — bring up one WireGuard tunnel per WAN, then a
multipath scheduler (round-robin / lowest-latency / redundant) across them.
3. **Any-port / TCP transport** — relay accepts WireGuard-over-TCP/WebSocket on 443 for
networks that block UDP; agent probes and adapts.
4. Web dashboard + ACLs; key rotation; packaged installers for the true one-click story.