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:

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

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

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)

# 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

# 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)

# 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

# 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):

  # 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 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

---

<EFBFBD> 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

# 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 - Why JS can't zero memory and how SeedPGP defends
• RECOVERY_PLAYBOOK.md - Offline recovery instructions
• 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
• Security: Private disclosure via GitHub security advisory
• Recovery Help: See RECOVERY_PLAYBOOK.md

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