ezthrottle 1.1.1 → 1.4.0

package/dist/webhookUtils.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Webhook utilities for EZThrottle SDK.
+ * Provides HMAC signature verification for secure webhook delivery.
+ */
+/**
+ * Result of webhook signature verification
+ */
+export interface VerificationResult {
+    verified: boolean;
+    reason: string;
+}
+/**
+ * Custom error for webhook verification failures
+ */
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify HMAC-SHA256 signature from X-EZThrottle-Signature header.
+ *
+ * @param payload - Raw webhook payload (request body as Buffer or string)
+ * @param signatureHeader - Value of X-EZThrottle-Signature header
+ * @param secret - Your webhook secret (primary or secondary)
+ * @param tolerance - Maximum age of timestamp in seconds (default: 300 = 5 minutes)
+ * @returns Object with verified boolean and reason string
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { verifyWebhookSignature } from 'ezthrottle';
+ *
+ * const app = express();
+ * const WEBHOOK_SECRET = 'your_webhook_secret';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const signature = req.headers['x-ezthrottle-signature'] as string;
+ *   const { verified, reason } = verifyWebhookSignature(
+ *     req.body,
+ *     signature,
+ *     WEBHOOK_SECRET
+ *   );
+ *
+ *   if (!verified) {
+ *     return res.status(401).json({ error: `Invalid signature: ${reason}` });
+ *   }
+ *
+ *   // Process webhook...
+ *   const data = JSON.parse(req.body.toString());
+ *   console.log(`Job ${data.job_id} completed: ${data.status}`);
+ *
+ *   res.json({ ok: true });
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignature(payload: Buffer | string, signatureHeader: string, secret: string, tolerance?: number): VerificationResult;
+/**
+ * Verify webhook signature and throw exception if invalid.
+ *
+ * @param payload - Raw webhook payload
+ * @param signatureHeader - Value of X-EZThrottle-Signature header
+ * @param secret - Your webhook secret
+ * @param tolerance - Maximum age of timestamp in seconds (default: 300)
+ * @throws {WebhookVerificationError} If signature verification fails
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { verifyWebhookSignatureStrict, WebhookVerificationError } from 'ezthrottle';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   try {
+ *     verifyWebhookSignatureStrict(
+ *       req.body,
+ *       req.headers['x-ezthrottle-signature'] as string,
+ *       WEBHOOK_SECRET
+ *     );
+ *   } catch (error) {
+ *     if (error instanceof WebhookVerificationError) {
+ *       return res.status(401).json({ error: error.message });
+ *     }
+ *     throw error;
+ *   }
+ *
+ *   // Process webhook...
+ *   res.json({ ok: true });
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignatureStrict(payload: Buffer | string, signatureHeader: string, secret: string, tolerance?: number): void;
+/**
+ * Try verifying signature with primary secret, fall back to secondary if provided.
+ * Useful during secret rotation when you have both old and new secrets active.
+ *
+ * @param payload - Raw webhook payload
+ * @param signatureHeader - Value of X-EZThrottle-Signature header
+ * @param primarySecret - Your primary webhook secret
+ * @param secondarySecret - Your secondary webhook secret (optional)
+ * @param tolerance - Maximum age of timestamp in seconds
+ * @returns Object with verified boolean and reason string
+ *
+ * @example
+ * ```typescript
+ * // During secret rotation
+ * const { verified, reason } = tryVerifyWithSecrets(
+ *   req.body,
+ *   req.headers['x-ezthrottle-signature'] as string,
+ *   'new_secret_after_rotation',
+ *   'old_secret_before_rotation'
+ * );
+ *
+ * if (verified) {
+ *   console.log(`Signature verified with ${reason}`); // "valid_primary" or "valid_secondary"
+ * }
+ * ```
+ */
+export declare function tryVerifyWithSecrets(payload: Buffer | string, signatureHeader: string, primarySecret: string, secondarySecret?: string, tolerance?: number): VerificationResult;

package/dist/webhookUtils.js

@@ -0,0 +1,224 @@
+"use strict";
+/**
+ * Webhook utilities for EZThrottle SDK.
+ * Provides HMAC signature verification for secure webhook delivery.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerificationError = void 0;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.verifyWebhookSignatureStrict = verifyWebhookSignatureStrict;
+exports.tryVerifyWithSecrets = tryVerifyWithSecrets;
+const crypto = __importStar(require("crypto"));
+/**
+ * Custom error for webhook verification failures
+ */
+class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WebhookVerificationError';
+    }
+}
+exports.WebhookVerificationError = WebhookVerificationError;
+/**
+ * Verify HMAC-SHA256 signature from X-EZThrottle-Signature header.
+ *
+ * @param payload - Raw webhook payload (request body as Buffer or string)
+ * @param signatureHeader - Value of X-EZThrottle-Signature header
+ * @param secret - Your webhook secret (primary or secondary)
+ * @param tolerance - Maximum age of timestamp in seconds (default: 300 = 5 minutes)
+ * @returns Object with verified boolean and reason string
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { verifyWebhookSignature } from 'ezthrottle';
+ *
+ * const app = express();
+ * const WEBHOOK_SECRET = 'your_webhook_secret';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const signature = req.headers['x-ezthrottle-signature'] as string;
+ *   const { verified, reason } = verifyWebhookSignature(
+ *     req.body,
+ *     signature,
+ *     WEBHOOK_SECRET
+ *   );
+ *
+ *   if (!verified) {
+ *     return res.status(401).json({ error: `Invalid signature: ${reason}` });
+ *   }
+ *
+ *   // Process webhook...
+ *   const data = JSON.parse(req.body.toString());
+ *   console.log(`Job ${data.job_id} completed: ${data.status}`);
+ *
+ *   res.json({ ok: true });
+ * });
+ * ```
+ */
+function verifyWebhookSignature(payload, signatureHeader, secret, tolerance = 300) {
+    if (!signatureHeader) {
+        return { verified: false, reason: 'no_signature_header' };
+    }
+    try {
+        // Parse "t=timestamp,v1=signature" format
+        const parts = {};
+        signatureHeader.split(',').forEach(part => {
+            const [key, value] = part.split('=');
+            if (key && value) {
+                parts[key] = value;
+            }
+        });
+        const timestampStr = parts['t'] || '0';
+        const signature = parts['v1'] || '';
+        if (!signature) {
+            return { verified: false, reason: 'missing_v1_signature' };
+        }
+        // Check timestamp tolerance
+        const now = Math.floor(Date.now() / 1000);
+        const sigTime = parseInt(timestampStr, 10);
+        const timeDiff = Math.abs(now - sigTime);
+        if (timeDiff > tolerance) {
+            return {
+                verified: false,
+                reason: `timestamp_expired (diff=${timeDiff}s, tolerance=${tolerance}s)`
+            };
+        }
+        // Compute expected signature
+        const payloadStr = Buffer.isBuffer(payload) ? payload.toString('utf-8') : payload;
+        const signedPayload = `${timestampStr}.${payloadStr}`;
+        const expected = crypto
+            .createHmac('sha256', secret)
+            .update(signedPayload)
+            .digest('hex');
+        // Constant-time comparison
+        if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+            return { verified: true, reason: 'valid' };
+        }
+        else {
+            return { verified: false, reason: 'signature_mismatch' };
+        }
+    }
+    catch (error) {
+        return {
+            verified: false,
+            reason: `verification_error: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+}
+/**
+ * Verify webhook signature and throw exception if invalid.
+ *
+ * @param payload - Raw webhook payload
+ * @param signatureHeader - Value of X-EZThrottle-Signature header
+ * @param secret - Your webhook secret
+ * @param tolerance - Maximum age of timestamp in seconds (default: 300)
+ * @throws {WebhookVerificationError} If signature verification fails
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { verifyWebhookSignatureStrict, WebhookVerificationError } from 'ezthrottle';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   try {
+ *     verifyWebhookSignatureStrict(
+ *       req.body,
+ *       req.headers['x-ezthrottle-signature'] as string,
+ *       WEBHOOK_SECRET
+ *     );
+ *   } catch (error) {
+ *     if (error instanceof WebhookVerificationError) {
+ *       return res.status(401).json({ error: error.message });
+ *     }
+ *     throw error;
+ *   }
+ *
+ *   // Process webhook...
+ *   res.json({ ok: true });
+ * });
+ * ```
+ */
+function verifyWebhookSignatureStrict(payload, signatureHeader, secret, tolerance = 300) {
+    const { verified, reason } = verifyWebhookSignature(payload, signatureHeader, secret, tolerance);
+    if (!verified) {
+        throw new WebhookVerificationError(`Webhook signature verification failed: ${reason}`);
+    }
+}
+/**
+ * Try verifying signature with primary secret, fall back to secondary if provided.
+ * Useful during secret rotation when you have both old and new secrets active.
+ *
+ * @param payload - Raw webhook payload
+ * @param signatureHeader - Value of X-EZThrottle-Signature header
+ * @param primarySecret - Your primary webhook secret
+ * @param secondarySecret - Your secondary webhook secret (optional)
+ * @param tolerance - Maximum age of timestamp in seconds
+ * @returns Object with verified boolean and reason string
+ *
+ * @example
+ * ```typescript
+ * // During secret rotation
+ * const { verified, reason } = tryVerifyWithSecrets(
+ *   req.body,
+ *   req.headers['x-ezthrottle-signature'] as string,
+ *   'new_secret_after_rotation',
+ *   'old_secret_before_rotation'
+ * );
+ *
+ * if (verified) {
+ *   console.log(`Signature verified with ${reason}`); // "valid_primary" or "valid_secondary"
+ * }
+ * ```
+ */
+function tryVerifyWithSecrets(payload, signatureHeader, primarySecret, secondarySecret, tolerance = 300) {
+    // Try primary secret first
+    const primaryResult = verifyWebhookSignature(payload, signatureHeader, primarySecret, tolerance);
+    if (primaryResult.verified) {
+        return { verified: true, reason: 'valid_primary' };
+    }
+    // Try secondary secret if provided
+    if (secondarySecret) {
+        const secondaryResult = verifyWebhookSignature(payload, signatureHeader, secondarySecret, tolerance);
+        if (secondaryResult.verified) {
+            return { verified: true, reason: 'valid_secondary' };
+        }
+    }
+    return {
+        verified: false,
+        reason: `both_secrets_failed (primary: ${primaryResult.reason})`
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ezthrottle",
-  "version": "1.1.1",
+  "version": "1.4.0",
   "description": "Node.js SDK for EZThrottle - The API Dam for rate-limited services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,7 +21,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/rjpruitt16/ezthrottle-node"
+    "url": "git+https://github.com/rjpruitt16/ezthrottle-node.git"
   },
   "files": [
     "dist",
@@ -29,7 +29,7 @@
   ],
   "dependencies": {
     "node-fetch": "^2.7.0",
-    "uuid": "^8.3.2"
+    "uuid": "8.3.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",