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/argon2/index.mjs

@@ -0,0 +1,3 @@
+// CJS/ESM interop: import the UMD bundle as a default and re-export named functions
+import argon2 from './argon2.umd.min.js';
+export const { argon2d, argon2i, argon2id, argon2Verify } = argon2;

modules/argon2/package.json

@@ -4,12 +4,19 @@
   "description": "Vendored argon2 (hash-wasm v4.12.0) for BitGo SDK",
   "main": "argon2.umd.min.js",
   "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./argon2.umd.min.js"
+    }
+  },
   "scripts": {
     "test": "mocha test/**/*.ts",
     "verify": "./scripts/verify-vendor.sh"
   },
   "files": [
     "argon2.umd.min.js",
+    "index.mjs",
     "index.d.ts",
     "LICENSE",
     "PROVENANCE.md"

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,29 @@ 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.includes('The operation failed for an operation-specific reason')
+      ) {
+        throw new Error('incorrect password');
+      }
+      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

@@ -1,8 +1,9 @@
-import { argon2id } from '@bitgo/argon2';
 import * as sjcl from '@bitgo/sjcl';
 import { randomBytes } from 'crypto';
 
-/** Default Argon2id parameters per RFC 9106 second recommendation */
+/** Default Argon2id parameters per RFC 9106 second recommendation
+ * @see https://www.rfc-editor.org/rfc/rfc9106#section-4
+ */
 const ARGON2_DEFAULTS = {
   memorySize: 65536, // 64 MiB in KiB
   iterations: 3,
@@ -84,6 +85,30 @@ 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> {
+  let isV2 = false;
+  try {
+    // Only peeking at the v field to route; this is an internal format we produce, not external input.
+    const envelope = JSON.parse(ciphertext);
+    isV2 = envelope.v === 2;
+  } catch {
+    // Not valid JSON -- fall through to v1
+  }
+  if (isV2) {
+    // Do not catch errors here: a wrong password or corrupt envelope on v2 data
+    // should propagate, not silently fall through to a v1 decrypt attempt.
+    return decryptV2(password, ciphertext);
+  }
+  return sjcl.decrypt(password, ciphertext);
+}
+
 /**
  * Derive a 256-bit key from a password using Argon2id.
  */
@@ -92,6 +117,7 @@ async function deriveKeyV2(
   salt: Uint8Array,
   params: { memorySize: number; iterations: number; parallelism: number }
 ): Promise<CryptoKey> {
+  const { argon2id } = await import('@bitgo/argon2');
   const keyBytes = await argon2id({
     password,
     salt,

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,43 @@ 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));
+    });
+
+    it('wrong password on v2 data does not fall through to v1 decrypt', async () => {
+      const v2ct = await encryptV2(password, plaintext, { memorySize: 1024, iterations: 1, parallelism: 1 });
+      let caughtError: Error | undefined;
+      try {
+        await decryptAsync('wrong', v2ct);
+      } catch (e) {
+        caughtError = e as Error;
+      }
+      assert.ok(caughtError, 'should have thrown');
+      assert.ok(!caughtError.message?.includes('sjcl'), 'error must not be from SJCL');
+    });
+  });
 });

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;