hackerrun 0.1.0 → 0.1.2

package/CLAUDE.md

@@ -315,6 +315,140 @@ model PlatformSSHKey {
 - [x] Cloudflare Tunnel + wildcard DNS
 - [x] SSH Certificates + Remove Local Config (temp certs, SSH agent, `uc --connect ssh+cli://`, removed uncloud-sync.ts and ssh.ts)
 
+## CURRENT WORK: WireGuard VPN for IPv4 Users
+
+### Problem: SSH Tunnel Instability
+
+When users on IPv4-only networks run `hackerrun deploy`, the deploy fails with "connection reset by peer" during Docker image push (~250MB). The SSH tunnel through the gateway is unreliable for large data transfers.
+
+**Root cause analysis (see `../uncloud/pkg/client/connector/sshcli.go`):**
+- Uncloud's SSH connector only sets `ConnectTimeout=5`, NO keepalives
+- Large layer transfers take minutes with no packets sent
+- Intermediate NAT/firewalls drop "idle" connections
+- No retry logic for failed layer pushes
+
+**Current data flow (problematic):**
+```
+Local Docker → localhost:PORT → SSH tunnel → Gateway → SSH -W → VM unregistry:5000
+                                    ↑                    ↑
+                              Our tunnel          Uncloud's dialer
+                              (keepalives)        (NO keepalives)
+```
+
+### Solution: WireGuard VPN to Gateway
+
+Give IPv4 users IPv6 connectivity via WireGuard tunnel to gateway, bypassing SSH entirely for data transfer.
+
+**New data flow:**
+```
+User (IPv4) ──WireGuard──► Gateway (IPv4+IPv6) ──IPv6──► App VM unregistry:5000
+                UDP tunnel                        Direct
+                Built-in keepalives               No SSH involved
+```
+
+**Why WireGuard beats SSH tunneling:**
+
+| Aspect | SSH Tunnel | WireGuard |
+|--------|-----------|-----------|
+| Protocol | TCP over TCP (bad) | UDP (good for tunnels) |
+| Keepalives | Manual config, often missing | Built-in (25s default) |
+| Reconnection | Manual | Automatic, stateless |
+| Large transfers | Prone to stalls | Handles well |
+
+### Implementation Plan
+
+**Automatic VPN during deploy** - User doesn't need to know about VPN, it "just works":
+
+```bash
+$ hackerrun deploy
+Detecting network...
+IPv6 not available, establishing VPN tunnel...
+[sudo] password: ****
+✓ VPN connected (IPv6 via gateway)
+
+Deploying 'myapp' to hackerrun...
+# ... deploy proceeds with reliable IPv6 connection ...
+
+✓ App deployed successfully!
+Disconnecting VPN...
+✓ Done
+```
+
+**Flow:**
+1. `hackerrun deploy` starts
+2. CLI tests IPv6 connectivity to app VM (same as current logic)
+3. If IPv6 fails, CLI checks if WireGuard VPN is already up
+4. If not up, CLI auto-establishes VPN:
+   - Check for existing keypair in `~/.config/hackerrun/wg-key` (reuse if exists)
+   - If no keypair, generate one and register with platform
+   - Platform adds peer to gateway, returns config
+   - CLI runs `sudo wg-quick up hackerrun`
+5. CLI now has IPv6, proceeds with deploy (no SSH tunnel needed)
+6. After deploy completes (success or failure), CLI runs `sudo wg-quick down hackerrun`
+
+**Manual commands still available** for debugging/persistent connection:
+
+```bash
+hackerrun vpn status     # Check if VPN is active
+hackerrun vpn connect    # Manual connect (stays up until disconnect)
+hackerrun vpn disconnect # Manual disconnect
+```
+
+**Key files:**
+- `~/.config/hackerrun/wg-private-key` - User's WireGuard private key (generated once, reused)
+- `/etc/wireguard/hackerrun.conf` - WireGuard config (written with sudo)
+
+**Gateway WireGuard config:**
+```ini
+# Existing: NAT64 peers (app VMs connect to gateway for outbound IPv4)
+[Peer]
+PublicKey = <app-vm-key>
+AllowedIPs = 10.210.X.0/24
+
+# New: User VPN peers (users connect to gateway for IPv6 to app VMs)
+[Peer]
+PublicKey = <user-key>
+AllowedIPs = fd00:hackerrun:user:XXXX::/64  # ULA prefix, unique per user
+```
+
+**IPv6 addressing for user VPN:**
+- Use ULA prefix `fd00:hackerrun::/32` for user VPN addresses
+- Each user gets a /64: `fd00:hackerrun:user:<user-id>::/64`
+- Gateway routes these prefixes and can reach app VMs' IPv6
+
+**Platform changes needed:**
+- New model: `VPNPeer` (userId, publicKey, assignedPrefix, createdAt)
+- New endpoints:
+  - `POST /api/vpn/register` - Register public key, get config (idempotent - returns existing if already registered)
+  - `DELETE /api/vpn/unregister` - Remove peer (optional, for cleanup)
+  - `GET /api/vpn/config` - Get current VPN config if registered
+- Gateway management: SSH to gateway to add/remove WireGuard peers
+
+**CLI changes needed:**
+- New lib: `src/lib/vpn.ts` - WireGuard management (keygen, config, up/down)
+- New command: `src/commands/vpn.ts` - Manual VPN commands
+- Modify: `src/lib/uncloud-runner.ts` - Auto-connect VPN when IPv6 unavailable
+- Modify: `src/commands/deploy.ts` - Ensure VPN cleanup on exit
+
+**Sudo handling:**
+- `wg-quick up/down` requires root
+- CLI prompts: "IPv6 not available. Establishing VPN tunnel (requires sudo)..."
+- Uses `sudo wg-quick up hackerrun` - user enters password via terminal
+- Alternative for Linux: Could use `pkexec` for graphical sudo prompt
+
+**Edge cases:**
+- VPN already up from previous deploy → reuse, don't reconnect
+- Deploy fails mid-way → still disconnect VPN in finally block
+- User Ctrl+C during deploy → signal handler disconnects VPN
+- Multiple concurrent deploys → reference count VPN connections
+
+### Alternative Considered: Fix Uncloud's SSH
+
+Could contribute SSH keepalives to uncloud (`ServerAliveInterval=15`), but:
+- Still TCP-over-TCP (suboptimal for tunnels)
+- Doesn't fix fundamental protocol issues
+- WireGuard is better long-term solution
+
 ## Docker Container NAT64
 
 Containers need config to reach IPv4 APIs via NAT64:
@@ -523,6 +657,10 @@ Permissions needed:
 - [ ] BuildKit cache integration
 - [ ] Pre-baked build VM image (optional)
 
+## TODO
+
+- [ ] Package WireGuard into CLI (auto-install like uncloud) - detect OS/distro, show install instructions, offer to run install command with sudo
+
 ## Development
 
 ```bash