@bernierllc/contentful-webhook-handler 1.0.3

package/dist/ContentfulWebhookHandler.js

@@ -0,0 +1,213 @@
+"use strict";
+/*
+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.
+*/
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentfulWebhookHandler = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const logger_1 = require("@bernierllc/logger");
+/**
+ * Validates Contentful webhook signatures using HMAC-SHA256,
+ * parses webhook payloads, and provides type-safe interfaces
+ * for all webhook event types.
+ */
+class ContentfulWebhookHandler {
+    webhookSecret;
+    logger;
+    enableTimestampValidation;
+    maxTimestampDeltaSeconds;
+    /**
+     * Creates a new ContentfulWebhookHandler instance
+     *
+     * @param options Configuration options
+     */
+    constructor(options) {
+        this.webhookSecret = options.webhookSecret;
+        this.logger = options.logger || (0, logger_1.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, signature) {
+        try {
+            const hmac = crypto_1.default.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_1.default.timingSafeEqual(signatureBuffer, computedBuffer);
+            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
+     */
+    validateTimestamp(payload) {
+        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, headers) {
+        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 = JSON.parse(body);
+            // 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) {
+        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,
+            action: action
+        };
+    }
+    /**
+     * Updates the webhook secret
+     *
+     * @param newSecret New webhook secret
+     */
+    updateSecret(newSecret) {
+        this.webhookSecret = newSecret;
+        this.logger.info('Webhook secret updated');
+    }
+}
+exports.ContentfulWebhookHandler = ContentfulWebhookHandler;

package/dist/__tests__/ContentfulWebhookHandler.test.d.ts

@@ -0,0 +1 @@
+export {};