@dynamic-labs-wallet/browser 1.0.2 → 1.0.3

package/index.cjs

@@ -229,6 +229,25 @@ class InvalidPasswordError extends Error {
         this.name = 'InvalidPasswordError';
     }
 }
+const KEY_SHARE_DECRYPTION_ERROR = 'Decryption failed.';
+/**
+ * Thrown when a key share cannot be decrypted but no user-supplied password was
+ * involved. Distinct from InvalidPasswordError, which is reserved for cases
+ * where a user-entered password fails to decrypt a password-encrypted wallet.
+ *
+ * Internal-only signal: the user-facing message is deliberately generic so it
+ * does not leak implementation detail (e.g. environmentId fallback,
+ * cross-environment cipher, KDF/version mismatch). The `name` and any attached
+ * `cause` carry the real diagnostic for logs / monitoring.
+ */ class KeyShareDecryptionError extends Error {
+    constructor(options){
+        super(KEY_SHARE_DECRYPTION_ERROR);
+        this.name = 'KeyShareDecryptionError';
+        if ((options == null ? void 0 : options.cause) !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
 /**
  * Check if an error is an OperationError from SubtleCrypto.decrypt,
  * which indicates authentication failure (wrong password/derived key)
@@ -514,7 +533,15 @@ const writeCachedReason = (error, reason)=>{
     // Frozen/sealed errors — ignore, just lose the cache on this path.
     }
 };
+const isKeyShareDecryptionError = (error)=>error instanceof KeyShareDecryptionError || error instanceof Error && error.name === 'KeyShareDecryptionError';
 const computeReason = (error)=>{
+    // KeyShareDecryptionError represents a system-side decryption failure where
+    // no user password was involved (e.g. envId-fallback failed on a
+    // non-password-encrypted wallet). Classify ahead of the InvalidPasswordError
+    // check so it doesn't get mislabeled as `wrong_password`.
+    if (isKeyShareDecryptionError(error)) {
+        return 'decryption_failure';
+    }
     if (isPasswordMismatchError(error)) {
         return 'wrong_password';
     }
@@ -1053,6 +1080,7 @@ const logRetryExhausted = (operationName, maxAttempts, errorContext, logContext)
     if ((error == null ? void 0 : error.isRetryable) === false) return true;
     if (isPasswordMismatchError(error)) return true;
     if (error instanceof InvalidPasswordError) return true;
+    if (error instanceof KeyShareDecryptionError) return true;
     const message = error instanceof Error ? error.message : '';
     if (!message) return false;
     return NON_RETRYABLE_CEREMONY_ERROR_MESSAGES.some((msg)=>message.includes(msg));
@@ -2097,6 +2125,50 @@ const createDynamicOnlyDistribution = ({ allShares })=>({
 /** Track which wallets are currently executing inside a sign operation.
    * Used to prevent deadlocks when recovery is called from within a sign op. */ WalletQueueManager.walletsWithActiveSignOp = new Map();
 
+// Pure routing helper: maps a completed reshare ceremony's results into the
+// ShareDistribution that storage/publish should follow. Lives outside the
+// client class so it's straightforward to reason about and unit-test
+// without spinning up DynamicWalletClient.
+const selectReshareDistribution = ({ resolvedDelegation, resolvedCloudProviders, existingReshareResults, newReshareResults })=>{
+    const allClientShares = [
+        ...existingReshareResults,
+        ...newReshareResults
+    ];
+    // Share-set delegation signal: same-parties reshare with zero new client
+    // party. The refreshed rootUser-client output IS the delegated share —
+    // it goes to the webhook out-of-band, NOT to Dynamic backup, and local
+    // cache stays with gen1.
+    if (resolvedDelegation && newReshareResults.length === 0 && existingReshareResults.length === 1) {
+        return {
+            clientShares: [],
+            cloudProviderShares: {},
+            delegatedShare: existingReshareResults[0]
+        };
+    }
+    if (resolvedDelegation && resolvedCloudProviders.length > 0) {
+        return createDelegationWithCloudProviderDistribution({
+            providers: resolvedCloudProviders,
+            existingShares: existingReshareResults,
+            delegatedShare: newReshareResults[0]
+        });
+    }
+    if (resolvedDelegation) {
+        return createDelegationOnlyDistribution({
+            existingShares: existingReshareResults,
+            delegatedShare: newReshareResults[0]
+        });
+    }
+    if (resolvedCloudProviders.length > 0) {
+        return createCloudProviderDistribution({
+            providers: resolvedCloudProviders,
+            allShares: allClientShares
+        });
+    }
+    return createDynamicOnlyDistribution({
+        allShares: allClientShares
+    });
+};
+
 const ALG_LABEL_RSA = 'HYBRID-RSA-AES-256';
 /**
  * Convert base64 to base64url encoding
@@ -3582,7 +3654,7 @@ class DynamicWalletClient {
    *   existingClientKeyShares: ClientKeyShare[]
    * }>} Object containing new and existing client keygen results, IDs and shares
    * @todo Support higher to lower reshare strategies
-   */ async reshareStrategy({ chainName, wallet, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme }) {
+   */ async reshareStrategy({ chainName, wallet, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, delegateToProjectEnvironment }) {
         const bitcoinConfig = this.getBitcoinConfigForChain(chainName, accountAddress);
         const mpcSigner = getMPCSigner({
             chainName,
@@ -3592,7 +3664,8 @@ class DynamicWalletClient {
         // Determine share counts based on threshold signature schemes
         const { newClientShareCount, existingClientShareCount } = core.getReshareConfig({
             oldThresholdSignatureScheme,
-            newThresholdSignatureScheme
+            newThresholdSignatureScheme,
+            delegateToProjectEnvironment
         });
         // Create new client shares
         const newClientInitKeygenResults = await Promise.all(Array.from({
@@ -3698,16 +3771,20 @@ class DynamicWalletClient {
             throw backupError;
         }
     }
-    // Rotates walletMap.shareSetId when a ceremony_complete event reports a
-    // new rootUser share set. Skipped for `delegated` (rootUser unchanged;
-    // the delegation flow owns the otherShareSets[] write), `server`, and
-    // empty payloads (legacy redcoast that predates the share-set rollout —
-    // server falls back to walletId resolution on the follow-up backup call).
+    // Persists the ceremony_complete payload into the wallet map.
+    // - rootUser → rotate walletMap.shareSetId (if it actually changed).
+    // - delegated → append/replace under otherShareSets[] via recordDelegatedShareSet
+    //   (requires newThresholdSignatureScheme passed in by the reshare caller).
+    //   Reshare delegation flow owns this branch; refresh hits the non-rootUser
+    //   skip path below because newThresholdSignatureScheme isn't threaded.
+    // - server / undefined → no-op with a skip log so DataDog shows the path
+    //   (undefined is legacy redcoast that predates the share-set rollout —
+    //   server falls back to walletId resolution on the follow-up backup call).
     //
     // Each skip reason is logged distinctly so operators can grep DataDog for
     // "legacy server callbacks" vs "delegation skips" vs "no-op same id"
     // separately — three operationally different states.
-    rotateRootUserShareSetIdIfChanged({ accountAddress, wallet, ceremony, shareSetId, shareSetType, extraContext }) {
+    rotateRootUserShareSetIdIfChanged({ accountAddress, wallet, ceremony, shareSetId, shareSetType, newThresholdSignatureScheme, extraContext }) {
         const baseContext = _extends({
             walletId: wallet.walletId,
             ceremony
@@ -3724,10 +3801,20 @@ class DynamicWalletClient {
             });
             return;
         }
+        if (shareSetType === 'delegated' && newThresholdSignatureScheme) {
+            this.recordDelegatedShareSet({
+                accountAddress,
+                wallet,
+                newShareSetId: shareSetId,
+                newThresholdSignatureScheme
+            });
+            return;
+        }
         if (shareSetType !== 'rootUser') {
-            // 'delegated' → delegation flow owns the otherShareSets[] write (#947).
-            // 'server'    → internal server share set, not for SDK rotation.
-            // undefined   → server emitted partial payload (already warned upstream).
+            // 'delegated' (no newThresholdSignatureScheme, e.g. refresh) → SDK doesn't
+            // own the otherShareSets[] write from refresh.
+            // 'server' → internal server share set, not for SDK rotation.
+            // undefined → server emitted partial payload (already warned upstream).
             this.logger.info('[WaasShareSet] rotation skipped: non-rootUser share-set type', {
                 context: _extends({}, baseContext, {
                     shareSetType,
@@ -3754,6 +3841,38 @@ class DynamicWalletClient {
             shareSetId
         });
     }
+    // Records a new `delegated` share set under wallet.otherShareSets[],
+    // replacing an existing delegated entry if one is already there (rather
+    // than appending duplicates on retry). Only reachable from the reshare
+    // delegation flow — refresh doesn't thread newThresholdSignatureScheme
+    // so it falls through to the skip path before reaching here.
+    recordDelegatedShareSet({ accountAddress, wallet, newShareSetId, newThresholdSignatureScheme }) {
+        const walletProps = this.getWalletFromMap(accountAddress);
+        var _walletProps_otherShareSets;
+        const existing = (_walletProps_otherShareSets = walletProps == null ? void 0 : walletProps.otherShareSets) != null ? _walletProps_otherShareSets : [];
+        const newEntry = {
+            shareSetId: newShareSetId,
+            shareSetType: 'delegated',
+            thresholdSignatureScheme: newThresholdSignatureScheme,
+            createdAt: new Date().toISOString()
+        };
+        const delegatedIdx = existing.findIndex((s)=>s.shareSetType === 'delegated');
+        const updated = delegatedIdx >= 0 ? existing.map((s, i)=>i === delegatedIdx ? newEntry : s) : [
+            ...existing,
+            newEntry
+        ];
+        this.logger.info('[WaasShareSet] delegated shareSetId added by reshare ceremony', {
+            context: {
+                walletId: wallet.walletId,
+                rootUserShareSetId: wallet.shareSetId,
+                delegatedShareSetId: newShareSetId,
+                replacedExistingDelegated: delegatedIdx >= 0
+            }
+        });
+        this.updateWalletMap(accountAddress, {
+            otherShareSets: updated
+        });
+    }
     async internalReshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, cloudProviders = [], delegateToProjectEnvironment = false, mfaToken, elevatedAccessToken, revokeDelegation = false, hasAttemptedKeyShareRecovery = false, googleDriveAccessToken }) {
         const dynamicRequestId = uuid.v4();
         // Password validation - wrapped in try-catch for consistent error handling
@@ -3796,7 +3915,8 @@ class DynamicWalletClient {
         try {
             const { existingClientShareCount } = core.getReshareConfig({
                 oldThresholdSignatureScheme,
-                newThresholdSignatureScheme
+                newThresholdSignatureScheme,
+                delegateToProjectEnvironment: resolvedDelegation
             });
             const wallet = await this.getWallet({
                 accountAddress,
@@ -3810,11 +3930,14 @@ class DynamicWalletClient {
                 accountAddress,
                 wallet,
                 oldThresholdSignatureScheme,
-                newThresholdSignatureScheme
+                newThresholdSignatureScheme,
+                delegateToProjectEnvironment: resolvedDelegation
             });
-            // Ensure existing client key shares exist before reshare
-            if (existingClientKeyShares.length === 0) {
-                throw new Error(`Client key shares are required for reshare operation but none were found for account address: ${accountAddress}`);
+            // Ensure existing client key shares match what getReshareConfig expected.
+            // For most flows this is >= 1; for 2/2 → 2/2 + delegation it's 0 (the
+            // ceremony has no surviving client-side party from the old quorum).
+            if (existingClientKeyShares.length < existingClientShareCount) {
+                throw new Error(`Expected ${existingClientShareCount} existing client key share(s) for reshare operation but only found ${existingClientKeyShares.length} for account address: ${accountAddress}`);
             }
             const clientKeygenIds = [
                 ...newClientKeygenIds,
@@ -3878,6 +4001,7 @@ class DynamicWalletClient {
                         ceremony: 'reshare',
                         shareSetId,
                         shareSetType,
+                        newThresholdSignatureScheme,
                         extraContext: {
                             oldThresholdSignatureScheme,
                             newThresholdSignatureScheme,
@@ -4001,41 +4125,12 @@ class DynamicWalletClient {
                 }
                 throw reshareError;
             }
-            const allClientShares = [
-                ...existingReshareResults,
-                ...newReshareResults
-            ];
-            let distribution;
-            // Generic distribution logic - works with any cloud providers
-            // Use effective* variables which may have been populated from existing wallet state
-            if (resolvedDelegation && resolvedCloudProviders.length > 0) {
-                // Delegation + Cloud Providers: Client's existing share backs up to both Dynamic and cloud providers.
-                // The new share goes to the webhook for delegation.
-                distribution = createDelegationWithCloudProviderDistribution({
-                    providers: resolvedCloudProviders,
-                    existingShares: existingReshareResults,
-                    delegatedShare: newReshareResults[0]
-                });
-            } else if (resolvedDelegation) {
-                // Delegation only: Client's existing share backs up to Dynamic.
-                // The new share goes to the webhook for delegation. No cloud provider backup.
-                distribution = createDelegationOnlyDistribution({
-                    existingShares: existingReshareResults,
-                    delegatedShare: newReshareResults[0]
-                });
-            } else if (resolvedCloudProviders.length > 0) {
-                // Cloud Providers only: Split shares between Dynamic (N-1) and cloud providers (1).
-                // The last share (new share) goes to cloud providers.
-                distribution = createCloudProviderDistribution({
-                    providers: resolvedCloudProviders,
-                    allShares: allClientShares
-                });
-            } else {
-                // No delegation, no cloud providers: All shares go to Dynamic backend only.
-                distribution = createDynamicOnlyDistribution({
-                    allShares: allClientShares
-                });
-            }
+            const distribution = selectReshareDistribution({
+                resolvedDelegation,
+                resolvedCloudProviders,
+                existingReshareResults,
+                newReshareResults
+            });
             this.updateWalletMap(accountAddress, {
                 thresholdSignatureScheme: newThresholdSignatureScheme
             });
@@ -4094,10 +4189,22 @@ class DynamicWalletClient {
             });
             // Store client key shares to storage (localStorage or secureStorage)
             // only after backup succeeds.
-            await this.setClientKeySharesToStorage({
-                accountAddress,
-                clientKeyShares: distribution.clientShares
-            });
+            //
+            // Share-set delegation (FF=on) skips this entirely — the ceremony
+            // output's refreshed rootUser-client share went to the webhook
+            // (delegatedShare), and the original gen1 rootUser-client share must
+            // stay in local cache so the user can still sign rootUser. See the
+            // mixed-share-sign isolation property tested in
+            // `wallet-service/scripts/twoOfTwoReshareExperiment.ts`. Calling this
+            // with `clientShares: []` would clear the local cache (per the
+            // method's "full replacement" semantics), breaking signing until
+            // recovery refetches from Dynamic.
+            if (distribution.clientShares.length > 0) {
+                await this.setClientKeySharesToStorage({
+                    accountAddress,
+                    clientKeyShares: distribution.clientShares
+                });
+            }
             // 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
@@ -4139,7 +4246,7 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async performDelegationOperation({ accountAddress, password, signedSessionId, mfaToken, newThresholdSignatureScheme, revokeDelegation = false, operationName }) {
+    async performDelegationOperation({ accountAddress, password, signedSessionId, 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) {
@@ -4156,8 +4263,11 @@ class DynamicWalletClient {
             }
             const walletData = this.getWalletFromMap(accountAddress);
             const currentThresholdSignatureScheme = walletData.thresholdSignatureScheme;
-            // Get active cloud providers to maintain existing backups
-            const activeProviders = getActiveCloudProviders(walletData == null ? void 0 : walletData.clientKeySharesBackupInfo);
+            // Under the share-set reshare flow, rootUser is not mutated — the
+            // delegation creates a separate `delegated` share set. So we don't
+            // re-pin existing cloud providers; preservation is irrelevant when the
+            // primary share set is untouched.
+            const activeProviders = useShareSetReshare ? [] : getActiveCloudProviders(walletData == null ? void 0 : walletData.clientKeySharesBackupInfo);
             await this.reshare({
                 chainName: walletData.chainName,
                 accountAddress,
@@ -4182,19 +4292,82 @@ class DynamicWalletClient {
         }
     }
     async delegateKeyShares({ accountAddress, password = undefined, signedSessionId, 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) {
+            var _this_getWalletFromMap;
+            // FF on: delegation creates a separate `delegated` share set without
+            // touching rootUser. If the wallet already has one, this is a no-op.
+            const existingDelegated = getDelegatedShareSet((_this_getWalletFromMap = this.getWalletFromMap(accountAddress)) == null ? void 0 : _this_getWalletFromMap.otherShareSets);
+            if (existingDelegated) {
+                var _this_getWalletFromMap1;
+                this.logger.info('[WaasShareSet] delegateKeyShares no-op — wallet already has a delegated share set', {
+                    accountAddress,
+                    delegatedShareSetId: existingDelegated.shareSetId
+                });
+                const backupInfo = (_this_getWalletFromMap1 = this.getWalletFromMap(accountAddress)) == null ? void 0 : _this_getWalletFromMap1.clientKeySharesBackupInfo;
+                return (backupInfo == null ? void 0 : backupInfo.backups[core.BackupLocation.DELEGATED]) || [];
+            }
+            this.logger.info('[WaasShareSet] delegateKeyShares using share-set reshare path', {
+                accountAddress
+            });
+        }
         await this.performDelegationOperation({
             accountAddress,
             password,
             signedSessionId,
             mfaToken,
-            newThresholdSignatureScheme: core.ThresholdSignatureScheme.TWO_OF_THREE,
-            operationName: 'delegateKeyShares'
+            // 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 ? core.ThresholdSignatureScheme.TWO_OF_TWO : core.ThresholdSignatureScheme.TWO_OF_THREE,
+            operationName: 'delegateKeyShares',
+            useShareSetReshare
         });
         const backupInfo = this.getWalletFromMap(accountAddress).clientKeySharesBackupInfo;
         const delegatedKeyShares = backupInfo.backups[core.BackupLocation.DELEGATED] || [];
         return delegatedKeyShares;
     }
     async revokeDelegation({ accountAddress, password = undefined, signedSessionId, 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) {
+            var _this_getWalletFromMap;
+            const wallet = await this.getWallet({
+                accountAddress,
+                walletOperation: core.WalletOperation.NO_OPERATION,
+                password,
+                signedSessionId
+            });
+            const delegatedShareSet = getDelegatedShareSet((_this_getWalletFromMap = this.getWalletFromMap(accountAddress)) == null ? void 0 : _this_getWalletFromMap.otherShareSets);
+            if (!delegatedShareSet) {
+                this.logger.info('[WaasShareSet] revokeDelegation called but no delegated share set found', {
+                    accountAddress
+                });
+                return;
+            }
+            this.logger.info('[WaasShareSet] revokeDelegation via share-set REST DELETE (no MPC ceremony)', {
+                accountAddress,
+                delegatedShareSetId: delegatedShareSet.shareSetId,
+                walletId: wallet.walletId
+            });
+            await this.apiClient.revokeDelegation({
+                walletId: wallet.walletId,
+                shareSetId: delegatedShareSet.shareSetId,
+                signedSessionId,
+                dynamicRequestId: uuid.v4().replaceAll('-', '')
+            });
+            // Refresh wallet state so otherShareSets / backups reflect the cleared delegation
+            await this.getWallet({
+                accountAddress,
+                walletOperation: core.WalletOperation.NO_OPERATION,
+                password,
+                signedSessionId
+            });
+            return;
+        }
         await this.performDelegationOperation({
             accountAddress,
             password,
@@ -4741,7 +4914,7 @@ class DynamicWalletClient {
             hasDelegatedShare: !!distribution.delegatedShare
         }));
         try {
-            var _backupData_locationsWithKeyShares, _backupData_locationsWithKeyShares1;
+            var _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;
@@ -4836,10 +5009,24 @@ class DynamicWalletClient {
                     googleDriveAccessToken
                 }));
             }
+            // When this ceremony minted a separate `delegated` share set (FF=on
+            // path), backup activation must target that share set — not rootUser —
+            // so `/delegatedAccess/delivery` and `/backup/locations` resolve to the
+            // pending delegated row instead of mutating rootUser. The FF=off path
+            // leaves `otherShareSets` empty and falls back to rootUser, matching
+            // legacy in-place delegation behavior.
+            //
+            // Read otherShareSets fresh from the wallet map — `recordDelegatedShareSet`
+            // wrote the new entry during `ceremony_complete`, which fired between
+            // when `walletData` was captured at the top of this method and now.
+            const freshOtherShareSets = (_this_getWalletFromMap = this.getWalletFromMap(accountAddress)) == null ? void 0 : _this_getWalletFromMap.otherShareSets;
+            const delegatedShareSet = distribution.delegatedShare ? getDelegatedShareSet(freshOtherShareSets) : undefined;
+            var _delegatedShareSet_shareSetId;
+            const targetShareSetId = (_delegatedShareSet_shareSetId = delegatedShareSet == null ? void 0 : delegatedShareSet.shareSetId) != null ? _delegatedShareSet_shareSetId : walletData.shareSetId;
             if (distribution.delegatedShare) {
                 uploadPromises.push(retryPromise(()=>this.publishDelegatedShare({
                         walletId: walletData.walletId,
-                        shareSetId: walletData.shareSetId,
+                        shareSetId: targetShareSetId,
                         delegatedShare: distribution.delegatedShare,
                         signedSessionId: resolvedSignedSessionId,
                         dynamicRequestId,
@@ -4869,7 +5056,10 @@ class DynamicWalletClient {
             // won't fix.
             const backupData = await retryPromise(()=>this.apiClient.markKeySharesAsBackedUp({
                     walletId: walletData.walletId,
-                    shareSetId: walletData.shareSetId,
+                    // Same routing rule as publishDelegatedShare above: when this
+                    // ceremony minted a separate `delegated` share set, the atomic
+                    // swap in /backup/locations must activate THAT row, not rootUser.
+                    shareSetId: targetShareSetId,
                     locations,
                     dynamicRequestId,
                     passwordUpdateBatchId
@@ -5267,13 +5457,35 @@ class DynamicWalletClient {
     }
     async decryptKeyShare({ keyShare, password }) {
         const decodedKeyShare = JSON.parse(Buffer.from(keyShare, 'base64').toString());
-        const decryptedKeyShare = await decryptData({
-            data: decodedKeyShare,
-            password: password != null ? password : this.environmentId
-        });
-        this.logPasswordSharePresence(password, 'decrypt');
-        const deserializedKeyShare = JSON.parse(decryptedKeyShare);
-        return deserializedKeyShare;
+        // Track whether a user-supplied password was provided so we can emit a
+        // distinct error class on failure. The default `environmentId` fallback is
+        // applied here (and only here) so the original `password` argument retains
+        // the caller's intent — see `recoverEncryptedBackupByWallet` / `getWallet`,
+        // which no longer apply their own fallback.
+        const usedDefaultPassword = !password;
+        const effectivePassword = password != null ? password : this.environmentId;
+        try {
+            const decryptedKeyShare = await decryptData({
+                data: decodedKeyShare,
+                password: effectivePassword
+            });
+            this.logPasswordSharePresence(password, 'decrypt');
+            const deserializedKeyShare = JSON.parse(decryptedKeyShare);
+            return deserializedKeyShare;
+        } catch (error) {
+            // When no user password was supplied, an InvalidPasswordError is
+            // misleading — the user never entered a password, so the "wrong password"
+            // framing doesn't apply. Re-throw as a distinct system-side error so
+            // dashboards/logs classify it as `decryption_failure` instead of
+            // `wrong_password`, and surface that the cause is most likely an
+            // environment-ID mismatch (e.g. wallet encrypted in another environment).
+            if (usedDefaultPassword && error instanceof InvalidPasswordError) {
+                throw new KeyShareDecryptionError({
+                    cause: error
+                });
+            }
+            throw error;
+        }
     }
     /**
    * Validates that the provided password is consistent with existing encrypted wallets.
@@ -5529,9 +5741,12 @@ class DynamicWalletClient {
                 userId: this.userId
             });
             const dynamicKeyShares = data.keyShares.filter((keyShare)=>keyShare.encryptedAccountCredential !== null && keyShare.backupLocation === core.BackupLocation.DYNAMIC);
-            const decryptedKeyShares = await Promise.all(dynamicKeyShares.map((keyShare)=>this.decryptKeyShare({
+            const decryptedKeyShares = await Promise.all(dynamicKeyShares.map((keyShare)=>// `decryptKeyShare` owns the `environmentId` fallback; passing
+                // `password` (possibly undefined) lets it distinguish a user-supplied
+                // password failure from an envId-fallback failure.
+                this.decryptKeyShare({
                     keyShare: keyShare.encryptedAccountCredential,
-                    password: password != null ? password : this.environmentId
+                    password
                 })));
             if (storeRecoveredShares) {
                 await this.setClientKeySharesToStorage({
@@ -6232,9 +6447,11 @@ class DynamicWalletClient {
                     return wallet;
                 }
                 // TODO(zfaizal2): throw error if signedSessionId is not provided after service deploy
+                // `decryptKeyShare` owns the environmentId fallback so the original
+                // `password` (possibly undefined) propagates here.
                 const decryptedKeyShares = await this.recoverEncryptedBackupByWallet({
                     accountAddress,
-                    password: password != null ? password : this.environmentId,
+                    password,
                     walletOperation: walletOperation,
                     signedSessionId,
                     shareCount