kccleoc/seedpgp-web
0
0
Fork 0
mirror of https://github.com/kccleoc/seedpgp-web.git synced 2026-03-06 17:37:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Rewrite README with practical usage guide and risk-balanced setup instructions

Browse Source
This commit is contained in:
LC mac
2026-02-12 23:33:19 +08:00
parent 747e298cb2
commit 9cc74005f2
1 changed files with 323 additions and 484 deletions
Download Patch File Download Diff File Expand all files Collapse all files

807
README.md
View File

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