Add validateHMACSignature

Author: gcatanese

src/utils/hmacValidator.ts

@@ -27,12 +27,26 @@ class HmacValidator {
     public static HMAC_SHA256_ALGORITHM = "sha256";
     public static DATA_SEPARATOR = ":";
 
+    /**
+     * Calculate HMAC signature of the payload data
+     * @param data payload as String or as NotificationRequestItem
+     * @param key HMAC key
+     * @returns HMAC signature
+     */
     public calculateHmac(data: string | NotificationRequestItem, key: string): string {
         const dataString = typeof data !== "string" ? this.getDataToSign(data) : data;
         const rawKey = Buffer.from(key, "hex");
         return createHmac(HmacValidator.HMAC_SHA256_ALGORITHM, rawKey).update(dataString, "utf8").digest("base64");
     }
 
+    /**
+     * @deprecated use Use validateHMACSignature with correct parameter order instead
+     * Validate HMAC signature for Banking webhooks
+     * @param hmacKey 
+     * @param hmacSign 
+     * @param notification 
+     * @returns 
+     */
     public validateBankingHMAC(hmacKey: string, hmacSign: string, notification: string): boolean {
         const expectedSign = createHmac(HmacValidator.HMAC_SHA256_ALGORITHM, Buffer.from(hmacSign, "hex")).update(notification, "utf8").digest("base64");
         if(hmacKey?.length === expectedSign.length) {
@@ -44,6 +58,30 @@ class HmacValidator {
         return false;
     }
 
+    /**
+     * Validate HMAC signature for Banking/Management webhooks
+     * @param hmacKey HMAC key
+     * @param hmacSignature HMAC signature to validate 
+     * @param data webhook payload (as string)
+     * @returns true when HMAC signature is valid
+     */
+    public validateHMACSignature(hmacKey: string, hmacSignature: string, data: string): boolean {
+        const expectedSign = createHmac(HmacValidator.HMAC_SHA256_ALGORITHM, Buffer.from(hmacKey, "hex")).update(data, "utf8").digest("base64");
+        if(hmacSignature?.length === expectedSign.length) {
+            return timingSafeEqual(
+                Buffer.from(expectedSign, "base64"),
+                Buffer.from(hmacSignature, "base64")
+            );
+        }
+        return false;
+    }
+
+    /**
+     * Validate HMAC signature for Payment webhooks
+     * @param notificationRequestItem webhook payload (as NotificationRequestItem object)
+     * @param key HMAC key
+     * @returns true when HMAC signature is valid
+     */
     public validateHMAC(notificationRequestItem: NotificationRequestItem, key: string): boolean {
         if (notificationRequestItem.additionalData?.[ApiConstants.HMAC_SIGNATURE]) {
             const expectedSign = this.calculateHmac(notificationRequestItem, key);
@@ -55,7 +93,6 @@ class HmacValidator {
                 );
             }
             return false;
-
         }
         throw Error(`Missing ${ApiConstants.HMAC_SIGNATURE}`);
     }
@@ -64,6 +101,11 @@ class HmacValidator {
         return !Object.values(item).every((value): boolean => typeof value === "string");
     }
 
+    /**
+     * extract fields to be used to calculate the HMAC signature
+     * @param notificationRequestItem webhook payload
+     * @returns data to sign (as string)
+     */
     public getDataToSign(notificationRequestItem: DataToSign): string {
         if (this.isNotificationRequestItem(notificationRequestItem)) {
             const signedDataList = [];