pyhdwallet/README.md

# pyhdwallet – Secure HD Wallet Tool

**Deterministic BIP32/BIP39/BIP44 HD wallet generator** for Bitcoin, Ethereum, and other cryptocurrencies. Designed for **air-gapped, offline use** with multi-platform support.

## 📦 Installation

### **Quick Start (macOS/Linux with Internet)**

```bash
# Clone repository
git clone https://github.com/yourusername/hdwalletpy.git
cd hdwalletpy

# Install using automated script
./install_offline.sh
```

### **Air-Gapped Installation (No Internet)**

The project includes **pre-built vendored wheels** for offline installation on:

- **macOS ARM64** (Apple Silicon)
- **Linux x86_64** (Intel/AMD servers)
- **Linux aarch64** (ARM64 servers, Raspberry Pi, Mac containers)

**Steps:**

1. **On internet-connected machine:**

   ```bash
   git clone https://github.com/yourusername/hdwalletpy.git
   cd hdwalletpy

   # Verify vendor checksums
   cd vendor/macos-arm64 && shasum -a 256 -c SHA256SUMS      # macOS
   cd vendor/linux-x86_64 && sha256sum -c SHA256SUMS         # Linux x86
   cd vendor/linux-aarch64 && sha256sum -c SHA256SUMS        # Linux ARM
   ```

2. **Transfer to USB/CD:**

   ```bash
   # Copy entire repository to USB drive
   cp -r hdwalletpy /Volumes/USB/
   ```

3. **On air-gapped machine:**

   ```bash
   cd /path/to/hdwalletpy

   # Ensure Python 3.12 is installed
   python3.12 --version

   # Run offline installer (auto-detects platform)
   ./install_offline.sh

   # Activate virtual environment
   source .venv/bin/activate

   # Generate wallet
   python src/pyhdwallet.py gen --help
   ```

### **Developer Installation (with Docker)**

Build wheels and run tests across all platforms:

```bash
# Build Docker image
make build-image

# Build vendor wheels for all platforms
make vendor-all          # Runtime wheels only
make vendor-all-dev      # Runtime + dev wheels (pytest)

# Install development environment
make install-dev-offline

# Run tests
make test
```

## ✅ Basic Usage

```bash
# Generate wallet (prints mnemonic - debug mode)
python src/pyhdwallet.py gen

# Generate with off-screen mode + encrypted ZIP
python src/pyhdwallet.py gen --file --zip

# Generate with PGP encryption + ZIP
python src/pyhdwallet.py gen --file --zip --pgp recipient@example.com

# Recover wallet from mnemonic
python src/pyhdwallet.py recover

# Fetch PGP public key (requires internet)
python src/pyhdwallet.py fetchkey keyserver.ubuntu.com recipient@example.com

# Run tests
python src/pyhdwallet.py test
```

## 🔐 Security Features

- ✅ **BIP39** 24-word mnemonic generation
- ✅ **BIP32** hierarchical deterministic wallet derivation
- ✅ **BIP44** multi-currency account structure
- ✅ **Air-gapped operation** with vendored dependencies
- ✅ **AES-256 encrypted ZIP** artifacts with password protection
- ✅ **PGP encryption** support for at-rest storage
- ✅ **Deterministic output** for reproducible wallet generation
- ✅ **Multi-platform** offline support (macOS, Linux x86/ARM)
- ✅ **Checksum verification** for vendored wheels

## 🛠️ Makefile Targets

### **Vendoring (Air-Gapped Deployment)**

```bash
make vendor-macos         # Build macOS ARM64 wheels
make vendor-macos-dev     # Build macOS dev wheels (pytest)
make vendor-linux         # Build Linux x86_64 wheels (Docker)
make vendor-linux-dev     # Build Linux x86_64 dev wheels
make vendor-linux-arm     # Build Linux ARM64 wheels (Docker)
make vendor-linux-arm-dev # Build Linux ARM64 dev wheels
make vendor-all           # Build runtime wheels for ALL platforms
make vendor-all-dev       # Build dev wheels for ALL platforms
make verify-vendor        # Test offline installation
```

### **Binary Distribution**

```bash
make binary               # Build standalone binary for current platform
make binary-linux         # Build Linux binary via Docker
make binary-all           # Build binaries for all platforms
```

### **Development Workflow**

```bash
make install              # Create venv and install dependencies
make install-offline      # Install from vendor/ (offline)
make install-dev-offline  # Install dev dependencies (offline)
make test                 # Run test suite
make clean                # Remove venv, cache, vendor/
make clean-vendor         # Remove vendor/ only
```

### **Release Management**

```bash
make release              # Build complete release package
make release-test         # Test release binaries
make clean-release        # Remove release artifacts
```

## 📖 Full Documentation

See [playbook.md](./playbook.md) for:

- Detailed air-gapped security setup
- Multi-platform installation guide
- PGP key management
- Operational security checklist
- Troubleshooting guide
- Testing and development workflows

## 🔒 Recommended Air-Gapped Setup

1. **Build/verify on trusted internet machine**
2. **Transfer via USB/CD** to air-gapped machine
3. **Verify checksums** before installation
4. **Generate wallet offline** with PGP encryption
5. **Store encrypted artifacts** on separate media
6. **Test recovery process** before real use

**Threat model:** Protects against network-based attacks, remote exploitation, and keyloggers. Physical security and operational discipline required.

## 📝 License

MIT License - See [LICENSE](./LICENSE) for details.

## 🙏 Credits

Built with:

- [bip-utils](https://github.com/ebellocchia/bip_utils) - BIP32/39/44 implementation
- [PyInstaller](https://www.pyinstaller.org/) - Binary packaging
- Python 3.12 and cryptography libraries