Method to validate webhooks (#2)

Author: nagarjun

package.json

@@ -24,4 +24,4 @@
     "ts-jest": "^27.0.7",
     "typescript": "^4.4.4"
   }
-}
+}

src/base.ts

@@ -1,14 +1,32 @@
+import { Config } from "./types"
+
+// Default environment variables
+const ENV_API_KEY = 'NIGHTFALL_API_KEY'
+const ENV_WEBHOOK_SIGNING_SECRET = 'NIGHTFALL_WEBHOOK_SIGNING_SECRET'
+
 export class Base {
   protected readonly API_HOST = 'https://api.nightfall.ai'
   protected readonly API_KEY: string = ''
+  protected readonly WEBHOOK_SIGNING_SECRET: string = ''
   protected readonly AXIOS_HEADERS: { [key: string]: string | number } = {}
 
-  constructor(apiKey?: string) {
-    if (!apiKey && !process.env.hasOwnProperty('NIGHTFALL_API_KEY')) {
+  constructor(config?: Config) {
+    // Set API Key
+    if (!config?.apiKey && !process.env.hasOwnProperty(ENV_API_KEY)) {
       throw new Error('Please provide an API Key or configure your key as an environment variable.')
     }
 
-    this.API_KEY = apiKey || process.env.NIGHTFALL_API_KEY as string
+    this.API_KEY = config?.apiKey || process.env[ENV_API_KEY] as string
+
+    // Set webhook signing secret if supplied
+    if (config?.webhookSigningSecret) {
+      this.WEBHOOK_SIGNING_SECRET = config.webhookSigningSecret
+    }
+
+    // Attempt to set webhook signing secret from env if not supplied in config
+    if (!config?.webhookSigningSecret && process.env.hasOwnProperty(ENV_WEBHOOK_SIGNING_SECRET)) {
+      this.WEBHOOK_SIGNING_SECRET = process.env[ENV_WEBHOOK_SIGNING_SECRET] as string
+    }
 
     // Set Axios request headers since we will reuse this quite a lot
     this.AXIOS_HEADERS = {

src/filesScanner.ts

@@ -1,7 +1,7 @@
 import axios, { AxiosResponse } from "axios"
 import fs from 'fs'
 import { Base } from './base'
-import { ScanFile } from './types'
+import { Config, ScanFile } from './types'
 
 export class FileScanner extends Base {
   filePath: string
@@ -11,11 +11,10 @@ export class FileScanner extends Base {
   /**
    * Create an instance of the FileScanner helper.
    * 
-   * @param apiKey Your Nightfall API key
    * @param filePath The path of the file that needs to be scanned
    */
-  constructor(apiKey: string, filePath: string) {
-    super(apiKey)
+  constructor(config: Config, filePath: string) {
+    super(config)
     this.filePath = filePath
   }
 

src/nightfall.ts

@@ -1,20 +1,25 @@
 import axios, { AxiosError } from 'axios'
+import crypto from 'crypto'
 import { Base } from './base'
 import { FileScanner } from './filesScanner'
-import { NightfallResponse, NightfallError, ScanText, ScanFile } from './types'
+import {
+  Config, NightfallResponse, NightfallError, ScanText, ScanFile
+} from './types'
 
 export class Nightfall extends Base {
   /**
-   * Create an instance of the Nightfall client. Although you can supply
-   * your API key manually when you initiate the client, we recommend that
-   * you configure your API key as an environment variable named
-   * NIGHTFALL_API_KEY. The client automatically reads `process.env.NIGHTFALL_API_KEY`
-   * when you initiate the client like so: `const client = new Nightfall()`.
+   * Create an instance of the Nightfall client. Although you can supply your API key and webhook signing secret
+   * manually when you initiate the client, we recommend that you configure them as an environment variables named
+   * `NIGHTFALL_API_KEY` and `NIGHTFALL_WEBHOOK_SIGNING_SECRET`. The client automatically reads
+   * `process.env.NIGHTFALL_API_KEY` and `process.env.NIGHTFALL_WEBHOOK_SIGNING_SECRET` when you initiate the
+   * client like so: `const client = new Nightfall()`.
    * 
-   * @param apiKey Your Nightfall API key
+   * @param {Object} config An optional object to initialise the client with your key manually
+   * @param {string} config.apiKey Your Nightfall API Key
+   * @param {string} config.webhookSigningSecret Your webhook signing secret
    */
-  constructor(apiKey?: string) {
-    super(apiKey)
+  constructor(config?: Config) {
+    super(config)
   }
 
   /**
@@ -65,7 +70,13 @@ export class Nightfall extends Base {
    */
   async scanFile(filePath: string, policy: ScanFile.ScanPolicy, requestMetadata?: string): Promise<NightfallResponse<ScanFile.ScanResponse>> {
     try {
-      const fileScanner = new FileScanner(this.API_KEY, filePath)
+      const fileScanner = new FileScanner(
+        {
+          apiKey: this.API_KEY,
+          webhookSigningSecret: this.WEBHOOK_SIGNING_SECRET,
+        },
+        filePath,
+      )
       await fileScanner.initialize()
       await fileScanner.uploadChunks()
       await fileScanner.finish()
@@ -83,4 +94,38 @@ export class Nightfall extends Base {
       return Promise.reject(error)
     }
   }
+
+  /**
+   * A helper method to validate incoming webhook requests from Nightfall. In order to use this method, you
+   * must initialize the Nightfall client with your `webhookSigningSecret` or declare your signing secret as
+   * an environment variable called `NIGHTFALL_WEBHOOK_SIGNING_SECRET`. For more information,
+   * visit https://docs.nightfall.ai/docs/creating-a-webhook-server#webhook-signature-verification.
+   * 
+   * @param requestBody The webhook request body
+   * @param requestSignature The value of the X-Nightfall-Signature header
+   * @param requestTimestamp The value of the X-Nightfall-Timestamp header
+   * @param threshold Optional - The threshold in seconds. Defaults to 300 seconds (5 minutes).
+   * @returns A boolean that indicates whether the webhook is valid
+   */
+  validateWebhook(requestBody: ScanFile.WebhookBody, requestSignature: string, requestTimestamp: number, threshold?: number): boolean {
+    // Do not continue if the client isn't initialized with a webhook signing secret
+    if (!this.WEBHOOK_SIGNING_SECRET && !process.env.hasOwnProperty('NIGHTFALL_WEBHOOK_SIGNING_SECRET')) {
+      throw new Error('Please initialize the Nightfall client with a webhook signing secret or configure your signing secret as an environment variable.')
+    }
+
+    // First verify that the request occurred recently (before the configured threshold time)
+    // to protect against replay attacks
+    const defaultThreshold = threshold || 300
+    const now = Math.round(new Date().getTime() / 1000)
+    const thresholdTimestamp = now - defaultThreshold
+    if (requestTimestamp < thresholdTimestamp || requestTimestamp > now) {
+      return false
+    }
+
+    // Validate request signature using the signing secret
+    const hashPayload = `${requestTimestamp}:${JSON.stringify(requestBody)}`
+    const computedSignature = crypto.createHmac('sha256', this.WEBHOOK_SIGNING_SECRET).update(hashPayload).digest('hex')
+
+    return computedSignature === requestSignature
+  }
 }

src/tests/scanText.test.ts

@@ -2,23 +2,16 @@ import { Nightfall } from '../nightfall'
 import { creditCardConfig, creditCardPayload, errorResponse } from './mocks'
 
 describe('should test the text scanning method', () => {
-  // Set API key and other dependencies
-  if (!process.env.NIGHTFALL_API_KEY) {
-    throw new Error("NIGHTFALL_API_KEY environment variable is required")
-  }
-
-  const apiKey = process.env.NIGHTFALL_API_KEY
-
   // Run tests
   it('should create a new nightfall client and check if the scanText method exists', () => {
-    const client = new Nightfall(apiKey)
+    const client = new Nightfall()
 
     expect(client).toBeDefined()
     expect(typeof client.scanText).toBe('function')
   })
 
   it('should return an error if the request was configured incorrectly', async () => {
-    const client = new Nightfall(apiKey)
+    const client = new Nightfall()
     const scanTextSpy = jest.spyOn(client, 'scanText')
 
     const response = await client.scanText(creditCardPayload, {})
@@ -30,7 +23,7 @@ describe('should test the text scanning method', () => {
   })
 
   it('should return findings', async () => {
-    const client = new Nightfall(apiKey)
+    const client = new Nightfall()
     const scanTextSpy = jest.spyOn(client, 'scanText')
 
     const response = await client.scanText(creditCardPayload, creditCardConfig)

src/types/global.ts

@@ -1,3 +1,9 @@
+// Params to initiate the client
+export type Config = {
+  apiKey?: string
+  webhookSigningSecret?: string
+}
+
 export interface NightfallError {
   code: number;
   message: string;
@@ -27,4 +33,4 @@ export class NightfallResponse<T> {
   getError() {
     return this.error
   }
-}
+}

src/types/scanFile.ts

@@ -1,4 +1,4 @@
-import { Detector } from ".";
+import { Detector, NightfallError } from ".";
 
 export namespace ScanFile {
   export interface ScanRequest {
@@ -30,4 +30,13 @@ export namespace ScanFile {
     id: string
     message: string
   }
+
+  export interface WebhookBody {
+    findingsURL: string;
+    validUntil: string;
+    uploadID: string;
+    findingsPresent: boolean;
+    requestMetadata: string;
+    errors: NightfallError[];
+  }
 }

src/types/scanText.ts

@@ -38,4 +38,4 @@ export namespace ScanText {
     start: number
     end: number
   }
-}
+}