Platform Detection & Routing

Relevant source files

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

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

The Platform Detection & Routing system in spoof is responsible for identifying the host operating system and delegating network interface operations to the appropriate platform-specific implementation. This abstraction allows the core API and CLI to remain platform-agnostic while handling the vastly different underlying commands and system utilities required for MAC address manipulation on macOS, Linux, and Windows.

Sources: src/index.ts:109-119, CLAUDE.md:76-80

Architecture Overview

The system utilizes process.platform to branch logic at the entry points of major functions. The core routing occurs within high-level API functions such as findInterfacesAsync(), findInterfaceAsync(), and setInterfaceMACAsync().

The diagram above illustrates the routing flow from public API calls to specific platform implementations and their underlying system utilities.
Sources: src/index.ts:446-455, src/index.ts:718-732

Platform Implementations

macOS (Darwin)

On macOS, the system primarily relies on the networksetup utility for identifying hardware ports and the ifconfig command for reading or modifying MAC addresses. For Wi-Fi interfaces, it performs additional "power cycling" steps using networksetup -setairportpower to ensure changes take effect.

Utility	Purpose	Context
networksetup	List all hardware ports and toggle Wi-Fi power	findInterfacesDarwinAsync, setInterfaceMACAsync
ifconfig	Read and set the active MAC address	getInterfaceMACAsync, setInterfaceMACAsync

Sources: src/index.ts:457-463, src/index.ts:734-754

Linux

Linux routing includes an additional sub-layer to handle the presence of modern iproute2 (ip command) versus legacy net-tools (ifconfig). By default, the system checks for the ip command but allows users to force the legacy behavior via configuration.

• Sub-Routing Logic:
  • Checks if ip command is available using which ip.
  • Respects the preferIfconfig internal flag, which can be toggled via setPreferIfconfig().
  • Delegates to either findInterfacesLinuxIpAsync or findInterfacesLinuxIfconfigAsync.

Sources: src/index.ts:60-84, src/index.ts:503-509

Windows (Win32)

The Windows implementation is the most complex, involving interaction with the Windows Registry and shell commands. It uses ipconfig /all for discovery, getmac for verification, and the winreg library to modify values in the HKLM registry hive.

The sequence diagram shows the unique requirement on Windows to disable and re-enable the adapter via netsh after registry modification.
Sources: src/index.ts:861-897, src/index.ts:919-943

Key Data Structures

The routing system standardizes output into a common NetworkInterface type, regardless of the platform-specific data source.

export interface NetworkInterface {
  port: string           // e.g., "Wi-Fi", "Ethernet"
  device: string         // e.g., "en0", "eth0"
  address: string | null // Hardware MAC
  currentAddress: string | null // Active MAC
  description?: string   // Windows-specific adapter info
}

Sources: src/types.ts:9-21

CLI Routing and Configuration

The CLI entry point in src/cli.ts acts as the primary consumer of the routing logic. It handles global flags that influence how routing behaves, particularly for Linux systems.

Flag	Impact on Routing	Source File
--prefer-ifconfig	Forces the Linux implementation to bypass ip and use ifconfig.	src/cli.ts:70-72
--wifi	Instructs the platform-specific discovery to filter for wireless ports.	src/cli.ts:427-431
--timeout	Sets the AsyncOptions passed to platform-specific command executors.	src/cli.ts:59

Sources: src/cli.ts:39-72, src/index.ts:31-34

Conclusion

Platform Detection & Routing ensures that spoof remains a versatile tool across different environments. By encapsulating platform-specific quirks—such as macOS Wi-Fi power cycles, Linux tool versioning, and Windows Registry requirements—the system provides a unified interface for developers and end-users. This modular approach allows for the safe addition of new platform support or the updating of existing utilities without impacting the core CLI or library logic.

Sources: CLAUDE.md:75-80, src/index.ts:110-119