w3pk 0.7.7 → 0.8.0

package/README.md

@@ -54,7 +54,7 @@ const rpcUrl = endpoints[0]
 - 🔍 Build verification (IPFS CIDv1 hashing for package integrity)
 - 🛡️ Three-layer backup & recovery system
   - Passkey auto-sync (iCloud/Google/Microsoft)
-  - Encrypted backups (ZIP/QR with password protection)
+  - Encrypted backups (QR codes and backup files with password protection)
   - Social recovery (Shamir Secret Sharing)
 
 ## API
@@ -62,12 +62,19 @@ const rpcUrl = endpoints[0]
 ### Authentication Flow
 
 ```typescript
-// Register (generates and stores wallet securely)
-const { address, username } = await w3pk.register({ username: 'alice' })
-// Returns: { address, username } 
+// Check for existing wallet first (recommended)
+const hasWallet = await w3pk.hasExistingCredential()
+if (hasWallet) {
+  // Login to existing wallet
+  await w3pk.login()
+} else {
+  // Register new wallet (generates and stores wallet securely)
+  const { address, username } = await w3pk.register({ username: 'alice' })
+}
 
-// Subsequent sessions: just login
-await w3pk.login()
+// Advanced: List all wallets on device
+const wallets = await w3pk.listExistingCredentials()
+wallets.forEach(w => console.log(w.username, w.ethereumAddress))
 
 // Logout
 await w3pk.logout()
@@ -246,10 +253,6 @@ if (!isStrongPassword(password)) {
 const status = await w3pk.getBackupStatus()
 console.log('Security Score:', status.securityScore.score) // 0-100
 
-// Create encrypted ZIP backup
-const blob = await w3pk.createZipBackup(password)
-// Save blob to file system
-
 // Create QR backup
 const { qrCodeDataURL } = await w3pk.createQRBackup('password')
 // Display QR code or save as image
@@ -295,10 +298,10 @@ import { getCurrentBuildHash, verifyBuildHash } from 'w3pk'
 // Get IPFS hash of installed w3pk build
 const hash = await getCurrentBuildHash()
 console.log('Build hash:', hash)
-// => bafybeifysgwvsyog2akxjk4cjky2grqqyzfehamuwyk6zy56srgkc5jopi
+// => bafybeicujqydugwds3yuuipeh6xgiphi342cb6eh7w5z3ryz2hijnrqezm
 
 // Verify against trusted hash (from GitHub releases)
-const trusted = 'bafybeifysgwvsyog2akxjk4cjky2grqqyzfehamuwyk6zy56srgkc5jopi'
+const trusted = 'bafybeicujqydugwds3yuuipeh6xgiphi342cb6eh7w5z3ryz2hijnrqezm'
 const isValid = await verifyBuildHash(trusted)
 if (isValid) {
   console.log('✅ Build integrity verified!')
@@ -312,7 +315,7 @@ See [Build Verification Guide](./docs/BUILD_VERIFICATION.md) for complete docume
 ### Current Build Hash (v0.7.6)
 
 ```
-bafybeifysgwvsyog2akxjk4cjky2grqqyzfehamuwyk6zy56srgkc5jopi
+bafybeicujqydugwds3yuuipeh6xgiphi342cb6eh7w5z3ryz2hijnrqezm
 ```
 
 **Verify package integrity:**
@@ -320,7 +323,7 @@ bafybeifysgwvsyog2akxjk4cjky2grqqyzfehamuwyk6zy56srgkc5jopi
 ```typescript
 import { verifyBuildHash } from 'w3pk'
 
-const TRUSTED_HASH = 'bafybeifysgwvsyog2akxjk4cjky2grqqyzfehamuwyk6zy56srgkc5jopi'
+const TRUSTED_HASH = 'bafybeicujqydugwds3yuuipeh6xgiphi342cb6eh7w5z3ryz2hijnrqezm'
 const isValid = await verifyBuildHash(TRUSTED_HASH)
 
 if (!isValid) {
@@ -340,9 +343,10 @@ See [Build Verification Guide](./docs/BUILD_VERIFICATION.md) for complete docume
 ## Documentation
 
 - [Quick Start Guide](./docs/QUICK_START.md) - Get started in 5 minutes
+- [Integration Guidelines](./docs/INTEGRATION_GUIDELINES.md) - Best practices for production apps
 - [API Reference](./docs/API_REFERENCE.md) - Complete API documentation
 - [Build Verification](./docs/BUILD_VERIFICATION.md) - Package integrity verification
-- [Security Architecture](./docs/SECURITY.md) - Integration best practices
+- [Security Architecture](./docs/SECURITY.md) - Security model and threat analysis
 - [Recovery & Backup System](./docs/RECOVERY.md) - Three-layer backup architecture
 - [ZK Proofs](./docs/ZK.md) - Zero-Knowledge cryptography utilities
 - [Browser compatibility](./docs/BROWSER_COMPATIBILITY.md)

package/dist/index.d.mts

@@ -288,6 +288,47 @@ declare class Web3Passkey {
     logout(): Promise<void>;
     get isAuthenticated(): boolean;
     get user(): UserInfo | null;
+    /**
+     * Check if there are existing credentials on this device
+     * Useful for preventing accidental multiple wallet creation
+     *
+     * @returns true if at least one credential exists
+     * @example
+     * const hasWallet = await w3pk.hasExistingCredential()
+     * if (hasWallet) {
+     *   // Prompt user to login instead of registering
+     *   await w3pk.login()
+     * }
+     */
+    hasExistingCredential(): Promise<boolean>;
+    /**
+     * Get the number of existing credentials on this device
+     *
+     * @returns count of credentials
+     * @example
+     * const count = await w3pk.getExistingCredentialCount()
+     * if (count > 0) {
+     *   console.warn(`You have ${count} wallet(s) on this device`)
+     * }
+     */
+    getExistingCredentialCount(): Promise<number>;
+    /**
+     * List existing credentials (usernames and addresses)
+     * Useful for allowing users to select which wallet to login to
+     *
+     * @returns array of credentials with username, address, and metadata
+     * @example
+     * const wallets = await w3pk.listExistingCredentials()
+     * wallets.forEach(w => {
+     *   console.log(`${w.username}: ${w.ethereumAddress}`)
+     * })
+     */
+    listExistingCredentials(): Promise<Array<{
+        username: string;
+        ethereumAddress: string;
+        createdAt: string;
+        lastUsed: string;
+    }>>;
     /**
      * Generate new BIP39 wallet with 12-word mnemonic
      */
@@ -316,7 +357,7 @@ declare class Web3Passkey {
     }>;
     /**
      * Export mnemonic (disabled for security)
-     * Use createZipBackup() or createQRBackup() instead
+     * Use createBackupFile() instead
      * @deprecated
      * @throws WalletError
      */
@@ -369,59 +410,105 @@ declare class Web3Passkey {
      */
     getBackupStatus(): Promise<any>;
     /**
-     * Create password-protected ZIP backup
-     */
-    createZipBackup(password: string, options?: {
-        includeInstructions?: boolean;
-        deviceBinding?: boolean;
-    }): Promise<Blob>;
-    /**
-     * Create QR code backup
+     * Create simplified backup file
+     * This backup can be used to:
+     * - Restore wallet with existing passkey
+     * - Register new passkey with this wallet
+     * - Sync wallet across devices
+     * - Split among guardians for social recovery
+     *
+     * @param encryptionType - 'password' (default), 'passkey', or 'hybrid'
+     * @param password - Required for 'password' and 'hybrid' encryption
      */
-    createQRBackup(password?: string, options?: {
-        errorCorrection?: "L" | "M" | "Q" | "H";
-    }): Promise<{
-        qrCodeDataURL: string;
-        instructions: string;
+    createBackupFile(encryptionType?: 'password' | 'passkey' | 'hybrid', password?: string): Promise<{
+        blob: Blob;
+        filename: string;
     }>;
     /**
-     * Set up social recovery with M-of-N guardian shares
-     * @param threshold - Number of guardians required to recover
+     * Set up social recovery by splitting backup file among guardians
+     * Uses Shamir Secret Sharing to split the backup - requires M-of-N guardians to recover
+     *
+     * @param guardians - List of guardian names/emails
+     * @param threshold - Number of guardians required to recover (M-of-N)
+     * @param password - Optional password for additional encryption layer
      */
     setupSocialRecovery(guardians: {
         name: string;
         email?: string;
-        phone?: string;
-    }[], threshold: number): Promise<any[]>;
+    }[], threshold: number, password?: string): Promise<{
+        guardianShares: any[];
+        setupComplete: boolean;
+    }>;
     /**
-     * Generate guardian invitation with QR code
-     */
-    generateGuardianInvite(guardianId: string): Promise<any>;
+     * Generate guardian invitation document and QR code
+     *
+     * @param guardianShare - The guardian's share data
+     * @param message - Optional custom message for the guardian
+     */
+    generateGuardianInvite(guardianShare: any, message?: string): Promise<{
+        qrCodeDataURL?: string;
+        shareDocument: string;
+        downloadBlob: Blob;
+        filename: string;
+    }>;
     /**
      * Recover wallet from guardian shares
+     * Combines M-of-N guardian shares to reconstruct the backup file
+     *
+     * @param shares - Array of guardian share objects (JSON strings or parsed objects)
+     * @param password - Password to decrypt the backup (if password-protected)
      */
-    recoverFromGuardians(shares: string[]): Promise<{
+    recoverFromGuardians(shares: Array<string | any>, password?: string): Promise<{
         mnemonic: string;
         ethereumAddress: string;
     }>;
     /**
-     * Restore wallet from encrypted backup
+     * Restore wallet from backup file with existing passkey
+     * Use case: User has passkey synced to this device
+     *
+     * After restoration, you can either:
+     * - Use importMnemonic() to associate with current logged-in user
+     * - Use registerWithBackupFile() to create new passkey for this wallet
      */
-    restoreFromBackup(backupData: string, password: string): Promise<{
+    restoreFromBackupFile(backupData: string | Blob, password?: string): Promise<{
         mnemonic: string;
         ethereumAddress: string;
     }>;
     /**
-     * Restore wallet from QR code
+     * Register new passkey with wallet from backup file
+     * Use case: Fresh device, user has backup file but no passkey yet
+     *
+     * This creates a NEW passkey and associates it with the wallet from the backup
+     *
+     * @param backupData - Backup file (JSON string or Blob)
+     * @param password - Password to decrypt the backup
+     * @param username - Username for the new passkey
      */
-    restoreFromQR(qrData: string, password?: string): Promise<{
-        mnemonic: string;
-        ethereumAddress: string;
+    registerWithBackupFile(backupData: string | Blob, password: string, username: string): Promise<{
+        address: string;
+        username: string;
     }>;
     /**
      * Get cross-device sync status
      */
     getSyncStatus(): Promise<any>;
+    /**
+     * Export wallet for syncing to another device
+     * Uses passkey encryption so it works on devices where the passkey is synced
+     */
+    exportForSync(): Promise<{
+        blob: Blob;
+        filename: string;
+        qrCode?: string;
+    }>;
+    /**
+     * Import wallet from another device (sync wallet to this device)
+     * Use case: User has passkey on both devices, wallet only on one
+     */
+    importFromSync(syncData: string | Blob): Promise<{
+        ethereumAddress: string;
+        success: boolean;
+    }>;
     /**
      * Detect platform sync capabilities
      */
@@ -517,7 +604,7 @@ interface RecoveryPhraseStatus {
 }
 interface EncryptedBackupInfo {
     id: string;
-    method: 'zip' | 'qr' | 'file';
+    method: 'qr' | 'file';
     location: string;
     createdAt: string;
     deviceFingerprint?: string;
@@ -551,11 +638,6 @@ interface SecurityScore {
     level: 'vulnerable' | 'protected' | 'secured' | 'fort-knox';
     nextMilestone: string;
 }
-interface ZipBackupOptions {
-    password: string;
-    includeInstructions?: boolean;
-    deviceBinding?: boolean;
-}
 interface QRBackupOptions {
     password?: string;
     errorCorrection?: 'L' | 'M' | 'Q' | 'H';
@@ -786,4 +868,4 @@ interface SyncStatus {
 
 declare function createWeb3Passkey(config?: Web3PasskeyConfig): Web3Passkey;
 
-export { ApiError, AuthenticationError, type BackupStatus, CryptoError, DEFAULT_TAG, type DeviceInfo, type EIP7702Authorization, type EncryptedBackupInfo, type Guardian, type GuardianInvite, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, 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, type ZipBackupOptions, assertEthereumAddress, assertMnemonic, assertUsername, createWeb3Passkey, createWeb3Passkey as default, getAllTopics, getCurrentBuildHash, getCurrentOrigin, getExplainer, getPackageVersion, getW3pkBuildHash, isStrongPassword, normalizeOrigin, searchExplainers, validateEthereumAddress, validateMnemonic, validateUsername, verifyBuildHash };
+export { ApiError, AuthenticationError, type BackupStatus, CryptoError, DEFAULT_TAG, type DeviceInfo, type EIP7702Authorization, type EncryptedBackupInfo, type Guardian, type GuardianInvite, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, 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, assertEthereumAddress, assertMnemonic, assertUsername, createWeb3Passkey, createWeb3Passkey as default, getAllTopics, getCurrentBuildHash, getCurrentOrigin, getExplainer, getPackageVersion, getW3pkBuildHash, isStrongPassword, normalizeOrigin, searchExplainers, validateEthereumAddress, validateMnemonic, validateUsername, verifyBuildHash };

package/dist/index.d.ts

@@ -288,6 +288,47 @@ declare class Web3Passkey {
     logout(): Promise<void>;
     get isAuthenticated(): boolean;
     get user(): UserInfo | null;
+    /**
+     * Check if there are existing credentials on this device
+     * Useful for preventing accidental multiple wallet creation
+     *
+     * @returns true if at least one credential exists
+     * @example
+     * const hasWallet = await w3pk.hasExistingCredential()
+     * if (hasWallet) {
+     *   // Prompt user to login instead of registering
+     *   await w3pk.login()
+     * }
+     */
+    hasExistingCredential(): Promise<boolean>;
+    /**
+     * Get the number of existing credentials on this device
+     *
+     * @returns count of credentials
+     * @example
+     * const count = await w3pk.getExistingCredentialCount()
+     * if (count > 0) {
+     *   console.warn(`You have ${count} wallet(s) on this device`)
+     * }
+     */
+    getExistingCredentialCount(): Promise<number>;
+    /**
+     * List existing credentials (usernames and addresses)
+     * Useful for allowing users to select which wallet to login to
+     *
+     * @returns array of credentials with username, address, and metadata
+     * @example
+     * const wallets = await w3pk.listExistingCredentials()
+     * wallets.forEach(w => {
+     *   console.log(`${w.username}: ${w.ethereumAddress}`)
+     * })
+     */
+    listExistingCredentials(): Promise<Array<{
+        username: string;
+        ethereumAddress: string;
+        createdAt: string;
+        lastUsed: string;
+    }>>;
     /**
      * Generate new BIP39 wallet with 12-word mnemonic
      */
@@ -316,7 +357,7 @@ declare class Web3Passkey {
     }>;
     /**
      * Export mnemonic (disabled for security)
-     * Use createZipBackup() or createQRBackup() instead
+     * Use createBackupFile() instead
      * @deprecated
      * @throws WalletError
      */
@@ -369,59 +410,105 @@ declare class Web3Passkey {
      */
     getBackupStatus(): Promise<any>;
     /**
-     * Create password-protected ZIP backup
-     */
-    createZipBackup(password: string, options?: {
-        includeInstructions?: boolean;
-        deviceBinding?: boolean;
-    }): Promise<Blob>;
-    /**
-     * Create QR code backup
+     * Create simplified backup file
+     * This backup can be used to:
+     * - Restore wallet with existing passkey
+     * - Register new passkey with this wallet
+     * - Sync wallet across devices
+     * - Split among guardians for social recovery
+     *
+     * @param encryptionType - 'password' (default), 'passkey', or 'hybrid'
+     * @param password - Required for 'password' and 'hybrid' encryption
      */
-    createQRBackup(password?: string, options?: {
-        errorCorrection?: "L" | "M" | "Q" | "H";
-    }): Promise<{
-        qrCodeDataURL: string;
-        instructions: string;
+    createBackupFile(encryptionType?: 'password' | 'passkey' | 'hybrid', password?: string): Promise<{
+        blob: Blob;
+        filename: string;
     }>;
     /**
-     * Set up social recovery with M-of-N guardian shares
-     * @param threshold - Number of guardians required to recover
+     * Set up social recovery by splitting backup file among guardians
+     * Uses Shamir Secret Sharing to split the backup - requires M-of-N guardians to recover
+     *
+     * @param guardians - List of guardian names/emails
+     * @param threshold - Number of guardians required to recover (M-of-N)
+     * @param password - Optional password for additional encryption layer
      */
     setupSocialRecovery(guardians: {
         name: string;
         email?: string;
-        phone?: string;
-    }[], threshold: number): Promise<any[]>;
+    }[], threshold: number, password?: string): Promise<{
+        guardianShares: any[];
+        setupComplete: boolean;
+    }>;
     /**
-     * Generate guardian invitation with QR code
-     */
-    generateGuardianInvite(guardianId: string): Promise<any>;
+     * Generate guardian invitation document and QR code
+     *
+     * @param guardianShare - The guardian's share data
+     * @param message - Optional custom message for the guardian
+     */
+    generateGuardianInvite(guardianShare: any, message?: string): Promise<{
+        qrCodeDataURL?: string;
+        shareDocument: string;
+        downloadBlob: Blob;
+        filename: string;
+    }>;
     /**
      * Recover wallet from guardian shares
+     * Combines M-of-N guardian shares to reconstruct the backup file
+     *
+     * @param shares - Array of guardian share objects (JSON strings or parsed objects)
+     * @param password - Password to decrypt the backup (if password-protected)
      */
-    recoverFromGuardians(shares: string[]): Promise<{
+    recoverFromGuardians(shares: Array<string | any>, password?: string): Promise<{
         mnemonic: string;
         ethereumAddress: string;
     }>;
     /**
-     * Restore wallet from encrypted backup
+     * Restore wallet from backup file with existing passkey
+     * Use case: User has passkey synced to this device
+     *
+     * After restoration, you can either:
+     * - Use importMnemonic() to associate with current logged-in user
+     * - Use registerWithBackupFile() to create new passkey for this wallet
      */
-    restoreFromBackup(backupData: string, password: string): Promise<{
+    restoreFromBackupFile(backupData: string | Blob, password?: string): Promise<{
         mnemonic: string;
         ethereumAddress: string;
     }>;
     /**
-     * Restore wallet from QR code
+     * Register new passkey with wallet from backup file
+     * Use case: Fresh device, user has backup file but no passkey yet
+     *
+     * This creates a NEW passkey and associates it with the wallet from the backup
+     *
+     * @param backupData - Backup file (JSON string or Blob)
+     * @param password - Password to decrypt the backup
+     * @param username - Username for the new passkey
      */
-    restoreFromQR(qrData: string, password?: string): Promise<{
-        mnemonic: string;
-        ethereumAddress: string;
+    registerWithBackupFile(backupData: string | Blob, password: string, username: string): Promise<{
+        address: string;
+        username: string;
     }>;
     /**
      * Get cross-device sync status
      */
     getSyncStatus(): Promise<any>;
+    /**
+     * Export wallet for syncing to another device
+     * Uses passkey encryption so it works on devices where the passkey is synced
+     */
+    exportForSync(): Promise<{
+        blob: Blob;
+        filename: string;
+        qrCode?: string;
+    }>;
+    /**
+     * Import wallet from another device (sync wallet to this device)
+     * Use case: User has passkey on both devices, wallet only on one
+     */
+    importFromSync(syncData: string | Blob): Promise<{
+        ethereumAddress: string;
+        success: boolean;
+    }>;
     /**
      * Detect platform sync capabilities
      */
@@ -517,7 +604,7 @@ interface RecoveryPhraseStatus {
 }
 interface EncryptedBackupInfo {
     id: string;
-    method: 'zip' | 'qr' | 'file';
+    method: 'qr' | 'file';
     location: string;
     createdAt: string;
     deviceFingerprint?: string;
@@ -551,11 +638,6 @@ interface SecurityScore {
     level: 'vulnerable' | 'protected' | 'secured' | 'fort-knox';
     nextMilestone: string;
 }
-interface ZipBackupOptions {
-    password: string;
-    includeInstructions?: boolean;
-    deviceBinding?: boolean;
-}
 interface QRBackupOptions {
     password?: string;
     errorCorrection?: 'L' | 'M' | 'Q' | 'H';
@@ -786,4 +868,4 @@ interface SyncStatus {
 
 declare function createWeb3Passkey(config?: Web3PasskeyConfig): Web3Passkey;
 
-export { ApiError, AuthenticationError, type BackupStatus, CryptoError, DEFAULT_TAG, type DeviceInfo, type EIP7702Authorization, type EncryptedBackupInfo, type Guardian, type GuardianInvite, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, 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, type ZipBackupOptions, assertEthereumAddress, assertMnemonic, assertUsername, createWeb3Passkey, createWeb3Passkey as default, getAllTopics, getCurrentBuildHash, getCurrentOrigin, getExplainer, getPackageVersion, getW3pkBuildHash, isStrongPassword, normalizeOrigin, searchExplainers, validateEthereumAddress, validateMnemonic, validateUsername, verifyBuildHash };
+export { ApiError, AuthenticationError, type BackupStatus, CryptoError, DEFAULT_TAG, type DeviceInfo, type EIP7702Authorization, type EncryptedBackupInfo, type Guardian, type GuardianInvite, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, 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, assertEthereumAddress, assertMnemonic, assertUsername, createWeb3Passkey, createWeb3Passkey as default, getAllTopics, getCurrentBuildHash, getCurrentOrigin, getExplainer, getPackageVersion, getW3pkBuildHash, isStrongPassword, normalizeOrigin, searchExplainers, validateEthereumAddress, validateMnemonic, validateUsername, verifyBuildHash };