@serve.zone/dcrouter 11.12.4 → 11.14.0

package/dist_ts_interfaces/data/index.d.ts

@@ -2,3 +2,4 @@ export * from './auth.js';
 export * from './stats.js';
 export * from './remoteingress.js';
 export * from './route-management.js';
+export * from './vpn.js';

package/dist_ts_interfaces/data/index.js

@@ -2,4 +2,5 @@ export * from './auth.js';
 export * from './stats.js';
 export * from './remoteingress.js';
 export * from './route-management.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL2RhdGEvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHVCQUF1QixDQUFDIn0=
+export * from './vpn.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL2RhdGEvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsVUFBVSxDQUFDIn0=

package/dist_ts_interfaces/data/remoteingress.d.ts

@@ -47,11 +47,20 @@ export interface IRouteRemoteIngress {
      *  When absent, the route applies to all edges. */
     edgeFilter?: string[];
 }
+/**
+ * Route-level VPN access configuration.
+ * When attached to a route, restricts access to VPN clients only.
+ */
+export interface IRouteVpn {
+    /** Whether this route requires VPN access */
+    required: boolean;
+}
 /**
  * Extended route config used within dcrouter.
- * Adds the optional `remoteIngress` property to SmartProxy's IRouteConfig.
+ * Adds optional `remoteIngress` and `vpn` properties to SmartProxy's IRouteConfig.
  * SmartProxy ignores unknown properties at runtime.
  */
 export type IDcRouterRouteConfig = IRouteConfig & {
     remoteIngress?: IRouteRemoteIngress;
+    vpn?: IRouteVpn;
 };

package/dist_ts_interfaces/data/vpn.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A registered VPN client (secrets excluded from API responses).
+ */
+export interface IVpnClient {
+    clientId: string;
+    enabled: boolean;
+    tags?: string[];
+    description?: string;
+    assignedIp?: string;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt?: string;
+}
+/**
+ * VPN server status.
+ */
+export interface IVpnServerStatus {
+    running: boolean;
+    forwardingMode: 'tun' | 'socket';
+    subnet: string;
+    wgListenPort: number;
+    serverPublicKeys: {
+        noisePublicKey: string;
+        wgPublicKey: string;
+    } | null;
+    registeredClients: number;
+    connectedClients: number;
+}
+/**
+ * VPN client telemetry data.
+ */
+export interface IVpnClientTelemetry {
+    clientId: string;
+    assignedIp: string;
+    bytesSent: number;
+    bytesReceived: number;
+    packetsDropped: number;
+    bytesDropped: number;
+    lastKeepaliveAt?: string;
+    keepalivesReceived: number;
+    rateLimitBytesPerSec?: number;
+    burstBytes?: number;
+}

package/dist_ts_interfaces/data/vpn.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidnBuLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHNfaW50ZXJmYWNlcy9kYXRhL3Zwbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist_ts_interfaces/requests/index.d.ts

@@ -9,3 +9,4 @@ export * from './certificate.js';
 export * from './remoteingress.js';
 export * from './route-management.js';
 export * from './api-tokens.js';
+export * from './vpn.js';

package/dist_ts_interfaces/requests/index.js

@@ -9,4 +9,5 @@ export * from './certificate.js';
 export * from './remoteingress.js';
 export * from './route-management.js';
 export * from './api-tokens.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDIn0=
+export * from './vpn.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsVUFBVSxDQUFDIn0=

package/dist_ts_interfaces/requests/vpn.d.ts

@@ -0,0 +1,135 @@
+import * as plugins from '../plugins.js';
+import * as authInterfaces from '../data/auth.js';
+import type { IVpnClient, IVpnServerStatus, IVpnClientTelemetry } from '../data/vpn.js';
+/**
+ * Get all registered VPN clients.
+ */
+export interface IReq_GetVpnClients extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetVpnClients> {
+    method: 'getVpnClients';
+    request: {
+        identity: authInterfaces.IIdentity;
+    };
+    response: {
+        clients: IVpnClient[];
+    };
+}
+/**
+ * Get VPN server status.
+ */
+export interface IReq_GetVpnStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetVpnStatus> {
+    method: 'getVpnStatus';
+    request: {
+        identity: authInterfaces.IIdentity;
+    };
+    response: {
+        status: IVpnServerStatus;
+    };
+}
+/**
+ * Create a new VPN client. Returns the config bundle (secrets only shown once).
+ */
+export interface IReq_CreateVpnClient extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CreateVpnClient> {
+    method: 'createVpnClient';
+    request: {
+        identity: authInterfaces.IIdentity;
+        clientId: string;
+        tags?: string[];
+        description?: string;
+    };
+    response: {
+        success: boolean;
+        client?: IVpnClient;
+        /** WireGuard .conf file content (only returned at creation) */
+        wireguardConfig?: string;
+        message?: string;
+    };
+}
+/**
+ * Delete a VPN client.
+ */
+export interface IReq_DeleteVpnClient extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_DeleteVpnClient> {
+    method: 'deleteVpnClient';
+    request: {
+        identity: authInterfaces.IIdentity;
+        clientId: string;
+    };
+    response: {
+        success: boolean;
+        message?: string;
+    };
+}
+/**
+ * Enable a VPN client.
+ */
+export interface IReq_EnableVpnClient extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_EnableVpnClient> {
+    method: 'enableVpnClient';
+    request: {
+        identity: authInterfaces.IIdentity;
+        clientId: string;
+    };
+    response: {
+        success: boolean;
+        message?: string;
+    };
+}
+/**
+ * Disable a VPN client.
+ */
+export interface IReq_DisableVpnClient extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_DisableVpnClient> {
+    method: 'disableVpnClient';
+    request: {
+        identity: authInterfaces.IIdentity;
+        clientId: string;
+    };
+    response: {
+        success: boolean;
+        message?: string;
+    };
+}
+/**
+ * Rotate a VPN client's keys. Returns the new config bundle.
+ */
+export interface IReq_RotateVpnClientKey extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RotateVpnClientKey> {
+    method: 'rotateVpnClientKey';
+    request: {
+        identity: authInterfaces.IIdentity;
+        clientId: string;
+    };
+    response: {
+        success: boolean;
+        /** WireGuard .conf file content with new keys */
+        wireguardConfig?: string;
+        message?: string;
+    };
+}
+/**
+ * Export a VPN client config.
+ */
+export interface IReq_ExportVpnClientConfig extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ExportVpnClientConfig> {
+    method: 'exportVpnClientConfig';
+    request: {
+        identity: authInterfaces.IIdentity;
+        clientId: string;
+        format: 'smartvpn' | 'wireguard';
+    };
+    response: {
+        success: boolean;
+        config?: string;
+        message?: string;
+    };
+}
+/**
+ * Get telemetry for a specific VPN client.
+ */
+export interface IReq_GetVpnClientTelemetry extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetVpnClientTelemetry> {
+    method: 'getVpnClientTelemetry';
+    request: {
+        identity: authInterfaces.IIdentity;
+        clientId: string;
+    };
+    response: {
+        success: boolean;
+        telemetry?: IVpnClientTelemetry;
+        message?: string;
+    };
+}

package/dist_ts_interfaces/requests/vpn.js

@@ -0,0 +1,3 @@
+import * as plugins from '../plugins.js';
+import * as authInterfaces from '../data/auth.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidnBuLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHNfaW50ZXJmYWNlcy9yZXF1ZXN0cy92cG4udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUM7QUFDekMsT0FBTyxLQUFLLGNBQWMsTUFBTSxpQkFBaUIsQ0FBQyJ9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@serve.zone/dcrouter",
   "private": false,
-  "version": "11.12.4",
+  "version": "11.14.0",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "exports": {
@@ -59,6 +59,7 @@
     "@push.rocks/smartrx": "^3.0.10",
     "@push.rocks/smartstate": "^2.3.0",
     "@push.rocks/smartunique": "^3.0.9",
+    "@push.rocks/smartvpn": "1.12.0",
     "@push.rocks/taskbuffer": "^8.0.2",
     "@serve.zone/catalog": "^2.9.0",
     "@serve.zone/interfaces": "^5.3.0",

package/readme.md

@@ -4,7 +4,7 @@
 
 **dcrouter: The all-in-one gateway for your datacenter.** 🚀
 
-A comprehensive traffic routing solution that provides unified gateway capabilities for HTTP/HTTPS, TCP/SNI, email (SMTP), DNS, RADIUS, and remote edge ingress — all from a single process. Designed for enterprises requiring robust traffic management, automatic TLS certificate provisioning, distributed edge networking, and enterprise-grade email infrastructure.
+A comprehensive traffic routing solution that provides unified gateway capabilities for HTTP/HTTPS, TCP/SNI, email (SMTP), DNS, RADIUS, VPN, and remote edge ingress — all from a single process. Designed for enterprises requiring robust traffic management, automatic TLS certificate provisioning, VPN-based access control, distributed edge networking, and enterprise-grade email infrastructure.
 
 ## Issue Reporting and Security
 
@@ -23,6 +23,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - [DNS Server](#dns-server)
 - [RADIUS Server](#radius-server)
 - [Remote Ingress](#remote-ingress)
+- [VPN Access Control](#vpn-access-control)
 - [Certificate Management](#certificate-management)
 - [Storage & Caching](#storage--caching)
 - [Security Features](#security-features)
@@ -73,6 +74,14 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - **Real-time status monitoring** — connected/disconnected state, public IP, active tunnels, heartbeat tracking
 - **OpsServer dashboard** with enable/disable, edit, secret regeneration, token copy, and delete actions
 
+### 🔐 VPN Access Control (powered by [smartvpn](https://code.foss.global/push.rocks/smartvpn))
+- **WireGuard + native transports** — standard WireGuard clients (iOS, Android, macOS, Windows, Linux) plus custom WebSocket/QUIC tunnels
+- **Route-level VPN gating** — mark any route with `vpn: { required: true }` to restrict access to VPN clients only
+- **Rootless operation** — auto-detects privileges: kernel TUN when running as root, userspace NAT (smoltcp) when not
+- **Client management** — create, enable, disable, rotate keys, export WireGuard `.conf` files via OpsServer API
+- **IP-based enforcement** — VPN clients get IPs from a configurable subnet; SmartProxy enforces `ipAllowList` per route
+- **PROXY protocol v2** — in socket mode, the NAT engine sends PP v2 on outbound connections to preserve VPN client identity
+
 ### ⚡ High Performance
 - **Rust-powered proxy engine** via SmartProxy for maximum throughput
 - **Rust-powered MTA engine** via smartmta (TypeScript + Rust hybrid) for reliable email delivery
@@ -89,7 +98,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 ### 🖥️ OpsServer Dashboard
 - **Web-based management interface** with real-time monitoring
 - **JWT authentication** with session persistence
-- **Live views** for connections, email queues, DNS queries, RADIUS sessions, certificates, remote ingress edges, and security events
+- **Live views** for connections, email queues, DNS queries, RADIUS sessions, certificates, remote ingress edges, VPN clients, and security events
 - **Domain-centric certificate overview** with backoff status and one-click reprovisioning
 - **Remote ingress management** with connection token generation and one-click copy
 - **Read-only configuration display** — DcRouter is configured through code
@@ -248,6 +257,13 @@ const router = new DcRouter({
     hubDomain: 'hub.example.com',
   },
 
+  // VPN — restrict sensitive routes to VPN clients
+  vpnConfig: {
+    enabled: true,
+    serverEndpoint: 'vpn.example.com',
+    wgListenPort: 51820,
+  },
+
   // Persistent storage
   storage: { fsPath: '/var/lib/dcrouter/data' },
 
@@ -276,6 +292,7 @@ graph TB
         DNS[DNS Queries]
         RAD[RADIUS Clients]
         EDGE[Edge Nodes]
+        VPN[VPN Clients]
     end
 
     subgraph "DcRouter Core"
@@ -285,6 +302,7 @@ graph TB
         DS[SmartDNS Server<br/><i>Rust-powered</i>]
         RS[SmartRadius Server]
         RI[RemoteIngress Hub<br/><i>Rust data plane</i>]
+        VS[SmartVPN Server<br/><i>Rust data plane</i>]
         CM[Certificate Manager<br/><i>smartacme v9</i>]
         OS[OpsServer Dashboard]
         MM[Metrics Manager]
@@ -305,12 +323,14 @@ graph TB
     DNS --> DS
     RAD --> RS
     EDGE --> RI
+    VPN --> VS
 
     DC --> SP
     DC --> ES
     DC --> DS
     DC --> RS
     DC --> RI
+    DC --> VS
     DC --> CM
     DC --> OS
     DC --> MM
@@ -428,6 +448,17 @@ interface IDcRouterOptions {
     };
   };
 
+  // ── VPN ───────────────────────────────────────────────────────
+  /** VPN server for route-level access control */
+  vpnConfig?: {
+    enabled?: boolean;                   // default: false
+    subnet?: string;                     // default: '10.8.0.0/24'
+    wgListenPort?: number;               // default: 51820
+    dns?: string[];                      // DNS servers pushed to VPN clients
+    serverEndpoint?: string;             // Hostname in generated client configs
+    forwardingMode?: 'tun' | 'socket';   // default: auto-detect (root → tun, else socket)
+  };
+
   // ── HTTP/3 (QUIC) ────────────────────────────────────────────
   /** HTTP/3 config — enabled by default on qualifying HTTPS routes */
   http3?: {
@@ -975,6 +1006,78 @@ The OpsServer Remote Ingress view provides:
 | **Copy Token** | Generate and copy a base64url connection token to clipboard |
 | **Delete** | Remove the edge registration |
 
+## VPN Access Control
+
+DcRouter integrates [`@push.rocks/smartvpn`](https://code.foss.global/push.rocks/smartvpn) to provide VPN-based route access control. VPN clients connect via standard WireGuard or native WebSocket/QUIC transports, receive an IP from a configurable subnet, and can then access routes that are restricted to VPN-only traffic.
+
+### How It Works
+
+1. **SmartVPN daemon** runs inside dcrouter with a Rust data plane (WireGuard via `boringtun`, custom protocol via Noise IK)
+2. Clients connect and get assigned an IP from the VPN subnet (e.g. `10.8.0.0/24`)
+3. Routes with `vpn: { required: true }` get `security.ipAllowList` automatically injected with the VPN subnet
+4. SmartProxy enforces the allowlist — only VPN-sourced traffic is accepted on those routes
+
+### Two Operating Modes
+
+| Mode | Root Required? | How It Works |
+|------|---------------|-------------|
+| **TUN** (`forwardingMode: 'tun'`) | Yes | Kernel TUN device — VPN traffic enters the network stack with real VPN IPs |
+| **Socket** (`forwardingMode: 'socket'`) | No | Userspace NAT via smoltcp — outbound connections send PROXY protocol v2 to preserve VPN client IPs |
+
+DcRouter auto-detects: if running as root, it uses TUN mode; otherwise, it falls back to socket mode. You can override this with the `forwardingMode` option.
+
+### Configuration
+
+```typescript
+const router = new DcRouter({
+  vpnConfig: {
+    enabled: true,
+    subnet: '10.8.0.0/24',          // VPN client IP pool (default)
+    wgListenPort: 51820,             // WireGuard UDP port (default)
+    serverEndpoint: 'vpn.example.com', // Hostname in generated client configs
+    dns: ['1.1.1.1', '8.8.8.8'],    // DNS servers pushed to clients
+    // forwardingMode: 'socket',     // Override auto-detection
+  },
+  smartProxyConfig: {
+    routes: [
+      // This route is VPN-only — non-VPN clients are blocked
+      {
+        name: 'admin-panel',
+        match: { domains: ['admin.example.com'], ports: [443] },
+        action: {
+          type: 'forward',
+          targets: [{ host: '192.168.1.50', port: 8080 }],
+          tls: { mode: 'terminate', certificate: 'auto' },
+        },
+        vpn: { required: true },  // 🔐 Only VPN clients can access this
+      },
+      // This route is public — anyone can access it
+      {
+        name: 'public-site',
+        match: { domains: ['example.com'], ports: [443] },
+        action: {
+          type: 'forward',
+          targets: [{ host: '192.168.1.10', port: 80 }],
+          tls: { mode: 'terminate', certificate: 'auto' },
+        },
+      },
+    ],
+  },
+});
+```
+
+### Client Management via OpsServer API
+
+Once the VPN server is running, you can manage clients through the OpsServer dashboard or API:
+
+- **Create client** — generates WireGuard keypairs, assigns IP, returns a ready-to-use `.conf` file
+- **Enable / Disable** — toggle client access without deleting
+- **Rotate keys** — generate fresh keypairs (invalidates old ones)
+- **Export config** — re-export in WireGuard or SmartVPN format
+- **Telemetry** — per-client bytes sent/received, keepalives, rate limiting
+
+Standard WireGuard clients on any platform (iOS, Android, macOS, Windows, Linux) can connect using the generated `.conf` file or QR code — no custom VPN software needed.
+
 ## Certificate Management
 
 DcRouter uses [`@push.rocks/smartacme`](https://code.foss.global/push.rocks/smartacme) v9 for ACME certificate provisioning. smartacme v9 brings significant improvements over previous versions:
@@ -1458,6 +1561,7 @@ The container exposes all service ports:
 | 1812, 1813 | UDP | RADIUS auth/acct |
 | 3000 | TCP | OpsServer dashboard |
 | 8443 | TCP | Remote ingress tunnels |
+| 51820 | UDP | WireGuard VPN |
 | 29000–30000 | TCP | Dynamic port range |
 
 ### Building the Image
@@ -1471,7 +1575,7 @@ The Docker build supports multi-platform (`linux/amd64`, `linux/arm64`) via [tsd
 
 ## 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.
+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.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '11.12.4',
+  version: '11.14.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }

package/ts/classes.dcrouter.ts

@@ -22,6 +22,7 @@ import { OpsServer } from './opsserver/index.js';
 import { MetricsManager } from './monitoring/index.js';
 import { RadiusServer, type IRadiusServerConfig } from './radius/index.js';
 import { RemoteIngressManager, TunnelManager } from './remoteingress/index.js';
+import { VpnManager, type IVpnManagerConfig } from './vpn/index.js';
 import { RouteConfigManager, ApiTokenManager } from './config/index.js';
 import { SecurityLogger, ContentScanner, IPReputationChecker } from './security/index.js';
 import { type IHttp3Config, augmentRoutesWithHttp3 } from './http3/index.js';
@@ -188,6 +189,26 @@ export interface IDcRouterOptions {
       keyPath?: string;
     };
   };
+
+  /**
+   * VPN server configuration.
+   * Enables VPN-based access control: routes with vpn.required are only
+   * accessible from VPN clients. Supports WireGuard + native (WS/QUIC) transports.
+   */
+  vpnConfig?: {
+    /** Enable VPN server (default: false) */
+    enabled?: boolean;
+    /** VPN subnet CIDR (default: '10.8.0.0/24') */
+    subnet?: string;
+    /** WireGuard UDP listen port (default: 51820) */
+    wgListenPort?: number;
+    /** DNS servers pushed to VPN clients */
+    dns?: string[];
+    /** Server endpoint hostname for client configs (e.g. 'vpn.example.com') */
+    serverEndpoint?: string;
+    /** Override forwarding mode. Default: auto-detect (tun if root, socket otherwise) */
+    forwardingMode?: 'tun' | 'socket';
+  };
 }
 
 /**
@@ -226,6 +247,9 @@ export class DcRouter {
   public remoteIngressManager?: RemoteIngressManager;
   public tunnelManager?: TunnelManager;
 
+  // VPN
+  public vpnManager?: VpnManager;
+
   // Programmatic config API
   public routeConfigManager?: RouteConfigManager;
   public apiTokenManager?: ApiTokenManager;
@@ -429,6 +453,7 @@ export class DcRouter {
             () => this.getConstructorRoutes(),
             () => this.smartProxy,
             () => this.options.http3,
+            () => this.options.vpnConfig?.enabled ? (this.options.vpnConfig.subnet || '10.8.0.0/24') : undefined,
           );
           this.apiTokenManager = new ApiTokenManager(this.storageManager);
           await this.apiTokenManager.initialize();
@@ -533,6 +558,25 @@ export class DcRouter {
       );
     }
 
+    // VPN Server: optional, depends on SmartProxy
+    if (this.options.vpnConfig?.enabled) {
+      this.serviceManager.addService(
+        new plugins.taskbuffer.Service('VpnServer')
+          .optional()
+          .dependsOn('SmartProxy')
+          .withStart(async () => {
+            await this.setupVpnServer();
+          })
+          .withStop(async () => {
+            if (this.vpnManager) {
+              await this.vpnManager.stop();
+              this.vpnManager = undefined;
+            }
+          })
+          .withRetry({ maxRetries: 3, baseDelayMs: 2000, maxDelayMs: 30_000 }),
+      );
+    }
+
     // Wire up aggregated events for logging
     this.serviceSubjectSubscription = this.serviceManager.serviceSubject.subscribe((event) => {
       const level = event.type === 'failed' ? 'error' : event.type === 'retrying' ? 'warn' : 'info';
@@ -616,6 +660,15 @@ export class DcRouter {
       logger.log('info', `RADIUS Service: auth=${this.options.radiusConfig.authPort || 1812}, acct=${this.options.radiusConfig.acctPort || 1813}, clients=${this.options.radiusConfig.clients?.length || 0}, VLANs=${vlanStats.totalMappings}, accounting=${this.options.radiusConfig.accounting?.enabled ? 'enabled' : 'disabled'}`);
     }
 
+    // VPN summary
+    if (this.vpnManager && this.options.vpnConfig?.enabled) {
+      const subnet = this.vpnManager.getSubnet();
+      const wgPort = this.options.vpnConfig.wgListenPort ?? 51820;
+      const mode = this.vpnManager.forwardingMode;
+      const clientCount = this.vpnManager.listClients().length;
+      logger.log('info', `VPN Service: mode=${mode}, subnet=${subnet}, wg=:${wgPort}, clients=${clientCount}`);
+    }
+
     // Remote Ingress summary
     if (this.tunnelManager && this.options.remoteIngressConfig?.enabled) {
       const edgeCount = this.remoteIngressManager?.getAllEdges().length || 0;
@@ -741,6 +794,11 @@ export class DcRouter {
       logger.log('info', 'HTTP/3: Augmented qualifying HTTPS routes with QUIC/H3 configuration');
     }
 
+    // VPN route security injection: restrict vpn.required routes to VPN subnet
+    if (this.options.vpnConfig?.enabled) {
+      routes = this.injectVpnSecurity(routes);
+    }
+
     // Cache constructor routes for RouteConfigManager
     this.constructorRoutes = [...routes];
 
@@ -892,6 +950,22 @@ export class DcRouter {
         smartProxyConfig.proxyIPs = ['127.0.0.1'];
       }
 
+      // When VPN is in socket mode, the userspace NAT engine sends PP v2 headers
+      // on outbound connections to SmartProxy to preserve VPN client tunnel IPs.
+      if (this.options.vpnConfig?.enabled) {
+        const vpnForwardingMode = this.options.vpnConfig.forwardingMode
+          ?? (process.getuid?.() === 0 ? 'tun' : 'socket');
+        if (vpnForwardingMode === 'socket') {
+          smartProxyConfig.acceptProxyProtocol = true;
+          if (!smartProxyConfig.proxyIPs) {
+            smartProxyConfig.proxyIPs = [];
+          }
+          if (!smartProxyConfig.proxyIPs.includes('127.0.0.1')) {
+            smartProxyConfig.proxyIPs.push('127.0.0.1');
+          }
+        }
+      }
+
       // Create SmartProxy instance
       logger.log('info', `Creating SmartProxy instance: routes=${smartProxyConfig.routes?.length}, acme=${smartProxyConfig.acme?.enabled}, certProvisionFunction=${!!smartProxyConfig.certProvisionFunction}`);
       
@@ -1996,6 +2070,58 @@ export class DcRouter {
     logger.log('info', `Remote Ingress hub started on port ${this.options.remoteIngressConfig.tunnelPort || 8443} with ${edgeCount} registered edge(s)`);
   }
 
+  /**
+   * Set up VPN server for VPN-based route access control.
+   */
+  private async setupVpnServer(): Promise<void> {
+    if (!this.options.vpnConfig?.enabled) {
+      return;
+    }
+
+    logger.log('info', 'Setting up VPN server...');
+
+    this.vpnManager = new VpnManager(this.storageManager, {
+      subnet: this.options.vpnConfig.subnet,
+      wgListenPort: this.options.vpnConfig.wgListenPort,
+      dns: this.options.vpnConfig.dns,
+      serverEndpoint: this.options.vpnConfig.serverEndpoint,
+      forwardingMode: this.options.vpnConfig.forwardingMode,
+    });
+
+    await this.vpnManager.start();
+  }
+
+  /**
+   * Inject VPN security into routes that have vpn.required === true.
+   * Adds the VPN subnet to security.ipAllowList so only VPN clients can access them.
+   */
+  private injectVpnSecurity(routes: plugins.smartproxy.IRouteConfig[]): plugins.smartproxy.IRouteConfig[] {
+    const vpnSubnet = this.options.vpnConfig?.subnet || '10.8.0.0/24';
+    let injectedCount = 0;
+
+    const result = routes.map((route) => {
+      const dcrouterRoute = route as import('../ts_interfaces/data/remoteingress.js').IDcRouterRouteConfig;
+      if (dcrouterRoute.vpn?.required) {
+        injectedCount++;
+        const existing = route.security?.ipAllowList || [];
+        return {
+          ...route,
+          security: {
+            ...route.security,
+            ipAllowList: [...existing, vpnSubnet],
+          },
+        };
+      }
+      return route;
+    });
+
+    if (injectedCount > 0) {
+      logger.log('info', `VPN: Injected ipAllowList (${vpnSubnet}) into ${injectedCount} VPN-protected route(s)`);
+    }
+
+    return result;
+  }
+
   /**
    * Set up RADIUS server for network authentication
    */