feat(vpn): add tag-based VPN route access control and support configured initial VPN clients

2026-03-30 12:07:58 +00:00
parent 43618abeba
commit eb211348d2
14 changed files with 125 additions and 33 deletions
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@serve.zone/dcrouter',
-  version: '11.14.0',
+  version: '11.15.0',
  description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }
--- a/ts/classes.dcrouter.ts
+++ b/ts/classes.dcrouter.ts
@@ -208,6 +208,12 @@ export interface IDcRouterOptions {
    serverEndpoint?: string;
    /** Override forwarding mode. Default: auto-detect (tun if root, socket otherwise) */
    forwardingMode?: 'tun' | 'socket';
+    /** Pre-defined VPN clients created on startup */
+    clients?: Array<{
+      clientId: string;
+      serverDefinedClientTags?: string[];
+      description?: string;
+    }>;
  };
 }

@@ -453,7 +459,14 @@ 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.options.vpnConfig?.enabled
+              ? (tags?: string[]) => {
+                  if (tags?.length && this.vpnManager) {
+                    return this.vpnManager.getClientIpsForServerDefinedTags(tags);
+                  }
+                  return [this.options.vpnConfig?.subnet || '10.8.0.0/24'];
+                }
+              : undefined,
          );
          this.apiTokenManager = new ApiTokenManager(this.storageManager);
          await this.apiTokenManager.initialize();
@@ -2086,6 +2099,11 @@ export class DcRouter {
      dns: this.options.vpnConfig.dns,
      serverEndpoint: this.options.vpnConfig.serverEndpoint,
      forwardingMode: this.options.vpnConfig.forwardingMode,
+      initialClients: this.options.vpnConfig.clients,
+      onClientChanged: () => {
+        // Re-apply routes so tag-based ipAllowLists get updated
+        this.routeConfigManager?.applyRoutes();
+      },
    });

    await this.vpnManager.start();
@@ -2104,11 +2122,23 @@ export class DcRouter {
      if (dcrouterRoute.vpn?.required) {
        injectedCount++;
        const existing = route.security?.ipAllowList || [];
+
+        let vpnAllowList: string[];
+        if (dcrouterRoute.vpn.allowedServerDefinedClientTags?.length && this.vpnManager) {
+          // Tag-based: only specific client IPs
+          vpnAllowList = this.vpnManager.getClientIpsForServerDefinedTags(
+            dcrouterRoute.vpn.allowedServerDefinedClientTags,
+          );
+        } else {
+          // No tags specified: entire VPN subnet
+          vpnAllowList = [vpnSubnet];
+        }
+
        return {
          ...route,
          security: {
            ...route.security,
-            ipAllowList: [...existing, vpnSubnet],
+            ipAllowList: [...existing, ...vpnAllowList],
          },
        };
      }
@@ -2116,7 +2146,7 @@ export class DcRouter {
    });

    if (injectedCount > 0) {
-      logger.log('info', `VPN: Injected ipAllowList (${vpnSubnet}) into ${injectedCount} VPN-protected route(s)`);
+      logger.log('info', `VPN: Injected ipAllowList into ${injectedCount} VPN-protected route(s)`);
    }

    return result;
--- a/ts/config/classes.route-config-manager.ts
+++ b/ts/config/classes.route-config-manager.ts
@@ -23,7 +23,7 @@ export class RouteConfigManager {
    private getHardcodedRoutes: () => plugins.smartproxy.IRouteConfig[],
    private getSmartProxy: () => plugins.smartproxy.SmartProxy | undefined,
    private getHttp3Config?: () => IHttp3Config | undefined,
-    private getVpnSubnet?: () => string | undefined,
+    private getVpnAllowList?: (tags?: string[]) => string[],
  ) {}

  /**
@@ -246,7 +246,7 @@ export class RouteConfigManager {
  // Private: apply merged routes to SmartProxy
  // =========================================================================

-  private async applyRoutes(): Promise<void> {
+  public async applyRoutes(): Promise<void> {
    const smartProxy = this.getSmartProxy();
    if (!smartProxy) return;

@@ -262,9 +262,9 @@ export class RouteConfigManager {
      enabledRoutes.push(route);
    }

-    // Add enabled programmatic routes (with HTTP/3 augmentation if enabled)
+    // Add enabled programmatic routes (with HTTP/3 and VPN augmentation)
    const http3Config = this.getHttp3Config?.();
-    const vpnSubnet = this.getVpnSubnet?.();
+    const vpnAllowList = this.getVpnAllowList;
    for (const stored of this.storedRoutes.values()) {
      if (stored.enabled) {
        let route = stored.route;
@@ -272,15 +272,16 @@ export class RouteConfigManager {
          route = augmentRouteWithHttp3(route, { enabled: true, ...http3Config });
        }
        // Inject VPN security for programmatic routes with vpn.required
-        if (vpnSubnet) {
+        if (vpnAllowList) {
          const dcRoute = route as IDcRouterRouteConfig;
          if (dcRoute.vpn?.required) {
            const existing = route.security?.ipAllowList || [];
+            const allowList = vpnAllowList(dcRoute.vpn.allowedServerDefinedClientTags);
            route = {
              ...route,
              security: {
                ...route.security,
-                ipAllowList: [...existing, vpnSubnet],
+                ipAllowList: [...existing, ...allowList],
              },
            };
          }
--- a/ts/opsserver/handlers/vpn.handler.ts
+++ b/ts/opsserver/handlers/vpn.handler.ts
@@ -25,7 +25,7 @@ export class VpnHandler {
          const clients = manager.listClients().map((c) => ({
            clientId: c.clientId,
            enabled: c.enabled,
-            tags: c.tags,
+            serverDefinedClientTags: c.serverDefinedClientTags,
            description: c.description,
            assignedIp: c.assignedIp,
            createdAt: c.createdAt,
@@ -89,7 +89,7 @@ export class VpnHandler {
          try {
            const bundle = await manager.createClient({
              clientId: dataArg.clientId,
-              tags: dataArg.tags,
+              serverDefinedClientTags: dataArg.serverDefinedClientTags,
              description: dataArg.description,
            });

@@ -98,7 +98,7 @@ export class VpnHandler {
              client: {
                clientId: bundle.entry.clientId,
                enabled: bundle.entry.enabled ?? true,
-                tags: bundle.entry.tags,
+                serverDefinedClientTags: bundle.entry.serverDefinedClientTags,
                description: bundle.entry.description,
                assignedIp: bundle.entry.assignedIp,
                createdAt: Date.now(),
--- a/ts/vpn/classes.vpn-manager.ts
+++ b/ts/vpn/classes.vpn-manager.ts
@@ -16,6 +16,14 @@ export interface IVpnManagerConfig {
  serverEndpoint?: string;
  /** Override forwarding mode. Default: auto-detect (tun if root, socket otherwise) */
  forwardingMode?: 'tun' | 'socket';
+  /** Pre-defined VPN clients created on startup (idempotent — skips already-persisted clients) */
+  initialClients?: Array<{
+    clientId: string;
+    serverDefinedClientTags?: string[];
+    description?: string;
+  }>;
+  /** Called when clients are created/deleted/toggled — triggers route re-application */
+  onClientChanged?: () => void;
 }

 interface IPersistedServerKeys {
@@ -28,7 +36,7 @@ interface IPersistedServerKeys {
 interface IPersistedClient {
  clientId: string;
  enabled: boolean;
-  tags?: string[];
+  serverDefinedClientTags?: string[];
  description?: string;
  assignedIp?: string;
  noisePublicKey: string;
@@ -36,6 +44,8 @@ interface IPersistedClient {
  createdAt: number;
  updatedAt: number;
  expiresAt?: string;
+  /** @deprecated Legacy field — migrated to serverDefinedClientTags on load */
+  tags?: string[];
 }

 /**
@@ -92,7 +102,7 @@ export class VpnManager {
        publicKey: client.noisePublicKey,
        wgPublicKey: client.wgPublicKey,
        enabled: client.enabled,
-        tags: client.tags,
+        serverDefinedClientTags: client.serverDefinedClientTags,
        description: client.description,
        assignedIp: client.assignedIp,
        expiresAt: client.expiresAt,
@@ -122,6 +132,21 @@ export class VpnManager {
    };

    await this.vpnServer.start(serverConfig);
+
+    // Create initial clients from config (idempotent — skip already-persisted)
+    if (this.config.initialClients) {
+      for (const initial of this.config.initialClients) {
+        if (!this.clients.has(initial.clientId)) {
+          const bundle = await this.createClient({
+            clientId: initial.clientId,
+            serverDefinedClientTags: initial.serverDefinedClientTags,
+            description: initial.description,
+          });
+          logger.log('info', `VPN: Created initial client '${initial.clientId}' (IP: ${bundle.entry.assignedIp})`);
+        }
+      }
+    }
+
    logger.log('info', `VPN server started: mode=${this._forwardingMode}, subnet=${subnet}, wg=:${wgListenPort}, clients=${this.clients.size}`);
  }

@@ -148,7 +173,7 @@ export class VpnManager {
   */
  public async createClient(opts: {
    clientId: string;
-    tags?: string[];
+    serverDefinedClientTags?: string[];
    description?: string;
  }): Promise<plugins.smartvpn.IClientConfigBundle> {
    if (!this.vpnServer) {
@@ -157,7 +182,7 @@ export class VpnManager {

    const bundle = await this.vpnServer.createClient({
      clientId: opts.clientId,
-      tags: opts.tags,
+      serverDefinedClientTags: opts.serverDefinedClientTags,
      description: opts.description,
    });

@@ -174,7 +199,7 @@ export class VpnManager {
    const persisted: IPersistedClient = {
      clientId: bundle.entry.clientId,
      enabled: bundle.entry.enabled ?? true,
-      tags: bundle.entry.tags,
+      serverDefinedClientTags: bundle.entry.serverDefinedClientTags,
      description: bundle.entry.description,
      assignedIp: bundle.entry.assignedIp,
      noisePublicKey: bundle.entry.publicKey,
@@ -186,6 +211,7 @@ export class VpnManager {
    this.clients.set(persisted.clientId, persisted);
    await this.persistClient(persisted);

+    this.config.onClientChanged?.();
    return bundle;
  }

@@ -199,6 +225,7 @@ export class VpnManager {
    await this.vpnServer.removeClient(clientId);
    this.clients.delete(clientId);
    await this.storageManager.delete(`${STORAGE_PREFIX_CLIENTS}${clientId}`);
+    this.config.onClientChanged?.();
  }

  /**
@@ -220,6 +247,7 @@ export class VpnManager {
      client.updatedAt = Date.now();
      await this.persistClient(client);
    }
+    this.config.onClientChanged?.();
  }

  /**
@@ -234,6 +262,7 @@ export class VpnManager {
      client.updatedAt = Date.now();
      await this.persistClient(client);
    }
+    this.config.onClientChanged?.();
  }

  /**
@@ -283,6 +312,22 @@ export class VpnManager {
    return config;
  }

+  // ── Tag-based access control ───────────────────────────────────────────
+
+  /**
+   * Get assigned IPs for all enabled clients matching any of the given server-defined tags.
+   */
+  public getClientIpsForServerDefinedTags(tags: string[]): string[] {
+    const ips: string[] = [];
+    for (const client of this.clients.values()) {
+      if (!client.enabled || !client.assignedIp) continue;
+      if (client.serverDefinedClientTags?.some(t => tags.includes(t))) {
+        ips.push(client.assignedIp);
+      }
+    }
+    return ips;
+  }
+
  // ── Status and telemetry ───────────────────────────────────────────────

  /**
@@ -364,6 +409,12 @@ export class VpnManager {
    for (const key of keys) {
      const client = await this.storageManager.getJSON<IPersistedClient>(key);
      if (client) {
+        // Migrate legacy `tags` → `serverDefinedClientTags`
+        if (!client.serverDefinedClientTags && client.tags) {
+          client.serverDefinedClientTags = client.tags;
+          delete client.tags;
+          await this.persistClient(client);
+        }
        this.clients.set(client.clientId, client);
      }
    }