Async API Reference (Primary)

Relevant source files

The following files were used as context for generating this wiki page:

• src/index.ts
• src/types.ts
• src/cli.ts
• CLAUDE.md
• test/setInterfaceMAC.test.ts

Introduction

The Async API is the primary interface for the spoof library, providing non-blocking methods to interact with network interfaces across macOS (Darwin), Linux, and Windows (win32). It was introduced to replace the legacy synchronous API, which is now deprecated. The Async API leverages Node.js promisify to wrap child process executions, enabling better handling of timeouts and cancellation via AbortSignal.

This API serves as the core engine for the spoof CLI tool, handling complex platform-specific operations such as Wi-Fi power cycling on macOS and registry modifications on Windows.

Sources: src/index.ts:1-25, src/index.ts:476-485, CLAUDE.md:46-52

---

Core Data Structures

The Async API utilizes standardized types to ensure cross-platform consistency when describing network hardware.

NetworkInterface

The NetworkInterface interface represents the state and identity of a physical or virtual network adapter.

Field	Type	Description
port	string	The hardware name (e.g., "Wi-Fi", "Ethernet").
device	string	The system identifier (e.g., "en0", "eth0").
address	string | null	The permanent hardware MAC address.
currentAddress	string | null	The currently active (possibly spoofed) MAC address.
description	string	Optional adapter description (Windows only).

Sources: src/types.ts:6-19

AsyncOptions

All primary async functions accept an optional AsyncOptions object to control execution flow.

Option	Type	Default	Description
timeout	number	30000	Operation timeout in milliseconds.
signal	AbortSignal	undefined	Used to cancel the pending operation.

Sources: src/types.ts:31-37, src/index.ts:13

---

Interface Discovery API

These methods allow for querying the system's network adapters in a non-blocking manner.

findInterfacesAsync()

Retrieves a list of all network interfaces on the machine. It branches into platform-specific logic (findInterfacesDarwinAsync, findInterfacesLinuxAsync, or findInterfacesWin32Async) to parse system command outputs.

getInterfaceMACAsync()

Returns the currently active MAC address for a specific device.

Platform	Command Used
macOS	ifconfig <device>
Linux	ip link show <device> (falls back to ifconfig)
Windows	getmac /v /fo csv

Sources: src/index.ts:747-768, test/setInterfaceMAC.test.ts:495-502

---

MAC Modification API

setInterfaceMACAsync()

This is the central function for spoofing addresses. It validates inputs against DEVICE_NAME_RE and MAC_VALIDATION_RE before proceeding with platform-specific implementation.

Logic Flow by Platform

• macOS (Darwin): If the port is "Wi-Fi", it uses networksetup to power cycle the device off and on before and after the ifconfig <device> ether <mac> command to ensure the change takes effect.
• Linux: Defaults to the ip command sequence (down -> address -> up). If preferIfconfig is set or ip is missing, it uses ifconfig <device> down hw ether <mac> followed by up.
• Windows (win32): Modifies the Windows Registry and restarts the adapter using netsh.

---

Windows Implementation Details

Unlike Unix-based systems where MAC changes are handled via standard network utilities, Windows requires direct manipulation of the registry. The API searches the path:
\SYSTEM\CurrentControlSet\Control\Class\{4D36E972-E325-11CE-BFC1-08002BE10318}

It iterates through subkeys to find a match for the device name (checking fields like NetConnectionID, DriverDesc, or AdapterModel) before setting the NetworkAddress value.

Sources: src/index.ts:33-34, src/index.ts:896-912, src/index.ts:930-940

---

Conclusion

The Async API Reference (Primary) defines a robust, promise-based framework for network identity management. By abstracting away the significant differences between networksetup, iproute2, and winreg, it provides developers with a consistent interface for discovering adapters and programmatically altering MAC addresses while maintaining support for modern Node.js features like timeouts and cancellation.

Sources: src/index.ts:488-500, CLAUDE.md:46-49