kccleoc/seedpgp-web
0
0
Fork 0
mirror of https://github.com/kccleoc/seedpgp-web.git synced 2026-03-07 09:57:50 +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

799
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 |
**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)
```bash ```bash
# 1. Clone and install
git clone https://github.com/kccleoc/seedpgp-web.git git clone https://github.com/kccleoc/seedpgp-web.git
cd seedpgp-web cd seedpgp-web
bun install
# 2. Run locally (offline)
bun run dev
# → Browser opens at http://localhost:5173
# → NO network traffic, everything stays local
```
**Then proceed to "Using SeedPGP" below.**
---
### Path B: Tails Airgapped Setup (Best for $10K+)
**Why Tails?** Tails is a security-focused OS that runs in RAM, leaves no trace, and completely isolates your device from the internet.
#### Step 1: Get Tails
```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
```
#### Step 2: Boot Tails (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
```
#### Step 3: Clone SeedPGP in Tails
```bash
# Open Terminal in Tails
# (right-click desktop → Applications → System Tools → Terminal)
git clone https://github.com/kccleoc/seedpgp-web.git
cd seedpgp-web
# Install Bun (if first time)
curl -fsSL https://bun.sh/install | bash
bun install bun install
bun run dev bun run dev
# Open http://localhost:5173
# → Copy http://localhost:5173 to browser address bar
``` ```
2. **Enter your 12/24-word BIP39 mnemonic** #### Step 4: Generate Backup (Next Section)
3. **Choose encryption method**: All traffic is local only. When you shut down, everything is erased from RAM.
- **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
--- ---
## 🛡️ Explicit Threat Model Documentation ### Path C: Cloud Browser (Testing Only)
### 🎯 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 Open: https://seedpgp-web.pages.dev
[Airgapped Device] → Run SeedPGP locally → Encrypt with public key ⚠️ Use ONLY for testing with small amounts ($0–$100)
[Airgapped Device] → Print QR code → Store physically ✅ CSP headers verified to block all external connections
[Online Device] → Never touches private key or plaintext seed ⚠️ Still requires trusting Cloudflare infrastructure
``` ```
2. **Local Execution** (Next best): ---
## 🔐 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 ```bash
# Clone and run offline # Using GPG (Linux/Mac)
git clone https://github.com/kccleoc/seedpgp-web.git gpg --full-generate-key
cd seedpgp-web # Follow prompts for RSA-4096, expiration, passphrase
bun install
# Disable network, then run # Export public key (to use in SeedPGP)
bun run dev -- --host 127.0.0.1 gpg --armor --export your-email@example.com > public.asc
``` ```
3. **Cloudflare Pages** (Convenient but trust required): - **YES** → Upload in SeedPGP:
- ✅ Real CSP enforcement (blocks network at browser level) 1. Click **"PGP Key Input"** (top left)
- ✅ Security headers (X-Frame-Options, X-Content-Type-Options) 2. Paste your **public key** (`.asc` file)
- ⚠️ Trusts Cloudflare infrastructure 3. SeedPGP shows key fingerprint (verify it's yours)
- ⚠️ Requires HTTPS connection 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
--- ---
## 📚 Simple Usage Examples ### Step 3: Store Your Backups
### Example 1: Password-only Encryption (Simplest) You now have:
```typescript - ✅ **Paper backup** (12/24 words written down)
import { encryptToSeed, decryptFromSeed } from "./lib/seedpgp"; - ✅ **QR code backup** (encrypted, can be scanned)
// Backup with password **Storage strategy:**
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..." | What | Where | Why |
|---|---|---|
// Restore with password | **Seed paper** | Safe deposit box OR home safe | Original source of truth |
const restored = await decryptFromSeed({ | **QR code** | Multiple physical locations (home, office, safety box) | Can recover without trusting paper |
frameText: result.framed, | **PGP private key** (if used) | Offline storage, encrypted | Needed to restore from QR |
messagePassword: "MyStrongPassword123!", | **Password** (if used) | Your password manager (encrypted) | Needed to restore from QR |
});
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 ### Step 4: Test Your Recovery
### Prerequisites ⚠️ **CRITICAL**: Do this immediately after backup.
- [Bun](https://bun.sh) v1.3.6+ (recommended) or Node.js 18+ ```
- Git 1. Scan or upload the QR code
→ Click "QR Scanner" button
→ Use camera or upload image
### Quick Install 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 ```bash
# Clone and install # Run all tests
git clone https://github.com/kccleoc/seedpgp-web.git
cd seedpgp-web
bun install
# Run tests
bun test bun test
# Start development server
bun run dev
# Open http://localhost:5173
```
### Production Build
```bash
bun run build # Build to dist/
bun run preview # Preview production build
```
---
## 🔐 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)
```bash
# Run on airgapped machine
bun run dev -- --host 127.0.0.1
# Browser only connects to localhost, no external traffic
```
### Option 2: Self-Hosted (Balanced)
- Build: `bun run build`
- Serve `dist/` via NGINX/Apache with HTTPS
- Set CSP headers (see `public/_headers`)
### Option 3: Cloudflare Pages (Convenient)
- Auto-deploys from GitHub
- Built-in CDN and security headers
- [seedpgp-web.pages.dev](https://seedpgp-web.pages.dev)
---
## 🧪 Testing & Verification
### Test Suite
```bash
# Run all tests (unit + integration)
bun test
# Run only unit tests
bun test src/**/*.test.ts
# Run integration tests (CSP, network, clipboard) # Run integration tests (CSP, network, clipboard)
bun test:integration 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 **Test coverage:** 94+ tests covering BIP39, CRC16, Krux compatibility, CSP enforcement, network blocking, clipboard security, and session key management.
- ✅ **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
--- ---
## 📁 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/ CRYPTOGRAPHY IS HARD. USE AT YOUR OWN RISK.
├── src/
│ ├── components/ # React UI components This software is provided as-is, without warranty.
│ │ ├── PgpKeyInput.tsx # PGP key import (drag & drop)
│ │ ├── QrDisplay.tsx # QR code generation 1. Test with small amounts before trusting with real funds
│ │ ├── QRScanner.tsx # Camera + file scanning 2. Verify recovery works immediately after backup
│ │ ├── SecurityWarnings.tsx # Threat model display 3. Keep multiple geographically distributed copies
│ │ ├── StorageDetails.tsx # Storage monitoring 4. Your device security matters more than app security
│ │ └── ClipboardDetails.tsx # Clipboard tracking 5. For amounts >$100K, consult professional security advice
│ ├── lib/
│ │ ├── seedpgp.ts # Core encryption/decryption The author is not responsible for lost funds due to bugs,
│ │ ├── sessionCrypto.ts # AES-GCM session key management user mistakes, or security breaches.
│ │ ├── krux.ts # Krux KEF compatibility
│ │ ├── bip39.ts # BIP39 validation Your seed phrase = your cryptocurrency.
│ │ ├── base45.ts # Base45 encoding/decoding Guard it with your life.
│ │ └── 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
``` ```
--- ---
## 🔄 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. **Author:** kccleoc
- ✅ **Improved error handling** in the scanner to prevent crashes and provide better feedback. **Security Audited:** v1.4.4 (no exploits found)
- ✅ **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.