w3pk 0.9.1 → 0.9.3

package/README.md

@@ -11,6 +11,8 @@ Passwordless Web3 authentication SDK with encrypted wallets and privacy features
 ## Install
 ```bash
 npm install w3pk ethers
+# or
+npm install w3pk viem
 ```
 
 ## Quick Start
@@ -34,9 +36,6 @@ const tx = await w3pk.sendTransaction({ to: '0x...', value: 1n * 10n**18n, chain
 // EIP-1193 provider (ethers, viem, wagmi, RainbowKit)
 const eip1193 = w3pk.getEIP1193Provider({ chainId: 1 })
 
-// Derive wallets (STANDARD/STRICT/YOLO modes)
-const wallet = await w3pk.deriveWallet('STANDARD', 'GAMING')
-
 // Get RPC endpoints
 const endpoints = await w3pk.getEndpoints(1)
 ```
@@ -85,17 +84,28 @@ await w3pk.logout()
 
 ### Wallet Derivation
 
+w3pk supports multiple security modes for deriving wallets with different privacy and security trade-offs:
+
 ```typescript
-// STANDARD mode - address only (no private key)
+// PRIMARY mode - WebAuthn P-256 passkey (EIP-7951)
+// Uses hardware-backed passkey directly, no seed phrase involved
+const primaryWallet = await w3pk.deriveWallet('PRIMARY')
+// Returns: { address, publicKey, origin, mode: 'PRIMARY', tag: 'MAIN' }
+
+// STANDARD mode - Default balanced security (recommended)
+// Returns address only, private key stays in SDK for signing
 const mainWallet = await w3pk.deriveWallet('STANDARD')
-// Returns: { address, index, origin, tag: 'MAIN' }
+// Returns: { address, index, origin, mode: 'STANDARD', tag: 'MAIN' }
 
-// YOLO mode - includes private key for app-specific use
+// YOLO mode - Private key exposed to app
+// Use only when app needs direct key access (advanced use cases)
 const gamingWallet = await w3pk.deriveWallet('YOLO', 'GAMING')
-// Returns: { address, privateKey, index, origin, tag: 'GAMING' }
+// Returns: { address, privateKey, index, origin, mode: 'YOLO', tag: 'GAMING' }
 
-// STRICT mode - address only, no persistent sessions allowed
+// STRICT mode - Maximum security, re-auth required every time
+// Requires biometric/PIN for each call - impractical for most apps
 const strictWallet = await w3pk.deriveWallet('STRICT', 'SECURE')
+// Returns: { address, privateKey, index, origin, mode: 'STRICT', tag: 'SECURE' }
 
 // Different tags generate different addresses
 console.log(mainWallet.address !== gamingWallet.address) // true
@@ -345,8 +355,13 @@ console.log('Security Score:', status.securityScore.total) // 0-100
 // Create encrypted backup file
 const { blob, filename } = await w3pk.createBackupFile('password', password)
 
-// Setup social recovery (M-of-N guardians)
-await w3pk.setupSocialRecovery(
+// Setup social recovery (M-of-N guardians) - guardians store backup file fragments
+import { SocialRecoveryManager } from 'w3pk'
+const backupFileJson = await blob.text()
+const socialRecovery = new SocialRecoveryManager()
+const guardians = await socialRecovery.setupSocialRecovery(
+  backupFileJson,
+  w3pk.user.ethereumAddress,
   [
     { name: 'Alice', email: 'alice@example.com' },
     { name: 'Bob', phone: '+1234567890' },
@@ -356,10 +371,11 @@ await w3pk.setupSocialRecovery(
 )
 
 // Generate guardian invite
-const invite = await w3pk.generateGuardianInvite(guardianShare)
+const invite = await socialRecovery.generateGuardianInvite(guardians[0])
 
-// Recover from guardian shares
-const { mnemonic } = await w3pk.recoverFromGuardians([share1, share2])
+// Recover from guardian shares - reconstructs encrypted backup file
+const { backupFileJson } = await socialRecovery.recoverFromGuardians([share1, share2])
+await w3pk.registerWithBackupFile(backupFileJson, password, 'username')
 
 // Restore from backup file
 await w3pk.restoreFromBackupFile(encryptedData, password)
@@ -421,6 +437,8 @@ console.log(result.report)
 await inspectNow()  // Logs report directly to console
 ```
 
+**Note:** Inspection API calls are sponsored by the [W3HC (Web3 Hackers Collective)](https://w3hc.org).
+
 **Node.js (analyze local files):**
 ```typescript
 import { inspect, gatherCode } from 'w3pk/inspect/node'
@@ -464,6 +482,7 @@ Host applications should verify their installed W3PK build against this registry
 - [Security Inspection](./docs/INSPECTION.md)
 - [EIP-7951](./docs/EIP-7951.md)
 - [Security Architecture](./docs/SECURITY.md)
+- [Post-Quantum Cryptography](./docs/POST_QUANTUM.md) - Quantum-safe migration roadmap
 - [Recovery & Backup System](./docs/RECOVERY.md)
 - [Portability Guide](./docs/PORTABILITY.md)
 - [ZK Proofs](./docs/ZK.md)

package/dist/index.d.mts

@@ -1753,6 +1753,93 @@ interface RecoveryProgress {
     canRecover: boolean;
 }
 
+/**
+ * Social Recovery Manager
+ * Manages guardian-based wallet recovery using Shamir Secret Sharing
+ */
+
+declare class SocialRecoveryManager {
+    private storageKey;
+    /**
+     * Get storage (localStorage or in-memory fallback)
+     */
+    private getItem;
+    /**
+     * Set storage (localStorage or in-memory fallback)
+     */
+    private setItem;
+    /**
+     * Set up social recovery
+     * Splits encrypted backup file into M-of-N shares and distributes to guardians
+     *
+     * @param backupFileJson - The complete backup file JSON string (password-encrypted)
+     * @param ethereumAddress - The Ethereum address for verification
+     * @param guardians - Array of guardian information
+     * @param threshold - Minimum number of guardians needed for recovery
+     */
+    setupSocialRecovery(backupFileJson: string, ethereumAddress: string, guardians: {
+        name: string;
+        email?: string;
+        phone?: string;
+    }[], threshold: number): Promise<Guardian[]>;
+    /**
+     * Get current social recovery configuration
+     */
+    getSocialRecoveryConfig(): SocialRecoveryConfig | null;
+    /**
+     * Generate guardian invitation
+     * Creates QR code and educational materials for guardian
+     */
+    generateGuardianInvite(guardian: Guardian): Promise<GuardianInvite>;
+    /**
+     * Generate QR code from share data
+     * Uses 'qrcode' library if available, falls back to canvas text
+     */
+    private generateQRCode;
+    /**
+     * Create fallback QR representation
+     */
+    private createPlaceholderQR;
+    /**
+     * Wrap text for display
+     */
+    private wrapText;
+    /**
+     * Get guardian explainer text
+     */
+    private getGuardianExplainer;
+    /**
+     * Recover backup file from guardian shares
+     * Returns the reconstructed backup file JSON that can be used with restoreFromBackupFile()
+     */
+    recoverFromGuardians(shareData: string[]): Promise<{
+        backupFileJson: string;
+        ethereumAddress: string;
+    }>;
+    /**
+     * Get recovery progress
+     */
+    getRecoveryProgress(collectedShares: string[]): RecoveryProgress;
+    /**
+     * Mark guardian as verified
+     * Note: This updates guardian status but does NOT automatically refresh security score.
+     * The security score will be updated on the next call to BackupManager.getBackupStatus()
+     */
+    markGuardianVerified(guardianId: string): void;
+    /**
+     * Revoke a guardian
+     */
+    revokeGuardian(guardianId: string): void;
+    /**
+     * Add new guardian (requires re-sharing with new backup file)
+     */
+    addGuardian(backupFileJson: string, newGuardian: {
+        name: string;
+        email?: string;
+        phone?: string;
+    }): Promise<Guardian>;
+}
+
 /**
  * Cross-Device Sync Type Definitions
  */
@@ -1982,4 +2069,4 @@ declare function inspectNow(options?: BrowserInspectOptions): Promise<void>;
 
 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 Guardian, type GuardianInvite, type PasskeySelectionResult, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, type SiweMessage, type SocialRecoveryConfig, 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, deriveStealthKeys, deriveWalletFromMnemonic, detectWalletProvider, encodeEIP7702AuthorizationMessage, extractRS, generateBIP39Wallet, generateSiweNonce, generateStealthAddress, getAllChains, getAllTopics, getChainById, getCurrentBuildHash, getCurrentOrigin, getDefaultProvider, getEndpoints, getExplainer, getOriginSpecificAddress, getPackageVersion, getW3pkBuildHash, hashEIP7702AuthorizationMessage, inspect, inspectNow, isStrongPassword, normalizeOrigin, parseSiweMessage, promptPasskeySelection, requestExternalWalletAuthorization, safeAtob, safeBtoa, searchExplainers, supportsEIP7702Authorization, validateEthereumAddress, validateMnemonic, validateSiweMessage, validateUsername, verifyBuildHash, verifyEIP7702Authorization, verifySiweSignature };
+export { ApiError, AuthenticationError, type BackupStatus, type BrowserInspectOptions, type BrowserInspectResult, CryptoError, DEFAULT_MODE, DEFAULT_TAG, type DeviceInfo, type EIP1193Provider, type EIP7702Authorization, type EncryptedBackupInfo, type Guardian, type GuardianInvite, 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, deriveStealthKeys, deriveWalletFromMnemonic, detectWalletProvider, encodeEIP7702AuthorizationMessage, extractRS, generateBIP39Wallet, generateSiweNonce, generateStealthAddress, getAllChains, getAllTopics, getChainById, getCurrentBuildHash, getCurrentOrigin, getDefaultProvider, getEndpoints, getExplainer, getOriginSpecificAddress, getPackageVersion, getW3pkBuildHash, hashEIP7702AuthorizationMessage, inspect, inspectNow, isStrongPassword, normalizeOrigin, parseSiweMessage, promptPasskeySelection, requestExternalWalletAuthorization, safeAtob, safeBtoa, searchExplainers, supportsEIP7702Authorization, validateEthereumAddress, validateMnemonic, validateSiweMessage, validateUsername, verifyBuildHash, verifyEIP7702Authorization, verifySiweSignature };

package/dist/index.d.ts

@@ -1753,6 +1753,93 @@ interface RecoveryProgress {
     canRecover: boolean;
 }
 
+/**
+ * Social Recovery Manager
+ * Manages guardian-based wallet recovery using Shamir Secret Sharing
+ */
+
+declare class SocialRecoveryManager {
+    private storageKey;
+    /**
+     * Get storage (localStorage or in-memory fallback)
+     */
+    private getItem;
+    /**
+     * Set storage (localStorage or in-memory fallback)
+     */
+    private setItem;
+    /**
+     * Set up social recovery
+     * Splits encrypted backup file into M-of-N shares and distributes to guardians
+     *
+     * @param backupFileJson - The complete backup file JSON string (password-encrypted)
+     * @param ethereumAddress - The Ethereum address for verification
+     * @param guardians - Array of guardian information
+     * @param threshold - Minimum number of guardians needed for recovery
+     */
+    setupSocialRecovery(backupFileJson: string, ethereumAddress: string, guardians: {
+        name: string;
+        email?: string;
+        phone?: string;
+    }[], threshold: number): Promise<Guardian[]>;
+    /**
+     * Get current social recovery configuration
+     */
+    getSocialRecoveryConfig(): SocialRecoveryConfig | null;
+    /**
+     * Generate guardian invitation
+     * Creates QR code and educational materials for guardian
+     */
+    generateGuardianInvite(guardian: Guardian): Promise<GuardianInvite>;
+    /**
+     * Generate QR code from share data
+     * Uses 'qrcode' library if available, falls back to canvas text
+     */
+    private generateQRCode;
+    /**
+     * Create fallback QR representation
+     */
+    private createPlaceholderQR;
+    /**
+     * Wrap text for display
+     */
+    private wrapText;
+    /**
+     * Get guardian explainer text
+     */
+    private getGuardianExplainer;
+    /**
+     * Recover backup file from guardian shares
+     * Returns the reconstructed backup file JSON that can be used with restoreFromBackupFile()
+     */
+    recoverFromGuardians(shareData: string[]): Promise<{
+        backupFileJson: string;
+        ethereumAddress: string;
+    }>;
+    /**
+     * Get recovery progress
+     */
+    getRecoveryProgress(collectedShares: string[]): RecoveryProgress;
+    /**
+     * Mark guardian as verified
+     * Note: This updates guardian status but does NOT automatically refresh security score.
+     * The security score will be updated on the next call to BackupManager.getBackupStatus()
+     */
+    markGuardianVerified(guardianId: string): void;
+    /**
+     * Revoke a guardian
+     */
+    revokeGuardian(guardianId: string): void;
+    /**
+     * Add new guardian (requires re-sharing with new backup file)
+     */
+    addGuardian(backupFileJson: string, newGuardian: {
+        name: string;
+        email?: string;
+        phone?: string;
+    }): Promise<Guardian>;
+}
+
 /**
  * Cross-Device Sync Type Definitions
  */
@@ -1982,4 +2069,4 @@ declare function inspectNow(options?: BrowserInspectOptions): Promise<void>;
 
 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 Guardian, type GuardianInvite, type PasskeySelectionResult, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, type SiweMessage, type SocialRecoveryConfig, 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, deriveStealthKeys, deriveWalletFromMnemonic, detectWalletProvider, encodeEIP7702AuthorizationMessage, extractRS, generateBIP39Wallet, generateSiweNonce, generateStealthAddress, getAllChains, getAllTopics, getChainById, getCurrentBuildHash, getCurrentOrigin, getDefaultProvider, getEndpoints, getExplainer, getOriginSpecificAddress, getPackageVersion, getW3pkBuildHash, hashEIP7702AuthorizationMessage, inspect, inspectNow, isStrongPassword, normalizeOrigin, parseSiweMessage, promptPasskeySelection, requestExternalWalletAuthorization, safeAtob, safeBtoa, searchExplainers, supportsEIP7702Authorization, validateEthereumAddress, validateMnemonic, validateSiweMessage, validateUsername, verifyBuildHash, verifyEIP7702Authorization, verifySiweSignature };
+export { ApiError, AuthenticationError, type BackupStatus, type BrowserInspectOptions, type BrowserInspectResult, CryptoError, DEFAULT_MODE, DEFAULT_TAG, type DeviceInfo, type EIP1193Provider, type EIP7702Authorization, type EncryptedBackupInfo, type Guardian, type GuardianInvite, 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, deriveStealthKeys, deriveWalletFromMnemonic, detectWalletProvider, encodeEIP7702AuthorizationMessage, extractRS, generateBIP39Wallet, generateSiweNonce, generateStealthAddress, getAllChains, getAllTopics, getChainById, getCurrentBuildHash, getCurrentOrigin, getDefaultProvider, getEndpoints, getExplainer, getOriginSpecificAddress, getPackageVersion, getW3pkBuildHash, hashEIP7702AuthorizationMessage, inspect, inspectNow, isStrongPassword, normalizeOrigin, parseSiweMessage, promptPasskeySelection, requestExternalWalletAuthorization, safeAtob, safeBtoa, searchExplainers, supportsEIP7702Authorization, validateEthereumAddress, validateMnemonic, validateSiweMessage, validateUsername, verifyBuildHash, verifyEIP7702Authorization, verifySiweSignature };