Shared Type Definitions

Relevant source files

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

• src/types.ts
• src/index.ts
• src/cli.ts
• CLAUDE.md
• package.json

Introduction

The "Shared Type Definitions" in the spoof project provide a unified structure for describing network hardware, operational configurations, and platform-specific logic. By centralizing these definitions, the project ensures consistency between the core library (src/index.ts) and the command-line interface (src/cli.ts).

These types facilitate the discovery of network interfaces across different operating systems (macOS, Linux, and Windows) and define the interfaces for asynchronous control flows, such as timeouts and cancellation signals.

Sources: src/types.ts:1-36, CLAUDE.md:71-71

Core Data Structures

NetworkInterface

The primary entity within the system is the NetworkInterface. It encapsulates both the physical attributes of a network adapter and its current state.

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, primarily used on Windows.

Sources: src/types.ts:6-20

AsyncOptions

To support robust asynchronous operations, the project defines AsyncOptions. This structure allows the library to handle long-running system commands with standardized timeout logic and abort capabilities.

Option	Type	Default	Description
timeout	number	30000 (ms)	Maximum duration for an operation.
signal	AbortSignal	undefined	Standard Web API signal for operation cancellation.

Sources: src/types.ts:31-36, src/index.ts:14-14

Functional Type Definitions

RandomFunction

The RandomFunction type defines a signature for generating integers within a specific range. While the project uses a cryptographically secure implementation by default, this type allows for the injection of custom logic (e.g., for deterministic testing).

export type RandomFunction = (min: number, max: number) => number

Sources: src/types.ts:26-26, src/index.ts:509-524

Platform

The Platform type restricts the valid environment identifiers supported by the tool.

Value	OS Representation
'darwin'	macOS
'linux'	Linux Distributions
'win32'	Windows

Sources: src/types.ts:21-21, src/index.ts:74-74

CLI Specific Types

The CLI module utilizes specialized interfaces to handle argument parsing and internal operation reporting.

ParsedArgs

Defines the structure of arguments processed by the minimist library, including global flags and command-specific strings.

OperationResult

Used to report the outcome of MAC modification attempts, particularly for the set, randomize, and reset commands.

Field	Type	Description
device	string	The device identifier targeted.
success	boolean	Whether the operation was successful.
error	string	Detailed error message if success is false.
newAddress	string	The MAC address assigned during the operation.

Sources: src/cli.ts:32-39

Summary

The Shared Type Definitions serve as the architectural contract for the spoof project. By defining clear interfaces for network data, platform identifiers, and execution options, the system maintains high technical accuracy across different operating systems. These definitions support the library's core mission of abstracting complex platform-specific CLI utilities (like ifconfig, ip link, or netsh) into a simple, typed API.

Sources: src/index.ts:89-105, CLAUDE.md:71-74