feat(sdk-hmac): added Buffer support for HMAC subject text

TICKET: ANT-1025

Author: sasikumar-bitgo

modules/sdk-hmac/src/hmac.ts

@@ -21,13 +21,34 @@ export function calculateHMAC(key: string | BinaryLike | KeyObject, message: str
 }
 
 /**
- * Calculate the subject string that is to be HMAC'ed for a HTTP request or response
+ * Utility to join segments with '|' delimiter
+ * Returns Buffer when text segment is Buffer, string otherwise
+ */
+function joinSegments(segments: Array<string | number | Buffer>): string | Buffer {
+  const hasBuffer = segments.some((s) => Buffer.isBuffer(s));
+
+  if (hasBuffer) {
+    const parts: Buffer[] = [];
+    const sep = Buffer.from('|', 'utf8');
+    for (let i = 0; i < segments.length; i++) {
+      if (i > 0) parts.push(sep);
+      const seg = segments[i];
+      parts.push(Buffer.isBuffer(seg) ? seg : Buffer.from(String(seg), 'utf8'));
+    }
+    return Buffer.concat(parts);
+  }
+
+  return segments.join('|');
+}
+
+/**
+ * Calculate the subject that is to be HMAC'ed for a HTTP request or response
  * @param urlPath request url, including query params
- * @param text request body text
+ * @param text request body text (string or Buffer)
  * @param timestamp request timestamp from `Date.now()`
  * @param statusCode Only set for HTTP responses, leave blank for requests
  * @param method request method
- * @returns {string}
+ * @returns {string | Buffer} - returns Buffer when text is Buffer, string otherwise
  */
 export function calculateHMACSubject({
   urlPath,
@@ -36,23 +57,24 @@ 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;
+  const queryPath = (urlDetails.query && urlDetails.query.length > 0 ? urlDetails.path : urlDetails.pathname) || '';
+
   if (statusCode !== undefined && isFinite(statusCode) && Number.isInteger(statusCode)) {
     if (authVersion === 3) {
-      return [method.toUpperCase(), timestamp, queryPath, statusCode, text].join('|');
+      return joinSegments([method.toUpperCase(), timestamp, queryPath, statusCode, text]);
     }
-    return [timestamp, queryPath, statusCode, text].join('|');
+    return joinSegments([timestamp, queryPath, statusCode, text]);
   }
   if (authVersion === 3) {
-    return [method.toUpperCase(), timestamp, '3.0', queryPath, text].join('|');
+    return joinSegments([method.toUpperCase(), timestamp, '3.0', queryPath, text]);
   }
-  return [timestamp, queryPath, text].join('|');
+  return joinSegments([timestamp, queryPath, 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,46 @@ describe('HMAC Utility Functions', () => {
         })
       ).to.equal(expectedSubject);
     });
+
+    it('should return Buffer when text is Buffer (request)', () => {
+      const expectedSubject = 'GET|1672531200000|3.0|/api/test?query=123|body-content';
+      const result = calculateHMACSubject({
+        urlPath: '/api/test?query=123',
+        text: Buffer.from('body-content', 'utf8'),
+        timestamp: MOCK_TIMESTAMP,
+        method: 'get',
+        authVersion: 3,
+      });
+      expect(Buffer.isBuffer(result)).to.be.true;
+      expect(result.toString('utf8')).to.equal(expectedSubject);
+    });
+
+    it('should return Buffer when text is Buffer (response with statusCode)', () => {
+      const expectedSubject = 'GET|1672531200000|/api/test|200|response-body';
+      const result = calculateHMACSubject({
+        urlPath: '/api/test',
+        text: Buffer.from('response-body', 'utf8'),
+        timestamp: MOCK_TIMESTAMP,
+        statusCode: 200,
+        method: 'get',
+        authVersion: 3,
+      });
+      expect(Buffer.isBuffer(result)).to.be.true;
+      expect(result.toString('utf8')).to.equal(expectedSubject);
+    });
+
+    it('should handle Buffer text with authVersion 2', () => {
+      const expectedSubject = '1672531200000|/api/test|request-body';
+      const result = calculateHMACSubject({
+        urlPath: '/api/test',
+        text: Buffer.from('request-body', 'utf8'),
+        timestamp: MOCK_TIMESTAMP,
+        method: 'post',
+        authVersion: 2,
+      });
+      expect(Buffer.isBuffer(result)).to.be.true;
+      expect(result.toString('utf8')).to.equal(expectedSubject);
+    });
   });
 
   describe('calculateRequestHMAC', () => {
@@ -113,7 +153,7 @@ describe('HMAC Utility Functions', () => {
   });
 
   describe('verifyResponse', () => {
-    it('should verify the HMAC and timestamp validity', () => {
+    it('should verify the HMAC and timestamp validity with string text', () => {
       const result = verifyResponse({
         url: '/api/test',
         statusCode: 200,
@@ -130,6 +170,7 @@ describe('HMAC Utility Functions', () => {
         expectedHmac: 'a16c08b1fa8bff1e2e58d1831855e1745361f78bd6eb6e18b5b7ee17ae0a3bb7',
         isInResponseValidityWindow: true,
       });
+      expect(typeof result.signatureSubject).to.equal('string');
     });
 
     it('should return invalid if HMAC does not match', () => {
@@ -161,5 +202,23 @@ describe('HMAC Utility Functions', () => {
 
       expect(result.isInResponseValidityWindow).to.be.false;
     });
+
+    it('should return Buffer signatureSubject when text is Buffer', () => {
+      const textBuffer = Buffer.from('response-body', 'utf8');
+      const result = verifyResponse({
+        url: '/api/test',
+        statusCode: 200,
+        text: textBuffer,
+        timestamp: MOCK_TIMESTAMP,
+        token: 'test-token',
+        hmac: 'a16c08b1fa8bff1e2e58d1831855e1745361f78bd6eb6e18b5b7ee17ae0a3bb7',
+        method: 'post',
+        authVersion: 3,
+      });
+
+      expect(result.isValid).to.be.true;
+      expect(Buffer.isBuffer(result.signatureSubject)).to.be.true;
+      expect(result.signatureSubject.toString('utf8')).to.equal('POST|1672531200000|/api/test|200|response-body');
+    });
   });
 });