w3pk 0.7.0 → 0.7.1

package/README.md

@@ -48,6 +48,10 @@ const rpcUrl = endpoints[0]
 - 🥷 ERC-5564 stealth addresses (privacy-preserving transactions with view tags)
 - 🔗 Chainlist support (2390+ networks, auto-filtered RPC endpoints)
 - ⚡ EIP-7702 network detection (329+ supported networks)
+- 🛡️ Three-layer backup & recovery system
+  - Passkey auto-sync (iCloud/Google/Microsoft)
+  - Encrypted backups (ZIP/QR with password protection)
+  - Social recovery (Shamir Secret Sharing)
 
 **Optional: Zero-Knowledge Proofs**
 
@@ -218,6 +222,54 @@ if (result.isForUser) {
 const myPayments = await w3pk.stealth?.scanAnnouncements(announcements)
 ```
 
+### Backup & Recovery
+
+```typescript
+// Get backup status
+const status = await w3pk.getBackupStatus()
+console.log('Security Score:', status.securityScore.score) // 0-100
+
+// Create encrypted ZIP backup
+const blob = await w3pk.createZipBackup('MyS3cur3!Password@2042')
+// Save blob to file system
+
+// Create QR backup
+const { qrCodeDataURL } = await w3pk.createQRBackup('password')
+// Display QR code or save as image
+
+// Setup social recovery (3-of-5 guardians)
+await w3pk.setupSocialRecovery(
+  [
+    { name: 'Alice', email: 'alice@example.com' },
+    { name: 'Bob', phone: '+1234567890' },
+    { name: 'Charlie' }
+  ],
+  3 // threshold
+)
+
+// Generate guardian invite
+const invite = await w3pk.generateGuardianInvite(guardianId)
+// Share invite.qrCode or invite.shareCode with guardian
+
+// Recover from guardian shares
+const { mnemonic } = await w3pk.recoverFromGuardians([
+  share1, share2, share3
+])
+
+// Restore from backup
+await w3pk.restoreFromBackup(encryptedData, password)
+
+// Simulate recovery scenarios for testing
+const result = await w3pk.simulateRecoveryScenario({
+  type: 'lost-device',
+  hasBackup: true,
+  hasSocialRecovery: true
+})
+console.log('Can recover:', result.canRecover)
+```
+
+See [Recovery Guide](./docs/RECOVERY.md) for complete documentation.
+
 ## Browser Compatibility
 
 **Supported (95%+ of users):**
@@ -233,6 +285,7 @@ const myPayments = await w3pk.stealth?.scanAnnouncements(announcements)
 ## Documentation
 
 - [Quick Start Guide](./docs/QUICK_START.md) - Get started in 5 minutes
+- [Recovery & Backup System](./docs/RECOVERY.md) - Three-layer backup architecture
 - [Browser Compatibility](./docs/BROWSER_COMPATIBILITY.md) - Supported browsers, devices, and OS versions
 - [Security Architecture](./docs/SECURITY.md) - Integration best practices
 - [ERC-5564 Stealth Addresses](./docs/ERC5564_STEALTH_ADDRESSES.md) - Complete guide with examples

package/dist/index.d.mts

@@ -424,6 +424,108 @@ declare class Web3Passkey {
      * Access ZK proof module (if available)
      */
     get zk(): any;
+    /**
+     * Get comprehensive backup status
+     * Shows user exactly what protects their wallet
+     */
+    getBackupStatus(): Promise<any>;
+    /**
+     * Create password-protected ZIP backup
+     * @param password - Strong password to encrypt the backup
+     * @param options - Optional backup configuration
+     */
+    createZipBackup(password: string, options?: {
+        includeInstructions?: boolean;
+        deviceBinding?: boolean;
+    }): Promise<Blob>;
+    /**
+     * Create QR code backup
+     * @param password - Optional password to encrypt QR code
+     * @param options - QR code configuration
+     */
+    createQRBackup(password?: string, options?: {
+        errorCorrection?: "L" | "M" | "Q" | "H";
+    }): Promise<{
+        qrCodeDataURL: string;
+        instructions: string;
+    }>;
+    /**
+     * Set up social recovery
+     * Splits mnemonic into M-of-N shares for guardian-based recovery
+     *
+     * @param guardians - Array of guardian information
+     * @param threshold - Number of guardians required to recover (M in M-of-N)
+     */
+    setupSocialRecovery(guardians: {
+        name: string;
+        email?: string;
+        phone?: string;
+    }[], threshold: number): Promise<any[]>;
+    /**
+     * Generate guardian invitation
+     * Creates QR code and instructions for a guardian
+     */
+    generateGuardianInvite(guardianId: string): Promise<any>;
+    /**
+     * Recover wallet from guardian shares
+     * @param shares - Array of share data from guardians (JSON strings)
+     */
+    recoverFromGuardians(shares: string[]): Promise<{
+        mnemonic: string;
+        ethereumAddress: string;
+    }>;
+    /**
+     * Restore wallet from encrypted backup
+     * @param backupData - Backup file contents (JSON string)
+     * @param password - Password used to encrypt the backup
+     */
+    restoreFromBackup(backupData: string, password: string): Promise<{
+        mnemonic: string;
+        ethereumAddress: string;
+    }>;
+    /**
+     * Restore wallet from QR code
+     * @param qrData - Scanned QR code data (JSON string)
+     * @param password - Optional password if QR was encrypted
+     */
+    restoreFromQR(qrData: string, password?: string): Promise<{
+        mnemonic: string;
+        ethereumAddress: string;
+    }>;
+    /**
+     * Get cross-device sync status
+     * Shows which devices have access and sync capabilities
+     */
+    getSyncStatus(): Promise<any>;
+    /**
+     * Detect sync capabilities
+     * Shows what platform sync is available (iCloud, Google, etc.)
+     */
+    detectSyncCapabilities(): Promise<any>;
+    /**
+     * Simulate recovery scenario (educational)
+     * Tests what happens in various loss scenarios
+     *
+     * @param scenario - Type of scenario to simulate
+     */
+    simulateRecoveryScenario(scenario: {
+        type: "lost-device" | "lost-phrase" | "lost-both" | "switch-platform";
+        description: string;
+    }): Promise<any>;
+    /**
+     * Run interactive recovery test
+     * Tests all recovery scenarios and provides feedback
+     */
+    runRecoveryTest(): Promise<{
+        scenarios: any[];
+        overallScore: number;
+        feedback: string;
+    }>;
+    /**
+     * Get educational content
+     * @param topic - Topic to explain (e.g., 'whatIsPasskey', 'socialRecoveryExplained')
+     */
+    getEducation(topic: string): Promise<any>;
     /**
      * Check if there's an active session
      */
@@ -485,6 +587,523 @@ declare function deriveWalletFromMnemonic(mnemonic: string, index?: number): {
     privateKey: string;
 };
 
+/**
+ * Backup and Recovery Type Definitions
+ */
+interface BackupStatus {
+    passkeySync: PasskeySyncStatus;
+    recoveryPhrase: RecoveryPhraseStatus;
+    socialRecovery?: SocialRecoveryStatus;
+    securityScore: SecurityScore;
+}
+interface PasskeySyncStatus {
+    enabled: boolean;
+    deviceCount: number;
+    lastSyncTime?: number;
+    platform: 'apple' | 'google' | 'microsoft' | 'unknown';
+}
+interface RecoveryPhraseStatus {
+    verified: boolean;
+    verificationCount: number;
+    lastVerified?: number;
+    encryptedBackups: EncryptedBackupInfo[];
+}
+interface EncryptedBackupInfo {
+    id: string;
+    method: 'zip' | 'qr' | 'file';
+    location: string;
+    createdAt: number;
+    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: number;
+    lastVerified?: number;
+}
+interface SecurityScore {
+    total: number;
+    breakdown: {
+        passkeyActive: number;
+        passkeyMultiDevice: number;
+        phraseVerified: number;
+        encryptedBackup: number;
+        socialRecovery: number;
+    };
+    level: 'vulnerable' | 'protected' | 'secured' | 'fort-knox';
+    nextMilestone: string;
+}
+interface BackupMetadata {
+    id: string;
+    ethereumAddress: string;
+    method: 'zip' | 'qr' | 'file';
+    createdAt: number;
+    deviceFingerprint?: string;
+    addressChecksum: string;
+}
+interface ZipBackupOptions {
+    password: string;
+    includeInstructions?: boolean;
+    deviceBinding?: boolean;
+}
+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 Backup Manager
+ * Orchestrates all backup and recovery operations
+ */
+
+declare class BackupManager {
+    private storage;
+    private zipCreator;
+    private qrCreator;
+    constructor();
+    /**
+     * Get comprehensive backup status
+     * Shows user exactly what protects their wallet
+     */
+    getBackupStatus(ethereumAddress: string): Promise<BackupStatus>;
+    /**
+     * Detect passkey sync capabilities
+     */
+    private detectPasskeySync;
+    /**
+     * Check if platform supports resident keys (required for passkey sync)
+     */
+    private checkResidentKeySupport;
+    /**
+     * Calculate security score
+     */
+    private calculateSecurityScore;
+    /**
+     * Create password-protected ZIP backup
+     */
+    createZipBackup(mnemonic: string, ethereumAddress: string, options: ZipBackupOptions): Promise<Blob>;
+    /**
+     * Create QR code backup
+     */
+    createQRBackup(mnemonic: string, ethereumAddress: string, options?: QRBackupOptions): Promise<{
+        qrCodeDataURL: string;
+        instructions: string;
+    }>;
+    /**
+     * Restore from ZIP backup
+     */
+    restoreFromZipBackup(backupData: string, password: string): Promise<{
+        mnemonic: string;
+        ethereumAddress: string;
+    }>;
+    /**
+     * Restore from QR backup
+     */
+    restoreFromQR(qrData: string, password?: string): Promise<{
+        mnemonic: string;
+        ethereumAddress: string;
+    }>;
+    /**
+     * Simulate recovery scenario (educational)
+     */
+    simulateRecoveryScenario(scenario: RecoveryScenario, currentStatus: BackupStatus): Promise<SimulationResult>;
+}
+
+/**
+ * IndexedDB Storage for Backup Metadata
+ */
+
+declare class BackupStorage {
+    private dbName;
+    private version;
+    private db;
+    /**
+     * Initialize the database
+     */
+    init(): Promise<void>;
+    /**
+     * Store backup metadata
+     */
+    storeBackupMetadata(metadata: BackupMetadata): Promise<void>;
+    /**
+     * Get all backups for an address
+     */
+    getBackupsByAddress(ethereumAddress: string): Promise<BackupMetadata[]>;
+    /**
+     * Get backup by ID
+     */
+    getBackupById(id: string): Promise<BackupMetadata | null>;
+    /**
+     * Delete backup metadata
+     */
+    deleteBackup(id: string): Promise<void>;
+    /**
+     * Get count of backups by method
+     */
+    getBackupCountByMethod(method: 'zip' | 'qr' | 'file'): Promise<number>;
+}
+
+/**
+ * Social Recovery Type Definitions
+ */
+interface Guardian {
+    id: string;
+    name: string;
+    email?: string;
+    phone?: string;
+    publicKey?: string;
+    shareEncrypted: string;
+    status: 'pending' | 'active' | 'revoked';
+    addedAt: number;
+    lastVerified?: number;
+}
+interface GuardianInvite {
+    guardianId: string;
+    qrCode: string;
+    shareCode: string;
+    explainer: string;
+    link?: string;
+}
+interface SocialRecoveryConfig {
+    threshold: number;
+    totalGuardians: number;
+    guardians: Guardian[];
+    createdAt: number;
+    ethereumAddress: string;
+}
+interface RecoveryShare {
+    guardianId: string;
+    share: string;
+    index: number;
+}
+interface RecoveryProgress {
+    collected: number;
+    required: number;
+    guardians: {
+        id: string;
+        name: string;
+        hasProvided: boolean;
+    }[];
+    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 mnemonic into M-of-N shares and distributes to guardians
+     */
+    setupSocialRecovery(mnemonic: 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
+     */
+    private generateQRCode;
+    /**
+     * Create placeholder QR code
+     */
+    private createPlaceholderQR;
+    /**
+     * Wrap text for display
+     */
+    private wrapText;
+    /**
+     * Get guardian explainer text
+     */
+    private getGuardianExplainer;
+    /**
+     * Recover mnemonic from guardian shares
+     */
+    recoverFromGuardians(shareData: string[]): Promise<{
+        mnemonic: string;
+        ethereumAddress: string;
+    }>;
+    /**
+     * Get recovery progress
+     */
+    getRecoveryProgress(collectedShares: string[]): RecoveryProgress;
+    /**
+     * Mark guardian as verified
+     */
+    markGuardianVerified(guardianId: string): void;
+    /**
+     * Revoke a guardian
+     */
+    revokeGuardian(guardianId: string): void;
+    /**
+     * Add new guardian (requires re-sharing)
+     */
+    addGuardian(mnemonic: string, newGuardian: {
+        name: string;
+        email?: string;
+        phone?: string;
+    }): Promise<Guardian>;
+}
+
+/**
+ * Cross-Device Sync Type Definitions
+ */
+interface SyncVault {
+    id: string;
+    encryptedData: string;
+    deviceFingerprints: string[];
+    syncMethod: 'icloud' | 'google' | 'microsoft' | 'custom';
+    version: number;
+    updatedAt: number;
+}
+interface DeviceInfo {
+    id: string;
+    name: string;
+    platform: 'ios' | 'android' | 'macos' | 'windows' | 'linux' | 'unknown';
+    lastActive: number;
+    trusted: boolean;
+    canRevoke: boolean;
+}
+interface SyncCapabilities {
+    passkeysSync: boolean;
+    platform: 'apple' | 'google' | 'microsoft' | 'none';
+    estimatedDevices: number;
+    syncEnabled: boolean;
+}
+interface SyncStatus {
+    enabled: boolean;
+    devices: DeviceInfo[];
+    lastSyncTime?: number;
+    platform: string;
+}
+interface SyncResult {
+    success: boolean;
+    steps: SyncStep[];
+}
+interface SyncStep {
+    title: string;
+    action: string;
+    educational: string;
+    status: 'waiting' | 'in-progress' | 'completed' | 'failed';
+}
+
+/**
+ * Encrypted Sync Vault
+ * Manages encrypted wallet data for cross-device sync
+ */
+
+declare class VaultSync {
+    /**
+     * Create encrypted sync package
+     * Uses passkey + device fingerprint for encryption
+     */
+    createSyncPackage(mnemonic: string, credentialId: string, publicKey: string): Promise<SyncVault>;
+    /**
+     * Detect available sync method
+     */
+    private detectSyncMethod;
+    /**
+     * Restore from sync vault
+     * Interactive guide for multi-device setup
+     */
+    restoreFromSync(vault: SyncVault, credentialId: string, publicKey: string): Promise<string>;
+    /**
+     * Get setup flow for new device
+     * Educational flow with step-by-step instructions
+     */
+    getSetupFlow(): Promise<SyncResult>;
+    /**
+     * Educational message about how sync works
+     */
+    getSyncExplainer(): string;
+}
+
+/**
+ * Device Manager
+ * Track and manage trusted devices with wallet access
+ */
+
+declare class DeviceManager {
+    private storageKey;
+    /**
+     * Register current device
+     */
+    registerDevice(): Promise<DeviceInfo>;
+    /**
+     * Get all registered devices
+     */
+    getDevices(): Promise<DeviceInfo[]>;
+    /**
+     * Get sync status with device list
+     */
+    getSyncStatus(): Promise<SyncStatus>;
+    /**
+     * Revoke a device
+     */
+    revokeDevice(deviceId: string): Promise<void>;
+    /**
+     * Update device last active timestamp
+     */
+    updateLastActive(): Promise<void>;
+    /**
+     * Get device name
+     */
+    private getDeviceName;
+    /**
+     * Detect device platform
+     */
+    private detectPlatform;
+    /**
+     * Get platform display name
+     */
+    private getPlatformName;
+    /**
+     * Get formatted device list for display
+     */
+    getDeviceListFormatted(): Promise<string>;
+    /**
+     * Format time difference for display
+     */
+    private formatTimeDiff;
+}
+
+/**
+ * Platform Detection for Passkey Sync
+ * Detects available sync platforms (iCloud, Google, Microsoft)
+ */
+
+declare class PlatformDetector {
+    /**
+     * Detect available sync capabilities
+     * Shows what's automatically protecting the user
+     */
+    detectSyncCapabilities(): Promise<SyncCapabilities>;
+    /**
+     * Detect user's platform
+     */
+    private detectPlatform;
+    /**
+     * Check if passkey sync is supported
+     */
+    private checkPasskeySync;
+    /**
+     * Estimate number of synced devices
+     * Note: This is a rough estimate, actual count requires server-side tracking
+     */
+    private estimateDeviceCount;
+    /**
+     * Get platform-specific educational message
+     */
+    getPlatformEducation(platform: 'apple' | 'google' | 'microsoft' | 'none'): string;
+    /**
+     * Get sync setup instructions
+     */
+    getSyncInstructions(platform: 'apple' | 'google' | 'microsoft' | 'none'): string[];
+}
+
+/**
+ * Recovery Scenario Simulator
+ * Educational tool to help users understand recovery options
+ */
+
+declare class RecoverySimulator {
+    /**
+     * Predefined recovery scenarios
+     */
+    getScenarios(): RecoveryScenario[];
+    /**
+     * Simulate a recovery scenario
+     */
+    simulateScenario(scenario: RecoveryScenario, currentStatus: BackupStatus): Promise<SimulationResult>;
+    /**
+     * Estimate fastest recovery time
+     */
+    private estimateFastestRecovery;
+    /**
+     * Get educational note for scenario
+     */
+    private getEducationalNote;
+    /**
+     * Run interactive test
+     */
+    runInteractiveTest(currentStatus: BackupStatus): Promise<{
+        scenarios: SimulationResult[];
+        overallScore: number;
+        feedback: string;
+    }>;
+}
+
+/**
+ * Educational Content
+ * Explainers for users to understand security concepts
+ */
+interface EducationalModule {
+    title: string;
+    content: string;
+    visual?: string;
+    interactive?: string;
+}
+/**
+ * Get explainer by topic
+ */
+declare function getExplainer(topic: string): EducationalModule | null;
+/**
+ * Get all explainer topics
+ */
+declare function getAllTopics(): string[];
+/**
+ * Search explainers
+ */
+declare function searchExplainers(query: string): EducationalModule[];
+
 /**
  * Web3 Passkey SDK
  * Passwordless authentication with encrypted wallets
@@ -492,4 +1111,4 @@ declare function deriveWalletFromMnemonic(mnemonic: string, index?: number): {
 
 declare function createWeb3Passkey(config?: Web3PasskeyConfig): Web3Passkey;
 
-export { ApiError, AuthenticationError, CryptoError, RegistrationError, type StealthAddressConfig, StealthAddressModule, type StealthAddressResult, type StealthKeys, StorageError, type UserInfo, WalletError, type WalletInfo, Web3Passkey, type Web3PasskeyConfig, Web3PasskeyError, canControlStealthAddress, checkStealthAddress, computeStealthPrivateKey, createWalletFromMnemonic, createWeb3Passkey, createWeb3Passkey as default, deriveStealthKeys, deriveWalletFromMnemonic, generateBIP39Wallet, generateStealthAddress };
+export { ApiError, AuthenticationError, BackupManager, type BackupStatus, BackupStorage, CryptoError, type DeviceInfo, DeviceManager, type EncryptedBackupInfo, type Guardian, type GuardianInvite, PlatformDetector, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SimulationResult, type SocialRecoveryConfig, SocialRecoveryManager, type StealthAddressConfig, StealthAddressModule, type StealthAddressResult, type StealthKeys, StorageError, type SyncCapabilities, type SyncStatus, type SyncVault, type UserInfo, VaultSync, WalletError, type WalletInfo, Web3Passkey, type Web3PasskeyConfig, Web3PasskeyError, type ZipBackupOptions, canControlStealthAddress, checkStealthAddress, computeStealthPrivateKey, createWalletFromMnemonic, createWeb3Passkey, createWeb3Passkey as default, deriveStealthKeys, deriveWalletFromMnemonic, generateBIP39Wallet, generateStealthAddress, getAllTopics, getExplainer, searchExplainers };