From 9cc74005f226b2eaea59c10190189ca5e5b7a7fd Mon Sep 17 00:00:00 2001 From: LC mac Date: Thu, 12 Feb 2026 23:33:19 +0800 Subject: [PATCH] docs: Rewrite README with practical usage guide and risk-balanced setup instructions --- README.md | 807 ++++++++++++++++++++++-------------------------------- 1 file changed, 323 insertions(+), 484 deletions(-) diff --git a/README.md b/README.md index 87f055e..19da9dc 100644 --- a/README.md +++ b/README.md @@ -8,537 +8,376 @@ A client-side web app for encrypting cryptocurrency seed phrases with OpenPGP an --- -## ✨ Quick Start +## πŸ’‘ Safe Usage Guide: Choose Your Path -### πŸ”’ Backup Your Seed (in 30 seconds) +**Before you start**: How much are you backing up? This determines your setup. -1. **Run locally** (recommended for maximum security): +| 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 | - ```bash - git clone https://github.com/kccleoc/seedpgp-web.git - cd seedpgp-web - bun install - bun run dev - # Open http://localhost:5173 - ``` - -2. **Enter your 12/24-word BIP39 mnemonic** - -3. **Choose encryption method**: - - **Option A**: Upload your PGP public key (`.asc` file or paste) - - **Option B**: Set a strong password (AES-256 encryption) - -4. **Click "Generate QR Backup"** β†’ Save/print the QR code - -### πŸ”“ Restore Your Seed - -1. **Scan the QR code** (camera or upload image) - -2. **Provide decryption key**: - - PGP private key + passphrase (if using PGP) - - Password (if using password encryption) - -3. **Mnemonic appears for 10 seconds** β†’ auto-clears for security +**Key principle**: The more funds at stake, the more setup friction you accept. --- -## πŸ›‘οΈ Explicit Threat Model Documentation +## πŸš€ Getting Started (Choose Your Path) -### 🎯 What SeedPGP Protects Against (Security Guarantees) - -SeedPGP is designed to protect against specific threats when used correctly: - -| Threat | Protection | Implementation Details | -|--------|------------|------------------------| -| **Accidental browser storage** | Real-time monitoring & alerts for localStorage/sessionStorage | StorageDetails component shows all browser storage activity | -| **Clipboard exposure** | Clipboard tracking with warnings and history clearing | ClipboardDetails tracks all copy operations, shows what/when | -| **Network leaks** | Strict CSP headers blocking ALL external requests | Cloudflare Pages enforces CSP: `default-src 'self'; connect-src 'none'` | -| **Wrong-key usage** | Key fingerprint validation prevents wrong-key decryption | OpenPGP.js validates recipient fingerprints before decryption | -| **QR corruption** | CRC16-CCITT-FALSE checksum detects scanning/printing errors | Frame format includes 4-digit hex CRC for integrity verification | -| **Memory persistence** | Session-key encryption with auto-clear timers | AES-GCM-256 session keys, 10-second auto-clear for restored mnemonics | -| **Shoulder surfing** | Read-only mode blurs sensitive data, disables inputs | Toggle blurs content, disables form inputs, prevents clipboard operations | - -### ⚠️ **Critical Limitations & What SeedPGP CANNOT Protect Against** - -**IMPORTANT: Understand these limitations before trusting SeedPGP with significant funds:** - -| Threat | Reason | Recommended Mitigation | -|--------|--------|-----------------------| -| **Browser extensions** | Malicious extensions can read DOM, memory, keystrokes | Use dedicated browser with all extensions disabled; consider browser isolation | -| **Memory analysis** | JavaScript cannot force immediate memory wiping; strings may persist in RAM | Use airgapped device, reboot after use, consider hardware wallets | -| **XSS attacks** | If hosting server is compromised, malicious JS could be injected | Host locally from verified source, use Subresource Integrity (SRI) checks | -| **Hardware keyloggers** | Physical device compromise at hardware/firmware level | Use trusted hardware, consider hardware wallets for large amounts | -| **Supply chain attacks** | Compromised dependencies (OpenPGP.js, React, etc.) | Audit dependencies regularly, verify checksums, consider reproducible builds | -| **Quantum computers** | Future threat to current elliptic curve cryptography | Store encrypted backups physically, rotate periodically, monitor crypto developments | -| **Browser bugs/exploits** | Zero-day vulnerabilities in browser rendering engine | Keep browsers updated, use security-focused browsers (Brave, Tor) | -| **Screen recording** | Malware or built-in OS screen recording | Use privacy screens, be aware of surroundings during sensitive operations | -| **Timing attacks** | Potential side-channel attacks on JavaScript execution | Use constant-time algorithms where possible, though limited in browser context | - -### πŸ”¬ Technical Security Architecture - -**Encryption Stack:** - -- **PGP Encryption:** OpenPGP.js with AES-256 (OpenPGP standard) -- **Session Keys:** Web Crypto API AES-GCM-256 with `extractable: false` -- **Key Derivation:** PBKDF2 for password-based keys (when used) -- **Integrity:** CRC16-CCITT-FALSE checksums on all frames -- **Encoding:** Base45 (RFC 9285) for QR-friendly representation - -**Memory Management Limitations:** - -- JavaScript strings are immutable and may persist in memory after "clearing" -- Garbage collection timing is non-deterministic and implementation-dependent -- Browser crash dumps may contain sensitive data in memory -- The best practice is to minimize exposure time and use airgapped devices - -**Detailed Memory & Encryption Strategy:** See [MEMORY_STRATEGY.md](MEMORY_STRATEGY.md) for comprehensive documentation on: - -- Why JavaScript cannot guarantee memory zeroing -- How SeedPGP's defense-in-depth approach mitigates memory risks -- Optional React hook (`useEncryptedState`) for encrypting component state -- Testing & validation procedures -- Future enhancement recommendations - -### πŸ† Best Practices for Maximum Security - -1. **Airgapped Workflow** (Recommended for large amounts): - - ``` - [Online Device] β†’ Generate PGP keypair β†’ Export public key - [Airgapped Device] β†’ Run SeedPGP locally β†’ Encrypt with public key - [Airgapped Device] β†’ Print QR code β†’ Store physically - [Online Device] β†’ Never touches private key or plaintext seed - ``` - -2. **Local Execution** (Next best): - - ```bash - # Clone and run offline - git clone https://github.com/kccleoc/seedpgp-web.git - cd seedpgp-web - bun install - # Disable network, then run - bun run dev -- --host 127.0.0.1 - ``` - -3. **Cloudflare Pages** (Convenient but trust required): - - βœ… Real CSP enforcement (blocks network at browser level) - - βœ… Security headers (X-Frame-Options, X-Content-Type-Options) - - ⚠️ Trusts Cloudflare infrastructure - - ⚠️ Requires HTTPS connection - ---- - -## πŸ“š Simple Usage Examples - -### Example 1: Password-only Encryption (Simplest) - -```typescript -import { encryptToSeed, decryptFromSeed } from "./lib/seedpgp"; - -// Backup with password -const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"; -const result = await encryptToSeed({ - plaintext: mnemonic, - messagePassword: "MyStrongPassword123!", -}); - -console.log(result.framed); // "SEEDPGP1:0:ABCD:BASE45DATA..." - -// Restore with password -const restored = await decryptFromSeed({ - frameText: result.framed, - messagePassword: "MyStrongPassword123!", -}); - -console.log(restored.w); // Original mnemonic -``` - -### Example 2: PGP Key Encryption (More Secure) - -```typescript -import { encryptToSeed, decryptFromSeed } from "./lib/seedpgp"; - -const publicKey = `-----BEGIN PGP PUBLIC KEY BLOCK----- -... your public key here ... ------END PGP PUBLIC KEY BLOCK-----`; - -const privateKey = `-----BEGIN PGP PRIVATE KEY BLOCK----- -... your private key here ... ------END PGP PRIVATE KEY BLOCK-----`; - -// Backup with PGP key -const result = await encryptToSeed({ - plaintext: mnemonic, - publicKeyArmored: publicKey, -}); - -// Restore with PGP key -const restored = await decryptFromSeed({ - frameText: result.framed, - privateKeyArmored: privateKey, - privateKeyPassphrase: "your-key-password", -}); -``` - -### Example 3: Krux-Compatible Encryption (Hardware Wallet Users) - -```typescript -import { encryptToSeed, decryptFromSeed } from "./lib/seedpgp"; - -// Krux mode uses passphrase-only encryption -const result = await encryptToSeed({ - plaintext: mnemonic, - messagePassword: "MyStrongPassphrase", - mode: 'krux', - kruxLabel: 'Main Wallet Backup', - kruxIterations: 200000, -}); - -// Hex format compatible with Krux firmware -console.log(result.framed); // Hex string starting with KEF: -``` - ---- - -## πŸ”§ Installation & Development - -### Prerequisites - -- [Bun](https://bun.sh) v1.3.6+ (recommended) or Node.js 18+ -- Git - -### Quick Install +### Path A: Simple Desktop Setup (Best for <$10K) ```bash -# Clone and install +# 1. Clone and install git clone https://github.com/kccleoc/seedpgp-web.git cd seedpgp-web bun install -# Run tests -bun test - -# Start development server +# 2. Run locally (offline) bun run dev -# Open http://localhost:5173 +# β†’ Browser opens at http://localhost:5173 +# β†’ NO network traffic, everything stays local ``` -### Production Build +**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 -bun run build # Build to dist/ -bun run preview # Preview production build +# 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 ``` ---- - -## πŸ” Advanced Security Features - -### Session-Key Encryption - -- **AES-GCM-256** ephemeral keys for in-memory protection -- Auto-destroys on tab close/navigation -- Manual lock/clear button for immediate wiping - -### Storage Monitoring - -- Real-time tracking of localStorage/sessionStorage -- Alerts for sensitive data detection -- Visual indicators of storage usage - -### Clipboard Protection - -- Tracks all copy operations -- Shows what was copied and when -- One-click history clearing - -### Read-Only Mode - -- Blurs all sensitive data -- Disables all inputs -- Prevents clipboard operations -- Perfect for demonstrations or shared screens - ---- - -## πŸ“– API Reference - -### Core Functions - -#### `encryptToSeed(params)` - -Encrypts a mnemonic to SeedPGP format. - -```typescript -interface EncryptionParams { - plaintext: string | SeedPgpPlaintext; // Mnemonic or plaintext object - publicKeyArmored?: string; // PGP public key (optional) - messagePassword?: string; // Password (optional) - mode?: 'pgp' | 'krux'; // Encryption mode - kruxLabel?: string; // Label for Krux mode - kruxIterations?: number; // PBKDF2 iterations for Krux -} - -const result = await encryptToSeed({ - plaintext: "your mnemonic here", - messagePassword: "optional-password", -}); -// Returns: { framed: string, pgpBytes?: Uint8Array, recipientFingerprint?: string } -``` - -#### `decryptFromSeed(params)` - -Decrypts a SeedPGP frame. - -```typescript -interface DecryptionParams { - frameText: string; // SEEDPGP1 frame or KEF hex - privateKeyArmored?: string; // PGP private key (optional) - privateKeyPassphrase?: string; // Key password (optional) - messagePassword?: string; // Message password (optional) - mode?: 'pgp' | 'krux'; // Encryption mode -} - -const plaintext = await decryptFromSeed({ - frameText: "SEEDPGP1:0:ABCD:...", - messagePassword: "your-password", -}); -// Returns: SeedPgpPlaintext { v: 1, t: "bip39", w: string, l: "en", pp: number } -``` - -### Frame Format - -``` -SEEDPGP1:FRAME:CRC16:BASE45DATA -β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”¬β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ - Protocol & Frame CRC16 Base45-encoded - Version Number Check PGP Message - -Examples: -β€’ SEEDPGP1:0:ABCD:J9ESODB... # Single frame -β€’ KEF:0123456789ABCDEF... # Krux Encryption Format (hex) -``` - ---- - -## πŸš€ Deployment Options - -### Option 1: Localhost (Most Secure) +#### Step 2: Boot Tails (Airgapped) ```bash -# Run on airgapped machine -bun run dev -- --host 127.0.0.1 -# Browser only connects to localhost, no external traffic +# 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 ``` -### Option 2: Self-Hosted (Balanced) +#### Step 3: Clone SeedPGP in Tails -- Build: `bun run build` -- Serve `dist/` via NGINX/Apache with HTTPS -- Set CSP headers (see `public/_headers`) +```bash +# Open Terminal in Tails +# (right-click desktop β†’ Applications β†’ System Tools β†’ Terminal) -### Option 3: Cloudflare Pages (Convenient) +git clone https://github.com/kccleoc/seedpgp-web.git +cd seedpgp-web -- Auto-deploys from GitHub -- Built-in CDN and security headers -- [seedpgp-web.pages.dev](https://seedpgp-web.pages.dev) +# 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. --- -## πŸ§ͺ Testing & Verification +### Path C: Cloud Browser (Testing Only) -### Test Suite +``` +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](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 + +--- + +## οΏ½ 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 (unit + integration) +# Run all tests bun test -# Run only unit tests -bun test src/**/*.test.ts - # Run integration tests (CSP, network, clipboard) bun test:integration - -# Run specific test categories -bun test --test-name-pattern="Trezor" # BIP39 test vectors -bun test --test-name-pattern="CRC" # Integrity checks -bun test --test-name-pattern="Krux" # Krux compatibility -bun test --test-name-pattern="CSP Enforcement" # Security policy tests - -# Watch mode (development) -bun test --watch ``` -### Test Coverage - -- βœ… **20+ comprehensive tests** including security and edge cases -- βœ… **8 official Trezor BIP39 test vectors** -- βœ… **CRC16 integrity validation** (corruption detection) -- βœ… **CSP enforcement tests** (restrictive headers verified) -- βœ… **Network blocking tests** (all 5 network API mechanisms) -- βœ… **Clipboard security tests** (auto-clear, event tracking) -- βœ… **Session key rotation tests** (time + operation limits) -- βœ… **Wrong key/password** rejection testing - -### Integration Tests - -Security-focused integration tests verify: - -**CSP Enforcement** ([src/integration.test.ts](src/integration.test.ts)) - -- Restrictive CSP headers present in HTML -- `connect-src 'none'` blocks all external connections -- `script-src 'self'` prevents external script injection -- Additional security headers (X-Frame-Options, X-Content-Type-Options) - -**Network Blocking** ([src/integration.test.ts](src/integration.test.ts)) - -- User-controlled network toggle blocks 5 API mechanisms: - 1. Fetch API - 2. XMLHttpRequest - 3. WebSocket - 4. Beacon API - 5. Image external resources - 6. Service Worker registration - -**Clipboard Behavior** ([src/integration.test.ts](src/integration.test.ts)) - -- Sensitive field detection (mnemonic, seed, password, private, key) -- Auto-clear after 10 seconds with random garbage -- Clipboard event audit trail tracking -- Warning alerts for sensitive data copies - -**Session Key Management** ([src/integration.test.ts](src/integration.test.ts)) - -- Key rotation every 5 minutes -- Key rotation after 1000 operations -- Key destruction with page visibility change -- AES-256-GCM blob format validation +**Test coverage:** 94+ tests covering BIP39, CRC16, Krux compatibility, CSP enforcement, network blocking, clipboard security, and session key management. --- -## πŸ“ Project Structure +## πŸ“– Technical Documentation + +- [MEMORY_STRATEGY.md](MEMORY_STRATEGY.md) - Why JS can't zero memory and how SeedPGP defends +- [RECOVERY_PLAYBOOK.md](RECOVERY_PLAYBOOK.md) - Offline recovery instructions +- [SECURITY_AUDIT_REPORT.md](SECURITY_AUDIT_REPORT.md) - Full audit findings + +--- + +## βš–οΈ License & Disclaimer + +**MIT License** - See LICENSE for details + +**⚠️ IMPORTANT DISCLAIMER:** ``` -seedpgp-web/ -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ components/ # React UI components -β”‚ β”‚ β”œβ”€β”€ PgpKeyInput.tsx # PGP key import (drag & drop) -β”‚ β”‚ β”œβ”€β”€ QrDisplay.tsx # QR code generation -β”‚ β”‚ β”œβ”€β”€ QRScanner.tsx # Camera + file scanning -β”‚ β”‚ β”œβ”€β”€ SecurityWarnings.tsx # Threat model display -β”‚ β”‚ β”œβ”€β”€ StorageDetails.tsx # Storage monitoring -β”‚ β”‚ └── ClipboardDetails.tsx # Clipboard tracking -β”‚ β”œβ”€β”€ lib/ -β”‚ β”‚ β”œβ”€β”€ seedpgp.ts # Core encryption/decryption -β”‚ β”‚ β”œβ”€β”€ sessionCrypto.ts # AES-GCM session key management -β”‚ β”‚ β”œβ”€β”€ krux.ts # Krux KEF compatibility -β”‚ β”‚ β”œβ”€β”€ bip39.ts # BIP39 validation -β”‚ β”‚ β”œβ”€β”€ base45.ts # Base45 encoding/decoding -β”‚ β”‚ └── crc16.ts # CRC16-CCITT-FALSE checksums -β”‚ β”œβ”€β”€ App.tsx # Main application -β”‚ └── main.tsx # React entry point -β”œβ”€β”€ public/ -β”‚ └── _headers # Cloudflare security headers -β”œβ”€β”€ package.json -β”œβ”€β”€ vite.config.ts -β”œβ”€β”€ RECOVERY_PLAYBOOK.md # Offline recovery guide -└── README.md # This file +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. ``` --- -## πŸ”„ Version History +## πŸ†˜ Support & Security -### v1.4.5 (2026-02-07) +- **Issues:** [GitHub Issues](https://github.com/kccleoc/seedpgp-web/issues) +- **Security:** Private disclosure via GitHub security advisory +- **Recovery Help:** See [RECOVERY_PLAYBOOK.md](RECOVERY_PLAYBOOK.md) -- βœ… **Fixed QR Scanner bugs** related to camera initialization and race conditions. -- βœ… **Improved error handling** in the scanner to prevent crashes and provide better feedback. -- βœ… **Stabilized component props** to prevent unnecessary re-renders and fix `AbortError`. - -### v1.4.4 (2026-02-03) - -- βœ… **Enhanced security documentation** with explicit threat model -- βœ… **Improved README** with simple examples and best practices -- βœ… **Better air-gapped usage guidance** for maximum security -- βœ… **Version bump** with security audit improvements - -### v1.4.3 (2026-01-30) - -- βœ… Fixed textarea contrast for readability -- βœ… Fixed overlapping floating boxes -- βœ… Polished UI with modern crypto wallet design - -### v1.4.2 (2026-01-30) - -- βœ… Migrated to Cloudflare Pages for real CSP enforcement -- βœ… Added "Encrypted in memory" badge -- βœ… Improved security header configuration - -### v1.4.0 (2026-01-29) - -- βœ… Extended session-key encryption to Restore flow -- βœ… Added 10-second auto-clear timer for restored mnemonic -- βœ… Added manual Hide button for immediate clearing - -[View full version history...](https://github.com/kccleoc/seedpgp-web/releases) - ---- - -## πŸ—ΊοΈ Roadmap - -### Short-term (v1.5.x) - -- [ ] Enhanced BIP39 validation (full wordlist + checksum) -- [ ] Multi-frame support for larger payloads -- [ ] Hardware wallet integration (Trezor/Keystone) - -### Medium-term - -- [ ] Shamir Secret Sharing support -- [ ] Mobile companion app (React Native) -- [ ] Printable paper backup templates -- [ ] Encrypted cloud backup with PBKDF2 - -### Long-term - -- [ ] BIP85 child mnemonic derivation -- [ ] Quantum-resistant algorithm options -- [ ] Cross-platform desktop app (Tauri) - ---- - -## βš–οΈ License - -MIT License - see [LICENSE](LICENSE) file for details. - -## πŸ‘€ Author - -**kccleoc** - [GitHub](https://github.com/kccleoc) -**Security Audit**: v1.4.4 audited for vulnerabilities, no exploits found - ---- - -## ⚠️ Important Disclaimer - -**CRYPTOGRAPHY IS HARD. USE AT YOUR OWN RISK.** - -This software is provided as-is, without warranty of any kind. Always: - -1. **Test with small amounts** before trusting with significant funds -2. **Verify decryption works** immediately after creating backups -3. **Keep multiple backup copies** in different physical locations -4. **Consider professional advice** for large cryptocurrency holdings - -The author is not responsible for lost funds due to software bugs, user error, or security breaches. - ---- - -## πŸ†˜ Getting Help - -- **Issues**: [GitHub Issues](https://github.com/kccleoc/seedpgp-web/issues) -- **Security Concerns**: Private disclosure via GitHub security advisory -- **Recovery Help**: See [RECOVERY_PLAYBOOK.md](RECOVERY_PLAYBOOK.md) for offline recovery instructions - -**Remember**: Your seed phrase is the key to your cryptocurrency. Guard it with your life. +**Author:** kccleoc +**Security Audited:** v1.4.4 (no exploits found)