appium-ios-tuntap 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.1.8](https://github.com/appium/appium-ios-tuntap/compare/v0.1.7...v0.1.8) (2026-04-12)
+
+### Code Refactoring
+
+* isolate OS networking in TunTapPlatform ([#27](https://github.com/appium/appium-ios-tuntap/issues/27)) ([7de387f](https://github.com/appium/appium-ios-tuntap/commit/7de387f0e4c2a07b81056f8da95f69cf34809cef))
+
 ## [0.1.7](https://github.com/appium/appium-ios-tuntap/compare/v0.1.6...v0.1.7) (2026-04-11)
 
 ### Miscellaneous Chores

package/build/config.gypi

@@ -502,7 +502,7 @@
     "cache": "/Users/runner/.npm",
     "node_gyp": "/Users/runner/work/appium-ios-tuntap/appium-ios-tuntap/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js",
     "npm_version": "11.11.0",
-    "userconfig": "/private/var/folders/tb/y368xp_x10s3ty1b_mtl5mxr0000gn/T/14b7acab7dfe7d9e4e5a02e7d608ed97/.npmrc",
+    "userconfig": "/private/var/folders/tb/y368xp_x10s3ty1b_mtl5mxr0000gn/T/dae56aff1d9f6176e257d9aa15256f4d/.npmrc",
     "init_module": "/Users/runner/.npm-init.js",
     "globalconfig": "/Users/runner/hostedtoolcache/node/24.14.1/arm64/etc/npmrc",
     "local_prefix": "/Users/runner/work/appium-ios-tuntap/appium-ios-tuntap",

package/lib/TunTap.d.ts

@@ -1,56 +1,114 @@
+import type { TunTapInterfaceStats } from './platform/types.js';
+/**
+ * Called by {@link TunTap.startPolling} for each packet read from the TUN device.
+ *
+ * @param data — raw L3 frame (IPv6) read from the device
+ */
 export type PacketCallback = (data: Buffer) => void;
-export declare class TunTapError extends Error {
-    code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
-}
-export declare class TunTapPermissionError extends TunTapError {
-    constructor(message: string);
-}
-export declare class TunTapDeviceError extends TunTapError {
-    constructor(message: string);
-}
 /**
- * TUN/TAP device for IP tunneling
+ * High-level wrapper around the native TUN device with IPv6-only configuration helpers.
+ *
+ * Routing and addressing use a built-in OS backend chosen from the `platform` argument (requires root, EUID 0 on Darwin/Linux).
  */
 export declare class TunTap {
     private device;
+    private readonly platformBackend;
     private _isOpen;
     private _isClosed;
     private removeExitListener;
-    constructor(name?: string);
+    /**
+     * @param name — optional interface name hint for the native layer
+     * @param platform — Node.js platform id (e.g. `darwin`, `linux`); defaults to `process.platform`
+     */
+    constructor(name?: string, platform?: NodeJS.Platform);
+    /** Whether {@link TunTap.open} has succeeded and {@link TunTap.close} has not run. */
     get isOpen(): boolean;
+    /** Whether {@link TunTap.close} has been called (device cannot be reopened). */
     get isClosed(): boolean;
     /**
-     * Throws if the device is not in a usable state (not open or already closed).
+     * Open the TUN device via the native addon.
+     *
+     * @returns `true` when the device is open
+     * @throws {TunTapError} if already closed
+     * @throws {TunTapDeviceError} if the device cannot be opened
+     * @throws {TunTapPermissionError} if the OS denies access
      */
-    private assertReady;
     open(): boolean;
+    /**
+     * Close the device and unregister process `exit` cleanup.
+     *
+     * @returns `true` when closed (idempotent)
+     * @throws {TunTapError} on native close failure
+     */
     close(): boolean;
+    /**
+     * Read one datagram/packet from the TUN device (blocking in the native layer).
+     *
+     * @param maxSize — upper bound on bytes to read (default 4096)
+     * @returns packet buffer
+     * @throws {TunTapError} if not open, closed, or read fails
+     * @throws {RangeError} if `maxSize` is out of range
+     */
     read(maxSize?: number): Buffer;
+    /**
+     * Write a full IPv6 packet to the TUN device.
+     *
+     * @param data — L3 payload to write
+     * @returns number of bytes written
+     * @throws {TunTapError} if not open, closed, or write fails
+     * @throws {TypeError} if `data` is not a `Buffer`
+     * @throws {RangeError} if `data` exceeds the maximum buffer size
+     */
     write(data: Buffer): number;
     /**
-     * Start event-driven reading from the TUN device.
-     * The callback is invoked with each packet read from the device.
+     * Start libuv-driven polling on the TUN fd; `callback` runs on the Node thread pool per packet.
+     *
+     * @param callback — invoked with each packet read from the device
+     * @param bufferSize — max read size per poll (default 65535)
+     * @throws {TunTapError} if not open or closed
+     * @throws {TypeError} if `callback` is not a function
+     * @throws {RangeError} if `bufferSize` is out of range
      */
     startPolling(callback: PacketCallback, bufferSize?: number): void;
+    /** OS-assigned interface name (e.g. `utun4` on macOS). */
     get name(): string;
+    /** File descriptor for the open TUN device (for advanced use). */
     get fd(): number;
+    /**
+     * Configure IPv6 address and MTU on this interface using the platform backend (must run as root on Darwin/Linux).
+     *
+     * @param address — IPv6 address
+     * @param mtu — link MTU (min 1280, max 65535)
+     * @throws {TypeError} if `address` is not a valid IPv6 literal
+     * @throws {RangeError} if `mtu` is out of range
+     * @throws {TunTapError} on backend failure
+     */
     configure(address: string, mtu?: number): Promise<void>;
-    private configureLinux;
+    /**
+     * Add an IPv6 route via this TUN interface.
+     *
+     * @param destination — IPv6 address or CIDR (e.g. `fd00::/64`)
+     * @throws {TypeError} if `destination` is invalid
+     * @throws {TunTapError} on backend failure
+     */
     addRoute(destination: string): Promise<void>;
-    private addRouteLinux;
+    /**
+     * Remove an IPv6 route previously added for this interface.
+     *
+     * @param destination — same form as {@link TunTap.addRoute}
+     * @throws {TypeError} if `destination` is invalid
+     * @throws {TunTapError} if the backend reports an error other than “route missing”
+     */
     removeRoute(destination: string): Promise<void>;
     /**
-     * Get interface statistics.
-     */
-    getStats(): Promise<{
-        rxBytes: number;
-        txBytes: number;
-        rxPackets: number;
-        txPackets: number;
-        rxErrors: number;
-        txErrors: number;
-    }>;
-    private getStatsDarwin;
-    private getStatsLinux;
+     * Fetch RX/TX counters for this interface from the OS (e.g. `netstat` / `ip -s`).
+     *
+     * @returns byte and packet counts plus error counters
+     * @throws {TunTapError} if not ready or stats cannot be parsed
+     */
+    getStats(): Promise<TunTapInterfaceStats>;
+    /**
+     * Throws if the device is not in a usable state (not open or already closed).
+     */
+    private assertReady;
 }

package/lib/TunTap.js

@@ -1,37 +1,14 @@
-import { execFile } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { isIPv6 } from 'node:net';
-import { promisify } from 'node:util';
+import { TunTapDeviceError, TunTapError, TunTapPermissionError, } from './errors.js';
 import { log } from './logger.js';
+import { createTunTapPlatform } from './platform/create-platform.js';
 const require = createRequire(import.meta.url);
-const execFileAsync = promisify(execFile);
-const PLATFORM = process.platform;
 const DEFAULT_READ_BUFFER_SIZE = 4096;
 const MAX_BUFFER_SIZE = 0xFFFF; // 65535
 const DEFAULT_MTU = 1500;
 const MIN_MTU = 1280;
 const nativeTuntap = require('../build/Release/tuntap.node');
-// Custom error types
-export class TunTapError extends Error {
-    code;
-    constructor(message, code) {
-        super(message);
-        this.code = code;
-        this.name = 'TunTapError';
-    }
-}
-export class TunTapPermissionError extends TunTapError {
-    constructor(message) {
-        super(message, 'EPERM');
-        this.name = 'TunTapPermissionError';
-    }
-}
-export class TunTapDeviceError extends TunTapError {
-    constructor(message) {
-        super(message, 'ENODEV');
-        this.name = 'TunTapDeviceError';
-    }
-}
 /**
  * Validates an IPv6 route destination (address with optional CIDR prefix).
  */
@@ -49,15 +26,23 @@ function isValidIPv6Route(destination) {
     return isIPv6(parts[0]);
 }
 /**
- * TUN/TAP device for IP tunneling
+ * High-level wrapper around the native TUN device with IPv6-only configuration helpers.
+ *
+ * Routing and addressing use a built-in OS backend chosen from the `platform` argument (requires root, EUID 0 on Darwin/Linux).
  */
 export class TunTap {
     device;
+    platformBackend;
     _isOpen;
     _isClosed;
     removeExitListener = null;
-    constructor(name = '') {
+    /**
+     * @param name — optional interface name hint for the native layer
+     * @param platform — Node.js platform id (e.g. `darwin`, `linux`); defaults to `process.platform`
+     */
+    constructor(name = '', platform = process.platform) {
         this.device = new nativeTuntap.TunDevice(name);
+        this.platformBackend = createTunTapPlatform(platform);
         this._isOpen = false;
         this._isClosed = false;
         // Register cleanup on process exit only.
@@ -78,23 +63,22 @@ export class TunTap {
             process.removeListener('exit', cleanup);
         };
     }
+    /** Whether {@link TunTap.open} has succeeded and {@link TunTap.close} has not run. */
     get isOpen() {
         return this._isOpen;
     }
+    /** Whether {@link TunTap.close} has been called (device cannot be reopened). */
     get isClosed() {
         return this._isClosed;
     }
     /**
-     * Throws if the device is not in a usable state (not open or already closed).
+     * Open the TUN device via the native addon.
+     *
+     * @returns `true` when the device is open
+     * @throws {TunTapError} if already closed
+     * @throws {TunTapDeviceError} if the device cannot be opened
+     * @throws {TunTapPermissionError} if the OS denies access
      */
-    assertReady() {
-        if (!this._isOpen) {
-            throw new TunTapError('Device not open');
-        }
-        if (this._isClosed) {
-            throw new TunTapError('Device has been closed');
-        }
-    }
     open() {
         if (this._isClosed) {
             throw new TunTapError('Device has been closed and cannot be reopened');
@@ -119,6 +103,12 @@ export class TunTap {
         }
         return this._isOpen;
     }
+    /**
+     * Close the device and unregister process `exit` cleanup.
+     *
+     * @returns `true` when closed (idempotent)
+     * @throws {TunTapError} on native close failure
+     */
     close() {
         if (this.removeExitListener) {
             this.removeExitListener();
@@ -138,6 +128,14 @@ export class TunTap {
         }
         return true;
     }
+    /**
+     * Read one datagram/packet from the TUN device (blocking in the native layer).
+     *
+     * @param maxSize — upper bound on bytes to read (default 4096)
+     * @returns packet buffer
+     * @throws {TunTapError} if not open, closed, or read fails
+     * @throws {RangeError} if `maxSize` is out of range
+     */
     read(maxSize = DEFAULT_READ_BUFFER_SIZE) {
         this.assertReady();
         if (maxSize <= 0 || maxSize > MAX_BUFFER_SIZE) {
@@ -150,6 +148,15 @@ export class TunTap {
             throw new TunTapError(`Read failed: ${err.message}`);
         }
     }
+    /**
+     * Write a full IPv6 packet to the TUN device.
+     *
+     * @param data — L3 payload to write
+     * @returns number of bytes written
+     * @throws {TunTapError} if not open, closed, or write fails
+     * @throws {TypeError} if `data` is not a `Buffer`
+     * @throws {RangeError} if `data` exceeds the maximum buffer size
+     */
     write(data) {
         this.assertReady();
         if (!Buffer.isBuffer(data)) {
@@ -173,8 +180,13 @@ export class TunTap {
         }
     }
     /**
-     * Start event-driven reading from the TUN device.
-     * The callback is invoked with each packet read from the device.
+     * Start libuv-driven polling on the TUN fd; `callback` runs on the Node thread pool per packet.
+     *
+     * @param callback — invoked with each packet read from the device
+     * @param bufferSize — max read size per poll (default 65535)
+     * @throws {TunTapError} if not open or closed
+     * @throws {TypeError} if `callback` is not a function
+     * @throws {RangeError} if `bufferSize` is out of range
      */
     startPolling(callback, bufferSize = MAX_BUFFER_SIZE) {
         this.assertReady();
@@ -186,12 +198,23 @@ export class TunTap {
         }
         this.device.startPolling(callback, bufferSize);
     }
+    /** OS-assigned interface name (e.g. `utun4` on macOS). */
     get name() {
         return this.device.getName();
     }
+    /** File descriptor for the open TUN device (for advanced use). */
     get fd() {
         return this.device.getFd();
     }
+    /**
+     * Configure IPv6 address and MTU on this interface using the platform backend (must run as root on Darwin/Linux).
+     *
+     * @param address — IPv6 address
+     * @param mtu — link MTU (min 1280, max 65535)
+     * @throws {TypeError} if `address` is not a valid IPv6 literal
+     * @throws {RangeError} if `mtu` is out of range
+     * @throws {TunTapError} on backend failure
+     */
     async configure(address, mtu = DEFAULT_MTU) {
         this.assertReady();
         if (!isIPv6(address)) {
@@ -201,16 +224,7 @@ export class TunTap {
             throw new RangeError(`MTU must be between ${MIN_MTU} and ${MAX_BUFFER_SIZE}`);
         }
         try {
-            if (PLATFORM === 'darwin') {
-                await execFileAsync('sudo', ['ifconfig', this.name, 'inet6', address, 'prefixlen', '64', 'up']);
-                await execFileAsync('sudo', ['ifconfig', this.name, 'mtu', String(mtu)]);
-            }
-            else if (PLATFORM === 'linux') {
-                await this.configureLinux(address, mtu);
-            }
-            else {
-                throw new TunTapError(`Unsupported platform: ${PLATFORM}`);
-            }
+            await this.platformBackend.configure(this.name, address, mtu);
         }
         catch (err) {
             if (err instanceof TunTapError) {
@@ -219,28 +233,13 @@ export class TunTap {
             throw new TunTapError(`Failed to configure TUN interface: ${err.message}`);
         }
     }
-    async configureLinux(address, mtu) {
-        try {
-            await execFileAsync('which', ['ip']);
-        }
-        catch {
-            throw new TunTapError('The "ip" command is not available. Please install iproute2 (e.g., sudo apt install iproute2)');
-        }
-        try {
-            await execFileAsync('sudo', ['ip', '-6', 'addr', 'add', `${address}/64`, 'dev', this.name]);
-        }
-        catch (err) {
-            const message = err.message;
-            if (message.includes('Permission denied')) {
-                throw new TunTapPermissionError('Permission denied when configuring network interface. Run with sudo.');
-            }
-            if (!message.includes('File exists')) {
-                throw err;
-            }
-            log.warn(`Address ${address} may already be configured on ${this.name}`);
-        }
-        await execFileAsync('sudo', ['ip', 'link', 'set', 'dev', this.name, 'up', 'mtu', String(mtu)]);
-    }
+    /**
+     * Add an IPv6 route via this TUN interface.
+     *
+     * @param destination — IPv6 address or CIDR (e.g. `fd00::/64`)
+     * @throws {TypeError} if `destination` is invalid
+     * @throws {TunTapError} on backend failure
+     */
     async addRoute(destination) {
         this.assertReady();
         if (!destination || typeof destination !== 'string') {
@@ -250,15 +249,7 @@ export class TunTap {
             throw new TypeError('Destination must be a valid IPv6 address or CIDR (e.g., fd00::1/128)');
         }
         try {
-            if (PLATFORM === 'darwin') {
-                await execFileAsync('sudo', ['route', '-n', 'add', '-inet6', destination, '-interface', this.name]);
-            }
-            else if (PLATFORM === 'linux') {
-                await this.addRouteLinux(destination);
-            }
-            else {
-                throw new TunTapError(`Unsupported platform: ${PLATFORM}`);
-            }
+            await this.platformBackend.addRoute(this.name, destination);
         }
         catch (err) {
             if (err instanceof TunTapError) {
@@ -267,22 +258,13 @@ export class TunTap {
             throw new TunTapError(`Failed to add route: ${err.message}`);
         }
     }
-    async addRouteLinux(destination) {
-        try {
-            await execFileAsync('sudo', ['ip', '-6', 'route', 'add', destination, 'dev', this.name]);
-        }
-        catch (err) {
-            const message = err.message;
-            if (message.includes('Permission denied')) {
-                throw new TunTapPermissionError('Permission denied when adding route. Run with sudo.');
-            }
-            if (message.includes('File exists')) {
-                log.info(`Route to ${destination} already exists`);
-                return;
-            }
-            throw err;
-        }
-    }
+    /**
+     * Remove an IPv6 route previously added for this interface.
+     *
+     * @param destination — same form as {@link TunTap.addRoute}
+     * @throws {TypeError} if `destination` is invalid
+     * @throws {TunTapError} if the backend reports an error other than “route missing”
+     */
     async removeRoute(destination) {
         this.assertReady();
         if (!destination || typeof destination !== 'string') {
@@ -292,15 +274,7 @@ export class TunTap {
             throw new TypeError('Destination must be a valid IPv6 address or CIDR');
         }
         try {
-            if (PLATFORM === 'darwin') {
-                await execFileAsync('sudo', ['route', '-n', 'delete', '-inet6', destination]);
-            }
-            else if (PLATFORM === 'linux') {
-                await execFileAsync('sudo', ['ip', '-6', 'route', 'del', destination, 'dev', this.name]);
-            }
-            else {
-                throw new TunTapError(`Unsupported platform: ${PLATFORM}`);
-            }
+            await this.platformBackend.removeRoute(this.name, destination);
         }
         catch (err) {
             const message = err.message;
@@ -311,18 +285,15 @@ export class TunTap {
         }
     }
     /**
-     * Get interface statistics.
+     * Fetch RX/TX counters for this interface from the OS (e.g. `netstat` / `ip -s`).
+     *
+     * @returns byte and packet counts plus error counters
+     * @throws {TunTapError} if not ready or stats cannot be parsed
      */
     async getStats() {
         this.assertReady();
         try {
-            if (PLATFORM === 'darwin') {
-                return await this.getStatsDarwin();
-            }
-            if (PLATFORM === 'linux') {
-                return await this.getStatsLinux();
-            }
-            throw new TunTapError(`Unsupported platform: ${PLATFORM}`);
+            return await this.platformBackend.getStats(this.name);
         }
         catch (err) {
             if (err instanceof TunTapError) {
@@ -331,47 +302,15 @@ export class TunTap {
             throw new TunTapError(`Failed to get interface statistics: ${err.message}`);
         }
     }
-    async getStatsDarwin() {
-        const { stdout } = await execFileAsync('netstat', ['-I', this.name, '-b']);
-        const lines = stdout.trim().split('\n');
-        if (lines.length < 2) {
-            throw new TunTapError('Unexpected netstat output');
-        }
-        const stats = lines[1].split(/\s+/);
-        return {
-            rxPackets: parseInt(stats[4], 10) || 0,
-            rxErrors: parseInt(stats[5], 10) || 0,
-            rxBytes: parseInt(stats[6], 10) || 0,
-            txPackets: parseInt(stats[7], 10) || 0,
-            txErrors: parseInt(stats[8], 10) || 0,
-            txBytes: parseInt(stats[9], 10) || 0,
-        };
-    }
-    async getStatsLinux() {
-        const { stdout } = await execFileAsync('ip', ['-s', 'link', 'show', this.name]);
-        const lines = stdout.trim().split('\n');
-        const rxIndex = lines.findIndex((line) => line.includes('RX:'));
-        const txIndex = lines.findIndex((line) => line.includes('TX:'));
-        if (rxIndex === -1 || txIndex === -1) {
-            throw new TunTapError('Could not parse interface statistics');
-        }
-        const rxLine = lines[rxIndex + 1]?.trim();
-        const txLine = lines[txIndex + 1]?.trim();
-        if (!rxLine || !txLine) {
-            throw new TunTapError('Could not parse interface statistics: missing data lines');
+    /**
+     * Throws if the device is not in a usable state (not open or already closed).
+     */
+    assertReady() {
+        if (!this._isOpen) {
+            throw new TunTapError('Device not open');
         }
-        const rxStats = rxLine.split(/\s+/);
-        const txStats = txLine.split(/\s+/);
-        if (rxStats.length < 3 || txStats.length < 3) {
-            throw new TunTapError('Could not parse interface statistics: unexpected format');
+        if (this._isClosed) {
+            throw new TunTapError('Device has been closed');
         }
-        return {
-            rxBytes: parseInt(rxStats[0], 10) || 0,
-            rxPackets: parseInt(rxStats[1], 10) || 0,
-            rxErrors: parseInt(rxStats[2], 10) || 0,
-            txBytes: parseInt(txStats[0], 10) || 0,
-            txPackets: parseInt(txStats[1], 10) || 0,
-            txErrors: parseInt(txStats[2], 10) || 0,
-        };
     }
 }

package/lib/errors.d.ts

@@ -0,0 +1,22 @@
+/** Base error for TUN/TAP and tunnel configuration failures. */
+export declare class TunTapError extends Error {
+    code?: string | undefined;
+    name: string;
+    /**
+     * @param message — human-readable description
+     * @param code — optional machine-readable code (e.g. `EPERM`)
+     */
+    constructor(message: string, code?: string | undefined);
+}
+/** Raised when the process lacks privileges required for a networking operation (e.g. not running as root). */
+export declare class TunTapPermissionError extends TunTapError {
+    name: string;
+    /** @param message — description including hint to run with appropriate privileges */
+    constructor(message: string);
+}
+/** Raised when the TUN device cannot be opened or is unavailable. */
+export declare class TunTapDeviceError extends TunTapError {
+    name: string;
+    /** @param message — description from the native layer or OS */
+    constructor(message: string);
+}

package/lib/errors.js

@@ -0,0 +1,29 @@
+/** Base error for TUN/TAP and tunnel configuration failures. */
+export class TunTapError extends Error {
+    code;
+    name = 'TunTapError';
+    /**
+     * @param message — human-readable description
+     * @param code — optional machine-readable code (e.g. `EPERM`)
+     */
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Raised when the process lacks privileges required for a networking operation (e.g. not running as root). */
+export class TunTapPermissionError extends TunTapError {
+    name = 'TunTapPermissionError';
+    /** @param message — description including hint to run with appropriate privileges */
+    constructor(message) {
+        super(message, 'EPERM');
+    }
+}
+/** Raised when the TUN device cannot be opened or is unavailable. */
+export class TunTapDeviceError extends TunTapError {
+    name = 'TunTapDeviceError';
+    /** @param message — description from the native layer or OS */
+    constructor(message) {
+        super(message, 'ENODEV');
+    }
+}

package/lib/index.d.ts

@@ -1,2 +1,3 @@
+export { TunTapDeviceError, TunTapError, TunTapPermissionError, } from './errors.js';
 export { TunTap, type PacketCallback } from './TunTap.js';
 export * from './tunnel.js';

package/lib/index.js

@@ -1,2 +1,3 @@
+export { TunTapDeviceError, TunTapError, TunTapPermissionError, } from './errors.js';
 export { TunTap } from './TunTap.js';
 export * from './tunnel.js';

package/lib/platform/create-platform.d.ts

@@ -0,0 +1,3 @@
+import type { TunTapPlatform } from './types.js';
+/** @internal Built-in {@link TunTapPlatform} for a Node `process.platform` value. */
+export declare function createTunTapPlatform(platform: NodeJS.Platform): TunTapPlatform;

package/lib/platform/create-platform.js

@@ -0,0 +1,14 @@
+import { DarwinTunTapPlatform } from './darwin.js';
+import { LinuxTunTapPlatform } from './linux.js';
+import { UnsupportedTunTapPlatform } from './unsupported.js';
+/** @internal Built-in {@link TunTapPlatform} for a Node `process.platform` value. */
+export function createTunTapPlatform(platform) {
+    switch (platform) {
+        case 'darwin':
+            return new DarwinTunTapPlatform();
+        case 'linux':
+            return new LinuxTunTapPlatform();
+        default:
+            return new UnsupportedTunTapPlatform(platform);
+    }
+}

package/lib/platform/darwin.d.ts

@@ -0,0 +1,12 @@
+import type { TunTapInterfaceStats, TunTapPlatform } from './types.js';
+/** macOS implementation using `ifconfig`, `route`, and `netstat`. */
+export declare class DarwinTunTapPlatform implements TunTapPlatform {
+    /** @inheritdoc */
+    configure(interfaceName: string, address: string, mtu: number): Promise<void>;
+    /** @inheritdoc */
+    addRoute(interfaceName: string, destination: string): Promise<void>;
+    /** @inheritdoc */
+    removeRoute(_interfaceName: string, destination: string): Promise<void>;
+    /** @inheritdoc */
+    getStats(interfaceName: string): Promise<TunTapInterfaceStats>;
+}

package/lib/platform/darwin.js

@@ -0,0 +1,53 @@
+import { TunTapError } from '../errors.js';
+import { execFileAsync } from './exec.js';
+import { assertEffectiveRoot } from './require-root.js';
+/** macOS implementation using `ifconfig`, `route`, and `netstat`. */
+export class DarwinTunTapPlatform {
+    /** @inheritdoc */
+    async configure(interfaceName, address, mtu) {
+        assertEffectiveRoot();
+        await execFileAsync('ifconfig', [
+            interfaceName,
+            'inet6',
+            address,
+            'prefixlen',
+            '64',
+            'up',
+        ]);
+        await execFileAsync('ifconfig', [interfaceName, 'mtu', String(mtu)]);
+    }
+    /** @inheritdoc */
+    async addRoute(interfaceName, destination) {
+        assertEffectiveRoot();
+        await execFileAsync('route', [
+            '-n',
+            'add',
+            '-inet6',
+            destination,
+            '-interface',
+            interfaceName,
+        ]);
+    }
+    /** @inheritdoc */
+    async removeRoute(_interfaceName, destination) {
+        assertEffectiveRoot();
+        await execFileAsync('route', ['-n', 'delete', '-inet6', destination]);
+    }
+    /** @inheritdoc */
+    async getStats(interfaceName) {
+        const { stdout } = await execFileAsync('netstat', ['-I', interfaceName, '-b']);
+        const lines = stdout.trim().split('\n');
+        if (lines.length < 2) {
+            throw new TunTapError('Unexpected netstat output');
+        }
+        const stats = lines[1].split(/\s+/);
+        return {
+            rxPackets: parseInt(stats[4], 10) || 0,
+            rxErrors: parseInt(stats[5], 10) || 0,
+            rxBytes: parseInt(stats[6], 10) || 0,
+            txPackets: parseInt(stats[7], 10) || 0,
+            txErrors: parseInt(stats[8], 10) || 0,
+            txBytes: parseInt(stats[9], 10) || 0,
+        };
+    }
+}

package/lib/platform/exec.d.ts

@@ -0,0 +1,2 @@
+import { execFile } from 'node:child_process';
+export declare const execFileAsync: typeof execFile.__promisify__;

package/lib/platform/exec.js

@@ -0,0 +1,3 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+export const execFileAsync = promisify(execFile);

package/lib/platform/linux.d.ts

@@ -0,0 +1,12 @@
+import type { TunTapInterfaceStats, TunTapPlatform } from './types.js';
+/** Linux implementation using `ip` from iproute2. */
+export declare class LinuxTunTapPlatform implements TunTapPlatform {
+    /** @inheritdoc */
+    configure(interfaceName: string, address: string, mtu: number): Promise<void>;
+    /** @inheritdoc */
+    addRoute(interfaceName: string, destination: string): Promise<void>;
+    /** @inheritdoc */
+    removeRoute(interfaceName: string, destination: string): Promise<void>;
+    /** @inheritdoc */
+    getStats(interfaceName: string): Promise<TunTapInterfaceStats>;
+}

package/lib/platform/linux.js

@@ -0,0 +1,77 @@
+import { log } from '../logger.js';
+import { TunTapError } from '../errors.js';
+import { execFileAsync } from './exec.js';
+import { assertEffectiveRoot } from './require-root.js';
+/** Linux implementation using `ip` from iproute2. */
+export class LinuxTunTapPlatform {
+    /** @inheritdoc */
+    async configure(interfaceName, address, mtu) {
+        assertEffectiveRoot();
+        try {
+            await execFileAsync('which', ['ip']);
+        }
+        catch {
+            throw new TunTapError('The "ip" command is not available. Please install iproute2 (e.g., sudo apt install iproute2)');
+        }
+        try {
+            await execFileAsync('ip', ['-6', 'addr', 'add', `${address}/64`, 'dev', interfaceName]);
+        }
+        catch (err) {
+            // `util.promisify(execFile)` rejects with `ExecException` (extends `Error`; adds `stderr`, `code`, …).
+            const { message } = err;
+            if (!message.includes('File exists')) {
+                throw err;
+            }
+            log.warn(`Address ${address} may already be configured on ${interfaceName}`);
+        }
+        await execFileAsync('ip', ['link', 'set', 'dev', interfaceName, 'up', 'mtu', String(mtu)]);
+    }
+    /** @inheritdoc */
+    async addRoute(interfaceName, destination) {
+        assertEffectiveRoot();
+        try {
+            await execFileAsync('ip', ['-6', 'route', 'add', destination, 'dev', interfaceName]);
+        }
+        catch (err) {
+            const { message } = err;
+            if (message.includes('File exists')) {
+                log.info(`Route to ${destination} already exists`);
+                return;
+            }
+            throw err;
+        }
+    }
+    /** @inheritdoc */
+    async removeRoute(interfaceName, destination) {
+        assertEffectiveRoot();
+        await execFileAsync('ip', ['-6', 'route', 'del', destination, 'dev', interfaceName]);
+    }
+    /** @inheritdoc */
+    async getStats(interfaceName) {
+        const { stdout } = await execFileAsync('ip', ['-s', 'link', 'show', interfaceName]);
+        const lines = stdout.trim().split('\n');
+        const rxIndex = lines.findIndex((line) => line.includes('RX:'));
+        const txIndex = lines.findIndex((line) => line.includes('TX:'));
+        if (rxIndex === -1 || txIndex === -1) {
+            throw new TunTapError('Could not parse interface statistics');
+        }
+        const rxLine = lines[rxIndex + 1]?.trim();
+        const txLine = lines[txIndex + 1]?.trim();
+        if (!rxLine || !txLine) {
+            throw new TunTapError('Could not parse interface statistics: missing data lines');
+        }
+        const rxStats = rxLine.split(/\s+/);
+        const txStats = txLine.split(/\s+/);
+        if (rxStats.length < 3 || txStats.length < 3) {
+            throw new TunTapError('Could not parse interface statistics: unexpected format');
+        }
+        return {
+            rxBytes: parseInt(rxStats[0], 10) || 0,
+            rxPackets: parseInt(rxStats[1], 10) || 0,
+            rxErrors: parseInt(rxStats[2], 10) || 0,
+            txBytes: parseInt(txStats[0], 10) || 0,
+            txPackets: parseInt(txStats[1], 10) || 0,
+            txErrors: parseInt(txStats[2], 10) || 0,
+        };
+    }
+}

package/lib/platform/require-root.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Ensures the process has effective superuser privileges (EUID 0).
+ * Privileged `ip` / `ifconfig` / `route` calls are executed directly — no `sudo` subprocess.
+ */
+export declare function assertEffectiveRoot(): void;

package/lib/platform/require-root.js

@@ -0,0 +1,11 @@
+import { TunTapPermissionError } from '../errors.js';
+/**
+ * Ensures the process has effective superuser privileges (EUID 0).
+ * Privileged `ip` / `ifconfig` / `route` calls are executed directly — no `sudo` subprocess.
+ */
+export function assertEffectiveRoot() {
+    const geteuid = process.geteuid;
+    if (typeof geteuid !== 'function' || geteuid.call(process) !== 0) {
+        throw new TunTapPermissionError('TUN interface configuration and routing require root privileges (effective UID 0)');
+    }
+}

package/lib/platform/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Per-interface traffic counters returned by {@link TunTapPlatform.getStats}.
+ */
+export interface TunTapInterfaceStats {
+    rxBytes: number;
+    txBytes: number;
+    rxPackets: number;
+    txPackets: number;
+    rxErrors: number;
+    txErrors: number;
+}
+/**
+ * OS-specific commands for configuring the TUN interface (address, MTU, routes, stats).
+ * Built-in Darwin/Linux implementations require **effective UID 0** (run the process as root) for
+ * {@link TunTapPlatform.configure}, {@link TunTapPlatform.addRoute}, and {@link TunTapPlatform.removeRoute}.
+ * Add a new implementation (e.g. Windows) by extending this interface and wiring it in `create-platform.ts`.
+ */
+export interface TunTapPlatform {
+    /**
+     * Assign an IPv6 address (typically /64) and MTU on the interface, and bring it up.
+     *
+     * @param interfaceName — kernel interface name (e.g. `utun7`)
+     * @param address — IPv6 address
+     * @param mtu — link MTU in bytes
+     */
+    configure(interfaceName: string, address: string, mtu: number): Promise<void>;
+    /**
+     * Add an IPv6 route via this interface.
+     *
+     * @param interfaceName — kernel interface name
+     * @param destination — IPv6 host or CIDR (e.g. `fd00::1/128`)
+     */
+    addRoute(interfaceName: string, destination: string): Promise<void>;
+    /**
+     * Remove an IPv6 route for the given destination.
+     *
+     * @param interfaceName — kernel interface name (ignored on some platforms)
+     * @param destination — same form as passed to {@link TunTapPlatform.addRoute}
+     */
+    removeRoute(interfaceName: string, destination: string): Promise<void>;
+    /**
+     * Read RX/TX byte and packet counters for the interface from the OS.
+     *
+     * @param interfaceName — kernel interface name
+     * @returns interface statistics
+     */
+    getStats(interfaceName: string): Promise<TunTapInterfaceStats>;
+}

package/lib/platform/types.js

@@ -0,0 +1 @@
+export {};

package/lib/platform/unsupported.d.ts

@@ -0,0 +1,20 @@
+import type { TunTapInterfaceStats, TunTapPlatform } from './types.js';
+/**
+ * Stub backend for unsupported `process.platform` values; every method throws {@link TunTapError}.
+ */
+export declare class UnsupportedTunTapPlatform implements TunTapPlatform {
+    private readonly platformId;
+    /**
+     * @param platformId — value from `process.platform` (or test override)
+     */
+    constructor(platformId: string);
+    /** @inheritdoc */
+    configure(): Promise<void>;
+    /** @inheritdoc */
+    addRoute(): Promise<void>;
+    /** @inheritdoc */
+    removeRoute(): Promise<void>;
+    /** @inheritdoc */
+    getStats(): Promise<TunTapInterfaceStats>;
+    private unsupported;
+}

package/lib/platform/unsupported.js

@@ -0,0 +1,32 @@
+import { TunTapError } from '../errors.js';
+/**
+ * Stub backend for unsupported `process.platform` values; every method throws {@link TunTapError}.
+ */
+export class UnsupportedTunTapPlatform {
+    platformId;
+    /**
+     * @param platformId — value from `process.platform` (or test override)
+     */
+    constructor(platformId) {
+        this.platformId = platformId;
+    }
+    /** @inheritdoc */
+    async configure() {
+        this.unsupported();
+    }
+    /** @inheritdoc */
+    async addRoute() {
+        this.unsupported();
+    }
+    /** @inheritdoc */
+    async removeRoute() {
+        this.unsupported();
+    }
+    /** @inheritdoc */
+    async getStats() {
+        this.unsupported();
+    }
+    unsupported() {
+        throw new TunTapError(`Unsupported platform: ${this.platformId}`);
+    }
+}

package/lib/tunnel.d.ts

@@ -19,19 +19,44 @@ export interface PacketData {
     destPort: number;
     payload: Buffer;
 }
+/**
+ * Event names and listener argument tuples for {@link TunnelManager}
+ * (matches Node’s `EventEmitter` event map shape).
+ *
+ * @example
+ * tunnelManager.on('data', (packet) => {
+ *   // `packet` is PacketData
+ * });
+ */
+export interface TunnelManagerEvents {
+    data: [packet: PacketData];
+}
 export interface PacketConsumer {
+    /**
+     * Invoked for each parsed TCP/UDP payload extracted from the tunnel stream.
+     *
+     * @param packet — decoded addresses, ports, and payload
+     */
     onPacket(packet: PacketData): void;
 }
 export interface TunnelConnection {
     Address: string;
     RsdPort?: number;
     tunnelManager: TunnelManager;
+    /** Tear down the tunnel, close the TUN device, and end the socket when appropriate. */
     closer: () => Promise<void>;
+    /** @param consumer — receives packets for the lifetime of the registration */
     addPacketConsumer(consumer: PacketConsumer): void;
+    /** @param consumer — must be the same reference passed to {@link TunnelConnection.addPacketConsumer} */
     removePacketConsumer(consumer: PacketConsumer): void;
+    /** @returns async iterator of packets until the tunnel is stopped */
     getPacketStream(): AsyncIterable<PacketData>;
 }
-export declare class TunnelManager extends EventEmitter {
+/**
+ * Bridges a CoreDevice tunnel `Socket` and a {@link TunTap} interface: IPv6 framing, TUN I/O, and packet fan-out.
+ * Emits {@link TunnelManagerEvents} (currently `data` with {@link PacketData}) for TCP/UDP packets, same as registered consumers.
+ */
+export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
     private tun;
     private cancelled;
     private readInterval;
@@ -40,21 +65,65 @@ export declare class TunnelManager extends EventEmitter {
     private packetQueue;
     private deviceConn;
     private cleanupPromise;
+    /** Creates a manager with no TUN device until {@link TunnelManager.setupInterface} succeeds. */
     constructor();
+    /**
+     * Register a listener for parsed tunnel packets (in addition to the `data` event).
+     *
+     * @param consumer — object with {@link PacketConsumer.onPacket}
+     */
     addPacketConsumer(consumer: PacketConsumer): void;
+    /**
+     * Unregister a consumer previously added with {@link TunnelManager.addPacketConsumer}.
+     *
+     * @param consumer — same reference as passed to `addPacketConsumer`
+     */
     removePacketConsumer(consumer: PacketConsumer): void;
+    /**
+     * Async iterator over tunnel packets until {@link TunnelManager.stop} sets `cancelled`.
+     *
+     * @yields {@link PacketData} for each TCP/UDP packet
+     */
     getPacketStream(): AsyncIterable<PacketData>;
+    /**
+     * Open a {@link TunTap}, assign the client IPv6 address/MTU, and add a /128 route to the server.
+     *
+     * @param tunnelInfo — handshake result (client address, MTU, server address)
+     * @returns interface name, MTU, and the live {@link TunTap} instance
+     */
     setupInterface(tunnelInfo: TunnelInfo): Promise<{
         name: string;
         mtu: number;
         interface: TunTap;
     }>;
+    /**
+     * Begin bidirectional forwarding: device socket ↔ TUN (requires {@link TunnelManager.setupInterface} first).
+     *
+     * @param deviceConn — connected tunnel socket after the CDTunnel handshake
+     */
     startForwarding(deviceConn: Socket): void;
+    /**
+     * Idempotent shutdown: stop polling, destroy the socket, clear consumers, close the TUN device.
+     *
+     * @returns the same promise if already stopping/stopped
+     */
+    stop(): Promise<void>;
     private processBuffer;
     private startTunReadLoop;
-    stop(): Promise<void>;
     private _performStop;
 }
+/**
+ * Perform the CDTunnel JSON handshake (8-byte magic + length-prefixed JSON) over `socket`.
+ *
+ * @param socket — connected stream to the tunnel service
+ * @returns parsed tunnel parameters from the device response
+ */
 export declare function exchangeCoreTunnelParameters(socket: Socket): Promise<TunnelInfo>;
+/**
+ * End-to-end setup: handshake, TUN configuration, route, and forwarding on `secureServiceSocket`.
+ *
+ * @param secureServiceSocket — tunnel socket (e.g. from lockdown secure service)
+ * @returns connection handle with {@link TunnelConnection.closer} and packet APIs
+ */
 export declare function connectToTunnelLockdown(secureServiceSocket: Socket): Promise<TunnelConnection>;
 export {};

package/lib/tunnel.js

@@ -2,6 +2,10 @@ import { log } from './logger.js';
 import { TunTap } from './TunTap.js';
 import { EventEmitter } from 'node:events';
 import { Buffer } from 'node:buffer';
+/**
+ * Bridges a CoreDevice tunnel `Socket` and a {@link TunTap} interface: IPv6 framing, TUN I/O, and packet fan-out.
+ * Emits {@link TunnelManagerEvents} (currently `data` with {@link PacketData}) for TCP/UDP packets, same as registered consumers.
+ */
 export class TunnelManager extends EventEmitter {
     tun;
     cancelled;
@@ -11,6 +15,7 @@ export class TunnelManager extends EventEmitter {
     packetQueue;
     deviceConn;
     cleanupPromise;
+    /** Creates a manager with no TUN device until {@link TunnelManager.setupInterface} succeeds. */
     constructor() {
         super();
         this.tun = null;
@@ -22,12 +27,27 @@ export class TunnelManager extends EventEmitter {
         this.deviceConn = null;
         this.cleanupPromise = null;
     }
+    /**
+     * Register a listener for parsed tunnel packets (in addition to the `data` event).
+     *
+     * @param consumer — object with {@link PacketConsumer.onPacket}
+     */
     addPacketConsumer(consumer) {
         this.packetConsumers.add(consumer);
     }
+    /**
+     * Unregister a consumer previously added with {@link TunnelManager.addPacketConsumer}.
+     *
+     * @param consumer — same reference as passed to `addPacketConsumer`
+     */
     removePacketConsumer(consumer) {
         this.packetConsumers.delete(consumer);
     }
+    /**
+     * Async iterator over tunnel packets until {@link TunnelManager.stop} sets `cancelled`.
+     *
+     * @yields {@link PacketData} for each TCP/UDP packet
+     */
     async *getPacketStream() {
         const queue = [];
         let resolver = null;
@@ -64,6 +84,12 @@ export class TunnelManager extends EventEmitter {
             this.removePacketConsumer(consumer);
         }
     }
+    /**
+     * Open a {@link TunTap}, assign the client IPv6 address/MTU, and add a /128 route to the server.
+     *
+     * @param tunnelInfo — handshake result (client address, MTU, server address)
+     * @returns interface name, MTU, and the live {@link TunTap} instance
+     */
     async setupInterface(tunnelInfo) {
         log.debug(`Setting up tunnel with parameters:`, tunnelInfo);
         try {
@@ -98,6 +124,11 @@ export class TunnelManager extends EventEmitter {
             throw err;
         }
     }
+    /**
+     * Begin bidirectional forwarding: device socket ↔ TUN (requires {@link TunnelManager.setupInterface} first).
+     *
+     * @param deviceConn — connected tunnel socket after the CDTunnel handshake
+     */
     startForwarding(deviceConn) {
         if (!this.tun) {
             log.error('TUN device is not set up');
@@ -138,6 +169,19 @@ export class TunnelManager extends EventEmitter {
             log.error('Device connection error: ', err);
         });
     }
+    /**
+     * Idempotent shutdown: stop polling, destroy the socket, clear consumers, close the TUN device.
+     *
+     * @returns the same promise if already stopping/stopped
+     */
+    async stop() {
+        // Prevent multiple concurrent stops
+        if (this.cleanupPromise) {
+            return this.cleanupPromise;
+        }
+        this.cleanupPromise = this._performStop();
+        return this.cleanupPromise;
+    }
     processBuffer() {
         let offset = 0;
         // Process as many complete packets as available
@@ -283,14 +327,6 @@ export class TunnelManager extends EventEmitter {
             }
         }, 5); // Poll every 5ms
     }
-    async stop() {
-        // Prevent multiple concurrent stops
-        if (this.cleanupPromise) {
-            return this.cleanupPromise;
-        }
-        this.cleanupPromise = this._performStop();
-        return this.cleanupPromise;
-    }
     async _performStop() {
         const tunName = this.tun ? this.tun.name : 'unknown';
         log.debug(`Stopping tunnel manager for ${tunName}`);
@@ -335,6 +371,12 @@ function formatIPv6Address(buffer) {
     }
     return parts.join(':');
 }
+/**
+ * Perform the CDTunnel JSON handshake (8-byte magic + length-prefixed JSON) over `socket`.
+ *
+ * @param socket — connected stream to the tunnel service
+ * @returns parsed tunnel parameters from the device response
+ */
 export async function exchangeCoreTunnelParameters(socket) {
     return new Promise((resolve, reject) => {
         const request = {
@@ -412,6 +454,12 @@ export async function exchangeCoreTunnelParameters(socket) {
         socket.on('end', handleEnd);
     });
 }
+/**
+ * End-to-end setup: handshake, TUN configuration, route, and forwarding on `secureServiceSocket`.
+ *
+ * @param secureServiceSocket — tunnel socket (e.g. from lockdown secure service)
+ * @returns connection handle with {@link TunnelConnection.closer} and packet APIs
+ */
 export async function connectToTunnelLockdown(secureServiceSocket) {
     const tunnelManager = new TunnelManager();
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-tuntap",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Native TUN/TAP interface module for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",