@push.rocks/smartvpn 1.17.1 → 1.19.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@push.rocks/smartvpn',
-    version: '1.17.1',
+    version: '1.19.0',
     description: 'A VPN solution with TypeScript control plane and Rust data plane daemon'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxzQkFBc0I7SUFDNUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHlFQUF5RTtDQUN2RixDQUFBIn0=

package/dist_ts/smartvpn.interfaces.d.ts

@@ -75,8 +75,9 @@ export interface IVpnServerConfig {
     /** Enable NAT/masquerade for client traffic */
     enableNat?: boolean;
     /** Forwarding mode: 'tun' (kernel TUN, requires root), 'socket' (userspace NAT),
+     *  'bridge' (L2 bridge to host LAN), 'hybrid' (per-client socket+bridge),
      *  or 'testing' (monitoring only). Default: 'testing'. */
-    forwardingMode?: 'tun' | 'socket' | 'testing';
+    forwardingMode?: 'tun' | 'socket' | 'bridge' | 'hybrid' | 'testing';
     /** Default rate limit for new clients (bytes/sec). Omit for unlimited. */
     defaultRateLimitBytesPerSec?: number;
     /** Default burst size for new clients (bytes). Omit for unlimited. */
@@ -120,6 +121,19 @@ export interface IVpnServerConfig {
      *  Controls what traffic the client routes through the VPN tunnel.
      *  Defaults to ['0.0.0.0/0'] (full tunnel). Set to e.g. ['10.8.0.0/24'] for split tunnel. */
     clientAllowedIPs?: string[];
+    /** LAN subnet CIDR for bridge mode (e.g. '192.168.1.0/24').
+     *  VPN clients get IPs from this subnet instead of the VPN subnet.
+     *  Required when forwardingMode is 'bridge'. */
+    bridgeLanSubnet?: string;
+    /** Physical network interface to bridge (e.g. 'eth0').
+     *  Auto-detected from the default route if omitted. */
+    bridgePhysicalInterface?: string;
+    /** Start of VPN client IP range within the LAN subnet (host offset, e.g. 200 for .200).
+     *  Default: 200. */
+    bridgeIpRangeStart?: number;
+    /** End of VPN client IP range within the LAN subnet (host offset, e.g. 250 for .250).
+     *  Default: 250. */
+    bridgeIpRangeEnd?: number;
 }
 /**
  * Destination routing policy for VPN client traffic.
@@ -253,6 +267,10 @@ export interface IClientSecurity {
     maxConnections?: number;
     /** Per-client rate limiting. */
     rateLimit?: IClientRateLimit;
+    /** Per-client destination routing policy override.
+     *  When set, overrides the server-level destinationPolicy for this client's traffic.
+     *  Supports the same options: forceTarget, block, allow with allow/block lists. */
+    destinationPolicy?: IDestinationPolicy;
 }
 /**
  * Server-side client definition — the central config object for the Hub.
@@ -283,6 +301,18 @@ export interface IClientEntry {
     expiresAt?: string;
     /** Assigned VPN IP address (set by server) */
     assignedIp?: string;
+    /** If true, client gets a host network IP via bridge mode (L2 to LAN).
+     *  If false (default), client gets a VPN subnet IP via socket/NAT mode. */
+    useHostIp?: boolean;
+    /** If true and useHostIp is true, obtain IP via DHCP relay.
+     *  If false or omitted, use staticIp or auto-assign from bridge IP range. */
+    useDhcp?: boolean;
+    /** Static LAN IP when useHostIp is true and useDhcp is false. */
+    staticIp?: string;
+    /** If true, assign this client to a specific 802.1Q VLAN on the bridge. */
+    forceVlan?: boolean;
+    /** 802.1Q VLAN ID (1-4094). Required when forceVlan is true. */
+    vlanId?: number;
 }
 /**
  * Complete client config bundle — returned by createClient() and rotateClientKey().

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartvpn",
-  "version": "1.17.1",
+  "version": "1.19.0",
   "private": false,
   "description": "A VPN solution with TypeScript control plane and Rust data plane daemon",
   "type": "module",

package/readme.md

@@ -2,16 +2,19 @@
 
 A high-performance VPN solution with a **TypeScript control plane** and a **Rust data plane daemon**. Enterprise-ready client authentication, triple transport support (WebSocket + QUIC + WireGuard), and a typed hub API for managing clients from code.
 
-🔐 **Noise IK** mutual authentication — per-client X25519 keypairs, server-side registry
-🚀 **Triple transport**: WebSocket (Cloudflare-friendly), raw **QUIC** (datagrams), and **WireGuard** (standard protocol)
-🛡️ **ACL engine** — deny-overrides-allow IP filtering, aligned with SmartProxy conventions
-🔀 **PROXY protocol v2** — real client IPs behind reverse proxies (HAProxy, SmartProxy, Cloudflare Spectrum)
-📊 **Per-transport metrics**: active clients and total connections broken down by websocket, QUIC, and WireGuard
-🔄 **Hub API**: one `createClient()` call generates keys, assigns IP, returns both SmartVPN + WireGuard configs
-📡 **Real-time telemetry**: RTT, jitter, loss ratio, link health — all via typed APIs
-🌐 **Unified forwarding pipeline**: all transports share the same engine — TUN (kernel), userspace NAT (no root), or testing mode
-🎯 **Destination routing policy**: force-target, block, or allow traffic per destination with nftables integration
-⚡ **Handshake-driven WireGuard state**: peers appear as "connected" only after a successful WireGuard handshake, and auto-disconnect on idle timeout
+- 🔐 **Noise IK** mutual authentication — per-client X25519 keypairs, server-side registry
+- 🚀 **Triple transport**: WebSocket (Cloudflare-friendly), raw **QUIC** (datagrams), and **WireGuard** (standard protocol)
+- 🛡️ **ACL engine** — deny-overrides-allow IP filtering, aligned with SmartProxy conventions
+- 🔀 **PROXY protocol v2** — real client IPs behind reverse proxies (HAProxy, SmartProxy, Cloudflare Spectrum)
+- 📊 **Per-transport metrics**: active clients and total connections broken down by websocket, QUIC, and WireGuard
+- 🔄 **Hub API**: one `createClient()` call generates keys, assigns IP, returns both SmartVPN + WireGuard configs
+- 📡 **Real-time telemetry**: RTT, jitter, loss ratio, link health — all via typed APIs
+- 🌐 **Unified forwarding pipeline**: all transports share the same engine — TUN (kernel), userspace NAT (no root), L2 bridge, hybrid, or testing mode
+- 🏠 **Bridge mode**: VPN clients get IPs from your LAN subnet — seamlessly bridge remote clients onto a physical network
+- 🔀 **Hybrid mode**: per-client routing — some clients bridge to the LAN, others use userspace NAT, all on the same server
+- 🏷️ **VLAN support**: assign individual clients to 802.1Q VLANs on the bridge
+- 🎯 **Destination routing policy**: force-target, block, or allow traffic per destination with nftables integration
+- ⚡ **Handshake-driven WireGuard state**: peers appear as "connected" only after a successful WireGuard handshake, and auto-disconnect on idle timeout
 
 ## Issue Reporting and Security
 
@@ -84,7 +87,7 @@ await server.start({
   publicKey: '<server-noise-public-key-base64>',
   subnet: '10.8.0.0/24',
   transportMode: 'all',       // WebSocket + QUIC + WireGuard simultaneously (default)
-  forwardingMode: 'tun',      // 'tun' (kernel), 'socket' (userspace NAT), or 'testing'
+  forwardingMode: 'tun',      // 'tun' | 'socket' | 'bridge' | 'hybrid' | 'testing'
   wgPrivateKey: '<server-wg-private-key-base64>', // required for WireGuard transport
   enableNat: true,
   dns: ['1.1.1.1', '8.8.8.8'],
@@ -237,6 +240,21 @@ In **TUN mode**, destination policies are enforced via **nftables** rules (using
 
 In **socket mode**, the policy is evaluated in the userspace NAT engine before per-client ACLs.
 
+**Per-client override** — individual clients can have their own destination policy that overrides the server-level default:
+
+```typescript
+await server.createClient({
+  clientId: 'restricted-client',
+  security: {
+    destinationPolicy: {
+      default: 'block',                         // block everything by default
+      allowList: ['10.0.0.0/8'],                 // except internal network
+    },
+    // ... other security settings
+  },
+});
+```
+
 ### 🔗 Socket Forward Proxy Protocol
 
 When using `forwardingMode: 'socket'` (userspace NAT), you can prepend **PROXY protocol v2 headers** on outbound TCP connections. This conveys the VPN client's tunnel IP as the source address to downstream services (e.g., SmartProxy):
@@ -251,12 +269,14 @@ await server.start({
 
 ### 📦 Packet Forwarding Modes
 
-SmartVPN supports three forwarding modes, configurable per-server and per-client:
+SmartVPN supports five forwarding modes, configurable per-server:
 
 | Mode | Flag | Description | Root Required |
 |------|------|-------------|---------------|
 | **TUN** | `'tun'` | Kernel TUN device — real packet forwarding with system routing | ✅ Yes |
 | **Userspace NAT** | `'socket'` | Userspace TCP/UDP proxy via `connect(2)` — no TUN, no root needed | ❌ No |
+| **Bridge** | `'bridge'` | L2 bridge — VPN clients get IPs from a physical LAN subnet | ✅ Yes |
+| **Hybrid** | `'hybrid'` | Per-client routing: some clients use socket NAT, others use bridge — both engines run simultaneously | ✅ Yes |
 | **Testing** | `'testing'` | Monitoring only — packets are counted but not forwarded | ❌ No |
 
 ```typescript
@@ -267,6 +287,23 @@ await server.start({
   enableNat: true,
 });
 
+// Server with bridge mode — VPN clients appear on the LAN
+await server.start({
+  // ...
+  forwardingMode: 'bridge',
+  bridgeLanSubnet: '192.168.1.0/24',      // LAN subnet to bridge into
+  bridgePhysicalInterface: 'eth0',         // auto-detected if omitted
+  bridgeIpRangeStart: 200,                 // clients get .200–.250 (defaults)
+  bridgeIpRangeEnd: 250,
+});
+
+// Server with hybrid mode — per-client routing
+await server.start({
+  // ...
+  forwardingMode: 'hybrid',
+  bridgePhysicalInterface: 'eth0',         // for bridge clients
+});
+
 // Client with TUN device
 const { assignedIp } = await client.connect({
   // ...
@@ -274,7 +311,55 @@ const { assignedIp } = await client.connect({
 });
 ```
 
-The userspace NAT mode extracts destination IP/port from IP packets, opens a real socket to the destination, and relays data — supporting both TCP streams and UDP datagrams without requiring `CAP_NET_ADMIN` or root privileges.
+The **userspace NAT** mode extracts destination IP/port from IP packets, opens a real socket to the destination, and relays data — supporting both TCP streams and UDP datagrams without requiring `CAP_NET_ADMIN` or root privileges.
+
+The **bridge** mode assigns VPN clients IPs from a real LAN subnet instead of a virtual VPN subnet. Clients appear as if they're directly on the physical network — perfect for remote access to home labs, office networks, or IoT devices.
+
+The **hybrid** mode runs both engines simultaneously with a **per-client routing table**. Each client's `useHostIp` flag determines whether its packets go through the bridge (L2, LAN IP) or socket NAT (userspace, VPN IP). This is ideal when most clients need internet NAT but some need direct LAN access.
+
+### 🏠 Per-Client Bridge & VLAN Settings
+
+When using `bridge` or `hybrid` mode, each client can be individually configured for LAN bridging, static IPs, DHCP, and 802.1Q VLAN assignment:
+
+```typescript
+// Client that bridges to the LAN with a static IP
+await server.createClient({
+  clientId: 'office-printer',
+  useHostIp: true,           // bridge to LAN instead of VPN subnet
+  staticIp: '192.168.1.210', // fixed LAN IP
+});
+
+// Client that gets a LAN IP via DHCP
+await server.createClient({
+  clientId: 'roaming-laptop',
+  useHostIp: true,
+  useDhcp: true,             // obtain IP from LAN DHCP server
+});
+
+// Client on a specific VLAN
+await server.createClient({
+  clientId: 'iot-sensor',
+  useHostIp: true,
+  forceVlan: true,
+  vlanId: 100,               // 802.1Q VLAN ID (1-4094)
+});
+
+// Regular NAT client (default, no bridge)
+await server.createClient({
+  clientId: 'remote-worker',
+  // useHostIp defaults to false → uses socket NAT
+});
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `useHostIp` | `boolean` | `true` = bridge to LAN (host IP), `false` = VPN subnet via NAT (default) |
+| `useDhcp` | `boolean` | When `useHostIp` is true, obtain IP via DHCP relay instead of static/auto-assign |
+| `staticIp` | `string` | Fixed LAN IP when `useHostIp` is true and `useDhcp` is false |
+| `forceVlan` | `boolean` | Assign this client to a specific 802.1Q VLAN on the bridge |
+| `vlanId` | `number` | VLAN ID (1-4094), required when `forceVlan` is true |
+
+VLAN support uses Linux bridge VLAN filtering — each client's TAP port gets tagged with the specified VLAN ID, isolating traffic at Layer 2.
 
 ### 📊 Telemetry & QoS
 
@@ -444,10 +529,10 @@ server.on('reconnected', () => { /* socket transport reconnected */ });
 
 | Interface | Purpose |
 |-----------|---------|
-| `IVpnServerConfig` | Server configuration (listen addr, keys, subnet, transport mode, forwarding mode, clients, proxy protocol, destination policy) |
+| `IVpnServerConfig` | Server configuration (listen addr, keys, subnet, transport mode, forwarding mode incl. bridge/hybrid, clients, proxy protocol, destination policy) |
 | `IVpnClientConfig` | Client configuration (server URL, keys, transport, forwarding mode, WG options, client-defined tags) |
-| `IClientEntry` | Server-side client definition (ID, keys, security, priority, server/client tags, expiry) |
-| `IClientSecurity` | Per-client ACLs and rate limits (SmartProxy-aligned naming) |
+| `IClientEntry` | Server-side client definition (ID, keys, security, priority, server/client tags, expiry, bridge/VLAN settings) |
+| `IClientSecurity` | Per-client ACLs, rate limits, and destination policy override (SmartProxy-aligned naming) |
 | `IClientRateLimit` | Rate limiting config (bytesPerSec, burstBytes) |
 | `IClientConfigBundle` | Full config bundle returned by `createClient()` — includes SmartVPN config, WireGuard .conf, and secrets |
 | `IVpnClientInfo` | Connected client info (IP, stats, authenticated key, remote addr, transport type) |

package/ts/00_commitinfo_data.ts

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

package/ts/smartvpn.interfaces.ts

@@ -92,8 +92,9 @@ export interface IVpnServerConfig {
   /** Enable NAT/masquerade for client traffic */
   enableNat?: boolean;
   /** Forwarding mode: 'tun' (kernel TUN, requires root), 'socket' (userspace NAT),
+   *  'bridge' (L2 bridge to host LAN), 'hybrid' (per-client socket+bridge),
    *  or 'testing' (monitoring only). Default: 'testing'. */
-  forwardingMode?: 'tun' | 'socket' | 'testing';
+  forwardingMode?: 'tun' | 'socket' | 'bridge' | 'hybrid' | 'testing';
   /** Default rate limit for new clients (bytes/sec). Omit for unlimited. */
   defaultRateLimitBytesPerSec?: number;
   /** Default burst size for new clients (bytes). Omit for unlimited. */
@@ -137,6 +138,22 @@ export interface IVpnServerConfig {
    *  Controls what traffic the client routes through the VPN tunnel.
    *  Defaults to ['0.0.0.0/0'] (full tunnel). Set to e.g. ['10.8.0.0/24'] for split tunnel. */
   clientAllowedIPs?: string[];
+
+  // Bridge mode configuration (forwardingMode: 'bridge')
+
+  /** LAN subnet CIDR for bridge mode (e.g. '192.168.1.0/24').
+   *  VPN clients get IPs from this subnet instead of the VPN subnet.
+   *  Required when forwardingMode is 'bridge'. */
+  bridgeLanSubnet?: string;
+  /** Physical network interface to bridge (e.g. 'eth0').
+   *  Auto-detected from the default route if omitted. */
+  bridgePhysicalInterface?: string;
+  /** Start of VPN client IP range within the LAN subnet (host offset, e.g. 200 for .200).
+   *  Default: 200. */
+  bridgeIpRangeStart?: number;
+  /** End of VPN client IP range within the LAN subnet (host offset, e.g. 250 for .250).
+   *  Default: 250. */
+  bridgeIpRangeEnd?: number;
 }
 
 /**
@@ -310,6 +327,10 @@ export interface IClientSecurity {
   maxConnections?: number;
   /** Per-client rate limiting. */
   rateLimit?: IClientRateLimit;
+  /** Per-client destination routing policy override.
+   *  When set, overrides the server-level destinationPolicy for this client's traffic.
+   *  Supports the same options: forceTarget, block, allow with allow/block lists. */
+  destinationPolicy?: IDestinationPolicy;
 }
 
 /**
@@ -341,6 +362,21 @@ export interface IClientEntry {
   expiresAt?: string;
   /** Assigned VPN IP address (set by server) */
   assignedIp?: string;
+
+  // Per-client bridge/host-IP settings
+
+  /** If true, client gets a host network IP via bridge mode (L2 to LAN).
+   *  If false (default), client gets a VPN subnet IP via socket/NAT mode. */
+  useHostIp?: boolean;
+  /** If true and useHostIp is true, obtain IP via DHCP relay.
+   *  If false or omitted, use staticIp or auto-assign from bridge IP range. */
+  useDhcp?: boolean;
+  /** Static LAN IP when useHostIp is true and useDhcp is false. */
+  staticIp?: string;
+  /** If true, assign this client to a specific 802.1Q VLAN on the bridge. */
+  forceVlan?: boolean;
+  /** 802.1Q VLAN ID (1-4094). Required when forceVlan is true. */
+  vlanId?: number;
 }
 
 /**