feat(sdk-api): replace manual v2 envelope validation with io-ts codec

Replace hand-written if-checks and V2Envelope interface with a
V2EnvelopeCodec that enforces type safety, Argon2id parameter caps,
and non-empty base64 strings in a single decode step.

WCN-30

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

TICKET: WCN-30

Author: pranavjain97

modules/sdk-api/package.json

@@ -42,6 +42,7 @@
   "dependencies": {
     "@bitgo/argon2": "^1.0.0",
     "@bitgo/sdk-core": "^36.40.0",
+    "io-ts": "npm:@bitgo-forks/io-ts@2.1.4",
     "@bitgo/sdk-hmac": "^1.9.0",
     "@bitgo/sjcl": "^1.1.0",
     "@bitgo/unspents": "^0.51.3",

modules/sdk-api/src/encrypt.ts

@@ -1,5 +1,7 @@
+import { base64String, boundedInt, decodeWithCodec } from '@bitgo/sdk-core';
 import * as sjcl from '@bitgo/sjcl';
 import { randomBytes } from 'crypto';
+import * as t from 'io-ts';
 
 /** Default Argon2id parameters per RFC 9106 second recommendation
  * @see https://www.rfc-editor.org/rfc/rfc9106#section-4
@@ -26,15 +28,17 @@ const ARGON2_MAX = {
 /** AES-256-GCM IV length in bytes */
 const GCM_IV_LENGTH = 12;
 
-export interface V2Envelope {
-  v: 2;
-  m: number;
-  t: number;
-  p: number;
-  salt: string;
-  iv: string;
-  ct: string;
-}
+const V2EnvelopeCodec = t.type({
+  v: t.literal(2),
+  m: boundedInt(1, ARGON2_MAX.memorySize, 'memorySize'),
+  t: boundedInt(1, ARGON2_MAX.iterations, 'iterations'),
+  p: boundedInt(1, ARGON2_MAX.parallelism, 'parallelism'),
+  salt: base64String,
+  iv: base64String,
+  ct: base64String,
+});
+
+export type V2Envelope = t.TypeOf<typeof V2EnvelopeCodec>;
 
 /**
  * convert a 4 element Uint8Array to a 4 byte Number
@@ -197,25 +201,14 @@ export async function encryptV2(
  * The envelope must contain: v, m, t, p, salt, iv, ct.
  */
 export async function decryptV2(password: string, ciphertext: string): Promise<string> {
-  let envelope: V2Envelope;
+  let parsed: unknown;
   try {
-    envelope = JSON.parse(ciphertext);
+    parsed = 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.m > ARGON2_MAX.memorySize || envelope.m < 1) {
-    throw new Error(`v2 decrypt: memorySize ${envelope.m} exceeds allowed range [1, ${ARGON2_MAX.memorySize}]`);
-  }
-  if (envelope.t > ARGON2_MAX.iterations || envelope.t < 1) {
-    throw new Error(`v2 decrypt: iterations ${envelope.t} exceeds allowed range [1, ${ARGON2_MAX.iterations}]`);
-  }
-  if (envelope.p > ARGON2_MAX.parallelism || envelope.p < 1) {
-    throw new Error(`v2 decrypt: parallelism ${envelope.p} exceeds allowed range [1, ${ARGON2_MAX.parallelism}]`);
-  }
+  const envelope = decodeWithCodec(V2EnvelopeCodec, parsed, 'v2 decrypt: invalid envelope');
 
   const salt = new Uint8Array(Buffer.from(envelope.salt, 'base64'));
   const iv = new Uint8Array(Buffer.from(envelope.iv, 'base64'));

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

@@ -122,7 +122,7 @@ describe('encryption methods tests', () => {
     });
 
     it('throws on wrong envelope version', async () => {
-      await assert.rejects(() => decryptV2(password, JSON.stringify({ v: 99 })), /unsupported envelope version/);
+      await assert.rejects(() => decryptV2(password, JSON.stringify({ v: 99 })), /invalid envelope/);
     });
 
     it('throws on invalid salt length', async () => {
@@ -135,7 +135,37 @@ describe('encryption methods tests', () => {
 
     it('v1 and v2 are independent (v1 data does not decrypt with v2)', async () => {
       const v1ct = encrypt(password, plaintext);
-      await assert.rejects(() => decryptV2(password, v1ct), /unsupported envelope version/);
+      await assert.rejects(() => decryptV2(password, v1ct), /invalid envelope/);
+    });
+
+    it('rejects envelope with memorySize exceeding max', async () => {
+      const envelope = { v: 2, m: 999999999, t: 3, p: 4, salt: 'AAAA', iv: 'AAAA', ct: 'AAAA' };
+      await assert.rejects(() => decryptV2(password, JSON.stringify(envelope)), /invalid envelope/);
+    });
+
+    it('rejects envelope with iterations exceeding max', async () => {
+      const envelope = { v: 2, m: 65536, t: 100, p: 4, salt: 'AAAA', iv: 'AAAA', ct: 'AAAA' };
+      await assert.rejects(() => decryptV2(password, JSON.stringify(envelope)), /invalid envelope/);
+    });
+
+    it('rejects envelope with parallelism exceeding max', async () => {
+      const envelope = { v: 2, m: 65536, t: 3, p: 100, salt: 'AAAA', iv: 'AAAA', ct: 'AAAA' };
+      await assert.rejects(() => decryptV2(password, JSON.stringify(envelope)), /invalid envelope/);
+    });
+
+    it('rejects envelope with zero-valued parameters', async () => {
+      const envelope = { v: 2, m: 0, t: 3, p: 4, salt: 'AAAA', iv: 'AAAA', ct: 'AAAA' };
+      await assert.rejects(() => decryptV2(password, JSON.stringify(envelope)), /invalid envelope/);
+    });
+
+    it('rejects envelope with non-numeric parameter types', async () => {
+      const envelope = { v: 2, m: '65536', t: 3, p: 4, salt: 'AAAA', iv: 'AAAA', ct: 'AAAA' };
+      await assert.rejects(() => decryptV2(password, JSON.stringify(envelope)), /invalid envelope/);
+    });
+
+    it('rejects envelope with empty salt', async () => {
+      const envelope = { v: 2, m: 65536, t: 3, p: 4, salt: '', iv: 'AAAA', ct: 'AAAA' };
+      await assert.rejects(() => decryptV2(password, JSON.stringify(envelope)), /invalid envelope/);
     });
   });
 

modules/sdk-core/src/bitgo/utils/codecs.ts

@@ -0,0 +1,36 @@
+import * as E from 'fp-ts/Either';
+import * as t from 'io-ts';
+
+/** io-ts codec for an integer within [min, max]. Rejects non-numbers, floats, and out-of-range values. */
+export const boundedInt = (min: number, max: number, label: string) =>
+  new t.Type<number, number, unknown>(
+    label,
+    (u): u is number => typeof u === 'number' && Number.isInteger(u) && u >= min && u <= max,
+    (u, c) =>
+      typeof u === 'number' && Number.isInteger(u) && u >= min && u <= max
+        ? t.success(u)
+        : t.failure(u, c, `${label}: expected integer in [${min}, ${max}], got ${JSON.stringify(u)}`),
+    t.identity
+  );
+
+/** io-ts codec for a non-empty string (intended for base64-encoded binary fields). */
+export const base64String = new t.Type<string, string, unknown>(
+  'Base64String',
+  (u): u is string => typeof u === 'string' && u.length > 0,
+  (u, c) =>
+    typeof u === 'string' && u.length > 0 ? t.success(u) : t.failure(u, c, 'expected non-empty base64 string'),
+  t.identity
+);
+
+/**
+ * Decode unknown input with an io-ts codec. Returns the decoded value or throws
+ * with a descriptive error message. Use when callers should not depend on fp-ts/io-ts directly.
+ */
+export function decodeWithCodec<A>(codec: t.Type<A, unknown, unknown>, input: unknown, label: string): A {
+  const result = codec.decode(input);
+  if (E.isLeft(result)) {
+    const errors = result.left.map((e) => e.message ?? 'unknown').join('; ');
+    throw new Error(`${label}: ${errors}`);
+  }
+  return result.right;
+}

modules/sdk-core/src/bitgo/utils/index.ts

@@ -7,6 +7,7 @@ export * from './promise-utils';
 export * from './triple';
 export * from './tss';
 export * from './util';
+export * from './codecs';
 export * from './decode';
 export * from './notEmpty';
 export * from './wallet';