w3pk 0.10.1 → 0.10.3

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

@@ -379,6 +379,23 @@ declare class ApiError extends Web3PasskeyError {
     statusCode?: number | undefined;
     constructor(message: string, statusCode?: number | undefined, originalError?: unknown);
 }
+/**
+ * The passkey authenticated, but this device has no credential metadata.
+ * The app should start a sync or restore flow.
+ */
+declare class SyncRequiredError extends Web3PasskeyError {
+    credentialId: string;
+    constructor(credentialId: string);
+}
+/**
+ * The credential metadata is on this device, but the wallet record is gone.
+ * The app should offer a restore from backup.
+ */
+declare class WalletMissingError extends Web3PasskeyError {
+    credentialId: string;
+    ethereumAddress: string;
+    constructor(credentialId: string, ethereumAddress: string);
+}
 
 /**
  * Persistent Session Storage
@@ -386,11 +403,22 @@ 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 raw key is stored next to the blob so silent
+ *   restore works without a prompt, and re-imported as non-extractable. Any
+ *   script on the origin can read it, which adds little: it could already
+ *   use a stored key to decrypt. 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.
  */
 
 /**
@@ -453,6 +481,89 @@ interface Web3PasskeyConfig {
     zkProofs?: ZKProofConfig;
 }
 
+/**
+ * Backup and Recovery Type Definitions
+ */
+type BackupMethod = 'file' | 'qr' | 'phrase';
+interface BackupStatus {
+    hasBackup: boolean;
+    lastBackupAt?: string;
+    methods: BackupMethod[];
+    passkeySync: PasskeySyncStatus;
+    recoveryPhrase: RecoveryPhraseStatus;
+    socialRecovery?: SocialRecoveryStatus;
+    securityScore: SecurityScore;
+}
+interface PasskeySyncStatus {
+    enabled: boolean;
+    deviceCount: number;
+    lastSyncTime?: string;
+    platform: 'apple' | 'google' | 'microsoft' | 'unknown';
+}
+interface RecoveryPhraseStatus {
+    verified: boolean;
+    verificationCount: number;
+    lastVerified?: string;
+    encryptedBackups: EncryptedBackupInfo[];
+}
+interface EncryptedBackupInfo {
+    id: string;
+    method: 'qr' | 'file';
+    location: string;
+    createdAt: string;
+    deviceFingerprint?: string;
+}
+interface SocialRecoveryStatus {
+    enabled: boolean;
+    guardians: Guardian$1[];
+    threshold: number;
+    sharesDistributed: number;
+    verifiedGuardians: number;
+}
+interface Guardian$1 {
+    id: string;
+    name: string;
+    email?: string;
+    publicKey?: string;
+    shareEncrypted: string;
+    status: 'pending' | 'active' | 'revoked';
+    addedAt: string;
+    lastVerified?: string;
+}
+interface SecurityScore {
+    total: number;
+    breakdown: {
+        passkeyActive: number;
+        passkeyMultiDevice: number;
+        phraseVerified: number;
+        encryptedBackup: number;
+        socialRecovery: number;
+    };
+    level: 'vulnerable' | 'protected' | 'secured' | 'fort-knox';
+    nextMilestone: string;
+}
+interface QRBackupOptions {
+    password?: string;
+    errorCorrection?: 'L' | 'M' | 'Q' | 'H';
+}
+interface RecoveryScenario {
+    type: 'lost-device' | 'lost-phrase' | 'lost-both' | 'switch-platform';
+    description: string;
+}
+interface SimulationResult {
+    scenario: RecoveryScenario;
+    success: boolean;
+    availableMethods: RecoveryMethod[];
+    timeEstimate: string;
+    educationalNote: string;
+}
+interface RecoveryMethod {
+    method: string;
+    success: boolean;
+    time: string;
+    requirements: string[];
+}
+
 /**
  * Main Web3Passkey SDK
  *
@@ -486,6 +597,7 @@ declare class Web3Passkey {
     private walletStorage;
     private currentUser;
     private currentWallet;
+    private persisted;
     private sessionManager;
     stealth?: StealthAddressModule;
     private zkModule?;
@@ -509,6 +621,7 @@ declare class Web3Passkey {
     }): Promise<{
         address: string;
         username: string;
+        hasBackup: boolean;
     }>;
     /**
      * Login with WebAuthn using resident credentials
@@ -521,10 +634,24 @@ 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;
     get user(): UserInfo | null;
+    /**
+     * Whether the browser granted persistent storage (`navigator.storage.persist()`),
+     * requested after each register, login and restore: true means the origin's
+     * storage is exempt from storage-pressure eviction. null until the browser
+     * answers (Firefox asks the user), or where the API is missing.
+     */
+    get storagePersisted(): boolean | null;
+    private requestPersistentStorage;
     /**
      * List existing credentials (usernames and addresses)
      * Useful for allowing users to select which wallet to login to
@@ -859,7 +986,12 @@ declare class Web3Passkey {
     /**
      * Get backup status
      */
-    getBackupStatus(): Promise<any>;
+    getBackupStatus(): Promise<BackupStatus>;
+    /**
+     * Record that the user wrote down their recovery phrase
+     * Call it once the user confirms, so getBackupStatus() reports a backup
+     */
+    confirmRecoveryPhraseBackup(): Promise<void>;
     /**
      * Create simplified backup file
      * This backup can be used to:
@@ -1008,7 +1140,9 @@ declare class Web3Passkey {
     extendSession(): void;
     /**
      * Clear active session
-     * Also clears ALL persistent sessions from IndexedDB
+     * Also clears ALL persistent sessions from localStorage
+     *
+     * @throws {StorageError} if persistent sessions could not be cleared
      */
     clearSession(): Promise<void>;
     /**
@@ -1016,6 +1150,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 +1443,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 +1465,7 @@ interface AuthenticationCredential {
         signature: ArrayBuffer;
         userHandle?: ArrayBuffer;
     };
-    getClientExtensionResults(): {
-        prf?: {
-            results?: {
-                first?: ArrayBuffer;
-                second?: ArrayBuffer;
-            };
-        };
-    };
+    getClientExtensionResults(): PrfExtensionResults;
 }
 
 /**
@@ -1390,85 +1534,6 @@ declare function getCurrentOrigin(): string;
  */
 declare function deriveAddressFromP256PublicKey(publicKeySpki: string): Promise<string>;
 
-/**
- * Backup and Recovery Type Definitions
- */
-interface BackupStatus {
-    passkeySync: PasskeySyncStatus;
-    recoveryPhrase: RecoveryPhraseStatus;
-    socialRecovery?: SocialRecoveryStatus;
-    securityScore: SecurityScore;
-}
-interface PasskeySyncStatus {
-    enabled: boolean;
-    deviceCount: number;
-    lastSyncTime?: string;
-    platform: 'apple' | 'google' | 'microsoft' | 'unknown';
-}
-interface RecoveryPhraseStatus {
-    verified: boolean;
-    verificationCount: number;
-    lastVerified?: string;
-    encryptedBackups: EncryptedBackupInfo[];
-}
-interface EncryptedBackupInfo {
-    id: string;
-    method: 'qr' | 'file';
-    location: string;
-    createdAt: string;
-    deviceFingerprint?: string;
-}
-interface SocialRecoveryStatus {
-    enabled: boolean;
-    guardians: Guardian$1[];
-    threshold: number;
-    sharesDistributed: number;
-    verifiedGuardians: number;
-}
-interface Guardian$1 {
-    id: string;
-    name: string;
-    email?: string;
-    publicKey?: string;
-    shareEncrypted: string;
-    status: 'pending' | 'active' | 'revoked';
-    addedAt: string;
-    lastVerified?: string;
-}
-interface SecurityScore {
-    total: number;
-    breakdown: {
-        passkeyActive: number;
-        passkeyMultiDevice: number;
-        phraseVerified: number;
-        encryptedBackup: number;
-        socialRecovery: number;
-    };
-    level: 'vulnerable' | 'protected' | 'secured' | 'fort-knox';
-    nextMilestone: string;
-}
-interface QRBackupOptions {
-    password?: string;
-    errorCorrection?: 'L' | 'M' | 'Q' | 'H';
-}
-interface RecoveryScenario {
-    type: 'lost-device' | 'lost-phrase' | 'lost-both' | 'switch-platform';
-    description: string;
-}
-interface SimulationResult {
-    scenario: RecoveryScenario;
-    success: boolean;
-    availableMethods: RecoveryMethod[];
-    timeEstimate: string;
-    educationalNote: string;
-}
-interface RecoveryMethod {
-    method: string;
-    success: boolean;
-    time: string;
-    requirements: string[];
-}
-
 /**
  * Recovery Scenario Simulator
  * Educational tool to help users understand recovery options
@@ -2190,6 +2255,7 @@ interface MLKemKeypair {
     privateKey: Uint8Array;
 }
 interface EncryptedPayload {
+    version?: 2;
     recipients: Array<{
         publicKey: string;
         ciphertext: string;
@@ -2286,4 +2352,4 @@ declare function mlkemDecryptWithKey(payload: EncryptedPayload, privateKey: stri
 
 declare function createWeb3Passkey(config?: Web3PasskeyConfig): Web3Passkey;
 
-export { ApiError, AuthenticationError, type BackupStatus, type BrowserInspectOptions, type BrowserInspectResult, CryptoError, DEFAULT_MODE, DEFAULT_TAG, type DeviceInfo, type EIP1193Provider, type EIP7702Authorization, type EncryptedBackupInfo, type EncryptedPayload, type Guardian, type GuardianInvite, type MLKemKeypair, type PasskeySelectionResult, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, type SiweMessage, type SocialRecoveryConfig, SocialRecoveryManager, type StealthAddressConfig, StealthAddressModule, type StealthAddressResult, type StealthKeys, StorageError, type SyncCapabilities, type SyncStatus, type SyncVault, type UserInfo, WalletError, type WalletInfo, Web3Passkey, type Web3PasskeyConfig, Web3PasskeyError, arrayBufferToBase64Url, assertEthereumAddress, assertMnemonic, assertUsername, authenticateWithPasskey, base64ToArrayBuffer, base64UrlDecode, base64UrlToArrayBuffer, canControlStealthAddress, checkStealthAddress, clearCache, computeStealthPrivateKey, createSiweMessage, createWalletFromMnemonic, createWeb3Passkey, createWeb3Passkey as default, deriveAddressFromP256PublicKey, deriveIndexFromOriginModeAndTag, deriveMLKemKeypair, deriveStealthKeys, deriveWalletFromMnemonic, detectWalletProvider, encodeEIP7702AuthorizationMessage, extractRS, generateBIP39Wallet, generateSiweNonce, generateStealthAddress, getAllChains, getAllTopics, getChainById, getCurrentBuildHash, getCurrentOrigin, getDefaultProvider, getEndpoints, getExplainer, getOriginSpecificAddress, getPackageVersion, getW3pkBuildHash, hashEIP7702AuthorizationMessage, inspect, inspectNow, isStrongPassword, mlkemDecrypt, mlkemDecryptWithKey, mlkemEncrypt, mlkemEncryptWithKey, normalizeOrigin, parseSiweMessage, promptPasskeySelection, requestExternalWalletAuthorization, safeAtob, safeBtoa, searchExplainers, supportsEIP7702Authorization, validateEthereumAddress, validateMnemonic, validateSiweMessage, validateUsername, verifyBuildHash, verifyEIP7702Authorization, verifySiweSignature };
+export { ApiError, AuthenticationError, type BackupMethod, type BackupStatus, type BrowserInspectOptions, type BrowserInspectResult, CryptoError, DEFAULT_MODE, DEFAULT_TAG, type DeviceInfo, type EIP1193Provider, type EIP7702Authorization, type EncryptedBackupInfo, type EncryptedPayload, type Guardian, type GuardianInvite, type MLKemKeypair, type PasskeySelectionResult, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, type SiweMessage, type SocialRecoveryConfig, SocialRecoveryManager, type StealthAddressConfig, StealthAddressModule, type StealthAddressResult, type StealthKeys, StorageError, type SyncCapabilities, SyncRequiredError, type SyncStatus, type SyncVault, type UserInfo, WalletError, type WalletInfo, WalletMissingError, Web3Passkey, type Web3PasskeyConfig, Web3PasskeyError, arrayBufferToBase64Url, assertEthereumAddress, assertMnemonic, assertUsername, authenticateWithPasskey, base64ToArrayBuffer, base64UrlDecode, base64UrlToArrayBuffer, canControlStealthAddress, checkStealthAddress, clearCache, computeStealthPrivateKey, createSiweMessage, createWalletFromMnemonic, createWeb3Passkey, createWeb3Passkey as default, deriveAddressFromP256PublicKey, deriveIndexFromOriginModeAndTag, deriveMLKemKeypair, deriveStealthKeys, deriveWalletFromMnemonic, detectWalletProvider, encodeEIP7702AuthorizationMessage, extractRS, generateBIP39Wallet, generateSiweNonce, generateStealthAddress, getAllChains, getAllTopics, getChainById, getCurrentBuildHash, getCurrentOrigin, getDefaultProvider, getEndpoints, getExplainer, getOriginSpecificAddress, getPackageVersion, getW3pkBuildHash, hashEIP7702AuthorizationMessage, inspect, inspectNow, isStrongPassword, mlkemDecrypt, mlkemDecryptWithKey, mlkemEncrypt, mlkemEncryptWithKey, normalizeOrigin, parseSiweMessage, promptPasskeySelection, requestExternalWalletAuthorization, safeAtob, safeBtoa, searchExplainers, supportsEIP7702Authorization, validateEthereumAddress, validateMnemonic, validateSiweMessage, validateUsername, verifyBuildHash, verifyEIP7702Authorization, verifySiweSignature };