appium-ios-tuntap 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/binding.gyp

@@ -20,7 +20,7 @@
         "-Wno-unused-parameter",
         "-fPIC"
       ],
-      "cflags_cc": [ 
+      "cflags_cc": [
         "-std=c++17",
         "-Wno-vla-extension",
         "-O3",
@@ -48,7 +48,7 @@
         ]
       },
       "msvs_settings": {
-        "VCCLCompilerTool": { 
+        "VCCLCompilerTool": {
           "ExceptionHandling": 1,
           "AdditionalOptions": [
             "/std:c++17",
@@ -56,7 +56,7 @@
           ]
         }
       },
-      "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/package.json

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

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; }
 };
 

package/src/native/tun_backend_windows.cc

@@ -0,0 +1,370 @@
+#ifdef _WIN32
+
+#include "tun_backend.h"
+
+#include <windows.h>
+
+#include <atomic>
+#include <chrono>
+#include <cstring>
+#include <sstream>
+#include <thread>
+#include <utility>
+#include <vector>
+
+#include "handle.h"
+#include "wintun_loader.h"
+
+namespace {
+
+constexpr LPCWSTR kTunnelType = L"AppiumTunTap";
+constexpr DWORD kSessionCapacity = 0x400000; // 4 MiB; must be power of two.
+
+// WinTun adapter names are limited to MAX_ADAPTER_NAME-1 wide chars (~127).
+// We stay well under that.
+std::wstring BuildDefaultAdapterName() {
+  std::wostringstream oss;
+  oss << L"appium-tun" << ::GetCurrentProcessId() << L"-" << ::GetTickCount();
+  return oss.str();
+}
+
+class WindowsTunBackend : public TunPlatformBackend {
+public:
+  WindowsTunBackend() = default;
+  ~WindowsTunBackend() override {
+    StopReceiveLoop();
+    EndSessionInternal();
+    CloseAdapterInternal();
+  }
+
+  WindowsTunBackend(const WindowsTunBackend&) = delete;
+  WindowsTunBackend& operator=(const WindowsTunBackend&) = delete;
+  WindowsTunBackend(WindowsTunBackend&&) = delete;
+  WindowsTunBackend& operator=(WindowsTunBackend&&) = delete;
+
+  bool OpenDevice(const std::string& requested_name,
+                  std::string& out_interface_name,
+                  std::string& error) override {
+    auto& api = WintunApi::Instance();
+    if (!api.Load(error)) {
+      return false;
+    }
+
+    std::wstring adapter_name =
+        requested_name.empty() ? BuildDefaultAdapterName() : Utf8ToUtf16(requested_name);
+    if (adapter_name.empty()) {
+      error = "Failed to encode adapter name as UTF-16";
+      return false;
+    }
+
+    // Creating or opening a WinTun adapter requires the process to run with
+    // administrator privileges (elevated). Without elevation `CreateAdapter`
+    // fails with ERROR_ACCESS_DENIED, which `FormatLastError` surfaces in the
+    // error string below. This mirrors the root (EUID 0) requirement of the
+    // POSIX backends.
+    //
+    // Prefer creating a fresh adapter so `WintunCloseAdapter` on shutdown
+    // also tears down the kernel object. Falling back to `OpenAdapter`
+    // handles the "leftover from a crashed process" case where the adapter
+    // already exists; that adapter will likewise be removed on close, which
+    // is the desired behavior — we do not want stale adapters to accumulate.
+    adapter_ = api.CreateAdapter(adapter_name.c_str(), kTunnelType, nullptr);
+    if (!adapter_) {
+      DWORD created_err = ::GetLastError();
+      adapter_ = api.OpenAdapter(adapter_name.c_str());
+      if (!adapter_) {
+        DWORD opened_err = ::GetLastError();
+        error = "Failed to create or open WinTun adapter: create failed with " +
+                FormatLastError(created_err) + "; open failed with " +
+                FormatLastError(opened_err);
+        return false;
+      }
+    }
+
+    session_ = api.StartSession(adapter_, kSessionCapacity);
+    if (!session_) {
+      error = "Failed to start WinTun session: " + FormatLastError(::GetLastError());
+      CloseAdapterInternal();
+      return false;
+    }
+
+    read_event_ = api.GetReadWaitEvent(session_);
+    if (!read_event_) {
+      error = "Failed to acquire WinTun read-wait event: " + FormatLastError(::GetLastError());
+      EndSessionInternal();
+      CloseAdapterInternal();
+      return false;
+    }
+
+    interface_name_ = Utf16ToUtf8(adapter_name);
+    if (interface_name_.empty()) {
+      error = "Failed to encode adapter name as UTF-8";
+      EndSessionInternal();
+      CloseAdapterInternal();
+      return false;
+    }
+
+    out_interface_name = interface_name_;
+    return true;
+  }
+
+  void CloseDevice() override {
+    StopReceiveLoop();
+    EndSessionInternal();
+    CloseAdapterInternal();
+    interface_name_.clear();
+  }
+
+  bool IsOpen() const override { return session_ != nullptr; }
+
+  ReadPacketStatus ReadPacket(size_t max_payload_size,
+                              std::vector<uint8_t>& out,
+                              std::string& error) override {
+    if (!session_) {
+      error = "Device not open";
+      return ReadPacketStatus::Error;
+    }
+
+    auto& api = WintunApi::Instance();
+    DWORD packet_size = 0;
+    BYTE* packet = api.ReceivePacket(session_, &packet_size);
+    if (!packet) {
+      DWORD err = ::GetLastError();
+      switch (err) {
+        case ERROR_NO_MORE_ITEMS:
+          out.clear();
+          return ReadPacketStatus::NoData;
+        case ERROR_HANDLE_EOF:
+          out.clear();
+          return ReadPacketStatus::Closed;
+        default:
+          out.clear();
+          error = "WintunReceivePacket failed: " + FormatLastError(err);
+          return ReadPacketStatus::Error;
+      }
+    }
+
+    const size_t copy_len = static_cast<size_t>(packet_size) > max_payload_size
+                                ? max_payload_size
+                                : static_cast<size_t>(packet_size);
+    out.assign(packet, packet + copy_len);
+    api.ReleaseReceivePacket(session_, packet);
+    return ReadPacketStatus::Data;
+  }
+
+  ssize_t WritePacket(const uint8_t* data,
+                      size_t length,
+                      std::string& error) override {
+    if (!session_) {
+      error = "Device not open";
+      return -1;
+    }
+    if (length == 0) {
+      return 0;
+    }
+    if (length > WINTUN_MAX_IP_PACKET_SIZE) {
+      error = "Packet exceeds WINTUN_MAX_IP_PACKET_SIZE";
+      return -1;
+    }
+
+    auto& api = WintunApi::Instance();
+    BYTE* slot = api.AllocateSendPacket(session_, static_cast<DWORD>(length));
+    if (!slot) {
+      DWORD err = ::GetLastError();
+      if (err == ERROR_HANDLE_EOF) {
+        error = "WinTun adapter is terminating";
+      } else if (err == ERROR_BUFFER_OVERFLOW) {
+        error = "WinTun send-ring is full";
+      } else {
+        error = "WintunAllocateSendPacket failed: " + FormatLastError(err);
+      }
+      return -1;
+    }
+
+    std::memcpy(slot, data, length);
+    api.SendPacket(session_, slot);
+    return static_cast<ssize_t>(length);
+  }
+
+  // The worker thread can begin invoking `on_packet`/`on_error` immediately
+  // after this returns; callers must therefore not assume callbacks fire
+  // only after the function returns. In practice the callbacks defined in
+  // `tuntap.cc` either marshal to libuv via TSFN (`on_packet`) or take
+  // `device_mutex_` (`on_error`). Brief contention on `device_mutex_` is
+  // expected and resolves on the order of microseconds because
+  // `std::thread`'s constructor does not block on the worker reaching its
+  // first instruction. There is no deadlock risk because the calling JS
+  // thread releases the lock as soon as `StartPolling` returns.
+  bool StartReceiveLoop(uv_loop_t* /*loop*/,
+                        size_t buffer_size,
+                        PacketCallback on_packet,
+                        ErrorCallback on_error,
+                        std::string& error) override {
+    if (!session_) {
+      error = "Device not open";
+      return false;
+    }
+    if (buffer_size == 0) {
+      error = "Invalid receive-loop parameters";
+      return false;
+    }
+    if (worker_running_.load()) {
+      error = "Receive loop already started";
+      return false;
+    }
+
+    quit_event_.reset(::CreateEventW(nullptr, /*manualReset=*/TRUE,
+                                     /*initialState=*/FALSE, nullptr));
+    if (!quit_event_.is_valid()) {
+      error = "Failed to create quit event: " + FormatLastError(::GetLastError());
+      return false;
+    }
+
+    worker_running_.store(true);
+    try {
+      worker_ = std::thread(&WindowsTunBackend::WorkerMain, this, buffer_size,
+                            std::move(on_packet), std::move(on_error));
+    } catch (const std::system_error& sysErr) {
+      worker_running_.store(false);
+      quit_event_.reset();
+      error = std::string("Failed to spawn receive thread: ") + sysErr.what();
+      return false;
+    }
+    return true;
+  }
+
+  void StopReceiveLoop() override {
+    if (!worker_.joinable()) {
+      // Either never started or already cleaned up. Reset the event in case
+      // it was created without ever spawning a thread.
+      quit_event_.reset();
+      return;
+    }
+    worker_running_.store(false);
+    if (quit_event_.is_valid()) {
+      ::SetEvent(quit_event_.get());
+    }
+    worker_.join();
+    quit_event_.reset();
+  }
+
+  // WinTun exposes no POSIX file descriptor: its readable object is a Win32
+  // event `HANDLE`, not a numeric fd. Always -1 — the N-API layer treats -1
+  // as "no pollable fd" and drives delivery through `StartReceiveLoop`.
+  int GetNativeFd() const override { return -1; }
+
+private:
+  static std::string Utf16ToUtf8(const std::wstring& utf16) {
+    if (utf16.empty()) {
+      return std::string();
+    }
+    int len = ::WideCharToMultiByte(CP_UTF8, 0, utf16.c_str(),
+                                    static_cast<int>(utf16.size()), nullptr, 0,
+                                    nullptr, nullptr);
+    if (len <= 0) {
+      return std::string();
+    }
+    std::string out(static_cast<size_t>(len), '\0');
+    ::WideCharToMultiByte(CP_UTF8, 0, utf16.c_str(),
+                          static_cast<int>(utf16.size()), out.data(), len,
+                          nullptr, nullptr);
+    return out;
+  }
+
+  void EndSessionInternal() {
+    if (session_) {
+      WintunApi::Instance().EndSession(session_);
+      session_ = nullptr;
+    }
+    read_event_ = nullptr;
+  }
+
+  void CloseAdapterInternal() {
+    if (adapter_) {
+      WintunApi::Instance().CloseAdapter(adapter_);
+      adapter_ = nullptr;
+    }
+  }
+
+  void WorkerMain(size_t buffer_size,
+                  PacketCallback on_packet,
+                  ErrorCallback on_error) {
+    auto& api = WintunApi::Instance();
+    HANDLE wait_handles[2] = {read_event_, quit_event_.get()};
+
+    while (worker_running_.load()) {
+      // Drain everything available before going back to wait. WinTun's
+      // read-wait event is auto-reset on signal, so we must consume all
+      // queued packets before re-arming.
+      bool drained = false;
+      while (worker_running_.load()) {
+        DWORD packet_size = 0;
+        BYTE* packet = api.ReceivePacket(session_, &packet_size);
+        if (packet) {
+          const size_t copy_len = static_cast<size_t>(packet_size) > buffer_size
+                                      ? buffer_size
+                                      : static_cast<size_t>(packet_size);
+          std::vector<uint8_t> data(packet, packet + copy_len);
+          api.ReleaseReceivePacket(session_, packet);
+          if (on_packet) {
+            on_packet(std::move(data));
+          }
+          continue;
+        }
+
+        DWORD err = ::GetLastError();
+        if (err == ERROR_NO_MORE_ITEMS) {
+          drained = true;
+          break;
+        }
+        if (err == ERROR_HANDLE_EOF) {
+          if (on_error) {
+            on_error("WinTun adapter terminating");
+          }
+          worker_running_.store(false);
+          return;
+        }
+        if (on_error) {
+          on_error("WintunReceivePacket failed: " + FormatLastError(err));
+        }
+        worker_running_.store(false);
+        return;
+      }
+
+      if (!worker_running_.load()) {
+        return;
+      }
+      if (!drained) {
+        continue;
+      }
+
+      DWORD wait = ::WaitForMultipleObjects(2, wait_handles, FALSE, INFINITE);
+      if (wait == WAIT_OBJECT_0 + 1) {
+        // quit_event signalled.
+        return;
+      }
+      if (wait != WAIT_OBJECT_0) {
+        if (on_error) {
+          on_error("WaitForMultipleObjects failed: " + FormatLastError(::GetLastError()));
+        }
+        return;
+      }
+    }
+  }
+
+  WINTUN_ADAPTER_HANDLE adapter_ = nullptr;
+  WINTUN_SESSION_HANDLE session_ = nullptr;
+  HANDLE read_event_ = nullptr; // Owned by `session_`; do not CloseHandle.
+  Handle quit_event_;
+  std::thread worker_;
+  std::atomic<bool> worker_running_{false};
+  std::string interface_name_;
+};
+
+} // namespace
+
+std::unique_ptr<TunPlatformBackend> CreatePlatformBackend() {
+  return std::make_unique<WindowsTunBackend>();
+}
+
+#endif

package/src/native/wintun_loader.cc

@@ -0,0 +1,192 @@
+#ifdef _WIN32
+
+#include "wintun_loader.h"
+
+#include <vector>
+
+namespace {
+
+constexpr LPCWSTR kWintunDllName = L"wintun.dll";
+
+// Returns the directory that contains the addon module that this code is
+// linked into. Used to locate `wintun.dll` shipped next to `tuntap.node`.
+std::wstring GetAddonDirectory() {
+  HMODULE module = nullptr;
+  // Pass the address of any function in this translation unit so the resolver
+  // returns the addon's own module rather than the host process executable.
+  if (!GetModuleHandleExW(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS |
+                              GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT,
+                          reinterpret_cast<LPCWSTR>(&GetAddonDirectory),
+                          &module)) {
+    return std::wstring();
+  }
+
+  std::vector<wchar_t> buffer(MAX_PATH);
+  for (;;) {
+    DWORD len = GetModuleFileNameW(module, buffer.data(),
+                                   static_cast<DWORD>(buffer.size()));
+    if (len == 0) {
+      return std::wstring();
+    }
+    if (len < buffer.size()) {
+      buffer.resize(len);
+      break;
+    }
+    buffer.resize(buffer.size() * 2);
+  }
+
+  std::wstring path(buffer.begin(), buffer.end());
+  size_t pos = path.find_last_of(L"\\/");
+  if (pos == std::wstring::npos) {
+    return std::wstring();
+  }
+  path.resize(pos);
+  return path;
+}
+
+template <typename T>
+bool Resolve(HMODULE module, const char* name, T& out, std::string& error) {
+  out = reinterpret_cast<T>(::GetProcAddress(module, name));
+  if (!out) {
+    error = std::string("Failed to resolve wintun.dll export: ") + name;
+    return false;
+  }
+  return true;
+}
+
+} // namespace
+
+WintunApi& WintunApi::Instance() {
+  static WintunApi instance;
+  return instance;
+}
+
+bool WintunApi::Load(std::string& error) {
+  std::lock_guard<std::mutex> lock(load_mutex_);
+  if (loaded_) {
+    return true;
+  }
+
+  // Try addon-directory first so `wintun.dll` shipped next to `tuntap.node`
+  // wins over a stale system copy.
+  std::wstring addon_dir = GetAddonDirectory();
+  if (!addon_dir.empty()) {
+    std::wstring local = addon_dir + L"\\" + kWintunDllName;
+    if (TryLoadFrom(local.c_str())) {
+      return ResolveEntryPoints(error);
+    }
+  }
+
+  // Fall back to the OS-default search list (Application dir, System32, …)
+  // by passing only the file name.
+  if (TryLoadFrom(kWintunDllName)) {
+    return ResolveEntryPoints(error);
+  }
+
+  error = std::string("Failed to load wintun.dll: ") + FormatLastError(::GetLastError()) +
+          ". Make sure wintun.dll is shipped next to tuntap.node or installed system-wide.";
+  return false;
+}
+
+bool WintunApi::TryLoadFrom(LPCWSTR path) {
+  // `LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR` lets a DLL loaded from an explicit
+  // path resolve its own dependencies from its own directory. WinTun has
+  // no third-party dependencies today, but this is the documented-safe
+  // flag set for loading by absolute path and is free to include.
+  module_ = ::LoadLibraryExW(path, nullptr,
+                             LOAD_LIBRARY_SEARCH_APPLICATION_DIR |
+                                 LOAD_LIBRARY_SEARCH_SYSTEM32 |
+                                 LOAD_LIBRARY_SEARCH_USER_DIRS |
+                                 LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR);
+  return module_ != nullptr;
+}
+
+bool WintunApi::ResolveEntryPoints(std::string& error) {
+  if (!module_) {
+    error = "wintun.dll module handle is null";
+    return false;
+  }
+
+  if (!Resolve(module_, "WintunCreateAdapter", CreateAdapter, error) ||
+      !Resolve(module_, "WintunOpenAdapter", OpenAdapter, error) ||
+      !Resolve(module_, "WintunCloseAdapter", CloseAdapter, error) ||
+      !Resolve(module_, "WintunGetRunningDriverVersion", GetRunningDriverVersion, error) ||
+      !Resolve(module_, "WintunStartSession", StartSession, error) ||
+      !Resolve(module_, "WintunEndSession", EndSession, error) ||
+      !Resolve(module_, "WintunGetReadWaitEvent", GetReadWaitEvent, error) ||
+      !Resolve(module_, "WintunReceivePacket", ReceivePacket, error) ||
+      !Resolve(module_, "WintunReleaseReceivePacket", ReleaseReceivePacket, error) ||
+      !Resolve(module_, "WintunAllocateSendPacket", AllocateSendPacket, error) ||
+      !Resolve(module_, "WintunSendPacket", SendPacket, error)) {
+    // Some pointers may already have been resolved before the failure.
+    // Null everything so callers cannot read stale addresses into a
+    // module that we are about to FreeLibrary.
+    ClearEntryPoints();
+    ::FreeLibrary(module_);
+    module_ = nullptr;
+    return false;
+  }
+
+  loaded_ = true;
+  return true;
+}
+
+void WintunApi::ClearEntryPoints() {
+  CreateAdapter = nullptr;
+  OpenAdapter = nullptr;
+  CloseAdapter = nullptr;
+  GetRunningDriverVersion = nullptr;
+  StartSession = nullptr;
+  EndSession = nullptr;
+  GetReadWaitEvent = nullptr;
+  ReceivePacket = nullptr;
+  ReleaseReceivePacket = nullptr;
+  AllocateSendPacket = nullptr;
+  SendPacket = nullptr;
+}
+
+std::string FormatLastError(DWORD error_code) {
+  if (error_code == 0) {
+    return "no error";
+  }
+
+  LPSTR buffer = nullptr;
+  DWORD len = ::FormatMessageA(
+      FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM |
+          FORMAT_MESSAGE_IGNORE_INSERTS,
+      nullptr, error_code, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
+      reinterpret_cast<LPSTR>(&buffer), 0, nullptr);
+
+  std::string message;
+  if (len && buffer) {
+    message.assign(buffer, len);
+    ::LocalFree(buffer);
+    while (!message.empty() && (message.back() == '\n' || message.back() == '\r')) {
+      message.pop_back();
+    }
+  }
+
+  if (message.empty()) {
+    message = "Unknown error";
+  }
+  return message + " (code=" + std::to_string(error_code) + ")";
+}
+
+std::wstring Utf8ToUtf16(const std::string& utf8) {
+  if (utf8.empty()) {
+    return std::wstring();
+  }
+
+  int len = ::MultiByteToWideChar(CP_UTF8, 0, utf8.c_str(),
+                                  static_cast<int>(utf8.size()), nullptr, 0);
+  if (len <= 0) {
+    return std::wstring();
+  }
+
+  std::wstring result(static_cast<size_t>(len), L'\0');
+  ::MultiByteToWideChar(CP_UTF8, 0, utf8.c_str(),
+                        static_cast<int>(utf8.size()), result.data(), len);
+  return result;
+}
+
+#endif

package/src/native/wintun_loader.h

@@ -0,0 +1,93 @@
+#pragma once
+
+#ifdef _WIN32
+
+#include <windows.h>
+#include <ifdef.h>
+
+#include <mutex>
+#include <string>
+
+// Function-pointer typedefs reproduced from the WireGuard-supplied wintun.h
+// (https://git.zx2c4.com/wintun/plain/api/wintun.h, GPL-2.0 OR MIT). Only the
+// pieces we use are declared here so we do not have to vendor the full
+// upstream header.
+
+typedef struct _WINTUN_ADAPTER* WINTUN_ADAPTER_HANDLE;
+typedef struct _TUN_SESSION* WINTUN_SESSION_HANDLE;
+
+#ifndef WINTUN_MIN_RING_CAPACITY
+#define WINTUN_MIN_RING_CAPACITY 0x20000
+#endif
+#ifndef WINTUN_MAX_RING_CAPACITY
+#define WINTUN_MAX_RING_CAPACITY 0x4000000
+#endif
+#ifndef WINTUN_MAX_IP_PACKET_SIZE
+#define WINTUN_MAX_IP_PACKET_SIZE 0xFFFF
+#endif
+
+typedef WINTUN_ADAPTER_HANDLE(WINAPI* WINTUN_CREATE_ADAPTER_FUNC)(LPCWSTR Name,
+                                                                 LPCWSTR TunnelType,
+                                                                 const GUID* RequestedGUID);
+typedef WINTUN_ADAPTER_HANDLE(WINAPI* WINTUN_OPEN_ADAPTER_FUNC)(LPCWSTR Name);
+typedef VOID(WINAPI* WINTUN_CLOSE_ADAPTER_FUNC)(WINTUN_ADAPTER_HANDLE Adapter);
+typedef BOOL(WINAPI* WINTUN_DELETE_DRIVER_FUNC)(VOID);
+typedef VOID(WINAPI* WINTUN_GET_ADAPTER_LUID_FUNC)(WINTUN_ADAPTER_HANDLE Adapter, NET_LUID* Luid);
+typedef DWORD(WINAPI* WINTUN_GET_RUNNING_DRIVER_VERSION_FUNC)(VOID);
+
+typedef WINTUN_SESSION_HANDLE(WINAPI* WINTUN_START_SESSION_FUNC)(WINTUN_ADAPTER_HANDLE Adapter,
+                                                                DWORD Capacity);
+typedef VOID(WINAPI* WINTUN_END_SESSION_FUNC)(WINTUN_SESSION_HANDLE Session);
+typedef HANDLE(WINAPI* WINTUN_GET_READ_WAIT_EVENT_FUNC)(WINTUN_SESSION_HANDLE Session);
+typedef BYTE*(WINAPI* WINTUN_RECEIVE_PACKET_FUNC)(WINTUN_SESSION_HANDLE Session, DWORD* PacketSize);
+typedef VOID(WINAPI* WINTUN_RELEASE_RECEIVE_PACKET_FUNC)(WINTUN_SESSION_HANDLE Session,
+                                                        const BYTE* Packet);
+typedef BYTE*(WINAPI* WINTUN_ALLOCATE_SEND_PACKET_FUNC)(WINTUN_SESSION_HANDLE Session,
+                                                       DWORD PacketSize);
+typedef VOID(WINAPI* WINTUN_SEND_PACKET_FUNC)(WINTUN_SESSION_HANDLE Session, const BYTE* Packet);
+
+// Singleton container for the resolved entry points. Callers must invoke
+// `Load` (returning false on failure) before reading any function pointer.
+class WintunApi {
+public:
+  static WintunApi& Instance();
+
+  // Loads `wintun.dll` and resolves all required entry points. On the first
+  // failure `error` describes which step went wrong; subsequent calls succeed
+  // immediately as long as a previous call already loaded the library.
+  bool Load(std::string& error);
+
+  WINTUN_CREATE_ADAPTER_FUNC CreateAdapter = nullptr;
+  WINTUN_OPEN_ADAPTER_FUNC OpenAdapter = nullptr;
+  WINTUN_CLOSE_ADAPTER_FUNC CloseAdapter = nullptr;
+  WINTUN_GET_RUNNING_DRIVER_VERSION_FUNC GetRunningDriverVersion = nullptr;
+  WINTUN_START_SESSION_FUNC StartSession = nullptr;
+  WINTUN_END_SESSION_FUNC EndSession = nullptr;
+  WINTUN_GET_READ_WAIT_EVENT_FUNC GetReadWaitEvent = nullptr;
+  WINTUN_RECEIVE_PACKET_FUNC ReceivePacket = nullptr;
+  WINTUN_RELEASE_RECEIVE_PACKET_FUNC ReleaseReceivePacket = nullptr;
+  WINTUN_ALLOCATE_SEND_PACKET_FUNC AllocateSendPacket = nullptr;
+  WINTUN_SEND_PACKET_FUNC SendPacket = nullptr;
+
+private:
+  WintunApi() = default;
+  WintunApi(const WintunApi&) = delete;
+  WintunApi& operator=(const WintunApi&) = delete;
+
+  bool TryLoadFrom(LPCWSTR path);
+  bool ResolveEntryPoints(std::string& error);
+  void ClearEntryPoints();
+
+  std::mutex load_mutex_;
+  HMODULE module_ = nullptr;
+  bool loaded_ = false;
+};
+
+// Builds a UTF-8 description of the latest Win32 error suitable for embedding
+// in `std::string` error messages.
+std::string FormatLastError(DWORD error_code);
+
+// Converts a UTF-8 string to UTF-16 for Win32 wide-char APIs.
+std::wstring Utf8ToUtf16(const std::string& utf8);
+
+#endif