@c15t/backend 1.5.0 → 1.6.0

package/src/v2/middleware/cors/cors.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import { createCORSOptions } from './cors';
+
+describe('createCORSOptions (unit)', () => {
+	describe('configuration shape', () => {
+		it('returns expected defaults when no trustedOrigins provided', async () => {
+			const config = createCORSOptions();
+			expect(config.credentials).toBe(true);
+			expect(config.maxAge).toBe(600);
+			expect(config.allowHeaders).toEqual([
+				'Content-Type',
+				'Authorization',
+				'x-request-id',
+			]);
+			expect(config.methods).toEqual([
+				'GET',
+				'POST',
+				'PUT',
+				'DELETE',
+				'PATCH',
+				'OPTIONS',
+			]);
+			// origin present -> echo
+			expect(await config.origin('http://localhost:3002')).toBe(
+				'http://localhost:3002'
+			);
+			// no origin -> '*'
+			expect(await config.origin('')).toBe('*');
+		});
+	});
+
+	describe('wildcard "*"', () => {
+		it('allows any concrete origin and echoes it back', async () => {
+			const config = createCORSOptions(['*']);
+			expect(await config.origin('http://localhost:3002')).toBe(
+				'http://localhost:3002'
+			);
+			// missing origin -> '*'
+			expect(await config.origin('')).toBe('*');
+		});
+	});
+
+	describe('specific origins', () => {
+		it('allows trusted origin and rejects untrusted', async () => {
+			const config = createCORSOptions(['http://localhost:3002']);
+			expect(await config.origin('http://localhost:3002')).toBe(
+				'http://localhost:3002'
+			);
+			expect(await config.origin('http://malicious-site.com')).toBeNull();
+		});
+
+		it('treats localhost variants (ports, IPs) as trusted when "localhost" provided', async () => {
+			const config = createCORSOptions(['localhost']);
+			expect(await config.origin('http://localhost:1234')).toBe(
+				'http://localhost:1234'
+			);
+			expect(await config.origin('http://127.0.0.1:3000')).toBe(
+				'http://127.0.0.1:3000'
+			);
+			expect(await config.origin('http://[::1]:3000')).toBe(
+				'http://[::1]:3000'
+			);
+		});
+	});
+
+	describe('www and non-www variants', () => {
+		it('allows www when non-www is trusted', async () => {
+			const config = createCORSOptions(['http://c15t.com']);
+			expect(await config.origin('http://www.c15t.com')).toBe(
+				'http://www.c15t.com'
+			);
+		});
+
+		it('allows non-www when www is trusted', async () => {
+			const config = createCORSOptions(['http://www.c15t.com']);
+			expect(await config.origin('http://c15t.com')).toBe('http://c15t.com');
+		});
+	});
+
+	describe('ports and protocols', () => {
+		it('matches with exact port when provided', async () => {
+			const config = createCORSOptions(['localhost:3002']);
+			expect(await config.origin('http://localhost:3002')).toBe(
+				'http://localhost:3002'
+			);
+			expect(await config.origin('http://localhost:4000')).toBeNull();
+		});
+
+		it('is protocol-agnostic for host comparison', async () => {
+			const config = createCORSOptions(['example.com']);
+			expect(await config.origin('http://example.com')).toBe(
+				'http://example.com'
+			);
+			expect(await config.origin('https://www.example.com')).toBe(
+				'https://www.example.com'
+			);
+		});
+	});
+
+	describe('invalid or missing origins', () => {
+		it('returns null for clearly invalid origins', async () => {
+			const config = createCORSOptions(['example.com']);
+			expect(await config.origin('::::invalid::::')).toBeNull();
+		});
+
+		it('returns "*" when origin header is missing/empty', async () => {
+			const config = createCORSOptions(['*']);
+			expect(await config.origin('')).toBe('*');
+		});
+	});
+});

package/src/v2/middleware/cors/cors.ts

@@ -0,0 +1,192 @@
+/**
+ * CORS middleware utility for c15t that handles origin validation and CORS headers
+ *
+ * @packageDocumentation
+ */
+
+/** Regular expression to match www prefix in domain names */
+const WWW_REGEX = /^www\./;
+
+/** Regular expression to match protocol and www prefix in URLs */
+const PROTOCOL_WWW_REGEX = /^https?:\/\/(www\.)?/;
+
+/**
+ * Supported HTTP methods for CORS
+ */
+const SUPPORTED_METHODS = [
+	'GET',
+	'POST',
+	'PUT',
+	'DELETE',
+	'PATCH',
+	'OPTIONS',
+] as const;
+
+/**
+ * Supported headers for CORS requests
+ */
+const SUPPORTED_HEADERS = [
+	'Content-Type',
+	'Authorization',
+	'x-request-id',
+] as const;
+
+/**
+ * CORS configuration options type
+ */
+export interface CORSConfig {
+	/** Origin validation function */
+	origin: (origin: string) => Promise<string | null>;
+	/** Whether to allow credentials */
+	credentials: boolean;
+	/** Allowed headers */
+	allowHeaders: readonly string[];
+	/** Max age for preflight requests */
+	maxAge: number;
+	/** Allowed HTTP methods */
+	methods: readonly string[];
+}
+
+/**
+ * Default CORS configuration for unrestricted access
+ */
+const DEFAULT_CORS_CONFIG: CORSConfig = {
+	origin: async (origin: string) => {
+		// For default config, always return the origin if it exists, or '*' if it doesn't
+		return await Promise.resolve(origin || '*');
+	},
+	credentials: true,
+	allowHeaders: SUPPORTED_HEADERS,
+	maxAge: 600,
+	methods: SUPPORTED_METHODS,
+} as const;
+
+/**
+ * Creates CORS options configuration for the c15t middleware
+ *
+ * @param trustedOrigins - Array of allowed origin patterns or single string. Can include wildcards ('*').
+ * If undefined, defaults to allowing all origins without credentials.
+ *
+ * @returns CORS configuration object with origin validation function and header settings
+ *
+ * @example
+ * ```ts
+ * const corsOptions = createCORSOptions(['http://localhost:3000', 'https://example.com']);
+ * ```
+ *
+ * @throws {TypeError} When URL parsing fails in origin validation
+ */
+export function createCORSOptions(
+	trustedOrigins?: string[] | string
+): CORSConfig {
+	// If trustedOrigins is undefined or empty, return default config that allows all origins
+	if (!trustedOrigins) {
+		return DEFAULT_CORS_CONFIG;
+	}
+
+	// Convert string to array if needed
+	const origins = Array.isArray(trustedOrigins)
+		? trustedOrigins
+		: [trustedOrigins];
+	if (origins.length === 0) {
+		return DEFAULT_CORS_CONFIG;
+	}
+
+	/**
+	 * Normalizes an origin string by removing protocol and www prefix
+	 *
+	 * @param origin - The origin URL to normalize
+	 * @returns Normalized origin string without protocol and www prefix
+	 *
+	 * @internal
+	 */
+	function normalizeOrigin(origin: string): string {
+		try {
+			// Handle bare domains like 'localhost' or 'example.com'
+			if (
+				!origin.includes('://') &&
+				!origin.includes(':') &&
+				!origin.includes('/')
+			) {
+				return origin.toLowerCase();
+			}
+			// Add protocol if missing
+			const originWithProtocol =
+				origin.startsWith('http://') ||
+				origin.startsWith('https://') ||
+				origin.startsWith('ws://') ||
+				origin.startsWith('wss://')
+					? origin
+					: `http://${origin}`;
+			const url = new URL(originWithProtocol);
+			const hostname = url.hostname.replace(WWW_REGEX, '');
+			// Return without protocol to match both http and https
+			return `${hostname}${url.port ? `:${url.port}` : ''}`;
+		} catch {
+			// Fallback: remove www manually and protocol
+			return origin.replace(PROTOCOL_WWW_REGEX, '').replace(WWW_REGEX, '');
+		}
+	}
+
+	/**
+	 * Expands a list of origins to include www variants
+	 *
+	 * @param origins - Array of origin strings to expand
+	 * @returns Array of origins including www variants
+	 *
+	 * @internal
+	 */
+	function expandWithWWW(origins: string[]): string[] {
+		const expanded = new Set<string>();
+		for (const origin of origins) {
+			if (origin === '*') {
+				expanded.add('*');
+				continue;
+			}
+			const normalized = normalizeOrigin(origin);
+			expanded.add(normalized);
+			// Add www version if not already present
+			if (!normalized.includes('www.')) {
+				expanded.add(`www.${normalized}`);
+			}
+		}
+		return Array.from(expanded);
+	}
+
+	const expandedTrusted = expandWithWWW(origins);
+
+	const returnConfig = {
+		origin: async (origin: string) => {
+			if (!origin) {
+				return '*';
+			}
+			const normalizedOrigin = normalizeOrigin(origin);
+			if (expandedTrusted.includes('*')) {
+				return origin;
+			}
+			// Check if the origin matches any trusted origin
+			const isTrusted = expandedTrusted.some((trusted) => {
+				const normalizedTrusted = normalizeOrigin(trusted);
+				// For localhost, match both with and without port
+				if (normalizedTrusted === 'localhost') {
+					return (
+						normalizedOrigin === 'localhost' ||
+						normalizedOrigin.startsWith('localhost:') ||
+						normalizedOrigin === '127.0.0.1' ||
+						normalizedOrigin.startsWith('127.0.0.1:') ||
+						normalizedOrigin === '[::1]' ||
+						normalizedOrigin.startsWith('[::1]:')
+					);
+				}
+				return normalizedTrusted === normalizedOrigin;
+			});
+			return isTrusted ? origin : null;
+		},
+		credentials: true,
+		allowHeaders: SUPPORTED_HEADERS,
+		maxAge: 600,
+		methods: SUPPORTED_METHODS,
+	};
+
+	return returnConfig;
+}

package/src/v2/middleware/cors/index.ts

@@ -0,0 +1,30 @@
+/**
+ * CORS middleware for c15t
+ *
+ * This module provides comprehensive CORS (Cross-Origin Resource Sharing) functionality including:
+ * - Origin validation with support for wildcards and subdomains
+ * - Flexible CORS options configuration
+ * - Context processing and enrichment
+ * - Protocol-agnostic matching
+ * - Support for www and non-www variants
+ *
+ * @example
+ * ```ts
+ * import { createCORSOptions, isOriginTrusted, processCors } from '@c15t/backend/middleware/cors';
+ *
+ * // Create CORS options with trusted origins
+ * const corsOptions = createCORSOptions(['https://example.com', '*.trusted-domain.com']);
+ *
+ * // Process CORS for a request
+ * const enrichedContext = processCors(request, context, trustedOrigins);
+ *
+ * // Validate an origin directly
+ * const isTrusted = isOriginTrusted('https://api.trusted-domain.com', trustedOrigins);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { createCORSOptions } from './cors';
+export { isOriginTrusted } from './is-origin-trusted';
+export { processCors } from './process-cors';

package/src/v2/middleware/cors/is-origin-trusted.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import { isOriginTrusted } from './is-origin-trusted';
+
+/**
+ * Test suite for CORS utility functions
+ */
+describe('CORS utilities', () => {
+	describe('isOriginTrusted', () => {
+		it('should match exact origins', () => {
+			const trustedDomains = ['example.com'];
+			expect(isOriginTrusted('https://example.com', trustedDomains)).toBe(true);
+			expect(isOriginTrusted('https://other.com', trustedDomains)).toBe(false);
+		});
+
+		it('should handle origins with trailing slashes', () => {
+			const trustedDomains = ['example.com'];
+			expect(isOriginTrusted('https://example.com/', trustedDomains)).toBe(
+				true
+			);
+			expect(isOriginTrusted('https://example.com//', trustedDomains)).toBe(
+				true
+			);
+		});
+
+		it('should handle origins with paths', () => {
+			const trustedDomains = ['example.com'];
+			expect(isOriginTrusted('https://example.com/path', trustedDomains)).toBe(
+				true
+			);
+			expect(
+				isOriginTrusted('https://example.com/path/subpath', trustedDomains)
+			).toBe(true);
+		});
+
+		it('should handle multiple trusted domains', () => {
+			const trustedDomains = ['example.com', 'test.com'];
+			expect(isOriginTrusted('https://example.com', trustedDomains)).toBe(true);
+			expect(isOriginTrusted('https://test.com', trustedDomains)).toBe(true);
+			expect(isOriginTrusted('https://other.com', trustedDomains)).toBe(false);
+		});
+
+		it('should handle wildcard subdomains', () => {
+			const trustedDomains = ['*.example.com'];
+			expect(isOriginTrusted('https://sub.example.com', trustedDomains)).toBe(
+				true
+			);
+			expect(
+				isOriginTrusted('https://other.sub.example.com', trustedDomains)
+			).toBe(true);
+			expect(isOriginTrusted('https://example.com', trustedDomains)).toBe(
+				false
+			);
+			expect(isOriginTrusted('https://other.com', trustedDomains)).toBe(false);
+		});
+
+		it('should handle different protocols', () => {
+			const trustedDomains = ['example.com'];
+			expect(isOriginTrusted('http://example.com', trustedDomains)).toBe(true);
+			expect(isOriginTrusted('wss://example.com', trustedDomains)).toBe(true);
+		});
+
+		it('should handle ports in origins', () => {
+			const trustedDomains = ['example.com'];
+			expect(isOriginTrusted('https://example.com:3000', trustedDomains)).toBe(
+				true
+			);
+			expect(isOriginTrusted('http://example.com:8080', trustedDomains)).toBe(
+				true
+			);
+		});
+
+		it('should handle empty trusted domains array', () => {
+			const trustedDomains: string[] = [];
+			expect(isOriginTrusted('https://example.com', trustedDomains)).toBe(
+				false
+			);
+		});
+
+		it('should handle invalid origin formats', () => {
+			const trustedDomains = ['example.com'];
+			expect(isOriginTrusted('invalid-url', trustedDomains)).toBe(false);
+			expect(isOriginTrusted('', trustedDomains)).toBe(false);
+		});
+
+		it('should handle case sensitivity', () => {
+			const trustedDomains = ['EXAMPLE.com'];
+			expect(isOriginTrusted('https://example.com', trustedDomains)).toBe(true);
+			expect(isOriginTrusted('https://EXAMPLE.COM', trustedDomains)).toBe(true);
+		});
+
+		it('should handle subdomain levels with wildcards', () => {
+			const trustedDomains = ['*.example.com'];
+			expect(isOriginTrusted('https://a.b.example.com', trustedDomains)).toBe(
+				true
+			);
+			expect(isOriginTrusted('https://a.example.com', trustedDomains)).toBe(
+				true
+			);
+			expect(isOriginTrusted('https://example.com', trustedDomains)).toBe(
+				false
+			);
+		});
+	});
+});

package/src/v2/middleware/cors/is-origin-trusted.ts

@@ -0,0 +1,126 @@
+/**
+ * Origin validation utilities for CORS security
+ *
+ * @packageDocumentation
+ */
+
+import type { Logger } from '@doubletie/logger';
+
+/**
+ * Regular expression to strip protocol, trailing slashes, and port numbers from URLs
+ * Matches:
+ * - http:// or https:// protocol
+ * - ws:// or wss:// protocol
+ * - trailing slashes
+ * - port numbers with colon
+ *
+ * @internal
+ */
+export const STRIP_REGEX = /^(https?:\/\/)|(wss?:\/\/)|(\/+$)|:\d+/g;
+
+/**
+ * Checks if a domain matches a wildcard pattern
+ *
+ * @param hostname - The hostname to check
+ * @param wildcardPattern - The wildcard pattern (e.g. *.example.com)
+ * @param logger - Optional logger for debugging
+ * @returns true if the hostname matches the wildcard pattern
+ *
+ * @internal
+ */
+function matchesWildcard(
+	hostname: string,
+	wildcardPattern: string,
+	logger?: Logger
+): boolean {
+	const wildcardDomain = wildcardPattern.slice(2); // Remove *. prefix
+	const parts = hostname.split('.');
+	const isValid = parts.length > 2 && hostname.endsWith(wildcardDomain);
+
+	logger?.debug(
+		`Wildcard match result: ${isValid} ${hostname} ends with ${wildcardDomain} ${parts.length > 2} ${hostname.endsWith(wildcardDomain)}`
+	);
+
+	return isValid;
+}
+
+/**
+ * Validates if a given origin matches any of the trusted domain patterns
+ *
+ * Supports:
+ * - Exact domain matches
+ * - Wildcard subdomains (e.g. *.example.com)
+ * - Protocol-agnostic matching
+ * - Case-insensitive comparison
+ *
+ * @param origin - The origin URL to validate (e.g. https://example.com)
+ * @param trustedDomains - Array of trusted domain patterns. Can include wildcards (e.g. *.example.com)
+ * @param logger - Optional logger for debugging validation process
+ *
+ * @returns `true` if the origin matches any trusted domain pattern, `false` otherwise
+ *
+ * @throws {Error} When trustedDomains array is empty
+ * @throws {TypeError} When origin URL is invalid
+ *
+ * @example
+ * ```ts
+ * // Simple domain matching
+ * isOriginTrusted('https://example.com', ['example.com']); // true
+ *
+ * // Wildcard subdomain matching
+ * isOriginTrusted('https://api.example.com', ['*.example.com']); // true
+ *
+ * // Allow all origins
+ * isOriginTrusted('https://any-domain.com', ['*']); // true
+ * ```
+ */
+export function isOriginTrusted(
+	origin: string,
+	trustedDomains: string[],
+	logger?: Logger
+): boolean {
+	try {
+		if (trustedDomains.length === 0) {
+			throw new Error('No trusted domains');
+		}
+
+		logger?.debug(
+			`Checking if origin ${origin} is trusted in ${trustedDomains}`
+		);
+
+		// Special case: if "*" is in trusted domains, allow all origins
+		if (trustedDomains.includes('*')) {
+			logger?.debug('Allowing all origins');
+			return true;
+		}
+
+		// Parse the origin URL to get just the hostname
+		const url = new URL(origin);
+		const originHostname = url.hostname.toLowerCase();
+		logger?.debug(`Parsed origin hostname: ${originHostname}`);
+
+		return trustedDomains.some((domain) => {
+			// Handle empty domains (which might come from splitting empty strings)
+			if (!domain || domain.trim() === '') {
+				logger?.debug('Skipping empty domain');
+				return false;
+			}
+
+			const strippedDomain = domain.replace(STRIP_REGEX, '').toLowerCase();
+			logger?.debug(`Checking against stripped domain: ${strippedDomain}`);
+
+			if (strippedDomain.startsWith('*.')) {
+				return matchesWildcard(originHostname, strippedDomain, logger);
+			}
+
+			const isMatch = originHostname === strippedDomain;
+			logger?.debug(
+				`Exact match result: ${isMatch} ${originHostname} === ${strippedDomain}`
+			);
+			return isMatch;
+		});
+	} catch (error) {
+		logger?.error('Error validating origin:', error);
+		return false;
+	}
+}

package/src/v2/middleware/cors/process-cors.ts

@@ -0,0 +1,91 @@
+/**
+ * CORS processing middleware for c15t
+ * Handles origin validation and context enrichment
+ *
+ * @packageDocumentation
+ */
+
+import type { C15TContext } from '~/v2/types';
+import { isOriginTrusted } from './is-origin-trusted';
+
+/**
+ * Result of CORS processing
+ * @internal
+ */
+interface CORSProcessingResult {
+	/** The origin from the request */
+	origin: string | null;
+	/** Whether the origin is trusted */
+	isTrusted: boolean;
+}
+
+/**
+ * Extracts and validates CORS information from a request
+ *
+ * @param request - The request to process
+ * @param trustedOrigins - Array of trusted origins
+ * @param logger - Optional logger for debugging
+ * @returns CORS processing result
+ *
+ * @internal
+ */
+function extractCORSInfo(
+	request: Request,
+	trustedOrigins?: string[],
+	logger?: C15TContext['logger']
+): CORSProcessingResult {
+	const origin = request.headers.get('origin');
+
+	if (!origin || !trustedOrigins) {
+		return {
+			origin: origin,
+			isTrusted: false,
+		};
+	}
+
+	return {
+		origin,
+		isTrusted: isOriginTrusted(origin, trustedOrigins, logger),
+	};
+}
+
+/**
+ * Processes CORS validation for an incoming request and enriches the context
+ * with origin information. This middleware function validates the origin against
+ * trusted patterns and updates the context with the validation results.
+ *
+ * @param request - The incoming HTTP request to process
+ * @param context - The c15t middleware context to enrich
+ * @param trustedOrigins - Array of trusted origin patterns. Can include wildcards ('*')
+ *
+ * @returns The enriched context with origin validation results
+ *
+ * @example
+ * ```ts
+ * const enrichedContext = processCors(
+ *   request,
+ *   context,
+ *   ['https://example.com', '*.trusted-domain.com']
+ * );
+ * ```
+ *
+ * @see {@link isOriginTrusted} for origin validation details
+ */
+export const processCors = (
+	request: Request,
+	context: C15TContext,
+	trustedOrigins?: string[]
+): C15TContext => {
+	const { origin, isTrusted } = extractCORSInfo(
+		request,
+		trustedOrigins,
+		context.logger
+	);
+
+	if (origin) {
+		context.origin = origin;
+		context.trustedOrigin = isTrusted;
+	}
+
+	return context;
+};

package/src/v2/middleware/openapi/config.ts

@@ -0,0 +1,27 @@
+import type { C15TOptions } from '~/v2/types';
+import { version } from '~/version';
+/**
+ * Default OpenAPI configuration
+ */
+export const createOpenAPIConfig = (options: C15TOptions) => {
+	const basePath = options.basePath || '';
+	return {
+		enabled: true,
+		specPath: `${basePath}/spec.json`,
+		docsPath: `${basePath}/docs`,
+		...(options.advanced?.openapi || {}),
+	};
+};
+
+/**
+ * Default OpenAPI options
+ */
+export const createDefaultOpenAPIOptions = (options: C15TOptions) => ({
+	info: {
+		title: options.appName || 'c15t API',
+		version,
+		description: 'API for consent management',
+	},
+	servers: [{ url: options.basePath || '/' }],
+	security: [{ bearerAuth: [] }],
+});