173 lines
4.1 KiB
Markdown
173 lines
4.1 KiB
Markdown
# pyhdwallet – Secure HD Wallet Tool
|
||
|
||
A Python command-line tool for generating and recovering BIP39 HD wallets with support for Ethereum, Solana, and Bitcoin. Designed for offline operation with optional PGP encryption and AES-encrypted ZIP artifacts.
|
||
|
||
---
|
||
|
||
## 📦 Installation
|
||
|
||
### **Quick Start (macOS/Linux with Internet)**
|
||
|
||
```bash
|
||
# Clone repository
|
||
git clone https://github.com/<your-username>/hdwalletpy.git
|
||
cd hdwalletpy
|
||
|
||
# Install using automated script
|
||
./install_offline.sh
|
||
```
|
||
|
||
The script automatically:
|
||
|
||
- Creates Python 3.12 virtual environment
|
||
- Installs from vendored wheels (offline-capable)
|
||
- Verifies installation with test suite
|
||
- Leaves you in activated venv
|
||
|
||
---
|
||
|
||
### **Air-Gapped Installation (No Internet)**
|
||
|
||
This repository includes pre-built Python wheels for offline use.
|
||
|
||
**Supported platforms:**
|
||
|
||
- macOS ARM64 (M1/M2/M3) - Python 3.12
|
||
- Linux x86_64 (Ubuntu/Tails) - Python 3.12
|
||
|
||
**Steps:**
|
||
|
||
1. On an online machine, clone and verify:
|
||
|
||
```bash
|
||
git clone https://github.com/<your-username>/hdwalletpy.git
|
||
cd hdwalletpy
|
||
|
||
# Verify checksums
|
||
cd vendor/linux-x86_64 # or macos-arm64
|
||
sha256sum -c SHA256SUMS # Linux
|
||
shasum -a 256 -c SHA256SUMS # macOS
|
||
```
|
||
|
||
2. Transfer entire repo to USB drive
|
||
|
||
3. On air-gapped machine:
|
||
|
||
```bash
|
||
cd hdwalletpy
|
||
./install_offline.sh
|
||
```
|
||
|
||
4. Generate wallet:
|
||
|
||
```bash
|
||
python src/pyhdwallet.py gen --off-screen --file
|
||
```
|
||
|
||
---
|
||
|
||
### **Developer Installation (with Docker)**
|
||
|
||
For development or building wheels for other platforms:
|
||
|
||
```bash
|
||
# Build Docker image
|
||
make build-image
|
||
|
||
# Build wheels for all platforms
|
||
make vendor-all
|
||
|
||
# Install development environment
|
||
make install
|
||
|
||
# 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 --off-screen --file
|
||
|
||
# Generate with PGP encryption + ZIP
|
||
python src/pyhdwallet.py gen \
|
||
--pgp-pubkey-file pubkeys/mykey.asc \
|
||
--expected-fingerprint A27B96F2B169B5491013D2DA892B822C14A9AA18 \
|
||
--off-screen \
|
||
--file
|
||
|
||
# Recover wallet from mnemonic
|
||
python src/pyhdwallet.py recover --interactive --file
|
||
|
||
# Fetch PGP public key (requires internet)
|
||
python src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.asc
|
||
|
||
# Run tests
|
||
python src/pyhdwallet.py test
|
||
pytest -v tests/test_vectors.py
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 Security Features
|
||
|
||
- **Offline-first**: Network access blocked during key generation/recovery
|
||
- **Test suite**: Regression tests with frozen vectors ensure derivation logic integrity
|
||
- **PGP fingerprint pinning**: Prevents key substitution attacks
|
||
- **TTY safety guard**: Refuses to print secrets when stdout is piped/redirected
|
||
- **AES-encrypted outputs**: Wallet artifacts encrypted with `pyzipper`
|
||
- **No shell history leaks**: Use `--interactive` or `--mnemonic-stdin` for recovery
|
||
|
||
---
|
||
|
||
## 🛠️ Makefile Targets
|
||
|
||
**Vendoring (for air-gapped deployment):**
|
||
|
||
```bash
|
||
make vendor-macos # Build macOS ARM64 wheels
|
||
make vendor-linux # Build Linux x86_64 wheels (Docker)
|
||
make vendor-all # Build for both platforms
|
||
make verify-vendor # Test offline installation
|
||
```
|
||
|
||
**Development:**
|
||
|
||
```bash
|
||
make install # Create venv and install dependencies
|
||
make test # Run test suite
|
||
make build-image # Build Docker image
|
||
make shell # Open shell in Docker container
|
||
make clean # Remove venvs and build artifacts
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 Full Documentation
|
||
|
||
- **[playbook.md](playbook.md)** - Complete command reference and operational guide
|
||
- **[tests/](tests/)** - Regression test suite documentation
|
||
|
||
---
|
||
|
||
## 🔒 Recommended Air-Gapped Setup
|
||
|
||
For maximum security when generating production wallets:
|
||
|
||
1. Use fresh Ubuntu Live USB or Tails OS
|
||
2. Never connect to network after booting
|
||
3. Transfer this repository via separate USB
|
||
4. Run `./install_offline.sh`
|
||
5. Generate wallet: `python src/pyhdwallet.py gen --off-screen --file`
|
||
6. Write mnemonic to paper/metal backup
|
||
7. Transfer encrypted ZIP to secure storage
|
||
8. Wipe USB drives securely
|
||
|
||
See [playbook.md](playbook.md) for detailed air-gapped procedures.
|