@decentnetwork/lan 0.1.197 → 0.1.199

package/dist/proxy/hls-prefetch.js

@@ -179,6 +179,8 @@ export class HlsPrefetcher {
     #cache = new Map(); // Map preserves insertion order → LRU-ish
     #cacheBytes = 0;
     #inflight = new Map();
+    #background = new Map();
+    #playlistGeneration = 0;
     #liveBufferPrimed = false;
     #fetcher;
     #maxBytes;
@@ -266,7 +268,7 @@ export class HlsPrefetcher {
      *  losing request is aborted immediately so the rescue does not keep splitting
      *  bandwidth after a winner is available. Redemption probes are separate,
      *  forced-exit requests and are never aborted by this path. */
-    #whole(u, extra) {
+    #whole(u, extra, outerSignal) {
         const one = (signal, label) => this.#fetcher(u, { ...extra, host: u.host }, label, signal);
         return new Promise((resolve, reject) => {
             let settled = false;
@@ -275,12 +277,25 @@ export class HlsPrefetcher {
             let timer = null;
             const first = new AbortController();
             let hedge = null;
+            const cleanup = () => outerSignal?.removeEventListener("abort", onOuterAbort);
+            const onOuterAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                first.abort();
+                hedge?.abort();
+                cleanup();
+                reject(new Error("aborted"));
+            };
             const win = (winner) => (r) => {
                 if (settled)
                     return;
                 settled = true;
                 if (timer)
                     clearTimeout(timer);
+                cleanup();
                 (winner === first ? hedge : first)?.abort();
                 // Keep the winner alive through resolution; aborting a fully consumed
                 // response would only discard its reusable keep-alive socket.
@@ -298,6 +313,7 @@ export class HlsPrefetcher {
                 }
                 else if (pending === 0) {
                     settled = true;
+                    cleanup();
                     reject(e);
                 }
             };
@@ -309,6 +325,11 @@ export class HlsPrefetcher {
                 pending++;
                 one(hedge.signal, "prefetch-hedge").then(win(hedge), lose);
             };
+            if (outerSignal?.aborted) {
+                onOuterAbort();
+                return;
+            }
+            outerSignal?.addEventListener("abort", onOuterAbort, { once: true });
             one(first.signal, "prefetch").then(win(first), lose);
             timer = setTimeout(() => {
                 timer = null;
@@ -322,7 +343,7 @@ export class HlsPrefetcher {
      *  STRIPE_TRIES exits. Returns null only if every try failed. `exactLen`, when
      *  given, rejects a 206 whose body isn't exactly that long (so assembly is
      *  byte-correct); the probe passes it undefined to accept whatever 206 arrives. */
-    #fetchRange(u, start, end, extra, exactLen, exitHint) {
+    #fetchRange(u, start, end, extra, exactLen, exitHint, outerSignal) {
         return new Promise((resolve) => {
             let settled = false;
             let launched = 0;
@@ -338,11 +359,13 @@ export class HlsPrefetcher {
                     return;
                 settled = true;
                 clearHedge();
+                outerSignal?.removeEventListener("abort", onOuterAbort);
                 for (const ac of controllers)
                     if (ac !== winner)
                         ac.abort();
                 resolve(r);
             };
+            const onOuterAbort = () => finish(null);
             const scheduleHedge = () => {
                 if (settled || launched >= STRIPE_TRIES || hedgeTimer)
                     return;
@@ -387,6 +410,11 @@ export class HlsPrefetcher {
                 if (finished >= launched)
                     finish(null);
             };
+            if (outerSignal?.aborted) {
+                finish(null);
+                return;
+            }
+            outerSignal?.addEventListener("abort", onOuterAbort, { once: true });
             launch();
         });
     }
@@ -394,25 +422,29 @@ export class HlsPrefetcher {
      *  each hedged. Assembles them into the full body with a corrected
      *  content-length. Falls back to one whole fetch if the origin ignores Range or
      *  any stripe truly can't be fetched (correctness over speed). */
-    async #stripeFetch(u, extra) {
+    async #stripeFetch(u, extra, signal) {
+        if (signal?.aborted)
+            throw new Error("aborted");
         const stripeCount = this.#stripeCount();
         // A count of one explicitly disables striping (emergency rollback or an
         // origin/path known not to benefit from parallel range connections).
         if (stripeCount <= 1)
-            return this.#whole(u, extra);
+            return this.#whole(u, extra, signal);
         // Tiny probe (2 bytes): learn the total size + confirm the origin honors
         // Range, cheaply — a big sequential probe would add a whole round-trip of
         // latency before any stripe starts and starve the live buffer.
-        const probe = await this.#fetchRange(u, 0, 1, extra);
+        const probe = await this.#fetchRange(u, 0, 1, extra, undefined, undefined, signal);
+        if (signal?.aborted)
+            throw new Error("aborted");
         if (!probe)
-            return this.#whole(u, extra);
+            return this.#whole(u, extra, signal);
         if (probe.status === 200)
             return probe; // range ignored → whole body already here
         if (probe.status !== 206)
-            return this.#whole(u, extra);
+            return this.#whole(u, extra, signal);
         const total = contentRangeTotal(probe.headers["content-range"]);
         if (!total || total <= 0)
-            return this.#whole(u, extra);
+            return this.#whole(u, extra, signal);
         const headers = { ...probe.headers };
         delete headers["content-range"];
         // Split the WHOLE body into N equal stripes, fetched IN PARALLEL across the
@@ -427,13 +459,15 @@ export class HlsPrefetcher {
             if (start > end)
                 return Promise.resolve(Buffer.alloc(0));
             const want = end - start + 1;
-            return this.#fetchRange(u, start, end, extra, want, i).then((r) => (r && r.body.length === want ? r.body : null));
+            return this.#fetchRange(u, start, end, extra, want, i, signal).then((r) => (r && r.body.length === want ? r.body : null));
         }));
+        if (signal?.aborted)
+            throw new Error("aborted");
         if (parts.some((p) => p === null))
-            return this.#whole(u, extra); // a stripe couldn't be fetched → whole for integrity
+            return this.#whole(u, extra, signal); // a stripe couldn't be fetched → whole for integrity
         const body = Buffer.concat(parts);
         if (body.length !== total)
-            return this.#whole(u, extra);
+            return this.#whole(u, extra, signal);
         headers["content-length"] = String(body.length);
         return { status: 200, headers, body };
     }
@@ -523,12 +557,35 @@ export class HlsPrefetcher {
         const segs = parseM3u8Segments(body, playlistUrl);
         if (segs.length === 0)
             return;
+        const generation = ++this.#playlistGeneration;
         // For a live playlist the tail is "upcoming"; for VOD the player walks the
         // list from wherever it is, and refetches of the playlist don't happen —
         // prefetching the head of the list still fills the startup buffer. Either
         // way: take the last `ahead` entries we don't already hold.
+        const tail = segs.slice(-this.#ahead);
+        const wanted = new Set(tail);
+        const cancelled = [];
+        for (const [url, controller] of this.#background) {
+            if (wanted.has(url))
+                continue;
+            controller.abort();
+            this.#background.delete(url);
+            const p = this.#inflight.get(url);
+            if (p)
+                cancelled.push(p);
+        }
+        if (cancelled.length > 0) {
+            void Promise.allSettled(cancelled).then(() => {
+                if (this.#playlistGeneration === generation)
+                    this.#schedulePrefetch(tail);
+            });
+            return;
+        }
+        this.#schedulePrefetch(tail);
+    }
+    #schedulePrefetch(segs) {
         const conc = Math.max(1, Math.floor(this.#concurrencyFn ? this.#concurrencyFn() : this.#concurrency));
-        const want = segs.slice(-this.#ahead).filter((u) => !this.#peek(u) && !this.#inflight.has(u));
+        const want = segs.filter((u) => !this.#peek(u) && !this.#inflight.has(u));
         for (const u of want) {
             if (this.#inflight.size >= conc)
                 break;
@@ -536,10 +593,13 @@ export class HlsPrefetcher {
         }
     }
     #prefetch(url) {
-        const p = (async () => {
+        const controller = new AbortController();
+        this.#background.set(url, controller);
+        let p;
+        p = (async () => {
             try {
                 const u = new URL(url);
-                const res = await this.#stripeFetch(u, {});
+                const res = await this.#stripeFetch(u, {}, controller.signal);
                 if (res.status !== 200 || res.body.length === 0 || res.body.length > this.#maxEntryBytes)
                     return null;
                 const ct = res.headers["content-type"];
@@ -555,7 +615,10 @@ export class HlsPrefetcher {
                 return null;
             }
             finally {
-                this.#inflight.delete(url);
+                if (this.#inflight.get(url) === p)
+                    this.#inflight.delete(url);
+                if (this.#background.get(url) === controller)
+                    this.#background.delete(url);
             }
         })();
         this.#inflight.set(url, p);

package/dist/proxy/multi-exit-router.d.ts

@@ -50,6 +50,7 @@ export interface MultiExitRouterOptions {
 }
 export declare const BUILTIN_REGION_DOMAINS: Record<string, string[]>;
 export declare function isUsefulRecoverySample(peakBps: number, averageBps: number, minBps?: number): boolean;
+export declare function redemptionProbeQuietDelay(lastForegroundMs: number, nowMs?: number, quietMs?: number): number;
 interface HlsExitScore {
     speedEwma: number | null;
     flooredAtMs: number | null;

package/dist/proxy/multi-exit-router.js

@@ -239,6 +239,14 @@ const REDEMPTION_MS = 90_000;
 // exit is tested with a duplicate background segment while the player's normal
 // fetch remains on proven exits, so recovery discovery cannot stall playback.
 const REDEMPTION_PROBE_GAP_MS = 15_000;
+// A recovery test is deliberately background work: never let it overlap an
+// active live stream.  Each foreground segment pushes the timer back; once the
+// player has been quiet for this long, the most recent segment is safe to reuse
+// as a realistic recovery sample.
+const REDEMPTION_PROBE_QUIET_MS = 10_000;
+export function redemptionProbeQuietDelay(lastForegroundMs, nowMs = Date.now(), quietMs = REDEMPTION_PROBE_QUIET_MS) {
+    return Math.max(0, quietMs - Math.max(0, nowMs - lastForegroundMs));
+}
 function floorExit(exit) {
     exit.speedEwma = exit.speedEwma === null ? FLOOR_BPS : Math.min(exit.speedEwma, FLOOR_BPS);
     exit.flooredAtMs = Date.now();
@@ -1137,6 +1145,38 @@ export function startMultiExitRouter(opts) {
     // Fetch one URL through the region's exit pool, buffered, with failover.
     let redemptionProbeInFlight = false;
     let lastRedemptionProbeMs = 0;
+    let lastForegroundHlsMs = 0;
+    let redemptionProbeTimer = null;
+    let pendingRedemptionProbe = null;
+    function armRedemptionProbe(delayMs) {
+        if (redemptionProbeTimer)
+            clearTimeout(redemptionProbeTimer);
+        redemptionProbeTimer = setTimeout(() => {
+            redemptionProbeTimer = null;
+            const quietDelay = redemptionProbeQuietDelay(lastForegroundHlsMs);
+            if (quietDelay > 0) {
+                armRedemptionProbe(quietDelay);
+                return;
+            }
+            const pending = pendingRedemptionProbe;
+            if (!pending)
+                return;
+            if (redemptionProbeInFlight || Date.now() - lastRedemptionProbeMs < REDEMPTION_PROBE_GAP_MS) {
+                armRedemptionProbe(REDEMPTION_PROBE_GAP_MS);
+                return;
+            }
+            maybeStartRedemptionProbe(pending.u, pending.extraHeaders, pending.region);
+            // Keep checking while the player remains idle: an exit may not become
+            // redemption-eligible until its 90-second floor expires.
+            armRedemptionProbe(REDEMPTION_PROBE_GAP_MS);
+        }, Math.max(1, delayMs));
+        redemptionProbeTimer.unref?.();
+    }
+    function deferRedemptionProbeUntilIdle(u, extraHeaders, region) {
+        lastForegroundHlsMs = Date.now();
+        pendingRedemptionProbe = { u: new URL(u.toString()), extraHeaders: { ...extraHeaders }, region };
+        armRedemptionProbe(REDEMPTION_PROBE_QUIET_MS);
+    }
     function maybeStartRedemptionProbe(u, extraHeaders, region) {
         const now = Date.now();
         if (redemptionProbeInFlight || now - lastRedemptionProbeMs < REDEMPTION_PROBE_GAP_MS)
@@ -1205,7 +1245,7 @@ export function startMultiExitRouter(opts) {
                 return;
             }
             if (!forcedExit && label === "prefetch")
-                maybeStartRedemptionProbe(u, extraHeaders, region);
+                deferRedemptionProbeUntilIdle(u, extraHeaders, region);
             const base0 = forcedExit ? [forcedExit] : pickOrder(region);
             if (base0.length === 0) {
                 reject(new Error("no healthy exit"));
@@ -1774,6 +1814,13 @@ export function startMultiExitRouter(opts) {
         server.on("close", () => clearInterval(reporter));
     }
     return {
-        stop: () => { stopped = true; server.close(); },
+        stop: () => {
+            stopped = true;
+            if (redemptionProbeTimer)
+                clearTimeout(redemptionProbeTimer);
+            redemptionProbeTimer = null;
+            pendingRedemptionProbe = null;
+            server.close();
+        },
     };
 }

package/dist/tun/route-manager.d.ts

@@ -1,13 +1,20 @@
 /**
  * TUN device + route management.
- * Linux uses `ip` (iproute2). macOS uses `ifconfig` + `route`.
+ * Linux uses `ip` (iproute2), macOS uses `ifconfig` + `route`, and
+ * Windows uses the built-in NetTCPIP PowerShell cmdlets.
  */
 import type { TunDeviceConfig } from "./types.js";
+export type RoutePlatform = "linux" | "darwin" | "win32";
+export interface RouteManagerOptions {
+    platform?: RoutePlatform;
+    commandRunner?: (command: string) => string;
+}
 export declare class RouteManager {
     private logger;
     private createdInterface;
     private platform;
-    constructor();
+    private commandRunner;
+    constructor(opts?: RouteManagerOptions);
     /**
      * Create and configure TUN interface (Linux only — on macOS the helper
      * binary creates the utun device implicitly).
@@ -18,6 +25,7 @@ export declare class RouteManager {
      * `name` here should be the ACTUAL device name (e.g. utun12 on macOS).
      */
     configureTun(config: TunDeviceConfig): Promise<void>;
+    private configureTunWindows;
     private configureTunLinux;
     private configureTunDarwin;
     /**
@@ -43,6 +51,8 @@ export declare class RouteManager {
     setupMasquerade(subnet: string, outInterface: string, tunInterface: string): Promise<void>;
     cleanupMasquerade(subnet: string, outInterface: string, tunInterface: string): Promise<void>;
     private exec;
+    private powerShell;
+    private powerShellQuote;
     /**
      * Convert "10.86.0.0/16" -> 16
      */

package/dist/tun/route-manager.js

@@ -1,6 +1,7 @@
 /**
  * TUN device + route management.
- * Linux uses `ip` (iproute2). macOS uses `ifconfig` + `route`.
+ * Linux uses `ip` (iproute2), macOS uses `ifconfig` + `route`, and
+ * Windows uses the built-in NetTCPIP PowerShell cmdlets.
  */
 import { execSync } from "child_process";
 import { Logger } from "../utils/logger.js";
@@ -8,22 +9,23 @@ export class RouteManager {
     logger;
     createdInterface = null;
     platform;
-    constructor() {
+    commandRunner;
+    constructor(opts = {}) {
         this.logger = new Logger({ prefix: "RouteManager" });
-        if (process.platform === "darwin") {
-            this.platform = "darwin";
-        }
-        else {
-            this.platform = "linux";
+        const detected = opts.platform ?? process.platform;
+        if (detected !== "linux" && detected !== "darwin" && detected !== "win32") {
+            throw new Error(`Unsupported route platform: ${detected}`);
         }
+        this.platform = detected;
+        this.commandRunner = opts.commandRunner ?? ((command) => execSync(command, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }));
     }
     /**
      * Create and configure TUN interface (Linux only — on macOS the helper
      * binary creates the utun device implicitly).
      */
     async createTun(config) {
-        if (this.platform === "darwin") {
-            // utun is auto-created by the helper; just configure
+        if (this.platform === "darwin" || this.platform === "win32") {
+            // utun/Wintun is auto-created by the helper; just configure.
             await this.configureTun(config);
             return;
         }
@@ -48,8 +50,34 @@ export class RouteManager {
         if (this.platform === "darwin") {
             return this.configureTunDarwin(config);
         }
+        if (this.platform === "win32") {
+            return this.configureTunWindows(config);
+        }
         return this.configureTunLinux(config);
     }
+    async configureTunWindows(config) {
+        const { name, ip, subnet } = config;
+        const mtu = config.mtu ?? 900;
+        const alias = this.powerShellQuote(name);
+        const address = this.powerShellQuote(ip);
+        const destination = this.powerShellQuote(subnet);
+        // Use a /32 local address and add the AgentNet /16 explicitly. This mirrors
+        // the macOS point-to-point setup and avoids Windows creating a competing
+        // connected /16 route with an arbitrary metric.
+        this.powerShell([
+            "$ErrorActionPreference='Stop'",
+            `Enable-NetAdapter -Name ${alias} -Confirm:$false -ErrorAction SilentlyContinue`,
+            `Get-NetIPAddress -InterfaceAlias ${alias} -AddressFamily IPv4 -ErrorAction SilentlyContinue | Where-Object { $_.IPAddress -like '10.86.*' } | Remove-NetIPAddress -Confirm:$false -ErrorAction SilentlyContinue`,
+            `Get-NetRoute -InterfaceAlias ${alias} -DestinationPrefix ${destination} -ErrorAction SilentlyContinue | Remove-NetRoute -Confirm:$false -ErrorAction SilentlyContinue`,
+            `New-NetIPAddress -InterfaceAlias ${alias} -IPAddress ${address} -PrefixLength 32 -AddressFamily IPv4 -PolicyStore ActiveStore | Out-Null`,
+            `Set-NetIPInterface -InterfaceAlias ${alias} -AddressFamily IPv4 -NlMtuBytes ${mtu}`,
+            `New-NetRoute -DestinationPrefix ${destination} -InterfaceAlias ${alias} -NextHop 0.0.0.0 -RouteMetric 1 -PolicyStore ActiveStore | Out-Null`,
+            `Get-NetFirewallRule -Name 'DecentAgentNet-Inbound' -ErrorAction SilentlyContinue | Remove-NetFirewallRule -ErrorAction SilentlyContinue`,
+            `New-NetFirewallRule -Name 'DecentAgentNet-Inbound' -DisplayName 'Decent AgentNet virtual network' -Direction Inbound -Action Allow -InterfaceAlias ${alias} -Profile Any | Out-Null`,
+        ].join("; "));
+        this.createdInterface = name;
+        this.logger.info(`Assigned ${ip}/32 to ${name}, route ${subnet}, mtu=${mtu} (Windows)`);
+    }
     async configureTunLinux(config) {
         const { name, ip, subnet } = config;
         const mtu = config.mtu ?? 900;
@@ -162,6 +190,13 @@ export class RouteManager {
      * Remove TUN interface (Linux only — on macOS utun goes away when helper exits).
      */
     async removeTun(name) {
+        if (this.platform === "win32") {
+            // Wintun adapters are intentionally persistent and reused by name. The
+            // helper ending its session is enough; cleanup() removes IP/routes.
+            this.logger.debug(`Windows Wintun adapter ${name} retained for reuse`);
+            this.createdInterface = null;
+            return;
+        }
         if (this.platform === "darwin") {
             // utun is auto-destroyed when the helper subprocess exits
             this.logger.debug(`macOS utun ${name} cleaned up by helper exit`);
@@ -221,6 +256,21 @@ export class RouteManager {
                 // utun device cleanup is handled when helper exits
                 return;
             }
+            if (this.platform === "win32") {
+                const alias = this.powerShellQuote(name);
+                const destination = this.powerShellQuote(subnet);
+                const removeIp = ip
+                    ? `Get-NetIPAddress -InterfaceAlias ${alias} -IPAddress ${this.powerShellQuote(ip)} -AddressFamily IPv4 -ErrorAction SilentlyContinue | Remove-NetIPAddress -Confirm:$false -ErrorAction SilentlyContinue`
+                    : `Get-NetIPAddress -InterfaceAlias ${alias} -AddressFamily IPv4 -ErrorAction SilentlyContinue | Where-Object { $_.IPAddress -like '10.86.*' } | Remove-NetIPAddress -Confirm:$false -ErrorAction SilentlyContinue`;
+                this.powerShell([
+                    "$ErrorActionPreference='SilentlyContinue'",
+                    `Get-NetRoute -InterfaceAlias ${alias} -DestinationPrefix ${destination} -ErrorAction SilentlyContinue | Remove-NetRoute -Confirm:$false -ErrorAction SilentlyContinue`,
+                    removeIp,
+                    `Get-NetFirewallRule -Name 'DecentAgentNet-Inbound' -ErrorAction SilentlyContinue | Remove-NetFirewallRule -ErrorAction SilentlyContinue`,
+                ].join("; "));
+                this.createdInterface = null;
+                return;
+            }
             try {
                 this.exec(`ip route del ${subnet} dev ${name}`);
             }
@@ -242,6 +292,10 @@ export class RouteManager {
      * Enable IP forwarding (Linux only)
      */
     async enableIpForwarding() {
+        if (this.platform === "win32") {
+            this.logger.warn("Kernel IP forwarding/NAT is not enabled on Windows; the AgentNet CONNECT exit proxy does not require it");
+            return;
+        }
         if (this.platform === "darwin") {
             try {
                 this.exec("sysctl -w net.inet.ip.forwarding=1");
@@ -264,7 +318,10 @@ export class RouteManager {
     }
     async disableIpForwarding() {
         try {
-            if (this.platform === "darwin") {
+            if (this.platform === "win32") {
+                return;
+            }
+            else if (this.platform === "darwin") {
                 this.exec("sysctl -w net.inet.ip.forwarding=0");
             }
             else {
@@ -281,8 +338,8 @@ export class RouteManager {
      * Not implemented on macOS in MVP.
      */
     async setupMasquerade(subnet, outInterface, tunInterface) {
-        if (this.platform === "darwin") {
-            this.logger.warn("Masquerade not implemented on macOS in MVP");
+        if (this.platform === "darwin" || this.platform === "win32") {
+            this.logger.warn(`Masquerade not implemented on ${this.platform} in MVP`);
             return;
         }
         this.exec(`iptables -t nat -A POSTROUTING -o ${outInterface} -j MASQUERADE`);
@@ -291,7 +348,7 @@ export class RouteManager {
         this.logger.info(`Masquerade setup for ${subnet} (${tunInterface} -> ${outInterface})`);
     }
     async cleanupMasquerade(subnet, outInterface, tunInterface) {
-        if (this.platform === "darwin")
+        if (this.platform === "darwin" || this.platform === "win32")
             return;
         for (const cmd of [
             `iptables -t nat -D POSTROUTING -o ${outInterface} -j MASQUERADE`,
@@ -310,13 +367,22 @@ export class RouteManager {
     exec(command) {
         this.logger.debug(`Executing: ${command}`);
         try {
-            return execSync(command, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+            return this.commandRunner(command);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             throw new Error(`Command failed: ${command}\n${message}`);
         }
     }
+    powerShell(script) {
+        // -EncodedCommand is UTF-16LE and avoids cmd.exe quoting/injection hazards
+        // from interface aliases or Windows paths.
+        const encoded = Buffer.from(script, "utf16le").toString("base64");
+        return this.exec(`powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encoded}`);
+    }
+    powerShellQuote(value) {
+        return `'${value.replace(/'/g, "''")}'`;
+    }
     /**
      * Convert "10.86.0.0/16" -> 16
      */

package/dist/tun/tun-device.d.ts

@@ -14,6 +14,10 @@ export interface TunDeviceOptions {
     mockMode?: boolean;
     helperPath?: string;
 }
+/** Relative helper path inside the package's bin/ directory. Windows keeps
+ * each architecture in its own directory because the matching driver DLL must
+ * be named exactly `wintun.dll` beside the executable. */
+export declare function helperBinaryRelativePath(platform: NodeJS.Platform, arch: string): string | null;
 export declare class TunDevice extends EventEmitter {
     private config;
     private logger;

package/dist/tun/tun-device.js

@@ -13,6 +13,24 @@ import { resolve, dirname } from "path";
 import { existsSync } from "fs";
 import { fileURLToPath } from "url";
 import { Logger } from "../utils/logger.js";
+/** Relative helper path inside the package's bin/ directory. Windows keeps
+ * each architecture in its own directory because the matching driver DLL must
+ * be named exactly `wintun.dll` beside the executable. */
+export function helperBinaryRelativePath(platform, arch) {
+    if (platform === "linux" && arch === "x64")
+        return "tun-helper-linux-amd64";
+    if (platform === "linux" && arch === "arm64")
+        return "tun-helper-linux-arm64";
+    if (platform === "darwin" && arch === "x64")
+        return "tun-helper-darwin-amd64";
+    if (platform === "darwin" && arch === "arm64")
+        return "tun-helper-darwin-arm64";
+    if (platform === "win32" && arch === "x64")
+        return "windows-amd64/tun-helper-windows-amd64.exe";
+    if (platform === "win32" && arch === "arm64")
+        return "windows-arm64/tun-helper-windows-arm64.exe";
+    return null;
+}
 export class TunDevice extends EventEmitter {
     config;
     logger;
@@ -81,7 +99,19 @@ export class TunDevice extends EventEmitter {
                     clearTimeout(timer);
                     res();
                 });
-                helper.kill("SIGTERM");
+                // Closing stdin is the helper's cross-platform graceful-shutdown
+                // signal. In particular, Node maps kill("SIGTERM") to an immediate
+                // TerminateProcess on Windows, which can interrupt Wintun inside a DLL
+                // call (0xc0000005) and leave an orphaned adapter. EOF lets main.go
+                // return normally and run its deferred session/adapter Close(). Keep
+                // SIGTERM/SIGKILL only as a fallback for a wedged helper.
+                if (helper.stdin && !helper.stdin.destroyed)
+                    helper.stdin.end();
+                setTimeout(() => {
+                    if (helper.exitCode === null && helper.signalCode === null) {
+                        helper.kill("SIGTERM");
+                    }
+                }, 1000).unref?.();
             });
         }
         this.emit("closed");
@@ -178,8 +208,9 @@ export class TunDevice extends EventEmitter {
     async openReal() {
         const helperPath = this.helperPath || this.findHelperBinary();
         if (!helperPath || !existsSync(helperPath)) {
+            const expected = helperBinaryRelativePath(process.platform, process.arch);
             throw new Error(`TUN helper binary not found: ${helperPath || "(none)"}\n` +
-                `Build it with: cd helper/tun-helper && go build -o bin/tun-helper-linux-amd64 .`);
+                `Expected package helper: ${expected || `${process.platform}/${process.arch} (unsupported)`}`);
         }
         // On Linux the helper creates a FIXED-name interface (agentnet0). If a
         // prior helper died uncleanly — e.g. "read tun: file descriptor in bad
@@ -301,27 +332,13 @@ export class TunDevice extends EventEmitter {
             resolve(moduleDir, "../../../bin"),
             resolve(process.cwd(), "bin"),
         ];
-        const platform = process.platform;
-        const arch = process.arch;
-        let suffix;
-        if (platform === "linux" && arch === "x64") {
-            suffix = "linux-amd64";
-        }
-        else if (platform === "darwin" && arch === "arm64") {
-            suffix = "darwin-arm64";
-        }
-        else if (platform === "darwin" && arch === "x64") {
-            suffix = "darwin-amd64";
-        }
-        else if (platform === "linux" && arch === "arm64") {
-            suffix = "linux-arm64";
-        }
-        else {
-            this.logger.warn(`Unsupported platform: ${platform}/${arch}`);
+        const relativePath = helperBinaryRelativePath(process.platform, process.arch);
+        if (!relativePath) {
+            this.logger.warn(`Unsupported platform: ${process.platform}/${process.arch}`);
             return null;
         }
         for (const dir of candidates) {
-            const path = resolve(dir, `tun-helper-${suffix}`);
+            const path = resolve(dir, relativePath);
             if (existsSync(path)) {
                 return path;
             }

package/docs/CONFIGURATION.md

@@ -77,8 +77,8 @@ dora:
 
 ### `network`
 
-- **`interface`** — TUN device name on Linux. macOS uses kernel-
-  assigned `utun*` regardless of this field.
+- **`interface`** — TUN device name on Linux and native Windows (Wintun).
+  macOS uses kernel-assigned `utun*` regardless of this field.
 - **`ip`** — fallback IP if dora can't be reached. **When dora is
   enabled and reachable, dora's allocation overrides this.**
 - **`subnet`** — `/16` is the only tested size today. Don't change