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. Designed for offline use on TailsOS with built-in security verification.

Live Demo (Testing Only): https://seedpgp-web.pages.dev

---

🚦 Quick Start — Recommended TailsOS Workflow

For real funds ($100+), follow this airgapped TailsOS workflow:

# 1. Boot TailsOS (airgapped - no network!)
# 2. Open Terminal and run:
git clone https://github.com/kccleoc/seedpgp-web.git
cd seedpgp-web

# 3. Build and verify (single command)
make full-build-tails

# 4. Serve locally in Tor Browser
make serve-local
# → Open http://localhost:8000 in Tor Browser

That's it. The Makefile handles everything: build, CSP injection, integrity verification, and security auditing.

---

💡 Security-First Usage Guide

Your Fund Size	Recommended Setup	Build Command	Time
Testing (<$100)	Any computer, local mode	make build-offline	5 min
Real Use ($100–$10K)	Clean computer, network disabled	make build-offline	15 min
Serious ($10K–$100K)	TailsOS airgapped	make full-build-tails	30 min
Vault (>$100K)	TailsOS + hardware wallet + multisig	make full-build-tails	1+ hour

The more funds at stake, the more security precautions you take.

---

🔧 Makefile Commands Reference

Core Build Commands

# Install dependencies
make install

# Build for Cloudflare Pages (production)
make build

# Build for offline local testing
make build-offline

# Build for TailsOS with embedded CSP + integrity checks
make build-tails

# Full TailsOS pipeline (recommended for real use)
make full-build-tails

Testing & Verification

# Verify TailsOS build integrity (CSP, checksums, paths)
make verify-tails

# Verify offline compatibility
make verify-offline

# Run security audit
make audit

# Run test suite
make test

Local Servers

# Serve with Python HTTP server
make serve-local

# Serve with Bun server
make serve-bun

# Development mode (hot reload)
make dev

Utility

# Clean build artifacts
make clean

# Show all available commands
make help

---

🛡️ Path 1: TailsOS Airgapped Setup (RECOMMENDED for $10K+)

This is the gold standard for seed phrase management. Takes 30 minutes, provides maximum security.

Why TailsOS?

• Amnesic: Runs entirely in RAM, leaves no trace on disk
• Airgapped: You physically disconnect from all networks
• Isolated: Browser can't access persistent storage
• Audited: Open-source OS trusted by journalists and activists

Step 1: Prepare TailsOS USB

# On your primary computer:

# 1. Download Tails ISO
# Visit: https://tails.net/install/
# Download latest version (verify signature!)

# 2. Burn to USB stick
# Use Balena Etcher or dd command
# Minimum 8GB USB required

# 3. Label this USB "TAILS SEED OPS"
# Keep separate from daily-use USBs

Step 2: Boot TailsOS (Airgapped)

# Physical security checklist:
□ Unplug Ethernet cable from computer
□ Disable WiFi in BIOS (if possible)
□ Put phone in airplane mode (away from desk)
□ Close curtains (prevent shoulder surfing)

# Boot process:
1. Insert TailsOS USB
2. Reboot computer
3. Press F12/ESC/DEL to enter boot menu
4. Select USB drive
5. Choose "Start Tails"
6. ⚠️ DO NOT configure WiFi when prompted
7. Verify network icon shows "disconnected"

Step 3: Build SeedPGP on TailsOS

# Open Terminal (Applications → System Tools → Terminal)

# Install Bun (first time only)
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

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

# Install dependencies
make install

# Build with security hardening
make full-build-tails

What make full-build-tails does:

1. Cleans all previous build artifacts
2. Builds with relative paths for offline use
3. Injects CSP meta tag directly into HTML
4. Creates dist-tails/ directory with:
   • Complete app bundle
   • README.txt with SHA-256 checksums
   • Security documentation
5. Verifies CSP enforcement, relative paths, integrity
6. Audits for network calls, external URLs, security issues

Step 4: Verify Build Integrity

The build process automatically verifies:

✅ CSP enforces connect-src 'none' (all network calls blocked)
✅ Relative paths detected (offline compatible)
✅ No suspicious external domains
ℹ️  fetch() references exist in bundle (from openpgp.js)
✓  These are BLOCKED by CSP connect-src 'none' at runtime
✅ TailsOS build verification complete

Security Note: fetch() and XMLHttpRequest references exist in the bundle (from OpenPGP.js library code), but they are completely blocked by CSP connect-src 'none' at the browser level. The verification confirms CSP enforcement, not the absence of dead code.

Step 5: Serve Locally in Tor Browser

# Start local HTTP server
make serve-local

# Output:
# 🚀 Starting local server at http://localhost:8000
#    Press Ctrl+C to stop

Open Tor Browser (pre-installed in TailsOS):

1. Launch Tor Browser from desktop
2. Navigate to: http://localhost:8000
3. App loads — all processing happens locally
4. Verify "Network BLOCKED" indicator in app header

Step 6: Use SeedPGP Securely

Now proceed to "Using SeedPGP" section below. All entropy generation, encryption, and QR generation happens offline in your browser's memory.

When finished:

# Stop server (Ctrl+C in Terminal)
# Shutdown TailsOS (Applications → Shutdown)
# ✅ All data erased from RAM
# ✅ No trace left on computer

---

🏠 Path 2: Local Offline Setup (Acceptable for <$10K)

For smaller amounts, you can run on a regular computer with network disabled.

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

# Install dependencies
make install

# Build for offline use
make full-build-offline

# Disconnect network NOW:
# - Unplug Ethernet
# - Disable WiFi
# - Airplane mode ON

# Serve locally
make serve-local

# Open browser: http://localhost:8000

Security vs TailsOS:

Feature	Local Offline	TailsOS Airgapped
RAM-only execution	❌ No	✅ Yes
Disk trace	⚠️ Possible	✅ None
Extension isolation	⚠️ Manual	✅ Automatic
Memory dump protection	❌ Limited	✅ Strong
Best for	Testing, <$10K	$10K+, serious use

---

🔐 Using SeedPGP: The Workflow

Step 1: Generate Entropy (New Seed)

SeedPGP offers multiple entropy sources you can combine:

🎲 Dice Rolls    - Physical randomness (99 rolls recommended)
🎥 Camera Noise  - Visual entropy from textured surfaces
🎵 Audio Input   - Microphone randomness from ambient sound

Recommended: Dice Rolls (Highest Trust)

1. Click "Create" tab → "Dice Rolls"
2. Roll physical dice 99 times
3. Enter each result (1-6)
4. App shows entropy progress bar
5. Click "Generate Seed"
6. Your 12 or 24-word mnemonic appears

⚠️ CRITICAL: Write down seed phrase on paper RIGHT NOW. Don't trust digital storage.

Step 2: Encrypt Your Seed

Option A: Password-Based Encryption (Simplest)

1. Your seed phrase is visible in the textarea
2. Enter a strong password (25+ characters):
   Example: "Tr0pic!M0nkey$Orange#2024@Secret%Phrase"
3. Confirm password
4. Click "Generate QR Backup"
5. Screenshot or print the QR code

Option B: PGP Key Encryption (Most Secure)

# Prerequisites: Have a PGP keypair (generate with GPG)
gpg --full-generate-key  # Follow prompts
gpg --armor --export your-email@example.com > public.asc

# In SeedPGP:
1. Click "PGP Key Input"
2. Paste your public key
3. App shows fingerprint → verify it matches
4. Click "Use This Key"
5. Click "Generate QR Backup"
6. Save QR code securely

Step 3: Test Recovery IMMEDIATELY

⚠️ DO NOT SKIP THIS STEP

1. Click "Restore" tab
2. Scan or upload your QR backup
3. Enter password OR provide private key
4. Verify decrypted seed matches original
5. If mismatch → ⚠️ DO NOT USE, redo backup

Why test? Better to find a corrupt backup now than during an emergency.

Step 4: Store Backups Securely

You now have:

• ✅ Paper seed (12/24 words handwritten)
• ✅ Encrypted QR code (digital backup)

Storage strategy:

Item	Location	Redundancy
Paper seed	Safe deposit box	Primary copy
Paper seed copy 2	Home safe	Backup copy
QR code	USB drive in safe	Digital recovery
QR code copy 2	Cloud storage (encrypted!)	Disaster recovery
Password/PGP key	Password manager	Encrypted separately

Geographic distribution: Keep copies in different physical locations (home, office, bank vault).

---

🧪 Development & Testing

Run Tests

# All tests
make test

# Individual test suites
bun test src/lib/bip39.test.ts
bun test src/lib/seedpgp.test.ts
bun test src/lib/krux.test.ts

Development Mode

# Hot reload development server
make dev

# With network blocking enabled by default
VITE_NETWORK_BLOCK=true make dev

Security Auditing

# Full security audit
make audit

# Output includes:
# - CSP configuration check
# - Network API usage analysis
# - Persistent storage detection
# - eval()/Function() detection
# - Defense-in-depth layer summary

---

🏗️ Build Artifacts Explained

make build-tails Output

dist-tails/
├── index.html          # CSP injected, relative paths
├── assets/
│   ├── index-*.js     # Main bundle (minified)
│   ├── index-*.css    # Styles
│   └── secp256k1.wasm # Crypto library
└── README.txt         # SHA-256 checksums + usage instructions

CSP Configuration (Embedded in HTML)

<meta http-equiv="Content-Security-Policy" 
      content="default-src 'self'; 
               script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval'; 
               style-src 'self' 'unsafe-inline'; 
               img-src 'self' data: blob:; 
               connect-src 'none'; 
               font-src 'self'; 
               object-src 'none'; 
               base-uri 'self'; 
               form-action 'none';" 
      data-env="tails">

Key directive: connect-src 'none' — Browser refuses ALL network requests (fetch, XHR, WebSocket, etc.)

---

🛡️ Security Architecture

Defense-in-Depth Layers

Layer	Mechanism	Bypassable?	Purpose
1. CSP	connect-src 'none' in HTML	❌ No (browser enforced)	PRIMARY DEFENSE
2. Network Blocker	JS patches window.fetch/XHR	✅ Yes (console bypass)	Defense-in-depth
3. Airgapped OS	TailsOS, no network drivers	❌ No (physical isolation)	Ultimate isolation
4. Session Crypto	AES-256-GCM, non-exportable	⚠️ Memory dumps	Protects cached data
5. Auto-Clear	10s clipboard wipe	✅ Yes (user can cancel)	Reduces exposure window

Primary Security: CSP + TailsOS = two independent layers that must BOTH fail for compromise.

Threat Model

What SeedPGP Protects Against:

✅ Browser extensions stealing seed
✅ Malicious websites accessing clipboard
✅ Network exfiltration attempts
✅ Accidental data leaks to localStorage
✅ Session replay attacks

What SeedPGP CANNOT Protect Against:

❌ Compromised TailsOS ISO (verify signatures!)
❌ Hardware keyloggers
❌ Evil maid attacks (physical device tampering)
❌ Memory dumps from privileged malware
❌ Social engineering (phishing for password)

Mitigation: Use TailsOS (verified ISO) + physical security + test recovery immediately.

---

📖 Technical Documentation

• MEMORY_STRATEGY.md - Why JS can't zero memory, defense strategies
• RECOVERY_PLAYBOOK.md - Offline recovery procedures
• TAILS_OFFLINE_PLAYBOOK.md - Complete TailsOS workflow
• SeedPGP-Web-Forensic-Security-Report.pdf - Independent security audit

---

🆘 Troubleshooting

Build Issues

# Permission denied during build
sudo chmod +x Makefile
make clean && make install

# Bun not found
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

# CSP not embedded
make clean build-tails
grep "Content-Security-Policy" dist-tails/index.html

TailsOS Issues

# Can't access localhost:8000
# → Check firewall: sudo ufw allow 8000
# → Use 127.0.0.1:8000 instead

# Bun installation fails
# → TailsOS persistence required
# → Use temporary session, re-install each boot

# Camera/microphone not working
# → TailsOS may block by default
# → Use dice rolls instead (recommended anyway)

Recovery Issues

# QR scan fails
# → Ensure good lighting, steady camera
# → Upload image file instead of scanning

# Decryption fails
# → Verify password exactly matches
# → Check PGP key fingerprint
# → QR may be damaged → test backup immediately after creation!

---

⚖️ License & Disclaimer

MIT License - See LICENSE file

⚠️ CRITICAL DISCLAIMER:

CRYPTOCURRENCY SECURITY IS YOUR RESPONSIBILITY.

This software is provided "AS IS", without warranty of any kind.

1. TEST with small amounts ($1-10) before trusting with real funds
2. VERIFY recovery works immediately after creating backup
3. STORE multiple copies in geographically distributed locations
4. USE TailsOS for amounts > $10K
5. CONSULT professional security advice for amounts > $100K

Your seed phrase = your funds. Lose the seed = lose the funds.
The author is NOT responsible for:
- Lost funds due to bugs, user error, or hardware failure
- Compromised devices or insecure storage
- Forgotten passwords or lost backups

If you don't understand how this works, start with $10 and test thoroughly.

---

🙏 Credits & Security

Author: kccleoc
Security Audit: v1.4.7 (February 2026) - No exploits found
License: MIT

Report Security Issues:

• Private disclosure via GitHub Security Advisory
• For urgent issues: Encrypt with PGP key in repository

Dependencies Audited:

• OpenPGP.js v5.11+
• BIP39 reference implementation
• jsQR for QR scanning
• secp256k1 WASM module

---

🚀 Quick Reference Card

# === PRODUCTION WORKFLOW (TailsOS) ===
make full-build-tails    # Build + verify + audit
make serve-local         # Serve on localhost:8000

# === DEVELOPMENT ===
make dev                 # Hot reload
make test                # Run tests
make audit               # Security audit

# === VERIFICATION ===
make verify-tails        # Check CSP, checksums, paths
grep "connect-src" dist-tails/index.html  # Manual CSP check

# === CLEANUP ===
make clean               # Remove all build artifacts

Remember: More funds = more security steps. Don't skip TailsOS for serious amounts.