@bun-win32/netdiag 1.0.0

package/dns.ts

@@ -0,0 +1,161 @@
+import { type Pointer, toArrayBuffer } from 'bun:ffi';
+
+import { ipv4FromU32, ipv6FromBytes } from './addr';
+import { DnsType } from './constants';
+import { Dnsapi, readWideAt, Ws2_32 } from './win32';
+
+const DNS_QUERY_STANDARD = 0x0000_0000;
+const DNS_FREE_RECORD_LIST = 0x0000_0001; // DnsFreeType.DnsFreeRecordList
+const AF_INET = 0x0000_0002;
+const AF_INET6 = 0x0000_0017;
+
+export type RecordType = 'A' | 'AAAA' | 'CNAME' | 'MX' | 'NS' | 'PTR' | 'SOA' | 'SRV' | 'TXT';
+
+export type DnsRecord =
+  | { type: 'A'; address: string; ttl: number }
+  | { type: 'AAAA'; address: string; ttl: number }
+  | { type: 'CNAME'; name: string; ttl: number }
+  | { type: 'MX'; preference: number; exchange: string; ttl: number }
+  | { type: 'NS'; name: string; ttl: number }
+  | { type: 'PTR'; name: string; ttl: number }
+  | { type: 'SOA'; primary: string; admin: string; serial: number; refresh: number; retry: number; expire: number; minimumTtl: number; ttl: number }
+  | { type: 'SRV'; priority: number; weight: number; port: number; target: string; ttl: number }
+  | { type: 'TXT'; strings: string[]; ttl: number };
+
+export interface LookupResult {
+  ipv4: string[];
+  ipv6: string[];
+}
+
+const RECORD_TYPE_VALUES: Record<RecordType, number> = {
+  A: DnsType.DNS_TYPE_A,
+  AAAA: DnsType.DNS_TYPE_AAAA,
+  CNAME: DnsType.DNS_TYPE_CNAME,
+  MX: DnsType.DNS_TYPE_MX,
+  NS: DnsType.DNS_TYPE_NS,
+  PTR: DnsType.DNS_TYPE_PTR,
+  SOA: DnsType.DNS_TYPE_SOA,
+  SRV: DnsType.DNS_TYPE_SRV,
+  TXT: DnsType.DNS_TYPE_TEXT,
+};
+
+let winsockReady = false;
+function ensureWinsock(): void {
+  if (winsockReady) return;
+  Ws2_32.WSAStartup(0x0202, Buffer.allocUnsafeSlow(0x0198).ptr);
+  winsockReady = true;
+}
+
+function readWidePointer(pointer: number): string {
+  return pointer === 0 ? '' : readWideAt(Buffer.from(toArrayBuffer(pointer as Pointer, 0, 0x0400)), 0);
+}
+
+// DNS_RECORD data union (x64): each per-type payload begins at +32; wide-string fields are SEPARATELY-allocated pointers.
+function decodeRecord(addr: Pointer, type: RecordType, ttl: number): DnsRecord {
+  const node = Buffer.from(toArrayBuffer(addr, 0, 72)); // header(32) + largest fixed payload (SOA)
+  switch (type) {
+    case 'A':
+      return { type, address: ipv4FromU32(node.readUInt32LE(32)), ttl };
+    case 'AAAA':
+      return { type, address: ipv6FromBytes(node, 32), ttl };
+    case 'CNAME':
+    case 'NS':
+    case 'PTR':
+      return { type, name: readWidePointer(Number(node.readBigUInt64LE(32))), ttl };
+    case 'MX':
+      return { type, exchange: readWidePointer(Number(node.readBigUInt64LE(32))), preference: node.readUInt16LE(40), ttl };
+    case 'SRV':
+      return { type, target: readWidePointer(Number(node.readBigUInt64LE(32))), priority: node.readUInt16LE(40), weight: node.readUInt16LE(42), port: node.readUInt16LE(44), ttl };
+    case 'SOA':
+      return {
+        type,
+        primary: readWidePointer(Number(node.readBigUInt64LE(32))),
+        admin: readWidePointer(Number(node.readBigUInt64LE(40))),
+        serial: node.readUInt32LE(48),
+        refresh: node.readUInt32LE(52),
+        retry: node.readUInt32LE(56),
+        expire: node.readUInt32LE(60),
+        minimumTtl: node.readUInt32LE(64),
+        ttl,
+      };
+    case 'TXT': {
+      const count = node.readUInt32LE(32);
+      const array = Buffer.from(toArrayBuffer(addr, 0, 40 + count * 8)); // dwStringCount@32, pStringArray@40
+      const strings: string[] = [];
+      for (let index = 0; index < count; index++) strings.push(readWidePointer(Number(array.readBigUInt64LE(40 + index * 8))));
+      return { type, strings, ttl };
+    }
+  }
+}
+
+const queryOut = Buffer.allocUnsafeSlow(8);
+
+/** Query DNS directly (DnsQuery_W) for a typed record set — arbitrary record types, beyond node:dns's fixed list. */
+export function resolve<T extends RecordType>(name: string, type: T): Extract<DnsRecord, { type: T }>[];
+export function resolve(name: string): Extract<DnsRecord, { type: 'A' }>[];
+export function resolve(name: string, type: RecordType = 'A'): DnsRecord[] {
+  const typeValue = RECORD_TYPE_VALUES[type];
+  const wide = Buffer.allocUnsafeSlow((name.length + 1) * 2);
+  wide.writeUInt16LE(0, wide.write(name, 'utf16le'));
+  const status = Dnsapi.DnsQuery_W(wide.ptr, typeValue, DNS_QUERY_STANDARD, null, queryOut.ptr, null);
+  if (status !== 0) return [];
+  const head = Number(queryOut.readBigUInt64LE(0));
+  if (head === 0) return [];
+  const records: DnsRecord[] = [];
+  try {
+    let current = head;
+    while (current !== 0) {
+      const node = Buffer.from(toArrayBuffer(current as Pointer, 0, 32));
+      if (node.readUInt16LE(16) === typeValue) records.push(decodeRecord(current as Pointer, type, node.readUInt32LE(24)));
+      current = Number(node.readBigUInt64LE(0));
+    }
+  } finally {
+    Dnsapi.DnsRecordListFree(head as Pointer, DNS_FREE_RECORD_LIST);
+  }
+  return records;
+}
+
+function ipv6ToArpa(ip: string): string {
+  ensureWinsock();
+  const bytes = Buffer.allocUnsafeSlow(16);
+  const wide = Buffer.allocUnsafeSlow((ip.length + 1) * 2);
+  wide.writeUInt16LE(0, wide.write(ip, 'utf16le'));
+  if (Ws2_32.InetPtonW(AF_INET6, wide.ptr, bytes.ptr) !== 1) throw new Error(`invalid IPv6 address "${ip}"`);
+  let name = '';
+  for (let index = 15; index >= 0; index--) name += `${(bytes[index] & 0x0f).toString(16)}.${(bytes[index] >> 4).toString(16)}.`;
+  return `${name}ip6.arpa`;
+}
+
+/** Reverse-resolve an IP to PTR names (in-addr.arpa / ip6.arpa). */
+export function reverse(ip: string): string[] {
+  const queryName = ip.includes(':') ? ipv6ToArpa(ip) : `${ip.split('.').reverse().join('.')}.in-addr.arpa`;
+  return resolve(queryName, 'PTR').map((record) => record.name);
+}
+
+/** The SYSTEM resolver (getaddrinfo) — honors the hosts file and the full resolution policy; a different answer from resolve(). */
+export function lookup(name: string): LookupResult {
+  ensureWinsock();
+  const result: LookupResult = { ipv4: [], ipv6: [] };
+  const resultPointer = Buffer.allocUnsafeSlow(8);
+  const nameBuffer = Buffer.allocUnsafeSlow(name.length + 1); // getaddrinfo is the ANSI (LPCSTR) variant
+  nameBuffer.write(name, 'latin1');
+  nameBuffer[name.length] = 0;
+  if (Ws2_32.getaddrinfo(nameBuffer.ptr, null, null, resultPointer.ptr) !== 0) return result;
+  const head = Number(resultPointer.readBigUInt64LE(0));
+  try {
+    let nodePointer = head;
+    while (nodePointer !== 0) {
+      const node = Buffer.from(toArrayBuffer(nodePointer as Pointer, 0, 48)); // ADDRINFOA
+      const addressPointer = Number(node.readBigUInt64LE(32));
+      if (addressPointer !== 0) {
+        const sockaddr = Buffer.from(toArrayBuffer(addressPointer as Pointer, 0, 28));
+        if (node.readInt32LE(4) === AF_INET) result.ipv4.push(ipv4FromU32(sockaddr.readUInt32LE(4)));
+        else if (node.readInt32LE(4) === AF_INET6) result.ipv6.push(ipv6FromBytes(sockaddr, 8));
+      }
+      nodePointer = Number(node.readBigUInt64LE(40));
+    }
+  } finally {
+    Ws2_32.freeaddrinfo(head as Pointer);
+  }
+  return result;
+}

package/extras.ts

@@ -0,0 +1,76 @@
+import { decodeSockaddr, ipv4FromU32 } from './addr';
+import { ICMP_PACKET_TOO_BIG, ICMP_SUCCESS } from './constants';
+import { resolveIPv4, sendEcho } from './ping';
+import { Iphlpapi, Win32Error } from './win32';
+
+const AF_INET = 0x0000_0002;
+const IP_FLAG_DF = 0x02;
+const SOCKADDR_INET_SIZE = 28;
+const MIB_IPFORWARD_ROW2_SIZE = 104;
+const ROW2_INTERFACE_INDEX = 8;
+const ROW2_NEXT_HOP = 44; // SOCKADDR_INET
+const ROW2_METRIC = 84;
+
+export interface BestRoute {
+  destination: string;
+  sourceAddress: string;
+  nextHop: string;
+  interfaceIndex: number;
+  metric: number;
+}
+
+export interface PathMtuResult {
+  mtu: number;
+  determined: boolean;
+}
+
+const bestRouteBuffer = Buffer.allocUnsafeSlow(MIB_IPFORWARD_ROW2_SIZE);
+const bestSourceBuffer = Buffer.allocUnsafeSlow(SOCKADDR_INET_SIZE);
+const destinationBuffer = Buffer.allocUnsafeSlow(SOCKADDR_INET_SIZE);
+
+/**
+ * Which interface, source IP, and next hop the kernel would use to reach a host
+ * (GetBestRoute2) — IPv4. No incumbent does this without parsing `route print`.
+ */
+export function bestRoute(host: string): BestRoute {
+  const destination = resolveIPv4(host);
+  destinationBuffer.fill(0);
+  destinationBuffer.writeUInt16LE(AF_INET, 0); // SOCKADDR_INET.si_family
+  destinationBuffer.writeUInt32LE(destination, 4); // sin_addr (network order)
+  const error = Iphlpapi.GetBestRoute2(null, 0, null, destinationBuffer.ptr, 0, bestRouteBuffer.ptr, bestSourceBuffer.ptr);
+  if (error !== 0) throw new Win32Error(error);
+  return {
+    destination: ipv4FromU32(destination),
+    sourceAddress: decodeSockaddr(bestSourceBuffer, 0).address,
+    nextHop: decodeSockaddr(bestRouteBuffer, ROW2_NEXT_HOP).address,
+    interfaceIndex: bestRouteBuffer.readUInt32LE(ROW2_INTERFACE_INDEX),
+    metric: bestRouteBuffer.readUInt32LE(ROW2_METRIC),
+  };
+}
+
+/**
+ * Path-MTU discovery by binary-searching a Don't-Fragment ICMP payload: a hop
+ * that must fragment replies IP_PACKET_TOO_BIG, a DF black-hole simply times out
+ * — both shrink the upper bound, so the largest payload that round-trips is the
+ * path MTU (payload + 28-byte IP+ICMP headers). No raw socket, no admin.
+ */
+export function pathMtu(host: string, options: { timeoutMs?: number } = {}): PathMtuResult {
+  const destination = resolveIPv4(host);
+  const timeoutMs = options.timeoutMs ?? 1500;
+  let low = 0;
+  let high = 1472; // 1500 MTU − 28 header
+  let largestWorking = -1;
+  while (low <= high) {
+    const payload = (low + high) >> 1;
+    const echo = sendEcho(destination, 128, timeoutMs, payload, IP_FLAG_DF);
+    if (echo.replied && echo.status === ICMP_SUCCESS) {
+      largestWorking = payload;
+      low = payload + 1;
+    } else if (echo.replied && echo.status === ICMP_PACKET_TOO_BIG) {
+      high = payload - 1;
+    } else {
+      high = payload - 1; // timeout / DF black-hole → treat as too big (conservative)
+    }
+  }
+  return largestWorking < 0 ? { mtu: 0, determined: false } : { mtu: largestWorking + 28, determined: true };
+}

package/index.ts

@@ -0,0 +1,13 @@
+export * from './adapters';
+export * from './addr';
+export * from './arp';
+export * from './constants';
+export * from './dns';
+export * from './extras';
+export * from './ping';
+export * from './routes';
+export * from './sockets';
+export * from './stats';
+export * from './traceroute';
+export * from './wifi';
+export * from './win32';

package/package.json

@@ -0,0 +1,85 @@
+{
+  "author": "Stev Peifer <stev.p@outlook.com>",
+  "bugs": {
+    "url": "https://github.com/ObscuritySRL/bun-win32/issues"
+  },
+  "dependencies": {
+    "@bun-win32/core": "1.1.4",
+    "@bun-win32/dnsapi": "1.0.2",
+    "@bun-win32/iphlpapi": "1.0.5",
+    "@bun-win32/kernel32": "1.0.26",
+    "@bun-win32/wlanapi": "1.0.4",
+    "@bun-win32/ws2_32": "1.0.6"
+  },
+  "description": "Syscall-grade network diagnostics for Bun on Windows — routing table, socket→PID map, no-admin ICMP ping/traceroute, ARP, DNS, live throughput, and WiFi — decoded from binary structs, zero native dependencies, no netsh/ping.exe/wmic scraping.",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "license": "MIT",
+  "module": "index.ts",
+  "name": "@bun-win32/netdiag",
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/ObscuritySRL/bun-win32#readme",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/ObscuritySRL/bun-win32.git",
+    "directory": "packages/netdiag"
+  },
+  "type": "module",
+  "version": "1.0.0",
+  "main": "./index.ts",
+  "keywords": [
+    "bun",
+    "ffi",
+    "win32",
+    "windows",
+    "network",
+    "netstat",
+    "ping",
+    "traceroute",
+    "dns",
+    "wifi",
+    "arp",
+    "routing",
+    "diagnostics",
+    "typescript"
+  ],
+  "files": [
+    "AI.md",
+    "README.md",
+    "adapters.ts",
+    "addr.ts",
+    "arp.ts",
+    "constants.ts",
+    "dns.ts",
+    "extras.ts",
+    "index.ts",
+    "ping.ts",
+    "routes.ts",
+    "sockets.ts",
+    "stats.ts",
+    "traceroute.ts",
+    "wifi.ts",
+    "win32.ts"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "example:net-report": "bun ./example/net-report.ts",
+    "example:netwatch": "bun ./example/netwatch.ts",
+    "example:ping": "bun ./example/ping.ts",
+    "example:selftest": "bun ./example/netdiag.selftest.ts",
+    "example:wifi-scan": "bun ./example/wifi-scan.ts"
+  }
+}

package/ping.ts

@@ -0,0 +1,193 @@
+import { type Pointer, toArrayBuffer } from 'bun:ffi';
+
+import { ipv4FromU32 } from './addr';
+import { ICMP_REQUEST_TIMED_OUT, ICMP_SUCCESS, icmpStatusName } from './constants';
+import { Iphlpapi, Kernel32, Ws2_32 } from './win32';
+
+const AF_INET = 0x0000_0002;
+const ADDRINFO_SIZE = 48; // ADDRINFOA (x64)
+const ADDRINFO_FAMILY = 4;
+const ADDRINFO_ADDR = 32; // ai_addr (sockaddr*)
+const ADDRINFO_NEXT = 40;
+
+export interface PingReply {
+  alive: boolean;
+  address: string;
+  roundTripMs: number;
+  ttl: number;
+  status: number;
+  statusText: string;
+  bytes: number;
+}
+
+export interface PingOptions {
+  timeoutMs?: number;
+  payloadSize?: number;
+  ttl?: number;
+}
+
+export interface EchoResult {
+  replied: boolean;
+  address: string;
+  roundTripMs: number;
+  ttl: number;
+  status: number;
+  bytes: number;
+}
+
+let winsockReady = false;
+function ensureWinsock(): void {
+  if (winsockReady) return;
+  Ws2_32.WSAStartup(0x0202, Buffer.allocUnsafeSlow(0x0198).ptr); // WSADATA 408 bytes
+  winsockReady = true;
+}
+
+/** Resolve a host (name or IPv4 literal) to a network-order IPv4 u32 via the system resolver (ANSI getaddrinfo). Throws on failure. */
+export function resolveIPv4(host: string): number {
+  ensureWinsock();
+  const resultPointer = Buffer.allocUnsafeSlow(8);
+  const nameBuffer = Buffer.allocUnsafeSlow(host.length + 1); // own buffer; getaddrinfo is the ANSI (LPCSTR) variant
+  nameBuffer.write(host, 'latin1');
+  nameBuffer[host.length] = 0;
+  const error = Ws2_32.getaddrinfo(nameBuffer.ptr, null, null, resultPointer.ptr);
+  if (error !== 0) throw new Error(`cannot resolve "${host}": getaddrinfo failed (${error})`);
+  const head = Number(resultPointer.readBigUInt64LE(0));
+  try {
+    let nodePointer = head;
+    while (nodePointer !== 0) {
+      const node = Buffer.from(toArrayBuffer(Number(nodePointer) as Pointer, 0, ADDRINFO_SIZE));
+      const addressPointer = Number(node.readBigUInt64LE(ADDRINFO_ADDR));
+      if (node.readInt32LE(ADDRINFO_FAMILY) === AF_INET && addressPointer !== 0) {
+        return Buffer.from(toArrayBuffer(Number(addressPointer) as Pointer, 0, 16)).readUInt32LE(4); // sockaddr_in.sin_addr
+      }
+      nodePointer = Number(node.readBigUInt64LE(ADDRINFO_NEXT));
+    }
+  } finally {
+    Ws2_32.freeaddrinfo(Number(head) as Pointer);
+  }
+  throw new Error(`no IPv4 address found for "${host}"`);
+}
+
+let icmpHandle = 0n;
+function handle(): bigint {
+  if (icmpHandle === 0n) icmpHandle = Iphlpapi.IcmpCreateFile();
+  return icmpHandle;
+}
+
+const requestData = Buffer.allocUnsafeSlow(0x0001_0000); // up to 64K payload (own, stable)
+requestData.fill(0x61);
+const replyBuffer = Buffer.allocUnsafeSlow(0x0002_0000); // 128K (own, stable)
+const replyView = new DataView(replyBuffer.buffer, replyBuffer.byteOffset, replyBuffer.byteLength);
+const optionsBuffer = Buffer.allocUnsafeSlow(8); // IP_OPTION_INFORMATION32 (x64): Ttl,Tos,Flags,OptionsSize, OptionsData u32
+
+/**
+ * One synchronous ICMP echo. ttl > 0 builds an IP_OPTION_INFORMATION32 (the
+ * REQUIRED x64 layout — the 64-bit struct returns ERROR_INVALID_PARAMETER) for
+ * traceroute/PMTU; ttl <= 0 sends with the OS default TTL and no options. The
+ * options struct is assembled immediately before the call with no await between.
+ */
+export function sendEcho(destination: number, ttl: number, timeoutMs: number, payloadSize: number, flags = 0): EchoResult {
+  let optionsPointer: Pointer | null = null;
+  if (ttl > 0 || flags !== 0) {
+    optionsBuffer.writeUInt8(ttl > 0 ? ttl : 128, 0);
+    optionsBuffer.writeUInt8(0, 1); // Tos
+    optionsBuffer.writeUInt8(flags, 2); // Flags (IP_FLAG_DF = 0x02 for path-MTU)
+    optionsBuffer.writeUInt8(0, 3); // OptionsSize
+    optionsBuffer.writeUInt32LE(0, 4); // OptionsData = NULL
+    optionsPointer = optionsBuffer.ptr;
+  }
+  const size = payloadSize < 0 ? 0 : payloadSize > 0xffff ? 0xffff : payloadSize; // RequestSize is a WORD
+  const replies = Iphlpapi.IcmpSendEcho(handle(), destination, requestData.ptr, size, optionsPointer, replyBuffer.ptr, replyBuffer.byteLength, timeoutMs);
+  if (replies === 0) {
+    // 0 replies = no echo arrived. GetLastError carries the IP_STATUS, but Bun's FFI does not
+    // reliably preserve it across the boundary → default to "timed out" (the dominant cause).
+    const lastError = Kernel32.GetLastError();
+    return { replied: false, address: '', roundTripMs: 0, ttl: 0, status: lastError === 0 ? ICMP_REQUEST_TIMED_OUT : lastError, bytes: 0 };
+  }
+  // ICMP_ECHO_REPLY (x64): Address@0 Status@4 RoundTripTime@8 DataSize@12 Reserved@14 Data@16 Options{Ttl@24}
+  return {
+    replied: true,
+    address: ipv4FromU32(replyView.getUint32(0, true)),
+    status: replyView.getUint32(4, true),
+    roundTripMs: replyView.getUint32(8, true),
+    bytes: replyView.getUint16(12, true),
+    ttl: replyBuffer.readUInt8(24),
+  };
+}
+
+/** No-admin ICMP ping over IcmpSendEcho — no ping.exe spawn, no locale parse, no CMD flash. */
+export async function ping(host: string, options: PingOptions = {}): Promise<PingReply> {
+  const destination = resolveIPv4(host);
+  const echo = sendEcho(destination, options.ttl ?? 0, options.timeoutMs ?? 1000, options.payloadSize ?? 32);
+  return {
+    alive: echo.replied && echo.status === ICMP_SUCCESS,
+    address: echo.replied ? echo.address : ipv4FromU32(destination),
+    roundTripMs: echo.roundTripMs,
+    ttl: echo.ttl,
+    status: echo.status,
+    statusText: icmpStatusName(echo.status),
+    bytes: echo.bytes,
+  };
+}
+
+/** Ping several hosts — no N-process fork (the async /24 sweep, pingSweep, adds true concurrency over IcmpSendEcho2). */
+export function pingMany(hosts: string[], options: PingOptions = {}): Promise<PingReply[]> {
+  return Promise.all(hosts.map((host) => ping(host, options)));
+}
+
+export interface SweepReply {
+  address: string;
+  alive: boolean;
+  roundTripMs: number;
+}
+
+const sweepRequest = Buffer.allocUnsafeSlow(32);
+sweepRequest.fill(0x61);
+
+/**
+ * Async /24 subnet sweep: fan out IcmpSendEcho2 with a Win32 Event per host (NOT
+ * the ApcRoutine — that fires on a foreign alertable thread, a JSCallback crash
+ * class), then collect. Wall time ≈ one timeout, not N×timeout — the thing
+ * scrapers can't do without forking N processes. `prefix` is a /24 base.
+ */
+export async function pingSweep(prefix: string, options: { timeoutMs?: number } = {}): Promise<SweepReply[]> {
+  const timeoutMs = options.timeoutMs ?? 1000;
+  const octets = prefix
+    .replace(/\/\d+$/, '')
+    .split('.')
+    .map(Number); // accepts '192.168.0', '192.168.0.0', '192.168.0.0/24'
+  if (octets.length < 3 || octets.slice(0, 3).some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+    throw new Error(`pingSweep prefix must be a /24 base like '192.168.0' (got "${prefix}")`);
+  }
+  const prefixWord = (octets[0] | (octets[1] << 8) | (octets[2] << 16)) >>> 0;
+  const icmpHandle = handle();
+
+  const addresses: string[] = [];
+  const events: bigint[] = [];
+  const replyBuffers: Buffer[] = [];
+  for (let host = 1; host <= 254; host++) {
+    const destination = (prefixWord | (host << 24)) >>> 0;
+    const event = Kernel32.CreateEventW(null, 1, 0, null); // manual-reset, non-signaled
+    const reply = Buffer.allocUnsafeSlow(256);
+    addresses.push(`${octets[0]}.${octets[1]}.${octets[2]}.${host}`);
+    events.push(event);
+    replyBuffers.push(reply);
+    Iphlpapi.IcmpSendEcho2(icmpHandle, event, null, null, destination, sweepRequest.ptr, 32, null, reply.ptr, reply.byteLength, timeoutMs); // ERROR_IO_PENDING
+  }
+
+  await Bun.sleep(timeoutMs + 250); // all events signal by completion/timeout
+
+  const result: SweepReply[] = [];
+  for (let index = 0; index < addresses.length; index++) {
+    let alive = false;
+    let roundTripMs = 0;
+    if (Kernel32.WaitForSingleObject(events[index], 0) === 0 && Iphlpapi.IcmpParseReplies(replyBuffers[index].ptr, replyBuffers[index].byteLength) > 0) {
+      const view = new DataView(replyBuffers[index].buffer, replyBuffers[index].byteOffset, replyBuffers[index].byteLength);
+      alive = view.getUint32(4, true) === ICMP_SUCCESS;
+      roundTripMs = view.getUint32(8, true);
+    }
+    result.push({ address: addresses[index], alive, roundTripMs });
+    Kernel32.CloseHandle(events[index]);
+  }
+  return result;
+}

package/routes.ts

@@ -0,0 +1,80 @@
+import { decodeSockaddr } from './addr';
+import { addressFamilyValue, type AddressFamilyName } from './constants';
+import { Iphlpapi, mibTable } from './win32';
+
+// MIB_IPFORWARD_TABLE2 { ULONG NumEntries; MIB_IPFORWARD_ROW2 Table[] } — rows 8-aligned.
+const TABLE_FIRST_ROW = 8;
+// MIB_IPFORWARD_ROW2 (x64, netioapi.h) — stride verified end-to-end vs `route print` (S4.3).
+const ROW_SIZE = 104;
+const ROW_INTERFACE_INDEX = 8;
+const ROW_DESTINATION_PREFIX = 12; // IP_ADDRESS_PREFIX.Prefix (SOCKADDR_INET)
+const ROW_PREFIX_LENGTH = 40; // IP_ADDRESS_PREFIX.PrefixLength (UINT8)
+const ROW_NEXT_HOP = 44; // SOCKADDR_INET
+const ROW_METRIC = 84;
+const ROW_PROTOCOL = 88;
+const ROW_LOOPBACK = 92;
+const ROW_ORIGIN = 100;
+
+const ROUTE_PROTOCOL_NAMES: ReadonlyMap<number, string> = new Map([
+  [1, 'other'],
+  [2, 'local'],
+  [3, 'static'],
+  [4, 'icmp'],
+  [10, 'rip'],
+  [13, 'ospf'],
+  [14, 'bgp'],
+]);
+
+const ROUTE_ORIGIN_NAMES: ReadonlyMap<number, string> = new Map([
+  [0, 'manual'],
+  [1, 'well-known'],
+  [2, 'dhcp'],
+  [3, 'router-advertisement'],
+  [4, '6to4'],
+]);
+
+export interface Route {
+  destinationPrefix: { address: string; length: number };
+  nextHop: string;
+  interfaceIndex: number;
+  metric: number;
+  protocol: string;
+  loopback: boolean;
+  origin: string;
+  family: 'ipv4' | 'ipv6' | 'unknown';
+}
+
+/** The IPv4 + IPv6 routing table over GetIpForwardTable2 (replaces the wmic-dependent default-gateway). */
+export function routes(family: AddressFamilyName = 'all'): Route[] {
+  const familyValue = addressFamilyValue(family);
+  return mibTable(
+    (tablePointer) => Iphlpapi.GetIpForwardTable2(familyValue, tablePointer),
+    TABLE_FIRST_ROW,
+    ROW_SIZE,
+    (table, row) => {
+      const prefix = decodeSockaddr(table, row + ROW_DESTINATION_PREFIX);
+      const nextHop = decodeSockaddr(table, row + ROW_NEXT_HOP);
+      return {
+        destinationPrefix: { address: prefix.address, length: table.readUInt8(row + ROW_PREFIX_LENGTH) },
+        nextHop: nextHop.address,
+        interfaceIndex: table.readUInt32LE(row + ROW_INTERFACE_INDEX),
+        metric: table.readUInt32LE(row + ROW_METRIC),
+        protocol: ROUTE_PROTOCOL_NAMES.get(table.readUInt32LE(row + ROW_PROTOCOL)) ?? 'other',
+        loopback: table.readUInt8(row + ROW_LOOPBACK) !== 0,
+        origin: ROUTE_ORIGIN_NAMES.get(table.readUInt32LE(row + ROW_ORIGIN)) ?? 'unknown',
+        family: prefix.family,
+      };
+    },
+  );
+}
+
+/** The next hop of the lowest-metric default route (0.0.0.0/0 or ::/0) — the locale-proof default-gateway replacement. */
+export function defaultGateway(family: AddressFamilyName = 'ipv4'): string | undefined {
+  let best: Route | undefined;
+  for (const route of routes(family)) {
+    if (route.destinationPrefix.length !== 0) continue;
+    if (route.nextHop === '' || route.nextHop === '0.0.0.0' || route.nextHop === '::') continue;
+    if (best === undefined || route.metric < best.metric) best = route;
+  }
+  return best?.nextHop;
+}