w3pk 0.9.2 → 0.10.0

package/docs/API_REFERENCE.md

@@ -20,6 +20,7 @@ Complete reference for all methods, types, and utilities in the w3pk SDK.
 - [Standalone Utilities](#standalone-utilities)
   - [Validation Utilities](#validation-utilities)
   - [Build Verification Utilities](#build-verification-utilities)
+  - [Post-Quantum Cryptography](#post-quantum-cryptography)
   - [Wallet Generation Utilities](#wallet-generation-utilities)
 - [Security Inspection](#security-inspection)
   - [Browser Inspection](#browser-inspection)
@@ -1613,6 +1614,8 @@ const w3pk = createWeb3Passkey({
 
 All stealth address methods are accessed via `w3pk.stealth.*`
 
+> **🔒 Security Note:** The ERC-5564 implementation properly reduces all scalars modulo the secp256k1 curve order to prevent unspendable funds. The same reduced scalar is used consistently in both public-key operations (`s_h × G`) and private-key operations (`spendingKey + s_h`) to ensure the derived stealth address always matches the derived private key.
+
 ### `stealth.generateStealthAddress(options?: { requireAuth?: boolean }): Promise<StealthAddressResult>`
 
 Generate a fresh ERC-5564 compliant stealth address for a recipient.
@@ -2308,11 +2311,23 @@ const hybridBackup = await w3pk.createBackupFile('hybrid', 'MySecurePassword123!
 
 ---
 
-### `setupSocialRecovery(guardians: Guardian[], threshold: number): Promise<Guardian[]>`
+## Social Recovery API
+
+Social recovery is handled by the `SocialRecoveryManager` class, which splits password-encrypted backup files into guardian shares using Shamir Secret Sharing.
+
+### Import
+
+```typescript
+import { SocialRecoveryManager } from 'w3pk';
+```
 
-Set up social recovery with M-of-N guardian shares using Shamir Secret Sharing.
+### `SocialRecoveryManager.setupSocialRecovery(backupFileJson: string, ethereumAddress: string, guardians: Guardian[], threshold: number): Promise<Guardian[]>`
+
+Set up social recovery by splitting an encrypted backup file among guardians.
 
 **Parameters:**
+- `backupFileJson: string` - Password-encrypted backup file JSON
+- `ethereumAddress: string` - Ethereum address for verification
 - `guardians: Guardian[]`
   ```typescript
   interface Guardian {
@@ -2323,15 +2338,27 @@ Set up social recovery with M-of-N guardian shares using Shamir Secret Sharing.
   ```
 - `threshold: number` - Number of guardians required to recover (M in M-of-N)
 
-**Returns:** Array of guardians with encrypted shares
+**Returns:** Array of guardians with encrypted share fragments
 
-**Security:** Forces fresh authentication
+**Security:**
+- Guardians receive fragments of an already-encrypted backup file
+- Password is never shared with guardians
+- Requires both threshold shares + password to recover
 
 **Example:**
 
 ```typescript
-// Setup 3-of-5 social recovery
-const guardians = await w3pk.setupSocialRecovery(
+import { SocialRecoveryManager } from 'w3pk';
+
+// Step 1: Create password-encrypted backup file
+const { blob } = await w3pk.createBackupFile('password', 'MySecurePassword123!');
+const backupFileJson = await blob.text();
+
+// Step 2: Setup social recovery with 3-of-5 threshold
+const socialRecovery = new SocialRecoveryManager();
+const guardians = await socialRecovery.setupSocialRecovery(
+  backupFileJson,
+  w3pk.user.ethereumAddress,
   [
     { name: 'Alice', email: 'alice@example.com' },
     { name: 'Bob', phone: '+1234567890' },
@@ -2340,19 +2367,19 @@ const guardians = await w3pk.setupSocialRecovery(
     { name: 'Eve', email: 'eve@example.com' }
   ],
   3  // Need 3 guardians to recover
-)
+);
 
-console.log('Social recovery configured with', guardians.length, 'guardians')
+console.log('Social recovery configured with', guardians.length, 'guardians');
 ```
 
 ---
 
-### `generateGuardianInvite(guardianId: string): Promise<GuardianInvite>`
+### `SocialRecoveryManager.generateGuardianInvite(guardian: Guardian): Promise<GuardianInvite>`
 
-Generate invitation for a guardian with their recovery share.
+Generate invitation for a guardian with their encrypted share fragment.
 
 **Parameters:**
-- `guardianId: string` - Guardian ID
+- `guardian: Guardian` - Guardian object with share
 
 **Returns:**
 
@@ -2360,57 +2387,89 @@ Generate invitation for a guardian with their recovery share.
 interface GuardianInvite {
   guardianId: string;
   qrCode: string;        // Data URL for QR code
-  shareCode: string;     // Text code for manual entry
+  shareCode: string;     // JSON string for manual entry
   explainer: string;     // Educational text for guardian
-  link?: string;         // Optional deep link
 }
 ```
 
 **Example:**
 
 ```typescript
-const invite = await w3pk.generateGuardianInvite(guardian.id)
+const socialRecovery = new SocialRecoveryManager();
+
+for (const guardian of guardians) {
+  const invite = await socialRecovery.generateGuardianInvite(guardian);
+
+  // Show QR code to guardian
+  console.log('QR code:', invite.qrCode);
+  console.log('Share code:', invite.shareCode);
+  console.log('Instructions:', invite.explainer);
 
-// Show QR code to guardian
-console.log('Show this QR code to guardian:', invite.qrCode)
-console.log('Or share this code:', invite.shareCode)
-console.log('Instructions:', invite.explainer)
+  // Send via email, messaging app, etc.
+}
 ```
 
 ---
 
-### `recoverFromGuardians(shares: string[]): Promise<RecoveryResult>`
+### `SocialRecoveryManager.recoverFromGuardians(shares: string[]): Promise<{ backupFileJson: string; ethereumAddress: string }>`
 
-Recover wallet from guardian shares (Shamir Secret Sharing).
+Reconstruct encrypted backup file from guardian shares.
 
 **Parameters:**
-- `shares: string[]` - Array of share data from guardians (JSON strings)
+- `shares: string[]` - Array of share codes from guardians (JSON strings)
 
 **Returns:**
 
 ```typescript
-interface RecoveryResult {
-  mnemonic: string;
-  ethereumAddress: string;
+{
+  backupFileJson: string;      // Reconstructed encrypted backup file
+  ethereumAddress: string;     // Ethereum address from backup
 }
 ```
 
 **Example:**
 
 ```typescript
-// Collect shares from 3 guardians
+import { SocialRecoveryManager } from 'w3pk';
+
+const socialRecovery = new SocialRecoveryManager();
+
+// Step 1: Collect shares from 3+ guardians
 const shares = [
-  aliceShare,  // JSON string from Alice
-  bobShare,    // JSON string from Bob
-  charlieShare // JSON string from Charlie
-]
+  aliceShareCode,   // JSON string from Alice
+  bobShareCode,     // JSON string from Bob
+  charlieShareCode  // JSON string from Charlie
+];
 
-const { mnemonic, ethereumAddress } = await w3pk.recoverFromGuardians(shares)
-console.log('Wallet recovered:', ethereumAddress)
-console.log('Mnemonic:', mnemonic)
+// Step 2: Reconstruct encrypted backup file
+const { backupFileJson, ethereumAddress } = await socialRecovery.recoverFromGuardians(shares);
+console.log('Backup file reconstructed for:', ethereumAddress);
 
-// Now import the mnemonic
-await w3pk.importMnemonic(mnemonic)
+// Step 3: Decrypt with password and register
+const password = 'MySecurePassword123!'; // Password set during setup
+await w3pk.registerWithBackupFile(backupFileJson, password, 'username');
+console.log('Wallet recovered and registered!');
+```
+
+---
+
+### `SocialRecoveryManager.getSocialRecoveryConfig(): SocialRecoveryConfig | null`
+
+Get current social recovery configuration from localStorage.
+
+**Returns:** Social recovery configuration or null if not set up
+
+**Example:**
+
+```typescript
+const socialRecovery = new SocialRecoveryManager();
+const config = socialRecovery.getSocialRecoveryConfig();
+
+if (config) {
+  console.log('Threshold:', config.threshold);
+  console.log('Total guardians:', config.totalGuardians);
+  console.log('Guardians:', config.guardians);
+}
 ```
 
 ---
@@ -3151,7 +3210,89 @@ console.log(encoded) // => SGVsbG8gV29ybGQ=
 ### Cryptographic Utilities
 
 ```typescript
-import { extractRS } from 'w3pk'
+import {
+  extractRS,
+  deriveEncryptionKeyFromWebAuthn,
+  generateSalt
+} from 'w3pk'
+```
+
+#### `deriveEncryptionKeyFromWebAuthn(prfOutput: ArrayBuffer, salt: Uint8Array): Promise<CryptoKey>`
+
+**🔐 SECURE - WebAuthn PRF-based encryption**
+
+Derives an AES-256-GCM encryption key from WebAuthn PRF (Pseudo-Random Function) extension output.
+
+**Security:**
+- Uses authenticator-held secrets via PRF extension (never exposed)
+- Implements random unique salts (no precomputation attacks)
+- PBKDF2 with 210,000 iterations (OWASP 2023 recommendation)
+- Prevents offline decryption attacks
+
+**Parameters:**
+- `prfOutput: ArrayBuffer` - 32-byte secret from WebAuthn PRF extension
+- `salt: Uint8Array` - 32-byte random salt (generate with `generateSalt()`)
+
+**Returns:** `Promise<CryptoKey>` - AES-256-GCM key for encryption/decryption
+
+**Example:**
+```typescript
+// 1. Enable PRF during WebAuthn registration
+const credential = await navigator.credentials.create({
+  publicKey: {
+    challenge: new Uint8Array(32),
+    rp: { name: "Example" },
+    user: { id: userId, name: "user", displayName: "User" },
+    pubKeyCredParams: [{ alg: -7, type: "public-key" }],
+    extensions: {
+      prf: {}  // Enable PRF extension
+    }
+  }
+});
+
+// 2. Get PRF output during authentication
+const assertion = await navigator.credentials.get({
+  publicKey: {
+    challenge: new Uint8Array(32),
+    extensions: {
+      prf: {
+        eval: {
+          first: new Uint8Array(32)  // Salt for PRF
+        }
+      }
+    }
+  }
+});
+
+const prfOutput = assertion.getClientExtensionResults().prf.results.first;
+
+// 3. Generate and store salt
+const salt = generateSalt();  // Store this with your ciphertext
+
+// 4. Derive encryption key
+const encryptionKey = await deriveEncryptionKeyFromWebAuthn(
+  prfOutput,
+  salt
+);
+
+// 5. Encrypt sensitive data
+const encrypted = await crypto.subtle.encrypt(
+  { name: "AES-GCM", iv: crypto.getRandomValues(new Uint8Array(12)) },
+  encryptionKey,
+  new TextEncoder().encode("secret data")
+);
+```
+
+#### `generateSalt(): Uint8Array`
+
+Generates a cryptographically secure random 32-byte salt for encryption.
+
+**Returns:** `Uint8Array` - 32 random bytes
+
+**Example:**
+```typescript
+const salt = generateSalt();
+// Store salt alongside ciphertext for later decryption
 ```
 
 #### `extractRS(derSignature: Uint8Array): { r: string; s: string }`
@@ -3209,6 +3350,189 @@ This ensures compatibility with Ethereum's signature malleability protection.
 
 ---
 
+### Post-Quantum Cryptography
+
+w3pk provides ML-KEM-1024 encryption both as instance methods (recommended) and standalone functions.
+
+#### Instance Methods (Recommended)
+
+Use these methods with your w3pk wallet instance - no private key exposure:
+
+##### `w3pk.deriveMLKemPublicKey(options?): Promise<string>`
+
+Derive your ML-KEM-1024 public key for sharing with others.
+
+**Parameters:**
+```typescript
+{
+  context?: string;        // Domain separation (default: 'mlkem-v1')
+  mode?: SecurityMode;     // 'STANDARD', 'STRICT', or 'YOLO' (default: 'STANDARD')
+  tag?: string;            // Address derivation tag (default: 'MAIN')
+  origin?: string;         // Origin (default: current origin)
+  requireAuth?: boolean;   // Force re-auth (default: false, always true in STRICT)
+}
+```
+
+**Returns:** Base64-encoded public key (1568 bytes)
+
+**Example:**
+```typescript
+const w3pk = createWeb3Passkey();
+await w3pk.login();
+
+const myPubKey = await w3pk.deriveMLKemPublicKey();
+// Share myPubKey with others
+```
+
+**Note:** PRIMARY mode not supported (uses P-256 WebAuthn keys).
+
+---
+
+##### `w3pk.mlkemEncrypt(plaintext: string, recipientPublicKeys: Array<string | Uint8Array>, options?): Promise<EncryptedPayload>`
+
+Encrypt data for yourself and additional recipients.
+
+**Parameters:**
+```typescript
+{
+  context?: string;        // Domain separation (default: 'mlkem-v1')
+  mode?: SecurityMode;     // Security mode (default: 'STANDARD')
+  tag?: string;            // Tag (default: 'MAIN')
+  origin?: string;         // Origin (default: current)
+  requireAuth?: boolean;   // Force re-auth (default: false)
+}
+```
+
+**Example:**
+```typescript
+const serverPubKey = await fetch('/api/mlkem-key').then(r => r.text());
+
+const encrypted = await w3pk.mlkemEncrypt(
+  'my secret data',
+  [serverPubKey]  // You + server can both decrypt
+);
+```
+
+---
+
+##### `w3pk.mlkemDecrypt(payload: EncryptedPayload, options?): Promise<string>`
+
+Decrypt data encrypted for your wallet.
+
+**Parameters:** Same options as `mlkemEncrypt`
+
+**Example:**
+```typescript
+const plaintext = await w3pk.mlkemDecrypt(encrypted);
+```
+
+---
+
+#### Standalone Functions
+
+Low-level functions for direct key management:
+
+```typescript
+import { mlkemEncrypt, mlkemDecrypt, deriveMLKemKeypair, type EncryptedPayload } from 'w3pk'
+```
+
+##### `deriveMLKemKeypair(privateKey: string | Uint8Array, context?: string): Promise<MLKemKeypair>`
+
+Derive deterministic ML-KEM keypair from any private key using HKDF-SHA256.
+
+**Parameters:**
+- `privateKey` - Ethereum private key (hex with optional `0x` prefix or Uint8Array)
+- `context` - Context string for domain separation (default: `'mlkem-v1'`)
+
+**Returns:**
+```typescript
+{
+  publicKey: Uint8Array;   // 1568 bytes
+  privateKey: Uint8Array;  // 3168 bytes
+}
+```
+
+**Example:**
+```typescript
+const keypair = await deriveMLKemKeypair('0x1234...', 'my-app');
+```
+
+---
+
+##### `mlkemEncrypt(plaintext: string, publicKeys: (string | Uint8Array) | Array<string | Uint8Array>): Promise<EncryptedPayload>`
+
+Encrypt data using ML-KEM-1024 (post-quantum KEM) + AES-256-GCM for one or more recipients.
+
+**Parameters:**
+- `plaintext: string` - The data to encrypt
+- `publicKeys: (string | Uint8Array) | Array<string | Uint8Array>` - Single public key or array of ML-KEM-1024 public keys (1568 bytes each)
+
+**Returns:**
+```typescript
+{
+  recipients: Array<{
+    publicKey: string;    // Base64 recipient public key (1568 bytes)
+    ciphertext: string;   // Base64 ML-KEM ciphertext for this recipient (1600 bytes)
+  }>;
+  encryptedData: string;  // Base64 AES-encrypted data (shared across all recipients)
+  iv: string;             // Base64 initialization vector (12 bytes)
+  authTag: string;        // Base64 authentication tag (16 bytes)
+}
+```
+
+**Example:**
+
+```typescript
+import { mlkemEncrypt } from 'w3pk'
+
+// Single recipient
+const encrypted = await mlkemEncrypt('my secret data', publicKey1)
+
+// Multiple recipients
+const encrypted = await mlkemEncrypt('my secret data', [publicKey1, publicKey2, publicKey3])
+
+console.log('Recipients:', encrypted.recipients.length)
+```
+
+**Security:**
+- ✅ **Quantum-resistant** - ML-KEM-1024 (NIST FIPS 203)
+- ✅ **Multi-recipient support** - Encrypt once for multiple recipients
+- ✅ **Key zeroization** - All secrets securely wiped from memory
+- ✅ **Authenticated encryption** - AES-256-GCM with 128-bit auth tag
+
+---
+
+#### `mlkemDecrypt(payload: EncryptedPayload, privateKey: string | Uint8Array, publicKey?: string | Uint8Array): Promise<string>`
+
+Decrypt data encrypted with `mlkemEncrypt()`.
+
+**Parameters:**
+- `payload: EncryptedPayload` - The encrypted payload from `mlkemEncrypt()`
+- `privateKey: string | Uint8Array` - ML-KEM-1024 private key (3168 bytes)
+- `publicKey?: string | Uint8Array` - (Optional) Your public key for faster recipient lookup (1568 bytes)
+
+**Returns:** `string` - Decrypted plaintext
+
+**Example:**
+
+```typescript
+import { mlkemDecrypt } from 'w3pk'
+
+// Auto-detect which recipient you are
+const plaintext = await mlkemDecrypt(encrypted, privateKey)
+
+// Or specify your public key for faster lookup
+const plaintext = await mlkemDecrypt(encrypted, privateKey, myPublicKey)
+```
+
+**Throws:** Error if decryption fails (invalid key, no matching recipient, corrupted data, or tampered auth tag)
+
+**Related:**
+- See [POST_QUANTUM.md](../docs/POST_QUANTUM.md) for full quantum readiness roadmap
+- See [NIST FIPS 203](https://csrc.nist.gov/pubs/fips/203/final) for ML-KEM specification
+
+---
+
 ### Wallet Generation Utilities
 
 ```typescript

package/docs/ARCHITECTURE.md

@@ -148,33 +148,42 @@ m/44'/60'/0'/0/2  ← Third address
 
 **Purpose**: Link WebAuthn authentication to wallet encryption
 
-**Implementation**: [src/wallet/crypto.ts:21-66](src/wallet/crypto.ts#L21-L66)
+**Implementation**: [src/wallet/crypto.ts](src/wallet/crypto.ts)
+
+✅ **SECURITY**: Uses PRF-based encryption with authenticator-held secrets and random salts
 
-**Process**:
+**SECURE Implementation (PRF-based)**:
 ```typescript
 function deriveEncryptionKeyFromWebAuthn(
-  credentialId: string,
-  publicKey: string
+  prfOutput: ArrayBuffer,  // From WebAuthn PRF extension
+  salt: Uint8Array         // Random 32-byte salt
 ): CryptoKey {
-  // Step 1: Combine inputs
-  const keyMaterial = `w3pk-v4:${credentialId}:${publicKey}`;
+  // Step 1: Validate inputs
+  assert(prfOutput.byteLength === 32);
+  assert(salt.byteLength === 32);
 
-  // Step 2: Hash with SHA-256
-  const hash = SHA256(keyMaterial);
+  // Step 2: Import PRF output (authenticator-held secret)
+  const keyMaterial = importKey(prfOutput);
 
-  // Step 3: PBKDF2 key derivation (210,000 iterations)
-  const encryptionKey = PBKDF2(hash, salt, 210000);
+  // Step 3: PBKDF2 key derivation with random salt
+  const encryptionKey = PBKDF2(keyMaterial, salt, 210000);
 
   // Result: AES-256-GCM key (NEVER STORED)
   return encryptionKey;
 }
 ```
 
-**Properties**:
-- **Deterministic**: Same inputs → Same output
-- **Secure**: 210,000 PBKDF2 iterations (OWASP 2023)
-- **Stateless**: No key storage required
-- **Authentication-gated**: Requires biometric/PIN to access inputs
+**Security Properties**:
+- **Authenticator Secret**: Uses PRF output from hardware (never exposed to application)
+- **Random Salts**: Each encryption uses unique 32-byte salt (prevents precomputation)
+- **PBKDF2**: 210,000 iterations (OWASP 2023 recommendation)
+- **AES-256-GCM**: Strong authenticated encryption
+- **Authentication-gated**: Requires biometric/PIN to trigger PRF
+
+**Implementation Note**:
+The SDK uses `deriveEncryptionKeyAuto()` as a helper that:
+1. Uses PRF-based encryption when available (secure)
+2. Falls back to v2 implementation for existing wallets without PRF support
 
 ---
 
@@ -217,11 +226,12 @@ STEP 2: Create WebAuthn Credential (INDEPENDENT)
 
 STEP 3: Derive Encryption Key
 ┌──────────────────────────────────────┐
-│  deriveEncryptionKeyFromWebAuthn()   │
+│ deriveEncryptionKeyFromWebAuthn()    │
 │                                      │
-│  Input: credentialId + publicKey     │
+│ Input: PRF output (32 bytes secret)  │
+│        + random salt (32 bytes)      │
 │       ↓                              │
-│  SHA-256 hash                        │
+│  Import PRF as key material          │
 │       ↓                              │
 │  PBKDF2 (210,000 iterations)         │
 │       ↓                              │
@@ -486,43 +496,29 @@ const signedTx = await wallet.signTransaction(tx);
 **Implementation**: [src/wallet/crypto.ts:21-66](src/wallet/crypto.ts#L21-L66)
 
 ```javascript
+// SECURE: PRF-based key derivation
 async function deriveEncryptionKeyFromWebAuthn(
-  credentialId: string,
-  publicKey: string
+  prfOutput: ArrayBuffer,  // From WebAuthn PRF extension
+  salt: Uint8Array         // Random 32-byte salt
 ): Promise<CryptoKey> {
-  // 1. Combine inputs into key material
-  const keyMaterial = `w3pk-v4:${credentialId}:${publicKey}`;
-
-  // 2. SHA-256 hash
-  const keyMaterialHash = await crypto.subtle.digest(
-    "SHA-256",
-    new TextEncoder().encode(keyMaterial)
-  );
-
-  // 3. Import as PBKDF2 base key
-  const importedKey = await crypto.subtle.importKey(
+  // 1. Import PRF output as key material (authenticator secret)
+  const keyMaterial = await crypto.subtle.importKey(
     "raw",
-    keyMaterialHash,
+    prfOutput,  // SECRET from authenticator
     { name: "PBKDF2" },
     false,
     ["deriveKey"]
   );
 
-  // 4. Generate deterministic salt
-  const salt = await crypto.subtle.digest(
-    "SHA-256",
-    new TextEncoder().encode("w3pk-salt-v4")
-  );
-
-  // 5. Derive AES-256-GCM key
+  // 2. Derive AES-256-GCM key with PBKDF2
   return crypto.subtle.deriveKey(
     {
       name: "PBKDF2",
-      salt: new Uint8Array(salt),
+      salt: salt,  // Random 32-byte salt (stored with ciphertext)
       iterations: 210000,  // OWASP 2023 recommendation
       hash: "SHA-256",
     },
-    importedKey,
+    keyMaterial,  // PRF output from authenticator
     { name: "AES-GCM", length: 256 },
     false,
     ["encrypt", "decrypt"]
@@ -530,11 +526,12 @@ async function deriveEncryptionKeyFromWebAuthn(
 }
 ```
 
-**Properties**:
-- **Deterministic**: Same inputs always produce same output
-- **Secure**: 210,000 iterations make brute-force impractical
+**Security Properties**:
+- **Authenticator-Bound**: PRF output is hardware-held secret (never exposed)
+- **Unique Salts**: Each encryption uses random salt (no precomputation)
+- **Strong KDF**: 210,000 PBKDF2 iterations make brute-force impractical (OWASP 2023)
 - **Stateless**: No need to store the encryption key
-- **Fast enough**: ~100-200ms on modern devices
+- **Fast**: ~100-200ms on modern devices
 
 ---