hookarmor 1.0.3 → 1.1.1

package/src/dispatcher.js

@@ -1,356 +1,429 @@
-const http = require('http');
-const https = require('https');
-const crypto = require('crypto');
-const EventEmitter = require('events');
-const Alerter = require('./alerter');
-
-class Dispatcher extends EventEmitter {
-  constructor(storage, options = {}) {
-    super();
-    this.storage = storage;
-    this.defaultConcurrency = options.defaultConcurrency || 5;
-    this.inFlightCount = new Map();
-    this.waitQueues = new Map();
-    this.defaultTimeoutMs = options.defaultTimeoutMs || 25000;
-  }
-
-  // Verify signature at ingress (preventing HookArmor from acting as an open signature oracle)
-  static verifyIngressSignature(provider, rawBody, headers, secret, toleranceSec = 300) {
-    if (!secret) return { valid: true };
-
-    try {
-      if (provider === 'stripe') {
-        const sigHeader = headers['stripe-signature'];
-        if (!sigHeader) return { valid: false, reason: 'Missing Stripe-Signature header' };
-
-        const parts = sigHeader.split(',').reduce((acc, item) => {
-          const [k, v] = item.split('=');
-          if (k && v) acc[k.trim()] = v.trim();
-          return acc;
-        }, {});
-
-        if (!parts.t || !parts.v1) return { valid: false, reason: 'Malformed Stripe-Signature header' };
-
-        const timestamp = parseInt(parts.t, 10);
-        const now = Math.floor(Date.now() / 1000);
-        if (Math.abs(now - timestamp) > toleranceSec) {
-          return { valid: false, reason: `Timestamp outside tolerance (${Math.abs(now - timestamp)}s > ${toleranceSec}s)` };
-        }
-
-        const expectedSig = crypto
-          .createHmac('sha256', secret)
-          .update(`${parts.t}.${rawBody}`)
-          .digest('hex');
-
-        const expectedBuf = Buffer.from(expectedSig);
-        const actualBuf = Buffer.from(parts.v1);
-        if (expectedBuf.length !== actualBuf.length || !crypto.timingSafeEqual(expectedBuf, actualBuf)) {
-          return { valid: false, reason: 'Signature mismatch' };
-        }
-        return { valid: true };
-      }
-
-      if (provider === 'shopify') {
-        const hmac = headers['x-shopify-hmac-sha256'];
-        if (!hmac) return { valid: false, reason: 'Missing X-Shopify-Hmac-Sha256 header' };
-
-        const expectedSig = crypto
-          .createHmac('sha256', secret)
-          .update(rawBody)
-          .digest('base64');
-
-        const expectedBuf = Buffer.from(expectedSig);
-        const actualBuf = Buffer.from(hmac);
-        if (expectedBuf.length !== actualBuf.length || !crypto.timingSafeEqual(expectedBuf, actualBuf)) {
-          return { valid: false, reason: 'Shopify HMAC mismatch' };
-        }
-        return { valid: true };
-      }
-
-      if (provider === 'github') {
-        const sig = headers['x-hub-signature-256'];
-        if (!sig) return { valid: false, reason: 'Missing X-Hub-Signature-256 header' };
-
-        const expectedSig = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
-        const expectedBuf = Buffer.from(expectedSig);
-        const actualBuf = Buffer.from(sig);
-        if (expectedBuf.length !== actualBuf.length || !crypto.timingSafeEqual(expectedBuf, actualBuf)) {
-          return { valid: false, reason: 'GitHub signature mismatch' };
-        }
-        return { valid: true };
-      }
-
-      return { valid: true };
-    } catch (err) {
-      return { valid: false, reason: err.message };
-    }
-  }
-
-  // Fresh re-signing on forward/replay to defeat the 5-minute Stripe expiration trap
-  signHeaders(provider, rawBody, headers, secret) {
-    if (!secret) return headers;
-
-    const modified = { ...headers };
-    try {
-      if (provider === 'stripe') {
-        const freshTimestamp = Math.floor(Date.now() / 1000);
-        const freshSignature = crypto
-          .createHmac('sha256', secret)
-          .update(`${freshTimestamp}.${rawBody}`)
-          .digest('hex');
-        modified['stripe-signature'] = `t=${freshTimestamp},v1=${freshSignature}`;
-      } else if (provider === 'shopify') {
-        const freshHmac = crypto
-          .createHmac('sha256', secret)
-          .update(rawBody)
-          .digest('base64');
-        modified['x-shopify-hmac-sha256'] = freshHmac;
-      } else if (provider === 'github') {
-        const freshSig = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
-        modified['x-hub-signature-256'] = freshSig;
-      }
-    } catch (e) {}
-
-    return modified;
-  }
-
-  async acquireSlot(endpointId, limit) {
-    const current = this.inFlightCount.get(endpointId) || 0;
-    if (current < limit) {
-      this.inFlightCount.set(endpointId, current + 1);
-      return;
-    }
-
-    return new Promise(resolve => {
-      if (!this.waitQueues.has(endpointId)) this.waitQueues.set(endpointId, []);
-      this.waitQueues.get(endpointId).push(resolve);
-    });
-  }
-
-  releaseSlot(endpointId, limit) {
-    const queue = this.waitQueues.get(endpointId);
-    if (queue && queue.length > 0) {
-      const next = queue.shift();
-      next();
-    } else {
-      const current = this.inFlightCount.get(endpointId) || 1;
-      this.inFlightCount.set(endpointId, Math.max(0, current - 1));
-    }
-  }
-
-  // Calculate exponential backoff with jitter: 30s, 2m, 10m, 30m, 2h
-  calculateNextRetry(attempt) {
-    const intervals = [30, 120, 600, 1800, 7200]; // seconds
-    const base = intervals[Math.min(attempt, intervals.length - 1)];
-    const jitter = Math.floor(Math.random() * (base * 0.2));
-    const delaySec = base + jitter;
-    return new Date(Date.now() + delaySec * 1000).toISOString();
-  }
-
-  async dispatch(event, endpoint) {
-    const limit = endpoint.concurrency_limit || this.defaultConcurrency;
-    await this.acquireSlot(endpoint.id, limit);
-
-    try {
-      return await this._executeDispatch(event, endpoint);
-    } finally {
-      this.releaseSlot(endpoint.id, limit);
-    }
-  }
-
-  async _executeDispatch(event, endpoint) {
-    const startTime = Date.now();
-    const targetUrl = endpoint.target_url;
-
-    let headers = { ...event.headers };
-
-    // Preserve original raw signatures before re-signing for audit and forensic trace
-    if (event.headers && event.headers['stripe-signature']) {
-      headers['x-hookarmor-original-stripe-signature'] = event.headers['stripe-signature'];
-    }
-    if (event.headers && event.headers['x-shopify-hmac-sha256']) {
-      headers['x-hookarmor-original-shopify-hmac'] = event.headers['x-shopify-hmac-sha256'];
-    }
-
-    // Re-sign outbound headers if endpoint secret is configured (Transparent Zero-Code-Change Mode)
-    if (endpoint.secret) {
-      headers = this.signHeaders(event.provider, event.raw_body, headers, endpoint.secret);
-    }
-
-    // Optional Isolated Trust Domain mode: if HOOKARMOR_SIGNING_SECRET is provided
-    const internalSecret = process.env.HOOKARMOR_SIGNING_SECRET || endpoint.internal_secret;
-    if (internalSecret) {
-      const freshTs = Math.floor(Date.now() / 1000);
-      const internalSig = crypto.createHmac('sha256', internalSecret).update(`${freshTs}.${event.raw_body}`).digest('hex');
-      headers['x-hookarmor-signature'] = `t=${freshTs},v1=${internalSig}`;
-    }
-
-    // Remove hop-by-hop and encoding headers
-    delete headers['host'];
-    delete headers['connection'];
-    delete headers['content-length'];
-    delete headers['content-encoding'];
-    delete headers['transfer-encoding'];
-
-    const rawBuffer = Buffer.from(event.raw_body, 'utf8');
-    headers['content-length'] = rawBuffer.length;
-    headers['x-hookarmor-delivery-id'] = event.id;
-    headers['x-hookarmor-attempt'] = String(event.attempts + 1);
-    headers['x-hookarmor-original-timestamp'] = event.created_at;
-    const isReplay = (event.attempts > 0 || event.status === 'replaying');
-    headers['x-hookarmor-is-replay'] = isReplay ? 'true' : 'false';
-
-    return new Promise((resolve) => {
-      try {
-        const url = new URL(targetUrl);
-        const isHttps = url.protocol === 'https:';
-        const client = isHttps ? https : http;
-
-        const req = client.request(url, {
-          method: 'POST',
-          headers,
-          timeout: this.defaultTimeoutMs
-        }, (res) => {
-          let responseBody = '';
-          res.setEncoding('utf8');
-          res.on('data', chunk => {
-            if (responseBody.length < 4000) {
-              responseBody += chunk;
-            }
-          });
-
-          res.on('end', async () => {
-            const latencyMs = Date.now() - startTime;
-            const statusCode = res.statusCode || 0;
-            const isSuccess = statusCode >= 200 && statusCode < 300;
-
-            let nextRetryAt = null;
-            if (!isSuccess && endpoint.auto_retry && (event.attempts + 1) < endpoint.max_retries) {
-              nextRetryAt = this.calculateNextRetry(event.attempts);
-            }
-
-            const updatedEvent = this.storage.recordAttempt({
-              eventId: event.id,
-              statusCode,
-              responseBody,
-              errorMessage: isSuccess ? '' : `Destination returned HTTP ${statusCode}`,
-              latencyMs,
-              nextRetryAt
-            });
-
-            const result = {
-              eventId: event.id,
-              endpointId: endpoint.id,
-              success: isSuccess,
-              statusCode,
-              latencyMs,
-              responseBody,
-              nextRetryAt
-            };
-
-            this.emit('delivery', result);
-
-            if (!isSuccess) {
-              await Alerter.sendAlert(endpoint.alert_webhook_url, {
-                event,
-                endpoint,
-                attempt: { statusCode, errorMessage: `HTTP ${statusCode}`, latencyMs }
-              });
-            }
-
-            resolve(result);
-          });
-        });
-
-        req.on('timeout', async () => {
-          req.destroy(new Error(`Connection timed out after ${this.defaultTimeoutMs}ms`));
-        });
-
-        req.on('error', async (err) => {
-          const latencyMs = Date.now() - startTime;
-          let nextRetryAt = null;
-          if (endpoint.auto_retry && (event.attempts + 1) < endpoint.max_retries) {
-            nextRetryAt = this.calculateNextRetry(event.attempts);
-          }
-
-          const updatedEvent = this.storage.recordAttempt({
-            eventId: event.id,
-            statusCode: 0,
-            responseBody: '',
-            errorMessage: err.message,
-            latencyMs,
-            nextRetryAt
-          });
-
-          const result = {
-            eventId: event.id,
-            endpointId: endpoint.id,
-            success: false,
-            statusCode: 0,
-            latencyMs,
-            errorMessage: err.message,
-            nextRetryAt
-          };
-
-          this.emit('delivery', result);
-
-          await Alerter.sendAlert(endpoint.alert_webhook_url, {
-            event,
-            endpoint,
-            attempt: { statusCode: 0, errorMessage: err.message, latencyMs }
-          });
-
-          resolve(result);
-        });
-
-        req.write(rawBuffer);
-        req.end();
-      } catch (err) {
-        const latencyMs = Date.now() - startTime;
-        this.storage.recordAttempt({
-          eventId: event.id,
-          statusCode: 0,
-          responseBody: '',
-          errorMessage: err.message,
-          latencyMs
-        });
-
-        const result = {
-          eventId: event.id,
-          endpointId: endpoint.id,
-          success: false,
-          statusCode: 0,
-          latencyMs,
-          errorMessage: err.message
-        };
-
-        this.emit('delivery', result);
-        resolve(result);
-      }
-    });
-  }
-
-  async replayEvent(eventId) {
-    const event = this.storage.getEvent(eventId);
-    if (!event) throw new Error(`Event not found: ${eventId}`);
-    const endpoint = this.storage.getEndpoint(event.endpoint_id);
-    if (!endpoint) throw new Error(`Endpoint not found: ${event.endpoint_id}`);
-
-    return this.dispatch(event, endpoint);
-  }
-
-  async replayAllFailed(endpointId = null) {
-    const failedEvents = this.storage.getFailedEventsToRetry(endpointId);
-    const results = [];
-    for (const event of failedEvents) {
-      const endpoint = this.storage.getEndpoint(event.endpoint_id);
-      if (endpoint) {
-        const res = await this.dispatch(event, endpoint);
-        results.push(res);
-      }
-    }
-    return results;
-  }
-}
-
-module.exports = Dispatcher;
+const http = require('http');
+const https = require('https');
+const crypto = require('crypto');
+const EventEmitter = require('events');
+const Alerter = require('./alerter');
+const { checkUrl, guardedLookup } = require('./netguard');
+
+function safeEqual(a, b) {
+  const bufA = Buffer.from(String(a));
+  const bufB = Buffer.from(String(b));
+  return bufA.length === bufB.length && crypto.timingSafeEqual(bufA, bufB);
+}
+
+// Svix (used by Clerk) secrets are "whsec_" + base64 key bytes
+function svixKey(secret) {
+  return Buffer.from(String(secret).replace(/^whsec_/, ''), 'base64');
+}
+
+function svixSignature(secret, msgId, timestamp, rawBody) {
+  const hmac = crypto.createHmac('sha256', svixKey(secret));
+  hmac.update(Buffer.from(`${msgId}.${timestamp}.`, 'utf8'));
+  hmac.update(Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody || ''), 'utf8'));
+  return hmac.digest('base64');
+}
+
+class Dispatcher extends EventEmitter {
+  constructor(storage, options = {}) {
+    super();
+    this.storage = storage;
+    this.defaultConcurrency = options.defaultConcurrency || 5;
+    this.inFlightCount = new Map();
+    this.waitQueues = new Map();
+    this.defaultTimeoutMs = options.defaultTimeoutMs || 25000;
+    this.strictSSRF = Boolean(options.strictSSRF);
+    this.signingSecret = options.signingSecret || null;
+  }
+
+  // Verify signature at ingress (preventing HookArmor from acting as an open signature oracle).
+  // When a secret is configured, events without a supported signature scheme are rejected.
+  static verifyIngressSignature(provider, rawBody, headers, secret, toleranceSec = 300) {
+    if (!secret) return { valid: true };
+
+    try {
+      if (provider === 'stripe') {
+        const sigHeader = headers['stripe-signature'];
+        if (!sigHeader) return { valid: false, reason: 'Missing Stripe-Signature header' };
+
+        // Stripe may send several v1 signatures (e.g. while a secret is being rolled)
+        let timestampStr = null;
+        const signatures = [];
+        for (const item of sigHeader.split(',')) {
+          const idx = item.indexOf('=');
+          if (idx === -1) continue;
+          const k = item.slice(0, idx).trim();
+          const v = item.slice(idx + 1).trim();
+          if (k === 't') timestampStr = v;
+          if (k === 'v1' && v) signatures.push(v);
+        }
+
+        if (!timestampStr || signatures.length === 0) return { valid: false, reason: 'Malformed Stripe-Signature header' };
+
+        const timestamp = parseInt(timestampStr, 10);
+        const now = Math.floor(Date.now() / 1000);
+        if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > toleranceSec) {
+          return { valid: false, reason: `Timestamp outside tolerance (${toleranceSec}s)` };
+        }
+
+        const hmac = crypto.createHmac('sha256', secret);
+        hmac.update(Buffer.from(`${timestampStr}.`, 'utf8'));
+        hmac.update(Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody || ''), 'utf8'));
+        const expectedSig = hmac.digest('hex');
+
+        if (!signatures.some((sig) => safeEqual(expectedSig, sig))) {
+          return { valid: false, reason: 'Signature mismatch' };
+        }
+        return { valid: true };
+      }
+
+      if (provider === 'shopify') {
+        const hmac = headers['x-shopify-hmac-sha256'];
+        if (!hmac) return { valid: false, reason: 'Missing X-Shopify-Hmac-Sha256 header' };
+
+        const expectedSig = crypto
+          .createHmac('sha256', secret)
+          .update(Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody || ''), 'utf8'))
+          .digest('base64');
+
+        if (!safeEqual(expectedSig, hmac)) {
+          return { valid: false, reason: 'Shopify HMAC mismatch' };
+        }
+        return { valid: true };
+      }
+
+      if (provider === 'github') {
+        const sig = headers['x-hub-signature-256'];
+        if (!sig) return { valid: false, reason: 'Missing X-Hub-Signature-256 header' };
+
+        const expectedSig = 'sha256=' + crypto
+          .createHmac('sha256', secret)
+          .update(Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody || ''), 'utf8'))
+          .digest('hex');
+        if (!safeEqual(expectedSig, sig)) {
+          return { valid: false, reason: 'GitHub signature mismatch' };
+        }
+        return { valid: true };
+      }
+
+      if (provider === 'clerk/svix') {
+        const msgId = headers['svix-id'];
+        const timestampStr = headers['svix-timestamp'];
+        const sigHeader = headers['svix-signature'];
+        if (!msgId || !timestampStr || !sigHeader) {
+          return { valid: false, reason: 'Missing svix-id, svix-timestamp or svix-signature header' };
+        }
+
+        const timestamp = parseInt(timestampStr, 10);
+        const now = Math.floor(Date.now() / 1000);
+        if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > toleranceSec) {
+          return { valid: false, reason: `Timestamp outside tolerance (${toleranceSec}s)` };
+        }
+
+        const expectedSig = svixSignature(secret, msgId, timestampStr, rawBody);
+        // Header is a space-separated list of "v1,<base64>" entries
+        const matches = sigHeader.split(' ').some((entry) => {
+          const [version, sig] = entry.split(',');
+          return version === 'v1' && sig && safeEqual(expectedSig, sig);
+        });
+        if (!matches) return { valid: false, reason: 'Svix signature mismatch' };
+        return { valid: true };
+      }
+
+      return { valid: false, reason: 'Endpoint has a secret but the request carries no supported signature (Stripe, Shopify, GitHub, Svix/Clerk)' };
+    } catch (err) {
+      return { valid: false, reason: err.message };
+    }
+  }
+
+  // Fresh re-signing on forward/replay to defeat the 5-minute Stripe expiration trap
+  signHeaders(provider, rawBody, headers, secret) {
+    if (!secret) return headers;
+
+    const modified = { ...headers };
+    try {
+      if (provider === 'stripe') {
+        const freshTimestamp = Math.floor(Date.now() / 1000);
+        const hmac = crypto.createHmac('sha256', secret);
+        hmac.update(Buffer.from(`${freshTimestamp}.`, 'utf8'));
+        hmac.update(Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody || ''), 'utf8'));
+        const freshSignature = hmac.digest('hex');
+        modified['stripe-signature'] = `t=${freshTimestamp},v1=${freshSignature}`;
+      } else if (provider === 'shopify') {
+        const freshHmac = crypto
+          .createHmac('sha256', secret)
+          .update(Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody || ''), 'utf8'))
+          .digest('base64');
+        modified['x-shopify-hmac-sha256'] = freshHmac;
+      } else if (provider === 'github') {
+        const freshSig = 'sha256=' + crypto
+          .createHmac('sha256', secret)
+          .update(Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody || ''), 'utf8'))
+          .digest('hex');
+        modified['x-hub-signature-256'] = freshSig;
+      } else if (provider === 'clerk/svix' && modified['svix-id']) {
+        const freshTimestamp = String(Math.floor(Date.now() / 1000));
+        modified['svix-timestamp'] = freshTimestamp;
+        modified['svix-signature'] = `v1,${svixSignature(secret, modified['svix-id'], freshTimestamp, rawBody)}`;
+      }
+    } catch (e) {}
+
+    return modified;
+  }
+
+  async acquireSlot(endpointId, limit) {
+    const current = this.inFlightCount.get(endpointId) || 0;
+    if (current < limit) {
+      this.inFlightCount.set(endpointId, current + 1);
+      return;
+    }
+
+    return new Promise(resolve => {
+      if (!this.waitQueues.has(endpointId)) this.waitQueues.set(endpointId, []);
+      this.waitQueues.get(endpointId).push(resolve);
+    });
+  }
+
+  releaseSlot(endpointId, limit) {
+    const queue = this.waitQueues.get(endpointId);
+    if (queue && queue.length > 0) {
+      const next = queue.shift();
+      next();
+    } else {
+      const current = this.inFlightCount.get(endpointId) || 1;
+      this.inFlightCount.set(endpointId, Math.max(0, current - 1));
+    }
+  }
+
+  // Calculate exponential backoff with jitter: 30s, 2m, 10m, 30m, 2h
+  calculateNextRetry(attempt) {
+    const intervals = [30, 120, 600, 1800, 7200]; // seconds
+    const base = intervals[Math.min(attempt, intervals.length - 1)];
+    const jitter = Math.floor(Math.random() * (base * 0.2));
+    const delaySec = base + jitter;
+    // SQLite datetime format, so the worker's comparison against datetime('now') is correct
+    return new Date(Date.now() + delaySec * 1000).toISOString().slice(0, 19).replace('T', ' ');
+  }
+
+  // Callers must have claimed the event (status 'replaying') before dispatching
+  async dispatch(event, endpoint, { replay = false } = {}) {
+    const limit = endpoint.concurrency_limit || this.defaultConcurrency;
+    await this.acquireSlot(endpoint.id, limit);
+
+    try {
+      return await this._executeDispatch(event, endpoint, replay);
+    } finally {
+      this.releaseSlot(endpoint.id, limit);
+    }
+  }
+
+  async _executeDispatch(event, endpoint, replay = false) {
+    const startTime = Date.now();
+    const targetUrl = endpoint.target_url;
+
+    let headers = { ...event.headers };
+
+    // Never forward sender-supplied HookArmor headers; ours are added below
+    for (const name of Object.keys(headers)) {
+      if (name.startsWith('x-hookarmor-')) delete headers[name];
+    }
+
+    // Preserve original raw signatures before re-signing for audit and forensic trace
+    if (event.headers && event.headers['stripe-signature']) {
+      headers['x-hookarmor-original-stripe-signature'] = event.headers['stripe-signature'];
+    }
+    if (event.headers && event.headers['x-shopify-hmac-sha256']) {
+      headers['x-hookarmor-original-shopify-hmac'] = event.headers['x-shopify-hmac-sha256'];
+    }
+    if (event.headers && event.headers['svix-signature']) {
+      headers['x-hookarmor-original-svix-signature'] = event.headers['svix-signature'];
+    }
+
+    const rawBuffer = Buffer.isBuffer(event.raw_body)
+      ? event.raw_body
+      : Buffer.from(String(event.raw_body || ''), 'utf8');
+
+    // Re-sign outbound headers if endpoint secret is configured (Transparent Zero-Code-Change Mode)
+    if (endpoint.secret) {
+      headers = this.signHeaders(event.provider, rawBuffer, headers, endpoint.secret);
+    }
+
+    // Isolated Trust Domain mode: vouch only for events whose signature was verified at ingress
+    if (this.signingSecret && event.verified) {
+      const freshTs = Math.floor(Date.now() / 1000);
+      const hmac = crypto.createHmac('sha256', this.signingSecret);
+      hmac.update(Buffer.from(`${freshTs}.`, 'utf8'));
+      hmac.update(rawBuffer);
+      const internalSig = hmac.digest('hex');
+      headers['x-hookarmor-signature'] = `t=${freshTs},v1=${internalSig}`;
+    }
+
+    // Remove hop-by-hop and encoding headers
+    delete headers['host'];
+    delete headers['connection'];
+    delete headers['content-length'];
+    delete headers['content-encoding'];
+    delete headers['transfer-encoding'];
+    delete headers['expect'];
+
+    headers['content-length'] = String(rawBuffer.length);
+    headers['x-hookarmor-delivery-id'] = event.id;
+    headers['x-hookarmor-attempt'] = String(event.attempts + 1);
+    // Strict ISO-8601 UTC timestamp with Z to prevent client-side local timezone parsing skew
+    const createdAtStr = String(event.created_at || '');
+    const originalTimestamp = createdAtStr.includes('T')
+      ? (createdAtStr.endsWith('Z') ? createdAtStr : `${createdAtStr}Z`)
+      : (createdAtStr ? `${createdAtStr.replace(' ', 'T')}Z` : new Date().toISOString());
+    headers['x-hookarmor-original-timestamp'] = originalTimestamp;
+    const isReplay = replay || event.attempts > 0;
+    headers['x-hookarmor-is-replay'] = isReplay ? 'true' : 'false';
+
+    return new Promise((resolve) => {
+      let settled = false;
+
+      // Single exit point: every outcome records exactly one attempt and resolves exactly once
+      const finish = async ({ statusCode = 0, responseBody = '', errorMessage = '' }) => {
+        if (settled) return;
+        settled = true;
+
+        const latencyMs = Date.now() - startTime;
+        const isSuccess = statusCode >= 200 && statusCode < 300;
+
+        let nextRetryAt = null;
+        if (!isSuccess && endpoint.auto_retry && (event.attempts + 1) < endpoint.max_retries) {
+          nextRetryAt = this.calculateNextRetry(event.attempts);
+        }
+
+        const message = isSuccess ? '' : (errorMessage || `Destination returned HTTP ${statusCode}`);
+        try {
+          this.storage.recordAttempt({
+            eventId: event.id,
+            statusCode,
+            responseBody,
+            errorMessage: message,
+            latencyMs,
+            nextRetryAt
+          });
+        } catch (err) {
+          console.error(`[Dispatcher] Failed to record attempt for ${event.id}:`, err.message);
+        }
+
+        const result = {
+          eventId: event.id,
+          endpointId: endpoint.id,
+          success: isSuccess,
+          statusCode,
+          latencyMs,
+          responseBody,
+          errorMessage: message || undefined,
+          nextRetryAt
+        };
+
+        this.emit('delivery', result);
+
+        if (!isSuccess) {
+          // Alert on initial failure and on final exhaustion to prevent notification flood (§6.6)
+          const isFirstFailure = (event.attempts === 0);
+          const isExhausted = !nextRetryAt;
+          if (isFirstFailure || isExhausted) {
+            await Alerter.sendAlert(endpoint.alert_webhook_url, {
+              event,
+              endpoint,
+              attempt: { statusCode, errorMessage: message, latencyMs, isExhausted }
+            }, { strictSSRF: this.strictSSRF });
+          }
+        }
+
+        resolve(result);
+      };
+
+      try {
+        const check = checkUrl(targetUrl, this.strictSSRF);
+        if (!check.ok) {
+          finish({ errorMessage: `Delivery blocked: ${check.reason}` });
+          return;
+        }
+
+        const url = new URL(targetUrl);
+        const isHttps = url.protocol === 'https:';
+        const client = isHttps ? https : http;
+
+        let gotResponse = false;
+        const req = client.request(url, {
+          method: 'POST',
+          headers,
+          timeout: this.defaultTimeoutMs,
+          lookup: guardedLookup(this.strictSSRF)
+        }, (res) => {
+          gotResponse = true;
+          let responseBody = '';
+          res.setEncoding('utf8');
+          res.on('data', chunk => {
+            if (responseBody.length < 4000) {
+              responseBody += chunk;
+            }
+          });
+          res.on('end', () => finish({ statusCode: res.statusCode || 0, responseBody }));
+          res.on('error', (err) => finish({ errorMessage: err.message }));
+          res.on('aborted', () => finish({ errorMessage: 'Response aborted by destination' }));
+          res.on('close', () => {
+            if (!res.complete) finish({ errorMessage: 'Response closed before it completed' });
+          });
+        });
+
+        req.on('timeout', () => {
+          req.destroy(new Error(`Connection timed out after ${this.defaultTimeoutMs}ms`));
+        });
+
+        req.on('error', (err) => finish({ errorMessage: err.message }));
+        req.on('close', () => {
+          if (!gotResponse) finish({ errorMessage: 'Connection closed before a response was received' });
+        });
+
+        req.write(rawBuffer);
+        req.end();
+      } catch (err) {
+        finish({ errorMessage: err.message });
+      }
+    });
+  }
+
+  async replayEvent(eventId) {
+    const event = this.storage.getEvent(eventId);
+    if (!event) {
+      const err = new Error(`Event not found: ${eventId}`);
+      err.code = 'NOT_FOUND';
+      throw err;
+    }
+    const endpoint = this.storage.getEndpoint(event.endpoint_id);
+    if (!endpoint) {
+      const err = new Error(`Endpoint not found: ${event.endpoint_id}`);
+      err.code = 'NOT_FOUND';
+      throw err;
+    }
+    if (!this.storage.claimEventForManualReplay(eventId)) {
+      const err = new Error(`Event ${eventId} is already being delivered`);
+      err.code = 'IN_FLIGHT';
+      throw err;
+    }
+
+    return this.dispatch(event, endpoint, { replay: true });
+  }
+
+  // Claims every failed event (including ones that exhausted automatic retries) and delivers
+  // them in the background through the per-endpoint concurrency limiter.
+  replayAllFailed(endpointId = null, batchSize = 500) {
+    const failedEvents = this.storage.getFailedEventsForReplay(endpointId, batchSize);
+    const claimed = [];
+    for (const event of failedEvents) {
+      const endpoint = this.storage.getEndpoint(event.endpoint_id);
+      if (!endpoint || !this.storage.claimEventForRetry(event.id)) continue;
+      claimed.push(event.id);
+      this.dispatch(event, endpoint, { replay: true }).catch((err) => {
+        console.error(`[Dispatcher] Replay error for ${event.id}:`, err.message);
+      });
+    }
+    return { replayedCount: claimed.length, eventIds: claimed, remaining: this.storage.countFailed(endpointId) };
+  }
+}
+
+module.exports = Dispatcher;