refactor(sdk-core): clean up backup key fallback in upgradeEncryption (WCN-174)

The retry-with-original-passphrase fallback is specific to keys encrypted
at wallet creation (backup key, boxA, boxB — these are never re-encrypted
on password change). It doesn't belong on the generic Keychains.reencryptAsV2
primitive, which was leaking backup-key context into its error message.

- Keychains.reencryptAsV2 is now a pure primitive: decrypt with
  passphrase, re-encrypt as v2, surface errors directly
- Fallback moves to a private Wallet.reencryptCreationTimeKey helper,
  used only for backup/boxA/boxB paths where the semantics apply
- Error messages now name the specific key that failed to decrypt

TICKET: WCN-174

Author: pranavjain97

modules/bitgo/test/v2/unit/keychains.ts

@@ -1197,7 +1197,7 @@ describe('V2 Keychains', function () {
   });
 
   describe('reencryptAsV2', function () {
-    it('decrypts a v1 envelope with the current passphrase and re-encrypts as v2', async function () {
+    it('decrypts a v1 envelope with the passphrase and re-encrypts as v2', async function () {
       const prv = 'thePrivateKey';
       const encryptedV1 = await bitgo.encrypt({ input: prv, password: 'myPass', encryptionVersion: 1 });
       JSON.parse(encryptedV1).v.should.equal(1);
@@ -1207,30 +1207,6 @@ describe('V2 Keychains', function () {
       (await bitgo.decrypt({ input: result, password: 'myPass' })).should.equal(prv);
     });
 
-    it('falls back to originalPassphrase when the current passphrase fails to decrypt', async function () {
-      const prv = 'thePrivateKey';
-      const encryptedWithOriginal = await bitgo.encrypt({
-        input: prv,
-        password: 'originalPass',
-        encryptionVersion: 1,
-      });
-
-      const result = await keychains.reencryptAsV2(encryptedWithOriginal, 'currentPass', 'originalPass');
-      JSON.parse(result).v.should.equal(2);
-      (await bitgo.decrypt({ input: result, password: 'currentPass' })).should.equal(prv);
-      await bitgo.decrypt({ input: result, password: 'originalPass' }).should.be.rejected();
-    });
-
-    it('throws with a helpful message when decryption fails and no originalPassphrase is provided', async function () {
-      const encrypted = await bitgo.encrypt({ input: 'prv', password: 'realPass', encryptionVersion: 1 });
-      await keychains.reencryptAsV2(encrypted, 'wrongPass').should.be.rejectedWith(/original passphrase/);
-    });
-
-    it('throws when both the current and original passphrases fail', async function () {
-      const encrypted = await bitgo.encrypt({ input: 'prv', password: 'realPass', encryptionVersion: 1 });
-      await keychains.reencryptAsV2(encrypted, 'wrongCurrent', 'alsoWrong').should.be.rejected();
-    });
-
     it('accepts a v2 envelope and re-encrypts it as v2 (idempotent)', async function () {
       const prv = 'xprv-v2';
       const encryptedV2 = await bitgo.encrypt({ input: prv, password: 'pass', encryptionVersion: 2 });
@@ -1240,5 +1216,10 @@ describe('V2 Keychains', function () {
       JSON.parse(result).v.should.equal(2);
       (await bitgo.decrypt({ input: result, password: 'pass' })).should.equal(prv);
     });
+
+    it('surfaces decrypt errors directly (no fallback logic in the primitive)', async function () {
+      const encrypted = await bitgo.encrypt({ input: 'prv', password: 'realPass', encryptionVersion: 1 });
+      await keychains.reencryptAsV2(encrypted, 'wrongPass').should.be.rejected();
+    });
   });
 });

modules/sdk-core/src/bitgo/keychain/iKeychains.ts

@@ -249,7 +249,7 @@ export interface IKeychains {
   updatePassword(params: UpdatePasswordOptions): Promise<ChangedKeychains>;
   updateSingleKeychainPassword(params?: UpdateSingleKeychainPasswordOptions): Promise<Keychain>;
   getEncryptionVersion(ciphertext: string): EncryptionVersion;
-  reencryptAsV2(encryptedPrv: string, passphrase: string, originalPassphrase?: string): Promise<string>;
+  reencryptAsV2(encryptedPrv: string, passphrase: string): Promise<string>;
   create(params?: { seed?: Buffer; isRootKey?: boolean }): KeyPair;
   add(params?: AddKeychainOptions): Promise<Keychain>;
   createBitGo(params?: CreateBitGoOptions): Promise<Keychain>;

modules/sdk-core/src/bitgo/keychain/keychains.ts

@@ -212,26 +212,16 @@ export class Keychains implements IKeychains {
   }
 
   /**
-   * Decrypt an encrypted private key and re-encrypt it as a v2 (Argon2id + AES-256-GCM) envelope.
-   * Tries `passphrase` first; falls back to `originalPassphrase` if provided and decryption fails.
-   * The result is always encrypted with `passphrase` (the current one), never the original.
+   * Decrypt an encrypted private key with `passphrase` and re-encrypt it as a v2
+   * (Argon2id + AES-256-GCM) envelope with the same passphrase.
    *
    * Used to upgrade legacy v1 (SJCL) envelopes to v2 without changing the passphrase.
+   * Callers that need to try a fallback passphrase (e.g. an original passphrase from
+   * before a password rotation) should handle that themselves — this primitive does one
+   * thing and lets decryption errors surface directly.
    */
-  async reencryptAsV2(encryptedPrv: string, passphrase: string, originalPassphrase?: string): Promise<string> {
-    let prv: string;
-    try {
-      prv = await this.bitgo.decrypt({ input: encryptedPrv, password: passphrase });
-    } catch {
-      if (originalPassphrase) {
-        prv = await this.bitgo.decrypt({ input: encryptedPrv, password: originalPassphrase });
-      } else {
-        throw new Error(
-          'Failed to decrypt with the provided passphrase. ' +
-            'If the wallet password was changed after creation, provide the original passphrase so the backup key can be decrypted.'
-        );
-      }
-    }
+  async reencryptAsV2(encryptedPrv: string, passphrase: string): Promise<string> {
+    const prv = await this.bitgo.decrypt({ input: encryptedPrv, password: passphrase });
     return this.bitgo.encrypt({ input: prv, password: passphrase, encryptionVersion: 2 });
   }
 

modules/sdk-core/src/bitgo/wallet/wallet.ts

@@ -3523,7 +3523,12 @@ export class Wallet implements IWallet {
       if (keychainsApi.getEncryptionVersion(backupSource) === 2) {
         skipped.push({ type: 'backup', reason: 'already v2' });
       } else {
-        const newEncryptedPrv = await keychainsApi.reencryptAsV2(backupSource, passphrase, originalPassphrase);
+        const newEncryptedPrv = await this.reencryptCreationTimeKey(
+          backupSource,
+          passphrase,
+          originalPassphrase,
+          'backup key'
+        );
         backupKeychain.encryptedPrv = newEncryptedPrv;
         if (!dryRun && serverStored) {
           // Only PUT if the key was server-stored; boxB-only wallets have no server record.
@@ -3558,13 +3563,23 @@ export class Wallet implements IWallet {
 
     // Re-encrypt MPCv2 key shares (keycard-only — not stored server-side).
     if (boxA) {
-      userKeychain.reducedEncryptedPrv = await keychainsApi.reencryptAsV2(boxA, passphrase, originalPassphrase);
+      userKeychain.reducedEncryptedPrv = await this.reencryptCreationTimeKey(
+        boxA,
+        passphrase,
+        originalPassphrase,
+        'boxA'
+      );
       updated.push({ type: 'user reducedEncryptedPrv (keycard only)', id: userKeychain.id });
     }
     if (boxB && backupKeychain.encryptedPrv) {
       // MPCv2: encryptedPrv exists server-side but reducedEncryptedPrv does not.
       // Re-encrypt boxB so the new keycard uses the reduced form instead of the full blob.
-      backupKeychain.reducedEncryptedPrv = await keychainsApi.reencryptAsV2(boxB, passphrase, originalPassphrase);
+      backupKeychain.reducedEncryptedPrv = await this.reencryptCreationTimeKey(
+        boxB,
+        passphrase,
+        originalPassphrase,
+        'boxB'
+      );
       updated.push({ type: 'backup reducedEncryptedPrv (keycard only)', id: backupKeychain.id });
     }
 
@@ -3587,6 +3602,33 @@ export class Wallet implements IWallet {
     return { doc, walletLabel };
   }
 
+  /**
+   * Re-encrypt a ciphertext that was written at wallet creation time (backup key, boxA, boxB).
+   * These are not re-encrypted on password change, so the encryption passphrase may still be
+   * the original one from when the wallet was created. Try the current passphrase first; fall
+   * back to `originalPassphrase` if provided.
+   */
+  private async reencryptCreationTimeKey(
+    encryptedPrv: string,
+    passphrase: string,
+    originalPassphrase: string | undefined,
+    keyDescription: string
+  ): Promise<string> {
+    const keychainsApi = this.baseCoin.keychains();
+    try {
+      return await keychainsApi.reencryptAsV2(encryptedPrv, passphrase);
+    } catch (err) {
+      if (!originalPassphrase) {
+        throw new Error(
+          `Failed to decrypt ${keyDescription} with the provided passphrase. If the wallet passphrase ` +
+            'was changed after creation, pass boxD so the original passphrase can be recovered.'
+        );
+      }
+      const prv = await this.bitgo.decrypt({ input: encryptedPrv, password: originalPassphrase });
+      return this.bitgo.encrypt({ input: prv, password: passphrase, encryptionVersion: 2 });
+    }
+  }
+
   private async fetchPasscodeEncryptionCode(coin: string, walletId: string): Promise<string> {
     const response = (await this.bitgo
       .post(this.bitgo.microservicesUrl(`/api/v2/${coin}/wallet/${walletId}/passcoderecovery`))