w3pk 0.7.0 → 0.7.2

package/dist/index.d.ts

@@ -320,9 +320,10 @@ declare class Web3Passkey {
     private zkModule?;
     constructor(config?: Web3PasskeyConfig);
     /**
-     * Lazy-load ZK module to avoid bundling large dependencies
+     * Lazy-load ZK module only when accessed
+     * This prevents bundlers from including circomlibjs unless ZK features are used
      */
-    private initializeZKModule;
+    private loadZKModule;
     /**
      * Get mnemonic from active session or trigger authentication
      * This is used internally by methods that need the mnemonic
@@ -334,12 +335,13 @@ declare class Web3Passkey {
      * Register a new user with WebAuthn
      * Automatically generates a wallet if none exists
      * Creates a passkey and associates it with the Ethereum address (account #0)
-     * Returns the mnemonic phrase - IMPORTANT: User must save this!
+     * Returns the derived address #0 and username
      */
     register(options: {
         username: string;
     }): Promise<{
-        mnemonic: string;
+        address: string;
+        username: string;
     }>;
     /**
      * Login with WebAuthn (usernameless)
@@ -424,6 +426,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 +589,547 @@ 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[];
+
+/**
+ * Input validation utilities
+ */
+declare function validateEthereumAddress(address: string): boolean;
+declare function validateUsername(username: string): boolean;
+declare function validateMnemonic(mnemonic: string): boolean;
+declare function assertEthereumAddress(address: string): void;
+declare function assertUsername(username: string): void;
+declare function assertMnemonic(mnemonic: string): void;
+/**
+ * Validates password strength based on security best practices
+ * @param password - The password to validate
+ * @returns true if password meets strength requirements, false otherwise
+ *
+ * Requirements:
+ * - At least 12 characters long
+ * - Contains at least one uppercase letter
+ * - Contains at least one lowercase letter
+ * - Contains at least one number
+ * - Contains at least one special character
+ * - Not a common password
+ */
+declare function isStrongPassword(password: string): boolean;
+
 /**
  * Web3 Passkey SDK
  * Passwordless authentication with encrypted wallets
@@ -492,4 +1137,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, assertEthereumAddress, assertMnemonic, assertUsername, canControlStealthAddress, checkStealthAddress, computeStealthPrivateKey, createWalletFromMnemonic, createWeb3Passkey, createWeb3Passkey as default, deriveStealthKeys, deriveWalletFromMnemonic, generateBIP39Wallet, generateStealthAddress, getAllTopics, getExplainer, isStrongPassword, searchExplainers, validateEthereumAddress, validateMnemonic, validateUsername };