@c15t/backend 1.8.0 → 2.0.0-rc.1

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

@@ -1,195 +0,0 @@
-/**
- * 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',
-	'x-c15t-country',
-	'x-c15t-region',
-	'accept-language',
-] 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

@@ -1,30 +0,0 @@
-/**
- * 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

@@ -1,164 +0,0 @@
-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
-			);
-		});
-
-		describe('multiple subdomain levels', () => {
-			it('should match base domain when explicitly listed', () => {
-				const trustedDomains = ['my-site.com'];
-				expect(isOriginTrusted('https://my-site.com', trustedDomains)).toBe(
-					true
-				);
-			});
-
-			it('should match single-level subdomain with wildcard pattern', () => {
-				const trustedDomains = ['*.my-site.com'];
-				expect(
-					isOriginTrusted('https://foobar.my-site.com', trustedDomains)
-				).toBe(true);
-			});
-
-			it('should match multi-level subdomain with wildcard pattern', () => {
-				const trustedDomains = ['*.my-site.com'];
-				expect(
-					isOriginTrusted('https://foo.bar.my-site.com', trustedDomains)
-				).toBe(true);
-			});
-
-			it('should match three-level subdomain with wildcard pattern', () => {
-				const trustedDomains = ['*.my-site.com'];
-				expect(
-					isOriginTrusted('https://a.b.c.my-site.com', trustedDomains)
-				).toBe(true);
-			});
-
-			it('should not match base domain with wildcard pattern', () => {
-				const trustedDomains = ['*.my-site.com'];
-				expect(isOriginTrusted('https://my-site.com', trustedDomains)).toBe(
-					false
-				);
-			});
-
-			it('should not match similar domain that is not a subdomain', () => {
-				const trustedDomains = ['*.my-site.com'];
-				expect(isOriginTrusted('https://notmy-site.com', trustedDomains)).toBe(
-					false
-				);
-				expect(
-					isOriginTrusted('https://foobar-my-site.com', trustedDomains)
-				).toBe(false);
-			});
-
-			it('should match both base domain and subdomains when both are configured', () => {
-				const trustedDomains = ['my-site.com', '*.my-site.com'];
-				expect(isOriginTrusted('https://my-site.com', trustedDomains)).toBe(
-					true
-				);
-				expect(
-					isOriginTrusted('https://foobar.my-site.com', trustedDomains)
-				).toBe(true);
-				expect(
-					isOriginTrusted('https://foo.bar.my-site.com', trustedDomains)
-				).toBe(true);
-			});
-		});
-	});
-});

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

@@ -1,129 +0,0 @@
-/**
- * Origin validation utilities for CORS security
- *
- * @packageDocumentation
- */
-
-import type { Logger } from '@c15t/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
-
-	// Ensure the hostname is not the base domain and ends with .wildcardDomain
-	// This prevents matching domains like 'foobar-my-site.com' against '*.my-site.com'
-	const isValid =
-		hostname !== wildcardDomain && hostname.endsWith(`.${wildcardDomain}`);
-
-	logger?.debug(
-		`Wildcard match result: ${isValid} ${hostname} ends with .${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

@@ -1,91 +0,0 @@
-/**
- * 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

@@ -1,27 +0,0 @@
-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: [] }],
-});