546 lines
18 KiB
Markdown
546 lines
18 KiB
Markdown
# @push.rocks/smartvpn
|
||
|
||
A high-performance VPN with a **TypeScript control plane** and a **Rust data plane daemon**. Manage VPN connections with clean, fully-typed APIs while all networking heavy lifting — encryption, tunneling, QoS, rate limiting — runs at native speed in Rust.
|
||
|
||
## Issue Reporting and Security
|
||
|
||
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
|
||
|
||
## Install
|
||
|
||
```bash
|
||
pnpm install @push.rocks/smartvpn
|
||
```
|
||
|
||
## 🏗️ Architecture
|
||
|
||
```
|
||
TypeScript (control plane) Rust (data plane)
|
||
┌──────────────────────────┐ ┌────────────────────────────────────┐
|
||
│ VpnClient / VpnServer │ │ smartvpn_daemon │
|
||
│ └─ VpnBridge │──stdio/──▶ │ ├─ management (JSON IPC) │
|
||
│ └─ RustBridge │ socket │ ├─ transport (WebSocket/TLS) │
|
||
│ (smartrust) │ │ ├─ crypto (Noise NK + XCha20) │
|
||
└──────────────────────────┘ │ ├─ codec (binary framing) │
|
||
│ ├─ keepalive (adaptive state FSM) │
|
||
│ ├─ telemetry (RTT/jitter/loss) │
|
||
│ ├─ qos (classify + priority Q) │
|
||
│ ├─ ratelimit (token bucket) │
|
||
│ ├─ mtu (overhead calc + ICMP) │
|
||
│ ├─ tunnel (TUN device) │
|
||
│ ├─ network (NAT/IP pool) │
|
||
│ └─ reconnect (exp. backoff) │
|
||
└────────────────────────────────────┘
|
||
```
|
||
|
||
**Key design decisions:**
|
||
|
||
| Decision | Choice | Why |
|
||
|----------|--------|-----|
|
||
| Transport | WebSocket over HTTPS | Works through Cloudflare and other terminating proxies |
|
||
| Encryption | Noise NK + XChaCha20-Poly1305 | Strong forward secrecy, large nonce space (no counter needed) |
|
||
| Keepalive | Adaptive app-level pings | Cloudflare drops WS pings; interval adapts to link health (10–60s) |
|
||
| QoS | Packet classification + priority queues | DNS/SSH/ICMP always drain first; bulk flows get deprioritized |
|
||
| Rate limiting | Per-client token bucket | Byte-granular, dynamically reconfigurable via IPC |
|
||
| IPC | JSON lines over stdio / Unix socket | `stdio` for dev, `socket` for production (daemon stays alive) |
|
||
| Binary protocol | `[type:1B][length:4B][payload:NB]` | Minimal overhead, easy to parse at wire speed |
|
||
|
||
## 🚀 Quick Start
|
||
|
||
### VPN Client
|
||
|
||
```typescript
|
||
import { VpnClient } from '@push.rocks/smartvpn';
|
||
|
||
const client = new VpnClient({
|
||
transport: { transport: 'stdio' },
|
||
});
|
||
|
||
await client.start();
|
||
|
||
const { assignedIp } = await client.connect({
|
||
serverUrl: 'wss://vpn.example.com/tunnel',
|
||
serverPublicKey: 'BASE64_SERVER_PUBLIC_KEY',
|
||
dns: ['1.1.1.1', '8.8.8.8'],
|
||
mtu: 1420,
|
||
keepaliveIntervalSecs: 30,
|
||
});
|
||
|
||
console.log(`Connected! Assigned IP: ${assignedIp}`);
|
||
|
||
// Connection quality (adaptive keepalive + telemetry)
|
||
const quality = await client.getConnectionQuality();
|
||
console.log(quality);
|
||
// {
|
||
// srttMs: 42.5, jitterMs: 3.2, minRttMs: 38.0, maxRttMs: 67.0,
|
||
// lossRatio: 0.0, consecutiveTimeouts: 0,
|
||
// linkHealth: 'healthy', currentKeepaliveIntervalSecs: 60
|
||
// }
|
||
|
||
// MTU info
|
||
const mtu = await client.getMtuInfo();
|
||
console.log(mtu);
|
||
// { tunMtu: 1420, effectiveMtu: 1421, linkMtu: 1500, overheadBytes: 79, ... }
|
||
|
||
// Traffic stats (includes quality snapshot)
|
||
const stats = await client.getStatistics();
|
||
|
||
await client.disconnect();
|
||
client.stop();
|
||
```
|
||
|
||
### VPN Server
|
||
|
||
```typescript
|
||
import { VpnServer } from '@push.rocks/smartvpn';
|
||
|
||
const server = new VpnServer({
|
||
transport: { transport: 'stdio' },
|
||
});
|
||
|
||
// Generate a Noise keypair first
|
||
await server.start();
|
||
// If you don't have keys yet:
|
||
const keypair = await server.generateKeypair();
|
||
|
||
// Start the VPN listener (or pass config to start() directly)
|
||
await server.start({
|
||
listenAddr: '0.0.0.0:443',
|
||
privateKey: keypair.privateKey,
|
||
publicKey: keypair.publicKey,
|
||
subnet: '10.8.0.0/24',
|
||
dns: ['1.1.1.1'],
|
||
mtu: 1420,
|
||
enableNat: true,
|
||
// Optional: default rate limit for all new clients
|
||
defaultRateLimitBytesPerSec: 10_000_000, // 10 MB/s
|
||
defaultBurstBytes: 20_000_000, // 20 MB burst
|
||
});
|
||
|
||
// List connected clients
|
||
const clients = await server.listClients();
|
||
|
||
// Per-client rate limiting (live, no reconnect needed)
|
||
await server.setClientRateLimit('client-id', 5_000_000, 10_000_000);
|
||
await server.removeClientRateLimit('client-id'); // unlimited
|
||
|
||
// Per-client telemetry
|
||
const telemetry = await server.getClientTelemetry('client-id');
|
||
console.log(telemetry);
|
||
// {
|
||
// clientId, assignedIp, lastKeepaliveAt, keepalivesReceived,
|
||
// packetsDropped, bytesDropped, bytesReceived, bytesSent,
|
||
// rateLimitBytesPerSec, burstBytes
|
||
// }
|
||
|
||
// Kick a client
|
||
await server.disconnectClient('client-id');
|
||
|
||
await server.stopServer();
|
||
server.stop();
|
||
```
|
||
|
||
### Production: Socket Transport
|
||
|
||
In production, the daemon runs as a system service and you connect over a Unix socket:
|
||
|
||
```typescript
|
||
const client = new VpnClient({
|
||
transport: {
|
||
transport: 'socket',
|
||
socketPath: '/var/run/smartvpn.sock',
|
||
autoReconnect: true,
|
||
reconnectBaseDelayMs: 100,
|
||
reconnectMaxDelayMs: 30000,
|
||
maxReconnectAttempts: 10,
|
||
},
|
||
});
|
||
|
||
await client.start(); // connects to existing daemon (does not spawn)
|
||
```
|
||
|
||
When using socket transport, `client.stop()` closes the socket but **does not kill the daemon** — exactly what you want in production.
|
||
|
||
## 📋 API Reference
|
||
|
||
### `VpnClient`
|
||
|
||
| Method | Returns | Description |
|
||
|--------|---------|-------------|
|
||
| `start()` | `Promise<boolean>` | Start the daemon bridge (spawn or connect) |
|
||
| `connect(config?)` | `Promise<{ assignedIp }>` | Connect to VPN server |
|
||
| `disconnect()` | `Promise<void>` | Disconnect from VPN |
|
||
| `getStatus()` | `Promise<IVpnStatus>` | Current connection state |
|
||
| `getStatistics()` | `Promise<IVpnStatistics>` | Traffic stats + connection quality |
|
||
| `getConnectionQuality()` | `Promise<IVpnConnectionQuality>` | RTT, jitter, loss, link health |
|
||
| `getMtuInfo()` | `Promise<IVpnMtuInfo>` | MTU info and overhead breakdown |
|
||
| `stop()` | `void` | Kill/close the daemon bridge |
|
||
| `running` | `boolean` | Whether bridge is active |
|
||
|
||
### `VpnServer`
|
||
|
||
| Method | Returns | Description |
|
||
|--------|---------|-------------|
|
||
| `start(config?)` | `Promise<void>` | Start daemon + VPN server |
|
||
| `stopServer()` | `Promise<void>` | Stop the VPN server |
|
||
| `getStatus()` | `Promise<IVpnStatus>` | Server connection state |
|
||
| `getStatistics()` | `Promise<IVpnServerStatistics>` | Server stats (includes client counts) |
|
||
| `listClients()` | `Promise<IVpnClientInfo[]>` | Connected clients with QoS stats |
|
||
| `disconnectClient(id)` | `Promise<void>` | Kick a client |
|
||
| `generateKeypair()` | `Promise<IVpnKeypair>` | Generate Noise NK keypair |
|
||
| `setClientRateLimit(id, rate, burst)` | `Promise<void>` | Set per-client rate limit (bytes/sec) |
|
||
| `removeClientRateLimit(id)` | `Promise<void>` | Remove rate limit (unlimited) |
|
||
| `getClientTelemetry(id)` | `Promise<IVpnClientTelemetry>` | Per-client telemetry + drop stats |
|
||
| `stop()` | `void` | Kill/close the daemon bridge |
|
||
|
||
### `VpnConfig`
|
||
|
||
Static utility class for config validation and file I/O:
|
||
|
||
```typescript
|
||
import { VpnConfig } from '@push.rocks/smartvpn';
|
||
|
||
// Validate (throws on invalid)
|
||
VpnConfig.validateClientConfig(config);
|
||
VpnConfig.validateServerConfig(config);
|
||
|
||
// Load/save JSON configs
|
||
const config = await VpnConfig.loadFromFile<IVpnClientConfig>('/etc/smartvpn/client.json');
|
||
await VpnConfig.saveToFile('/etc/smartvpn/client.json', config);
|
||
```
|
||
|
||
### `VpnInstaller`
|
||
|
||
Generate system service units for the daemon:
|
||
|
||
```typescript
|
||
import { VpnInstaller } from '@push.rocks/smartvpn';
|
||
|
||
const platform = VpnInstaller.detectPlatform(); // 'linux' | 'macos' | 'windows' | 'unknown'
|
||
|
||
// Linux (systemd)
|
||
const unit = VpnInstaller.generateSystemdUnit({
|
||
binaryPath: '/usr/local/bin/smartvpn_daemon',
|
||
socketPath: '/var/run/smartvpn.sock',
|
||
mode: 'server',
|
||
});
|
||
|
||
// macOS (launchd)
|
||
const plist = VpnInstaller.generateLaunchdPlist({
|
||
binaryPath: '/usr/local/bin/smartvpn_daemon',
|
||
socketPath: '/var/run/smartvpn.sock',
|
||
mode: 'client',
|
||
});
|
||
|
||
// Auto-detect platform
|
||
const serviceUnit = VpnInstaller.generateServiceUnit({
|
||
binaryPath: '/usr/local/bin/smartvpn_daemon',
|
||
socketPath: '/var/run/smartvpn.sock',
|
||
mode: 'server',
|
||
});
|
||
```
|
||
|
||
### Events
|
||
|
||
Both `VpnClient` and `VpnServer` extend `EventEmitter`:
|
||
|
||
```typescript
|
||
client.on('exit', ({ code, signal }) => { /* daemon exited */ });
|
||
client.on('reconnected', () => { /* socket reconnected */ });
|
||
|
||
server.on('client-connected', (info) => { /* IVpnClientInfo */ });
|
||
server.on('client-disconnected', ({ clientId, reason }) => { /* ... */ });
|
||
```
|
||
|
||
## 📊 QoS System
|
||
|
||
The Rust daemon includes a full QoS stack that operates on decrypted IP packets:
|
||
|
||
### Adaptive Keepalive
|
||
|
||
The keepalive system automatically adjusts its interval based on connection quality:
|
||
|
||
| Link Health | Keepalive Interval | Triggered When |
|
||
|-------------|-------------------|----------------|
|
||
| 🟢 Healthy | 60s | Jitter < 30ms, loss < 2%, no timeouts |
|
||
| 🟡 Degraded | 30s | Jitter > 50ms, loss > 5%, or 1+ timeout |
|
||
| 🔴 Critical | 10s | Loss > 20% or 2+ consecutive timeouts |
|
||
|
||
State transitions include hysteresis (3 consecutive good checks to upgrade, 2 to recover) to prevent flapping. Dead peer detection fires after 3 consecutive timeouts in Critical state.
|
||
|
||
### Packet Classification
|
||
|
||
IP packets are classified into three priority levels by inspecting headers (no deep packet inspection):
|
||
|
||
| Priority | Traffic |
|
||
|----------|---------|
|
||
| **High** | ICMP, DNS (port 53), SSH (port 22), small packets (< 128 bytes) |
|
||
| **Normal** | Everything else |
|
||
| **Low** | Bulk flows exceeding 1 MB within a 60s window |
|
||
|
||
Priority channels drain with biased `tokio::select!` — high-priority packets always go first.
|
||
|
||
### Smart Packet Dropping
|
||
|
||
Under backpressure, packets are dropped intelligently:
|
||
|
||
1. **Low** queue full → drop silently
|
||
2. **Normal** queue full → drop
|
||
3. **High** queue full → wait 5ms, then drop as last resort
|
||
|
||
Drop statistics are tracked per priority level and exposed via telemetry.
|
||
|
||
### Per-Client Rate Limiting
|
||
|
||
Token bucket algorithm with byte granularity:
|
||
|
||
```typescript
|
||
// Set: 10 MB/s sustained, 20 MB burst
|
||
await server.setClientRateLimit('client-id', 10_000_000, 20_000_000);
|
||
|
||
// Check drops via telemetry
|
||
const t = await server.getClientTelemetry('client-id');
|
||
console.log(`Dropped: ${t.packetsDropped} packets, ${t.bytesDropped} bytes`);
|
||
|
||
// Remove limit
|
||
await server.removeClientRateLimit('client-id');
|
||
```
|
||
|
||
Rate limits can be changed live without disconnecting the client.
|
||
|
||
### Path MTU
|
||
|
||
Tunnel overhead is calculated precisely:
|
||
|
||
| Layer | Bytes |
|
||
|-------|-------|
|
||
| IP header | 20 |
|
||
| TCP header (with timestamps) | 32 |
|
||
| WebSocket framing | 6 |
|
||
| VPN frame header | 5 |
|
||
| Noise AEAD tag | 16 |
|
||
| **Total overhead** | **79** |
|
||
|
||
For a standard 1500-byte Ethernet link, effective TUN MTU = **1421 bytes**. The default TUN MTU of 1420 is conservative and correct. Oversized packets get an ICMP "Fragmentation Needed" (Type 3, Code 4) written back into the TUN, so the source TCP adjusts its MSS automatically.
|
||
|
||
## 🔐 Security Model
|
||
|
||
The VPN uses a **Noise NK** handshake pattern:
|
||
|
||
1. **NK** = client does **N**ot authenticate, but **K**nows the server's static public key
|
||
2. The client generates an ephemeral keypair, performs `e, es` (DH with server's static key)
|
||
3. Server responds with `e, ee` (DH with both ephemeral keys)
|
||
4. Result: forward-secret transport keys derived from both DH operations
|
||
|
||
Post-handshake, all IP packets are encrypted with **XChaCha20-Poly1305**:
|
||
- 24-byte random nonces (no counter synchronization needed)
|
||
- 16-byte authentication tags
|
||
- Wire format: `[nonce:24B][ciphertext:var][tag:16B]`
|
||
|
||
## 📦 Binary Protocol
|
||
|
||
Inside the WebSocket tunnel, packets use a simple binary framing:
|
||
|
||
```
|
||
┌──────────┬──────────┬────────────────────┐
|
||
│ Type (1B)│ Len (4B) │ Payload (variable) │
|
||
└──────────┴──────────┴────────────────────┘
|
||
```
|
||
|
||
| Type | Value | Description |
|
||
|------|-------|-------------|
|
||
| `HandshakeInit` | `0x01` | Client → Server handshake |
|
||
| `HandshakeResp` | `0x02` | Server → Client handshake |
|
||
| `IpPacket` | `0x10` | Encrypted IP packet |
|
||
| `Keepalive` | `0x20` | App-level ping (8-byte timestamp payload) |
|
||
| `KeepaliveAck` | `0x21` | App-level pong (echoes timestamp for RTT) |
|
||
| `SessionResume` | `0x30` | Resume a dropped session |
|
||
| `SessionResumeOk` | `0x31` | Resume accepted |
|
||
| `SessionResumeErr` | `0x32` | Resume rejected |
|
||
| `Disconnect` | `0x3F` | Graceful disconnect |
|
||
|
||
## 🛠️ Rust Daemon CLI
|
||
|
||
```bash
|
||
# Development: stdio management (JSON lines on stdin/stdout)
|
||
smartvpn_daemon --management --mode client
|
||
smartvpn_daemon --management --mode server
|
||
|
||
# Production: Unix socket management
|
||
smartvpn_daemon --management-socket /var/run/smartvpn.sock --mode server
|
||
|
||
# Generate a Noise keypair
|
||
smartvpn_daemon --generate-keypair
|
||
```
|
||
|
||
## 🔧 Building from Source
|
||
|
||
```bash
|
||
# Install dependencies
|
||
pnpm install
|
||
|
||
# Build TypeScript + cross-compile Rust (amd64 + arm64)
|
||
pnpm build
|
||
|
||
# Build Rust only (debug)
|
||
cd rust && cargo build
|
||
|
||
# Run all tests (71 Rust + 32 TypeScript)
|
||
cd rust && cargo test
|
||
pnpm test
|
||
```
|
||
|
||
## TypeScript Interfaces
|
||
|
||
<details>
|
||
<summary>Click to expand full type definitions</summary>
|
||
|
||
```typescript
|
||
// Transport options
|
||
type TVpnTransportOptions =
|
||
| { transport: 'stdio' }
|
||
| {
|
||
transport: 'socket';
|
||
socketPath: string;
|
||
autoReconnect?: boolean;
|
||
reconnectBaseDelayMs?: number;
|
||
reconnectMaxDelayMs?: number;
|
||
maxReconnectAttempts?: number;
|
||
};
|
||
|
||
// Client config
|
||
interface IVpnClientConfig {
|
||
serverUrl: string;
|
||
serverPublicKey: string;
|
||
dns?: string[];
|
||
mtu?: number;
|
||
keepaliveIntervalSecs?: number;
|
||
}
|
||
|
||
// Server config
|
||
interface IVpnServerConfig {
|
||
listenAddr: string;
|
||
privateKey: string;
|
||
publicKey: string;
|
||
subnet: string;
|
||
tlsCert?: string;
|
||
tlsKey?: string;
|
||
dns?: string[];
|
||
mtu?: number;
|
||
keepaliveIntervalSecs?: number;
|
||
enableNat?: boolean;
|
||
defaultRateLimitBytesPerSec?: number;
|
||
defaultBurstBytes?: number;
|
||
}
|
||
|
||
// Status
|
||
type TVpnConnectionState = 'disconnected' | 'connecting' | 'handshaking'
|
||
| 'connected' | 'reconnecting' | 'error';
|
||
|
||
interface IVpnStatus {
|
||
state: TVpnConnectionState;
|
||
assignedIp?: string;
|
||
serverAddr?: string;
|
||
connectedSince?: string;
|
||
lastError?: string;
|
||
}
|
||
|
||
// Statistics
|
||
interface IVpnStatistics {
|
||
bytesSent: number;
|
||
bytesReceived: number;
|
||
packetsSent: number;
|
||
packetsReceived: number;
|
||
keepalivesSent: number;
|
||
keepalivesReceived: number;
|
||
uptimeSeconds: number;
|
||
quality?: IVpnConnectionQuality;
|
||
}
|
||
|
||
interface IVpnServerStatistics extends IVpnStatistics {
|
||
activeClients: number;
|
||
totalConnections: number;
|
||
}
|
||
|
||
// Connection quality (QoS)
|
||
type TVpnLinkHealth = 'healthy' | 'degraded' | 'critical';
|
||
|
||
interface IVpnConnectionQuality {
|
||
srttMs: number;
|
||
jitterMs: number;
|
||
minRttMs: number;
|
||
maxRttMs: number;
|
||
lossRatio: number;
|
||
consecutiveTimeouts: number;
|
||
linkHealth: TVpnLinkHealth;
|
||
currentKeepaliveIntervalSecs: number;
|
||
}
|
||
|
||
// MTU info
|
||
interface IVpnMtuInfo {
|
||
tunMtu: number;
|
||
effectiveMtu: number;
|
||
linkMtu: number;
|
||
overheadBytes: number;
|
||
oversizedPacketsDropped: number;
|
||
icmpTooBigSent: number;
|
||
}
|
||
|
||
// Client info (with QoS fields)
|
||
interface IVpnClientInfo {
|
||
clientId: string;
|
||
assignedIp: string;
|
||
connectedSince: string;
|
||
bytesSent: number;
|
||
bytesReceived: number;
|
||
packetsDropped: number;
|
||
bytesDropped: number;
|
||
lastKeepaliveAt?: string;
|
||
keepalivesReceived: number;
|
||
rateLimitBytesPerSec?: number;
|
||
burstBytes?: number;
|
||
}
|
||
|
||
// Per-client telemetry
|
||
interface IVpnClientTelemetry {
|
||
clientId: string;
|
||
assignedIp: string;
|
||
lastKeepaliveAt?: string;
|
||
keepalivesReceived: number;
|
||
packetsDropped: number;
|
||
bytesDropped: number;
|
||
bytesReceived: number;
|
||
bytesSent: number;
|
||
rateLimitBytesPerSec?: number;
|
||
burstBytes?: number;
|
||
}
|
||
|
||
interface IVpnKeypair {
|
||
publicKey: string;
|
||
privateKey: string;
|
||
}
|
||
```
|
||
|
||
</details>
|
||
|
||
## License and Legal Information
|
||
|
||
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
|
||
|
||
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
||
|
||
### Trademarks
|
||
|
||
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
|
||
|
||
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
|
||
|
||
### Company Information
|
||
|
||
Task Venture Capital GmbH
|
||
Registered at District Court Bremen HRB 35230 HB, Germany
|
||
|
||
For any legal inquiries or further information, please contact us via email at hello@task.vc.
|
||
|
||
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
|