@dynamic-labs-wallet/browser 0.0.339 → 0.0.341

package/index.esm.js

@@ -355,6 +355,17 @@ class InvalidPasswordError extends Error {
     return metadata;
 };
 
+class StaleLocalSharesError extends Error {
+    constructor(args){
+        super(args.localSharesRefreshed ? 'Local key shares were stale and have been refreshed from the server. Please retry the operation.' : 'Local key shares are stale and could not be refreshed automatically. Please recover or re-authenticate before re-attempting.');
+        this.name = 'StaleLocalSharesError';
+        this.accountAddress = args.accountAddress;
+        this.localKeygenIds = args.localKeygenIds;
+        this.recordedKeygenIds = args.recordedKeygenIds;
+        this.localSharesRefreshed = args.localSharesRefreshed;
+    }
+}
+
 const GOOGLE_DRIVE_UPLOAD_API = 'https://www.googleapis.com';
 const USER_ACTIONABLE_REASONS = new Set([
     'auth_denied',
@@ -722,36 +733,6 @@ const getClientKeyShareBackupInfo = (params)=>{
         passwordEncrypted
     };
 };
-/**
- * Helper function to merge keyshares and remove duplicates based on pubkey and secretShare
- * @param existingKeyShares - Array of existing keyshares
- * @param newKeyShares - Array of new keyshares to merge
- * @returns Array of merged unique keyshares
- */ const mergeUniqueKeyShares = (existingKeyShares, newKeyShares)=>{
-    const hasDegeneratePubkeyToString = [
-        ...existingKeyShares,
-        ...newKeyShares
-    ].some((share)=>{
-        var _share_pubkey;
-        return 'pubkey' in share && ((_share_pubkey = share.pubkey) == null ? void 0 : _share_pubkey.toString()) === '[object Object]' // NOSONAR
-        ;
-    });
-    if (hasDegeneratePubkeyToString) {
-        Logger.warn('[mergeUniqueKeyShares] pubkey.toString() returned "[object Object]" — dedup falls back to secretShare-only comparison', {
-            existingCount: existingKeyShares.length,
-            newCount: newKeyShares.length
-        });
-    }
-    const uniqueKeyShares = newKeyShares.filter((newShare)=>!existingKeyShares.some((existingShare)=>{
-            if (!('pubkey' in newShare) || !('pubkey' in existingShare)) return false;
-            if (!newShare.pubkey || !existingShare.pubkey) return false;
-            return newShare.pubkey.toString() === existingShare.pubkey.toString() && newShare.secretShare === existingShare.secretShare;
-        }));
-    return [
-        ...existingKeyShares,
-        ...uniqueKeyShares
-    ];
-};
 const timeoutPromise = ({ timeInMs, activity = 'Ceremony' })=>{
     return new Promise((_, reject)=>setTimeout(()=>reject(new Error(`${activity} did not complete in ${timeInMs}ms`)), timeInMs));
 };
@@ -2754,23 +2735,15 @@ class DynamicWalletClient {
             walletOperation,
             dynamicRequestId
         }, this.getTraceContext(traceContext)));
-        // Refresh walletMap from API before recovery to ensure backup info is up-to-date
+        // Refresh walletMap from API before recovery to ensure backup info is up-to-date.
         await this.getWallets();
-        // Recover key shares from backup (don't auto-store, we'll overwrite below)
-        // Use internal method directly to bypass queueing - we're already inside a queued operation
         const recoveredKeyShares = await this.internalRecoverEncryptedBackupByWallet({
             accountAddress,
-            password: password != null ? password : this.environmentId,
-            walletOperation,
+            password,
             signedSessionId,
+            walletOperation,
             mfaToken,
-            storeRecoveredShares: false
-        });
-        // Overwrite local key shares with recovered ones (not merge)
-        await this.setClientKeySharesToStorage({
-            accountAddress,
-            clientKeyShares: recoveredKeyShares,
-            overwriteOrMerge: 'overwrite'
+            storeRecoveredShares: true
         });
         this.logger.info('[DynamicWaasWalletClient] Key shares recovered, retrying operation', _extends({
             accountAddress,
@@ -3104,8 +3077,7 @@ class DynamicWalletClient {
             });
             await this.setClientKeySharesToStorage({
                 accountAddress,
-                clientKeyShares: refreshResults,
-                overwriteOrMerge: 'overwrite'
+                clientKeyShares: refreshResults
             });
         } catch (error) {
             // Expected condition — not a server error, no need to page on this.
@@ -3127,6 +3099,13 @@ class DynamicWalletClient {
             throw error;
         }
     }
+    async getKeygenIdForShare(mpcSigner, share) {
+        // BIP340.exportID accepts the raw secretShare string; other signers accept the whole keygen result.
+        if (mpcSigner instanceof BIP340) {
+            return mpcSigner.exportID(share.secretShare);
+        }
+        return mpcSigner.exportID(share);
+    }
     async getExportId({ chainName, clientKeyShare, bitcoinConfig }) {
         const mpcSigner = getMPCSigner({
             chainName,
@@ -3134,15 +3113,7 @@ class DynamicWalletClient {
             bitcoinConfig
         });
         try {
-            // For BIP340, try passing the secretShare as a string directly
-            // The exportID accepts either BIP340KeygenResult or string (secretShare)
-            let exportId;
-            if (mpcSigner instanceof BIP340) {
-                const secretShareString = clientKeyShare.secretShare;
-                exportId = await mpcSigner.exportID(secretShareString);
-            } else {
-                exportId = await mpcSigner.exportID(clientKeyShare);
-            }
+            const exportId = await this.getKeygenIdForShare(mpcSigner, clientKeyShare);
             this.logger.debug('[DynamicWaasWalletClient] getExportId succeeded', {
                 chainName,
                 exportId
@@ -3460,8 +3431,7 @@ class DynamicWalletClient {
             // only after backup succeeds.
             await this.setClientKeySharesToStorage({
                 accountAddress,
-                clientKeyShares: distribution.clientShares,
-                overwriteOrMerge: 'overwrite'
+                clientKeyShares: distribution.clientShares
             });
         } catch (error) {
             logError({
@@ -3484,8 +3454,7 @@ class DynamicWalletClient {
             });
             await this.setClientKeySharesToStorage({
                 accountAddress,
-                clientKeyShares: [],
-                overwriteOrMerge: 'overwrite'
+                clientKeyShares: []
             });
             throw error;
         }
@@ -3831,63 +3800,44 @@ class DynamicWalletClient {
    * Helper function to store client key shares in storage.
    * Uses secureStorage when available (mobile), otherwise falls back to localStorage (browser).
    */ /**
-   * Resolves the final array of shares to persist by either replacing
-   * (overwrite) or merging with existing shares (merge), and emits a
-   * persistence-info log so we can audit storage operations from traces.
-   */ async resolveSharesToPersist({ accountAddress, clientKeyShares, overwriteOrMerge, source, readExisting }) {
-        let sharesToStore;
-        let existingCount = 0;
-        if (overwriteOrMerge === 'overwrite') {
-            sharesToStore = clientKeyShares;
-        } else {
-            const existing = await readExisting();
-            existingCount = existing.length;
-            sharesToStore = mergeUniqueKeyShares(existing, clientKeyShares);
-        }
+   * Emits a persistence-info log so storage writes are auditable from traces.
+   */ logSharePersistence({ accountAddress, clientKeyShares, source }) {
         this.logger.info('[DynamicWaasWalletClient] Persisting client key shares', {
             accountAddress,
             source,
-            mode: overwriteOrMerge,
-            inputCount: clientKeyShares.length,
-            existingCount,
-            finalCount: sharesToStore.length
+            inputCount: clientKeyShares.length
         });
-        return sharesToStore;
     }
-    async setClientKeySharesToLocalStorage({ accountAddress, clientKeyShares, overwriteOrMerge = 'merge' }) {
+    async setClientKeySharesToLocalStorage({ accountAddress, clientKeyShares }) {
         accountAddress = normalizeAddress(accountAddress);
-        const sharesToStore = await this.resolveSharesToPersist({
+        this.logSharePersistence({
             accountAddress,
             clientKeyShares,
-            overwriteOrMerge,
-            source: 'localStorage',
-            readExisting: ()=>this.getClientKeySharesFromLocalStorage({
-                    accountAddress
-                })
+            source: 'localStorage'
         });
         const stringifiedClientKeyShares = JSON.stringify({
-            clientKeyShares: sharesToStore
+            clientKeyShares
         });
         await this.storage.setItem(accountAddress, stringifiedClientKeyShares);
     }
     /**
-   * Helper function to store client key shares in storage.
+   * Replaces the client key shares stored for `accountAddress` with `clientKeyShares`.
    * Uses secureStorage when available (mobile), otherwise falls back to localStorage (browser).
-   */ async setClientKeySharesToStorage({ accountAddress, clientKeyShares, overwriteOrMerge = 'merge' }) {
+   *
+   * A WaaS wallet holds exactly one client share per device (see share-distribution
+   * factories in types.ts), so writes are always a full replacement — there is no
+   * merge mode. Callers that need to clear local shares pass `clientKeyShares: []`.
+   */ async setClientKeySharesToStorage({ accountAddress, clientKeyShares }) {
         accountAddress = normalizeAddress(accountAddress);
         // Use secure storage if available (mobile)
         if (this.secureStorage) {
             try {
-                const sharesToStore = await this.resolveSharesToPersist({
+                this.logSharePersistence({
                     accountAddress,
                     clientKeyShares,
-                    overwriteOrMerge,
-                    source: 'secureStorage',
-                    readExisting: ()=>this.getClientKeySharesFromStorage({
-                            accountAddress
-                        })
+                    source: 'secureStorage'
                 });
-                await this.secureStorage.setClientKeyShare(accountAddress, sharesToStore);
+                await this.secureStorage.setClientKeyShare(accountAddress, clientKeyShares);
                 return;
             } catch (error) {
                 logError({
@@ -3903,8 +3853,7 @@ class DynamicWalletClient {
         // Fallback to localStorage (browser)
         await this.setClientKeySharesToLocalStorage({
             accountAddress,
-            clientKeyShares,
-            overwriteOrMerge
+            clientKeyShares
         });
     }
     /**
@@ -4263,6 +4212,93 @@ class DynamicWalletClient {
             throw error;
         }
     }
+    // Defense-in-depth check: before uploading a backup, confirm that local client shares
+    // still match the keygenIds recorded for backups[DYNAMIC] on the server. On mismatch,
+    // refreshes local storage from the server's encrypted backup (so a subsequent retry
+    // sees fresh state) and then throws StaleLocalSharesError. We deliberately don't
+    // continue the upload silently after recovery — callers like updatePassword hold
+    // operation-specific context (existing/new password) that must be re-applied to
+    // freshly-recovered shares. Throwing surfaces the stale-state event so the host can
+    // re-enter the outer operation with correct context. Skipped on internal post-rotation
+    // flows that pass clientKeyShares explicitly (the refresh path).
+    async ensureLocalSharesAreFresh({ accountAddress, walletData, localShares, password, signedSessionId }) {
+        var _freshBackupInfo_backups;
+        // Always round-trip to the server — walletMap is populated at wallet-load and is
+        // not invalidated when another tab rotates shares, so trusting it would
+        // false-positive on cross-tab refresh.
+        const { chainName } = walletData;
+        const mpcSigner = getMPCSigner({
+            chainName,
+            baseRelayUrl: this.baseMPCRelayApiUrl,
+            bitcoinConfig: this.getBitcoinConfigForChain(chainName, accountAddress)
+        });
+        const [freshBackupInfo, localKeygenIds] = await Promise.all([
+            this.fetchFreshWalletBackupInfo({
+                accountAddress
+            }),
+            Promise.all(localShares.map((share)=>this.getKeygenIdForShare(mpcSigner, share)))
+        ]);
+        var _freshBackupInfo_backups_BackupLocation_DYNAMIC;
+        const recordedKeygenIds = ((_freshBackupInfo_backups_BackupLocation_DYNAMIC = freshBackupInfo == null ? void 0 : (_freshBackupInfo_backups = freshBackupInfo.backups) == null ? void 0 : _freshBackupInfo_backups[BackupLocation.DYNAMIC]) != null ? _freshBackupInfo_backups_BackupLocation_DYNAMIC : []).map((entry)=>entry.keygenId).filter((id)=>typeof id === 'string' && id.length > 0);
+        // First-time backup or legacy data (server didn't populate keygenId yet) — nothing to compare.
+        if (recordedKeygenIds.length === 0) return;
+        const recordedSet = new Set(recordedKeygenIds);
+        const localMatchesRecorded = localKeygenIds.length === recordedSet.size && localKeygenIds.every((id)=>recordedSet.has(id));
+        if (localMatchesRecorded) return;
+        this.logger.warn('[storeEncryptedBackupByWallet] Stale local shares detected; refreshing local storage', {
+            accountAddress,
+            walletId: walletData.walletId,
+            environmentId: this.environmentId,
+            localKeygenIds,
+            recordedKeygenIds
+        });
+        // Resolve a session, falling back to the host's reverse-channel callback when one
+        // wasn't passed in. If neither source produces a session we skip the refresh and
+        // still throw — the host can re-auth from the error.
+        let resolvedSessionId;
+        try {
+            resolvedSessionId = await this.resolveSignedSessionId(signedSessionId);
+        } catch (e) {
+            resolvedSessionId = undefined;
+        }
+        let localSharesRefreshed = false;
+        if (resolvedSessionId) {
+            // The recovery decrypt key is whatever the server's blob was encrypted with — not the
+            // caller's `password` arg, which is the key we'll re-encrypt the *next* upload with.
+            // For setPassword the wallet is currently passwordless (blob encrypted with environmentId)
+            // and the caller passed the new password; passing it through here would
+            // InvalidPasswordError. Fall back to undefined so internalRecover picks environmentId.
+            const recoveryPassword = freshBackupInfo.passwordEncrypted ? password : undefined;
+            try {
+                // walletMap was already refreshed by fetchFreshWalletBackupInfo above, so we skip the
+                // getWallets() refresh that recoverKeySharesOnMismatch performs for its own callers.
+                await this.internalRecoverEncryptedBackupByWallet({
+                    accountAddress,
+                    password: recoveryPassword,
+                    signedSessionId: resolvedSessionId,
+                    walletOperation: WalletOperation.RECOVER,
+                    storeRecoveredShares: true
+                });
+                localSharesRefreshed = true;
+                this.logger.info('[storeEncryptedBackupByWallet] Local shares refreshed from server; caller should retry', {
+                    accountAddress,
+                    walletId: walletData.walletId
+                });
+            } catch (recoveryError) {
+                this.logger.error('[storeEncryptedBackupByWallet] Failed to refresh local shares from server', {
+                    accountAddress,
+                    walletId: walletData.walletId,
+                    error: recoveryError instanceof Error ? recoveryError.message : String(recoveryError)
+                });
+            }
+        }
+        throw new StaleLocalSharesError({
+            accountAddress,
+            localKeygenIds,
+            recordedKeygenIds,
+            localSharesRefreshed
+        });
+    }
     /**
    * Central backup orchestrator that encrypts and stores wallet key shares.
    *
@@ -4295,10 +4331,24 @@ class DynamicWalletClient {
    * @returns Promise with backup metadata including share locations and IDs
    */ async storeEncryptedBackupByWallet({ accountAddress, clientKeyShares = undefined, password = undefined, signedSessionId, cloudProviders = [], delegatedKeyshare = undefined, passwordUpdateBatchId, googleDriveAccessToken }) {
         var _this_getWalletFromMap, _backupData_locationsWithKeyShares, _backupData_locationsWithKeyShares1;
+        const hasProvidedShares = clientKeyShares !== undefined;
         const keySharesToBackup = clientKeyShares != null ? clientKeyShares : await this.getClientKeySharesFromStorage({
             accountAddress
         });
-        // Check if we should backup to cloud providers (either requested or already exists)
+        // Freshness check — only when shares were loaded from local storage. Internal
+        // post-rotation callers (refreshWalletAccountShares) pass clientKeyShares explicitly
+        // and hold shares whose keygenIds are intentionally newer than the recorded backup.
+        const walletDataForFreshness = this.getWalletFromMap(accountAddress);
+        if (!hasProvidedShares && walletDataForFreshness) {
+            await this.ensureLocalSharesAreFresh({
+                accountAddress,
+                walletData: walletDataForFreshness,
+                localShares: keySharesToBackup,
+                password,
+                signedSessionId
+            });
+        }
+        // Re-read after the freshness check: walletMap may have been updated with fresh server data.
         const walletBackupInfo = (_this_getWalletFromMap = this.getWalletFromMap(accountAddress)) == null ? void 0 : _this_getWalletFromMap.clientKeySharesBackupInfo;
         const activeCloudProviders = getActiveCloudProviders(walletBackupInfo);
         const shouldBackupToCloudProviders = cloudProviders.length > 0 || activeCloudProviders.length > 0;
@@ -4696,8 +4746,7 @@ class DynamicWalletClient {
             if (storeRecoveredShares) {
                 await this.setClientKeySharesToStorage({
                     accountAddress,
-                    clientKeyShares: decryptedKeyShares,
-                    overwriteOrMerge: 'merge'
+                    clientKeyShares: decryptedKeyShares
                 });
                 await this.storage.setItem(this.storageKey, JSON.stringify(this.walletMap));
             }
@@ -5183,24 +5232,27 @@ class DynamicWalletClient {
         }
         return true;
     }
+    async fetchWalletBackupInfoFromServer(accountAddress) {
+        var _user_verifiedCredentials;
+        const dynamicRequestId = v4();
+        const user = await this.apiClient.getUser(dynamicRequestId);
+        const wallet = (_user_verifiedCredentials = user.verifiedCredentials) == null ? void 0 : _user_verifiedCredentials.find((vc)=>{
+            var _vc_address;
+            return ((_vc_address = vc.address) == null ? void 0 : _vc_address.toLowerCase()) === accountAddress.toLowerCase();
+        });
+        return getClientKeyShareBackupInfo({
+            walletProperties: wallet == null ? void 0 : wallet.walletProperties
+        });
+    }
     async getWalletClientKeyShareBackupInfo({ accountAddress }) {
         const dynamicRequestId = v4();
         try {
-            var _this_getWalletFromMap, _walletBackupInfo_backups_BackupLocation_DYNAMIC, _walletBackupInfo_backups, _user_verifiedCredentials;
-            // Return existing backup info if it exists
+            var _this_getWalletFromMap, _walletBackupInfo_backups_BackupLocation_DYNAMIC, _walletBackupInfo_backups;
             const walletBackupInfo = (_this_getWalletFromMap = this.getWalletFromMap(accountAddress)) == null ? void 0 : _this_getWalletFromMap.clientKeySharesBackupInfo;
             if (walletBackupInfo && ((_walletBackupInfo_backups = walletBackupInfo.backups) == null ? void 0 : (_walletBackupInfo_backups_BackupLocation_DYNAMIC = _walletBackupInfo_backups[BackupLocation.DYNAMIC]) == null ? void 0 : _walletBackupInfo_backups_BackupLocation_DYNAMIC.length) > 0) {
                 return walletBackupInfo;
             }
-            // Get backup info from server
-            const user = await this.apiClient.getUser(dynamicRequestId);
-            const wallet = (_user_verifiedCredentials = user.verifiedCredentials) == null ? void 0 : _user_verifiedCredentials.find((vc)=>{
-                var _vc_address;
-                return ((_vc_address = vc.address) == null ? void 0 : _vc_address.toLowerCase()) === accountAddress.toLowerCase();
-            });
-            return getClientKeyShareBackupInfo({
-                walletProperties: wallet == null ? void 0 : wallet.walletProperties
-            });
+            return this.fetchWalletBackupInfoFromServer(accountAddress);
         } catch (error) {
             logError({
                 message: 'Error in getWalletClientKeyShareBackupInfo',
@@ -5213,6 +5265,18 @@ class DynamicWalletClient {
             throw error;
         }
     }
+    // Bypasses the cache short-circuit in getWalletClientKeyShareBackupInfo. Required when
+    // freshness matters across tabs/contexts — walletMap is populated at wallet-load time and
+    // is not invalidated when another tab rotates shares.
+    async fetchFreshWalletBackupInfo({ accountAddress }) {
+        const freshBackupInfo = await this.fetchWalletBackupInfoFromServer(accountAddress);
+        if (this.getWalletFromMap(accountAddress)) {
+            this.updateWalletMap(accountAddress, {
+                clientKeySharesBackupInfo: freshBackupInfo
+            });
+        }
+        return freshBackupInfo;
+    }
     async getWallet({ accountAddress, walletOperation = WalletOperation.NO_OPERATION, shareCount = undefined, password = undefined, signedSessionId }) {
         const dynamicRequestId = v4();
         try {
@@ -5333,13 +5397,8 @@ class DynamicWalletClient {
                     signedSessionId,
                     shareCount
                 });
-                const existingKeyShares = await this.getClientKeySharesFromStorage({
-                    accountAddress
-                });
-                await this.setClientKeySharesToStorage({
-                    accountAddress,
-                    clientKeyShares: mergeUniqueKeyShares(existingKeyShares, decryptedKeyShares)
-                });
+                // recoverEncryptedBackupByWallet (storeRecoveredShares: true by default) has
+                // already written decryptedKeyShares to storage. No further write needed.
                 this.logger.debug('[DynamicWaasWalletClient] Recovered backup', {
                     decryptedKeyShares
                 });
@@ -5424,6 +5483,45 @@ class DynamicWalletClient {
         });
     }
     /**
+   * Fetches the encrypted-shares blob from the server and caches it in this.storage.
+   * Returns the serialized blob, or null if the wallet is unknown or the API returns
+   * no data. Does not decrypt — callers (e.g. unlockWallet, getWallet eager-load)
+   * own the decrypt step.
+   */ async fetchAndCacheEncryptedShares({ accountAddress, signedSessionId, mfaToken }) {
+        const walletData = this.getWalletFromMap(accountAddress);
+        if (!walletData) {
+            return null;
+        }
+        const { shares } = this.recoverStrategy({
+            clientKeyShareBackupInfo: walletData.clientKeySharesBackupInfo,
+            thresholdSignatureScheme: walletData.thresholdSignatureScheme,
+            walletOperation: WalletOperation.RECOVER
+        });
+        const externalKeyShareIds = shares[BackupLocation.DYNAMIC] || [];
+        this.logger.info('[unlockWallet] cache miss after getWallet, fetching encrypted shares from server', {
+            context: {
+                accountAddress,
+                walletId: walletData.walletId,
+                externalKeyShareIds
+            }
+        });
+        const data = await this.apiClient.recoverEncryptedBackupByWallet({
+            walletId: walletData.walletId,
+            externalKeyShareIds,
+            signedSessionId,
+            mfaToken,
+            requiresSignedSessionId: this.requiresSignedSessionId(),
+            userId: this.userId
+        });
+        if (!data) {
+            return null;
+        }
+        const serialized = JSON.stringify(data);
+        const encryptedStorageKey = `${normalizeAddress(accountAddress)}${ENCRYPTED_SHARES_STORAGE_SUFFIX}`;
+        await this.storage.setItem(encryptedStorageKey, serialized);
+        return serialized;
+    }
+    /**
    * Unlocks a password-encrypted wallet by decrypting cached encrypted shares.
    * This method should be called after getWalletRecoveryState returns LOCKED state.
    *
@@ -5431,7 +5529,7 @@ class DynamicWalletClient {
    * @param password - The password to decrypt the shares
    * @param signedSessionId - The signed session ID for authentication
    * @returns The unlocked wallet properties
-   */ async unlockWallet({ accountAddress, password, signedSessionId }) {
+   */ async unlockWallet({ accountAddress, password, signedSessionId, mfaToken }) {
         const dynamicRequestId = v4();
         try {
             await this.requireWalletFromMap(accountAddress, signedSessionId);
@@ -5451,6 +5549,18 @@ class DynamicWalletClient {
                 });
                 encryptedData = await this.storage.getItem(encryptedStorageKey);
             }
+            // getWallet short-circuits via checkWalletFields when client key shares are
+            // durable but the encrypted-shares cache in this.storage was evicted (e.g. RN
+            // secureStorage survives a WebKit content-process recycle while localStorage
+            // does not). Populate the cache directly so the single decrypt path below
+            // can proceed.
+            if (!encryptedData) {
+                encryptedData = await this.fetchAndCacheEncryptedShares({
+                    accountAddress,
+                    signedSessionId,
+                    mfaToken
+                });
+            }
             if (!encryptedData) {
                 throw new Error('No encrypted shares found for wallet');
             }
@@ -5464,7 +5574,17 @@ class DynamicWalletClient {
             const otherEncryptedWallets = Object.entries(this.walletMap).filter(([addr, w])=>addr !== normalizedAccountAddress && w.walletReadyState !== WalletReadyState.READY && isWalletPasswordEncrypted(w));
             const results = await Promise.allSettled(otherEncryptedWallets.map(async ([otherAddr])=>{
                 const otherEncryptedStorageKey = `${otherAddr}${ENCRYPTED_SHARES_STORAGE_SUFFIX}`;
-                const otherEncryptedData = await this.storage.getItem(otherEncryptedStorageKey);
+                let otherEncryptedData = await this.storage.getItem(otherEncryptedStorageKey);
+                // Same cache-eviction scenario as the main wallet above: on RN, the
+                // encrypted-shares blob can be gone while client shares survive in
+                // secureStorage. Re-fetch from the server before giving up.
+                if (!otherEncryptedData) {
+                    otherEncryptedData = await this.fetchAndCacheEncryptedShares({
+                        accountAddress: otherAddr,
+                        signedSessionId,
+                        mfaToken
+                    });
+                }
                 if (!otherEncryptedData) {
                     return;
                 }
@@ -5853,4 +5973,4 @@ DynamicWalletClient.rooms = {};
 DynamicWalletClient.roomsInitializing = {};
 DynamicWalletClient.roomsPersistChain = Promise.resolve();
 
-export { BACKUP_FILENAME, CLIENT_KEYSHARE_EXPORT_FILENAME_PREFIX, DynamicWalletClient, ENVIRONMENT_SETTINGS_STORAGE_KEY, ERROR_ACCOUNT_ADDRESS_REQUIRED, ERROR_CREATE_WALLET_ACCOUNT, ERROR_EXPORT_PRIVATE_KEY, ERROR_IMPORT_PRIVATE_KEY, ERROR_KEYGEN_FAILED, ERROR_PASSCODE_REQUIRED, ERROR_PASSWORD_MISMATCH, ERROR_PASSWORD_REQUIRED_FOR_ENCRYPTED_WALLET, ERROR_PUBLIC_KEY_MISMATCH, ERROR_REFRESH_NOT_SUPPORTED_FOR_TWO_OF_THREE, ERROR_SIGN_MESSAGE, ERROR_SIGN_TYPED_DATA, ERROR_VERIFY_MESSAGE_SIGNATURE, ERROR_VERIFY_TRANSACTION_SIGNATURE, HEAVY_QUEUE_OPERATIONS, RECOVER_QUEUE_OPERATIONS, ROOM_CACHE_COUNT, ROOM_EXPIRATION_TIME, SIGNED_SESSION_ID_MIN_VERSION, SIGNED_SESSION_ID_MIN_VERSION_BY_NAMESPACE, SIGN_QUEUE_OPERATIONS, STORAGE_KEY, WalletBusyError, WalletNotReadyError, cancelICloudAuth, createAddCloudProviderToExistingDelegationDistribution, createBackupData, createCloudProviderDistribution, createDelegationOnlyDistribution, createDelegationWithCloudProviderDistribution, createDynamicOnlyDistribution, deleteICloudBackup, downloadStringAsFile, extractPubkey, formatEvmMessage, formatMessage, getActiveCloudProviders, getBitcoinAddressTypeFromDerivationPath, getClientKeyShareBackupInfo, getClientKeyShareExportFileName, getGoogleOAuthAccountId, getICloudBackup, getMPCSignatureScheme, getMPCSigner, hasCloudProviderBackup, hasDelegatedBackup, hasEncryptedSharesCached, initializeCloudKit, isBrowser, isHeavyQueueOperation, isHexString, isICloudAuthenticated, isNonRetryableCeremonyError, isPublicKeyMismatchError, isRecoverQueueOperation, isSignQueueOperation, listICloudBackups, markCeremonyErrorNonRetryable, mergeUniqueKeyShares, readEnvironmentSettings, retryPromise, shouldReshareToSameBackups, timeoutPromise };
+export { BACKUP_FILENAME, CLIENT_KEYSHARE_EXPORT_FILENAME_PREFIX, DynamicWalletClient, ENVIRONMENT_SETTINGS_STORAGE_KEY, ERROR_ACCOUNT_ADDRESS_REQUIRED, ERROR_CREATE_WALLET_ACCOUNT, ERROR_EXPORT_PRIVATE_KEY, ERROR_IMPORT_PRIVATE_KEY, ERROR_KEYGEN_FAILED, ERROR_PASSCODE_REQUIRED, ERROR_PASSWORD_MISMATCH, ERROR_PASSWORD_REQUIRED_FOR_ENCRYPTED_WALLET, ERROR_PUBLIC_KEY_MISMATCH, ERROR_REFRESH_NOT_SUPPORTED_FOR_TWO_OF_THREE, ERROR_SIGN_MESSAGE, ERROR_SIGN_TYPED_DATA, ERROR_VERIFY_MESSAGE_SIGNATURE, ERROR_VERIFY_TRANSACTION_SIGNATURE, HEAVY_QUEUE_OPERATIONS, RECOVER_QUEUE_OPERATIONS, ROOM_CACHE_COUNT, ROOM_EXPIRATION_TIME, SIGNED_SESSION_ID_MIN_VERSION, SIGNED_SESSION_ID_MIN_VERSION_BY_NAMESPACE, SIGN_QUEUE_OPERATIONS, STORAGE_KEY, StaleLocalSharesError, WalletBusyError, WalletNotReadyError, cancelICloudAuth, createAddCloudProviderToExistingDelegationDistribution, createBackupData, createCloudProviderDistribution, createDelegationOnlyDistribution, createDelegationWithCloudProviderDistribution, createDynamicOnlyDistribution, deleteICloudBackup, downloadStringAsFile, extractPubkey, formatEvmMessage, formatMessage, getActiveCloudProviders, getBitcoinAddressTypeFromDerivationPath, getClientKeyShareBackupInfo, getClientKeyShareExportFileName, getGoogleOAuthAccountId, getICloudBackup, getMPCSignatureScheme, getMPCSigner, hasCloudProviderBackup, hasDelegatedBackup, hasEncryptedSharesCached, initializeCloudKit, isBrowser, isHeavyQueueOperation, isHexString, isICloudAuthenticated, isNonRetryableCeremonyError, isPublicKeyMismatchError, isRecoverQueueOperation, isSignQueueOperation, listICloudBackups, markCeremonyErrorNonRetryable, readEnvironmentSettings, retryPromise, shouldReshareToSameBackups, timeoutPromise };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dynamic-labs-wallet/browser",
-  "version": "0.0.339",
+  "version": "0.0.341",
   "license": "Licensed under the Dynamic Labs, Inc. Terms Of Service (https://www.dynamic.xyz/terms-conditions)",
   "type": "module",
   "dependencies": {
-    "@dynamic-labs-wallet/core": "0.0.339",
+    "@dynamic-labs-wallet/core": "0.0.341",
     "@dynamic-labs-wallet/forward-mpc-client": "0.9.0",
-    "@dynamic-labs-wallet/primitives": "0.0.339",
+    "@dynamic-labs-wallet/primitives": "0.0.341",
     "@dynamic-labs/sdk-api-core": "^0.0.964",
     "argon2id": "1.0.1",
     "axios": "1.15.2",

package/src/backup/errors.d.ts

@@ -0,0 +1,13 @@
+export declare class StaleLocalSharesError extends Error {
+    readonly accountAddress: string;
+    readonly localKeygenIds: string[];
+    readonly recordedKeygenIds: string[];
+    readonly localSharesRefreshed: boolean;
+    constructor(args: {
+        accountAddress: string;
+        localKeygenIds: string[];
+        recordedKeygenIds: string[];
+        localSharesRefreshed: boolean;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/src/backup/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/backup/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,SAAgB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzC,SAAgB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5C,SAAgB,oBAAoB,EAAE,OAAO,CAAC;gBAElC,IAAI,EAAE;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,oBAAoB,EAAE,OAAO,CAAC;KAC/B;CAYF"}

package/src/client.d.ts

@@ -297,6 +297,7 @@ export declare class DynamicWalletClient {
      */
     private getBitcoinConfigForChain;
     private internalRefreshWalletAccountShares;
+    private getKeygenIdForShare;
     getExportId({ chainName, clientKeyShare, bitcoinConfig, }: {
         chainName: string;
         clientKeyShare: ClientKeyShare;
@@ -420,20 +421,21 @@ export declare class DynamicWalletClient {
      * Uses secureStorage when available (mobile), otherwise falls back to localStorage (browser).
      */
     /**
-     * Resolves the final array of shares to persist by either replacing
-     * (overwrite) or merging with existing shares (merge), and emits a
-     * persistence-info log so we can audit storage operations from traces.
+     * Emits a persistence-info log so storage writes are auditable from traces.
      */
-    private resolveSharesToPersist;
+    private logSharePersistence;
     private setClientKeySharesToLocalStorage;
     /**
-     * Helper function to store client key shares in storage.
+     * Replaces the client key shares stored for `accountAddress` with `clientKeyShares`.
      * Uses secureStorage when available (mobile), otherwise falls back to localStorage (browser).
+     *
+     * A WaaS wallet holds exactly one client share per device (see share-distribution
+     * factories in types.ts), so writes are always a full replacement — there is no
+     * merge mode. Callers that need to clear local shares pass `clientKeyShares: []`.
      */
-    setClientKeySharesToStorage({ accountAddress, clientKeyShares, overwriteOrMerge, }: {
+    setClientKeySharesToStorage({ accountAddress, clientKeyShares, }: {
         accountAddress: string;
         clientKeyShares: ClientKeyShare[];
-        overwriteOrMerge?: 'overwrite' | 'merge';
     }): Promise<void>;
     /**
      * Ensures that client key shares exist for the given account address.
@@ -477,6 +479,7 @@ export declare class DynamicWalletClient {
             externalKeyShareId?: string;
         }[];
     }>;
+    private ensureLocalSharesAreFresh;
     /**
      * Central backup orchestrator that encrypts and stores wallet key shares.
      *
@@ -737,9 +740,11 @@ export declare class DynamicWalletClient {
         accountAddress: string;
         walletOperation?: WalletOperation;
     }): Promise<boolean>;
+    private fetchWalletBackupInfoFromServer;
     getWalletClientKeyShareBackupInfo({ accountAddress }: {
         accountAddress: string;
     }): Promise<KeyShareBackupInfo>;
+    private fetchFreshWalletBackupInfo;
     getWallet({ accountAddress, walletOperation, shareCount, password, signedSessionId, }: {
         accountAddress: string;
         walletOperation?: WalletOperation;
@@ -768,6 +773,13 @@ export declare class DynamicWalletClient {
         signedSessionId?: string;
         password?: string;
     }): Promise<WalletRecoveryState>;
+    /**
+     * Fetches the encrypted-shares blob from the server and caches it in this.storage.
+     * Returns the serialized blob, or null if the wallet is unknown or the API returns
+     * no data. Does not decrypt — callers (e.g. unlockWallet, getWallet eager-load)
+     * own the decrypt step.
+     */
+    private fetchAndCacheEncryptedShares;
     /**
      * Unlocks a password-encrypted wallet by decrypting cached encrypted shares.
      * This method should be called after getWalletRecoveryState returns LOCKED state.
@@ -777,10 +789,11 @@ export declare class DynamicWalletClient {
      * @param signedSessionId - The signed session ID for authentication
      * @returns The unlocked wallet properties
      */
-    unlockWallet({ accountAddress, password, signedSessionId, }: {
+    unlockWallet({ accountAddress, password, signedSessionId, mfaToken, }: {
         accountAddress: string;
         password: string;
         signedSessionId: string;
+        mfaToken?: string;
     }): Promise<WalletProperties>;
     /**
      * Decrypts cached encrypted key shares for a wallet and stores them locally.