kccleoc/seedpgp-web
0
0
Fork 0
mirror of https://github.com/kccleoc/seedpgp-web.git synced 2026-03-07 01:47:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

security improvement and bugs fixing; modify makefile

Browse Source
This commit is contained in:
LC mac
2026-02-18 03:24:05 +08:00
parent 127b479f4f
commit 4da39b7b89
21 changed files with 52111 additions and 930 deletions
Download Patch File Download Diff File Expand all files Collapse all files

785
README.md
View File

@@ -2,418 +2,595 @@
**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.
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.
**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>
**Live Demo (Testing Only):** <https://seedpgp-web.pages.dev>
---
## 🚦 Quick Start — Bitcoin Beginners
## 🚦 Quick Start — Recommended TailsOS Workflow
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:
For **real funds** ($100+), follow this airgapped TailsOS workflow:
```bash
# 1. Boot TailsOS (airgapped - no network!)
# 2. Open Terminal and run:
git clone https://github.com/kccleoc/seedpgp-web.git
cd seedpgp-web
bun install
# 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
```
1. Build the offline bundle and serve it locally (recommended):
**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
```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
# 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
```
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)
### Testing & Verification
```bash
# 1. Clone and install
git clone https://github.com/kccleoc/seedpgp-web.git
cd seedpgp-web
bun install
# Verify TailsOS build integrity (CSP, checksums, paths)
make verify-tails
# 2. Run locally (offline)
bun run dev
# → Browser opens at http://localhost:5173
# → NO network traffic, everything stays local
# Verify offline compatibility
make verify-offline
# Run security audit
make audit
# Run test suite
make test
```
**Then proceed to "Using SeedPGP" below.**
### Local Servers
```bash
# Serve with Python HTTP server
make serve-local
# Serve with Bun server
make serve-bun
# Development mode (hot reload)
make dev
```
### Utility
```bash
# Clean build artifacts
make clean
# Show all available commands
make help
```
---
### Path B: Tails Airgapped Setup (Best for $10K+)
## 🛡️ Path 1: TailsOS Airgapped Setup (RECOMMENDED 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.
This is the **gold standard** for seed phrase management. Takes 30 minutes, provides maximum security.
#### Step 1: Get Tails
### 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
```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
# 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 Tails (Airgapped)
### Step 2: Boot TailsOS (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
# 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: Clone SeedPGP in Tails
### Step 3: Build SeedPGP on TailsOS
```bash
# Open Terminal in Tails
# (right-click desktop → Applications → System Tools → Terminal)
# 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 Bun (if first time)
curl -fsSL https://bun.sh/install | bash
# Install dependencies
make install
bun install
bun run dev
# → Copy http://localhost:5173 to browser address bar
# Build with security hardening
make full-build-tails
```
#### Step 4: Generate Backup (Next Section)
**What `make full-build-tails` does:**
All traffic is local only. When you shut down, everything is erased from RAM.
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:
```bash
✅ 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
```bash
# 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:**
```bash
# Stop server (Ctrl+C in Terminal)
# Shutdown TailsOS (Applications → Shutdown)
# ✅ All data erased from RAM
# ✅ No trace left on computer
```
---
### Path C: Cloud Browser (Testing Only)
## 🏠 Path 2: Local Offline Setup (Acceptable for <$10K)
For smaller amounts, you can run on a regular computer with network disabled.
```bash
# 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
```
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
```
**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: Enter Your Seed Phrase
### Step 1: Generate Entropy (New Seed)
**Do you have a seed phrase yet?**
SeedPGP offers multiple entropy sources you can combine:
- **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)
```bash
🎲 Dice Rolls - Physical randomness (99 rolls recommended)
🎥 Camera Noise - Visual entropy from textured surfaces
🎵 Audio Input - Microphone randomness from ambient sound
```
**How to use:**
**Recommended: Dice Rolls (Highest Trust)**
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.
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 & Backup Your Seed
### Step 2: Encrypt Your Seed
Now you'll encrypt the seed so only you can decrypt it.
**Option A: Password-Based Encryption (Simplest)**
#### Option A: Password Encryption (Simplest)
```
✅ Easiest to use
✅ Works anywhere (no dependencies)
⚠️ Password strength is critical
```bash
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
```
**Steps:**
**Option B: PGP Key Encryption (Most Secure)**
1. Your seed phrase is already visible
2. Enter a **strong password** (25+ characters recommended):
```bash
# Prerequisites: Have a PGP keypair (generate with GPG)
gpg --full-generate-key # Follow prompts
gpg --armor --export your-email@example.com > public.asc
```
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
# 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
```
**Do you have a PGP keypair?**
### Step 3: Test Recovery IMMEDIATELY
- **NO** → Generate one (outside this app):
**⚠️ DO NOT SKIP THIS STEP**
```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
```
```bash
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
```
- **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
**Why test?** Better to find a corrupt backup now than during an emergency.
---
### Step 3: Store Your Backups
### Step 4: Store Backups Securely
You now have:
- ✅ **Paper backup** (12/24 words written down)
- ✅ **QR code backup** (encrypted, can be scanned)
- ✅ **Paper seed** (12/24 words handwritten)
- ✅ **Encrypted QR code** (digital backup)
**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 |
| 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).
---
### Step 4: Test Your Recovery
## 🧪 Development & Testing
⚠️ **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
### Run Tests
```bash
# Run all tests
bun test
# All tests
make test
# Run integration tests (CSP, network, clipboard)
bun test:integration
# Individual test suites
bun test src/lib/bip39.test.ts
bun test src/lib/seedpgp.test.ts
bun test src/lib/krux.test.ts
```
**Test coverage:** 94+ tests covering BIP39, CRC16, Krux compatibility, CSP enforcement, network blocking, clipboard security, and session key management.
### Development Mode
```bash
# Hot reload development server
make dev
# With network blocking enabled by default
VITE_NETWORK_BLOCK=true make dev
```
### Security Auditing
```bash
# 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)
```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](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
- [MEMORY_STRATEGY.md](doc/MEMORY_STRATEGY.md) - Why JS can't zero memory, defense strategies
- [RECOVERY_PLAYBOOK.md](doc/RECOVERY_PLAYBOOK.md) - Offline recovery procedures
- [TAILS_OFFLINE_PLAYBOOK.md](doc/TAILS_OFFLINE_PLAYBOOK.md) - Complete TailsOS workflow
- [SeedPGP-Web-Forensic-Security-Report.pdf](doc/) - Independent security audit
---
## 🆘 Troubleshooting
### Build Issues
```bash
# 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
```bash
# 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
```bash
# 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 for details
**MIT License** - See LICENSE file
**⚠️ IMPORTANT DISCLAIMER:**
**⚠️ CRITICAL DISCLAIMER:**
```
CRYPTOGRAPHY IS HARD. USE AT YOUR OWN RISK.
CRYPTOCURRENCY SECURITY IS YOUR RESPONSIBILITY.
This software is provided as-is, without warranty.
This software is provided "AS IS", without warranty of any kind.
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
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
The author is not responsible for lost funds due to bugs,
user mistakes, or security breaches.
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
Your seed phrase = your cryptocurrency.
Guard it with your life.
If you don't understand how this works, start with $10 and test thoroughly.
```
---
## 🆘 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)
## 🙏 Credits & Security
**Author:** kccleoc
**Security Audited:** v1.4.4 (no exploits found)
**Security Audit:** v1.4.7 (February 2026) - No exploits found
**License:** MIT
**Report Security Issues:**
- Private disclosure via [GitHub Security Advisory](https://github.com/kccleoc/seedpgp-web/security)
- 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
```bash
# === 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.