@decentnetwork/lan 0.1.197 → 0.1.199

package/docs/INSTALL-WINDOWS.md

@@ -0,0 +1,137 @@
+# Install AgentNet natively on Windows
+
+AgentNet runs directly in 64-bit Windows. WSL is not required. The npm package
+contains a Windows helper and WireGuard's signed `wintun.dll`; AgentNet chooses
+the x64 or ARM64 files automatically.
+
+Supported targets:
+
+- Windows 10 or 11, x64 or ARM64
+- Windows Server 2016 or newer, x64 or ARM64
+- Node.js 20 or newer
+
+The TUN adapter and routes require Administrator rights. Carrier, the AgentNet
+protocol, ACLs, chat, the built-in CONNECT exit proxy, and the local router are
+the same as on Linux and macOS.
+
+## Install
+
+1. Install the current LTS release of [Node.js](https://nodejs.org/).
+2. Open **PowerShell as Administrator**.
+3. Run:
+
+   ```powershell
+   npm install -g @decentnetwork/lan
+   agentnet init --name my-windows-pc
+   agentnet service install
+   ```
+
+`service install` creates the `agentnet0` Wintun adapter, registers the
+`10.86.0.0/16` route, and installs an elevated `Decent AgentNet` startup task.
+The launcher restarts the daemon after a failure and starts it again at boot.
+
+No separate Wintun installer is needed. Do not download a driver DLL from a
+third-party site.
+
+## Verify
+
+In the same Administrator PowerShell:
+
+```powershell
+agentnet service status
+agentnet diag
+Get-NetAdapter -Name agentnet0
+Get-NetRoute -DestinationPrefix 10.86.0.0/16
+ping 10.86.156.164
+```
+
+Replace the final address with a live AgentNet peer. The first dora roster and
+Carrier sessions can take 60–90 seconds after a new installation.
+
+Follow the service log with:
+
+```powershell
+Get-Content -Wait "$env:USERPROFILE\.agentnet\agentnet-service.log"
+```
+
+Useful lifecycle commands:
+
+```powershell
+agentnet service restart
+agentnet service status
+agentnet service install --uninstall
+```
+
+Run these commands from an Administrator PowerShell. `agentnet restart` is a
+different command: it asks an already-running daemon to re-exec over local IPC;
+`agentnet service restart` works even when that daemon is stuck.
+
+## Make the Windows machine an exit node
+
+An exit node does not need WSL, Windows NAT, or the client-side HLS accelerator.
+Enable AgentNet's application-level CONNECT proxy and restart the service:
+
+```powershell
+agentnet proxy enable
+agentnet service restart
+```
+
+The proxy listens on the node's AgentNet virtual IP at port `8888` by default.
+AgentNet friend/ACL policy remains the authorization boundary. On the machine
+watching CCTV, run the multi-exit router with HLS acceleration:
+
+```powershell
+agentnet proxy router --listen 0.0.0.0 --hls-accel
+```
+
+Then point Chrome at `http://127.0.0.1:8889`. `--hls-accel` belongs on the
+watching/client router, not on each exit node.
+
+## Foreground debugging
+
+Stop the startup task first so two daemons do not share one identity:
+
+```powershell
+schtasks.exe /End /TN "Decent AgentNet"
+$env:DECENT_DEBUG = "1"
+$env:DECENT_DEBUG_VERBOSE = "1"
+agentnet up --real-tun
+```
+
+Press `Ctrl+C` when finished, then restore the task with
+`agentnet service restart`.
+
+## Troubleshooting
+
+| symptom | fix |
+|---|---|
+| `Access is denied`, route creation fails, or Wintun cannot create an adapter | Close the terminal and reopen PowerShell with **Run as administrator**. |
+| `Missing TUN helper` or `wintun.dll` is missing | Reinstall the current npm package. Antivirus quarantine is also worth checking. The helper and DLL must remain together in their `bin/windows-*` directory. |
+| Service is installed but `agentnet diag` cannot connect | Run commands from Administrator PowerShell and inspect `agentnet-service.log`; then use `agentnet service restart`. |
+| Only this Windows host cannot reach peers | Check `Get-NetRoute -DestinationPrefix 10.86.0.0/16` and ensure another VPN has not installed a more specific `10.86.*` route. |
+| Carrier shows a peer online but ping/messages stop after a restart | Upgrade both ends to the current AgentNet version; session rekey convergence requires compatible daemon versions. |
+| Native mode is blocked by enterprise policy | Use the previous WSL2 deployment as a fallback; do not run native and WSL daemons with the same identity at the same time. |
+
+## Implementation and trust
+
+- The helper is written in Go and uses the official
+  [`golang.zx2c4.com/wintun`](https://git.zx2c4.com/wintun-go/) binding.
+- Release packaging accepts only the official Wintun 0.14.1 archive with
+  SHA-256 `07c256185d6ee3652e09fa55c0b673e2624b565e02c4b9091c79ca7d2f24ef51`.
+- The release package includes Wintun's license and an asset manifest; npm
+  publishing fails if either architecture's DLL is missing or changed.
+
+The native helper is cross-compiled and unit-tested from the main repository.
+
+### Native validation
+
+Release `0.1.199` was validated on real Windows 11 x64 (build 26200) with
+Node.js 24.15.0 on July 15, 2026. The smoke test covered global npm install,
+Wintun creation, `/32` address and `/16` route, firewall, named-pipe CLI,
+dora roster, cross-node ICMP and chat, graceful service restart, adapter
+recreation, and HTTPS CONNECT egress. After restart, allow roughly 30–90
+seconds for dora roster/session convergence before treating an early
+`no-ipam-record` ping as a failure.
+
+Windows ARM64 is cross-compiled and packaged but has not yet had equivalent
+real-hardware validation.

package/docs/INSTALL.md

@@ -13,27 +13,18 @@ transparently between any two daemons that are Carrier friends.
 | | minimum |
 |---|---|
 | Node.js | **20+** |
-| OS | Linux (`x86_64`, `aarch64`), macOS (`aarch64`, `x86_64`), or **Windows 10 / 11 via WSL2** ([Windows guide](INSTALL-WINDOWS.md)) |
-| Root / sudo | Yes — needed to create the TUN device. The daemon drops back to user-mode for everything else. |
+| OS | Linux (`x86_64`, `aarch64`), macOS (`aarch64`, `x86_64`), or native 64-bit Windows 10/11/Server (`x64`, `ARM64`) ([Windows guide](INSTALL-WINDOWS.md)) |
+| Privilege | Root/sudo on Unix or Administrator on Windows — needed to create and configure the TUN device. |
 | Outbound network | TCP and UDP to public Carrier bootstrap nodes (ports 33445 + 443). No inbound port needed; no public IP needed. |
 
 ### Windows
 
-Windows **is** supported — but the daemon runs inside **WSL2** (Windows
-Subsystem for Linux), a real Linux environment Windows installs for you, not
-on Windows directly. Requirements:
+Windows runs AgentNet natively using the signed Wintun driver bundled with the
+npm package. Node selects the correct x64 or ARM64 helper automatically; WSL
+is no longer required. Installation and service commands must run from an
+Administrator PowerShell.
 
-- **Windows 11**, or **Windows 10 version 2004 or later** (build 19041+) —
-  this is what the one-command `wsl --install` needs.
-- **Fast (direct UDP) path needs Windows 11, version 22H2 or later.** There you
-  turn on WSL **mirrored networking mode**, which lets the direct UDP
-  hole-punch succeed (~200 ms — smooth for live video). On **Windows 10**
-  mirrored mode doesn't exist, so WSL's NAT blocks inbound UDP and the SDK
-  falls back to the TCP relay: it still works, just slower (fine for SSH, chat,
-  and most browsing; live sports may stutter).
-
-👉 **Non-technical step-by-step for Windows users: [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md)**
-(install WSL → install Node.js → install decentlan, three steps).
+👉 **Native Windows step-by-step: [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md)**
 
 ## Install
 
@@ -42,8 +33,8 @@ npm install -g @decentnetwork/lan
 ```
 
 This installs the `agentnet` CLI on `$PATH` along with platform-
-specific TUN helper binaries (we ship `linux-amd64`, `linux-arm64`,
-`darwin-amd64`, and `darwin-arm64`). Confirm:
+specific TUN helper binaries (Linux/macOS x64 + ARM64 and Windows x64 + ARM64).
+The Windows directories also contain the matching signed `wintun.dll`. Confirm:
 
 ```bash
 agentnet --help
@@ -59,8 +50,8 @@ sudo agentnet service install --config-dir $HOME/.agentnet
 
 That's it. `agentnet init` already points at the public dora and sends
 the one-time friend-request; `service install` writes a systemd unit
-(Linux) or LaunchDaemon (macOS) that runs the daemon as root with
-auto-restart and logs to `/var/log/agentnet.log`.
+(Linux), LaunchDaemon (macOS), or elevated startup task (Windows) with
+automatic restart.
 
 Wait ~60–90s, then verify:
 
@@ -105,7 +96,7 @@ The daemon will:
 1. Open a Carrier connection
 2. Register with dora and get a virtual IP (e.g. `10.86.1.12`)
 3. Pull the network roster and auto-friend every other peer in it
-4. Bring up `agentnet0` on Linux (or `utun*` on macOS) at that IP
+4. Bring up `agentnet0` on Linux/Windows (or `utun*` on macOS) at that IP
 5. Start a local DNS server for `*.decent` (default) so you can
    `ping my-laptop.decent`, `ssh peer-name.decent`, etc.
 
@@ -237,7 +228,8 @@ to stop. Drop the `.plist` file to disable persistence.
 
 ## Running CLI commands once the daemon is up
 
-The CLI talks to the daemon over a Unix socket in the config-dir.
+The CLI talks to the daemon over a Unix socket in the config-dir, or a named
+pipe derived from that directory on Windows.
 Most commands (`diag`, `ipam list`, `friends list`, `friends pending`,
 `resolve`, `dora autofriend`) just read or write config files — they
 **don't need sudo**:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/lan",
-  "version": "0.1.197",
+  "version": "0.1.199",
   "description": "Private virtual LAN for self-hosted services and AI agents, built on Elastos Carrier. NAT-traversal, name service, ACL, all over a peer-to-peer mesh — no public IP required.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,6 +24,7 @@
     "README.md",
     "LICENSE",
     "docs/INSTALL.md",
+    "docs/INSTALL-WINDOWS.md",
     "docs/CONFIGURATION.md"
   ],
   "sideEffects": false,
@@ -65,7 +66,11 @@
     "build:helper:linux-arm64": "cd helper/tun-helper && GOOS=linux GOARCH=arm64 go build -o ../../bin/tun-helper-linux-arm64 .",
     "build:helper:darwin-arm64": "cd helper/tun-helper && GOOS=darwin GOARCH=arm64 go build -o ../../bin/tun-helper-darwin-arm64 .",
     "build:helper:darwin-amd64": "cd helper/tun-helper && GOOS=darwin GOARCH=amd64 go build -o ../../bin/tun-helper-darwin-amd64 .",
-    "build:helpers:all": "npm run build:helper:linux-amd64 && npm run build:helper:linux-arm64 && npm run build:helper:darwin-arm64 && npm run build:helper:darwin-amd64",
+    "build:helper:windows-amd64": "mkdir -p bin/windows-amd64 && cd helper/tun-helper && GOOS=windows GOARCH=amd64 go build -o ../../bin/windows-amd64/tun-helper-windows-amd64.exe .",
+    "build:helper:windows-arm64": "mkdir -p bin/windows-arm64 && cd helper/tun-helper && GOOS=windows GOARCH=arm64 go build -o ../../bin/windows-arm64/tun-helper-windows-arm64.exe .",
+    "build:helpers:all": "npm run build:helper:linux-amd64 && npm run build:helper:linux-arm64 && npm run build:helper:darwin-arm64 && npm run build:helper:darwin-amd64 && npm run build:helper:windows-amd64 && npm run build:helper:windows-arm64",
+    "fetch:wintun": "node scripts/fetch-wintun.mjs",
+    "verify:wintun": "node scripts/verify-wintun.mjs",
     "build:all": "npm run build && npm run build:helper",
     "clean": "rm -rf dist bin",
     "dev": "node --loader ts-node/esm src/index.ts",
@@ -74,7 +79,7 @@
     "test:coverage": "vitest --coverage",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src --ext .ts",
-    "prepublishOnly": "rm -rf dist && npm run build && npm run typecheck && npm run build:helpers:all",
+    "prepublishOnly": "rm -rf dist && npm run build && npm run typecheck && npm run build:helpers:all && npm run verify:wintun",
     "build:console": "node scripts/build-console.mjs"
   },
   "dependencies": {