spoof-d 0.4.0 → 0.5.0

package/README.md

@@ -7,9 +7,9 @@
 
 > **✅ 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!
+### Easily spoof your MAC address and DUID 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.
+A Node.js utility for changing MAC addresses and DHCPv6 DUIDs 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
 
@@ -85,6 +85,110 @@ npm install -g .
 
 This gives you the latest development version with all the latest features.
 
+## Shell Completions
+
+`spoof-d` includes shell completion support for bash, zsh, fish, and PowerShell, making it easier to use the CLI with tab completion.
+
+### Automatic Installation
+
+The easiest way to install completions is using the built-in command:
+
+```bash
+spoofy completion
+```
+
+This will automatically detect your shell and install the appropriate completion file. You can also specify a shell explicitly:
+
+```bash
+spoofy completion --shell=bash
+spoofy completion --shell=zsh
+spoofy completion --shell=fish
+spoofy completion --shell=powershell
+```
+
+### Manual Installation
+
+#### Bash
+
+```bash
+# Copy completion file
+mkdir -p ~/.bash_completion.d
+cp completions/spoofy.bash ~/.bash_completion.d/spoofy
+
+# Add to ~/.bashrc
+echo "source ~/.bash_completion.d/spoofy" >> ~/.bashrc
+source ~/.bashrc
+```
+
+Or install globally (requires root):
+
+```bash
+sudo cp completions/spoofy.bash /etc/bash_completion.d/spoofy
+```
+
+#### Zsh
+
+```bash
+# Copy completion file
+mkdir -p ~/.zshrc.d
+cp completions/spoofy.zsh ~/.zshrc.d/_spoofy
+
+# Add to ~/.zshrc
+echo "fpath=(~/.zshrc.d \$fpath)" >> ~/.zshrc
+echo "autoload -U compinit && compinit" >> ~/.zshrc
+source ~/.zshrc
+```
+
+Or install globally (requires root):
+
+```bash
+sudo cp completions/spoofy.zsh /usr/local/share/zsh/site-functions/_spoofy
+```
+
+#### Fish
+
+```bash
+# Copy completion file
+mkdir -p ~/.config/fish/completions
+cp completions/spoofy.fish ~/.config/fish/completions/spoofy.fish
+```
+
+Fish will automatically load completions from `~/.config/fish/completions/`. Just restart your fish shell.
+
+Or install globally (requires root):
+
+```bash
+sudo cp completions/spoofy.fish /usr/share/fish/completions/spoofy.fish
+```
+
+#### PowerShell
+
+```powershell
+# Copy completion file
+New-Item -ItemType Directory -Force -Path (Split-Path $PROFILE)
+Copy-Item completions/spoofy.ps1 $PROFILE
+
+# Add to PowerShell profile
+Add-Content $PROFILE ". $PROFILE"
+
+# Reload profile
+. $PROFILE
+```
+
+Or add manually to your profile:
+
+```powershell
+. C:\path\to\completions\spoofy.ps1
+```
+
+### Features
+
+- **Command completion**: Tab-complete all available commands (`list`, `set`, `randomize`, `duid`, etc.)
+- **Interface name completion**: Automatically suggests available network interfaces
+- **Option completion**: Tab-complete all flags and options (`--wifi`, `--verbose`, etc.)
+- **DUID subcommand completion**: Full completion support for DUID commands
+- **Context-aware**: Completions adapt based on the current command and position
+
 ## Quick Start
 
 ### List network interfaces
@@ -173,7 +277,11 @@ sudo spoofy reset wi-fi
 
 ## DUID Spoofing (DHCPv6)
 
+<<<<<<< HEAD
 `spoof-d` also supports DHCPv6 DUID (DHCP Unique Identifier) spoofing for complete IPv6 network identity management.
+=======
+spoofy also supports DHCPv6 DUID (DHCP Unique Identifier) spoofing for complete IPv6 network identity management.
+>>>>>>> upstream/master
 
 ### What is a DUID?
 
@@ -183,8 +291,13 @@ A DUID (DHCP Unique Identifier) is used in DHCPv6 to uniquely identify a client
 
 The first time you spoof your DUID, your **original DUID is automatically saved** to:
 - macOS: `/var/db/dhcpclient/DUID.original`
+<<<<<<< HEAD
 - Linux: `/var/lib/spoofy/duid.original`
 - Windows: `%PROGRAMDATA%\spoofy\duid.original`
+=======
+- Linux: `/var/lib/spoofy/duid.original` *(planned)*
+- Windows: `%PROGRAMDATA%\spoofy\duid.original` *(planned)*
+>>>>>>> upstream/master
 
 This allows you to **restore to your pre-spoofing state** at any time using `spoofy duid restore`.
 
@@ -264,6 +377,7 @@ sudo spoofy duid reset en0
 | 3 | DUID-LL | Link-layer address only (default) |
 | 4 | DUID-UUID | UUID-based identifier |
 
+<<<<<<< HEAD
 ### Show detailed interface information
 
 ```bash
@@ -414,6 +528,79 @@ Long-running operations show progress indicators:
 
 ```bash
 ⏳ Changing MAC address... ✓ Successfully set MAC address
+=======
+### Programmatic Usage
+
+```javascript
+const spoofy = require('spoofy');
+
+// Get current DUID
+const current = spoofy.duid.getCurrentDUID();
+console.log('Current DUID:', spoofy.duid.formatDUID(current));
+
+// Parse DUID info
+const info = spoofy.duid.parseDUID(current);
+console.log('Type:', info.typeName);
+console.log('MAC:', info.lladdr);
+
+// Check if original is stored
+if (spoofy.duid.hasOriginalDUID()) {
+  const original = spoofy.duid.getOriginalDUID();
+  console.log('Original DUID:', spoofy.duid.formatDUID(original));
+}
+
+// Generate a random DUID
+const newDuid = spoofy.duid.generateDUID(spoofy.duid.DUID_TYPES.DUID_LL);
+console.log('Generated:', spoofy.duid.formatDUID(newDuid));
+
+// Set DUID (requires root) - automatically saves original on first call
+spoofy.duid.setDUID(newDuid, 'en0');
+
+// Randomize DUID
+spoofy.duid.randomizeDUID(spoofy.duid.DUID_TYPES.DUID_LLT, 'en0');
+
+// Sync DUID to current MAC address
+spoofy.duid.syncDUID('en0', spoofy.duid.DUID_TYPES.DUID_LL);
+
+// Restore to original DUID
+spoofy.duid.restoreDUID('en0');
+```
+
+### Combined MAC + DUID Spoofing
+
+For complete identity change on IPv6 networks, you should change both MAC and DUID.
+
+**Recommended workflow using sync:**
+
+```bash
+sudo spoofy randomize en0      # Spoof MAC first
+sudo spoofy duid sync en0      # Sync DUID to match spoofed MAC
+```
+
+The `sync` command automatically matches the DUID to your current (spoofed) MAC address.
+
+**Alternative - randomize both separately:**
+
+```bash
+sudo spoofy randomize en0
+sudo spoofy duid randomize en0
+```
+
+**Manual sync for advanced use:**
+
+When using DUID-LL or DUID-LLT types, the DUID includes the MAC address. For consistent spoofing, ensure the MAC in your DUID matches your spoofed MAC:
+
+```javascript
+const spoofy = require('spoofy');
+
+// Spoof MAC
+const newMac = '00:11:22:33:44:55';
+spoofy.setInterfaceMAC('en0', newMac, 'Wi-Fi');
+
+// Create matching DUID
+const duid = spoofy.duid.generateDUID(spoofy.duid.DUID_TYPES.DUID_LL, newMac);
+spoofy.duid.setDUID(duid, 'en0');
+>>>>>>> upstream/master
 ```
 
 ## Platform Support
@@ -460,7 +647,125 @@ sudo spoofy set 00:11:22:33:44:55 wlan0
 
 - 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
+- Requires sudo/root privileges for all MAC address and DUID changes
+- DUID changes may require DHCPv6 lease renewal to take effect
+
+## NetworkManager Integration (Linux)
+
+On Linux systems using NetworkManager, MAC address changes may be immediately overwritten by NetworkManager if the interface is managed. `spoof-d` includes NetworkManager detection and integration to help prevent this issue.
+
+### Automatic Detection
+
+When changing MAC addresses on Linux, `spoof-d` automatically:
+- Detects if NetworkManager is present and running
+- Checks if the target interface is managed by NetworkManager
+- Warns you if the interface is managed (MAC changes may be overwritten)
+
+### Using `--nm-reconnect`
+
+To automatically reconnect the NetworkManager device after a MAC change:
+
+```bash
+sudo spoofy randomize eth0 --nm-reconnect
+```
+
+This will:
+1. Change the MAC address
+2. Disconnect the device from NetworkManager
+3. Reconnect the device to apply the new MAC address
+
+### Force NetworkManager Restart
+
+If normal reconnection doesn't work, you can force NetworkManager to restart networking (use with caution):
+
+```bash
+sudo spoofy randomize eth0 --nm-reconnect --force
+```
+
+**Warning:** The `--force` flag will temporarily disable all NetworkManager networking, which may disconnect all network interfaces briefly.
+
+### Manual NetworkManager Management
+
+If you prefer to manage NetworkManager manually:
+
+1. **Temporarily disconnect the device:**
+   ```bash
+   nmcli dev disconnect eth0
+   sudo spoofy randomize eth0
+   nmcli dev connect eth0
+   ```
+
+2. **Mark device as unmanaged** (persistent):
+   Edit `/etc/NetworkManager/NetworkManager.conf`:
+   ```ini
+   [keyfile]
+   unmanaged-devices=interface-name:eth0
+   ```
+   Then restart NetworkManager:
+   ```bash
+   sudo systemctl restart NetworkManager
+   ```
+
+3. **Disable NetworkManager for specific interface** (temporary):
+   ```bash
+   nmcli device set eth0 managed no
+   sudo spoofy randomize eth0
+   nmcli device set eth0 managed yes
+   ```
+
+### Verbose Output
+
+Use `--verbose` to see detailed NetworkManager status:
+
+```bash
+sudo spoofy randomize eth0 --verbose
+```
+
+This will show:
+- NetworkManager detection method (nmcli, systemctl, etc.)
+- Device management status
+- Raw nmcli output for debugging
+
+## Testing
+
+The project includes test suites for core functionality:
+
+### DUID Tests
+
+Test DUID generation, parsing, and conversion:
+
+```bash
+# Run all DUID tests
+npm run test:duid
+# or
+node test/test-duid.js
+
+# Run specific test
+node test/test-duid.js --test=generation
+node test/test-duid.js --test=parsing
+```
+
+### NetworkManager Tests (Linux only)
+
+Test NetworkManager detection and device status parsing:
+
+```bash
+# Run all NetworkManager tests
+npm run test:nm
+# or
+node test/test-networkmanager.js
+
+# Run specific test (parsing tests work on any platform)
+node test/test-networkmanager.js --test=parsing
+```
+
+### Run All Tests
+
+```bash
+npm run test:all
+```
+
+**Note:** NetworkManager tests require a Linux system with NetworkManager installed. Parsing tests work on any platform.
 
 ## Troubleshooting
 
@@ -469,6 +774,7 @@ sudo spoofy set 00:11:22:33:44:55 wlan0
 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
+5. For DUID changes, you may need to disable/re-enable IPv6 or renew DHCPv6 lease
 
 ### Windows
 1. **Run as Administrator**: Right-click PowerShell or Command Prompt and select "Run as Administrator"
@@ -480,8 +786,12 @@ sudo spoofy set 00:11:22:33:44:55 wlan0
 ### 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
+3. **NetworkManager conflicts**: If NetworkManager is managing your interface, MAC changes may be overwritten
+   - Use `--nm-reconnect` to automatically reconnect after MAC change
+   - Or manually disconnect/reconnect: `nmcli dev disconnect <iface>` then `nmcli dev connect <iface>`
+   - Or mark interface as unmanaged in NetworkManager config (see NetworkManager Integration section)
 4. Virtual interfaces and certain hardware may not support MAC address changes
+5. If MAC changes don't persist, check NetworkManager status: `nmcli device status`
 
 ## Contributing