feat: move hmac fns to own package

- define hmac related functions in
  separate module

Ticket: CE-5010

Author: bitgoAaron

modules/sdk-api/package.json

@@ -41,6 +41,7 @@
   },
   "dependencies": {
     "@bitgo/sdk-core": "^28.18.0",
+    "@bitgo/sdk-hmac": "^1.0.0",
     "@bitgo/sjcl": "^1.0.1",
     "@bitgo/unspents": "^0.47.17",
     "@bitgo/utxo-lib": "^11.2.1",

modules/sdk-api/src/api.ts

@@ -11,7 +11,7 @@ import querystring from 'querystring';
 
 import { ApiResponseError, BitGoRequest } from '@bitgo/sdk-core';
 
-import { VerifyResponseOptions } from './types';
+import { AuthVersion, VerifyResponseOptions } from './types';
 import { BitGoAPI } from './bitgoAPI';
 
 const debug = Debug('bitgo:api');
@@ -178,7 +178,8 @@ export function verifyResponse(
   token: string | undefined,
   method: VerifyResponseOptions['method'],
   req: superagent.SuperAgentRequest,
-  response: superagent.Response
+  response: superagent.Response,
+  authVersion: AuthVersion
 ): superagent.Response {
   // we can't verify the response if we're not authenticated
   if (!req.isV2Authenticated || !req.authenticationToken) {
@@ -193,6 +194,7 @@ export function verifyResponse(
     timestamp: response.header.timestamp,
     token: req.authenticationToken,
     method,
+    authVersion,
   });
 
   if (!verificationResponse.isValid) {

modules/sdk-api/src/bitgoAPI.ts

@@ -21,17 +21,15 @@ import {
   makeRandomKey,
   sanitizeLegacyPath,
 } from '@bitgo/sdk-core';
-import * as sjcl from '@bitgo/sjcl';
+import * as sdkHmac from '@bitgo/sdk-hmac';
 import * as utxolib from '@bitgo/utxo-lib';
 import { bip32, ECPairInterface } from '@bitgo/utxo-lib';
 import * as bitcoinMessage from 'bitcoinjs-message';
-import { createHmac } from 'crypto';
 import { type Agent } from 'http';
 import debugLib from 'debug';
 import * as _ from 'lodash';
 import * as secp256k1 from 'secp256k1';
 import * as superagent from 'superagent';
-import * as urlLib from 'url';
 import {
   handleResponseError,
   handleResponseResult,
@@ -396,6 +394,7 @@ export class BitGoAPI implements BitGoBase {
           token: this._token,
           method,
           text: data || '',
+          authVersion: this._authVersion,
         });
         req.set('Auth-Timestamp', requestProperties.timestamp.toString());
 
@@ -420,7 +419,7 @@ export class BitGoAPI implements BitGoBase {
               return onfulfilled(response);
             }
 
-            const verifiedResponse = verifyResponse(this, this._token, method, req, response);
+            const verifiedResponse = verifyResponse(this, this._token, method, req, response, this._authVersion);
             return onfulfilled(verifiedResponse);
           }
         : null;
@@ -455,7 +454,7 @@ export class BitGoAPI implements BitGoBase {
    * @returns {*} - the result of the HMAC operation
    */
   calculateHMAC(key: string, message: string): string {
-    return createHmac('sha256', key).update(message).digest('hex');
+    return sdkHmac.calculateHMAC(key, message);
   }
 
   /**
@@ -467,83 +466,29 @@ export class BitGoAPI implements BitGoBase {
    * @param method request method
    * @returns {string}
    */
-  calculateHMACSubject({ urlPath, text, timestamp, statusCode, method }: CalculateHmacSubjectOptions): string {
-    const urlDetails = urlLib.parse(urlPath);
-    const queryPath = urlDetails.query && urlDetails.query.length > 0 ? urlDetails.path : urlDetails.pathname;
-    if (!_.isUndefined(statusCode) && _.isInteger(statusCode) && _.isFinite(statusCode)) {
-      if (this._authVersion === 3) {
-        return [method.toUpperCase(), timestamp, queryPath, statusCode, text].join('|');
-      }
-      return [timestamp, queryPath, statusCode, text].join('|');
-    }
-    if (this._authVersion === 3) {
-      return [method.toUpperCase(), timestamp, '3.0', queryPath, text].join('|');
-    }
-    return [timestamp, queryPath, text].join('|');
+  calculateHMACSubject(params: CalculateHmacSubjectOptions): string {
+    return sdkHmac.calculateHMACSubject({ ...params, authVersion: this._authVersion });
   }
 
   /**
    * Calculate the HMAC for an HTTP request
    */
-  calculateRequestHMAC({ url: urlPath, text, timestamp, token, method }: CalculateRequestHmacOptions): string {
-    const signatureSubject = this.calculateHMACSubject({ urlPath, text, timestamp, method });
-
-    // calculate the HMAC
-    return this.calculateHMAC(token, signatureSubject);
+  calculateRequestHMAC(params: CalculateRequestHmacOptions): string {
+    return sdkHmac.calculateRequestHMAC({ ...params, authVersion: this._authVersion });
   }
 
   /**
    * Calculate request headers with HMAC
    */
-  calculateRequestHeaders({ url, text, token, method }: CalculateRequestHeadersOptions): RequestHeaders {
-    const timestamp = Date.now();
-    const hmac = this.calculateRequestHMAC({ url, text, timestamp, token, method });
-
-    // calculate the SHA256 hash of the token
-    const hashDigest = sjcl.hash.sha256.hash(token);
-    const tokenHash = sjcl.codec.hex.fromBits(hashDigest);
-    return {
-      hmac,
-      timestamp,
-      tokenHash,
-    };
+  calculateRequestHeaders(params: CalculateRequestHeadersOptions): RequestHeaders {
+    return sdkHmac.calculateRequestHeaders({ ...params, authVersion: this._authVersion });
   }
 
   /**
    * Verify the HMAC for an HTTP response
    */
-  verifyResponse({
-    url: urlPath,
-    statusCode,
-    text,
-    timestamp,
-    token,
-    hmac,
-    method,
-  }: VerifyResponseOptions): VerifyResponseInfo {
-    const signatureSubject = this.calculateHMACSubject({
-      urlPath,
-      text,
-      timestamp,
-      statusCode,
-      method,
-    });
-
-    // calculate the HMAC
-    const expectedHmac = this.calculateHMAC(token, signatureSubject);
-
-    // determine if the response is still within the validity window (5 minute window)
-    const now = Date.now();
-    const isInResponseValidityWindow = timestamp >= now - 1000 * 60 * 5 && timestamp <= now;
-
-    // verify the HMAC and timestamp
-    return {
-      isValid: expectedHmac === hmac,
-      expectedHmac,
-      signatureSubject,
-      isInResponseValidityWindow,
-      verificationTime: now,
-    };
+  verifyResponse(params: VerifyResponseOptions): VerifyResponseInfo {
+    return sdkHmac.verifyResponse({ ...params, authVersion: this._authVersion });
   }
 
   /**
@@ -904,7 +849,7 @@ export class BitGoAPI implements BitGoBase {
         this._ecdhXprv = responseDetails.ecdhXprv;
 
         // verify the response's authenticity
-        verifyResponse(this, responseDetails.token, 'post', request, response);
+        verifyResponse(this, responseDetails.token, 'post', request, response, this._authVersion);
 
         // add the remaining component for easier access
         response.body.access_token = this._token;
@@ -1186,7 +1131,7 @@ export class BitGoAPI implements BitGoBase {
       }
 
       // verify the authenticity of the server's response before proceeding any further
-      verifyResponse(this, this._token, 'post', request, response);
+      verifyResponse(this, this._token, 'post', request, response, this._authVersion);
 
       const responseDetails = this.handleTokenIssuance(response.body);
       response.body.token = responseDetails.token;

modules/sdk-api/src/types.ts

@@ -1,7 +1,16 @@
 import { EnvironmentName, IRequestTracer, V1Network } from '@bitgo/sdk-core';
 import { ECPairInterface } from '@bitgo/utxo-lib';
 import { type Agent } from 'http';
-
+export {
+  supportedRequestMethods,
+  AuthVersion,
+  CalculateHmacSubjectOptions,
+  CalculateRequestHmacOptions,
+  CalculateRequestHeadersOptions,
+  RequestHeaders,
+  VerifyResponseOptions,
+  VerifyResponseInfo,
+} from '@bitgo/sdk-hmac';
 export interface BitGoAPIOptions {
   accessToken?: string;
   authVersion?: 2 | 3;
@@ -36,54 +45,6 @@ export interface PingOptions {
   reqId?: IRequestTracer;
 }
 
-export const supportedRequestMethods = ['get', 'post', 'put', 'del', 'patch', 'options'] as const;
-
-export interface CalculateHmacSubjectOptions {
-  urlPath: string;
-  text: string;
-  timestamp: number;
-  method: (typeof supportedRequestMethods)[number];
-  statusCode?: number;
-}
-
-export interface CalculateRequestHmacOptions {
-  url: string;
-  text: string;
-  timestamp: number;
-  token: string;
-  method: (typeof supportedRequestMethods)[number];
-}
-
-export interface RequestHeaders {
-  hmac: string;
-  timestamp: number;
-  tokenHash: string;
-}
-
-export interface CalculateRequestHeadersOptions {
-  url: string;
-  text: string;
-  token: string;
-  method: (typeof supportedRequestMethods)[number];
-}
-
-export interface VerifyResponseOptions extends CalculateRequestHeadersOptions {
-  hmac: string;
-  url: string;
-  text: string;
-  timestamp: number;
-  method: (typeof supportedRequestMethods)[number];
-  statusCode?: number;
-}
-
-export interface VerifyResponseInfo {
-  isValid: boolean;
-  expectedHmac: string;
-  signatureSubject: string;
-  isInResponseValidityWindow: boolean;
-  verificationTime: number;
-}
-
 export interface AuthenticateOptions {
   username: string;
   password: string;

modules/sdk-hmac/.eslintignore

@@ -0,0 +1,2 @@
+dist/
+src/opensslbytes.ts

modules/sdk-hmac/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.idea/
+dist/

modules/sdk-hmac/.mocharc.yml

@@ -0,0 +1,8 @@
+require: 'ts-node/register'
+timeout: '60000'
+reporter: 'min'
+reporter-option:
+  - 'cdn=true'
+  - 'json=false'
+exit: true
+spec: ['test/**/*.ts']

modules/sdk-hmac/.npmignore

@@ -0,0 +1,12 @@
+!dist/
+.idea/
+.prettierrc.yml
+tsconfig.json
+src/
+test/
+scripts/
+.nyc_output
+CODEOWNERS
+node_modules/
+.prettierignore
+.mocharc.js

modules/sdk-hmac/.prettierignore

@@ -0,0 +1,2 @@
+.nyc_output/
+dist/

modules/sdk-hmac/.prettierrc.yml

@@ -0,0 +1,3 @@
+printWidth: 120
+singleQuote: true
+trailingComma: 'es5'