# @push.rocks/smartvpn

A high-performance VPN solution with a **TypeScript control plane** and a **Rust data plane daemon**. Manage VPN connections with clean, typed APIs while all networking heavy lifting — encryption, tunneling, packet forwarding — 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
npm install @push.rocks/smartvpn
# or
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 + XCha)  │
└──────────────────────────┘            │  ├─ codec (binary framing)    │
                                        │  ├─ keepalive (app-level)     │
                                        │  ├─ tunnel (TUN device)       │
                                        │  ├─ network (NAT/IP pool)     │
                                        │  └─ reconnect (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 | App-level (not WS pings) | Cloudflare drops WS ping frames; app-level pings survive |
| 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';

// Development: spawn the Rust daemon as a child process
const client = new VpnClient({
  transport: { transport: 'stdio' },
});

// Start the daemon bridge
await client.start();

// Connect to a VPN server
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}`);

// Check status
const status = await client.getStatus();
console.log(status); // { state: 'connected', assignedIp: '10.8.0.2', ... }

// Get traffic stats
const stats = await client.getStatistics();
console.log(stats); // { bytesSent, bytesReceived, packetsSent, ... }

// Disconnect
await client.disconnect();
client.stop();
```

### VPN Server

```typescript
import { VpnServer } from '@push.rocks/smartvpn';

const server = new VpnServer({
  transport: { transport: 'stdio' },
});

// Start the daemon and the VPN server
await server.start({
  listenAddr: '0.0.0.0:443',
  privateKey: 'BASE64_PRIVATE_KEY',
  publicKey: 'BASE64_PUBLIC_KEY',
  subnet: '10.8.0.0/24',
  dns: ['1.1.1.1'],
  mtu: 1420,
  enableNat: true,
});

// Generate a Noise keypair
const keypair = await server.generateKeypair();
console.log(keypair); // { publicKey: '...', privateKey: '...' }

// List connected clients
const clients = await server.listClients();
// [{ clientId, assignedIp, connectedSince, bytesSent, bytesReceived }]

// Disconnect a specific client
await server.disconnectClient('some-client-id');

// Get server stats
const stats = await server.getStatistics();
// { bytesSent, bytesReceived, activeClients, totalConnections, ... }

// Stop
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 statistics |
| `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 |
| `disconnectClient(id)` | `Promise<void>` | Kick a client |
| `generateKeypair()` | `Promise<IVpnKeypair>` | Generate Noise NK keypair |
| `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';

// Auto-detect platform
const platform = VpnInstaller.detectPlatform(); // 'linux' | 'macos' | 'windows' | 'unknown'

// Generate systemd unit (Linux)
const unit = VpnInstaller.generateSystemdUnit({
  binaryPath: '/usr/local/bin/smartvpn_daemon',
  socketPath: '/var/run/smartvpn.sock',
  mode: 'server',
});
// unit.content = full systemd .service file
// unit.installPath = '/etc/systemd/system/smartvpn-server.service'

// Generate launchd plist (macOS)
const plist = VpnInstaller.generateLaunchdPlist({
  binaryPath: '/usr/local/bin/smartvpn_daemon',
  socketPath: '/var/run/smartvpn.sock',
  mode: 'client',
});

// Auto-detect and generate
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('status', (status) => { /* IVpnStatus */ });
client.on('error', (err) => { /* { message, code? } */ });
client.on('exit', ({ code, signal }) => { /* daemon exited */ });
client.on('reconnected', () => { /* socket reconnected */ });

server.on('client-connected', (info) => { /* IVpnClientInfo */ });
server.on('client-disconnected', ({ clientId, reason }) => { /* ... */ });
```

## 🔐 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` (Diffie-Hellman with server's static key)
3. Server responds with `e, ee` (Diffie-Hellman 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 |
| `KeepaliveAck` | `0x21` | App-level pong |
| `SessionResume` | `0x30` | Resume a dropped session |
| `SessionResumeOk` | `0x31` | Resume accepted |
| `SessionResumeErr` | `0x32` | Resume rejected |
| `Disconnect` | `0x3F` | Graceful disconnect |

## 🛠️ Rust Daemon CLI

The Rust binary supports several modes:

```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
pnpm build

# Build Rust only (debug)
cd rust && cargo build

# Run Rust tests
cd rust && cargo test

# Run TypeScript tests
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;          // e.g. 'wss://vpn.example.com/tunnel'
  serverPublicKey: string;    // base64-encoded Noise static key
  dns?: string[];
  mtu?: number;               // default: 1420
  keepaliveIntervalSecs?: number; // default: 30
}

// Server config
interface IVpnServerConfig {
  listenAddr: string;         // e.g. '0.0.0.0:443'
  privateKey: string;         // base64 Noise static private key
  publicKey: string;          // base64 Noise static public key
  subnet: string;             // e.g. '10.8.0.0/24'
  tlsCert?: string;
  tlsKey?: string;
  dns?: string[];
  mtu?: number;
  keepaliveIntervalSecs?: number;
  enableNat?: boolean;
}

// 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;
}

interface IVpnServerStatistics extends IVpnStatistics {
  activeClients: number;
  totalConnections: number;
}

interface IVpnClientInfo {
  clientId: string;
  assignedIp: string;
  connectedSince: string;
  bytesSent: number;
  bytesReceived: 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.