feat: Optional Security Headers added for webhook outputs (#379)

* feat: Optional Security Headers added for webhook outputs

- optional security header can be enabled by adding the following to your config:

  -"webhookHmacSharedKey": "SomeRandomHMACKey"

(Replace "SomeRandomHMACKey" with your private HMAC secret key)

- when ENABLED, the following headers will be included in the webhook
  request:

x-hmac-time	 1747750828
x-hmac-signature 7420964e60045e716a9b1d4fabcbc6a9cc913c7e63ac653b313d56a097a36d1a
x-request-id     769164d0-5592-4a67-9932-038573732fdc

(example values shown)

--

NOTE:
- THIS MUST USE **SHA-256** HASHING ALG
- MESSAGE TO HASH is **x-hmac-time + x-request-id** (UTF-8 string, no
  seperators)
- DIGEST OUTPUT is **HEX STRING**
- x-hmac-time is **UNIX EPOCH TIME**
- signature is computed using your shared **`webhookHmacSharedKey`**
- You MUST validate that the timestamp is within an acceptable range
  (e.g. 5 minutes) *before* comparing the HMAC (do this on your backend)

* Update statusService.ts

remove redudant code.

* Update types.ts

made webhookHmacSharedKey optional

Author: SullyK

model/src/data-model/types.ts

@@ -214,6 +214,7 @@ export type FormDefinition = {
   jwtKey?: string | undefined;
   toggle?: boolean | string | undefined;
   retryTimeoutSeconds?: number | undefined;
+  webhookHmacSharedKey?: string | undefined;
   fullStartPage?: string | undefined;
   serviceName?: string | undefined;
 };

model/src/schema/schema.ts

@@ -346,6 +346,7 @@ export const Schema = joi
     toggle: joi.alternatives().try(joi.boolean(), joi.string()).optional(),
     toggleRedirect: joi.string().optional(),
     retryTimeoutSeconds: joi.number().optional(),
+    webhookHmacSharedKey: joi.string().optional(),
     fullStartPage: joi.string().optional(),
     serviceName: joi.string().optional(),
   });

runner/src/server/services/statusService.ts

@@ -1,4 +1,5 @@
 import { HapiRequest, HapiServer } from "../types";
+import { createHmacRaw } from "../utils/hmac";
 import {
   CacheService,
   NotifyService,
@@ -130,6 +131,29 @@ export class StatusService {
 
     let newReference;
 
+    /**
+     * If the OPTIONAL config contains webhookHmacSharedKey, then we send HMAC Auth headers
+     * This is used to confirm ONLY X-Gov's backend is sending data to our API
+     * Everyone else will be Rejected
+     */
+    const id = request.params?.id;
+    const forms = request.server?.app?.forms;
+    const model = id && forms?.[id];
+    const hmacKey = model?.def?.webhookHmacSharedKey;
+    let customSecurityHeaders: Record<string, string> = {};
+
+    if (hmacKey) {
+      const [hmacSignature, requestTime, hmacExpiryTime] = await createHmacRaw(
+        request.yar.id,
+        hmacKey
+      );
+      customSecurityHeaders = {
+        "X-Request-ID": request.yar.id.toString(),
+        "X-HMAC-Signature": hmacSignature.toString(),
+        "X-HMAC-Time": requestTime.toString(),
+      };
+    }
+
     if (callback) {
       this.logger.info(
         ["StatusService", "outputRequests"],
@@ -153,7 +177,8 @@ export class StatusService {
         firstWebhook.outputData.url,
         { ...formData },
         "POST",
-        firstWebhook.outputData.sendAdditionalPayMetadata
+        firstWebhook.outputData.sendAdditionalPayMetadata,
+        customSecurityHeaders
       );
       await this.cacheService.mergeState(request, {
         reference: newReference,
@@ -178,7 +203,8 @@ export class StatusService {
             ...formData,
           },
           "POST",
-          sendAdditionalPayMetadata
+          sendAdditionalPayMetadata,
+          customSecurityHeaders
         )
       ),
     ];

runner/src/server/services/webhookService.ts

@@ -27,20 +27,26 @@ export class WebhookService {
     url: string,
     data: object,
     method: "POST" | "PUT" = "POST",
-    sendAdditionalPayMetadata: boolean = false
+    sendAdditionalPayMetadata: boolean = false,
+    authHeaders?: Record<string, string>
   ) {
     // Commented out due to potential for logging PII
     // this.logger.info(
     //   ["WebhookService", "postRequest body"],
     //   JSON.stringify(data)
     // );
+
     let request = method === "POST" ? post : put;
     try {
       if (!sendAdditionalPayMetadata) {
         delete data?.metadata?.pay;
       }
       const { payload } = await request(url, {
         ...DEFAULT_OPTIONS,
+        headers: {
+          ...DEFAULT_OPTIONS.headers,
+          ...(authHeaders || {}),
+        },
         payload: JSON.stringify(data),
       });
 

runner/src/server/utils/hmac.ts

@@ -80,6 +80,29 @@ export async function createHmac(email: string, hmacKey: string) {
   }
 }
 
+/**
+ * Similar to the above but returns raw epoch timestamps,
+ * making it preferable for cryptographic logic.
+ * The other function may benefit from refactoring
+ * to separate display logic from core logic. */
+export async function createHmacRaw(message: string, hmacKey: string) {
+  try {
+    const currentTimestamp = Math.floor(Date.now() / 1000);
+    const dataToHash = message + currentTimestamp;
+    const hmac = crypto
+      .createHmac("sha256", hmacKey)
+      .update(dataToHash)
+      .digest("hex");
+
+    const expiryTimestamp = currentTimestamp + TIME_THRESHOLD;
+
+    return [hmac, currentTimestamp, expiryTimestamp];
+  } catch (error) {
+    console.error("Error creating HMAC (raw):", error);
+    throw error;
+  }
+}
+
 /**
  * Validates an HMAC signature
  */