feat(sdk-api): add HKDF session caching layer for multi-call operations

pranavjain97 · pranavjain97 · commit 7794281bee2d · 2026-04-14T15:28:43.000-04:00
createEncryptionSession runs one Argon2id derivation and caches the master key as an HKDF CryptoKey. Each session.encrypt/decrypt derives a per-call AES-256-GCM key via HKDF (<1ms, native WebCrypto). Envelopes store both the Argon2id salt and a per-call hkdfSalt so standalone decryptV2 can decrypt without a session. session.destroy() clears the master key reference. decryptV2 updated to handle both standard and session-produced envelopes. Also addresses PR review comments on WCN-30: - Add RFC 9106 URL to Argon2id defaults comment - Fix decryptAsync to not swallow v2 errors (wrong password on v2 data previously fell through to a confusing SJCL error instead of propagating) - Mark BitGoBase.decrypt as deprecated in favour of decryptAsync WCN-31
diff --git a/modules/sdk-api/src/encrypt.ts b/modules/sdk-api/src/encrypt.ts
@@ -16,16 +16,148 @@ const ARGON2_DEFAULTS = {
 /** AES-256-GCM IV length in bytes */
 const GCM_IV_LENGTH = 12;
 
+/** HKDF salt length in bytes (per-call) */
+const HKDF_SALT_LENGTH = 32;
+
+/** Fixed HKDF info for domain separation */
+const HKDF_INFO = new TextEncoder().encode('bitgo-v2-session');
+
 export interface V2Envelope {
   v: 2;
   m: number;
   t: number;
   p: number;
   salt: string;
+  hkdfSalt?: string; // per-call HKDF salt; present only in session-produced envelopes
   iv: string;
   ct: string;
 }
 
+export interface EncryptionSession {
+  encrypt(plaintext: string): Promise<string>;
+  decrypt(ciphertext: string): Promise<string>;
+  destroy(): void;
+}
+
+/**
+ * Create an EncryptionSession that runs one Argon2id derivation and caches the
+ * master key for the duration of the operation. Each encrypt/decrypt call derives
+ * a per-call AES-256-GCM key via HKDF (<1ms). Call session.destroy() when done.
+ *
+ * Session-produced envelopes store both the Argon2id salt and a per-call HKDF salt
+ * so each ciphertext can be decrypted standalone via decryptV2 without a session.
+ */
+export async function createEncryptionSession(
+  password: string,
+  options?: {
+    memorySize?: number;
+    iterations?: number;
+    parallelism?: number;
+    salt?: Uint8Array;
+  }
+): Promise<EncryptionSession> {
+  const memorySize = options?.memorySize ?? ARGON2_DEFAULTS.memorySize;
+  const iterations = options?.iterations ?? ARGON2_DEFAULTS.iterations;
+  const parallelism = options?.parallelism ?? ARGON2_DEFAULTS.parallelism;
+
+  const argon2Salt = options?.salt ?? new Uint8Array(randomBytes(ARGON2_DEFAULTS.saltLength));
+  if (argon2Salt.length !== ARGON2_DEFAULTS.saltLength) {
+    throw new Error(`salt must be ${ARGON2_DEFAULTS.saltLength} bytes`);
+  }
+
+  const masterKeyBytes = await argon2id({
+    password,
+    salt: argon2Salt,
+    memorySize,
+    iterations,
+    parallelism,
+    hashLength: ARGON2_DEFAULTS.hashLength,
+    outputType: 'binary',
+  });
+
+  let hkdfKey: CryptoKey | null = await crypto.subtle.importKey('raw', masterKeyBytes, 'HKDF', false, ['deriveKey']);
+  const argon2SaltB64 = Buffer.from(argon2Salt).toString('base64');
+  let destroyed = false;
+
+  const checkAlive = (): void => {
+    if (destroyed) throw new Error('EncryptionSession has been destroyed');
+  };
+
+  return {
+    async encrypt(plaintext: string): Promise<string> {
+      checkAlive();
+      const hkdfSalt = new Uint8Array(randomBytes(HKDF_SALT_LENGTH));
+      const iv = new Uint8Array(randomBytes(GCM_IV_LENGTH));
+
+      const aesKey = await crypto.subtle.deriveKey(
+        { name: 'HKDF', hash: 'SHA-256', salt: hkdfSalt, info: HKDF_INFO },
+        hkdfKey!,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['encrypt']
+      );
+
+      const plaintextBytes = new TextEncoder().encode(plaintext);
+      const ctBuffer = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, aesKey, plaintextBytes);
+
+      const envelope: V2Envelope = {
+        v: 2,
+        m: memorySize,
+        t: iterations,
+        p: parallelism,
+        salt: argon2SaltB64,
+        hkdfSalt: Buffer.from(hkdfSalt).toString('base64'),
+        iv: Buffer.from(iv).toString('base64'),
+        ct: Buffer.from(ctBuffer).toString('base64'),
+      };
+
+      return JSON.stringify(envelope);
+    },
+
+    async decrypt(ciphertext: string): Promise<string> {
+      checkAlive();
+      let envelope: V2Envelope;
+      try {
+        envelope = JSON.parse(ciphertext);
+      } catch {
+        throw new Error('v2 decrypt: invalid JSON envelope');
+      }
+
+      if (envelope.v !== 2) {
+        throw new Error(`v2 decrypt: unsupported envelope version ${envelope.v}`);
+      }
+
+      if (!envelope.hkdfSalt) {
+        throw new Error('envelope was not encrypted with a session; use decryptV2 instead');
+      }
+
+      if (envelope.salt !== argon2SaltB64) {
+        throw new Error('envelope was not encrypted with this session');
+      }
+
+      const iv = new Uint8Array(Buffer.from(envelope.iv, 'base64'));
+      const ct = new Uint8Array(Buffer.from(envelope.ct, 'base64'));
+      const hkdfSalt = new Uint8Array(Buffer.from(envelope.hkdfSalt, 'base64'));
+
+      const aesKey = await crypto.subtle.deriveKey(
+        { name: 'HKDF', hash: 'SHA-256', salt: hkdfSalt, info: HKDF_INFO },
+        hkdfKey!,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['decrypt']
+      );
+
+      const plaintextBuffer = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, aesKey, ct);
+      return new TextDecoder().decode(plaintextBuffer);
+    },
+
+    destroy(): void {
+      hkdfKey = null;
+      destroyed = true;
+    },
+  };
+}
+
 /**
  * convert a 4 element Uint8Array to a 4 byte Number
  *
@@ -183,7 +315,8 @@ export async function encryptV2(
 /**
  * Decrypt a v2 envelope (Argon2id KDF + AES-256-GCM).
  *
- * The envelope must contain: v, m, t, p, salt, iv, ct.
+ * Handles both standard v2 envelopes (Argon2id -> AES-GCM) and session-produced
+ * envelopes (Argon2id -> HKDF -> AES-GCM) identified by the presence of hkdfSalt.
  */
 export async function decryptV2(password: string, ciphertext: string): Promise<string> {
   let envelope: V2Envelope;
@@ -200,14 +333,32 @@ export async function decryptV2(password: string, ciphertext: string): Promise<s
   const salt = new Uint8Array(Buffer.from(envelope.salt, 'base64'));
   const iv = new Uint8Array(Buffer.from(envelope.iv, 'base64'));
   const ct = new Uint8Array(Buffer.from(envelope.ct, 'base64'));
+  const params = { memorySize: envelope.m, iterations: envelope.t, parallelism: envelope.p };
 
-  const key = await deriveKeyV2(password, salt, {
-    memorySize: envelope.m,
-    iterations: envelope.t,
-    parallelism: envelope.p,
-  });
+  if (envelope.hkdfSalt) {
+    // Session envelope: Argon2id -> HKDF -> AES-GCM
+    const masterKeyBytes = await argon2id({
+      password,
+      salt,
+      ...params,
+      hashLength: ARGON2_DEFAULTS.hashLength,
+      outputType: 'binary',
+    });
+    const hkdfKey = await crypto.subtle.importKey('raw', masterKeyBytes, 'HKDF', false, ['deriveKey']);
+    const hkdfSalt = new Uint8Array(Buffer.from(envelope.hkdfSalt, 'base64'));
+    const aesKey = await crypto.subtle.deriveKey(
+      { name: 'HKDF', hash: 'SHA-256', salt: hkdfSalt, info: HKDF_INFO },
+      hkdfKey,
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['decrypt']
+    );
+    const plaintextBuffer = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, aesKey, ct);
+    return new TextDecoder().decode(plaintextBuffer);
+  }
 
+  // Standard v2 envelope: Argon2id -> AES-GCM directly
+  const key = await deriveKeyV2(password, salt, params);
   const plaintextBuffer = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ct);
-
   return new TextDecoder().decode(plaintextBuffer);
 }
diff --git a/modules/sdk-api/test/unit/encrypt.ts b/modules/sdk-api/test/unit/encrypt.ts
@@ -1,7 +1,7 @@
 import assert from 'assert';
 import { randomBytes } from 'crypto';
 
-import { decrypt, decryptAsync, decryptV2, encrypt, encryptV2, V2Envelope } from '../../src';
+import { decrypt, decryptAsync, decryptV2, encrypt, encryptV2, V2Envelope, createEncryptionSession } from '../../src';
 
 describe('encryption methods tests', () => {
   describe('encrypt', () => {
@@ -177,4 +177,113 @@ describe('encryption methods tests', () => {
       assert.ok(!caughtError.message?.includes('sjcl'), 'error must not be from SJCL');
     });
   });
+
+  describe('EncryptionSession (HKDF caching)', () => {
+    const opts = { memorySize: 1024, iterations: 1, parallelism: 1 };
+    const password = 'test-password';
+    const plaintext = 'hello session';
+
+    it('session-produced envelope contains salt and hkdfSalt', async () => {
+      const session = await createEncryptionSession(password, opts);
+      const ct = await session.encrypt(plaintext);
+      session.destroy();
+
+      const envelope: V2Envelope = JSON.parse(ct);
+      assert.strictEqual(envelope.v, 2);
+      assert.ok(envelope.salt, 'must have argon2 salt');
+      assert.ok(envelope.hkdfSalt, 'must have hkdf salt');
+      assert.ok(envelope.iv, 'must have iv');
+      assert.ok(envelope.ct, 'must have ciphertext');
+    });
+
+    it('session round-trip via session.decrypt', async () => {
+      const session = await createEncryptionSession(password, opts);
+      const ct = await session.encrypt(plaintext);
+      const result = await session.decrypt(ct);
+      session.destroy();
+      assert.strictEqual(result, plaintext);
+    });
+
+    it('session envelope can be decrypted standalone via decryptV2', async () => {
+      const session = await createEncryptionSession(password, opts);
+      const ct = await session.encrypt(plaintext);
+      session.destroy();
+      const result = await decryptV2(password, ct);
+      assert.strictEqual(result, plaintext);
+    });
+
+    it('session envelope can be decrypted via decryptAsync', async () => {
+      const session = await createEncryptionSession(password, opts);
+      const ct = await session.encrypt(plaintext);
+      session.destroy();
+      const result = await decryptAsync(password, ct);
+      assert.strictEqual(result, plaintext);
+    });
+
+    it('multiple encrypts produce different hkdfSalt values', async () => {
+      const session = await createEncryptionSession(password, opts);
+      const ct1 = await session.encrypt(plaintext);
+      const ct2 = await session.encrypt(plaintext);
+      session.destroy();
+      const e1: V2Envelope = JSON.parse(ct1);
+      const e2: V2Envelope = JSON.parse(ct2);
+      assert.notStrictEqual(e1.hkdfSalt, e2.hkdfSalt);
+    });
+
+    it('all session encrypts share the same argon2 salt', async () => {
+      const session = await createEncryptionSession(password, opts);
+      const ct1 = await session.encrypt(plaintext);
+      const ct2 = await session.encrypt(plaintext);
+      session.destroy();
+      const e1: V2Envelope = JSON.parse(ct1);
+      const e2: V2Envelope = JSON.parse(ct2);
+      assert.strictEqual(e1.salt, e2.salt);
+    });
+
+    it('wrong password rejected by decryptV2', async () => {
+      const session = await createEncryptionSession(password, opts);
+      const ct = await session.encrypt(plaintext);
+      session.destroy();
+      await assert.rejects(() => decryptV2('wrong-password', ct));
+    });
+
+    it('destroy prevents further encrypt calls', async () => {
+      const session = await createEncryptionSession(password, opts);
+      session.destroy();
+      await assert.rejects(() => session.encrypt(plaintext), /destroyed/);
+    });
+
+    it('destroy prevents further decrypt calls', async () => {
+      const session = await createEncryptionSession(password, opts);
+      const ct = await session.encrypt(plaintext);
+      session.destroy();
+      await assert.rejects(() => session.decrypt(ct), /destroyed/);
+    });
+
+    it('session rejects envelopes from a different session', async () => {
+      const session1 = await createEncryptionSession(password, opts);
+      const session2 = await createEncryptionSession(password, opts);
+      const ct = await session1.encrypt(plaintext);
+      await assert.rejects(() => session2.decrypt(ct), /not encrypted with this session/);
+      session1.destroy();
+      session2.destroy();
+    });
+
+    it('session rejects standard v2 envelopes (no hkdfSalt)', async () => {
+      const v2ct = await encryptV2(password, plaintext, opts);
+      const session = await createEncryptionSession(password, opts);
+      await assert.rejects(() => session.decrypt(v2ct), /use decryptV2/);
+      session.destroy();
+    });
+
+    it('Argon2id params are stored in envelope', async () => {
+      const session = await createEncryptionSession(password, { memorySize: 2048, iterations: 2, parallelism: 2 });
+      const ct = await session.encrypt(plaintext);
+      session.destroy();
+      const envelope: V2Envelope = JSON.parse(ct);
+      assert.strictEqual(envelope.m, 2048);
+      assert.strictEqual(envelope.t, 2);
+      assert.strictEqual(envelope.p, 2);
+    });
+  });
 });
diff --git a/modules/sdk-core/src/bitgo/bitgoBase.ts b/modules/sdk-core/src/bitgo/bitgoBase.ts
@@ -14,6 +14,7 @@ import { EcdhDerivedKeypair, GetSigningKeyApi } from './keychain';
 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
+  /** @deprecated Use decryptAsync instead */
   decrypt(params: DecryptOptions): string;
   decryptAsync(params: DecryptOptions): Promise<string>;
   decryptKeys(params: DecryptKeysOptions): string[];
