{"id":30145401,"url":"https://github.com/appium/appium-ios-tuntap","last_synced_at":"2026-06-17T08:00:32.140Z","repository":{"id":302585351,"uuid":"963629594","full_name":"appium/appium-ios-tuntap","owner":"appium","description":"tuntap bridge to create a virtual connection for appium remotexpc module","archived":false,"fork":false,"pushed_at":"2026-06-13T11:04:17.000Z","size":825,"stargazers_count":7,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-13T13:23:42.591Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appium.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"open_collective":"appium"}},"created_at":"2025-04-10T01:16:00.000Z","updated_at":"2026-06-13T11:04:18.000Z","dependencies_parsed_at":"2025-07-03T07:11:51.332Z","dependency_job_id":"b098972f-6652-4679-919a-08c89679c3aa","html_url":"https://github.com/appium/appium-ios-tuntap","commit_stats":null,"previous_names":["appium/appium-ios-tuntap"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/appium/appium-ios-tuntap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-tuntap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-tuntap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-tuntap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-tuntap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appium","download_url":"https://codeload.github.com/appium/appium-ios-tuntap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-tuntap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34439296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-11T08:37:16.313Z","updated_at":"2026-06-17T08:00:32.116Z","avatar_url":"https://github.com/appium.png","language":"TypeScript","funding_links":["https://opencollective.com/appium"],"categories":[],"sub_categories":[],"readme":"# TunTap Bridge\n\nA native TUN/TAP interface module for Node.js that works on macOS, Linux, and Windows, with enhanced error handling, signal management, and thread safety.\n\n## Description\n\nThis module provides a Node.js interface to TUN/TAP virtual network devices, allowing you to create and manage network tunnels from JavaScript/TypeScript. It's useful for VPNs, network tunneling, and other network-related applications.\n\n## Features\n\n- **Cross-platform**: Works on macOS (utun), Linux (TUN/TAP), and Windows (WinTun)\n- **TypeScript support**: Full TypeScript definitions included\n- **Signal handling**: Graceful shutdown on SIGINT/SIGTERM\n- **Thread safety**: Safe to use from multiple Node.js worker threads\n- **Resource management**: Automatic cleanup of file descriptors and network interfaces\n- **Enhanced error handling**: Custom error types for better debugging\n- **Input validation**: Validates IPv6 addresses, MTU ranges, and buffer sizes\n- **Performance optimized**: Built with C++17 and compiler optimizations\n- **Network statistics**: Get interface statistics (RX/TX bytes, packets, errors)\n\n## Installation\n\n```bash\nnpm install appium-ios-tuntap\n```\n\n## Prerequisites\n\n### macOS\n\nOn macOS, the module uses the built-in utun interfaces. No additional setup is required, but you'll need administrator privileges to create and configure the interfaces.\n\n### Linux\n\nOn Linux, the module requires:\n\n1. **TUN/TAP Kernel Module**: The TUN/TAP kernel module must be loaded.\n\n   ```bash\n   # Check if the module is loaded\n   lsmod | grep tun\n\n   # If not loaded, load it\n   sudo modprobe tun\n\n   # To load it automatically at boot\n   echo \"tun\" | sudo tee -a /etc/modules\n   ```\n\n2. **Permissions**: The user running the application needs access to `/dev/net/tun`.\n\n   ```bash\n   # Option 1: Run your application with sudo\n   sudo node your-app.js\n\n   # Option 2: Add your user to the 'tun' group (if it exists)\n   sudo usermod -a -G tun your-username\n\n   # Option 3: Create a udev rule to set permissions\n   echo 'KERNEL==\"tun\", GROUP=\"your-username\", MODE=\"0660\"' | sudo tee /etc/udev/rules.d/99-tuntap.rules\n   sudo udevadm control --reload-rules\n   sudo udevadm trigger\n   ```\n\n3. **iproute2 Package**: The `ip` command is required for configuring interfaces.\n\n   ```bash\n   # Debian/Ubuntu\n   sudo apt install iproute2\n\n   # CentOS/RHEL\n   sudo yum install iproute\n\n   # Arch Linux\n   sudo pacman -S iproute2\n   ```\n\n4. **Development Headers**: If you're building from source, you'll need the Linux kernel headers.\n\n   ```bash\n   # Debian/Ubuntu\n   sudo apt install linux-headers-$(uname -r)\n\n   # CentOS/RHEL\n   sudo yum install kernel-devel\n\n   # Arch Linux\n   sudo pacman -S linux-headers\n   ```\n\n### Windows\n\nOn Windows the module uses [WinTun](https://www.wintun.net/) (the same userspace TUN driver shipped with WireGuard). Requirements:\n\n1. **`wintun.dll`**: ships with the package. The official signed binaries for `amd64`, `arm64`, `x86`, and `arm` are bundled under `vendor/wintun/bin/\u003carch\u003e/wintun.dll`; the addon discovers the right one automatically based on its own compile-time architecture. No download or copy step is required.\n2. **Administrator privileges**: required to create the kernel adapter and configure addresses/routes via `netsh`. Launch your shell with **Run as administrator**.\n3. **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`.\n\n## Usage\n\n### Basic Usage\n\n```javascript\nimport { TunTap } from 'appium-ios-tuntap';\n\n// Create a TUN device\nconst tun = new TunTap();\n\n// Open the device\nif (tun.open()) {\n  console.log(`Opened TUN device: ${tun.name}`);\n\n  // Configure the device with an IPv6 address and MTU\n  await tun.configure('fd00::1', 1500);\n\n  // Add a route\n  await tun.addRoute('fd00::/64');\n\n  // Read from the device\n  const data = tun.read(4096);\n  if (data.length \u003e 0) {\n    console.log(`Read ${data.length} bytes`);\n  }\n\n  // Write to the device\n  const buffer = Buffer.from([/* your packet data */]);\n  const bytesWritten = tun.write(buffer);\n  console.log(`Wrote ${bytesWritten} bytes`);\n\n  // Get interface statistics\n  const stats = await tun.getStats();\n  console.log('RX bytes:', stats.rxBytes);\n  console.log('TX bytes:', stats.txBytes);\n\n  // Close the device when done\n  tun.close();\n}\n```\n\n### Error Handling\n\n```javascript\nimport { TunTap, TunTapError, TunTapPermissionError, TunTapDeviceError } from 'appium-ios-tuntap';\n\ntry {\n  const tun = new TunTap();\n  tun.open();\n  await tun.configure('fe80::1', 1500);\n  // ... use the device ...\n  tun.close();\n} catch (err) {\n  if (err instanceof TunTapPermissionError) {\n    console.error('Permission denied. Please run with sudo.');\n  } else if (err instanceof TunTapDeviceError) {\n    console.error('Device error:', err.message);\n  } else if (err instanceof TunTapError) {\n    console.error('TUN/TAP error:', err.message);\n  } else {\n    console.error('Unexpected error:', err);\n  }\n}\n```\n\n### Tunnel Manager\n\n```javascript\nimport { connectToTunnelLockdown } from 'appium-ios-tuntap';\nimport { Socket } from 'net';\n\n// Create a socket connection to your tunnel endpoint\nconst socket = new Socket();\nsocket.connect(port, host, async () =\u003e {\n  try {\n    // Establish tunnel connection\n    const tunnel = await connectToTunnelLockdown(socket);\n\n    console.log('Tunnel established:', tunnel.Address);\n\n    // Add packet consumer\n    tunnel.addPacketConsumer({\n      onPacket: (packet) =\u003e {\n        console.log(`${packet.protocol} packet: ${packet.src}:${packet.sourcePort} → ${packet.dst}:${packet.destPort}`);\n      }\n    });\n\n    // Or use async iteration\n    for await (const packet of tunnel.getPacketStream()) {\n      console.log('Received packet:', packet);\n    }\n\n    // Close tunnel when done\n    await tunnel.closer();\n  } catch (err) {\n    console.error('Tunnel error:', err);\n  }\n});\n```\n\n## API Reference\n\n### TunTap Class\n\n#### Constructor\n- `new TunTap(name?: string)` - Create a new TUN/TAP device instance\n\n#### Methods\n- `open(): boolean` - Open the TUN device\n- `close(): boolean` - Close the TUN device\n- `read(maxSize?: number): Buffer` - Read data from the device (default: 4096 bytes)\n- `write(data: Buffer): number` - Write data to the device\n- `configure(address: string, mtu?: number): Promise\u003cvoid\u003e` - Configure IPv6 address and MTU\n- `addRoute(destination: string): Promise\u003cvoid\u003e` - Add a route to the device\n- `removeRoute(destination: string): Promise\u003cvoid\u003e` - Remove a route from the device\n- `getStats(): Promise\u003cStats\u003e` - Get interface statistics\n\n#### Properties\n- `name: string` - The device name (e.g., 'utun0', 'tun0')\n- `fd: number` - The native file descriptor on POSIX (macOS/Linux). Returns `-1` on Windows; Wintun does not expose a numeric file descriptor.\n\n### Error Types\n\n- `TunTapError` - Base error class for all TUN/TAP errors\n- `TunTapPermissionError` - Thrown when there are permission issues\n- `TunTapDeviceError` - Thrown when the device is not available or cannot be opened\n\n### Signal Handling\n\nThe module automatically handles SIGINT and SIGTERM signals for graceful shutdown. All open devices will be closed and network interfaces cleaned up when the process exits.\n\n## Troubleshooting\n\n### Linux Issues\n\n1. **\"TUN/TAP device not available\"**: The TUN/TAP kernel module is not loaded.\n   - Solution: `sudo modprobe tun`\n\n2. **\"Permission denied\" when opening /dev/net/tun**: The user doesn't have sufficient permissions.\n   - Solution: Run with sudo or add your user to the 'tun' group.\n\n3. **\"Permission denied\" when configuring the interface**: The user doesn't have sudo privileges.\n   - Solution: Run the application with sudo or configure sudo to allow the specific commands without a password.\n\n4. **\"Command not found\" when configuring the interface**: The `ip` command is not available.\n   - Solution: Install the iproute2 package.\n\n### macOS Issues\n\n1. **\"Failed to create control socket\"**: The application doesn't have sufficient permissions.\n   - Solution: Run with sudo.\n\n2. **\"Could not find an available utun device\"**: All utun devices are in use.\n   - Solution: Close other applications that might be using utun devices.\n\n## Debug Mode\n\nEnable debug logging by running your application with the `--debug` flag:\n\n```bash\nnode your-app.js --debug\n```\n\n## Testing\n\nMost tests for this module require **root privileges** (sudo) to create and manage TUN/TAP devices.\n\n- If you run the tests without root, privileged tests will be automatically skipped.\n- Some tests may interact with system networking; use caution on production systems.\n- The test suite is designed to clean up after itself, but always verify no stray TUN/TAP devices remain after running.\n\n### Running the Tests\n\nFrom the project root, run:\n\n```sh\nsudo npm run test:unit\n```\n\nOr, to run all tests:\n\n```sh\nsudo npm test\n```\n\nIf you are **not** running as root, you will see a message that tests are skipped.\n\n### Manual Testing for Signal Handling (v0.0.4+)\n\nAutomated tests cannot reliably verify process cleanup on SIGINT/SIGTERM due to test runner limitations.  \nTo manually verify the fix for signal handling (introduced in v0.0.4):\n\n1. Run the CLI utility:\n   ```sh\n   sudo node test/test-tuntap.js\n   ```\n2. While it is running, press `Ctrl+C` to send SIGINT.\n3. Confirm that:\n   - The process exits immediately.\n   - All TUN/TAP devices are closed and cleaned up.\n\nThis ensures the signal handler works as intended.\n\n## License\n\nApache-2.0\n\n### Third-party software\n\nThis 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/):\n\n- `vendor/wintun/bin/{amd64,arm64,x86,arm}/wintun.dll`\n- `vendor/wintun/LICENSE.txt` \u0026mdash; the upstream WinTun license; required when redistributing the DLL\n\nMaintainers can refresh the bundled binaries with `npm run refresh:wintun` after bumping `WINTUN_VERSION` in [scripts/fetch-wintun.mjs](scripts/fetch-wintun.mjs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappium%2Fappium-ios-tuntap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappium%2Fappium-ios-tuntap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappium%2Fappium-ios-tuntap/lists"}