@c15t/backend 0.0.1-rc.10

package/src/api/middlewares/origin-check.ts

@@ -0,0 +1,260 @@
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { GenericEndpointContext } from '~/types';
+import { getHost, getOrigin, getProtocol } from '~/utils/url';
+import { wildcardMatch } from '~/utils/wildcard';
+import { createAuthMiddleware } from '../call';
+
+/**
+ * Regular expression for validating relative URLs
+ * Ensures URLs don't contain path traversal attacks and have a valid structure
+ *
+ * @internal
+ */
+const VALID_RELATIVE_URL_REGEX =
+	/^\/(?!\/|\\|%2f|%5c)[\w\-./]*(?:\?[\w\-./=&%]*)?$/;
+
+/**
+ * Middleware that validates request origins and callback URLs against trusted origins
+ *
+ * This middleware performs security checks to prevent cross-site request forgery (CSRF)
+ * and open redirect vulnerabilities by validating various URLs in the request against
+ * a list of trusted origins configured in the C15T context.
+ *
+ * @remarks
+ * The middleware checks the following URLs from request body and headers:
+ * - Origin/Referer header (when cookies are used and CSRF checks are enabled)
+ * - callbackURL
+ * - redirectTo
+ * - errorCallbackURL
+ * - newSubjectCallbackURL
+ *
+ * URLs are validated using exact matching for origins and wildcard pattern matching
+ * for hostnames. Relative URLs are allowed for callback URLs but must match a safe
+ * URL pattern.
+ *
+ * @throws {C15TError} Throws a FORBIDDEN error if any URL fails validation
+ *
+ * @example
+ * ```typescript
+ * import { c15tInstance } from '@c15t/backend';
+ * // This middleware is typically used in router configuration
+ * const router = createRouter(endpoints, {
+ *   routerMiddleware: [
+ *     {
+ *       path: '/**',
+ *       middleware: originCheckMiddleware
+ *     }
+ *   ]
+ * });
+ *
+ * // To configure trusted origins in your C15T options:
+ * const c15t = c15tInstance({
+ *   // Static list of trusted origins
+ *   trustedOrigins: [
+ *     'https://example.com',
+ *     'https://*.example.org'
+ *   ]
+ *
+ *   // Or a function to dynamically determine trusted origins
+ *   trustedOrigins: (request) => {
+ *     const host = new URL(request.url).host;
+ *     return [`https://${host}`, `http://${host}`];
+ *   }
+ * });
+ * ```
+ */
+export const originCheckMiddleware = createAuthMiddleware(async (ctx) => {
+	if (ctx.request?.method !== 'POST' || !ctx.request) {
+		return;
+	}
+	const { body, query, context } = ctx;
+	const originHeader =
+		ctx.headers?.get('origin') || ctx.headers?.get('referer') || '';
+	const callbackURL = body?.callbackURL || query?.callbackURL;
+	const redirectURL = body?.redirectTo;
+	const errorCallbackURL = body?.errorCallbackURL;
+	const newSubjectCallbackURL = body?.newSubjectCallbackURL;
+	const trustedOrigins: string[] = Array.isArray(context.options.trustedOrigins)
+		? context.trustedOrigins
+		: [
+				...context.trustedOrigins,
+				...(context.options.trustedOrigins?.(ctx.request) || []),
+			];
+	const usesCookies = ctx.headers?.has('cookie');
+
+	/**
+	 * Determines if a URL matches a trusted origin pattern
+	 *
+	 * @internal
+	 * @param url - The URL to check
+	 * @param pattern - The trusted origin pattern to match against
+	 * @returns Whether the URL matches the pattern
+	 */
+	const matchesPattern = (url: string, pattern: string): boolean => {
+		if (url.startsWith('/')) {
+			return false;
+		}
+		if (pattern.includes('*')) {
+			return wildcardMatch(pattern)(getHost(url));
+		}
+
+		const protocol = getProtocol(url);
+		return protocol === 'http:' || protocol === 'https:' || !protocol
+			? pattern === getOrigin(url)
+			: url.startsWith(pattern);
+	};
+
+	/**
+	 * Validates a URL against trusted origins
+	 *
+	 * @internal
+	 * @param url - The URL to validate
+	 * @param label - A label describing what type of URL is being validated
+	 * @throws {C15TError} If the URL is not from a trusted origin
+	 */
+	const validateURL = (url: string | undefined, label: string) => {
+		if (!url) {
+			return;
+		}
+		const isTrustedOrigin = trustedOrigins.some(
+			(origin) =>
+				matchesPattern(url, origin) ||
+				(url?.startsWith('/') &&
+					label !== 'origin' &&
+					VALID_RELATIVE_URL_REGEX.test(url))
+		);
+		if (!isTrustedOrigin) {
+			ctx.context.logger.error(`Invalid ${label}: ${url}`);
+			ctx.context.logger.info(
+				`If it's a valid URL, please add ${url} to trustedOrigins in your auth config\n`,
+				`Current list of trustedOrigins: ${trustedOrigins}`
+			);
+			throw new C15TError(
+				'The URL provided is not from a trusted origin. Please ensure the URL is correctly configured in the trusted origins list.',
+				{
+					code: BASE_ERROR_CODES.FORBIDDEN,
+					status: 403,
+					data: {
+						url,
+						label,
+						trustedOrigins,
+					},
+				}
+			);
+		}
+	};
+	if (usesCookies && !ctx.context.options.advanced?.disableCSRFCheck) {
+		validateURL(originHeader, 'origin');
+	}
+	callbackURL && validateURL(callbackURL, 'callbackURL');
+	redirectURL && validateURL(redirectURL, 'redirectURL');
+	errorCallbackURL && validateURL(errorCallbackURL, 'errorCallbackURL');
+	newSubjectCallbackURL &&
+		validateURL(newSubjectCallbackURL, 'newSubjectCallbackURL');
+});
+
+/**
+ * Creates a middleware that validates a specific URL against trusted origins
+ *
+ * This factory function creates a middleware for validating a single URL extracted
+ * from the request context against the list of trusted origins.
+ *
+ * @param getValue - A function that extracts the URL to validate from the endpoint context
+ * @returns A middleware that validates the extracted URL
+ * @throws {C15TError} Throws a FORBIDDEN error if the URL fails validation
+ *
+ * @remarks
+ * Unlike the more comprehensive originCheckMiddleware, this factory allows creating
+ * targeted middleware for specific URL fields or custom extraction logic.
+ *
+ * @example
+ * ```typescript
+ * // Create a middleware that validates the 'returnUrl' from request body
+ * const validateReturnUrl = originCheck(ctx => ctx.body?.returnUrl);
+ *
+ * // Use the middleware in a specific route
+ * router.post('/api/subscribe', validateReturnUrl, subscribeHandler);
+ *
+ * // Create a middleware that validates a URL from a custom header
+ * const validateHeaderUrl = originCheck(ctx =>
+ *   ctx.headers?.get('x-callback-url')
+ * );
+ * ```
+ */
+export const originCheck = (
+	getValue: (ctx: GenericEndpointContext) => string
+) =>
+	createAuthMiddleware(async (ctx) => {
+		if (!ctx.request) {
+			return;
+		}
+		const { context } = ctx;
+		const callbackURL = getValue(ctx);
+		const trustedOrigins: string[] = Array.isArray(
+			context.options.trustedOrigins
+		)
+			? context.trustedOrigins
+			: [
+					...context.trustedOrigins,
+					...(context.options.trustedOrigins?.(ctx.request) || []),
+				];
+
+		/**
+		 * Determines if a URL matches a trusted origin pattern
+		 *
+		 * @internal
+		 * @param url - The URL to check
+		 * @param pattern - The trusted origin pattern to match against
+		 * @returns Whether the URL matches the pattern
+		 */
+		const matchesPattern = (url: string, pattern: string): boolean => {
+			if (url.startsWith('/')) {
+				return false;
+			}
+			if (pattern.includes('*')) {
+				return wildcardMatch(pattern)(getHost(url));
+			}
+			return url.startsWith(pattern);
+		};
+
+		/**
+		 * Validates a URL against trusted origins
+		 *
+		 * @internal
+		 * @param url - The URL to validate
+		 * @param label - A label describing what type of URL is being validated
+		 * @throws {C15TError} If the URL is not from a trusted origin
+		 */
+		const validateURL = (url: string | undefined, label: string) => {
+			if (!url) {
+				return;
+			}
+			const isTrustedOrigin = trustedOrigins.some(
+				(origin) =>
+					matchesPattern(url, origin) ||
+					(url?.startsWith('/') &&
+						label !== 'origin' &&
+						VALID_RELATIVE_URL_REGEX.test(url))
+			);
+			if (!isTrustedOrigin) {
+				ctx.context.logger.error(`Invalid ${label}: ${url}`);
+				ctx.context.logger.info(
+					`If it's a valid URL, please add ${url} to trustedOrigins in your auth config\n`,
+					`Current list of trustedOrigins: ${trustedOrigins}`
+				);
+				throw new C15TError(
+					'The URL provided is not from a trusted origin. Please ensure the URL is correctly configured in the trusted origins list.',
+					{
+						code: BASE_ERROR_CODES.FORBIDDEN,
+						status: 403,
+						data: {
+							url,
+							label,
+							trustedOrigins,
+						},
+					}
+				);
+			}
+		};
+		callbackURL && validateURL(callbackURL, 'callbackURL');
+	});

package/src/api/middlewares/validate-context.ts

@@ -0,0 +1,175 @@
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { C15TContext, C15TPlugin } from '~/types';
+import { createAuthMiddleware } from '../call';
+
+import type { Adapter } from '~/db/adapters/types';
+
+/**
+ * Redacts sensitive information from context for error reporting
+ *
+ * @param context - The context object to redact
+ * @returns A sanitized version of the context
+ */
+function redactContext(context: unknown): Record<string, unknown> {
+	if (!context || typeof context !== 'object') {
+		return { type: typeof context };
+	}
+
+	const typedContext = context as C15TContext;
+	return {
+		baseURL: typedContext.baseURL,
+		storageType: typedContext.storage?.constructor.name,
+		pluginsCount: Array.isArray(typedContext.plugins)
+			? typedContext.plugins.length
+			: 0,
+		hasOptions: !!typedContext.options,
+		hasLogger: !!typedContext.logger,
+		hasPlugins: !!typedContext.plugins,
+	};
+}
+
+/**
+ * Validates plugin initialization status
+ *
+ * @param plugins - Array of configured plugins
+ * @param initializedPlugins - Array of successfully initialized plugins
+ * @returns Array of failed plugin names, or null if all plugins initialized
+ */
+function validatePlugins(
+	plugins: C15TPlugin[] | undefined,
+	initializedPlugins: C15TPlugin[] | undefined
+): string[] | null {
+	if (!plugins?.length) {
+		return null;
+	}
+
+	const initializedNames = new Set(initializedPlugins?.map((p) => p.id) ?? []);
+
+	const failedPlugins = plugins
+		.filter((p) => !initializedNames.has(p.id))
+		.map((p) => p.id);
+
+	return failedPlugins.length > 0 ? failedPlugins : null;
+}
+
+/**
+ * Middleware that validates the context for all routes
+ *
+ * This middleware ensures that the context object is properly structured and
+ * contains all required properties and services before allowing the request to proceed.
+ *
+ * @remarks
+ * The middleware performs comprehensive validation of:
+ * - Basic context structure
+ * - Required configuration options
+ * - Storage adapter availability
+ * - Logger availability
+ * - Plugin initialization status
+ * - Required services and dependencies
+ *
+ * @throws {C15TError} Throws appropriate errors for:
+ * - INVALID_CONFIGURATION: When context or options are invalid
+ * - STORAGE_ERROR: When storage adapter is not available
+ * - INITIALIZATION_FAILED: When required services failed to initialize
+ *
+ * @example
+ * ```typescript
+ * // Using with memory adapter
+ * const router = createRouter(endpoints, {
+ *   routerMiddleware: [
+ *     {
+ *       path: '/**',
+ *       middleware: validateContextMiddleware
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+export const validateContextMiddleware = createAuthMiddleware(async (ctx) => {
+	const { context } = ctx;
+
+	// Basic context validation
+	if (!context || typeof context !== 'object') {
+		throw new C15TError(
+			'The context configuration is incomplete. Please ensure all required configuration options are provided and properly formatted.',
+			{
+				code: BASE_ERROR_CODES.INVALID_CONFIGURATION,
+				status: 500,
+				data: redactContext(context),
+			}
+		);
+	}
+
+	// Ensure the context is properly typed
+	const typedContext = context as C15TContext;
+
+	// Validate required configuration
+	if (!typedContext.options) {
+		throw new C15TError(
+			'The context configuration is missing required options. Please ensure the options object is properly configured.',
+			{
+				code: BASE_ERROR_CODES.INVALID_CONFIGURATION,
+				status: 500,
+			}
+		);
+	}
+
+	// Optional storage adapter validation
+	if (typedContext.storage) {
+		const storage = typedContext.storage as Adapter;
+		const requiredMethods = ['subjects', 'records', 'policies'];
+		const missingMethods = requiredMethods.filter(
+			(method) => !(method in storage)
+		);
+
+		if (missingMethods.length > 0) {
+			typedContext.logger?.warn?.('Storage adapter missing methods', {
+				missingMethods,
+				storageType: storage.constructor.name,
+			});
+		}
+	}
+
+	// Validate logger (make it optional for memory adapter in development)
+	if (!typedContext.logger && process.env.NODE_ENV === 'production') {
+		throw new C15TError(
+			'Logger is required in production environment. Please configure a logger for your application.',
+			{
+				code: BASE_ERROR_CODES.INVALID_CONFIGURATION,
+				status: 500,
+				data: {
+					environment: process.env.NODE_ENV,
+				},
+			}
+		);
+	}
+
+	// Validate plugins if any are configured
+	const failedPlugins = validatePlugins(
+		typedContext.options.plugins,
+		typedContext.plugins as C15TPlugin[] | undefined
+	);
+	if (failedPlugins) {
+		throw new C15TError(
+			'Plugin initialization failed. Some plugins could not be initialized properly. Please check your plugin configuration.',
+			{
+				code: BASE_ERROR_CODES.PLUGIN_INITIALIZATION_FAILED,
+				status: 500,
+				data: {
+					failedPlugins,
+				},
+			}
+		);
+	}
+
+	// Log successful validation if logger exists
+	typedContext.logger?.debug?.('Context validation successful', {
+		baseURL: typedContext.baseURL,
+		storageType: typedContext.storage?.constructor.name,
+		pluginsCount: Array.isArray(typedContext.plugins)
+			? typedContext.plugins.length
+			: 0,
+	});
+
+	return { context: typedContext };
+});

package/src/api/routes/__tests__/consent.test.ts

@@ -0,0 +1,270 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { c15tInstance } from '~/core';
+import { memoryAdapter } from '~/db/adapters/memory-adapter';
+import type { ConsentPolicy } from '~/db/schema';
+import { BASE_ERROR_CODES } from '~/error';
+import type { C15TContext } from '~/types';
+import { setConsent } from '../set-consent';
+
+describe('Consent Endpoints', () => {
+	let context: C15TContext;
+
+	beforeEach(async () => {
+		const instance = await c15tInstance({
+			baseURL: 'http://localhost:3000',
+			database: memoryAdapter({}),
+			trustedOrigins: ['http://localhost:3000'],
+			secret: 'test-secret',
+		});
+
+		const contextResult = await instance.$context;
+		if (!contextResult.isOk()) {
+			throw new Error('Failed to initialize context');
+		}
+		context = contextResult.value;
+	});
+
+	describe('setConsent', () => {
+		// Helper function for common consent data
+		const createConsentData = (
+			type: 'cookie_banner' | 'privacy_policy',
+			overrides = {}
+		) => ({
+			type,
+			domain: 'example.com',
+			preferences: {
+				marketing: true,
+				analytics: true,
+			},
+			...overrides,
+		});
+
+		// Helper function for common response checks
+		const expectValidConsentResponse = (
+			response: {
+				id: string;
+				givenAt: string;
+				subjectId: string;
+				domainId: string;
+				type: string;
+				status: string;
+				domain: string;
+				metadata?: unknown;
+			},
+			type: string,
+			extraChecks = {}
+		) => {
+			// biome-ignore lint/suspicious/noMisplacedAssertion: its okay
+			expect(response).toMatchObject({
+				type,
+				status: 'active',
+				domain: 'example.com',
+				metadata: undefined,
+				...extraChecks,
+			});
+			// biome-ignore lint/suspicious/noMisplacedAssertion: its okay
+			expect(typeof response.id).toBe('string');
+			// biome-ignore lint/suspicious/noMisplacedAssertion: its okay
+			expect(response.givenAt).toBeDefined();
+			// biome-ignore lint/suspicious/noMisplacedAssertion: its okay
+			expect(response.subjectId).toBeDefined();
+			// biome-ignore lint/suspicious/noMisplacedAssertion: its okay
+			expect(response.domainId).toBeDefined();
+		};
+
+		it('should set cookie banner consent successfully', async () => {
+			const response = await setConsent({
+				context,
+				params: undefined,
+				query: undefined,
+				body: createConsentData('cookie_banner'),
+			});
+			expectValidConsentResponse(response, 'cookie_banner');
+		});
+
+		it('should set privacy policy consent successfully with external subject', async () => {
+			await context.registry.createSubject({
+				externalId: 'test-subject',
+				isIdentified: true,
+				identityProvider: 'test',
+			});
+
+			const response = await setConsent({
+				context,
+				params: undefined,
+				query: undefined,
+				body: createConsentData('privacy_policy', {
+					externalSubjectId: 'test-subject',
+				}),
+			});
+
+			expectValidConsentResponse(response, 'privacy_policy', {
+				externalSubjectId: 'test-subject',
+			});
+		});
+
+		describe('Policy ID handling', () => {
+			let policy: ConsentPolicy;
+
+			beforeEach(async () => {
+				policy = await context.registry.createConsentPolicy({
+					name: 'Test Privacy Policy',
+					version: '1.0',
+					content: 'Test content',
+					contentHash: 'test-hash',
+					effectiveDate: new Date(),
+					updatedAt: new Date(),
+					isActive: true,
+				});
+			});
+
+			it('should set consent with explicit policy ID', async () => {
+				const response = await setConsent({
+					context,
+					params: undefined,
+					query: undefined,
+					body: createConsentData('privacy_policy', { policyId: policy.id }),
+				});
+
+				expectValidConsentResponse(response, 'privacy_policy');
+			});
+
+			it('should find latest policy when policy ID is not provided', async () => {
+				const response = await setConsent({
+					context,
+					params: undefined,
+					query: undefined,
+					body: createConsentData('privacy_policy'),
+				});
+
+				expectValidConsentResponse(response, 'privacy_policy');
+			});
+
+			it('should error with invalid policy ID', async () => {
+				await expect(
+					setConsent({
+						context,
+						params: undefined,
+						query: undefined,
+						body: createConsentData('privacy_policy', {
+							policyId: 'invalid-id',
+						}),
+					})
+				).rejects.toMatchObject({
+					name: 'C15TError',
+					code: BASE_ERROR_CODES.NOT_FOUND,
+					status: 404,
+				});
+			});
+		});
+
+		describe('Subject mapping validation', () => {
+			it('should validate that subjectId and externalSubjectId map to the same subject', async () => {
+				// Create a subject with external ID
+				const subject = await context.registry.createSubject({
+					externalId: 'test-subject',
+					isIdentified: true,
+					identityProvider: 'test',
+				});
+
+				if (!subject) {
+					throw new Error('Failed to create test subject');
+				}
+
+				// Test with matching IDs
+				const response = await setConsent({
+					context,
+					params: undefined,
+					query: undefined,
+					body: createConsentData('privacy_policy', {
+						subjectId: subject.id,
+						externalSubjectId: 'test-subject',
+					}),
+				});
+
+				expectValidConsentResponse(response, 'privacy_policy', {
+					subjectId: subject.id,
+					externalSubjectId: 'test-subject',
+				});
+
+				// Create another subject with different external ID
+				const otherSubject = await context.registry.createSubject({
+					externalId: 'other-subject',
+					isIdentified: true,
+					identityProvider: 'test',
+				});
+
+				if (!otherSubject) {
+					throw new Error('Failed to create other test subject');
+				}
+
+				// Test with mismatched IDs
+				await expect(
+					setConsent({
+						context,
+						params: undefined,
+						query: undefined,
+						body: createConsentData('privacy_policy', {
+							subjectId: subject.id,
+							externalSubjectId: 'other-subject',
+						}),
+					})
+				).rejects.toMatchObject({
+					name: 'C15TError',
+					code: BASE_ERROR_CODES.BAD_REQUEST,
+					status: 400,
+				});
+			});
+		});
+
+		describe('Error cases', () => {
+			it('should create anonymous subject when external subject is not found', async () => {
+				const response = await setConsent({
+					context,
+					params: undefined,
+					query: undefined,
+					body: createConsentData('privacy_policy', {
+						externalSubjectId: 'non-existent',
+					}),
+				});
+
+				expectValidConsentResponse(response, 'privacy_policy', {
+					externalSubjectId: 'non-existent',
+				});
+			});
+
+			it('should error if subject ID is not found', async () => {
+				await expect(
+					setConsent({
+						context,
+						params: undefined,
+						query: undefined,
+						body: createConsentData('privacy_policy', {
+							subjectId: 'non-existent',
+						}),
+					})
+				).rejects.toMatchObject({
+					name: 'C15TError',
+					code: BASE_ERROR_CODES.NOT_FOUND,
+					status: 404,
+				});
+			});
+
+			it('should handle invalid consent data', async () => {
+				await expect(
+					setConsent({
+						context,
+						params: undefined,
+						query: undefined,
+						body: createConsentData('cookie_banner', {
+							preferences: {
+								marketing: 'invalid' as unknown as boolean,
+								analytics: 'invalid' as unknown as boolean,
+							},
+						}),
+					})
+				).rejects.toThrow('Invalid body parameters');
+			});
+		});
+	});
+});