swiftshopr-payments 1.0.0

package/src/webhooks.js

@@ -0,0 +1,163 @@
+/**
+ * Webhooks Module
+ * Helpers for receiving and verifying SwiftShopr webhooks
+ */
+
+const crypto = require('crypto');
+const { SwiftShoprError } = require('./utils/http');
+
+/**
+ * Webhook event types
+ */
+const WebhookEvents = {
+  PAYMENT_COMPLETED: 'payment.completed',
+  PAYMENT_FAILED: 'payment.failed',
+  PAYMENT_EXPIRED: 'payment.expired',
+  REFUND_REQUESTED: 'refund.requested',
+  REFUND_COMPLETED: 'refund.completed',
+  REFUND_FAILED: 'refund.failed',
+};
+
+/**
+ * Maximum age of webhook timestamp (5 minutes)
+ */
+const MAX_TIMESTAMP_AGE_MS = 5 * 60 * 1000;
+
+/**
+ * Create Webhooks helper instance
+ */
+function createWebhooksHelper(webhookSecret) {
+  /**
+   * Verify webhook signature
+   *
+   * @param {string|Object} payload - Raw request body (string) or parsed JSON
+   * @param {string} signature - X-Webhook-Signature header
+   * @param {string} timestamp - X-Webhook-Timestamp header
+   * @returns {boolean} True if signature is valid
+   */
+  function verify(payload, signature, timestamp) {
+    if (!webhookSecret) {
+      throw new SwiftShoprError(
+        'CONFIG_ERROR',
+        'Webhook secret is required for verification',
+      );
+    }
+
+    if (!payload || !signature || !timestamp) {
+      return false;
+    }
+
+    // Check timestamp is not too old (replay attack prevention)
+    const timestampMs = parseInt(timestamp, 10);
+    if (isNaN(timestampMs)) {
+      return false;
+    }
+
+    const age = Date.now() - timestampMs;
+    if (age > MAX_TIMESTAMP_AGE_MS || age < -MAX_TIMESTAMP_AGE_MS) {
+      return false;
+    }
+
+    // Compute expected signature
+    const payloadString =
+      typeof payload === 'string' ? payload : JSON.stringify(payload);
+    const signaturePayload = `${timestamp}.${payloadString}`;
+
+    const expectedSignature = crypto
+      .createHmac('sha256', webhookSecret)
+      .update(signaturePayload)
+      .digest('hex');
+
+    // Constant-time comparison
+    try {
+      return crypto.timingSafeEqual(
+        Buffer.from(signature),
+        Buffer.from(expectedSignature),
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Parse and verify webhook event
+   *
+   * @param {string|Object} payload - Raw request body
+   * @param {Object} headers - Request headers
+   * @returns {Object} Parsed and verified webhook event
+   * @throws {SwiftShoprError} If verification fails
+   */
+  function constructEvent(payload, headers) {
+    const signature =
+      headers['x-webhook-signature'] || headers['X-Webhook-Signature'];
+    const timestamp =
+      headers['x-webhook-timestamp'] || headers['X-Webhook-Timestamp'];
+
+    if (!verify(payload, signature, timestamp)) {
+      throw new SwiftShoprError(
+        'WEBHOOK_SIGNATURE_INVALID',
+        'Webhook signature verification failed',
+      );
+    }
+
+    const event = typeof payload === 'string' ? JSON.parse(payload) : payload;
+
+    return {
+      type: event.event,
+      data: {
+        intentId: event.intentId,
+        orderId: event.orderId,
+        txHash: event.txHash,
+        amount: event.amount,
+        status: event.status,
+        currency: event.currency,
+        network: event.network,
+        explorerUrl: event.explorerUrl,
+        storeId: event.storeId,
+        timestamp: event.timestamp,
+        // Refund-specific fields
+        refundId: event.refundId,
+        refundAmount: event.refundAmount,
+        refundReason: event.refundReason,
+      },
+      receivedAt: new Date().toISOString(),
+    };
+  }
+
+  return {
+    verify,
+    constructEvent,
+    events: WebhookEvents,
+  };
+}
+
+/**
+ * Express middleware for webhook verification
+ *
+ * @param {string} secret - Webhook secret
+ * @returns {Function} Express middleware
+ */
+function webhookMiddleware(secret) {
+  const helper = createWebhooksHelper(secret);
+
+  return (req, res, next) => {
+    try {
+      // Need raw body for signature verification
+      const payload = req.rawBody || req.body;
+      const event = helper.constructEvent(payload, req.headers);
+      req.webhookEvent = event;
+      next();
+    } catch (error) {
+      res.status(400).json({
+        error: 'webhook_verification_failed',
+        message: error.message,
+      });
+    }
+  };
+}
+
+module.exports = {
+  createWebhooksHelper,
+  webhookMiddleware,
+  WebhookEvents,
+};