Webhook signature verification tool

rishavbhowmik · rishavbhowmik · commit 598b280d0c49 · 2022-07-06T16:15:26.000+05:30
diff --git a/index.ts b/index.ts
@@ -40,6 +40,7 @@ import { IKCallback } from "./libs/interfaces/IKCallback";
 import manage from "./libs/manage";
 import signature from "./libs/signature";
 import upload from "./libs/upload";
+import { verify as verifyWebhookSignature } from "./utils/webhook-signature";
 import customMetadataField from "./libs/manage/custom-metadata-field";
 /*
     Implementations
@@ -76,7 +77,15 @@ const promisify = function <T = void>(thisContext: ImageKit, fn: Function) {
   };
 };
 
-class ImageKit {
+export const Webhook = {
+  verify: verifyWebhookSignature,
+}
+
+class ImageKitStaticUtils {
+  static Webhook = Webhook;
+}
+
+class ImageKit extends ImageKitStaticUtils {
   options: ImageKitOptions = {
     uploadEndpoint: "https://upload.imagekit.io/api/v1/files/upload",
     publicKey: "",
@@ -86,6 +95,7 @@ class ImageKit {
   };
 
   constructor(opts: ImageKitOptions = {} as ImageKitOptions) {
+    super()
     this.options = _.extend(this.options, opts);
     if (!this.options.publicKey) {
       throw new Error(errorMessages.MANDATORY_PUBLIC_KEY_MISSING.message);
diff --git a/libs/interfaces/index.ts b/libs/interfaces/index.ts
@@ -17,6 +17,12 @@ import { MoveFolderOptions, MoveFolderResponse, MoveFolderError } from "./MoveFo
 import { DeleteFileVersionOptions, RestoreFileVersionOptions } from "./FileVersion"
 import { CreateCustomMetadataFieldOptions, CustomMetadataField, UpdateCustomMetadataFieldOptions, GetCustomMetadataFieldsOptions } from "./CustomMetatadaField"
 import { RenameFileOptions, RenameFileResponse } from "./Rename"
+import {
+  WebhookEvent,
+  WebhookEventVideoAccepted,
+  WebhookEventVideoCompleted,
+  WebhookEventVideoFailed,
+} from "./webhookEvent";
 
 type FinalUrlOptions = ImageKitOptions & UrlOptions; // actual options used to construct url
 
@@ -56,5 +62,9 @@ export type {
   UpdateCustomMetadataFieldOptions,
   RenameFileOptions,
   RenameFileResponse,
+  WebhookEvent,
+  WebhookEventVideoAccepted,
+  WebhookEventVideoCompleted,
+  WebhookEventVideoFailed,
 };
 export type { IKCallback } from "./IKCallback";
diff --git a/libs/interfaces/webhookEvent.ts b/libs/interfaces/webhookEvent.ts
@@ -0,0 +1,80 @@
+type Asset = {
+  url: string;
+};
+
+type TransformationOptions = {
+  video_codec: string;
+  audio_codec: string;
+  auto_rotate: boolean;
+  quality: number;
+  format: string;
+};
+
+interface WebhookEventBase {
+  type: string;
+  id: string;
+  created_at: string; // Date
+}
+
+/** WebhookEvent for "video.transformation.*" type */
+interface WebhookEventVideoBase extends WebhookEventBase {
+  request: {
+    x_request_id: string;
+    url: string;
+    user_agent: string;
+  };
+}
+
+export interface WebhookEventVideoAccepted extends WebhookEventVideoBase {
+  type: "video.transformation.accepted";
+  data: {
+    asset: Asset;
+    transformation: {
+      type: string;
+      options: TransformationOptions;
+    };
+  };
+}
+
+export interface WebhookEventVideoCompleted extends WebhookEventVideoBase {
+  type: "video.transformation.completed";
+  timings: {
+    donwload_duration: number;
+    encoding_duration: number;
+  };
+  data: {
+    asset: Asset;
+    transformation: {
+      type: string;
+      options: TransformationOptions;
+      output: {
+        url: string;
+        video_metadata: {
+          duration: number;
+          width: number;
+          height: number;
+          bitrate: number;
+        };
+      };
+    };
+  };
+}
+
+export interface WebhookEventVideoFailed extends WebhookEventVideoBase {
+  type: "video.transformation.failed";
+  data: {
+    asset: Asset;
+    transformation: {
+      type: string;
+      options: TransformationOptions;
+      error: {
+        reason: string;
+      };
+    };
+  };
+}
+
+export type WebhookEvent =
+  | WebhookEventVideoAccepted
+  | WebhookEventVideoCompleted
+  | WebhookEventVideoFailed;
diff --git a/tests/webhook-signature.js b/tests/webhook-signature.js
@@ -0,0 +1,145 @@
+import { Webhook } from "../index";
+import { expect } from "chai";
+
+// Sample webhook data
+const WEBHOOK_REQUEST_SAMPLE_SECRET = "whsec_xeO2UNkfKMQnfJf7Q/Qx+fYptL1wabXd";
+const WEBHOOK_REQUEST_SAMPLE_TIMESTAMP = new Date(1655788406333);
+const WEBHOOK_REQUEST_SAMPLE_SIGNATURE_HEADER =
+  "t=1655788406333,v1=d30758f47fcb31e1fa0109d3b3e2a6c623e699aaf1461cba6bd462ef58ea4b31";
+const WEBHOOK_REQUEST_SAMPLE_RAW_BODY =
+  '{"type":"video.transformation.accepted","id":"58e6d24d-6098-4319-be8d-40c3cb0a402d","created_at":"2022-06-20T11:59:58.461Z","request":{"x_request_id":"fa98fa2e-d6cd-45b4-acf5-bc1d2bbb8ba9","url":"http://ik.imagekit.io/demo/sample-video.mp4?tr=f-webm,q-10","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:101.0) Gecko/20100101 Firefox/101.0"},"data":{"asset":{"url":"http://ik.imagekit.io/demo/sample-video.mp4"},"transformation":{"type":"video-transformation","options":{"video_codec":"vp9","audio_codec":"opus","auto_rotate":true,"quality":10,"format":"webm"}}}}';
+const WEBHOOK_REQUEST_SAMPLE = Object.seal({
+  secret: WEBHOOK_REQUEST_SAMPLE_SECRET,
+  timestamp: WEBHOOK_REQUEST_SAMPLE_TIMESTAMP,
+  signatureHeader: WEBHOOK_REQUEST_SAMPLE_SIGNATURE_HEADER,
+  rawBody: WEBHOOK_REQUEST_SAMPLE_RAW_BODY,
+  body: JSON.parse(WEBHOOK_REQUEST_SAMPLE_RAW_BODY),
+});
+
+describe("WebhookSignature", function () {
+  const { verify } = Webhook;
+
+  context("Test Webhook.verify() - Positive cases", () => {
+    it("Verify with body as string", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const { timestamp, event } = verify(
+        webhookRequest.rawBody,
+        webhookRequest.signatureHeader,
+        webhookRequest.secret
+      );
+      expect(timestamp).to.equal(webhookRequest.timestamp.getTime());
+      expect(event).to.deep.equal(webhookRequest.body);
+    });
+    it("Verify with body as Buffer", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const { timestamp, event } = verify(
+        Buffer.from(webhookRequest.rawBody),
+        webhookRequest.signatureHeader,
+        webhookRequest.secret
+      );
+      expect(timestamp).to.equal(webhookRequest.timestamp.getTime());
+      expect(event).to.deep.equal(webhookRequest.body);
+    });
+    it("Verify with body as Uint8Array", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const rawBody = Uint8Array.from(Buffer.from(webhookRequest.rawBody));
+      const { timestamp, event } = verify(
+        rawBody,
+        webhookRequest.signatureHeader,
+        webhookRequest.secret
+      );
+      expect(timestamp).to.equal(webhookRequest.timestamp.getTime());
+      expect(event).to.deep.equal(webhookRequest.body);
+    });
+  });
+
+  context("Test WebhookSignature.verify() - Negative cases", () => {
+    it("Timestamp missing", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const invalidSignature =
+        "v1=b6bc2aa82491c32f1cbef0eb52b7ffffff467ea65a03b5d4ccdcfb9e0941c946";
+      try {
+        verify(webhookRequest.rawBody, invalidSignature, webhookRequest.secret);
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Timestamp missing");
+      }
+    });
+    it("Timestamp invalid", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const invalidSignature =
+        "t=notANumber,v1=b6bc2aa82491c32f1cbef0eb52b7ffffff467ea65a03b5d4ccdcfb9e0941c946";
+      try {
+        verify(webhookRequest.rawBody, invalidSignature, webhookRequest.secret);
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Timestamp invalid");
+      }
+    });
+    it("Signature missing", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const invalidSignature = "t=1656326161409";
+      try {
+        verify(webhookRequest.rawBody, invalidSignature, webhookRequest.secret);
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Signature missing");
+      }
+    });
+    it("Incorrect signature - v1 manipulated", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const invalidSignature = `t=${webhookRequest.timestamp.getTime()},v1=d66b01d8f1e158d1af7646184716037510ac8ce0a1e70b726a1b698f954785b2`;
+      try {
+        verify(webhookRequest.rawBody, invalidSignature, webhookRequest.secret);
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Incorrect signature");
+      }
+    });
+    it("Incorrect signature - incorrect request body", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const incorrectBody = { hello: "world" };
+      const incorrectRawBody = JSON.stringify(incorrectBody);
+      try {
+        verify(
+          incorrectRawBody,
+          webhookRequest.signatureHeader,
+          webhookRequest.secret
+        );
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Incorrect signature");
+      }
+    });
+    it("Incorrect signature - timestamp manipulated", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const incorrectSignature = webhookRequest.signatureHeader.replace(
+        `t=${webhookRequest.timestamp.getTime()}`,
+        `t=${webhookRequest.timestamp.getTime() + 1}`
+      ); // Correct timestamp replaced with incorrect timestamp
+      try {
+        verify(
+          webhookRequest.rawBody,
+          incorrectSignature,
+          webhookRequest.secret
+        );
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Incorrect signature");
+      }
+    });
+    it("Incorrect signature - different secret", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      try {
+        verify(
+          webhookRequest.rawBody,
+          webhookRequest.signatureHeader,
+          "A different secret"
+        );
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Incorrect signature");
+      }
+    });
+  });
+});
diff --git a/utils/webhook-signature.ts b/utils/webhook-signature.ts
@@ -0,0 +1,101 @@
+import { createHmac } from "crypto";
+import { isNaN } from "lodash";
+import type { WebhookEvent } from "../libs/interfaces";
+
+class WebhookSignatureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WebhookSignatureError";
+  }
+}
+
+/**
+ * @description Enum for Webhook signature item names
+ */
+enum SignatureItems {
+  Timestamp = "t",
+  V1 = "v1",
+}
+
+const HASH_ALGORITHM = "sha256";
+
+/**
+ * @param timstamp - Webhook request timestamp
+ * @param payload - Webhook payload as UTF8 encoded string
+ * @param secret - Webhook secret as UTF8 encoded string
+ * @returns Hmac with webhook secret as key and `${timestamp}.${payload}` as hash payload.
+ */
+const computeHmac = (
+  timstamp: Date,
+  payload: string,
+  secret: string
+): string => {
+  const hashPayload = `${timstamp.getTime()}.${payload}`;
+  return createHmac(HASH_ALGORITHM, secret).update(hashPayload).digest("hex");
+};
+
+/**
+ * @description Extract items from webhook signature string
+ */
+const deserializeSignature = (
+  signature: string
+): {
+  timestamp: number;
+  v1: string;
+} => {
+  const items = signature.split(",");
+  const itemMap = items.map((item) => item.split("=")); // eg. [["t", 1656921250765], ["v1", 'afafafafafaf']]
+  const timestampString = itemMap.find(
+    ([key]) => key === SignatureItems.Timestamp
+  )?.[1]; // eg. 1656921250765
+
+  // parse timestamp
+  if (timestampString === undefined) {
+    throw new WebhookSignatureError("Timestamp missing");
+  }
+  const timestamp = parseInt(timestampString, 10);
+  if (isNaN(timestamp) || timestamp < 0) {
+    throw new WebhookSignatureError("Timestamp invalid");
+  }
+
+  // parse v1 signature
+  const v1 = itemMap.find(([key]) => key === SignatureItems.V1)?.[1]; // eg. 'afafafafafaf'
+  if (v1 === undefined) {
+    throw new WebhookSignatureError("Signature missing");
+  }
+
+  return { timestamp, v1 };
+};
+
+/**
+ * @param payload - Webhook request (Raw body)
+ * @param signature - Webhook signature as UTF8 encoded strings (Stored in `x-ik-signature` header of the request)
+ * @param secret - Webhook secret as UTF8 encoded string [Copy from ImageKit dashboard](https://imagekit.io/dashboard/developer/webhooks)
+ * @returns \{ `timstamp`: Verified UNIX epoch timestamp if signature, `event`: Parsed webhook event payload \}
+ */
+export const verify = (
+  payload: string | Uint8Array,
+  signature: string,
+  secret: string
+): {
+  timestamp: number;
+  event: WebhookEvent;
+} => {
+  const { timestamp, v1 } = deserializeSignature(signature);
+  const payloadAsString: string =
+    typeof payload === "string"
+      ? payload
+      : Buffer.from(payload).toString("utf8");
+  const computedHmac = computeHmac(
+    new Date(timestamp),
+    payloadAsString,
+    secret
+  );
+  if (v1 !== computedHmac) {
+    throw new WebhookSignatureError("Incorrect signature");
+  }
+  return {
+    timestamp,
+    event: JSON.parse(payloadAsString) as WebhookEvent,
+  };
+};
