w3pk 0.9.2 → 0.10.0

package/docs/SECURITY.md

@@ -2,6 +2,8 @@
 
 This document explains the security model of w3pk and how wallet protection works.
 
+✅ **SECURITY**: Uses PRF-based encryption with authenticator-held secrets and random salts to prevent offline decryption attacks. See [PRF-based Encryption](#migration-to-prf-based-encryption) section below.
+
 ## Overview
 
 w3pk provides **multiple layers of security** to protect user wallets:
@@ -12,7 +14,7 @@ w3pk provides **multiple layers of security** to protect user wallets:
 4. **Mode-based access control** - STANDARD/STRICT modes are view-only, YOLO mode provides full access
 5. **Encrypted storage** - AES-256-GCM encryption at rest
 6. **Secure sessions** - In-memory and optional persistent sessions (disabled in STRICT mode)
-7. **Persistent session encryption** - WebAuthn-derived key encryption for "Remember Me" functionality
+7. **PRF-based encryption** - WebAuthn PRF extension for secure key derivation (v0.9.4+)
 
 ## Enhanced Security Model (v0.8.0+)
 
@@ -1081,32 +1083,96 @@ Signature:   ${authorization.r.substring(0, 10)}...
 
 This section tracks major security-related changes to w3pk's implementation.
 
-### v0.7.0+ (Current)
+### v0.9.4+ - PRF-Based Encryption (Critical Security Fix)
 
-#### Removed: `deriveEncryptionKeyFromSignature()` (Commit 182740c)
-**Impact:** Security improvement
+#### BREAKING: `deriveEncryptionKeyFromWebAuthn()` signature changed
+**Impact:** Fixes critical encryption vulnerabilities (BREAKING CHANGE)
 
 **What changed:**
-- Removed the `deriveEncryptionKeyFromSignature()` function
-- This was a testing/legacy fallback for signature-based key derivation
-- Code comment warned: "Does NOT require biometric authentication for decryption"
+- `deriveEncryptionKeyFromWebAuthn()` signature changed from `(credentialId, publicKey?)` to `(prfOutput, salt)`
+- Now uses WebAuthn PRF extension to obtain authenticator-held secrets
+- Implements random unique salts instead of hardcoded constants
+- Added `generateSalt()` helper for creating cryptographic random salts
 
-**Why this improves security:**
-- Eliminates a weaker encryption path that could have been misused
-- Reduces code complexity and potential for developer errors
-- Single clear encryption method (`deriveEncryptionKeyFromWebAuthn()`)
-- Prevents accidental use of signature-based approach without proper session management
+**Security improvements:**
+- ✅ Key material now derived from authenticator secret (PRF output), not public credentialId/publicKey
+- ✅ Uses random 32-byte salts stored with ciphertext, not hardcoded constants
+- ✅ Eliminates offline decryption vulnerability
+- ✅ Prevents precomputation attacks
+
+**Migration required:**
+```typescript
+// ❌ OLD (v0.9.3 and earlier) - INSECURE
+const key = await deriveEncryptionKeyFromWebAuthn(credentialId, publicKey);
+
+// ✅ NEW (v0.9.4+) - SECURE
+const assertion = await navigator.credentials.get({
+  publicKey: {
+    challenge: new Uint8Array(32),
+    extensions: {
+      prf: { eval: { first: new Uint8Array(32) } }
+    }
+  }
+});
+const prfOutput = assertion.getClientExtensionResults().prf.results.first;
+const salt = generateSalt();  // Store with ciphertext
+const key = await deriveEncryptionKeyFromWebAuthn(prfOutput, salt);
+```
+
+**Status:**
+- ✅ Secure implementation complete
+- 🔴 Breaking change - migration required
+- 📖 Migration guide below
 
-**Migration:** No action needed. This function was never the primary method and was only used for testing.
+See: [Migration to PRF-based Encryption](#migration-to-prf-based-encryption)
+
+---
+
+### v0.9.4+ - ERC-5564 Stealth Scalar Reduction Fix (High Severity)
+
+#### Fixed stealth address scalar reduction vulnerability
+
+**What changed:**
+- Added `reduceScalarModN()` function to properly reduce scalars modulo secp256k1 curve order
+- Updated `generateStealthAddress()`, `checkStealthAddress()`, and `computeStealthPrivateKey()` to use reduced scalars
+- Ensures the same reduced scalar `s_h` is used consistently in both public-key and private-key operations
+
+**Security improvements:**
+- ✅ Prevents intermittent failures when keccak256(sharedSecret) ≥ curve order
+- ✅ Eliminates risk of unspendable stealth funds caused by inconsistent scalar handling
+- ✅ Ensures derived stealth address always matches derived private key
+- ✅ Validates scalars are in valid range [1, n-1] and rejects zero
+
+**Technical details:**
+- ERC-5564 computes `s_h = keccak256(sharedSecret)` and uses it as a scalar
+- Previously, `s_h` was used directly without reduction modulo `n` (secp256k1 curve order)
+- Public-key path: `stealthPubKey = spendingPubKey + (s_h × G)` would fail if `s_h ≥ n`
+- Private-key path: `stealthPrivKey = spendingKey + s_h` reduced the sum but not `s_h` itself
+- Inconsistent scalar values between paths could result in address/key mismatch
+- Now both paths use the same properly-reduced scalar
+
+**Impact:**
+- Non-breaking change (pure bugfix)
+- All existing stealth addresses remain valid
+- Eliminates edge-case failures and unspendable funds
+
+---
 
-#### Current Encryption Method
-**Primary:** `deriveEncryptionKeyFromWebAuthn(credentialId, publicKey)`
-- Deterministic key derivation from credential metadata
-- PBKDF2 with 210,000 iterations (OWASP 2023)
-- Fixed salt: `"w3pk-salt-v4"`
-- Security relies on SDK authentication-gating
+#### No Backward Compatibility
+**Decision:** Complete removal of insecure legacy function
 
-**Status:** Working as intended. This approach enables session management while maintaining security through WebAuthn authentication requirements.
+**What was removed:**
+- Removed `deriveEncryptionKeyFromWebAuthnLegacy()` function entirely
+- No backward compatibility layer for insecure encryption
+
+**Why:**
+- Legacy function had critical security vulnerabilities
+- Offline decryption attack risk unacceptable
+- Clean break ensures no accidental use of insecure method
+
+**Migration:** All call sites updated to use `deriveEncryptionKeyAuto()` which:
+- Uses PRF-based encryption when available (secure)
+- Falls back to v2 implementation internally for wallets without PRF support
 
 ### v0.7.0 - RP ID Auto-Detection (Security Hardening)
 
@@ -3683,6 +3749,159 @@ This democratizes security analysis and helps users make informed decisions abou
 
 ---
 
+## Migration to PRF-based Encryption
+
+### Overview
+
+The secure `deriveEncryptionKeyFromWebAuthn()` uses PRF-based encryption to prevent vulnerabilities:
+- **Fixed**: Now derives encryption key from authenticator-held secret (PRF output), not public credential data
+- **Fixed**: Uses random unique salts, not hardcoded constants
+
+**Benefits**: Prevents offline decryption attacks by requiring authenticator interaction.
+
+### Migration Steps
+
+#### 1. Enable PRF Extension in Registration
+
+```typescript
+// Update WebAuthn registration to enable PRF
+const credential = await navigator.credentials.create({
+  publicKey: {
+    challenge: crypto.getRandomValues(new Uint8Array(32)),
+    rp: {
+      name: "Your App",
+      id: window.location.hostname
+    },
+    user: {
+      id: userId,
+      name: username,
+      displayName: username
+    },
+    pubKeyCredParams: [{ alg: -7, type: "public-key" }],
+    authenticatorSelection: {
+      authenticatorAttachment: "platform",
+      userVerification: "required"
+    },
+    extensions: {
+      prf: {}  // ← Enable PRF extension
+    }
+  }
+});
+
+// Check if PRF is supported
+const prfEnabled = credential.getClientExtensionResults().prf?.enabled;
+if (!prfEnabled) {
+  console.warn("PRF not supported on this authenticator");
+  // Fall back to legacy method or require different authenticator
+}
+```
+
+#### 2. Capture PRF Output During Authentication
+
+```typescript
+// Get PRF output during WebAuthn assertion
+const prfSalt = crypto.getRandomValues(new Uint8Array(32));
+
+const assertion = await navigator.credentials.get({
+  publicKey: {
+    challenge: crypto.getRandomValues(new Uint8Array(32)),
+    rpId: window.location.hostname,
+    extensions: {
+      prf: {
+        eval: {
+          first: prfSalt  // Input to PRF (can be constant per credential)
+        }
+      }
+    }
+  }
+});
+
+// Extract PRF output
+const prfResults = assertion.getClientExtensionResults().prf;
+if (!prfResults?.results?.first) {
+  throw new Error("PRF output not available");
+}
+const prfOutput = prfResults.results.first;  // 32-byte secret
+```
+
+#### 3. Generate and Store Salt with Ciphertext
+
+```typescript
+import { deriveEncryptionKeyFromWebAuthn, generateSalt } from 'w3pk';
+
+// Generate random salt (do this once per encryption)
+const salt = generateSalt();  // 32 random bytes
+
+// Derive secure encryption key
+const encryptionKey = await deriveEncryptionKeyFromWebAuthn(
+  prfOutput,  // From authenticator (secret)
+  salt        // Random (store with ciphertext)
+);
+
+// Encrypt wallet data
+const encrypted = await crypto.subtle.encrypt(
+  { name: "AES-GCM", iv: crypto.getRandomValues(new Uint8Array(12)) },
+  encryptionKey,
+  new TextEncoder().encode(mnemonic)
+);
+
+// Store both salt and ciphertext together
+await storage.save({
+  encryptedMnemonic: base64(encrypted),
+  salt: base64(salt),  // ← Must be stored for decryption
+  credentialId: credential.id
+});
+```
+
+#### 4. Decrypt Using Stored Salt
+
+```typescript
+// Load encrypted data
+const data = await storage.load();
+const salt = base64Decode(data.salt);
+const encryptedMnemonic = base64Decode(data.encryptedMnemonic);
+
+// Get PRF output (same as step 2)
+const assertion = await navigator.credentials.get({
+  publicKey: {
+    challenge: crypto.getRandomValues(new Uint8Array(32)),
+    extensions: {
+      prf: { eval: { first: prfSalt } }
+    }
+  }
+});
+const prfOutput = assertion.getClientExtensionResults().prf.results.first;
+
+// Derive key with stored salt
+const encryptionKey = await deriveEncryptionKeyFromWebAuthn(prfOutput, salt);
+
+// Decrypt
+const decrypted = await crypto.subtle.decrypt(
+  { name: "AES-GCM", iv: extractIV(encryptedMnemonic) },
+  encryptionKey,
+  encryptedMnemonic
+);
+```
+
+### Browser Support
+
+PRF extension support (as of 2026):
+- ✅ Chrome/Edge 108+ (Windows Hello, Touch ID)
+- ✅ Safari 17+ (Touch ID, Face ID)
+- ✅ Firefox 122+ (limited)
+- ⚠️ Check with `getClientExtensionResults().prf.enabled`
+
+### Impact on Existing Users
+
+✅ **NO BREAKING CHANGE for SDK users**: The SDK handles migration automatically via `deriveEncryptionKeyAuto()`.
+
+**For direct API users:**
+- **Function signature changed**: `deriveEncryptionKeyFromWebAuthn()` now requires `(prfOutput, salt)` parameters
+- **Legacy function removed**: No `deriveEncryptionKeyFromWebAuthnLegacy()` available
+- **Migration path**: Use PRF-based encryption or use the auto-fallback helper
+
+---
+
 ## Post-Quantum Cryptography
 
 w3pk is preparing for the future quantum computing threat. While quantum computers capable of breaking current cryptography (ECDSA, secp256k1) are estimated to be **10-15 years away**, we have a comprehensive migration roadmap in place.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w3pk",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "WebAuthn SDK for passwordless authentication, encrypted wallets, ERC-5564 stealth addresses, and zero-knowledge proofs",
   "author": "Julien Béranger",
   "license": "GPL-3.0",
@@ -84,30 +84,34 @@
     "scripts/compute-build-hash.mjs"
   ],
   "devDependencies": {
-    "@types/node": "^24.9.0",
+    "@types/node": "^25.9.2",
     "@types/qrcode": "^1.5.5",
     "circomlib": "^2.0.5",
     "tsup": "^8.5.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "ethers": "^6.0.0"
   },
   "optionalDependencies": {
-    "@ipld/car": "^5.4.2",
-    "blockstore-core": "^6.1.1",
+    "@ipld/car": "^5.4.6",
+    "blockstore-core": "^7.0.1",
     "circomlibjs": "^0.1.7",
-    "ipfs-unixfs-importer": "^16.0.1",
+    "ipfs-unixfs-importer": "^17.0.1",
     "qrcode": "^1.5.4",
-    "snarkjs": "^0.7.5"
+    "snarkjs": "^0.7.6"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.2.0",
+    "mlkem": "^2.7.0"
   },
   "scripts": {
     "build": "tsup",
     "build:zk": "npm run build && npm run compile:circuits",
     "compile:circuits": "node scripts/compile-circuits.js",
     "dev": "tsup --watch",
-    "test": "tsx test/test.ts && tsx test/comprehensive.test.ts && tsx test/backup.test.ts && tsx test/social-recovery.test.ts && tsx test/recovery-education.test.ts && tsx test/zk/zk.test.ts && tsx test/nft-ownership.test.ts && tsx test/chainlist.test.ts && tsx test/eip7702.test.ts && tsx test/external-wallet.test.ts && tsx test/erc5564.test.ts && tsx test/zk/key-stretching.test.ts && tsx test/username-encoding.test.ts && tsx test/username-validation.test.ts && tsx test/origin-derivation.test.ts && tsx test/build-hash.test.ts && tsx test/credential-checking.test.ts && tsx test/webauthn-native.test.ts && tsx test/persistent-session.test.ts && tsx test/sign-message.test.ts && tsx test/siwe.test.ts && tsx test/requirereauth.test.ts && tsx test/eip7951.test.ts && tsx test/send-transaction.test.ts && tsx test/eip1193-provider.test.ts",
+    "test": "tsx test/test.ts && tsx test/comprehensive.test.ts && tsx test/backup.test.ts && tsx test/social-recovery.test.ts && tsx test/recovery-education.test.ts && tsx test/zk/zk.test.ts && tsx test/nft-ownership.test.ts && tsx test/chainlist.test.ts && tsx test/eip7702.test.ts && tsx test/external-wallet.test.ts && tsx test/erc5564.test.ts && tsx test/zk/key-stretching.test.ts && tsx test/username-encoding.test.ts && tsx test/username-validation.test.ts && tsx test/origin-derivation.test.ts && tsx test/build-hash.test.ts && tsx test/credential-checking.test.ts && tsx test/webauthn-native.test.ts && tsx test/persistent-session.test.ts && tsx test/sign-message.test.ts && tsx test/siwe.test.ts && tsx test/requirereauth.test.ts && tsx test/eip7951.test.ts && tsx test/send-transaction.test.ts && tsx test/eip1193-provider.test.ts && tsx test/mlkem.test.ts",
     "test:basic": "tsx test/test.ts",
     "test:comprehensive": "tsx test/comprehensive.test.ts",
     "test:backup": "tsx test/backup.test.ts",
@@ -125,7 +129,6 @@
     "test:sign-message": "tsx test/sign-message.test.ts",
     "test:siwe": "tsx test/siwe.test.ts",
     "build:hash": "node scripts/compute-build-hash.mjs",
-    "release:notes": "node scripts/generate-release-notes.mjs",
     "html": "lsof -ti:3000 | xargs kill -9 2>/dev/null || true && tsup && npx serve . -l 3000 & sleep 5 && open http://localhost:3000/standalone/checker.html"
   }
 }