Sync API Reference (Legacy)

Relevant source files

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

• src/index.ts
• src/types.ts
• CLAUDE.md
• test/basic.test.ts
• test/setInterfaceMAC.test.ts
• test/findInterfaces.test.ts

The Sync API represents the original synchronous execution model of the spoof library. While these functions remain available for backward compatibility, they are considered legacy and have been largely superseded by the Async API. The primary purpose of this module is to provide blocking methods for discovering network interfaces and modifying MAC addresses across macOS and Linux platforms.

On the Windows platform, synchronous MAC modification is explicitly unsupported, and users are required to utilize the async variants. Synchronous functions in this module trigger deprecation warnings upon execution to encourage migration to the modern asynchronous equivalents.

Sources: src/index.ts:18-30, src/index.ts:602-607, CLAUDE.md:65-68

Core Synchronous Functions

The Sync API is built around three primary operations: listing all available interfaces, finding a specific interface by name, and applying a new MAC address.

Interface Discovery

Interface discovery relies on executing system-specific commands (such as networksetup on macOS or ip/ifconfig on Linux) and parsing the resulting string output synchronously.

Function	Parameter	Returns	Description
findInterfaces()	targets?: string[]	NetworkInterface[]	Scans the system for network hardware and returns an array of interface objects.
findInterface()	target: string	NetworkInterface | undefined	Helper that returns the first match for a specific device or port name.

Sources: src/index.ts:109-111, src/index.ts:401-404, src/types.ts

MAC Address Modification

The setInterfaceMAC function handles the platform-specific logic required to change a hardware address. On macOS, this includes optional logic to power-cycle Wi-Fi cards to ensure the change takes effect.

Data Structures and Types

The Sync API utilizes the same core types as the modern library to represent network hardware state.

NetworkInterface

This interface describes the state of a network adapter as captured during a discovery scan.

Field	Type	Description
port	string	Human-readable name (e.g., "Wi-Fi", "Ethernet").
device	string	OS-level identifier (e.g., "en0", "eth0").
address	string | null	The permanent hardware (burned-in) MAC address.
currentAddress	string | null	The MAC address currently active on the interface.

Sources: src/types.ts, src/index.ts:133-138

Platform Specific Logic

The synchronous implementation varies significantly based on the host operating system, using child_process.execSync to perform blocking I/O.

macOS (Darwin) Implementation

Discovery on macOS parses the output of networksetup -listallhardwareports. This provides a mapping between the "Hardware Port" name and the "Device" identifier.
Sources: src/index.ts:113-119, test/findInterfaces.test.ts:50-55

Linux Implementation

Linux discovery defaults to the modern ip link show command if available. If the ip utility is missing or if setPreferIfconfig(true) has been called, it falls back to parsing ifconfig.

Deprecation Mechanism

To manage the transition to the Async API, the library maintains a internal deprecationWarnings Set. When a synchronous function is called, it triggers warnDeprecated(), which logs a console warning exactly once per function name to prevent log spamming during repeated calls.

function warnDeprecated(fnName: string): void {
  if (!deprecationWarnings.has(fnName)) {
    deprecationWarnings.add(fnName)
    console.warn(`[DEPRECATION WARNING] ${fnName}() is deprecated...`)
  }
}

Sources: src/index.ts:22-30, src/index.ts:602-616

Summary

The Sync API Reference (Legacy) provides a robust but deprecated set of tools for MAC address management. It serves as the foundation for the project's original functionality, supporting complex platform-specific workflows like macOS Wi-Fi power cycling and Linux tool detection. Developers are advised to use these functions only in legacy environments where asynchronous execution is not feasible.

Sources: CLAUDE.md:65-68, src/index.ts:602-620