Add CI, strengthen verification logic, raw-body checks, QStash loading, and test harness

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm test

.npmignore

@@ -0,0 +1,6 @@
+dist/test.js
+dist/test.d.ts
+dist/test-compiled.js
+dist/test-compiled.d.ts
+dist/adapters/testExpress.js
+dist/adapters/testExpress.d.ts

package.json

@@ -7,7 +7,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "node dist/test.js",
+    "test": "ts-node src/test.ts",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint 'src/**/*.ts' --fix",
     "format": "prettier --write src/**/*.ts",

src/adapters/express.ts

@@ -6,7 +6,7 @@ import {
 import { WebhookVerificationService } from '../index';
 import { handleQueuedRequest, resolveQueueConfig } from '../upstash/queue';
 import { QueueOption } from '../upstash/types';
-import { toWebRequest, MinimalNodeRequest } from './shared';
+import { toWebRequest, MinimalNodeRequest, hasParsedBody } from './shared';
 
 export interface ExpressLikeResponse {
   status: (code: number) => ExpressLikeResponse;
@@ -26,6 +26,7 @@ export interface ExpressWebhookMiddlewareOptions {
   normalize?: boolean | NormalizeOptions;
   queue?: QueueOption;
   onError?: (error: Error) => void;
+  strictRawBody?: boolean;
 }
 
 export function createWebhookMiddleware(
@@ -37,6 +38,16 @@ export function createWebhookMiddleware(
     next: ExpressLikeNext,
   ): Promise<void> => {
     try {
+      const strictRawBody = options.strictRawBody ?? true;
+      if (strictRawBody && hasParsedBody(req)) {
+        res.status(400).json({
+          error: 'Webhook request body must be raw bytes. Configure express.raw({ type: "*/*" }) before this middleware.',
+          errorCode: 'VERIFICATION_ERROR',
+          platform: options.platform,
+        });
+        return;
+      }
+
       const webRequest = await toWebRequest(req);
 
       if (options.queue) {
@@ -49,7 +60,7 @@ export function createWebhookMiddleware(
         });
 
         const bodyText = await queueResponse.text();
-        let body: unknown = undefined;
+        let body: unknown;
         if (bodyText) {
           try {
             body = JSON.parse(bodyText);

src/adapters/shared.ts

@@ -20,6 +20,17 @@ function getHeaderValue(
   return value;
 }
 
+export function hasParsedBody(
+  request: MinimalNodeRequest,
+): boolean {
+  const { body } = request;
+  return body !== null
+    && body !== undefined
+    && typeof body === 'object'
+    && !(body instanceof Uint8Array)
+    && !(body instanceof ArrayBuffer);
+}
+
 async function readIncomingMessageBodyAsBuffer(
   request: MinimalNodeRequest,
 ): Promise<Uint8Array> {
@@ -67,7 +78,7 @@ export async function extractRawBody(
     return new TextEncoder().encode(body);
   }
 
-  if (body !== null && body !== undefined && typeof body === 'object') {
+  if (hasParsedBody(request)) {
     console.warn(
       '[Tern] Warning: request body is already parsed as JSON. '
         + 'Signature verification may fail. '

src/index.ts

@@ -1,3 +1,4 @@
+import { timingSafeEqual } from 'crypto';
 import {
   WebhookConfig,
   WebhookVerificationResult,
@@ -125,27 +126,36 @@ export class WebhookVerificationService {
       errorCode?: WebhookErrorCode;
     }> = [];
 
-    for (const [platform, secret] of Object.entries(secrets)) {
-      if (!secret) {
-        continue;
-      }
-
-      const result = await this.verifyWithPlatformConfig<TPayload>(
-        requestClone,
-        platform.toLowerCase() as WebhookPlatform,
-        secret,
-        toleranceInSeconds,
-        normalize,
-      );
-
-      if (result.isValid) {
-        return result;
-      }
+    const verificationResults = await Promise.all(
+      Object.entries(secrets)
+        .filter(([, secret]) => Boolean(secret))
+        .map(async ([platform, secret]) => {
+          const normalizedPlatform = platform.toLowerCase() as WebhookPlatform;
+          const result = await this.verifyWithPlatformConfig<TPayload>(
+            requestClone,
+            normalizedPlatform,
+            secret as string,
+            toleranceInSeconds,
+            normalize,
+          );
+
+          return {
+            platform: normalizedPlatform,
+            result,
+          };
+        }),
+    );
+
+    const firstValid = verificationResults.find((item) => item.result.isValid);
+    if (firstValid) {
+      return firstValid.result;
+    }
 
+    for (const item of verificationResults) {
       failedAttempts.push({
-        platform: platform.toLowerCase() as WebhookPlatform,
-        error: result.error,
-        errorCode: result.errorCode,
+        platform: item.platform,
+        error: item.result.error,
+        errorCode: item.result.errorCode,
       });
     }
 
@@ -166,7 +176,6 @@ export class WebhookVerificationService {
     };
   }
 
-
   private static resolveCanonicalEventId(
     platform: WebhookPlatform,
     metadata?: Record<string, any>,
@@ -177,6 +186,17 @@ export class WebhookVerificationService {
     return `${platform}_${rawId}`;
   }
 
+  private static safeCompare(a: string, b: string): boolean {
+    if (a.length !== b.length) {
+      return false;
+    }
+
+    return timingSafeEqual(
+      new TextEncoder().encode(a),
+      new TextEncoder().encode(b),
+    );
+  }
+
   private static pickString(...candidates: Array<unknown>): string | undefined {
     for (const candidate of candidates) {
       if (candidate === undefined || candidate === null) {
@@ -228,7 +248,7 @@ export class WebhookVerificationService {
       case 'doppler':
         return this.pickString(payload?.event?.id, metadata?.id) || null;
       case 'sanity':
-        return this.pickString(payload?.transactionId, payload?._id) || null;
+        return this.pickString(payload?.transactionId, payload?.['_id']) || null;
       case 'razorpay':
         return this.pickString(
           payload?.payload?.payment?.entity?.id,
@@ -261,7 +281,7 @@ export class WebhookVerificationService {
   }
 
   static detectPlatform(request: Request): WebhookPlatform {
-    const headers = request.headers;
+    const { headers } = request;
 
     if (headers.has('stripe-signature')) return 'stripe';
     if (headers.has('x-hub-signature-256')) return 'github';
@@ -324,8 +344,8 @@ export class WebhookVerificationService {
         };
       }
 
-      // Simple comparison - we don't actually verify, just check if tokens match
-      const isValid = idHeader === webhookId && tokenHeader === webhookToken;
+      const isValid = this.safeCompare(idHeader, webhookId)
+        && this.safeCompare(tokenHeader, webhookToken);
 
       if (!isValid) {
         return {
@@ -364,7 +384,6 @@ export class WebhookVerificationService {
     }
   }
 
-
   static async handleWithQueue(
     request: Request,
     options: {