seedpgp-web/README.md

# SeedPGP v1.4.7

**Secure BIP39 mnemonic backup using PGP encryption and QR codes**

A client-side web app for encrypting cryptocurrency seed phrases with OpenPGP and encoding them as QR-friendly Base45 frames with CRC16 integrity checking.

**Quick note for Bitcoin users (beginner-friendly):**

- This tool helps you securely back up your Bitcoin seed phrase (BIP39) by encrypting it with OpenPGP and giving you a compact QR-friendly export. You don't need to understand the internals to use it — follow the Quick Start below and test recovery immediately.
- If you are new to Bitcoin: write your seed phrase on paper, keep copies in separate secure locations, and consider using Tails for larger amounts.

**Live App:** <https://seedpgp-web.pages.dev>

---

## 🚦 Quick Start — Bitcoin Beginners

If you're new to Bitcoin, this short guide gets you from zero to a tested backup in a few minutes.

1. Clone the repo and install dependencies:

```bash
git clone https://github.com/kccleoc/seedpgp-web.git
cd seedpgp-web
bun install
```

1. Build the offline bundle and serve it locally (recommended):

```bash
make full-build-offline   # builds and verifies dist/
make serve-local         # start local HTTP server on http://localhost:8000
# or: bun run serve       # uses Bun server
```

1. Open your browser at `http://localhost:8000`, generate a seed, write it on paper, then encrypt/export using the app.

2. IMPORTANT: Test recovery immediately — import the backup into the app and confirm the seed matches.

Notes:

- Always store the written seed (paper) securely; treat it like cash.
- For larger amounts, follow the Tails air-gapped instructions in the `doc/TAILS_OFFLINE_PLAYBOOK.md` file.

---

## 💡 Safe Usage Guide: Choose Your Path

**Before you start**: How much are you backing up? This determines your setup.

| Your Fund Size | Recommended Setup | Time | Security |
|---|---|---|---|
| **Testing** (<$100) | Local on any device | 5 min | ✅ Good |
| **Medium** ($100–$10K) | Local on regular computer + paper backup | 15 min | ✅✅ Very Good |
| **Large** ($10K–$100K) | Tails (airgapped) + paper backup + duplicate key | 30 min | ✅✅✅ Excellent |
| **Vault** (>$100K) | Tails airgapped + hardware wallet + professional custody | 1+ hour | ✅✅✅✅ Fort Knox |

**Key principle**: The more funds at stake, the more setup friction you accept.

---

## 🚀 Getting Started (Choose Your Path)

### Path A: Simple Desktop Setup (Best for <$10K)

```bash
# 1. Clone and install
git clone https://github.com/kccleoc/seedpgp-web.git
cd seedpgp-web
bun install

# 2. Run locally (offline)
bun run dev
# → Browser opens at http://localhost:5173
# → NO network traffic, everything stays local
```

**Then proceed to "Using SeedPGP" below.**

---

### Path B: Tails Airgapped Setup (Best for $10K+)

**Why Tails?** Tails is a security-focused OS that runs in RAM, leaves no trace, and completely isolates your device from the internet.

#### Step 1: Get Tails

```bash
# On your primary computer:
# 1. Download Tails ISO from https://tails.net/install/
# 2. Verify signature (Tails provides fingerprint)
# 3. Burn to USB stick using Balena Etcher or similar
# 4. Keep this USB for seed operations only
```

#### Step 2: Boot Tails (Airgapped)

```bash
# 1. Insert Tails USB into target machine
# 2. Reboot and boot from USB (F12/ESC during startup)
# 3. Select "Start Tails" → runs from RAM, nothing written to disk
# 4. IMPORTANT: DO NOT connect to WiFi or Ethernet
#    - Unplug network cable
#    - Disable WiFi in BIOS
#    - Airplane mode ON
```

#### Step 3: Clone SeedPGP in Tails

```bash
# Open Terminal in Tails
# (right-click desktop → Applications → System Tools → Terminal)

git clone https://github.com/kccleoc/seedpgp-web.git
cd seedpgp-web

# Install Bun (if first time)
curl -fsSL https://bun.sh/install | bash

bun install
bun run dev

# → Copy http://localhost:5173 to browser address bar
```

#### Step 4: Generate Backup (Next Section)

All traffic is local only. When you shut down, everything is erased from RAM.

---

### Path C: Cloud Browser (Testing Only)

```
Open: https://seedpgp-web.pages.dev
⚠️  Use ONLY for testing with small amounts ($0–$100)
✅ CSP headers verified to block all external connections
⚠️  Still requires trusting Cloudflare infrastructure
```

---

## 🔐 Using SeedPGP: The Workflow

### Step 1: Enter Your Seed Phrase

**Do you have a seed phrase yet?**

- **YES** → Scroll to "Restore & Encrypt Existing Seed" below
- **NO** → Click "Seed Blender" button to generate one securely

#### Generate a New Seed (Seed Blender)

Seed Blender lets you mix entropy from multiple sources:

```
🎲 Dice rolls     (you control the randomness)
🎥 Camera noise   (uses camera pixels)
🎵 Audio input    (uses microphone randomness)
📋 Clipboard paste (combine multiple sources)
```

**How to use:**

1. Click **"Seed Blender"** button (left side)
2. Choose 1+ entropy sources (hint: more sources = more random)
3. For each source, follow on-screen instructions
   - Dice: Roll 50+ times, enter numbers
   - Camera: Point at random scene, let it capture
   - Audio: Make random sounds near microphone
   - Clipboard: Paste random text from outside sources
4. Click **"Generate Seed"**
5. **Your 12 or 24-word mnemonic appears** → Write it down RIGHT NOW on paper
6. Never share it. Ever. Treat like your password.

---

### Step 2: Encrypt & Backup Your Seed

Now you'll encrypt the seed so only you can decrypt it.

#### Option A: Password Encryption (Simplest)

```
✅ Easiest to use
✅ Works anywhere (no dependencies)
⚠️  Password strength is critical
```

**Steps:**

1. Your seed phrase is already visible
2. Enter a **strong password** (25+ characters recommended):

   ```
   Example: Tr0picM0nkey$Orange#2024!Secret
   ```

3. Choose encryption:
   - **PGP** → Uses OpenPGP (skip to next section if you have a PGP key)
   - **Password** → Simple AES-256 encryption
4. Click **"Generate QR Backup"**
5. **Screenshot or print the QR code** → Store in secure location
6. Test immediately: Scan → Decrypt with your password → Verify it matches

---

#### Option B: PGP Key Encryption (Most Secure)

```
✅ Most secure (multi-factor: key + passphrase)
✅ Works across devices/services that support PGP
⚠️  More steps, requires PGP knowledge
```

**Do you have a PGP keypair?**

- **NO** → Generate one (outside this app):

  ```bash
  # Using GPG (Linux/Mac)
  gpg --full-generate-key
  # Follow prompts for RSA-4096, expiration, passphrase
  
  # Export public key (to use in SeedPGP)
  gpg --armor --export your-email@example.com > public.asc
  ```

- **YES** → Upload in SeedPGP:
  1. Click **"PGP Key Input"** (top left)
  2. Paste your **public key** (`.asc` file)
  3. SeedPGP shows key fingerprint (verify it's yours)
  4. Click **"Use This Key"**
  5. Click **"Generate QR Backup"**
  6. **Screenshot or print the QR code**
  7. Test: Scan → Provide your private key + passphrase → Verify

---

### Step 3: Store Your Backups

You now have:

- ✅ **Paper backup** (12/24 words written down)
- ✅ **QR code backup** (encrypted, can be scanned)

**Storage strategy:**

| What | Where | Why |
|---|---|---|
| **Seed paper** | Safe deposit box OR home safe | Original source of truth |
| **QR code** | Multiple physical locations (home, office, safety box) | Can recover without trusting paper |
| **PGP private key** (if used) | Offline storage, encrypted | Needed to restore from QR |
| **Password** (if used) | Your password manager (encrypted) | Needed to restore from QR |

---

### Step 4: Test Your Recovery

⚠️ **CRITICAL**: Do this immediately after backup.

```
1. Scan or upload the QR code
   → Click "QR Scanner" button
   → Use camera or upload image

2. Provide decryption method:
   - Option A: Paste your password
   - Option B: Upload private key + enter passphrase

3. Mnemonic appears for 10 seconds
   → **Verify it matches your original seed exactly**
   → Screenshot is auto-cleared (security feature)
   → If mismatch → ⚠️ DO NOT USE, troubleshoot

4. Clear manually:
   → Click "Hide/Clear" button
   → Mnemonic erased from memory
```

**Why test?** Better to discover a corrupt backup NOW than in an emergency.

---

### Step 5: Import Into Your Wallet

**When you're ready to move money:**

1. Open your cryptocurrency wallet (Ledger, MetaMask, Electrum, etc.)
2. Look for "Import Seed" or "Restore Wallet" option
3. Enter your 12 or 24-word mnemonic
4. Wallet imports all your addresses
5. **Send a test transaction** (tiny amount) first
6. Verify address matches

**That's it.** Your funds are now controlled by this seed phrase.

---

## 🛡️ Threat Model & Limitations

See [MEMORY_STRATEGY.md](doc/MEMORY_STRATEGY.md) for comprehensive explanation of what SeedPGP protects against and what it can't.

**TL;DR - Real risks are:**

| Threat | Mitigation |
|--------|-----------|
| **Browser extensions stealing data** | Use dedicated browser, disable all extensions |
| **Your device gets hacked** | Use Tails (airgapped), hardware wallet for large amounts |
| **You forget your password** | Store in password manager or offline |
| **You lose all copies of backup** | Keep multiple geographically distributed copies |
| **Someone reads your paper backup** | Use physical security (safe, safe deposit box) |
| **Recovery fails when you need it** | TEST IMMEDIATELY after creating backup |

**What SeedPGP DOES protect:**

- ✅ All traffic blocked at CSP level (browser enforcement)
- ✅ Network APIs patched as redundancy
- ✅ Clipboard tracked and auto-cleared
- ✅ Storage monitored for leaks
- ✅ Session keys encrypted, destroyed on page close

---

## <20> Security Features & Architecture

**Encryption:**

- **OpenPGP.js** with AES-256 (standard OpenPGP encryption)
- **Session Keys:** Web Crypto API AES-GCM-256 (extractable: false)
- **Key Derivation:** PBKDF2 (password-based keys)
- **Integrity:** CRC16-CCITT-FALSE checksums (detects file corruption)
- **Encoding:** Base45 (RFC 9285) for QR compatibility

**Browser Security (Defense-in-Depth):**

- **CSP headers:** `connect-src 'none'` (blocks all external connections at browser level)
- **Network API patching:** Fetch, XMLHttpRequest, WebSocket, Image.src all blocked
- **Clipboard monitoring:** Auto-clear sensitive data after 10 seconds
- **Storage auditing:** Real-time localStorage/sessionStorage tracking
- **Session destruction:** Keys auto-destroyed on page close

**Why this matters:** Even if you clone SeedPGP into your computer, it still CAN'T send your seed to the internet. CSP + patching = belt and suspenders.

---

## 🏆 Best Practices Summary

1. **For Testing (<$100):** Use any setup, test everything
2. **For Real Use ($100+):** Run locally on clean computer with internet disabled
3. **For Large Amounts ($10K+):** Use Tails airgapped USB
4. **For Vault Amounts (>$100K):** Tails + hardware wallet + professional advice

**Remember:**

- Write down your seed on **paper** → store securely
- Test recovery **immediately** after backup
- Keep **multiple copies** in different locations geographically
- Treat your seed like your passwords
- Your device security is more important than the app

---

## 🧪 Testing

```bash
# Run all tests
bun test

# Run integration tests (CSP, network, clipboard)
bun test:integration
```

**Test coverage:** 94+ tests covering BIP39, CRC16, Krux compatibility, CSP enforcement, network blocking, clipboard security, and session key management.

---

## 📖 Technical Documentation

- [MEMORY_STRATEGY.md](doc/MEMORY_STRATEGY.md) - Why JS can't zero memory and how SeedPGP defends
- [RECOVERY_PLAYBOOK.md](doc/RECOVERY_PLAYBOOK.md) - Offline recovery instructions
- [SECURITY_AUDIT_REPORT.md](doc/SECURITY_AUDIT_REPORT.md) - Full audit findings

---

## ⚖️ License & Disclaimer

**MIT License** - See LICENSE for details

**⚠️ IMPORTANT DISCLAIMER:**

```
CRYPTOGRAPHY IS HARD. USE AT YOUR OWN RISK.

This software is provided as-is, without warranty.

1. Test with small amounts before trusting with real funds
2. Verify recovery works immediately after backup
3. Keep multiple geographically distributed copies
4. Your device security matters more than app security
5. For amounts >$100K, consult professional security advice

The author is not responsible for lost funds due to bugs,
user mistakes, or security breaches.

Your seed phrase = your cryptocurrency.
Guard it with your life.
```

---

## 🆘 Support & Security

- **Issues:** [GitHub Issues](https://github.com/kccleoc/seedpgp-web/issues)
- **Security:** Private disclosure via GitHub security advisory
- **Recovery Help:** See [RECOVERY_PLAYBOOK.md](doc/RECOVERY_PLAYBOOK.md)

**Author:** kccleoc  
**Security Audited:** v1.4.4 (no exploits found)