appium-ios-tuntap 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.1.6](https://github.com/appium/appium-ios-tuntap/compare/v0.1.5...v0.1.6) (2026-04-11)
+
+### Code Refactoring
+
+* refactor TUN/TAP native layer and harden TunTap TypeScript interface ([3fa00fe](https://github.com/appium/appium-ios-tuntap/commit/3fa00fe57a7cc44e6490d8e97d7defe2f782c0dc))
+
 ## [0.1.5](https://github.com/appium/appium-ios-tuntap/compare/v0.1.4...v0.1.5) (2026-04-09)
 
 ### Code Refactoring

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/d5aab3f73716915039a0303184de39d0/.npmrc",
+    "userconfig": "/private/var/folders/tb/y368xp_x10s3ty1b_mtl5mxr0000gn/T/8df09367f00966ee4ef2275480f452a9/.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,3 +1,4 @@
+export type PacketCallback = (data: Buffer) => void;
 export declare class TunTapError extends Error {
     code?: string | undefined;
     constructor(message: string, code?: string | undefined);
@@ -13,21 +14,34 @@ export declare class TunTapDeviceError extends TunTapError {
  */
 export declare class TunTap {
     private device;
-    private isOpen;
-    private isClosed;
+    private _isOpen;
+    private _isClosed;
     private removeExitListener;
     constructor(name?: string);
+    get isOpen(): boolean;
+    get isClosed(): boolean;
+    /**
+     * Throws if the device is not in a usable state (not open or already closed).
+     */
+    private assertReady;
     open(): boolean;
     close(): boolean;
     read(maxSize?: number): Buffer;
     write(data: Buffer): number;
+    /**
+     * Start event-driven reading from the TUN device.
+     * The callback is invoked with each packet read from the device.
+     */
+    startPolling(callback: PacketCallback, bufferSize?: number): void;
     get name(): string;
     get fd(): number;
     configure(address: string, mtu?: number): Promise<void>;
+    private configureLinux;
     addRoute(destination: string): Promise<void>;
+    private addRouteLinux;
     removeRoute(destination: string): Promise<void>;
     /**
-     * Get interface statistics
+     * Get interface statistics.
      */
     getStats(): Promise<{
         rxBytes: number;
@@ -37,4 +51,6 @@ export declare class TunTap {
         rxErrors: number;
         txErrors: number;
     }>;
+    private getStatsDarwin;
+    private getStatsLinux;
 }

package/lib/TunTap.js

@@ -1,35 +1,16 @@
-import { createRequire } from 'node:module';
 import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { isIPv6 } from 'node:net';
 import { promisify } from 'node:util';
 import { log } from './logger.js';
 const require = createRequire(import.meta.url);
-const nativeTuntap = require('../build/Release/tuntap.node');
 const execFileAsync = promisify(execFile);
-/**
- * Validates that a string is a safe IPv6 route destination (address or prefix).
- * Rejects shell metacharacters to prevent injection even though execFile is safe.
- */
-function isValidIPv6Route(destination) {
-    if (!destination || typeof destination !== 'string') {
-        return false;
-    }
-    const parts = destination.split('/');
-    if (parts.length > 2) {
-        return false;
-    }
-    const [addr, prefixLen] = parts;
-    if (!isIPv6(addr)) {
-        return false;
-    }
-    if (prefixLen !== undefined) {
-        const len = Number(prefixLen);
-        if (!Number.isInteger(len) || len < 0 || len > 128) {
-            return false;
-        }
-    }
-    return true;
-}
+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;
@@ -51,26 +32,44 @@ export class TunTapDeviceError extends TunTapError {
         this.name = 'TunTapDeviceError';
     }
 }
+/**
+ * Validates an IPv6 route destination (address with optional CIDR prefix).
+ */
+function isValidIPv6Route(destination) {
+    const parts = destination.split('/');
+    if (parts.length > 2) {
+        return false;
+    }
+    if (parts.length === 2) {
+        const prefix = parseInt(parts[1], 10);
+        if (isNaN(prefix) || prefix < 0 || prefix > 128 || parts[1] !== String(prefix)) {
+            return false;
+        }
+    }
+    return isIPv6(parts[0]);
+}
 /**
  * TUN/TAP device for IP tunneling
  */
 export class TunTap {
     device;
-    isOpen;
-    isClosed;
+    _isOpen;
+    _isClosed;
     removeExitListener = null;
     constructor(name = '') {
         this.device = new nativeTuntap.TunDevice(name);
-        this.isOpen = false;
-        this.isClosed = false;
-        // Register cleanup on process exit
+        this._isOpen = false;
+        this._isClosed = false;
+        // Register cleanup on process exit only.
+        // Signal handling is the caller's responsibility — libraries should not
+        // install global signal handlers. The kernel cleans up the TUN fd on exit.
         const cleanup = () => {
-            if (this.isOpen && !this.isClosed) {
+            if (this._isOpen && !this._isClosed) {
                 try {
                     this.close();
                 }
                 catch (err) {
-                    log.error('Error closing TUN device during cleanup:', err);
+                    log.error('Error closing TUN device during cleanup:', err.message);
                 }
             }
         };
@@ -79,42 +78,59 @@ export class TunTap {
             process.removeListener('exit', cleanup);
         };
     }
+    get isOpen() {
+        return this._isOpen;
+    }
+    get isClosed() {
+        return this._isClosed;
+    }
+    /**
+     * 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');
+        }
+        if (this._isClosed) {
+            throw new TunTapError('Device has been closed');
+        }
+    }
     open() {
-        if (this.isClosed) {
+        if (this._isClosed) {
             throw new TunTapError('Device has been closed and cannot be reopened');
         }
-        if (!this.isOpen) {
+        if (!this._isOpen) {
             try {
-                this.isOpen = this.device.open();
-                if (!this.isOpen) {
+                this._isOpen = this.device.open();
+                if (!this._isOpen) {
                     throw new TunTapDeviceError('Failed to open TUN device');
                 }
             }
             catch (err) {
-                // Re-throw with more specific error types
-                if (err.message?.includes('Permission denied') || err.message?.includes('sudo')) {
-                    throw new TunTapPermissionError(err.message);
+                const message = err.message ?? '';
+                if (message.includes('Permission denied') || message.includes('sudo')) {
+                    throw new TunTapPermissionError(message);
                 }
-                else if (err.message?.includes('not available') || err.message?.includes('does not exist')) {
-                    throw new TunTapDeviceError(err.message);
+                if (message.includes('not available') || message.includes('does not exist')) {
+                    throw new TunTapDeviceError(message);
                 }
                 throw err;
             }
         }
-        return this.isOpen;
+        return this._isOpen;
     }
     close() {
         if (this.removeExitListener) {
             this.removeExitListener();
             this.removeExitListener = null;
         }
-        if (!this.isClosed) {
+        if (!this._isClosed) {
             try {
-                if (this.isOpen) {
+                if (this._isOpen) {
                     this.device.close();
-                    this.isOpen = false;
+                    this._isOpen = false;
                 }
-                this.isClosed = true;
+                this._isClosed = true;
             }
             catch (err) {
                 throw new TunTapError(`Failed to close device: ${err.message}`);
@@ -122,15 +138,10 @@ export class TunTap {
         }
         return true;
     }
-    read(maxSize = 4096) {
-        if (!this.isOpen) {
-            throw new TunTapError('Device not open');
-        }
-        if (this.isClosed) {
-            throw new TunTapError('Device has been closed');
-        }
-        if (maxSize <= 0 || maxSize > 65536) {
-            throw new RangeError('Read size must be between 1 and 65536 bytes');
+    read(maxSize = DEFAULT_READ_BUFFER_SIZE) {
+        this.assertReady();
+        if (maxSize <= 0 || maxSize > MAX_BUFFER_SIZE) {
+            throw new RangeError(`Read size must be between 1 and ${MAX_BUFFER_SIZE} bytes`);
         }
         try {
             return this.device.read(maxSize);
@@ -140,20 +151,15 @@ export class TunTap {
         }
     }
     write(data) {
-        if (!this.isOpen) {
-            throw new TunTapError('Device not open');
-        }
-        if (this.isClosed) {
-            throw new TunTapError('Device has been closed');
-        }
+        this.assertReady();
         if (!Buffer.isBuffer(data)) {
             throw new TypeError('Data must be a Buffer');
         }
         if (data.length === 0) {
             return 0;
         }
-        if (data.length > 65536) {
-            throw new RangeError('Write data too large (max 65536 bytes)');
+        if (data.length > MAX_BUFFER_SIZE) {
+            throw new RangeError(`Write data too large (max ${MAX_BUFFER_SIZE} bytes)`);
         }
         try {
             const result = this.device.write(data);
@@ -166,57 +172,44 @@ export class TunTap {
             throw new TunTapError(`Write failed: ${err.message}`);
         }
     }
+    /**
+     * Start event-driven reading from the TUN device.
+     * The callback is invoked with each packet read from the device.
+     */
+    startPolling(callback, bufferSize = MAX_BUFFER_SIZE) {
+        this.assertReady();
+        if (typeof callback !== 'function') {
+            throw new TypeError('Callback must be a function');
+        }
+        if (bufferSize <= 0 || bufferSize > MAX_BUFFER_SIZE) {
+            throw new RangeError(`Buffer size must be between 1 and ${MAX_BUFFER_SIZE} bytes`);
+        }
+        this.device.startPolling(callback, bufferSize);
+    }
     get name() {
         return this.device.getName();
     }
     get fd() {
         return this.device.getFd();
     }
-    async configure(address, mtu = 1500) {
-        if (!this.isOpen) {
-            throw new TunTapError('Device not open');
-        }
-        if (this.isClosed) {
-            throw new TunTapError('Device has been closed');
-        }
+    async configure(address, mtu = DEFAULT_MTU) {
+        this.assertReady();
         if (!isIPv6(address)) {
             throw new TypeError('Invalid IPv6 address format');
         }
-        // Validate MTU
-        if (mtu < 1280 || mtu > 65535) {
-            throw new RangeError('MTU must be between 1280 and 65535');
+        if (mtu < MIN_MTU || mtu > MAX_BUFFER_SIZE) {
+            throw new RangeError(`MTU must be between ${MIN_MTU} and ${MAX_BUFFER_SIZE}`);
         }
-        const platform = process.platform;
         try {
-            if (platform === 'darwin') {
+            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') {
-                try {
-                    await execFileAsync('which', ['ip']);
-                }
-                catch {
-                    throw new TunTapError('The "ip" command is not available. Please install the iproute2 package (e.g., sudo apt install iproute2)');
-                }
-                try {
-                    await execFileAsync('sudo', ['ip', '-6', 'addr', 'add', `${address}/64`, 'dev', this.name]);
-                    await execFileAsync('sudo', ['ip', 'link', 'set', 'dev', this.name, 'up', 'mtu', String(mtu)]);
-                }
-                catch (err) {
-                    if (err.message.includes('Permission denied')) {
-                        throw new TunTapPermissionError(`Permission denied when configuring network interface. Make sure you have sudo privileges or run the application with sudo.`);
-                    }
-                    else if (err.message.includes('File exists')) {
-                        log.warn(`Address ${address} may already be configured on ${this.name}`);
-                    }
-                    else {
-                        throw err;
-                    }
-                }
+            else if (PLATFORM === 'linux') {
+                await this.configureLinux(address, mtu);
             }
             else {
-                throw new TunTapError(`Unsupported platform: ${platform}`);
+                throw new TunTapError(`Unsupported platform: ${PLATFORM}`);
             }
         }
         catch (err) {
@@ -226,133 +219,159 @@ export class TunTap {
             throw new TunTapError(`Failed to configure TUN interface: ${err.message}`);
         }
     }
-    async addRoute(destination) {
-        if (!this.isOpen) {
-            throw new TunTapError('Device not open');
+    async configureLinux(address, mtu) {
+        try {
+            await execFileAsync('which', ['ip']);
         }
-        if (this.isClosed) {
-            throw new TunTapError('Device has been closed');
+        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)]);
+    }
+    async addRoute(destination) {
+        this.assertReady();
+        if (!destination || typeof destination !== 'string') {
+            throw new TypeError('Destination must be a non-empty string');
         }
         if (!isValidIPv6Route(destination)) {
-            throw new TypeError('Destination must be a valid IPv6 address or prefix (e.g. fd00::1/64)');
+            throw new TypeError('Destination must be a valid IPv6 address or CIDR (e.g., fd00::1/128)');
         }
-        const platform = process.platform;
         try {
-            if (platform === 'darwin') {
+            if (PLATFORM === 'darwin') {
                 await execFileAsync('sudo', ['route', '-n', 'add', '-inet6', destination, '-interface', this.name]);
             }
-            else if (platform === 'linux') {
-                try {
-                    await execFileAsync('sudo', ['ip', '-6', 'route', 'add', destination, 'dev', this.name]);
-                }
-                catch (err) {
-                    if (err.message.includes('Permission denied')) {
-                        throw new TunTapPermissionError(`Permission denied when adding route. Make sure you have sudo privileges or run the application with sudo.`);
-                    }
-                    else if (err.message.includes('File exists')) {
-                        log.info(`Route to ${destination} already exists`);
-                    }
-                    else {
-                        throw err;
-                    }
-                }
+            else if (PLATFORM === 'linux') {
+                await this.addRouteLinux(destination);
             }
             else {
-                throw new TunTapError(`Unsupported platform: ${platform}`);
+                throw new TunTapError(`Unsupported platform: ${PLATFORM}`);
             }
         }
         catch (err) {
             if (err instanceof TunTapError) {
                 throw err;
             }
-            if (!err.message.includes('Route to') && !err.message.includes('already exists')) {
-                throw new TunTapError(`Failed to add route: ${err.message}`);
+            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;
         }
     }
     async removeRoute(destination) {
-        if (!this.isOpen) {
-            throw new TunTapError('Device not open');
+        this.assertReady();
+        if (!destination || typeof destination !== 'string') {
+            throw new TypeError('Destination must be a non-empty string');
         }
         if (!isValidIPv6Route(destination)) {
-            throw new TypeError('Destination must be a valid IPv6 address or prefix (e.g. fd00::1/64)');
+            throw new TypeError('Destination must be a valid IPv6 address or CIDR');
         }
-        const platform = process.platform;
         try {
-            if (platform === 'darwin') {
+            if (PLATFORM === 'darwin') {
                 await execFileAsync('sudo', ['route', '-n', 'delete', '-inet6', destination]);
             }
-            else if (platform === 'linux') {
+            else if (PLATFORM === 'linux') {
                 await execFileAsync('sudo', ['ip', '-6', 'route', 'del', destination, 'dev', this.name]);
             }
             else {
-                throw new TunTapError(`Unsupported platform: ${platform}`);
+                throw new TunTapError(`Unsupported platform: ${PLATFORM}`);
             }
         }
         catch (err) {
-            if (!err.message.includes('not in table') && !err.message.includes('No such process')) {
-                throw new TunTapError(`Failed to remove route: ${err.message}`);
+            const message = err.message;
+            if (message.includes('not in table') || message.includes('No such process')) {
+                return;
             }
+            throw new TunTapError(`Failed to remove route: ${message}`);
         }
     }
     /**
-     * Get interface statistics
+     * Get interface statistics.
      */
     async getStats() {
-        if (!this.isOpen) {
-            throw new TunTapError('Device not open');
-        }
-        const platform = process.platform;
+        this.assertReady();
         try {
-            if (platform === 'darwin') {
-                const { stdout } = await execFileAsync('netstat', ['-I', this.name, '-b']);
-                const lines = stdout.trim().split('\n');
-                if (lines.length < 2) {
-                    throw new Error('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,
-                };
-            }
-            else if (platform === 'linux') {
-                const { stdout } = await execFileAsync('ip', ['-s', 'link', 'show', this.name]);
-                const lines = stdout.trim().split('\n');
-                let rxIndex = -1;
-                let txIndex = -1;
-                for (let i = 0; i < lines.length; i++) {
-                    if (lines[i].includes('RX:')) {
-                        rxIndex = i + 1;
-                    }
-                    if (lines[i].includes('TX:')) {
-                        txIndex = i + 1;
-                    }
-                }
-                if (rxIndex === -1 || txIndex === -1) {
-                    throw new Error('Could not parse interface statistics');
-                }
-                const rxStats = lines[rxIndex].trim().split(/\s+/);
-                const txStats = lines[txIndex].trim().split(/\s+/);
-                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,
-                };
+            if (PLATFORM === 'darwin') {
+                return await this.getStatsDarwin();
             }
-            else {
-                throw new TunTapError(`Unsupported platform: ${platform}`);
+            if (PLATFORM === 'linux') {
+                return await this.getStatsLinux();
             }
+            throw new TunTapError(`Unsupported platform: ${PLATFORM}`);
         }
         catch (err) {
+            if (err instanceof TunTapError) {
+                throw err;
+            }
             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');
+        }
+        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/index.d.ts

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

package/package.json

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

package/src/tuntap.cc

@@ -9,7 +9,6 @@
 #include <memory>
 #include <mutex>
 #include <atomic>
-#include <csignal>
 #include <uv.h>
 
 #ifdef __APPLE__
@@ -20,17 +19,14 @@
 #include <netinet/in.h>
 #include <netinet6/in6_var.h>
 #define UTUN_CONTROL_NAME "com.apple.net.utun_control"
+#define UTUN_HEADER_SIZE 4
 #else
 #include <linux/if.h>
 #include <linux/if_tun.h>
 #include <sys/stat.h>
+#define UTUN_HEADER_SIZE 0
 #endif
 
-// Global state for signal handling
-static std::atomic<bool> g_shutdown_requested(false);
-static std::mutex g_devices_mutex;
-static std::vector<class TunDevice*> g_active_devices;
-
 // RAII wrapper for file descriptors
 class FileDescriptor {
 private:
@@ -46,11 +42,9 @@ public:
     }
   }
 
-  // Disable copy
   FileDescriptor(const FileDescriptor&) = delete;
   FileDescriptor& operator=(const FileDescriptor&) = delete;
 
-  // Enable move
   FileDescriptor(FileDescriptor&& other) noexcept : fd_(other.fd_) {
     other.fd_ = -1;
   }
@@ -90,14 +84,11 @@ public:
   TunDevice(const Napi::CallbackInfo& info);
   ~TunDevice();
 
-private:
-  static Napi::FunctionReference constructor;
-  static std::once_flag signal_handler_flag;
-
-public:
   void CloseInternal();
 
 private:
+  static Napi::FunctionReference constructor;
+
   Napi::Value Open(const Napi::CallbackInfo& info);
   Napi::Value Close(const Napi::CallbackInfo& info);
   Napi::Value Read(const Napi::CallbackInfo& info);
@@ -113,9 +104,9 @@ private:
 
   uv_poll_t* poll_handle_ = nullptr;
   Napi::ThreadSafeFunction tsfn_;
+  static constexpr size_t MAX_POLL_BUFFER = 65535;
+  size_t poll_buffer_size_ = MAX_POLL_BUFFER;
 
-  void RegisterDevice();
-  void UnregisterDevice();
   void StopPolling();
   static void PollCallback(uv_poll_t* handle, int status, int events);
 };
@@ -157,19 +148,6 @@ TunDevice::~TunDevice() {
   CloseInternal();
 }
 
-void TunDevice::RegisterDevice() {
-  std::lock_guard<std::mutex> lock(g_devices_mutex);
-  g_active_devices.push_back(this);
-}
-
-void TunDevice::UnregisterDevice() {
-  std::lock_guard<std::mutex> lock(g_devices_mutex);
-  g_active_devices.erase(
-    std::remove(g_active_devices.begin(), g_active_devices.end(), this),
-    g_active_devices.end()
-  );
-}
-
 void TunDevice::CloseInternal() {
   if (is_open_.exchange(false)) {
     StopPolling();
@@ -185,21 +163,15 @@ Napi::Value TunDevice::Open(const Napi::CallbackInfo& info) {
     return Napi::Boolean::New(env, true);
   }
 
-  if (g_shutdown_requested.load()) {
-    Napi::Error::New(env, "Shutdown in progress").ThrowAsJavaScriptException();
-    return Napi::Boolean::New(env, false);
-  }
-
 #ifdef __APPLE__
-  // macOS implementation using utun interfaces
+  // macOS: create utun interface via PF_SYSTEM control socket
   struct ctl_info ctlInfo;
   struct sockaddr_ctl sc;
 
   FileDescriptor temp_fd(socket(PF_SYSTEM, SOCK_DGRAM, SYSPROTO_CONTROL));
   if (!temp_fd.is_valid()) {
-    std::string error = "Failed to create control socket: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Failed to create control socket: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
@@ -208,9 +180,8 @@ Napi::Value TunDevice::Open(const Napi::CallbackInfo& info) {
   ctlInfo.ctl_name[sizeof(ctlInfo.ctl_name) - 1] = '\0';
 
   if (ioctl(temp_fd.get(), CTLIOCGINFO, &ctlInfo) < 0) {
-    std::string error = "Failed to get utun control info: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Failed to get utun control info: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
@@ -220,7 +191,7 @@ Napi::Value TunDevice::Open(const Napi::CallbackInfo& info) {
   sc.ss_sysaddr = SYSPROTO_CONTROL;
   sc.sc_id = ctlInfo.ctl_id;
 
-  // Parse utun number if provided, otherwise use a default (utun0 = unit 1)
+  // Parse utun number if provided, otherwise auto-select (utun0 = unit 1)
   int utun_unit = 0;
   if (!name_.empty() && name_.find("utun") == 0) {
     try {
@@ -232,24 +203,20 @@ Napi::Value TunDevice::Open(const Napi::CallbackInfo& info) {
 
   if (utun_unit > 0) {
     sc.sc_unit = utun_unit;
-    // Try to connect with the specified unit
     if (connect(temp_fd.get(), (struct sockaddr*)&sc, sizeof(sc)) < 0) {
-      std::string error = "Failed to connect to utun control socket with specified unit: ";
-      error += strerror(errno);
-      Napi::Error::New(env, error).ThrowAsJavaScriptException();
+      Napi::Error::New(env, std::string("Failed to connect to utun with specified unit: ") + strerror(errno))
+        .ThrowAsJavaScriptException();
       return Napi::Boolean::New(env, false);
     }
   } else {
-    // Find the first available unit
     bool connected = false;
     for (sc.sc_unit = 1; sc.sc_unit < 255; sc.sc_unit++) {
       if (connect(temp_fd.get(), (struct sockaddr*)&sc, sizeof(sc)) == 0) {
         connected = true;
         break;
       } else if (errno != EBUSY) {
-        std::string error = "Failed to connect to utun control socket: ";
-        error += strerror(errno);
-        Napi::Error::New(env, error).ThrowAsJavaScriptException();
+        Napi::Error::New(env, std::string("Failed to connect to utun control socket: ") + strerror(errno))
+          .ThrowAsJavaScriptException();
         return Napi::Boolean::New(env, false);
       }
     }
@@ -260,55 +227,49 @@ Napi::Value TunDevice::Open(const Napi::CallbackInfo& info) {
     }
   }
 
-  // Get the utun device name
   char utunname[20];
   socklen_t utunname_len = sizeof(utunname);
   if (getsockopt(temp_fd.get(), SYSPROTO_CONTROL, UTUN_OPT_IFNAME, utunname, &utunname_len) < 0) {
-    std::string error = "Failed to get utun interface name: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Failed to get utun interface name: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
   name_ = std::string(utunname);
 
 #else
-  // Linux implementation using TUN/TAP
-  // First check if /dev/net/tun exists
+  // Linux: create TUN device via /dev/net/tun
   struct stat statbuf;
   if (stat("/dev/net/tun", &statbuf) != 0) {
-    std::string error = "TUN/TAP device not available: /dev/net/tun does not exist. ";
-    error += "Please ensure the TUN/TAP kernel module is loaded (modprobe tun).";
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env,
+      "TUN/TAP device not available: /dev/net/tun does not exist. "
+      "Please ensure the TUN/TAP kernel module is loaded (modprobe tun).")
+      .ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
   FileDescriptor temp_fd(open("/dev/net/tun", O_RDWR));
   if (!temp_fd.is_valid()) {
-    std::string error = "Failed to open /dev/net/tun: ";
-    error += strerror(errno);
-    error += ". This usually means you don't have sufficient permissions. ";
-    error += "Try running with sudo or add your user to the 'tun' group.";
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env,
+      std::string("Failed to open /dev/net/tun: ") + strerror(errno) +
+      ". This usually means you don't have sufficient permissions. "
+      "Try running with sudo or add your user to the 'tun' group.")
+      .ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
   struct ifreq ifr;
   memset(&ifr, 0, sizeof(ifr));
-
-  // Set flags - IFF_TUN for TUN device, IFF_NO_PI to not provide packet info
   ifr.ifr_flags = IFF_TUN | IFF_NO_PI;
 
-  // If name is provided, use it
   if (!name_.empty()) {
     strncpy(ifr.ifr_name, name_.c_str(), IFNAMSIZ - 1);
     ifr.ifr_name[IFNAMSIZ - 1] = '\0';
   }
 
   if (ioctl(temp_fd.get(), TUNSETIFF, &ifr) < 0) {
-    std::string error = "Failed to configure TUN device: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Failed to configure TUN device: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
@@ -318,20 +279,17 @@ Napi::Value TunDevice::Open(const Napi::CallbackInfo& info) {
   // Set non-blocking mode
   int flags = fcntl(temp_fd.get(), F_GETFL, 0);
   if (flags < 0) {
-    std::string error = "Failed to get file descriptor flags: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Failed to get file descriptor flags: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
   if (fcntl(temp_fd.get(), F_SETFL, flags | O_NONBLOCK) < 0) {
-    std::string error = "Failed to set non-blocking mode: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Failed to set non-blocking mode: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return Napi::Boolean::New(env, false);
   }
 
-  // Transfer ownership to member variable
   fd_ = std::move(temp_fd);
   is_open_ = true;
 
@@ -354,63 +312,44 @@ Napi::Value TunDevice::Read(const Napi::CallbackInfo& info) {
     return env.Null();
   }
 
-  if (g_shutdown_requested.load()) {
-    return Napi::Buffer<uint8_t>::New(env, 0);
-  }
-
-  // Read buffer size
-  size_t buffer_size = 4096; // Default
+  size_t buffer_size = 4096;
   if (info.Length() > 0 && info[0].IsNumber()) {
     buffer_size = info[0].As<Napi::Number>().Uint32Value();
+    if (buffer_size == 0 || buffer_size > MAX_POLL_BUFFER) {
+      Napi::RangeError::New(env, "Read buffer size must be between 1 and " + std::to_string(MAX_POLL_BUFFER)).ThrowAsJavaScriptException();
+      return env.Null();
+    }
   }
 
-  // Create buffer for reading
-  Napi::Buffer<uint8_t> buffer = Napi::Buffer<uint8_t>::New(env, buffer_size);
-  uint8_t* data = buffer.Data();
-
 #ifdef __APPLE__
-  // On macOS, reads include a 4-byte protocol family prefix
-  // We'll read the packet and then remove this prefix
-  std::vector<uint8_t> tmp_buffer(buffer_size + 4);
-
-  ssize_t bytes_read = read(fd_.get(), tmp_buffer.data(), buffer_size + 4);
-  if (bytes_read <= 0) {
+  // macOS: reads include a 4-byte protocol family prefix that must be stripped
+  std::vector<uint8_t> raw(buffer_size + 4);
+  ssize_t n = read(fd_.get(), raw.data(), raw.size());
+  if (n <= 0) {
     if (errno == EAGAIN || errno == EWOULDBLOCK) {
-      // No data available
       return Napi::Buffer<uint8_t>::New(env, 0);
     }
-
-    // Error occurred
-    std::string error = "Read error: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Read error: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return env.Null();
   }
-
-  // Skip the 4-byte protocol family header
-  if (bytes_read > 4) {
-    memcpy(data, tmp_buffer.data() + 4, bytes_read - 4);
-    return Napi::Buffer<uint8_t>::Copy(env, data, bytes_read - 4);
-  } else {
+  if (n <= 4) {
     return Napi::Buffer<uint8_t>::New(env, 0);
   }
+  return Napi::Buffer<uint8_t>::Copy(env, raw.data() + 4, n - 4);
 #else
-  // On Linux, we read directly into the buffer
-  ssize_t bytes_read = read(fd_.get(), data, buffer_size);
-  if (bytes_read < 0) {
+  // Linux: raw IP packets directly
+  std::vector<uint8_t> raw(buffer_size);
+  ssize_t n = read(fd_.get(), raw.data(), raw.size());
+  if (n < 0) {
     if (errno == EAGAIN || errno == EWOULDBLOCK) {
-      // No data available
       return Napi::Buffer<uint8_t>::New(env, 0);
     }
-
-    // Error occurred
-    std::string error = "Read error: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Read error: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return env.Null();
   }
-
-  return Napi::Buffer<uint8_t>::Copy(env, data, bytes_read);
+  return Napi::Buffer<uint8_t>::Copy(env, raw.data(), n);
 #endif
 }
 
@@ -423,11 +362,6 @@ Napi::Value TunDevice::Write(const Napi::CallbackInfo& info) {
     return Napi::Number::New(env, -1);
   }
 
-  if (g_shutdown_requested.load()) {
-    Napi::Error::New(env, "Shutdown in progress").ThrowAsJavaScriptException();
-    return Napi::Number::New(env, -1);
-  }
-
   if (info.Length() < 1 || !info[0].IsBuffer()) {
     Napi::TypeError::New(env, "Expected buffer as first argument").ThrowAsJavaScriptException();
     return Napi::Number::New(env, -1);
@@ -438,34 +372,26 @@ Napi::Value TunDevice::Write(const Napi::CallbackInfo& info) {
   size_t length = buffer.Length();
 
 #ifdef __APPLE__
-  // On macOS, we need to prepend a 4-byte protocol family header
-  // For IPv6, the protocol family is AF_INET6 (30 on macOS)
-  std::vector<uint8_t> tmp_buffer(length + 4);
+  // macOS: prepend 4-byte AF_INET6 protocol family header
+  std::vector<uint8_t> frame(length + 4);
   uint32_t family = htonl(AF_INET6);
+  memcpy(frame.data(), &family, 4);
+  memcpy(frame.data() + 4, data, length);
 
-  memcpy(tmp_buffer.data(), &family, 4);
-  memcpy(tmp_buffer.data() + 4, data, length);
-
-  ssize_t bytes_written = write(fd_.get(), tmp_buffer.data(), length + 4);
+  ssize_t bytes_written = write(fd_.get(), frame.data(), frame.size());
   if (bytes_written < 0) {
-    std::string error = "Write error: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Write error: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return Napi::Number::New(env, -1);
   }
-
-  // Return the original data length without the header
   return Napi::Number::New(env, bytes_written > 4 ? bytes_written - 4 : 0);
 #else
-  // On Linux, we write directly from the buffer
   ssize_t bytes_written = write(fd_.get(), data, length);
   if (bytes_written < 0) {
-    std::string error = "Write error: ";
-    error += strerror(errno);
-    Napi::Error::New(env, error).ThrowAsJavaScriptException();
+    Napi::Error::New(env, std::string("Write error: ") + strerror(errno))
+      .ThrowAsJavaScriptException();
     return Napi::Number::New(env, -1);
   }
-
   return Napi::Number::New(env, bytes_written);
 #endif
 }
@@ -488,12 +414,25 @@ Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
     Napi::Error::New(env, "Device not open").ThrowAsJavaScriptException();
     return env.Null();
   }
-  if (!info[0].IsFunction()) {
+
+  if (info.Length() < 1 || !info[0].IsFunction()) {
     Napi::TypeError::New(env, "Expected function as first argument").ThrowAsJavaScriptException();
     return env.Null();
   }
+
   StopPolling();
 
+  // Optional buffer size as second argument (default: MAX_POLL_BUFFER)
+  poll_buffer_size_ = MAX_POLL_BUFFER;
+  if (info.Length() > 1 && info[1].IsNumber()) {
+    auto size = info[1].As<Napi::Number>().Uint32Value();
+    if (size == 0 || size > MAX_POLL_BUFFER) {
+      Napi::RangeError::New(env, "Buffer size must be between 1 and " + std::to_string(MAX_POLL_BUFFER)).ThrowAsJavaScriptException();
+      return env.Null();
+    }
+    poll_buffer_size_ = size;
+  }
+
   tsfn_ = Napi::ThreadSafeFunction::New(
     env,
     info[0].As<Napi::Function>(),
@@ -502,27 +441,46 @@ Napi::Value TunDevice::StartPolling(const Napi::CallbackInfo& info) {
     1
   );
 
+  uv_loop_t* loop = nullptr;
+  napi_status napi_st = napi_get_uv_event_loop(env, &loop);
+  if (napi_st != napi_ok || loop == nullptr) {
+    tsfn_.Release();
+    tsfn_ = nullptr;
+    Napi::Error::New(env, "Failed to acquire event loop").ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
   auto handle = std::make_unique<uv_poll_t>();
-  if (uv_poll_init(uv_default_loop(), handle.get(), fd_.get()) != 0) {
-      Napi::Error::New(env, "Failed to initialize poll handle").ThrowAsJavaScriptException();
-      return env.Null();
+  if (uv_poll_init(loop, handle.get(), fd_.get()) != 0) {
+    tsfn_.Release();
+    tsfn_ = nullptr;
+    Napi::Error::New(env, "Failed to initialize poll handle").ThrowAsJavaScriptException();
+    return env.Null();
   }
 
   handle->data = this;
   if (uv_poll_start(handle.get(), UV_READABLE, PollCallback) != 0) {
-      Napi::Error::New(env, "Failed to start polling").ThrowAsJavaScriptException();
-      return env.Null();
+    // Properly close the initialized-but-not-started handle
+    uv_close(reinterpret_cast<uv_handle_t*>(handle.release()), [](uv_handle_t* h) {
+      delete reinterpret_cast<uv_poll_t*>(h);
+    });
+    tsfn_.Release();
+    tsfn_ = nullptr;
+    Napi::Error::New(env, "Failed to start polling").ThrowAsJavaScriptException();
+    return env.Null();
   }
 
   poll_handle_ = handle.release();
-
   return env.Undefined();
 }
 
 void TunDevice::StopPolling() {
   if (poll_handle_) {
     uv_poll_stop(poll_handle_);
-    delete poll_handle_;
+    // Must use uv_close before freeing a libuv handle
+    uv_close(reinterpret_cast<uv_handle_t*>(poll_handle_), [](uv_handle_t* handle) {
+      delete reinterpret_cast<uv_poll_t*>(handle);
+    });
     poll_handle_ = nullptr;
   }
   if (tsfn_) {
@@ -534,6 +492,10 @@ void TunDevice::StopPolling() {
 void TunDevice::PollCallback(uv_poll_t* handle, int status, int events) {
   if (status < 0) {
     fprintf(stderr, "tuntap poll error: %s\n", uv_strerror(status));
+    auto* self = static_cast<TunDevice*>(handle->data);
+    if (self) {
+      self->StopPolling();
+    }
     return;
   }
 
@@ -541,35 +503,36 @@ void TunDevice::PollCallback(uv_poll_t* handle, int status, int events) {
     return;
   }
 
-  TunDevice* self = static_cast<TunDevice*>(handle->data);
+  auto* self = static_cast<TunDevice*>(handle->data);
   if (!self || !self->is_open_.load() || !self->fd_.is_valid()) {
     return;
   }
 
-  std::vector<uint8_t> buffer(4096);
+  std::vector<uint8_t> buffer(self->poll_buffer_size_ + UTUN_HEADER_SIZE);
   ssize_t bytes_read = read(self->fd_.get(), buffer.data(), buffer.size());
 
-  if (bytes_read <= 0) {
+  if (bytes_read == 0) {
+    self->StopPolling();
+    return;
+  }
+  if (bytes_read < 0) {
     if (errno != EAGAIN && errno != EWOULDBLOCK) {
-        fprintf(stderr, "tuntap read error: %s\n", strerror(errno));
+      fprintf(stderr, "tuntap read error: %s\n", strerror(errno));
+      self->StopPolling();
     }
     return;
   }
 
-#ifdef __APPLE__
-  if (bytes_read > 4) {
-    self->tsfn_.BlockingCall([buffer = std::move(buffer), bytes_read](Napi::Env env, Napi::Function jsCallback) {
-      jsCallback.Call({ Napi::Buffer<uint8_t>::Copy(env, buffer.data() + 4, bytes_read - 4) });
-    });
+  if (bytes_read > UTUN_HEADER_SIZE) {
+    self->tsfn_.BlockingCall(
+      [buf = std::move(buffer), bytes_read](Napi::Env env, Napi::Function jsCallback) {
+        if (env == nullptr || jsCallback.IsEmpty()) return;
+        jsCallback.Call({ Napi::Buffer<uint8_t>::Copy(env, buf.data() + UTUN_HEADER_SIZE, bytes_read - UTUN_HEADER_SIZE) });
+      }
+    );
   }
-#else
-  self->tsfn_.BlockingCall([buffer = std::move(buffer), bytes_read](Napi::Env env, Napi::Function jsCallback) {
-    jsCallback.Call({ Napi::Buffer<uint8_t>::Copy(env, buffer.data(), bytes_read) });
-  });
-#endif
 }
 
-// Module initialization
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
   return TunDevice::Init(env, exports);
 }