@push.rocks/smartvpn 1.21.0 → 2.0.0

package/third-party-notices.md

@@ -0,0 +1,81 @@
+# Third-party notices
+
+These notices accompany SmartVPN's static Linux amd64 and arm64 musl executables.
+SmartVPN's own code is MIT-licensed under [license.md](./license.md).
+
+## Cargo dependencies
+
+[Cargo dependency notices](./notices/cargo-dependencies.html) reproduce the selected
+upstream license and copyright texts for 270 third-party packages. Eight additional
+locked, feature-inactive packages are covered by these supplemental MIT notices:
+
+- [aho-corasick 1.1.4](./notices/aho-corasick-license.txt), from the published crate's `LICENSE-MIT`.
+- [defmt 0.3.100 and 1.0.1, defmt-macros 1.0.1, defmt-parser 1.0.0](./notices/defmt-license.txt),
+  from their shared upstream `LICENSE-MIT`. The respective source commits are
+  `f6decae6e09d1216aff052aa0733a6b5e632a100`, `8459657ef6df5e6f3386512744110caef5f0612a`
+  (also macros), and `4a8cdb44891ed57b8ff5a023b6bec7137c48708f` in
+  [knurling-rs/defmt](https://github.com/knurling-rs/defmt).
+  All three source files have SHA-256 `2710a622a896bba67356913d4d0492cab5465f61b2ecce6d880aeb483834fb50`;
+  the copy adds only a final newline.
+- [proc-macro-error2 2.0.1 and proc-macro-error-attr2 2.0.0](./notices/proc-macro-error2-license.txt),
+  from their identical published `LICENSE-MIT` files.
+- [valuable 0.1.1](./notices/valuable-license.txt), from
+  [its pinned upstream LICENSE](https://github.com/tokio-rs/valuable/blob/9efc29b6e58cef28f6566a47aa7e142a55fead77/LICENSE).
+
+Together these cover all 278 locked registry packages, conservatively including
+build-only and target-inactive dependencies. Listing a package does not mean it
+is linked into either Linux executable. MIT is preferred where offered as an
+alternative; other selected terms include Apache-2.0, BSD, ISC, Unicode-3.0,
+CDLA-Permissive-2.0 and the existing tun 0.7.22 dependency's WTFPL.
+The exact package versions, declared license expressions and reviewed file hashes
+are recorded in [inventory.json](./notices/inventory.json).
+
+The [additional MIT source attributions](./notices/mit-source-attributions.txt)
+retain cesu8 1.1.0's Rust Project/Eric Kidd source headers and siphasher 1.0.2's
+Rust Project/Frank Denis `COPYING` attribution, together with the selected MIT terms.
+cesu8's historical Rust copyright inventory is also retained conservatively in
+the generated notices. Combined upstream license files remain intact; additional
+terms concerning unlinked components are not a claim that those components ship.
+The earlier [Linux route backend notices](./assets/third-party-licenses.md) remain
+as supplementary exact upstream attribution, not the complete distribution index.
+
+## Compiler and static runtime
+
+`rust-toolchain.toml` pins Rust 1.95.0 and both musl targets. Components supplied
+by that compiler are outside Cargo.lock and have separate notices:
+
+- [Rust standard-library inventory](./notices/rust-standard-library.html), from the
+  official toolchain's `share/doc/rust/COPYRIGHT-library.html`. Its source SHA-256
+  is `90567e2718bf7fd65a71a3a43c5596488e80e5f51ed02bfea6fec54458b5f3d1`;
+  the copy adds only a final newline. This upstream inventory covers other targets too.
+- [musl copyright](./notices/musl-copyright.txt), from
+  [musl 1.2.5](https://git.musl-libc.org/cgit/musl/tree/COPYRIGHT?h=v1.2.5).
+  The C build toolchains use musl commit `0784374d561435f7c787a555aeab8ede699ed298`
+  with the two security patches selected by
+  [Rust 1.95.0's build recipe](https://github.com/rust-lang/rust/blob/1.95.0/src/ci/docker/scripts/musl-toolchain.sh).
+  The final executables link Rust's self-contained musl CRT/libraries.
+- [Compiler-builtins license](./notices/compiler-builtins-license.txt), from
+  [Rust 1.95.0](https://github.com/rust-lang/rust/blob/1.95.0/library/compiler-builtins/LICENSE.txt),
+  retaining MIT and Apache-2.0 WITH LLVM-exception terms.
+- [LLVM libunwind license](./notices/llvm-libunwind-license.txt), from
+  [Rust's pinned LLVM revision](https://github.com/rust-lang/llvm-project/blob/1cb4e3833c1919c2e6fb579a23ac0e2b22587b7e/libunwind/LICENSE.TXT),
+  including its additional third-party terms.
+
+The TypeScript dependency graph is installed independently through the npm
+manifest; its packages are not bundled into these Rust executables.
+
+## Reproduction and review
+
+From the repository root, with cargo-about 0.9.1:
+
+```sh
+cargo about generate --manifest-path rust/Cargo.toml --config rust/about.toml --locked --fail --output-file notices/cargo-dependencies.html rust/about.hbs
+```
+
+The configuration selects checksum-verified upstream notices when published
+crates omit or misname them. Network access is required for pinned Git sources.
+After a Cargo graph, compiler, or notice-input change, regenerate and review the
+notices, refresh the inventory, and rerun distribution review. Tests reject stale
+hashes, incomplete graph coverage, generic copyright placeholders and missing npm
+notice paths. Keep this index, `license.md`, `assets/third-party-licenses.md` and
+the entire `notices/` directory beside any separately distributed executable.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartvpn',
-  version: '1.21.0',
+  version: '2.0.0',
   description: 'A VPN solution with TypeScript control plane and Rust data plane daemon'
 }

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).
@@ -71,9 +28,11 @@ export class VpnBridge<TCommands extends TCommandMap> extends plugins.events.Eve
 
     this.bridge = new plugins.smartrust.RustBridge<TCommands>({
       binaryName,
-      envVarName: 'SMARTVPN_RUST_BINARY',
-      platformPackagePrefix: '@push.rocks/smartvpn',
-      localPaths: buildLocalPaths(binaryName),
+      binaryPath: options.transport.transport === 'stdio'
+        ? paths.getBinaryPath(binaryName)
+        : undefined,
+      localPaths: [],
+      searchSystemPath: false,
       cliArgs: ['--management', '--mode', this.mode],
       maxPayloadSize: 10 * 1024 * 1024, // 10 MB
     });
@@ -85,6 +44,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 +88,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

@@ -32,6 +32,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 +84,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;
   }
 
   /**