spoof-d 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) Feross Aboukhadijeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# spoof-d
+
+[![npm version](https://img.shields.io/npm/v/spoof-d)](https://www.npmjs.com/package/spoof-d)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![GitHub forks](https://img.shields.io/github/forks/TT5H/spoof-d)](https://github.com/TT5H/spoof-d/network)
+[![GitHub stars](https://img.shields.io/github/stars/TT5H/spoof-d)](https://github.com/TT5H/spoof-d/stargazers)
+
+> **✅ Cross-Platform Support**: This is a modernized fork of the original `spoof` project, updated for compatibility with modern macOS (Sequoia 15.4+, Tahoe 26+), Windows 10/11, and Linux. All platforms are now fully supported!
+
+### Easily spoof your MAC address on macOS, Windows, and Linux!
+
+A Node.js utility for changing MAC addresses across all major platforms. Features reliable macOS support, modern Windows PowerShell integration, and Linux `ip link` commands. This fork includes enhanced error handling, automatic verification, retry logic, and improved cross-platform compatibility.
+
+## About This Fork
+
+This repository ([TT5H/spoof-d](https://github.com/TT5H/spoof-d)) is a fork of [basedbytes/spoofy](https://github.com/basedbytes/spoofy), which itself is a fork of the original `spoof` project. This fork extends the functionality with full cross-platform support and enhanced features.
+
+### What's Changed
+
+- **✅ Full Cross-Platform Support**: Complete Windows 10/11 and Linux support (not just macOS)
+- **Modern macOS Support**: Fixed MAC spoofing for macOS Sequoia 15.4+ and Tahoe 26+
+- **Windows Support**: Full Windows 10/11 support using PowerShell and registry methods with automatic fallback
+- **Linux Support**: Modern Linux support using `ip link` commands (replaces deprecated `ifconfig`)
+- **Enhanced Error Handling**: Custom error classes with actionable suggestions and better error messages
+- **Automatic Verification**: Verifies MAC address changes after setting them
+- **Retry Logic**: Automatic retry with exponential backoff for transient failures
+- **Timeout Handling**: Prevents hanging operations with configurable timeouts
+- **Better Validation**: Comprehensive input validation with helpful error messages
+- **Removed `airport` dependency**: The deprecated `airport -z` command has been replaced with modern `networksetup` commands
+- **Timing-sensitive MAC changes**: WiFi MAC addresses are now changed in the brief window after power-on but before network connection
+- **Improved interface detection**: Better cross-platform interface detection using modern system commands
+- **Cleaner codebase**: Removed deprecated code paths and unnecessary constants
+
+## Key Features
+
+### Enhanced Error Handling
+- **Custom error classes** with specific error types (ValidationError, PermissionError, NetworkError, etc.)
+- **Actionable suggestions** provided with every error message
+- **Better error context** to help diagnose issues quickly
+
+### Reliability Features
+- **Automatic verification** of MAC address changes after setting them
+- **Retry logic** with exponential backoff for transient failures
+- **Timeout handling** to prevent hanging operations
+- **Comprehensive validation** of inputs before attempting changes
+
+### Cross-Platform Excellence
+- **Windows**: PowerShell integration with registry fallback
+- **macOS**: Modern networksetup commands with WiFi timing handling
+- **Linux**: Modern ip link commands with ifconfig fallback
+- **Unified API** across all platforms
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm install -g spoof-d
+```
+
+After installation, use the `spoofy` command (the package name is `spoof-d`, but the command is still `spoofy`).
+
+After installation, you can use the `spoofy` command from anywhere.
+
+### From source
+
+```bash
+git clone https://github.com/TT5H/spoof-d.git
+cd spoof-d
+npm install
+npm install -g .
+```
+
+This gives you the latest development version with all the latest features.
+
+## Quick Start
+
+### List network interfaces
+
+**macOS/Linux:**
+```bash
+spoofy list
+```
+
+**Windows (run PowerShell as Administrator):**
+```powershell
+spoofy list
+```
+
+### Randomize MAC address
+
+**macOS (WiFi is typically `en0`):**
+```bash
+sudo spoofy randomize en0
+```
+
+**Windows:**
+```powershell
+# Run PowerShell as Administrator
+spoofy randomize "Ethernet"
+```
+
+**Linux:**
+```bash
+sudo spoofy randomize eth0
+```
+
+**Note:** WiFi will disconnect briefly and may need to reconnect to networks. On Windows, ensure you're running as Administrator.
+
+## Usage
+
+You can always see up-to-date usage instructions by running `spoofy --help`.
+
+### List available devices
+
+```bash
+spoofy list
+```
+
+Output:
+
+```
+- "Ethernet" on device "en4" with MAC address 70:56:51:BE:B3:00
+- "Wi-Fi" on device "en0" with MAC address 70:56:51:BE:B3:01 currently set to 70:56:51:BE:B3:02
+- "Bluetooth PAN" on device "en1"
+```
+
+### List only Wi-Fi devices
+
+```bash
+spoofy list --wifi
+```
+
+### Randomize MAC address _(requires root)_
+
+Using hardware port name:
+
+```bash
+sudo spoofy randomize wi-fi
+```
+
+Or using device name:
+
+```bash
+sudo spoofy randomize en0
+```
+
+### Set specific MAC address _(requires root)_
+
+```bash
+sudo spoofy set 00:11:22:33:44:55 en0
+```
+
+### Reset to original MAC address _(requires root)_
+
+```bash
+sudo spoofy reset wi-fi
+```
+
+**Note**: On macOS, restarting your computer will also reset your MAC address to the original hardware address.
+
+## Platform Support
+
+### macOS ✅
+
+- ✅ **Fully supported** and tested on macOS Tahoe 26.2
+- ✅ Works on macOS Sequoia 15.4+
+- ⚠️ Older versions may work but are untested
+- Uses `networksetup` and `ifconfig` commands
+- Special handling for WiFi interfaces on modern macOS
+
+### Windows ✅
+
+- ✅ **Fully supported** on Windows 10 and Windows 11
+- ✅ Uses PowerShell `Get-NetAdapter` and `Set-NetAdapter` commands
+- ✅ Falls back to registry method for compatibility
+- ⚠️ Requires Administrator privileges (run PowerShell/CMD as Administrator)
+- Some network adapters may not support MAC address changes (hardware limitation)
+
+**Windows Usage:**
+```powershell
+# Run PowerShell or CMD as Administrator
+spoofy list
+spoofy randomize "Ethernet"
+spoofy set 00:11:22:33:44:55 "Wi-Fi"
+```
+
+### Linux ✅
+
+- ✅ **Fully supported** using modern `ip link` commands
+- ✅ Falls back to `ifconfig` if `ip` command is not available
+- ⚠️ Requires root privileges (use `sudo`)
+- Works with most modern Linux distributions
+
+**Linux Usage:**
+```bash
+sudo spoofy list
+sudo spoofy randomize eth0
+sudo spoofy set 00:11:22:33:44:55 wlan0
+```
+
+## Known Issues
+
+- WiFi will briefly disconnect when changing MAC address
+- Some network restrictions or hardware may prevent MAC spoofing
+- Requires sudo/root privileges for all MAC address changes
+
+## Troubleshooting
+
+### macOS
+1. Make sure you're running with `sudo` (required for network changes)
+2. Ensure WiFi is turned on before attempting to change MAC
+3. On modern macOS, you may need to reconnect to WiFi after the change
+4. Try running `networksetup -detectnewhardware` if changes don't take effect
+
+### Windows
+1. **Run as Administrator**: Right-click PowerShell or Command Prompt and select "Run as Administrator"
+2. Some network adapters don't support MAC address changes (hardware limitation)
+3. If `Set-NetAdapter` fails, the tool will automatically try the registry method
+4. You may need to disable and re-enable the adapter manually if changes don't take effect
+5. Check adapter compatibility: Some virtual adapters and certain hardware may not support MAC spoofing
+
+### Linux
+1. Make sure you're running with `sudo` (required for network changes)
+2. Ensure the `ip` command is available (usually in `iproute2` package)
+3. Some network interfaces may be managed by NetworkManager - you may need to disable it temporarily
+4. Virtual interfaces and certain hardware may not support MAC address changes
+
+## Contributing
+
+This is an active fork. Contributions, bug reports, and feature requests are welcome!
+
+To contribute:
+1. Fork this repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT License (inherited from original project)
+
+## Credits
+
+- **This fork**: [TT5H/spoof-d](https://github.com/TT5H/spoof-d) - Enhanced cross-platform support with improved error handling
+- **Parent fork**: [basedbytes/spoofy](https://github.com/basedbytes/spoofy) - Modernized macOS support
+- **Original project**: `spoof` by Feross Aboukhadijeh
+
+This fork maintains compatibility with modern operating systems and extends support to Windows and Linux.

package/bin/cmd.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+
+const chalk = require("chalk");
+const minimist = require("minimist");
+const spoof = require("../");
+const { stripIndent } = require("common-tags");
+const cp = require("child_process");
+
+const argv = minimist(process.argv.slice(2), {
+  alias: {
+    v: "version",
+  },
+  boolean: ["version"],
+});
+const cmd = argv._[0];
+
+try {
+  init();
+} catch (err) {
+  handleError(err);
+  process.exitCode = -1;
+}
+
+function handleError(err) {
+  if (err.code) {
+    // Custom error with code and suggestions
+    console.error(chalk.red(`✗ ${err.name || "Error"}:`), err.message);
+    
+    if (err.suggestions && err.suggestions.length > 0) {
+      console.error(chalk.yellow("\nSuggestions:"));
+      err.suggestions.forEach((suggestion, index) => {
+        console.error(chalk.gray(`  ${index + 1}. ${suggestion}`));
+      });
+    }
+  } else {
+    // Standard error
+    console.error(chalk.red("✗ Error:"), err.message);
+    
+    // Provide helpful suggestions for common errors
+    if (err.message.includes("ENOENT") || err.message.includes("spawn")) {
+      console.error(chalk.yellow("\nThis might be a system command issue. Suggestions:"));
+      if (process.platform === "linux") {
+        console.error(chalk.gray("  • Install iproute2: sudo apt-get install iproute2"));
+      } else if (process.platform === "win32") {
+        console.error(chalk.gray("  • Ensure PowerShell is installed and in PATH"));
+      }
+    } else if (err.message.includes("permission") || err.message.includes("Permission")) {
+      console.error(chalk.yellow("\nPermission issue. Suggestions:"));
+      if (process.platform === "win32") {
+        console.error(chalk.gray("  • Run PowerShell/CMD as Administrator"));
+      } else {
+        console.error(chalk.gray("  • Use sudo: sudo spoofy <command>"));
+      }
+    }
+  }
+  
+  if (process.env.DEBUG) {
+    console.error(chalk.gray("\nStack trace:"));
+    console.error(err.stack);
+  }
+}
+
+function init() {
+  if (cmd === "version" || argv.version) {
+    version();
+  } else if (cmd === "list" || cmd === "ls") {
+    list();
+  } else if (cmd === "set") {
+    const mac = argv._[1];
+    const devices = argv._.slice(2);
+    set(mac, devices);
+  } else if (cmd === "randomize") {
+    const devices = argv._.slice(1);
+    randomize(devices);
+  } else if (cmd === "reset") {
+    const devices = argv._.slice(1);
+    reset(devices);
+  } else if (cmd === "normalize") {
+    const mac = argv._[1];
+    normalize(mac);
+  } else {
+    help();
+  }
+}
+
+function help() {
+  const platform = process.platform;
+  let example = "";
+  let note = "";
+
+  if (platform === "win32") {
+    example = `      spoofy randomize "Ethernet"`;
+    note = "\n    Note: On Windows, run PowerShell or CMD as Administrator.";
+  } else if (platform === "darwin") {
+    example = `      spoofy randomize en0`;
+    note = "\n    Note: On macOS/Linux, use sudo for MAC address changes.";
+  } else {
+    example = `      sudo spoofy randomize eth0`;
+    note = "\n    Note: On Linux, use sudo for MAC address changes.";
+  }
+
+  const message = stripIndent`
+    spoofy - Cross-platform MAC address spoofing utility
+
+    Example (randomize MAC address):
+${example}${note}
+
+    Usage:
+      spoofy list [--wifi]                     List available devices.
+      spoofy set <mac> <devices>...            Set device MAC address.
+      spoofy randomize [--local] <devices>...  Set device MAC address randomly.
+      spoofy reset <devices>...                Reset device MAC address to default.
+      spoofy normalize <mac>                   Given a MAC address, normalize it.
+      spoofy help                              Shows this help message.
+      spoofy version | --version | -v          Show package version.
+
+    Options:
+      --wifi          Try to only show wireless interfaces.
+      --local         Set the locally administered flag on randomized MACs.
+
+    Platform Support:
+      ✅ macOS (Sequoia 15.4+, Tahoe 26+)
+      ✅ Windows 10/11
+      ✅ Linux (modern distributions)
+  `;
+  console.log(message);
+}
+
+function version() {
+  console.log(require("../package.json").version);
+}
+
+function set(mac, devices) {
+  if (!mac) {
+    throw new Error("MAC address is required. Usage: spoofy set <mac> <device>");
+  }
+  
+  if (!devices || devices.length === 0) {
+    throw new Error("Device name is required. Usage: spoofy set <mac> <device>");
+  }
+  
+  devices.forEach((device) => {
+    const it = spoof.findInterface(device);
+
+    if (!it) {
+      throw new Error(
+        `Could not find device "${device}". ` +
+        "List available devices using: spoofy list"
+      );
+    }
+
+    setMACAddress(it.device, mac, it.port);
+  });
+}
+
+function normalize(mac) {
+  if (!mac) {
+    throw new Error("MAC address is required. Usage: spoofy normalize <mac>");
+  }
+  
+  try {
+    const normalized = spoof.normalize(mac);
+    if (!normalized) {
+      throw new Error(`"${mac}" is not a valid MAC address`);
+    }
+    console.log(normalized);
+  } catch (err) {
+    throw new Error(
+      `Could not normalize MAC address "${mac}": ${err.message}`
+    );
+  }
+}
+
+function randomize(devices) {
+  if (!devices || devices.length === 0) {
+    throw new Error("Device name is required. Usage: spoofy randomize <device>");
+  }
+  
+  devices.forEach((device) => {
+    const it = spoof.findInterface(device);
+
+    if (!it) {
+      throw new Error(
+        `Could not find device "${device}". ` +
+        "List available devices using: spoofy list"
+      );
+    }
+
+    const mac = spoof.randomize(argv.local);
+    console.log(chalk.blue("ℹ"), `Generated random MAC address: ${chalk.bold.cyan(mac)}`);
+    setMACAddress(it.device, mac, it.port);
+  });
+}
+
+function reset(devices) {
+  if (!devices || devices.length === 0) {
+    throw new Error("Device name is required. Usage: spoofy reset <device>");
+  }
+  
+  devices.forEach((device) => {
+    const it = spoof.findInterface(device);
+
+    if (!it) {
+      throw new Error(
+        `Could not find device "${device}". ` +
+        "List available devices using: spoofy list"
+      );
+    }
+
+    if (!it.address) {
+      throw new Error(
+        `Could not read hardware MAC address for "${device}". ` +
+        "The device may not have a MAC address or may be a virtual interface."
+      );
+    }
+
+    console.log(chalk.blue("ℹ"), `Resetting to hardware MAC address: ${chalk.bold.cyan(it.address)}`);
+    setMACAddress(it.device, it.address, it.port);
+  });
+}
+
+function list() {
+  const targets = [];
+  if (argv.wifi) {
+    if (process.platform === "win32") {
+      targets.push("wi-fi", "wireless", "wlan");
+    } else {
+      targets.push("wi-fi");
+    }
+  }
+
+  const interfaces = spoof.findInterfaces(targets);
+
+  if (interfaces.length === 0) {
+    console.log(chalk.yellow("No network interfaces found."));
+    return;
+  }
+
+  interfaces.forEach((it) => {
+    const line = [];
+    line.push(
+      "-",
+      chalk.bold.green(it.port || it.device),
+      "on device",
+      chalk.bold.green(it.device)
+    );
+    
+    if (it.status && process.platform === "win32") {
+      line.push(chalk.gray(`(${it.status})`));
+    }
+    
+    if (it.address) {
+      line.push("with MAC address", chalk.bold.cyan(it.address));
+    }
+    if (it.currentAddress && it.currentAddress !== it.address) {
+      line.push("currently set to", chalk.bold.red(it.currentAddress));
+    }
+    console.log(line.join(" "));
+  });
+}
+
+function setMACAddress(device, mac, port) {
+  // Check for admin/root privileges
+  if (process.platform === "win32") {
+    // On Windows, check if running as administrator
+    try {
+      const output = cp
+        .execSync(
+          'powershell -Command "[Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent() | Select-Object -ExpandProperty IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)"',
+          { stdio: "pipe", shell: true }
+        )
+        .toString()
+        .trim()
+        .toLowerCase();
+      
+      if (output !== "true") {
+        throw new Error(
+          "Must run as Administrator to change network settings. " +
+          "Right-click Command Prompt or PowerShell and select 'Run as Administrator'"
+        );
+      }
+    } catch (err) {
+      if (err.message.includes("Must run as Administrator")) {
+        throw err;
+      }
+      // If check fails, warn but continue (might work anyway)
+      console.warn(chalk.yellow("Warning: Could not verify administrator privileges. Operation may fail."));
+    }
+  } else if (process.platform !== "win32") {
+    // Unix-like systems (macOS, Linux)
+    if (process.getuid && process.getuid() !== 0) {
+      throw new Error(
+        "Must run as root (or using sudo) to change network settings"
+      );
+    }
+  }
+
+  try {
+    spoof.setInterfaceMAC(device, mac, port);
+    console.log(
+      chalk.green("✓") +
+      " Successfully set MAC address to " +
+      chalk.bold.cyan(mac) +
+      " on " +
+      chalk.bold.green(device)
+    );
+    
+    // Note: Verification is already done in setInterfaceMAC, so we don't need to do it again here
+  } catch (err) {
+    // Error is already formatted by handleError in the catch block above
+    throw err;
+  }
+}