HTTP route script with signature verification template

import * as crypto from 'crypto';

import * as wmill from "windmill-client";

const SECRET_KEY_VARIABLE_PATH = "secret_key_path";

/**

 * Trigger Preprocessor

 *

 * ⚠️ This function runs BEFORE the main function.

 *

 * Windmill allows you to define a `preprocessor` for any trigger type (HTTP, WebSocket, Kafka, Email, etc.).

 * The preprocessor gives you the ability to perform custom logic such as validation, transformation, or authentication

 * before the `main()` function is executed.

 *

 * In this example:

 * - The trigger kind is `http`, which means we have access to HTTP-specific metadata.

 * - We use `wm_trigger.http.headers` to extract custom headers from the incoming HTTP request, such as:

 *   - `x-signature` for verifying the integrity and authenticity of the request.

 *   - `x-timestamp` to guard against replay attacks by validating the request time.

 * - The `raw_string` argument contains the **raw JSON body** of the request as a string — which is crucial for verifying the HMAC signature.

 *

 * ⚠️ **Important:** `raw_string` is required for signature verification in this example. 

 * Make sure the **"raw body"** option is enabled in your HTTP route configuration. 

 * If it's not enabled, `raw_string` will be undefined and the script will throw an error.

 *

 * Once the signature and timestamp are verified, we parse the raw JSON body and return the parsed payload as `body`, which is passed directly into the `main()` function as a named argument.

 *

 * Learn more: https://www.windmill.dev/docs/core_concepts/preprocessors

 */

export async function preprocessor(

  event: {

    kind: 'http';

    body: any;

    raw_string: string | null;

    route: string;

    path: string;

    method: string;

    params: Record<string, string>;

    query: Record<string, string>;

    headers: Record<string, string>;

  },

) {

  if (event.kind === 'http') {

    if (!event.raw_string) {

      throw new Error("Missing raw body. Ensure the 'raw body' option is enabled in the HTTP route configuration.");

    }

    // Extract signature from headers

    const signature = event.headers['x-signature'] || event.headers['signature'];

    if (!signature) {

      throw new Error('Missing signature in request headers.');

    }

    // Check timestamp if present to prevent replay attacks

    const timestamp = event.headers['x-timestamp'] || event.headers['timestamp'];

    if (timestamp) {

      const timestampValue = parseInt(timestamp, 10);

      const currentTime = Math.floor(Date.now() / 1000); // Current time in seconds

      const TIME_WINDOW_SECONDS = 5 * 60; // 5 minutes

      if (isNaN(timestampValue)) {

        throw new Error('Invalid timestamp format.');

      }

      if (Math.abs(currentTime - timestampValue) > TIME_WINDOW_SECONDS) {

        throw new Error('Request timestamp is outside the acceptable time window.');

      }

    }

    // Verify the signature

    const isValidSignature = await verifySignature(signature, event.raw_string, timestamp);

    if (!isValidSignature) {

      throw new Error('Invalid signature.');

    }

    // Parse the body if it's JSON (with error handling)

    let parsedBody: any = {};

    try {

      parsedBody = JSON.parse(event.raw_string);

    } catch (error: unknown) {

      const errorMessage = error instanceof Error ? error.message : 'Unknown parsing error';

      throw new Error(`Failed to parse request body: ${errorMessage}`);

    }

    // Return both HTTP details and the parsed body to main

    return {

      body: parsedBody

    };

  }

  throw new Error(`Expected trigger of kind 'http', but received: ${event.kind}`);

}

/**

 * Verifies the HMAC-SHA256 signature against the raw body and optional timestamp.

 *

 * @param signature - The signature from request headers

 * @param body - Raw request body as a string

 * @param timestamp - Optional timestamp from request headers

 * @returns boolean indicating if the signature is valid

 */

async function verifySignature(signature: string, body?: string, timestamp?: string): Promise<boolean> {

  const dataToVerify = timestamp

    ? `${body || ''}${timestamp}`

    : (body || '');

  const secretKey = await wmill.getVariable(SECRET_KEY_VARIABLE_PATH);

  const expectedSignature = crypto

    .createHmac('sha256', secretKey || '')

    .update(dataToVerify)

    .digest('hex');

  try {

    return crypto.timingSafeEqual(

      Buffer.from(signature),

      Buffer.from(expectedSignature)

    );

  } catch (error: unknown) {

    console.error('Signature comparison error:', error);

    return false;

  }

  // NOTE: Modify this logic if your provider uses a different signing mechanism (e.g., Base64, RSA, etc.)

}

/**

 * Main Function - Handles processed trigger events

 *

 * ⚠️ Called AFTER `preprocessor()`, with its return values.

 *

 * @param body - Parsed request body

 */

export async function main(body: any) {

  // At this point, the request has been authenticated (signature + timestamp) and body safely parsed

  return {

    statusCode: 200,

    body: {

      message: "Request authenticated successfully",

      receivedData: body,

    }

  };

}