feat: add Buffer support for HMAC generation

Ticket: ANT-1033

Author: bdesoky

modules/sdk-api/src/bitgoAPI.ts

@@ -522,7 +522,7 @@ export class BitGoAPI implements BitGoBase {
    * @param method request method
    * @returns {string}
    */
-  calculateHMACSubject(params: CalculateHmacSubjectOptions): string {
+  calculateHMACSubject(params: CalculateHmacSubjectOptions): string | Buffer {
     return sdkHmac.calculateHMACSubject({ ...params, authVersion: this._authVersion });
   }
 

modules/sdk-hmac/src/hmac.ts

@@ -27,7 +27,8 @@ export function calculateHMAC(key: string | BinaryLike | KeyObject, message: str
  * @param timestamp request timestamp from `Date.now()`
  * @param statusCode Only set for HTTP responses, leave blank for requests
  * @param method request method
- * @returns {string}
+ * @param authVersion authentication version (2 or 3)
+ * @returns {string | Buffer}
  */
 export function calculateHMACSubject({
   urlPath,
@@ -36,23 +37,33 @@ export function calculateHMACSubject({
   statusCode,
   method,
   authVersion,
-}: CalculateHmacSubjectOptions): string {
+}: CalculateHmacSubjectOptions): string | Buffer {
   /* Normalize legacy 'del' to 'delete' for backward compatibility */
   if (method === 'del') {
     method = 'delete';
   }
   const urlDetails = urlLib.parse(urlPath);
   const queryPath = urlDetails.query && urlDetails.query.length > 0 ? urlDetails.path : urlDetails.pathname;
+
+  let prefixedText: string;
   if (statusCode !== undefined && isFinite(statusCode) && Number.isInteger(statusCode)) {
-    if (authVersion === 3) {
-      return [method.toUpperCase(), timestamp, queryPath, statusCode, text].join('|');
-    }
-    return [timestamp, queryPath, statusCode, text].join('|');
+    prefixedText =
+      authVersion === 3
+        ? [method.toUpperCase(), timestamp, queryPath, statusCode].join('|')
+        : [timestamp, queryPath, statusCode].join('|');
+  } else {
+    prefixedText =
+      authVersion === 3
+        ? [method.toUpperCase(), timestamp, '3.0', queryPath].join('|')
+        : [timestamp, queryPath].join('|');
   }
-  if (authVersion === 3) {
-    return [method.toUpperCase(), timestamp, '3.0', queryPath, text].join('|');
+  prefixedText += '|';
+
+  const isBuffer = Buffer.isBuffer(text);
+  if (isBuffer) {
+    return Buffer.concat([Buffer.from(prefixedText, 'utf-8'), text]);
   }
-  return [timestamp, queryPath, text].join('|');
+  return prefixedText + text;
 }
 
 /**

modules/sdk-hmac/src/types.ts

@@ -4,7 +4,7 @@ export type AuthVersion = 2 | 3;
 
 export interface CalculateHmacSubjectOptions {
   urlPath: string;
-  text: string;
+  text: string | Buffer;
   timestamp: number;
   method: (typeof supportedRequestMethods)[number];
   statusCode?: number;
@@ -13,7 +13,7 @@ export interface CalculateHmacSubjectOptions {
 
 export interface CalculateRequestHmacOptions {
   url: string;
-  text: string;
+  text: string | Buffer;
   timestamp: number;
   token: string;
   method: (typeof supportedRequestMethods)[number];
@@ -22,7 +22,7 @@ export interface CalculateRequestHmacOptions {
 
 export interface CalculateRequestHeadersOptions {
   url: string;
-  text: string;
+  text: string | Buffer;
   token: string;
   method: (typeof supportedRequestMethods)[number];
   authVersion: AuthVersion;
@@ -37,7 +37,7 @@ export interface RequestHeaders {
 export interface VerifyResponseOptions extends CalculateRequestHeadersOptions {
   hmac: string;
   url: string;
-  text: string;
+  text: string | Buffer;
   timestamp: number;
   method: (typeof supportedRequestMethods)[number];
   statusCode?: number;
@@ -47,7 +47,7 @@ export interface VerifyResponseOptions extends CalculateRequestHeadersOptions {
 export interface VerifyResponseInfo {
   isValid: boolean;
   expectedHmac: string;
-  signatureSubject: string;
+  signatureSubject: string | Buffer;
   isInResponseValidityWindow: boolean;
   verificationTime: number;
 }

modules/sdk-hmac/test/hmac.ts

@@ -74,6 +74,49 @@ describe('HMAC Utility Functions', () => {
         })
       ).to.equal(expectedSubject);
     });
+
+    it('should handle Buffer text input and return a Buffer for requests', () => {
+      const buffer = Buffer.from('binary-data-content');
+      const result = calculateHMACSubject({
+        urlPath: '/api/test',
+        text: buffer,
+        timestamp: MOCK_TIMESTAMP,
+        method: 'get',
+        authVersion: 3,
+      });
+
+      expect(Buffer.isBuffer(result)).to.be.true;
+
+      // Check the content structure
+      const expectedPrefix = 'GET|1672531200000|3.0|/api/test|';
+      const prefixBuffer = Buffer.from(expectedPrefix, 'utf8');
+
+      // Manually reconstruct the expected buffer to compare
+      const expectedBuffer = Buffer.concat([prefixBuffer, buffer]);
+      expect(result).to.deep.equal(expectedBuffer);
+    });
+
+    it('should handle Buffer text input and return a Buffer for responses', () => {
+      const buffer = Buffer.from('binary-response-data');
+      const result = calculateHMACSubject({
+        urlPath: '/api/test',
+        text: buffer,
+        timestamp: MOCK_TIMESTAMP,
+        statusCode: 200,
+        method: 'get',
+        authVersion: 3,
+      });
+
+      expect(Buffer.isBuffer(result)).to.be.true;
+
+      // Check the content structure
+      const expectedPrefix = 'GET|1672531200000|/api/test|200|';
+      const prefixBuffer = Buffer.from(expectedPrefix, 'utf8');
+
+      // Manually reconstruct the expected buffer to compare
+      const expectedBuffer = Buffer.concat([prefixBuffer, buffer]);
+      expect(result).to.deep.equal(expectedBuffer);
+    });
   });
 
   describe('calculateRequestHMAC', () => {
@@ -161,5 +204,37 @@ describe('HMAC Utility Functions', () => {
 
       expect(result.isInResponseValidityWindow).to.be.false;
     });
+
+    it('should verify response with Buffer data', () => {
+      const responseData = Buffer.from('binary-response-data');
+
+      // First create an HMAC for this binary data
+      const signatureSubject = calculateHMACSubject({
+        urlPath: '/api/test',
+        text: responseData,
+        timestamp: MOCK_TIMESTAMP,
+        statusCode: 200,
+        method: 'post',
+        authVersion: 3,
+      });
+
+      const token = 'test-token';
+      const expectedHmac = calculateHMAC(token, signatureSubject);
+
+      // Now verify using the generated HMAC
+      const result = verifyResponse({
+        url: '/api/test',
+        statusCode: 200,
+        text: responseData, // Use binary data here
+        timestamp: MOCK_TIMESTAMP,
+        token: token,
+        hmac: expectedHmac,
+        method: 'post',
+        authVersion: 3,
+      });
+      expect(result.isValid).to.be.true;
+      expect(result.expectedHmac).to.equal(expectedHmac);
+      expect(Buffer.isBuffer(result.signatureSubject)).to.be.true;
+    });
   });
 });