feat(sdk-api): add decryptKeys method for bulk wallet key decryption

TICKET: CSI-384

Author: ayush-9

modules/sdk-api/src/bitgoAPI.ts

@@ -6,6 +6,7 @@ import {
   BitGoRequest,
   CoinConstructor,
   common,
+  DecryptKeysOptions,
   DecryptOptions,
   defaultConstants,
   EcdhDerivedKeypair,
@@ -622,6 +623,57 @@ export class BitGoAPI implements BitGoBase {
     }
   }
 
+  /**
+   * Attempt to decrypt multiple wallet keys with the provided passphrase
+   * @param {DecryptKeysOptions} params - Parameters object containing wallet key pairs and password
+   * @param {Array<{walletId: string, encryptedPrv: string}>} params.walletIdEncryptedKeyPairs - Array of wallet ID and encrypted private key pairs
+   * @param {string} params.password - The passphrase to attempt decryption with
+   * @returns {string[]} - Array of wallet IDs for which decryption failed
+   */
+  decryptKeys(params: DecryptKeysOptions): string[] {
+    params = params || {};
+    if (!params.walletIdEncryptedKeyPairs) {
+      throw new Error('Missing parameter: walletIdEncryptedKeyPairs');
+    }
+
+    if (!params.password) {
+      throw new Error('Missing parameter: password');
+    }
+
+    if (!Array.isArray(params.walletIdEncryptedKeyPairs)) {
+      throw new Error('walletIdEncryptedKeyPairs must be an array');
+    }
+
+    if (params.walletIdEncryptedKeyPairs.length === 0) {
+      return [];
+    }
+
+    const failedWalletIds: string[] = [];
+
+    for (const keyPair of params.walletIdEncryptedKeyPairs) {
+      if (!keyPair.walletId || typeof keyPair.walletId !== 'string') {
+        throw new Error('each key pair must have a string walletId');
+      }
+
+      if (!keyPair.encryptedPrv || typeof keyPair.encryptedPrv !== 'string') {
+        throw new Error('each key pair must have a string encryptedPrv');
+      }
+
+      try {
+        this.decrypt({
+          input: keyPair.encryptedPrv,
+          password: params.password,
+        });
+        // If no error was thrown, decryption was successful
+      } catch (error) {
+        // If decryption fails, add the walletId to the failed list
+        failedWalletIds.push(keyPair.walletId);
+      }
+    }
+
+    return failedWalletIds;
+  }
+
   /**
    * Serialize this BitGo object to a JSON object.
    *

modules/sdk-api/test/unit/bitgoAPI.ts

@@ -1,6 +1,7 @@
 import 'should';
 import { BitGoAPI } from '../../src/bitgoAPI';
 import { ProxyAgent } from 'proxy-agent';
+import * as sinon from 'sinon';
 
 describe('Constructor', function () {
   describe('cookiesPropagationEnabled argument', function () {
@@ -125,4 +126,183 @@ describe('Constructor', function () {
       result.should.equal(expectedUrl);
     });
   });
+
+  describe('decryptKeys', function () {
+    let bitgo: BitGoAPI;
+
+    beforeEach(function () {
+      bitgo = new BitGoAPI({
+        env: 'test',
+      });
+    });
+
+    afterEach(function () {
+      sinon.restore();
+    });
+
+    it('should throw if no params are provided', function () {
+      try {
+        // @ts-expect-error - intentionally calling with no params for test
+        bitgo.decryptKeys();
+        throw new Error('Expected error but got none');
+      } catch (e) {
+        e.message.should.containEql('Missing parameter');
+      }
+    });
+
+    it('should throw if walletIdEncryptedKeyPairs is missing', function () {
+      try {
+        // @ts-expect-error - intentionally missing required param
+        bitgo.decryptKeys({ password: 'password123' });
+        throw new Error('Expected error but got none');
+      } catch (e) {
+        e.message.should.containEql('Missing parameter: walletIdEncryptedKeyPairs');
+      }
+    });
+
+    it('should throw if password is missing', function () {
+      try {
+        // @ts-expect-error - intentionally missing required param
+        bitgo.decryptKeys({ walletIdEncryptedKeyPairs: [] });
+        throw new Error('Expected error but got none');
+      } catch (e) {
+        e.message.should.containEql('Missing parameter: password');
+      }
+    });
+
+    it('should throw if walletIdEncryptedKeyPairs is not an array', function () {
+      try {
+        // @ts-expect-error - intentionally providing wrong type
+        bitgo.decryptKeys({ walletIdEncryptedKeyPairs: 'not an array', password: 'password123' });
+        throw new Error('Expected error but got none');
+      } catch (e) {
+        e.message.should.equal('walletIdEncryptedKeyPairs must be an array');
+      }
+    });
+
+    it('should return empty array for empty walletIdEncryptedKeyPairs', function () {
+      const result = bitgo.decryptKeys({ walletIdEncryptedKeyPairs: [], password: 'password123' });
+      result.should.be.an.Array();
+      result.should.be.empty();
+    });
+
+    it('should throw if any walletId is missing or not a string', function () {
+      try {
+        bitgo.decryptKeys({
+          walletIdEncryptedKeyPairs: [
+            // @ts-expect-error - intentionally missing walletId
+            {
+              encryptedPrv: 'encrypted-data',
+            },
+          ],
+          password: 'password123',
+        });
+        throw new Error('Expected error but got none');
+      } catch (e) {
+        e.message.should.equal('each key pair must have a string walletId');
+      }
+
+      try {
+        bitgo.decryptKeys({
+          walletIdEncryptedKeyPairs: [
+            {
+              // @ts-expect-error - intentionally providing wrong type
+              walletId: 123,
+              encryptedPrv: 'encrypted-data',
+            },
+          ],
+          password: 'password123',
+        });
+        throw new Error('Expected error but got none');
+      } catch (e) {
+        e.message.should.equal('each key pair must have a string walletId');
+      }
+    });
+
+    it('should throw if any encryptedPrv is missing or not a string', function () {
+      try {
+        bitgo.decryptKeys({
+          walletIdEncryptedKeyPairs: [
+            // @ts-expect-error - intentionally missing encryptedPrv
+            {
+              walletId: 'wallet-id-1',
+            },
+          ],
+          password: 'password123',
+        });
+        throw new Error('Expected error but got none');
+      } catch (e) {
+        e.message.should.equal('each key pair must have a string encryptedPrv');
+      }
+
+      try {
+        bitgo.decryptKeys({
+          walletIdEncryptedKeyPairs: [
+            {
+              walletId: 'wallet-id-1',
+              // @ts-expect-error - intentionally providing wrong type
+              encryptedPrv: 123,
+            },
+          ],
+          password: 'password123',
+        });
+        throw new Error('Expected error but got none');
+      } catch (e) {
+        e.message.should.equal('each key pair must have a string encryptedPrv');
+      }
+    });
+
+    it('should return walletIds of keys that failed to decrypt', function () {
+      // Create a stub for the decrypt method
+      const decryptStub = sinon.stub(bitgo, 'decrypt');
+
+      // Make it succeed for first wallet and fail for second wallet
+      decryptStub.onFirstCall().returns('decrypted-key-1');
+      decryptStub.onSecondCall().throws(new Error('decryption failed'));
+
+      const result = bitgo.decryptKeys({
+        walletIdEncryptedKeyPairs: [
+          { walletId: 'wallet-id-1', encryptedPrv: 'encrypted-data-1' },
+          { walletId: 'wallet-id-2', encryptedPrv: 'encrypted-data-2' },
+        ],
+        password: 'password123',
+      });
+
+      result.should.be.an.Array();
+      result.should.have.length(1);
+      result[0].should.equal('wallet-id-2');
+    });
+
+    it('should correctly process multiple wallet keys', function () {
+      // Create a spy on the decrypt method
+      const decryptStub = sinon.stub(bitgo, 'decrypt');
+
+      // Configure the stub to throw for specific wallets
+      decryptStub
+        .withArgs({ input: 'encrypted-data-2', password: 'password123' })
+        .throws(new Error('decryption failed'));
+      decryptStub
+        .withArgs({ input: 'encrypted-data-4', password: 'password123' })
+        .throws(new Error('decryption failed'));
+      decryptStub.returns('success'); // Default return for other calls
+
+      const result = bitgo.decryptKeys({
+        walletIdEncryptedKeyPairs: [
+          { walletId: 'wallet-id-1', encryptedPrv: 'encrypted-data-1' },
+          { walletId: 'wallet-id-2', encryptedPrv: 'encrypted-data-2' },
+          { walletId: 'wallet-id-3', encryptedPrv: 'encrypted-data-3' },
+          { walletId: 'wallet-id-4', encryptedPrv: 'encrypted-data-4' },
+        ],
+        password: 'password123',
+      });
+
+      // Should be called once for each wallet
+      decryptStub.callCount.should.equal(4);
+
+      // Should include only the failed wallet IDs
+      result.should.be.an.Array();
+      result.should.have.length(2);
+      result.should.containDeep(['wallet-id-2', 'wallet-id-4']);
+    });
+  });
 });

modules/sdk-core/src/api/types.ts

@@ -9,6 +9,14 @@ export interface DecryptOptions {
   password?: string;
 }
 
+export interface DecryptKeysOptions {
+  walletIdEncryptedKeyPairs: Array<{
+    walletId: string;
+    encryptedPrv: string;
+  }>;
+  password: string;
+}
+
 export interface EncryptOptions {
   input: string;
   password?: string;

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

@@ -1,4 +1,11 @@
-import { BitGoRequest, DecryptOptions, EncryptOptions, GetSharingKeyOptions, IRequestTracer } from '../api';
+import {
+  BitGoRequest,
+  DecryptKeysOptions,
+  DecryptOptions,
+  EncryptOptions,
+  GetSharingKeyOptions,
+  IRequestTracer,
+} from '../api';
 import { IBaseCoin } from './baseCoin';
 import { CoinConstructor } from './coinFactory';
 import { EnvironmentName } from './environments';
@@ -8,6 +15,7 @@ export interface BitGoBase {
   wallets(): any; // TODO - define v1 wallets type
   coin(coinName: string): IBaseCoin; // need to change it to BaseCoin once it's moved to @bitgo/sdk-core
   decrypt(params: DecryptOptions): string;
+  decryptKeys(params: DecryptKeysOptions): string[];
   del(url: string): BitGoRequest;
   encrypt(params: EncryptOptions): string;
   readonly env: EnvironmentName;

yarn.lock

@@ -11304,7 +11304,7 @@ formidable@^1.1.1, formidable@^1.2.0:
   resolved "https://registry.npmjs.org/formidable/-/formidable-1.2.6.tgz#d2a51d60162bbc9b4a055d8457a7c75315d1a168"
   integrity sha512-KcpbcpuLNOwrEjnbpMC0gS+X8ciDoZE1kkqzat4a8vrprf+s9pKNQ/QIwWfbfs4ltgmFl3MD177SNTkve3BwGQ==
 
-formidable@^3.5.1:
+formidable@^3.5.1, formidable@^3.5.2:
   version "3.5.2"
   resolved "https://registry.npmjs.org/formidable/-/formidable-3.5.2.tgz#207c33fecdecb22044c82ba59d0c63a12fb81d77"
   integrity sha512-Jqc1btCy3QzRbJaICGwKcBfGWuLADRerLzDqi2NwSt/UkXLsHJw2TVResiaoBufHVHy9aSgClOHCeJsSsFLTbg==
@@ -18986,6 +18986,21 @@ [email protected]:
     qs "^6.5.1"
     readable-stream "^2.0.5"
 
+superagent@^10.1.1:
+  version "10.2.0"
+  resolved "https://registry.npmjs.org/superagent/-/superagent-10.2.0.tgz#28f262a0a56433e0df53db978ceaa51f23e762ab"
+  integrity sha512-IKeoGox6oG9zyDeizaezkJ2/aK0wc5la9st7WsAKyrAkfJ56W3whVbVtF68k6wuc87/y9T85NyON5FLz7Mrzzw==
+  dependencies:
+    component-emitter "^1.3.0"
+    cookiejar "^2.1.4"
+    debug "^4.3.4"
+    fast-safe-stringify "^2.1.1"
+    form-data "^4.0.0"
+    formidable "^3.5.2"
+    methods "^1.1.2"
+    mime "2.6.0"
+    qs "^6.11.0"
+
 superagent@^3.8.3:
   version "3.8.3"
   resolved "https://registry.npmjs.org/superagent/-/superagent-3.8.3.tgz#460ea0dbdb7d5b11bc4f78deba565f86a178e128"