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

ts/00_commitinfo_data.ts

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

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

ts/config/classes.route-config-manager.ts

@@ -7,6 +7,7 @@ import type {
   IMergedRoute,
   IRouteWarning,
 } from '../../ts_interfaces/data/route-management.js';
+import type { IDcRouterRouteConfig } from '../../ts_interfaces/data/remoteingress.js';
 import { type IHttp3Config, augmentRouteWithHttp3 } from '../http3/index.js';
 
 const ROUTES_PREFIX = '/config-api/routes/';
@@ -22,6 +23,7 @@ export class RouteConfigManager {
     private getHardcodedRoutes: () => plugins.smartproxy.IRouteConfig[],
     private getSmartProxy: () => plugins.smartproxy.SmartProxy | undefined,
     private getHttp3Config?: () => IHttp3Config | undefined,
+    private getVpnSubnet?: () => string | undefined,
   ) {}
 
   /**
@@ -262,13 +264,28 @@ export class RouteConfigManager {
 
     // Add enabled programmatic routes (with HTTP/3 augmentation if enabled)
     const http3Config = this.getHttp3Config?.();
+    const vpnSubnet = this.getVpnSubnet?.();
     for (const stored of this.storedRoutes.values()) {
       if (stored.enabled) {
+        let route = stored.route;
         if (http3Config && http3Config.enabled !== false) {
-          enabledRoutes.push(augmentRouteWithHttp3(stored.route, { enabled: true, ...http3Config }));
-        } else {
-          enabledRoutes.push(stored.route);
+          route = augmentRouteWithHttp3(route, { enabled: true, ...http3Config });
         }
+        // Inject VPN security for programmatic routes with vpn.required
+        if (vpnSubnet) {
+          const dcRoute = route as IDcRouterRouteConfig;
+          if (dcRoute.vpn?.required) {
+            const existing = route.security?.ipAllowList || [];
+            route = {
+              ...route,
+              security: {
+                ...route.security,
+                ipAllowList: [...existing, vpnSubnet],
+              },
+            };
+          }
+        }
+        enabledRoutes.push(route);
       }
     }
 

ts/opsserver/classes.opsserver.ts

@@ -28,6 +28,7 @@ export class OpsServer {
   private remoteIngressHandler!: handlers.RemoteIngressHandler;
   private routeManagementHandler!: handlers.RouteManagementHandler;
   private apiTokenHandler!: handlers.ApiTokenHandler;
+  private vpnHandler!: handlers.VpnHandler;
 
   constructor(dcRouterRefArg: DcRouter) {
     this.dcRouterRef = dcRouterRefArg;
@@ -86,6 +87,7 @@ export class OpsServer {
     this.remoteIngressHandler = new handlers.RemoteIngressHandler(this);
     this.routeManagementHandler = new handlers.RouteManagementHandler(this);
     this.apiTokenHandler = new handlers.ApiTokenHandler(this);
+    this.vpnHandler = new handlers.VpnHandler(this);
 
     console.log('✅ OpsServer TypedRequest handlers initialized');
   }

ts/opsserver/handlers/index.ts

@@ -8,4 +8,5 @@ export * from './email-ops.handler.js';
 export * from './certificate.handler.js';
 export * from './remoteingress.handler.js';
 export * from './route-management.handler.js';
-export * from './api-token.handler.js';
+export * from './api-token.handler.js';
+export * from './vpn.handler.js';

ts/opsserver/handlers/vpn.handler.ts

@@ -0,0 +1,257 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+export class VpnHandler {
+  constructor(private opsServerRef: OpsServer) {
+    this.registerHandlers();
+  }
+
+  private registerHandlers(): void {
+    const viewRouter = this.opsServerRef.viewRouter;
+    const adminRouter = this.opsServerRef.adminRouter;
+
+    // ---- Read endpoints (viewRouter — valid identity required via middleware) ----
+
+    // Get all registered VPN clients
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnClients>(
+        'getVpnClients',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { clients: [] };
+          }
+          const clients = manager.listClients().map((c) => ({
+            clientId: c.clientId,
+            enabled: c.enabled,
+            tags: c.tags,
+            description: c.description,
+            assignedIp: c.assignedIp,
+            createdAt: c.createdAt,
+            updatedAt: c.updatedAt,
+            expiresAt: c.expiresAt,
+          }));
+          return { clients };
+        },
+      ),
+    );
+
+    // Get VPN server status
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnStatus>(
+        'getVpnStatus',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          const vpnConfig = this.opsServerRef.dcRouterRef.options.vpnConfig;
+          if (!manager) {
+            return {
+              status: {
+                running: false,
+                forwardingMode: 'socket' as const,
+                subnet: vpnConfig?.subnet || '10.8.0.0/24',
+                wgListenPort: vpnConfig?.wgListenPort ?? 51820,
+                serverPublicKeys: null,
+                registeredClients: 0,
+                connectedClients: 0,
+              },
+            };
+          }
+
+          const connected = await manager.getConnectedClients();
+          return {
+            status: {
+              running: manager.running,
+              forwardingMode: manager.forwardingMode,
+              subnet: manager.getSubnet(),
+              wgListenPort: vpnConfig?.wgListenPort ?? 51820,
+              serverPublicKeys: manager.getServerPublicKeys(),
+              registeredClients: manager.listClients().length,
+              connectedClients: connected.length,
+            },
+          };
+        },
+      ),
+    );
+
+    // ---- Write endpoints (adminRouter — admin identity required via middleware) ----
+
+    // Create a new VPN client
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateVpnClient>(
+        'createVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            const bundle = await manager.createClient({
+              clientId: dataArg.clientId,
+              tags: dataArg.tags,
+              description: dataArg.description,
+            });
+
+            return {
+              success: true,
+              client: {
+                clientId: bundle.entry.clientId,
+                enabled: bundle.entry.enabled ?? true,
+                tags: bundle.entry.tags,
+                description: bundle.entry.description,
+                assignedIp: bundle.entry.assignedIp,
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+                expiresAt: bundle.entry.expiresAt,
+              },
+              wireguardConfig: bundle.wireguardConfig,
+            };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Delete a VPN client
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteVpnClient>(
+        'deleteVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            await manager.removeClient(dataArg.clientId);
+            return { success: true };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Enable a VPN client
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_EnableVpnClient>(
+        'enableVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            await manager.enableClient(dataArg.clientId);
+            return { success: true };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Disable a VPN client
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DisableVpnClient>(
+        'disableVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            await manager.disableClient(dataArg.clientId);
+            return { success: true };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Rotate a VPN client's keys
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RotateVpnClientKey>(
+        'rotateVpnClientKey',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            const bundle = await manager.rotateClientKey(dataArg.clientId);
+            return {
+              success: true,
+              wireguardConfig: bundle.wireguardConfig,
+            };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Export a VPN client config
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ExportVpnClientConfig>(
+        'exportVpnClientConfig',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            const config = await manager.exportClientConfig(dataArg.clientId, dataArg.format);
+            return { success: true, config };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+
+    // Get telemetry for a specific VPN client
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnClientTelemetry>(
+        'getVpnClientTelemetry',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            const telemetry = await manager.getClientTelemetry(dataArg.clientId);
+            if (!telemetry) {
+              return { success: false, message: 'Client not found or not connected' };
+            }
+            return {
+              success: true,
+              telemetry: {
+                clientId: telemetry.clientId,
+                assignedIp: telemetry.assignedIp,
+                bytesSent: telemetry.bytesSent,
+                bytesReceived: telemetry.bytesReceived,
+                packetsDropped: telemetry.packetsDropped,
+                bytesDropped: telemetry.bytesDropped,
+                lastKeepaliveAt: telemetry.lastKeepaliveAt,
+                keepalivesReceived: telemetry.keepalivesReceived,
+                rateLimitBytesPerSec: telemetry.rateLimitBytesPerSec,
+                burstBytes: telemetry.burstBytes,
+              },
+            };
+          } catch (err: unknown) {
+            return { success: false, message: (err as Error).message };
+          }
+        },
+      ),
+    );
+  }
+}

ts/plugins.ts

@@ -58,13 +58,14 @@ import * as smartnetwork from '@push.rocks/smartnetwork';
 import * as smartpath from '@push.rocks/smartpath';
 import * as smartproxy from '@push.rocks/smartproxy';
 import * as smartpromise from '@push.rocks/smartpromise';
+import * as smartvpn from '@push.rocks/smartvpn';
 import * as smartradius from '@push.rocks/smartradius';
 import * as smartrequest from '@push.rocks/smartrequest';
 import * as smartrx from '@push.rocks/smartrx';
 import * as smartunique from '@push.rocks/smartunique';
 import * as taskbuffer from '@push.rocks/taskbuffer';
 
-export { projectinfo, qenv, smartacme, smartdata, smartdns, smartfs, smartguard, smartjwt, smartlog, smartmetrics, smartdb, smartmta, smartnetwork, smartpath, smartproxy, smartpromise, smartradius, smartrequest, smartrx, smartunique, taskbuffer };
+export { projectinfo, qenv, smartacme, smartdata, smartdns, smartfs, smartguard, smartjwt, smartlog, smartmetrics, smartdb, smartmta, smartnetwork, smartpath, smartproxy, smartpromise, smartradius, smartrequest, smartrx, smartunique, smartvpn, taskbuffer };
 
 // Define SmartLog types for use in error handling
 export type TLogLevel = 'error' | 'warn' | 'info' | 'success' | 'debug';

ts/vpn/classes.vpn-manager.ts

@@ -0,0 +1,378 @@
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import type { StorageManager } from '../storage/classes.storagemanager.js';
+
+const STORAGE_PREFIX_KEYS = '/vpn/server-keys';
+const STORAGE_PREFIX_CLIENTS = '/vpn/clients/';
+
+export interface IVpnManagerConfig {
+  /** 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';
+}
+
+interface IPersistedServerKeys {
+  noisePrivateKey: string;
+  noisePublicKey: string;
+  wgPrivateKey: string;
+  wgPublicKey: string;
+}
+
+interface IPersistedClient {
+  clientId: string;
+  enabled: boolean;
+  tags?: string[];
+  description?: string;
+  assignedIp?: string;
+  noisePublicKey: string;
+  wgPublicKey: string;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt?: string;
+}
+
+/**
+ * Manages the SmartVPN server lifecycle and VPN client CRUD.
+ * Persists server keys and client registrations via StorageManager.
+ */
+export class VpnManager {
+  private storageManager: StorageManager;
+  private config: IVpnManagerConfig;
+  private vpnServer?: plugins.smartvpn.VpnServer;
+  private clients: Map<string, IPersistedClient> = new Map();
+  private serverKeys?: IPersistedServerKeys;
+  private _forwardingMode: 'tun' | 'socket';
+
+  constructor(storageManager: StorageManager, config: IVpnManagerConfig) {
+    this.storageManager = storageManager;
+    this.config = config;
+    // Auto-detect forwarding mode: tun if root, socket otherwise
+    this._forwardingMode = config.forwardingMode
+      ?? (process.getuid?.() === 0 ? 'tun' : 'socket');
+  }
+
+  /** The effective forwarding mode (tun or socket). */
+  public get forwardingMode(): 'tun' | 'socket' {
+    return this._forwardingMode;
+  }
+
+  /** The VPN subnet CIDR. */
+  public getSubnet(): string {
+    return this.config.subnet || '10.8.0.0/24';
+  }
+
+  /** Whether the VPN server is running. */
+  public get running(): boolean {
+    return this.vpnServer?.running ?? false;
+  }
+
+  /**
+   * Start the VPN server.
+   * Loads or generates server keys, loads persisted clients, starts VpnServer.
+   */
+  public async start(): Promise<void> {
+    // Load or generate server keys
+    this.serverKeys = await this.loadOrGenerateServerKeys();
+
+    // Load persisted clients
+    await this.loadPersistedClients();
+
+    // Build client entries for the daemon
+    const clientEntries: plugins.smartvpn.IClientEntry[] = [];
+    for (const client of this.clients.values()) {
+      clientEntries.push({
+        clientId: client.clientId,
+        publicKey: client.noisePublicKey,
+        wgPublicKey: client.wgPublicKey,
+        enabled: client.enabled,
+        tags: client.tags,
+        description: client.description,
+        assignedIp: client.assignedIp,
+        expiresAt: client.expiresAt,
+      });
+    }
+
+    const subnet = this.getSubnet();
+    const wgListenPort = this.config.wgListenPort ?? 51820;
+
+    // Create and start VpnServer
+    this.vpnServer = new plugins.smartvpn.VpnServer({
+      transport: { transport: 'stdio' },
+    });
+
+    const serverConfig: plugins.smartvpn.IVpnServerConfig = {
+      listenAddr: '0.0.0.0:0', // WS listener not strictly needed but required field
+      privateKey: this.serverKeys.noisePrivateKey,
+      publicKey: this.serverKeys.noisePublicKey,
+      subnet,
+      dns: this.config.dns,
+      forwardingMode: this._forwardingMode,
+      transportMode: 'all',
+      wgPrivateKey: this.serverKeys.wgPrivateKey,
+      wgListenPort,
+      clients: clientEntries,
+      socketForwardProxyProtocol: this._forwardingMode === 'socket',
+    };
+
+    await this.vpnServer.start(serverConfig);
+    logger.log('info', `VPN server started: mode=${this._forwardingMode}, subnet=${subnet}, wg=:${wgListenPort}, clients=${this.clients.size}`);
+  }
+
+  /**
+   * Stop the VPN server.
+   */
+  public async stop(): Promise<void> {
+    if (this.vpnServer) {
+      try {
+        await this.vpnServer.stopServer();
+      } catch {
+        // Ignore stop errors
+      }
+      this.vpnServer.stop();
+      this.vpnServer = undefined;
+    }
+    logger.log('info', 'VPN server stopped');
+  }
+
+  // ── Client CRUD ────────────────────────────────────────────────────────
+
+  /**
+   * Create a new VPN client. Returns the config bundle (secrets only shown once).
+   */
+  public async createClient(opts: {
+    clientId: string;
+    tags?: string[];
+    description?: string;
+  }): Promise<plugins.smartvpn.IClientConfigBundle> {
+    if (!this.vpnServer) {
+      throw new Error('VPN server not running');
+    }
+
+    const bundle = await this.vpnServer.createClient({
+      clientId: opts.clientId,
+      tags: opts.tags,
+      description: opts.description,
+    });
+
+    // Update WireGuard config endpoint if serverEndpoint is configured
+    if (this.config.serverEndpoint && bundle.wireguardConfig) {
+      const wgPort = this.config.wgListenPort ?? 51820;
+      bundle.wireguardConfig = bundle.wireguardConfig.replace(
+        /Endpoint\s*=\s*.+/,
+        `Endpoint = ${this.config.serverEndpoint}:${wgPort}`,
+      );
+    }
+
+    // Persist client entry (without private keys)
+    const persisted: IPersistedClient = {
+      clientId: bundle.entry.clientId,
+      enabled: bundle.entry.enabled ?? true,
+      tags: bundle.entry.tags,
+      description: bundle.entry.description,
+      assignedIp: bundle.entry.assignedIp,
+      noisePublicKey: bundle.entry.publicKey,
+      wgPublicKey: bundle.entry.wgPublicKey || '',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      expiresAt: bundle.entry.expiresAt,
+    };
+    this.clients.set(persisted.clientId, persisted);
+    await this.persistClient(persisted);
+
+    return bundle;
+  }
+
+  /**
+   * Remove a VPN client.
+   */
+  public async removeClient(clientId: string): Promise<void> {
+    if (!this.vpnServer) {
+      throw new Error('VPN server not running');
+    }
+    await this.vpnServer.removeClient(clientId);
+    this.clients.delete(clientId);
+    await this.storageManager.delete(`${STORAGE_PREFIX_CLIENTS}${clientId}`);
+  }
+
+  /**
+   * List all registered clients (without secrets).
+   */
+  public listClients(): IPersistedClient[] {
+    return [...this.clients.values()];
+  }
+
+  /**
+   * Enable a client.
+   */
+  public async enableClient(clientId: string): Promise<void> {
+    if (!this.vpnServer) throw new Error('VPN server not running');
+    await this.vpnServer.enableClient(clientId);
+    const client = this.clients.get(clientId);
+    if (client) {
+      client.enabled = true;
+      client.updatedAt = Date.now();
+      await this.persistClient(client);
+    }
+  }
+
+  /**
+   * Disable a client.
+   */
+  public async disableClient(clientId: string): Promise<void> {
+    if (!this.vpnServer) throw new Error('VPN server not running');
+    await this.vpnServer.disableClient(clientId);
+    const client = this.clients.get(clientId);
+    if (client) {
+      client.enabled = false;
+      client.updatedAt = Date.now();
+      await this.persistClient(client);
+    }
+  }
+
+  /**
+   * Rotate a client's keys. Returns the new config bundle.
+   */
+  public async rotateClientKey(clientId: string): Promise<plugins.smartvpn.IClientConfigBundle> {
+    if (!this.vpnServer) throw new Error('VPN server not running');
+    const bundle = await this.vpnServer.rotateClientKey(clientId);
+
+    // Update endpoint in WireGuard config
+    if (this.config.serverEndpoint && bundle.wireguardConfig) {
+      const wgPort = this.config.wgListenPort ?? 51820;
+      bundle.wireguardConfig = bundle.wireguardConfig.replace(
+        /Endpoint\s*=\s*.+/,
+        `Endpoint = ${this.config.serverEndpoint}:${wgPort}`,
+      );
+    }
+
+    // Update persisted entry with new public keys
+    const client = this.clients.get(clientId);
+    if (client) {
+      client.noisePublicKey = bundle.entry.publicKey;
+      client.wgPublicKey = bundle.entry.wgPublicKey || '';
+      client.updatedAt = Date.now();
+      await this.persistClient(client);
+    }
+
+    return bundle;
+  }
+
+  /**
+   * Export a client config (without secrets).
+   */
+  public async exportClientConfig(clientId: string, format: 'smartvpn' | 'wireguard'): Promise<string> {
+    if (!this.vpnServer) throw new Error('VPN server not running');
+    let config = await this.vpnServer.exportClientConfig(clientId, format);
+
+    // Update endpoint in WireGuard config
+    if (format === 'wireguard' && this.config.serverEndpoint) {
+      const wgPort = this.config.wgListenPort ?? 51820;
+      config = config.replace(
+        /Endpoint\s*=\s*.+/,
+        `Endpoint = ${this.config.serverEndpoint}:${wgPort}`,
+      );
+    }
+
+    return config;
+  }
+
+  // ── Status and telemetry ───────────────────────────────────────────────
+
+  /**
+   * Get server status.
+   */
+  public async getStatus(): Promise<plugins.smartvpn.IVpnStatus | null> {
+    if (!this.vpnServer) return null;
+    return this.vpnServer.getStatus();
+  }
+
+  /**
+   * Get server statistics.
+   */
+  public async getStatistics(): Promise<plugins.smartvpn.IVpnServerStatistics | null> {
+    if (!this.vpnServer) return null;
+    return this.vpnServer.getStatistics();
+  }
+
+  /**
+   * List currently connected clients.
+   */
+  public async getConnectedClients(): Promise<plugins.smartvpn.IVpnClientInfo[]> {
+    if (!this.vpnServer) return [];
+    return this.vpnServer.listClients();
+  }
+
+  /**
+   * Get telemetry for a specific client.
+   */
+  public async getClientTelemetry(clientId: string): Promise<plugins.smartvpn.IVpnClientTelemetry | null> {
+    if (!this.vpnServer) return null;
+    return this.vpnServer.getClientTelemetry(clientId);
+  }
+
+  /**
+   * Get server public keys (for display/info).
+   */
+  public getServerPublicKeys(): { noisePublicKey: string; wgPublicKey: string } | null {
+    if (!this.serverKeys) return null;
+    return {
+      noisePublicKey: this.serverKeys.noisePublicKey,
+      wgPublicKey: this.serverKeys.wgPublicKey,
+    };
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────
+
+  private async loadOrGenerateServerKeys(): Promise<IPersistedServerKeys> {
+    const stored = await this.storageManager.getJSON<IPersistedServerKeys>(STORAGE_PREFIX_KEYS);
+    if (stored?.noisePrivateKey && stored?.wgPrivateKey) {
+      logger.log('info', 'Loaded VPN server keys from storage');
+      return stored;
+    }
+
+    // Generate new keys via the daemon
+    const tempServer = new plugins.smartvpn.VpnServer({
+      transport: { transport: 'stdio' },
+    });
+    await tempServer.start();
+
+    const noiseKeys = await tempServer.generateKeypair();
+    const wgKeys = await tempServer.generateWgKeypair();
+    tempServer.stop();
+
+    const keys: IPersistedServerKeys = {
+      noisePrivateKey: noiseKeys.privateKey,
+      noisePublicKey: noiseKeys.publicKey,
+      wgPrivateKey: wgKeys.privateKey,
+      wgPublicKey: wgKeys.publicKey,
+    };
+
+    await this.storageManager.setJSON(STORAGE_PREFIX_KEYS, keys);
+    logger.log('info', 'Generated and persisted new VPN server keys');
+    return keys;
+  }
+
+  private async loadPersistedClients(): Promise<void> {
+    const keys = await this.storageManager.list(STORAGE_PREFIX_CLIENTS);
+    for (const key of keys) {
+      const client = await this.storageManager.getJSON<IPersistedClient>(key);
+      if (client) {
+        this.clients.set(client.clientId, client);
+      }
+    }
+    if (this.clients.size > 0) {
+      logger.log('info', `Loaded ${this.clients.size} persisted VPN client(s)`);
+    }
+  }
+
+  private async persistClient(client: IPersistedClient): Promise<void> {
+    await this.storageManager.setJSON(`${STORAGE_PREFIX_CLIENTS}${client.clientId}`, client);
+  }
+}

ts/vpn/index.ts

@@ -0,0 +1 @@
+export * from './classes.vpn-manager.js';