@push.rocks/smartvpn 1.0.3

package/readme.md

@@ -0,0 +1,410 @@
+# @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.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@push.rocks/smartvpn',
+  version: '1.0.3',
+  description: 'A VPN solution with TypeScript control plane and Rust data plane daemon'
+}

package/ts/index.ts

@@ -0,0 +1,6 @@
+export * from './smartvpn.interfaces.js';
+export { VpnBridge } from './smartvpn.classes.vpnbridge.js';
+export { VpnClient } from './smartvpn.classes.vpnclient.js';
+export { VpnServer } from './smartvpn.classes.vpnserver.js';
+export { VpnConfig } from './smartvpn.classes.vpnconfig.js';
+export { VpnInstaller } from './smartvpn.classes.vpninstaller.js';

package/ts/smartvpn.classes.vpnbridge.ts

@@ -0,0 +1,152 @@
+import * as plugins from './smartvpn.plugins.js';
+import * as paths from './smartvpn.paths.js';
+import type {
+  TVpnTransportOptions,
+  IVpnTransportSocket,
+} from './smartvpn.interfaces.js';
+import type { TCommandMap } from '@push.rocks/smartrust';
+
+/**
+ * Get the package root directory.
+ */
+function getPackageRoot(): string {
+  const thisDir = plugins.path.dirname(plugins.url.fileURLToPath(import.meta.url));
+  return plugins.path.resolve(thisDir, '..');
+}
+
+/**
+ * Map Node.js platform/arch to tsrust's platform suffix.
+ */
+function getTsrustPlatformSuffix(): string | null {
+  const archMap: Record<string, string> = { x64: 'amd64', arm64: 'arm64' };
+  const osMap: Record<string, string> = { linux: 'linux', darwin: 'macos' };
+  const os = osMap[process.platform];
+  const arch = archMap[process.arch];
+  if (os && arch) {
+    return `${os}_${arch}`;
+  }
+  return null;
+}
+
+/**
+ * Build local search paths for the smartvpn daemon binary.
+ */
+function buildLocalPaths(binaryName: string): string[] {
+  const packageRoot = getPackageRoot();
+  const suffix = getTsrustPlatformSuffix();
+  const paths: string[] = [];
+
+  // dist_rust/ (tsrust cross-compiled output)
+  if (suffix) {
+    paths.push(plugins.path.join(packageRoot, 'dist_rust', `${binaryName}_${suffix}`));
+  }
+  paths.push(plugins.path.join(packageRoot, 'dist_rust', binaryName));
+
+  // Local dev build paths
+  paths.push(plugins.path.resolve(process.cwd(), 'rust', 'target', 'release', binaryName));
+  paths.push(plugins.path.resolve(process.cwd(), 'rust', 'target', 'debug', binaryName));
+
+  return paths;
+}
+
+/**
+ * Shared bridge wrapper around smartrust RustBridge.
+ * Supports stdio mode (dev: spawn child process) and socket mode (production: connect to running daemon).
+ */
+export class VpnBridge<TCommands extends TCommandMap> extends plugins.events.EventEmitter {
+  private bridge: plugins.smartrust.RustBridge<TCommands>;
+  private transportOptions: TVpnTransportOptions;
+  private mode: 'client' | 'server';
+
+  constructor(options: {
+    transport: TVpnTransportOptions;
+    mode: 'client' | 'server';
+    binaryName?: string;
+  }) {
+    super();
+
+    const binaryName = options.binaryName || 'smartvpn_daemon';
+    this.transportOptions = options.transport;
+    this.mode = options.mode;
+
+    this.bridge = new plugins.smartrust.RustBridge<TCommands>({
+      binaryName,
+      envVarName: 'SMARTVPN_RUST_BINARY',
+      platformPackagePrefix: '@push.rocks/smartvpn',
+      localPaths: buildLocalPaths(binaryName),
+      cliArgs: ['--management', '--mode', this.mode],
+      maxPayloadSize: 10 * 1024 * 1024, // 10 MB
+    });
+
+    // Forward events from inner bridge
+    this.bridge.on('exit', (code: number | null, signal: string | null) => {
+      this.emit('exit', code, signal);
+    });
+    this.bridge.on('reconnected', () => {
+      this.emit('reconnected');
+    });
+
+    // Forward management events from the daemon
+    // smartrust emits 'management:<eventName>' for unsolicited events
+    this.bridge.on('management:status', (data: any) => {
+      this.emit('status', data);
+    });
+    this.bridge.on('management:error', (data: any) => {
+      this.emit('error', data);
+    });
+    this.bridge.on('management:client-connected', (data: any) => {
+      this.emit('client-connected', data);
+    });
+    this.bridge.on('management:client-disconnected', (data: any) => {
+      this.emit('client-disconnected', data);
+    });
+    this.bridge.on('management:started', (data: any) => {
+      this.emit('started', data);
+    });
+    this.bridge.on('management:stopped', (data: any) => {
+      this.emit('stopped', data);
+    });
+  }
+
+  /**
+   * Start the bridge: spawn in stdio mode or connect in socket mode.
+   */
+  public async start(): Promise<boolean> {
+    if (this.transportOptions.transport === 'socket') {
+      const socketOpts = this.transportOptions as IVpnTransportSocket;
+      return this.bridge.connect(socketOpts.socketPath, {
+        autoReconnect: socketOpts.autoReconnect,
+        reconnectBaseDelayMs: socketOpts.reconnectBaseDelayMs,
+        reconnectMaxDelayMs: socketOpts.reconnectMaxDelayMs,
+        maxReconnectAttempts: socketOpts.maxReconnectAttempts,
+      });
+    } else {
+      return this.bridge.spawn();
+    }
+  }
+
+  /**
+   * Stop the bridge. In socket mode, closes the socket (daemon stays alive).
+   * In stdio mode, kills the child process.
+   */
+  public stop(): void {
+    this.bridge.kill();
+  }
+
+  /**
+   * Send a typed command to the daemon.
+   */
+  public async sendCommand<K extends string & keyof TCommands>(
+    method: K,
+    params: TCommands[K]['params'],
+  ): Promise<TCommands[K]['result']> {
+    return this.bridge.sendCommand(method, params);
+  }
+
+  /**
+   * Whether the bridge is currently running/connected.
+   */
+  public get running(): boolean {
+    return this.bridge.running;
+  }
+}

package/ts/smartvpn.classes.vpnclient.ts

@@ -0,0 +1,87 @@
+import * as plugins from './smartvpn.plugins.js';
+import { VpnBridge } from './smartvpn.classes.vpnbridge.js';
+import type {
+  IVpnClientOptions,
+  IVpnClientConfig,
+  IVpnStatus,
+  IVpnStatistics,
+  TVpnClientCommands,
+} from './smartvpn.interfaces.js';
+
+/**
+ * VPN Client — manages a smartvpn daemon in client mode.
+ */
+export class VpnClient extends plugins.events.EventEmitter {
+  private bridge: VpnBridge<TVpnClientCommands>;
+  private options: IVpnClientOptions;
+
+  constructor(options: IVpnClientOptions) {
+    super();
+    this.options = options;
+    this.bridge = new VpnBridge<TVpnClientCommands>({
+      transport: options.transport,
+      mode: 'client',
+    });
+
+    // Forward bridge events
+    this.bridge.on('exit', (code: number | null, signal: string | null) => {
+      this.emit('exit', { code, signal });
+    });
+    this.bridge.on('reconnected', () => {
+      this.emit('reconnected');
+    });
+  }
+
+  /**
+   * Start the daemon bridge (spawn or connect).
+   */
+  public async start(): Promise<boolean> {
+    return this.bridge.start();
+  }
+
+  /**
+   * Connect to the VPN server using the provided config.
+   */
+  public async connect(config?: IVpnClientConfig): Promise<{ assignedIp: string }> {
+    const cfg = config || this.options.config;
+    if (!cfg) {
+      throw new Error('VpnClient.connect: no config provided');
+    }
+    return this.bridge.sendCommand('connect', { config: cfg });
+  }
+
+  /**
+   * Disconnect from the VPN server.
+   */
+  public async disconnect(): Promise<void> {
+    await this.bridge.sendCommand('disconnect', {} as Record<string, never>);
+  }
+
+  /**
+   * Get current connection status.
+   */
+  public async getStatus(): Promise<IVpnStatus> {
+    return this.bridge.sendCommand('getStatus', {} as Record<string, never>);
+  }
+
+  /**
+   * Get traffic statistics.
+   */
+  public async getStatistics(): Promise<IVpnStatistics> {
+    return this.bridge.sendCommand('getStatistics', {} as Record<string, never>);
+  }
+
+  /**
+   * Stop the daemon bridge.
+   */
+  public stop(): void {
+    this.bridge.stop();
+  }
+
+  /**
+   * Whether the bridge is running.
+   */
+  public get running(): boolean {
+    return this.bridge.running;
+  }
+}