@bun-win32/netdiag 1.0.0

package/wifi.ts

@@ -0,0 +1,363 @@
+import { type Pointer, toArrayBuffer } from 'bun:ffi';
+
+import { macFromBytes } from './addr';
+import { readWideAt, Win32Error, Wlanapi } from './win32';
+
+const WLAN_API_VERSION_2_0 = 0x0000_0002;
+const WLAN_INTF_OPCODE_CURRENT_CONNECTION = 0x0000_0007;
+const WLAN_CONNECTION_MODE_PROFILE = 0x0000_0000;
+const DOT11_BSS_TYPE_INFRASTRUCTURE = 0x0000_0001;
+const DOT11_BSS_TYPE_ANY = 0x0000_0003;
+const INTERFACE_ENTRY_SIZE = 532; // WLAN_INTERFACE_INFO
+const NETWORK_ENTRY_SIZE = 628; // WLAN_AVAILABLE_NETWORK
+const LIST_HEADER_SIZE = 8; // dwNumberOfItems + dwIndex
+const CONNECTED_FLAG = 0x0000_0001;
+const HAS_PROFILE_FLAG = 0x0000_0002;
+const ERROR_ACCESS_DENIED = 5;
+const SCAN_SETTLE_MS = 4000; // WlanScan may flush the cached list; MSDN-sanctioned settle window
+
+const INTERFACE_STATE_NAMES: ReadonlyMap<number, string> = new Map([
+  [0, 'not-ready'],
+  [1, 'connected'],
+  [2, 'ad-hoc'],
+  [3, 'disconnecting'],
+  [4, 'disconnected'],
+  [5, 'associating'],
+  [6, 'discovering'],
+  [7, 'authenticating'],
+]);
+
+const AUTH_NAMES: ReadonlyMap<number, string> = new Map([
+  [1, 'open'],
+  [2, 'shared-key'],
+  [3, 'wpa'],
+  [4, 'wpa-psk'],
+  [5, 'wpa-none'],
+  [6, 'wpa2'],
+  [7, 'wpa2-psk'],
+  [8, 'wpa3'],
+  [9, 'wpa3-sae'],
+  [10, 'owe'],
+  [11, 'wpa3-enterprise'],
+]);
+
+const CIPHER_NAMES: ReadonlyMap<number, string> = new Map([
+  [0, 'none'],
+  [1, 'wep-40'],
+  [2, 'tkip'],
+  [4, 'ccmp-aes'],
+  [5, 'wep-104'],
+  [6, 'bip'],
+  [8, 'gcmp'],
+  [0x100, 'wpa-use-group'],
+  [0x101, 'wep'],
+]);
+
+const PHY_NAMES: ReadonlyMap<number, string> = new Map([
+  [1, 'fhss'],
+  [2, 'dsss'],
+  [3, 'ir-baseband'],
+  [4, 'ofdm-a'],
+  [5, 'hr-dsss-b'],
+  [6, 'erp-g'],
+  [7, 'ht-n'],
+  [8, 'vht-ac'],
+  [9, 'dmg-ad'],
+  [10, 'he-ax'],
+  [11, 'eht-be'],
+]);
+
+export interface WifiInterface {
+  guid: string;
+  description: string;
+  state: string;
+}
+
+export interface WifiNetwork {
+  ssid: string;
+  bssCount: number;
+  signalQuality: number;
+  secured: boolean;
+  authAlgorithm: string;
+  cipherAlgorithm: string;
+  connectable: boolean;
+  connected: boolean;
+  hasProfile: boolean;
+}
+
+export interface WifiConnection {
+  profileName: string;
+  ssid: string;
+  bssid: string;
+  phyType: string;
+  signalQuality: number;
+  rxRateMbps: number;
+  txRateMbps: number;
+  secured: boolean;
+  authAlgorithm: string;
+  cipherAlgorithm: string;
+}
+
+export interface WifiBss {
+  ssid: string;
+  bssid: string;
+  rssi: number;
+  linkQuality: number;
+  phyType: string;
+  channelFrequencyKhz: number;
+}
+
+export interface WifiScanOptions {
+  triggerScan?: boolean;
+}
+
+export interface WifiConnectOptions {
+  beta: boolean;
+}
+
+export interface WifiConnectResult {
+  ok: boolean;
+  reasonCode: number;
+  reason: string;
+}
+
+interface RawInterface {
+  guid: string;
+  description: string;
+  state: number;
+  pointer: Pointer;
+}
+
+let clientHandle = 0n;
+function handle(): bigint {
+  if (clientHandle === 0n) {
+    const negotiated = Buffer.allocUnsafeSlow(4);
+    const handleBuffer = Buffer.allocUnsafeSlow(8);
+    const status = Wlanapi.WlanOpenHandle(WLAN_API_VERSION_2_0, null, negotiated.ptr, handleBuffer.ptr);
+    if (status !== 0) throw new Win32Error(status);
+    clientHandle = handleBuffer.readBigUInt64LE(0);
+  }
+  return clientHandle;
+}
+
+function formatGuid(buffer: Buffer, offset: number): string {
+  const part1 = buffer.readUInt32LE(offset).toString(16).padStart(8, '0');
+  const part2 = buffer
+    .readUInt16LE(offset + 4)
+    .toString(16)
+    .padStart(4, '0');
+  const part3 = buffer
+    .readUInt16LE(offset + 6)
+    .toString(16)
+    .padStart(4, '0');
+  const part4 = macFromBytes(buffer, offset + 8, 2).replaceAll(':', '');
+  const part5 = macFromBytes(buffer, offset + 10, 6).replaceAll(':', '');
+  return `{${part1}-${part2}-${part3}-${part4}-${part5}}`;
+}
+
+// DOT11_SSID: uLength (ULONG) then ucSSID[32]; SSID bytes are raw UTF-8 (Unicode/emoji-proof — a node-wifi failure mode).
+function readSsid(buffer: Buffer, offset: number): string {
+  const length = buffer.readUInt32LE(offset);
+  return buffer.toString('utf8', offset + 4, offset + 4 + Math.min(length, 32));
+}
+
+// Returns the (caller-must-free) interface list pointer plus decoded entries whose `pointer` doubles as pInterfaceGuid (GUID@0 trick).
+function enumerateInterfaces(): { listPointer: number; interfaces: RawInterface[] } {
+  const listPointerBuffer = Buffer.allocUnsafeSlow(8);
+  if (Wlanapi.WlanEnumInterfaces(handle(), null, listPointerBuffer.ptr) !== 0) return { listPointer: 0, interfaces: [] };
+  const listPointer = Number(listPointerBuffer.readBigUInt64LE(0));
+  if (listPointer === 0) return { listPointer: 0, interfaces: [] };
+  const count = Buffer.from(toArrayBuffer(listPointer as Pointer, 0, LIST_HEADER_SIZE)).readUInt32LE(0);
+  const interfaces: RawInterface[] = [];
+  for (let index = 0; index < count; index++) {
+    const pointer = (listPointer + LIST_HEADER_SIZE + index * INTERFACE_ENTRY_SIZE) as Pointer;
+    const entry = Buffer.from(toArrayBuffer(pointer, 0, INTERFACE_ENTRY_SIZE));
+    interfaces.push({ guid: formatGuid(entry, 0), description: readWideAt(entry, 16), state: entry.readUInt32LE(528), pointer });
+  }
+  return { listPointer, interfaces };
+}
+
+function selectInterface(interfaces: RawInterface[], interfaceGuid?: string): RawInterface | undefined {
+  if (interfaceGuid) return interfaces.find((candidate) => candidate.guid === interfaceGuid);
+  return interfaces.find((candidate) => candidate.state === 1) ?? interfaces[0];
+}
+
+/** Wireless interfaces (empty on Ethernet-only hosts — never throws). */
+export function wifiInterfaces(): WifiInterface[] {
+  const { listPointer, interfaces } = enumerateInterfaces();
+  try {
+    return interfaces.map((candidate) => ({ guid: candidate.guid, description: candidate.description, state: INTERFACE_STATE_NAMES.get(candidate.state) ?? 'unknown' }));
+  } finally {
+    if (listPointer !== 0) Wlanapi.WlanFreeMemory(listPointer as Pointer);
+  }
+}
+
+/**
+ * Visible networks from wlanapi structs — locale-proof, Unicode/emoji-SSID-proof.
+ * `triggerScan` (default false) chooses the OS-cached list (instant) vs a FRESH scan
+ * (WlanScan → ~4 s settle → list; WlanScan may flush the prior list).
+ */
+export async function wifiScan(options: WifiScanOptions = {}): Promise<WifiNetwork[]> {
+  const { listPointer, interfaces } = enumerateInterfaces();
+  const networks: WifiNetwork[] = [];
+  try {
+    for (const iface of interfaces) {
+      if (options.triggerScan) {
+        Wlanapi.WlanScan(handle(), iface.pointer, null, null, null);
+        await Bun.sleep(SCAN_SETTLE_MS);
+      }
+      const networkListBuffer = Buffer.allocUnsafeSlow(8);
+      const status = Wlanapi.WlanGetAvailableNetworkList(handle(), iface.pointer, 0, null, networkListBuffer.ptr);
+      if (status === ERROR_ACCESS_DENIED) throw new Error('WiFi scan denied (ERROR_ACCESS_DENIED) — Windows precise-location consent is required (Settings → Privacy → Location). This is an OS gate, not a netdiag bug.');
+      if (status !== 0) continue;
+      const networkListPointer = Number(networkListBuffer.readBigUInt64LE(0));
+      if (networkListPointer === 0) continue;
+      try {
+        const networkCount = Buffer.from(toArrayBuffer(networkListPointer as Pointer, 0, LIST_HEADER_SIZE)).readUInt32LE(0);
+        for (let index = 0; index < networkCount; index++) {
+          const entry = Buffer.from(toArrayBuffer((networkListPointer + LIST_HEADER_SIZE + index * NETWORK_ENTRY_SIZE) as Pointer, 0, NETWORK_ENTRY_SIZE));
+          const flags = entry.readUInt32LE(620);
+          networks.push({
+            ssid: readSsid(entry, 512),
+            bssCount: entry.readUInt32LE(552),
+            signalQuality: entry.readUInt32LE(604),
+            secured: entry.readInt32LE(608) !== 0,
+            authAlgorithm: AUTH_NAMES.get(entry.readUInt32LE(612)) ?? `auth(${entry.readUInt32LE(612)})`,
+            cipherAlgorithm: CIPHER_NAMES.get(entry.readUInt32LE(616)) ?? `cipher(${entry.readUInt32LE(616)})`,
+            connectable: entry.readInt32LE(556) !== 0,
+            connected: (flags & CONNECTED_FLAG) !== 0,
+            hasProfile: (flags & HAS_PROFILE_FLAG) !== 0,
+          });
+        }
+      } finally {
+        Wlanapi.WlanFreeMemory(networkListPointer as Pointer);
+      }
+    }
+  } finally {
+    if (listPointer !== 0) Wlanapi.WlanFreeMemory(listPointer as Pointer);
+  }
+  return networks;
+}
+
+/** The current connection (signal/rate/BSSID/auth) via WlanQueryInterface — null if not connected / no WiFi. */
+export function wifiConnection(interfaceGuid?: string): WifiConnection | null {
+  const { listPointer, interfaces } = enumerateInterfaces();
+  try {
+    const target = selectInterface(interfaces, interfaceGuid);
+    if (target === undefined) return null;
+    const sizeBuffer = Buffer.allocUnsafeSlow(4);
+    const dataPointerBuffer = Buffer.allocUnsafeSlow(8);
+    if (Wlanapi.WlanQueryInterface(handle(), target.pointer, WLAN_INTF_OPCODE_CURRENT_CONNECTION, null, sizeBuffer.ptr, dataPointerBuffer.ptr, null) !== 0) return null;
+    const dataPointer = Number(dataPointerBuffer.readBigUInt64LE(0));
+    if (dataPointer === 0) return null;
+    try {
+      const attributes = Buffer.from(toArrayBuffer(dataPointer as Pointer, 0, sizeBuffer.readUInt32LE(0)));
+      return {
+        profileName: readWideAt(attributes, 8),
+        ssid: readSsid(attributes, 520),
+        bssid: macFromBytes(attributes, 560, 6),
+        phyType: PHY_NAMES.get(attributes.readUInt32LE(568)) ?? 'unknown',
+        signalQuality: attributes.readUInt32LE(576),
+        rxRateMbps: attributes.readUInt32LE(580) / 1000,
+        txRateMbps: attributes.readUInt32LE(584) / 1000,
+        secured: attributes.readInt32LE(588) !== 0,
+        authAlgorithm: AUTH_NAMES.get(attributes.readUInt32LE(596)) ?? 'unknown',
+        cipherAlgorithm: CIPHER_NAMES.get(attributes.readUInt32LE(600)) ?? 'unknown',
+      };
+    } finally {
+      Wlanapi.WlanFreeMemory(dataPointer as Pointer);
+    }
+  } finally {
+    if (listPointer !== 0) Wlanapi.WlanFreeMemory(listPointer as Pointer);
+  }
+}
+
+// WLAN_BSS_ENTRY (x64) — netdiag authors this decoder; entries are VARIABLE length (advance by ulIeOffset + ulIeSize).
+const BSS_ENTRY_SSID = 0;
+const BSS_ENTRY_BSSID = 40;
+const BSS_ENTRY_PHY_TYPE = 52;
+const BSS_ENTRY_RSSI = 56; // LONG — SIGNED dBm, distinct from the 0–100 signalQuality
+const BSS_ENTRY_LINK_QUALITY = 60;
+const BSS_ENTRY_CHANNEL_FREQUENCY = 92;
+const BSS_ENTRY_IE_OFFSET = 352;
+const BSS_ENTRY_IE_SIZE = 356;
+
+/** Per-BSSID census with signed-dBm RSSI + channel-center frequency via WlanGetNetworkBssList. WLAN_BSS_LIST: dwTotalSize@0, dwNumberOfItems@4. */
+export function wifiBssList(interfaceGuid?: string): WifiBss[] {
+  const { listPointer, interfaces } = enumerateInterfaces();
+  const result: WifiBss[] = [];
+  try {
+    const target = selectInterface(interfaces, interfaceGuid);
+    if (target === undefined) return result;
+    const bssListBuffer = Buffer.allocUnsafeSlow(8);
+    if (Wlanapi.WlanGetNetworkBssList(handle(), target.pointer, null, DOT11_BSS_TYPE_ANY, 0, null, bssListBuffer.ptr) !== 0) return result;
+    const bssListPointer = Number(bssListBuffer.readBigUInt64LE(0));
+    if (bssListPointer === 0) return result;
+    try {
+      const totalSize = Buffer.from(toArrayBuffer(bssListPointer as Pointer, 0, LIST_HEADER_SIZE)).readUInt32LE(0);
+      const blob = Buffer.from(toArrayBuffer(bssListPointer as Pointer, 0, totalSize));
+      const count = blob.readUInt32LE(4);
+      let offset = LIST_HEADER_SIZE;
+      for (let index = 0; index < count && offset + BSS_ENTRY_IE_SIZE + 4 <= totalSize; index++) {
+        result.push({
+          ssid: readSsid(blob, offset + BSS_ENTRY_SSID),
+          bssid: macFromBytes(blob, offset + BSS_ENTRY_BSSID, 6),
+          rssi: blob.readInt32LE(offset + BSS_ENTRY_RSSI),
+          linkQuality: blob.readUInt32LE(offset + BSS_ENTRY_LINK_QUALITY),
+          phyType: PHY_NAMES.get(blob.readUInt32LE(offset + BSS_ENTRY_PHY_TYPE)) ?? 'unknown',
+          channelFrequencyKhz: blob.readUInt32LE(offset + BSS_ENTRY_CHANNEL_FREQUENCY),
+        });
+        offset = (offset + blob.readUInt32LE(offset + BSS_ENTRY_IE_OFFSET) + blob.readUInt32LE(offset + BSS_ENTRY_IE_SIZE) + 7) & ~7; // entries are 8-aligned
+      }
+    } finally {
+      Wlanapi.WlanFreeMemory(bssListPointer as Pointer);
+    }
+  } finally {
+    if (listPointer !== 0) Wlanapi.WlanFreeMemory(listPointer as Pointer);
+  }
+  return result;
+}
+
+function reasonCodeToString(reasonCode: number): string {
+  const buffer = Buffer.allocUnsafeSlow(0x0400);
+  return Wlanapi.WlanReasonCodeToString(reasonCode, 0x0200, buffer.ptr, null) === 0 ? readWideAt(buffer, 0) : `reason code ${reasonCode}`;
+}
+
+/**
+ * BETA — connect to a saved profile via WlanConnect. Signature-correct but
+ * UNEXERCISED against a live AP; pass { beta: true } to acknowledge. Verify the
+ * result by polling wifiConnection(), never by callback.
+ */
+export function wifiConnect(profileName: string, interfaceGuid: string | undefined, options: WifiConnectOptions): WifiConnectResult {
+  if (!options?.beta) throw new Error('wifiConnect is a BETA capability, unexercised against a live AP — pass { beta: true } to acknowledge.');
+  const { listPointer, interfaces } = enumerateInterfaces();
+  try {
+    const target = selectInterface(interfaces, interfaceGuid);
+    if (target === undefined) return { ok: false, reasonCode: 0, reason: 'no WiFi interface' };
+    const profile = Buffer.allocUnsafeSlow((profileName.length + 1) * 2);
+    profile.writeUInt16LE(0, profile.write(profileName, 'utf16le'));
+    const parameters = Buffer.allocUnsafeSlow(40); // WLAN_CONNECTION_PARAMETERS (x64)
+    parameters.fill(0);
+    parameters.writeUInt32LE(WLAN_CONNECTION_MODE_PROFILE, 0);
+    parameters.writeBigUInt64LE(BigInt(Number(profile.ptr)), 8); // strProfile
+    parameters.writeUInt32LE(DOT11_BSS_TYPE_INFRASTRUCTURE, 32);
+    const status = Wlanapi.WlanConnect(handle(), target.pointer, parameters.ptr, null);
+    return { ok: status === 0, reasonCode: status, reason: reasonCodeToString(status) };
+  } finally {
+    if (listPointer !== 0) Wlanapi.WlanFreeMemory(listPointer as Pointer);
+  }
+}
+
+/** BETA — disconnect the interface via WlanDisconnect. Pass { beta: true } to acknowledge. */
+export function wifiDisconnect(interfaceGuid: string | undefined, options: WifiConnectOptions): WifiConnectResult {
+  if (!options?.beta) throw new Error('wifiDisconnect is a BETA capability — pass { beta: true } to acknowledge.');
+  const { listPointer, interfaces } = enumerateInterfaces();
+  try {
+    const target = selectInterface(interfaces, interfaceGuid);
+    if (target === undefined) return { ok: false, reasonCode: 0, reason: 'no WiFi interface' };
+    const status = Wlanapi.WlanDisconnect(handle(), target.pointer, null);
+    return { ok: status === 0, reasonCode: status, reason: reasonCodeToString(status) };
+  } finally {
+    if (listPointer !== 0) Wlanapi.WlanFreeMemory(listPointer as Pointer);
+  }
+}

package/win32.ts

@@ -0,0 +1,144 @@
+import Iphlpapi from '@bun-win32/iphlpapi';
+import { read, toArrayBuffer, type Pointer } from 'bun:ffi';
+
+export { default as Dnsapi } from '@bun-win32/dnsapi';
+export { default as Kernel32 } from '@bun-win32/kernel32';
+export { default as Wlanapi } from '@bun-win32/wlanapi';
+export { default as Ws2_32 } from '@bun-win32/ws2_32';
+export { Iphlpapi };
+
+const ERROR_SUCCESS = 0x0000_0000;
+const ERROR_BUFFER_OVERFLOW = 0x0000_006f; // 111 — Table sizing return
+const ERROR_INSUFFICIENT_BUFFER = 0x0000_007a; // 122 — GetExtended*Table sizing return
+
+const WIN32_ERROR_MESSAGES: ReadonlyMap<number, string> = new Map([
+  [5, 'access denied — this operation requires Administrator'],
+  [50, 'the request is not supported on this system'],
+  [87, 'invalid parameter — likely a malformed request struct or address family'],
+  [232, 'no data is available'],
+  [1168, 'element not found'],
+  [1314, 'a required privilege is not held by the client — this operation requires Administrator'],
+  [1722, 'the RPC server is unavailable'],
+]);
+
+export function win32ErrorMessage(code: number): string {
+  return WIN32_ERROR_MESSAGES.get(code) ?? `Win32 error ${code}`;
+}
+
+export class Win32Error extends Error {
+  readonly code: number;
+  constructor(code: number) {
+    super(`${win32ErrorMessage(code)} (code ${code})`);
+    this.code = code;
+    this.name = 'Win32Error';
+  }
+}
+
+/**
+ * The Win32 sizing-call idiom, encapsulated. Nearly every IP Helper table API is
+ * called twice: once to learn the byte count, once to fill a buffer. This holds
+ * one growable data buffer + one persistent DataView + a stable 4-byte size
+ * buffer, reused across polls — never allocate per sample.
+ *
+ * The data buffer is always > 4096 bytes ⇒ an own (off-heap) ArrayBuffer with a
+ * stable address: pooled small buffers relocate under GC and dangle their `.ptr`
+ * (and the kernel writes absolute in-buffer pointers that a relocation would
+ * invalidate). `.ptr` is read INLINE at each call.
+ */
+export class SizedBufferState {
+  #buffer: Buffer;
+  #view: DataView;
+  readonly #sizeBuffer: Buffer;
+
+  constructor(initialBytes = 0x0000_4000) {
+    this.#buffer = Buffer.allocUnsafe(initialBytes);
+    this.#view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset, this.#buffer.byteLength);
+    this.#sizeBuffer = Buffer.allocUnsafeSlow(4);
+  }
+
+  get buffer(): Buffer {
+    return this.#buffer;
+  }
+
+  get view(): DataView {
+    return this.#view;
+  }
+
+  /**
+   * Invoke with the current buffer; on ERROR_INSUFFICIENT_BUFFER/ERROR_BUFFER_OVERFLOW
+   * grow geometrically-by-need and retry once. `invoke(dataPointer, sizePointer)`
+   * returns a Win32 error code. Returns the (possibly regrown) DataView.
+   */
+  fill(invoke: (dataPointer: Pointer, sizePointer: Pointer) => number): DataView {
+    this.#sizeBuffer.writeUInt32LE(this.#buffer.byteLength, 0);
+    let error = invoke(this.#buffer.ptr, this.#sizeBuffer.ptr);
+    if (error === ERROR_INSUFFICIENT_BUFFER || error === ERROR_BUFFER_OVERFLOW) {
+      const required = this.#sizeBuffer.readUInt32LE(0);
+      if (required > this.#buffer.byteLength) {
+        this.#buffer = Buffer.allocUnsafe(required);
+        this.#view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset, this.#buffer.byteLength);
+      }
+      this.#sizeBuffer.writeUInt32LE(this.#buffer.byteLength, 0);
+      error = invoke(this.#buffer.ptr, this.#sizeBuffer.ptr); // re-read .ptr: the buffer may have moved
+    }
+    if (error !== ERROR_SUCCESS) throw new Win32Error(error);
+    return this.#view;
+  }
+}
+
+/**
+ * Walk an in-buffer singly-linked list (the GetAdaptersAddresses shape): every
+ * node lives inside one stable buffer, chained by an absolute `Next` pointer at
+ * `nextOffset`. Yields each node's byte offset within `base`. `headPointer` is
+ * the absolute address of the first node (0 ⇒ empty list); for a top-level list
+ * whose first node sits at the buffer start pass `Number(base.ptr)`.
+ */
+export function* walkList(base: Buffer, headPointer: number, nextOffset: number): Generator<number> {
+  const baseAddress = Number(base.ptr);
+  let pointer = headPointer;
+  while (pointer !== 0) {
+    const offset = pointer - baseAddress;
+    yield offset;
+    pointer = Number(base.readBigUInt64LE(offset + nextOffset));
+  }
+}
+
+/** ASCII string from `offset` up to NUL (or buffer end). Negative offset ⇒ ''. */
+export function readAnsiAt(base: Buffer, offset: number): string {
+  if (offset < 0) return '';
+  const end = base.indexOf(0, offset);
+  return base.toString('ascii', offset, end < 0 ? base.byteLength : end);
+}
+
+/** UTF-16LE string from `offset` up to the NUL terminator. Negative offset ⇒ '' (repo memory: Bun's TextDecoder rejects 'utf-16le'; use Buffer). */
+export function readWideAt(base: Buffer, offset: number): string {
+  if (offset < 0) return '';
+  let end = offset;
+  while (end + 1 < base.byteLength && base.readUInt16LE(end) !== 0) end += 2;
+  return base.toString('utf16le', offset, end);
+}
+
+const mibTableOut = Buffer.allocUnsafeSlow(8);
+
+/**
+ * Decode a self-allocating Table2 API (GetIpForwardTable2 / GetIpNetTable2): the
+ * API allocates the table and writes its pointer into the out buffer; we read
+ * NumEntries, wrap the row region in ONE Buffer over native memory, decode each
+ * row, and ALWAYS FreeMibTable in `finally` (or leak native memory every poll).
+ * `invoke(tablePointer)` receives the reused 8-byte out buffer pointer and
+ * returns a Win32 error code.
+ */
+export function mibTable<T>(invoke: (tablePointer: Pointer) => number, firstRowOffset: number, rowSize: number, decodeRow: (table: Buffer, rowOffset: number) => T): T[] {
+  const error = invoke(mibTableOut.ptr);
+  if (error !== ERROR_SUCCESS) throw new Win32Error(error);
+  const tablePointer = Number(mibTableOut.readBigUInt64LE(0)) as Pointer;
+  try {
+    const numEntries = read.u32(tablePointer, 0);
+    const table = Buffer.from(toArrayBuffer(tablePointer, 0, firstRowOffset + numEntries * rowSize));
+    const rows: T[] = new Array(numEntries);
+    for (let index = 0; index < numEntries; index++) rows[index] = decodeRow(table, firstRowOffset + index * rowSize);
+    return rows;
+  } finally {
+    Iphlpapi.FreeMibTable(tablePointer);
+  }
+}