@pierre/storage 0.0.3 → 0.0.6

package/src/util.ts

@@ -0,0 +1,62 @@
+export function timingSafeEqual(a: string | Uint8Array, b: string | Uint8Array): boolean {
+	const bufferA = typeof a === 'string' ? new TextEncoder().encode(a) : a;
+	const bufferB = typeof b === 'string' ? new TextEncoder().encode(b) : b;
+
+	if (bufferA.length !== bufferB.length) return false;
+
+	let result = 0;
+	for (let i = 0; i < bufferA.length; i++) {
+		result |= bufferA[i] ^ bufferB[i];
+	}
+	return result === 0;
+}
+
+export async function getEnvironmentCrypto() {
+	if (!globalThis.crypto) {
+		const { webcrypto } = await import('node:crypto');
+		return webcrypto;
+	}
+	return globalThis.crypto;
+}
+
+export async function createHmac(algorithm: string, secret: string, data: string): Promise<string> {
+	if (algorithm !== 'sha256') {
+		throw new Error('Only sha256 algorithm is supported');
+	}
+	if (!secret || secret.length === 0) {
+		throw new Error('Secret is required');
+	}
+
+	const crypto = await getEnvironmentCrypto();
+	const encoder = new TextEncoder();
+	const key = await crypto.subtle.importKey(
+		'raw',
+		encoder.encode(secret),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign'],
+	);
+
+	const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(data));
+	return Array.from(new Uint8Array(signature))
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('');
+}
+
+// Keep the legacy async function for backward compatibility
+export async function createHmacAsync(secret: string, data: string): Promise<string> {
+	const crypto = await getEnvironmentCrypto();
+	const encoder = new TextEncoder();
+	const key = await crypto.subtle.importKey(
+		'raw',
+		encoder.encode(secret),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign'],
+	);
+
+	const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(data));
+	return Array.from(new Uint8Array(signature))
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('');
+}

package/src/webhook.ts

@@ -0,0 +1,251 @@
+/**
+ * Webhook validation utilities for Pierre Git Storage
+ */
+
+import type {
+	ParsedWebhookSignature,
+	WebhookEventPayload,
+	WebhookValidationOptions,
+	WebhookValidationResult,
+} from './types';
+
+import { createHmac, timingSafeEqual } from './util';
+
+const DEFAULT_MAX_AGE_SECONDS = 300; // 5 minutes
+
+/**
+ * Parse the X-Pierre-Signature header
+ * Format: t=<timestamp>,sha256=<signature>
+ */
+export function parseSignatureHeader(header: string): ParsedWebhookSignature | null {
+	if (!header || typeof header !== 'string') {
+		return null;
+	}
+
+	let timestamp = '';
+	let signature = '';
+
+	// Split by comma and parse each element
+	const elements = header.split(',');
+	for (const element of elements) {
+		const trimmedElement = element.trim();
+		const parts = trimmedElement.split('=', 2);
+		if (parts.length !== 2) {
+			continue;
+		}
+
+		const [key, value] = parts;
+		switch (key) {
+			case 't':
+				timestamp = value;
+				break;
+			case 'sha256':
+				signature = value;
+				break;
+		}
+	}
+
+	if (!timestamp || !signature) {
+		return null;
+	}
+
+	return { timestamp, signature };
+}
+
+/**
+ * Validate a webhook signature and timestamp
+ *
+ * @param payload - The raw webhook payload (request body)
+ * @param signatureHeader - The X-Pierre-Signature header value
+ * @param secret - The webhook secret for HMAC verification
+ * @param options - Validation options
+ * @returns Validation result with details
+ *
+ * @example
+ * ```typescript
+ * const result = await validateWebhookSignature(
+ *   requestBody,
+ *   request.headers['x-pierre-signature'],
+ *   webhookSecret
+ * );
+ *
+ * if (!result.valid) {
+ *   console.error('Invalid webhook:', result.error);
+ *   return;
+ * }
+ * ```
+ */
+export async function validateWebhookSignature(
+	payload: string | Buffer,
+	signatureHeader: string,
+	secret: string,
+	options: WebhookValidationOptions = {},
+): Promise<WebhookValidationResult> {
+	if (!secret || secret.length === 0) {
+		return {
+			valid: false,
+			error: 'Empty secret is not allowed',
+		};
+	}
+
+	// Parse the signature header
+	const parsed = parseSignatureHeader(signatureHeader);
+	if (!parsed) {
+		return {
+			valid: false,
+			error: 'Invalid signature header format',
+		};
+	}
+
+	// Parse timestamp
+	const timestamp = Number.parseInt(parsed.timestamp, 10);
+	if (isNaN(timestamp)) {
+		return {
+			valid: false,
+			error: 'Invalid timestamp in signature',
+		};
+	}
+
+	// Validate timestamp age (prevent replay attacks)
+	const maxAge = options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
+	if (maxAge > 0) {
+		const now = Math.floor(Date.now() / 1000);
+		const age = now - timestamp;
+
+		if (age > maxAge) {
+			return {
+				valid: false,
+				error: `Webhook timestamp too old (${age} seconds)`,
+				timestamp,
+			};
+		}
+
+		// Also reject timestamps from the future (clock skew tolerance of 60 seconds)
+		if (age < -60) {
+			return {
+				valid: false,
+				error: 'Webhook timestamp is in the future',
+				timestamp,
+			};
+		}
+	}
+
+	// Convert payload to string if it's a Buffer
+	const payloadStr = typeof payload === 'string' ? payload : payload.toString('utf8');
+
+	// Compute expected signature
+	// Format: HMAC-SHA256(secret, timestamp + "." + payload)
+	const signedData = `${parsed.timestamp}.${payloadStr}`;
+	const expectedSignature = await createHmac('sha256', secret, signedData);
+
+	// Compare signatures using constant-time comparison
+	const expectedBuffer = Buffer.from(expectedSignature);
+	const actualBuffer = Buffer.from(parsed.signature);
+
+	// Ensure both buffers are the same length for timing-safe comparison
+	if (expectedBuffer.length !== actualBuffer.length) {
+		return {
+			valid: false,
+			error: 'Invalid signature',
+			timestamp,
+		};
+	}
+
+	const signaturesMatch = timingSafeEqual(expectedBuffer, actualBuffer);
+	if (!signaturesMatch) {
+		return {
+			valid: false,
+			error: 'Invalid signature',
+			timestamp,
+		};
+	}
+
+	return {
+		valid: true,
+		timestamp,
+	};
+}
+
+/**
+ * Validate a webhook request
+ *
+ * This is a convenience function that validates the signature and parses the payload.
+ *
+ * @param payload - The raw webhook payload (request body)
+ * @param headers - The request headers (must include x-pierre-signature and x-pierre-event)
+ * @param secret - The webhook secret for HMAC verification
+ * @param options - Validation options
+ * @returns The parsed webhook payload if valid, or validation error
+ *
+ * @example
+ * ```typescript
+ * const result = await validateWebhook(
+ *   request.body,
+ *   request.headers,
+ *   process.env.WEBHOOK_SECRET
+ * );
+ *
+ * if (!result.valid) {
+ *   return new Response('Invalid webhook', { status: 401 });
+ * }
+ *
+ * // Type-safe access to the webhook payload
+ * console.log('Push event:', result.payload);
+ * ```
+ */
+export async function validateWebhook(
+	payload: string | Buffer,
+	headers: Record<string, string | string[] | undefined>,
+	secret: string,
+	options: WebhookValidationOptions = {},
+): Promise<WebhookValidationResult & { payload?: WebhookEventPayload }> {
+	// Get signature header
+	const signatureHeader = headers['x-pierre-signature'] || headers['X-Pierre-Signature'];
+	if (!signatureHeader || Array.isArray(signatureHeader)) {
+		return {
+			valid: false,
+			error: 'Missing or invalid X-Pierre-Signature header',
+		};
+	}
+
+	// Get event type header
+	const eventType = headers['x-pierre-event'] || headers['X-Pierre-Event'];
+	if (!eventType || Array.isArray(eventType)) {
+		return {
+			valid: false,
+			error: 'Missing or invalid X-Pierre-Event header',
+		};
+	}
+
+	// Validate signature
+	const validationResult = await validateWebhookSignature(
+		payload,
+		signatureHeader,
+		secret,
+		options,
+	);
+
+	if (!validationResult.valid) {
+		return validationResult;
+	}
+
+	// Parse payload
+	const payloadStr = typeof payload === 'string' ? payload : payload.toString('utf8');
+	let parsedPayload: WebhookEventPayload;
+	try {
+		parsedPayload = JSON.parse(payloadStr);
+	} catch {
+		return {
+			valid: false,
+			error: 'Invalid JSON payload',
+			timestamp: validationResult.timestamp,
+		};
+	}
+
+	return {
+		valid: true,
+		eventType,
+		timestamp: validationResult.timestamp,
+		payload: parsedPayload,
+	};
+}