appium-ios-tuntap 0.2.5 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* add Windows (WinTun) native backend ([#43](https://github.com/appium/appium-ios-tuntap/issues/43)) ([565b4c1](https://github.com/appium/appium-ios-tuntap/commit/565b4c1cfd2ddf4956ed32ade4f8208cd0d4f0f6)), closes [#ifdef](https://github.com/appium/appium-ios-tuntap/issues/ifdef)
+
 ## [0.2.5](https://github.com/appium/appium-ios-tuntap/compare/v0.2.4...v0.2.5) (2026-05-14)
 
 ### Code Refactoring

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

@@ -20,7 +20,7 @@
         "-Wno-unused-parameter",
         "-fPIC"
       ],
-      "cflags_cc": [ 
+      "cflags_cc": [
         "-std=c++17",
         "-Wno-vla-extension",
         "-O3",
@@ -48,15 +48,15 @@
         ]
       },
       "msvs_settings": {
-        "VCCLCompilerTool": { 
+        "VCCLCompilerTool": {
           "ExceptionHandling": 1,
           "AdditionalOptions": [
-            "/std:c++17",
+            "/std:c++20",
             "/O2"
           ]
         }
       },
-      "defines": [ 
+      "defines": [
         "NAPI_CPP_EXCEPTIONS",
         "NAPI_VERSION=8"
       ],
@@ -89,6 +89,22 @@
               "-framework", "CoreFoundation"
             ]
           }
+        }],
+        ["OS=='win'", {
+          "sources": [
+            "src/native/handle.cc",
+            "src/native/wintun_loader.cc",
+            "src/native/tun_backend_windows.cc"
+          ],
+          "libraries": [
+            "iphlpapi.lib",
+            "ws2_32.lib"
+          ],
+          "defines": [
+            "_WIN32_WINNT=0x0A00",
+            "WIN32_LEAN_AND_MEAN",
+            "NOMINMAX"
+          ]
         }]
       ]
     }

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.d.ts

@@ -1,6 +1,6 @@
 import { TunTap } from './TunTap.js';
 import { EventEmitter } from 'node:events';
-import { Socket } from 'node:net';
+import type { Socket } from 'node:net';
 import { Buffer } from 'node:buffer';
 export interface PacketData {
     protocol: 'TCP' | 'UDP';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-tuntap",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "description": "Native TUN/TAP interface module for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -15,16 +15,19 @@
     "format": "prettier -w ./src ./test",
     "format:check": "prettier --check ./src ./test",
     "install": "node-gyp-build",
+    "refresh:wintun": "node scripts/fetch-wintun.mjs",
     "prepare": "npm run build",
     "test": "npm run test:integration && npm run test:unit",
-    "test:unit": "mocha 'test/unit/**/*.spec.mjs' --exit --timeout 2m",
-    "test:integration": "mocha 'test/integration/**/*.spec.mjs' --exit --timeout 2m"
+    "test:unit": "mocha \"test/unit/**/*.spec.mjs\" --exit --timeout 2m",
+    "test:integration": "mocha \"test/integration/**/*.spec.mjs\" --exit --timeout 2m"
   },
   "files": [
     "src/tuntap.cc",
     "src/native",
     "lib",
     "prebuilds",
+    "scripts",
+    "vendor",
     "binding.gyp",
     "package.json",
     "README.md",
@@ -56,6 +59,7 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^25.0.1",
+    "commander": "^14.0.3",
     "conventional-changelog-conventionalcommits": "^9.0.0",
     "mocha": "^11.7.5",
     "prebuildify": "^6.0.1",

package/scripts/fetch-wintun.mjs

@@ -0,0 +1,70 @@
+// Maintainer-only helper that refreshes the bundled WinTun binaries committed
+// under vendor/wintun/. The npm `install` hook does NOT invoke this script —
+// the package ships with the official signed DLLs already checked in. Run
+// `npm run refresh:wintun -- --version <semver>` to pull a different release.
+
+import {fs, logger, net, tempDir, zip} from '@appium/support';
+import {Command} from 'commander';
+import {join, dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const log = logger.getLogger('refresh-wintun');
+
+const DEFAULT_WINTUN_VERSION = '0.14.1';
+const BUNDLED_ARCHES = ['amd64', 'arm64', 'x86', 'arm'];
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), '..');
+const vendorDir = join(rootDir, 'vendor', 'wintun');
+
+async function deployDll(arch, extractDir) {
+  const destDir = join(vendorDir, 'bin', arch);
+  await fs.mkdir(destDir, {recursive: true});
+  const src = join(extractDir, 'wintun', 'bin', arch, 'wintun.dll');
+  const dest = join(destDir, 'wintun.dll');
+  await fs.copyFile(src, dest);
+  log.info(`wintun.dll (${arch}) -> ${dest}`);
+}
+
+async function deployLicense(extractDir) {
+  const src = join(extractDir, 'wintun', 'LICENSE.txt');
+  const dest = join(vendorDir, 'LICENSE.txt');
+  await fs.copyFile(src, dest);
+  log.info(`LICENSE.txt -> ${dest}`);
+}
+
+async function refreshWintun(version) {
+  const url = `https://www.wintun.net/builds/wintun-${version}.zip`;
+  const tmpDir = await tempDir.openDir();
+  try {
+    const zipPath = join(tmpDir, 'wintun.zip');
+    const extractDir = join(tmpDir, 'out');
+    await fs.mkdir(extractDir, {recursive: true});
+
+    log.info(`Downloading WinTun ${version}...`);
+    await net.downloadFile(url, zipPath);
+    await zip.extractAllTo(zipPath, extractDir);
+
+    await fs.mkdir(vendorDir, {recursive: true});
+    await Promise.all([
+      ...BUNDLED_ARCHES.map((arch) => deployDll(arch, extractDir)),
+      deployLicense(extractDir),
+    ]);
+  } finally {
+    await fs.rimraf(tmpDir);
+  }
+}
+
+const program = new Command();
+program
+  .name('refresh-wintun')
+  .description('Refresh the bundled WinTun binaries under vendor/wintun/')
+  .option(
+    '-v, --version <semver>',
+    'WinTun release version to download',
+    DEFAULT_WINTUN_VERSION,
+  )
+  .action(async (options) => {
+    await refreshWintun(options.version);
+  });
+
+await program.parseAsync(process.argv);

package/src/native/handle.cc

@@ -0,0 +1,59 @@
+#ifdef _WIN32
+
+#include "handle.h"
+
+namespace {
+
+bool IsRealHandle(HANDLE handle) {
+  return handle != nullptr && handle != INVALID_HANDLE_VALUE;
+}
+
+} // namespace
+
+Handle::Handle() : handle_(nullptr) {}
+
+Handle::Handle(HANDLE handle) : handle_(handle) {}
+
+Handle::~Handle() {
+  if (IsRealHandle(handle_)) {
+    ::CloseHandle(handle_);
+  }
+}
+
+Handle::Handle(Handle&& other) noexcept : handle_(other.handle_) {
+  other.handle_ = nullptr;
+}
+
+Handle& Handle::operator=(Handle&& other) noexcept {
+  if (this != &other) {
+    if (IsRealHandle(handle_)) {
+      ::CloseHandle(handle_);
+    }
+    handle_ = other.handle_;
+    other.handle_ = nullptr;
+  }
+  return *this;
+}
+
+HANDLE Handle::get() const {
+  return handle_;
+}
+
+HANDLE Handle::release() {
+  HANDLE temp = handle_;
+  handle_ = nullptr;
+  return temp;
+}
+
+bool Handle::is_valid() const {
+  return IsRealHandle(handle_);
+}
+
+void Handle::reset(HANDLE handle) {
+  if (IsRealHandle(handle_)) {
+    ::CloseHandle(handle_);
+  }
+  handle_ = handle;
+}
+
+#endif

package/src/native/handle.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#ifdef _WIN32
+
+#include <windows.h>
+
+// RAII wrapper for a Win32 `HANDLE`. Mirrors `FileDescriptor` so backends can
+// rely on the same lifetime semantics regardless of OS.
+class Handle {
+public:
+  Handle();
+  explicit Handle(HANDLE handle);
+  ~Handle();
+
+  Handle(const Handle&) = delete;
+  Handle& operator=(const Handle&) = delete;
+
+  Handle(Handle&& other) noexcept;
+  Handle& operator=(Handle&& other) noexcept;
+
+  HANDLE get() const;
+  HANDLE release();
+  bool is_valid() const;
+  void reset(HANDLE handle = nullptr);
+
+private:
+  HANDLE handle_;
+};
+
+#endif

package/src/native/tun_backend.h

@@ -1,7 +1,7 @@
 #pragma once
 
-#if !defined(__linux__) && !defined(__APPLE__)
-#error "appium-ios-tuntap native addon supports only Linux and macOS"
+#if !defined(__linux__) && !defined(__APPLE__) && !defined(_WIN32)
+#error "appium-ios-tuntap native addon supports only Linux, macOS, and Windows"
 #endif
 
 #include <cstddef>
@@ -27,9 +27,25 @@ enum class ReadPacketStatus {
   Error,
 };
 
+/**
+ * Backend abstraction that hides OS-specific TUN device handling from the
+ * N-API surface.
+ *
+ * Each backend owns:
+ * - its native handle (POSIX file descriptor or Win32 `HANDLE`)
+ * - the receive-loop primitive it needs (libuv `uv_poll_t` on POSIX, a
+ *   dedicated worker thread plus a Win32 event on Windows)
+ */
 class TunPlatformBackend {
 public:
+  // Invoked once per packet read by the receive loop. Always called on a
+  // background thread (libuv loop thread on POSIX, worker thread on Windows);
+  // the caller in `tuntap.cc` is responsible for marshalling onto the JS
+  // thread via `Napi::ThreadSafeFunction`.
   using PacketCallback = std::function<void(std::vector<uint8_t>)>;
+
+  // Invoked at most once when the receive loop encounters a fatal error and
+  // stops. The receive loop must not deliver any further packets afterwards.
   using ErrorCallback = std::function<void(const std::string&)>;
 
   virtual ~TunPlatformBackend() = default;
@@ -47,6 +63,8 @@ public:
                               size_t length,
                               std::string& error) = 0;
 
+  // Begin asynchronous packet delivery. `loop` is supplied by Node-API and is
+  // used by POSIX backends for `uv_poll_init`; Windows ignores it.
   virtual bool StartReceiveLoop(uv_loop_t* loop,
                                 size_t buffer_size,
                                 PacketCallback on_packet,
@@ -54,6 +72,8 @@ public:
                                 std::string& error) = 0;
   virtual void StopReceiveLoop() = 0;
 
+  // Returns the underlying POSIX file descriptor when one exists. Backends
+  // without a numeric fd (e.g. Wintun on Windows) return `-1`.
   virtual int GetNativeFd() const { return -1; }
 };