@dynamic-labs-wallet/browser 1.1.55 → 1.1.57

package/index.esm.js

@@ -1,4 +1,4 @@
-import { BitcoinAddressType, MPC_RELAY_PROD_API_URL, DEFAULT_ED25519_VARIANT, getMPCChainConfig, parseNamespacedVersion, WalletApiError, NETWORK_ERROR_STATUS, formatRawMessageForSigning, BackupLocation, ENCRYPTED_SHARES_STORAGE_SUFFIX, Logger, createRejectablePromise, handleAxiosError, extractServerErrorCode, WalletOperation, ThresholdSignatureScheme, WalletReadyState, classifyForwardMpcError, isRecoveredForwardMpcConnectionChurn, FEATURE_FLAGS, getClientThreshold, MPC_CONFIG, forwardMpcMayHaveJoinedRoom, normalizeAndValidatePrivateKey, getTSSConfig, toJsonSafeContext, serializeMessageForForwardMPC, isEvmCompatibleChain, serializeError, withTraceId, attachRequestIds, getReshareConfig, isBusinessAccountActionRequired, createExportIntent, getRequiredExternalKeyShareId, verifiedCredentialNameToChainEnum, AuthMode, NoopLogger, DynamicApiClient, BusinessAccountClient, getEnvironmentFromUrl, IFRAME_DOMAIN_MAP } from '@dynamic-labs-wallet/core';
+import { BitcoinAddressType, MPC_RELAY_PROD_API_URL, DEFAULT_ED25519_VARIANT, getMPCChainConfig, parseNamespacedVersion, WalletApiError, NETWORK_ERROR_STATUS, formatRawMessageForSigning, BackupLocation, ENCRYPTED_SHARES_STORAGE_SUFFIX, Logger, createRejectablePromise, handleAxiosError, extractServerErrorCode, WalletOperation, ThresholdSignatureScheme, WalletReadyState, classifyForwardMpcError, isRecoveredForwardMpcConnectionChurn, FEATURE_FLAGS, getClientThreshold, MPC_CONFIG, forwardMpcMayHaveJoinedRoom, normalizeAndValidatePrivateKey, getTSSConfig, toJsonSafeContext, serializeMessageForForwardMPC, isEvmCompatibleChain, serializeError, withTraceId, attachRequestIds, getReshareConfig, isBusinessAccountActionRequired, SigningConsentRequiredError, createExportIntent, createReshareIntent, getRequiredExternalKeyShareId, verifiedCredentialNameToChainEnum, AuthMode, NoopLogger, DynamicApiClient, BusinessAccountClient, getEnvironmentFromUrl, IFRAME_DOMAIN_MAP } from '@dynamic-labs-wallet/core';
 export * from '@dynamic-labs-wallet/core';
 export { Logger } from '@dynamic-labs-wallet/core';
 import { EdBls12377, BIP340, Ed25519, ExportableEd25519, Ecdsa, MessageHash, EcdsaSignature, EcdsaKeygenResult, ExportableEd25519KeygenResult, Ed25519KeygenResult, BIP340KeygenResult } from '#internal/web';
@@ -2978,9 +2978,9 @@ class WalletQueueManager {
    * lock within `acquireTimeoutMs` (a stuck holder in another context) fails
    * like a queue timeout instead of racing unlocked; dead contexts release
    * their locks automatically. Falls back to the in-memory queues when
-   * `navigator.locks` is unavailable or the share lock flag is off.
+   * `navigator.locks` is unavailable.
    */ static async withShareLock(accountAddress, acquireTimeoutMs, mode, callback) {
-        if (!this.shareLockEnabled || typeof navigator === 'undefined' || !navigator.locks) {
+        if (typeof navigator === 'undefined' || !navigator.locks) {
             return callback();
         }
         const abort = new AbortController();
@@ -3342,18 +3342,30 @@ class WalletQueueManager {
         const heavyQueue = this.getHeavyOpQueue(accountAddress);
         // Create promise and track it
         const recoveryPromise = (async ()=>{
-            // A recovery rewrites the shares, so it cannot start while a sign is using them.
-            await this.waitForSignQueueIdle(accountAddress);
-            // Add to heavy queue - will wait if other heavy operations are in progress
-            return heavyQueue.add(()=>this.withShareLock(accountAddress, HEAVY_OP_TIMEOUT_MS, 'exclusive', async ()=>{
-                    try {
-                        return await callback();
-                    } finally{
-                        // Clean up tracking when done
-                        logRecoveryFinished();
-                        this.clearPendingRecoveryPromise(accountAddress);
-                    }
-                }));
+            let started = false;
+            try {
+                // A recovery rewrites the shares, so it cannot start while a sign is using them.
+                await this.waitForSignQueueIdle(accountAddress);
+                // Add to heavy queue - will wait if other heavy operations are in progress
+                return await heavyQueue.add(()=>this.withShareLock(accountAddress, HEAVY_OP_TIMEOUT_MS, 'exclusive', async ()=>{
+                        started = true;
+                        try {
+                            return await callback();
+                        } finally{
+                            // Clean up tracking when done
+                            logRecoveryFinished();
+                            this.clearPendingRecoveryPromise(accountAddress);
+                        }
+                    }));
+            } catch (error) {
+                // Failed before the callback ran (e.g. lock acquisition timeout): its `finally` never will,
+                // and a stale rejected promise would be returned to every later recovery call.
+                if (!started) {
+                    logRecoveryFinished();
+                    this.clearPendingRecoveryPromise(accountAddress);
+                }
+                throw error;
+            }
         })();
         // Track this recovery
         this.setPendingRecoveryPromise(accountAddress, recoveryPromise);
@@ -3405,11 +3417,7 @@ class WalletQueueManager {
     /**
    * Reset static state for testing purposes.
    * This clears all wallet queues and pending recovery promises.
-   */ static setShareLockEnabled(enabled) {
-        this.shareLockEnabled = enabled;
-    }
-    static resetForTesting() {
-        this.shareLockEnabled = false;
+   */ static resetForTesting() {
         this.heavyOpQueues.clear();
         this.signQueues.clear();
         this.pendingRecoveryPromises.clear();
@@ -3423,7 +3431,6 @@ class WalletQueueManager {
 /** Heavy operation queues per wallet address. These run with concurrency=1. */ WalletQueueManager.heavyOpQueues = new Map();
 /** Sign queues per wallet address. These allow concurrent operations. */ WalletQueueManager.signQueues = new Map();
 /** Timeout applied to new sign queues. Mutable for tests via resetForTesting. */ WalletQueueManager.signQueueTimeoutMs = 20000;
-/** Gates the cross-instance Web Lock; set from the `enable-share-web-lock` flag. */ WalletQueueManager.shareLockEnabled = false;
 /** Longest a bounded wait on an in-flight recovery lasts before the sign carries on with the shares it has. */ WalletQueueManager.recoveryWaitCapMs = 10000;
 /** Track pending recovery promises for deduplication */ WalletQueueManager.pendingRecoveryPromises = new Map();
 /** Per wallet, the signs that have loaded their key shares and not finished. */ WalletQueueManager.shareHolderQueues = new Map();
@@ -3851,7 +3858,9 @@ const validateOfflineRecoveryParams = ({ accountAddress, cloudProviderAccessToke
             ],
             offlineRecovery: true,
             mfaToken,
-            recoveryEncryptionPublicKey: params.recoveryEncryptionPublicKey
+            recoveryEncryptionPublicKey: params.recoveryEncryptionPublicKey,
+            approvalQuorum: params.approvalQuorum,
+            proposalId: params.proposalId
         }, providerReshareArgs));
         Logger.info('offlineRecovery completed', {
             operation: 'offlineRecovery',
@@ -3981,6 +3990,25 @@ const BACKUP_OPERATION = {
  * path so normal signing stays quiet, well below the 20s queue timeout so a
  * stall is still captured while it is stalling.
  */ const SLOW_SIGN_PREFLIGHT_MS = 1000;
+// The server derives the gated operation from reshareKind, so a backup is
+// marked on every call, governed or not: unmarked, it reads as a plain reshare
+// and the backup's policy gate never runs.
+const reshareKindOf = ({ offlineRecovery, cloudBackup })=>{
+    if (offlineRecovery) return 'offlineRecovery';
+    return cloudBackup ? 'cloudBackup' : undefined;
+};
+/**
+ * The reshare call resolves with an action-required body instead of a room
+ * when a governed request is answered before the stream opens (a 422
+ * `intent_required`). redcoast's reshare route answers on the stream today,
+ * but a body with no room must never reach the ceremony: it would fail there
+ * and roll back local shares that are intact.
+ */ const assertReshareRoomOpened = (data)=>{
+    if (isBusinessAccountActionRequired(data)) {
+        throw new SigningConsentRequiredError(data);
+    }
+    return data;
+};
 /** A secure-storage key share read slower than this is logged on its own, so reads before the sign queue are visible too. */ const SLOW_KEY_SHARE_READ_MS = 1000;
 const KNOWN_SHARE_SET_TYPES = new Set([
     'rootUser',
@@ -6713,7 +6741,10 @@ class DynamicWalletClient {
             existingClientKeyShares
         };
     }
-    async reshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, sessionPublicKey, cloudProviders = [], delegateToProjectEnvironment = false, offlineRecovery = false, mfaToken, elevatedAccessToken, revokeDelegation = false, googleDriveAccessToken, googleDriveTokenSource, initialSignerRules, recoveryEncryptionPublicKey }) {
+    async reshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, sessionPublicKey, cloudProviders = [], delegateToProjectEnvironment = false, offlineRecovery = false, mfaToken, elevatedAccessToken, revokeDelegation = false, googleDriveAccessToken, googleDriveTokenSource, initialSignerRules, recoveryEncryptionPublicKey, approvalQuorum, proposalId, cloudBackup = false }) {
+        if (cloudBackup && (offlineRecovery || delegateToProjectEnvironment)) {
+            throw new Error('reshare: cloudBackup excludes offlineRecovery and delegateToProjectEnvironment');
+        }
         if (delegateToProjectEnvironment && offlineRecovery) {
             throw new Error('reshare: delegateToProjectEnvironment and offlineRecovery are mutually exclusive');
         }
@@ -6749,7 +6780,10 @@ class DynamicWalletClient {
                 googleDriveAccessToken,
                 googleDriveTokenSource,
                 initialSignerRules,
-                recoveryEncryptionPublicKey
+                recoveryEncryptionPublicKey,
+                approvalQuorum,
+                proposalId,
+                cloudBackup
             }));
     }
     /** Reshare into a new 2/2 share set for the target signer; seed it to CKS
@@ -7088,6 +7122,7 @@ class DynamicWalletClient {
                     completePromise,
                     errorGate.promise
                 ]),
+            failed: errorGate.promise,
             get fired () {
                 return fired;
             }
@@ -7272,7 +7307,9 @@ class DynamicWalletClient {
    *   {@link recordReshareThresholdScheme} guard on the success path. Wiping
    *   here would strand a wallet whose local keys are still valid.
    */ async rollbackFailedReshareLocalState({ accountAddress, oldThresholdSignatureScheme, offlineRecovery, error }) {
-        if (offlineRecovery || isPublicKeyMismatchError(error) || isStaleClientSharesError(error)) return;
+        if (offlineRecovery || isPublicKeyMismatchError(error) || isStaleClientSharesError(error) || // Consent refusals happen before any ceremony starts — the local shares
+        // are still good and must not be rolled back.
+        error instanceof SigningConsentRequiredError) return;
         this.updateWalletMap(accountAddress, {
             thresholdSignatureScheme: oldThresholdSignatureScheme
         });
@@ -7309,7 +7346,7 @@ class DynamicWalletClient {
             clientKeySharesBackupInfo: updatedBackupInfo
         } : {}));
     }
-    async internalReshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, sessionPublicKey, cloudProviders = [], delegateToProjectEnvironment = false, offlineRecovery = false, mfaToken, elevatedAccessToken, revokeDelegation = false, googleDriveAccessToken, googleDriveTokenSource, staleShareRetry = false, initialSignerRules, recoveryEncryptionPublicKey }) {
+    async internalReshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, sessionPublicKey, cloudProviders = [], delegateToProjectEnvironment = false, offlineRecovery = false, mfaToken, elevatedAccessToken, revokeDelegation = false, googleDriveAccessToken, googleDriveTokenSource, staleShareRetry = false, initialSignerRules, recoveryEncryptionPublicKey, approvalQuorum, proposalId, cloudBackup = false }) {
         const dynamicRequestId = v4();
         // Password validation - wrapped in try-catch for consistent error handling
         // This path should NOT wipe key shares on failure (shares remain valid)
@@ -7424,7 +7461,11 @@ class DynamicWalletClient {
                     dynamicRequestId
                 }
             });
-            const data = await this.apiClient.reshare(_extends({
+            const reshareKind = reshareKindOf({
+                offlineRecovery,
+                cloudBackup
+            });
+            const data = assertReshareRoomOpened(await this.apiClient.reshare(_extends({
                 walletId: wallet.walletId,
                 shareSetId: wallet.shareSetId,
                 clientKeygenIds: clientKeygenIds,
@@ -7436,17 +7477,19 @@ class DynamicWalletClient {
                 elevatedAccessToken,
                 revokeDelegation,
                 initialSignerRules
-            }, offlineRecovery ? {
-                reshareKind: 'offlineRecovery'
+            }, reshareKind ? {
+                reshareKind
             } : {}, recoveryEncryptionPublicKey ? {
                 offlineRecoveryEncryptionKey: {
                     alg: 'HYBRID-RSA-AES-256',
                     publicKeyPemB64: recoveryEncryptionPublicKey
                 }
             } : {}, {
+                approvalQuorum,
+                proposalId,
                 onError: ceremonyGate.onError,
                 onCeremonyComplete: ceremonyGate.onCeremonyComplete
-            }));
+            })));
             this.logger.info('[WaasReshare] room_created received, starting local MPC', {
                 context: {
                     walletId: wallet.walletId,
@@ -7491,49 +7534,23 @@ class DynamicWalletClient {
             let existingReshareResults;
             let newReshareResults;
             try {
-                const [existingSettled, newSettled] = await Promise.all([
-                    Promise.allSettled(existingClientKeyShares.map((keyShare)=>mpcSigner.reshareRemainingParty(roomId, newMpcConfig.threshold, keyShare, allPartyKeygenIds))),
-                    Promise.allSettled(newClientInitKeygenResults.map((keygenResult)=>mpcSigner.reshareNewParty(roomId, oldMpcConfig.threshold, newMpcConfig.threshold, keygenResult, allPartyKeygenIds)))
-                ]);
-                const collectRejections = (results, keygenIds, role)=>results.reduce((acc, r, i)=>{
-                        if (r.status === 'rejected') {
-                            acc.push({
-                                role,
-                                partyIndex: i,
-                                keygenId: keygenIds[i],
-                                error: r.reason
-                            });
-                        }
-                        return acc;
-                    }, []);
-                const failures = [
-                    ...collectRejections(existingSettled, existingClientKeygenIds, 'existingParty'),
-                    ...collectRejections(newSettled, newClientKeygenIds, 'newParty')
-                ];
-                if (failures.length > 0) {
-                    const firstError = failures[0].error;
-                    const error = firstError instanceof Error ? firstError : new Error(String(firstError));
-                    logError({
-                        message: 'Reshare MPC ceremony party failures',
-                        error,
-                        context: {
-                            dynamicRequestId,
-                            roomId,
-                            failures: failures.map((f)=>({
-                                    role: f.role,
-                                    partyIndex: f.partyIndex,
-                                    keygenId: f.keygenId,
-                                    error: f.error instanceof Error ? f.error.message : String(f.error)
-                                })),
-                            existingSuccessCount: existingSettled.filter((r)=>r.status === 'fulfilled').length,
-                            newSuccessCount: newSettled.filter((r)=>r.status === 'fulfilled').length
-                        }
-                    });
-                    throw error;
-                }
-                existingReshareResults = existingSettled.map((r)=>r.value);
-                newReshareResults = newSettled.map((r)=>r.value);
+                ({ existingReshareResults, newReshareResults } = await this.runReshareParties({
+                    mpcSigner,
+                    roomId,
+                    oldThreshold: oldMpcConfig.threshold,
+                    newThreshold: newMpcConfig.threshold,
+                    allPartyKeygenIds,
+                    existingClientKeyShares,
+                    existingClientKeygenIds,
+                    newClientInitKeygenResults,
+                    newClientKeygenIds,
+                    refused: ceremonyGate.failed,
+                    dynamicRequestId
+                }));
             } catch (reshareError) {
+                // A consent refusal never started the ceremony: the local shares are
+                // intact, so there is nothing to heal.
+                if (reshareError instanceof SigningConsentRequiredError) throw reshareError;
                 // Heal stale local shares before rethrowing so a retry succeeds.
                 await this.healStaleShares({
                     accountAddress,
@@ -7663,7 +7680,10 @@ class DynamicWalletClient {
                     googleDriveTokenSource,
                     staleShareRetry: true,
                     initialSignerRules,
-                    recoveryEncryptionPublicKey
+                    recoveryEncryptionPublicKey,
+                    approvalQuorum,
+                    proposalId,
+                    cloudBackup
                 });
             }
             logError({
@@ -7689,7 +7709,67 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async performDelegationOperation({ accountAddress, password, signedSessionId, sessionPublicKey, mfaToken, newThresholdSignatureScheme, revokeDelegation = false, useShareSetReshare = false, operationName, initialSignerRules }) {
+    /**
+   * Runs the client's MPC parties for a reshare until they finish or the
+   * server refuses the reshare on the stream, whichever comes first.
+   */ async runReshareParties({ mpcSigner, roomId, oldThreshold, newThreshold, allPartyKeygenIds, existingClientKeyShares, existingClientKeygenIds, newClientInitKeygenResults, newClientKeygenIds, refused, dynamicRequestId }) {
+        // redcoast answers room_created before wallet-service has accepted the
+        // reshare, so a refusal (consent_required, policy violation) lands on
+        // the stream while the local parties wait for a server that never
+        // joins. Race them against it, as export does, so the refusal surfaces
+        // now rather than as a relay timeout.
+        const mpcPartiesPromise = Promise.all([
+            Promise.allSettled(existingClientKeyShares.map((keyShare)=>mpcSigner.reshareRemainingParty(roomId, newThreshold, keyShare, allPartyKeygenIds))),
+            Promise.allSettled(newClientInitKeygenResults.map((keygenResult)=>mpcSigner.reshareNewParty(roomId, oldThreshold, newThreshold, keygenResult, allPartyKeygenIds)))
+        ]);
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        mpcPartiesPromise.catch(()=>{});
+        const [existingSettled, newSettled] = await Promise.race([
+            mpcPartiesPromise,
+            refused
+        ]);
+        const collectRejections = (results, keygenIds, role)=>results.reduce((acc, r, i)=>{
+                if (r.status === 'rejected') {
+                    acc.push({
+                        role,
+                        partyIndex: i,
+                        keygenId: keygenIds[i],
+                        error: r.reason
+                    });
+                }
+                return acc;
+            }, []);
+        const failures = [
+            ...collectRejections(existingSettled, existingClientKeygenIds, 'existingParty'),
+            ...collectRejections(newSettled, newClientKeygenIds, 'newParty')
+        ];
+        if (failures.length > 0) {
+            const firstError = failures[0].error;
+            const error = firstError instanceof Error ? firstError : new Error(String(firstError));
+            logError({
+                message: 'Reshare MPC ceremony party failures',
+                error,
+                context: {
+                    dynamicRequestId,
+                    roomId,
+                    failures: failures.map((f)=>({
+                            role: f.role,
+                            partyIndex: f.partyIndex,
+                            keygenId: f.keygenId,
+                            error: f.error instanceof Error ? f.error.message : String(f.error)
+                        })),
+                    existingSuccessCount: existingSettled.filter((r)=>r.status === 'fulfilled').length,
+                    newSuccessCount: newSettled.filter((r)=>r.status === 'fulfilled').length
+                }
+            });
+            throw error;
+        }
+        return {
+            existingReshareResults: existingSettled.map((r)=>r.value),
+            newReshareResults: newSettled.map((r)=>r.value)
+        };
+    }
+    async performDelegationOperation({ accountAddress, password, signedSessionId, sessionPublicKey, mfaToken, newThresholdSignatureScheme, revokeDelegation = false, useShareSetReshare = false, operationName, initialSignerRules, approvalQuorum, proposalId }) {
         try {
             const delegateToProjectEnvironment = this.featureFlags && this.featureFlags[FEATURE_FLAGS.ENABLE_DELEGATED_KEY_SHARES_FLAG] === true;
             if (!delegateToProjectEnvironment) {
@@ -7726,7 +7806,9 @@ class DynamicWalletClient {
                 mfaToken,
                 revokeDelegation,
                 // Do not attach rules on the revoke path.
-                initialSignerRules: revokeDelegation ? undefined : initialSignerRules
+                initialSignerRules: revokeDelegation ? undefined : initialSignerRules,
+                approvalQuorum,
+                proposalId
             });
         } catch (error) {
             logError({
@@ -7739,7 +7821,7 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async delegateKeyShares({ accountAddress, password = undefined, signedSessionId, sessionPublicKey, mfaToken, initialSignerRules }) {
+    async delegateKeyShares({ accountAddress, password = undefined, signedSessionId, sessionPublicKey, mfaToken, initialSignerRules, approvalQuorum, proposalId }) {
         var _this_featureFlags;
         const useShareSetReshare = ((_this_featureFlags = this.featureFlags) == null ? void 0 : _this_featureFlags[FEATURE_FLAGS.ENABLE_SHARE_SET_RESHARE]) === true;
         if (useShareSetReshare) {
@@ -7774,15 +7856,12 @@ class DynamicWalletClient {
             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
-            // + delegation case that returns newClientShareCount=1 (the share
-            // routed to the webhook) so the ceremony generates it correctly.
-            // FF off: legacy 2/2 → 2/3 reshare that mutates rootUser.
-            newThresholdSignatureScheme: useShareSetReshare ? ThresholdSignatureScheme.TWO_OF_TWO : ThresholdSignatureScheme.TWO_OF_THREE,
+            newThresholdSignatureScheme: this.delegationThresholdSignatureScheme(useShareSetReshare),
             operationName: 'delegateKeyShares',
             useShareSetReshare,
-            initialSignerRules
+            initialSignerRules,
+            approvalQuorum,
+            proposalId
         });
         const backupInfo = this.getRequiredWalletFromMap(accountAddress).clientKeySharesBackupInfo;
         const delegatedKeyShares = backupInfo.backups[BackupLocation.DELEGATED] || [];
@@ -7846,7 +7925,7 @@ class DynamicWalletClient {
    * operation logic lives in `./offlineRecovery.ts` (cloud-provider-agnostic,
    * so iCloud / other providers slot in there); this method just drives it
    * with the client instance and returns the exported set's own backups.
-   */ async offlineRecovery({ accountAddress, password = undefined, signedSessionId, sessionPublicKey, mfaToken, cloudProvider = DEFAULT_OFFLINE_RECOVERY_CLOUD_PROVIDER, cloudProviderAccessToken, recoveryEncryptionPublicKey }) {
+   */ async offlineRecovery({ accountAddress, password = undefined, signedSessionId, sessionPublicKey, mfaToken, cloudProvider = DEFAULT_OFFLINE_RECOVERY_CLOUD_PROVIDER, cloudProviderAccessToken, recoveryEncryptionPublicKey, approvalQuorum, proposalId }) {
         await performOfflineRecoveryOperation(this, {
             accountAddress,
             password,
@@ -7855,7 +7934,9 @@ class DynamicWalletClient {
             mfaToken,
             cloudProvider,
             cloudProviderAccessToken,
-            recoveryEncryptionPublicKey
+            recoveryEncryptionPublicKey,
+            approvalQuorum,
+            proposalId
         });
         // The exported set's own locations. Not `backups[cloudProvider]`: that is
         // rootUser's record for the provider, which this operation never writes.
@@ -7910,6 +7991,73 @@ class DynamicWalletClient {
             initiatorUserId
         });
     }
+    /** The scheme a delegation reshare moves the wallet to: share-set delegation mints its own 2/2 set. */ delegationThresholdSignatureScheme(useShareSetReshare) {
+        // 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
+        // + delegation case that returns newClientShareCount=1 (the share
+        // routed to the webhook) so the ceremony generates it correctly.
+        // FF off: legacy 2/2 → 2/3 reshare that mutates rootUser.
+        return useShareSetReshare ? ThresholdSignatureScheme.TWO_OF_TWO : ThresholdSignatureScheme.TWO_OF_THREE;
+    }
+    /**
+   * Builds the reshare Intent for a governed reshare entry point, to be
+   * signed with the session key and sent as `approvalQuorum` on that same
+   * entry point (`backupKeySharesToGoogleDrive`/`backupKeySharesToICloud`,
+   * `delegateKeyShares` or `offlineRecovery`).
+   *
+   * The Intent echoes the fields that entry point sends, so it is built here
+   * from the same wallet state. An offline recovery's Intent must also echo
+   * the recovery key the server will use: pass the one the `INTENT_REQUIRED`
+   * consent error carried. Makes no API call and starts no ceremony.
+   */ async prepareReshareIntent({ accountAddress, password = undefined, signedSessionId, businessAccountId, initiatorUserId, completeBy, operation, offlineRecoveryEncryptionKey }) {
+        if (operation === 'offlineRecovery' !== !!offlineRecoveryEncryptionKey) {
+            throw new Error('prepareReshareIntent: offlineRecoveryEncryptionKey is required for offlineRecovery, from its INTENT_REQUIRED consent error, and invalid otherwise');
+        }
+        // Refreshed from the server, as the backup entry point does before it
+        // picks its route: a wallet delegated from another device since it was
+        // cached backs up without a reshare, and must not get an intent for one.
+        await this.getWallet({
+            accountAddress,
+            password,
+            signedSessionId,
+            refresh: true
+        });
+        const walletData = this.getRequiredWalletFromMap(accountAddress);
+        const identity = {
+            accountAddress,
+            businessAccountId,
+            completeBy,
+            initiatorUserId
+        };
+        if (operation === 'delegatedAccess') {
+            var _this_featureFlags;
+            const useShareSetReshare = ((_this_featureFlags = this.featureFlags) == null ? void 0 : _this_featureFlags[FEATURE_FLAGS.ENABLE_SHARE_SET_RESHARE]) === true;
+            return createReshareIntent(_extends({}, identity, {
+                newThresholdSignatureScheme: this.delegationThresholdSignatureScheme(useShareSetReshare),
+                reshareType: 'delegatedAccess'
+            }));
+        }
+        if (operation === 'offlineRecovery') {
+            return createReshareIntent(_extends({}, identity, {
+                // performOfflineRecoveryOperation always pins the exported set at 2/2.
+                newThresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
+                offlineRecoveryEncryptionKey,
+                reshareType: 'offlineRecovery'
+            }));
+        }
+        // A cloud backup reshares only from 2/2, or from a non-delegated 2/3
+        // (backupKeySharesToCloudProvider); any other wallet backs up without a
+        // reshare, so there is nothing to approve.
+        const scheme = walletData.thresholdSignatureScheme;
+        const reshares = scheme === ThresholdSignatureScheme.TWO_OF_TWO || scheme === ThresholdSignatureScheme.TWO_OF_THREE && !hasDelegatedBackup(walletData.clientKeySharesBackupInfo, walletData.otherShareSets);
+        if (!reshares) {
+            throw new Error('prepareReshareIntent: this wallet backs up without a reshare, so no approval applies');
+        }
+        return createReshareIntent(_extends({}, identity, {
+            newThresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_THREE,
+            reshareType: 'cloudBackup'
+        }));
+    }
     async exportKey({ accountAddress, chainName, bitcoinConfig, password = undefined, signedSessionId, mfaToken, elevatedAccessToken, approvalQuorum, proposalId, traceContext }) {
         // Public entry point delegates to the private implementation. Keeping the
         // `staleShareRetry` flag off the public signature mirrors sign/refresh/
@@ -9224,10 +9372,10 @@ class DynamicWalletClient {
             recordedKeygenIds
         };
         // Per-wallet operations (e.g. updatePassword) emit one detection per wallet; keep the
-        // warn to one per burst so log monitors count stale sessions, not stale wallets.
+        // warn to one per burst so log monitors count stale sessions, not stale wallets. In-window
+        // repeats emit nothing — the count is folded into the next burst's warn.
         if (Date.now() - DynamicWalletClient.lastStaleSharesWarnAt < DynamicWalletClient.STALE_SHARES_WARN_WINDOW_MS) {
             DynamicWalletClient.suppressedStaleSharesWarns++;
-            this.logger.debug('[storeEncryptedBackupByWallet] Stale local shares detected; refreshing local storage (deduplicated)', staleSharesLogContext);
         } else {
             DynamicWalletClient.lastStaleSharesWarnAt = Date.now();
             const suppressedStaleShareWarnings = DynamicWalletClient.suppressedStaleSharesWarns;
@@ -9246,6 +9394,7 @@ class DynamicWalletClient {
             resolvedSessionId = undefined;
         }
         let localSharesRefreshed = false;
+        let recoveryErrorReason;
         if (resolvedSessionId) {
             // The recovery decrypt key is whatever the server's blob was encrypted with — not the
             // caller's `password` arg, which is the key we'll re-encrypt the *next* upload with.
@@ -9267,17 +9416,14 @@ class DynamicWalletClient {
                 });
                 localSharesRefreshed = true;
             } catch (recoveryError) {
-                this.logger.error('[storeEncryptedBackupByWallet] Failed to refresh local shares from server', {
-                    accountAddress,
-                    walletId: walletData.walletId,
-                    error: recoveryError instanceof Error ? recoveryError.message : String(recoveryError)
-                });
+                recoveryErrorReason = this.logStaleSharesRefreshFailure(recoveryError, accountAddress, walletData.walletId);
             }
         }
         this.logStaleSharesRecoveryOutcome({
             context: staleSharesLogContext,
             localSharesRefreshed,
-            resolvedSessionId
+            resolvedSessionId,
+            recoveryErrorReason
         });
         throw new StaleLocalSharesError({
             accountAddress,
@@ -9286,9 +9432,26 @@ class DynamicWalletClient {
             localSharesRefreshed
         });
     }
+    // Network failures are transient (the caller retries), so they log at warn;
+    // everything else stays error.
+    logStaleSharesRefreshFailure(recoveryError, accountAddress, walletId) {
+        const reason = classifyPasswordBackupError(recoveryError);
+        const refreshFailureContext = {
+            accountAddress,
+            walletId,
+            error: recoveryError instanceof Error ? recoveryError.message : String(recoveryError),
+            recoveryErrorReason: reason
+        };
+        if (reason === 'network') {
+            this.logger.warn('[storeEncryptedBackupByWallet] Failed to refresh local shares from server', refreshFailureContext);
+        } else {
+            this.logger.error('[storeEncryptedBackupByWallet] Failed to refresh local shares from server', refreshFailureContext);
+        }
+        return reason;
+    }
     // One outcome line per stale event so monitors count recoverable vs
     // unrecoverable staleness (refreshOutcome facet) rather than raw detections.
-    logStaleSharesRecoveryOutcome({ context, localSharesRefreshed, resolvedSessionId }) {
+    logStaleSharesRecoveryOutcome({ context, localSharesRefreshed, resolvedSessionId, recoveryErrorReason }) {
         let refreshOutcome;
         if (localSharesRefreshed) {
             refreshOutcome = 'refreshed';
@@ -9299,10 +9462,14 @@ class DynamicWalletClient {
         }
         const recoveryContext = _extends({}, context, {
             refreshOutcome,
-            sessionId: resolvedSessionId
+            sessionId: resolvedSessionId,
+            recoveryErrorReason
         });
         if (localSharesRefreshed) {
             this.logger.info('[storeEncryptedBackupByWallet] Stale local shares recovery; caller should retry', recoveryContext);
+        } else if (recoveryErrorReason === 'network') {
+            // Connectivity blips are transient, so they aren't an oncall-actionable error.
+            this.logger.warn('[storeEncryptedBackupByWallet] Stale local shares recovery hit a network error; backup refused', recoveryContext);
         } else {
             this.logger.error('[storeEncryptedBackupByWallet] Stale local shares recovery failed; backup refused', recoveryContext);
         }
@@ -10058,7 +10225,7 @@ class DynamicWalletClient {
    * - For 2-of-2 wallets: Automatically reshares to 2-of-3 threshold, then distributes shares (1 to backend, 1 to cloud)
    * - For non-delegated 2-of-3 wallets: same-scheme reshare to mint a fresh recovery share
    * - For delegated 2-of-3 (and other) wallets: storeEncryptedBackupByWallet backs up to backend and cloud
-   */ async backupKeySharesToCloudProvider({ accountAddress, password, signedSessionId, sessionPublicKey, backupLocation, googleDriveAccessToken, googleDriveTokenSource }) {
+   */ async backupKeySharesToCloudProvider({ accountAddress, password, signedSessionId, sessionPublicKey, backupLocation, googleDriveAccessToken, googleDriveTokenSource, approvalQuorum, proposalId }) {
         try {
             await this.getWallet({
                 accountAddress,
@@ -10082,7 +10249,10 @@ class DynamicWalletClient {
                         backupLocation
                     ],
                     googleDriveAccessToken,
-                    googleDriveTokenSource
+                    googleDriveTokenSource,
+                    cloudBackup: true,
+                    approvalQuorum,
+                    proposalId
                 });
             } else if (currentThresholdSignatureScheme === ThresholdSignatureScheme.TWO_OF_THREE && !hasDelegatedBackup(walletData.clientKeySharesBackupInfo, walletData.otherShareSets)) {
                 await this.reshareNonDelegatedTwoOfThree({
@@ -10092,7 +10262,9 @@ class DynamicWalletClient {
                     signedSessionId,
                     sessionPublicKey,
                     googleDriveAccessToken,
-                    googleDriveTokenSource
+                    googleDriveTokenSource,
+                    approvalQuorum,
+                    proposalId
                 });
             } else {
                 await this.storeEncryptedBackupByWallet({
@@ -10124,7 +10296,7 @@ class DynamicWalletClient {
    * reshare that mints a fresh recovery share. The fresh share is redistributed to
    * every provider already holding a backup plus the requested one,
    * restricted to providers the reshare can deliver to.
-   */ async reshareNonDelegatedTwoOfThree({ accountAddress, backupLocation, password, signedSessionId, sessionPublicKey, googleDriveAccessToken, googleDriveTokenSource }) {
+   */ async reshareNonDelegatedTwoOfThree({ accountAddress, backupLocation, password, signedSessionId, sessionPublicKey, googleDriveAccessToken, googleDriveTokenSource, approvalQuorum, proposalId }) {
         const walletData = this.getRequiredWalletFromMap(accountAddress);
         const cloudProviders = new Set([
             ...getActiveCloudProviders(walletData.clientKeySharesBackupInfo).filter((provider)=>provider === BackupLocation.GOOGLE_DRIVE || provider === BackupLocation.ICLOUD),
@@ -10159,7 +10331,10 @@ class DynamicWalletClient {
             sessionPublicKey,
             cloudProviders: Array.from(cloudProviders),
             googleDriveAccessToken: resolvedDrive.googleDriveAccessToken,
-            googleDriveTokenSource: resolvedDrive.googleDriveTokenSource
+            googleDriveTokenSource: resolvedDrive.googleDriveTokenSource,
+            cloudBackup: true,
+            approvalQuorum,
+            proposalId
         });
     }
     /**
@@ -10229,7 +10404,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, sessionPublicKey, googleDriveAccessToken }) {
+   */ async backupKeySharesToGoogleDrive({ accountAddress, password, signedSessionId, sessionPublicKey, googleDriveAccessToken, approvalQuorum, proposalId }) {
         // 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
@@ -10267,7 +10442,9 @@ class DynamicWalletClient {
                 googleDriveAccessToken: resolvedAccessToken,
                 // Persist which token source backed up the Google Drive location for
                 // audit (enum only — never the token value).
-                googleDriveTokenSource: tokenSource
+                googleDriveTokenSource: tokenSource,
+                approvalQuorum,
+                proposalId
             });
             success = true;
         } finally{
@@ -10340,13 +10517,23 @@ 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, sessionPublicKey }) {
+   */ async backupKeySharesToICloud({ accountAddress, password, signedSessionId, sessionPublicKey, approvalQuorum, proposalId }) {
+        // Refreshed from the server, as the Google Drive backup and
+        // prepareReshareIntent do: the route (reshare or not) must be picked from
+        // the same wallet state the reshare intent was built from.
+        await this.getWallet({
+            accountAddress,
+            signedSessionId,
+            refresh: true
+        });
         return this.backupKeySharesToCloudProvider({
             accountAddress,
             password,
             signedSessionId,
             sessionPublicKey,
-            backupLocation: BackupLocation.ICLOUD
+            backupLocation: BackupLocation.ICLOUD,
+            approvalQuorum,
+            proposalId
         });
     }
     /**
@@ -11765,7 +11952,6 @@ class DynamicWalletClient {
         });
         this.debug = Boolean(debug);
         this.featureFlags = featureFlags || {};
-        WalletQueueManager.setShareLockEnabled(this.featureFlags[FEATURE_FLAGS.ENABLE_SHARE_WEB_LOCK_FLAG] === true);
         this.argon2idRebackupTargets = argon2idRebackupTargets || [];
         // setup storage for walletMap metadata (used regardless of secureStorage)
         if (supportsLocalStorage()) {