@bernierllc/contentful-webhook-handler 1.0.3

package/.eslintrc.cjs

@@ -0,0 +1,36 @@
+/*
+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 = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+    project: './tsconfig.json',
+  },
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+  ],
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-unsafe-assignment': 'warn',
+    '@typescript-eslint/no-unsafe-member-access': 'warn',
+    '@typescript-eslint/no-unsafe-call': 'warn',
+    '@typescript-eslint/no-unsafe-return': 'warn',
+  },
+  env: {
+    node: true,
+    jest: true,
+  },
+};

package/LICENSE.md

@@ -0,0 +1,9 @@
+# Limited-Use License
+
+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.
+
+For licensing inquiries, please contact: legal@bernierllc.com

package/README.md

@@ -0,0 +1,385 @@
+# @bernierllc/contentful-webhook-handler
+
+Validates Contentful webhook signatures using HMAC-SHA256, parses webhook payloads, and provides type-safe interfaces for all webhook event types.
+
+## Features
+
+- **HMAC-SHA256 Signature Validation**: Securely verify webhook authenticity
+- **Type-Safe Payload Parsing**: Full TypeScript support for all Contentful webhook events
+- **Event Type Detection**: Extract resource type and action from webhook topics
+- **Replay Attack Prevention**: Optional timestamp validation
+- **Timing-Safe Comparison**: Prevents timing attacks during signature validation
+- **Comprehensive Error Handling**: Detailed error messages for debugging
+
+## Installation
+
+```bash
+npm install @bernierllc/contentful-webhook-handler
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { ContentfulWebhookHandler } from '@bernierllc/contentful-webhook-handler';
+
+const handler = new ContentfulWebhookHandler({
+  webhookSecret: process.env.CONTENTFUL_WEBHOOK_SECRET!
+});
+```
+
+### Validate and Parse Webhook
+
+```typescript
+// In your webhook endpoint handler
+app.post('/webhooks/contentful', (req, res) => {
+  const body = JSON.stringify(req.body);
+  const headers = {
+    'x-contentful-signature': req.headers['x-contentful-signature'],
+    'x-contentful-topic': req.headers['x-contentful-topic']
+  };
+
+  const result = handler.parseWebhook(body, headers);
+
+  if (!result.valid) {
+    console.error('Invalid webhook:', result.error);
+    return res.status(401).json({ error: result.error });
+  }
+
+  // Process valid webhook
+  const { payload, topic } = result;
+  console.log(`Received ${topic} for ${payload.sys.type} ${payload.sys.id}`);
+
+  res.status(200).json({ success: true });
+});
+```
+
+### Extract Event Type
+
+```typescript
+const result = handler.parseWebhook(body, headers);
+
+if (result.valid && result.topic) {
+  const eventType = handler.getEventType(result.topic);
+
+  console.log(`Resource: ${eventType.resource}`); // 'Entry' | 'Asset' | 'ContentType'
+  console.log(`Action: ${eventType.action}`);     // 'create' | 'publish' | 'delete' | etc.
+
+  // Route based on event type
+  if (eventType.resource === 'Entry' && eventType.action === 'publish') {
+    await handleEntryPublish(result.payload);
+  }
+}
+```
+
+### Enable Replay Attack Prevention
+
+```typescript
+const handler = new ContentfulWebhookHandler({
+  webhookSecret: process.env.CONTENTFUL_WEBHOOK_SECRET!,
+  enableTimestampValidation: true,
+  maxTimestampDeltaSeconds: 300 // 5 minutes
+});
+```
+
+### Update Webhook Secret
+
+```typescript
+// When rotating secrets
+handler.updateSecret(newWebhookSecret);
+```
+
+## API
+
+### `ContentfulWebhookHandler`
+
+#### Constructor Options
+
+```typescript
+interface ContentfulWebhookHandlerOptions {
+  webhookSecret: string;                // Required: Your Contentful webhook secret
+  logger?: Logger;                      // Optional: Custom logger instance
+  enableTimestampValidation?: boolean;  // Optional: Enable replay attack prevention (default: false)
+  maxTimestampDeltaSeconds?: number;    // Optional: Max timestamp age in seconds (default: 300)
+}
+```
+
+#### Methods
+
+##### `parseWebhook(body: string, headers: Partial<ContentfulWebhookHeaders>): WebhookValidationResult`
+
+Validates signature and parses webhook payload.
+
+**Parameters:**
+- `body`: Raw webhook body as string (must be unparsed JSON)
+- `headers`: Webhook headers (must include `x-contentful-signature` and `x-contentful-topic`)
+
+**Returns:**
+```typescript
+interface WebhookValidationResult {
+  valid: boolean;                        // True if webhook is valid
+  error?: string;                        // Error message if invalid
+  payload?: ContentfulWebhookPayload;    // Parsed payload if valid
+  topic?: ContentfulWebhookTopic;        // Webhook topic if valid
+}
+```
+
+##### `validateSignature(body: string, signature: string): boolean`
+
+Validates webhook signature using HMAC-SHA256.
+
+**Parameters:**
+- `body`: Raw webhook body as string
+- `signature`: Base64-encoded signature from `x-contentful-signature` header
+
+**Returns:** `true` if signature is valid, `false` otherwise
+
+##### `getEventType(topic: ContentfulWebhookTopic): EventType`
+
+Extracts resource type and action from webhook topic.
+
+**Parameters:**
+- `topic`: Contentful webhook topic (e.g., "Entry.publish")
+
+**Returns:**
+```typescript
+interface EventType {
+  resource: 'Entry' | 'Asset' | 'ContentType';
+  action: 'create' | 'save' | 'auto_save' | 'publish' | 'unpublish' | 'delete' | 'archive' | 'unarchive';
+}
+```
+
+##### `updateSecret(newSecret: string): void`
+
+Updates the webhook secret (useful for secret rotation).
+
+**Parameters:**
+- `newSecret`: New webhook secret
+
+## Supported Webhook Topics
+
+### Entry Events
+- `Entry.create` - Entry created
+- `Entry.save` - Entry saved (draft)
+- `Entry.auto_save` - Entry auto-saved
+- `Entry.publish` - Entry published
+- `Entry.unpublish` - Entry unpublished
+- `Entry.archive` - Entry archived
+- `Entry.unarchive` - Entry unarchived
+- `Entry.delete` - Entry deleted
+
+### Asset Events
+- `Asset.create` - Asset created
+- `Asset.save` - Asset saved
+- `Asset.auto_save` - Asset auto-saved
+- `Asset.publish` - Asset published
+- `Asset.unpublish` - Asset unpublished
+- `Asset.archive` - Asset archived
+- `Asset.unarchive` - Asset unarchived
+- `Asset.delete` - Asset deleted
+
+### ContentType Events
+- `ContentType.create` - Content type created
+- `ContentType.save` - Content type saved
+- `ContentType.publish` - Content type published
+- `ContentType.unpublish` - Content type unpublished
+- `ContentType.delete` - Content type deleted
+
+## Express.js Integration Example
+
+```typescript
+import express from 'express';
+import { ContentfulWebhookHandler } from '@bernierllc/contentful-webhook-handler';
+
+const app = express();
+
+// IMPORTANT: Use express.text() to preserve raw body for signature validation
+app.use('/webhooks/contentful', express.text({ type: 'application/json' }));
+
+const handler = new ContentfulWebhookHandler({
+  webhookSecret: process.env.CONTENTFUL_WEBHOOK_SECRET!,
+  enableTimestampValidation: true
+});
+
+app.post('/webhooks/contentful', (req, res) => {
+  const result = handler.parseWebhook(req.body, {
+    'x-contentful-signature': req.headers['x-contentful-signature'] as string,
+    'x-contentful-topic': req.headers['x-contentful-topic'] as string
+  });
+
+  if (!result.valid) {
+    return res.status(401).json({ error: result.error });
+  }
+
+  // Process webhook
+  const eventType = handler.getEventType(result.topic!);
+
+  switch (eventType.resource) {
+    case 'Entry':
+      if (eventType.action === 'publish') {
+        console.log('Entry published:', result.payload!.sys.id);
+      }
+      break;
+    case 'Asset':
+      if (eventType.action === 'delete') {
+        console.log('Asset deleted:', result.payload!.sys.id);
+      }
+      break;
+  }
+
+  res.status(200).json({ success: true });
+});
+
+app.listen(3000, () => {
+  console.log('Webhook server running on port 3000');
+});
+```
+
+## Security Best Practices
+
+1. **Always validate signatures**: Never trust webhook data without signature validation
+2. **Use raw body**: Ensure you pass the unparsed JSON string to `parseWebhook()`
+3. **Enable timestamp validation**: Prevent replay attacks by validating webhook timestamps
+4. **Rotate secrets regularly**: Use `updateSecret()` to rotate your webhook secrets
+5. **Use HTTPS**: Always use HTTPS endpoints for webhooks in production
+6. **Rate limiting**: Implement rate limiting on webhook endpoints
+
+## Error Handling
+
+```typescript
+const result = handler.parseWebhook(body, headers);
+
+if (!result.valid) {
+  switch (result.error) {
+    case 'Missing signature header (x-contentful-signature)':
+      // Handle missing signature
+      break;
+    case 'Missing topic header (x-contentful-topic)':
+      // Handle missing topic
+      break;
+    case 'Invalid signature':
+      // Handle signature validation failure
+      break;
+    case 'Invalid timestamp (possible replay attack)':
+      // Handle replay attack attempt
+      break;
+    default:
+      // Handle other errors (e.g., JSON parsing)
+      console.error('Webhook error:', result.error);
+  }
+}
+```
+
+## MECE Architecture
+
+This package follows MECE (Mutually Exclusive, Collectively Exhaustive) principles:
+
+**Includes:**
+- HMAC-SHA256 signature validation
+- Webhook payload parsing and typing
+- Event type detection and routing
+- Header validation
+- Replay attack prevention
+
+**Excludes:**
+- ❌ Webhook receiving/HTTP server (use `@bernierllc/webhook-receiver`)
+- ❌ Webhook queueing (use `@bernierllc/message-queue`)
+- ❌ Webhook processing logic (use `@bernierllc/contentful-webhook-service`)
+
+## Integration Documentation
+
+### Logger Integration
+
+This package integrates with `@bernierllc/logger` for structured logging of webhook validation events. The logger provides:
+
+- Structured JSON output for all validation events
+- Configurable log levels (info, warn, error)
+- Context-aware logging with service metadata
+- Optional custom logger injection via constructor
+
+```typescript
+import { Logger } from '@bernierllc/logger';
+
+const customLogger = new Logger({
+  service: 'my-webhook-service',
+  level: 'debug'
+});
+
+const handler = new ContentfulWebhookHandler({
+  webhookSecret: process.env.CONTENTFUL_WEBHOOK_SECRET!,
+  logger: customLogger
+});
+```
+
+The integration uses graceful degradation - if no custom logger is provided, a default logger instance is created automatically.
+
+### NeverHub Integration
+
+This package is designed for NeverHub integration when used in service-layer packages like `@bernierllc/contentful-webhook-service`. While the core handler itself doesn't directly integrate with NeverHub, it provides the building blocks for NeverHub-aware webhook processing:
+
+- Type-safe webhook payloads for NeverHub event routing
+- Signature validation for secure webhook ingestion
+- Event type extraction for NeverHub event classification
+
+When building a service layer with NeverHub integration, use this pattern:
+
+```typescript
+import { ContentfulWebhookHandler } from '@bernierllc/contentful-webhook-handler';
+import { NeverHubAdapter } from '@bernierllc/neverhub-adapter';
+
+class ContentfulWebhookService {
+  private handler: ContentfulWebhookHandler;
+  private neverhub?: NeverHubAdapter;
+
+  async initialize() {
+    this.handler = new ContentfulWebhookHandler({
+      webhookSecret: process.env.CONTENTFUL_WEBHOOK_SECRET!
+    });
+
+    // Auto-detect NeverHub
+    if (await NeverHubAdapter.detect()) {
+      this.neverhub = new NeverHubAdapter();
+      await this.neverhub.register({
+        type: 'contentful-webhook-service',
+        capabilities: ['webhook-processing', 'signature-validation']
+      });
+    }
+  }
+
+  async processWebhook(body: string, headers: any) {
+    const result = this.handler.parseWebhook(body, headers);
+
+    if (result.valid && this.neverhub) {
+      // Route validated webhooks to NeverHub
+      await this.neverhub.emit('contentful.webhook', {
+        topic: result.topic,
+        payload: result.payload
+      });
+    }
+
+    return result;
+  }
+}
+```
+
+This architecture ensures graceful degradation - the webhook handler works with or without NeverHub, allowing for flexible deployment scenarios.
+
+## Dependencies
+
+- `@bernierllc/contentful-types` - Contentful type definitions
+- `@bernierllc/logger` - Logging utilities
+
+## License
+
+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.
+
+## Related Packages
+
+- [@bernierllc/contentful-types](../contentful-types) - Contentful TypeScript types
+- [@bernierllc/contentful-webhook-service](../../service/contentful-webhook-service) - Webhook processing service
+- [@bernierllc/webhook-receiver](../webhook-receiver) - Generic webhook receiver

package/dist/ContentfulWebhookHandler.d.ts

@@ -0,0 +1,71 @@
+import { ContentfulWebhookPayload, ContentfulWebhookTopic, ContentfulWebhookHeaders } from '@bernierllc/contentful-types';
+import { Logger } 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 declare class ContentfulWebhookHandler {
+    private webhookSecret;
+    private logger;
+    private enableTimestampValidation;
+    private maxTimestampDeltaSeconds;
+    /**
+     * Creates a new ContentfulWebhookHandler instance
+     *
+     * @param options Configuration options
+     */
+    constructor(options: ContentfulWebhookHandlerOptions);
+    /**
+     * 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;
+    /**
+     * Validates webhook timestamp to prevent replay attacks
+     *
+     * @param payload Parsed webhook payload
+     * @returns True if timestamp is within acceptable range
+     */
+    private validateTimestamp;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Updates the webhook secret
+     *
+     * @param newSecret New webhook secret
+     */
+    updateSecret(newSecret: string): void;
+}