@hookflo/tern 2.2.5 → 2.2.9

package/README.md

@@ -193,7 +193,7 @@ const result = await WebhookVerificationService.verify(request, stripeConfig);
 
 ## Supported Platforms
 
-### Stripe
+### Stripe OK Tested
 - **Signature Format**: `t={timestamp},v1={signature}`
 - **Algorithm**: HMAC-SHA256
 - **Payload Format**: `{timestamp}.{body}`
@@ -209,20 +209,20 @@ const result = await WebhookVerificationService.verify(request, stripeConfig);
 - **Payload Format**: `{id}.{timestamp}.{body}`
 
 ### Other Platforms
-- **Dodo Payments**: HMAC-SHA256
-- **Paddle**: HMAC-SHA256
-- **Razorpay**: HMAC-SHA256
-- **Lemon Squeezy**: HMAC-SHA256
-- **Auth0**: HMAC-SHA256
-- **WorkOS**: HMAC-SHA256 (`workos-signature`, `t/v1`)
-- **WooCommerce**: HMAC-SHA256 (base64 signature)
-- **ReplicateAI**: HMAC-SHA256 (Standard Webhooks style)
+- **Dodo Payments**: HMAC-SHA256 OK Tested
+- **Paddle**: HMAC-SHA256 OK Tested
+- **Razorpay**: HMAC-SHA256 Pending
+- **Lemon Squeezy**: HMAC-SHA256 OK Tested
+- **Auth0**: HMAC-SHA256 Pending
+- **WorkOS**: HMAC-SHA256 (`workos-signature`, `t/v1`) OK Tested
+- **WooCommerce**: HMAC-SHA256 (base64 signature) Pending
+- **ReplicateAI**: HMAC-SHA256 (Standard Webhooks style) OK Tested
 - **fal.ai**: ED25519 (`x-fal-webhook-signature`)
-- **Shopify**: HMAC-SHA256 (base64 signature)
-- **Vercel**: HMAC-SHA256
-- **Polar**: HMAC-SHA256
-- **Supabase**: Token-based authentication
-- **GitLab**: Token-based authentication 
+- **Shopify**: HMAC-SHA256 (base64 signature) OK Tested
+- **Vercel**: HMAC-SHA256 Pending
+- **Polar**: HMAC-SHA256 OK Tested
+- **Supabase**: Token-based authentication Pending
+- **GitLab**: Token-based authentication OK Tested
 
 ## Custom Platform Configuration
 

package/dist/platforms/algorithms.js

@@ -119,12 +119,12 @@ exports.platformAlgorithmConfigs = {
         platform: "supabase",
         signatureConfig: {
             algorithm: "custom",
-            headerName: "x-webhook-token",
+            headerName: "x-supabase-token",
             headerFormat: "raw",
             payloadFormat: "raw",
             customConfig: {
                 type: "token-based",
-                idHeader: "x-webhook-id",
+                idHeader: "x-supabase-token",
             },
         },
         description: "Supabase webhooks use token-based authentication",
@@ -244,14 +244,13 @@ exports.platformAlgorithmConfigs = {
             headerFormat: "raw",
             payloadFormat: "custom",
             customConfig: {
-                requestIdHeader: "x-fal-request-id",
-                userIdHeader: "x-fal-user-id",
+                requestIdHeader: "x-fal-webhook-request-id",
+                userIdHeader: "x-fal-webhook-user-id",
                 timestampHeader: "x-fal-webhook-timestamp",
-                kidHeader: "x-fal-webhook-key-id",
                 jwksUrl: "https://rest.alpha.fal.ai/.well-known/jwks.json",
             },
         },
-        description: "fal.ai webhooks use ED25519 with a signed request/user/timestamp/body-hash payload",
+        description: "fal.ai webhooks use ED25519 with JWKS key verification. No secret required — pass empty string.",
     },
     custom: {
         platform: "custom",

package/dist/verifiers/algorithms.d.ts

@@ -1,5 +1,5 @@
-import { WebhookVerifier } from './base';
-import { WebhookVerificationResult, SignatureConfig, WebhookPlatform } from '../types';
+import { WebhookVerifier } from "./base";
+import { WebhookVerificationResult, SignatureConfig, WebhookPlatform } from "../types";
 export declare abstract class AlgorithmBasedVerifier extends WebhookVerifier {
     protected config: SignatureConfig;
     protected platform: WebhookPlatform;
@@ -20,7 +20,27 @@ export declare class GenericHMACVerifier extends AlgorithmBasedVerifier {
     verify(request: Request): Promise<WebhookVerificationResult>;
 }
 export declare class Ed25519Verifier extends AlgorithmBasedVerifier {
-    private resolvePublicKey;
+    /**
+     * Fetch all public keys from JWKS endpoint.
+     * Returns array of PEM strings — tries all keys during verification
+     * so key rotation works transparently.
+     * Caches for 24 hours per fal.ai docs recommendation.
+     */
+    private fetchJWKSKeys;
+    /**
+     * Resolve public keys to use for verification.
+     * Priority:
+     *   1. Explicit publicKey in config
+     *   2. Non-empty secret passed directly (user-provided PEM)
+     *   3. JWKS URL in config (fal.ai — fetches all keys, tries each)
+     */
+    private resolvePublicKeys;
+    /**
+     * Build fal.ai specific payload string.
+     *
+     * Per fal.ai docs, message is newline-separated (NOT dot-separated):
+     *   {request-id}\n{user-id}\n{timestamp}\n{sha256hex(body)}
+     */
     private buildFalPayload;
     verify(request: Request): Promise<WebhookVerificationResult>;
 }

package/dist/verifiers/algorithms.js

@@ -4,7 +4,9 @@ exports.HMACSHA512Verifier = exports.HMACSHA1Verifier = exports.HMACSHA256Verifi
 exports.createAlgorithmVerifier = createAlgorithmVerifier;
 const crypto_1 = require("crypto");
 const base_1 = require("./base");
+// Cache stores array of PEM keys per JWKS URL
 const ed25519KeyCache = new Map();
+const JWKS_CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours per fal.ai docs
 class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
     constructor(secret, config, platform, toleranceInSeconds = 300) {
         super(secret, toleranceInSeconds);
@@ -18,7 +20,7 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
             const trimmed = part.trim();
             if (!trimmed)
                 continue;
-            const equalIndex = trimmed.indexOf('=');
+            const equalIndex = trimmed.indexOf("=");
             if (equalIndex === -1)
                 continue;
             const key = trimmed.slice(0, equalIndex).trim();
@@ -34,20 +36,20 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
         if (!headerValue)
             return null;
         switch (this.config.headerFormat) {
-            case 'prefixed':
-                return headerValue;
-            case 'comma-separated': {
+            case "prefixed":
+                return headerValue.trim();
+            case "comma-separated": {
                 const sigMap = this.parseDelimitedHeader(headerValue);
-                const signatureKey = this.config.customConfig?.signatureKey || 'v1';
+                const signatureKey = this.config.customConfig?.signatureKey || "v1";
                 return sigMap[signatureKey] || sigMap.signature || sigMap.v1 || null;
             }
-            case 'raw':
+            case "raw":
             default:
-                if (this.config.customConfig?.signatureFormat?.includes('v1=')) {
-                    const signatures = headerValue.split(' ');
+                if (this.config.customConfig?.signatureFormat?.includes("v1=")) {
+                    const signatures = headerValue.split(" ");
                     for (const sig of signatures) {
-                        const [version, signature] = sig.split(',');
-                        if (version === 'v1') {
+                        const [version, signature] = sig.split(",");
+                        if (version === "v1") {
                             return signature;
                         }
                     }
@@ -63,37 +65,37 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
         if (!timestampHeader)
             return null;
         switch (this.config.timestampFormat) {
-            case 'unix':
+            case "unix":
                 return parseInt(timestampHeader, 10);
-            case 'iso':
+            case "iso":
                 return Math.floor(new Date(timestampHeader).getTime() / 1000);
-            case 'custom':
+            case "custom":
                 return parseInt(timestampHeader, 10);
             default:
                 return parseInt(timestampHeader, 10);
         }
     }
     extractTimestampFromSignature(request) {
-        if (this.config.headerFormat !== 'comma-separated') {
+        if (this.config.headerFormat !== "comma-separated") {
             return null;
         }
         const headerValue = request.headers.get(this.config.headerName);
         if (!headerValue)
             return null;
         const sigMap = this.parseDelimitedHeader(headerValue);
-        const timestampKey = this.config.customConfig?.timestampKey || 't';
+        const timestampKey = this.config.customConfig?.timestampKey || "t";
         return sigMap[timestampKey] ? parseInt(sigMap[timestampKey], 10) : null;
     }
     formatPayload(rawBody, request) {
         switch (this.config.payloadFormat) {
-            case 'timestamped': {
-                const timestamp = this.extractTimestampFromSignature(request)
-                    || this.extractTimestamp(request);
+            case "timestamped": {
+                const timestamp = this.extractTimestampFromSignature(request) ||
+                    this.extractTimestamp(request);
                 return timestamp ? `${timestamp}.${rawBody}` : rawBody;
             }
-            case 'custom':
+            case "custom":
                 return this.formatCustomPayload(rawBody, request);
-            case 'raw':
+            case "raw":
             default:
                 return rawBody;
         }
@@ -103,78 +105,80 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
             return rawBody;
         }
         const customFormat = this.config.customConfig.payloadFormat;
-        if (customFormat.includes('{id}') && customFormat.includes('{timestamp}')) {
-            const id = request.headers.get(this.config.customConfig.idHeader || 'x-webhook-id');
-            const timestamp = request.headers.get(this.config.timestampHeader || 'x-webhook-timestamp');
+        if (customFormat.includes("{id}") && customFormat.includes("{timestamp}")) {
+            const id = request.headers.get(this.config.customConfig.idHeader || "x-webhook-id");
+            const timestamp = request.headers.get(this.config.timestampHeader || "x-webhook-timestamp");
             return customFormat
-                .replace('{id}', id || '')
-                .replace('{timestamp}', timestamp || '')
-                .replace('{body}', rawBody);
+                .replace("{id}", id || "")
+                .replace("{timestamp}", timestamp || "")
+                .replace("{body}", rawBody);
         }
-        if (customFormat.includes('{timestamp}')
-            && customFormat.includes('{body}')) {
-            const timestamp = this.extractTimestampFromSignature(request)
-                || this.extractTimestamp(request);
+        if (customFormat.includes("{timestamp}") &&
+            customFormat.includes("{body}")) {
+            const timestamp = this.extractTimestampFromSignature(request) ||
+                this.extractTimestamp(request);
             return customFormat
-                .replace('{timestamp}', timestamp?.toString() || '')
-                .replace('{body}', rawBody);
+                .replace("{timestamp}", timestamp?.toString() || "")
+                .replace("{body}", rawBody);
         }
         return rawBody;
     }
-    verifyHMAC(payload, signature, algorithm = 'sha256') {
+    verifyHMAC(payload, signature, algorithm = "sha256") {
         const hmac = (0, crypto_1.createHmac)(algorithm, this.secret);
         hmac.update(payload);
-        const expectedSignature = hmac.digest('hex');
+        const expectedSignature = hmac.digest("hex");
         return this.safeCompare(signature, expectedSignature);
     }
-    verifyHMACWithPrefix(payload, signature, algorithm = 'sha256') {
+    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')}`;
+        const expectedSignature = `${this.config.prefix || ""}${hmac.digest("hex")}`;
         return this.safeCompare(signature, expectedSignature);
     }
-    verifyHMACWithBase64(payload, signature, algorithm = 'sha256') {
-        const secretEncoding = this.config.customConfig?.secretEncoding || 'base64';
+    verifyHMACWithBase64(payload, signature, algorithm = "sha256") {
+        const secretEncoding = this.config.customConfig?.secretEncoding || "base64";
         let secretMaterial = this.secret;
-        if (secretEncoding === 'base64') {
-            const base64Secret = this.secret.includes('_')
-                ? this.secret.split('_').slice(1).join('_')
+        if (secretEncoding === "base64") {
+            const base64Secret = this.secret.includes("_")
+                ? this.secret.split("_").slice(1).join("_")
                 : this.secret;
-            secretMaterial = new Uint8Array(Buffer.from(base64Secret, 'base64'));
+            secretMaterial = new Uint8Array(Buffer.from(base64Secret, "base64"));
         }
+        // 'utf8', 'raw', or anything else → use secret as-is
         const hmac = (0, crypto_1.createHmac)(algorithm, secretMaterial);
         hmac.update(payload);
-        const expectedSignature = hmac.digest('base64');
+        const expectedSignature = hmac.digest("base64");
         return this.safeCompare(signature, expectedSignature);
     }
     extractMetadata(request) {
         const metadata = {
             algorithm: this.config.algorithm,
         };
-        const timestamp = this.extractTimestamp(request) || this.extractTimestampFromSignature(request);
+        const timestamp = this.extractTimestamp(request) ||
+            this.extractTimestampFromSignature(request);
         if (timestamp) {
             metadata.timestamp = timestamp.toString();
         }
         switch (this.platform) {
-            case 'github':
-                metadata.event = request.headers.get('x-github-event');
-                metadata.delivery = request.headers.get('x-github-delivery');
+            case "github":
+                metadata.event = request.headers.get("x-github-event");
+                metadata.delivery = request.headers.get("x-github-delivery");
                 break;
-            case 'stripe': {
+            case "stripe": {
                 const headerValue = request.headers.get(this.config.headerName);
-                if (headerValue && this.config.headerFormat === 'comma-separated') {
+                if (headerValue && this.config.headerFormat === "comma-separated") {
                     const sigMap = this.parseDelimitedHeader(headerValue);
                     metadata.id = sigMap.id;
                 }
                 break;
             }
-            case 'clerk':
-            case 'dodopayments':
-            case 'replicateai':
-                metadata.id = request.headers.get(this.config.customConfig?.idHeader || 'webhook-id');
+            case "clerk":
+            case "dodopayments":
+            case "replicateai":
+                metadata.id = request.headers.get(this.config.customConfig?.idHeader || "webhook-id");
                 break;
-            case 'workos':
-                metadata.id = request.headers.get(this.config.customConfig?.idHeader || 'webhook-id');
+            case "workos":
+                metadata.id = request.headers.get(this.config.customConfig?.idHeader || "webhook-id");
                 break;
             default:
                 break;
@@ -191,13 +195,13 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
                 return {
                     isValid: false,
                     error: `Missing signature header: ${this.config.headerName}`,
-                    errorCode: 'MISSING_SIGNATURE',
+                    errorCode: "MISSING_SIGNATURE",
                     platform: this.platform,
                 };
             }
             const rawBody = await request.text();
             let timestamp = null;
-            if (this.config.headerFormat === 'comma-separated') {
+            if (this.config.headerFormat === "comma-separated") {
                 timestamp = this.extractTimestampFromSignature(request);
             }
             else {
@@ -206,18 +210,18 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
             if (timestamp && !this.isTimestampValid(timestamp)) {
                 return {
                     isValid: false,
-                    error: 'Webhook timestamp expired',
-                    errorCode: 'TIMESTAMP_EXPIRED',
+                    error: "Webhook timestamp expired",
+                    errorCode: "TIMESTAMP_EXPIRED",
                     platform: this.platform,
                 };
             }
             const payload = this.formatPayload(rawBody, request);
             let isValid = false;
-            const algorithm = this.config.algorithm.replace('hmac-', '');
-            if (this.config.customConfig?.encoding === 'base64') {
+            const algorithm = this.config.algorithm.replace("hmac-", "");
+            if (this.config.customConfig?.encoding === "base64") {
                 isValid = this.verifyHMACWithBase64(payload, signature, algorithm);
             }
-            else if (this.config.headerFormat === 'prefixed') {
+            else if (this.config.headerFormat === "prefixed") {
                 isValid = this.verifyHMACWithPrefix(payload, signature, algorithm);
             }
             else {
@@ -226,8 +230,8 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
             if (!isValid) {
                 return {
                     isValid: false,
-                    error: 'Invalid signature',
-                    errorCode: 'INVALID_SIGNATURE',
+                    error: "Invalid signature",
+                    errorCode: "INVALID_SIGNATURE",
                     platform: this.platform,
                 };
             }
@@ -238,19 +242,18 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
             catch (e) {
                 parsedPayload = rawBody;
             }
-            const metadata = this.extractMetadata(request);
             return {
                 isValid: true,
                 platform: this.platform,
                 payload: parsedPayload,
-                metadata,
+                metadata: this.extractMetadata(request),
             };
         }
         catch (error) {
             return {
                 isValid: false,
                 error: `${this.platform} verification error: ${error.message}`,
-                errorCode: 'VERIFICATION_ERROR',
+                errorCode: "VERIFICATION_ERROR",
                 platform: this.platform,
             };
         }
@@ -258,47 +261,91 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
 }
 exports.GenericHMACVerifier = GenericHMACVerifier;
 class Ed25519Verifier extends AlgorithmBasedVerifier {
-    async resolvePublicKey(request) {
-        const configPublicKey = this.config.customConfig?.publicKey;
-        if (configPublicKey) {
-            return configPublicKey;
+    /**
+     * Fetch all public keys from JWKS endpoint.
+     * Returns array of PEM strings — tries all keys during verification
+     * so key rotation works transparently.
+     * Caches for 24 hours per fal.ai docs recommendation.
+     */
+    async fetchJWKSKeys(jwksUrl) {
+        const cached = ed25519KeyCache.get(jwksUrl);
+        if (cached && Date.now() < cached.expiresAt) {
+            return cached.pems;
         }
-        if (this.secret && this.secret.trim().length > 0) {
-            return this.secret;
+        const response = await fetch(jwksUrl);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch JWKS from ${jwksUrl}: ${response.status}`);
         }
-        const jwksUrl = this.config.customConfig?.jwksUrl;
-        const kidHeader = this.config.customConfig?.kidHeader;
-        const kid = kidHeader ? request.headers.get(kidHeader) : null;
-        if (!jwksUrl || !kid) {
-            return null;
+        const body = (await response.json());
+        const keys = body.keys || [];
+        if (keys.length === 0) {
+            throw new Error("No keys found in JWKS response");
         }
-        const cacheKey = `${jwksUrl}:${kid}`;
-        if (ed25519KeyCache.has(cacheKey)) {
-            return ed25519KeyCache.get(cacheKey);
+        const pems = [];
+        for (const key of keys) {
+            try {
+                const keyObject = (0, crypto_1.createPublicKey)({ key, format: "jwk" });
+                const pem = keyObject
+                    .export({ type: "spki", format: "pem" })
+                    .toString();
+                pems.push(pem);
+            }
+            catch {
+                // skip malformed keys, continue with rest
+                continue;
+            }
         }
-        const response = await fetch(jwksUrl);
-        if (!response.ok) {
-            return null;
+        if (pems.length === 0) {
+            throw new Error("No valid ED25519 keys found in JWKS");
         }
-        const body = await response.json();
-        const key = body.keys?.find((entry) => entry.kid === kid);
-        if (!key) {
-            return null;
+        ed25519KeyCache.set(jwksUrl, {
+            pems,
+            expiresAt: Date.now() + JWKS_CACHE_TTL,
+        });
+        return pems;
+    }
+    /**
+     * Resolve public keys to use for verification.
+     * Priority:
+     *   1. Explicit publicKey in config
+     *   2. Non-empty secret passed directly (user-provided PEM)
+     *   3. JWKS URL in config (fal.ai — fetches all keys, tries each)
+     */
+    async resolvePublicKeys(request) {
+        // 1. explicit public key in config
+        const configPublicKey = this.config.customConfig?.publicKey;
+        if (configPublicKey) {
+            return [configPublicKey];
         }
-        const keyObject = (0, crypto_1.createPublicKey)({ key, format: 'jwk' });
-        const pem = keyObject.export({ type: 'spki', format: 'pem' }).toString();
-        ed25519KeyCache.set(cacheKey, pem);
-        return pem;
+        // 2. non-empty secret = user passed PEM directly
+        // empty string = fal.ai pattern (no shared secret, use JWKS)
+        if (this.secret &&
+            this.secret.trim().length > 0 &&
+            this.platform !== "falai") {
+            return [this.secret];
+        }
+        // 3. fetch from JWKS — handles fal.ai and any other JWKS-based platform
+        const jwksUrl = this.config.customConfig?.jwksUrl;
+        if (!jwksUrl) {
+            return [];
+        }
+        return this.fetchJWKSKeys(jwksUrl);
     }
+    /**
+     * Build fal.ai specific payload string.
+     *
+     * Per fal.ai docs, message is newline-separated (NOT dot-separated):
+     *   {request-id}\n{user-id}\n{timestamp}\n{sha256hex(body)}
+     */
     buildFalPayload(rawBody, request) {
-        const requestIdHeader = this.config.customConfig?.requestIdHeader || 'x-fal-request-id';
-        const userIdHeader = this.config.customConfig?.userIdHeader || 'x-fal-user-id';
-        const timestampHeader = this.config.customConfig?.timestampHeader || 'x-fal-webhook-timestamp';
-        const requestId = request.headers.get(requestIdHeader) || '';
-        const userId = request.headers.get(userIdHeader) || '';
-        const timestamp = request.headers.get(timestampHeader) || '';
-        const bodyHash = (0, crypto_1.createHash)('sha256').update(rawBody).digest('hex');
-        return `${requestId}.${userId}.${timestamp}.${bodyHash}`;
+        const requestIdHeader = this.config.customConfig?.requestIdHeader || "x-fal-webhook-request-id";
+        const userIdHeader = this.config.customConfig?.userIdHeader || "x-fal-webhook-user-id";
+        const timestampHeader = this.config.customConfig?.timestampHeader || "x-fal-webhook-timestamp";
+        const requestId = request.headers.get(requestIdHeader) || "";
+        const userId = request.headers.get(userIdHeader) || "";
+        const timestamp = request.headers.get(timestampHeader) || "";
+        const bodyHash = (0, crypto_1.createHash)("sha256").update(rawBody).digest("hex");
+        return `${requestId}\n${userId}\n${timestamp}\n${bodyHash}`;
     }
     async verify(request) {
         try {
@@ -307,32 +354,79 @@ class Ed25519Verifier extends AlgorithmBasedVerifier {
                 return {
                     isValid: false,
                     error: `Missing signature header: ${this.config.headerName}`,
-                    errorCode: 'MISSING_SIGNATURE',
+                    errorCode: "MISSING_SIGNATURE",
                     platform: this.platform,
                 };
             }
             const rawBody = await request.text();
-            const payload = this.platform === 'falai'
+            // fal.ai timestamp validation before signature check
+            if (this.platform === "falai") {
+                const timestampHeader = this.config.customConfig?.timestampHeader ||
+                    "x-fal-webhook-timestamp";
+                const timestampStr = request.headers.get(timestampHeader);
+                if (timestampStr) {
+                    const timestamp = parseInt(timestampStr, 10);
+                    if (!this.isTimestampValid(timestamp)) {
+                        return {
+                            isValid: false,
+                            error: "Webhook timestamp expired",
+                            errorCode: "TIMESTAMP_EXPIRED",
+                            platform: this.platform,
+                        };
+                    }
+                }
+            }
+            const payload = this.platform === "falai"
                 ? this.buildFalPayload(rawBody, request)
                 : this.formatPayload(rawBody, request);
-            const publicKey = await this.resolvePublicKey(request);
-            if (!publicKey) {
+            // resolve all public keys
+            let publicKeys;
+            try {
+                publicKeys = await this.resolvePublicKeys(request);
+            }
+            catch (error) {
+                return {
+                    isValid: false,
+                    error: `Failed to resolve public keys: ${error.message}`,
+                    errorCode: "VERIFICATION_ERROR",
+                    platform: this.platform,
+                };
+            }
+            if (publicKeys.length === 0) {
                 return {
                     isValid: false,
-                    error: 'Missing public key for ED25519 verification',
-                    errorCode: 'VERIFICATION_ERROR',
+                    error: "No public keys available for ED25519 verification",
+                    errorCode: "VERIFICATION_ERROR",
                     platform: this.platform,
                 };
             }
-            const signatureBytes = new Uint8Array(Buffer.from(signature, 'base64'));
-            const keyObject = (0, crypto_1.createPublicKey)(publicKey);
-            const payloadBytes = new Uint8Array(Buffer.from(payload));
-            const isValid = (0, crypto_1.verify)(null, payloadBytes, keyObject, signatureBytes);
+            // fal.ai signature is hex encoded (not base64)
+            // other ED25519 platforms use base64 by default
+            const signatureEncoding = this.platform === "falai" ? "hex" : "base64";
+            const signatureBytes = new Uint8Array(Buffer.from(signature, signatureEncoding));
+            const payloadBytes = new Uint8Array(Buffer.from(payload, "utf-8"));
+            // try all keys — succeeds if any key validates
+            // this handles key rotation gracefully
+            let isValid = false;
+            for (const pem of publicKeys) {
+                try {
+                    const keyObject = (0, crypto_1.createPublicKey)(pem);
+                    const valid = (0, crypto_1.verify)(null, payloadBytes, keyObject, signatureBytes);
+                    if (valid) {
+                        isValid = true;
+                        break;
+                    }
+                }
+                catch {
+                    // this key failed — try next
+                    continue;
+                }
+            }
             if (!isValid) {
                 return {
                     isValid: false,
-                    error: 'Invalid signature',
-                    errorCode: 'INVALID_SIGNATURE',
+                    error: "Invalid signature",
+                    errorCode: "INVALID_SIGNATURE",
                     platform: this.platform,
                 };
             }
@@ -349,9 +443,11 @@ class Ed25519Verifier extends AlgorithmBasedVerifier {
                 payload: parsedPayload,
                 metadata: {
                     algorithm: this.config.algorithm,
-                    requestId: request.headers.get(this.config.customConfig?.requestIdHeader || 'x-fal-request-id'),
-                    userId: request.headers.get(this.config.customConfig?.userIdHeader || 'x-fal-user-id'),
-                    timestamp: request.headers.get(this.config.customConfig?.timestampHeader || 'x-fal-webhook-timestamp') || undefined,
+                    requestId: request.headers.get(this.config.customConfig?.requestIdHeader ||
+                        "x-fal-webhook-request-id"),
+                    userId: request.headers.get(this.config.customConfig?.userIdHeader || "x-fal-webhook-user-id"),
+                    timestamp: request.headers.get(this.config.customConfig?.timestampHeader ||
+                        "x-fal-webhook-timestamp") || undefined,
                 },
             };
         }
@@ -359,7 +455,7 @@ class Ed25519Verifier extends AlgorithmBasedVerifier {
             return {
                 isValid: false,
                 error: `${this.platform} verification error: ${error.message}`,
-                errorCode: 'VERIFICATION_ERROR',
+                errorCode: "VERIFICATION_ERROR",
                 platform: this.platform,
             };
         }
@@ -367,33 +463,33 @@ class Ed25519Verifier extends AlgorithmBasedVerifier {
 }
 exports.Ed25519Verifier = Ed25519Verifier;
 class HMACSHA256Verifier extends GenericHMACVerifier {
-    constructor(secret, config, platform = 'unknown', toleranceInSeconds = 300) {
+    constructor(secret, config, platform = "unknown", toleranceInSeconds = 300) {
         super(secret, config, platform, toleranceInSeconds);
     }
 }
 exports.HMACSHA256Verifier = HMACSHA256Verifier;
 class HMACSHA1Verifier extends GenericHMACVerifier {
-    constructor(secret, config, platform = 'unknown', toleranceInSeconds = 300) {
+    constructor(secret, config, platform = "unknown", toleranceInSeconds = 300) {
         super(secret, config, platform, toleranceInSeconds);
     }
 }
 exports.HMACSHA1Verifier = HMACSHA1Verifier;
 class HMACSHA512Verifier extends GenericHMACVerifier {
-    constructor(secret, config, platform = 'unknown', toleranceInSeconds = 300) {
+    constructor(secret, config, platform = "unknown", toleranceInSeconds = 300) {
         super(secret, config, platform, toleranceInSeconds);
     }
 }
 exports.HMACSHA512Verifier = HMACSHA512Verifier;
-function createAlgorithmVerifier(secret, config, platform = 'unknown', toleranceInSeconds = 300) {
+function createAlgorithmVerifier(secret, config, platform = "unknown", toleranceInSeconds = 300) {
     switch (config.algorithm) {
-        case 'hmac-sha256':
-        case 'hmac-sha1':
-        case 'hmac-sha512':
+        case "hmac-sha256":
+        case "hmac-sha1":
+        case "hmac-sha512":
             return new GenericHMACVerifier(secret, config, platform, toleranceInSeconds);
-        case 'ed25519':
+        case "ed25519":
             return new Ed25519Verifier(secret, config, platform, toleranceInSeconds);
-        case 'rsa-sha256':
-        case 'custom':
+        case "rsa-sha256":
+        case "custom":
             throw new Error(`Algorithm ${config.algorithm} not yet implemented`);
         default:
             throw new Error(`Unknown algorithm: ${config.algorithm}`);

package/dist/verifiers/base.d.ts

@@ -1,4 +1,4 @@
-import { WebhookVerificationResult } from '../types';
+import { WebhookVerificationResult } from "../types";
 export declare abstract class WebhookVerifier {
     protected secret: string;
     protected toleranceInSeconds: number;

package/dist/verifiers/base.js

@@ -9,7 +9,9 @@ class WebhookVerifier {
     }
     isTimestampValid(timestamp) {
         const now = Math.floor(Date.now() / 1000);
-        return Math.abs(now - timestamp) <= this.toleranceInSeconds;
+        // WorkOS sends milliseconds — auto-detect by magnitude
+        const timestampInSeconds = timestamp > 1e12 ? Math.floor(timestamp / 1000) : timestamp;
+        return Math.abs(now - timestampInSeconds) <= this.toleranceInSeconds;
     }
     safeCompare(a, b) {
         if (a.length !== b.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hookflo/tern",
-  "version": "2.2.5",
+  "version": "2.2.9",
   "description": "A robust, scalable webhook verification framework supporting multiple platforms and signature algorithms",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",