appium-ios-tuntap 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.4.1](https://github.com/appium/appium-ios-tuntap/compare/v0.4.0...v0.4.1) (2026-05-31)
+
+### Bug Fixes
+
+* Improve tunnel performance ([#45](https://github.com/appium/appium-ios-tuntap/issues/45)) ([576d353](https://github.com/appium/appium-ios-tuntap/commit/576d3535137bb0cf79634ab820b3675db6cbbb86))
+
+## [0.4.0](https://github.com/appium/appium-ios-tuntap/compare/v0.3.0...v0.4.0) (2026-05-30)
+
+### Features
+
+* implement Windows (WinTun) JavaScript platform layer ([#44](https://github.com/appium/appium-ios-tuntap/issues/44)) ([da2a9bb](https://github.com/appium/appium-ios-tuntap/commit/da2a9bba1d7226f67ce0f00c533df72164aac858))
+
 ## [0.3.0](https://github.com/appium/appium-ios-tuntap/compare/v0.2.5...v0.3.0) (2026-05-22)
 
 ### Features

package/README.md

@@ -1,6 +1,6 @@
 # TunTap Bridge
 
-A native TUN/TAP interface module for Node.js that works on both macOS and Linux, with enhanced error handling, signal management, and thread safety.
+A native TUN/TAP interface module for Node.js that works on macOS, Linux, and Windows, with enhanced error handling, signal management, and thread safety.
 
 ## Description
 
@@ -8,7 +8,7 @@ This module provides a Node.js interface to TUN/TAP virtual network devices, all
 
 ## Features
 
-- **Cross-platform**: Works on macOS (utun) and Linux (TUN/TAP)
+- **Cross-platform**: Works on macOS (utun), Linux (TUN/TAP), and Windows (WinTun)
 - **TypeScript support**: Full TypeScript definitions included
 - **Signal handling**: Graceful shutdown on SIGINT/SIGTERM
 - **Thread safety**: Safe to use from multiple Node.js worker threads
@@ -88,6 +88,14 @@ On Linux, the module requires:
    sudo pacman -S linux-headers
    ```
 
+### Windows
+
+On Windows the module uses [WinTun](https://www.wintun.net/) (the same userspace TUN driver shipped with WireGuard). Requirements:
+
+1. **`wintun.dll`**: ships with the package. The official signed binaries for `amd64`, `arm64`, `x86`, and `arm` are bundled under `vendor/wintun/bin/<arch>/wintun.dll`; the addon discovers the right one automatically based on its own compile-time architecture. No download or copy step is required.
+2. **Administrator privileges**: required to create the kernel adapter and configure addresses/routes via `netsh`. Launch your shell with **Run as administrator**.
+3. **Build toolchain (only if compiling from source)**: Visual Studio Build Tools 2022 with the C++ workload, the Windows 10 SDK, and Python 3.x on `PATH`.
+
 ## Usage
 
 ### Basic Usage
@@ -207,7 +215,7 @@ socket.connect(port, host, async () => {
 
 #### Properties
 - `name: string` - The device name (e.g., 'utun0', 'tun0')
-- `fd: number` - The file descriptor of the device
+- `fd: number` - The native file descriptor on POSIX (macOS/Linux). Returns `-1` on Windows; Wintun does not expose a numeric file descriptor.
 
 ### Error Types
 
@@ -294,3 +302,12 @@ This ensures the signal handler works as intended.
 ## License
 
 Apache-2.0
+
+### Third-party software
+
+This package redistributes the official signed **WinTun** DLLs (version 0.14.1) from [wintun.net](https://www.wintun.net/) under the bundled-binary license shipped by the WinTun project. The unmodified binaries and the upstream license live under [vendor/wintun/](vendor/wintun/):
+
+- `vendor/wintun/bin/{amd64,arm64,x86,arm}/wintun.dll`
+- `vendor/wintun/LICENSE.txt` &mdash; the upstream WinTun license; required when redistributing the DLL
+
+Maintainers can refresh the bundled binaries with `npm run refresh:wintun` after bumping `WINTUN_VERSION` in [scripts/fetch-wintun.mjs](scripts/fetch-wintun.mjs).

package/binding.gyp

@@ -51,7 +51,7 @@
         "VCCLCompilerTool": {
           "ExceptionHandling": 1,
           "AdditionalOptions": [
-            "/std:c++17",
+            "/std:c++20",
             "/O2"
           ]
         }

package/lib/index.d.ts

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

package/lib/index.js

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

package/lib/platform/create-platform.js

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

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

@@ -0,0 +1,17 @@
+/**
+ * Throws {@link TunTapPermissionError} unless the current process is an
+ * elevated (Administrator) Windows process. Mirrors `assertEffectiveRoot`
+ * from {@link ./require-root.ts} for POSIX.
+ */
+export declare function assertAdminOnWindows(): Promise<void>;
+/**
+ * Returns true when the current process is running with Administrator
+ * privileges on Windows. Implementation runs `net session` (which always
+ * exists, regardless of locale) and inspects the exit code.
+ *
+ * The result is memoized for the lifetime of the process; admin status cannot
+ * change between calls without restarting the shell.
+ */
+export declare const isAdministrator: (() => Promise<boolean>) & {
+    cache: Map<unknown, Promise<boolean>>;
+};

package/lib/platform/require-admin.js

@@ -0,0 +1,32 @@
+import { util } from '@appium/support';
+import { TunTapPermissionError } from '../errors.js';
+import { execFileAsync } from './exec.js';
+/**
+ * Throws {@link TunTapPermissionError} unless the current process is an
+ * elevated (Administrator) Windows process. Mirrors `assertEffectiveRoot`
+ * from {@link ./require-root.ts} for POSIX.
+ */
+export async function assertAdminOnWindows() {
+    if (await isAdministrator()) {
+        return;
+    }
+    throw new TunTapPermissionError('TUN interface configuration and routing require Administrator privileges on Windows. ' +
+        'Re-launch the shell with "Run as administrator".');
+}
+/**
+ * Returns true when the current process is running with Administrator
+ * privileges on Windows. Implementation runs `net session` (which always
+ * exists, regardless of locale) and inspects the exit code.
+ *
+ * The result is memoized for the lifetime of the process; admin status cannot
+ * change between calls without restarting the shell.
+ */
+export const isAdministrator = util.memoize(async function isAdministratorUncached() {
+    try {
+        await execFileAsync('net', ['session'], { windowsHide: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+});

package/lib/platform/windows.d.ts

@@ -0,0 +1,13 @@
+import type { TunTapInterfaceStats, TunTapPlatform } from './types.js';
+/** Windows implementation backed by `netsh` for configuration/routing and
+ *  PowerShell `Get-NetAdapterStatistics` for byte counters. */
+export declare class WindowsTunTapPlatform 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/windows.js

@@ -0,0 +1,195 @@
+import { TunTapError } from '../errors.js';
+import { log } from '../logger.js';
+import { assertAdminOnWindows } from './require-admin.js';
+import { execFileAsync } from './exec.js';
+/** Tightly-restricted character set for adapter names passed into PowerShell. */
+const SAFE_NAME_RE = /^[A-Za-z0-9_\- ]+$/;
+/** Phrases that indicate `netsh` could not find the requested route/address. */
+const MISSING_TARGET_HINTS = [
+    'element not found',
+    'cannot find',
+    'no matching',
+    'does not exist',
+    'not found',
+];
+/** Windows implementation backed by `netsh` for configuration/routing and
+ *  PowerShell `Get-NetAdapterStatistics` for byte counters. */
+export class WindowsTunTapPlatform {
+    /** @inheritdoc */
+    async configure(interfaceName, address, mtu) {
+        await assertAdminOnWindows();
+        assertSafeAdapterName(interfaceName);
+        log.debug(`[win] configure: interface=${interfaceName} address=${address} mtu=${mtu}`);
+        await addIpv6Address(interfaceName, address);
+        await setIpv6Mtu(interfaceName, mtu);
+    }
+    /** @inheritdoc */
+    async addRoute(interfaceName, destination) {
+        await assertAdminOnWindows();
+        assertSafeAdapterName(interfaceName);
+        log.debug(`[win] addRoute: interface=${interfaceName} destination=${destination}`);
+        await addIpv6Route(interfaceName, destination);
+        // WinTun presents as an Ethernet adapter, so Windows requires Neighbor
+        // Discovery (NDP) before it will send packets through the interface.
+        // For /128 host routes we seed a static neighbor entry so NDP is bypassed
+        // and the first connection attempt is not silently dropped.
+        if (destination.endsWith('/128')) {
+            const address = destination.slice(0, -4);
+            await addStaticNeighbor(interfaceName, address);
+        }
+    }
+    /** @inheritdoc */
+    async removeRoute(interfaceName, destination) {
+        await assertAdminOnWindows();
+        assertSafeAdapterName(interfaceName);
+        await deleteIpv6Route(interfaceName, destination);
+    }
+    /** @inheritdoc */
+    async getStats(interfaceName) {
+        assertSafeAdapterName(interfaceName);
+        const script = `Get-NetAdapterStatistics -Name '${interfaceName}' ` +
+            '| Select-Object ReceivedBytes,SentBytes,ReceivedUnicastPackets,' +
+            'SentUnicastPackets,ReceivedDiscardedPackets,OutboundDiscardedPackets ' +
+            '| ConvertTo-Json -Compress';
+        const { stdout } = await execFileAsync('powershell', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-ExecutionPolicy',
+            'Bypass',
+            '-Command',
+            script,
+        ]);
+        let parsed;
+        try {
+            parsed = JSON.parse(stdout);
+        }
+        catch {
+            throw new TunTapError(`Failed to parse Get-NetAdapterStatistics output: ${stdout.trim()}`);
+        }
+        const num = (key) => {
+            const value = parsed[key];
+            const n = typeof value === 'number' ? value : parseInt(String(value ?? ''), 10);
+            return Number.isFinite(n) ? n : 0;
+        };
+        return {
+            rxBytes: num('ReceivedBytes'),
+            rxPackets: num('ReceivedUnicastPackets'),
+            rxErrors: num('ReceivedDiscardedPackets'),
+            txBytes: num('SentBytes'),
+            txPackets: num('SentUnicastPackets'),
+            txErrors: num('OutboundDiscardedPackets'),
+        };
+    }
+}
+/** Validates an adapter name before embedding in a PowerShell expression. */
+function assertSafeAdapterName(interfaceName) {
+    if (!SAFE_NAME_RE.test(interfaceName)) {
+        throw new TunTapError(`Refusing to use adapter name with unsupported characters: ${JSON.stringify(interfaceName)}`);
+    }
+}
+function isMissingTargetError(err) {
+    const message = String(err?.message ?? '').toLowerCase();
+    return MISSING_TARGET_HINTS.some((hint) => message.includes(hint));
+}
+async function addIpv6Address(interfaceName, address) {
+    try {
+        const r = await execFileAsync('netsh', [
+            'interface',
+            'ipv6',
+            'add',
+            'address',
+            `interface=${interfaceName}`,
+            `address=${address}/64`,
+            'store=active',
+        ]);
+        log.debug(`[win] add address ok: ${r.stdout.trim() || '(no output)'}`);
+    }
+    catch (err) {
+        const message = err.message ?? '';
+        log.warn(`[win] add address err: ${message}`);
+        if (!/already exists|object already/i.test(message)) {
+            throw err;
+        }
+        log.warn(`Address ${address} may already be configured on ${interfaceName}`);
+    }
+}
+async function setIpv6Mtu(interfaceName, mtu) {
+    try {
+        const r = await execFileAsync('netsh', [
+            'interface',
+            'ipv6',
+            'set',
+            'subinterface',
+            interfaceName,
+            `mtu=${mtu}`,
+            'store=active',
+        ]);
+        log.debug(`[win] set mtu ok: ${r.stdout.trim() || '(no output)'}`);
+    }
+    catch (err) {
+        log.warn(`[win] set mtu err: ${err.message ?? err}`);
+        throw err;
+    }
+}
+async function addIpv6Route(interfaceName, destination) {
+    try {
+        const r = await execFileAsync('netsh', [
+            'interface',
+            'ipv6',
+            'add',
+            'route',
+            destination,
+            interfaceName,
+            'store=active',
+        ]);
+        log.debug(`[win] add route ok: ${r.stdout.trim() || '(no output)'}`);
+    }
+    catch (err) {
+        const message = err.message ?? '';
+        log.warn(`[win] add route err: ${message}`);
+        if (/already exists|object already/i.test(message)) {
+            log.debug(`Route to ${destination} already exists`);
+            return;
+        }
+        throw err;
+    }
+}
+async function deleteIpv6Route(interfaceName, destination) {
+    try {
+        await execFileAsync('netsh', [
+            'interface',
+            'ipv6',
+            'delete',
+            'route',
+            destination,
+            interfaceName,
+            'store=active',
+        ]);
+    }
+    catch (err) {
+        if (isMissingTargetError(err)) {
+            return;
+        }
+        throw err;
+    }
+}
+async function addStaticNeighbor(interfaceName, address) {
+    log.debug(`[win] addStaticNeighbor: interface=${interfaceName} address=${address}`);
+    try {
+        const r = await execFileAsync('netsh', [
+            'interface',
+            'ipv6',
+            'add',
+            'neighbor',
+            interfaceName,
+            address,
+            '00-00-00-00-00-01',
+            'store=active',
+        ]);
+        log.debug(`[win] add neighbor ok: ${r.stdout.trim() || '(no output)'}`);
+    }
+    catch (err) {
+        const msg = err.message ?? String(err);
+        log.warn(`[win] add neighbor err: ${msg}`);
+    }
+}

package/lib/tunnel/constants.d.ts

@@ -0,0 +1,10 @@
+/** CDTunnel lockdown handshake MTU (IPv6 minimum). */
+export declare const CD_TUNNEL_MTU = 1280;
+export declare const CD_TUNNEL_MAGIC = "CDTunnel";
+export declare const CD_TUNNEL_MAGIC_SIZE = 8;
+export declare const CD_TUNNEL_HEADER_SIZE: number;
+export declare const CD_TUNNEL_HANDSHAKE_TIMEOUT_MS = 30000;
+export declare const IPV6_HEADER_SIZE = 40;
+export declare const IPV6_VERSION = 6;
+export declare const IPPROTO_TCP = 6;
+export declare const IPPROTO_UDP = 17;

package/lib/tunnel/constants.js

@@ -0,0 +1,10 @@
+/** CDTunnel lockdown handshake MTU (IPv6 minimum). */
+export const CD_TUNNEL_MTU = 1280;
+export const CD_TUNNEL_MAGIC = 'CDTunnel';
+export const CD_TUNNEL_MAGIC_SIZE = 8;
+export const CD_TUNNEL_HEADER_SIZE = CD_TUNNEL_MAGIC_SIZE + 2;
+export const CD_TUNNEL_HANDSHAKE_TIMEOUT_MS = 30_000;
+export const IPV6_HEADER_SIZE = 40;
+export const IPV6_VERSION = 6;
+export const IPPROTO_TCP = 6;
+export const IPPROTO_UDP = 17;

package/lib/tunnel/index.d.ts

@@ -0,0 +1,2 @@
+export type { PacketConsumer, PacketData, TunnelConnection, TunnelManagerEvents } from './types.js';
+export { TunnelManager, connectToTunnelLockdown, exchangeCoreTunnelParameters } from './manager.js';

package/lib/tunnel/index.js

@@ -0,0 +1 @@
+export { TunnelManager, connectToTunnelLockdown, exchangeCoreTunnelParameters } from './manager.js';

package/lib/{tunnel.d.ts → tunnel/manager.d.ts}

@@ -1,57 +1,7 @@
-import { TunTap } from './TunTap.js';
+import { TunTap } from '../TunTap.js';
 import { EventEmitter } from 'node:events';
-import { Socket } from 'node:net';
-import { Buffer } from 'node:buffer';
-export interface PacketData {
-    protocol: 'TCP' | 'UDP';
-    src: string;
-    dst: string;
-    sourcePort: number;
-    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 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 TunnelManagerEvents {
-    data: [packet: PacketData];
-}
-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>;
-}
-interface TunnelClientParameters {
-    address: string;
-    mtu: number;
-}
-interface TunnelInfo {
-    clientParameters: TunnelClientParameters;
-    serverAddress: string;
-    serverRSDPort?: number;
-}
+import type { Socket } from 'node:net';
+import type { PacketConsumer, PacketData, TunnelConnection, TunnelInfo, TunnelManagerEvents } from './types.js';
 /**
  * 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.
@@ -59,14 +9,11 @@ interface TunnelInfo {
 export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
     private tun;
     private cancelled;
-    private readInterval;
+    private mtu;
     private buffer;
-    private packetConsumers;
-    private packetQueue;
+    private readonly packetConsumers;
     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).
      *
@@ -108,7 +55,11 @@ export declare class TunnelManager extends EventEmitter<TunnelManagerEvents> {
      * @returns the same promise if already stopping/stopped
      */
     stop(): Promise<void>;
+    private hasPacketTap;
     private processBuffer;
+    private writeDeviceFrameToTun;
+    private tapL4Packet;
+    private dispatchPacketData;
     private startTunReadLoop;
     private _performStop;
 }
@@ -126,4 +77,3 @@ export declare function exchangeCoreTunnelParameters(socket: Socket): Promise<Tu
  * @returns connection handle with {@link TunnelConnection.closer} and packet APIs
  */
 export declare function connectToTunnelLockdown(secureServiceSocket: Socket): Promise<TunnelConnection>;
-export {};