@hookflo/tern 2.2.7 → 2.2.10

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/adapters/express.d.ts

@@ -1,5 +1,5 @@
-import { WebhookPlatform, WebhookVerificationResult, NormalizeOptions } from '../types';
-import { MinimalNodeRequest } from './shared';
+import { WebhookPlatform, WebhookVerificationResult, NormalizeOptions } from "../types";
+import { MinimalNodeRequest } from "./shared";
 export interface ExpressLikeResponse {
     status: (code: number) => ExpressLikeResponse;
     json: (payload: unknown) => unknown;
@@ -7,7 +7,7 @@ export interface ExpressLikeResponse {
 export interface ExpressLikeRequest extends MinimalNodeRequest {
     webhook?: WebhookVerificationResult;
 }
-export type ExpressLikeNext = () => void;
+export type ExpressLikeNext = (err?: unknown) => void;
 export interface ExpressWebhookMiddlewareOptions {
     platform: WebhookPlatform;
     secret: string;

package/dist/adapters/express.js

@@ -9,7 +9,12 @@ function createWebhookMiddleware(options) {
             const webRequest = await (0, shared_1.toWebRequest)(req);
             const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(webRequest, options.platform, options.secret, options.toleranceInSeconds, options.normalize);
             if (!result.isValid) {
-                res.status(400).json({ error: result.error, errorCode: result.errorCode, platform: result.platform, metadata: result.metadata });
+                res.status(400).json({
+                    error: result.error,
+                    errorCode: result.errorCode,
+                    platform: result.platform,
+                    metadata: result.metadata,
+                });
                 return;
             }
             req.webhook = result;
@@ -17,7 +22,7 @@ function createWebhookMiddleware(options) {
         }
         catch (error) {
             options.onError?.(error);
-            res.status(500).json({ error: error.message });
+            next(error);
         }
     };
 }

package/dist/adapters/shared.d.ts

@@ -6,8 +6,8 @@ export interface MinimalNodeRequest {
     get?: (name: string) => string | undefined;
     originalUrl?: string;
     url?: string;
-    on?: (event: string, cb: (chunk?: any) => void) => void;
+    on?: (event: string, cb: (chunk?: unknown) => void) => void;
 }
-export declare function extractRawBody(request: MinimalNodeRequest): Promise<string>;
+export declare function extractRawBody(request: MinimalNodeRequest): Promise<Uint8Array>;
 export declare function toHeadersInit(headers: Record<string, string | string[] | undefined>): HeadersInit;
 export declare function toWebRequest(request: MinimalNodeRequest): Promise<Request>;

package/dist/adapters/shared.js

@@ -6,39 +6,65 @@ exports.toWebRequest = toWebRequest;
 function getHeaderValue(headers, name) {
     const value = headers[name.toLowerCase()] ?? headers[name];
     if (Array.isArray(value)) {
-        return value.join(',');
+        return value.join(",");
     }
     return value;
 }
-async function readIncomingMessageBody(request) {
-    if (!request.on) {
-        return '';
-    }
+async function readIncomingMessageBodyAsBuffer(request) {
+    if (!request.on)
+        return new Uint8Array(0);
     const chunks = [];
     return new Promise((resolve, reject) => {
-        request.on?.('data', (chunk) => {
-            if (typeof chunk === 'string') {
+        request.on?.("data", (chunk) => {
+            if (chunk instanceof Uint8Array) {
                 chunks.push(chunk);
-                return;
             }
-            chunks.push(Buffer.from(chunk ?? '').toString('utf8'));
+            else if (typeof chunk === "string") {
+                chunks.push(new TextEncoder().encode(chunk));
+            }
+            else if (chunk != null) {
+                try {
+                    chunks.push(new TextEncoder().encode(String(chunk)));
+                }
+                catch {
+                    // skip unreadable chunk silently
+                }
+            }
         });
-        request.on?.('end', () => resolve(chunks.join('')));
-        request.on?.('error', reject);
+        request.on?.("end", () => {
+            const totalLength = chunks.reduce((sum, c) => sum + c.byteLength, 0);
+            const result = new Uint8Array(totalLength);
+            let offset = 0;
+            for (const chunk of chunks) {
+                result.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            resolve(result);
+        });
+        request.on?.("error", (err) => reject(err));
     });
 }
 async function extractRawBody(request) {
     const body = request.body;
-    if (typeof body === 'string') {
+    if (body instanceof Uint8Array) {
         return body;
     }
-    if (Buffer.isBuffer(body)) {
-        return body.toString('utf8');
+    if (typeof body === "string") {
+        return new TextEncoder().encode(body);
     }
-    if (body && typeof body === 'object') {
-        return JSON.stringify(body);
+    if (body !== null && body !== undefined && typeof body === "object") {
+        console.warn("[Tern] Warning: request body is already parsed as JSON. " +
+            "Signature verification may fail. " +
+            'Add express.raw({ type: "*/*" }) before Tern on webhook routes, ' +
+            "or register webhook routes before app.use(express.json()).");
+        return new TextEncoder().encode(JSON.stringify(body));
     }
-    return readIncomingMessageBody(request);
+    // nothing ran — read raw stream directly
+    return readIncomingMessageBodyAsBuffer(request);
+}
+// converts Uint8Array to a plain ArrayBuffer that all TS versions accept as BodyInit
+function toArrayBuffer(uint8) {
+    return uint8.buffer.slice(uint8.byteOffset, uint8.byteOffset + uint8.byteLength);
 }
 function toHeadersInit(headers) {
     const normalized = new Headers();
@@ -47,7 +73,7 @@ function toHeadersInit(headers) {
             continue;
         }
         if (Array.isArray(value)) {
-            normalized.set(key, value.join(','));
+            normalized.set(key, value.join(","));
             continue;
         }
         normalized.set(key, value);
@@ -55,13 +81,17 @@ function toHeadersInit(headers) {
     return normalized;
 }
 async function toWebRequest(request) {
-    const protocol = request.protocol || 'https';
-    const host = request.get?.('host') || getHeaderValue(request.headers, 'host') || 'localhost';
-    const path = request.originalUrl || request.url || '/';
+    const protocol = request.protocol || "https";
+    const host = request.get?.("host") ||
+        getHeaderValue(request.headers, "host") ||
+        "localhost";
+    const path = request.originalUrl || request.url || "/";
     const rawBody = await extractRawBody(request);
-    return new Request(`${protocol}://${host}${path}`, {
-        method: request.method || 'POST',
+    const init = {
+        method: request.method || "POST",
         headers: toHeadersInit(request.headers),
-        body: rawBody,
-    });
+        body: toArrayBuffer(rawBody),
+        duplex: "half",
+    };
+    return new Request(`${protocol}://${host}${path}`, init);
 }

package/dist/adapters/testExpress.d.ts

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

package/dist/adapters/testExpress.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto_1 = __importDefault(require("crypto"));
+const shared_1 = require("./shared");
+const __1 = __importDefault(require(".."));
+const secret = "whsec_test_secret";
+const payload = JSON.stringify({ type: "payment_intent.succeeded", data: { amount: 2000 } }) +
+    "\n";
+function buildStripeSignature(body, secret) {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const signed = `${timestamp}.${body}`;
+    const hmac = crypto_1.default
+        .createHmac("sha256", secret.replace("whsec_", ""))
+        .update(signed)
+        .digest("hex");
+    return `t=${timestamp},v1=${hmac}`;
+}
+// ── Test 1: raw stream — no middleware ran ───────────────────
+async function testRawStream() {
+    const sig = buildStripeSignature(payload, secret); // ✓ fixed: was missing secret arg
+    const chunks = [Buffer.from(payload, "utf8")];
+    const req = {
+        method: "POST",
+        headers: {
+            "stripe-signature": sig,
+            "content-type": "application/json",
+        },
+        body: undefined,
+        on: (event, cb) => {
+            if (event === "data") {
+                for (const chunk of chunks)
+                    cb(chunk);
+            }
+            if (event === "end") {
+                cb();
+            }
+        },
+    };
+    const webReq = await (0, shared_1.toWebRequest)(req);
+    const result = await __1.default.verifyWithPlatformConfig(webReq, "stripe", secret);
+    console.log("Test 1 Raw stream (no middleware):", result.isValid ? "✓ PASS" : `✗ FAIL — ${result.error}`);
+}
+// ── Test 2: Buffer body — express.raw() ran ──────────────────
+async function testBufferBody() {
+    const sig = buildStripeSignature(payload, secret);
+    const req = {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "stripe-signature": sig,
+        },
+        body: Buffer.from(payload, "utf8"),
+    };
+    const webReq = await (0, shared_1.toWebRequest)(req);
+    const result = await __1.default.verifyWithPlatformConfig(webReq, "stripe", secret);
+    console.log("Test 2 Buffer body (express.raw):", result.isValid ? "✓ PASS" : `✗ FAIL — ${result.error}`);
+}
+// ── Test 3: parsed object — express.json() ran ───────────────
+async function testParsedObject() {
+    // signature computed against raw payload including \n
+    const sig = buildStripeSignature(payload, secret);
+    const req = {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "stripe-signature": sig,
+        },
+        body: JSON.parse(payload), // \n gone, bytes lost
+    };
+    const webReq = await (0, shared_1.toWebRequest)(req);
+    const result = await __1.default.verifyWithPlatformConfig(webReq, "stripe", secret);
+    // should FAIL — \n was in original signature but lost after JSON.parse
+    console.log("Test 3 Parsed object (express.json):", !result.isValid ? "✓ FAILS AS EXPECTED" : "✗ SHOULD HAVE FAILED");
+}
+async function run() {
+    await testRawStream(); // no middleware      → should PASS
+    await testBufferBody(); // express.raw()      → should PASS
+    await testParsedObject(); // express.json()     → should FAIL as expected
+    console.log("\nDone. Test 3 failing is correct behavior.");
+}
+run();

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/package.json

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