feat(sdk-api): add verification flow for v4

TICKET: CAAS-819

Author: MohammedRyaan786

modules/express/src/clientRoutes.ts

@@ -1323,7 +1323,7 @@ function parseBody(req: express.Request, res: express.Response, next: express.Ne
  * @param config
  */
 function prepareBitGo(config: Config) {
-  const { env, customRootUri, customBitcoinNetwork } = config;
+  const { env, customRootUri, customBitcoinNetwork, authVersion } = config;
 
   return function prepBitGo(req: express.Request, res: express.Response, next: express.NextFunction) {
     // Get access token
@@ -1343,6 +1343,7 @@ function prepareBitGo(config: Config) {
       env,
       customRootURI: customRootUri,
       customBitcoinNetwork,
+      authVersion,
       accessToken,
       userAgent,
       ...(useProxyUrl

modules/express/src/config.ts

@@ -4,6 +4,19 @@ import 'dotenv/config';
 
 import { args } from './args';
 
+// Falls back to auth version 2 for unrecognized values, preserving existing behavior
+// where invalid authVersion values silently defaulted to v2.
+// Returns undefined when no value is provided, so mergeConfigs can fall through to other sources.
+function parseAuthVersion(val: number | undefined): 2 | 3 | 4 | undefined {
+  if (val === undefined || isNaN(val)) {
+    return undefined;
+  }
+  if (val === 2 || val === 3 || val === 4) {
+    return val;
+  }
+  return 2;
+}
+
 function readEnvVar(name, ...deprecatedAliases): string | undefined {
   if (process.env[name] !== undefined && process.env[name] !== '') {
     return process.env[name];
@@ -36,7 +49,7 @@ export interface Config {
   timeout: number;
   customRootUri?: string;
   customBitcoinNetwork?: V1Network;
-  authVersion: number;
+  authVersion: 2 | 3 | 4;
   externalSignerUrl?: string;
   signerMode?: boolean;
   signerFileSystemPath?: string;
@@ -62,7 +75,7 @@ export const ArgConfig = (args): Partial<Config> => ({
   timeout: args.timeout,
   customRootUri: args.customrooturi,
   customBitcoinNetwork: args.custombitcoinnetwork,
-  authVersion: args.authVersion,
+  authVersion: parseAuthVersion(args.authVersion),
   externalSignerUrl: args.externalSignerUrl,
   signerMode: args.signerMode,
   signerFileSystemPath: args.signerFileSystemPath,
@@ -88,7 +101,7 @@ export const EnvConfig = (): Partial<Config> => ({
   timeout: Number(readEnvVar('BITGO_TIMEOUT')),
   customRootUri: readEnvVar('BITGO_CUSTOM_ROOT_URI'),
   customBitcoinNetwork: readEnvVar('BITGO_CUSTOM_BITCOIN_NETWORK') as V1Network,
-  authVersion: Number(readEnvVar('BITGO_AUTH_VERSION')),
+  authVersion: parseAuthVersion(Number(readEnvVar('BITGO_AUTH_VERSION'))),
   externalSignerUrl: readEnvVar('BITGO_EXTERNAL_SIGNER_URL'),
   signerMode: readEnvVar('BITGO_SIGNER_MODE') ? true : undefined,
   signerFileSystemPath: readEnvVar('BITGO_SIGNER_FILE_SYSTEM_PATH'),

modules/sdk-api/src/api.ts

@@ -10,6 +10,7 @@ import urlLib from 'url';
 import querystring from 'querystring';
 
 import { ApiResponseError, BitGoRequest } from '@bitgo/sdk-core';
+import { extractPathWithQuery } from '@bitgo/sdk-hmac';
 
 import { AuthVersion, VerifyResponseOptions } from './types';
 import { BitGoAPI } from './bitgoAPI';
@@ -213,63 +214,171 @@ export function setRequestQueryString(req: superagent.SuperAgentRequest): void {
   }
 }
 
+/** Result from version-specific response verification. */
+interface ResponseVerificationResult {
+  verificationResult: {
+    isValid: boolean;
+    expectedHmac: string;
+    isInResponseValidityWindow: boolean;
+    verificationTime: number;
+  };
+  hmacErrorDetails: Record<string, unknown>;
+  responseTimestamp: string | number;
+}
+
 /**
- * Verify that the response received from the server is signed correctly.
- * Right now, it is very permissive with the timestamp variance.
+ * Verify a v4 server response HMAC.
+ *
+ * Returns undefined if the server didn't sign the response (e.g. error before
+ * auth middleware ran), signalling the caller to pass the response through
+ * without verification.
+ *
+ * @param authToken - The raw access token (HMAC key). Guaranteed non-undefined by the caller.
  */
-export function verifyResponse(
+function verifyV4ResponseHeaders(
   bitgo: BitGoAPI,
-  token: string | undefined,
   method: VerifyResponseOptions['method'],
   req: superagent.SuperAgentRequest,
   response: superagent.Response,
-  authVersion: AuthVersion
-): superagent.Response {
-  // we can't verify the response if we're not authenticated
-  if (!req.isV2Authenticated || !req.authenticationToken) {
-    return response;
+  authToken: string
+): ResponseVerificationResult | undefined {
+  const hmac = response.header['x-signature'];
+  const timestamp = response.header['x-request-timestamp'];
+  const authRequestId = response.header['x-auth-request-id'];
+
+  if (!hmac || !timestamp) {
+    // Server didn't sign the response. This can happen legitimately when the
+    // request fails before reaching the auth middleware (e.g. 401/404).
+    debug(
+      'v4 response verification skipped: server response (status %d) missing HMAC headers (x-signature: %s, x-request-timestamp: %s)',
+      response.status,
+      hmac ? 'present' : 'missing',
+      timestamp ? 'present' : 'missing'
+    );
+    return undefined;
+  }
+
+  // Hash the raw response body bytes.
+  // Convert response.text to a Buffer (UTF-8) so we're hashing the actual bytes,
+  // not relying on Node's implicit string encoding in crypto.update().
+  const rawResponseBuffer = Buffer.from(response.text || '');
+  const bodyHashHex = bitgo.calculateBodyHash(rawResponseBuffer);
+
+  // req.v4PathWithQuery is always set by requestPatch; fallback parses req.url as a safety net.
+  let pathWithQuery = req.v4PathWithQuery;
+  if (!pathWithQuery) {
+    // Use sdk-hmac's extractPathWithQuery helper which handles both absolute URLs
+    pathWithQuery = extractPathWithQuery(req.url);
   }
 
-  const verificationResponse = bitgo.verifyResponse({
+  const result = bitgo.verifyResponse({
+    hmac,
+    timestampSec: Number(timestamp),
+    method: req.v4Method || method,
+    pathWithQuery,
+    bodyHashHex,
+    authRequestId: authRequestId || req.v4AuthRequestId || '',
+    statusCode: response.status,
+    rawToken: authToken,
+  });
+
+  return {
+    verificationResult: result,
+    responseTimestamp: timestamp,
+    hmacErrorDetails: { expectedHmac: result.expectedHmac, receivedHmac: hmac, preimage: result.preimage },
+  };
+}
+
+/**
+ * Verify a v2/v3 server response HMAC.
+ *
+ * @param authToken - The raw access token (HMAC key). Guaranteed non-undefined by the caller.
+ */
+function verifyV2V3ResponseHeaders(
+  bitgo: BitGoAPI,
+  token: string | undefined,
+  method: VerifyResponseOptions['method'],
+  req: superagent.SuperAgentRequest,
+  response: superagent.Response,
+  authVersion: AuthVersion,
+  authToken: string
+): ResponseVerificationResult {
+  const result = bitgo.verifyResponse({
     url: req.url,
     hmac: response.header.hmac,
     statusCode: response.status,
     text: response.text,
     timestamp: response.header.timestamp,
-    token: req.authenticationToken,
+    token: authToken,
     method,
     authVersion,
   });
 
-  if (!verificationResponse.isValid) {
-    // calculate the HMAC
-    const receivedHmac = response.header.hmac;
-    const expectedHmac = verificationResponse.expectedHmac;
-    const signatureSubject = verificationResponse.signatureSubject;
-    // Log only the first 10 characters of the token to ensure the full token isn't logged.
-    const partialBitgoToken = token ? token.substring(0, 10) : '';
-    const errorDetails = {
-      expectedHmac,
-      receivedHmac,
-      hmacInput: signatureSubject,
-      requestToken: req.authenticationToken,
+  const partialBitgoToken = token ? token.substring(0, 10) : '';
+  return {
+    verificationResult: result,
+    responseTimestamp: response.header.timestamp,
+    hmacErrorDetails: {
+      expectedHmac: result.expectedHmac,
+      receivedHmac: response.header.hmac,
+      hmacInput: result.signatureSubject,
+      requestToken: authToken,
       bitgoToken: partialBitgoToken,
-    };
-    debug('Invalid response HMAC: %O', errorDetails);
-    throw new ApiResponseError('invalid response HMAC, possible man-in-the-middle-attack', 511, errorDetails);
+    },
+  };
+}
+
+/**
+ * Verify that the response received from the server is signed correctly.
+ * Right now, it is very permissive with the timestamp variance.
+ */
+export function verifyResponse(
+  bitgo: BitGoAPI,
+  token: string | undefined,
+  method: VerifyResponseOptions['method'],
+  req: superagent.SuperAgentRequest,
+  response: superagent.Response,
+  authVersion: AuthVersion
+): superagent.Response {
+  // we can't verify the response if we're not authenticated
+  if (!req.isV2Authenticated || !req.authenticationToken) {
+    return response;
   }
 
-  if (bitgo.getAuthVersion() === 3 && !verificationResponse.isInResponseValidityWindow) {
-    const errorDetails = {
-      timestamp: response.header.timestamp,
-      verificationTime: verificationResponse.verificationTime,
-    };
+  // --- Build version-specific params, call bitgo.verifyResponse(), collect error context ---
+  // req.authenticationToken is guaranteed non-undefined here (checked above).
+  const authToken = req.authenticationToken as string;
+  let result: ResponseVerificationResult;
+
+  if (authVersion === 4) {
+    const v4Result = verifyV4ResponseHeaders(bitgo, method, req, response, authToken);
+    if (!v4Result) {
+      // Server didn't sign the response — pass through without verification
+      return response;
+    }
+    result = v4Result;
+  } else {
+    result = verifyV2V3ResponseHeaders(bitgo, token, method, req, response, authVersion, authToken);
+  }
+
+  // --- Common validation for all auth versions ---
+  const { verificationResult, hmacErrorDetails, responseTimestamp } = result;
+
+  if (!verificationResult.isValid) {
+    debug('Invalid response HMAC: %O', hmacErrorDetails);
+    throw new ApiResponseError('invalid response HMAC, possible man-in-the-middle-attack', 511, hmacErrorDetails);
+  }
+
+  // v3 and v4 enforce the response validity window; v2 does not
+  if (authVersion >= 3 && !verificationResult.isInResponseValidityWindow) {
+    const errorDetails = { timestamp: responseTimestamp, verificationTime: verificationResult.verificationTime };
     debug('Server response outside response validity time window: %O', errorDetails);
     throw new ApiResponseError(
       'server response outside response validity time window, possible man-in-the-middle-attack',
       511,
       errorDetails
     );
   }
+
   return response;
 }