@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/. 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/ account to submit Pull Requests directly.

Install

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

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

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:

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:

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:

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:

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 Not authenticate, but Knows 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:

# 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

# 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

Click to expand full type definitions

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

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 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.