v11.23.4

changelog.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 2026-03-31 - 11.23.4 - fix(deps)
+bump @push.rocks/smartvpn to 1.17.1
+
+- Updates the @push.rocks/smartvpn dependency from 1.16.5 to 1.17.1.
+
+## 2026-03-31 - 11.23.3 - fix(ts_web)
+update appstate to import interfaces from source TypeScript module path
+
+- Replaces the appstate interfaces import from ../dist_ts_interfaces/index.js with ../ts_interfaces/index.js.
+- Aligns the web app state module with the source interface location instead of the built distribution path.
+
+## 2026-03-31 - 11.23.2 - fix(repo)
+no changes to commit
+
+
+## 2026-03-31 - 11.23.1 - fix(repo)
+no changes to commit
+
+
+## 2026-03-31 - 11.23.0 - feat(vpn)
+support optional non-mandatory VPN route access and align route config with enabled semantics
+
+- rename route VPN configuration from `required` to `enabled` across code, docs, and examples
+- add `vpn.mandatory` to control whether VPN allowlists replace or extend existing `security.ipAllowList` rules
+- improve VPN client status matching in the ops view by falling back to assigned IP when client IDs differ
+
+## 2026-03-31 - 11.22.0 - feat(vpn)
+add VPN client editing and connected client visibility in ops server
+
+- Adds API support to list currently connected VPN clients and update client metadata without rotating keys
+- Updates the web VPN view to show live connection status, client detail telemetry, and separate enable/disable actions
+- Refreshes documentation for smart split tunnel behavior, QR code setup/export, and storage architecture
+- Bumps @push.rocks/smartvpn from 1.16.4 to 1.16.5
+
+## 2026-03-31 - 11.21.5 - fix(routing)
+apply VPN route allowlists dynamically after VPN clients load
+
+- Moves VPN security injection for hardcoded and programmatic routes into RouteConfigManager.applyRoutes() so allowlists are generated from current VPN client state.
+- Re-applies routes after starting the VPN manager to ensure tag-based ipAllowLists are available once VPN clients are loaded.
+- Avoids caching constructor routes with stale VPN security baked in while preserving HTTP/3 route augmentation.
+
+## 2026-03-31 - 11.21.4 - fix(deps)
+bump @push.rocks/smartvpn to 1.16.4
+
+- Updates the @push.rocks/smartvpn dependency from 1.16.3 to 1.16.4 in package.json.
+
+## 2026-03-31 - 11.21.3 - fix(deps)
+bump @push.rocks/smartvpn to 1.16.3
+
+- Updates the @push.rocks/smartvpn dependency from 1.16.2 to 1.16.3.
+
+## 2026-03-31 - 11.21.2 - fix(deps)
+bump @push.rocks/smartvpn to 1.16.2
+
+- Updates the @push.rocks/smartvpn dependency from 1.16.1 to 1.16.2 in package.json.
+
+## 2026-03-31 - 11.21.1 - fix(vpn)
+resolve VPN-gated route domains into per-client AllowedIPs with cached DNS lookups
+
+- Derive WireGuard AllowedIPs from DNS A records of matched vpn.required route domains instead of only configured public proxy IPs.
+- Cache resolved domain IPs for 5 minutes and fall back to stale results on DNS lookup failures.
+- Make per-client AllowedIPs generation asynchronous throughout VPN config export and regeneration flows.
+
 ## 2026-03-31 - 11.21.0 - feat(vpn)
 add tag-aware WireGuard AllowedIPs for VPN-gated routes
 

package.json

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

pnpm-lock.yaml

@@ -96,8 +96,8 @@ importers:
         specifier: ^3.0.9
         version: 3.0.9
       '@push.rocks/smartvpn':
-        specifier: 1.16.1
-        version: 1.16.1
+        specifier: 1.17.1
+        version: 1.17.1
       '@push.rocks/taskbuffer':
         specifier: ^8.0.2
         version: 8.0.2
@@ -1339,8 +1339,8 @@ packages:
   '@push.rocks/smartversion@3.0.5':
     resolution: {integrity: sha512-8MZSo1yqyaKxKq0Q5N188l4un++9GFWVbhCAX5mXJwewZHn97ujffTeL+eOQYpWFTEpUhaq1QhL4NhqObBCt1Q==}
 
-  '@push.rocks/smartvpn@1.16.1':
-    resolution: {integrity: sha512-LQzt3ajMKIs3anYki/3drt7XcCuekoKvApCltLEjsoGEEX5JkXGSZFB+UFvqEhG8NcEuHw574rU3tB2orHzKTQ==}
+  '@push.rocks/smartvpn@1.17.1':
+    resolution: {integrity: sha512-oTOxNUrh+doL9AocgPnMbcYZKrWJhCeuqNotu1RfiteIV9DDdznvA+cl3nOgxD/ImUYrFPz6PUp5BEMogWcS8Q==}
 
   '@push.rocks/smartwatch@6.4.0':
     resolution: {integrity: sha512-KDswRgE/siBmZRCsRA07MtW5oF4c9uQEBkwTGPIWneHzksbCDsvs/7agKFEL7WnNifLNwo8w1K1qoiVWkX1fvw==}
@@ -6622,7 +6622,7 @@ snapshots:
       '@types/semver': 7.7.1
       semver: 7.7.4
 
-  '@push.rocks/smartvpn@1.16.1':
+  '@push.rocks/smartvpn@1.17.1':
     dependencies:
       '@push.rocks/smartnftables': 1.1.0
       '@push.rocks/smartpath': 6.0.0

readme.md

@@ -76,7 +76,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ### 🔐 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
+- **Route-level VPN gating** — mark any route with `vpn: { enabled: true }` to restrict access to VPN clients only, or `vpn: { enabled: true, mandatory: false }` to add VPN clients alongside existing access rules
 - **Tag-based access control** — assign `serverDefinedClientTags` to clients and restrict routes with `allowedServerDefinedClientTags`
 - **Constructor-defined clients** — pre-define VPN clients with tags in config for declarative, code-driven setup
 - **Rootless operation** — uses userspace NAT (smoltcp) with no root required
@@ -1030,8 +1030,8 @@ DcRouter integrates [`@push.rocks/smartvpn`](https://code.foss.global/push.rocks
 
 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. **Split tunnel** by default — generated WireGuard configs only route VPN subnet traffic through the tunnel (`AllowedIPs = 10.8.0.0/24`), so regular internet traffic stays direct
-4. Routes with `vpn: { required: true }` get `security.ipAllowList` automatically injected
+3. **Smart split tunnel** — generated WireGuard configs auto-include the VPN subnet plus DNS-resolved IPs of VPN-gated domains. Domains from routes with `vpn.enabled` are resolved at config generation time, so clients route only the necessary traffic through the tunnel
+4. Routes with `vpn: { enabled: true }` get `security.ipAllowList` dynamically injected (re-computed on every client change). With `mandatory: true` (default), the allowlist is replaced; with `mandatory: false`, VPN IPs are appended to existing rules
 5. When `allowedServerDefinedClientTags` is set, only matching client IPs are injected (not the whole subnet)
 6. SmartProxy enforces the allowlist — only authorized VPN clients can access protected routes
 7. All VPN traffic is forced through SmartProxy via userspace NAT with PROXY protocol v2 — no root required
@@ -1091,7 +1091,7 @@ const router = new DcRouter({
           targets: [{ host: '192.168.1.50', port: 8080 }],
           tls: { mode: 'terminate', certificate: 'auto' },
         },
-        vpn: { required: true },
+        vpn: { enabled: true },
       },
       // 🔐 VPN + tag-restricted: only 'engineering' tagged clients
       {
@@ -1102,10 +1102,10 @@ const router = new DcRouter({
           targets: [{ host: '192.168.1.51', port: 8080 }],
           tls: { mode: 'terminate', certificate: 'auto' },
         },
-        vpn: { required: true, allowedServerDefinedClientTags: ['engineering'] },
+        vpn: { enabled: true, allowedServerDefinedClientTags: ['engineering'] },
         // → alice + bob can access, carol cannot
       },
-      // 🌐 Public: no VPN required
+      // 🌐 Public: no VPN
       {
         name: 'public-site',
         match: { domains: ['example.com'], ports: [443] },
@@ -1136,13 +1136,14 @@ Routes with `allowedServerDefinedClientTags` only permit VPN clients whose admin
 The OpsServer dashboard and API provide full VPN client lifecycle management:
 
 - **Create client** — generates WireGuard keypairs, assigns IP, returns a ready-to-use `.conf` file
+- **QR code** — scan with the WireGuard mobile app (iOS/Android) for instant setup
 - **Enable / Disable** — toggle client access without deleting
 - **Rotate keys** — generate fresh keypairs (invalidates old ones)
-- **Export config** — download in WireGuard (`.conf`) or SmartVPN (`.json`) format
+- **Export config** — download in WireGuard (`.conf`), SmartVPN (`.json`), or scan as QR code
 - **Telemetry** — per-client bytes sent/received, keepalives, rate limiting
 - **Delete** — remove a client and revoke access
 
-Standard WireGuard clients on any platform (iOS, Android, macOS, Windows, Linux) can connect using the generated `.conf` file — no custom VPN software needed.
+Standard WireGuard clients on any platform (iOS, Android, macOS, Windows, Linux) can connect using the generated `.conf` file or by scanning the QR code — no custom VPN software needed.
 
 ## Certificate Management
 

readme.storage.md

@@ -0,0 +1,120 @@
+# DCRouter Storage Overview
+
+DCRouter uses two complementary storage systems: **StorageManager** for configuration and state, and **CacheDb** for time-limited cached data.
+
+## StorageManager (Key-Value Store)
+
+A lightweight, pluggable key-value store for configuration, credentials, and runtime state. Data is persisted as flat JSON files on disk by default.
+
+### Default Path
+
+```
+~/.serve.zone/dcrouter/storage/
+```
+
+Configurable via `options.storage.fsPath` or `options.baseDir`.
+
+### Backends
+
+```typescript
+// Filesystem (default)
+storage: { fsPath: '/var/lib/dcrouter/data' }
+
+// Custom (Redis, S3, etc.)
+storage: {
+  readFunction: async (key) => await redis.get(key),
+  writeFunction: async (key, value) => await redis.set(key, value),
+}
+
+// In-memory (omit storage config — data lost on restart)
+```
+
+### What's Stored
+
+| Prefix | Contents | Managed By |
+|--------|----------|------------|
+| `/vpn/server-keys` | VPN server Noise + WireGuard keypairs | `VpnManager` |
+| `/vpn/clients/{clientId}` | VPN client registrations (keys, tags, description, assigned IP) | `VpnManager` |
+| `/config-api/routes/{uuid}.json` | Programmatic routes (created via OpsServer API) | `RouteConfigManager` |
+| `/config-api/tokens/{uuid}.json` | API tokens (hashed secrets, scopes, expiry) | `ApiTokenManager` |
+| `/config-api/overrides/{routeName}.json` | Hardcoded route overrides (enable/disable) | `RouteConfigManager` |
+| `/email/bounces/suppression-list.json` | Email bounce suppression list | `smartmta` |
+| `/certs/*` | TLS certificates and ACME state | `SmartAcme` (via `StorageBackedCertManager`) |
+
+### API
+
+```typescript
+// Read/write JSON
+await storageManager.getJSON<T>(key);
+await storageManager.setJSON(key, value);
+
+// Raw string read/write
+await storageManager.get(key);
+await storageManager.set(key, value);
+
+// List keys by prefix
+await storageManager.list('/vpn/clients/');
+
+// Delete
+await storageManager.delete(key);
+```
+
+## CacheDb (Embedded MongoDB)
+
+An embedded MongoDB-compatible database (via `@push.rocks/smartdb` + `@push.rocks/smartdata`) for cached data with automatic TTL-based cleanup.
+
+### Default Path
+
+```
+~/.serve.zone/dcrouter/tsmdb/
+```
+
+Configurable via `options.cacheConfig.storagePath`.
+
+### What's Cached
+
+| Document Type | Default TTL | Purpose |
+|--------------|-------------|---------|
+| `CachedEmail` | 30 days | Email metadata cache for dashboard display |
+| `CachedIPReputation` | 1 day | IP reputation lookup results (DNSBL checks) |
+
+### Configuration
+
+```typescript
+cacheConfig: {
+  enabled: true,                                    // default: true
+  storagePath: '~/.serve.zone/dcrouter/tsmdb',     // default
+  dbName: 'dcrouter',                               // default
+  cleanupIntervalHours: 1,                          // how often to purge expired records
+  ttlConfig: {
+    emails: 30,          // days
+    ipReputation: 1,     // days
+    bounces: 30,         // days (reserved)
+    dkimKeys: 90,        // days (reserved)
+    suppression: 30,     // days (reserved)
+  },
+}
+```
+
+### How It Works
+
+1. `CacheDb` starts a `LocalSmartDb` instance (embedded MongoDB process)
+2. `smartdata` connects to it via Unix socket
+3. Document classes (`CachedEmail`, `CachedIPReputation`) are decorated with `@Collection` and use `smartdata` ORM
+4. `CacheCleaner` runs on a timer, purging records older than their configured TTL
+
+### Disabling
+
+For development or lightweight deployments, disable the cache to avoid starting a MongoDB process:
+
+```typescript
+cacheConfig: { enabled: false }
+```
+
+## When to Use Which
+
+| Use Case | System | Why |
+|----------|--------|-----|
+| VPN keys, API tokens, routes, certs | **StorageManager** | Small JSON blobs, key-value access, no queries needed |
+| Email metadata, IP reputation | **CacheDb** | Time-series data, TTL expiry, potential for queries/aggregation |
+| Runtime state (connected clients, metrics) | **Neither** | In-memory only, rebuilt on startup |

test_watch/devserver.ts

@@ -29,13 +29,13 @@ const devRouter = new DcRouter({
         name: 'vpn-internal-app',
         match: { ports: [18080], domains: ['internal.example.com'] },
         action: { type: 'forward', targets: [{ host: 'localhost', port: 5000 }] },
-        vpn: { required: true },
+        vpn: { enabled: true },
       },
       {
         name: 'vpn-eng-dashboard',
         match: { ports: [18080], domains: ['eng.example.com'] },
         action: { type: 'forward', targets: [{ host: 'localhost', port: 5001 }] },
-        vpn: { required: true, allowedServerDefinedClientTags: ['engineering'] },
+        vpn: { enabled: true, allowedServerDefinedClientTags: ['engineering'] },
       },
     ] as any[],
   },

ts/00_commitinfo_data.ts

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

ts/classes.dcrouter.ts

@@ -192,7 +192,7 @@ export interface IDcRouterOptions {
 
   /**
    * VPN server configuration.
-   * Enables VPN-based access control: routes with vpn.required are only
+   * Enables VPN-based access control: routes with vpn.enabled are only
    * accessible from VPN clients. Supports WireGuard + native (WS/QUIC) transports.
    */
   vpnConfig?: {
@@ -813,12 +813,8 @@ 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
+    // Cache constructor routes for RouteConfigManager (without VPN security baked in —
+    // applyRoutes() injects VPN security dynamically so it stays current with client changes)
     this.constructorRoutes = [...routes];
 
     // If we have routes or need a basic SmartProxy instance, create it
@@ -2105,34 +2101,35 @@ export class DcRouter {
         // Re-apply routes so tag-based ipAllowLists get updated
         this.routeConfigManager?.applyRoutes();
       },
-      getClientAllowedIPs: (clientTags: string[]) => {
+      getClientAllowedIPs: async (clientTags: string[]) => {
         const subnet = this.options.vpnConfig?.subnet || '10.8.0.0/24';
         const ips = new Set<string>([subnet]);
 
-        // Determine the server's public-facing IP(s) that VPN-gated domains resolve to
-        const publicIPs: string[] = [];
-        if (this.options.proxyIps?.length) {
-          publicIPs.push(...this.options.proxyIps);
-        }
-        if (this.options.publicIp) {
-          publicIPs.push(this.options.publicIp);
-        } else if (this.detectedPublicIp) {
-          publicIPs.push(this.detectedPublicIp);
-        }
-        if (!publicIPs.length) return [...ips];
-
-        // Check routes for VPN-gated tag match
+        // Check routes for VPN-gated tag match and collect domains
         const routes = this.options.smartProxyConfig?.routes || [];
+        const domainsToResolve = new Set<string>();
         for (const route of routes) {
           const dcRoute = route as import('../ts_interfaces/data/remoteingress.js').IDcRouterRouteConfig;
-          if (!dcRoute.vpn?.required) continue;
+          if (!dcRoute.vpn?.enabled) continue;
 
           const routeTags = dcRoute.vpn.allowedServerDefinedClientTags;
           if (!routeTags?.length || clientTags.some(t => routeTags.includes(t))) {
-            for (const ip of publicIPs) {
-              ips.add(`${ip}/32`);
+            // Collect domains from this route
+            const domains = (route.match as any)?.domains;
+            if (Array.isArray(domains)) {
+              for (const d of domains) {
+                // Strip wildcard prefix for DNS resolution (*.example.com → example.com)
+                domainsToResolve.add(d.replace(/^\*\./, ''));
+              }
             }
-            break; // All routes resolve to the same server IPs
+          }
+        }
+
+        // Resolve DNS A records for matched domains (with caching)
+        for (const domain of domainsToResolve) {
+          const resolvedIps = await this.resolveVpnDomainIPs(domain);
+          for (const ip of resolvedIps) {
+            ips.add(`${ip}/32`);
           }
         }
 
@@ -2141,51 +2138,38 @@ export class DcRouter {
     });
 
     await this.vpnManager.start();
+
+    // Re-apply routes now that VPN clients are loaded — ensures hardcoded routes
+    // get correct tag-based ipAllowLists (not possible during setupSmartProxy since
+    // VPN server wasn't ready yet)
+    this.routeConfigManager?.applyRoutes();
   }
 
+  /** Cache for DNS-resolved IPs of VPN-gated domains. TTL: 5 minutes. */
+  private vpnDomainIpCache = new Map<string, { ips: string[]; expiresAt: number }>();
+
   /**
-   * Inject VPN security into routes that have vpn.required === true.
-   * Adds the VPN subnet to security.ipAllowList so only VPN clients can access them.
+   * Resolve a domain's A record(s) for VPN AllowedIPs, with a 5-minute cache.
    */
-  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 || [];
-
-        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, ...vpnAllowList],
-          },
-        };
-      }
-      return route;
-    });
-
-    if (injectedCount > 0) {
-      logger.log('info', `VPN: Injected ipAllowList into ${injectedCount} VPN-protected route(s)`);
+  private async resolveVpnDomainIPs(domain: string): Promise<string[]> {
+    const cached = this.vpnDomainIpCache.get(domain);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.ips;
+    }
+    try {
+      const { promises: dnsPromises } = await import('dns');
+      const ips = await dnsPromises.resolve4(domain);
+      this.vpnDomainIpCache.set(domain, { ips, expiresAt: Date.now() + 5 * 60 * 1000 });
+      return ips;
+    } catch (err) {
+      logger.log('warn', `VPN: Failed to resolve ${domain} for AllowedIPs: ${(err as Error).message}`);
+      return cached?.ips || []; // Return stale cache on failure, or empty
     }
-
-    return result;
   }
 
+  // VPN security injection is now handled dynamically by RouteConfigManager.applyRoutes()
+  // via the getVpnAllowList callback — no longer a separate method here.
+
   /**
    * Set up RADIUS server for network authentication
    */

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

@@ -252,41 +252,45 @@ export class RouteConfigManager {
 
     const enabledRoutes: plugins.smartproxy.IRouteConfig[] = [];
 
-    // Add enabled hardcoded routes (respecting overrides)
+    const http3Config = this.getHttp3Config?.();
+    const vpnAllowList = this.getVpnAllowList;
+
+    // Helper: inject VPN security into a route if vpn.enabled is set
+    const injectVpn = (route: plugins.smartproxy.IRouteConfig): plugins.smartproxy.IRouteConfig => {
+      if (!vpnAllowList) return route;
+      const dcRoute = route as IDcRouterRouteConfig;
+      if (!dcRoute.vpn?.enabled) return route;
+      const allowList = vpnAllowList(dcRoute.vpn.allowedServerDefinedClientTags);
+      const mandatory = dcRoute.vpn.mandatory !== false; // defaults to true
+      return {
+        ...route,
+        security: {
+          ...route.security,
+          ipAllowList: mandatory
+            ? allowList
+            : [...(route.security?.ipAllowList || []), ...allowList],
+        },
+      };
+    };
+
+    // Add enabled hardcoded routes (respecting overrides, with fresh VPN injection)
     for (const route of this.getHardcodedRoutes()) {
       const name = route.name || '';
       const override = this.overrides.get(name);
       if (override && !override.enabled) {
         continue; // Skip disabled hardcoded route
       }
-      enabledRoutes.push(route);
+      enabledRoutes.push(injectVpn(route));
     }
 
     // Add enabled programmatic routes (with HTTP/3 and VPN augmentation)
-    const http3Config = this.getHttp3Config?.();
-    const vpnAllowList = this.getVpnAllowList;
     for (const stored of this.storedRoutes.values()) {
       if (stored.enabled) {
         let route = stored.route;
         if (http3Config && http3Config.enabled !== false) {
           route = augmentRouteWithHttp3(route, { enabled: true, ...http3Config });
         }
-        // Inject VPN security for programmatic routes with vpn.required
-        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, ...allowList],
-              },
-            };
-          }
-        }
-        enabledRoutes.push(route);
+        enabledRoutes.push(injectVpn(route));
       }
     }
 

ts/opsserver/handlers/vpn.handler.ts

@@ -72,6 +72,31 @@ export class VpnHandler {
       ),
     );
 
+    // Get currently connected VPN clients
+    viewRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnConnectedClients>(
+        'getVpnConnectedClients',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { connectedClients: [] };
+          }
+
+          const connected = await manager.getConnectedClients();
+          return {
+            connectedClients: connected.map((c) => ({
+              clientId: c.registeredClientId || c.clientId,
+              assignedIp: c.assignedIp,
+              connectedSince: c.connectedSince,
+              bytesSent: c.bytesSent,
+              bytesReceived: c.bytesReceived,
+              transport: c.transportType,
+            })),
+          };
+        },
+      ),
+    );
+
     // ---- Write endpoints (adminRouter — admin identity required via middleware) ----
 
     // Create a new VPN client
@@ -112,6 +137,29 @@ export class VpnHandler {
       ),
     );
 
+    // Update a VPN client's metadata
+    adminRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateVpnClient>(
+        'updateVpnClient',
+        async (dataArg, toolsArg) => {
+          const manager = this.opsServerRef.dcRouterRef.vpnManager;
+          if (!manager) {
+            return { success: false, message: 'VPN not configured' };
+          }
+
+          try {
+            await manager.updateClient(dataArg.clientId, {
+              description: dataArg.description,
+              serverDefinedClientTags: dataArg.serverDefinedClientTags,
+            });
+            return { success: true };
+          } 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>(

ts/vpn/classes.vpn-manager.ts

@@ -32,7 +32,7 @@ export interface IVpnManagerConfig {
   /** Compute per-client AllowedIPs based on the client's server-defined tags.
    *  Called at config generation time (create/export). Returns CIDRs for WireGuard AllowedIPs.
    *  When not set, defaults to [subnet]. */
-  getClientAllowedIPs?: (clientTags: string[]) => string[];
+  getClientAllowedIPs?: (clientTags: string[]) => Promise<string[]>;
 }
 
 interface IPersistedServerKeys {
@@ -196,7 +196,7 @@ export class VpnManager {
 
     // Override AllowedIPs with per-client values based on tag-matched routes
     if (this.config.getClientAllowedIPs && bundle.wireguardConfig) {
-      const allowedIPs = this.config.getClientAllowedIPs(opts.serverDefinedClientTags || []);
+      const allowedIPs = await this.config.getClientAllowedIPs(opts.serverDefinedClientTags || []);
       bundle.wireguardConfig = bundle.wireguardConfig.replace(
         /AllowedIPs\s*=\s*.+/,
         `AllowedIPs = ${allowedIPs.join(', ')}`,
@@ -275,6 +275,22 @@ export class VpnManager {
     this.config.onClientChanged?.();
   }
 
+  /**
+   * Update a client's metadata (description, tags) without rotating keys.
+   */
+  public async updateClient(clientId: string, update: {
+    description?: string;
+    serverDefinedClientTags?: string[];
+  }): Promise<void> {
+    const client = this.clients.get(clientId);
+    if (!client) throw new Error(`Client not found: ${clientId}`);
+    if (update.description !== undefined) client.description = update.description;
+    if (update.serverDefinedClientTags !== undefined) client.serverDefinedClientTags = update.serverDefinedClientTags;
+    client.updatedAt = Date.now();
+    await this.persistClient(client);
+    this.config.onClientChanged?.();
+  }
+
   /**
    * Rotate a client's keys. Returns the new config bundle.
    */
@@ -317,7 +333,7 @@ export class VpnManager {
       // Override AllowedIPs with per-client values based on tag-matched routes
       if (this.config.getClientAllowedIPs) {
         const clientTags = persisted?.serverDefinedClientTags || [];
-        const allowedIPs = this.config.getClientAllowedIPs(clientTags);
+        const allowedIPs = await this.config.getClientAllowedIPs(clientTags);
         config = config.replace(
           /AllowedIPs\s*=\s*.+/,
           `AllowedIPs = ${allowedIPs.join(', ')}`,

ts_interfaces/data/remoteingress.ts

@@ -53,11 +53,14 @@ export interface IRouteRemoteIngress {
 
 /**
  * Route-level VPN access configuration.
- * When attached to a route, restricts access to VPN clients only.
+ * When attached to a route, controls VPN client access.
  */
 export interface IRouteVpn {
-  /** Whether this route requires VPN access */
-  required: boolean;
+  /** Enable VPN client access for this route */
+  enabled: boolean;
+  /** When true (default), ONLY VPN clients can access this route (replaces ipAllowList).
+   *  When false, VPN client IPs are added alongside the existing allowlist. */
+  mandatory?: boolean;
   /** Only allow VPN clients with these server-defined tags. Omitted = all VPN clients. */
   allowedServerDefinedClientTags?: string[];
 }

ts_interfaces/data/vpn.ts

@@ -27,6 +27,18 @@ export interface IVpnServerStatus {
   connectedClients: number;
 }
 
+/**
+ * A currently connected VPN client (runtime info from the daemon).
+ */
+export interface IVpnConnectedClient {
+  clientId: string;
+  assignedIp: string;
+  connectedSince: string;
+  bytesSent: number;
+  bytesReceived: number;
+  transport: string;
+}
+
 /**
  * VPN client telemetry data.
  */

ts_interfaces/readme.md

@@ -97,7 +97,7 @@ interface IIdentity {
 | `IRemoteIngressStatus` | Runtime status: connected, publicIp, activeTunnels, lastHeartbeat |
 | `IRouteRemoteIngress` | Route-level config: enabled flag and optional edgeFilter |
 | `IDcRouterRouteConfig` | Extended SmartProxy route config with optional `remoteIngress` and `vpn` properties |
-| `IRouteVpn` | Route-level VPN config: `required` flag and optional `allowedServerDefinedClientTags` |
+| `IRouteVpn` | Route-level VPN config: `enabled`/`mandatory` flags and optional `allowedServerDefinedClientTags` |
 
 #### VPN Interfaces
 | Interface | Description |

ts_interfaces/requests/vpn.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../plugins.js';
 import * as authInterfaces from '../data/auth.js';
-import type { IVpnClient, IVpnServerStatus, IVpnClientTelemetry } from '../data/vpn.js';
+import type { IVpnClient, IVpnServerStatus, IVpnClientTelemetry, IVpnConnectedClient } from '../data/vpn.js';
 
 // ============================================================================
 // VPN Client Management
@@ -61,6 +61,42 @@ export interface IReq_CreateVpnClient extends plugins.typedrequestInterfaces.imp
   };
 }
 
+/**
+ * Update a VPN client's metadata (description, tags) without rotating keys.
+ */
+export interface IReq_UpdateVpnClient extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_UpdateVpnClient
+> {
+  method: 'updateVpnClient';
+  request: {
+    identity: authInterfaces.IIdentity;
+    clientId: string;
+    description?: string;
+    serverDefinedClientTags?: string[];
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}
+
+/**
+ * Get currently connected VPN clients.
+ */
+export interface IReq_GetVpnConnectedClients extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetVpnConnectedClients
+> {
+  method: 'getVpnConnectedClients';
+  request: {
+    identity: authInterfaces.IIdentity;
+  };
+  response: {
+    connectedClients: IVpnConnectedClient[];
+  };
+}
+
 /**
  * Delete a VPN client.
  */

ts_web/00_commitinfo_data.ts

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

ts_web/appstate.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import * as interfaces from '../dist_ts_interfaces/index.js';
+import * as interfaces from '../ts_interfaces/index.js';
 
 // Create main app state instance
 export const appState = new plugins.domtools.plugins.smartstate.Smartstate();
@@ -911,6 +911,7 @@ export const toggleRemoteIngressAction = remoteIngressStatePart.createAction<{
 
 export interface IVpnState {
   clients: interfaces.data.IVpnClient[];
+  connectedClients: interfaces.data.IVpnConnectedClient[];
   status: interfaces.data.IVpnServerStatus | null;
   isLoading: boolean;
   error: string | null;
@@ -923,6 +924,7 @@ export const vpnStatePart = await appState.getStatePart<IVpnState>(
   'vpn',
   {
     clients: [],
+    connectedClients: [],
     status: null,
     isLoading: false,
     error: null,
@@ -950,14 +952,20 @@ export const fetchVpnAction = vpnStatePart.createAction(async (statePartArg): Pr
       interfaces.requests.IReq_GetVpnStatus
     >('/typedrequest', 'getVpnStatus');
 
-    const [clientsResponse, statusResponse] = await Promise.all([
+    const connectedRequest = new plugins.domtools.plugins.typedrequest.TypedRequest<
+      interfaces.requests.IReq_GetVpnConnectedClients
+    >('/typedrequest', 'getVpnConnectedClients');
+
+    const [clientsResponse, statusResponse, connectedResponse] = await Promise.all([
       clientsRequest.fire({ identity: context.identity }),
       statusRequest.fire({ identity: context.identity }),
+      connectedRequest.fire({ identity: context.identity }),
     ]);
 
     return {
       ...currentState,
       clients: clientsResponse.clients,
+      connectedClients: connectedResponse.connectedClients,
       status: statusResponse.status,
       isLoading: false,
       error: null,
@@ -1054,6 +1062,39 @@ export const toggleVpnClientAction = vpnStatePart.createAction<{
   }
 });
 
+export const updateVpnClientAction = vpnStatePart.createAction<{
+  clientId: string;
+  description?: string;
+  serverDefinedClientTags?: string[];
+}>(async (statePartArg, dataArg, actionContext): Promise<IVpnState> => {
+  const context = getActionContext();
+  const currentState = statePartArg.getState()!;
+
+  try {
+    const request = new plugins.domtools.plugins.typedrequest.TypedRequest<
+      interfaces.requests.IReq_UpdateVpnClient
+    >('/typedrequest', 'updateVpnClient');
+
+    const response = await request.fire({
+      identity: context.identity!,
+      clientId: dataArg.clientId,
+      description: dataArg.description,
+      serverDefinedClientTags: dataArg.serverDefinedClientTags,
+    });
+
+    if (!response.success) {
+      return { ...currentState, error: response.message || 'Failed to update client' };
+    }
+
+    return await actionContext!.dispatch(fetchVpnAction, null);
+  } catch (error: unknown) {
+    return {
+      ...currentState,
+      error: error instanceof Error ? error.message : 'Failed to update VPN client',
+    };
+  }
+});
+
 export const clearNewClientConfigAction = vpnStatePart.createAction(
   async (statePartArg): Promise<IVpnState> => {
     return { ...statePartArg.getState()!, newClientConfig: null };

ts_web/elements/ops-view-vpn.ts

@@ -141,10 +141,18 @@ export class OpsViewVpn extends DeesElement {
     `,
   ];
 
+  /** Look up connected client info by clientId or assignedIp */
+  private getConnectedInfo(client: interfaces.data.IVpnClient): interfaces.data.IVpnConnectedClient | undefined {
+    return this.vpnState.connectedClients?.find(
+      c => c.clientId === client.clientId || (client.assignedIp && c.assignedIp === client.assignedIp)
+    );
+  }
+
   render(): TemplateResult {
     const status = this.vpnState.status;
     const clients = this.vpnState.clients;
-    const connectedCount = status?.connectedClients ?? 0;
+    const connectedClients = this.vpnState.connectedClients || [];
+    const connectedCount = connectedClients.length;
     const totalClients = clients.length;
     const enabledClients = clients.filter(c => c.enabled).length;
 
@@ -270,18 +278,28 @@ export class OpsViewVpn extends DeesElement {
         .heading1=${'VPN Clients'}
         .heading2=${'Manage WireGuard and SmartVPN client registrations'}
         .data=${clients}
-        .displayFunction=${(client: interfaces.data.IVpnClient) => ({
-          'Client ID': client.clientId,
-          'Status': client.enabled
-            ? html`<span class="statusBadge enabled">enabled</span>`
-            : html`<span class="statusBadge disabled">disabled</span>`,
-          'VPN IP': client.assignedIp || '-',
-          'Tags': client.serverDefinedClientTags?.length
-            ? html`${client.serverDefinedClientTags.map(t => html`<span class="tagBadge">${t}</span>`)}`
-            : '-',
-          'Description': client.description || '-',
-          'Created': new Date(client.createdAt).toLocaleDateString(),
-        })}
+        .displayFunction=${(client: interfaces.data.IVpnClient) => {
+          const conn = this.getConnectedInfo(client);
+          let statusHtml;
+          if (!client.enabled) {
+            statusHtml = html`<span class="statusBadge disabled">disabled</span>`;
+          } else if (conn) {
+            const since = new Date(conn.connectedSince).toLocaleString();
+            statusHtml = html`<span class="statusBadge enabled" title="Since ${since}">connected</span>`;
+          } else {
+            statusHtml = html`<span class="statusBadge enabled" style="background: ${cssManager.bdTheme('#eff6ff', '#172554')}; color: ${cssManager.bdTheme('#1e40af', '#60a5fa')};">offline</span>`;
+          }
+          return {
+            'Client ID': client.clientId,
+            'Status': statusHtml,
+            'VPN IP': client.assignedIp || '-',
+            'Tags': client.serverDefinedClientTags?.length
+              ? html`${client.serverDefinedClientTags.map(t => html`<span class="tagBadge">${t}</span>`)}`
+              : '-',
+            'Description': client.description || '-',
+            'Created': new Date(client.createdAt).toLocaleDateString(),
+          };
+        }}
         .dataActions=${[
           {
             name: 'Create Client',
@@ -328,14 +346,91 @@ export class OpsViewVpn extends DeesElement {
             },
           },
           {
-            name: 'Toggle',
+            name: 'Detail',
+            iconName: 'lucide:info',
+            type: ['doubleClick'],
+            actionFunc: async (actionData: any) => {
+              const client = actionData.item as interfaces.data.IVpnClient;
+              const conn = this.getConnectedInfo(client);
+              const { DeesModal } = await import('@design.estate/dees-catalog');
+
+              // Fetch telemetry on-demand
+              let telemetryHtml = html`<p style="color: #9ca3af;">Loading telemetry...</p>`;
+              try {
+                const request = new plugins.domtools.plugins.typedrequest.TypedRequest<
+                  interfaces.requests.IReq_GetVpnClientTelemetry
+                >('/typedrequest', 'getVpnClientTelemetry');
+                const response = await request.fire({
+                  identity: appstate.loginStatePart.getState()!.identity!,
+                  clientId: client.clientId,
+                });
+                const t = response.telemetry;
+                if (t) {
+                  const formatBytes = (b: number) => b > 1048576 ? `${(b / 1048576).toFixed(1)} MB` : b > 1024 ? `${(b / 1024).toFixed(1)} KB` : `${b} B`;
+                  telemetryHtml = html`
+                    <div class="serverInfo" style="margin-top: 12px;">
+                      <div class="infoItem"><span class="infoLabel">Bytes Sent</span><span class="infoValue">${formatBytes(t.bytesSent)}</span></div>
+                      <div class="infoItem"><span class="infoLabel">Bytes Received</span><span class="infoValue">${formatBytes(t.bytesReceived)}</span></div>
+                      <div class="infoItem"><span class="infoLabel">Keepalives</span><span class="infoValue">${t.keepalivesReceived}</span></div>
+                      <div class="infoItem"><span class="infoLabel">Last Keepalive</span><span class="infoValue">${t.lastKeepaliveAt ? new Date(t.lastKeepaliveAt).toLocaleString() : '-'}</span></div>
+                      <div class="infoItem"><span class="infoLabel">Packets Dropped</span><span class="infoValue">${t.packetsDropped}</span></div>
+                    </div>
+                  `;
+                } else {
+                  telemetryHtml = html`<p style="color: #9ca3af;">No telemetry available (client not connected)</p>`;
+                }
+              } catch {
+                telemetryHtml = html`<p style="color: #9ca3af;">Telemetry unavailable</p>`;
+              }
+
+              DeesModal.createAndShow({
+                heading: `Client: ${client.clientId}`,
+                content: html`
+                  <div class="serverInfo">
+                    <div class="infoItem"><span class="infoLabel">Client ID</span><span class="infoValue">${client.clientId}</span></div>
+                    <div class="infoItem"><span class="infoLabel">VPN IP</span><span class="infoValue">${client.assignedIp || '-'}</span></div>
+                    <div class="infoItem"><span class="infoLabel">Status</span><span class="infoValue">${!client.enabled ? 'Disabled' : conn ? 'Connected' : 'Offline'}</span></div>
+                    ${conn ? html`
+                      <div class="infoItem"><span class="infoLabel">Connected Since</span><span class="infoValue">${new Date(conn.connectedSince).toLocaleString()}</span></div>
+                      <div class="infoItem"><span class="infoLabel">Transport</span><span class="infoValue">${conn.transport}</span></div>
+                    ` : ''}
+                    <div class="infoItem"><span class="infoLabel">Description</span><span class="infoValue">${client.description || '-'}</span></div>
+                    <div class="infoItem"><span class="infoLabel">Tags</span><span class="infoValue">${client.serverDefinedClientTags?.join(', ') || '-'}</span></div>
+                    <div class="infoItem"><span class="infoLabel">Created</span><span class="infoValue">${new Date(client.createdAt).toLocaleString()}</span></div>
+                    <div class="infoItem"><span class="infoLabel">Updated</span><span class="infoValue">${new Date(client.updatedAt).toLocaleString()}</span></div>
+                  </div>
+                  <h3 style="margin: 16px 0 4px; font-size: 14px;">Telemetry</h3>
+                  ${telemetryHtml}
+                `,
+                menuOptions: [
+                  { name: 'Close', iconName: 'lucide:x', action: async (m: any) => await m.destroy() },
+                ],
+              });
+            },
+          },
+          {
+            name: 'Enable',
             iconName: 'lucide:power',
             type: ['contextmenu', 'inRow'],
+            actionRelevancyCheckFunc: (actionData: any) => !actionData.item.enabled,
             actionFunc: async (actionData: any) => {
               const client = actionData.item as interfaces.data.IVpnClient;
               await appstate.vpnStatePart.dispatchAction(appstate.toggleVpnClientAction, {
                 clientId: client.clientId,
-                enabled: !client.enabled,
+                enabled: true,
+              });
+            },
+          },
+          {
+            name: 'Disable',
+            iconName: 'lucide:power',
+            type: ['contextmenu', 'inRow'],
+            actionRelevancyCheckFunc: (actionData: any) => actionData.item.enabled,
+            actionFunc: async (actionData: any) => {
+              const client = actionData.item as interfaces.data.IVpnClient;
+              await appstate.vpnStatePart.dispatchAction(appstate.toggleVpnClientAction, {
+                clientId: client.clientId,
+                enabled: false,
               });
             },
           },
@@ -449,6 +544,47 @@ export class OpsViewVpn extends DeesElement {
               });
             },
           },
+          {
+            name: 'Edit',
+            iconName: 'lucide:pencil',
+            type: ['contextmenu', 'inRow'],
+            actionFunc: async (actionData: any) => {
+              const client = actionData.item as interfaces.data.IVpnClient;
+              const { DeesModal } = await import('@design.estate/dees-catalog');
+              const currentDescription = client.description ?? '';
+              const currentTags = client.serverDefinedClientTags?.join(', ') ?? '';
+              DeesModal.createAndShow({
+                heading: `Edit: ${client.clientId}`,
+                content: html`
+                  <dees-form>
+                    <dees-input-text .key=${'description'} .label=${'Description'} .value=${currentDescription}></dees-input-text>
+                    <dees-input-text .key=${'tags'} .label=${'Server-Defined Tags (comma-separated)'} .value=${currentTags}></dees-input-text>
+                  </dees-form>
+                `,
+                menuOptions: [
+                  { name: 'Cancel', iconName: 'lucide:x', action: async (modalArg: any) => await modalArg.destroy() },
+                  {
+                    name: 'Save',
+                    iconName: 'lucide:check',
+                    action: async (modalArg: any) => {
+                      const form = modalArg.shadowRoot?.querySelector('.content')?.querySelector('dees-form');
+                      if (!form) return;
+                      const data = await form.collectFormData();
+                      const serverDefinedClientTags = data.tags
+                        ? data.tags.split(',').map((t: string) => t.trim()).filter(Boolean)
+                        : [];
+                      await appstate.vpnStatePart.dispatchAction(appstate.updateVpnClientAction, {
+                        clientId: client.clientId,
+                        description: data.description || undefined,
+                        serverDefinedClientTags,
+                      });
+                      await modalArg.destroy();
+                    },
+                  },
+                ],
+              });
+            },
+          },
           {
             name: 'Rotate Keys',
             iconName: 'lucide:rotate-cw',

ts_web/readme.md

@@ -53,7 +53,8 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 ### 🔐 VPN Management
 - VPN server status with forwarding mode, subnet, and WireGuard port
 - Client registration table with create, enable/disable, and delete actions
-- WireGuard config download and clipboard copy on client creation
+- WireGuard config download, clipboard copy, and **QR code display** on client creation
+- QR code export for existing clients — scan with WireGuard mobile app (iOS/Android)
 - Per-client telemetry (bytes sent/received, keepalives)
 - Server public key display for manual client configuration