@spacesops/wdk-react-native-core 1.0.0-beta.40

package/dist/services/walletSetupService.d.ts

@@ -0,0 +1,217 @@
+import type { SecureStorage } from '@tetherto/wdk-react-native-secure-storage';
+import type { NetworkConfigs } from '../types';
+/**
+ * Wallet setup service
+ * Handles creating new wallets and loading existing wallets with biometric authentication
+ * Caches credentials in ephemeral memory to avoid repeated biometric prompts
+ *
+ * ## Biometric Authentication Lifecycle
+ *
+ * ### When Biometric Authentication is Required
+ *
+ * 1. **Creating a new wallet** (`createNewWallet`)
+ *   - Always requires biometric authentication before wallet creation
+ *   - Ensures only authorized users can create wallets
+ *   - Credentials are cached after successful authentication
+ *
+ * 2. **Loading existing wallet** (`loadExistingWallet`)
+ *   - Requires biometric authentication if credentials are not cached
+ *   - If credentials are in cache, authentication is skipped (better UX)
+ *   - Cache is checked first before prompting for biometrics
+ *
+ * 3. **Importing wallet from mnemonic** (`initializeFromMnemonic`)
+ *   - Always requires biometric authentication before import
+ *   - Ensures only authorized users can import wallets
+ *   - Credentials are cached after successful authentication
+ *
+ * ### Credential Caching Behavior
+ *
+ * - **Cache Location**: Ephemeral memory only (Map<string, CachedCredentials>)
+ *   - Cache is keyed by `identifier` (user email/ID) for multi-wallet support
+ *   - Cache persists for the lifetime of the app session
+ *   - Cache is cleared when app is terminated (not persisted to disk)
+ *
+ * - **Cache Contents**:
+ *   - `encryptionKey`: Cached after first retrieval (most sensitive, requires biometrics)
+ *   - `encryptedSeed`: Cached after first retrieval
+ *   - `encryptedEntropy`: Cached after first retrieval
+ *
+ * - **Cache Benefits**:
+ *   - Avoids repeated biometric prompts during the same app session
+ *   - Improves UX for operations that need credentials multiple times
+ *   - Reduces security surface (fewer biometric prompts = fewer attack vectors)
+ *
+ * ### When Cache is Cleared
+ *
+ * Cache is automatically cleared in the following scenarios:
+ *
+ * 1. **Explicit cache clearing** (`clearCredentialsCache`)
+ *   - Called when wallet data is corrupted or invalid
+ *   - Called during wallet deletion
+ *   - Can be called manually for security (e.g., on logout)
+ *
+ * 2. **App termination**
+ *   - Cache is in-memory only, so it's cleared when app closes
+ *   - Next app launch will require biometric authentication again
+ *
+ * 3. **Wallet deletion** (`deleteWallet`)
+ *   - Cache for the deleted wallet identifier is cleared
+ *   - Other wallet caches remain intact
+ *
+ * ### Security Considerations
+ *
+ * - **Cache Lifetime**: Ephemeral (in-memory only, cleared on app termination)
+ * - **Cache Scope**: Per-identifier (multi-wallet support)
+ * - **Cache Invalidation**: Manual via `clearCredentialsCache()` or automatic on app termination
+ * - **Biometric Prompt Frequency**:
+ *   - First access per app session: Always required
+ *   - Subsequent accesses in same session: Cached (no prompt)
+ *   - After app restart: Always required again
+ *
+ * ### Best Practices
+ *
+ * 1. **Clear cache on logout**: Call `clearCredentialsCache(identifier)` when user logs out
+ * 2. **Clear cache on errors**: Clear cache if decryption fails (may indicate corrupted data)
+ * 3. **Don't persist cache**: Cache is intentionally in-memory only for security
+ * 4. **Handle cache misses**: Always handle the case where cache is empty (will prompt for biometrics)
+ *
+ * ### Example Usage
+ *
+ * ```typescript
+ * // Create new wallet (always requires biometrics)
+ * await WalletSetupService.createNewWallet(networkConfigs, walletId)
+ *
+ * // Load existing wallet (biometrics only if not cached)
+ * const credentials = await WalletSetupService.loadExistingWallet(walletId)
+ *
+ * // Clear cache (e.g., on logout)
+ * WalletSetupService.clearCredentialsCache(walletId)
+ * ```
+ */
+export declare class WalletSetupService {
+    /**
+     * SecureStorage singleton instance
+     * Set by WdkAppProvider during initialization
+     */
+    private static secureStorageInstance;
+    /**
+     * Set the secureStorage singleton instance
+     * Called by WdkAppProvider during initialization
+     * Also exposed publicly for testing purposes
+     *
+     * @param secureStorage - SecureStorage instance to use
+     * @param allowOverwrite - If false, warns when overwriting existing instance (default: true)
+     */
+    static setSecureStorage(secureStorage: SecureStorage, allowOverwrite?: boolean): void;
+    /**
+     * Get the secureStorage singleton instance
+     * Throws error if not initialized (should only happen if called before WdkAppProvider mounts)
+     */
+    private static getSecureStorage;
+    /**
+     * Check if secureStorage is initialized
+     * Useful for testing or debugging
+     */
+    static isSecureStorageInitialized(): boolean;
+    /**
+     * Get cache key for walletId
+     */
+    private static getCacheKey;
+    /**
+     * Cache credentials after retrieval
+     */
+    private static cacheCredentials;
+    /**
+     * Generic helper to retrieve a credential value (checks cache first, then secureStorage)
+     */
+    private static getCredential;
+    /**
+     * Validate that encrypted data can be decrypted with the encryption key
+     * Attempts to initialize WDK with the provided credentials to verify compatibility
+     *
+     * @param networkConfigs - Network configurations for worklet
+     * @param encryptionKey - Encryption key to test
+     * @param encryptedSeed - Encrypted seed to test
+     * @param encryptedEntropy - Optional encrypted entropy to test
+     * @throws Error if validation fails (decryption fails)
+     */
+    private static validateEncryptionCompatibility;
+    /**
+     * Create a new wallet
+     * Generates entropy, encrypts it, and stores credentials securely
+     * Requires biometric authentication to ensure authorized wallet creation
+     */
+    static createNewWallet(networkConfigs: NetworkConfigs, walletId?: string): Promise<{
+        encryptionKey: string;
+        encryptedSeed: string;
+    }>;
+    /**
+     * Load existing wallet from secure storage
+     * Checks cache first, only requires biometric authentication if not cached
+     */
+    static loadExistingWallet(walletId?: string): Promise<{
+        encryptionKey: string;
+        encryptedSeed: string;
+    }>;
+    /**
+     * Check if a wallet exists
+     */
+    static hasWallet(walletId?: string): Promise<boolean>;
+    /**
+     * Initialize WDK from an existing mnemonic phrase
+     * Converts mnemonic to encrypted seed and entropy, stores them securely, and initializes WDK
+     * Requires biometric authentication to ensure authorized wallet import
+     */
+    static initializeFromMnemonic(networkConfigs: NetworkConfigs, mnemonic: string, walletId?: string): Promise<{
+        encryptionKey: string;
+        encryptedSeed: string;
+        encryptedEntropy: string;
+    }>;
+    /**
+     * Initialize WDK with wallet credentials
+     */
+    static initializeWDK(networkConfigs: NetworkConfigs, credentials: {
+        encryptionKey: string;
+        encryptedSeed: string;
+    }): Promise<void>;
+    /**
+     * Complete wallet initialization flow
+     * Either creates a new wallet or loads an existing one
+     */
+    static initializeWallet(networkConfigs: NetworkConfigs, options: {
+        createNew?: boolean;
+        walletId?: string;
+    }): Promise<void>;
+    /**
+     * Delete wallet and clear all data
+     *
+     * @param identifier - Optional identifier for multi-wallet support. If provided, deletes wallet for that identifier.
+     *                    If not provided, deletes the default wallet.
+     */
+    static deleteWallet(walletId?: string): Promise<void>;
+    /**
+     * Get encryption key (checks cache first, then secureStorage with biometrics)
+     */
+    static getEncryptionKey(walletId?: string): Promise<string | null>;
+    /**
+     * Get encrypted seed (checks cache first, then secureStorage)
+     */
+    static getEncryptedSeed(walletId?: string): Promise<string | null>;
+    /**
+     * Get encrypted entropy (checks cache first, then secureStorage)
+     */
+    static getEncryptedEntropy(walletId?: string): Promise<string | null>;
+    /**
+     * Get mnemonic phrase from wallet
+     * Retrieves encrypted entropy and encryption key, then decrypts to get mnemonic
+     *
+     * @param walletId - Optional walletId for multi-wallet support
+     * @returns Promise<string | null> - The mnemonic phrase or null if not found
+     */
+    static getMnemonic(walletId?: string): Promise<string | null>;
+    /**
+     * Clear all cached credentials
+     * Should be called on logout or app background for security
+     */
+    static clearCredentialsCache(walletId?: string): void;
+}