@hookflo/tern 1.0.0

package/dist/utils.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRecommendedAlgorithm = getRecommendedAlgorithm;
+exports.platformSupportsAlgorithm = platformSupportsAlgorithm;
+exports.getPlatformsByAlgorithm = getPlatformsByAlgorithm;
+exports.createSignatureConfigForPlatform = createSignatureConfigForPlatform;
+exports.isValidSignatureConfig = isValidSignatureConfig;
+exports.getPlatformDescription = getPlatformDescription;
+exports.isCustomAlgorithm = isCustomAlgorithm;
+exports.getAlgorithmStats = getAlgorithmStats;
+exports.getMostCommonAlgorithm = getMostCommonAlgorithm;
+exports.detectPlatformFromHeaders = detectPlatformFromHeaders;
+exports.getPlatformSummary = getPlatformSummary;
+exports.compareSignatureConfigs = compareSignatureConfigs;
+exports.cloneSignatureConfig = cloneSignatureConfig;
+exports.mergeSignatureConfigs = mergeSignatureConfigs;
+exports.validatePlatformConfig = validatePlatformConfig;
+exports.getValidPlatforms = getValidPlatforms;
+exports.getPlatformsByAlgorithmType = getPlatformsByAlgorithmType;
+exports.cleanHeaders = cleanHeaders;
+const types_1 = require("./types");
+const algorithms_1 = require("./platforms/algorithms");
+/**
+ * Utility functions for the scalable webhook verification framework
+ */
+/**
+ * Get the recommended algorithm for a platform
+ */
+function getRecommendedAlgorithm(platform) {
+    const config = (0, algorithms_1.getPlatformAlgorithmConfig)(platform);
+    return config.signatureConfig.algorithm;
+}
+/**
+ * Check if a platform supports a specific algorithm
+ */
+function platformSupportsAlgorithm(platform, algorithm) {
+    const config = (0, algorithms_1.getPlatformAlgorithmConfig)(platform);
+    return config.signatureConfig.algorithm === algorithm;
+}
+/**
+ * Get all platforms that support a specific algorithm
+ */
+function getPlatformsByAlgorithm(algorithm) {
+    const { getPlatformsUsingAlgorithm } = require('./platforms/algorithms');
+    return getPlatformsUsingAlgorithm(algorithm);
+}
+/**
+ * Create a signature config for a platform
+ */
+function createSignatureConfigForPlatform(platform) {
+    const config = (0, algorithms_1.getPlatformAlgorithmConfig)(platform);
+    return config.signatureConfig;
+}
+/**
+ * Validate a signature config
+ */
+function isValidSignatureConfig(config) {
+    return (0, algorithms_1.validateSignatureConfig)(config);
+}
+/**
+ * Get platform description
+ */
+function getPlatformDescription(platform) {
+    const config = (0, algorithms_1.getPlatformAlgorithmConfig)(platform);
+    return config.description || `Webhook verification for ${platform}`;
+}
+/**
+ * Check if a platform uses custom algorithm
+ */
+function isCustomAlgorithm(platform) {
+    const config = (0, algorithms_1.getPlatformAlgorithmConfig)(platform);
+    return config.signatureConfig.algorithm === 'custom';
+}
+/**
+ * Get algorithm statistics
+ */
+function getAlgorithmStats() {
+    const platforms = Object.values(types_1.WebhookPlatformKeys);
+    const stats = {};
+    for (const platform of platforms) {
+        const config = (0, algorithms_1.getPlatformAlgorithmConfig)(platform);
+        const { algorithm } = config.signatureConfig;
+        stats[algorithm] = (stats[algorithm] || 0) + 1;
+    }
+    return stats;
+}
+/**
+ * Get most common algorithm
+ */
+function getMostCommonAlgorithm() {
+    const stats = getAlgorithmStats();
+    return Object.entries(stats).reduce((a, b) => (stats[a[0]] > stats[b[0]] ? a : b))[0];
+}
+/**
+ * Check if a request matches a platform's signature pattern
+ */
+function detectPlatformFromHeaders(headers) {
+    const headerMap = new Map();
+    headers.forEach((value, key) => {
+        headerMap.set(key.toLowerCase(), value);
+    });
+    // GitHub
+    if (headerMap.has('x-hub-signature-256')) {
+        return 'github';
+    }
+    // Stripe
+    if (headerMap.has('stripe-signature')) {
+        return 'stripe';
+    }
+    // Clerk
+    if (headerMap.has('svix-signature')) {
+        return 'clerk';
+    }
+    // Dodo Payments
+    if (headerMap.has('webhook-signature')) {
+        return 'dodopayments';
+    }
+    // Shopify
+    if (headerMap.has('x-shopify-hmac-sha256')) {
+        return 'shopify';
+    }
+    // Vercel
+    if (headerMap.has('x-vercel-signature')) {
+        return 'vercel';
+    }
+    // Polar
+    if (headerMap.has('x-polar-signature')) {
+        return 'polar';
+    }
+    // Supabase
+    if (headerMap.has('x-webhook-token')) {
+        return 'supabase';
+    }
+    return null;
+}
+/**
+ * Get platform configuration summary
+ */
+function getPlatformSummary() {
+    const platforms = Object.values(types_1.WebhookPlatformKeys);
+    return platforms.map((platform) => {
+        const config = (0, algorithms_1.getPlatformAlgorithmConfig)(platform);
+        return {
+            platform,
+            algorithm: config.signatureConfig.algorithm,
+            description: config.description || '',
+            isCustom: config.signatureConfig.algorithm === 'custom',
+        };
+    });
+}
+/**
+ * Compare two signature configs
+ */
+function compareSignatureConfigs(config1, config2) {
+    return JSON.stringify(config1) === JSON.stringify(config2);
+}
+/**
+ * Clone a signature config
+ */
+function cloneSignatureConfig(config) {
+    return JSON.parse(JSON.stringify(config));
+}
+/**
+ * Merge signature configs (config2 overrides config1)
+ */
+function mergeSignatureConfigs(config1, config2) {
+    return { ...config1, ...config2 };
+}
+/**
+ * Validate platform configuration
+ */
+function validatePlatformConfig(platform) {
+    try {
+        const config = (0, algorithms_1.getPlatformAlgorithmConfig)(platform);
+        return (0, algorithms_1.validateSignatureConfig)(config.signatureConfig);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get all valid platforms
+ */
+function getValidPlatforms() {
+    const platforms = Object.values(types_1.WebhookPlatformKeys);
+    return platforms.filter((platform) => validatePlatformConfig(platform));
+}
+/**
+ * Get platforms by algorithm type
+ */
+function getPlatformsByAlgorithmType() {
+    const platforms = Object.values(types_1.WebhookPlatformKeys);
+    const result = {};
+    for (const platform of platforms) {
+        const config = (0, algorithms_1.getPlatformAlgorithmConfig)(platform);
+        const { algorithm } = config.signatureConfig;
+        if (!result[algorithm]) {
+            result[algorithm] = [];
+        }
+        result[algorithm].push(platform);
+    }
+    return result;
+}
+function cleanHeaders(headers) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (value !== undefined) {
+            cleaned[key] = value;
+        }
+    }
+    return cleaned;
+}

package/dist/verifiers/algorithms.d.ts

@@ -0,0 +1,22 @@
+import { WebhookVerifier } from "./base";
+import { WebhookVerificationResult, SignatureConfig } from "../types";
+export declare abstract class AlgorithmBasedVerifier extends WebhookVerifier {
+    protected config: SignatureConfig;
+    constructor(secret: string, config: SignatureConfig, toleranceInSeconds?: number);
+    abstract verify(request: Request): Promise<WebhookVerificationResult>;
+    protected extractSignature(request: Request): string | null;
+    protected extractTimestamp(request: Request): number | null;
+    protected formatPayload(rawBody: string, timestamp?: number | null): string;
+    protected verifyHMAC(payload: string, signature: string, algorithm?: string): boolean;
+    protected verifyHMACWithPrefix(payload: string, signature: string, algorithm?: string): boolean;
+}
+export declare class HMACSHA256Verifier extends AlgorithmBasedVerifier {
+    verify(request: Request): Promise<WebhookVerificationResult>;
+}
+export declare class HMACSHA1Verifier extends AlgorithmBasedVerifier {
+    verify(request: Request): Promise<WebhookVerificationResult>;
+}
+export declare class HMACSHA512Verifier extends AlgorithmBasedVerifier {
+    verify(request: Request): Promise<WebhookVerificationResult>;
+}
+export declare function createAlgorithmVerifier(secret: string, config: SignatureConfig, toleranceInSeconds?: number): AlgorithmBasedVerifier;

package/dist/verifiers/algorithms.js

@@ -0,0 +1,273 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HMACSHA512Verifier = exports.HMACSHA1Verifier = exports.HMACSHA256Verifier = exports.AlgorithmBasedVerifier = void 0;
+exports.createAlgorithmVerifier = createAlgorithmVerifier;
+const crypto_1 = require("crypto");
+const base_1 = require("./base");
+class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
+    constructor(secret, config, toleranceInSeconds = 300) {
+        super(secret, toleranceInSeconds);
+        this.config = config;
+    }
+    extractSignature(request) {
+        const headerValue = request.headers.get(this.config.headerName);
+        if (!headerValue)
+            return null;
+        switch (this.config.headerFormat) {
+            case "prefixed":
+                return headerValue.startsWith(this.config.prefix || "")
+                    ? headerValue.substring((this.config.prefix || "").length)
+                    : null;
+            case "comma-separated":
+                // Handle comma-separated format like Stripe: "t=1234567890,v1=abc123"
+                const parts = headerValue.split(",");
+                const sigMap = {};
+                for (const part of parts) {
+                    const [key, value] = part.split("=");
+                    if (key && value) {
+                        sigMap[key] = value;
+                    }
+                }
+                return sigMap.v1 || sigMap.signature || null;
+            case "raw":
+            default:
+                return headerValue;
+        }
+    }
+    extractTimestamp(request) {
+        if (!this.config.timestampHeader)
+            return null;
+        const timestampHeader = request.headers.get(this.config.timestampHeader);
+        if (!timestampHeader)
+            return null;
+        switch (this.config.timestampFormat) {
+            case "unix":
+                return parseInt(timestampHeader, 10);
+            case "iso":
+                return Math.floor(new Date(timestampHeader).getTime() / 1000);
+            case "custom":
+                // Custom timestamp parsing logic can be added here
+                return parseInt(timestampHeader, 10);
+            default:
+                return parseInt(timestampHeader, 10);
+        }
+    }
+    formatPayload(rawBody, timestamp) {
+        switch (this.config.payloadFormat) {
+            case "timestamped":
+                return timestamp ? `${timestamp}.${rawBody}` : rawBody;
+            case "custom":
+                // Custom payload formatting logic can be added here
+                return rawBody;
+            case "raw":
+            default:
+                return rawBody;
+        }
+    }
+    verifyHMAC(payload, signature, algorithm = "sha256") {
+        const hmac = (0, crypto_1.createHmac)(algorithm, this.secret);
+        hmac.update(payload);
+        const expectedSignature = hmac.digest("hex");
+        return this.safeCompare(signature, expectedSignature);
+    }
+    verifyHMACWithPrefix(payload, signature, algorithm = "sha256") {
+        const hmac = (0, crypto_1.createHmac)(algorithm, this.secret);
+        hmac.update(payload);
+        const expectedSignature = `${this.config.prefix || ""}${hmac.digest("hex")}`;
+        return this.safeCompare(signature, expectedSignature);
+    }
+}
+exports.AlgorithmBasedVerifier = AlgorithmBasedVerifier;
+class HMACSHA256Verifier extends AlgorithmBasedVerifier {
+    async verify(request) {
+        try {
+            const signature = this.extractSignature(request);
+            if (!signature) {
+                return {
+                    isValid: false,
+                    error: `Missing signature header: ${this.config.headerName}`,
+                    platform: "unknown",
+                };
+            }
+            const rawBody = await request.text();
+            const timestamp = this.extractTimestamp(request);
+            if (timestamp && !this.isTimestampValid(timestamp)) {
+                return {
+                    isValid: false,
+                    error: "Webhook timestamp expired",
+                    platform: "unknown",
+                };
+            }
+            const payload = this.formatPayload(rawBody, timestamp);
+            const isValid = this.config.prefix
+                ? this.verifyHMACWithPrefix(payload, signature, "sha256")
+                : this.verifyHMAC(payload, signature, "sha256");
+            if (!isValid) {
+                return {
+                    isValid: false,
+                    error: "Invalid signature",
+                    platform: "unknown",
+                };
+            }
+            let parsedPayload;
+            try {
+                parsedPayload = JSON.parse(rawBody);
+            }
+            catch (e) {
+                // Return valid even if JSON parsing fails
+                parsedPayload = rawBody;
+            }
+            return {
+                isValid: true,
+                platform: "unknown",
+                payload: parsedPayload,
+                metadata: {
+                    timestamp: timestamp?.toString(),
+                    algorithm: "hmac-sha256",
+                },
+            };
+        }
+        catch (error) {
+            return {
+                isValid: false,
+                error: `HMAC-SHA256 verification error: ${error.message}`,
+                platform: "unknown",
+            };
+        }
+    }
+}
+exports.HMACSHA256Verifier = HMACSHA256Verifier;
+class HMACSHA1Verifier extends AlgorithmBasedVerifier {
+    async verify(request) {
+        try {
+            const signature = this.extractSignature(request);
+            if (!signature) {
+                return {
+                    isValid: false,
+                    error: `Missing signature header: ${this.config.headerName}`,
+                    platform: "unknown",
+                };
+            }
+            const rawBody = await request.text();
+            const timestamp = this.extractTimestamp(request);
+            if (timestamp && !this.isTimestampValid(timestamp)) {
+                return {
+                    isValid: false,
+                    error: "Webhook timestamp expired",
+                    platform: "unknown",
+                };
+            }
+            const payload = this.formatPayload(rawBody, timestamp);
+            const isValid = this.config.prefix
+                ? this.verifyHMACWithPrefix(payload, signature, "sha1")
+                : this.verifyHMAC(payload, signature, "sha1");
+            if (!isValid) {
+                return {
+                    isValid: false,
+                    error: "Invalid signature",
+                    platform: "unknown",
+                };
+            }
+            let parsedPayload;
+            try {
+                parsedPayload = JSON.parse(rawBody);
+            }
+            catch (e) {
+                parsedPayload = rawBody;
+            }
+            return {
+                isValid: true,
+                platform: "unknown",
+                payload: parsedPayload,
+                metadata: {
+                    timestamp: timestamp?.toString(),
+                    algorithm: "hmac-sha1",
+                },
+            };
+        }
+        catch (error) {
+            return {
+                isValid: false,
+                error: `HMAC-SHA1 verification error: ${error.message}`,
+                platform: "unknown",
+            };
+        }
+    }
+}
+exports.HMACSHA1Verifier = HMACSHA1Verifier;
+class HMACSHA512Verifier extends AlgorithmBasedVerifier {
+    async verify(request) {
+        try {
+            const signature = this.extractSignature(request);
+            if (!signature) {
+                return {
+                    isValid: false,
+                    error: `Missing signature header: ${this.config.headerName}`,
+                    platform: "unknown",
+                };
+            }
+            const rawBody = await request.text();
+            const timestamp = this.extractTimestamp(request);
+            if (timestamp && !this.isTimestampValid(timestamp)) {
+                return {
+                    isValid: false,
+                    error: "Webhook timestamp expired",
+                    platform: "unknown",
+                };
+            }
+            const payload = this.formatPayload(rawBody, timestamp);
+            const isValid = this.config.prefix
+                ? this.verifyHMACWithPrefix(payload, signature, "sha512")
+                : this.verifyHMAC(payload, signature, "sha512");
+            if (!isValid) {
+                return {
+                    isValid: false,
+                    error: "Invalid signature",
+                    platform: "unknown",
+                };
+            }
+            let parsedPayload;
+            try {
+                parsedPayload = JSON.parse(rawBody);
+            }
+            catch (e) {
+                parsedPayload = rawBody;
+            }
+            return {
+                isValid: true,
+                platform: "unknown",
+                payload: parsedPayload,
+                metadata: {
+                    timestamp: timestamp?.toString(),
+                    algorithm: "hmac-sha512",
+                },
+            };
+        }
+        catch (error) {
+            return {
+                isValid: false,
+                error: `HMAC-SHA512 verification error: ${error.message}`,
+                platform: "unknown",
+            };
+        }
+    }
+}
+exports.HMACSHA512Verifier = HMACSHA512Verifier;
+// Factory function to create verifiers based on algorithm
+function createAlgorithmVerifier(secret, config, toleranceInSeconds = 300) {
+    switch (config.algorithm) {
+        case "hmac-sha256":
+            return new HMACSHA256Verifier(secret, config, toleranceInSeconds);
+        case "hmac-sha1":
+            return new HMACSHA1Verifier(secret, config, toleranceInSeconds);
+        case "hmac-sha512":
+            return new HMACSHA512Verifier(secret, config, toleranceInSeconds);
+        case "rsa-sha256":
+        case "ed25519":
+        case "custom":
+            // These can be implemented as needed
+            throw new Error(`Algorithm ${config.algorithm} not yet implemented`);
+        default:
+            throw new Error(`Unknown algorithm: ${config.algorithm}`);
+    }
+}

package/dist/verifiers/base.d.ts

@@ -0,0 +1,9 @@
+import { WebhookVerificationResult } from "../types";
+export declare abstract class WebhookVerifier {
+    protected secret: string;
+    protected toleranceInSeconds: number;
+    constructor(secret: string, toleranceInSeconds?: number);
+    abstract verify(request: Request): Promise<WebhookVerificationResult>;
+    protected isTimestampValid(timestamp: number): boolean;
+    protected safeCompare(a: string, b: string): boolean;
+}

package/dist/verifiers/base.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerifier = void 0;
+const crypto_1 = require("crypto");
+class WebhookVerifier {
+    constructor(secret, toleranceInSeconds = 300) {
+        this.secret = secret;
+        this.toleranceInSeconds = toleranceInSeconds;
+    }
+    isTimestampValid(timestamp) {
+        const now = Math.floor(Date.now() / 1000);
+        return Math.abs(now - timestamp) <= this.toleranceInSeconds;
+    }
+    safeCompare(a, b) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        return (0, crypto_1.timingSafeEqual)(new TextEncoder().encode(a), new TextEncoder().encode(b));
+    }
+}
+exports.WebhookVerifier = WebhookVerifier;

package/dist/verifiers/custom-algorithms.d.ts

@@ -0,0 +1,18 @@
+import { WebhookVerifier } from "./base";
+import { WebhookVerificationResult, SignatureConfig } from "../types";
+export declare class TokenBasedVerifier extends WebhookVerifier {
+    private config;
+    constructor(secret: string, config: SignatureConfig, toleranceInSeconds?: number);
+    verify(request: Request): Promise<WebhookVerificationResult>;
+}
+export declare class ClerkCustomVerifier extends WebhookVerifier {
+    private config;
+    constructor(secret: string, config: SignatureConfig, toleranceInSeconds?: number);
+    verify(request: Request): Promise<WebhookVerificationResult>;
+}
+export declare class StripeCustomVerifier extends WebhookVerifier {
+    private config;
+    constructor(secret: string, config: SignatureConfig, toleranceInSeconds?: number);
+    verify(request: Request): Promise<WebhookVerificationResult>;
+}
+export declare function createCustomVerifier(secret: string, config: SignatureConfig, toleranceInSeconds?: number): WebhookVerifier;