@bernierllc/contentful-webhook-handler 1.0.3

package/jest.config.cjs

@@ -0,0 +1,33 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: '<rootDir>/../../../jest-environment-node-fixed.cjs',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.test.ts',
+    '!src/**/__tests__/**',
+    '!src/index.ts'
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 90,
+      functions: 90,
+      lines: 90,
+      statements: 90
+    }
+  },
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+    '/dist/',
+    '/__tests__/'
+  ]
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bernierllc/contentful-webhook-handler",
+  "version": "1.0.3",
+  "description": "Validates Contentful webhook signatures using HMAC-SHA256, parses webhook payloads, and provides type-safe interfaces for all webhook event types",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --no-watch",
+    "test:run": "jest --no-watch",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage --no-watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "prepublishOnly": "npm run build && npm run lint && npm test"
+  },
+  "keywords": [
+    "contentful",
+    "webhook",
+    "signature-validation",
+    "hmac",
+    "sha256"
+  ],
+  "author": "Bernier LLC",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bernierllc/tools.git",
+    "directory": "packages/core/contentful-webhook-handler"
+  },
+  "dependencies": {
+    "@bernierllc/contentful-types": "workspace:*",
+    "@bernierllc/logger": "^1.0.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.30",
+    "@typescript-eslint/eslint-plugin": "^7.3.1",
+    "@typescript-eslint/parser": "^7.3.1",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.2"
+  }
+}

package/src/ContentfulWebhookHandler.ts

@@ -0,0 +1,260 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import crypto from 'crypto';
+import {
+  ContentfulWebhookPayload,
+  ContentfulWebhookTopic,
+  ContentfulWebhookHeaders
+} from '@bernierllc/contentful-types';
+import { Logger, createLogger } from '@bernierllc/logger';
+
+export interface WebhookValidationResult {
+  valid: boolean;
+  error?: string;
+  payload?: ContentfulWebhookPayload;
+  topic?: ContentfulWebhookTopic;
+}
+
+export interface EventType {
+  resource: 'Entry' | 'Asset' | 'ContentType';
+  action: 'create' | 'save' | 'auto_save' | 'publish' | 'unpublish' | 'delete' | 'archive' | 'unarchive';
+}
+
+export interface ContentfulWebhookHandlerOptions {
+  webhookSecret: string;
+  logger?: Logger;
+  enableTimestampValidation?: boolean;
+  maxTimestampDeltaSeconds?: number;
+}
+
+/**
+ * Validates Contentful webhook signatures using HMAC-SHA256,
+ * parses webhook payloads, and provides type-safe interfaces
+ * for all webhook event types.
+ */
+export class ContentfulWebhookHandler {
+  private webhookSecret: string;
+  private logger: Logger;
+  private enableTimestampValidation: boolean;
+  private maxTimestampDeltaSeconds: number;
+
+  /**
+   * Creates a new ContentfulWebhookHandler instance
+   *
+   * @param options Configuration options
+   */
+  constructor(options: ContentfulWebhookHandlerOptions) {
+    this.webhookSecret = options.webhookSecret;
+    this.logger = options.logger || createLogger({
+      context: {
+        service: 'ContentfulWebhookHandler',
+        version: '1.0.0',
+        environment: process.env.NODE_ENV || 'development'
+      }
+    });
+    this.enableTimestampValidation = options.enableTimestampValidation ?? false;
+    this.maxTimestampDeltaSeconds = options.maxTimestampDeltaSeconds ?? 300; // 5 minutes default
+  }
+
+  /**
+   * Validates a webhook signature using HMAC-SHA256
+   *
+   * @param body Raw webhook body as string
+   * @param signature Signature from x-contentful-signature header
+   * @returns True if signature is valid
+   */
+  validateSignature(body: string, signature: string): boolean {
+    try {
+      const hmac = crypto.createHmac('sha256', this.webhookSecret);
+      hmac.update(body);
+      const computedSignature = hmac.digest('base64');
+
+      // Use timing-safe comparison to prevent timing attacks
+      const signatureBuffer = Buffer.from(signature);
+      const computedBuffer = Buffer.from(computedSignature);
+
+      // Ensure buffers are the same length for timingSafeEqual
+      if (signatureBuffer.length !== computedBuffer.length) {
+        this.logger.warn('Invalid webhook signature (length mismatch)');
+        return false;
+      }
+
+      // TypeScript requires explicit cast for Buffer to ArrayBufferView
+      const isValid = crypto.timingSafeEqual(
+        signatureBuffer as unknown as Uint8Array,
+        computedBuffer as unknown as Uint8Array
+      );
+
+      if (!isValid) {
+        this.logger.warn('Invalid webhook signature');
+      }
+
+      return isValid;
+    } catch (err) {
+      // Handle buffer length mismatch or other crypto errors
+      if (err instanceof Error) {
+        this.logger.error('Signature validation error', err);
+      } else {
+        this.logger.error('Signature validation error', new Error(String(err)));
+      }
+      return false;
+    }
+  }
+
+  /**
+   * Validates webhook timestamp to prevent replay attacks
+   *
+   * @param payload Parsed webhook payload
+   * @returns True if timestamp is within acceptable range
+   */
+  private validateTimestamp(payload: ContentfulWebhookPayload): boolean {
+    if (!this.enableTimestampValidation) {
+      return true;
+    }
+
+    const updatedAt = payload.sys.updatedAt;
+    if (!updatedAt) {
+      this.logger.warn('No timestamp in webhook payload');
+      return false;
+    }
+
+    const payloadTime = new Date(updatedAt).getTime();
+    const currentTime = Date.now();
+    const deltaSeconds = Math.abs(currentTime - payloadTime) / 1000;
+
+    if (deltaSeconds > this.maxTimestampDeltaSeconds) {
+      this.logger.warn('Webhook timestamp outside acceptable range', {
+        deltaSeconds,
+        maxAllowed: this.maxTimestampDeltaSeconds
+      });
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Parses and validates a Contentful webhook
+   *
+   * @param body Raw webhook body as string
+   * @param headers Webhook headers
+   * @returns Validation result with parsed payload if valid
+   */
+  parseWebhook(
+    body: string,
+    headers: Partial<ContentfulWebhookHeaders>
+  ): WebhookValidationResult {
+    try {
+      // Validate required headers
+      const signature = headers['x-contentful-signature'];
+      if (!signature) {
+        return {
+          valid: false,
+          error: 'Missing signature header (x-contentful-signature)'
+        };
+      }
+
+      const topic = headers['x-contentful-topic'];
+      if (!topic) {
+        return {
+          valid: false,
+          error: 'Missing topic header (x-contentful-topic)'
+        };
+      }
+
+      // Validate signature
+      if (!this.validateSignature(body, signature)) {
+        return {
+          valid: false,
+          error: 'Invalid signature'
+        };
+      }
+
+      // Parse payload
+      const payload: ContentfulWebhookPayload = JSON.parse(body) as ContentfulWebhookPayload;
+
+      // Validate timestamp for replay attack prevention
+      if (!this.validateTimestamp(payload)) {
+        return {
+          valid: false,
+          error: 'Invalid timestamp (possible replay attack)'
+        };
+      }
+
+      this.logger.info('Webhook validated successfully', {
+        topic,
+        id: payload.sys.id,
+        type: payload.sys.type
+      });
+
+      return {
+        valid: true,
+        payload,
+        topic
+      };
+    } catch (err) {
+      if (err instanceof Error) {
+        this.logger.error('Failed to parse webhook', err);
+        return {
+          valid: false,
+          error: err.message
+        };
+      } else {
+        const errorMessage = String(err);
+        this.logger.error('Failed to parse webhook', new Error(errorMessage));
+        return {
+          valid: false,
+          error: errorMessage
+        };
+      }
+    }
+  }
+
+  /**
+   * Extracts resource type and action from a topic string
+   *
+   * @param topic Contentful webhook topic (e.g., "Entry.publish")
+   * @returns Object with resource type and action
+   */
+  getEventType(topic: ContentfulWebhookTopic): EventType {
+    const parts = topic.split('.');
+
+    if (parts.length !== 2) {
+      throw new Error(`Invalid topic format: ${topic}`);
+    }
+
+    const [resource, action] = parts;
+
+    // Validate resource type
+    if (!['Entry', 'Asset', 'ContentType'].includes(resource)) {
+      throw new Error(`Invalid resource type: ${resource}`);
+    }
+
+    // Validate action type
+    const validActions = ['create', 'save', 'auto_save', 'publish', 'unpublish', 'delete', 'archive', 'unarchive'];
+    if (!validActions.includes(action)) {
+      throw new Error(`Invalid action type: ${action}`);
+    }
+
+    return {
+      resource: resource as EventType['resource'],
+      action: action as EventType['action']
+    };
+  }
+
+  /**
+   * Updates the webhook secret
+   *
+   * @param newSecret New webhook secret
+   */
+  updateSecret(newSecret: string): void {
+    this.webhookSecret = newSecret;
+    this.logger.info('Webhook secret updated');
+  }
+}