@dynamic-labs-wallet/browser 1.0.43 → 1.0.44

package/index.cjs

@@ -1265,6 +1265,22 @@ const downloadStringAsFile = ({ filename, content, mimeType = 'application/json'
     }
     return false;
 };
+/**
+ * Checks for the server's stale-share preflight rejection (HTTP 409 sent as
+ * an SSE error event with `code: 'STALE_CLIENT_SHARES'`). The server compares
+ * the `shareSetId` the SDK sends on sign requests against the wallet's active
+ * share set and rejects BEFORE any room/ceremony work when they diverge
+ * (e.g. the shares were rotated by a reshare/refresh on another device).
+ * The SDK heals (re-syncs local shares from backup) and retries internally.
+ *
+ * The SSE event-stream layer copies the event's data fields onto the Error
+ * object (see createErrorFromEventData), so `code` is available here.
+ */ const isStaleClientSharesError = (error)=>{
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    return error.code === 'STALE_CLIENT_SHARES';
+};
 /**
  * Determines whether a reshare operation should reuse the wallet's existing backup locations.
  *
@@ -2565,6 +2581,15 @@ const KNOWN_SHARE_SET_TYPES = new Set([
     'delegated',
     'server'
 ]);
+/**
+ * keygenIds the server records for the wallet's Dynamic-backed-up client
+ * shares — the reference generation that local shares are compared against.
+ * Empty for first-time backups or legacy data without keygenIds.
+ */ const recordedDynamicKeygenIds = (backupInfo)=>{
+    var _backupInfo_backups;
+    var _backupInfo_backups_BackupLocation_DYNAMIC;
+    return ((_backupInfo_backups_BackupLocation_DYNAMIC = backupInfo == null ? void 0 : (_backupInfo_backups = backupInfo.backups) == null ? void 0 : _backupInfo_backups[core.BackupLocation.DYNAMIC]) != null ? _backupInfo_backups_BackupLocation_DYNAMIC : []).map((backup)=>backup.keygenId).filter((keygenId)=>typeof keygenId === 'string' && keygenId.length > 0);
+};
 class DynamicWalletClient {
     /**
    * Check if wallet has heavy operations in progress
@@ -3399,22 +3424,114 @@ class DynamicWalletClient {
         }
     }
     /**
-   * On public-key mismatch, restore local shares from backup and rethrow so
-   * the caller's next call (with refreshed shares) succeeds. Auto-retry was
-   * removed because in the iframe transport the error response is already
-   * posted to the host before any retry can resolve.
-   * Passthrough for non-mismatch errors.
-   */ async recoverKeySharesOnMismatch({ error, accountAddress, password, signedSessionId, walletOperation, mfaToken, traceContext, dynamicRequestId }) {
-        if (!isPublicKeyMismatchError(error)) {
-            throw error;
+   * Best-effort heal for stale local shares. Runs verifyAndRecoverStaleShare
+   * through the shared recovery queue: concurrent triggers join the in-flight
+   * recovery (WalletQueueManager dedup), and execution is deadlock-safe when
+   * called from inside a queued sign/heavy operation. Never throws — callers
+   * are already on a failing path and rethrow their original error.
+   */ async healStaleShares(params) {
+        const runCheck = ()=>WalletQueueManager.queueRecoverOperation(params.accountAddress, core.WalletOperation.RECOVER, ()=>this.verifyAndRecoverStaleShare(params));
+        try {
+            const result = await runCheck();
+            // The queue dedup returns the in-flight recovery's promise, dropping
+            // this caller's params. If that run skipped recovery but we carry a
+            // confirmed mismatch, re-run once with our params. (A run we started
+            // ourselves with confirmedMismatch=true always recovers, so this only
+            // fires after joining a weaker concurrent check.)
+            if (params.confirmedMismatch && (result == null ? void 0 : result.recovered) === false) {
+                await runCheck();
+            }
+        } catch (error) {
+            this.logger.error('[StaleShareCheck] share recovery failed', {
+                accountAddress: params.accountAddress,
+                dynamicRequestId: params.dynamicRequestId,
+                trigger: params.trigger,
+                error: error instanceof Error ? error.message : String(error)
+            });
         }
-        this.logger.info('[DynamicWaasWalletClient] Public key mismatch detected, recovering key shares from backup', _extends({
+    }
+    /**
+   * Ground-truth staleness check: refreshes the wallet from the API, compares
+   * local share keygenIds against the server's recorded Dynamic-backup
+   * keygenIds, and restores from backup when the local generation is stale
+   * (a reshare/refresh on another device/browser rotates the shares without
+   * this client noticing). No-ops when shares are fresh, so callers may run
+   * it on any ceremony failure regardless of the error message.
+   */ async verifyAndRecoverStaleShare({ accountAddress, chainName, password, signedSessionId, walletOperation, mfaToken, dynamicRequestId, traceContext, bitcoinConfig, trigger, confirmedMismatch }) {
+        this.logger.info('[StaleShareCheck] verifying local share generation against server', _extends({
             accountAddress,
-            walletOperation,
+            chainName,
+            trigger,
+            confirmedMismatch,
             dynamicRequestId
         }, this.getTraceContext(traceContext)));
-        // Refresh walletMap from API before recovery to ensure backup info is up-to-date.
+        // Refresh walletMap from the API: the cached entry may predate a rotation
+        // performed on another device, which would make this comparison a no-op.
+        // Full getWallets (not just backup info) so shareSetId etc. are also
+        // current for the caller's retry.
         await this.getWallets();
+        const wallet = this.getWalletFromMap(accountAddress);
+        const recordedKeygenIds = recordedDynamicKeygenIds(wallet == null ? void 0 : wallet.clientKeySharesBackupInfo);
+        let staleness;
+        let localKeygenIds = [];
+        if (recordedKeygenIds.length === 0) {
+            // First-time backup or legacy data (server didn't populate keygenId) —
+            // generation can't be compared. A confirmed mismatch still recovers
+            // below (legacy recovery behavior); an unclassified
+            // failure does not.
+            staleness = 'unverifiable';
+        } else {
+            try {
+                const localShares = await this.getClientKeySharesFromStorage({
+                    accountAddress
+                });
+                const comparison = await this.compareShareGenerations({
+                    accountAddress,
+                    chainName,
+                    localShares,
+                    recordedKeygenIds,
+                    bitcoinConfig
+                });
+                localKeygenIds = comparison.localKeygenIds;
+                staleness = comparison.fresh ? 'fresh' : 'stale';
+            } catch (error) {
+                // Unreadable/corrupted local share — treat as stale and recover.
+                this.logger.warn('[StaleShareCheck] could not derive keygenId from local shares — treating as stale', {
+                    accountAddress,
+                    trigger,
+                    dynamicRequestId,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+                staleness = 'stale';
+            }
+        }
+        // Stale generation always recovers. A confirmed mismatch also recovers
+        // when the comparison is inconclusive or even reports fresh (possible
+        // server-side inconsistency) — matching the legacy recovery behavior.
+        const shouldRecover = staleness === 'stale' || confirmedMismatch;
+        if (!shouldRecover) {
+            this.logger.info('[StaleShareCheck] no recovery needed', {
+                accountAddress,
+                trigger,
+                staleness,
+                localKeygenIds,
+                dynamicRequestId
+            });
+            return {
+                recovered: false,
+                localKeygenIds,
+                recordedKeygenIds
+            };
+        }
+        this.logger.warn('[StaleShareCheck] recovering current shares from backup', _extends({
+            accountAddress,
+            trigger,
+            confirmedMismatch,
+            staleness,
+            localKeygenIds,
+            recordedKeygenIds,
+            dynamicRequestId
+        }, this.getTraceContext(traceContext)));
         await this.internalRecoverEncryptedBackupByWallet({
             accountAddress,
             password,
@@ -3423,12 +3540,35 @@ class DynamicWalletClient {
             mfaToken,
             storeRecoveredShares: true
         });
-        this.logger.info('[DynamicWaasWalletClient] Key shares recovered; rethrowing original error for caller to retry', _extends({
+        this.logger.info('[StaleShareCheck] recovery completed — next operation will use the recovered shares', {
             accountAddress,
-            walletOperation,
+            trigger,
             dynamicRequestId
-        }, this.getTraceContext(traceContext)));
-        throw error;
+        });
+        return {
+            recovered: true,
+            localKeygenIds,
+            recordedKeygenIds
+        };
+    }
+    /**
+   * Set-compare local share keygenIds (MPC exportID) against the keygenIds
+   * the server recorded for the wallet's Dynamic backups. Shared by the
+   * stale-share heal (verifyAndRecoverStaleShare) and the backup preflight
+   * (ensureLocalSharesAreFresh).
+   */ async compareShareGenerations({ accountAddress, chainName, localShares, recordedKeygenIds, bitcoinConfig }) {
+        const mpcSigner = getMPCSigner({
+            chainName,
+            baseRelayUrl: this.baseMPCRelayApiUrl,
+            bitcoinConfig: bitcoinConfig != null ? bitcoinConfig : this.getBitcoinConfigForChain(chainName, accountAddress)
+        });
+        const localKeygenIds = await Promise.all(localShares.map((share)=>this.getKeygenIdForShare(mpcSigner, share)));
+        const recordedSet = new Set(recordedKeygenIds);
+        const fresh = localKeygenIds.length === recordedSet.size && localKeygenIds.every((id)=>recordedSet.has(id));
+        return {
+            fresh,
+            localKeygenIds
+        };
     }
     //todo: need to modify with imported flag
     async sign({ accountAddress, message, chainName, password = undefined, isFormatted = false, signedSessionId, mfaToken, elevatedAccessToken, context, onError, traceContext, bitcoinConfig }) {
@@ -3447,7 +3587,7 @@ class DynamicWalletClient {
                 bitcoinConfig
             }));
     }
-    async internalSign({ accountAddress, message, chainName, password = undefined, isFormatted = false, signedSessionId, mfaToken, elevatedAccessToken, context, onError, traceContext, bitcoinConfig }) {
+    async internalSign({ accountAddress, message, chainName, password = undefined, isFormatted = false, signedSessionId, mfaToken, elevatedAccessToken, context, onError, traceContext, bitcoinConfig, staleShareRetry = false }) {
         const dynamicRequestId = uuid.v4();
         try {
             await this.verifyPassword({
@@ -3490,6 +3630,17 @@ class DynamicWalletClient {
             // (sseErrorPromise would never reach Promise.race in that path)
             // eslint-disable-next-line @typescript-eslint/no-empty-function
             sseErrorPromise.catch(()=>{});
+            // Dedicated channel for the server's 409 stale-shares preflight: it must
+            // abort the ceremony into the heal-and-retry path WITHOUT settling the
+            // host request (so the transparent retry's outcome is what the host
+            // sees). Needed as a race arm because in the cached-room flow
+            // serverSignPromise is never awaited, so its rejection alone would float.
+            let rejectOnStaleShares;
+            const staleSharesPromise = new Promise((_, reject)=>{
+                rejectOnStaleShares = reject;
+            });
+            // eslint-disable-next-line @typescript-eslint/no-empty-function
+            staleSharesPromise.catch(()=>{});
             // Perform the server sign
             const serverSignPromise = this.serverSign({
                 walletId: wallet.walletId,
@@ -3501,6 +3652,13 @@ class DynamicWalletClient {
                 roomId,
                 context,
                 onError: (error)=>{
+                    // The server's 409 stale-shares preflight rejection is healed and
+                    // retried internally (see the catch below) — don't settle the host
+                    // request or poison the SSE race with it.
+                    if (isStaleClientSharesError(error)) {
+                        rejectOnStaleShares(error);
+                        return;
+                    }
                     onError == null ? void 0 : onError(error);
                     rejectOnSSEError(error);
                 },
@@ -3508,6 +3666,11 @@ class DynamicWalletClient {
                 traceContext,
                 bitcoinConfig
             });
+            // In the cached-room flow the promise below is never awaited — attach a
+            // handler so a rejection (e.g. the 409 preflight, which also arrives via
+            // staleSharesPromise above) doesn't surface as an unhandled rejection.
+            // eslint-disable-next-line @typescript-eslint/no-empty-function
+            serverSignPromise.catch(()=>{});
             // Only await if roomId is not provided
             roomId = roomId != null ? roomId : (await serverSignPromise).roomId;
             this.logger.info('[DynamicWaasWalletClient] Server sign completed', _extends({
@@ -3520,6 +3683,9 @@ class DynamicWalletClient {
                 operation: 'serverSign'
             }, this.getTraceContext(traceContext)));
             let signature;
+            // Set by the clientSign rejection handler below; read in the catch to
+            // detect a client-side mismatch masked by a generic SSE race winner.
+            let clientSignMismatchError;
             try {
                 // Race clientSign against SSE errors so that server-side failures
                 // (e.g. policy violations) immediately reject instead of hanging
@@ -3547,6 +3713,12 @@ class DynamicWalletClient {
                             roomId: undefined,
                             context,
                             onError: (error)=>{
+                                // See the initial serverSign onError: 409 stale-shares is
+                                // healed + retried internally, never surfaced to the host.
+                                if (isStaleClientSharesError(error)) {
+                                    rejectOnStaleShares(error);
+                                    return;
+                                }
                                 onError == null ? void 0 : onError(error);
                                 rejectOnSSEError(error);
                             },
@@ -3557,26 +3729,63 @@ class DynamicWalletClient {
                         return freshRoomId;
                     }
                 });
-                // Prevent unhandled rejection from the losing promise in the race:
-                // if sseErrorPromise wins, clientSign keeps running and will eventually
-                // reject (MPC timeout); if clientSign wins, sseErrorPromise may never settle.
-                // eslint-disable-next-line @typescript-eslint/no-empty-function
-                clientSignPromise.catch(()=>{});
+                // Handle the losing race promise (prevents an unhandled rejection) and
+                // capture a client-side ERROR_PUBLIC_KEY_MISMATCH here — the only place
+                // a stale-local-share failure surfaces, since the server's generic SSE
+                // error wins the race and masks it. Schedule recovery regardless of
+                // which promise wins or when this rejection settles.
+                clientSignPromise.catch((error)=>{
+                    if (isPublicKeyMismatchError(error)) {
+                        clientSignMismatchError = error;
+                        this.logger.warn('[StaleShareCheck] clientSign rejected with public-key mismatch — scheduling share recovery', _extends({
+                            accountAddress,
+                            chainName,
+                            dynamicRequestId
+                        }, this.getTraceContext(traceContext)));
+                        void this.healStaleShares({
+                            accountAddress,
+                            chainName,
+                            password,
+                            signedSessionId,
+                            walletOperation: core.WalletOperation.SIGN_MESSAGE,
+                            mfaToken,
+                            dynamicRequestId,
+                            traceContext,
+                            bitcoinConfig,
+                            trigger: 'clientSign rejection',
+                            confirmedMismatch: true
+                        });
+                    }
+                });
                 signature = await Promise.race([
                     clientSignPromise,
-                    sseErrorPromise
+                    sseErrorPromise,
+                    staleSharesPromise
                 ]);
             } catch (signError) {
-                // Restore shares from backup on mismatch; passthrough otherwise.
-                await this.recoverKeySharesOnMismatch({
-                    error: signError,
+                // The 409 stale-shares preflight is handled exclusively by the outer
+                // catch (heal + transparent retry) — skip the generic heal here so the
+                // ground-truth check runs once, right before the retry decision.
+                if (isStaleClientSharesError(signError)) {
+                    throw signError;
+                }
+                // Heal before rethrowing so the caller's retry succeeds. Run the
+                // ground-truth check whatever the raced error was: a generic SSE
+                // error frequently wins the race while the client-side mismatch
+                // settles later, so error-string inspection alone is timing-dependent.
+                // The check no-ops when shares are fresh.
+                await this.healStaleShares({
                     accountAddress,
+                    chainName,
                     password,
                     signedSessionId,
                     walletOperation: core.WalletOperation.SIGN_MESSAGE,
                     mfaToken,
+                    dynamicRequestId,
                     traceContext,
-                    dynamicRequestId
+                    bitcoinConfig,
+                    trigger: 'sign failure',
+                    confirmedMismatch: isPublicKeyMismatchError(signError) || clientSignMismatchError !== undefined
                 });
                 throw signError;
             }
@@ -3592,6 +3801,51 @@ class DynamicWalletClient {
             }, this.getTraceContext(traceContext)));
             return signature;
         } catch (error) {
+            // Server-side stale-share preflight (409 STALE_CLIENT_SHARES): the
+            // request was rejected BEFORE any room/ceremony work, and the onError
+            // wrappers above kept it away from the host — so the host request is
+            // still pending. Heal the local shares from backup and transparently
+            // retry once; the host only ever sees the (successful) outcome.
+            if (!staleShareRetry && isStaleClientSharesError(error)) {
+                // Heal first (re-sync local shares + walletMap from the server), then
+                // retry regardless of whether shares were replaced: even a "fresh"
+                // verdict means the heal's getWallets() refreshed the stale
+                // walletMap.shareSetId the server rejected. The retry is guarded to
+                // run at most once; if it 409s again the error surfaces normally.
+                await this.healStaleShares({
+                    accountAddress,
+                    chainName,
+                    password,
+                    signedSessionId,
+                    walletOperation: core.WalletOperation.SIGN_MESSAGE,
+                    mfaToken,
+                    dynamicRequestId,
+                    traceContext,
+                    bitcoinConfig,
+                    trigger: 'server 409 stale-shares preflight',
+                    confirmedMismatch: true
+                });
+                this.logger.info('[StaleShareCheck] retrying sign transparently after 409 stale-shares preflight', _extends({
+                    accountAddress,
+                    chainName,
+                    dynamicRequestId
+                }, this.getTraceContext(traceContext)));
+                return await this.internalSign({
+                    accountAddress,
+                    message,
+                    chainName,
+                    password,
+                    isFormatted,
+                    signedSessionId,
+                    mfaToken,
+                    elevatedAccessToken,
+                    context,
+                    onError,
+                    traceContext,
+                    bitcoinConfig,
+                    staleShareRetry: true
+                });
+            }
             logError({
                 message: 'Error in sign',
                 error: error,
@@ -3605,12 +3859,13 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async refreshWalletAccountShares({ accountAddress, chainName, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, traceContext }) {
+    async refreshWalletAccountShares({ accountAddress, chainName, password = undefined, signedSessionId, sessionPublicKey, mfaToken, elevatedAccessToken, traceContext }) {
         return WalletQueueManager.queueHeavyOperation(accountAddress, core.WalletOperation.REFRESH, ()=>this.internalRefreshWalletAccountShares({
                 accountAddress,
                 chainName,
                 password,
                 signedSessionId,
+                sessionPublicKey,
                 mfaToken,
                 elevatedAccessToken,
                 traceContext
@@ -3677,7 +3932,7 @@ class DynamicWalletClient {
             addressType: addressType
         } : undefined;
     }
-    async internalRefreshWalletAccountShares({ accountAddress, chainName, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, traceContext }) {
+    async internalRefreshWalletAccountShares({ accountAddress, chainName, password = undefined, signedSessionId, sessionPublicKey, mfaToken, elevatedAccessToken, traceContext, staleShareRetry = false }) {
         const dynamicRequestId = uuid.v4();
         try {
             this.assertPasswordRequired(password);
@@ -3769,16 +4024,19 @@ class DynamicWalletClient {
             try {
                 refreshResults = await Promise.all(clientKeyShares.map((clientKeyShare)=>mpcSigner.refresh(roomId, clientKeyShare)));
             } catch (refreshError) {
-                // Restore shares from backup on mismatch; passthrough otherwise.
-                await this.recoverKeySharesOnMismatch({
-                    error: refreshError,
+                // Heal stale local shares before rethrowing so a retry succeeds.
+                await this.healStaleShares({
                     accountAddress,
+                    chainName,
                     password,
                     signedSessionId,
                     walletOperation: core.WalletOperation.REFRESH,
                     mfaToken,
+                    dynamicRequestId,
                     traceContext,
-                    dynamicRequestId
+                    bitcoinConfig,
+                    trigger: 'refresh failure',
+                    confirmedMismatch: isPublicKeyMismatchError(refreshError)
                 });
                 throw refreshError;
             }
@@ -3804,7 +4062,8 @@ class DynamicWalletClient {
                         accountAddress,
                         clientKeyShares: refreshResults,
                         password: password != null ? password : this.environmentId,
-                        signedSessionId
+                        signedSessionId,
+                        sessionPublicKey
                     })
             });
             await this.setClientKeySharesToStorage({
@@ -3830,6 +4089,42 @@ class DynamicWalletClient {
                 });
                 throw error;
             }
+            // Server-side stale-share preflight (409 STALE_CLIENT_SHARES): rejected
+            // BEFORE any room/ceremony work, so nothing was rotated. Heal the local
+            // shares from backup and transparently retry once — even a "fresh" heal
+            // verdict matters, because its getWallets() refreshed the stale
+            // walletMap.shareSetId the server rejected.
+            if (!staleShareRetry && isStaleClientSharesError(error)) {
+                await this.healStaleShares({
+                    accountAddress,
+                    chainName,
+                    password,
+                    signedSessionId,
+                    walletOperation: core.WalletOperation.REFRESH,
+                    mfaToken,
+                    dynamicRequestId,
+                    traceContext,
+                    bitcoinConfig: this.getBitcoinConfigForChain(chainName, accountAddress),
+                    trigger: 'server 409 stale-shares preflight (refresh)',
+                    confirmedMismatch: true
+                });
+                this.logger.info('[StaleShareCheck] retrying refresh transparently after 409 stale-shares preflight', _extends({
+                    accountAddress,
+                    chainName,
+                    dynamicRequestId
+                }, this.getTraceContext(traceContext)));
+                return await this.internalRefreshWalletAccountShares({
+                    accountAddress,
+                    chainName,
+                    password,
+                    signedSessionId,
+                    sessionPublicKey,
+                    mfaToken,
+                    elevatedAccessToken,
+                    traceContext,
+                    staleShareRetry: true
+                });
+            }
             logError({
                 message: 'Error in refreshWalletAccountShares',
                 error: error,
@@ -3921,7 +4216,7 @@ class DynamicWalletClient {
             existingClientKeyShares
         };
     }
-    async reshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, cloudProviders = [], delegateToProjectEnvironment = false, mfaToken, elevatedAccessToken, revokeDelegation = false, googleDriveAccessToken, googleDriveTokenSource }) {
+    async reshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, sessionPublicKey, cloudProviders = [], delegateToProjectEnvironment = false, mfaToken, elevatedAccessToken, revokeDelegation = false, googleDriveAccessToken, googleDriveTokenSource }) {
         return WalletQueueManager.queueHeavyOperation(accountAddress, core.WalletOperation.RESHARE, ()=>this.internalReshare({
                 chainName,
                 accountAddress,
@@ -3929,6 +4224,7 @@ class DynamicWalletClient {
                 newThresholdSignatureScheme,
                 password,
                 signedSessionId,
+                sessionPublicKey,
                 cloudProviders,
                 delegateToProjectEnvironment,
                 mfaToken,
@@ -4413,7 +4709,7 @@ class DynamicWalletClient {
             clientKeySharesBackupInfo: updatedBackupInfo
         } : {}));
     }
-    async internalReshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, cloudProviders = [], delegateToProjectEnvironment = false, mfaToken, elevatedAccessToken, revokeDelegation = false, googleDriveAccessToken, googleDriveTokenSource }) {
+    async internalReshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, sessionPublicKey, cloudProviders = [], delegateToProjectEnvironment = false, mfaToken, elevatedAccessToken, revokeDelegation = false, googleDriveAccessToken, googleDriveTokenSource, staleShareRetry = false }) {
         const dynamicRequestId = uuid.v4();
         // Password validation - wrapped in try-catch for consistent error handling
         // This path should NOT wipe key shares on failure (shares remain valid)
@@ -4625,15 +4921,18 @@ class DynamicWalletClient {
                 existingReshareResults = existingSettled.map((r)=>r.value);
                 newReshareResults = newSettled.map((r)=>r.value);
             } catch (reshareError) {
-                // Restore shares from backup on mismatch; passthrough otherwise.
-                await this.recoverKeySharesOnMismatch({
-                    error: reshareError,
+                // Heal stale local shares before rethrowing so a retry succeeds.
+                await this.healStaleShares({
                     accountAddress,
+                    chainName,
                     password,
                     signedSessionId,
                     walletOperation: core.WalletOperation.RESHARE,
                     mfaToken,
-                    dynamicRequestId
+                    dynamicRequestId,
+                    bitcoinConfig,
+                    trigger: 'reshare failure',
+                    confirmedMismatch: isPublicKeyMismatchError(reshareError)
                 });
                 throw reshareError;
             }
@@ -4668,6 +4967,7 @@ class DynamicWalletClient {
                         accountAddress,
                         password,
                         signedSessionId,
+                        sessionPublicKey,
                         distribution,
                         googleDriveAccessToken,
                         googleDriveTokenSource
@@ -4705,6 +5005,47 @@ class DynamicWalletClient {
                 }
             });
         } catch (error) {
+            // Server-side stale-share preflight (409 STALE_CLIENT_SHARES): rejected
+            // BEFORE any room/ceremony work, so local shares are intact (nothing to
+            // wipe). Heal from backup and transparently retry once — even a "fresh"
+            // heal verdict matters, because its getWallets() refreshed the stale
+            // walletMap.shareSetId the server rejected.
+            if (!staleShareRetry && isStaleClientSharesError(error)) {
+                await this.healStaleShares({
+                    accountAddress,
+                    chainName,
+                    password,
+                    signedSessionId,
+                    walletOperation: core.WalletOperation.RESHARE,
+                    mfaToken,
+                    dynamicRequestId,
+                    bitcoinConfig: this.getBitcoinConfigForChain(chainName, accountAddress),
+                    trigger: 'server 409 stale-shares preflight (reshare)',
+                    confirmedMismatch: true
+                });
+                this.logger.info('[StaleShareCheck] retrying reshare transparently after 409 stale-shares preflight', {
+                    accountAddress,
+                    chainName,
+                    dynamicRequestId
+                });
+                return await this.internalReshare({
+                    chainName,
+                    accountAddress,
+                    oldThresholdSignatureScheme,
+                    newThresholdSignatureScheme,
+                    password,
+                    signedSessionId,
+                    sessionPublicKey,
+                    cloudProviders,
+                    delegateToProjectEnvironment,
+                    mfaToken,
+                    elevatedAccessToken,
+                    revokeDelegation,
+                    googleDriveAccessToken,
+                    googleDriveTokenSource,
+                    staleShareRetry: true
+                });
+            }
             logError({
                 message: 'Error in reshare, resetting wallet to previous state',
                 error: error,
@@ -4719,9 +5060,12 @@ class DynamicWalletClient {
                     dynamicRequestId
                 }
             });
-            // Skip the wipe on mismatch — recoverKeySharesOnMismatch just restored
-            // these shares from backup, undoing that would break the caller's retry.
-            if (!isPublicKeyMismatchError(error)) {
+            // Skip the wipe on mismatch — healStaleShares just restored these
+            // shares from backup, undoing that would break the caller's retry.
+            // Same for a 409 stale-shares preflight (only reachable here on the
+            // retried attempt): the request was rejected before any ceremony, so
+            // local shares are consistent — wiping would strand the user.
+            if (!isPublicKeyMismatchError(error) && !isStaleClientSharesError(error)) {
                 this.updateWalletMap(accountAddress, {
                     thresholdSignatureScheme: oldThresholdSignatureScheme
                 });
@@ -4733,7 +5077,7 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async performDelegationOperation({ accountAddress, password, signedSessionId, mfaToken, newThresholdSignatureScheme, revokeDelegation = false, useShareSetReshare = false, operationName }) {
+    async performDelegationOperation({ accountAddress, password, signedSessionId, sessionPublicKey, mfaToken, newThresholdSignatureScheme, revokeDelegation = false, useShareSetReshare = false, operationName }) {
         try {
             const delegateToProjectEnvironment = this.featureFlags && this.featureFlags[core.FEATURE_FLAGS.ENABLE_DELEGATED_KEY_SHARES_FLAG] === true;
             if (!delegateToProjectEnvironment) {
@@ -4762,6 +5106,7 @@ class DynamicWalletClient {
                 newThresholdSignatureScheme,
                 password,
                 signedSessionId,
+                sessionPublicKey,
                 cloudProviders: activeProviders,
                 // Server soft-deletes the wallet API key on revoke; a delegated
                 // distribution would 400 on the follow-up delivery POST.
@@ -4780,7 +5125,7 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async delegateKeyShares({ accountAddress, password = undefined, signedSessionId, mfaToken }) {
+    async delegateKeyShares({ accountAddress, password = undefined, signedSessionId, sessionPublicKey, mfaToken }) {
         var _this_featureFlags;
         const useShareSetReshare = ((_this_featureFlags = this.featureFlags) == null ? void 0 : _this_featureFlags[core.FEATURE_FLAGS.ENABLE_SHARE_SET_RESHARE]) === true;
         if (useShareSetReshare) {
@@ -4805,6 +5150,7 @@ class DynamicWalletClient {
             accountAddress,
             password,
             signedSessionId,
+            sessionPublicKey,
             mfaToken,
             // FF on: reshare to 2/2 — the new delegated share set is always 2/2
             // (server + delegated webhook). getReshareConfig now has a 2/2 → 2/2
@@ -4819,7 +5165,7 @@ class DynamicWalletClient {
         const delegatedKeyShares = backupInfo.backups[core.BackupLocation.DELEGATED] || [];
         return delegatedKeyShares;
     }
-    async revokeDelegation({ accountAddress, password = undefined, signedSessionId, mfaToken }) {
+    async revokeDelegation({ accountAddress, password = undefined, signedSessionId, sessionPublicKey, mfaToken }) {
         var _this_featureFlags;
         const useShareSetReshare = ((_this_featureFlags = this.featureFlags) == null ? void 0 : _this_featureFlags[core.FEATURE_FLAGS.ENABLE_SHARE_SET_RESHARE]) === true;
         if (useShareSetReshare) {
@@ -4865,6 +5211,7 @@ class DynamicWalletClient {
             accountAddress,
             password,
             signedSessionId,
+            sessionPublicKey,
             mfaToken,
             newThresholdSignatureScheme: core.ThresholdSignatureScheme.TWO_OF_TWO,
             revokeDelegation: true,
@@ -4881,6 +5228,22 @@ class DynamicWalletClient {
         return new web.BIP340KeygenResult(extractedPubkey, secretShare);
     }
     async exportKey({ accountAddress, chainName, bitcoinConfig, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, traceContext }) {
+        // Public entry point delegates to the private implementation. Keeping the
+        // `staleShareRetry` flag off the public signature mirrors sign/refresh/
+        // reshare and ensures the transparent 409 retry can't be suppressed by
+        // external callers or intercepted by subclass overrides.
+        return this.internalExportKey({
+            accountAddress,
+            chainName,
+            bitcoinConfig,
+            password,
+            signedSessionId,
+            mfaToken,
+            elevatedAccessToken,
+            traceContext
+        });
+    }
+    async internalExportKey({ accountAddress, chainName, bitcoinConfig, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, traceContext, staleShareRetry = false }) {
         const dynamicRequestId = uuid.v4();
         try {
             const wallet = await this.getWallet({
@@ -4925,10 +5288,51 @@ class DynamicWalletClient {
                 roomId: data.roomId
             }, this.getTraceContext(traceContext)));
             const derivedPrivateKey = await this.derivePrivateKeyFromExport(mpcSigner, keyExportRaw, wallet);
+            // derivePrivateKeyFromExport returns undefined for unsupported signer
+            // types; fail loudly rather than returning undefined as a string.
+            if (derivedPrivateKey === undefined) {
+                throw new Error(`Private key export is not supported for chain ${chainName}`);
+            }
             return {
                 derivedPrivateKey
             };
         } catch (error) {
+            // Server-side stale-share preflight (409 STALE_CLIENT_SHARES): rejected
+            // BEFORE any room/ceremony work. Heal the local shares from backup and
+            // transparently retry once — even a "fresh" heal verdict matters,
+            // because its getWallets() refreshed the stale walletMap.shareSetId the
+            // server rejected.
+            if (!staleShareRetry && isStaleClientSharesError(error)) {
+                await this.healStaleShares({
+                    accountAddress,
+                    chainName,
+                    password,
+                    signedSessionId,
+                    walletOperation: core.WalletOperation.EXPORT_PRIVATE_KEY,
+                    mfaToken,
+                    dynamicRequestId,
+                    traceContext,
+                    bitcoinConfig,
+                    trigger: 'server 409 stale-shares preflight (export)',
+                    confirmedMismatch: true
+                });
+                this.logger.info('[StaleShareCheck] retrying export transparently after 409 stale-shares preflight', _extends({
+                    accountAddress,
+                    chainName,
+                    dynamicRequestId
+                }, this.getTraceContext(traceContext)));
+                return await this.internalExportKey({
+                    accountAddress,
+                    chainName,
+                    bitcoinConfig,
+                    password,
+                    signedSessionId,
+                    mfaToken,
+                    elevatedAccessToken,
+                    traceContext,
+                    staleShareRetry: true
+                });
+            }
             logError({
                 message: 'Error in exportKey',
                 error: error,
@@ -4938,6 +5342,22 @@ class DynamicWalletClient {
                     dynamicRequestId
                 }, this.getTraceContext(traceContext))
             });
+            // Heal stale local shares before rethrowing so a retry succeeds —
+            // export reconstructs from the local share, so a generation rotated on
+            // another device fails here too.
+            await this.healStaleShares({
+                accountAddress,
+                chainName,
+                password,
+                signedSessionId,
+                walletOperation: core.WalletOperation.EXPORT_PRIVATE_KEY,
+                mfaToken,
+                dynamicRequestId,
+                traceContext,
+                bitcoinConfig,
+                trigger: 'export failure',
+                confirmedMismatch: isPublicKeyMismatchError(error)
+            });
             throw error;
         }
     }
@@ -5307,6 +5727,14 @@ class DynamicWalletClient {
    * Auto-recovery logic has been removed in favor of the queue pattern.
    * Callers should handle recovery explicitly if needed.
    */ async ensureClientShare(accountAddress) {
+        var _WalletQueueManager_getPendingRecoveryPromise;
+        // A recovery may be in flight (e.g. a stale-share heal scheduled when a
+        // previous sign hit a public-key mismatch). Wait for it so this operation
+        // reads the recovered shares instead of the superseded ones. Recovery
+        // failures are logged where they happen; this operation should proceed
+        // with whatever shares exist rather than fail on the recovery.
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        await ((_WalletQueueManager_getPendingRecoveryPromise = WalletQueueManager.getPendingRecoveryPromise(accountAddress)) == null ? void 0 : _WalletQueueManager_getPendingRecoveryPromise.catch(()=>{}));
         const shares = await this.getClientKeySharesFromStorage({
             accountAddress
         });
@@ -5315,13 +5743,14 @@ class DynamicWalletClient {
         }
         return shares;
     }
-    async backupToDynamicBackend({ walletId, clientShares, password, signedSessionId, dynamicRequestId, chainName, bitcoinConfig, isPasswordEncrypted, accountAddress, preEncryptedShares, passwordUpdateBatchId, encryptionVersion = DEFAULT_ENCRYPTION_VERSION }) {
+    async backupToDynamicBackend({ walletId, clientShares, password, signedSessionId, sessionPublicKey, dynamicRequestId, chainName, bitcoinConfig, isPasswordEncrypted, accountAddress, preEncryptedShares, passwordUpdateBatchId, encryptionVersion = DEFAULT_ENCRYPTION_VERSION }) {
         var _this_getWalletFromMap;
         const encryptedDynamicShares = preEncryptedShares != null ? preEncryptedShares : await Promise.all(clientShares.map((keyShare)=>this.encryptKeyShare({
                 keyShare,
                 password,
                 version: encryptionVersion
             })));
+        const resolvedSessionPublicKey = sessionPublicKey != null ? sessionPublicKey : await (this.getSessionPublicKeyCallback == null ? void 0 : this.getSessionPublicKeyCallback.call(this));
         const data = await this.apiClient.storeEncryptedBackupByWallet({
             walletId,
             shareSetId: (_this_getWalletFromMap = this.getWalletFromMap(accountAddress)) == null ? void 0 : _this_getWalletFromMap.shareSetId,
@@ -5329,6 +5758,7 @@ class DynamicWalletClient {
             passwordEncrypted: isPasswordEncrypted,
             encryptionVersion,
             signedSessionId,
+            sessionPublicKey: resolvedSessionPublicKey,
             requiresSignedSessionId: this.requiresSignedSessionId(),
             dynamicRequestId
         });
@@ -5477,7 +5907,7 @@ class DynamicWalletClient {
         }
         return location;
     }
-    async backupSharesWithDistribution({ accountAddress, password, signedSessionId, distribution, preserveDelegatedLocation = false, passwordUpdateBatchId, googleDriveAccessToken, googleDriveTokenSource, businessAccountId, encryptionVersion }) {
+    async backupSharesWithDistribution({ accountAddress, password, signedSessionId, sessionPublicKey, distribution, preserveDelegatedLocation = false, passwordUpdateBatchId, googleDriveAccessToken, googleDriveTokenSource, businessAccountId, encryptionVersion }) {
         const dynamicRequestId = uuid.v4();
         // Get wallet data early for logging context (also used in catch block)
         const walletData = this.getWalletFromMap(accountAddress);
@@ -5556,6 +5986,7 @@ class DynamicWalletClient {
                         clientShares: distribution.clientShares,
                         password,
                         signedSessionId: resolvedSignedSessionId,
+                        sessionPublicKey,
                         dynamicRequestId,
                         chainName: walletData.chainName,
                         bitcoinConfig,
@@ -5752,29 +6183,23 @@ class DynamicWalletClient {
     // 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 = await this.fetchFreshWalletBackupInfo({
+            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[core.BackupLocation.DYNAMIC]) != null ? _freshBackupInfo_backups_BackupLocation_DYNAMIC : []).map((entry)=>entry.keygenId).filter((id)=>typeof id === 'string' && id.length > 0);
+        const recordedKeygenIds = recordedDynamicKeygenIds(freshBackupInfo);
         // 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;
+        const { fresh, localKeygenIds } = await this.compareShareGenerations({
+            accountAddress,
+            chainName,
+            localShares,
+            recordedKeygenIds
+        });
+        if (fresh) return;
         this.logger.warn('[storeEncryptedBackupByWallet] Stale local shares detected; refreshing local storage', {
             accountAddress,
             walletId: walletData.walletId,
@@ -5801,7 +6226,7 @@ class DynamicWalletClient {
             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.
+                // getWallets() refresh that verifyAndRecoverStaleShare performs for its own callers.
                 await this.internalRecoverEncryptedBackupByWallet({
                     accountAddress,
                     password: recoveryPassword,
@@ -5859,7 +6284,7 @@ class DynamicWalletClient {
    * @param params.signedSessionId - Optional signed session ID for authentication
    * @param params.backupToGoogleDrive - Whether to backup to Google Drive (defaults to false)
    * @returns Promise with backup metadata including share locations and IDs
-   */ async storeEncryptedBackupByWallet({ accountAddress, clientKeyShares = undefined, password = undefined, signedSessionId, cloudProviders = [], delegatedKeyshare = undefined, passwordUpdateBatchId, googleDriveAccessToken, googleDriveTokenSource, businessAccountId, encryptionVersion }) {
+   */ async storeEncryptedBackupByWallet({ accountAddress, clientKeyShares = undefined, password = undefined, signedSessionId, sessionPublicKey, cloudProviders = [], delegatedKeyshare = undefined, passwordUpdateBatchId, googleDriveAccessToken, googleDriveTokenSource, businessAccountId, encryptionVersion }) {
         var _backupData_locationsWithKeyShares, _backupData_locationsWithKeyShares1;
         const hasProvidedShares = clientKeyShares !== undefined;
         const keySharesToBackup = clientKeyShares != null ? clientKeyShares : await this.getClientKeySharesFromStorage({
@@ -5929,6 +6354,7 @@ class DynamicWalletClient {
             accountAddress,
             password,
             signedSessionId,
+            sessionPublicKey,
             distribution,
             preserveDelegatedLocation,
             passwordUpdateBatchId,
@@ -6001,7 +6427,7 @@ class DynamicWalletClient {
             errorContext
         } : {}));
     }
-    async updatePassword({ accountAddress, existingPassword, newPassword, signedSessionId, passwordUpdateBatchId }) {
+    async updatePassword({ accountAddress, existingPassword, newPassword, signedSessionId, sessionPublicKey, passwordUpdateBatchId }) {
         const dynamicRequestId = uuid.v4();
         try {
             const wallet = this.getWalletFromMap(accountAddress);
@@ -6021,6 +6447,7 @@ class DynamicWalletClient {
                 accountAddress,
                 password: newPassword,
                 signedSessionId,
+                sessionPublicKey,
                 passwordUpdateBatchId
             });
             this.logPasswordOperationSuccess('updatePassword', {
@@ -6050,7 +6477,7 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async setPassword({ accountAddress, newPassword, signedSessionId, passwordUpdateBatchId }) {
+    async setPassword({ accountAddress, newPassword, signedSessionId, sessionPublicKey, passwordUpdateBatchId }) {
         const dynamicRequestId = uuid.v4();
         try {
             const wallet = this.getWalletFromMap(accountAddress);
@@ -6061,6 +6488,7 @@ class DynamicWalletClient {
                 accountAddress,
                 password: newPassword,
                 signedSessionId,
+                sessionPublicKey,
                 passwordUpdateBatchId
             });
             this.logPasswordOperationSuccess('setPassword', {
@@ -6481,7 +6909,7 @@ class DynamicWalletClient {
    * Internal helper method that handles the complete flow for ensuring wallet key shares are backed up to a cloud provider.
    * - For 2-of-2 wallets: Automatically reshares to 2-of-3 threshold, then distributes shares (1 to backend, 1 to cloud)
    * - For 2-of-3 wallets: Call storeEncryptedBackupByWallet to backup for backend and cloud
-   */ async backupKeySharesToCloudProvider({ accountAddress, password, signedSessionId, backupLocation, googleDriveAccessToken, googleDriveTokenSource }) {
+   */ async backupKeySharesToCloudProvider({ accountAddress, password, signedSessionId, sessionPublicKey, backupLocation, googleDriveAccessToken, googleDriveTokenSource }) {
         try {
             await this.getWallet({
                 accountAddress,
@@ -6500,6 +6928,7 @@ class DynamicWalletClient {
                     newThresholdSignatureScheme: core.ThresholdSignatureScheme.TWO_OF_THREE,
                     password,
                     signedSessionId,
+                    sessionPublicKey,
                     cloudProviders: [
                         backupLocation
                     ],
@@ -6511,6 +6940,7 @@ class DynamicWalletClient {
                     accountAddress,
                     password,
                     signedSessionId,
+                    sessionPublicKey,
                     cloudProviders: [
                         backupLocation
                     ],
@@ -6541,7 +6971,7 @@ class DynamicWalletClient {
    * @param params.signedSessionId - Optional signed session ID for authentication
    * @param params.googleDriveAccessToken - Optional Google OAuth access token. When provided, the SDK uses it directly
    *   instead of looking up the user's linked Google account and exchanging it for a token via the Dynamic backend.
-   */ async backupKeySharesToGoogleDrive({ accountAddress, password, signedSessionId, googleDriveAccessToken }) {
+   */ async backupKeySharesToGoogleDrive({ accountAddress, password, signedSessionId, sessionPublicKey, googleDriveAccessToken }) {
         // Track whether the Drive token was supplied by the caller (external) or
         // will be resolved from the user's stored OAuth account (stored_oauth), so
         // backups using a token we don't control are auditable. Enum only — the
@@ -6561,6 +6991,7 @@ class DynamicWalletClient {
                 accountAddress,
                 password,
                 signedSessionId,
+                sessionPublicKey,
                 backupLocation: core.BackupLocation.GOOGLE_DRIVE,
                 // Forward the resolved token so the downstream upload path doesn't
                 // re-fetch it via fetchGoogleDriveAccessToken.
@@ -6632,11 +7063,12 @@ class DynamicWalletClient {
    * @param params.accountAddress - The wallet account address to backup
    * @param params.password - Optional password for encryption (uses environment ID if not provided)
    * @param params.signedSessionId - Optional signed session ID for authentication
-   */ async backupKeySharesToICloud({ accountAddress, password, signedSessionId }) {
+   */ async backupKeySharesToICloud({ accountAddress, password, signedSessionId, sessionPublicKey }) {
         return this.backupKeySharesToCloudProvider({
             accountAddress,
             password,
             signedSessionId,
+            sessionPublicKey,
             backupLocation: core.BackupLocation.ICLOUD
         });
     }
@@ -7849,6 +8281,10 @@ class DynamicWalletClient {
         if (internalOptions == null ? void 0 : internalOptions.getSignedSessionId) {
             this.getSignedSessionIdCallback = internalOptions.getSignedSessionId;
         }
+        // Set session public key callback if provided (internal use only)
+        if (internalOptions == null ? void 0 : internalOptions.getSessionPublicKey) {
+            this.getSessionPublicKeyCallback = internalOptions.getSessionPublicKey;
+        }
         // Read the callback lazily so it tracks `getSignedSessionIdCallback` even
         // when tests reassign it after construction.
         this.signedSession = new SignedSessionManager({
@@ -8050,6 +8486,7 @@ exports.isNonRetryableCeremonyError = isNonRetryableCeremonyError;
 exports.isPublicKeyMismatchError = isPublicKeyMismatchError;
 exports.isRecoverQueueOperation = isRecoverQueueOperation;
 exports.isSignQueueOperation = isSignQueueOperation;
+exports.isStaleClientSharesError = isStaleClientSharesError;
 exports.listICloudBackups = listICloudBackups;
 exports.markCeremonyErrorNonRetryable = markCeremonyErrorNonRetryable;
 exports.readEnvironmentSettings = readEnvironmentSettings;