w3pk 0.9.2 → 0.9.3

package/README.md

@@ -355,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' },
@@ -366,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)

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 };