streamflow/docs/VPN_TEST_GUIDE.md

# VPN Fix - Quick Testing Guide

## 1. Rebuild the Container
```bash
cd /home/iulian/projects/tv
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

## 2. Test VPN Connection

### From Web UI:
1. Navigate to **Settings → VPN**
2. Enter your ProtonVPN credentials:
   - Username: `your-protonvpn-username`
   - Password: `your-protonvpn-password`
3. Click **"Save Settings"**
4. Select a country (e.g., United States)
5. Click **"Connect to [Country]"**
6. Wait for "VPN Connected" message
7. Click **"Check IP"** button
8. Verify the results:
   - ✓ Public IP is different from your real IP
   - ✓ Location shows VPN country
   - ✓ ISP contains "Proton" or VPN-related text
   - ✓ DNS servers show `10.2.0.1, 10.2.0.2`
   - ✓ VPN Interface badge shows "Active" (green)

### From Command Line (Inside Container):
```bash
# Enter the container
docker exec -it streamflow bash

# Run the test script
./scripts/test-vpn.sh

# Or manual tests:
# Check VPN interface
ip addr show tun0

# Check your public IP
curl https://api.ipify.org

# Check DNS
cat /etc/resolv.conf

# Check routing
ip route | grep default
```

## 3. API Testing

### Check IP Address
```bash
# Get your auth token first from browser DevTools (Application → Local Storage)
TOKEN="your-jwt-token"

# Check current IP
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:12345/api/vpn/check-ip | jq
```

Expected output:
```json
{
  "publicIp": "X.X.X.X",
  "ipInfo": {
    "ip": "X.X.X.X",
    "city": "...",
    "country": "US",
    "org": "AS... ProtonVPN..."
  },
  "dnsServers": ["10.2.0.1", "10.2.0.2"],
  "vpnInterfaceActive": true
}
```

### Run Full Diagnostics
```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:12345/api/vpn/diagnostics | jq
```

## 4. Expected Behavior

### BEFORE FIX (Broken):
- ❌ Real IP visible after VPN connect
- ❌ DNS servers: 8.8.8.8, 1.1.1.1 (public DNS)
- ❌ ISP shows your real ISP
- ❌ Location shows your real location

### AFTER FIX (Working):
- ✅ VPN IP visible (different from real IP)
- ✅ DNS servers: 10.2.0.1, 10.2.0.2 (ProtonVPN DNS)
- ✅ ISP shows ProtonVPN or similar
- ✅ Location shows VPN country
- ✅ VPN interface (tun0) active
- ✅ Default route goes through tun0

## 5. Troubleshooting

### VPN won't connect:
```bash
# Check backend logs
docker logs streamflow --tail 100

# Look for:
# - "[VPN] Successfully connected!"
# - "Initialization Sequence Completed"
```

### Connected but real IP still shows:
```bash
# Inside container
docker exec -it streamflow bash

# Check if tun0 exists
ip addr show tun0

# Check routing
ip route

# Should show: default via X.X.X.X dev tun0
```

### DNS Leak:
```bash
# Check DNS servers
docker exec -it streamflow cat /etc/resolv.conf

# Should show:
# nameserver 10.2.0.1
# nameserver 10.2.0.2
```

### Can't access container after VPN:
- Ensure ports are still mapped in docker-compose.yml
- Check if firewall is blocking incoming connections
- Try accessing from localhost vs external IP

## 6. Common Issues

| Issue | Solution |
|-------|----------|
| "VPN not configured" error | Save credentials first before connecting |
| Connection timeout | Try different country/server |
| Real IP still visible | Check logs, verify tun0 exists, restart VPN |
| DNS leak detected | Rebuild container to fix DNS script |
| No internet when VPN connected | Check OpenVPN logs, try different server |
| "NET_ADMIN capability" error | Add capabilities to docker-compose.yml |

## 7. Verify Changes Applied

### Check Dockerfile has updated DNS script:
```bash
grep -A 5 "Update DNS when VPN" Dockerfile
```

Should include the for loop to parse `foreign_option_*`

### Check vpn.js has kill switch:
```bash
grep -A 5 "setupFirewall" backend/routes/vpn.js
```

Should include iptables rules

### Check diagnostics utility exists:
```bash
ls -l backend/utils/vpnDiagnostics.js
```

Should exist and be readable

## 8. Before/After Comparison

Test the same command before and after connecting to VPN:

```bash
# Before VPN
curl https://api.ipify.org
# Output: Your real IP (e.g., 93.114.x.x)

# Connect VPN via UI

# After VPN
curl https://api.ipify.org
# Output: VPN IP (e.g., 185.159.x.x)

# Check location
curl https://ipinfo.io/$(curl -s https://api.ipify.org)/json | jq '.country'
# Should show VPN country code
```

## 9. Files Changed

Summary of modified files:
- ✓ `Dockerfile` - Fixed DNS script
- ✓ `backend/routes/vpn.js` - Added kill switch, verification, diagnostics
- ✓ `backend/utils/vpnDiagnostics.js` - NEW diagnostic utility
- ✓ `frontend/src/components/VPNSettings.jsx` - Added Check IP button
- ✓ `scripts/test-vpn.sh` - NEW test script
- ✓ `docs/VPN_TROUBLESHOOTING.md` - NEW troubleshooting guide
- ✓ `VPN_FIX_SUMMARY.md` - NEW summary document

## 10. Success Criteria

VPN is working correctly when:
- [x] VPN connects without errors
- [x] Public IP is VPN IP (not real IP)
- [x] Location matches VPN country
- [x] DNS servers are ProtonVPN DNS
- [x] VPN interface (tun0) is active
- [x] All traffic routes through tun0
- [x] Streaming works through VPN
- [x] No DNS leaks
- [x] Kill switch active (traffic blocked if VPN drops)

---

**Need help?** See `docs/VPN_TROUBLESHOOTING.md` for detailed troubleshooting steps.