w3pk 0.10.1 → 0.10.2

package/README.md

@@ -257,6 +257,8 @@ await w3pk.clearSession()
 
 **Note:** STRICT mode never allows persistent sessions.
 
+**PRF-keyed persistence:** persistent sessions are encrypted under a key derived from the WebAuthn PRF extension (an authenticator-held secret, released only during a biometric/PIN-verified assertion) and re-keyed at every real login. Authenticators without PRF support get in-memory sessions only — there is no weaker at-rest fallback. See [Security Architecture](./docs/SECURITY.md) for details.
+
 ### RPC Endpoints
 
 ```typescript

package/dist/index.d.mts

@@ -386,11 +386,20 @@ declare class ApiError extends Web3PasskeyError {
  * Enables "Remember Me" functionality for STANDARD and YOLO mode wallets.
  *
  * SECURITY:
- * - Sessions encrypted with WebAuthn-derived keys
+ * - The mnemonic blob is encrypted with a key derived from the WebAuthn PRF
+ *   extension: a secret the authenticator releases only during a
+ *   user-verified assertion. Nothing stored on disk can re-derive it.
+ * - requireReauth: true  → the key is NOT stored; every restore re-evaluates
+ *   the PRF on a live assertion. The blob is hardware-bound at rest.
+ * - requireReauth: false → the key is stored as a NON-EXTRACTABLE CryptoKey
+ *   so silent restore works without a prompt. Scripts can use it but never
+ *   read its bytes; it is refreshed at every real (prompted) login.
+ * - Authenticators without PRF get no persistent sessions (in-memory only) —
+ *   there is deliberately no weaker fallback encryption.
  * - Only enabled for STANDARD and YOLO modes (STRICT mode excluded)
- * - Time-limited expiration
- * - Origin-isolated via IndexedDB
- * - Requires valid WebAuthn credential to decrypt
+ * - Time-limited expiration; the expiry IS the renewal boundary: when the
+ *   blob expires, the next login prompts, and that assertion's PRF output
+ *   re-keys a fresh blob.
  */
 
 /**
@@ -521,6 +530,12 @@ declare class Web3Passkey {
     login(): Promise<UserInfo>;
     /**
      * Logout current user and clear session
+     *
+     * The user is always logged out in memory, even if clearing persistent
+     * storage fails — in that case a StorageError is thrown so the app knows
+     * a persistent session may still exist on the device
+     *
+     * @throws {StorageError} if persistent sessions could not be cleared
      */
     logout(): Promise<void>;
     get isAuthenticated(): boolean;
@@ -1009,6 +1024,8 @@ declare class Web3Passkey {
     /**
      * Clear active session
      * Also clears ALL persistent sessions from IndexedDB
+     *
+     * @throws {StorageError} if persistent sessions could not be cleared
      */
     clearSession(): Promise<void>;
     /**
@@ -1016,6 +1033,14 @@ declare class Web3Passkey {
      * @param hours - Duration in hours
      */
     setSessionDuration(hours: number): void;
+    /**
+     * Update the persistent-session duration (the "Remember Me" window).
+     * Takes effect the next time a session is persisted — i.e. at the next
+     * real (prompted) login, which is also when the blob is re-keyed with a
+     * fresh PRF-derived key. The duration is therefore the renewal interval.
+     * @param hours - Duration in hours
+     */
+    setPersistentSessionDuration(hours: number): void;
     /**
      * Derive ML-KEM-1024 public key from the current wallet
      *
@@ -1301,6 +1326,15 @@ declare function verifyEIP7702Authorization(chainId: bigint, contractAddress: st
     s: string;
 } | string, expectedSigner: string): boolean;
 
+/** Client extension results consumed by w3pk (subset of the WebAuthn spec) */
+interface PrfExtensionResults {
+    prf?: {
+        enabled?: boolean;
+        results?: {
+            first?: ArrayBuffer;
+        };
+    };
+}
 /**
  * Native WebAuthn credential response (authentication)
  */
@@ -1314,14 +1348,7 @@ interface AuthenticationCredential {
         signature: ArrayBuffer;
         userHandle?: ArrayBuffer;
     };
-    getClientExtensionResults(): {
-        prf?: {
-            results?: {
-                first?: ArrayBuffer;
-                second?: ArrayBuffer;
-            };
-        };
-    };
+    getClientExtensionResults(): PrfExtensionResults;
 }
 
 /**

package/dist/index.d.ts

@@ -386,11 +386,20 @@ declare class ApiError extends Web3PasskeyError {
  * Enables "Remember Me" functionality for STANDARD and YOLO mode wallets.
  *
  * SECURITY:
- * - Sessions encrypted with WebAuthn-derived keys
+ * - The mnemonic blob is encrypted with a key derived from the WebAuthn PRF
+ *   extension: a secret the authenticator releases only during a
+ *   user-verified assertion. Nothing stored on disk can re-derive it.
+ * - requireReauth: true  → the key is NOT stored; every restore re-evaluates
+ *   the PRF on a live assertion. The blob is hardware-bound at rest.
+ * - requireReauth: false → the key is stored as a NON-EXTRACTABLE CryptoKey
+ *   so silent restore works without a prompt. Scripts can use it but never
+ *   read its bytes; it is refreshed at every real (prompted) login.
+ * - Authenticators without PRF get no persistent sessions (in-memory only) —
+ *   there is deliberately no weaker fallback encryption.
  * - Only enabled for STANDARD and YOLO modes (STRICT mode excluded)
- * - Time-limited expiration
- * - Origin-isolated via IndexedDB
- * - Requires valid WebAuthn credential to decrypt
+ * - Time-limited expiration; the expiry IS the renewal boundary: when the
+ *   blob expires, the next login prompts, and that assertion's PRF output
+ *   re-keys a fresh blob.
  */
 
 /**
@@ -521,6 +530,12 @@ declare class Web3Passkey {
     login(): Promise<UserInfo>;
     /**
      * Logout current user and clear session
+     *
+     * The user is always logged out in memory, even if clearing persistent
+     * storage fails — in that case a StorageError is thrown so the app knows
+     * a persistent session may still exist on the device
+     *
+     * @throws {StorageError} if persistent sessions could not be cleared
      */
     logout(): Promise<void>;
     get isAuthenticated(): boolean;
@@ -1009,6 +1024,8 @@ declare class Web3Passkey {
     /**
      * Clear active session
      * Also clears ALL persistent sessions from IndexedDB
+     *
+     * @throws {StorageError} if persistent sessions could not be cleared
      */
     clearSession(): Promise<void>;
     /**
@@ -1016,6 +1033,14 @@ declare class Web3Passkey {
      * @param hours - Duration in hours
      */
     setSessionDuration(hours: number): void;
+    /**
+     * Update the persistent-session duration (the "Remember Me" window).
+     * Takes effect the next time a session is persisted — i.e. at the next
+     * real (prompted) login, which is also when the blob is re-keyed with a
+     * fresh PRF-derived key. The duration is therefore the renewal interval.
+     * @param hours - Duration in hours
+     */
+    setPersistentSessionDuration(hours: number): void;
     /**
      * Derive ML-KEM-1024 public key from the current wallet
      *
@@ -1301,6 +1326,15 @@ declare function verifyEIP7702Authorization(chainId: bigint, contractAddress: st
     s: string;
 } | string, expectedSigner: string): boolean;
 
+/** Client extension results consumed by w3pk (subset of the WebAuthn spec) */
+interface PrfExtensionResults {
+    prf?: {
+        enabled?: boolean;
+        results?: {
+            first?: ArrayBuffer;
+        };
+    };
+}
 /**
  * Native WebAuthn credential response (authentication)
  */
@@ -1314,14 +1348,7 @@ interface AuthenticationCredential {
         signature: ArrayBuffer;
         userHandle?: ArrayBuffer;
     };
-    getClientExtensionResults(): {
-        prf?: {
-            results?: {
-                first?: ArrayBuffer;
-                second?: ArrayBuffer;
-            };
-        };
-    };
+    getClientExtensionResults(): PrfExtensionResults;
 }
 
 /**