w3pk 0.9.2 → 0.10.0

package/docs/POST_QUANTUM.md

@@ -1290,14 +1290,299 @@ const delegation = await w3pk.requestExternalWalletDelegation({
 
 ---
 
+## ML-KEM Encryption
+
+w3pk supports ML-KEM-1024 encryption for quantum-resistant data protection with multi-recipient support and deterministic key derivation from private keys.
+
+### Deterministic Key Derivation
+
+Derive ML-KEM keypairs deterministically from any private key material (Ethereum keys, random seeds, etc.):
+
+```typescript
+import { deriveMLKemKeypair, mlkemEncryptWithKey, mlkemDecryptWithKey } from 'w3pk';
+
+// Derive ML-KEM keypair from Ethereum private key
+const ethPrivateKey = '0x1234...'; // Your wallet private key
+const keypair = await deriveMLKemKeypair(ethPrivateKey, 'my-app');
+// Returns: { publicKey: Uint8Array(1568), privateKey: Uint8Array(3168) }
+
+// Share your public key with others
+const publicKeyBase64 = Buffer.from(keypair.publicKey).toString('base64');
+
+// Later: Recreate keypair from same private key (deterministic!)
+const sameKeypair = await deriveMLKemKeypair(ethPrivateKey, 'my-app');
+// sameKeypair.publicKey === keypair.publicKey ✅
+```
+
+### Encrypt/Decrypt with w3pk Instance (Recommended)
+
+The easiest way to use ML-KEM encryption - no private key exposure:
+
+```typescript
+import { createWeb3Passkey } from 'w3pk';
+
+const w3pk = createWeb3Passkey();
+await w3pk.login();
+
+// 1. Share your public key with others
+const myPublicKey = await w3pk.deriveMLKemPublicKey();
+// Send myPublicKey to the server or publish it
+
+// 2. Get server's public key
+const serverPubKey = await fetch('/api/mlkem-public-key').then(r => r.text());
+
+// 3. Encrypt for yourself + server
+const encrypted = await w3pk.mlkemEncrypt(
+  'my secret data',
+  [serverPubKey]  // Server can decrypt
+);
+// You can also decrypt because you're auto-added as recipient
+
+// 4. Later: Decrypt locally (server never sees plaintext!)
+const plaintext = await w3pk.mlkemDecrypt(encrypted);
+```
+
+**Security:** Your Ethereum private key never leaves the w3pk instance, matching the security model of `signMessage()` and `sendTransaction()`.
+
+**Supported Modes:**
+- ✅ **STANDARD** (default) - Private key derived internally, not exposed to app
+- ✅ **STRICT** - Same as STANDARD but always requires WebAuthn re-authentication
+- ✅ **YOLO** - Private key available to app
+- ❌ **PRIMARY** - Not supported (uses P-256 WebAuthn keys, not Ethereum keys)
+
+### Encrypt/Decrypt with Key Derivation (Low-level API)
+
+For advanced use cases where you manage private keys directly:
+
+```typescript
+// Client encrypts for themselves + server
+const serverKeypair = await deriveMLKemKeypair(serverEthKey, 'server');
+const encrypted = await mlkemEncryptWithKey(
+  'my secret data',
+  myEthPrivateKey,              // Sender's private key (auto-added as recipient)
+  [serverKeypair.publicKey],    // Additional recipients
+  'client'                       // Context for sender's key derivation
+);
+
+// Later: Client decrypts locally (no server needed!)
+const plaintext = await mlkemDecryptWithKey(
+  encrypted,
+  myEthPrivateKey,              // Same private key used for encryption
+  'client'                       // Same context
+);
+
+// Or: Server decrypts for operations
+const plaintext = await mlkemDecryptWithKey(
+  encrypted,
+  serverEthKey,
+  'server'
+);
+```
+
+### Direct Encryption (Without Key Derivation)
+
+For maximum flexibility, use raw public keys directly:
+
+```typescript
+import { mlkemEncrypt, mlkemDecrypt } from 'w3pk';
+
+// Single recipient
+const publicKey = 'base64_encoded_public_key...'; // 1568 bytes
+const encrypted = await mlkemEncrypt('my secret data', publicKey);
+
+// Multiple recipients (encrypt once, multiple people can decrypt)
+const encrypted = await mlkemEncrypt('my secret data', [
+  publicKey1,
+  publicKey2,
+  publicKey3
+]);
+// Returns: { recipients: [...], encryptedData, iv, authTag }
+
+// Decrypt with your private key (auto-detects which recipient you are)
+const privateKey = 'base64_encoded_private_key...'; // 3168 bytes
+const plaintext = await mlkemDecrypt(encrypted, privateKey);
+// Returns: 'my secret data'
+
+// Or specify your public key for faster lookup
+const plaintext = await mlkemDecrypt(encrypted, privateKey, publicKey);
+```
+
+### Security Properties
+
+- ✅ **ML-KEM-1024** (NIST FIPS 203) - Post-quantum secure
+- ✅ **AES-256-GCM** - 128-bit quantum security (sufficient)
+- ✅ **Key zeroization** - Shared secrets securely wiped from memory
+- ✅ **Hybrid encryption** - KEM + symmetric cipher for efficiency
+- ✅ **Cross-platform** - Works in browser and Node.js
+
+### API Reference
+
+#### Instance Methods (Recommended)
+
+These methods work with your w3pk wallet instance - no private key exposure:
+
+#### `w3pk.deriveMLKemPublicKey(options?): Promise<string>`
+
+Derives your ML-KEM-1024 public key that can be shared for encryption.
+
+**Parameters:**
+- `options.context` - Context string for domain separation (default: `'mlkem-v1'`)
+- `options.mode` - Security mode: `'STANDARD'`, `'STRICT'`, or `'YOLO'` (default: `'STANDARD'`)
+- `options.tag` - Tag for address derivation (default: `'MAIN'`)
+- `options.origin` - Origin for derivation (default: current origin)
+- `options.requireAuth` - Force WebAuthn re-authentication (default: false, always true in STRICT mode)
+
+**Note:** PRIMARY mode is not supported as it uses P-256 WebAuthn keys instead of Ethereum keys.
+
+**Returns:** Base64-encoded ML-KEM public key (1568 bytes)
+
+**Example:**
+```typescript
+const w3pk = createWeb3Passkey();
+await w3pk.login();
+const pubKey = await w3pk.deriveMLKemPublicKey();
+```
+
+#### `w3pk.mlkemEncrypt(plaintext: string, recipientPublicKeys: Array<string | Uint8Array>, options?): Promise<EncryptedPayload>`
+
+Encrypts data for yourself and additional recipients.
+
+**Parameters:**
+- `plaintext` - The data to encrypt
+- `recipientPublicKeys` - Array of recipient ML-KEM public keys (base64 or Uint8Array)
+- `options.context` - Context string (default: `'mlkem-v1'`)
+- `options.mode` - Security mode: `'STANDARD'`, `'STRICT'`, or `'YOLO'` (default: `'STANDARD'`)
+- `options.tag` - Tag for address derivation (default: `'MAIN'`)
+- `options.origin` - Origin (default: current origin)
+- `options.requireAuth` - Force re-authentication (default: false, always true in STRICT mode)
+
+**Returns:** Encrypted payload
+
+**Example:**
+```typescript
+const encrypted = await w3pk.mlkemEncrypt('secret', [serverPubKey]);
+```
+
+#### `w3pk.mlkemDecrypt(payload: EncryptedPayload, options?): Promise<string>`
+
+Decrypts data encrypted for your wallet.
+
+**Parameters:**
+- `payload` - The encrypted payload
+- `options.context` - Context string (default: `'mlkem-v1'`, must match encryption)
+- `options.mode` - Security mode: `'STANDARD'`, `'STRICT'`, or `'YOLO'` (default: `'STANDARD'`)
+- `options.tag` - Tag (default: `'MAIN'`)
+- `options.origin` - Origin (default: current origin)
+- `options.requireAuth` - Force re-authentication (default: false, always true in STRICT mode)
+
+**Returns:** Decrypted plaintext
+
+**Example:**
+```typescript
+const plaintext = await w3pk.mlkemDecrypt(encrypted);
+```
+
+---
+
+#### Low-Level Functions
+
+These functions require managing private keys directly:
+
+#### `deriveMLKemKeypair(privateKey: string | Uint8Array, context?: string): Promise<MLKemKeypair>`
+
+Derives a deterministic ML-KEM-1024 keypair from any private key material using HKDF-SHA256.
+
+**Parameters:**
+- `privateKey` - Private key material (hex string with optional `0x` prefix, or Uint8Array)
+- `context` - Optional context string for domain separation (default: `'mlkem-v1'`)
+
+**Returns:** `MLKemKeypair` object containing:
+- `publicKey` - ML-KEM-1024 public key (Uint8Array, 1568 bytes)
+- `privateKey` - ML-KEM-1024 private key (Uint8Array, 3168 bytes)
+
+**Security:** Uses HKDF with salt `"mlkem-keypair-v1"` and the provided context to derive a 64-byte seed, then generates a deterministic ML-KEM keypair. Same input always produces same output. All sensitive material is zeroized after use.
+
+#### `mlkemEncryptWithKey(plaintext: string, senderPrivateKey: string | Uint8Array, recipientPublicKeys: Array<string | Uint8Array>, senderContext?: string): Promise<EncryptedPayload>`
+
+Convenience function that derives the sender's ML-KEM keypair, then encrypts for sender + recipients.
+
+**Parameters:**
+- `plaintext` - The data to encrypt
+- `senderPrivateKey` - Sender's private key (hex string or Uint8Array)
+- `recipientPublicKeys` - Array of recipient ML-KEM public keys
+- `senderContext` - Optional context for sender's key derivation (default: `'mlkem-v1'`)
+
+**Returns:** `EncryptedPayload` (sender's public key is automatically included as first recipient)
+
+**Use case:** Encrypt data so both you and a server can decrypt independently.
+
+#### `mlkemDecryptWithKey(payload: EncryptedPayload, privateKey: string | Uint8Array, context?: string): Promise<string>`
+
+Convenience function that derives an ML-KEM keypair, then decrypts the payload.
+
+**Parameters:**
+- `payload` - The encrypted payload
+- `privateKey` - Private key material (hex string or Uint8Array)
+- `context` - Optional context for key derivation (default: `'mlkem-v1'`)
+
+**Returns:** Decrypted plaintext string
+
+**Use case:** Decrypt data using your Ethereum private key without managing separate ML-KEM keys.
+
+#### `mlkemEncrypt(plaintext: string, publicKeys: (string | Uint8Array) | Array<string | Uint8Array>): Promise<EncryptedPayload>`
+
+Encrypts data using ML-KEM-1024 + AES-256-GCM for one or more recipients.
+
+**Parameters:**
+- `plaintext` - The data to encrypt
+- `publicKeys` - Single public key or array of ML-KEM-1024 public keys (base64 strings or Uint8Arrays, 1568 bytes each)
+
+**Returns:** `EncryptedPayload` object containing:
+- `recipients` - Array of recipient entries, each containing:
+  - `publicKey` - Base64 recipient public key (1568 bytes)
+  - `ciphertext` - Base64 ML-KEM ciphertext for this recipient (1600 bytes: 1568 KEM + 32 encrypted AES key)
+- `encryptedData` - Base64 AES-encrypted data (shared across all recipients)
+- `iv` - Base64 initialization vector (12 bytes)
+- `authTag` - Base64 authentication tag (16 bytes)
+
+**How it works:**
+1. Generates a random AES-256 key
+2. Encrypts plaintext with AES-256-GCM using that key
+3. For each recipient: encapsulates a shared secret with their ML-KEM public key, then XOR-encrypts the AES key with the shared secret
+4. Each recipient can decrypt using their private key to recover the AES key, then decrypt the data
+
+#### `mlkemDecrypt(payload: EncryptedPayload, privateKey: string | Uint8Array, publicKey?: string | Uint8Array): Promise<string>`
+
+Decrypts data encrypted with `mlkemEncrypt()`.
+
+**Parameters:**
+- `payload` - The encrypted payload from `mlkemEncrypt()`
+- `privateKey` - ML-KEM-1024 private key (base64 string or Uint8Array, 3168 bytes)
+- `publicKey` - (Optional) Your ML-KEM-1024 public key for faster recipient lookup (base64 string or Uint8Array, 1568 bytes)
+
+**Returns:** Decrypted plaintext string
+
+**Throws:** Error if decryption fails (invalid key, no matching recipient, corrupted data, or tampered auth tag)
+
+**Note:** If `publicKey` is not provided, the function will try each recipient until it finds a match (slower but convenient)
+
+---
+
 ## Document Maintenance
 
-**Version:** 1.1
-**Last Updated:** 2026-02-27
-**Next Review:** 2026-08-27 (6 months)
+**Version:** 1.2
+**Last Updated:** 2026-03-21
+**Next Review:** 2026-09-21 (6 months)
 **Maintained By:** Julien Béranger ([@julienbrg](https://github.com/julienbrg))
 
 **Changelog:**
+- 2026-03-21: Added ML-KEM encryption utilities with deterministic key derivation
+  - Documented `deriveMLKemKeypair()` function for HKDF-based key derivation from private keys
+  - Documented `mlkemEncryptWithKey()` and `mlkemDecryptWithKey()` convenience functions
+  - Documented `mlkemEncrypt()` function for direct post-quantum encryption
+  - Documented `mlkemDecrypt()` function for decryption
+  - Added security properties and comprehensive API reference
+  - Linked to NIST FIPS 203 (ML-KEM) standard
 - 2026-02-27: **Updated to align with [Ethereum quantum resistance roadmap](https://x.com/VitalikButerin/status/2027075026378543132)** (February 2026)
   - Added Ethereum's four quantum-vulnerable components
   - Integrated [EIP-8141](https://eips.ethereum.org/EIPS/eip-8141) (native AA) as long-term solution

package/docs/RECOVERY.md

@@ -264,15 +264,25 @@ await sdk.importFromSync(syncData);
 
 ### **3. Social Recovery**
 
-**Purpose**: Distribute encrypted wallet data among trusted guardians using Shamir Secret Sharing (M-of-N)
+**Purpose**: Distribute encrypted backup file fragments among trusted guardians using Shamir Secret Sharing (M-of-N)
 
 **Setup (3-of-5 example):**
 ```typescript
+import { SocialRecoveryManager } from 'w3pk';
+
 const sdk = createWeb3Passkey();
 await sdk.login();
 
-// Create encrypted backup and split among guardians
-const { guardianShares } = await sdk.setupSocialRecovery(
+// Step 1: Create password-encrypted backup file
+const password = 'MySecurePassword123!'; // User must remember this
+const { blob } = await sdk.createBackupFile('password', password);
+const backupFileJson = await blob.text();
+
+// Step 2: Split backup file among guardians
+const socialRecovery = new SocialRecoveryManager();
+const guardians = await socialRecovery.setupSocialRecovery(
+  backupFileJson, // Encrypted backup file JSON
+  sdk.user.ethereumAddress,
   [
     { name: 'Alice', email: 'alice@example.com' },
     { name: 'Bob', email: 'bob@example.com' },
@@ -280,84 +290,61 @@ const { guardianShares } = await sdk.setupSocialRecovery(
     { name: 'David', email: 'david@example.com' },
     { name: 'Eve', email: 'eve@example.com' },
   ],
-  3, // threshold: need 3 shares to recover
-  'OptionalPassword' // encrypts backup before splitting
+  3 // threshold: need 3 shares to recover
 );
 
-// Generate invitation for each guardian
-for (const share of guardianShares) {
-  const invitation = await sdk.generateGuardianInvite(share);
-  // Send invitation.downloadBlob or invitation.qrCodeDataURL to guardian
+// Step 3: Generate invitation for each guardian
+for (const guardian of guardians) {
+  const invite = await socialRecovery.generateGuardianInvite(guardian);
+  // Send invite.qrCode and invite.explainer to guardian
+  // Guardian stores their share safely (password manager, etc.)
 }
 ```
 
-**Recover Wallet (Two Options):**
-
-**Option 1: Recover and register new passkey (recommended for lost devices)**
+**Recover Wallet:**
 ```typescript
+import { SocialRecoveryManager } from 'w3pk';
+
 const sdk = createWeb3Passkey();
+const socialRecovery = new SocialRecoveryManager();
 
 // Step 1: Collect shares from 3+ guardians
-const shares = [aliceShare, bobShare, charlieShare];
+const shares = [aliceShareCode, bobShareCode, charlieShareCode];
 
-// Step 2: Combine shares and decrypt to get mnemonic and address
-const { mnemonic, ethereumAddress } = await sdk.recoverFromGuardians(
-  shares,
-  'OptionalPassword' // password used during setupSocialRecovery (if any)
-);
+// Step 2: Reconstruct encrypted backup file from shares
+const { backupFileJson, ethereumAddress } = await socialRecovery.recoverFromGuardians(shares);
 
-// Step 3: Create a new password-protected backup from recovered mnemonic
-const { BackupFileManager } = await import('w3pk/backup/backup-file');
-const manager = new BackupFileManager();
-const { backupFile } = await manager.createPasswordBackup(
-  mnemonic,
-  ethereumAddress,
-  'NewPassword123!' // Choose a new password
-);
+// Step 3: Decrypt backup file with password
+const password = prompt('Enter your backup password');
 
-// Step 4: Register new passkey using the backup
-const backupData = JSON.stringify(backupFile);
-await sdk.registerWithBackupFile(backupData, 'NewPassword123!', 'username');
+// Step 4: Register new passkey with recovered backup file
+await sdk.registerWithBackupFile(backupFileJson, password, 'username');
 // Now logged in with new passkey, credentials stored locally ✅
 ```
 
-**Option 2: Recover and import to existing passkey**
-```typescript
-const sdk = createWeb3Passkey();
-
-// Step 1: Login with existing WebAuthn credential
-await sdk.login();
-
-// Step 2: Collect shares and recover mnemonic
-const shares = [aliceShare, bobShare, charlieShare];
-const { mnemonic } = await sdk.recoverFromGuardians(
-  shares,
-  'OptionalPassword'
-);
-
-// Step 3: Import mnemonic to current logged-in user
-await sdk.importMnemonic(mnemonic);
-// Credentials stored locally under current passkey ✅
-```
-
 **Encryption**:
-1. Create BackupFile (password/passkey encrypted)
-2. Serialize to JSON
-3. Split using Shamir Secret Sharing (M-of-N)
-4. Each guardian gets one share
+1. User creates password-encrypted BackupFile (AES-256-GCM)
+2. Serialize BackupFile to JSON
+3. Split JSON using Shamir Secret Sharing (M-of-N threshold)
+4. Each guardian gets one encrypted fragment
+5. Recovery requires: threshold shares + original password
 
 **Use Case**: Forgot password, lost all devices, ultimate safety net
 
-**Security**: No single guardian can recover wallet alone
+**Security**: No single guardian can recover wallet alone. Guardians hold fragments of an already-encrypted backup file.
 
 **Pros:**
 - ✅ No single point of failure
+- ✅ Double encryption: backup is encrypted, then fragments are distributed
+- ✅ Guardians never see plaintext wallet data
+- ✅ Password protection even after collecting shares
 - ✅ Survives your own forgetfulness
 - ✅ Survives any 2 guardians disappearing
 - ✅ Highest security and redundancy
 
 **Cons:**
 - ⚠️ Requires trusted friends/family
+- ⚠️ Must remember password (guardians don't have it)
 - ⚠️ Setup complexity
 - ⚠️ Recovery takes time (24-48 hours)
 - ⚠️ Coordination required
@@ -365,9 +352,10 @@ await sdk.importMnemonic(mnemonic);
 **Recovery scenarios:**
 | Scenario | Can Recover? | How |
 |----------|--------------|-----|
-| Forgot password + lost devices | ✅ Yes | Contact 3 guardians → combine shares |
-| Lost backup + lost passkey | ✅ Yes | Contact 3 guardians |
+| Lost all devices | ✅ Yes | Contact 3 guardians → combine shares → enter password |
+| Lost backup + lost passkey | ✅ Yes | Contact 3 guardians → reconstruct backup file → enter password |
 | 2 guardians unavailable | ✅ Yes | Still have 3 others |
+| Forgot password + have shares | ❌ No | Backup file is encrypted with password |
 | All guardians lost shares | ❌ No | Need another recovery layer |
 
 ---
@@ -396,45 +384,81 @@ await sdk.importMnemonic(mnemonic);
 ### **Social Recovery Cryptography**
 
 ```typescript
-Shamir Secret Sharing Algorithm:
+Backup File-Based Shamir Secret Sharing:
 
 Example: 3-of-5 scheme
-- Split secret S into 5 shares: s1, s2, s3, s4, s5
-- Any 3 shares can reconstruct S
-- Any 2 shares reveal ZERO information about S
-- Each guardian only has an encrypted piece
+
+Step 1: Create Encrypted Backup File
+- User creates password-encrypted backup file
+- Backup contains: { encryptedMnemonic, ethereumAddress, ... }
+- Encryption: PBKDF2(password) → AES-256-GCM
+- Result: BackupFile JSON (already encrypted)
+
+Step 2: Split Backup File
+- Serialize BackupFile to JSON string
+- Convert JSON to bytes
+- Split bytes using Shamir Secret Sharing (3-of-5)
+- Result: 5 shares of encrypted data
+
+Step 3: Distribute Shares
+- Each guardian gets one share (hex-encoded fragment)
+- Shares are fragments of the encrypted backup file
+- Guardians never see the plaintext mnemonic
+- Guardians don't have the password
+
+Recovery Process:
+- Collect 3+ shares from guardians
+- Combine shares → reconstruct BackupFile JSON
+- Decrypt with password → extract mnemonic
+- Register new passkey or import to existing
 
 Mathematical basis:
-- Polynomial interpolation over finite field
+- Polynomial interpolation over finite field GF(256)
 - Degree = threshold - 1 (e.g., degree-2 polynomial for 3-of-5)
 - Points on polynomial = shares
-- Reconstruct polynomial with 3 points → get secret
+- Any 3 points → reconstruct polynomial → recover secret
+- Any 2 points → mathematically impossible to recover
+```
+
+**Security Model:**
+```
+Double Encryption:
+Layer 1: Backup file encrypted with password (AES-256-GCM)
+Layer 2: Encrypted backup split into shares (Shamir)
+
+Result:
+- Guardians hold fragments of encrypted data
+- Even with threshold shares, password still required
+- No single guardian has access to wallet
+- No collusion of guardians can bypass password
 
-Share encryption:
-Each share is encrypted with guardian's public key:
-- Guardian generates key pair (on their device)
-- Share encrypted with guardian's public key
-- Only guardian can decrypt their share
-- Prevents share theft from coordinator
+Attack Scenarios:
+✅ Attacker steals 2 shares → Cannot reconstruct
+✅ Attacker steals 3+ shares → Still needs password
+✅ Attacker has password → Still needs threshold shares
+❌ Attacker has password + threshold shares → Can recover
 ```
 
 **Trust model:**
 ```
 Coordinator (You):
+- Must remember password (guardians don't have it)
 - Cannot recover from less than threshold shares
-- Can revoke/replace guardians
-- Can update threshold
+- Can revoke/replace guardians (requires new setup)
+- Can verify guardian shares are distributed
 
 Guardians:
-- Cannot recover alone
-- Cannot collude unless threshold met
+- Hold encrypted fragments only
+- Cannot decrypt without password
+- Cannot recover alone (need threshold + password)
 - Can verify share validity
-- Can export/backup their share
+- Can store share safely (it's already encrypted)
 
 Attacker:
 - Cannot recover with < threshold shares
-- Cannot brute-force (mathematically secure)
-- Must compromise guardians directly
+- Cannot decrypt backup without password
+- Must compromise both guardians AND password
+- Mathematically secure (Shamir + AES-256-GCM)
 ```
 
 ---
@@ -485,24 +509,36 @@ await w3pk.importFromSync(backupData);
 ### Social Recovery
 
 ```typescript
-// Setup
-const { guardianShares } = await w3pk.setupSocialRecovery(guardians, threshold, password);
+import { SocialRecoveryManager } from 'w3pk';
 
-// Generate invitations
-const invitation = await w3pk.generateGuardianInvite(guardianShare);
+// Setup - Create password-encrypted backup and split among guardians
+const { blob } = await w3pk.createBackupFile('password', 'MyPassword123!');
+const backupFileJson = await blob.text();
 
-// Recover (returns mnemonic - then register or import)
-const { mnemonic, ethereumAddress } = await w3pk.recoverFromGuardians(shares, password);
+const socialRecovery = new SocialRecoveryManager();
+const guardians = await socialRecovery.setupSocialRecovery(
+  backupFileJson,
+  w3pk.user.ethereumAddress,
+  [
+    { name: 'Alice', email: 'alice@example.com' },
+    { name: 'Bob', email: 'bob@example.com' },
+    { name: 'Charlie', email: 'charlie@example.com' }
+  ],
+  2 // threshold
+);
 
-// Option 1: Register new passkey (stores credentials)
-const { BackupFileManager } = await import('w3pk/backup/backup-file');
-const manager = new BackupFileManager();
-const { backupFile } = await manager.createPasswordBackup(mnemonic, ethereumAddress, 'newpass');
-await w3pk.registerWithBackupFile(JSON.stringify(backupFile), 'newpass', 'username');
+// Generate invitations for guardians
+for (const guardian of guardians) {
+  const invite = await socialRecovery.generateGuardianInvite(guardian);
+  // Send invite.qrCode and invite.shareCode to guardian
+}
 
-// Option 2: Import to existing passkey (stores credentials)
-await w3pk.login();
-await w3pk.importMnemonic(mnemonic);
+// Recover - Collect shares and reconstruct encrypted backup file
+const shares = [aliceShareCode, bobShareCode]; // JSON strings from guardians
+const { backupFileJson, ethereumAddress } = await socialRecovery.recoverFromGuardians(shares);
+
+// Decrypt and register with password
+await w3pk.registerWithBackupFile(backupFileJson, 'MyPassword123!', 'username');
 ```
 
 ---
@@ -705,17 +741,20 @@ Platform-specific:
 3. Contact your guardians (need 3 of 5)
 4. Each guardian provides their share:
    - Scan QR code, OR
-   - Enter share code manually
-5. After 3 shares collected:
-   - System reconstructs backup file
-   - Enter password if used during setup
-   - System extracts mnemonic
-6. Choose recovery path:
-   - "Register New Passkey" → Creates new WebAuthn credential, stores locally ✅
-   - "Login & Import" → Login with existing passkey, import mnemonic ✅
+   - Paste share code manually (JSON format)
+5. After collecting threshold shares (e.g., 3):
+   - System reconstructs encrypted backup file ✅
+   - Backup file is still encrypted
+6. Enter your password:
+   - This is the password you set during social recovery setup
+   - Guardians DO NOT have this password
+   - System decrypts backup file → extracts mnemonic
+7. Choose username and register:
+   - System creates new passkey on your device
+   - Wallet credentials stored locally ✅
 
 Timeline: ~24-48 hours (depends on guardian availability)
-Note: Either path stores credentials locally after recovery
+Security: Requires both guardian shares AND your password
 ```
 
 #### **Method 4: Manual Mnemonic Import**
@@ -764,7 +803,7 @@ A: You'll need to use another recovery method (passkey sync or social recovery).
 A: Mathematically secure with Shamir's Secret Sharing. Any 2 guardians cannot recover (need 3 of 5).
 
 **Q: Can guardians steal my wallet?**
-A: No, each guardian only has an encrypted piece. They need 3 pieces minimum, and even then, the backup may be password-protected.
+A: No. Guardians hold encrypted fragments of an already-encrypted backup file. Even if they collude and combine all shares, they still need your password to decrypt the backup file. The password is never shared with guardians.
 
 **Q: What happens if a guardian loses their share?**
 A: No problem! You only need 3 out of 5. As long as 3 guardians have their shares, you can recover.