Merge pull request #438 from ever-works/fix/polar-webhook-signature-verification

fix(payment): fix Polar webhook signature verification

Author: Innocent-Akim

app/api/polar/webhook/route.ts

@@ -57,7 +57,7 @@ const WEBHOOK_ID_HEADER = 'webhook-id';
  *         required: true
  *         schema:
  *           type: string
-	 *         description: "Polar webhook signature for verification (HMAC SHA256, format: v1,<hex_signature>)"
+ *         description: "Polar webhook signature for verification (HMAC SHA256, format: v1,<hex_signature>)"
  *       - name: "webhook-timestamp"
  *         in: "header"
  *         required: true
@@ -118,18 +118,15 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
 			return NextResponse.json({ error: 'No signature provided' }, { status: 400 });
 		}
 
-		// Extract signature from format "v1,<signature>"
-		// Polar uses format: v1,<hex_signature>
-		const signatureParts = signatureHeader.split(',');
-		const signature = signatureParts.length > 1 ? signatureParts[1] : signatureHeader;
-
+		// Pass full signature header (including "v1," prefix) to provider
+		// validateEvent expects the complete header value with format "v1,<signature>"
 		// Process webhook through provider
-		// Pass raw body text, signature, timestamp, and webhook-id for signature verification
+		// Pass raw body text, signature header (full value), timestamp, and webhook-id for signature verification
 		const polarProvider = getOrCreatePolarProvider();
 		const webhookResult = await polarProvider.handleWebhook(
-			body, 
-			signature, 
-			bodyText, 
+			body,
+			signatureHeader,
+			bodyText,
 			timestampHeader || undefined,
 			webhookIdHeader || undefined
 		);
@@ -153,18 +150,18 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
 	} catch (error) {
 		const errorMessage = error instanceof Error ? error.message : 'Unknown error';
 		const isDevelopment = coreConfig.NODE_ENV === 'development';
-		
+
 		logger.error('Webhook processing failed', {
 			error: errorMessage,
 			stack: error instanceof Error ? error.stack : undefined
 		});
 
 		// Don't expose internal error details in production
 		return NextResponse.json(
-			{ 
+			{
 				error: 'Webhook processing failed',
 				...(isDevelopment && { details: errorMessage })
-			}, 
+			},
 			{ status: 400 }
 		);
 	}

lib/payment/lib/providers/polar-provider.ts

@@ -1,7 +1,8 @@
 import { User } from '@supabase/auth-js';
 import React from 'react';
 import { Polar } from '@polar-sh/sdk';
-import crypto from 'crypto';
+import { validateEvent } from '@polar-sh/sdk/webhooks';
+
 import {
 	PaymentProviderInterface,
 	PaymentIntent,
@@ -109,6 +110,16 @@ const polarTranslations = {
 
 const defaultAppUrl = process.env.NEXT_PUBLIC_APP_URL || 'https://demo.ever.works';
 
+/**
+ * Cache entry for webhook ID deduplication
+ * Stores webhook IDs with TTL to prevent replay attacks
+ */
+interface WebhookIdCacheEntry {
+	webhookId: string;
+	processedAt: number;
+	expiresAt: number;
+}
+
 export class PolarProvider implements PaymentProviderInterface {
 	private polar: Polar;
 	private webhookSecret: string;
@@ -117,6 +128,13 @@ export class PolarProvider implements PaymentProviderInterface {
 	private apiKey: string;
 	private isSandbox: boolean = false;
 	private configuredApiUrl?: string;
+	// In-memory cache for webhook ID deduplication (replay protection)
+	// Key: webhook-id, Value: cache entry with expiration
+	private webhookIdCache: Map<string, WebhookIdCacheEntry> = new Map();
+	// Default replay protection window: ±300 seconds (5 minutes)
+	private readonly REPLAY_PROTECTION_WINDOW_SECONDS: number = 300;
+	// TTL for webhook ID cache entries: window * 2 + 60 seconds buffer (660 seconds = 11 minutes)
+	private readonly WEBHOOK_ID_CACHE_TTL_MS: number = 660000; // (300 * 2 + 60) * 1000
 
 	constructor(config: PolarConfig) {
 		if (!config.apiKey) {
@@ -134,7 +152,10 @@ export class PolarProvider implements PaymentProviderInterface {
 		this.organizationId = config.options?.organizationId;
 		// Clean appUrl: remove quotes, trailing slashes, and whitespace
 		const rawAppUrl = config.options?.appUrl || defaultAppUrl;
-		this.appUrl = rawAppUrl.trim().replace(/^["']|["']$/g, '').replace(/\/+$/, '');
+		this.appUrl = rawAppUrl
+			.trim()
+			.replace(/^["']|["']$/g, '')
+			.replace(/\/+$/, '');
 
 		this.configuredApiUrl = config.options?.apiUrl;
 
@@ -1056,16 +1077,16 @@ export class PolarProvider implements PaymentProviderInterface {
 	}
 
 	/**
-	 * Verifies webhook signature using Polar's official signature format
-	 * Polar uses: HMAC SHA256 of raw request body only (hex digest)
-	 * The webhook secret must be base64-decoded before HMAC computation
+	 * Verifies webhook signature using Polar SDK's validateEvent function
+	 * Uses the official @polar-sh/sdk webhook validation utility
+	 * Also implements replay protection via timestamp and webhook-id checks
 	 *
-	 * @param signature - Received signature from header (hex format)
+	 * @param signature - Received signature header value (should include "v1," prefix, e.g., "v1,<hex_signature>")
 	 * @param rawBody - Raw request body (required, no fallback)
 	 * @param payload - Parsed payload (unused, kept for compatibility)
-	 * @param timestamp - Webhook timestamp (optional, used for replay protection only)
-	 * @param webhookId - Webhook ID (optional, not used in signature)
-	 * @throws Error if signature verification fails
+	 * @param timestamp - Webhook timestamp (optional, used for replay protection)
+	 * @param webhookId - Webhook ID (optional, used for idempotency/replay protection)
+	 * @throws Error if signature verification fails or replay protection checks fail
 	 */
 	private verifyWebhookSignature(
 		signature: string,
@@ -1092,77 +1113,215 @@ export class PolarProvider implements PaymentProviderInterface {
 			throw new Error('Missing webhook-signature header required for signature verification');
 		}
 
-		// Validate timestamp replay protection if provided (optional but recommended)
-		if (timestamp) {
-			const webhookTime = parseInt(timestamp, 10);
-			const currentTime = Math.floor(Date.now() / 1000);
-			const tolerance = 300; // 5 minutes in seconds
+		try {
+			// Build headers object for validateEvent
+			// Polar SDK validateEvent expects headers with webhook-signature (full value including "v1," prefix),
+			// webhook-timestamp, and webhook-id
+			// The signature should be in format "v1,<hex_signature>" as sent by Polar
+			const headers: Record<string, string> = {
+				'webhook-signature': signature
+			};
 
-			if (isNaN(webhookTime)) {
-				this.logger.error('Invalid webhook timestamp format', {
-					bodyLength: rawBody.length
-				});
-				throw new Error('Invalid webhook timestamp format');
+			if (timestamp) {
+				headers['webhook-timestamp'] = timestamp;
 			}
 
-			if (Math.abs(currentTime - webhookTime) > tolerance) {
-				this.logger.error('Webhook timestamp is outside acceptable window', {
-					timeDifference: Math.abs(currentTime - webhookTime),
-					tolerance,
-					bodyLength: rawBody.length
-				});
-				throw new Error('Webhook timestamp is outside acceptable window');
+			if (webhookId) {
+				headers['webhook-id'] = webhookId;
 			}
-		}
 
-		// Base64-decode the webhook secret before HMAC computation (per Polar docs)
-		let secretKey: Buffer;
-		try {
-			secretKey = Buffer.from(this.webhookSecret, 'base64');
+			// Step 1: Verify HMAC signature using Polar SDK
+			// validateEvent takes the raw body, headers object, and secret
+			// It expects the webhook-signature header to contain the full value "v1,<signature>"
+			validateEvent(rawBody, headers, this.webhookSecret);
+
+			this.logger.debug('Webhook signature verified successfully using @polar-sh/sdk validateEvent', {
+				bodyLength: rawBody.length,
+				hasTimestamp: !!timestamp,
+				signatureFormat: signature.startsWith('v1,') ? 'v1,<signature>' : 'raw'
+			});
+
+			// Step 2: Replay protection - Timestamp validation
+			// Reject webhooks outside the acceptable time window (±300 seconds by default)
+			this.validateWebhookTimestamp(timestamp, rawBody.length, webhookId);
+
+			// Step 3: Replay protection - Idempotency check via webhook-id
+			// Ensure we haven't processed this webhook-id before
+			this.checkWebhookIdempotency(webhookId, rawBody.length, timestamp);
 		} catch (error) {
-			this.logger.error('Failed to base64-decode webhook secret', {
-				error: error instanceof Error ? error.message : String(error)
+			// Re-throw errors from replay protection checks as-is
+			if (
+				error instanceof Error &&
+				(error.message.includes('timestamp') || error.message.includes('webhook-id'))
+			) {
+				throw error;
+			}
+
+			this.logger.error('Webhook signature verification failed', {
+				error: error instanceof Error ? error.message : String(error),
+				bodyLength: rawBody.length,
+				hasTimestamp: !!timestamp,
+				hasWebhookId: !!webhookId,
+				signatureFormat: signature.startsWith('v1,') ? 'v1,<signature>' : 'raw'
 			});
-			throw new Error('Invalid webhook secret format (must be base64-encoded)');
+			throw new Error(
+				`Invalid webhook signature: ${error instanceof Error ? error.message : 'Verification failed'}`
+			);
 		}
+	}
 
-		// Compute HMAC-SHA256 over raw body only (no webhookId or timestamp)
-		const expectedSignature = crypto.createHmac('sha256', secretKey).update(rawBody, 'utf8').digest('hex');
+	/**
+	 * Validates webhook timestamp to prevent replay attacks
+	 * Rejects webhooks outside the acceptable time window
+	 *
+	 * @param timestamp - Webhook timestamp from header (Unix timestamp as string)
+	 * @param bodyLength - Length of the request body (for logging)
+	 * @param webhookId - Webhook ID (for logging)
+	 * @throws Error if timestamp is missing, invalid, or outside acceptable window
+	 */
+	private validateWebhookTimestamp(
+		timestamp: string | undefined,
+		bodyLength: number,
+		webhookId: string | undefined
+	): void {
+		// Timestamp is required for replay protection
+		if (!timestamp || typeof timestamp !== 'string' || timestamp.trim().length === 0) {
+			this.logger.error('Webhook timestamp missing or invalid', {
+				bodyLength,
+				webhookId: webhookId || 'unknown',
+				hasTimestamp: !!timestamp
+			});
+			throw new Error('Webhook timestamp is required for replay protection');
+		}
 
-		// Convert incoming signature from hex to buffer for timing-safe comparison
-		let signatureBuffer: Buffer;
-		try {
-			signatureBuffer = Buffer.from(signature, 'hex');
-		} catch (error) {
-			this.logger.error('Invalid signature format (expected hex)', {
-				error: error instanceof Error ? error.message : String(error)
+		// Parse timestamp (Polar sends Unix timestamp as string)
+		const webhookTimestamp = parseInt(timestamp, 10);
+		if (isNaN(webhookTimestamp) || webhookTimestamp <= 0) {
+			this.logger.error('Webhook timestamp is not a valid number', {
+				bodyLength,
+				webhookId: webhookId || 'unknown',
+				timestamp
 			});
-			throw new Error('Invalid webhook signature format (expected hexadecimal)');
+			throw new Error(`Invalid webhook timestamp format: ${timestamp}`);
 		}
 
-		const expectedSignatureBuffer = Buffer.from(expectedSignature, 'hex');
+		// Calculate time difference in seconds
+		const currentTimestamp = Math.floor(Date.now() / 1000);
+		const timeDifference = Math.abs(currentTimestamp - webhookTimestamp);
+
+		// Reject if timestamp is outside acceptable window
+		if (timeDifference > this.REPLAY_PROTECTION_WINDOW_SECONDS) {
+			this.logger.error('Webhook timestamp outside acceptable window', {
+				bodyLength,
+				webhookId: webhookId || 'unknown',
+				webhookTimestamp,
+				currentTimestamp,
+				timeDifferenceSeconds: timeDifference,
+				windowSeconds: this.REPLAY_PROTECTION_WINDOW_SECONDS,
+				isTooOld: webhookTimestamp < currentTimestamp
+			});
+			throw new Error(
+				`Webhook timestamp outside acceptable window: ${timeDifference} seconds difference (max: ${this.REPLAY_PROTECTION_WINDOW_SECONDS} seconds)`
+			);
+		}
 
-		// Use constant-time comparison to prevent timing attacks
-		// timingSafeEqual requires buffers of equal length
-		const signaturesMatch =
-			signatureBuffer.length === expectedSignatureBuffer.length &&
-			crypto.timingSafeEqual(signatureBuffer, expectedSignatureBuffer);
+		this.logger.debug('Webhook timestamp validation passed', {
+			bodyLength,
+			webhookId: webhookId || 'unknown',
+			timeDifferenceSeconds: timeDifference
+		});
+	}
 
-		if (!signaturesMatch) {
-			this.logger.error('Invalid webhook signature', {
-				expectedLength: expectedSignature.length,
-				receivedLength: signature.length,
-				bodyLength: rawBody.length
+	/**
+	 * Checks webhook idempotency to prevent duplicate processing
+	 * Uses in-memory cache with TTL to track processed webhook IDs
+	 *
+	 * @param webhookId - Webhook ID from header
+	 * @param bodyLength - Length of the request body (for logging)
+	 * @param timestamp - Webhook timestamp (for logging)
+	 * @throws Error if webhook-id is missing or has already been processed
+	 */
+	private checkWebhookIdempotency(
+		webhookId: string | undefined,
+		bodyLength: number,
+		timestamp: string | undefined
+	): void {
+		// Webhook ID is required for idempotency checks
+		if (!webhookId || typeof webhookId !== 'string' || webhookId.trim().length === 0) {
+			this.logger.error('Webhook ID missing or invalid', {
+				bodyLength,
+				timestamp: timestamp || 'unknown',
+				hasWebhookId: !!webhookId
 			});
-			throw new Error('Invalid webhook signature');
+			throw new Error('Webhook ID is required for idempotency protection');
+		}
+
+		// Clean up expired cache entries periodically (every 100 checks, approximately)
+		if (Math.random() < 0.01) {
+			this.cleanupExpiredWebhookIds();
+		}
+
+		// Check if webhook ID was already processed
+		const existingEntry = this.webhookIdCache.get(webhookId);
+		const now = Date.now();
+
+		if (existingEntry) {
+			// Check if entry is still valid (not expired)
+			if (existingEntry.expiresAt > now) {
+				this.logger.error('Webhook ID already processed (duplicate/replay detected)', {
+					bodyLength,
+					webhookId,
+					timestamp: timestamp || 'unknown',
+					previouslyProcessedAt: new Date(existingEntry.processedAt).toISOString(),
+					timeSinceFirstProcessing: Math.floor((now - existingEntry.processedAt) / 1000) + ' seconds'
+				});
+				throw new Error(`Webhook ID already processed: ${webhookId} (replay attack detected)`);
+			} else {
+				// Entry expired, remove it
+				this.webhookIdCache.delete(webhookId);
+			}
 		}
 
-		this.logger.debug('Webhook signature verified successfully', {
-			bodyLength: rawBody.length,
-			hasTimestamp: !!timestamp
+		// Record this webhook ID with TTL
+		const cacheEntry: WebhookIdCacheEntry = {
+			webhookId,
+			processedAt: now,
+			expiresAt: now + this.WEBHOOK_ID_CACHE_TTL_MS
+		};
+
+		this.webhookIdCache.set(webhookId, cacheEntry);
+
+		this.logger.debug('Webhook ID recorded for idempotency', {
+			bodyLength,
+			webhookId,
+			timestamp: timestamp || 'unknown',
+			expiresAt: new Date(cacheEntry.expiresAt).toISOString()
 		});
 	}
 
+	/**
+	 * Cleans up expired webhook ID cache entries
+	 * Removes entries that have exceeded their TTL
+	 */
+	private cleanupExpiredWebhookIds(): void {
+		const now = Date.now();
+		let cleanedCount = 0;
+
+		for (const [webhookId, entry] of this.webhookIdCache.entries()) {
+			if (entry.expiresAt <= now) {
+				this.webhookIdCache.delete(webhookId);
+				cleanedCount++;
+			}
+		}
+
+		if (cleanedCount > 0) {
+			this.logger.debug('Cleaned up expired webhook ID cache entries', {
+				cleanedCount,
+				remainingEntries: this.webhookIdCache.size
+			});
+		}
+	}
+
 	/**
 	 * Maps Polar webhook event types to internal event format
 	 *