/opt/splicevpn/HANDOVER.md
# SpliceVPN — Handover (2026-06-09)
## What it is
Go mesh-VPN over WireGuard. Marketing+download site at https://splicevpn.com.au.
Coordinator (control plane) + agent (client) + WireGuard hub (relay) all on jfmsrv01.
## Infra
- jfmsrv01: LAN 192.168.100.197 / WAN 103.138.201.66. nginx 1.24, certbot, Go 1.22.
Also runs GoSeek (root shell, :8090, LAN-ONLY — never forward).
- Firewall (Arista/Untangle): TCP 80,443 -> .197 (rule#49). UDP 51820 -> .197 (hub).
Lets-Encrypt rules #50/#51 stay DISABLED.
- Build VM: 192.168.100.110 (ssh builder). Server compiles directly; deploy via copy-paste.
## Layout
- Site docroot: /var/www/sites/splice/ (index.html, help.html, downloads)
- Go source: /opt/splice-src/ (module splicevpn; coordinator/ agent/)
- Binaries: /opt/splicevpn/bin/ (splice-coordinator, splice-agent)
- Client downloads in docroot: splice-agent, splice-agent.exe, splicevpn.tar.gz,
splicevpn-windows-amd64.zip, install-splicevpn.ps1, Install-SpliceVPN.bat
## Architecture (hub-and-spoke relay)
- Each distinct join_key = isolated network, own /16 from 100.64.0.0/10 (.1=hub, hosts .2+).
- Coordinator HTTP on 127.0.0.1:7777, public via nginx /api/ proxy.
/register /poll?key=&pubkey= /healthz. In-memory; 90s reap. Subnet-collision check.
Manages hub peers: `wg set wgsplice peer <pub> allowed-ips <ip>/32` on join, remove on reap.
Flags: --listen 0.0.0.0:7777 --hub-iface wgsplice --hub-endpoint 103.138.201.66:51820
systemd: splice-coordinator.service
- Hub: WG iface wgsplice, 100.64.0.1/10, ListenPort 51820, ip_forward=1.
/etc/wireguard/wgsplice.{key,conf}. systemd: wg-quick@wgsplice. ip_forward in sysctl.conf.
pubkey G5PLHNesi2nZe1zJf4q52O+UWEnQMgcyMToVnyF6nwY=
- Agent: pure-Go X25519 keygen. Peers ONLY with hub (AllowedIPs=network /16,
Endpoint=103.138.201.66:51820, keepalive 25). Re-registers on 404. Change-detect apply.
apply_unix.go=/etc/wireguard+wg-quick; apply_windows.go=%ProgramData%\SpliceVPN+wireguard.exe.
Flags: -coordinator(def https://splicevpn.com.au/api) -name -key -generate -advertise -iface(splice0) -port.
## Status: relay COMPLETE server-side, both binaries rebuilt & deployed.
## NOT yet done
- Two-machine end-to-end traffic test (ping over 100.64.x.x via hub).
- Site copy still says "never detours through someone's cloud" — UNTRUE now; soften to
"relayed through your own SpliceVPN hub".
- Refresh splicevpn-windows-amd64.zip + tarball (contain older agent).
## Known limits (MVP)
- Relay decrypts/sees inter-client traffic (not E2E/P2P). Direct hole-punching = future.
- Network isolation is soft (distinct /16 + client config; single hub iface). Per-net ifaces = hardening.
- Coordinator state in-memory: restart loses peers (agents self-heal via 404 re-register);
stale hub peers can linger until reap/next coordinator add.
- Auth = shared per-network key only.
- Linux clients need `apt install wireguard` (installer auto-handles Windows only).
## Security (done earlier)
- 000-default-deny vhost: bare-IP/unknown host -> 444. Backup /root/nginx-backup-2026-06-09.
- TODO: [REDACTED]
## Test
apt install -y wireguard # linux clients
sudo ./splice-agent -generate # box 1, prints key
sudo ./splice-agent -key spl_… # box 2
wg show wgsplice # server: both peers listed -> ping overlay IPs