From d529f58ddc8403f96966cdd0b009ea927bc594c9 Mon Sep 17 00:00:00 2001 From: Fredrik Johansson Date: Tue, 23 Jun 2026 09:57:44 +0200 Subject: [PATCH] Update README: hosting guide, browser vs daemon mode, NPM setup Co-Authored-By: Claude Sonnet 4.6 --- README.md | 376 ++++++++++++++++++++++++++---------------------------- 1 file changed, 183 insertions(+), 193 deletions(-) diff --git a/README.md b/README.md index cbd1693..2f1b987 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ friend-to-friend encrypted mesh networking with chat and file sharing. Written i waste-go/ ├── cmd/ │ ├── daemon/ The peer process — run one on each friend's machine -│ ├── anchor/ WebSocket signaling server — run this on your Hetzner VPS +│ ├── anchor/ WebSocket signaling server — run this on your VPS │ └── tui/ Bubble Tea terminal UI (connects to a running daemon) └── internal/ ├── proto/ All wire types (shared by daemon and anchor) @@ -19,235 +19,225 @@ waste-go/ └── ipc/ Local JSON API (UI talks to daemon here, port 17337) ``` -## Prerequisites +--- -- Go 1.24+ → https://go.dev/dl/ -- VS Code with the Go extension (`golang.go`) +## Hosting on a VPS -On first open VS Code will prompt you to install `gopls`, `dlv`, and `goimports` — accept all of them. +You need two things on the server: the **anchor** (signaling process) and the **web UI** (static files). Both are served through the same domain via Nginx Proxy Manager. -## Getting started +### 1. Build and run the anchor ```bash -# Fetch dependencies -go mod tidy +# On your local machine — cross-compile for Linux +GOOS=linux GOARCH=amd64 go build -o bin/waste-anchor ./cmd/anchor -# Build everything (confirms it compiles) -go build ./... +# Copy to VPS +scp bin/waste-anchor user@your-vps:~/waste-anchor +``` -# Terminal 1 — anchor (required for peers to find each other) +On the VPS, run the anchor and keep it alive (systemd, screen, whatever you use): + +```bash +./waste-anchor -bind 127.0.0.1:8080 +``` + +The anchor listens locally on port 8080 — Nginx Proxy Manager will expose it over TLS. + +### 2. Build and upload the web UI + +```bash +# On your local machine +cd web +npm install +npm run build +# Produces web/dist/ + +# Copy to VPS +rsync -az web/dist/ user@your-vps:/var/www/waste-web/ +``` + +Create a `/var/www/waste-web/config.js` on the VPS (not in git — this is host-specific): + +```js +window.WASTE_CONFIG = { + signalURL: 'wss://your-domain.com/ws', +} +``` + +This tells the browser where to connect for signaling. Without it the join form shows a blank signal server field and the user must fill it in manually. + +### 3. Nginx Proxy Manager setup + +Create one **Proxy Host** for your domain (e.g. `waste.example.com`) with TLS enabled. You need two locations: + +**Location 1 — WebSocket signaling (`/ws`)** +- Location: `/ws` +- Forward hostname/IP: `127.0.0.1` +- Forward port: `8080` +- Enable: WebSockets Support + +**Location 2 — Web UI (catch-all)** +- Location: `/` +- Choose "Serve Static Files" (or point to a local HTTP server serving `/var/www/waste-web`) +- Enable the SPA fallback so unknown paths return `index.html` — this is required for invite links to work + +If NPM doesn't support static file serving directly, run a small static server on a spare port (e.g. `npx serve -s /var/www/waste-web -l 3000`) and proxy `/` to `127.0.0.1:3000`. The key requirements: + +- `/ws` → anchor process (WebSocket, keep-alive) +- `/*` → static file server (SPA fallback: return `index.html` for unknown paths) + +--- + +## How it works: daemon vs browser mode + +There are two ways to use the web UI. + +### Browser mode (for anyone with just a URL) + +When the web UI is served from a non-localhost origin it runs entirely in the browser — no daemon, no install. Crypto (Ed25519/X25519) runs via libsodium compiled to WebAssembly. The identity seed is stored in `localStorage` and persists across sessions. + +A user visits your domain, enters their name and a network name, and joins. Invite links (`waste:…` or `?n=name&a=wss://…`) pre-fill the join form. + +**Identity note:** browser mode uses the master identity directly (same keypair on all networks, compatible with yaw2). The daemon derives a separate keypair per network via HKDF. A browser user and a daemon user on the same network will see each other and can chat — they just appear as different peers even if they're the same person. + +### Daemon mode (for users running the daemon locally) + +`launch-web.sh` starts the Go daemon and the Vite dev server. The web UI connects to the local daemon over WebSocket IPC (`ws://127.0.0.1:17338`). The daemon handles all crypto and connects to the anchor. + +When the web UI is loaded from `localhost`, it defaults to daemon mode. A "Switch to browser mode" button is available in the join screen if the daemon is not running. + +--- + +## Local development + +### Prerequisites + +- Go 1.24+ — https://go.dev/dl/ +- Node.js 20+ + +### Quick start (three peers in one terminal session) + +```bash +# Terminal 1 — local anchor go run ./cmd/anchor -bind 127.0.0.1:17339 # Terminal 2 — peer A go run ./cmd/daemon -alias alice -data-dir /tmp/waste-alice -ipc-port 17337 -anchor ws://127.0.0.1:17339/ws -# Terminal 3 — peer B (or use --join with an invite from peer A) +# Terminal 3 — peer B go run ./cmd/daemon -alias bob -data-dir /tmp/waste-bob -ipc-port 17341 -anchor ws://127.0.0.1:17339/ws ``` -Both peers join the same named network via IPC: +Join both to a network: ```bash -# Join peer A to a network called "friends" echo '{"type":"join_network","network_name":"friends"}' | nc 127.0.0.1 17337 - -# Join peer B to the same network echo '{"type":"join_network","network_name":"friends"}' | nc 127.0.0.1 17341 - -# Subscribe to peer A's events (in a separate terminal) -nc 127.0.0.1 17337 & - -# Send a message from B -echo '{"type":"send_message","room":"general","body":"hello from bob"}' | nc 127.0.0.1 17341 ``` -**On Windows** — use PowerShell's built-in TCP client instead of `nc`: - -```powershell -$c = [System.Net.Sockets.TcpClient]::new('127.0.0.1', 17341) -$w = [System.IO.StreamWriter]::new($c.GetStream()); $w.AutoFlush = $true - -$w.WriteLine('{"type":"join_network","network_name":"friends"}') -$w.WriteLine('{"type":"send_message","room":"general","body":"hello from bob"}') - -# In a separate terminal — subscribe to peer A's events -$r = [System.Net.Sockets.TcpClient]::new('127.0.0.1', 17337) -$reader = [System.IO.StreamReader]::new($r.GetStream()) -while ($true) { $reader.ReadLine() } -``` - -## Deploying the anchor on your Hetzner VPS +### Web UI (daemon mode) ```bash -GOOS=linux GOARCH=amd64 go build -o bin/waste-anchor ./cmd/anchor -scp bin/waste-anchor user@your-vps:~/ +# Requires a running daemon on port 17337 +./launch-web.sh -# On the VPS (also run coturn in STUN-only mode on port 3478) -./waste-anchor -bind 0.0.0.0:17339 +# Or with a custom alias and network: +ALIAS=alice NETWORK=friends ./launch-web.sh ``` -Then start daemons with `-anchor ws://your-vps-ip:17339/ws` and they'll connect via WebRTC -with ICE (STUN-assisted hole punching) through the anchor for signaling. - -## IPC protocol (plain JSON over TCP) - -Everything is newline-delimited JSON. You can test with `nc 127.0.0.1 17337`. - -**Commands you send:** -```jsonc -{"type":"join_network","network_name":"friends"} -{"type":"leave_network"} -{"type":"send_message","room":"general","body":"hi"} -{"type":"send_message","room":"dm:","body":"hey","to":""} -{"type":"get_state"} -{"type":"get_file_list"} // own share dir -{"type":"get_file_list","peer_id":"<64-hex>"} // remote peer's share dir -{"type":"send_file","peer_id":"<64-hex>","path":"notes.txt"} // offer a file from share dir -{"type":"generate_invite"} -``` - -**Events the daemon pushes:** -```jsonc -// Sent immediately on connect and in response to get_state -{"type":"state_snapshot","local_peer":{"id":"<64-hex>","alias":"alice","public_key":"<64-hex>","created_at":"..."},"connected_peers":[...],"rooms":["general"]} - -// Peer lifecycle -{"type":"peer_connected","peer":{"id":"<64-hex>","alias":"bob",...}} -{"type":"session_ready","peer_id":"<64-hex>","nick":"bob"} -{"type":"peer_disconnected","peer_id":"<64-hex>"} - -// Incoming message — mid is a 32-hex dedup token, to is set for DMs -{"type":"message_received","message":{"mid":"<32-hex>","from":"<64-hex>","room":"general","text":"hi","ts":1700000000000}} - -// File events -{"type":"incoming_file","peer_id":"<64-hex>","offer":{"xid":"<32-hex>","name":"notes.txt","size":1024,"sha256":"<64-hex>"}} -{"type":"file_progress","transfer_id":"<32-hex>","bytes_received":65536,"total_bytes":1048576} -{"type":"file_complete","transfer_id":"<32-hex>","path":"/data-dir/downloads-/notes.txt"} -{"type":"file_list","peer_id":"<64-hex>","files":[{"name":"notes.txt","size_bytes":1024}]} - -// Invite generation response -{"type":"invite_generated","invite":"waste:"} - -// Error -{"type":"error","error_message":"..."} -``` - -## Crypto choices - -| Purpose | Algorithm | Notes | -|---|---|---| -| Identity | Ed25519 | Fast, small keys, standard | -| Peer ID | Hex-encoded Ed25519 pubkey | 64 lowercase hex chars (YAW/2 §2) | -| Signaling encryption (2.0) | XSalsa20-Poly1305 (`nacl/box`) | X25519 keys derived from Ed25519 identity (YAW/2 §3) | -| **Signaling encryption (2.1)** | **XSalsa20-Poly1305, ephemeral X25519** | **Per-session keypair; `esk` wiped on close → forward secrecy** | -| Transport | WebRTC DataChannels (DTLS+SCTP) | pion/webrtc — ICE, hole punching included | -| Hashing | SHA-256 | File integrity, network name hashing | - -Replaces WASTE's original Blowfish/PCBC (broken cipher mode) + RSA. - -### Forward-secret signaling (YAW/2.1) - -By default waste-go speaks **YAW/2.1**: before sending an offer each peer generates a fresh -X25519 keypair (`esk`/`epk`), broadcasts its `epk` in a signed `ekey` message, then seals -`offer`/`answer`/`candidate` payloads with the *ephemeral* keys. `esk` is zeroed when the -session ends. Recorded signaling traffic cannot be decrypted even if the long-term Ed25519 -keys later leak. - -A 2.0 peer ignores the `ekey` message (unknown type → silently dropped) and the offerer -falls back to static-key sealing after a 2 s timeout, so **2.1 ↔ 2.0 sessions work** — the -session just isn't forward-secret. The log line `anchor: 2.0 fallback offer to …` flags this. - -> Peer IDs are 64-char lowercase hex (Ed25519 public key). Existing `identity.json` files -> on disk are unaffected — only the over-the-wire representation changed from base64url. - -## Onboarding a new peer - -Alice is already on the network and wants to add Bob. - -**Alice generates an invite** (from the TUI with `Ctrl+I`, or via IPC directly): -```bash -echo '{"type":"generate_invite"}' | nc 127.0.0.1 17337 -# → {"type":"invite_generated","invite":"waste:eyJhbmNob3IiOiJ3czovL..."} -``` - -**Bob starts his daemon using the invite** — the `--join` flag sets the anchor URL and auto-joins the network: -```bash -go run ./cmd/daemon -alias bob -data-dir ~/.waste-bob --join 'waste:eyJhbmNob3IiOiJ3czovL...' -``` - -**Bob opens the TUI** — `--join` also accepts the invite to skip the `-network` flag: -```bash -go run ./cmd/tui --join 'waste:eyJhbmNob3IiOiJ3czovL...' -``` - -The invite encodes the anchor URL and network name as a `waste:` URI. Share it over Signal, email, or any side channel — the anchor never sees plaintext messages, so the invite leaking to a third party only lets them join the same network (which is by design: same network = mutual trust). - -## Terminal UI - -Start the daemon first (see Getting started above), then: - -```bash -go run ./cmd/tui -network friends -``` - -Options: - -| Flag | Default | Description | -|---|---|---| -| `-network` | *(required unless -join)* | Network name to join on startup | -| `-join` | — | `waste:` invite string — sets the network name automatically | -| `-ipc` | `17337` | Daemon IPC port | - -**Layout:** - -``` -╭─ Rooms ──────╮╭─── #general ────────────────╮╭─ Peers ──────╮ -│ ▶ #general ││ 15:04 alice hey everyone ││ ◉ alice (me) │ -│ @ bob ││ 15:04 bob hi alice! ││ ● bob │ -│ ││ 15:05 charlie the mesh works ││ ● charlie │ -╰──────────────╯╰─────────────────────────────╯╰──────────────╯ -╭─────────────────────────────────────────────────────────────╮ -│ Type a message… │ -╰─────────────────────────────────────────────────────────────╯ -``` - -**Key bindings:** `Tab` / `Shift+Tab` — switch rooms · `PgUp` / `PgDn` — scroll · `Enter` — send · `Ctrl+I` — generate invite · `Esc` — close invite overlay · `Ctrl+C` — quit - -## Testing - -A self-contained test script boots anchor + three peers, joins them to a named network, exchanges group messages and DMs, and verifies SQLite persistence: +### Automated test ```bash ./test-network.sh ``` -Data lands at `/tmp/waste-test` (wiped on each run). Inspect after a run: +Boots anchor + three peers, joins them to a network, sends group messages and DMs, verifies SQLite persistence. + +--- + +## Onboarding a new peer + +Alice generates an invite (TUI: `Ctrl+I`, or via IPC): ```bash -# DB name includes the network ID (first 8 hex chars of sha256("yaw2-net:"+name)) -sqlite3 /tmp/waste-test/alice/messages-.db -.headers on -SELECT room, from_peer, text, sent_at FROM messages; -SELECT peer_id, alias, last_seen FROM peers; +echo '{"type":"generate_invite"}' | nc 127.0.0.1 17337 +# → {"type":"invite_generated","invite":"waste:eyJ..."} ``` -There is also a TUI integration test that boots the same three-peer network and -launches the Bubble Tea UI as alice: +Bob joins using the invite: ```bash -./test-tui.sh +go run ./cmd/daemon -alias bob -data-dir ~/.waste-bob --join 'waste:eyJ...' +go run ./cmd/tui --join 'waste:eyJ...' ``` -## Roadmap +The invite encodes the anchor URL and network name. Sharing it only lets the recipient join the same network — the anchor never sees plaintext messages. -- [x] **Crypto layer** — hex peer IDs, `nacl/box` signaling, Ed25519→X25519 key derivation -- [x] **Proto additions** — `mid` dedup field, signaling types, anchor wire types, `hello` message -- [x] **Anchor server** (`cmd/anchor`) — WebSocket signaling server replacing TCP relay -- [x] **WebRTC peer connections** — pion/webrtc DataChannels; ICE hole-punching via STUN -- [x] **Anchor client** (`internal/anchor`) — offer/answer/candidate lifecycle, `nacl/box` sealing -- [x] **IPC updates** — `join_network`/`leave_network`; `session_ready` event; DMs via `to` field -- [x] **Message persistence** — SQLite (`internal/store`); messages and peer alias cache -- [x] **TUI** — Bubble Tea terminal UI (`cmd/tui`); three-pane layout with room switching and DMs -- [x] **File transfer** — chunked binary DataChannel (`f:`); SHA-256 verified; backpressure; auto-accept -- [x] **Forward-secret signaling (YAW/2.1)** — ephemeral X25519 per session; `esk` wiped on close; 2.0 fallback -- [ ] **Native UI** — web frontend with native packaging (Tauri-style) +Invite links also work in the web UI. Share `https://your-domain.com/?invite=waste:eyJ...` and the join form is pre-filled. + +--- + +## Terminal UI + +```bash +go run ./cmd/tui -network friends +``` + +| Flag | Default | Description | +|---|---|---| +| `-network` | *(required unless -join)* | Network name to join on startup | +| `-join` | — | `waste:` invite string | +| `-ipc` | `17337` | Daemon IPC port | + +**Key bindings:** `Tab`/`Shift+Tab` — switch rooms · `PgUp`/`PgDn` — scroll · `Enter` — send · `Ctrl+I` — generate invite · `Esc` — close overlay · `Ctrl+C` — quit + +--- + +## IPC protocol + +Newline-delimited JSON on TCP port 17337 (or WebSocket on 17338). + +**Commands:** +```jsonc +{"type":"join_network","network_name":"friends"} +{"type":"send_message","room":"general","body":"hi"} +{"type":"send_message","to":"<64-hex>","body":"hey"} // DM +{"type":"generate_invite"} +{"type":"get_state"} +{"type":"get_file_list"} +{"type":"get_file_list","peer_id":"<64-hex>"} +{"type":"send_file","peer_id":"<64-hex>","path":"notes.txt"} +{"type":"export_identity","passphrase":"..."} +{"type":"import_identity","passphrase":"...","backup":"..."} +``` + +**Events:** +```jsonc +{"type":"state_snapshot","local_peer":{...},"connected_peers":[...],"master_alias":"alice","master_id":"<64-hex>"} +{"type":"peer_connected","peer":{"id":"<64-hex>","alias":"bob"}} +{"type":"session_ready","peer_id":"<64-hex>","nick":"bob"} +{"type":"peer_disconnected","peer_id":"<64-hex>"} +{"type":"message_received","message":{"mid":"<32-hex>","from":"<64-hex>","room":"general","text":"hi","ts":1700000000000}} +{"type":"network_joined","network_id":"...","network_name":"friends"} +{"type":"invite_generated","invite":"waste:"} +{"type":"incoming_file","peer_id":"<64-hex>","offer":{"xid":"...","name":"notes.txt","size":1024,"sha256":"..."}} +{"type":"file_complete","transfer_id":"...","path":"/downloads/notes.txt"} +{"type":"identity_exported","backup":"..."} +{"type":"error","error_message":"..."} +``` + +--- + +## Crypto + +| Purpose | Algorithm | +|---|---| +| Identity | Ed25519 | +| Signaling (2.0) | XSalsa20-Poly1305, X25519 keys derived from Ed25519 | +| Signaling (2.1) | XSalsa20-Poly1305, ephemeral X25519 per session (forward secrecy) | +| Transport | WebRTC DataChannels (DTLS+SCTP via pion/webrtc) | +| File integrity | SHA-256 | + +### Forward-secret signaling (YAW/2.1) + +Each peer generates a fresh X25519 keypair per session and broadcasts the public half in a signed `ekey` message before sending an offer. The `esk` is zeroed when the session ends. A 2.0 peer ignores `ekey` and the offerer falls back to static-key sealing after 2 s — so 2.1↔2.0 sessions work, just without forward secrecy.