@dynamic-labs-wallet/browser 1.0.19 → 1.0.21

package/index.cjs

@@ -2,13 +2,13 @@
 
 var core = require('@dynamic-labs-wallet/core');
 var web = require('#internal/web');
-var semver = require('semver');
 var uuid = require('uuid');
 var primitives = require('@dynamic-labs-wallet/primitives');
 var sdkApiCore = require('@dynamic-labs/sdk-api-core');
 var loadArgon2idWasm = require('argon2id');
 var axios = require('axios');
 var PQueue = require('p-queue');
+var semver = require('semver');
 
 function _extends() {
     _extends = Object.assign || function assign(target) {
@@ -997,6 +997,16 @@ const downloadFileFromGoogleDrive = async ({ accessToken, fileName })=>{
     }
 };
 
+/**
+ * Extracts the HTTP status from an `AxiosError`, or `undefined` for non-HTTP
+ * errors. Lives in its own leaf module (no `#internal/web` / WASM imports) so
+ * lightweight consumers like `services/signedSession.ts` can use it without
+ * pulling the MPC WASM bundle that `utils.ts` loads.
+ */ const getHttpStatus = (error)=>{
+    var _error_response;
+    return error instanceof axios.AxiosError ? (_error_response = error.response) == null ? void 0 : _error_response.status : undefined;
+};
+
 const STORAGE_KEY = 'dynamic-waas-wallet-client';
 const BACKUP_FILENAME = 'dynamicWalletKeyShareBackup.json';
 const CLIENT_KEYSHARE_EXPORT_FILENAME_PREFIX = 'dynamicWalletKeyShareBackup';
@@ -1076,14 +1086,6 @@ const getClientKeyShareBackupInfo = (params)=>{
 const timeoutPromise = ({ timeInMs, activity = 'Ceremony' })=>{
     return new Promise((_, reject)=>setTimeout(()=>reject(new Error(`${activity} did not complete in ${timeInMs}ms`)), timeInMs));
 };
-/**
- * Extracts the HTTP status code from an error, returning undefined for non-HTTP
- * failures (network errors, DNS, aborts) which retry logic typically treats
- * the same as 5xx.
- */ const getHttpStatus = (error)=>{
-    var _error_response;
-    return error instanceof axios.AxiosError ? (_error_response = error.response) == null ? void 0 : _error_response.status : undefined;
-};
 const buildErrorContext = (error)=>{
     var _error_response, _error_response1;
     return {
@@ -2463,6 +2465,84 @@ const readEnvironmentSettings = ()=>{
         }
     });
 
+/**
+ * Owns everything about signed sessions and their single-use replay nonces:
+ * resolving a session from an explicit value or the host reverse channel,
+ * deciding whether the SDK version requires one, and building the
+ * refresh-on-replay-400 retry predicate shared by the backup and recovery
+ * flows.
+ *
+ * Extracted from `DynamicWalletClient` so this logic can be exercised in
+ * isolation. The host callback is read lazily (`getCallback`) so it stays in
+ * sync with the owning client even if reassigned after construction.
+ */ class SignedSessionManager {
+    /** True when a reverse channel is configured to mint fresh signed sessions. */ get canRefresh() {
+        return this.getCallback() !== undefined;
+    }
+    /**
+   * Resolves the signed session ID from an explicit value or falls back to the
+   * host reverse channel. Throws if neither source provides a value.
+   */ async resolve(signedSessionId) {
+        const callback = this.getCallback();
+        const resolved = signedSessionId != null ? signedSessionId : await (callback == null ? void 0 : callback());
+        if (!resolved) {
+            throw new Error(signedSessionId === undefined && callback ? 'signedSessionId callback returned an invalid value' : 'signedSessionId is required for backup but was not provided and no callback is configured');
+        }
+        return resolved;
+    }
+    /** Whether the configured SDK version requires a signed session ID. */ isRequired() {
+        return this.required;
+    }
+    computeIsRequired(sdkVersion) {
+        if (!sdkVersion) {
+            return false;
+        }
+        try {
+            const parsedVersion = core.parseNamespacedVersion(sdkVersion);
+            if (!parsedVersion) {
+                return false;
+            }
+            const { namespace, version } = parsedVersion;
+            const namespaceMinVersion = SIGNED_SESSION_ID_MIN_VERSION_BY_NAMESPACE[namespace];
+            if (namespaceMinVersion) {
+                return semver.gte(version, namespaceMinVersion);
+            }
+            return semver.gte(version, SIGNED_SESSION_ID_MIN_VERSION);
+        } catch (error) {
+            this.logger.warn(`[DynamicWaasWalletClient] Error checking if requiresSignedSessionId should be set to true for version ${sdkVersion}`, {
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return false;
+        }
+    }
+    /**
+   * Builds a `retryPromise` `shouldRetry` predicate that refreshes a consumed
+   * single-use nonce via the reverse channel on a replay 400 and retries once.
+   * The signed session carries a single-use replay nonce: it is valid on its
+   * first use, but once consumed (e.g. by a preceding operation) the server
+   * rejects with a 400, at which point a fresh session is fetched and the call
+   * retried. `alsoRetry` lets callers opt into additional retryable statuses
+   * (e.g. 429 / 5xx) on top of the nonce refresh.
+   */ refreshShouldRetry({ onRefreshed, operationName, logContext, alsoRetry }) {
+        return async (error, attempt)=>{
+            const status = getHttpStatus(error);
+            if (status === 400 && attempt === 1 && this.canRefresh) {
+                onRefreshed(await this.resolve());
+                this.logger.info(`[${operationName}] refreshed signed session, retrying`, _extends({
+                    status
+                }, logContext));
+                return true;
+            }
+            return alsoRetry ? alsoRetry(status) : false;
+        };
+    }
+    constructor({ logger, sdkVersion, getCallback }){
+        this.logger = logger;
+        this.getCallback = getCallback;
+        this.required = this.computeIsRequired(sdkVersion);
+    }
+}
+
 /**
  * Determines the recovery state of a wallet based on backup info and local shares.
  *
@@ -2512,17 +2592,6 @@ const KNOWN_SHARE_SET_TYPES = new Set([
 ]);
 class DynamicWalletClient {
     /**
-   * Resolves the signed session ID from an explicit value or falls back to the callback.
-   * Throws if neither source provides a value.
-   */ async resolveSignedSessionId(signedSessionId) {
-        const resolved = signedSessionId != null ? signedSessionId : await (this.getSignedSessionIdCallback == null ? void 0 : this.getSignedSessionIdCallback.call(this));
-        if (!resolved) {
-            const errorMsg = signedSessionId === undefined && this.getSignedSessionIdCallback ? 'signedSessionId callback returned an invalid value' : 'signedSessionId is required for backup but was not provided and no callback is configured';
-            throw new Error(errorMsg);
-        }
-        return resolved;
-    }
-    /**
    * Check if wallet has heavy operations in progress
    */ static isHeavyOpInProgress(accountAddress) {
         return WalletQueueManager.isHeavyOpInProgress(accountAddress);
@@ -2608,29 +2677,8 @@ class DynamicWalletClient {
    * Check if the SDK version meets the requirement for signed session ID
    * Uses namespace-specific version requirements when available
    * @returns boolean indicating if requireSignedSessionId should be set to true
-   */ requiresSignedSessionId() {
-        if (!this.sdkVersion) {
-            return false;
-        }
-        try {
-            const parsedVersion = core.parseNamespacedVersion(this.sdkVersion);
-            if (!parsedVersion) {
-                return false;
-            }
-            const { namespace, version } = parsedVersion;
-            // Check if we have a namespace-specific version requirement
-            const namespaceMinVersion = SIGNED_SESSION_ID_MIN_VERSION_BY_NAMESPACE[namespace];
-            if (namespaceMinVersion) {
-                return semver.gte(version, namespaceMinVersion);
-            }
-            // Fall back to default version requirement
-            return semver.gte(version, SIGNED_SESSION_ID_MIN_VERSION);
-        } catch (error) {
-            this.logger.warn(`[DynamicWaasWalletClient] Error checking if requiresSignedSessionId should be set to true for version ${this.sdkVersion}`, {
-                error: error instanceof Error ? error.message : String(error)
-            });
-            return false;
-        }
+   */ /** @see SignedSessionManager.isRequired */ requiresSignedSessionId() {
+        return this.signedSession.isRequired();
     }
     async initLoggerContext(authToken) {
         // only decode jwt token in header auth mode
@@ -3665,24 +3713,35 @@ class DynamicWalletClient {
             });
             // Ensure client key shares exist before hitting the API
             const clientKeyShares = await this.ensureClientShare(accountAddress);
-            // Tracks whether the SSE ceremony_complete event fired during this
-            // operation. Logged at completion so we can correlate "callback didn't
-            // fire" with downstream sign failures or pending-rotation reports.
-            let ceremonyCallbackFired = false;
-            // Deferred resolved by onCeremonyComplete. The MPC ceremony itself
-            // requires client + server in the room concurrently, so we run
-            // mpcSigner.refresh BEFORE awaiting this — the await's purpose is to
-            // ensure the walletMap.shareSetId rotation (which happens in
-            // onCeremonyComplete) lands before storeEncryptedBackupByWallet reads
-            // it. Without it, backup races ceremony_complete and the atomic swap
-            // targets the stale row.
-            // Mirrors the pattern used in keyGen, with the key difference that
-            // refresh's API call returns on room_created (not on the local MPC
-            // result), so the await sits between the local MPC step and the
-            // backup step, not immediately after the API call.
-            let ceremonyCompleteResolver;
-            const ceremonyCompletePromise = new Promise((resolve)=>{
-                ceremonyCompleteResolver = resolve;
+            // The MPC ceremony needs client + server in the room concurrently, so we
+            // run mpcSigner.refresh BEFORE awaiting the gate. The gate's purpose is to
+            // ensure the walletMap.shareSetId rotation (done in onCeremonyComplete)
+            // lands before storeEncryptedBackupByWallet reads it; without it, backup
+            // would race ceremony_complete and the atomic swap could target the stale
+            // row. refresh's API call returns on room_created (not the local MPC
+            // result), so the gate await sits between the local MPC and the backup.
+            const ceremonyGate = this.createCeremonyTerminalGate((_accountAddress, _walletId, shareSetId, shareSetType)=>{
+                this.logger.info('[WaasRefresh] ceremony_complete received', {
+                    context: {
+                        walletId: wallet.walletId,
+                        newShareSetId: shareSetId,
+                        shareSetType,
+                        dynamicRequestId
+                    }
+                });
+                this.logOnMalformedCeremonyPayload({
+                    walletId: wallet.walletId,
+                    ceremony: 'refresh',
+                    shareSetId,
+                    shareSetType
+                });
+                this.rotateRootUserShareSetIdIfChanged({
+                    accountAddress,
+                    wallet,
+                    ceremony: 'refresh',
+                    shareSetId,
+                    shareSetType
+                });
             });
             this.logger.info('[WaasRefresh] calling refreshWalletAccountShares', {
                 context: {
@@ -3697,31 +3756,8 @@ class DynamicWalletClient {
                 shareSetId: wallet.shareSetId,
                 mfaToken,
                 elevatedAccessToken,
-                onCeremonyComplete: (_accountAddress, _walletId, shareSetId, shareSetType)=>{
-                    ceremonyCallbackFired = true;
-                    this.logger.info('[WaasRefresh] ceremony_complete received', {
-                        context: {
-                            walletId: wallet.walletId,
-                            newShareSetId: shareSetId,
-                            shareSetType,
-                            dynamicRequestId
-                        }
-                    });
-                    this.logOnMalformedCeremonyPayload({
-                        walletId: wallet.walletId,
-                        ceremony: 'refresh',
-                        shareSetId,
-                        shareSetType
-                    });
-                    this.rotateRootUserShareSetIdIfChanged({
-                        accountAddress,
-                        wallet,
-                        ceremony: 'refresh',
-                        shareSetId,
-                        shareSetType
-                    });
-                    ceremonyCompleteResolver(undefined);
-                }
+                onError: ceremonyGate.onError,
+                onCeremonyComplete: ceremonyGate.onCeremonyComplete
             });
             this.logger.info('[WaasRefresh] room_created received, starting local MPC', {
                 context: {
@@ -3751,40 +3787,11 @@ class DynamicWalletClient {
             this.logger.info('[WaasRefresh] local MPC done, awaiting ceremony_complete before backup', {
                 context: {
                     walletId: wallet.walletId,
-                    ceremonyCallbackFired,
+                    ceremonyCallbackFired: ceremonyGate.fired,
                     dynamicRequestId
                 }
             });
-            // Wait for ceremony_complete so the shareSetId rotation in
-            // onCeremonyComplete lands in walletMap before the backup call reads it.
-            // Bounded by a 5s timeout so a missing/late event never hangs the SDK —
-            // if it fires we proceed with the rotated id; if it doesn't we fall back
-            // to the (stale) walletMap.shareSetId, matching pre-fix behavior.
-            const REFRESH_CEREMONY_COMPLETE_TIMEOUT_MS = 5000;
-            let ceremonyCompleteTimedOut = false;
-            let refreshTimeoutId;
-            await Promise.race([
-                ceremonyCompletePromise,
-                new Promise((resolve)=>{
-                    refreshTimeoutId = setTimeout(()=>{
-                        ceremonyCompleteTimedOut = true;
-                        resolve(undefined);
-                    }, REFRESH_CEREMONY_COMPLETE_TIMEOUT_MS);
-                })
-            ]);
-            // Cancel the pending timer when ceremony_complete wins the race so it
-            // doesn't fire later and flip ceremonyCompleteTimedOut after the fact.
-            // Safe no-op when the timer has already fired.
-            clearTimeout(refreshTimeoutId);
-            if (ceremonyCompleteTimedOut) {
-                this.logger.warn(`[WaasRefresh] ceremony_complete didn’t arrive within ${REFRESH_CEREMONY_COMPLETE_TIMEOUT_MS}ms — proceeding with stale walletMap`, {
-                    context: {
-                        walletId: wallet.walletId,
-                        ceremonyCallbackFired,
-                        dynamicRequestId
-                    }
-                });
-            }
+            await ceremonyGate.awaitTerminal();
             // Backup & activate server shares BEFORE saving to local storage.
             // This prevents a mismatch where new client shares are stored locally
             // but old server shares remain active if backup/activation fails.
@@ -3807,15 +3814,13 @@ class DynamicWalletClient {
                 clientKeyShares: refreshResults
             });
             // Operation summary — correlates against downstream sign failures /
-            // pending-rotation reports. `ceremonyCallbackFired: false` here means
-            // either the server is legacy (didn't emit ceremony_complete) or the
-            // SSE event was lost mid-flight.
+            // pending-rotation reports. The gate always fired here (we throw before
+            // backup otherwise); kept for log continuity.
             this.logger.info('[WaasRefresh] completed', {
                 context: {
                     walletId: wallet.walletId,
                     oldShareSetId: wallet.shareSetId,
-                    ceremonyCallbackFired,
-                    ceremonyCompleteTimedOut,
+                    ceremonyCallbackFired: ceremonyGate.fired,
                     dynamicRequestId
                 }
             });
@@ -3971,6 +3976,50 @@ class DynamicWalletClient {
             });
         }
     }
+    // Terminal gate shared by refresh and reshare. Both APIs resolve early on
+    // room_created, so a failed ceremony surfaces *after* the API call returns —
+    // as an SSE error event, a stream close without ceremony_complete, or a
+    // transport drop (all delivered via onError). awaitTerminal() races the two
+    // outcomes with no timeout:
+    //   - ceremony_complete → resolves → caller backs up against the rotated id.
+    //   - any onError → rejects → caller throws, never backs up (the wedge fix:
+    //     a failed ceremony must not promote a client share whose server
+    //     counterpart was never persisted).
+    // redcoast always emits one or the other and the event-stream consumer turns
+    // "closed without ceremony_complete" into an onError, so the race always
+    // settles. Aborting fails closed — worst case is a clean retry.
+    //
+    // The reject handle is wired synchronously (Promise executors run inline)
+    // before the API call starts, so an immediate onError can never be dropped.
+    // The lost branch's rejection is swallowed so it never surfaces as unhandled.
+    createCeremonyTerminalGate(onCeremonyComplete) {
+        let resolveComplete;
+        const completePromise = new Promise((resolve)=>{
+            resolveComplete = resolve;
+        });
+        let rejectOnError;
+        const errorPromise = new Promise((_, reject)=>{
+            rejectOnError = reject;
+        });
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        errorPromise.catch(()=>{});
+        let fired = false;
+        return {
+            onError: rejectOnError,
+            onCeremonyComplete: (accountAddress, walletId, shareSetId, shareSetType)=>{
+                fired = true;
+                onCeremonyComplete == null ? void 0 : onCeremonyComplete(accountAddress, walletId, shareSetId, shareSetType);
+                resolveComplete();
+            },
+            awaitTerminal: ()=>Promise.race([
+                    completePromise,
+                    errorPromise
+                ]),
+            get fired () {
+                return fired;
+            }
+        };
+    }
     // Runs the post-ceremony backup-activation step (storeEncryptedBackupByWallet
     // for refresh, backupSharesWithDistribution for reshare). On failure, rolls
     // walletMap.shareSetId back to the source row.
@@ -4202,19 +4251,39 @@ class DynamicWalletClient {
                 ...existingClientKeygenIds
             ];
             const bitcoinConfig = this.getBitcoinConfigForChain(chainName, accountAddress);
-            // Tracks whether the SSE ceremony_complete event fired during this
-            // operation. Logged at completion so we can correlate "callback didn't
-            // fire" with downstream sign failures or pending-rotation reports.
-            let ceremonyCallbackFired = false;
-            // Deferred resolved by onCeremonyComplete. The MPC reshare requires
-            // client + server in the room concurrently, so we run mpcSigner.reshare*
-            // BEFORE awaiting this — the await's purpose is to ensure the
+            // The MPC reshare needs client + server in the room concurrently, so we
+            // run mpcSigner.reshare* BEFORE awaiting the gate. The gate ensures the
             // walletMap.shareSetId rotation lands before storeEncryptedBackupByWallet
-            // reads it. Without it, backup races ceremony_complete and the atomic
-            // swap targets the stale row.
-            let ceremonyCompleteResolver;
-            const ceremonyCompletePromise = new Promise((resolve)=>{
-                ceremonyCompleteResolver = resolve;
+            // reads it; without it, backup would race ceremony_complete and the atomic
+            // swap could target the stale row.
+            const ceremonyGate = this.createCeremonyTerminalGate((_accountAddress, _walletId, shareSetId, shareSetType)=>{
+                this.logger.info('[WaasReshare] ceremony_complete received', {
+                    context: {
+                        walletId: wallet.walletId,
+                        newShareSetId: shareSetId,
+                        shareSetType,
+                        dynamicRequestId
+                    }
+                });
+                this.logOnMalformedCeremonyPayload({
+                    walletId: wallet.walletId,
+                    ceremony: 'reshare',
+                    shareSetId,
+                    shareSetType
+                });
+                this.rotateRootUserShareSetIdIfChanged({
+                    accountAddress,
+                    wallet,
+                    ceremony: 'reshare',
+                    shareSetId,
+                    shareSetType,
+                    newThresholdSignatureScheme,
+                    extraContext: {
+                        oldThresholdSignatureScheme,
+                        newThresholdSignatureScheme,
+                        resolvedDelegation
+                    }
+                });
             });
             this.logger.info('[WaasReshare] calling reshare API', {
                 context: {
@@ -4237,37 +4306,8 @@ class DynamicWalletClient {
                 mfaToken,
                 elevatedAccessToken,
                 revokeDelegation,
-                onCeremonyComplete: (_accountAddress, _walletId, shareSetId, shareSetType)=>{
-                    ceremonyCallbackFired = true;
-                    this.logger.info('[WaasReshare] ceremony_complete received', {
-                        context: {
-                            walletId: wallet.walletId,
-                            newShareSetId: shareSetId,
-                            shareSetType,
-                            dynamicRequestId
-                        }
-                    });
-                    this.logOnMalformedCeremonyPayload({
-                        walletId: wallet.walletId,
-                        ceremony: 'reshare',
-                        shareSetId,
-                        shareSetType
-                    });
-                    this.rotateRootUserShareSetIdIfChanged({
-                        accountAddress,
-                        wallet,
-                        ceremony: 'reshare',
-                        shareSetId,
-                        shareSetType,
-                        newThresholdSignatureScheme,
-                        extraContext: {
-                            oldThresholdSignatureScheme,
-                            newThresholdSignatureScheme,
-                            resolvedDelegation
-                        }
-                    });
-                    ceremonyCompleteResolver(undefined);
-                }
+                onError: ceremonyGate.onError,
+                onCeremonyComplete: ceremonyGate.onCeremonyComplete
             });
             this.logger.info('[WaasReshare] room_created received, starting local MPC', {
                 context: {
@@ -4376,38 +4416,11 @@ class DynamicWalletClient {
             this.logger.info('[WaasReshare] local MPC done, awaiting ceremony_complete before backup', {
                 context: {
                     walletId: wallet.walletId,
-                    ceremonyCallbackFired,
+                    ceremonyCallbackFired: ceremonyGate.fired,
                     dynamicRequestId
                 }
             });
-            // Wait for ceremony_complete so the shareSetId rotation in
-            // onCeremonyComplete lands in walletMap before the backup call reads it.
-            // Bounded by a 5s timeout so a missing/late event never hangs the SDK.
-            const RESHARE_CEREMONY_COMPLETE_TIMEOUT_MS = 5000;
-            let ceremonyCompleteTimedOut = false;
-            let reshareTimeoutId;
-            await Promise.race([
-                ceremonyCompletePromise,
-                new Promise((resolve)=>{
-                    reshareTimeoutId = setTimeout(()=>{
-                        ceremonyCompleteTimedOut = true;
-                        resolve(undefined);
-                    }, RESHARE_CEREMONY_COMPLETE_TIMEOUT_MS);
-                })
-            ]);
-            // Cancel the pending timer when ceremony_complete wins the race so it
-            // doesn't fire later and flip ceremonyCompleteTimedOut after the fact.
-            // Safe no-op when the timer has already fired.
-            clearTimeout(reshareTimeoutId);
-            if (ceremonyCompleteTimedOut) {
-                this.logger.warn(`[WaasReshare] ceremony_complete didn’t arrive within ${RESHARE_CEREMONY_COMPLETE_TIMEOUT_MS}ms — proceeding with stale walletMap`, {
-                    context: {
-                        walletId: wallet.walletId,
-                        ceremonyCallbackFired,
-                        dynamicRequestId
-                    }
-                });
-            }
+            await ceremonyGate.awaitTerminal();
             // Backup & activate server shares BEFORE saving to local storage.
             // This prevents a mismatch where new client shares are stored locally
             // but old server shares remain active if backup/activation fails.
@@ -4445,18 +4458,16 @@ class DynamicWalletClient {
                 });
             }
             // Operation summary — correlates against downstream sign failures /
-            // pending-rotation reports. `ceremonyCallbackFired: false` here means
-            // either the server is legacy (didn't emit ceremony_complete) or the
-            // SSE event was lost mid-flight.
+            // pending-rotation reports. The gate always fired here (we throw before
+            // backup otherwise); kept for log continuity.
             this.logger.info('[WaasReshare] completed', {
                 context: {
-                    ceremonyCompleteTimedOut,
                     walletId: wallet.walletId,
                     oldShareSetId: wallet.shareSetId,
                     oldThresholdSignatureScheme,
                     newThresholdSignatureScheme,
                     resolvedDelegation,
-                    ceremonyCallbackFired
+                    ceremonyCallbackFired: ceremonyGate.fired
                 }
             });
         } catch (error) {
@@ -5296,8 +5307,7 @@ class DynamicWalletClient {
         try {
             var _preEncryptedCloudShares_, _this_getWalletFromMap, _backupData_locationsWithKeyShares, _backupData_locationsWithKeyShares1;
             // `let` so the retry path can swap in a freshly-signed session via the reverse channel on 400.
-            let resolvedSignedSessionId = await this.resolveSignedSessionId(signedSessionId);
-            const canRefreshSignedSessionId = this.getSignedSessionIdCallback !== undefined;
+            let resolvedSignedSessionId = await this.signedSession.resolve(signedSessionId);
             if (!(walletData == null ? void 0 : walletData.walletId)) {
                 const error = new Error(`WalletId not found for accountAddress ${accountAddress}`);
                 logError({
@@ -5390,19 +5400,18 @@ class DynamicWalletClient {
                         passwordUpdateBatchId
                     }), {
                     operationName,
-                    shouldRetry: async (error, attempt)=>{
-                        const status = getHttpStatus(error);
-                        if (status === 400 && attempt === 1 && canRefreshSignedSessionId) {
-                            resolvedSignedSessionId = await this.resolveSignedSessionId();
-                            this.logger.info(`[${operationName}] refreshed signed session, retrying`, {
-                                dynamicRequestId,
-                                status
-                            });
-                            return true;
-                        }
-                        // 429 (rate limit) is the textbook back-off-and-retry status.
-                        return status === undefined || status === 429 || status >= 500;
-                    }
+                    // Refresh a consumed nonce on a 400; otherwise back off and retry
+                    // transient statuses (undefined / 429 / 5xx).
+                    shouldRetry: this.signedSession.refreshShouldRetry({
+                        onRefreshed: (id)=>{
+                            resolvedSignedSessionId = id;
+                        },
+                        operationName,
+                        logContext: {
+                            dynamicRequestId
+                        },
+                        alsoRetry: (status)=>status === undefined || status === 429 || status !== undefined && status >= 500
+                    })
                 }));
             }
             // Cloud providers already have internal retries (Google Drive and iCloud),
@@ -5592,7 +5601,7 @@ class DynamicWalletClient {
         // still throw — the host can re-auth from the error.
         let resolvedSessionId;
         try {
-            resolvedSessionId = await this.resolveSignedSessionId(signedSessionId);
+            resolvedSessionId = await this.signedSession.resolve(signedSessionId);
         } catch (e) {
             resolvedSessionId = undefined;
         }
@@ -5950,13 +5959,14 @@ class DynamicWalletClient {
                     externalKeyShareIds: shares[core.BackupLocation.DYNAMIC] || []
                 }
             });
-            const result = await this.apiClient.recoverEncryptedBackupByWallet({
+            const result = await this.recoverEncryptedSharesWithNonceRetry({
                 walletId: wallet.walletId,
                 shareSetId: wallet.shareSetId,
                 externalKeyShareIds: shares[core.BackupLocation.DYNAMIC] || [],
-                signedSessionId,
-                requiresSignedSessionId: this.requiresSignedSessionId(),
-                userId: this.userId
+                signedSessionId
+            }, {
+                walletId: wallet.walletId,
+                context: 'validatePasswordAgainstEncryptedShares'
             });
             if (!result) {
                 throw new Error('Failed to retrieve encrypted backup from API for password validation');
@@ -6147,6 +6157,32 @@ class DynamicWalletClient {
                 mfaToken
             }));
     }
+    /**
+   * Fetches encrypted backup shares from the server, transparently refreshing
+   * the signed session on a single-use-nonce rejection. Recovery is otherwise
+   * non-retrying, so other errors surface immediately. When no reverse channel
+   * is configured the provided session is used unchanged.
+   */ async recoverEncryptedSharesWithNonceRetry(params, logContext) {
+        let resolvedSignedSessionId = params.signedSessionId;
+        return retryPromise(()=>this.apiClient.recoverEncryptedBackupByWallet(_extends({}, params, {
+                signedSessionId: resolvedSignedSessionId,
+                requiresSignedSessionId: this.requiresSignedSessionId(),
+                userId: this.userId
+            })), {
+            operationName: 'recoverEncryptedBackupByWallet',
+            // At most one retry — the nonce refresh — and no back-off before it,
+            // since a consumed-nonce 400 is deterministic, not a transient error.
+            maxAttempts: 2,
+            retryInterval: 0,
+            shouldRetry: this.signedSession.refreshShouldRetry({
+                onRefreshed: (id)=>{
+                    resolvedSignedSessionId = id;
+                },
+                operationName: 'recoverEncryptedBackupByWallet',
+                logContext
+            })
+        });
+    }
     async internalRecoverEncryptedBackupByWallet({ accountAddress, password, walletOperation, signedSessionId, shareCount = undefined, storeRecoveredShares = true, mfaToken }) {
         try {
             const wallet = this.getWalletFromMap(accountAddress);
@@ -6167,14 +6203,15 @@ class DynamicWalletClient {
                     thresholdSignatureScheme: wallet.thresholdSignatureScheme
                 }
             });
-            const data = await this.apiClient.recoverEncryptedBackupByWallet({
+            const data = await this.recoverEncryptedSharesWithNonceRetry({
                 walletId: wallet.walletId,
                 shareSetId: wallet.shareSetId,
                 externalKeyShareIds: dynamicKeyShareIds,
                 signedSessionId,
-                mfaToken,
-                requiresSignedSessionId: this.requiresSignedSessionId(),
-                userId: this.userId
+                mfaToken
+            }, {
+                walletId: wallet.walletId,
+                walletOperation
             });
             const dynamicKeyShares = data.keyShares.filter((keyShare)=>keyShare.encryptedAccountCredential !== null && keyShare.backupLocation === core.BackupLocation.DYNAMIC);
             const decryptedKeyShares = await Promise.all(dynamicKeyShares.map((keyShare)=>// `decryptKeyShare` owns the `environmentId` fallback; passing
@@ -6842,8 +6879,10 @@ class DynamicWalletClient {
             })) {
                 const walletData = this.getWalletFromMap(accountAddress);
                 const isPasswordEncrypted = isWalletPasswordEncrypted(walletData);
-                // Password-encrypted wallet without password - fetch and cache for eager loading
-                if (walletOperation === core.WalletOperation.RECOVER && isPasswordEncrypted && !password) {
+                // Locked wallet (password-encrypted, no password supplied): its shares need the
+                // user's password, not the environmentId. Return it ENCRYPTED for any operation
+                // rather than fall through to an envId-decrypt that throws KeyShareDecryptionError.
+                if (isPasswordEncrypted && !password) {
                     // Skip fetch if encrypted shares are already cached in storage
                     const alreadyCached = await hasEncryptedSharesCached({
                         accountAddress,
@@ -6864,28 +6903,32 @@ class DynamicWalletClient {
                         }
                         return cachedWallet;
                     }
+                    // RECOVER on purpose: cache the full set a later unlockWallet needs, not the triggering op's subset.
                     const { shares } = this.recoverStrategy({
                         clientKeyShareBackupInfo: walletData.clientKeySharesBackupInfo,
                         thresholdSignatureScheme: walletData.thresholdSignatureScheme,
                         walletOperation: core.WalletOperation.RECOVER
                     });
                     const { dynamic: dynamicKeyShareIds } = shares;
-                    this.logger.info('[walletMap] getWallet: requesting key shares for eager loading', {
+                    this.logger.info('[walletMap] getWallet: caching encrypted shares for locked wallet', {
                         context: {
                             accountAddress,
                             walletId: walletData.walletId,
                             externalKeyShareIds: dynamicKeyShareIds,
                             dynamicRequestId,
-                            isPasswordEncrypted
+                            isPasswordEncrypted,
+                            walletOperation
                         }
                     });
-                    const data = await this.apiClient.recoverEncryptedBackupByWallet({
+                    const data = await this.recoverEncryptedSharesWithNonceRetry({
                         walletId: walletData.walletId,
                         shareSetId: walletData.shareSetId,
                         externalKeyShareIds: dynamicKeyShareIds,
-                        signedSessionId,
-                        requiresSignedSessionId: this.requiresSignedSessionId(),
-                        userId: this.userId
+                        signedSessionId
+                    }, {
+                        walletId: walletData.walletId,
+                        context: 'getWallet:eagerLoad',
+                        dynamicRequestId
                     });
                     // Cache encrypted shares for later decryption by unlockWallet
                     const encryptedStorageKey = `${normalizeAddress(accountAddress)}${core.ENCRYPTED_SHARES_STORAGE_SUFFIX}`;
@@ -7022,13 +7065,14 @@ class DynamicWalletClient {
                 externalKeyShareIds
             }
         });
-        const data = await this.apiClient.recoverEncryptedBackupByWallet({
+        const data = await this.recoverEncryptedSharesWithNonceRetry({
             walletId: walletData.walletId,
             externalKeyShareIds,
             signedSessionId,
-            mfaToken,
-            requiresSignedSessionId: this.requiresSignedSessionId(),
-            userId: this.userId
+            mfaToken
+        }, {
+            walletId: walletData.walletId,
+            context: 'fetchAndCacheEncryptedShares'
         });
         if (!data) {
             return null;
@@ -7476,6 +7520,13 @@ class DynamicWalletClient {
         if (internalOptions == null ? void 0 : internalOptions.getSignedSessionId) {
             this.getSignedSessionIdCallback = internalOptions.getSignedSessionId;
         }
+        // Read the callback lazily so it tracks `getSignedSessionIdCallback` even
+        // when tests reassign it after construction.
+        this.signedSession = new SignedSessionManager({
+            logger: this.logger,
+            sdkVersion: this.sdkVersion,
+            getCallback: ()=>this.getSignedSessionIdCallback
+        });
         this.apiClient = new core.DynamicApiClient({
             environmentId,
             authToken,