webspresso 0.0.99 → 0.0.100

package/plugins/webhooks/api-handlers.js

@@ -0,0 +1,237 @@
+/**
+ * Webhooks Admin API Handlers
+ * REST endpoints for managing endpoints, inspecting delivery history, pinging, and retrying
+ * @module plugins/webhooks/api-handlers
+ */
+
+'use strict';
+
+/**
+ * Create Webhook API route handlers
+ * 
+ * @param {import('./dispatcher').WebhookDispatcher} dispatcher 
+ * @param {Object} [options]
+ * @returns {Record<string, Function>}
+ */
+function createWebhookApiHandlers(dispatcher, options = {}) {
+  /**
+   * GET /endpoints — List all webhook endpoints
+   */
+  async function listEndpointsHandler(req, res) {
+    try {
+      const active = req.query.active !== undefined ? req.query.active === 'true' : undefined;
+      const search = req.query.search || req.query.q || undefined;
+      const endpoints = await dispatcher.listEndpoints({ active, search });
+
+      // Enrich with delivery counts if knex available
+      const kx = dispatcher.resolveKnex();
+      let enriched = endpoints;
+      if (kx && endpoints.length > 0) {
+        try {
+          const stats = await kx(dispatcher.deliveriesTable)
+            .select('endpoint_id')
+            .count('* as total_deliveries')
+            .sum({ success_count: kx.raw('CASE WHEN success = 1 OR success = true THEN 1 ELSE 0 END') })
+            .groupBy('endpoint_id');
+
+          const statsMap = new Map();
+          for (const s of stats) {
+            statsMap.set(String(s.endpoint_id), {
+              totalDeliveries: Number(s.total_deliveries || 0),
+              successCount: Number(s.success_count || 0),
+            });
+          }
+
+          enriched = endpoints.map((ep) => {
+            const st = statsMap.get(String(ep.id)) || { totalDeliveries: 0, successCount: 0 };
+            return {
+              ...ep,
+              stats: {
+                total: st.totalDeliveries,
+                successful: st.successCount,
+                failed: st.totalDeliveries - st.successCount,
+                successRate: st.totalDeliveries > 0 ? Math.round((st.successCount / st.totalDeliveries) * 100) : 100,
+              },
+            };
+          });
+        } catch (statsErr) {
+          // Fallback if aggregation fails
+        }
+      }
+
+      return res.status(200).json({
+        items: enriched,
+        total: enriched.length,
+      });
+    } catch (err) {
+      return res.status(500).json({ error: err.message || 'Failed to list webhook endpoints' });
+    }
+  }
+
+  /**
+   * POST /endpoints — Create new endpoint
+   */
+  async function createEndpointHandler(req, res) {
+    try {
+      const body = req.body || {};
+      if (!body.name || !body.url) {
+        return res.status(400).json({ error: 'Endpoint name and URL are required.' });
+      }
+
+      const created = await dispatcher.createEndpoint(body);
+      return res.status(201).json(created);
+    } catch (err) {
+      return res.status(400).json({ error: err.message || 'Failed to create webhook endpoint' });
+    }
+  }
+
+  /**
+   * GET /endpoints/:id — Get endpoint details
+   */
+  async function getEndpointHandler(req, res) {
+    try {
+      const id = req.params.id;
+      const endpoint = await dispatcher.getEndpoint(id);
+      if (!endpoint) {
+        return res.status(404).json({ error: `Webhook endpoint #${id} not found` });
+      }
+      return res.status(200).json(endpoint);
+    } catch (err) {
+      return res.status(500).json({ error: err.message || 'Failed to get webhook endpoint' });
+    }
+  }
+
+  /**
+   * PUT/PATCH /endpoints/:id — Update endpoint
+   */
+  async function updateEndpointHandler(req, res) {
+    try {
+      const id = req.params.id;
+      const body = req.body || {};
+      const updated = await dispatcher.updateEndpoint(id, body);
+      if (!updated) {
+        return res.status(404).json({ error: `Webhook endpoint #${id} not found` });
+      }
+      return res.status(200).json(updated);
+    } catch (err) {
+      return res.status(400).json({ error: err.message || 'Failed to update webhook endpoint' });
+    }
+  }
+
+  /**
+   * DELETE /endpoints/:id — Delete endpoint
+   */
+  async function deleteEndpointHandler(req, res) {
+    try {
+      const id = req.params.id;
+      const deleted = await dispatcher.deleteEndpoint(id);
+      if (!deleted) {
+        return res.status(404).json({ error: `Webhook endpoint #${id} not found` });
+      }
+      return res.status(200).json({ success: true, message: `Endpoint #${id} deleted.` });
+    } catch (err) {
+      return res.status(500).json({ error: err.message || 'Failed to delete webhook endpoint' });
+    }
+  }
+
+  /**
+   * POST /endpoints/:id/ping — Send test ping
+   */
+  async function pingEndpointHandler(req, res) {
+    try {
+      const id = req.params.id;
+      const result = await dispatcher.pingEndpoint(id);
+      return res.status(200).json(result);
+    } catch (err) {
+      return res.status(400).json({ error: err.message || 'Failed to ping webhook endpoint' });
+    }
+  }
+
+  /**
+   * GET /deliveries — List delivery logs
+   */
+  async function listDeliveriesHandler(req, res) {
+    try {
+      const endpointId = req.query.endpointId || req.query.endpoint_id;
+      const event = req.query.event;
+      const success = req.query.success;
+      const page = req.query.page;
+      const limit = req.query.limit || req.query.perPage;
+
+      const data = await dispatcher.listDeliveries({
+        endpointId,
+        event,
+        success,
+        page,
+        limit,
+      });
+
+      return res.status(200).json(data);
+    } catch (err) {
+      return res.status(500).json({ error: err.message || 'Failed to list webhook deliveries' });
+    }
+  }
+
+  /**
+   * GET /deliveries/:id — Get single delivery log
+   */
+  async function getDeliveryHandler(req, res) {
+    try {
+      const id = req.params.id;
+      const item = await dispatcher.getDelivery(id);
+      if (!item) {
+        return res.status(404).json({ error: `Webhook delivery #${id} not found` });
+      }
+      return res.status(200).json(item);
+    } catch (err) {
+      return res.status(500).json({ error: err.message || 'Failed to get webhook delivery' });
+    }
+  }
+
+  /**
+   * POST /deliveries/:id/retry — Retry failed delivery
+   */
+  async function retryDeliveryHandler(req, res) {
+    try {
+      const id = req.params.id;
+      const result = await dispatcher.retryDelivery(id);
+      return res.status(200).json(result);
+    } catch (err) {
+      return res.status(400).json({ error: err.message || 'Failed to retry webhook delivery' });
+    }
+  }
+
+  /**
+   * POST /deliveries/purge — Purge old deliveries
+   */
+  async function purgeDeliveriesHandler(req, res) {
+    try {
+      const days = parseInt(req.body?.days || req.query?.days, 10) || 30;
+      const purgedCount = await dispatcher.purgeDeliveries({ days });
+      return res.status(200).json({
+        success: true,
+        purged: purgedCount,
+        message: `Purged ${purgedCount} webhook deliveries older than ${days} days.`,
+      });
+    } catch (err) {
+      return res.status(500).json({ error: err.message || 'Failed to purge webhook deliveries' });
+    }
+  }
+
+  return {
+    listEndpointsHandler,
+    createEndpointHandler,
+    getEndpointHandler,
+    updateEndpointHandler,
+    deleteEndpointHandler,
+    pingEndpointHandler,
+    listDeliveriesHandler,
+    getDeliveryHandler,
+    retryDeliveryHandler,
+    purgeDeliveriesHandler,
+  };
+}
+
+module.exports = {
+  createWebhookApiHandlers,
+};

package/plugins/webhooks/crypto.js

@@ -0,0 +1,144 @@
+/**
+ * Webhooks Cryptography & Signature Module
+ * Zero-dependency HMAC-SHA256 signing, constant-time verification & secret generation
+ * @module plugins/webhooks/crypto
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Generate a cryptographically secure webhook signing secret
+ * 
+ * @param {string} [prefix='whsec_'] 
+ * @param {number} [byteLength=24] 
+ * @returns {string} E.g. 'whsec_e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934c'
+ */
+function generateSecret(prefix = 'whsec_', byteLength = 24) {
+  const bytes = crypto.randomBytes(byteLength).toString('hex');
+  return `${prefix || ''}${bytes}`;
+}
+
+/**
+ * Perform constant-time string comparison to prevent timing attacks
+ * 
+ * @param {string} a 
+ * @param {string} b 
+ * @returns {boolean}
+ */
+function safeCompare(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') {
+    return false;
+  }
+  const bufA = Buffer.from(a, 'utf8');
+  const bufB = Buffer.from(b, 'utf8');
+  if (bufA.length !== bufB.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Sign a webhook payload using HMAC-SHA256
+ * 
+ * @param {string|Object} payload - Raw payload string or serializable object
+ * @param {string} secret - Secret key used for signing
+ * @param {Object} [options]
+ * @param {number} [options.timestamp] - Unix timestamp in seconds
+ * @returns {{ signature: string, timestampedSignature: string, timestamp: number, hex: string }}
+ */
+function signPayload(payload, secret, options = {}) {
+  if (!secret || typeof secret !== 'string') {
+    throw new Error('A valid string secret is required to sign webhook payloads.');
+  }
+
+  const payloadStr = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  const timestamp = typeof options.timestamp === 'number'
+    ? options.timestamp
+    : Math.floor(Date.now() / 1000);
+
+  // 1. Direct payload HMAC-SHA256 (compatible with GitHub / standard webhooks)
+  const hex = crypto.createHmac('sha256', secret).update(payloadStr, 'utf8').digest('hex');
+  const signature = `sha256=${hex}`;
+
+  // 2. Timestamped HMAC-SHA256 (compatible with Stripe / Svix / Slack)
+  const toSign = `${timestamp}.${payloadStr}`;
+  const timestampedHex = crypto.createHmac('sha256', secret).update(toSign, 'utf8').digest('hex');
+  const timestampedSignature = `t=${timestamp},v1=${timestampedHex}`;
+
+  return {
+    signature,
+    timestampedSignature,
+    timestamp,
+    hex,
+  };
+}
+
+/**
+ * Verify a webhook payload against an incoming signature header
+ * 
+ * @param {string|Object} payload 
+ * @param {string} signatureHeader 
+ * @param {string} secret 
+ * @param {Object} [options]
+ * @param {number} [options.tolerance=300] - Allowed timestamp drift in seconds (default 5 minutes)
+ * @returns {boolean}
+ */
+function verifySignature(payload, signatureHeader, secret, options = {}) {
+  if (!signatureHeader || typeof signatureHeader !== 'string' || !secret) {
+    return false;
+  }
+
+  const payloadStr = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  const tolerance = options.tolerance !== undefined ? options.tolerance : 300;
+
+  // Case A: Timestamped header format (t=1234567890,v1=abcdef...)
+  if (signatureHeader.includes('t=') && signatureHeader.includes('v1=')) {
+    const parts = signatureHeader.split(',');
+    let timestamp = null;
+    const signatures = [];
+
+    for (const part of parts) {
+      const [key, val] = part.trim().split('=');
+      if (key === 't') {
+        timestamp = parseInt(val, 10);
+      } else if (key === 'v1' && val) {
+        signatures.push(val);
+      }
+    }
+
+    if (!timestamp || isNaN(timestamp) || signatures.length === 0) {
+      return false;
+    }
+
+    // Check tolerance if enabled
+    if (tolerance > 0) {
+      const now = Math.floor(Date.now() / 1000);
+      if (Math.abs(now - timestamp) > tolerance) {
+        return false;
+      }
+    }
+
+    const toSign = `${timestamp}.${payloadStr}`;
+    const expectedHex = crypto.createHmac('sha256', secret).update(toSign, 'utf8').digest('hex');
+
+    return signatures.some((sig) => safeCompare(sig, expectedHex));
+  }
+
+  // Case B: Simple format (sha256=abcdef... or raw hex)
+  let receivedHex = signatureHeader.trim();
+  if (receivedHex.startsWith('sha256=')) {
+    receivedHex = receivedHex.slice(7);
+  }
+
+  const expectedHex = crypto.createHmac('sha256', secret).update(payloadStr, 'utf8').digest('hex');
+  return safeCompare(receivedHex, expectedHex);
+}
+
+module.exports = {
+  generateSecret,
+  safeCompare,
+  signPayload,
+  verifySignature,
+};