w3pk 0.7.0 → 0.7.2

package/docs/SECURITY.md

@@ -813,6 +813,283 @@ Before deploying w3pk in production:
 - [ ] ✅ Security monitoring and alerting
 - [ ] ✅ User education materials prepared
 
+## Credential Scoping and Domain Isolation
+
+### Credentials are Domain-Specific
+
+**Important:** Credentials created on one web application **cannot be used on another web application**, even for the same username. This is a fundamental WebAuthn security feature.
+
+### How It Works
+
+When you register a credential, it is cryptographically bound to the domain:
+
+```typescript
+// Registration on example.com
+const registrationOptions = {
+  challenge,
+  rp: {
+    name: "w3pk",
+    id: window.location.hostname,  // "example.com"
+  },
+  user: {
+    id: username,
+    name: username,
+    displayName: username,
+  },
+  // ...
+}
+
+// Authentication on example.com
+const authOptions = {
+  challenge,
+  rpId: window.location.hostname,  // Must be "example.com"
+  userVerification: "required",
+  // ...
+}
+```
+
+**Key Points:**
+
+1. **RP ID is auto-detected**: The Relying Party ID (RP ID) is automatically set to `window.location.hostname`
+2. **Cannot be configured**: Manual RP ID configuration was removed in v0.7.0 to enforce security
+3. **Cryptographically bound**: The WebAuthn credential private key is tied to the RP ID
+4. **Browser-enforced**: The browser's WebAuthn API enforces this isolation
+
+### Why Credentials Don't Work Across Domains
+
+**Example scenario:**
+
+```typescript
+// Step 1: Register on app1.com
+// User visits: https://app1.com
+await w3pk.register({ username: 'alice' })
+// → RP ID: "app1.com"
+// → Credential created and bound to "app1.com"
+// → Stored in browser with origin: "https://app1.com"
+
+// Step 2: Try to login on app2.com
+// User visits: https://app2.com
+await w3pk.login()
+// → RP ID: "app2.com" (different!)
+// → Browser WebAuthn API: "No credential found for RP ID 'app2.com'"
+// → Login fails ❌
+
+// Step 3: Must register separately on app2.com
+await w3pk.register({ username: 'alice' })
+// → Creates NEW credential for "app2.com"
+// → This is a completely separate credential
+```
+
+### Security Guarantees
+
+This domain isolation provides critical security guarantees:
+
+#### ✅ Protection Against Phishing
+
+```typescript
+// Legitimate site: example.com
+await w3pk.register({ username: 'alice' })
+// RP ID: "example.com"
+
+// Phishing site: examp1e.com (note the "1")
+await w3pk.login()
+// RP ID: "examp1e.com" (different!)
+// ❌ Credential not found - phishing attempt blocked
+```
+
+The attacker **cannot** use your `example.com` credential even if they:
+- Copy your localStorage data
+- Copy your IndexedDB data
+- Trick you into visiting their site
+- Use an identical UI
+
+The browser enforces that credentials for `example.com` can only be used on `example.com`.
+
+#### ✅ Origin-Based Storage Isolation
+
+```typescript
+// Browser storage is automatically scoped by origin
+localStorage  // Scoped to "https://example.com"
+IndexedDB     // Scoped to "https://example.com"
+
+// A different origin cannot access this storage
+// - https://attacker.com → different origin
+// - https://subdomain.example.com → different origin (unless RP ID configured for parent)
+// - http://example.com → different origin (different protocol)
+```
+
+#### ✅ No Cross-Site Credential Replay
+
+```typescript
+// Even if attacker intercepts network traffic
+const stolenSignature = interceptFromNetwork()
+
+// They cannot replay it on their site
+await navigator.credentials.get({
+  publicKey: {
+    challenge: stolenChallenge,
+    rpId: "attacker.com",  // Different RP ID!
+    // ...
+  }
+})
+// ❌ Browser rejects: "RP ID mismatch"
+```
+
+### Subdomain Considerations
+
+**By default, credentials are scoped to the exact hostname:**
+
+```typescript
+// Registered on: app.example.com
+// RP ID: "app.example.com"
+
+// Cannot use on: api.example.com (different subdomain)
+// Cannot use on: example.com (parent domain)
+```
+
+**Note:** The WebAuthn standard allows setting RP ID to a parent domain, but w3pk uses auto-detection which sets it to the exact hostname for maximum security.
+
+### Localhost and Development
+
+During development, credentials are scoped to `localhost`:
+
+```typescript
+// Development environment
+window.location.hostname  // "localhost"
+// RP ID: "localhost"
+
+// Credentials created during development:
+// ✅ Work on: http://localhost:3000
+// ✅ Work on: http://localhost:8080
+// ✅ Work on: https://localhost:5173
+// ❌ Don't work on: 127.0.0.1 (different hostname!)
+```
+
+**Development tip:** Always use `localhost`, not `127.0.0.1`, for consistent RP ID.
+
+### Migration from v0.6.0 to v0.7.0
+
+In v0.6.0, the RP ID could be manually configured:
+
+```typescript
+// v0.6.0 (old)
+const w3pk = createWeb3Passkey({
+  rpId: 'example.com',  // Manual configuration
+})
+```
+
+In v0.7.0+, this was removed for security:
+
+```typescript
+// v0.7.0+ (current)
+const w3pk = createWeb3Passkey({
+  // rpId is auto-detected from window.location.hostname
+  // Cannot be overridden
+})
+```
+
+**Why this change?**
+- Prevents misconfiguration
+- Enforces best practices
+- Eliminates cross-origin credential risks
+- Simplifies API
+
+### Credential Storage and Scoping
+
+**What's stored and where:**
+
+```typescript
+// localStorage (origin-scoped by browser)
+// Key: w3pk_credential_<credentialId>
+{
+  "id": "credential-abc123",
+  "publicKey": "MFkw...",      // Public key only
+  "username": "alice",
+  "ethereumAddress": "0x1234...",
+  "createdAt": 1234567890
+}
+
+// IndexedDB (origin-scoped by browser)
+// Store: wallets
+{
+  "ethereumAddress": "0x1234...",
+  "encryptedMnemonic": "v1kT...",  // AES-GCM encrypted
+  "credentialId": "credential-abc123",
+  "createdAt": 1234567890
+}
+
+// Authenticator (hardware/platform)
+// WebAuthn private key (bound to RP ID)
+// - Cannot be exported
+// - Cannot be used for different RP ID
+// - Hardware-protected
+```
+
+**Security properties:**
+
+1. **localStorage**: Origin-scoped by browser (cannot access from different origin)
+2. **IndexedDB**: Origin-scoped by browser + encrypted with WebAuthn signature
+3. **Authenticator**: RP ID-bound + hardware-protected
+
+### Common Questions
+
+**Q: Can I use the same wallet on multiple domains?**
+
+A: No, each domain requires separate registration. However, you can import the same mnemonic on different domains to access the same wallet addresses:
+
+```typescript
+// On domain1.com
+const { mnemonic } = await w3pk.register({ username: 'alice' })
+// Save mnemonic: "word1 word2 ... word12"
+
+// On domain2.com (later)
+await w3pk.register({
+  username: 'alice',
+  mnemonic: 'word1 word2 ... word12'  // Import same mnemonic
+})
+// ✅ Same wallet addresses, different WebAuthn credential
+```
+
+**Q: What if I want to share credentials across subdomains?**
+
+A: Currently not supported. Each subdomain requires separate registration. This is the most secure approach.
+
+**Q: Can I migrate credentials between domains?**
+
+A: WebAuthn credentials cannot be migrated, but wallets can:
+
+1. Export mnemonic from old domain
+2. Register on new domain with same mnemonic
+3. Same wallet addresses, new credential
+
+**Q: What happens if I switch from `app.example.com` to `example.com`?**
+
+A: These are different RP IDs. You'll need to re-register. Export your mnemonic first to preserve your wallet.
+
+### Security Best Practices
+
+1. **Educate users**: Make it clear that credentials are per-domain
+2. **Prompt for backup**: Always prompt users to save their mnemonic after registration
+3. **Test on production domain**: Don't expect development credentials to work in production
+4. **Use consistent domains**: Avoid switching between `www.example.com` and `example.com`
+5. **Display current domain**: Show users which domain they're authenticating for
+
+### Implementation Example
+
+```typescript
+// Show user which domain they're registering on
+const currentDomain = window.location.hostname
+
+console.log(`🔐 Creating credential for: ${currentDomain}`)
+console.log(`⚠️  This credential will only work on ${currentDomain}`)
+
+await w3pk.register({ username: 'alice' })
+
+console.log(`✅ Credential created for ${currentDomain}`)
+console.log(`💾 Save your recovery phrase - you'll need it to access`)
+console.log(`   this wallet on other domains or devices`)
+```
+
 ## WebAuthn Security Features
 
 ### User Verification
@@ -925,6 +1202,360 @@ Modern authenticators (TouchID, Windows Hello, YubiKey) have **built-in secure s
 - Mnemonic is the ultimate recovery mechanism
 - WebAuthn is for convenience + security, not recovery
 
+## Backup & Recovery Security
+
+w3pk implements a **three-layer backup and recovery system** that balances security, usability, and resilience. Each layer uses different cryptographic primitives and trust models.
+
+### Layer 1: Passkey Auto-Sync (Platform-Based)
+
+**How it works:**
+- WebAuthn credentials automatically sync via platform services (iCloud Keychain, Google Password Manager, Microsoft Account)
+- Encrypted end-to-end by platform provider
+- Requires device unlock + cloud account authentication
+
+**Security properties:**
+- ✅ **Encrypted in transit** - Platform handles E2E encryption
+- ✅ **Hardware-backed** - Credentials protected by Secure Enclave/TPM
+- ✅ **Automatic** - No user action required
+- ⚠️ **Platform trust** - Relies on Apple/Google/Microsoft security
+- ⚠️ **Ecosystem lock-in** - Cannot cross platforms (Apple → Android)
+
+**Threat model:**
+| Threat | Protected? | Notes |
+|--------|-----------|-------|
+| Device loss (same ecosystem) | ✅ Yes | Credentials restore on new device |
+| Device loss (cross-platform) | ❌ No | Need Layer 2 (mnemonic) |
+| Platform account compromise | ⚠️ Depends | Platform MFA protects |
+| State-level attack on cloud | ⚠️ Possible | Platform E2E encryption helps |
+
+### Layer 2: Encrypted Backups (User-Controlled)
+
+**How it works:**
+- Mnemonic encrypted with user-chosen password
+- Multiple backup formats: password-protected ZIP, QR code
+- Encryption: **AES-256-GCM** with **PBKDF2** (310,000 iterations, OWASP 2025 standard)
+
+**Security properties:**
+- ✅ **Military-grade encryption** - AES-256-GCM
+- ✅ **Password-based** - User controls secret
+- ✅ **Offline storage** - Can be stored on paper/USB/safe
+- ✅ **Platform-independent** - Works across any device
+- ⚠️ **Password strength critical** - Weak password = vulnerable
+
+**Cryptographic details:**
+```typescript
+// Key derivation
+PBKDF2-SHA256
+├─ Iterations: 310,000 (OWASP 2025)
+├─ Salt: 32 bytes (random per backup)
+└─ Output: 256-bit key
+
+// Encryption
+AES-256-GCM
+├─ Key: From PBKDF2
+├─ IV: 12 bytes (random per encryption)
+├─ Auth tag: 16 bytes (automatic)
+└─ Additional data: Ethereum address (for integrity)
+```
+
+**Password validation:**
+w3pk enforces strong passwords:
+- Minimum 12 characters
+- Uppercase + lowercase + numbers + special chars
+- Not in common password list
+- Strength score ≥50/100 required
+
+**Using `isStrongPassword` utility:**
+```typescript
+import { isStrongPassword } from 'w3pk'
+
+// Validate before creating backups
+const password = userInput
+if (!isStrongPassword(password)) {
+  throw new Error('Password must be at least 12 characters with uppercase, lowercase, numbers, and special characters')
+}
+
+// Now safe to create backup
+const blob = await w3pk.createZipBackup(password)
+```
+
+**Examples:**
+```typescript
+isStrongPassword('MyStr0ng!Pass')           // ✅ true
+isStrongPassword('C0mplex#Secure')          // ✅ true
+isStrongPassword('weak')                    // ❌ false - too short
+isStrongPassword('NoNumbers!')              // ❌ false - missing numbers
+isStrongPassword('Password123!')            // ❌ false - contains "password"
+```
+
+**Threat model:**
+| Threat | Protected? | Notes |
+|--------|-----------|-------|
+| Backup file stolen | ✅ Yes | Requires password to decrypt |
+| Weak password | ⚠️ Vulnerable | User responsibility |
+| Password forgotten | ❌ Unrecoverable | Need Layer 3 (social recovery) |
+| Brute force (strong password) | ✅ Yes | 310k iterations slow down attacks |
+| Brute force (weak password) | ❌ Vulnerable | Minutes to hours with GPU |
+
+**Brute force analysis:**
+
+Assuming attacker has:
+- Modern GPU (RTX 4090)
+- ~100,000 PBKDF2-SHA256 hashes/second at 310k iterations
+
+| Password Type | Entropy | Time to Crack |
+|--------------|---------|---------------|
+| `password123` (common) | ~20 bits | Seconds |
+| `MyPassword123!` (weak) | ~35 bits | Hours |
+| `MyS3cur3!Pass@2024` (medium) | ~50 bits | Months |
+| `correct horse battery staple` (strong) | ~80 bits | Centuries |
+| Truly random 16 chars | ~100 bits | Universe lifetime |
+
+**Recommendation:** Use password manager to generate strong passwords or use multi-word passphrases (4+ random words).
+
+### Layer 3: Social Recovery (Distributed Trust)
+
+**How it works:**
+- Mnemonic split into **N shares** using **Shamir Secret Sharing**
+- Requires **M-of-N** shares to recover (e.g., 3-of-5)
+- Each guardian receives encrypted share via QR code
+- Guardians never see the actual mnemonic
+
+**Cryptographic details:**
+```typescript
+// Shamir Secret Sharing over GF(256)
+├─ Threshold: M (minimum shares needed)
+├─ Total shares: N (total guardians)
+├─ Secret: Mnemonic (67 bytes UTF-8)
+├─ Polynomial degree: M-1
+├─ Field: Galois Field GF(256)
+│   ├─ Primitive polynomial: x^8 + x^4 + x^3 + x + 1 (0x11b)
+│   ├─ Generator: 3
+│   └─ Lagrange interpolation for reconstruction
+└─ Share format:
+    ├─ Byte 0: X coordinate (1-255)
+    └─ Bytes 1-67: Y values (polynomial evaluation)
+
+// Guardian share encryption
+AES-256-GCM (same as Layer 2)
+├─ Optional: Guardian can password-protect their share
+└─ QR code includes guardian metadata + instructions
+```
+
+**Security properties:**
+- ✅ **Information-theoretic security** - Cannot learn secret from M-1 shares
+- ✅ **Distributed trust** - No single point of failure
+- ✅ **Privacy-preserving** - Guardians never see mnemonic
+- ✅ **Flexible threshold** - Customize M-of-N based on risk tolerance
+- ⚠️ **Coordination required** - Must contact M guardians
+- ⚠️ **Guardian trust** - Guardians could collude (if ≥M)
+
+**Threat model:**
+| Threat | Protected? | Notes |
+|--------|-----------|-------|
+| M-1 guardians compromised | ✅ Yes | Cannot recover without Mth share |
+| M guardians collude | ❌ Vulnerable | Can reconstruct mnemonic |
+| All guardians lost | ❌ Unrecoverable | Need Layer 2 backup |
+| Guardian share stolen | ✅ Depends | If password-protected, still safe |
+| User forgets who guardians are | ⚠️ Problem | Keep guardian list separately |
+
+**Information-theoretic security proof:**
+
+Shamir Secret Sharing over GF(256) provides perfect secrecy:
+- Given M-1 shares, **every possible secret is equally likely**
+- Attacker learns **zero bits** of information about secret
+- No amount of computation can break this (unlike encryption)
+
+Mathematical proof:
+```
+For threshold M and secret S:
+- Polynomial P(x) = a₀ + a₁x + ... + aₘ₋₁x^(M-1)
+- Secret: S = P(0) = a₀
+- Share i: Sᵢ = P(i)
+
+Given M-1 shares {S₁, S₂, ..., Sₘ₋₁}:
+- Infinite polynomials pass through these points
+- Each yields different P(0) = a₀
+- All secrets equally probable
+- H(S | S₁,...,Sₘ₋₁) = H(S)  [Shannon entropy unchanged]
+```
+
+**Example configuration:**
+
+| Scenario | Threshold | Guardians | Rationale |
+|----------|-----------|-----------|-----------|
+| High paranoia | 5-of-7 | 7 close friends | Can lose 2 guardians |
+| Balanced | 3-of-5 | 5 trusted contacts | Standard recommendation |
+| Convenience | 2-of-3 | 3 family members | Easy to coordinate |
+| Multi-sig like | 2-of-2 | 2 co-owners | Both must agree |
+
+### Layered Security Strategy
+
+**Defense in depth:**
+```
+┌─────────────────────────────────────────────┐
+│ Recovery Scenario                            │
+├─────────────────────────────────────────────┤
+│                                              │
+│ Lost Device (Same Platform)                 │
+│ └─> Layer 1: Passkey Sync ✅ RECOVERED      │
+│                                              │
+│ Lost Device (Cross-Platform)                │
+│ └─> Layer 1: Failed ❌                       │
+│ └─> Layer 2: Encrypted Backup ✅ RECOVERED   │
+│                                              │
+│ Lost Device + Forgot Password               │
+│ └─> Layer 1: Failed ❌                       │
+│ └─> Layer 2: Failed ❌                       │
+│ └─> Layer 3: Social Recovery ✅ RECOVERED    │
+│                                              │
+│ Lost Everything + All Guardians Lost        │
+│ └─> ❌ UNRECOVERABLE                         │
+│                                              │
+└─────────────────────────────────────────────┘
+```
+
+**Security scoring:**
+
+w3pk calculates a security score (0-100) based on active backup methods:
+
+| Configuration | Score | Level |
+|--------------|-------|-------|
+| No backups | 0-25 | 🔴 Vulnerable |
+| Passkey sync only | 30-50 | 🟡 Protected |
+| Passkey + encrypted backup | 60-80 | 🟢 Secured |
+| All three layers | 85-100 | 🟦 Fort Knox |
+
+**Score calculation:**
+```typescript
+score = 0
++ (passkeySync.enabled ? 30 : 0)
++ (backups.zip > 0 ? 25 : 0)
++ (backups.qr > 0 ? 15 : 0)
++ (socialRecovery.configured ? 30 : 0)
+```
+
+### Backup Best Practices
+
+**1. Use multiple layers:**
+```typescript
+// ✅ GOOD: Enable all three layers
+await w3pk.setupSocialRecovery([...guardians], 3)
+await w3pk.createZipBackup('MyS3cur3!Password@2024')
+// Passkey sync enabled by default on platform
+
+// ❌ BAD: Rely on single layer
+// (only passkey sync - what if switch platforms?)
+```
+
+**2. Test recovery before trusting:**
+```typescript
+// Simulate recovery scenarios
+const test1 = await w3pk.simulateRecoveryScenario({
+  type: 'lost-device',
+  hasBackup: true,
+  hasSocialRecovery: true
+})
+console.log('Can recover?', test1.canRecover)
+
+const test2 = await w3pk.simulateRecoveryScenario({
+  type: 'lost-phrase',
+  hasPasskeySync: true
+})
+console.log('Can recover?', test2.canRecover)
+```
+
+**3. Store backups securely:**
+```typescript
+// ✅ GOOD: Offline, encrypted, geographically distributed
+- Physical safe (home)
+- Safety deposit box (bank)
+- Encrypted USB drive (office)
+- Password manager (different password)
+
+// ❌ BAD: Digital-only, centralized
+- Cloud storage unencrypted
+- Email to self
+- Single location
+- Shared with others
+```
+
+**4. Choose guardians wisely:**
+```typescript
+// ✅ GOOD guardian criteria:
+- Trustworthy (won't collude)
+- Available (can reach when needed)
+- Technical (understands basic security)
+- Diverse (different locations/relationships)
+- Long-term (stable relationship)
+
+// ❌ BAD guardian choices:
+- All family members (could collude)
+- All same location (disaster risk)
+- Strangers/acquaintances
+- People who might lose share
+```
+
+**5. Use strong passwords:**
+```typescript
+// ✅ GOOD passwords:
+'correct horse battery staple'  // Multi-word passphrase
+'MyS3cur3!Backup@December2024'  // Long with variety
+(password manager generated)     // Truly random
+
+// ❌ BAD passwords:
+'password123'      // Common
+'MyPassword'       // Dictionary word
+'12345678'         // Sequential
+'qwerty123'        // Keyboard pattern
+```
+
+### API Security Considerations
+
+**All backup operations require authentication:**
+```typescript
+// These operations trigger biometric prompt
+await w3pk.createZipBackup(password)        // ✅ Auth required
+await w3pk.createQRBackup(password)         // ✅ Auth required
+await w3pk.setupSocialRecovery(...)         // ✅ Auth required
+await w3pk.exportMnemonic()                 // ✅ Auth required
+
+// Read-only operations don't require auth
+await w3pk.getBackupStatus()                // ✅ No auth needed
+await w3pk.getSyncStatus()                  // ✅ No auth needed
+```
+
+**Password validation is client-side:**
+⚠️ **Important:** Password strength is checked in the browser. A determined attacker with code execution could bypass validation and create backups with weak passwords.
+
+**Mitigation:**
+- Use `requireAuth: true` for backup creation
+- Short session durations
+- XSS/injection protection (CSP, input sanitization)
+- Educate users on password strength
+
+**Recovery operations don't require authentication:**
+```typescript
+// Recovery from existing backups is public
+await w3pk.restoreFromBackup(encryptedData, password)
+await w3pk.recoverFromGuardians([shares...])
+
+// Rationale: If user has backup data + password/shares,
+// they own the wallet regardless of authentication
+```
+
+### Comparison with Other Recovery Systems
+
+| Recovery Method | w3pk Layer 1 | w3pk Layer 2 | w3pk Layer 3 | Traditional Seed | Hardware Wallet |
+|----------------|--------------|--------------|--------------|------------------|-----------------|
+| **Automatic** | ✅ Yes | ❌ Manual | ❌ Manual | ❌ Manual | ❌ Manual |
+| **Cross-platform** | ❌ No | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Offline storage** | ❌ No | ✅ Yes | ✅ Yes | ✅ Yes | N/A |
+| **No single point** | ❌ No | ❌ No | ✅ Yes | ❌ No | ❌ No |
+| **Cryptographic** | ✅ E2E | ✅ AES-256 | ✅ Shamir | N/A | N/A |
+| **User effort** | None | Medium | High | Low | None |
+| **Trust model** | Platform | Self | Distributed | Self | Self |
+
 ## Best Practices for Users
 
 ### 1. **Always Save Your Mnemonic**

package/docs/ZK_INTEGRATION_GUIDE.md

@@ -22,23 +22,25 @@ The w3pk SDK supports general-purpose zero-knowledge proofs that enable users to
 ### Installation
 
 ```bash
-npm install w3pk
-# ZK dependencies (snarkjs, circomlibjs) are included automatically
+npm install w3pk ethers
+# Optional: Install ZK dependencies if you'll use ZK features
+npm install snarkjs circomlibjs
 ```
 
+**Note**: ZK dependencies are optional. The SDK automatically loads them only when you access `w3pk.zk`, keeping your bundle small if you don't use ZK features.
+
 ### Quick Start
 
 ```typescript
 import { createWeb3Passkey } from 'w3pk'
 
 const w3pk = createWeb3Passkey({
-  apiBaseUrl: 'https://webauthn.w3hc.org',
   zkProofs: {
     enabledProofs: ['membership', 'threshold', 'range']
   }
 })
 
-// Access ZK module
+// Access ZK module (loads automatically on first use)
 const zk = w3pk.zk
 ```
 

package/docs/index.html

@@ -200,9 +200,10 @@
           const username = 'user_' + Date.now();
           const result = await window.w3pk.register({ username });
           console.log('Registration result:', result);
-          window.showResult(`User registered: ${username}`, {
-            username,
-            mnemonic: result.mnemonic,
+          window.showResult(`User registered: ${result.username}`, {
+            username: result.username,
+            address: result.address,
+            isAuthenticated: window.w3pk.isAuthenticated,
             user: window.w3pk.user
           }, 'success');
         } catch (error) {