feat(sdk-core): make decryptKeychainPrivateKey async for v1/v2 auto-detection

WCN-32: Convert decryptKeychainPrivateKey to use decryptAsync internally
so signing flows work with both v1 and v2 encrypted keychains. Make
getUserPrv async and update all callers across sdk-core, abstract-utxo,
abstract-eth, and bitgo.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pranavjain97

modules/abstract-eth/src/abstractEthLikeNewCoins.ts

@@ -2554,7 +2554,7 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
     const walletPassphrase = buildParams.walletPassphrase;
 
     const userKeychain = await this.keychains().get({ id: wallet.keyIds()[0] });
-    const userPrv = wallet.getUserPrv({ keychain: userKeychain, walletPassphrase });
+    const userPrv = await wallet.getUserPrv({ keychain: userKeychain, walletPassphrase });
     const userPrvBuffer = bip32.fromBase58(userPrv).privateKey;
     if (!userPrvBuffer) {
       throw new Error('invalid userPrv');

modules/abstract-utxo/src/abstractUtxoCoin.ts

@@ -677,7 +677,7 @@ export abstract class AbstractUtxoCoin
   /**
    * @deprecated - use function verifyUserPublicKey instead
    */
-  protected verifyUserPublicKey(params: VerifyUserPublicKeyOptions): boolean {
+  protected async verifyUserPublicKey(params: VerifyUserPublicKeyOptions): Promise<boolean> {
     return verifyUserPublicKey(this.bitgo, params);
   }
 

modules/abstract-utxo/src/impl/btc/inscriptionBuilder.ts

@@ -302,7 +302,7 @@ export class InscriptionBuilder implements IInscriptionBuilder {
     txPrebuild: PrebuildTransactionResult
   ): Promise<SubmitTransactionResponse> {
     const userKeychain = await this.wallet.baseCoin.keychains().get({ id: this.wallet.keyIds()[KeyIndices.USER] });
-    const prv = this.wallet.getUserPrv({ keychain: userKeychain, walletPassphrase });
+    const prv = await this.wallet.getUserPrv({ keychain: userKeychain, walletPassphrase });
 
     const halfSigned = (await this.wallet.signTransaction({ prv, txPrebuild })) as HalfSignedUtxoTransaction;
     return this.wallet.submitTransaction({ halfSigned });

modules/abstract-utxo/src/transaction/fixedScript/verifyTransaction.ts

@@ -79,7 +79,11 @@ export async function verifyTransaction<TNumber extends bigint | number>(
   let userPublicKeyVerified = false;
   try {
     // verify the user public key matches the private key - this will throw if there is no match
-    userPublicKeyVerified = verifyUserPublicKey(bitgo, { userKeychain: keychains.user, disableNetworking, txParams });
+    userPublicKeyVerified = await verifyUserPublicKey(bitgo, {
+      userKeychain: keychains.user,
+      disableNetworking,
+      txParams,
+    });
   } catch (e) {
     debug('failed to verify user public key!', e);
   }

modules/abstract-utxo/src/verifyKey.ts

@@ -84,7 +84,7 @@ export function verifyCustomChangeKeySignatures<TNumber extends number | bigint>
 /**
  * Decrypt the wallet's user private key and verify that the claimed public key matches
  */
-export function verifyUserPublicKey(bitgo: BitGoBase, params: VerifyUserPublicKeyOptions): boolean {
+export async function verifyUserPublicKey(bitgo: BitGoBase, params: VerifyUserPublicKeyOptions): Promise<boolean> {
   const { userKeychain, txParams, disableNetworking } = params;
   if (!userKeychain) {
     throw new Error('user keychain is required');
@@ -94,7 +94,7 @@ export function verifyUserPublicKey(bitgo: BitGoBase, params: VerifyUserPublicKe
 
   let userPrv = userKeychain.prv;
   if (!userPrv && txParams.walletPassphrase) {
-    userPrv = decryptKeychainPrivateKey(bitgo, userKeychain, txParams.walletPassphrase);
+    userPrv = await decryptKeychainPrivateKey(bitgo, userKeychain, txParams.walletPassphrase);
   }
 
   if (!userPrv) {

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

@@ -352,7 +352,7 @@ describe('V2 Wallet:', function () {
         prv,
         coldDerivationSeed: '123',
       };
-      wallet.getUserPrv(userPrvOptions).should.eql(derivedPrv);
+      (await wallet.getUserPrv(userPrvOptions)).should.eql(derivedPrv);
     });
 
     it('should use the user keychain derivedFromParentWithSeed as the cold derivation seed if none is provided', async () => {
@@ -365,7 +365,7 @@ describe('V2 Wallet:', function () {
           type: 'independent',
         },
       };
-      wallet.getUserPrv(userPrvOptions).should.eql(derivedPrv);
+      (await wallet.getUserPrv(userPrvOptions)).should.eql(derivedPrv);
     });
 
     it('should prefer the explicit cold derivation seed to the user keychain derivedFromParentWithSeed', async () => {
@@ -379,7 +379,7 @@ describe('V2 Wallet:', function () {
           type: 'independent',
         },
       };
-      wallet.getUserPrv(userPrvOptions).should.eql(derivedPrv);
+      (await wallet.getUserPrv(userPrvOptions)).should.eql(derivedPrv);
     });
 
     it('should return the prv provided for TSS SMC', async () => {
@@ -407,7 +407,7 @@ describe('V2 Wallet:', function () {
         prv,
         keychain,
       };
-      wallet.getUserPrv(userPrvOptions).should.eql(prv);
+      (await wallet.getUserPrv(userPrvOptions)).should.eql(prv);
     });
   });
 

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

@@ -2566,7 +2566,7 @@ describe('V2 Wallets:', function () {
         const keychainTest: OptionalKeychainEncryptedKey = {
           encryptedPrv: bitgo.encrypt({ input: fromUserPrv.toString(), password: walletPassphrase }),
         };
-        const userPrv = decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
+        const userPrv = await decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
         if (!userPrv) {
           throw new Error('Unable to decrypt user keychain');
         }
@@ -2638,7 +2638,7 @@ describe('V2 Wallets:', function () {
         const keychainTest: OptionalKeychainEncryptedKey = {
           encryptedPrv: bitgo.encrypt({ input: fromUserPrv.toString(), password: walletPassphrase }),
         };
-        const userPrv = decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
+        const userPrv = await decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
         if (!userPrv) {
           throw new Error('Unable to decrypt user keychain');
         }
@@ -2717,7 +2717,7 @@ describe('V2 Wallets:', function () {
         const keychainTest: OptionalKeychainEncryptedKey = {
           encryptedPrv: bitgo.encrypt({ input: fromUserPrv.toString(), password: walletPassphrase }),
         };
-        const userPrv = decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
+        const userPrv = await decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
         if (!userPrv) {
           throw new Error('Unable to decrypt user keychain');
         }
@@ -2785,7 +2785,7 @@ describe('V2 Wallets:', function () {
         const keychainTest: OptionalKeychainEncryptedKey = {
           encryptedPrv: bitgo.encrypt({ input: fromUserPrv.toString(), password: walletPassphrase }),
         };
-        const userPrv = decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
+        const userPrv = await decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
         if (!userPrv) {
           throw new Error('Unable to decrypt user keychain');
         }
@@ -2886,7 +2886,7 @@ describe('V2 Wallets:', function () {
         const keychainTest: OptionalKeychainEncryptedKey = {
           encryptedPrv: bitgo.encrypt({ input: fromUserPrv.toString(), password: walletPassphrase }),
         };
-        const userPrv = decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
+        const userPrv = await decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
         if (!userPrv) {
           throw new Error('Unable to decrypt user keychain');
         }
@@ -2988,7 +2988,7 @@ describe('V2 Wallets:', function () {
         const keychainTest: OptionalKeychainEncryptedKey = {
           encryptedPrv: bitgo.encrypt({ input: fromUserPrv.toString(), password: walletPassphrase }),
         };
-        const userPrv = decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
+        const userPrv = await decryptKeychainPrivateKey(bitgo, keychainTest, walletPassphrase);
         if (!userPrv) {
           throw new Error('Unable to decrypt user keychain');
         }

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

@@ -2,9 +2,9 @@ import { BitGoBase } from '../bitgoBase';
 import { OptionalKeychainEncryptedKey } from './iKeychains';
 import { notEmpty } from '../utils';
 
-function maybeDecrypt(bitgo: BitGoBase, input: string, password: string): string | undefined {
+async function maybeDecrypt(bitgo: BitGoBase, input: string, password: string): Promise<string | undefined> {
   try {
-    return bitgo.decrypt({
+    return await bitgo.decryptAsync({
       input,
       password,
     });
@@ -17,19 +17,20 @@ function maybeDecrypt(bitgo: BitGoBase, input: string, password: string): string
  * Decrypts the private key of a keychain.
  * This method will try the password against the traditional encryptedPrv,
  * and any webauthn device encryptedPrvs.
+ * Auto-detects v1 (SJCL) and v2 (Argon2id) envelopes.
  *
  * @param bitgo
  * @param keychain
  * @param password
  */
-export function decryptKeychainPrivateKey(
+export async function decryptKeychainPrivateKey(
   bitgo: BitGoBase,
   keychain: OptionalKeychainEncryptedKey,
   password: string
-): string | undefined {
+): Promise<string | undefined> {
   const prvs = [keychain.encryptedPrv, ...(keychain.webauthnDevices ?? []).map((d) => d.encryptedPrv)].filter(notEmpty);
   for (const prv of prvs) {
-    const decrypted = maybeDecrypt(bitgo, prv, password);
+    const decrypted = await maybeDecrypt(bitgo, prv, password);
     if (decrypted) {
       return decrypted;
     }

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

@@ -1070,7 +1070,7 @@ export interface IWallet {
   removeUser(params?: RemoveUserOptions): Promise<any>;
   prebuildTransaction(params?: PrebuildTransactionOptions): Promise<PrebuildTransactionResult>;
   signTransaction(params?: WalletSignTransactionOptions): Promise<SignedTransaction>;
-  getUserPrv(params?: GetUserPrvOptions): string;
+  getUserPrv(params?: GetUserPrvOptions): Promise<string>;
   prebuildAndSignTransaction(params?: PrebuildAndSignTransactionOptions): Promise<SignedTransaction>;
   signAndSendTxRequest(params?: SignAndSendTxRequestOptions): Promise<SignedTransaction>;
   accelerateTransaction(params?: AccelerateTransactionOptions): Promise<any>;

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

@@ -1673,7 +1673,7 @@ export class Wallet implements IWallet {
     if (!params.walletPassphrase) {
       throw new Error('wallet passphrase was not provided');
     }
-    const userPrv = decryptKeychainPrivateKey(this.bitgo, userKeychain, params.walletPassphrase);
+    const userPrv = await decryptKeychainPrivateKey(this.bitgo, userKeychain, params.walletPassphrase);
     if (!userPrv) {
       throw new Error('error decrypting wallet private key');
     }
@@ -1853,7 +1853,7 @@ export class Wallet implements IWallet {
       throw new Error('Missing walletPassphrase argument');
     }
 
-    const prv = decryptKeychainPrivateKey(this.bitgo, keychain, walletPassphrase);
+    const prv = await decryptKeychainPrivateKey(this.bitgo, keychain, walletPassphrase);
     if (!prv) {
       throw new IncorrectPasswordError('Password shared is incorrect for this wallet');
     }
@@ -2218,7 +2218,7 @@ export class Wallet implements IWallet {
     if (this.multisigType() === 'tss') {
       return this.signTransactionTss({
         ...presign,
-        prv: this.getUserPrv(presign as GetUserPrvOptions),
+        prv: await this.getUserPrv(presign as GetUserPrvOptions),
         apiVersion,
       });
     }
@@ -2256,7 +2256,7 @@ export class Wallet implements IWallet {
     }
     return this.baseCoin.signTransaction({
       ...signTransactionParams,
-      prv: this.getUserPrv(presign as GetUserPrvOptions),
+      prv: await this.getUserPrv(presign as GetUserPrvOptions),
       wallet: this,
     });
   }
@@ -2291,7 +2291,7 @@ export class Wallet implements IWallet {
       ...params,
       walletData: this._wallet,
       tssUtils: this.tssUtils,
-      prv: this.getUserPrv(userPrvOptions),
+      prv: await this.getUserPrv(userPrvOptions),
       keychain: keychains[0],
       backupKeychain: keychains.length > 1 ? keychains[1] : null,
       bitgoKeychain: keychains.length > 2 ? keychains[2] : null,
@@ -2330,7 +2330,7 @@ export class Wallet implements IWallet {
       ...params,
       walletData: this._wallet,
       tssUtils: this.tssUtils,
-      prv: this.getUserPrv(userPrvOptions),
+      prv: await this.getUserPrv(userPrvOptions),
       keychain: keychains[0],
       backupKeychain: keychains.length > 1 ? keychains[1] : null,
       bitgoKeychain: keychains.length > 2 ? keychains[2] : null,
@@ -2387,7 +2387,7 @@ export class Wallet implements IWallet {
    * @param [params.keychain / params.key] (object) or params.prv (string)
    * @param params.walletPassphrase (string)
    */
-  getUserPrv(params: GetUserPrvOptions = {}): string {
+  async getUserPrv(params: GetUserPrvOptions = {}): Promise<string> {
     const userKeychain = params.keychain || params.key;
     let userPrv = params.prv;
     if (userPrv && typeof userPrv !== 'string') {
@@ -2424,7 +2424,7 @@ export class Wallet implements IWallet {
       if (!params.walletPassphrase) {
         throw new Error('walletPassphrase property missing');
       }
-      userPrv = decryptKeychainPrivateKey(this.bitgo, userKeychain, params.walletPassphrase);
+      userPrv = await decryptKeychainPrivateKey(this.bitgo, userKeychain, params.walletPassphrase);
       if (!userPrv) {
         throw new Error('failed to decrypt user keychain');
       }
@@ -4409,7 +4409,7 @@ export class Wallet implements IWallet {
     // we ignore this check with if customSigningFunction is provided
     //  which means that the user is handling the signing in external signing mode
     if (!customSigningFunction && keychains?.[0]?.encryptedPrv && walletPassphrase) {
-      if (!decryptKeychainPrivateKey(this.bitgo, keychains[0], walletPassphrase)) {
+      if (!(await decryptKeychainPrivateKey(this.bitgo, keychains[0], walletPassphrase))) {
         const error: Error & { code?: string } = new Error(
           `unable to decrypt keychain with the given wallet passphrase`
         );