appium-ios-tuntap 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+## 1.0.0 (2025-07-22)
+
+### Features
+
+* add packet streaming api instead of eventEmitter ([8c4df4b](https://github.com/appium/appium-ios-tuntap/commit/8c4df4bace59c2b29a567e2f9c81b1737500c42b))
+
+### Bug Fixes
+
+* add proper headers for linux ([967ea00](https://github.com/appium/appium-ios-tuntap/commit/967ea007b198f77f7e3aaaa1489dc5a0977bc5e6))
+* add test to ci ([8753e01](https://github.com/appium/appium-ios-tuntap/commit/8753e0109f0ad4120ac4db1318c103fc2be0f7c7))
+
+### Miscellaneous Chores
+
+* add semantics release ([#7](https://github.com/appium/appium-ios-tuntap/issues/7)) ([a52b2e6](https://github.com/appium/appium-ios-tuntap/commit/a52b2e6010e99f1e5518726a93b313efab6475fb))
+* **release:** bump version to 0.0.2 ([ed690cf](https://github.com/appium/appium-ios-tuntap/commit/ed690cfcc56c22a33cfc303960b46091619fe7e1))
+* **release:** initial release of tuntap-bridge npm package v0.0.1 ([0b68aea](https://github.com/appium/appium-ios-tuntap/commit/0b68aeaae2af9d0a7af386055f3667b6826c6d22))
+* turn release ([#8](https://github.com/appium/appium-ios-tuntap/issues/8)) ([3efc5a4](https://github.com/appium/appium-ios-tuntap/commit/3efc5a4eb7cb4e4f59daffb2623ead811292fa69))
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.3] - 2025-01-07
+
+### Added
+- Signal handling for graceful shutdown (SIGINT/SIGTERM)
+- Thread safety with mutex protection in C++ code
+- Custom error types for better error handling:
+  - `TunTapError` - Base error class
+  - `TunTapPermissionError` - Permission-related errors
+  - `TunTapDeviceError` - Device availability errors
+- Input validation for all methods:
+  - IPv6 address format validation
+  - MTU range checking (1280-65535)
+  - Buffer size validation
+  - Type checking for all parameters
+- New methods:
+  - `removeRoute()` - Remove routes from the interface
+  - `getStats()` - Get network interface statistics
+- Resource cleanup handlers for automatic cleanup on process exit
+- Timeout handling for network operations
+- Memory leak prevention with RAII pattern
+- Debug logging support with `--debug` flag
+- Comprehensive test suite
+
+### Changed
+- Updated to C++17 standard for better performance and modern features
+- Improved error messages with more context and suggestions
+- Enhanced buffer management to reduce memory allocations
+- Better handling of concurrent operations
+- Optimized compilation with `-O3` flag
+- Improved TypeScript type definitions
+
+### Fixed
+- File descriptor leaks on error conditions
+- Resource cleanup on unexpected process termination
+- Race conditions in multi-threaded environments
+- Memory leaks in error paths
+- Proper cleanup of network interfaces on shutdown
+- Better error handling for permission issues
+
+### Security
+- Added proper bounds checking for all buffer operations
+- Validated all user inputs to prevent invalid operations
+- Thread-safe operations to prevent race conditions
+
+## [0.0.2] - Previous Release
+
+### Added
+- Basic TUN/TAP device support for macOS and Linux
+- TypeScript support
+- Basic read/write operations
+- IPv6 configuration support
+
+## [0.0.1] - Initial Release
+
+### Added
+- Initial implementation of TUN/TAP bridge
+- Support for creating virtual network interfaces
+- Basic documentation

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "{}"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright JS Foundation and other contributors, https://js.foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,256 @@
+# 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.
+
+## Description
+
+This 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.
+
+## Features
+
+- **Cross-platform**: Works on macOS (utun) and Linux (TUN/TAP)
+- **TypeScript support**: Full TypeScript definitions included
+- **Signal handling**: Graceful shutdown on SIGINT/SIGTERM
+- **Thread safety**: Safe to use from multiple Node.js worker threads
+- **Resource management**: Automatic cleanup of file descriptors and network interfaces
+- **Enhanced error handling**: Custom error types for better debugging
+- **Input validation**: Validates IPv6 addresses, MTU ranges, and buffer sizes
+- **Performance optimized**: Built with C++17 and compiler optimizations
+- **Network statistics**: Get interface statistics (RX/TX bytes, packets, errors)
+
+## Installation
+
+```bash
+npm install appium-ios-tuntap
+```
+
+## Prerequisites
+
+### macOS
+
+On 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.
+
+### Linux
+
+On Linux, the module requires:
+
+1. **TUN/TAP Kernel Module**: The TUN/TAP kernel module must be loaded.
+
+   ```bash
+   # Check if the module is loaded
+   lsmod | grep tun
+
+   # If not loaded, load it
+   sudo modprobe tun
+
+   # To load it automatically at boot
+   echo "tun" | sudo tee -a /etc/modules
+   ```
+
+2. **Permissions**: The user running the application needs access to `/dev/net/tun`.
+
+   ```bash
+   # Option 1: Run your application with sudo
+   sudo node your-app.js
+
+   # Option 2: Add your user to the 'tun' group (if it exists)
+   sudo usermod -a -G tun your-username
+
+   # Option 3: Create a udev rule to set permissions
+   echo 'KERNEL=="tun", GROUP="your-username", MODE="0660"' | sudo tee /etc/udev/rules.d/99-tuntap.rules
+   sudo udevadm control --reload-rules
+   sudo udevadm trigger
+   ```
+
+3. **iproute2 Package**: The `ip` command is required for configuring interfaces.
+
+   ```bash
+   # Debian/Ubuntu
+   sudo apt install iproute2
+
+   # CentOS/RHEL
+   sudo yum install iproute
+
+   # Arch Linux
+   sudo pacman -S iproute2
+   ```
+
+4. **Development Headers**: If you're building from source, you'll need the Linux kernel headers.
+
+   ```bash
+   # Debian/Ubuntu
+   sudo apt install linux-headers-$(uname -r)
+
+   # CentOS/RHEL
+   sudo yum install kernel-devel
+
+   # Arch Linux
+   sudo pacman -S linux-headers
+   ```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import { TunTap } from 'appium-ios-tuntap';
+
+// Create a TUN device
+const tun = new TunTap();
+
+// Open the device
+if (tun.open()) {
+  console.log(`Opened TUN device: ${tun.name}`);
+
+  // Configure the device with an IPv6 address and MTU
+  await tun.configure('fd00::1', 1500);
+
+  // Add a route
+  await tun.addRoute('fd00::/64');
+
+  // Read from the device
+  const data = tun.read(4096);
+  if (data.length > 0) {
+    console.log(`Read ${data.length} bytes`);
+  }
+
+  // Write to the device
+  const buffer = Buffer.from([/* your packet data */]);
+  const bytesWritten = tun.write(buffer);
+  console.log(`Wrote ${bytesWritten} bytes`);
+
+  // Get interface statistics
+  const stats = await tun.getStats();
+  console.log('RX bytes:', stats.rxBytes);
+  console.log('TX bytes:', stats.txBytes);
+
+  // Close the device when done
+  tun.close();
+}
+```
+
+### Error Handling
+
+```javascript
+import { TunTap, TunTapError, TunTapPermissionError, TunTapDeviceError } from 'appium-ios-tuntap';
+
+try {
+  const tun = new TunTap();
+  tun.open();
+  await tun.configure('fe80::1', 1500);
+  // ... use the device ...
+  tun.close();
+} catch (err) {
+  if (err instanceof TunTapPermissionError) {
+    console.error('Permission denied. Please run with sudo.');
+  } else if (err instanceof TunTapDeviceError) {
+    console.error('Device error:', err.message);
+  } else if (err instanceof TunTapError) {
+    console.error('TUN/TAP error:', err.message);
+  } else {
+    console.error('Unexpected error:', err);
+  }
+}
+```
+
+### Tunnel Manager
+
+```javascript
+import { connectToTunnelLockdown } from 'appium-ios-tuntap';
+import { Socket } from 'net';
+
+// Create a socket connection to your tunnel endpoint
+const socket = new Socket();
+socket.connect(port, host, async () => {
+  try {
+    // Establish tunnel connection
+    const tunnel = await connectToTunnelLockdown(socket);
+
+    console.log('Tunnel established:', tunnel.Address);
+
+    // Add packet consumer
+    tunnel.addPacketConsumer({
+      onPacket: (packet) => {
+        console.log(`${packet.protocol} packet: ${packet.src}:${packet.sourcePort} → ${packet.dst}:${packet.destPort}`);
+      }
+    });
+
+    // Or use async iteration
+    for await (const packet of tunnel.getPacketStream()) {
+      console.log('Received packet:', packet);
+    }
+
+    // Close tunnel when done
+    await tunnel.closer();
+  } catch (err) {
+    console.error('Tunnel error:', err);
+  }
+});
+```
+
+## API Reference
+
+### TunTap Class
+
+#### Constructor
+- `new TunTap(name?: string)` - Create a new TUN/TAP device instance
+
+#### Methods
+- `open(): boolean` - Open the TUN device
+- `close(): boolean` - Close the TUN device
+- `read(maxSize?: number): Buffer` - Read data from the device (default: 4096 bytes)
+- `write(data: Buffer): number` - Write data to the device
+- `configure(address: string, mtu?: number): Promise<void>` - Configure IPv6 address and MTU
+- `addRoute(destination: string): Promise<void>` - Add a route to the device
+- `removeRoute(destination: string): Promise<void>` - Remove a route from the device
+- `getStats(): Promise<Stats>` - Get interface statistics
+
+#### Properties
+- `name: string` - The device name (e.g., 'utun0', 'tun0')
+- `fd: number` - The file descriptor of the device
+
+### Error Types
+
+- `TunTapError` - Base error class for all TUN/TAP errors
+- `TunTapPermissionError` - Thrown when there are permission issues
+- `TunTapDeviceError` - Thrown when the device is not available or cannot be opened
+
+### Signal Handling
+
+The 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.
+
+## Troubleshooting
+
+### Linux Issues
+
+1. **"TUN/TAP device not available"**: The TUN/TAP kernel module is not loaded.
+   - Solution: `sudo modprobe tun`
+
+2. **"Permission denied" when opening /dev/net/tun**: The user doesn't have sufficient permissions.
+   - Solution: Run with sudo or add your user to the 'tun' group.
+
+3. **"Permission denied" when configuring the interface**: The user doesn't have sudo privileges.
+   - Solution: Run the application with sudo or configure sudo to allow the specific commands without a password.
+
+4. **"Command not found" when configuring the interface**: The `ip` command is not available.
+   - Solution: Install the iproute2 package.
+
+### macOS Issues
+
+1. **"Failed to create control socket"**: The application doesn't have sufficient permissions.
+   - Solution: Run with sudo.
+
+2. **"Could not find an available utun device"**: All utun devices are in use.
+   - Solution: Close other applications that might be using utun devices.
+
+## Debug Mode
+
+Enable debug logging by running your application with the `--debug` flag:
+
+```bash
+node your-app.js --debug
+```
+
+## License
+
+Apache-2.0

package/binding.gyp

@@ -0,0 +1,84 @@
+{
+  "targets": [
+    {
+      "target_name": "tuntap",
+      "sources": [ "src/tuntap.cc" ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "cflags!": [ "-fno-exceptions" ],
+      "cflags_cc!": [ "-fno-exceptions" ],
+      "cflags": [
+        "-O3",
+        "-Wall",
+        "-Wextra",
+        "-Wno-unused-parameter",
+        "-fPIC"
+      ],
+      "cflags_cc": [ 
+        "-std=c++17",
+        "-Wno-vla-extension",
+        "-O3",
+        "-Wall",
+        "-Wextra",
+        "-Wno-unused-parameter",
+        "-fPIC"
+      ],
+      "xcode_settings": {
+        "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+        "CLANG_CXX_LIBRARY": "libc++",
+        "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
+        "MACOSX_DEPLOYMENT_TARGET": "10.15",
+        "GCC_OPTIMIZATION_LEVEL": "3",
+        "WARNING_CFLAGS": [
+          "-Wall",
+          "-Wextra",
+          "-Wno-unused-parameter",
+          "-Wno-vla-extension",
+          "-Wno-error"
+        ],
+        "OTHER_CPLUSPLUSFLAGS": [
+          "-O3",
+          "-fPIC"
+        ]
+      },
+      "msvs_settings": {
+        "VCCLCompilerTool": { 
+          "ExceptionHandling": 1,
+          "AdditionalOptions": [
+            "/std:c++17",
+            "/O2"
+          ]
+        }
+      },
+      "defines": [ 
+        "NAPI_CPP_EXCEPTIONS",
+        "NAPI_VERSION=8"
+      ],
+      "conditions": [
+        ["OS=='linux'", {
+          "cflags": [
+            "-pthread"
+          ],
+          "cflags_cc": [
+            "-pthread"
+          ],
+          "ldflags": [
+            "-pthread"
+          ]
+        }],
+        ["OS=='mac'", {
+          "xcode_settings": {
+            "OTHER_LDFLAGS": [
+              "-framework", "SystemConfiguration",
+              "-framework", "CoreFoundation"
+            ]
+          }
+        }]
+      ]
+    }
+  ]
+}