w3pk 0.10.1 → 0.10.2

package/docs/API_REFERENCE.md

@@ -57,6 +57,8 @@ interface PersistentSessionConfig {
 }
 ```
 
+**PRF requirement:** persistent sessions are encrypted under a key derived from the WebAuthn PRF extension, which the authenticator only releases during a user-verified assertion. On authenticators without PRF support, no persistent session is stored — the device falls back to in-memory sessions only (there is no weaker at-rest fallback). The session is re-keyed at every real (prompted) login; the configured `duration` is therefore also the renewal interval. With `requireReauth: true` the decryption key is never written to disk; with `requireReauth: false` it is stored as a non-extractable `CryptoKey` to allow silent restore. See [SECURITY.md](./SECURITY.md#at-rest-encryption-what-it-protects-and-what-it-doesnt) for the full model.
+
 **Example:**
 
 ```typescript
@@ -2847,13 +2849,12 @@ Enable persistent sessions to maintain user login across page refreshes.
 4. `requireReauth: true` prompts for biometric on refresh (more secure)
 5. `requireReauth: false` silently restores session (more convenient)
 
-**Security:**
-- Sessions only persist for STANDARD and YOLO modes
-- STRICT mode sessions are NEVER persisted
-- Encrypted at rest with WebAuthn-derived key
-- Requires valid WebAuthn credential to decrypt
-- Time-limited expiration
-- Origin-isolated via IndexedDB
+**Security (read the trade-off):**
+- Sessions only persist for STANDARD and YOLO modes; STRICT mode is NEVER persisted
+- Time-limited expiration; origin-isolated via IndexedDB
+- ⚠️ The "WebAuthn-derived key" is derived from **public** credential metadata stored in the same browser profile, **not** from an authenticator-held secret. A persistent session is therefore **decryptable by anyone who can read this origin's storage** (malicious extension, XSS exfil, disk image), and it keeps the seed in that state for the whole duration it's enabled. This is a UX-for-security trade-off, not hardware-backed protection.
+- Enabling "Remember Me" does not add a new trust dependency (you already trust your origin's code), it **widens the window** in which a compromise of your origin can reach the seed. Keep `duration` short for higher-value wallets; don't enable on shared/untrusted devices.
+- Full threat model: **[SECURITY.md → At-Rest Encryption](./SECURITY.md#at-rest-encryption-what-it-protects-and-what-it-doesnt)**.
 
 **Example:**
 
@@ -3210,89 +3211,7 @@ console.log(encoded) // => SGVsbG8gV29ybGQ=
 ### Cryptographic Utilities
 
 ```typescript
-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
+import { extractRS } from 'w3pk'
 ```
 
 #### `extractRS(derSignature: Uint8Array): { r: string; s: string }`

package/docs/ARCHITECTURE.md

@@ -148,42 +148,33 @@ m/44'/60'/0'/0/2  ← Third address
 
 **Purpose**: Link WebAuthn authentication to wallet encryption
 
-**Implementation**: [src/wallet/crypto.ts](src/wallet/crypto.ts)
-
-✅ **SECURITY**: Uses PRF-based encryption with authenticator-held secrets and random salts
+**Implementation**: [src/wallet/crypto.ts:21-66](src/wallet/crypto.ts#L21-L66)
 
-**SECURE Implementation (PRF-based)**:
+**Process**:
 ```typescript
 function deriveEncryptionKeyFromWebAuthn(
-  prfOutput: ArrayBuffer,  // From WebAuthn PRF extension
-  salt: Uint8Array         // Random 32-byte salt
+  credentialId: string,
+  publicKey: string
 ): CryptoKey {
-  // Step 1: Validate inputs
-  assert(prfOutput.byteLength === 32);
-  assert(salt.byteLength === 32);
+  // Step 1: Combine inputs
+  const keyMaterial = `w3pk-v4:${credentialId}:${publicKey}`;
 
-  // Step 2: Import PRF output (authenticator-held secret)
-  const keyMaterial = importKey(prfOutput);
+  // Step 2: Hash with SHA-256
+  const hash = SHA256(keyMaterial);
 
-  // Step 3: PBKDF2 key derivation with random salt
-  const encryptionKey = PBKDF2(keyMaterial, salt, 210000);
+  // Step 3: PBKDF2 key derivation (210,000 iterations)
+  const encryptionKey = PBKDF2(hash, salt, 210000);
 
   // Result: AES-256-GCM key (NEVER STORED)
   return encryptionKey;
 }
 ```
 
-**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
+**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
 
 ---
 
@@ -226,12 +217,11 @@ STEP 2: Create WebAuthn Credential (INDEPENDENT)
 
 STEP 3: Derive Encryption Key
 ┌──────────────────────────────────────┐
-│ deriveEncryptionKeyFromWebAuthn()    │
+│  deriveEncryptionKeyFromWebAuthn()   │
 │                                      │
-│ Input: PRF output (32 bytes secret)  │
-│        + random salt (32 bytes)      │
+│  Input: credentialId + publicKey     │
 │       ↓                              │
-│  Import PRF as key material          │
+│  SHA-256 hash                        │
 │       ↓                              │
 │  PBKDF2 (210,000 iterations)         │
 │       ↓                              │
@@ -496,29 +486,43 @@ 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(
-  prfOutput: ArrayBuffer,  // From WebAuthn PRF extension
-  salt: Uint8Array         // Random 32-byte salt
+  credentialId: string,
+  publicKey: string
 ): Promise<CryptoKey> {
-  // 1. Import PRF output as key material (authenticator secret)
-  const keyMaterial = await crypto.subtle.importKey(
+  // 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(
     "raw",
-    prfOutput,  // SECRET from authenticator
+    keyMaterialHash,
     { name: "PBKDF2" },
     false,
     ["deriveKey"]
   );
 
-  // 2. Derive AES-256-GCM key with PBKDF2
+  // 4. Generate deterministic salt
+  const salt = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode("w3pk-salt-v4")
+  );
+
+  // 5. Derive AES-256-GCM key
   return crypto.subtle.deriveKey(
     {
       name: "PBKDF2",
-      salt: salt,  // Random 32-byte salt (stored with ciphertext)
+      salt: new Uint8Array(salt),
       iterations: 210000,  // OWASP 2023 recommendation
       hash: "SHA-256",
     },
-    keyMaterial,  // PRF output from authenticator
+    importedKey,
     { name: "AES-GCM", length: 256 },
     false,
     ["encrypt", "decrypt"]
@@ -526,12 +530,11 @@ async function deriveEncryptionKeyFromWebAuthn(
 }
 ```
 
-**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)
+**Properties**:
+- **Deterministic**: Same inputs always produce same output
+- **Secure**: 210,000 iterations make brute-force impractical
 - **Stateless**: No need to store the encryption key
-- **Fast**: ~100-200ms on modern devices
+- **Fast enough**: ~100-200ms on modern devices
 
 ---
 

package/docs/INTEGRATION_GUIDELINES.md

@@ -1412,13 +1412,10 @@ const strictWallet = await w3pk.deriveWallet('STRICT')
 ```
 
 **Persistent Session Security:**
-- STANDARD mode: Persistent sessions ✅ allowed
-- YOLO mode: Persistent sessions ✅ allowed
-- STRICT mode: Persistent sessions ❌ NEVER allowed
-- Sessions encrypted with WebAuthn-derived keys
-- Requires valid credential to decrypt
-- Time-limited expiration
-- Origin-isolated via IndexedDB
+- STANDARD / YOLO: persistent sessions allowed. STRICT: ❌ NEVER allowed.
+- Time-limited expiration; origin-isolated via IndexedDB.
+- ⚠️ The at-rest key is derived from **public** credential metadata in the same browser profile, not an authenticator secret — a persistent session is **decryptable by anyone who can read this origin's storage**, for the whole duration it's enabled. "Remember Me" is a UX-for-security trade-off that widens the exposure window; it does not add a new trust dependency beyond the origin-code integrity you already rely on. Keep the duration short for higher-value wallets and don't enable on shared devices.
+- Decide this deliberately against your threat model: **[SECURITY.md → At-Rest Encryption](./SECURITY.md#at-rest-encryption-what-it-protects-and-what-it-doesnt)**.
 
 ### Build Verification