@bernierllc/contentful-webhook-handler 1.0.3

package/dist/__tests__/ContentfulWebhookHandler.test.js

@@ -0,0 +1,576 @@
+"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 });
+const crypto_1 = __importDefault(require("crypto"));
+const ContentfulWebhookHandler_1 = require("../ContentfulWebhookHandler");
+const logger_1 = require("@bernierllc/logger");
+describe('ContentfulWebhookHandler', () => {
+    const TEST_SECRET = 'test-webhook-secret';
+    let handler;
+    beforeEach(() => {
+        handler = new ContentfulWebhookHandler_1.ContentfulWebhookHandler({
+            webhookSecret: TEST_SECRET
+        });
+    });
+    describe('constructor', () => {
+        it('should create handler with required options', () => {
+            expect(handler).toBeInstanceOf(ContentfulWebhookHandler_1.ContentfulWebhookHandler);
+        });
+        it('should accept custom logger', () => {
+            const customLogger = new logger_1.Logger({
+                level: logger_1.LogLevel.INFO,
+                transports: [new logger_1.ConsoleTransport()],
+                context: {
+                    service: 'CustomContext',
+                    version: '1.0.0',
+                    environment: 'test'
+                }
+            });
+            const customHandler = new ContentfulWebhookHandler_1.ContentfulWebhookHandler({
+                webhookSecret: TEST_SECRET,
+                logger: customLogger
+            });
+            expect(customHandler).toBeInstanceOf(ContentfulWebhookHandler_1.ContentfulWebhookHandler);
+        });
+        it('should accept timestamp validation options', () => {
+            const timestampHandler = new ContentfulWebhookHandler_1.ContentfulWebhookHandler({
+                webhookSecret: TEST_SECRET,
+                enableTimestampValidation: true,
+                maxTimestampDeltaSeconds: 600
+            });
+            expect(timestampHandler).toBeInstanceOf(ContentfulWebhookHandler_1.ContentfulWebhookHandler);
+        });
+    });
+    describe('validateSignature', () => {
+        it('should validate correct signature', () => {
+            const body = '{"test":"data"}';
+            const hmac = crypto_1.default.createHmac('sha256', TEST_SECRET);
+            hmac.update(body);
+            const signature = hmac.digest('base64');
+            const isValid = handler.validateSignature(body, signature);
+            expect(isValid).toBe(true);
+        });
+        it('should reject invalid signature', () => {
+            const body = '{"test":"data"}';
+            const invalidSignature = 'invalid-signature-base64';
+            const isValid = handler.validateSignature(body, invalidSignature);
+            expect(isValid).toBe(false);
+        });
+        it('should reject tampered body', () => {
+            const originalBody = '{"test":"data"}';
+            const tamperedBody = '{"test":"tampered"}';
+            const hmac = crypto_1.default.createHmac('sha256', TEST_SECRET);
+            hmac.update(originalBody);
+            const signature = hmac.digest('base64');
+            const isValid = handler.validateSignature(tamperedBody, signature);
+            expect(isValid).toBe(false);
+        });
+        it('should reject signature with different secret', () => {
+            const body = '{"test":"data"}';
+            const hmac = crypto_1.default.createHmac('sha256', 'different-secret');
+            hmac.update(body);
+            const signature = hmac.digest('base64');
+            const isValid = handler.validateSignature(body, signature);
+            expect(isValid).toBe(false);
+        });
+        it('should handle empty body', () => {
+            const body = '';
+            const hmac = crypto_1.default.createHmac('sha256', TEST_SECRET);
+            hmac.update(body);
+            const signature = hmac.digest('base64');
+            const isValid = handler.validateSignature(body, signature);
+            expect(isValid).toBe(true);
+        });
+        it('should return false for buffer length mismatch', () => {
+            const body = '{"test":"data"}';
+            const shortSignature = 'short';
+            const isValid = handler.validateSignature(body, shortSignature);
+            expect(isValid).toBe(false);
+        });
+        it('should handle crypto errors gracefully', () => {
+            const body = '{"test":"data"}';
+            // Intentionally malformed base64 that will cause issues
+            const badSignature = '!!!invalid-base64!!!';
+            const isValid = handler.validateSignature(body, badSignature);
+            expect(isValid).toBe(false);
+        });
+        it('should handle non-Error exceptions in signature validation', () => {
+            const testHandler = new ContentfulWebhookHandler_1.ContentfulWebhookHandler({
+                webhookSecret: TEST_SECRET
+            });
+            const body = '{"test":"data"}';
+            // Mock crypto.createHmac to throw a non-Error
+            const originalCreateHmac = crypto_1.default.createHmac;
+            crypto_1.default.createHmac = jest.fn().mockImplementationOnce(() => {
+                // eslint-disable-next-line @typescript-eslint/no-throw-literal
+                throw 'crypto error';
+            });
+            try {
+                const isValid = testHandler.validateSignature(body, 'signature');
+                expect(isValid).toBe(false);
+            }
+            finally {
+                // Restore original
+                crypto_1.default.createHmac = originalCreateHmac;
+            }
+        });
+    });
+    describe('parseWebhook', () => {
+        const createValidPayload = () => ({
+            sys: {
+                type: 'Entry',
+                id: 'test-entry-123',
+                space: {
+                    sys: {
+                        type: 'Link',
+                        linkType: 'Space',
+                        id: 'space-123'
+                    }
+                },
+                environment: {
+                    sys: {
+                        type: 'Link',
+                        linkType: 'Environment',
+                        id: 'master'
+                    }
+                },
+                contentType: {
+                    sys: {
+                        type: 'Link',
+                        linkType: 'ContentType',
+                        id: 'blogPost'
+                    }
+                },
+                revision: 1,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString()
+            },
+            fields: {
+                title: { 'en-US': 'Test Title' },
+                content: { 'en-US': 'Test content' }
+            }
+        });
+        const signBody = (body) => {
+            const hmac = crypto_1.default.createHmac('sha256', TEST_SECRET);
+            hmac.update(body);
+            return hmac.digest('base64');
+        };
+        it('should parse valid webhook', () => {
+            const payload = createValidPayload();
+            const body = JSON.stringify(payload);
+            const signature = signBody(body);
+            const headers = {
+                'x-contentful-signature': signature,
+                'x-contentful-topic': 'Entry.publish'
+            };
+            const result = handler.parseWebhook(body, headers);
+            expect(result.valid).toBe(true);
+            expect(result.error).toBeUndefined();
+            expect(result.payload).toEqual(payload);
+            expect(result.topic).toBe('Entry.publish');
+        });
+        it('should reject webhook without signature header', () => {
+            const payload = createValidPayload();
+            const body = JSON.stringify(payload);
+            const headers = {
+                'x-contentful-topic': 'Entry.publish'
+            };
+            const result = handler.parseWebhook(body, headers);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Missing signature header (x-contentful-signature)');
+            expect(result.payload).toBeUndefined();
+        });
+        it('should reject webhook without topic header', () => {
+            const payload = createValidPayload();
+            const body = JSON.stringify(payload);
+            const signature = signBody(body);
+            const headers = {
+                'x-contentful-signature': signature
+            };
+            const result = handler.parseWebhook(body, headers);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Missing topic header (x-contentful-topic)');
+            expect(result.payload).toBeUndefined();
+        });
+        it('should reject webhook with invalid signature', () => {
+            const payload = createValidPayload();
+            const body = JSON.stringify(payload);
+            const headers = {
+                'x-contentful-signature': 'invalid-signature',
+                'x-contentful-topic': 'Entry.publish'
+            };
+            const result = handler.parseWebhook(body, headers);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Invalid signature');
+            expect(result.payload).toBeUndefined();
+        });
+        it('should reject webhook with invalid JSON', () => {
+            const body = 'invalid json {';
+            const signature = signBody(body);
+            const headers = {
+                'x-contentful-signature': signature,
+                'x-contentful-topic': 'Entry.publish'
+            };
+            const result = handler.parseWebhook(body, headers);
+            expect(result.valid).toBe(false);
+            expect(result.error).toContain('Unexpected');
+            expect(result.payload).toBeUndefined();
+        });
+        it('should handle non-Error exceptions in parsing', () => {
+            // Create a new handler for this test to avoid affecting other tests
+            const testHandler = new ContentfulWebhookHandler_1.ContentfulWebhookHandler({
+                webhookSecret: TEST_SECRET
+            });
+            const body = '{"test":"data"}';
+            const hmac = crypto_1.default.createHmac('sha256', TEST_SECRET);
+            hmac.update(body);
+            const signature = hmac.digest('base64');
+            // Mock JSON.parse to throw a non-Error
+            const originalParse = global.JSON.parse;
+            global.JSON.parse = jest.fn().mockImplementationOnce(() => {
+                // eslint-disable-next-line @typescript-eslint/no-throw-literal
+                throw 'string error';
+            });
+            try {
+                const headers = {
+                    'x-contentful-signature': signature,
+                    'x-contentful-topic': 'Entry.publish'
+                };
+                const result = testHandler.parseWebhook(body, headers);
+                expect(result.valid).toBe(false);
+                expect(result.error).toBe('string error');
+            }
+            finally {
+                // Restore original
+                global.JSON.parse = originalParse;
+            }
+        });
+        it('should handle all webhook topics', () => {
+            const topics = [
+                'Entry.create',
+                'Entry.publish',
+                'Asset.delete',
+                'ContentType.save'
+            ];
+            topics.forEach(topic => {
+                const payload = createValidPayload();
+                const body = JSON.stringify(payload);
+                const signature = signBody(body);
+                const headers = {
+                    'x-contentful-signature': signature,
+                    'x-contentful-topic': topic
+                };
+                const result = handler.parseWebhook(body, headers);
+                expect(result.valid).toBe(true);
+                expect(result.topic).toBe(topic);
+            });
+        });
+    });
+    describe('timestamp validation', () => {
+        const createPayloadWithTimestamp = (timestamp) => ({
+            sys: {
+                type: 'Entry',
+                id: 'test-entry-123',
+                space: {
+                    sys: {
+                        type: 'Link',
+                        linkType: 'Space',
+                        id: 'space-123'
+                    }
+                },
+                environment: {
+                    sys: {
+                        type: 'Link',
+                        linkType: 'Environment',
+                        id: 'master'
+                    }
+                },
+                contentType: {
+                    sys: {
+                        type: 'Link',
+                        linkType: 'ContentType',
+                        id: 'blogPost'
+                    }
+                },
+                updatedAt: timestamp
+            }
+        });
+        const signBody = (body) => {
+            const hmac = crypto_1.default.createHmac('sha256', TEST_SECRET);
+            hmac.update(body);
+            return hmac.digest('base64');
+        };
+        it('should accept recent timestamp when validation enabled', () => {
+            const timestampHandler = new ContentfulWebhookHandler_1.ContentfulWebhookHandler({
+                webhookSecret: TEST_SECRET,
+                enableTimestampValidation: true,
+                maxTimestampDeltaSeconds: 300
+            });
+            const payload = createPayloadWithTimestamp(new Date().toISOString());
+            const body = JSON.stringify(payload);
+            const signature = signBody(body);
+            const headers = {
+                'x-contentful-signature': signature,
+                'x-contentful-topic': 'Entry.publish'
+            };
+            const result = timestampHandler.parseWebhook(body, headers);
+            expect(result.valid).toBe(true);
+        });
+        it('should reject old timestamp when validation enabled', () => {
+            const timestampHandler = new ContentfulWebhookHandler_1.ContentfulWebhookHandler({
+                webhookSecret: TEST_SECRET,
+                enableTimestampValidation: true,
+                maxTimestampDeltaSeconds: 300
+            });
+            // Create timestamp 10 minutes ago (600 seconds)
+            const oldDate = new Date(Date.now() - 600000);
+            const payload = createPayloadWithTimestamp(oldDate.toISOString());
+            const body = JSON.stringify(payload);
+            const signature = signBody(body);
+            const headers = {
+                'x-contentful-signature': signature,
+                'x-contentful-topic': 'Entry.publish'
+            };
+            const result = timestampHandler.parseWebhook(body, headers);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Invalid timestamp (possible replay attack)');
+        });
+        it('should accept any timestamp when validation disabled', () => {
+            // Default handler has timestamp validation disabled
+            const oldDate = new Date(Date.now() - 600000);
+            const payload = createPayloadWithTimestamp(oldDate.toISOString());
+            const body = JSON.stringify(payload);
+            const signature = signBody(body);
+            const headers = {
+                'x-contentful-signature': signature,
+                'x-contentful-topic': 'Entry.publish'
+            };
+            const result = handler.parseWebhook(body, headers);
+            expect(result.valid).toBe(true);
+        });
+        it('should reject payload without timestamp when validation enabled', () => {
+            const timestampHandler = new ContentfulWebhookHandler_1.ContentfulWebhookHandler({
+                webhookSecret: TEST_SECRET,
+                enableTimestampValidation: true,
+                maxTimestampDeltaSeconds: 300
+            });
+            const payload = {
+                sys: {
+                    type: 'Entry',
+                    id: 'test-entry-123',
+                    space: {
+                        sys: {
+                            type: 'Link',
+                            linkType: 'Space',
+                            id: 'space-123'
+                        }
+                    },
+                    environment: {
+                        sys: {
+                            type: 'Link',
+                            linkType: 'Environment',
+                            id: 'master'
+                        }
+                    }
+                }
+            };
+            const body = JSON.stringify(payload);
+            const signature = signBody(body);
+            const headers = {
+                'x-contentful-signature': signature,
+                'x-contentful-topic': 'Entry.publish'
+            };
+            const result = timestampHandler.parseWebhook(body, headers);
+            expect(result.valid).toBe(false);
+            expect(result.error).toBe('Invalid timestamp (possible replay attack)');
+        });
+    });
+    describe('getEventType', () => {
+        it('should parse Entry.publish topic', () => {
+            const result = handler.getEventType('Entry.publish');
+            expect(result.resource).toBe('Entry');
+            expect(result.action).toBe('publish');
+        });
+        it('should parse Asset.delete topic', () => {
+            const result = handler.getEventType('Asset.delete');
+            expect(result.resource).toBe('Asset');
+            expect(result.action).toBe('delete');
+        });
+        it('should parse ContentType.save topic', () => {
+            const result = handler.getEventType('ContentType.save');
+            expect(result.resource).toBe('ContentType');
+            expect(result.action).toBe('save');
+        });
+        it('should parse Entry.create topic', () => {
+            const result = handler.getEventType('Entry.create');
+            expect(result.resource).toBe('Entry');
+            expect(result.action).toBe('create');
+        });
+        it('should parse Entry.auto_save topic', () => {
+            const result = handler.getEventType('Entry.auto_save');
+            expect(result.resource).toBe('Entry');
+            expect(result.action).toBe('auto_save');
+        });
+        it('should parse Entry.archive topic', () => {
+            const result = handler.getEventType('Entry.archive');
+            expect(result.resource).toBe('Entry');
+            expect(result.action).toBe('archive');
+        });
+        it('should parse Entry.unarchive topic', () => {
+            const result = handler.getEventType('Entry.unarchive');
+            expect(result.resource).toBe('Entry');
+            expect(result.action).toBe('unarchive');
+        });
+        it('should parse Entry.unpublish topic', () => {
+            const result = handler.getEventType('Entry.unpublish');
+            expect(result.resource).toBe('Entry');
+            expect(result.action).toBe('unpublish');
+        });
+        it('should throw error for invalid topic format', () => {
+            expect(() => {
+                handler.getEventType('InvalidTopic');
+            }).toThrow('Invalid topic format: InvalidTopic');
+        });
+        it('should throw error for too many parts', () => {
+            expect(() => {
+                handler.getEventType('Entry.publish.extra');
+            }).toThrow('Invalid topic format: Entry.publish.extra');
+        });
+        it('should throw error for invalid resource', () => {
+            expect(() => {
+                handler.getEventType('InvalidResource.publish');
+            }).toThrow('Invalid resource type: InvalidResource');
+        });
+        it('should throw error for invalid action', () => {
+            expect(() => {
+                handler.getEventType('Entry.invalidAction');
+            }).toThrow('Invalid action type: invalidAction');
+        });
+    });
+    describe('updateSecret', () => {
+        it('should update webhook secret', () => {
+            const newSecret = 'new-test-secret';
+            handler.updateSecret(newSecret);
+            // Verify new secret works
+            const body = '{"test":"data"}';
+            const hmac = crypto_1.default.createHmac('sha256', newSecret);
+            hmac.update(body);
+            const signature = hmac.digest('base64');
+            const isValid = handler.validateSignature(body, signature);
+            expect(isValid).toBe(true);
+        });
+        it('should invalidate old secret after update', () => {
+            const body = '{"test":"data"}';
+            const hmac = crypto_1.default.createHmac('sha256', TEST_SECRET);
+            hmac.update(body);
+            const oldSignature = hmac.digest('base64');
+            // Update to new secret
+            handler.updateSecret('new-test-secret');
+            // Old signature should no longer work
+            const isValid = handler.validateSignature(body, oldSignature);
+            expect(isValid).toBe(false);
+        });
+    });
+    describe('integration scenarios', () => {
+        it('should handle complete Entry.publish webhook', () => {
+            const payload = {
+                sys: {
+                    type: 'Entry',
+                    id: 'blog-post-123',
+                    space: {
+                        sys: {
+                            type: 'Link',
+                            linkType: 'Space',
+                            id: 'my-space'
+                        }
+                    },
+                    environment: {
+                        sys: {
+                            type: 'Link',
+                            linkType: 'Environment',
+                            id: 'master'
+                        }
+                    },
+                    contentType: {
+                        sys: {
+                            type: 'Link',
+                            linkType: 'ContentType',
+                            id: 'blogPost'
+                        }
+                    },
+                    revision: 5,
+                    createdAt: '2025-01-01T00:00:00Z',
+                    updatedAt: new Date().toISOString()
+                },
+                fields: {
+                    title: { 'en-US': 'My Blog Post' },
+                    content: { 'en-US': 'Blog post content here' }
+                }
+            };
+            const body = JSON.stringify(payload);
+            const hmac = crypto_1.default.createHmac('sha256', TEST_SECRET);
+            hmac.update(body);
+            const signature = hmac.digest('base64');
+            const headers = {
+                'x-contentful-signature': signature,
+                'x-contentful-topic': 'Entry.publish',
+                'x-contentful-webhook-name': 'test-webhook',
+                'x-contentful-crn': 'crn:contentful:::content:spaces/my-space'
+            };
+            const result = handler.parseWebhook(body, headers);
+            expect(result.valid).toBe(true);
+            expect(result.payload?.sys.id).toBe('blog-post-123');
+            expect(result.topic).toBe('Entry.publish');
+            if (result.topic) {
+                const eventType = handler.getEventType(result.topic);
+                expect(eventType.resource).toBe('Entry');
+                expect(eventType.action).toBe('publish');
+            }
+        });
+        it('should handle Asset.delete webhook', () => {
+            const payload = {
+                sys: {
+                    type: 'Asset',
+                    id: 'asset-456',
+                    space: {
+                        sys: {
+                            type: 'Link',
+                            linkType: 'Space',
+                            id: 'my-space'
+                        }
+                    },
+                    environment: {
+                        sys: {
+                            type: 'Link',
+                            linkType: 'Environment',
+                            id: 'master'
+                        }
+                    },
+                    revision: 1,
+                    updatedAt: new Date().toISOString()
+                }
+            };
+            const body = JSON.stringify(payload);
+            const hmac = crypto_1.default.createHmac('sha256', TEST_SECRET);
+            hmac.update(body);
+            const signature = hmac.digest('base64');
+            const headers = {
+                'x-contentful-signature': signature,
+                'x-contentful-topic': 'Asset.delete'
+            };
+            const result = handler.parseWebhook(body, headers);
+            expect(result.valid).toBe(true);
+            expect(result.payload?.sys.type).toBe('Asset');
+            expect(result.topic).toBe('Asset.delete');
+        });
+    });
+});

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

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

package/dist/__tests__/index.test.js

@@ -0,0 +1,62 @@
+"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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+describe('index exports', () => {
+    it('should export ContentfulWebhookHandler class', () => {
+        expect(index_1.ContentfulWebhookHandler).toBeDefined();
+        expect(typeof index_1.ContentfulWebhookHandler).toBe('function');
+    });
+    it('should create a ContentfulWebhookHandler instance', () => {
+        const handler = new index_1.ContentfulWebhookHandler({
+            webhookSecret: 'test-secret'
+        });
+        expect(handler).toBeInstanceOf(index_1.ContentfulWebhookHandler);
+    });
+    it('should export type definitions', () => {
+        // Type check - these should compile
+        const payload = {
+            sys: {
+                type: 'Entry',
+                id: 'test',
+                space: {
+                    sys: { type: 'Link', linkType: 'Space', id: 'space' }
+                },
+                environment: {
+                    sys: { type: 'Link', linkType: 'Environment', id: 'master' }
+                }
+            }
+        };
+        const validationResult = {
+            valid: true,
+            payload,
+            topic: 'Entry.publish'
+        };
+        const eventType = {
+            resource: 'Entry',
+            action: 'publish'
+        };
+        const options = {
+            webhookSecret: 'test'
+        };
+        const topic = 'Entry.publish';
+        const headers = {
+            'x-contentful-signature': 'sig',
+            'x-contentful-topic': 'Entry.publish',
+            'x-contentful-webhook-name': 'test',
+            'x-contentful-crn': 'crn:test'
+        };
+        // If these compile, the types are exported correctly
+        expect(validationResult).toBeDefined();
+        expect(eventType).toBeDefined();
+        expect(options).toBeDefined();
+        expect(topic).toBeDefined();
+        expect(headers).toBeDefined();
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ContentfulWebhookHandler, WebhookValidationResult, EventType, ContentfulWebhookHandlerOptions } from './ContentfulWebhookHandler';
+export type { ContentfulWebhookPayload, ContentfulWebhookTopic, ContentfulWebhookHeaders } from '@bernierllc/contentful-types';

package/dist/index.js

@@ -0,0 +1,12 @@
+"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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentfulWebhookHandler = void 0;
+var ContentfulWebhookHandler_1 = require("./ContentfulWebhookHandler");
+Object.defineProperty(exports, "ContentfulWebhookHandler", { enumerable: true, get: function () { return ContentfulWebhookHandler_1.ContentfulWebhookHandler; } });