@push.rocks/smartvpn 1.22.0 → 2.1.0

package/ts/smartvpn.classes.vpnbridge.ts

@@ -6,49 +6,6 @@ import type {
 } from './smartvpn.interfaces.js';
 import type { TCommandMap } from '@push.rocks/smartrust';
 
-/**
- * Get the package root directory.
- */
-function getPackageRoot(): string {
-  const thisDir = plugins.path.dirname(plugins.url.fileURLToPath(import.meta.url));
-  return plugins.path.resolve(thisDir, '..');
-}
-
-/**
- * Map Node.js platform/arch to tsrust's platform suffix.
- */
-function getTsrustPlatformSuffix(): string | null {
-  const archMap: Record<string, string> = { x64: 'amd64', arm64: 'arm64' };
-  const osMap: Record<string, string> = { linux: 'linux', darwin: 'macos' };
-  const os = osMap[process.platform];
-  const arch = archMap[process.arch];
-  if (os && arch) {
-    return `${os}_${arch}`;
-  }
-  return null;
-}
-
-/**
- * Build local search paths for the smartvpn daemon binary.
- */
-function buildLocalPaths(binaryName: string): string[] {
-  const packageRoot = getPackageRoot();
-  const suffix = getTsrustPlatformSuffix();
-  const paths: string[] = [];
-
-  // dist_rust/ (tsrust cross-compiled output)
-  if (suffix) {
-    paths.push(plugins.path.join(packageRoot, 'dist_rust', `${binaryName}_${suffix}`));
-  }
-  paths.push(plugins.path.join(packageRoot, 'dist_rust', binaryName));
-
-  // Local dev build paths
-  paths.push(plugins.path.resolve(process.cwd(), 'rust', 'target', 'release', binaryName));
-  paths.push(plugins.path.resolve(process.cwd(), 'rust', 'target', 'debug', binaryName));
-
-  return paths;
-}
-
 /**
  * Shared bridge wrapper around smartrust RustBridge.
  * Supports stdio mode (dev: spawn child process) and socket mode (production: connect to running daemon).
@@ -62,19 +19,34 @@ export class VpnBridge<TCommands extends TCommandMap> extends plugins.events.Eve
     transport: TVpnTransportOptions;
     mode: 'client' | 'server';
     binaryName?: string;
+    networkNamespaceFd?: number;
   }) {
     super();
 
+    const namespaceFd = options.networkNamespaceFd;
+    if (namespaceFd !== undefined) {
+      if (plugins.os.platform() !== 'linux' || options.mode !== 'client' || options.transport.transport !== 'stdio') {
+        throw new Error('VpnBridge networkNamespaceFd requires a Linux stdio client');
+      }
+      if (!Number.isInteger(namespaceFd) || namespaceFd < 0 || namespaceFd > 0x7fff_ffff) {
+        throw new Error('VpnBridge networkNamespaceFd must be a non-negative native descriptor');
+      }
+    }
     const binaryName = options.binaryName || 'smartvpn_daemon';
-    this.transportOptions = options.transport;
+    // Keep the validated process transport stable even if the caller edits its options.
+    this.transportOptions = { ...options.transport };
     this.mode = options.mode;
 
     this.bridge = new plugins.smartrust.RustBridge<TCommands>({
       binaryName,
-      envVarName: 'SMARTVPN_RUST_BINARY',
-      platformPackagePrefix: '@push.rocks/smartvpn',
-      localPaths: buildLocalPaths(binaryName),
-      cliArgs: ['--management', '--mode', this.mode],
+      binaryPath: options.transport.transport === 'stdio'
+        ? paths.getBinaryPath(binaryName)
+        : undefined,
+      localPaths: [],
+      searchSystemPath: false,
+      cliArgs: ['--management', '--mode', this.mode,
+        ...(namespaceFd === undefined ? [] : ['--network-namespace-fd', '3'])],
+      inheritedFileDescriptors: namespaceFd === undefined ? undefined : [namespaceFd],
       maxPayloadSize: 10 * 1024 * 1024, // 10 MB
     });
 
@@ -85,6 +57,9 @@ export class VpnBridge<TCommands extends TCommandMap> extends plugins.events.Eve
     this.bridge.on('reconnected', () => {
       this.emit('reconnected');
     });
+    this.bridge.on('stderr', (line: string) => {
+      this.emit('stderr', line);
+    });
 
     // Forward management events from the daemon
     // smartrust emits 'management:<eventName>' for unsolicited events
@@ -126,11 +101,11 @@ export class VpnBridge<TCommands extends TCommandMap> extends plugins.events.Eve
   }
 
   /**
-   * Stop the bridge. In socket mode, closes the socket (daemon stays alive).
-   * In stdio mode, kills the child process.
+   * Confirm closure of the owned transport. Socket mode leaves the remote daemon alive;
+   * stdio mode waits for child exit and stdio closure. Failure remains retryable upstream.
    */
-  public stop(): void {
-    this.bridge.kill();
+  public async stop(): Promise<void> {
+    await this.bridge.terminate();
   }
 
   /**

package/ts/smartvpn.classes.vpnclient.ts

@@ -23,6 +23,7 @@ export class VpnClient extends plugins.events.EventEmitter {
     this.bridge = new VpnBridge<TVpnClientCommands>({
       transport: options.transport,
       mode: 'client',
+      networkNamespaceFd: options.networkNamespaceFd,
     });
 
     // Forward bridge events
@@ -32,6 +33,9 @@ export class VpnClient extends plugins.events.EventEmitter {
     this.bridge.on('reconnected', () => {
       this.emit('reconnected');
     });
+    this.bridge.on('stderr', (line: string) => {
+      this.emit('stderr', line);
+    });
   }
 
   /**
@@ -81,17 +85,18 @@ export class VpnClient extends plugins.events.EventEmitter {
   }
 
   /**
-   * Get MTU information (overhead, effective MTU, oversized packet stats).
+   * Get active runtime MTU information, or null when disconnected.
+   * Unknown outer-path measurements remain null.
    */
-  public async getMtuInfo(): Promise<IVpnMtuInfo> {
+  public async getMtuInfo(): Promise<IVpnMtuInfo | null> {
     return this.bridge.sendCommand('getMtuInfo', {} as Record<string, never>);
   }
 
   /**
-   * Stop the daemon bridge.
+   * Stop the daemon bridge and wait for confirmed ownership release.
    */
-  public stop(): void {
-    this.bridge.stop();
+  public async stop(): Promise<void> {
+    await this.bridge.stop();
   }
 
   /**

package/ts/smartvpn.classes.vpnconfig.ts

@@ -8,6 +8,12 @@ import type {
  * VPN configuration loader, saver, and validator.
  */
 export class VpnConfig {
+  private static validateMtu(mtu?: number): void {
+    if (mtu !== undefined && (!Number.isInteger(mtu) || mtu < 576 || mtu > 65472)) {
+      throw new Error('VpnConfig: mtu must be an integer between 576 and 65472 inner IP bytes');
+    }
+  }
+
   /**
    * Validate a client config object. Throws on invalid config.
    */
@@ -31,14 +37,26 @@ export class VpnConfig {
       if (config.wgPresharedKey) {
         VpnConfig.validateBase64Key(config.wgPresharedKey, 'wgPresharedKey');
       }
-      if (config.wgAllowedIps) {
-        for (const cidr of config.wgAllowedIps) {
-          if (!VpnConfig.isValidCidr(cidr)) {
-            throw new Error(`VpnConfig: invalid allowedIp CIDR: ${cidr}`);
-          }
+      if (!Array.isArray(config.wgAllowedIps) || config.wgAllowedIps.length === 0) {
+        throw new Error('VpnConfig: wgAllowedIps must be a nonempty array for WireGuard transport');
+      }
+      for (const cidr of config.wgAllowedIps) {
+        if (!VpnConfig.isValidCidr(cidr)) {
+          throw new Error(`VpnConfig: invalid allowedIp CIDR: ${cidr}`);
         }
       }
+      if (!VpnConfig.isValidIp(config.wgAddress)) {
+        throw new Error('VpnConfig: wgAddress must be an IPv4 address');
+      }
+      if (config.wgAddressPrefix !== undefined && (!Number.isInteger(config.wgAddressPrefix) || config.wgAddressPrefix < 0 || config.wgAddressPrefix > 32)) {
+        throw new Error('VpnConfig: wgAddressPrefix must be an integer from 0 through 32');
+      }
     } else {
+      if (config.managedNetwork && (!config.managedNetwork.authorityId || !config.managedNetwork.nodeId
+        || config.managedNetwork.authorityId.trim() !== config.managedNetwork.authorityId
+        || config.managedNetwork.nodeId.trim() !== config.managedNetwork.nodeId)) {
+        throw new Error('VpnConfig: managedNetwork requires an explicit authorityId and nodeId');
+      }
       if (!config.serverUrl) {
         throw new Error('VpnConfig: serverUrl is required');
       }
@@ -61,9 +79,7 @@ export class VpnConfig {
       }
       VpnConfig.validateBase64Key(config.clientPublicKey, 'clientPublicKey');
     }
-    if (config.mtu !== undefined && (config.mtu < 576 || config.mtu > 65535)) {
-      throw new Error('VpnConfig: mtu must be between 576 and 65535');
-    }
+    VpnConfig.validateMtu(config.mtu);
     if (config.keepaliveIntervalSecs !== undefined && config.keepaliveIntervalSecs < 1) {
       throw new Error('VpnConfig: keepaliveIntervalSecs must be >= 1');
     }
@@ -80,16 +96,38 @@ export class VpnConfig {
    * Validate a server config object. Throws on invalid config.
    */
   public static validateServerConfig(config: IVpnServerConfig): void {
+    if (config.forwardingMode === 'managed') {
+      if (!config.managedAuthorityId || config.managedAuthorityId.trim() !== config.managedAuthorityId) {
+        throw new Error('VpnConfig: managed mode requires managedAuthorityId');
+      }
+      if (config.clients?.length || config.wgPeers?.length || config.enableNat === true
+        || config.destinationPolicy !== undefined || config.clientAllowedIPs !== undefined || config.dns !== undefined
+        || config.bridgeLanSubnet !== undefined || config.bridgePhysicalInterface !== undefined
+        || config.bridgeIpRangeStart !== undefined || config.bridgeIpRangeEnd !== undefined
+        || config.socketForwardProxyProtocol === true || config.socketForwardProxyProtocolSource !== undefined
+        || config.socketForwardProxyProtocolVpnMetadata === true) {
+        throw new Error('VpnConfig: managed mode does not accept standalone clients, peers, routing, DNS, NAT or bridge configuration');
+      }
+      if (config.wgPrivateKey && ['all', 'wireguard'].includes(config.transportMode ?? 'all') && !config.serverEndpoint) {
+        throw new Error('VpnConfig: managed WireGuard requires an explicit serverEndpoint');
+      }
+    } else if (config.managedAuthorityId !== undefined) {
+      throw new Error('VpnConfig: managedAuthorityId requires managed mode');
+    }
+    if (config.wgPrivateKey) { VpnConfig.validateBase64Key(config.wgPrivateKey, 'wgPrivateKey'); }
     if (config.transportMode === 'wireguard') {
       // WireGuard server validation
       if (!config.privateKey) {
         throw new Error('VpnConfig: privateKey is required');
       }
       VpnConfig.validateBase64Key(config.privateKey, 'privateKey');
-      if (!config.wgPeers || config.wgPeers.length === 0) {
+      if (config.forwardingMode === 'managed' && !config.wgPrivateKey) {
+        throw new Error('VpnConfig: managed WireGuard requires wgPrivateKey');
+      }
+      if (config.forwardingMode !== 'managed' && (!config.wgPeers || config.wgPeers.length === 0)) {
         throw new Error('VpnConfig: at least one wgPeers entry is required for WireGuard mode');
       }
-      for (const peer of config.wgPeers) {
+      for (const peer of config.wgPeers ?? []) {
         if (!peer.publicKey) {
           throw new Error('VpnConfig: peer publicKey is required');
         }
@@ -138,9 +176,7 @@ export class VpnConfig {
         }
       }
     }
-    if (config.mtu !== undefined && (config.mtu < 576 || config.mtu > 65535)) {
-      throw new Error('VpnConfig: mtu must be between 576 and 65535');
-    }
+    VpnConfig.validateMtu(config.mtu);
     if (config.keepaliveIntervalSecs !== undefined && config.keepaliveIntervalSecs < 1) {
       throw new Error('VpnConfig: keepaliveIntervalSecs must be >= 1');
     }

package/ts/smartvpn.classes.vpnserver.ts

@@ -11,9 +11,14 @@ import type {
   IWgPeerConfig,
   IWgPeerInfo,
   IClientEntry,
+  IClientCreateOptions,
+  TClientUpdateOptions,
   IClientConfigBundle,
   IDestinationPolicy,
   TVpnServerCommands,
+  IManagedNetworkSnapshot,
+  IManagedNetworkStatus,
+  IManagedNodeProjection,
 } from './smartvpn.interfaces.js';
 
 /**
@@ -26,6 +31,10 @@ export class VpnServer extends plugins.events.EventEmitter {
   private nftHealthInterval?: ReturnType<typeof setInterval>;
   private nftSubnet?: string;
   private nftPolicy?: IDestinationPolicy;
+  private nftHealthCheck?: Promise<void>;
+  private startOperation?: Promise<void>;
+  private stopOperation?: Promise<void>;
+  private remotePolicyStopAcknowledged = false;
 
   constructor(options: IVpnServerOptions) {
     super();
@@ -42,12 +51,28 @@ export class VpnServer extends plugins.events.EventEmitter {
     this.bridge.on('reconnected', () => {
       this.emit('reconnected');
     });
+    this.bridge.on('stderr', (line: string) => {
+      this.emit('stderr', line);
+    });
   }
 
   /**
    * Start the daemon bridge (spawn or connect).
    */
   public async start(config?: IVpnServerConfig): Promise<void> {
+    if (this.startOperation || this.stopOperation || this.nft) {
+      throw new Error('VpnServer: finish the current lifecycle operation and cleanup before starting');
+    }
+    const operation = this.startOwnedResources(config);
+    this.startOperation = operation;
+    try {
+      await operation;
+    } finally {
+      this.startOperation = undefined;
+    }
+  }
+
+  private async startOwnedResources(config?: IVpnServerConfig): Promise<void> {
     const started = await this.bridge.start();
     if (!started) {
       throw new Error('VpnServer: failed to start daemon bridge');
@@ -77,6 +102,20 @@ export class VpnServer extends plugins.events.EventEmitter {
     return this.bridge.sendCommand('getStatus', {} as Record<string, never>);
   }
 
+  /** Apply a complete caller-owned snapshot. An IPC timeout does not cancel its owner.
+   * Inspect status and replay the exact target after uncertainty or a pending failure. */
+  public async reconcileManagedNetwork(snapshot: IManagedNetworkSnapshot): Promise<IManagedNetworkStatus> {
+    return this.bridge.sendCommand('reconcileManagedNetwork', { snapshot });
+  }
+
+  public async getManagedNetworkStatus(): Promise<IManagedNetworkStatus> {
+    return this.bridge.sendCommand('getManagedNetworkStatus', {});
+  }
+
+  public async getManagedNodeProjection(nodeId: string): Promise<IManagedNodeProjection> {
+    return this.bridge.sendCommand('getManagedNodeProjection', { nodeId });
+  }
+
   /**
    * Get server statistics.
    */
@@ -170,7 +209,7 @@ export class VpnServer extends plugins.events.EventEmitter {
    * Create a new client. Generates keypairs, assigns IP, returns full config bundle.
    * The secrets (private keys) are only returned at creation time.
    */
-  public async createClient(opts: Partial<IClientEntry>): Promise<IClientConfigBundle> {
+  public async createClient(opts: IClientCreateOptions): Promise<IClientConfigBundle> {
     return this.bridge.sendCommand('createClient', { client: opts });
   }
 
@@ -199,7 +238,7 @@ export class VpnServer extends plugins.events.EventEmitter {
   /**
    * Update a registered client's fields (ACLs, tags, description, etc.).
    */
-  public async updateClient(clientId: string, update: Partial<IClientEntry>): Promise<void> {
+  public async updateClient(clientId: string, update: TClientUpdateOptions): Promise<void> {
     await this.bridge.sendCommand('updateClient', { clientId, update });
   }
 
@@ -246,6 +285,7 @@ export class VpnServer extends plugins.events.EventEmitter {
    * Also starts a 60-second health check interval to re-apply if rules are removed externally.
    */
   private async setupTunDestinationPolicy(subnet: string, policy: IDestinationPolicy): Promise<void> {
+    this.remotePolicyStopAcknowledged = false;
     this.nftSubnet = subnet;
     this.nftPolicy = policy;
     this.nft = new plugins.smartnftables.SmartNftables({
@@ -257,24 +297,32 @@ export class VpnServer extends plugins.events.EventEmitter {
     await this.applyDestinationPolicyRules();
 
     // Health check: re-apply rules if they disappear
-    this.nftHealthInterval = setInterval(async () => {
-      if (!this.nft) return;
-      try {
-        const exists = await this.nft.tableExists();
-        if (!exists) {
-          console.warn('[smartvpn] nftables rules missing, re-applying destination policy');
-          this.nft = new plugins.smartnftables.SmartNftables({
-            tableName: 'smartvpn_tun',
-          });
-          await this.nft.initialize();
-          await this.applyDestinationPolicyRules();
-        }
-      } catch (err) {
-        console.warn(`[smartvpn] nftables health check failed: ${err}`);
-      }
+    this.nftHealthInterval = setInterval(() => {
+      if (this.nftHealthCheck || this.stopOperation) return;
+      this.nftHealthCheck = this.checkTunDestinationPolicy().finally(() => {
+        this.nftHealthCheck = undefined;
+      });
     }, 60_000);
   }
 
+  private async checkTunDestinationPolicy(): Promise<void> {
+    if (!this.nft) return;
+    try {
+      const exists = await this.nft.tableExists();
+      if (!exists) {
+        console.warn('[smartvpn] nftables rules missing, re-applying destination policy');
+        this.nft = new plugins.smartnftables.SmartNftables({
+          tableName: 'smartvpn_tun',
+          dryRun: process.getuid?.() !== 0,
+        });
+        await this.nft.initialize();
+        await this.applyDestinationPolicyRules();
+      }
+    } catch (err) {
+      console.warn(`[smartvpn] nftables health check failed: ${err}`);
+    }
+  }
+
   /**
    * Apply destination policy as nftables rules.
    * Order: blockList (drop) → allowList (accept) → default action.
@@ -331,37 +379,43 @@ export class VpnServer extends plugins.events.EventEmitter {
   }
 
   /**
-   * Stop the daemon bridge.
+   * Drain startup, confirm daemon closure, then drain policy work and clean up.
+   * Failure preserves ownership so callers can retry; no timeout implies success.
    */
-  public async stop(): Promise<void> {
-    // Clean up nftables rules
+  public stop(): Promise<void> {
+    if (this.stopOperation) return this.stopOperation;
+    const operation = this.stopOwnedResources();
+    this.stopOperation = operation;
+    void operation.then(
+      () => { this.stopOperation = undefined; },
+      () => { this.stopOperation = undefined; },
+    );
+    return operation;
+  }
+
+  private async stopOwnedResources(): Promise<void> {
+    // A failed start is still reported to its caller; stop must clean its partial resources.
+    await this.startOperation?.catch(() => undefined);
     if (this.nftHealthInterval) {
       clearInterval(this.nftHealthInterval);
       this.nftHealthInterval = undefined;
     }
+    // A socket disconnect cannot stop a remote packet worker. If this facade
+    // installed its host policy, stop that server before releasing enforcement.
+    if (this.nft && this.options.transport.transport === 'socket' && !this.remotePolicyStopAcknowledged) {
+      await this.stopServer();
+      this.remotePolicyStopAcknowledged = true;
+    }
+    // In stdio mode, keep policy enforced until the owned worker has exited.
+    await this.bridge.stop();
+    await this.nftHealthCheck;
     if (this.nft) {
-      try {
-        await this.nft.cleanup();
-      } catch (e) {
-        console.warn(`[smartvpn] nftables cleanup failed: ${e}`);
-      }
+      await this.nft.cleanup();
       this.nft = undefined;
     }
-
-    // Wait for bridge process to exit (with timeout)
-    const exitPromise = new Promise<void>((resolve) => {
-      if (!this.bridge.running) {
-        resolve();
-        return;
-      }
-      const timeout = setTimeout(() => resolve(), 5000);
-      this.bridge.once('exit', () => {
-        clearTimeout(timeout);
-        resolve();
-      });
-    });
-    this.bridge.stop();
-    await exitPromise;
+    this.nftSubnet = undefined;
+    this.nftPolicy = undefined;
+    this.remotePolicyStopAcknowledged = false;
   }
 
   /**