Framework/Handover — /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 =[REDACTED]

go.mod

module splicevpn

go 1.22

go list

splicevpn/agent
splicevpn/coordinator
splicevpn/linkmanager
splicevpn/proto