@push.rocks/smartvpn 1.7.0 → 1.9.0

package/readme.plan.md

@@ -0,0 +1,253 @@
+# PROXY Protocol v2 Support for SmartVPN WebSocket Transport
+
+## Context
+
+SmartVPN's WebSocket transport is designed to sit behind reverse proxies (Cloudflare, HAProxy, SmartProxy). The recently added ACL engine has `ipAllowList`/`ipBlockList` per client, but without PROXY protocol support the server only sees the proxy's IP — not the real client's. This makes source-IP ACLs useless behind a proxy.
+
+PROXY protocol v2 solves this by letting the proxy prepend a binary header with the real client IP/port before the WebSocket upgrade.
+
+---
+
+## Design
+
+### Two-Phase ACL with Real Client IP
+
+```
+TCP accept → Read PP v2 header → Extract real IP
+  │
+  ├─ Phase 1 (pre-handshake): Check server-level connectionIpBlockList → reject early
+  │
+  ├─ WebSocket upgrade → Noise IK handshake → Client identity known
+  │
+  └─ Phase 2 (post-handshake): Check per-client ipAllowList/ipBlockList → reject if denied
+```
+
+- **Phase 1**: Server-wide block list (`connectionIpBlockList` on `IVpnServerConfig`). Rejects before any crypto work. Protects server resources.
+- **Phase 2**: Per-client ACL from `IClientSecurity.ipAllowList`/`ipBlockList`. Applied after the Noise IK handshake identifies the client.
+
+### No New Dependencies
+
+PROXY protocol v2 is a fixed-format binary header (16-byte signature + variable address block). Manual parsing (~80 lines) follows the same pattern as `codec.rs`. No crate needed.
+
+### Scope: WebSocket Only
+
+- **WebSocket**: Needs PP v2 (sits behind reverse proxies)
+- **QUIC**: Direct UDP, just use `conn.remote_address()`
+- **WireGuard**: Direct UDP, uses boringtun peer tracking
+
+---
+
+## Implementation
+
+### Phase 1: New Rust module `proxy_protocol.rs`
+
+**New file: `rust/src/proxy_protocol.rs`**
+
+PP v2 binary format:
+```
+Bytes 0-11:   Signature  \x0D\x0A\x0D\x0A\x00\x0D\x0A\x51\x55\x49\x54\x0A
+Byte 12:      Version (high nibble = 0x2) | Command (low nibble: 0x0=LOCAL, 0x1=PROXY)
+Byte 13:      Address family | Protocol (0x11 = IPv4/TCP, 0x21 = IPv6/TCP)
+Bytes 14-15:  Address data length (big-endian u16)
+Bytes 16+:    IPv4: 4 src_ip + 4 dst_ip + 2 src_port + 2 dst_port (12 bytes)
+              IPv6: 16 src_ip + 16 dst_ip + 2 src_port + 2 dst_port (36 bytes)
+```
+
+```rust
+pub struct ProxyHeader {
+    pub src_addr: SocketAddr,
+    pub dst_addr: SocketAddr,
+    pub is_local: bool,  // LOCAL command = health check probe
+}
+
+/// Read and parse a PROXY protocol v2 header from a TCP stream.
+/// Reads exactly the header bytes — the stream is clean for WS upgrade after.
+pub async fn read_proxy_header(stream: &mut TcpStream) -> Result<ProxyHeader>
+```
+
+- 5-second timeout on header read (constant `PROXY_HEADER_TIMEOUT`)
+- Validates 12-byte signature, version nibble, command type
+- Parses IPv4 and IPv6 address blocks
+- LOCAL command returns `is_local: true` (caller closes connection gracefully)
+- Unit tests: valid IPv4/IPv6 headers, LOCAL command, invalid signature, truncated data
+
+**Modify: `rust/src/lib.rs`** — add `pub mod proxy_protocol;`
+
+### Phase 2: Server config + client info fields
+
+**File: `rust/src/server.rs` — `ServerConfig`**
+
+Add:
+```rust
+/// Enable PROXY protocol v2 parsing on WebSocket connections.
+/// SECURITY: Must be false when accepting direct client connections.
+pub proxy_protocol: Option<bool>,
+/// Server-level IP block list — applied at TCP accept time, before Noise handshake.
+pub connection_ip_block_list: Option<Vec<String>>,
+```
+
+**File: `rust/src/server.rs` — `ClientInfo`**
+
+Add:
+```rust
+/// Real client IP:port (from PROXY protocol header or direct TCP connection).
+pub remote_addr: Option<String>,
+```
+
+### Phase 3: ACL helper
+
+**File: `rust/src/acl.rs`**
+
+Add a public function for the server-level pre-handshake check:
+```rust
+/// Check whether a connection source IP is in a block list.
+pub fn is_connection_blocked(ip: Ipv4Addr, block_list: &[String]) -> bool {
+    ip_matches_any(ip, block_list)
+}
+```
+
+(Keeps `ip_matches_any` private; exposes only the specific check needed.)
+
+### Phase 4: WebSocket listener integration
+
+**File: `rust/src/server.rs` — `run_ws_listener()`**
+
+Between `listener.accept()` and `transport::accept_connection()`:
+
+```rust
+// Determine real client address
+let remote_addr = if state.config.proxy_protocol.unwrap_or(false) {
+    match proxy_protocol::read_proxy_header(&mut tcp_stream).await {
+        Ok(header) if header.is_local => {
+            // Health check probe — close gracefully
+            return;
+        }
+        Ok(header) => {
+            info!("PP v2: real client {} -> {}", header.src_addr, header.dst_addr);
+            Some(header.src_addr)
+        }
+        Err(e) => {
+            warn!("PP v2 parse failed from {}: {}", tcp_addr, e);
+            return; // Drop connection
+        }
+    }
+} else {
+    Some(tcp_addr) // Direct connection — use TCP SocketAddr
+};
+
+// Pre-handshake server-level block list check
+if let (Some(ref block_list), Some(ref addr)) = (&state.config.connection_ip_block_list, &remote_addr) {
+    if let std::net::IpAddr::V4(v4) = addr.ip() {
+        if acl::is_connection_blocked(v4, block_list) {
+            warn!("Connection blocked by server IP block list: {}", addr);
+            return;
+        }
+    }
+}
+
+// Then proceed with WS upgrade + handle_client_connection as before
+```
+
+Key correctness note: `read_proxy_header` reads *exactly* the PP header bytes via `read_exact`. The `TcpStream` is then in a clean state for the WS HTTP upgrade. No buffered wrapper needed.
+
+### Phase 5: Update `handle_client_connection` signature
+
+**File: `rust/src/server.rs`**
+
+Change signature:
+```rust
+async fn handle_client_connection(
+    state: Arc<ServerState>,
+    mut sink: Box<dyn TransportSink>,
+    mut stream: Box<dyn TransportStream>,
+    remote_addr: Option<std::net::SocketAddr>,  // NEW
+) -> Result<()>
+```
+
+After Noise IK handshake + registry lookup (where `client_security` is available), add connection-level per-client ACL:
+
+```rust
+if let (Some(ref sec), Some(addr)) = (&client_security, &remote_addr) {
+    if let std::net::IpAddr::V4(v4) = addr.ip() {
+        if acl::is_connection_blocked(v4, sec.ip_block_list.as_deref().unwrap_or(&[])) {
+            anyhow::bail!("Client {} connection denied: source IP {} blocked", registered_client_id, addr);
+        }
+        if let Some(ref allow) = sec.ip_allow_list {
+            if !allow.is_empty() && !acl::is_ip_allowed(v4, allow) {
+                anyhow::bail!("Client {} connection denied: source IP {} not in allow list", registered_client_id, addr);
+            }
+        }
+    }
+}
+```
+
+Populate `remote_addr` when building `ClientInfo`:
+```rust
+remote_addr: remote_addr.map(|a| a.to_string()),
+```
+
+### Phase 6: QUIC listener — pass remote addr through
+
+**File: `rust/src/server.rs` — `run_quic_listener()`**
+
+QUIC doesn't use PROXY protocol. Just pass `conn.remote_address()` through:
+```rust
+let remote = conn.remote_address();
+// ...
+handle_client_connection(state, Box::new(sink), Box::new(stream), Some(remote)).await
+```
+
+### Phase 7: TypeScript interface updates
+
+**File: `ts/smartvpn.interfaces.ts`**
+
+Add to `IVpnServerConfig`:
+```typescript
+/** Enable PROXY protocol v2 on incoming WebSocket connections.
+ *  Required when behind a reverse proxy that sends PP v2 headers. */
+proxyProtocol?: boolean;
+/** Server-level IP block list — applied at TCP accept time, before Noise handshake. */
+connectionIpBlockList?: string[];
+```
+
+Add to `IVpnClientInfo`:
+```typescript
+/** Real client IP:port (from PROXY protocol or direct TCP). */
+remoteAddr?: string;
+```
+
+### Phase 8: Tests
+
+**Rust unit tests in `proxy_protocol.rs`:**
+- `parse_valid_ipv4_header` — construct a valid PP v2 header with known IPs, verify parsed correctly
+- `parse_valid_ipv6_header` — same for IPv6
+- `parse_local_command` — health check probe returns `is_local: true`
+- `reject_invalid_signature` — random bytes rejected
+- `reject_truncated_header` — short reads fail gracefully
+- `reject_v1_header` — PROXY v1 text format rejected (we only support v2)
+
+**Rust unit tests in `acl.rs`:**
+- `is_connection_blocked` with various IP patterns
+
+**TypeScript tests:**
+- Config validation accepts `proxyProtocol: true` + `connectionIpBlockList`
+
+---
+
+## Key Files to Modify
+
+| File | Changes |
+|------|---------|
+| `rust/src/proxy_protocol.rs` | **NEW** — PP v2 parser + tests |
+| `rust/src/lib.rs` | Add `pub mod proxy_protocol;` |
+| `rust/src/server.rs` | `ServerConfig` + `ClientInfo` fields, `run_ws_listener` PP integration, `handle_client_connection` signature + connection ACL, `run_quic_listener` pass-through |
+| `rust/src/acl.rs` | Add `is_connection_blocked` public function |
+| `ts/smartvpn.interfaces.ts` | `proxyProtocol`, `connectionIpBlockList`, `remoteAddr` |
+
+---
+
+## Verification
+
+1. `cargo test` — all existing 121 tests + new PP parser tests pass
+2. `pnpm test` — all 79 TS tests pass (no PP in test setup, just config validation)
+3. Manual: `socat` or test harness to send a PP v2 header before WS upgrade, verify server logs real IP

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartvpn',
-  version: '1.7.0',
+  version: '1.9.0',
   description: 'A VPN solution with TypeScript control plane and Rust data plane daemon'
 }

package/ts/smartvpn.classes.vpnconfig.ts

@@ -51,6 +51,15 @@ export class VpnConfig {
       if (!config.serverPublicKey) {
         throw new Error('VpnConfig: serverPublicKey is required');
       }
+      // Noise IK requires client keypair
+      if (!config.clientPrivateKey) {
+        throw new Error('VpnConfig: clientPrivateKey is required for Noise IK authentication');
+      }
+      VpnConfig.validateBase64Key(config.clientPrivateKey, 'clientPrivateKey');
+      if (!config.clientPublicKey) {
+        throw new Error('VpnConfig: clientPublicKey is required for Noise IK authentication');
+      }
+      VpnConfig.validateBase64Key(config.clientPublicKey, 'clientPublicKey');
     }
     if (config.mtu !== undefined && (config.mtu < 576 || config.mtu > 65535)) {
       throw new Error('VpnConfig: mtu must be between 576 and 65535');
@@ -116,6 +125,18 @@ export class VpnConfig {
       if (!VpnConfig.isValidSubnet(config.subnet)) {
         throw new Error(`VpnConfig: invalid subnet: ${config.subnet}`);
       }
+      // Validate client entries if provided
+      if (config.clients) {
+        for (const client of config.clients) {
+          if (!client.clientId) {
+            throw new Error('VpnConfig: client entry must have a clientId');
+          }
+          if (!client.publicKey) {
+            throw new Error(`VpnConfig: client '${client.clientId}' must have a publicKey`);
+          }
+          VpnConfig.validateBase64Key(client.publicKey, `client '${client.clientId}' publicKey`);
+        }
+      }
     }
     if (config.mtu !== undefined && (config.mtu < 576 || config.mtu > 65535)) {
       throw new Error('VpnConfig: mtu must be between 576 and 65535');

package/ts/smartvpn.classes.vpnserver.ts

@@ -10,6 +10,8 @@ import type {
   IVpnClientTelemetry,
   IWgPeerConfig,
   IWgPeerInfo,
+  IClientEntry,
+  IClientConfigBundle,
   TVpnServerCommands,
 } from './smartvpn.interfaces.js';
 
@@ -152,6 +154,81 @@ export class VpnServer extends plugins.events.EventEmitter {
     return result.peers;
   }
 
+  // ── Client Registry (Hub) Methods ─────────────────────────────────────
+
+  /**
+   * Create a new client. Generates keypairs, assigns IP, returns full config bundle.
+   * The secrets (private keys) are only returned at creation time.
+   */
+  public async createClient(opts: Partial<IClientEntry>): Promise<IClientConfigBundle> {
+    return this.bridge.sendCommand('createClient', { client: opts });
+  }
+
+  /**
+   * Remove a registered client (also disconnects if connected).
+   */
+  public async removeClient(clientId: string): Promise<void> {
+    await this.bridge.sendCommand('removeClient', { clientId });
+  }
+
+  /**
+   * Get a registered client by ID.
+   */
+  public async getClient(clientId: string): Promise<IClientEntry> {
+    return this.bridge.sendCommand('getClient', { clientId });
+  }
+
+  /**
+   * List all registered clients.
+   */
+  public async listRegisteredClients(): Promise<IClientEntry[]> {
+    const result = await this.bridge.sendCommand('listRegisteredClients', {} as Record<string, never>);
+    return result.clients;
+  }
+
+  /**
+   * Update a registered client's fields (ACLs, tags, description, etc.).
+   */
+  public async updateClient(clientId: string, update: Partial<IClientEntry>): Promise<void> {
+    await this.bridge.sendCommand('updateClient', { clientId, update });
+  }
+
+  /**
+   * Enable a previously disabled client.
+   */
+  public async enableClient(clientId: string): Promise<void> {
+    await this.bridge.sendCommand('enableClient', { clientId });
+  }
+
+  /**
+   * Disable a client (also disconnects if connected).
+   */
+  public async disableClient(clientId: string): Promise<void> {
+    await this.bridge.sendCommand('disableClient', { clientId });
+  }
+
+  /**
+   * Rotate a client's keys. Returns a new config bundle with fresh keypairs.
+   */
+  public async rotateClientKey(clientId: string): Promise<IClientConfigBundle> {
+    return this.bridge.sendCommand('rotateClientKey', { clientId });
+  }
+
+  /**
+   * Export a client config (without secrets) in the specified format.
+   */
+  public async exportClientConfig(clientId: string, format: 'smartvpn' | 'wireguard'): Promise<string> {
+    const result = await this.bridge.sendCommand('exportClientConfig', { clientId, format });
+    return result.config;
+  }
+
+  /**
+   * Generate a standalone Noise IK keypair (not tied to a client).
+   */
+  public async generateClientKeypair(): Promise<IVpnKeypair> {
+    return this.bridge.sendCommand('generateClientKeypair', {} as Record<string, never>);
+  }
+
   /**
    * Stop the daemon bridge.
    */

package/ts/smartvpn.interfaces.ts

@@ -24,8 +24,12 @@ export type TVpnTransportOptions = IVpnTransportStdio | IVpnTransportSocket;
 export interface IVpnClientConfig {
   /** Server WebSocket URL, e.g. wss://vpn.example.com/tunnel */
   serverUrl: string;
-  /** Server's static public key (base64) for Noise NK handshake */
+  /** Server's static public key (base64) for Noise IK handshake */
   serverPublicKey: string;
+  /** Client's Noise IK private key (base64) — required for SmartVPN native transport */
+  clientPrivateKey: string;
+  /** Client's Noise IK public key (base64) — for reference/display */
+  clientPublicKey: string;
   /** Optional DNS servers to use while connected */
   dns?: string[];
   /** Optional MTU for the TUN device */
@@ -96,6 +100,15 @@ export interface IVpnServerConfig {
   wgListenPort?: number;
   /** WireGuard: configured peers */
   wgPeers?: IWgPeerConfig[];
+  /** Pre-registered clients for Noise IK authentication */
+  clients?: IClientEntry[];
+  /** Enable PROXY protocol v2 on incoming WebSocket connections.
+   *  Required when behind a reverse proxy that sends PP v2 headers (HAProxy, SmartProxy).
+   *  SECURITY: Must be false when accepting direct client connections. */
+  proxyProtocol?: boolean;
+  /** Server-level IP block list — applied at TCP accept, before Noise handshake.
+   *  Supports exact IPs, CIDR, wildcards, ranges. */
+  connectionIpBlockList?: string[];
 }
 
 export interface IVpnServerOptions {
@@ -146,6 +159,12 @@ export interface IVpnClientInfo {
   keepalivesReceived: number;
   rateLimitBytesPerSec?: number;
   burstBytes?: number;
+  /** Client's authenticated Noise IK public key (base64) */
+  authenticatedKey: string;
+  /** Registered client ID from the client registry */
+  registeredClientId: string;
+  /** Real client IP:port (from PROXY protocol or direct TCP connection) */
+  remoteAddr?: string;
 }
 
 export interface IVpnServerStatistics extends IVpnStatistics {
@@ -205,6 +224,84 @@ export interface IVpnClientTelemetry {
   burstBytes?: number;
 }
 
+// ============================================================================
+// Client Registry (Hub) types — aligned with SmartProxy IRouteSecurity pattern
+// ============================================================================
+
+/** Per-client rate limiting. */
+export interface IClientRateLimit {
+  /** Max throughput in bytes/sec */
+  bytesPerSec: number;
+  /** Burst allowance in bytes */
+  burstBytes: number;
+}
+
+/**
+ * Per-client security settings.
+ * Mirrors SmartProxy's IRouteSecurity: ipAllowList/ipBlockList naming + deny-overrides-allow.
+ * Adds VPN-specific destination filtering.
+ */
+export interface IClientSecurity {
+  /** Source IPs/CIDRs the client may connect FROM (empty = any).
+   *  Supports: exact IP, CIDR, wildcard (192.168.1.*), ranges (1.1.1.1-1.1.1.5). */
+  ipAllowList?: string[];
+  /** Source IPs blocked — overrides ipAllowList (deny wins). */
+  ipBlockList?: string[];
+  /** Destination IPs/CIDRs the client may reach through the VPN (empty = all). */
+  destinationAllowList?: string[];
+  /** Destination IPs blocked — overrides destinationAllowList (deny wins). */
+  destinationBlockList?: string[];
+  /** Max concurrent connections from this client. */
+  maxConnections?: number;
+  /** Per-client rate limiting. */
+  rateLimit?: IClientRateLimit;
+}
+
+/**
+ * Server-side client definition — the central config object for the Hub.
+ * Naming and structure aligned with SmartProxy's IRouteConfig / IRouteSecurity.
+ */
+export interface IClientEntry {
+  /** Human-readable client ID (e.g. "alice-laptop") */
+  clientId: string;
+  /** Client's Noise IK public key (base64) — for SmartVPN native transport */
+  publicKey: string;
+  /** Client's WireGuard public key (base64) — for WireGuard transport */
+  wgPublicKey?: string;
+  /** Security settings (ACLs, rate limits) */
+  security?: IClientSecurity;
+  /** Traffic priority (lower = higher priority, default: 100) */
+  priority?: number;
+  /** Whether this client is enabled (default: true) */
+  enabled?: boolean;
+  /** Tags for grouping (e.g. ["engineering", "office"]) */
+  tags?: string[];
+  /** Optional description */
+  description?: string;
+  /** Optional expiry (ISO 8601 timestamp, omit = never expires) */
+  expiresAt?: string;
+  /** Assigned VPN IP address (set by server) */
+  assignedIp?: string;
+}
+
+/**
+ * Complete client config bundle — returned by createClient() and rotateClientKey().
+ * Contains everything the client needs to connect.
+ */
+export interface IClientConfigBundle {
+  /** The server-side client entry */
+  entry: IClientEntry;
+  /** Ready-to-use SmartVPN client config (typed object) */
+  smartvpnConfig: IVpnClientConfig;
+  /** Ready-to-use WireGuard .conf file content (string) */
+  wireguardConfig: string;
+  /** Client's private keys (ONLY returned at creation time, not stored server-side) */
+  secrets: {
+    noisePrivateKey: string;
+    wgPrivateKey: string;
+  };
+}
+
 // ============================================================================
 // WireGuard-specific types
 // ============================================================================
@@ -262,6 +359,17 @@ export type TVpnServerCommands = {
   addWgPeer: { params: { peer: IWgPeerConfig }; result: void };
   removeWgPeer: { params: { publicKey: string }; result: void };
   listWgPeers: { params: Record<string, never>; result: { peers: IWgPeerInfo[] } };
+  // Client Registry (Hub) commands
+  createClient: { params: { client: Partial<IClientEntry> }; result: IClientConfigBundle };
+  removeClient: { params: { clientId: string }; result: void };
+  getClient: { params: { clientId: string }; result: IClientEntry };
+  listRegisteredClients: { params: Record<string, never>; result: { clients: IClientEntry[] } };
+  updateClient: { params: { clientId: string; update: Partial<IClientEntry> }; result: void };
+  enableClient: { params: { clientId: string }; result: void };
+  disableClient: { params: { clientId: string }; result: void };
+  rotateClientKey: { params: { clientId: string }; result: IClientConfigBundle };
+  exportClientConfig: { params: { clientId: string; format: 'smartvpn' | 'wireguard' }; result: { config: string } };
+  generateClientKeypair: { params: Record<string, never>; result: IVpnKeypair };
 };
 
 // ============================================================================