hookarmor 1.0.2 → 1.1.0

package/src/server.js

@@ -1,370 +1,544 @@
-const express = require('express');
-const cors = require('cors');
-const { randomUUID } = require('crypto');
-const path = require('path');
-const fs = require('fs');
-const http = require('http');
-const { WebSocketServer, WebSocket } = require('ws');
-
-const Storage = require('./storage');
-const Dispatcher = require('./dispatcher');
-const RetryWorker = require('./worker');
-
-function isPrivateOrMetadataUrl(urlString) {
-  try {
-    const parsed = new URL(urlString);
-    const hostname = parsed.hostname.toLowerCase();
-    if (
-      hostname === '169.254.169.254' ||
-      hostname === 'metadata.google.internal' ||
-      hostname === '100.100.100.200' ||
-      hostname.startsWith('169.254.')
-    ) {
-      return true;
-    }
-    return false;
-  } catch (e) {
-    return true;
-  }
-}
-
-function createServer(options = {}) {
-  const app = express();
-  const server = http.createServer(app);
-  const wss = new WebSocketServer({ server, path: '/ws' });
-
-  const storage = new Storage(options.dbPath);
-  const dispatcher = new Dispatcher(storage, {
-    defaultConcurrency: options.defaultConcurrency || 5,
-    defaultTimeoutMs: options.defaultTimeoutMs || 25000
-  });
-
-  const worker = new RetryWorker(storage, dispatcher, {
-    intervalMs: options.retryIntervalMs || 5000
-  });
-  if (options.autoStartWorker !== false) {
-    worker.start();
-  }
-
-  server.on('close', () => {
-    worker.stop();
-  });
-
-  // Broadcast helper for real-time WebSocket dashboard
-  function broadcast(type, data) {
-    const payload = JSON.stringify({ type, data });
-    wss.clients.forEach(client => {
-      if (client.readyState === WebSocket.OPEN) {
-        client.send(payload);
-      }
-    });
-  }
-
-  // Hook dispatcher events to WebSocket broadcasts
-  dispatcher.on('delivery', (res) => {
-    broadcast('delivery', res);
-  });
-
-  // Enable CORS
-  app.use(cors());
-
-  // Serve static UI assets
-  app.use('/static', express.static(path.join(__dirname, 'public')));
-
-  // Ingress endpoint for webhooks - uses raw body parser to preserve raw bytes
-  app.post('/in/:endpointId', express.raw({ type: '*/*', limit: '10mb' }), async (req, res) => {
-    const endpointId = req.params.endpointId;
-    const endpoint = storage.getEndpoint(endpointId);
-
-    if (!endpoint) {
-      return res.status(404).json({ error: `HookArmor endpoint not found: ${endpointId}` });
-    }
-
-    const rawBodyBuffer = req.body || Buffer.from('');
-    const rawBody = rawBodyBuffer.toString('utf8');
-    const headers = { ...req.headers };
-
-    // Detect provider & idempotency key
-    let provider = 'generic';
-    let eventType = null;
-    let idempotencyKey = headers['idempotency-key'] || headers['x-idempotency-key'] || null;
-
-    if (headers['stripe-signature']) {
-      provider = 'stripe';
-      try {
-        const parsed = JSON.parse(rawBody);
-        eventType = parsed.type;
-        if (parsed.id) idempotencyKey = parsed.id;
-      } catch (e) {}
-    } else if (headers['x-shopify-hmac-sha256'] || headers['x-shopify-topic']) {
-      provider = 'shopify';
-      eventType = headers['x-shopify-topic'];
-      if (headers['x-shopify-webhook-id']) idempotencyKey = headers['x-shopify-webhook-id'];
-    } else if (headers['x-github-event']) {
-      provider = 'github';
-      eventType = headers['x-github-event'];
-      if (headers['x-github-delivery']) idempotencyKey = headers['x-github-delivery'];
-    } else if (headers['clerk-signature'] || headers['svix-id']) {
-      provider = 'clerk/svix';
-      if (headers['svix-id']) idempotencyKey = headers['svix-id'];
-      try {
-        const parsed = JSON.parse(rawBody);
-        eventType = parsed.type;
-      } catch (e) {}
-    } else {
-      try {
-        const parsed = JSON.parse(rawBody);
-        eventType = parsed.event || parsed.type || parsed.action || null;
-        if (parsed.id) idempotencyKey = String(parsed.id);
-      } catch (e) {}
-    }
-
-    // 0. Verify signature on ingress if endpoint secret is configured
-    if (endpoint.secret) {
-      const verification = Dispatcher.verifyIngressSignature(provider, rawBody, headers, endpoint.secret);
-      if (!verification.valid) {
-        return res.status(400).json({
-          error: 'Webhook signature verification failed',
-          provider,
-          reason: verification.reason
-        });
-      }
-    }
-
-    // Deduplication check: if this event ID was already delivered, ack immediately without duplicating downstream side effects
-    if (idempotencyKey) {
-      const existing = storage.findEventByIdempotencyKey(endpoint.id, idempotencyKey);
-      if (existing && existing.status === 'delivered') {
-        return res.status(200).json({
-          received: true,
-          hookarmor_id: existing.id,
-          status: 'deduplicated',
-          message: `Idempotency key ${idempotencyKey} already delivered. Suppressed duplicate execution.`
-        });
-      }
-    }
-
-    const eventId = `evt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-
-    // 1. Durably save event in SQLite
-    const savedEvent = storage.saveEvent({
-      id: eventId,
-      endpointId: endpoint.id,
-      idempotencyKey,
-      provider,
-      eventType,
-      headers,
-      rawBody,
-      status: 'pending'
-    });
-
-    broadcast('event:received', {
-      id: eventId,
-      endpointId: endpoint.id,
-      provider,
-      eventType,
-      createdAt: savedEvent.created_at
-    });
-
-    // 2. Respond immediately with 200 OK to the sender so Stripe never times out or backs off
-    res.status(200).json({
-      received: true,
-      hookarmor_id: eventId,
-      status: 'buffered'
-    });
-
-    // 3. Dispatch to target destination asynchronously
-    setImmediate(async () => {
-      try {
-        await dispatcher.dispatch(savedEvent, endpoint);
-      } catch (err) {
-        console.error(`[Ingress] Dispatch error for ${eventId}:`, err);
-      }
-    });
-  });
-
-  // REST API: JSON Body Parser for Dashboard / Management
-  app.use(express.json());
-
-  // Management API Authentication Middleware (optional, active when HOOKARMOR_API_KEY is configured)
-  const apiKey = options.apiKey || process.env.HOOKARMOR_API_KEY || null;
-  app.use('/api', (req, res, next) => {
-    // Keep public waitlist signup open for landing page
-    if (req.path === '/waitlist' && req.method === 'POST') return next();
-
-    // Allow public read-only demo access & replay simulation so prospective users can explore live
-    const isPublicDemo =
-      (req.method === 'GET' && (req.path === '/stats' || req.path === '/endpoints' || req.path === '/events' || /^\/events\/[^\/]+$/.test(req.path))) ||
-      (req.method === 'POST' && (req.path === '/events/replay-all' || /^\/events\/[^\/]+\/replay$/.test(req.path)));
-
-    if (isPublicDemo) return next();
-
-    if (!apiKey) return next();
-
-    // Accept API token strictly via Authorization or X-Api-Key headers (NEVER query string URL)
-    const authHeader = req.headers['authorization'] || '';
-    const token = authHeader.replace(/^Bearer\s+/i, '').trim() || req.headers['x-api-key'] || '';
-    if (!token || token !== apiKey) {
-      return res.status(401).json({ error: 'Unauthorized: valid HookArmor API key required in header' });
-    }
-    next();
-  });
-
-  // Get Stats
-  app.get('/api/stats', (req, res) => {
-    res.json(storage.getStats());
-  });
-
-  // List Endpoints
-  app.get('/api/endpoints', (req, res) => {
-    res.json(storage.listEndpoints());
-  });
-
-  // Create or Update Endpoint
-  app.post('/api/endpoints', (req, res) => {
-    const { id, name, targetUrl, secret, alertWebhookUrl, autoRetry, maxRetries, concurrencyLimit, concurrency_limit } = req.body;
-    if (!id || !name || !targetUrl) {
-      return res.status(400).json({ error: 'id, name, and targetUrl are required' });
-    }
-    if (isPrivateOrMetadataUrl(targetUrl)) {
-      return res.status(400).json({ error: 'targetUrl cannot target cloud metadata or link-local addresses (SSRF blocked)' });
-    }
-    const endpoint = storage.createEndpoint({
-      id,
-      name,
-      targetUrl,
-      secret,
-      alertWebhookUrl,
-      autoRetry: autoRetry !== undefined ? autoRetry : 1,
-      maxRetries: maxRetries || 5,
-      concurrencyLimit: concurrencyLimit || concurrency_limit || 5
-    });
-    res.json(endpoint);
-  });
-
-  // List Events
-  app.get('/api/events', (req, res) => {
-    const { endpointId, status, limit, offset } = req.query;
-    const events = storage.listEvents({
-      endpointId,
-      status,
-      limit: parseInt(limit, 10) || 50,
-      offset: parseInt(offset, 10) || 0
-    });
-    res.json(events);
-  });
-
-  // Get single event with attempts
-  app.get('/api/events/:id', (req, res) => {
-    const event = storage.getEvent(req.params.id);
-    if (!event) return res.status(404).json({ error: 'Event not found' });
-    const attempts = storage.getAttempts(req.params.id);
-    res.json({ ...event, attempts });
-  });
-
-  // Replay a specific event
-  app.post('/api/events/:id/replay', async (req, res) => {
-    try {
-      const result = await dispatcher.replayEvent(req.params.id);
-      res.json(result);
-    } catch (err) {
-      res.status(500).json({ error: err.message });
-    }
-  });
-
-  // Replay all failed events (optionally filtered by endpoint)
-  app.post('/api/events/replay-all', async (req, res) => {
-    try {
-      const { endpointId } = req.body || {};
-      const results = await dispatcher.replayAllFailed(endpointId);
-      res.json({ replayedCount: results.length, results });
-    } catch (err) {
-      res.status(500).json({ error: err.message });
-    }
-  });
-
-  // Waitlist Registration
-  app.post('/api/waitlist', (req, res) => {
-    const { email, source } = req.body || {};
-    if (!email || !email.includes('@')) {
-      return res.status(400).json({ error: 'Valid email required' });
-    }
-    const result = storage.addWaitlist(email.trim().toLowerCase(), source || 'landing_page');
-    res.json({ success: true, message: 'Added to HookArmor Cloud beta waitlist!', email: result.email });
-  });
-
-  app.get('/api/waitlist', (req, res) => {
-    res.json(storage.listWaitlist());
-  });
-
-  // Mock Target Receiver (for self-testing and local simulation)
-  let mockTargetBehavior = {
-    statusCode: 200,
-    delayMs: 15,
-    responseBody: { status: 'mock_processed' }
-  };
-
-  app.post('/mock/target', (req, res) => {
-    setTimeout(() => {
-      res.status(mockTargetBehavior.statusCode).json(mockTargetBehavior.responseBody);
-    }, mockTargetBehavior.delayMs);
-  });
-
-  app.post('/mock/config', (req, res) => {
-    mockTargetBehavior = { ...mockTargetBehavior, ...req.body };
-    res.json({ message: 'Mock target configuration updated', config: mockTargetBehavior });
-  });
-
-  app.get('/mock/config', (req, res) => {
-    res.json(mockTargetBehavior);
-  });
-
-  // SEO & Web Crawler Discovery
-  app.get('/robots.txt', (req, res) => {
-    res.type('text/plain');
-    res.sendFile('robots.txt', { root: path.join(__dirname, 'public') });
-  });
-
-  app.get('/sitemap.xml', (req, res) => {
-    res.type('application/xml');
-    res.sendFile('sitemap.xml', { root: path.join(__dirname, 'public') });
-  });
-
-  app.get('/og-preview.png', (req, res) => {
-    res.type('image/png');
-    res.sendFile('og-preview.png', { root: path.join(__dirname, 'public') });
-  });
-
-  // Root Route: Dashboard if run locally via CLI; Landing page on cloud deployment
-  app.get('/', (req, res) => {
-    const isCloudProduction = Boolean(process.env.RAILWAY_ENVIRONMENT || process.env.RENDER || process.env.NODE_ENV === 'production');
-    if (!isCloudProduction) {
-      return res.sendFile('index.html', { root: path.join(__dirname, 'public') });
-    }
-    res.sendFile('landing.html', { root: path.join(__dirname, 'public') });
-  });
-
-  // Interactive Dashboard Routes
-  app.get(['/dashboard', '/app'], (req, res) => {
-    res.sendFile('index.html', { root: path.join(__dirname, 'public') });
-  });
-
-  // Engineering Blog Routes
-  app.get('/blog', (req, res) => {
-    res.sendFile('index.html', { root: path.join(__dirname, 'public', 'blog') });
-  });
-
-  app.get('/blog/:slug', (req, res) => {
-    const slug = req.params.slug.replace(/[^a-zA-Z0-9-_]/g, '');
-    const fileName = `${slug}.html`;
-    const filePath = path.join(__dirname, 'public', 'blog', fileName);
-    if (fs.existsSync(filePath)) {
-      return res.sendFile(fileName, { root: path.join(__dirname, 'public', 'blog') });
-    }
-    res.redirect('/blog');
-  });
-
-  return { app, server, storage, dispatcher, worker };
-}
-
-module.exports = { createServer };
+const express = require('express');
+const cors = require('cors');
+const crypto = require('crypto');
+const path = require('path');
+const fs = require('fs');
+const http = require('http');
+const { WebSocketServer, WebSocket } = require('ws');
+
+const Storage = require('./storage');
+const Dispatcher = require('./dispatcher');
+const RetryWorker = require('./worker');
+const { checkUrl } = require('./netguard');
+
+const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const ENDPOINT_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+function envFlag(name) {
+  const v = process.env[name];
+  if (v === undefined || v === '') return undefined;
+  return v === 'true' || v === '1';
+}
+
+function hostnameOf(hostHeader = '') {
+  const h = String(hostHeader).toLowerCase();
+  if (h.startsWith('[')) return h.slice(0, h.indexOf(']') + 1);
+  return h.split(':')[0];
+}
+
+function clampInt(value, fallback, min, max) {
+  const n = parseInt(value, 10);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(Math.max(n, min), max);
+}
+
+// Fixed-window in-memory rate limiter keyed by client IP
+function createRateLimiter({ limit, windowMs }) {
+  const hits = new Map();
+  return (key) => {
+    const now = Date.now();
+    if (hits.size > 10000) {
+      for (const [k, v] of hits) if (v.resetAt <= now) hits.delete(k);
+    }
+    const entry = hits.get(key);
+    if (!entry || entry.resetAt <= now) {
+      hits.set(key, { count: 1, resetAt: now + windowMs });
+      return true;
+    }
+    entry.count++;
+    return entry.count <= limit;
+  };
+}
+
+function publicEndpoint(ep) {
+  if (!ep) return ep;
+  const { secret, ...rest } = ep;
+  return { ...rest, has_secret: Boolean(secret) };
+}
+
+function createServer(options = {}) {
+  const isProduction = options.production !== undefined
+    ? options.production
+    : Boolean(process.env.NODE_ENV === 'production' || process.env.RAILWAY_ENVIRONMENT || process.env.RENDER);
+  const apiKey = options.apiKey || process.env.HOOKARMOR_API_KEY || null;
+  const isDemoMode = options.demoMode !== undefined
+    ? options.demoMode
+    : (process.env.HOOKARMOR_DEMO_MODE === 'true');
+  const allowNoAuth = options.allowNoAuth !== undefined ? options.allowNoAuth : envFlag('HOOKARMOR_ALLOW_NO_AUTH') === true;
+  // Strict outbound address checks default on in production (block loopback/private networks)
+  const strictSSRF = options.strictSSRF !== undefined
+    ? options.strictSSRF
+    : (envFlag('HOOKARMOR_STRICT_SSRF') !== undefined ? envFlag('HOOKARMOR_STRICT_SSRF') : isProduction);
+  const mockEnabled = options.enableMock !== undefined
+    ? options.enableMock
+    : (envFlag('HOOKARMOR_ENABLE_MOCK') !== undefined ? envFlag('HOOKARMOR_ENABLE_MOCK') : !isProduction);
+  const corsOrigins = options.corsOrigins || (process.env.HOOKARMOR_CORS_ORIGINS
+    ? process.env.HOOKARMOR_CORS_ORIGINS.split(',').map((s) => s.trim()).filter(Boolean)
+    : []);
+  const maxBody = options.maxBodySize || process.env.HOOKARMOR_MAX_BODY || '10mb';
+  const retentionDays = options.retentionDays !== undefined
+    ? options.retentionDays
+    : clampInt(process.env.HOOKARMOR_RETENTION_DAYS, 0, 0, 3650);
+
+  if (isProduction && !apiKey && !allowNoAuth) {
+    throw new Error(
+      'HOOKARMOR_API_KEY is required in production: without it the management API (events, endpoints, replays) is open to anyone. ' +
+      'Generate one with `openssl rand -hex 32`. Set HOOKARMOR_ALLOW_NO_AUTH=true only if the instance is not reachable from untrusted networks.'
+    );
+  }
+
+  const app = express();
+  const server = http.createServer(app);
+
+  const trustProxy = process.env.HOOKARMOR_TRUST_PROXY || ((process.env.RAILWAY_ENVIRONMENT || process.env.RENDER) ? '1' : null);
+  if (trustProxy) app.set('trust proxy', /^\d+$/.test(trustProxy) ? parseInt(trustProxy, 10) : trustProxy);
+
+  const storage = new Storage(options.dbPath);
+  const recovered = storage.recoverInterruptedDeliveries();
+  if (recovered > 0) {
+    console.warn(`[HookArmor] Re-queued ${recovered} event(s) that were mid-delivery when the process last stopped.`);
+  }
+
+  const dispatcher = new Dispatcher(storage, {
+    defaultConcurrency: options.defaultConcurrency || 5,
+    defaultTimeoutMs: options.defaultTimeoutMs || 25000,
+    strictSSRF,
+    signingSecret: options.signingSecret || process.env.HOOKARMOR_SIGNING_SECRET || null
+  });
+
+  const worker = new RetryWorker(storage, dispatcher, {
+    intervalMs: options.retryIntervalMs || 5000,
+    retentionDays
+  });
+  if (options.autoStartWorker !== false) {
+    worker.start();
+  }
+
+  server.on('close', () => {
+    worker.stop();
+  });
+
+  function tokenMatches(token) {
+    if (!apiKey || !token) return false;
+    // Hash both sides so the comparison is constant-time regardless of length
+    const a = crypto.createHash('sha256').update(String(token)).digest();
+    const b = crypto.createHash('sha256').update(String(apiKey)).digest();
+    return crypto.timingSafeEqual(a, b);
+  }
+
+  const authFailureLimiter = createRateLimiter({ limit: options.authFailureLimit || 30, windowMs: 10 * 60 * 1000 });
+  const waitlistLimiter = createRateLimiter({ limit: options.waitlistRateLimit || 5, windowMs: 10 * 60 * 1000 });
+
+  // ---------------------------------------------------------------- live WebSocket feed
+  const wss = new WebSocketServer({
+    server,
+    path: '/ws',
+    maxPayload: 4096,
+    // Without an API key the feed is only served to localhost (blocks DNS-rebinding pages)
+    verifyClient: (info) => Boolean(apiKey) || LOCAL_HOSTNAMES.has(hostnameOf(info.req.headers.host))
+  });
+
+  wss.on('connection', (socket) => {
+    socket.isAuthed = !apiKey || isDemoMode;
+    let authTimer = null;
+    if (!socket.isAuthed) {
+      authTimer = setTimeout(() => { if (!socket.isAuthed) socket.close(4001, 'Authentication required'); }, 15000);
+      if (authTimer.unref) authTimer.unref();
+    }
+    // Browsers cannot set headers on WebSocket upgrades, so the key arrives as the first message
+    socket.on('message', (raw) => {
+      try {
+        const msg = JSON.parse(String(raw));
+        if (msg.type === 'auth') {
+          if (tokenMatches(msg.token)) {
+            socket.isAuthed = true;
+            if (authTimer) clearTimeout(authTimer);
+            socket.send(JSON.stringify({ type: 'auth:ok' }));
+          } else {
+            socket.close(4001, 'Invalid API key');
+          }
+        }
+      } catch (e) {}
+    });
+  });
+
+  function broadcast(type, data) {
+    const payload = JSON.stringify({ type, data });
+    wss.clients.forEach(client => {
+      if (client.readyState === WebSocket.OPEN && client.isAuthed) {
+        client.send(payload);
+      }
+    });
+  }
+
+  // Hook dispatcher events to WebSocket broadcasts
+  dispatcher.on('delivery', (res) => {
+    broadcast('delivery', res);
+  });
+
+  // CORS is opt-in: the dashboard and landing page are same-origin and need none
+  if (corsOrigins.length > 0) {
+    app.use('/api', cors({ origin: corsOrigins }));
+  }
+
+  // Serve static UI assets
+  app.use('/static', express.static(path.join(__dirname, 'public')));
+
+  // Ingress endpoint for webhooks - uses raw body parser to preserve raw bytes
+  app.post('/in/:endpointId', express.raw({ type: '*/*', limit: maxBody }), (req, res) => {
+    const endpointId = req.params.endpointId;
+    const endpoint = storage.getEndpoint(endpointId);
+
+    if (!endpoint) {
+      return res.status(404).json({ error: 'HookArmor endpoint not found' });
+    }
+
+    const rawBodyBuffer = Buffer.isBuffer(req.body) ? req.body : Buffer.from('');
+    const rawBody = rawBodyBuffer.toString('utf8');
+    const headers = { ...req.headers };
+
+    // Detect provider & idempotency key
+    let provider = 'generic';
+    let eventType = null;
+    let idempotencyKey = headers['idempotency-key'] || headers['x-idempotency-key'] || null;
+
+    if (headers['stripe-signature']) {
+      provider = 'stripe';
+      try {
+        const parsed = JSON.parse(rawBody);
+        eventType = parsed.type;
+        if (parsed.id) idempotencyKey = parsed.id;
+      } catch (e) {}
+    } else if (headers['x-shopify-hmac-sha256'] || headers['x-shopify-topic']) {
+      provider = 'shopify';
+      eventType = headers['x-shopify-topic'];
+      if (headers['x-shopify-webhook-id']) idempotencyKey = headers['x-shopify-webhook-id'];
+    } else if (headers['x-github-event']) {
+      provider = 'github';
+      eventType = headers['x-github-event'];
+      if (headers['x-github-delivery']) idempotencyKey = headers['x-github-delivery'];
+    } else if (headers['clerk-signature'] || headers['svix-id']) {
+      provider = 'clerk/svix';
+      if (headers['svix-id']) idempotencyKey = headers['svix-id'];
+      try {
+        const parsed = JSON.parse(rawBody);
+        eventType = parsed.type;
+      } catch (e) {}
+    } else {
+      try {
+        const parsed = JSON.parse(rawBody);
+        eventType = parsed.event || parsed.type || parsed.action || null;
+        if (parsed.id) idempotencyKey = String(parsed.id);
+      } catch (e) {}
+    }
+    if (typeof eventType !== 'string') eventType = eventType == null ? null : String(eventType);
+    if (eventType) eventType = eventType.slice(0, 200);
+    if (idempotencyKey) idempotencyKey = String(idempotencyKey).slice(0, 255);
+
+    // 0. Verify signature on ingress if endpoint secret is configured
+    let verified = false;
+    if (endpoint.secret) {
+      const verification = Dispatcher.verifyIngressSignature(provider, rawBody, headers, endpoint.secret);
+      if (!verification.valid) {
+        return res.status(400).json({
+          error: 'Webhook signature verification failed',
+          provider,
+          reason: verification.reason
+        });
+      }
+      verified = true;
+    }
+
+    let savedEvent;
+    try {
+      // Deduplication: if HookArmor already holds this event, ack without creating a second delivery
+      if (idempotencyKey) {
+        const existing = storage.findEventByIdempotencyKey(endpoint.id, idempotencyKey);
+        if (existing) {
+          return res.status(200).json({
+            received: true,
+            hookarmor_id: existing.id,
+            status: 'deduplicated',
+            message: `Idempotency key already received (current status: ${existing.status}). Suppressed duplicate delivery.`
+          });
+        }
+      }
+
+      const eventId = `evt_${Date.now()}_${crypto.randomBytes(6).toString('hex')}`;
+
+      // 1. Durably save event in SQLite, already claimed for its first delivery
+      savedEvent = storage.saveEvent({
+        id: eventId,
+        endpointId: endpoint.id,
+        idempotencyKey,
+        provider,
+        eventType,
+        headers,
+        rawBody,
+        status: 'replaying',
+        verified
+      });
+    } catch (err) {
+      // Not persisted: return an error so the provider keeps its own retry schedule
+      console.error('[Ingress] Failed to persist event:', err.message);
+      return res.status(503).json({ error: 'HookArmor could not persist the event; please retry' });
+    }
+
+    broadcast('event:received', {
+      id: savedEvent.id,
+      endpointId: endpoint.id,
+      provider,
+      eventType,
+      createdAt: savedEvent.created_at
+    });
+
+    // 2. Respond immediately with 200 OK to the sender so Stripe never times out or backs off
+    res.status(200).json({
+      received: true,
+      hookarmor_id: savedEvent.id,
+      status: 'buffered'
+    });
+
+    // 3. Dispatch to target destination asynchronously
+    setImmediate(() => {
+      dispatcher.dispatch(savedEvent, endpoint).catch((err) => {
+        console.error(`[Ingress] Dispatch error for ${savedEvent.id}:`, err);
+      });
+    });
+  });
+
+  // REST API: JSON Body Parser for Dashboard / Management
+  app.use(express.json({ limit: '100kb' }));
+
+  app.use('/api', (req, res, next) => {
+    // Public waitlist signup for the landing page (rate limited)
+    if (req.path === '/waitlist' && req.method === 'POST') {
+      if (!waitlistLimiter(req.ip)) return res.status(429).json({ error: 'Too many signups from this address; try again later' });
+      return next();
+    }
+
+    if (!apiKey) {
+      if (!isDemoMode) {
+        // Open local-dev mode: only answer to localhost names, so a web page cannot reach this
+        // API through DNS rebinding
+        if (!LOCAL_HOSTNAMES.has(hostnameOf(req.headers.host))) {
+          return res.status(403).json({ error: 'Without HOOKARMOR_API_KEY the management API is only served on localhost' });
+        }
+        return next();
+      }
+    }
+
+    // Demo mode (public marketing sandbox): read-only access without a key
+    if (isDemoMode) {
+      const isPublicDemoRead = req.method === 'GET' &&
+        (req.path === '/stats' || req.path === '/endpoints' || req.path === '/events' || /^\/events\/[^\/]+$/.test(req.path));
+      if (isPublicDemoRead) return next();
+    }
+
+    const authHeader = req.headers['authorization'] || '';
+    const token = authHeader.replace(/^Bearer\s+/i, '').trim() || req.headers['x-api-key'] || '';
+    if (!tokenMatches(token)) {
+      // Only wrong keys count towards the lockout, not anonymous page loads
+      if (token && !authFailureLimiter(req.ip)) {
+        return res.status(429).json({ error: 'Too many failed authentication attempts; try again later' });
+      }
+      return res.status(401).json({ error: 'Unauthorized: valid HookArmor API key required in header' });
+    }
+    next();
+  });
+
+  // State-changing calls must be JSON. Cross-site forms cannot send that content type without a
+  // CORS preflight, which this server does not grant.
+  app.use('/api', (req, res, next) => {
+    const contentType = String(req.headers['content-type'] || '').split(';')[0].trim().toLowerCase();
+    const isJson = contentType === 'application/json' || contentType.endsWith('+json');
+    if (req.method !== 'GET' && req.method !== 'HEAD' && req.method !== 'OPTIONS' && !isJson) {
+      return res.status(415).json({ error: 'Content-Type must be application/json' });
+    }
+    next();
+  });
+
+  // Get Stats
+  app.get('/api/stats', (req, res) => {
+    res.json(storage.getStats());
+  });
+
+  // List Endpoints (secrets are never returned)
+  app.get('/api/endpoints', (req, res) => {
+    res.json(storage.listEndpoints().map(publicEndpoint));
+  });
+
+  // Create or Update Endpoint
+  app.post('/api/endpoints', (req, res) => {
+    const { id, name, targetUrl, secret, alertWebhookUrl, autoRetry, maxRetries, concurrencyLimit, concurrency_limit } = req.body || {};
+    if (!id || !name || !targetUrl) {
+      return res.status(400).json({ error: 'id, name, and targetUrl are required' });
+    }
+    if (typeof id !== 'string' || !ENDPOINT_ID_PATTERN.test(id)) {
+      return res.status(400).json({ error: 'id must be 1-64 characters: letters, digits, "-" or "_"' });
+    }
+    if (typeof name !== 'string' || name.length > 200) {
+      return res.status(400).json({ error: 'name must be a string of at most 200 characters' });
+    }
+    if (secret !== undefined && (typeof secret !== 'string' || secret.length > 500)) {
+      return res.status(400).json({ error: 'secret must be a string of at most 500 characters' });
+    }
+    const targetCheck = checkUrl(String(targetUrl), strictSSRF);
+    if (!targetCheck.ok) {
+      return res.status(400).json({ error: `targetUrl rejected: ${targetCheck.reason} (cloud metadata${strictSSRF ? ', loopback and private network' : ''} addresses are blocked)` });
+    }
+    if (alertWebhookUrl) {
+      const alertCheck = checkUrl(String(alertWebhookUrl), strictSSRF);
+      if (!alertCheck.ok) {
+        return res.status(400).json({ error: `alertWebhookUrl rejected: ${alertCheck.reason}` });
+      }
+    }
+    const endpoint = storage.createEndpoint({
+      id,
+      name,
+      targetUrl: String(targetUrl),
+      secret,
+      alertWebhookUrl: alertWebhookUrl === undefined ? undefined : String(alertWebhookUrl || ''),
+      autoRetry: autoRetry !== undefined ? autoRetry : 1,
+      maxRetries: clampInt(maxRetries, 5, 1, 50),
+      concurrencyLimit: clampInt(concurrencyLimit || concurrency_limit, 5, 1, 100)
+    });
+    res.json(publicEndpoint(endpoint));
+  });
+
+  // List Events
+  app.get('/api/events', (req, res) => {
+    const { endpointId, status, limit, offset } = req.query;
+    const events = storage.listEvents({
+      endpointId: typeof endpointId === 'string' ? endpointId : null,
+      status: typeof status === 'string' ? status : null,
+      limit: clampInt(limit, 50, 1, 500),
+      offset: clampInt(offset, 0, 0, Number.MAX_SAFE_INTEGER)
+    });
+    res.json(events);
+  });
+
+  // Get single event with attempts
+  app.get('/api/events/:id', (req, res) => {
+    const event = storage.getEvent(req.params.id);
+    if (!event) return res.status(404).json({ error: 'Event not found' });
+    const attempts = storage.getAttempts(req.params.id);
+    res.json({ ...event, attempts });
+  });
+
+  // Replay a specific event
+  app.post('/api/events/:id/replay', async (req, res) => {
+    try {
+      const result = await dispatcher.replayEvent(req.params.id);
+      res.json(result);
+    } catch (err) {
+      const status = err.code === 'NOT_FOUND' ? 404 : (err.code === 'IN_FLIGHT' ? 409 : 500);
+      res.status(status).json({ error: err.message });
+    }
+  });
+
+  // Replay all failed events, including ones that exhausted automatic retries.
+  // Returns immediately; deliveries run in the background through the concurrency limiter.
+  app.post('/api/events/replay-all', (req, res) => {
+    try {
+      const { endpointId } = req.body || {};
+      const result = dispatcher.replayAllFailed(typeof endpointId === 'string' ? endpointId : null);
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // Waitlist Registration
+  app.post('/api/waitlist', (req, res) => {
+    const { email, source } = req.body || {};
+    const cleanEmail = typeof email === 'string' ? email.trim().toLowerCase() : '';
+    if (!cleanEmail || cleanEmail.length > 254 || !/^[^\s@<>"']+@[^\s@<>"']+\.[^\s@<>"']+$/.test(cleanEmail)) {
+      return res.status(400).json({ error: 'Valid email required' });
+    }
+    const cleanSource = typeof source === 'string' ? source.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 50) || 'landing_page' : 'landing_page';
+    const result = storage.addWaitlist(cleanEmail, cleanSource);
+    res.json({ success: true, message: 'Added to HookArmor Cloud beta waitlist!', email: result.email });
+  });
+
+  app.get('/api/waitlist', (req, res) => {
+    res.json(storage.listWaitlist());
+  });
+
+  // Mock Target Receiver (local simulation only; not mounted in production unless HOOKARMOR_ENABLE_MOCK=true)
+  if (mockEnabled) {
+    let mockTargetBehavior = {
+      statusCode: 200,
+      delayMs: 15,
+      responseBody: { status: 'mock_processed' }
+    };
+
+    app.post('/mock/target', (req, res) => {
+      setTimeout(() => {
+        res.status(mockTargetBehavior.statusCode).json(mockTargetBehavior.responseBody);
+      }, mockTargetBehavior.delayMs);
+    });
+
+    app.post('/mock/config', (req, res) => {
+      const body = req.body || {};
+      mockTargetBehavior = {
+        statusCode: clampInt(body.statusCode, mockTargetBehavior.statusCode, 100, 599),
+        delayMs: clampInt(body.delayMs, mockTargetBehavior.delayMs, 0, 30000),
+        responseBody: body.responseBody !== undefined ? body.responseBody : mockTargetBehavior.responseBody
+      };
+      res.json({ message: 'Mock target configuration updated', config: mockTargetBehavior });
+    });
+
+    app.get('/mock/config', (req, res) => {
+      res.json(mockTargetBehavior);
+    });
+  }
+
+  // SEO & Web Crawler Discovery
+  app.get('/robots.txt', (req, res) => {
+    res.type('text/plain');
+    res.sendFile('robots.txt', { root: path.join(__dirname, 'public') });
+  });
+
+  app.get('/sitemap.xml', (req, res) => {
+    res.type('application/xml');
+    res.sendFile('sitemap.xml', { root: path.join(__dirname, 'public') });
+  });
+
+  app.get('/og-preview.png', (req, res) => {
+    res.type('image/png');
+    res.sendFile('og-preview.png', { root: path.join(__dirname, 'public') });
+  });
+
+  // Root Route: Dashboard by default on self-hosted instances; Landing page only if explicitly enabled (§6.13)
+  app.get('/', (req, res) => {
+    if (process.env.HOOKARMOR_SERVE_LANDING === 'true') {
+      return res.sendFile('landing.html', { root: path.join(__dirname, 'public') });
+    }
+    res.sendFile('index.html', { root: path.join(__dirname, 'public') });
+  });
+
+  // Interactive Dashboard Routes
+  app.get(['/dashboard', '/app'], (req, res) => {
+    res.sendFile('index.html', { root: path.join(__dirname, 'public') });
+  });
+
+  // Engineering Blog Routes
+  app.get('/blog', (req, res) => {
+    res.sendFile('index.html', { root: path.join(__dirname, 'public', 'blog') });
+  });
+
+  app.get('/blog/:slug', (req, res) => {
+    const slug = req.params.slug.replace(/[^a-zA-Z0-9-_]/g, '');
+    const fileName = `${slug}.html`;
+    const filePath = path.join(__dirname, 'public', 'blog', fileName);
+    if (fs.existsSync(filePath)) {
+      return res.sendFile(fileName, { root: path.join(__dirname, 'public', 'blog') });
+    }
+    res.redirect('/blog');
+  });
+
+  return { app, server, storage, dispatcher, worker, mockEnabled, strictSSRF };
+}
+
+module.exports = { createServer };