feat(vpn): add VPN server management and route-based VPN access control

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
    */