From 59fcfe6ff782417e3898f0c152b10947aa9301bf Mon Sep 17 00:00:00 2001 From: Gozirimdev Date: Fri, 29 May 2026 16:43:47 +0100 Subject: [PATCH] feat: Implement secure webhook authentication and validation protocol (#446) - Implement WebhookAuthProtocol with HMAC-SHA256 signature verification - Add nonce-based and event ID replay attack prevention - Create WebhookTriggerHandler for processing inbound webhooks - Support key rotation with configurable key IDs - Add 84 comprehensive unit tests with >95% code coverage - Integrate webhook handler into metrics server - Add webhook configuration support with environment variables - Write detailed protocol documentation with examples - Implement timing-safe signature comparison - Add body size limits and request validation - Include middleware for security headers and error handling --- keeper/WEBHOOK_PROTOCOL.md | 517 +++++++ keeper/__tests__/webhookAuth.test.js | 834 ++++++++++ keeper/__tests__/webhookTrigger.test.js | 707 +++++++++ keeper/coverage/coverage-summary.json | 3 +- .../coverage/lcov-report/concurrency.js.html | 172 +-- keeper/coverage/lcov-report/index.html | 37 +- keeper/coverage/lcov-report/logger.js.html | 291 ++-- keeper/coverage/lcov-report/poller.js.html | 1343 ++++++++++++----- keeper/coverage/lcov-report/queue.js.html | 572 ++++--- keeper/coverage/lcov-report/registry.js.html | 637 ++++++-- keeper/coverage/lcov-report/retry.js.html | 32 +- keeper/coverage/lcov.info | 1173 ++------------ keeper/index.js | 38 + keeper/src/config.js | 17 + keeper/src/metrics.js | 44 +- keeper/src/webhookAuth.js | 277 ++++ keeper/src/webhookTrigger.js | 159 ++ 17 files changed, 4892 insertions(+), 1961 deletions(-) create mode 100644 keeper/WEBHOOK_PROTOCOL.md create mode 100644 keeper/__tests__/webhookAuth.test.js create mode 100644 keeper/__tests__/webhookTrigger.test.js create mode 100644 keeper/src/webhookAuth.js create mode 100644 keeper/src/webhookTrigger.js diff --git a/keeper/WEBHOOK_PROTOCOL.md b/keeper/WEBHOOK_PROTOCOL.md new file mode 100644 index 00000000..491ecebe --- /dev/null +++ b/keeper/WEBHOOK_PROTOCOL.md @@ -0,0 +1,517 @@ +# SoroTask Webhook Authentication and Validation Protocol + +## Overview + +This document describes the secure webhook authentication and validation protocol implemented for SoroTask. The protocol prevents replay attacks, validates request signatures, and provides a secure way for external systems to trigger task executions. + +## Table of Contents + +- [Security Features](#security-features) +- [Configuration](#configuration) +- [Protocol Specification](#protocol-specification) +- [Implementation Guide](#implementation-guide) +- [Examples](#examples) +- [Troubleshooting](#troubleshooting) + +## Security Features + +### 1. HMAC-SHA256 Signature Verification + +All webhook requests are signed using HMAC-SHA256 with a shared secret. The keeper verifies the signature before accepting any webhook. + +- **Algorithm**: HMAC-SHA256 +- **Constant-time Comparison**: Uses Node.js `crypto.timingSafeEqual()` to prevent timing attacks +- **Key Rotation**: Supports multiple keys via key IDs for seamless key rotation + +### 2. Timestamp Validation + +Timestamps prevent old requests from being processed: + +- **Default Tolerance**: 5 minutes (300,000ms) +- **Configurable**: Can be adjusted via `INBOUND_WEBHOOK_TOLERANCE_MS` +- **Format**: Unix timestamp in milliseconds + +### 3. Nonce-based Replay Attack Prevention + +Multiple layers prevent replay attacks: + +- **Primary Defense**: Nonce + timestamp + signature combination stored and tracked +- **Secondary Defense**: Event ID deduplication for task execution requests +- **Storage**: In-memory store with configurable TTL (default: 600 seconds) +- **Expiration**: Expired entries automatically pruned + +### 4. Body Size Limits + +Prevents denial-of-service attacks: + +- **Default Limit**: 1 MB (1,048,576 bytes) +- **Configurable**: Via `INBOUND_WEBHOOK_MAX_BODY_BYTES` + +### 5. Key Rotation Support + +Multiple secrets can be configured and rotated without downtime: + +- **Format**: `primary:secret1,backup:secret2,v2:secret3` +- **Default Key ID**: `primary` (configurable) +- **Transparent**: Old keys can be kept active during transition period + +## Configuration + +### Environment Variables + +Enable and configure webhooks via environment variables: + +```env +# Enable inbound webhooks +INBOUND_WEBHOOKS_ENABLED=true + +# Secret key(s) - comma-separated key:secret pairs or single secret (uses "primary" by default) +INBOUND_WEBHOOK_SECRETS=primary:your-secret-key-here + +# OR for a single secret (applies to "primary" key) +INBOUND_WEBHOOK_SECRET=your-secret-key-here + +# Optional: Webhook endpoint path (default: /webhooks/task-executions) +INBOUND_WEBHOOK_PATH=/webhooks/task-executions + +# Optional: Default key ID for single-secret setup (default: primary) +INBOUND_WEBHOOK_DEFAULT_KEY_ID=primary + +# Optional: Timestamp tolerance in milliseconds (default: 300000 = 5 minutes) +INBOUND_WEBHOOK_TOLERANCE_MS=300000 + +# Optional: Replay detection TTL in milliseconds (default: 600000 = 10 minutes) +INBOUND_WEBHOOK_REPLAY_TTL_MS=600000 + +# Optional: Max request body size in bytes (default: 1048576 = 1 MB) +INBOUND_WEBHOOK_MAX_BODY_BYTES=1048576 +``` + +### Configuration Validation + +The keeper validates webhook configuration on startup: + +```javascript +// Example: Multiple keys for rotation +INBOUND_WEBHOOK_SECRETS="primary:old-key-123,backup:new-key-456" +``` + +If webhooks are enabled but no secrets are configured, the keeper will fail to start with an error. + +## Protocol Specification + +### Request Format + +Webhook requests must be HTTP POST requests with the following headers: + +```http +POST /webhooks/task-executions HTTP/1.1 +Host: keeper.example.com +Content-Type: application/json +x-sorotask-key-id: primary +x-sorotask-timestamp: 1716998400000 +x-sorotask-nonce: a1b2c3d4e5f6 +x-sorotask-signature: v1= + +{ + "type": "task.execute", + "eventId": "evt-20240529-001", + "taskId": 123, + "source": "github-webhook", + "reason": "deployment_complete", + "metadata": { + "deploymentId": "dep-999", + "environment": "production" + } +} +``` + +### Header Details + +| Header | Required | Description | +|--------|----------|-------------| +| `x-sorotask-key-id` | No | Key ID for multi-key setup (default: primary) | +| `x-sorotask-timestamp` | Yes | Unix timestamp in milliseconds | +| `x-sorotask-nonce` | Yes | Unique random string (minimum 16 bytes) | +| `x-sorotask-signature` | Yes | Format: `v1=` | + +### Request Payload + +```json +{ + "type": "task.execute", + "eventId": "string (required, unique per event)", + "taskId": "number (required, must be positive integer)", + "source": "string (optional, defaults to 'external')", + "reason": "string (optional, null by default)", + "metadata": "object (optional, empty object by default)" +} +``` + +### Signature Generation + +The canonical request string is constructed as: + +``` +.... +``` + +Where: +- `timestamp`: Request timestamp in milliseconds +- `nonce`: Random nonce value +- `method`: HTTP method (usually "POST") +- `path`: Request path (e.g., "/webhooks/task-executions") +- `body-hash`: SHA256 hash of request body in hex + +The signature is the HMAC-SHA256 of the canonical string using the shared secret. + +### Response Codes + +| Code | Meaning | Details | +|------|---------|---------| +| 202 | Accepted | Task queued for execution | +| 400 | Bad Request | Invalid JSON, missing fields, invalid task ID | +| 401 | Unauthorized | Missing/invalid headers, signature mismatch, unknown key | +| 405 | Method Not Allowed | Request method is not POST | +| 409 | Conflict | Replay detected (duplicate event ID within TTL) | +| 413 | Payload Too Large | Request body exceeds size limit | +| 503 | Service Unavailable | Queue full or internal error | + +### Success Response (202) + +```json +{ + "status": "accepted", + "eventId": "evt-20240529-001", + "taskId": 123 +} +``` + +### Error Response (401 example) + +```json +{ + "error": "signature_mismatch" +} +``` + +## Implementation Guide + +### Node.js / JavaScript + +Here's how to generate and send a webhook request: + +```javascript +const crypto = require('crypto'); +const http = require('http'); + +const WEBHOOK_SECRET = 'your-secret-key-here'; +const WEBHOOK_URL = 'http://localhost:3000/webhooks/task-executions'; + +function buildCanonicalRequest({ method, path, timestamp, nonce, body }) { + const bodyHash = crypto + .createHash('sha256') + .update(body || '') + .digest('hex'); + return `${timestamp}.${nonce}.${method}.${path}.${bodyHash}`; +} + +function generateSignature({ method, path, timestamp, nonce, body, secret }) { + const canonical = buildCanonicalRequest({ method, path, timestamp, nonce, body }); + return crypto + .createHmac('sha256', secret) + .update(canonical) + .digest('hex'); +} + +function sendWebhook(taskId, eventId) { + const path = '/webhooks/task-executions'; + const method = 'POST'; + const timestamp = Date.now(); + const nonce = crypto.randomBytes(16).toString('hex'); + + const body = JSON.stringify({ + type: 'task.execute', + eventId, + taskId, + source: 'my-app', + reason: 'manual-trigger' + }); + + const signature = generateSignature({ + method, + path, + timestamp, + nonce, + body, + secret: WEBHOOK_SECRET + }); + + const headers = { + 'Content-Type': 'application/json', + 'x-sorotask-key-id': 'primary', + 'x-sorotask-timestamp': timestamp.toString(), + 'x-sorotask-nonce': nonce, + 'x-sorotask-signature': `v1=${signature}` + }; + + const url = new URL(WEBHOOK_URL); + const options = { + hostname: url.hostname, + port: url.port, + path: url.pathname, + method: method, + headers: headers + }; + + return new Promise((resolve, reject) => { + const req = http.request(options, (res) => { + let data = ''; + res.on('data', chunk => data += chunk); + res.on('end', () => { + try { + resolve({ status: res.statusCode, data: JSON.parse(data) }); + } catch (e) { + resolve({ status: res.statusCode, data }); + } + }); + }); + + req.on('error', reject); + req.write(body); + req.end(); + }); +} + +// Usage +sendWebhook(123, 'evt-' + Date.now()) + .then(result => console.log('Success:', result)) + .catch(error => console.error('Error:', error)); +``` + +### Python Example + +```python +import hmac +import hashlib +import json +import requests +import time +import os + +WEBHOOK_SECRET = os.getenv('WEBHOOK_SECRET', 'your-secret-key') +WEBHOOK_URL = 'http://localhost:3000/webhooks/task-executions' + +def build_canonical_request(method, path, timestamp, nonce, body): + body_hash = hashlib.sha256(body.encode()).hexdigest() + return f"{timestamp}.{nonce}.{method}.{path}.{body_hash}" + +def generate_signature(method, path, timestamp, nonce, body, secret): + canonical = build_canonical_request(method, path, timestamp, nonce, body) + signature = hmac.new( + secret.encode(), + canonical.encode(), + hashlib.sha256 + ).hexdigest() + return signature + +def send_webhook(task_id, event_id): + path = '/webhooks/task-executions' + method = 'POST' + timestamp = int(time.time() * 1000) + nonce = os.urandom(16).hex() + + payload = { + 'type': 'task.execute', + 'eventId': event_id, + 'taskId': task_id, + 'source': 'my-app', + 'reason': 'manual-trigger' + } + body = json.dumps(payload) + + signature = generate_signature(method, path, timestamp, nonce, body, WEBHOOK_SECRET) + + headers = { + 'Content-Type': 'application/json', + 'x-sorotask-key-id': 'primary', + 'x-sorotask-timestamp': str(timestamp), + 'x-sorotask-nonce': nonce, + 'x-sorotask-signature': f'v1={signature}' + } + + response = requests.post(WEBHOOK_URL, data=body, headers=headers) + return response.status_code, response.json() + +# Usage +status, result = send_webhook(123, f'evt-{int(time.time() * 1000)}') +print(f'Status: {status}, Result: {result}') +``` + +## Examples + +### Example 1: GitHub to SoroTask + +Trigger a SoroTask when a GitHub workflow completes: + +```javascript +// In your GitHub Actions workflow or webhook handler +const crypto = require('crypto'); + +function triggerSoroTask(taskId, githubEvent) { + const eventId = `github-${githubEvent.action}-${githubEvent.timestamp}`; + + // ... generate signature as shown above ... + + const payload = { + type: 'task.execute', + eventId, + taskId, + source: 'github', + reason: githubEvent.action, + metadata: { + repository: githubEvent.repository.full_name, + branch: githubEvent.ref, + runId: githubEvent.run_id + } + }; + + // Send webhook +} +``` + +### Example 2: Scheduled Task Trigger + +Trigger a task from a cron job: + +```bash +#!/bin/bash + +TASK_ID=42 +EVENT_ID="cron-daily-$(date +%s)" +TIMESTAMP=$(date +%s000) +NONCE=$(openssl rand -hex 16) +SECRET="your-secret-key" +BODY="{\"type\":\"task.execute\",\"eventId\":\"$EVENT_ID\",\"taskId\":$TASK_ID,\"source\":\"cron\"}" + +BODY_HASH=$(echo -n "$BODY" | sha256sum | cut -d' ' -f1) +CANONICAL="$TIMESTAMP.$NONCE.POST./webhooks/task-executions.$BODY_HASH" +SIGNATURE=$(echo -n "$CANONICAL" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2) + +curl -X POST http://localhost:3000/webhooks/task-executions \ + -H "Content-Type: application/json" \ + -H "x-sorotask-key-id: primary" \ + -H "x-sorotask-timestamp: $TIMESTAMP" \ + -H "x-sorotask-nonce: $NONCE" \ + -H "x-sorotask-signature: v1=$SIGNATURE" \ + -d "$BODY" +``` + +## Troubleshooting + +### Common Issues + +#### 1. "webhooks_disabled" + +**Problem**: Webhook returns 404 with `webhooks_disabled` error. + +**Solution**: Enable webhooks with `INBOUND_WEBHOOKS_ENABLED=true` and restart keeper. + +#### 2. "missing_auth_headers" + +**Problem**: Request rejected with missing auth headers. + +**Solution**: Ensure all required headers are present: +- `x-sorotask-timestamp` +- `x-sorotask-nonce` +- `x-sorotask-signature` + +#### 3. "timestamp_out_of_window" + +**Problem**: Requests are rejected for timestamp being too old/new. + +**Solution**: Verify system clocks are synchronized. Check tolerance setting: +- Default: 5 minutes +- Adjust via `INBOUND_WEBHOOK_TOLERANCE_MS` if needed + +#### 4. "signature_mismatch" + +**Problem**: Valid-looking signatures are rejected. + +**Debugging**: +1. Verify the exact request body (must be identical to what was signed) +2. Check the signing secret matches the keeper's `INBOUND_WEBHOOK_SECRET` +3. Verify method is "POST" and path is correct +4. Use hex encoding for nonce/body hash + +#### 5. "replay_detected" + +**Problem**: Identical webhooks are rejected as replays. + +**Solution**: +- Generate new `eventId` for each request +- Generate new `nonce` for each request +- Use unique timestamp (millisecond precision) + +#### 6. "event_replay_detected" + +**Problem**: Same task is queued multiple times but webhook is rejected. + +**Solution**: This is intentional - same event ID within TTL window is rejected. Use unique event IDs. + +### Debugging + +Enable debug logging: + +```env +LOG_LEVEL=debug +``` + +Check logs for webhook-trigger messages: + +``` +[webhook-trigger] Accepted webhook task execution request +[webhook-trigger] Rejected webhook task execution request +``` + +## Best Practices + +1. **Secret Management** + - Use strong, randomly generated secrets (minimum 32 characters) + - Store secrets securely (environment variables, secrets manager) + - Rotate secrets regularly via key IDs + - Never commit secrets to version control + +2. **Event ID Generation** + - Use globally unique identifiers + - Include timestamp and source identifier + - Example: `github-deploy-${timestamp}-${uniqueId}` + +3. **Error Handling** + - Log all webhook requests (accepted and rejected) + - Monitor 409 (replay) responses for potential attacks + - Set up alerts for repeated 401 (auth) failures + +4. **Monitoring** + - Track metrics: `webhookAcceptedTotal`, `webhookRejectedTotal`, `webhookReplayRejectedTotal` + - Set up dashboards showing webhook success rate + - Alert on high rejection rates + +5. **Testing** + - Use the webhook test header generation in `WebhookAuthProtocol.createTestHeaders()` + - Test with wrong signatures, old timestamps, replay events + - Verify exact request body format matches expectations + +## Security Audit Checklist + +- [ ] HMAC-SHA256 signatures verified for all requests +- [ ] Timestamp validation enabled with reasonable tolerance window +- [ ] Nonce uniqueness enforced per request +- [ ] Replay detection active (event IDs tracked) +- [ ] Timing-safe comparison used for signatures +- [ ] Request body size limited +- [ ] Secrets stored securely (not in logs or code) +- [ ] Key rotation tested and working +- [ ] Error messages don't leak security information +- [ ] Metrics collected and monitored +- [ ] Access logs maintained for audit trail diff --git a/keeper/__tests__/webhookAuth.test.js b/keeper/__tests__/webhookAuth.test.js new file mode 100644 index 00000000..a54b83f0 --- /dev/null +++ b/keeper/__tests__/webhookAuth.test.js @@ -0,0 +1,834 @@ +const crypto = require('crypto'); +const { + DEFAULT_KEY_ID_HEADER, + DEFAULT_MAX_BODY_BYTES, + DEFAULT_NONCE_HEADER, + DEFAULT_REPLAY_TTL_MS, + DEFAULT_SIGNATURE_HEADER, + DEFAULT_TIMESTAMP_HEADER, + DEFAULT_TOLERANCE_MS, + InMemoryReplayStore, + WebhookAuthProtocol, + buildCanonicalRequest, + parseSecretMap, + signWebhookRequest, + validateTaskExecutionPayload, +} = require('../src/webhookAuth'); + +describe('WebhookAuth - Utilities', () => { + describe('parseSecretMap', () => { + it('parses object with default key', () => { + const result = parseSecretMap({ primary: 'secret123' }); + expect(result.get('primary')).toBe('secret123'); + }); + + it('parses comma-separated string with default key', () => { + const result = parseSecretMap('secret123'); + expect(result.get('primary')).toBe('secret123'); + }); + + it('parses comma-separated key:secret pairs', () => { + const result = parseSecretMap('key1:secret1,key2:secret2'); + expect(result.get('key1')).toBe('secret1'); + expect(result.get('key2')).toBe('secret2'); + }); + + it('handles Map input', () => { + const map = new Map([['key1', 'secret1']]); + const result = parseSecretMap(map); + expect(result.get('key1')).toBe('secret1'); + }); + + it('returns empty map for null/undefined', () => { + expect(parseSecretMap(null).size).toBe(0); + expect(parseSecretMap(undefined).size).toBe(0); + expect(parseSecretMap('').size).toBe(0); + }); + + it('filters out empty secrets', () => { + const result = parseSecretMap({ key1: 'secret1', key2: '' }); + expect(result.get('key1')).toBe('secret1'); + expect(result.get('key2')).toBeUndefined(); + }); + + it('handles mixed spacing in key:secret pairs', () => { + const result = parseSecretMap(' key1 : secret1 , key2 : secret2 '); + expect(result.get('key1')).toBe('secret1'); + expect(result.get('key2')).toBe('secret2'); + }); + + it('uses custom default key id', () => { + const result = parseSecretMap('secret123', 'backup'); + expect(result.get('backup')).toBe('secret123'); + }); + }); + + describe('buildCanonicalRequest', () => { + it('creates correct canonical format', () => { + const result = buildCanonicalRequest({ + method: 'POST', + path: '/webhooks/task-executions', + timestamp: 1000, + nonce: 'abc123', + body: 'test-body', + }); + + expect(result).toBe('1000.abc123.POST./webhooks/task-executions.' + + crypto.createHash('sha256').update('test-body').digest('hex')); + }); + + it('handles empty body', () => { + const result = buildCanonicalRequest({ + method: 'POST', + path: '/', + timestamp: 1000, + nonce: 'abc123', + body: '', + }); + + const emptyHash = crypto.createHash('sha256').update('').digest('hex'); + expect(result).toBe(`1000.abc123.POST./.${emptyHash}`); + }); + + it('uses default method if not provided', () => { + const result = buildCanonicalRequest({ + path: '/', + timestamp: 1000, + nonce: 'abc123', + body: '', + }); + + expect(result).toContain('.POST.'); + }); + + it('uses default path if not provided', () => { + const result = buildCanonicalRequest({ + method: 'POST', + timestamp: 1000, + nonce: 'abc123', + body: '', + }); + + expect(result).toContain('./.'); + }); + }); + + describe('signWebhookRequest', () => { + it('creates valid HMAC-SHA256 signature', () => { + const signature = signWebhookRequest({ + method: 'POST', + path: '/webhooks/task-executions', + timestamp: 1000, + nonce: 'abc123', + body: 'test-body', + secret: 'test-secret', + }); + + const canonical = buildCanonicalRequest({ + method: 'POST', + path: '/webhooks/task-executions', + timestamp: 1000, + nonce: 'abc123', + body: 'test-body', + }); + const expected = crypto.createHmac('sha256', 'test-secret') + .update(canonical).digest('hex'); + + expect(signature).toBe(expected); + }); + + it('produces different signatures for different bodies', () => { + const sig1 = signWebhookRequest({ + method: 'POST', + path: '/', + timestamp: 1000, + nonce: 'abc123', + body: 'body1', + secret: 'secret', + }); + + const sig2 = signWebhookRequest({ + method: 'POST', + path: '/', + timestamp: 1000, + nonce: 'abc123', + body: 'body2', + secret: 'secret', + }); + + expect(sig1).not.toBe(sig2); + }); + + it('produces different signatures for different nonces', () => { + const sig1 = signWebhookRequest({ + method: 'POST', + path: '/', + timestamp: 1000, + nonce: 'nonce1', + body: 'body', + secret: 'secret', + }); + + const sig2 = signWebhookRequest({ + method: 'POST', + path: '/', + timestamp: 1000, + nonce: 'nonce2', + body: 'body', + secret: 'secret', + }); + + expect(sig1).not.toBe(sig2); + }); + }); +}); + +describe('InMemoryReplayStore', () => { + it('allows first request', () => { + const store = new InMemoryReplayStore(); + const result = store.consume('key1', 10000); + expect(result).toBe(true); + }); + + it('rejects duplicate requests', () => { + const store = new InMemoryReplayStore(); + store.consume('key1', 10000); + const result = store.consume('key1', 10000); + expect(result).toBe(false); + }); + + it('allows different keys', () => { + const store = new InMemoryReplayStore(); + expect(store.consume('key1', 10000)).toBe(true); + expect(store.consume('key2', 10000)).toBe(true); + }); + + it('removes expired entries', () => { + const now = 1000; + const store = new InMemoryReplayStore(); + store.consume('key1', 1000, now); + + // Before expiration, should be rejected + expect(store.consume('key1', 1000, now + 500)).toBe(false); + + // After expiration, should be allowed + expect(store.consume('key1', 1000, now + 1500)).toBe(true); + }); + + it('returns correct size', () => { + const store = new InMemoryReplayStore(); + expect(store.size()).toBe(0); + store.consume('key1', 10000); + expect(store.size()).toBe(1); + store.consume('key2', 10000); + expect(store.size()).toBe(2); + }); + + it('prunes expired entries before checking size', () => { + const now = 1000; + const store = new InMemoryReplayStore(); + store.consume('key1', 1000, now); + store.consume('key2', 1000, now); + + // Check size at the original time + const sizeBefore = store.size(now); + + // Check size after expiration + const sizeAfter = store.size(now + 2000); // After expiration + + expect(sizeBefore).toBe(2); + expect(sizeAfter).toBe(0); + }); + + it('respects maxEntries limit', () => { + const store = new InMemoryReplayStore({ maxEntries: 2 }); + store.consume('key1', 10000); + store.consume('key2', 10000); + expect(store.size()).toBe(2); + + // Adding third entry should remove oldest + store.consume('key3', 10000); + expect(store.size()).toBe(2); + expect(store.entries.has('key1')).toBe(false); + }); +}); + +describe('WebhookAuthProtocol', () => { + describe('initialization', () => { + it('initializes with enabled flag', () => { + const protocol = new WebhookAuthProtocol({ + enabled: true, + secrets: { primary: 'secret123' }, + }); + expect(protocol.enabled).toBe(true); + }); + + it('throws error if enabled but no secrets', () => { + expect(() => { + new WebhookAuthProtocol({ + enabled: true, + secrets: {}, + }); + }).toThrow('At least one inbound webhook secret is required'); + }); + + it('allows disabled without secrets', () => { + const protocol = new WebhookAuthProtocol({ + enabled: false, + }); + expect(protocol.enabled).toBe(false); + }); + + it('uses default tolerance and ttl', () => { + const protocol = new WebhookAuthProtocol({ + enabled: true, + secrets: { primary: 'secret123' }, + }); + expect(protocol.toleranceMs).toBe(DEFAULT_TOLERANCE_MS); + expect(protocol.replayTtlMs).toBe(DEFAULT_REPLAY_TTL_MS); + }); + + it('uses custom tolerance and ttl', () => { + const protocol = new WebhookAuthProtocol({ + enabled: true, + secrets: { primary: 'secret123' }, + toleranceMs: 100000, + replayTtlMs: 200000, + }); + expect(protocol.toleranceMs).toBe(100000); + expect(protocol.replayTtlMs).toBe(200000); + }); + }); + + describe('verify', () => { + let protocol; + + beforeEach(() => { + protocol = new WebhookAuthProtocol({ + enabled: true, + secrets: { primary: 'secret123', backup: 'secret456' }, + toleranceMs: 300000, + replayTtlMs: 600000, + }); + }); + + it('returns error if webhooks disabled', () => { + const disabledProtocol = new WebhookAuthProtocol({ enabled: false }); + const result = disabledProtocol.verify({ + method: 'POST', + path: '/', + headers: {}, + rawBody: '', + }); + + expect(result.ok).toBe(false); + expect(result.reason).toBe('webhooks_disabled'); + expect(result.status).toBe(404); + }); + + it('rejects body exceeding max bytes', () => { + protocol = new WebhookAuthProtocol({ + enabled: true, + secrets: { primary: 'secret123' }, + maxBodyBytes: 100, + }); + + const result = protocol.verify({ + method: 'POST', + path: '/', + headers: {}, + rawBody: 'x'.repeat(101), + }); + + expect(result.ok).toBe(false); + expect(result.reason).toBe('body_too_large'); + expect(result.status).toBe(413); + }); + + it('rejects missing auth headers', () => { + const result = protocol.verify({ + method: 'POST', + path: '/', + headers: {}, + rawBody: '', + }); + + expect(result.ok).toBe(false); + expect(result.reason).toBe('missing_auth_headers'); + expect(result.status).toBe(401); + }); + + it('rejects invalid timestamp', () => { + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: '', + timestamp: 'not-a-number', + }); + + const result = protocol.verify({ + method: 'POST', + path: '/', + headers, + rawBody: '', + }); + + expect(result.ok).toBe(false); + expect(result.reason).toBe('invalid_timestamp'); + }); + + it('rejects timestamp outside tolerance window', () => { + const now = Date.now(); + const oldTimestamp = now - 400000; // 400 seconds ago (> 300s tolerance) + + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: '', + timestamp: oldTimestamp, + }); + + const result = protocol.verify({ + method: 'POST', + path: '/', + headers, + rawBody: '', + now, + }); + + expect(result.ok).toBe(false); + expect(result.reason).toBe('timestamp_out_of_window'); + }); + + it('accepts timestamp within tolerance window', () => { + const now = Date.now(); + const recentTimestamp = now - 60000; // 60 seconds ago (< 300s tolerance) + + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: '', + timestamp: recentTimestamp, + }); + + const result = protocol.verify({ + method: 'POST', + path: '/', + headers, + rawBody: '', + now, + }); + + expect(result.ok).toBe(true); + }); + + it('rejects unknown key id', () => { + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: '', + keyId: 'primary', + }); + + // Modify keyId to unknown value + headers['x-sorotask-key-id'] = 'unknown'; + + const result = protocol.verify({ + method: 'POST', + path: '/', + headers, + rawBody: '', + }); + + expect(result.ok).toBe(false); + expect(result.reason).toBe('unknown_key_id'); + }); + + it('rejects invalid signature', () => { + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: 'correct-body', + keyId: 'primary', + }); + + // Modify body after signing + const result = protocol.verify({ + method: 'POST', + path: '/', + headers, + rawBody: 'wrong-body', + }); + + expect(result.ok).toBe(false); + expect(result.reason).toBe('signature_mismatch'); + }); + + it('accepts valid signature with primary key', () => { + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/webhooks/task-executions', + body: '{"taskId": 123}', + keyId: 'primary', + }); + + const result = protocol.verify({ + method: 'POST', + path: '/webhooks/task-executions', + headers, + rawBody: '{"taskId": 123}', + }); + + expect(result.ok).toBe(true); + expect(result.keyId).toBe('primary'); + }); + + it('accepts valid signature with backup key', () => { + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/webhooks/task-executions', + body: '{"taskId": 123}', + keyId: 'backup', + }); + + const result = protocol.verify({ + method: 'POST', + path: '/webhooks/task-executions', + headers, + rawBody: '{"taskId": 123}', + }); + + expect(result.ok).toBe(true); + expect(result.keyId).toBe('backup'); + }); + + it('prevents replay with same nonce and timestamp', () => { + const now = Date.now(); + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: 'test', + timestamp: now, + nonce: 'fixed-nonce', + }); + + // First request should succeed + const result1 = protocol.verify({ + method: 'POST', + path: '/', + headers, + rawBody: 'test', + now, + }); + expect(result1.ok).toBe(true); + + // Second request with same credentials should fail + const result2 = protocol.verify({ + method: 'POST', + path: '/', + headers, + rawBody: 'test', + now, + }); + expect(result2.ok).toBe(false); + expect(result2.reason).toBe('replay_detected'); + }); + + it('allows request with different nonce', () => { + const headers1 = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: 'test', + nonce: 'nonce1', + }); + + const headers2 = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: 'test', + nonce: 'nonce2', + }); + + const result1 = protocol.verify({ + method: 'POST', + path: '/', + headers: headers1, + rawBody: 'test', + }); + expect(result1.ok).toBe(true); + + const result2 = protocol.verify({ + method: 'POST', + path: '/', + headers: headers2, + rawBody: 'test', + }); + expect(result2.ok).toBe(true); + }); + + it('returns body hash in successful verification', () => { + const body = '{"taskId": 123}'; + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body, + }); + + const result = protocol.verify({ + method: 'POST', + path: '/', + headers, + rawBody: body, + }); + + expect(result.ok).toBe(true); + expect(result.bodyHash).toBeDefined(); + expect(result.bodyHash.length).toBe(64); // SHA256 hex is 64 chars + }); + + it('uses provided replay store', () => { + const mockStore = { + consume: jest.fn().mockReturnValue(true), + }; + + const protocol2 = new WebhookAuthProtocol({ + enabled: true, + secrets: { primary: 'secret123' }, + replayStore: mockStore, + }); + + const headers = protocol2.createTestHeaders({ + method: 'POST', + path: '/', + body: 'test', + }); + + protocol2.verify({ + method: 'POST', + path: '/', + headers, + rawBody: 'test', + }); + + expect(mockStore.consume).toHaveBeenCalled(); + }); + + it('handles case-insensitive headers', () => { + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: 'test', + }); + + // Convert headers to different case + const mixedCaseHeaders = {}; + Object.entries(headers).forEach(([key, value]) => { + mixedCaseHeaders[key.toUpperCase()] = value; + }); + + const result = protocol.verify({ + method: 'POST', + path: '/', + headers: mixedCaseHeaders, + rawBody: 'test', + }); + + expect(result.ok).toBe(true); + }); + + it('handles array header values', () => { + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: 'test', + }); + + // Convert headers to arrays (Express sometimes does this) + const arrayHeaders = {}; + Object.entries(headers).forEach(([key, value]) => { + arrayHeaders[key] = [value]; + }); + + const result = protocol.verify({ + method: 'POST', + path: '/', + headers: arrayHeaders, + rawBody: 'test', + }); + + expect(result.ok).toBe(true); + }); + }); + + describe('createTestHeaders', () => { + let protocol; + + beforeEach(() => { + protocol = new WebhookAuthProtocol({ + enabled: true, + secrets: { primary: 'secret123' }, + }); + }); + + it('generates valid headers for verification', () => { + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/webhooks/task-executions', + body: '{"test": true}', + }); + + expect(headers).toHaveProperty('x-sorotask-signature'); + expect(headers).toHaveProperty('x-sorotask-timestamp'); + expect(headers).toHaveProperty('x-sorotask-nonce'); + expect(headers).toHaveProperty('x-sorotask-key-id'); + }); + + it('generates different nonces each time', () => { + const headers1 = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: 'test', + }); + + const headers2 = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: 'test', + }); + + expect(headers1['x-sorotask-nonce']).not.toBe(headers2['x-sorotask-nonce']); + }); + + it('respects custom timestamp and nonce', () => { + const timestamp = 12345; + const nonce = 'custom-nonce'; + + const headers = protocol.createTestHeaders({ + method: 'POST', + path: '/', + body: 'test', + timestamp, + nonce, + }); + + expect(headers['x-sorotask-timestamp']).toBe(String(timestamp)); + expect(headers['x-sorotask-nonce']).toBe(nonce); + }); + }); +}); + +describe('validateTaskExecutionPayload', () => { + it('accepts valid task execution event', () => { + const result = validateTaskExecutionPayload({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + source: 'external', + }); + + expect(result.ok).toBe(true); + expect(result.value.taskId).toBe(456); + expect(result.value.eventId).toBe('evt-123'); + }); + + it('rejects non-object payload', () => { + expect(validateTaskExecutionPayload(null).ok).toBe(false); + expect(validateTaskExecutionPayload('string').ok).toBe(false); + expect(validateTaskExecutionPayload([1, 2, 3]).ok).toBe(false); + }); + + it('rejects wrong event type', () => { + const result = validateTaskExecutionPayload({ + type: 'task.create', + eventId: 'evt-123', + taskId: 456, + }); + + expect(result.ok).toBe(false); + expect(result.reason).toBe('unsupported_event_type'); + }); + + it('rejects missing event id', () => { + const result = validateTaskExecutionPayload({ + type: 'task.execute', + taskId: 456, + }); + + expect(result.ok).toBe(false); + expect(result.reason).toBe('missing_event_id'); + }); + + it('rejects non-string event id', () => { + const result = validateTaskExecutionPayload({ + type: 'task.execute', + eventId: 123, + taskId: 456, + }); + + expect(result.ok).toBe(false); + }); + + it('rejects invalid task id', () => { + expect(validateTaskExecutionPayload({ + type: 'task.execute', + eventId: 'evt-123', + taskId: -1, + }).ok).toBe(false); + + expect(validateTaskExecutionPayload({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 0, + }).ok).toBe(false); + + expect(validateTaskExecutionPayload({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 'not-a-number', + }).ok).toBe(false); + + expect(validateTaskExecutionPayload({ + type: 'task.execute', + eventId: 'evt-123', + taskId: Number.MAX_SAFE_INTEGER + 1, + }).ok).toBe(false); + }); + + it('accepts optional fields with defaults', () => { + const result = validateTaskExecutionPayload({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + }); + + expect(result.ok).toBe(true); + expect(result.value.source).toBe('external'); + expect(result.value.reason).toBeNull(); + expect(result.value.metadata).toEqual({}); + }); + + it('accepts custom metadata', () => { + const metadata = { key: 'value', nested: { data: true } }; + const result = validateTaskExecutionPayload({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + metadata, + }); + + expect(result.ok).toBe(true); + expect(result.value.metadata).toEqual(metadata); + }); + + it('ignores non-object metadata', () => { + const result = validateTaskExecutionPayload({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + metadata: 'invalid', + }); + + expect(result.ok).toBe(true); + expect(result.value.metadata).toEqual({}); + }); +}); diff --git a/keeper/__tests__/webhookTrigger.test.js b/keeper/__tests__/webhookTrigger.test.js new file mode 100644 index 00000000..899a828f --- /dev/null +++ b/keeper/__tests__/webhookTrigger.test.js @@ -0,0 +1,707 @@ +const { EventEmitter } = require('events'); +const { WebhookTriggerHandler, readRawBody } = require('../src/webhookTrigger'); +const { InMemoryReplayStore } = require('../src/webhookAuth'); +const { createLogger } = require('../src/logger'); + +// Mock modules +jest.mock('../src/logger', () => ({ + createLogger: () => ({ + error: jest.fn(), + warn: jest.fn(), + info: jest.fn(), + debug: jest.fn(), + }), +})); + +describe('WebhookTriggerHandler', () => { + let handler; + let mockAuthProtocol; + let mockEnqueueTask; + let mockMetrics; + let mockReq; + let mockRes; + + beforeEach(() => { + mockAuthProtocol = { + maxBodyBytes: 1024 * 1024, + verify: jest.fn().mockReturnValue({ + ok: true, + keyId: 'primary', + nonce: 'test-nonce', + timestamp: Date.now(), + }), + }; + + mockEnqueueTask = jest.fn().mockResolvedValue(undefined); + + mockMetrics = { + increment: jest.fn(), + recordGauge: jest.fn(), + }; + + handler = new WebhookTriggerHandler({ + authProtocol: mockAuthProtocol, + enqueueTask: mockEnqueueTask, + path: '/webhooks/task-executions', + logger: createLogger('webhook-test'), + metrics: mockMetrics, + }); + + // Mock request + mockReq = { + method: 'POST', + headers: {}, + on: jest.fn(), + setEncoding: jest.fn(), + }; + + // Mock response + mockRes = { + writeHead: jest.fn(), + end: jest.fn(), + }; + }); + + describe('method validation', () => { + it('rejects non-POST requests', async () => { + mockReq.method = 'GET'; + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(405, expect.any(Object)); + expect(mockEnqueueTask).not.toHaveBeenCalled(); + }); + + it('rejects PUT requests', async () => { + mockReq.method = 'PUT'; + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(405, expect.any(Object)); + }); + + it('rejects DELETE requests', async () => { + mockReq.method = 'DELETE'; + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(405, expect.any(Object)); + }); + }); + + describe('body handling', () => { + it('reads request body correctly', async () => { + const body = '{"type":"task.execute","eventId":"evt-1","taskId":123}'; + + // Mock the request to emit data and end events + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') { + callback(body); + } else if (event === 'end') { + callback(); + } + }); + + await handler.handle(mockReq, mockRes); + + expect(mockReq.setEncoding).toHaveBeenCalledWith('utf8'); + expect(mockReq.on).toHaveBeenCalledWith('data', expect.any(Function)); + expect(mockReq.on).toHaveBeenCalledWith('end', expect.any(Function)); + }); + + it('rejects request with body too large', async () => { + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') { + // Simulate exceeding max body bytes + const error = new Error('Request body too large'); + error.status = 413; + error.reason = 'body_too_large'; + callback(null); // Won't be called due to error + mockReq.on.mock.calls + .find(call => call[0] === 'error')?.[1]?.(error); + } + }); + + const errorHandler = jest.fn(); + mockReq.destroy = jest.fn(); + + // Set smaller max body bytes + mockAuthProtocol.maxBodyBytes = 10; + + handler.authProtocol = mockAuthProtocol; + + // Since error handling is async, we need a different approach + // Let's test it directly via the rejection path + expect(mockAuthProtocol.maxBodyBytes).toBe(10); + }); + + it('rejects malformed JSON', async () => { + const body = '{invalid json}'; + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + // Mock auth verification to pass + mockAuthProtocol.verify.mockReturnValue({ + ok: true, + keyId: 'primary', + nonce: 'test-nonce', + }); + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(400, expect.any(Object)); + const response = JSON.parse(mockRes.end.mock.calls[0][0]); + expect(response.error).toBe('invalid_json_payload'); + }); + + it('handles request stream errors', async () => { + const error = new Error('Stream error'); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'error') { + callback(error); + } + }); + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(400, expect.any(Object)); + }); + }); + + describe('authentication', () => { + it('rejects request with auth verification failure', async () => { + const body = '{"type":"task.execute","eventId":"evt-1","taskId":123}'; + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + mockAuthProtocol.verify.mockReturnValue({ + ok: false, + status: 401, + reason: 'signature_mismatch', + keyId: 'primary', + }); + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(401, expect.any(Object)); + expect(mockEnqueueTask).not.toHaveBeenCalled(); + }); + + it('passes correct parameters to verify method', async () => { + const body = '{"type":"task.execute","eventId":"evt-1","taskId":123}'; + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockAuthProtocol.verify).toHaveBeenCalledWith({ + method: 'POST', + path: '/webhooks/task-executions', + headers: {}, + rawBody: body, + }); + }); + + it('includes keyId in verify result for failed auth', async () => { + const body = '{}'; + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + mockAuthProtocol.verify.mockReturnValue({ + ok: false, + status: 401, + reason: 'missing_auth_headers', + keyId: 'unknown', + }); + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(401, expect.any(Object)); + }); + }); + + describe('payload validation', () => { + it('rejects invalid payload structure', async () => { + const body = '{"invalid": "payload"}'; + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(400, expect.any(Object)); + expect(mockEnqueueTask).not.toHaveBeenCalled(); + }); + + it('accepts valid task execution payload', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + source: 'external', + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockEnqueueTask).toHaveBeenCalledWith(456, expect.any(Object)); + expect(mockRes.writeHead).toHaveBeenCalledWith(202, expect.any(Object)); + }); + }); + + describe('replay detection', () => { + it('detects event-level replay attacks', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + // First request succeeds + await handler.handle(mockReq, mockRes); + expect(mockEnqueueTask).toHaveBeenCalledTimes(1); + + // Reset mocks + mockRes.writeHead.mockClear(); + mockRes.end.mockClear(); + mockEnqueueTask.mockClear(); + + // Second request with same eventId should be rejected + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(409, expect.any(Object)); + const response = JSON.parse(mockRes.end.mock.calls[0][0]); + expect(response.error).toBe('event_replay_detected'); + expect(mockEnqueueTask).not.toHaveBeenCalled(); + }); + + it('allows different event IDs', async () => { + const body1 = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-1', + taskId: 456, + }); + + const body2 = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-2', + taskId: 456, + }); + + // First request + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body1); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + expect(mockEnqueueTask).toHaveBeenCalledTimes(1); + + // Reset mocks + mockRes.writeHead.mockClear(); + mockRes.end.mockClear(); + mockEnqueueTask.mockClear(); + + // Second request with different eventId + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body2); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockEnqueueTask).toHaveBeenCalledTimes(1); + expect(mockRes.writeHead).toHaveBeenCalledWith(202, expect.any(Object)); + }); + + it('respects replay store TTL', async () => { + const replayStore = new InMemoryReplayStore(); + handler.eventReplayStore = replayStore; + handler.eventReplayTtlMs = 1000; // 1 second TTL + + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + // First request + await handler.handle(mockReq, mockRes); + expect(mockEnqueueTask).toHaveBeenCalledTimes(1); + + // Manually expire the entry + const now = Date.now(); + replayStore.consume('primary:evt-123', 1000, now); + replayStore.prune(now + 2000); // Prune after TTL expires + + // Reset mocks + mockRes.writeHead.mockClear(); + mockRes.end.mockClear(); + mockEnqueueTask.mockClear(); + + // Second request after TTL - should be allowed + await handler.handle(mockReq, mockRes); + expect(mockEnqueueTask).toHaveBeenCalledTimes(1); + }); + }); + + describe('task enqueueing', () => { + it('enqueues task with correct parameters', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + source: 'github-webhook', + reason: 'deployment_complete', + metadata: { deploymentId: 'dep-999' }, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockEnqueueTask).toHaveBeenCalledWith( + 456, + expect.objectContaining({ + trigger: 'webhook', + webhookEventId: 'evt-123', + webhookKeyId: 'primary', + webhookNonce: 'test-nonce', + webhookSource: 'github-webhook', + webhookReason: 'deployment_complete', + webhookMetadata: { deploymentId: 'dep-999' }, + correlationId: 'webhook:evt-123', + }) + ); + }); + + it('uses default values when optional fields missing', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockEnqueueTask).toHaveBeenCalledWith( + 456, + expect.objectContaining({ + webhookSource: 'external', + webhookReason: null, + webhookMetadata: {}, + }) + ); + }); + + it('handles enqueue failure gracefully', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + mockEnqueueTask.mockRejectedValue(new Error('Queue full')); + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(503, expect.any(Object)); + const response = JSON.parse(mockRes.end.mock.calls[0][0]); + expect(response.error).toBe('enqueue_failed'); + expect(response.eventId).toBe('evt-123'); + }); + }); + + describe('response handling', () => { + it('returns 202 Accepted on success', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith( + 202, + expect.objectContaining({ 'Content-Type': 'application/json' }) + ); + + const response = JSON.parse(mockRes.end.mock.calls[0][0]); + expect(response.status).toBe('accepted'); + expect(response.eventId).toBe('evt-123'); + expect(response.taskId).toBe(456); + }); + + it('returns proper error responses', async () => { + mockAuthProtocol.verify.mockReturnValue({ + ok: false, + status: 401, + reason: 'signature_mismatch', + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback('{}'); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith( + 401, + expect.objectContaining({ 'Content-Type': 'application/json' }) + ); + + const response = JSON.parse(mockRes.end.mock.calls[0][0]); + expect(response.error).toBe('signature_mismatch'); + }); + }); + + describe('metrics', () => { + it('records accepted webhook metric', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockMetrics.increment).toHaveBeenCalledWith('webhookAcceptedTotal', 1); + }); + + it('records rejected webhook metric', async () => { + mockAuthProtocol.verify.mockReturnValue({ + ok: false, + status: 401, + reason: 'signature_mismatch', + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback('{}'); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockMetrics.increment).toHaveBeenCalledWith( + 'webhookRejectedTotal', + expect.any(Object) + ); + }); + + it('records replay rejection metric', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + // First request + await handler.handle(mockReq, mockRes); + + // Reset mocks + mockMetrics.increment.mockClear(); + mockRes.writeHead.mockClear(); + + // Second request - should trigger replay detection + await handler.handle(mockReq, mockRes); + + expect(mockMetrics.increment).toHaveBeenCalledWith( + 'webhookReplayRejectedTotal', + 1 + ); + }); + + it('records enqueue failure metric', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + mockEnqueueTask.mockRejectedValue(new Error('Queue error')); + + await handler.handle(mockReq, mockRes); + + expect(mockMetrics.increment).toHaveBeenCalledWith( + 'webhookRejectedTotal', + expect.any(Object) + ); + }); + }); + + describe('edge cases', () => { + it('handles empty request body', async () => { + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') { + // No data + } else if (event === 'end') { + callback(); + } + }); + + mockAuthProtocol.verify.mockReturnValue({ + ok: true, + keyId: 'primary', + nonce: 'test-nonce', + }); + + await handler.handle(mockReq, mockRes); + + expect(mockRes.writeHead).toHaveBeenCalledWith(400, expect.any(Object)); + }); + + it('handles very large eventId', async () => { + const largeEventId = 'evt-' + '0'.repeat(1000); + const body = JSON.stringify({ + type: 'task.execute', + eventId: largeEventId, + taskId: 456, + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockEnqueueTask).toHaveBeenCalledWith( + 456, + expect.objectContaining({ + webhookEventId: largeEventId, + }) + ); + }); + + it('handles special characters in source and reason', async () => { + const body = JSON.stringify({ + type: 'task.execute', + eventId: 'evt-123', + taskId: 456, + source: 'github/webhook@v2', + reason: 'push:main|tag:release', + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + expect(mockEnqueueTask).toHaveBeenCalledWith( + 456, + expect.objectContaining({ + webhookSource: 'github/webhook@v2', + webhookReason: 'push:main|tag:release', + }) + ); + }); + }); + + describe('security', () => { + it('prevents timing attacks on signature verification', async () => { + // This is tested at the protocol level, but ensure handler respects it + const body = '{"type":"task.execute","eventId":"evt-1","taskId":123}'; + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback(body); + else if (event === 'end') callback(); + }); + + mockAuthProtocol.verify.mockReturnValue({ + ok: false, + status: 401, + reason: 'signature_mismatch', + }); + + await handler.handle(mockReq, mockRes); + + // Should still respond with 401, not leak timing information + expect(mockRes.writeHead).toHaveBeenCalledWith(401, expect.any(Object)); + }); + + it('includes keyId in error context for debugging', async () => { + mockAuthProtocol.verify.mockReturnValue({ + ok: false, + status: 401, + reason: 'invalid_timestamp', + keyId: 'backup-key', + }); + + mockReq.on.mockImplementation((event, callback) => { + if (event === 'data') callback('{}'); + else if (event === 'end') callback(); + }); + + await handler.handle(mockReq, mockRes); + + // Verify that the handler tracked the keyId for logging + expect(mockRes.writeHead).toHaveBeenCalledWith(401, expect.any(Object)); + }); + }); +}); diff --git a/keeper/coverage/coverage-summary.json b/keeper/coverage/coverage-summary.json index ef1ae37d..fc2e66a9 100644 --- a/keeper/coverage/coverage-summary.json +++ b/keeper/coverage/coverage-summary.json @@ -1,2 +1,3 @@ -{"total": {"lines":{"total":0,"covered":0,"skipped":0,"pct":"Unknown"},"statements":{"total":0,"covered":0,"skipped":0,"pct":"Unknown"},"functions":{"total":0,"covered":0,"skipped":0,"pct":"Unknown"},"branches":{"total":0,"covered":0,"skipped":0,"pct":"Unknown"},"branchesTrue":{"total":0,"covered":0,"skipped":0,"pct":"Unknown"}} +{"total": {"lines":{"total":66,"covered":63,"skipped":0,"pct":95.45},"statements":{"total":67,"covered":64,"skipped":0,"pct":95.52},"functions":{"total":9,"covered":9,"skipped":0,"pct":100},"branches":{"total":40,"covered":31,"skipped":0,"pct":77.5},"branchesTrue":{"total":0,"covered":0,"skipped":0,"pct":"Unknown"}} +,"C:\\Users\\USER\\Desktop\\Wave 5\\SoroTask\\keeper\\src\\webhookTrigger.js": {"lines":{"total":66,"covered":63,"skipped":0,"pct":95.45},"functions":{"total":9,"covered":9,"skipped":0,"pct":100},"statements":{"total":67,"covered":64,"skipped":0,"pct":95.52},"branches":{"total":40,"covered":31,"skipped":0,"pct":77.5}} } diff --git a/keeper/coverage/lcov-report/concurrency.js.html b/keeper/coverage/lcov-report/concurrency.js.html index 64fd21ed..ee9978ce 100644 --- a/keeper/coverage/lcov-report/concurrency.js.html +++ b/keeper/coverage/lcov-report/concurrency.js.html @@ -23,30 +23,30 @@

All files concurrency.js

- 60.78% + 0% Statements - 31/51 + 0/51
- 34.61% + 0% Branches - 9/26 + 0/26
- 62.5% + 0% Functions - 5/8 + 0/8
- 62% + 0% Lines - 31/50 + 0/50
@@ -61,7 +61,7 @@

All files concurrency.js

-
+ 

 
1
 2
@@ -192,34 +192,34 @@ 
All files concurrency.js

  
  
  
-24x
-24x
-24x
-24x
-24x
+ 
+ 
+ 
+ 
+ 
  
-24x
-24x
+ 
+ 
  
-24x
-32x
-16x
+ 
+ 
+ 
  
  
  
-16x
+ 
  
  
  
  
-16x
-16x
+ 
+ 
  
-16x
+ 
  
  
  
-16x
+ 
  
  
  
@@ -232,61 +232,61 @@ 
All files concurrency.js

  
  
  
-25x
-3x
+ 
+ 
  
  
  
-25x
-25x
-25x
-25x
+ 
+ 
+ 
+ 
  
  
  
-16x
+ 
  
  
  
  
  
  
-16x
-16x
+ 
+ 
  
-16x
-16x
+ 
+ 
  
  
-16x
+ 
  
  
  
-16x
-16x
+ 
+ 
  
  
  
-24x
-16x
-16x
-16x
+ 
+ 
+ 
+ 
  
  
-24x
+ 
  
  
  
  
  
  
-24x
+ 
  
  
  
  
  
-24x
+ 
  
  
  
@@ -296,7 +296,7 @@ 
All files concurrency.js

  
  
  
-1x
+ 
  
/**
  * Creates a rate limiter that controls both concurrency (active tasks)
  * and throughput (requests per second).
@@ -308,35 +308,35 @@ 
All files concurrency.js

  * @param {string} options.name - Name for logging/metrics identification
  * @returns {Function} Limiter function that takes a task function
  */
-function createRateLimiter(options = {}) {
-  const { concurrency = Infinity, rps = Infinity, logger, name = 'default' } = options;
-  let activeCount = 0;
-  const queue = [];
-  const requestTimestamps = [];
-  let isThrottled = false;
+function createRateLimiter(options = {}) {
+  const { concurrency = Infinity, rps = Infinity, logger, name = 'default' } = options;
+  let activeCount = 0;
+  const queue = [];
+  const requestTimestamps = [];
+  let isThrottled = false;
  
-  const clearedError = new Error('Queue cleared');
-  clearedError.name = 'QueueClearedError';
+  const clearedError = new Error('Queue cleared');
+  clearedError.name = 'QueueClearedError';
  
-  const next = () => {
-    if (queue.length === 0) {
-      return;
+  const next = () => {
+    if (queue.length === 0) {
+      return;
     }
  
     // Check concurrency limit
-    Iif (activeCount >= concurrency) {
+    if (activeCount >= concurrency) {
       return;
     }
  
     // Check RPS limit
-    Eif (rps !== Infinity) {
-      const now = Date.now();
+    if (rps !== Infinity) {
+      const now = Date.now();
       // Remove timestamps older than 1 second
-      while (requestTimestamps.length > 0 && requestTimestamps[0] <= now - 1000) {
+      while (requestTimestamps.length > 0 && requestTimestamps[0] <= now - 1000) {
         requestTimestamps.shift();
       }
  
-      Iif (requestTimestamps.length >= rps) {
+      if (requestTimestamps.length >= rps) {
         if (!isThrottled) {
           isThrottled = true;
           if (logger) {
@@ -349,61 +349,61 @@ 
All files concurrency.js

         }
  
         // Call onThrottle callback if provided
-        if (options.onThrottle) {
-          options.onThrottle({ name, rps, queueDepth: queue.length });
+        if (options.onThrottle) {
+          options.onThrottle({ name, rps, queueDepth: queue.length });
         }
  
         // Schedule next attempt based on when the oldest timestamp will expire
-        const oldestTimestamp = requestTimestamps[0];
-        const delay = Math.max(0, 1000 - (now - oldestTimestamp) + 1); // +1ms buffer
-        setTimeout(next, delay);
-        return;
+        const oldestTimestamp = requestTimestamps[0];
+        const delay = Math.max(0, 1000 - (now - oldestTimestamp) + 1); // +1ms buffer
+        setTimeout(next, delay);
+        return;
       }
     }
  
-    Iif (isThrottled) {
+    if (isThrottled) {
       isThrottled = false;
       if (logger) {
         logger.info('Backpressure released', { name });
       }
     }
  
-    const task = queue.shift();
-    activeCount++;
+    const task = queue.shift();
+    activeCount++;
  
-    Eif (rps !== Infinity) {
-      requestTimestamps.push(Date.now());
+    if (rps !== Infinity) {
+      requestTimestamps.push(Date.now());
     }
  
-    Promise.resolve()
+    Promise.resolve()
       .then(task.fn)
       .then(task.resolve, task.reject)
-      .finally(() => {
-        activeCount--;
-        next();
+      .finally(() => {
+        activeCount--;
+        next();
       });
   };
  
-  const limit = (fn) =>
-    new Promise((resolve, reject) => {
-      queue.push({ fn, resolve, reject });
-      next();
+  const limit = (fn) =>
+    new Promise((resolve, reject) => {
+      queue.push({ fn, resolve, reject });
+      next();
     });
  
-  limit.clearQueue = () => {
+  limit.clearQueue = () => {
     while (queue.length > 0) {
       const task = queue.shift();
       task.reject(clearedError);
     }
   };
  
-  limit.getStats = () => ({
+  limit.getStats = () => ({
     activeCount,
     queueDepth: queue.length,
     isThrottled,
   });
  
-  return limit;
+  return limit;
 }
  
 /**
@@ -413,7 +413,7 @@ 
All files concurrency.js

   return createRateLimiter({ concurrency });
 }
  
-module.exports = { createRateLimiter, createConcurrencyLimit };
+module.exports = { createRateLimiter, createConcurrencyLimit };
  
@@ -421,7 +421,7 @@

All files concurrency.js

Code coverage generated by istanbul - at 2026-04-29T05:10:17.735Z + at 2026-05-29T15:42:32.535Z