@bun-win32/netdiag 1.0.0

package/AI.md

@@ -0,0 +1,99 @@
+# @bun-win32/netdiag — AI contract
+
+Syscall-grade Windows network diagnostics for Bun, decoded from binary Win32 structs via `bun:ffi`. **No child process, no node-gyp, no Administrator** (ICMP echo + table reads are unprivileged), locale-immune by construction. Windows-only, Bun-only.
+
+This file is the complete surface contract: an agent never needs to read the source. Every function below is a named export of `@bun-win32/netdiag` (and the unscoped `bun-netdiag`).
+
+```ts
+import { adapters, defaultGateway, ping, tcpConnections, throughput } from '@bun-win32/netdiag';
+```
+
+---
+
+## Capability map
+
+| function | returns | underlying Win32 API | admin? |
+|---|---|---|---|
+| `adapters(family?)` | `Adapter[]` (ipv4/ipv6, gateways, dns, mac, speed, mtu) | `GetAdaptersAddresses` | no |
+| `routes(family?)` | `Route[]` (destinationPrefix, nextHop, metric, protocol) | `GetIpForwardTable2` + `FreeMibTable` | no |
+| `defaultGateway(family?)` | `string \| undefined` (next hop of the lowest-metric default route) | `GetIpForwardTable2` | no |
+| `neighbors(family?)` / `arpTable()` | `Neighbor[]` (address, mac, state, isRouter) | `GetIpNetTable2` + `FreeMibTable` | no |
+| `tcpConnections(opts?)` | `TcpConnection[]` (socket→PID + optional process name) | `GetExtendedTcpTable` (+ `GetOwnerModuleFromTcpEntry`) | no |
+| `udpListeners(opts?)` | `UdpEndpoint[]` | `GetExtendedUdpTable` | no |
+| `ping(host, opts?)` | `Promise<PingReply>` (alive, roundTripMs, ttl, status) | `IcmpCreateFile` + `IcmpSendEcho` | **no** |
+| `pingMany(hosts, opts?)` | `Promise<PingReply[]>` | `IcmpSendEcho` | no |
+| `pingSweep(prefix, opts?)` | `Promise<SweepReply[]>` (async /24 sweep) | `IcmpSendEcho2` + Win32 Event | no |
+| `traceroute(host, opts?)` | `Promise<TraceHop[]>` (TTL ramp) | `IcmpSendEcho` + `IP_OPTION_INFORMATION32` | **no** |
+| `resolve(name, type?)` | `DnsRecord[]` (typed, discriminated on `type`) | `DnsQuery_W` + `DnsRecordListFree` | no |
+| `reverse(ip)` | `string[]` (PTR names) | `DnsQuery_W` | no |
+| `lookup(name)` | `{ ipv4: string[]; ipv6: string[] }` (system resolver) | `getaddrinfo` | no |
+| `tcpStatistics(family?)` / `ipStatistics()` / `udpStatistics()` | typed counter structs | `GetTcp/Ip/UdpStatisticsEx` | no |
+| `interfaceCounters()` | `InterfaceCounters[]` (octets, errors, discards) | `GetIfTable2` + `FreeMibTable` | no |
+| `throughput(intervalMs?)` | `Promise<ThroughputSample[]>` (rx/tx bytes/sec) | two `GetIfTable2` samples | no |
+| `bestRoute(host)` | `BestRoute` (source IP, next hop, interface the kernel would use) | `GetBestRoute2` | no |
+| `pathMtu(host, opts?)` | `PathMtuResult` (DF-probe binary search) | `IcmpSendEcho` + `IP_FLAG_DF` | no |
+| `wifiInterfaces()` | `WifiInterface[]` | `WlanEnumInterfaces` | no |
+| `wifiScan(opts?)` | `Promise<WifiNetwork[]>` (`triggerScan` for a fresh ~4 s scan) | `WlanGetAvailableNetworkList` (+ `WlanScan`) | no¹ |
+| `wifiConnection(guid?)` | `WifiConnection \| null` (signal, rate, bssid, auth) | `WlanQueryInterface` | no¹ |
+| `wifiBssList(guid?)` | `WifiBss[]` (signed-dBm RSSI, channel) | `WlanGetNetworkBssList` | no¹ |
+| `wifiConnect(profile, guid, {beta})` **beta** / `wifiDisconnect(guid, {beta})` **beta** | `WifiConnectResult` | `WlanConnect` / `WlanDisconnect` | no |
+
+¹ Windows 11 may require a one-time **Location** permission for WiFi SSID visibility (an OS gate — see gotchas).
+
+### Codecs (pure, no FFI) — `addr`
+`ipv4FromU32(value)`, `ipv6FromBytes(buffer, offset)` (RFC 5952), `portFromNetworkOrder(value)`, `macFromBytes(buffer, offset, length)`, `decodeSockaddr(buffer, offset)` → `SocketAddress`.
+
+### Constants / helpers
+`tcpStateName(state)`, `icmpStatusName(status)`, `addressFamilyValue(family)`, `DnsType`, `AF_INET`, `AF_INET6`, `TCP_TABLE_OWNER_PID_ALL`, `ICMP_SUCCESS`, …
+
+### Engine primitives — `win32`
+`SizedBufferState` (the reusable sizing-call buffer), `mibTable(invoke, firstRow, rowSize, decode)` (self-allocating Table2 decode + `FreeMibTable`), `walkList(base, head, nextOffset)` (in-buffer linked-list walk), `readWideAt` / `readAnsiAt`, `Win32Error` / `win32ErrorMessage`. Low-level ICMP: `sendEcho(destination, ttl, timeoutMs, payloadSize, flags?)`, `resolveIPv4(host)`.
+
+---
+
+## Layer 3 — the raw escape hatch
+
+Any IP Helper / wlanapi / dnsapi / winsock call netdiag didn't wrap is one import away — the binding packages are re-exported, and `SizedBufferState` / `mibTable` give you the sizing-call and self-alloc patterns:
+
+```ts
+import { Iphlpapi, SizedBufferState } from '@bun-win32/netdiag';
+
+const state = new SizedBufferState();
+const view = state.fill((dataPointer, sizePointer) => Iphlpapi.GetNetworkParams(dataPointer, sizePointer));
+const hostname = state.buffer.toString('ascii', 0, state.buffer.indexOf(0));
+```
+
+`Iphlpapi`, `Wlanapi`, `Dnsapi`, `Ws2_32`, `Kernel32` are all re-exported.
+
+---
+
+## Examples
+
+```ts
+import { adapters, defaultGateway, ping, resolve, tcpConnections, throughput, traceroute } from '@bun-win32/netdiag';
+
+defaultGateway('ipv4');                                  // '192.168.0.1' — no wmic, no spawn
+(await ping('1.1.1.1')).roundTripMs;                     // 11 — ICMP_ECHO_REPLY.RoundTripTime, no admin
+tcpConnections({ resolveNames: 'module' })               // [{ remoteAddress, remotePort, pid, processName: 'opera.exe' }, ...]
+  .filter((c) => c.state === 'established');
+await traceroute('8.8.8.8');                             // [{ ttl: 1, address: '192.168.0.1', status }, ...]
+resolve('google.com', 'MX');                             // [{ type: 'MX', preference: 10, exchange: 'smtp.google.com' }]
+(await throughput(1000))[0];                             // { name: 'Wi-Fi', rxBytesPerSec, txBytesPerSec }
+adapters().find((a) => a.gateways.length > 0)?.mac;      // '84:14:4d:b0:7d:e0'
+```
+
+---
+
+## Gotchas
+
+- **No admin, scoped honestly.** ICMP (`ping`/`traceroute`/`pingSweep`/`pathMtu`), every table read (routes/neighbors/sockets/adapters/stats), DNS, and WiFi scan/query are all unprivileged. Raw `SIO_RCVALL` packet capture and ARP/ND table *writes* would need Administrator — those are deliberately **not** in netdiag.
+- **`ping().status` on timeout.** Bun's FFI does not reliably preserve `GetLastError` across the boundary, so a 0-reply timeout is reported as `IP_REQ_TIMED_OUT` (11010) rather than guessing another `IP_STATUS`. `alive` is exactly `replied && status === IP_SUCCESS` — never an exit-code or TTL-string heuristic.
+- **Ports are network byte order.** All decoders byteswap via `portFromNetworkOrder`; 443 reads as 443, not 47873.
+- **Wide strings.** Decoded with `buffer.toString('utf16le')` up to NUL (Bun's `TextDecoder` rejects `'utf-16le'`). WiFi SSIDs are read from raw `DOT11_SSID` bytes as UTF-8 — Unicode/emoji-proof.
+- **WiFi connect is a beta.** `wifiConnect`/`wifiDisconnect` are signature-correct but UNEXERCISED against a live AP; they require `{ beta: true }`. Verify by polling `wifiConnection()`, never by callback.
+- **WiFi scan latency.** `wifiScan()` returns the instant OS-cached list; `wifiScan({ triggerScan: true })` runs a fresh `WlanScan` and waits ~4 s (which may flush the prior list).
+- **Win11 WiFi location consent.** `WlanGetAvailableNetworkList`/`WlanGetNetworkBssList` can return `ERROR_ACCESS_DENIED` until precise-location permission is granted (Settings → Privacy → Location). netdiag surfaces this as a distinct error, not an empty list — it is an OS gate, not a netdiag bug.
+- **Never silent.** Table APIs that fail throw `Win32Error` (code + message), never a silent empty array.
+- **`resolve()` vs `lookup()`.** `resolve()` (DnsQuery_W) queries DNS directly and honors the hosts file + OS resolver cache; `lookup()` (getaddrinfo) is the system resolver and may filter AAAA on IPv6-less hosts. They can return different answers — by design.
+- **IPv6 path-MTU / ping** are IPv4 today (roadmap: `Icmp6SendEcho2`).
+- **`throughput` rate uses the measured elapsed time**, so async-sleep quantization can't skew it.

package/README.md

@@ -0,0 +1,79 @@
+# @bun-win32/netdiag
+
+**Syscall-grade network diagnostics for Bun on Windows.** Routing table, socket→PID(+module) map, no-admin ICMP ping/traceroute, ARP/neighbors, DNS, live throughput, and WiFi — every result decoded from a **binary Win32 struct** via `bun:ffi`, never scraped from `netsh`/`ping.exe`/`wmic`/`arp`/`netstat` text.
+
+- **Zero child processes.** No `wmic`, no `ping.exe`, no `netsh`, no `tracert`, no PowerShell, no CMD-window flash.
+- **Zero native build.** Pure `bun:ffi` — no `node-gyp`, no NAN addon, no Node-version drift.
+- **Zero Administrator.** ICMP echo and every table read are unprivileged. The integration selftest runs in a non-elevated shell.
+- **Zero dependencies** outside the workspace. Every DLL it calls already ships in `C:\Windows\System32`.
+- **Locale-immune by construction.** Struct fields don't translate; a French or German Windows can't break a `DataView.getUint32`.
+
+> Windows-only, Bun-only — stated proudly. `bun add bun-netdiag` pulls a few kilobytes of TypeScript and zero native binaries.
+
+## 10-line wow
+
+```ts
+import { defaultGateway, ping, tcpConnections, throughput } from 'bun-netdiag';
+
+defaultGateway();                                         // '192.168.0.1'  — GetIpForwardTable2, no wmic
+(await ping('1.1.1.1')).roundTripMs;                      // 11            — ICMP reply struct, no admin
+tcpConnections({ resolveNames: 'module' })                // socket → PID → owning module, one syscall
+  .filter((c) => c.state === 'established')
+  .map((c) => `${c.remoteAddress}:${c.remotePort}  ${c.pid}  ${c.processName}`);
+//  160.79.104.10:443   20408   claude.exe
+//  52.96.157.162:443   24320   opera.exe
+(await throughput(1000))[0];                              // { name: 'Wi-Fi', rxBytesPerSec: 82_700_000, txBytesPerSec }
+```
+
+## Why this exists
+
+Every Windows networking package on npm either **shells out** to a localized command and regex-scrapes its stdout, or builds a **node-gyp native addon**. Both break. netdiag reads the same IP Helper / wlanapi / dnsapi structs the OS reads.
+
+| incumbent | weekly downloads | what's wrong (receipt) | netdiag |
+|---|---|---|---|
+| `default-gateway` | 8.1M | **GitHub-archived 2026-02-05**; spawns `wmic`, which Microsoft is removing from Windows 11 ([#25](https://github.com/silverwind/default-gateway/issues/25)); maintainer: *"parsing command output is a wrong approach"* ([#27](https://github.com/silverwind/default-gateway/issues/27)) | `defaultGateway()` reads `GetIpForwardTable2` directly |
+| `systeminformation` | 5.87M | spawns PowerShell/`netstat`/`netsh`; sockets are **PID-only** (hardcoded `process:''`); `networkStats` has a **500 ms throttle**; CVE-2021-21315 shell-injection class | `tcpConnections()` adds the **module name**; `throughput()` is sub-ms; no shell to inject |
+| `node-ping` | 190k | spawns `ping.exe` + regex-parses localized stdout — crashes on French Windows (`temps`, [#64](https://github.com/danielzzz/node-ping/issues/64)); `alive` always false ([#26](https://github.com/danielzzz/node-ping/issues/26)) | `ping()` reads `ICMP_ECHO_REPLY.RoundTripTime` (u32) — no locale, ever |
+| `node-wifi` | 2.9k | stale since 2021; `netsh` field-reorder on Win11 → `ssid='connected'` ([#184](https://github.com/friedrith/node-wifi/issues/184)); Unicode SSID mangling ([#198](https://github.com/friedrith/node-wifi/issues/198)) | `wifiScan()`/`wifiConnection()` read wlanapi structs by offset; SSID is raw UTF-8 |
+| `local-devices` / arp scrapers | 3.4k | spawn `arp -a` with a fixed-index parser; `arp -n` Unix flag fails on Windows ([#75](https://github.com/DylanPiercey/local-devices/issues/75)); device name always `?` ([#21](https://github.com/DylanPiercey/local-devices/issues/21)) | `neighbors()` reads `GetIpNetTable2` — typed, with reachability **state** and IPv6 ND; `reverse()` for names |
+| `net-ping` / `raw-socket` | 1.4k+1.8k | `node-gyp` build fails on Node 20/24 ([#91](https://github.com/nospaceships/node-raw-socket/issues/91)); raw ICMP socket needs **Administrator** ([#88](https://github.com/nospaceships/node-net-ping/issues/88)) | `ping()`/`traceroute()` over `IcmpSendEcho` — no node-gyp, no admin, no raw socket |
+| `node-netstat` / `windows-netstat` | 2.7k+6 | spawn `netstat` (LISTEN/LISTENING drift, [#42](https://github.com/danielkrainas/node-netstat/issues/42)) or node-gyp IPv4-only | `tcpConnections('all')` + `udpListeners('all')` — TCP4/6 + UDP4/6, canonical state strings |
+
+**No zero-install, pure-FFI Windows network-diagnostics competitor exists on npm** (verified 2026-06-13). The niche is unoccupied.
+
+## Benchmarks
+
+Every table is one syscall, not a process spawn. Measured on the host below (`bun run example/benchmark.ts` — `Bun.nanoseconds`, warm-up, DFG-verified):
+
+| operation | ns/op | samples/sec |
+|---|---|---|
+| `routes()` poll + decode | ~31,700 | ~31,500 |
+| `tcpConnections()` poll (v4+v6) | ~194,000 | ~5,100 |
+| `IcmpSendEcho` to 127.0.0.1 | ~79,800 | ~12,500 |
+| `interfaceCounters()` poll | ~606,000 | ~1,650 |
+
+Spawning `route print` once costs **~70 ms** (~14/sec). `routes()` polls **~2,200× faster** — the difference between a live dashboard and a stuttering one. (Numbers are host-specific; re-run the benchmark.)
+
+## API
+
+`adapters` · `routes` / `defaultGateway` · `neighbors` / `arpTable` · `tcpConnections` / `udpListeners` · `ping` / `pingMany` / `pingSweep` / `traceroute` · `resolve` / `reverse` / `lookup` · `tcpStatistics` / `ipStatistics` / `udpStatistics` / `interfaceCounters` / `throughput` · `bestRoute` / `pathMtu` · `wifiInterfaces` / `wifiScan` / `wifiConnection` / `wifiBssList` / `wifiConnect`(beta) / `wifiDisconnect`(beta) · the raw escape hatch (`Iphlpapi`, `Wlanapi`, `Dnsapi`, `Ws2_32`, `Kernel32`).
+
+Full surface contract in [`AI.md`](./AI.md). Examples in [`example/`](./example): `net-report`, `netwatch` (live dashboard), `ping`, `wifi-scan`, `benchmark`, `netdiag.selftest`.
+
+## Verified against the OS's own tools
+
+`netdiag.selftest.ts` passes 19 assertions in a non-elevated shell, and the cross-validation matches the OS tools exactly: `defaultGateway()` = `ipconfig`, `neighbors()` = `arp -a`, `tcpConnections()` PIDs = `netstat -ano`, `routes()` = `route print`, `resolve()` = `nslookup`, `ping()` TTL = `ping.exe`, `adapters()` MAC = `ipconfig /all`, `wifiConnection()` = `netsh wlan show interfaces`.
+
+## What this does NOT do
+
+- **Cross-platform.** Windows-only by design — the Windows backend done right. For Linux/macOS/Node, `systeminformation` / `default-gateway` are the answer.
+- **HTTP reachability.** netdiag is layer 3/4; use Bun's built-in `fetch()` for HTTP-level checks.
+- **Raw packet capture / ARP-table writes.** Those need Administrator and are out of the no-admin scope (the raw escape hatch is there if you need them).
+- **OUI/vendor lookup.** Out of the zero-dependency core.
+- **Bullet-proof WiFi connect.** `wifiConnect`/`wifiDisconnect` ship as a flagged beta, unexercised against a live AP.
+
+Roadmap: IPv6 ping/path-MTU (`Icmp6SendEcho2`), ping count/loss statistics + `deadlineMs`, per-connection ESTATS RTT (admin), CIDR/range `discover()`.
+
+## License
+
+MIT. Part of [bun-win32](https://github.com/ObscuritySRL/bun-win32).

package/adapters.ts

@@ -0,0 +1,123 @@
+import { decodeSockaddr, macFromBytes } from './addr';
+import { addressFamilyValue, type AddressFamilyName } from './constants';
+import { Iphlpapi, readAnsiAt, readWideAt, SizedBufferState, walkList } from './win32';
+
+// IP_ADAPTER_ADDRESSES_LH (x64) field offsets — verified vs iptypes.h + ipconfig /all (S3.3).
+const NODE_IF_INDEX = 4;
+const NODE_NEXT = 8;
+const NODE_ADAPTER_NAME = 16; // PCHAR (ANSI GUID)
+const NODE_FIRST_UNICAST = 24;
+const NODE_FIRST_DNS_SERVER = 48;
+const NODE_DNS_SUFFIX = 56; // PWCHAR
+const NODE_DESCRIPTION = 64; // PWCHAR
+const NODE_FRIENDLY_NAME = 72; // PWCHAR
+const NODE_PHYSICAL_ADDRESS = 80;
+const NODE_PHYSICAL_ADDRESS_LENGTH = 88;
+const NODE_MTU = 96;
+const NODE_IF_TYPE = 100;
+const NODE_OPER_STATUS = 104;
+const NODE_TRANSMIT_LINK_SPEED = 184; // ULONG64 bits/sec
+const NODE_FIRST_GATEWAY = 208;
+
+// Sub-list node (IP_ADAPTER_{UNICAST,GATEWAY,DNS_SERVER}_ADDRESS) shared shape.
+const SUB_NEXT = 8;
+const SUB_SOCKET_ADDRESS_POINTER = 16; // SOCKET_ADDRESS.lpSockaddr
+
+const GAA_FLAG_INCLUDE_GATEWAYS = 0x0000_0080;
+const GAA_FLAG_SKIP_ANYCAST = 0x0000_0002;
+const GAA_FLAG_SKIP_MULTICAST = 0x0000_0004;
+const LINK_SPEED_UNKNOWN = 0xffff_ffff_ffff_ffffn;
+
+const OPER_STATUS_NAMES: ReadonlyMap<number, string> = new Map([
+  [1, 'up'],
+  [2, 'down'],
+  [3, 'testing'],
+  [4, 'unknown'],
+  [5, 'dormant'],
+  [6, 'not-present'],
+  [7, 'lower-layer-down'],
+]);
+
+export interface Adapter {
+  index: number;
+  name: string;
+  friendlyName: string;
+  description: string;
+  mac: string;
+  type: number;
+  operStatus: string;
+  linkSpeedMbps: number;
+  mtu: number;
+  ipv4: string[];
+  ipv6: string[];
+  gateways: string[];
+  dnsServers: string[];
+  dnsSuffix: string;
+}
+
+const adapterState = new SizedBufferState(0x0000_8000);
+
+function pointerToOffset(base: Buffer, baseAddress: number, fieldOffset: number): number {
+  const pointer = Number(base.readBigUInt64LE(fieldOffset));
+  return pointer === 0 ? -1 : pointer - baseAddress;
+}
+
+function collectUnicast(base: Buffer, baseAddress: number, headFieldOffset: number, ipv4: string[], ipv6: string[]): void {
+  const head = Number(base.readBigUInt64LE(headFieldOffset));
+  for (const node of walkList(base, head, SUB_NEXT)) {
+    const sockaddrPointer = Number(base.readBigUInt64LE(node + SUB_SOCKET_ADDRESS_POINTER));
+    if (sockaddrPointer === 0) continue;
+    const address = decodeSockaddr(base, sockaddrPointer - baseAddress);
+    if (address.family === 'ipv4') ipv4.push(address.address);
+    else if (address.family === 'ipv6') ipv6.push(address.address);
+  }
+}
+
+function collectAddresses(base: Buffer, baseAddress: number, headFieldOffset: number, out: string[]): void {
+  const head = Number(base.readBigUInt64LE(headFieldOffset));
+  for (const node of walkList(base, head, SUB_NEXT)) {
+    const sockaddrPointer = Number(base.readBigUInt64LE(node + SUB_SOCKET_ADDRESS_POINTER));
+    if (sockaddrPointer === 0) continue;
+    out.push(decodeSockaddr(base, sockaddrPointer - baseAddress).address);
+  }
+}
+
+/** Typed adapter inventory (IPv4 + IPv6) over GetAdaptersAddresses — the modern replacement for GetAdaptersInfo. */
+export function adapters(family: AddressFamilyName = 'all'): Adapter[] {
+  const familyValue = addressFamilyValue(family);
+  const flags = GAA_FLAG_INCLUDE_GATEWAYS | GAA_FLAG_SKIP_ANYCAST | GAA_FLAG_SKIP_MULTICAST;
+  const view = adapterState.fill((dataPointer, sizePointer) => Iphlpapi.GetAdaptersAddresses(familyValue, flags, null, dataPointer, sizePointer));
+  const base = adapterState.buffer;
+  const baseAddress = Number(base.ptr);
+  const result: Adapter[] = [];
+
+  for (const node of walkList(base, baseAddress, NODE_NEXT)) {
+    const physicalLength = view.getUint32(node + NODE_PHYSICAL_ADDRESS_LENGTH, true);
+    const linkSpeed = base.readBigUInt64LE(node + NODE_TRANSMIT_LINK_SPEED);
+    const ipv4: string[] = [];
+    const ipv6: string[] = [];
+    const gateways: string[] = [];
+    const dnsServers: string[] = [];
+    collectUnicast(base, baseAddress, node + NODE_FIRST_UNICAST, ipv4, ipv6);
+    collectAddresses(base, baseAddress, node + NODE_FIRST_GATEWAY, gateways);
+    collectAddresses(base, baseAddress, node + NODE_FIRST_DNS_SERVER, dnsServers);
+
+    result.push({
+      index: view.getUint32(node + NODE_IF_INDEX, true),
+      name: readAnsiAt(base, pointerToOffset(base, baseAddress, node + NODE_ADAPTER_NAME)),
+      friendlyName: readWideAt(base, pointerToOffset(base, baseAddress, node + NODE_FRIENDLY_NAME)),
+      description: readWideAt(base, pointerToOffset(base, baseAddress, node + NODE_DESCRIPTION)),
+      mac: macFromBytes(base, node + NODE_PHYSICAL_ADDRESS, physicalLength),
+      type: view.getUint32(node + NODE_IF_TYPE, true),
+      operStatus: OPER_STATUS_NAMES.get(view.getInt32(node + NODE_OPER_STATUS, true)) ?? 'unknown',
+      linkSpeedMbps: linkSpeed === LINK_SPEED_UNKNOWN ? 0 : Number(linkSpeed / 1_000_000n),
+      mtu: view.getUint32(node + NODE_MTU, true),
+      ipv4,
+      ipv6,
+      gateways,
+      dnsServers,
+      dnsSuffix: readWideAt(base, pointerToOffset(base, baseAddress, node + NODE_DNS_SUFFIX)),
+    });
+  }
+  return result;
+}

package/addr.ts

@@ -0,0 +1,83 @@
+export interface SocketAddress {
+  family: 'ipv4' | 'ipv6' | 'unknown';
+  address: string;
+  port: number;
+  scopeId?: number;
+}
+
+const AF_INET = 0x0000_0002;
+const AF_INET6 = 0x0000_0017;
+
+/** IPv4 dotted-quad from a u32 holding the four address bytes in memory (network) order. */
+export function ipv4FromU32(value: number): string {
+  return `${value & 0xff}.${(value >>> 8) & 0xff}.${(value >>> 16) & 0xff}.${(value >>> 24) & 0xff}`;
+}
+
+/** Host-order port from a network-order (big-endian) 16-bit value. */
+export function portFromNetworkOrder(value: number): number {
+  return ((value & 0xff) << 8) | ((value >>> 8) & 0xff);
+}
+
+/** Colon-separated lowercase-hex MAC from `length` bytes at `offset`. */
+export function macFromBytes(buffer: Buffer, offset: number, length: number): string {
+  let mac = '';
+  for (let index = 0; index < length; index++) {
+    if (index > 0) mac += ':';
+    mac += buffer[offset + index].toString(16).padStart(2, '0');
+  }
+  return mac;
+}
+
+/** Canonical RFC 5952 IPv6 text (lowercase, longest-run `::` compression) from 16 bytes at `offset`. */
+export function ipv6FromBytes(buffer: Buffer, offset: number): string {
+  const groups: number[] = [];
+  for (let index = 0; index < 8; index++) groups.push((buffer[offset + index * 2] << 8) | buffer[offset + index * 2 + 1]);
+
+  let bestStart = -1;
+  let bestLength = 0;
+  let runStart = -1;
+  let runLength = 0;
+  for (let index = 0; index < 8; index++) {
+    if (groups[index] === 0) {
+      if (runStart === -1) runStart = index;
+      runLength++;
+    } else {
+      runStart = -1;
+      runLength = 0;
+    }
+    if (runLength > bestLength) {
+      bestLength = runLength;
+      bestStart = runStart;
+    }
+  }
+  if (bestLength < 2) bestStart = -1; // RFC 5952: do not compress a single zero group
+
+  const segments: string[] = [];
+  for (let index = 0; index < 8; index++) {
+    if (index === bestStart) {
+      segments.push(''); // open the compressed run
+      index += bestLength - 1;
+      if (index === 7) segments.push(''); // run reaches the end → trailing colon
+      continue;
+    }
+    segments.push(groups[index].toString(16));
+  }
+  if (bestStart === 0) segments.unshift(''); // run starts at the beginning → leading colon
+  return segments.join(':');
+}
+
+/**
+ * Decode a SOCKADDR_INET union at `offset`: si_family (USHORT) at +0 selects
+ * sockaddr_in (port@+2 BE, addr@+4) or sockaddr_in6 (port@+2 BE, addr@+8,
+ * scope_id@+24). Ports are network byte order; addresses are formatted.
+ */
+export function decodeSockaddr(buffer: Buffer, offset: number): SocketAddress {
+  const family = buffer.readUInt16LE(offset);
+  if (family === AF_INET) {
+    return { family: 'ipv4', address: ipv4FromU32(buffer.readUInt32LE(offset + 4)), port: buffer.readUInt16BE(offset + 2) };
+  }
+  if (family === AF_INET6) {
+    return { family: 'ipv6', address: ipv6FromBytes(buffer, offset + 8), port: buffer.readUInt16BE(offset + 2), scopeId: buffer.readUInt32LE(offset + 24) };
+  }
+  return { family: 'unknown', address: '', port: 0 };
+}

package/arp.ts

@@ -0,0 +1,62 @@
+import { decodeSockaddr, macFromBytes } from './addr';
+import { addressFamilyValue, type AddressFamilyName } from './constants';
+import { Iphlpapi, mibTable } from './win32';
+
+// MIB_IPNET_TABLE2 { ULONG NumEntries; MIB_IPNET_ROW2 Table[] } — rows 8-aligned.
+const TABLE_FIRST_ROW = 8;
+// MIB_IPNET_ROW2 (x64, netioapi.h) — stride verified end-to-end vs `arp -a` (S4.3).
+const ROW_SIZE = 88;
+const ROW_ADDRESS = 0; // SOCKADDR_INET
+const ROW_INTERFACE_INDEX = 28;
+const ROW_PHYSICAL_ADDRESS = 40;
+const ROW_PHYSICAL_ADDRESS_LENGTH = 72;
+const ROW_STATE = 76;
+const ROW_FLAGS = 80; // bit0 IsRouter, bit1 IsUnreachable
+
+const NEIGHBOR_STATE_NAMES: ReadonlyMap<number, string> = new Map([
+  [0, 'unreachable'],
+  [1, 'incomplete'],
+  [2, 'probe'],
+  [3, 'delay'],
+  [4, 'stale'],
+  [5, 'reachable'],
+  [6, 'permanent'],
+]);
+
+export interface Neighbor {
+  address: string;
+  mac: string;
+  interfaceIndex: number;
+  state: string;
+  isRouter: boolean;
+  isUnreachable: boolean;
+  family: 'ipv4' | 'ipv6' | 'unknown';
+}
+
+/** The typed neighbor (ARP + IPv6 ND) table over GetIpNetTable2 — richer than `arp -a` (reachability STATE, IPv6). */
+export function neighbors(family: AddressFamilyName = 'all'): Neighbor[] {
+  const familyValue = addressFamilyValue(family);
+  return mibTable(
+    (tablePointer) => Iphlpapi.GetIpNetTable2(familyValue, tablePointer),
+    TABLE_FIRST_ROW,
+    ROW_SIZE,
+    (table, row) => {
+      const address = decodeSockaddr(table, row + ROW_ADDRESS);
+      const flags = table.readUInt8(row + ROW_FLAGS);
+      return {
+        address: address.address,
+        mac: macFromBytes(table, row + ROW_PHYSICAL_ADDRESS, table.readUInt32LE(row + ROW_PHYSICAL_ADDRESS_LENGTH)),
+        interfaceIndex: table.readUInt32LE(row + ROW_INTERFACE_INDEX),
+        state: NEIGHBOR_STATE_NAMES.get(table.readUInt32LE(row + ROW_STATE)) ?? 'unknown',
+        isRouter: (flags & 0x1) !== 0,
+        isUnreachable: (flags & 0x2) !== 0,
+        family: address.family,
+      };
+    },
+  );
+}
+
+/** The classic IPv4-only ARP table view (a familiar `arp -a` shape over the modern API). */
+export function arpTable(): Neighbor[] {
+  return neighbors('ipv4');
+}

package/constants.ts

@@ -0,0 +1,75 @@
+export { DnsType } from '@bun-win32/dnsapi';
+
+export type AddressFamilyName = 'all' | 'ipv4' | 'ipv6';
+
+const ADDRESS_FAMILY_VALUES: Record<AddressFamilyName, number> = {
+  all: 0x0000_0000, // AF_UNSPEC
+  ipv4: 0x0000_0002, // AF_INET
+  ipv6: 0x0000_0017, // AF_INET6
+};
+
+export const AF_INET = 0x0000_0002;
+export const AF_INET6 = 0x0000_0017;
+
+export function addressFamilyValue(family: AddressFamilyName): number {
+  return ADDRESS_FAMILY_VALUES[family];
+}
+
+// GetExtendedTcpTable / GetExtendedUdpTable table-class selectors (TCP_TABLE_CLASS / UDP_TABLE_CLASS).
+export const TCP_TABLE_OWNER_MODULE_ALL = 0x0000_0008;
+export const TCP_TABLE_OWNER_PID_ALL = 0x0000_0005;
+export const TCPIP_OWNER_MODULE_INFO_BASIC = 0x0000_0000;
+export const UDP_TABLE_OWNER_PID = 0x0000_0001;
+
+// MIB_TCP_STATE (1..12).
+const TCP_STATE_NAMES: ReadonlyMap<number, string> = new Map([
+  [1, 'closed'],
+  [2, 'listen'],
+  [3, 'syn-sent'],
+  [4, 'syn-received'],
+  [5, 'established'],
+  [6, 'fin-wait-1'],
+  [7, 'fin-wait-2'],
+  [8, 'close-wait'],
+  [9, 'closing'],
+  [10, 'last-ack'],
+  [11, 'time-wait'],
+  [12, 'delete-tcb'],
+]);
+
+export function tcpStateName(state: number): string {
+  return TCP_STATE_NAMES.get(state) ?? `unknown(${state})`;
+}
+
+// ICMP reply status codes (ipexport.h IP_STATUS).
+export const ICMP_SUCCESS = 0x0000_0000;
+export const ICMP_PACKET_TOO_BIG = 11009;
+export const ICMP_REQUEST_TIMED_OUT = 11010;
+export const ICMP_TTL_EXPIRED_TRANSIT = 11013;
+
+const ICMP_STATUS_NAMES: ReadonlyMap<number, string> = new Map([
+  [0, 'success'],
+  [11001, 'buffer too small'],
+  [11002, 'destination network unreachable'],
+  [11003, 'destination host unreachable'],
+  [11004, 'destination protocol unreachable'],
+  [11005, 'destination port unreachable'],
+  [11006, 'no resources'],
+  [11007, 'bad option'],
+  [11008, 'hardware error'],
+  [11009, 'packet too big'],
+  [11010, 'request timed out'],
+  [11011, 'bad request'],
+  [11012, 'bad route'],
+  [11013, 'TTL expired in transit'],
+  [11014, 'TTL expired during reassembly'],
+  [11015, 'parameter problem'],
+  [11016, 'source quench'],
+  [11017, 'option too big'],
+  [11018, 'bad destination'],
+  [11050, 'general failure'],
+]);
+
+export function icmpStatusName(status: number): string {
+  return ICMP_STATUS_NAMES.get(status) ?? `unknown(${status})`;
+}