@hookflo/tern 1.0.0

package/dist/index.js

@@ -0,0 +1,142 @@
+"use strict";
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCustomVerifier = exports.createAlgorithmVerifier = exports.validateSignatureConfig = exports.getPlatformsUsingAlgorithm = exports.platformUsesAlgorithm = exports.getPlatformAlgorithmConfig = exports.WebhookVerificationService = void 0;
+const algorithms_1 = require("./verifiers/algorithms");
+const custom_algorithms_1 = require("./verifiers/custom-algorithms");
+const algorithms_2 = require("./platforms/algorithms");
+class WebhookVerificationService {
+    static async verify(request, config) {
+        const verifier = this.getVerifier(config);
+        return await verifier.verify(request);
+    }
+    static getVerifier(config) {
+        const platform = config.platform.toLowerCase();
+        // If a custom signature config is provided, use the new algorithm-based framework
+        if (config.signatureConfig) {
+            return this.createAlgorithmBasedVerifier(config);
+        }
+        // Fallback to platform-specific verifiers for backward compatibility
+        return this.getLegacyVerifier(config);
+    }
+    static createAlgorithmBasedVerifier(config) {
+        const { signatureConfig, secret, toleranceInSeconds = 300 } = config;
+        if (!signatureConfig) {
+            throw new Error('Signature config is required for algorithm-based verification');
+        }
+        // Use custom verifiers for special cases
+        if (signatureConfig.algorithm === 'custom') {
+            return (0, custom_algorithms_1.createCustomVerifier)(secret, signatureConfig, toleranceInSeconds);
+        }
+        // Use algorithm-based verifiers for standard algorithms
+        return (0, algorithms_1.createAlgorithmVerifier)(secret, signatureConfig, toleranceInSeconds);
+    }
+    static getLegacyVerifier(config) {
+        const platform = config.platform.toLowerCase();
+        // For legacy support, we'll use the algorithm-based approach
+        const platformConfig = (0, algorithms_2.getPlatformAlgorithmConfig)(platform);
+        const configWithSignature = {
+            ...config,
+            signatureConfig: platformConfig.signatureConfig,
+        };
+        return this.createAlgorithmBasedVerifier(configWithSignature);
+    }
+    // New method to create verifier using platform algorithm config
+    static async verifyWithPlatformConfig(request, platform, secret, toleranceInSeconds = 300) {
+        const platformConfig = (0, algorithms_2.getPlatformAlgorithmConfig)(platform);
+        const config = {
+            platform,
+            secret,
+            toleranceInSeconds,
+            signatureConfig: platformConfig.signatureConfig,
+        };
+        return await this.verify(request, config);
+    }
+    // Helper method to get all platforms using a specific algorithm
+    static getPlatformsUsingAlgorithm(algorithm) {
+        const { getPlatformsUsingAlgorithm } = require('./platforms/algorithms');
+        return getPlatformsUsingAlgorithm(algorithm);
+    }
+    // Helper method to check if a platform uses a specific algorithm
+    static platformUsesAlgorithm(platform, algorithm) {
+        const { platformUsesAlgorithm } = require('./platforms/algorithms');
+        return platformUsesAlgorithm(platform, algorithm);
+    }
+    // Helper method to validate signature config
+    static validateSignatureConfig(config) {
+        const { validateSignatureConfig } = require('./platforms/algorithms');
+        return validateSignatureConfig(config);
+    }
+    // Simple token-based verification for platforms like Supabase
+    static async verifyTokenBased(request, webhookId, webhookToken) {
+        try {
+            const idHeader = request.headers.get('x-webhook-id');
+            const tokenHeader = request.headers.get('x-webhook-token');
+            if (!idHeader || !tokenHeader) {
+                return {
+                    isValid: false,
+                    error: 'Missing required headers: x-webhook-id and x-webhook-token',
+                    platform: 'custom',
+                };
+            }
+            // Simple comparison - we don't actually verify, just check if tokens match
+            const isValid = idHeader === webhookId && tokenHeader === webhookToken;
+            if (!isValid) {
+                return {
+                    isValid: false,
+                    error: 'Invalid webhook ID or token',
+                    platform: 'custom',
+                };
+            }
+            const rawBody = await request.text();
+            let payload;
+            try {
+                payload = JSON.parse(rawBody);
+            }
+            catch (e) {
+                payload = rawBody;
+            }
+            return {
+                isValid: true,
+                platform: 'custom',
+                payload,
+                metadata: {
+                    id: idHeader,
+                    algorithm: 'token-based',
+                },
+            };
+        }
+        catch (error) {
+            return {
+                isValid: false,
+                error: `Token-based verification error: ${error.message}`,
+                platform: 'custom',
+            };
+        }
+    }
+}
+exports.WebhookVerificationService = WebhookVerificationService;
+__exportStar(require("./types"), exports);
+var algorithms_3 = require("./platforms/algorithms");
+Object.defineProperty(exports, "getPlatformAlgorithmConfig", { enumerable: true, get: function () { return algorithms_3.getPlatformAlgorithmConfig; } });
+Object.defineProperty(exports, "platformUsesAlgorithm", { enumerable: true, get: function () { return algorithms_3.platformUsesAlgorithm; } });
+Object.defineProperty(exports, "getPlatformsUsingAlgorithm", { enumerable: true, get: function () { return algorithms_3.getPlatformsUsingAlgorithm; } });
+Object.defineProperty(exports, "validateSignatureConfig", { enumerable: true, get: function () { return algorithms_3.validateSignatureConfig; } });
+var algorithms_4 = require("./verifiers/algorithms");
+Object.defineProperty(exports, "createAlgorithmVerifier", { enumerable: true, get: function () { return algorithms_4.createAlgorithmVerifier; } });
+var custom_algorithms_2 = require("./verifiers/custom-algorithms");
+Object.defineProperty(exports, "createCustomVerifier", { enumerable: true, get: function () { return custom_algorithms_2.createCustomVerifier; } });
+exports.default = WebhookVerificationService;

package/dist/platforms/algorithms.d.ts

@@ -0,0 +1,6 @@
+import { PlatformAlgorithmConfig, WebhookPlatform, SignatureConfig } from "../types";
+export declare const platformAlgorithmConfigs: Record<WebhookPlatform, PlatformAlgorithmConfig>;
+export declare function getPlatformAlgorithmConfig(platform: WebhookPlatform): PlatformAlgorithmConfig;
+export declare function platformUsesAlgorithm(platform: WebhookPlatform, algorithm: string): boolean;
+export declare function getPlatformsUsingAlgorithm(algorithm: string): WebhookPlatform[];
+export declare function validateSignatureConfig(config: SignatureConfig): boolean;

package/dist/platforms/algorithms.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.platformAlgorithmConfigs = void 0;
+exports.getPlatformAlgorithmConfig = getPlatformAlgorithmConfig;
+exports.platformUsesAlgorithm = platformUsesAlgorithm;
+exports.getPlatformsUsingAlgorithm = getPlatformsUsingAlgorithm;
+exports.validateSignatureConfig = validateSignatureConfig;
+// Platform to algorithm mapping configuration
+exports.platformAlgorithmConfigs = {
+    // GitHub uses HMAC-SHA256 with prefixed signature
+    github: {
+        platform: "github",
+        signatureConfig: {
+            algorithm: "hmac-sha256",
+            headerName: "x-hub-signature-256",
+            headerFormat: "prefixed",
+            prefix: "sha256=",
+            timestampHeader: undefined, // GitHub doesn't use timestamp validation
+            payloadFormat: "raw",
+        },
+        description: "GitHub webhooks use HMAC-SHA256 with sha256= prefix",
+    },
+    // Stripe uses HMAC-SHA256 with comma-separated format
+    stripe: {
+        platform: "stripe",
+        signatureConfig: {
+            algorithm: "hmac-sha256",
+            headerName: "stripe-signature",
+            headerFormat: "comma-separated",
+            timestampHeader: undefined, // Timestamp is embedded in signature
+            payloadFormat: "timestamped",
+            customConfig: {
+                signatureFormat: "t={timestamp},v1={signature}",
+            },
+        },
+        description: "Stripe webhooks use HMAC-SHA256 with comma-separated format",
+    },
+    // Clerk uses HMAC-SHA256 with custom base64 encoding
+    clerk: {
+        platform: "clerk",
+        signatureConfig: {
+            algorithm: "custom",
+            headerName: "svix-signature",
+            headerFormat: "raw",
+            timestampHeader: "svix-timestamp",
+            timestampFormat: "unix",
+            payloadFormat: "custom",
+            customConfig: {
+                type: "clerk-custom",
+                signatureFormat: "v1={signature}",
+                payloadFormat: "{id}.{timestamp}.{body}",
+                encoding: "base64",
+            },
+        },
+        description: "Clerk webhooks use HMAC-SHA256 with base64 encoding",
+    },
+    // Dodo Payments uses HMAC-SHA256
+    dodopayments: {
+        platform: "dodopayments",
+        signatureConfig: {
+            algorithm: "hmac-sha256",
+            headerName: "webhook-signature",
+            headerFormat: "raw",
+            timestampHeader: "webhook-timestamp",
+            timestampFormat: "unix",
+            payloadFormat: "raw",
+        },
+        description: "Dodo Payments webhooks use HMAC-SHA256",
+    },
+    // Shopify uses HMAC-SHA256
+    shopify: {
+        platform: "shopify",
+        signatureConfig: {
+            algorithm: "hmac-sha256",
+            headerName: "x-shopify-hmac-sha256",
+            headerFormat: "raw",
+            timestampHeader: "x-shopify-shop-domain",
+            payloadFormat: "raw",
+        },
+        description: "Shopify webhooks use HMAC-SHA256",
+    },
+    // Vercel uses HMAC-SHA256
+    vercel: {
+        platform: "vercel",
+        signatureConfig: {
+            algorithm: "hmac-sha256",
+            headerName: "x-vercel-signature",
+            headerFormat: "raw",
+            timestampHeader: "x-vercel-timestamp",
+            timestampFormat: "unix",
+            payloadFormat: "raw",
+        },
+        description: "Vercel webhooks use HMAC-SHA256",
+    },
+    // Polar uses HMAC-SHA256
+    polar: {
+        platform: "polar",
+        signatureConfig: {
+            algorithm: "hmac-sha256",
+            headerName: "x-polar-signature",
+            headerFormat: "raw",
+            timestampHeader: "x-polar-timestamp",
+            timestampFormat: "unix",
+            payloadFormat: "raw",
+        },
+        description: "Polar webhooks use HMAC-SHA256",
+    },
+    // Supabase uses simple token-based authentication
+    supabase: {
+        platform: "supabase",
+        signatureConfig: {
+            algorithm: "custom",
+            headerName: "x-webhook-token",
+            headerFormat: "raw",
+            payloadFormat: "raw",
+            customConfig: {
+                type: "token-based",
+                idHeader: "x-webhook-id",
+            },
+        },
+        description: "Supabase webhooks use token-based authentication",
+    },
+    // Custom platform - can be configured per instance
+    custom: {
+        platform: "custom",
+        signatureConfig: {
+            algorithm: "hmac-sha256",
+            headerName: "x-webhook-token",
+            headerFormat: "raw",
+            payloadFormat: "raw",
+        },
+        description: "Custom webhook configuration",
+    },
+    // Unknown platform - fallback
+    unknown: {
+        platform: "unknown",
+        signatureConfig: {
+            algorithm: "hmac-sha256",
+            headerName: "x-webhook-signature",
+            headerFormat: "raw",
+            payloadFormat: "raw",
+        },
+        description: "Unknown platform - using default HMAC-SHA256",
+    },
+};
+// Helper function to get algorithm config for a platform
+function getPlatformAlgorithmConfig(platform) {
+    return exports.platformAlgorithmConfigs[platform] || exports.platformAlgorithmConfigs.unknown;
+}
+// Helper function to check if a platform uses a specific algorithm
+function platformUsesAlgorithm(platform, algorithm) {
+    const config = getPlatformAlgorithmConfig(platform);
+    return config.signatureConfig.algorithm === algorithm;
+}
+// Helper function to get all platforms using a specific algorithm
+function getPlatformsUsingAlgorithm(algorithm) {
+    return Object.entries(exports.platformAlgorithmConfigs)
+        .filter(([_, config]) => config.signatureConfig.algorithm === algorithm)
+        .map(([platform, _]) => platform);
+}
+// Helper function to validate signature config
+function validateSignatureConfig(config) {
+    if (!config.algorithm || !config.headerName) {
+        return false;
+    }
+    // Validate algorithm-specific requirements
+    switch (config.algorithm) {
+        case "hmac-sha256":
+        case "hmac-sha1":
+        case "hmac-sha512":
+            return true; // These algorithms only need headerName
+        case "rsa-sha256":
+        case "ed25519":
+            return !!config.customConfig?.publicKey; // These need public key
+        case "custom":
+            return !!config.customConfig; // Custom needs custom config
+        default:
+            return false;
+    }
+}

package/dist/test-compiled.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test-compiled.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const test_1 = require("./test");
+(0, test_1.runAllTests)().catch(console.error);

package/dist/test.d.ts

@@ -0,0 +1,6 @@
+declare function testGitHubWebhook(): Promise<import("./types").WebhookVerificationResult>;
+declare function testTokenBasedWebhook(): Promise<import("./types").WebhookVerificationResult>;
+declare function testPlatformDetection(): void;
+declare function testCustomSignature(): Promise<import("./types").WebhookVerificationResult>;
+export declare function runAllTests(): Promise<void>;
+export { testGitHubWebhook, testTokenBasedWebhook, testPlatformDetection, testCustomSignature, };

package/dist/test.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAllTests = runAllTests;
+exports.testGitHubWebhook = testGitHubWebhook;
+exports.testTokenBasedWebhook = testTokenBasedWebhook;
+exports.testPlatformDetection = testPlatformDetection;
+exports.testCustomSignature = testCustomSignature;
+const index_1 = require("./index");
+const utils_1 = require("./utils");
+// Mock request for testing
+function createMockRequest(headers, body = '{"test": "data"}') {
+    return new Request('http://localhost/webhook', {
+        method: 'POST',
+        headers,
+        body,
+    });
+}
+// Test GitHub webhook
+async function testGitHubWebhook() {
+    console.log('Testing GitHub webhook...');
+    const request = createMockRequest({
+        'x-hub-signature-256': 'sha256=abc123',
+        'content-type': 'application/json',
+    });
+    const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'github', 'test-secret', 300);
+    console.log('GitHub result:', result);
+    return result;
+}
+// Test token-based webhook (Supabase style)
+async function testTokenBasedWebhook() {
+    console.log('Testing token-based webhook...');
+    const request = createMockRequest({
+        'x-webhook-id': 'test-webhook-id',
+        'x-webhook-token': 'test-webhook-token',
+        'content-type': 'application/json',
+    });
+    const result = await index_1.WebhookVerificationService.verifyTokenBased(request, 'test-webhook-id', 'test-webhook-token');
+    console.log('Token-based result:', result);
+    return result;
+}
+// Test platform detection
+function testPlatformDetection() {
+    console.log('Testing platform detection...');
+    const testCases = [
+        {
+            name: 'GitHub',
+            headers: { 'x-hub-signature-256': 'sha256=abc123' },
+        },
+        {
+            name: 'Stripe',
+            headers: { 'stripe-signature': 't=1234567890,v1=abc123' },
+        },
+        {
+            name: 'Clerk',
+            headers: { 'svix-signature': 'v1,abc123' },
+        },
+        {
+            name: 'Supabase',
+            headers: { 'x-webhook-token': 'token123' },
+        },
+    ];
+    for (const testCase of testCases) {
+        const request = createMockRequest((0, utils_1.cleanHeaders)(testCase.headers));
+        const detectedPlatform = (0, utils_1.detectPlatformFromHeaders)(request.headers);
+        console.log(`${testCase.name}: ${detectedPlatform}`);
+    }
+}
+// Test custom signature configuration
+async function testCustomSignature() {
+    console.log('Testing custom signature...');
+    const request = createMockRequest({
+        'x-custom-signature': 'sha256=abc123',
+        'content-type': 'application/json',
+    });
+    const result = await index_1.WebhookVerificationService.verify(request, {
+        platform: 'custom',
+        secret: 'custom-secret',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'x-custom-signature',
+            headerFormat: 'prefixed',
+            prefix: 'sha256=',
+            payloadFormat: 'raw',
+        },
+    });
+    console.log('Custom signature result:', result);
+    return result;
+}
+// Run all tests
+async function runAllTests() {
+    console.log('🚀 Running Webhook Verifier Tests\n');
+    try {
+        await testGitHubWebhook();
+        await testTokenBasedWebhook();
+        testPlatformDetection();
+        await testCustomSignature();
+        console.log('\n✅ All tests completed successfully!');
+    }
+    catch (error) {
+        console.error('\n❌ Test failed:', error);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+export type WebhookPlatform = 'custom' | 'clerk' | 'supabase' | 'github' | 'stripe' | 'shopify' | 'vercel' | 'polar' | 'dodopayments' | 'unknown';
+export declare enum WebhookPlatformKeys {
+    GitHub = "github",
+    Stripe = "stripe",
+    Clerk = "clerk",
+    DodoPayments = "dodopayments",
+    Shopify = "shopify",
+    Vercel = "vercel",
+    Polar = "polar",
+    Supabase = "supabase",
+    Custom = "custom",
+    Unknown = "unknown"
+}
+export type SignatureAlgorithm = 'hmac-sha256' | 'hmac-sha1' | 'hmac-sha512' | 'rsa-sha256' | 'ed25519' | 'custom';
+export interface SignatureConfig {
+    algorithm: SignatureAlgorithm;
+    headerName: string;
+    headerFormat?: 'raw' | 'prefixed' | 'comma-separated';
+    prefix?: string;
+    timestampHeader?: string;
+    timestampFormat?: 'unix' | 'iso' | 'custom';
+    payloadFormat?: 'raw' | 'timestamped' | 'custom';
+    customConfig?: Record<string, any>;
+}
+export interface WebhookVerificationResult {
+    isValid: boolean;
+    error?: string;
+    platform: WebhookPlatform;
+    payload?: any;
+    metadata?: {
+        timestamp?: string;
+        id?: string | null;
+        [key: string]: any;
+    };
+}
+export interface WebhookConfig {
+    platform: WebhookPlatform;
+    secret: string;
+    toleranceInSeconds?: number;
+    signatureConfig?: SignatureConfig;
+}
+export interface PlatformAlgorithmConfig {
+    platform: WebhookPlatform;
+    signatureConfig: SignatureConfig;
+    description?: string;
+}
+export interface TokenAuthConfig {
+    webhookId: string;
+    webhookToken: string;
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookPlatformKeys = void 0;
+var WebhookPlatformKeys;
+(function (WebhookPlatformKeys) {
+    WebhookPlatformKeys["GitHub"] = "github";
+    WebhookPlatformKeys["Stripe"] = "stripe";
+    WebhookPlatformKeys["Clerk"] = "clerk";
+    WebhookPlatformKeys["DodoPayments"] = "dodopayments";
+    WebhookPlatformKeys["Shopify"] = "shopify";
+    WebhookPlatformKeys["Vercel"] = "vercel";
+    WebhookPlatformKeys["Polar"] = "polar";
+    WebhookPlatformKeys["Supabase"] = "supabase";
+    WebhookPlatformKeys["Custom"] = "custom";
+    WebhookPlatformKeys["Unknown"] = "unknown";
+})(WebhookPlatformKeys || (exports.WebhookPlatformKeys = WebhookPlatformKeys = {}));

package/dist/utils.d.ts

@@ -0,0 +1,78 @@
+import { WebhookPlatform, SignatureConfig } from './types';
+/**
+ * Utility functions for the scalable webhook verification framework
+ */
+/**
+ * Get the recommended algorithm for a platform
+ */
+export declare function getRecommendedAlgorithm(platform: WebhookPlatform): string;
+/**
+ * Check if a platform supports a specific algorithm
+ */
+export declare function platformSupportsAlgorithm(platform: WebhookPlatform, algorithm: string): boolean;
+/**
+ * Get all platforms that support a specific algorithm
+ */
+export declare function getPlatformsByAlgorithm(algorithm: string): WebhookPlatform[];
+/**
+ * Create a signature config for a platform
+ */
+export declare function createSignatureConfigForPlatform(platform: WebhookPlatform): SignatureConfig;
+/**
+ * Validate a signature config
+ */
+export declare function isValidSignatureConfig(config: SignatureConfig): boolean;
+/**
+ * Get platform description
+ */
+export declare function getPlatformDescription(platform: WebhookPlatform): string;
+/**
+ * Check if a platform uses custom algorithm
+ */
+export declare function isCustomAlgorithm(platform: WebhookPlatform): boolean;
+/**
+ * Get algorithm statistics
+ */
+export declare function getAlgorithmStats(): Record<string, number>;
+/**
+ * Get most common algorithm
+ */
+export declare function getMostCommonAlgorithm(): string;
+/**
+ * Check if a request matches a platform's signature pattern
+ */
+export declare function detectPlatformFromHeaders(headers: Headers): WebhookPlatform | null;
+/**
+ * Get platform configuration summary
+ */
+export declare function getPlatformSummary(): Array<{
+    platform: WebhookPlatform;
+    algorithm: string;
+    description: string;
+    isCustom: boolean;
+}>;
+/**
+ * Compare two signature configs
+ */
+export declare function compareSignatureConfigs(config1: SignatureConfig, config2: SignatureConfig): boolean;
+/**
+ * Clone a signature config
+ */
+export declare function cloneSignatureConfig(config: SignatureConfig): SignatureConfig;
+/**
+ * Merge signature configs (config2 overrides config1)
+ */
+export declare function mergeSignatureConfigs(config1: SignatureConfig, config2: Partial<SignatureConfig>): SignatureConfig;
+/**
+ * Validate platform configuration
+ */
+export declare function validatePlatformConfig(platform: WebhookPlatform): boolean;
+/**
+ * Get all valid platforms
+ */
+export declare function getValidPlatforms(): WebhookPlatform[];
+/**
+ * Get platforms by algorithm type
+ */
+export declare function getPlatformsByAlgorithmType(): Record<string, WebhookPlatform[]>;
+export declare function cleanHeaders(headers: Record<string, string | undefined>): Record<string, string>;