feat(sdk-api): add decryptAsync with v1/v2 auto-detection

Add decryptAsync() that auto-detects v1 (SJCL) or v2 (Argon2id)
envelopes. This is the non-breaking migration path for clients to
move from sync decrypt() to async before the breaking release.

- decryptAsync() on encrypt.ts and BitGoAPI
- decryptAsync on BitGoBase interface
- Tests for v1 and v2 auto-detection, wrong password rejection

WCN-30

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

TICKET: WCN-30

Author: pranavjain97

modules/sdk-api/src/bitgoAPI.ts

@@ -40,7 +40,7 @@ import {
   toBitgoRequest,
   verifyResponseAsync,
 } from './api';
-import { decrypt, encrypt } from './encrypt';
+import { decrypt, decryptAsync, encrypt } from './encrypt';
 import { verifyAddress } from './v1/verifyAddress';
 import {
   AccessTokenOptions,
@@ -734,6 +734,26 @@ export class BitGoAPI implements BitGoBase {
     }
   }
 
+  /**
+   * Async decrypt that auto-detects v1 (SJCL) or v2 (Argon2id).
+   * Migration path from sync decrypt() -- use this before the breaking release.
+   */
+  async decryptAsync(params: DecryptOptions): Promise<string> {
+    params = params || {};
+    common.validateParams(params, ['input', 'password'], []);
+    if (!params.password) {
+      throw new Error(`cannot decrypt without password`);
+    }
+    try {
+      return await decryptAsync(params.password, params.input);
+    } catch (error) {
+      if (error.message.includes("ccm: tag doesn't match")) {
+        error.message = 'password error - ' + error.message;
+      }
+      throw error;
+    }
+  }
+
   /**
    * Attempt to decrypt multiple wallet keys with the provided passphrase
    * @param {DecryptKeysOptions} params - Parameters object containing wallet key pairs and password

modules/sdk-api/src/encrypt.ts

@@ -84,6 +84,25 @@ export function decrypt(password: string, ciphertext: string): string {
   return sjcl.decrypt(password, ciphertext);
 }
 
+/**
+ * Async decrypt that auto-detects v1 (SJCL) or v2 (Argon2id + AES-256-GCM)
+ * from the JSON envelope's `v` field.
+ *
+ * This is the migration path from sync `decrypt()`. Clients should move to
+ * `await decryptAsync()` before the breaking release that makes `decrypt()` async.
+ */
+export async function decryptAsync(password: string, ciphertext: string): Promise<string> {
+  try {
+    const envelope = JSON.parse(ciphertext);
+    if (envelope.v === 2) {
+      return await decryptV2(password, ciphertext);
+    }
+  } catch {
+    // Not valid JSON or no v field -- fall through to v1
+  }
+  return sjcl.decrypt(password, ciphertext);
+}
+
 /**
  * Derive a 256-bit key from a password using Argon2id.
  */

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

@@ -1,7 +1,7 @@
 import assert from 'assert';
 import { randomBytes } from 'crypto';
 
-import { decrypt, decryptV2, encrypt, encryptV2, V2Envelope } from '../../src';
+import { decrypt, decryptAsync, decryptV2, encrypt, encryptV2, V2Envelope } from '../../src';
 
 describe('encryption methods tests', () => {
   describe('encrypt', () => {
@@ -138,4 +138,31 @@ describe('encryption methods tests', () => {
       await assert.rejects(() => decryptV2(password, v1ct), /unsupported envelope version/);
     });
   });
+
+  describe('decryptAsync (auto-detect v1/v2)', () => {
+    const password = 'myPassword';
+    const plaintext = 'Hello, World!';
+
+    it('decrypts v1 data', async () => {
+      const v1ct = encrypt(password, plaintext);
+      const result = await decryptAsync(password, v1ct);
+      assert.strictEqual(result, plaintext);
+    });
+
+    it('decrypts v2 data', async () => {
+      const v2ct = await encryptV2(password, plaintext);
+      const result = await decryptAsync(password, v2ct);
+      assert.strictEqual(result, plaintext);
+    });
+
+    it('throws on wrong password for v1', async () => {
+      const v1ct = encrypt(password, plaintext);
+      await assert.rejects(() => decryptAsync('wrong', v1ct));
+    });
+
+    it('throws on wrong password for v2', async () => {
+      const v2ct = await encryptV2(password, plaintext);
+      await assert.rejects(() => decryptAsync('wrong', v2ct));
+    });
+  });
 });

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

@@ -15,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;
+  decryptAsync(params: DecryptOptions): Promise<string>;
   decryptKeys(params: DecryptKeysOptions): string[];
   del(url: string): BitGoRequest;
   encrypt(params: EncryptOptions): string;