@c15t/backend 1.8.0 → 2.0.0-rc.0

package/src/init.ts

@@ -1,314 +1,87 @@
-import { resourceFromAttributes } from '@opentelemetry/resources';
-import { NodeSDK } from '@opentelemetry/sdk-node';
-import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';
-import { defu } from 'defu';
-import type { DatabaseHook } from '~/pkgs/data-model';
-import { getAdapter } from '~/pkgs/db-adapters';
-import type { RegistryContext } from '~/pkgs/types';
-import { getBaseURL } from '~/pkgs/utils';
-import type { C15TContext, C15TOptions, C15TPlugin } from '~/types';
-import { version } from '../package.json';
-import { generateId } from './pkgs/data-model/fields/id-generator';
-import type { EntityName } from './pkgs/data-model/schema/types';
+import type { C15TContext, C15TOptions } from '~/types';
+import { createRegistry } from './db/registry';
+import { DB } from './db/schema';
+import { withTenantScope } from './db/tenant-scope';
 import {
 	createTelemetryOptions,
-	ERROR_CODES,
-	fail,
-	failAsync,
-	ok,
-	promiseToResult,
-	type SDKResult,
-	type TelemetryConfig,
-} from './pkgs/results';
-
-import type { DoubleTieOptions } from './pkgs/types/options';
-import { getLogger, initLogger } from './pkgs/utils/logger';
-import { createRegistry } from './schema/create-registry';
-import { getConsentTables } from './schema/definition';
-
-/**
- * c15t Initialization Module
- *
- * This module handles the initialization of the c15t consent management system.
- * It sets up the consent context, configures storage adapters, initializes plugins,
- * and establishes security settings like secrets and trusted origins.
- *
- * The initialization process includes:
- * - Setting up storage adapters for consent data
- * - Configuring security credentials and trusted origins
- * - Initializing core and custom plugins
- * - Creating the consent context object that serves as the foundation for the system
- *
- * This is an internal module typically not used directly by consumers of the c15t library.
- */
-
-// SDK instance should be at module level for proper lifecycle management
-let telemetrySdk: NodeSDK | undefined;
+	isTelemetryEnabled,
+} from './utils/create-telemetry-options';
+import { initLogger } from './utils/logger';
 
 /**
- * Initializes the c15t consent management system using Result pattern
- *
- * This function creates and configures the consent context based on the provided options.
- * It sets up storage adapters, initializes plugins, configures security settings,
- * and establishes the foundation for the consent management system.
+ * Initializes the c15t backend context.
  *
- * This version uses the neverthrow Result pattern for error handling.
- *
- * @template P - The plugin types used in the configuration
- * @param options - Configuration options for the c15t instance
- * @returns A Promise resolving to a Result containing the initialized consent context
+ * Telemetry (tracing and metrics) is opt-in and disabled by default.
+ * Users must:
+ * 1. Set up their own OpenTelemetry SDK (Node.js, Bun, edge runtime, etc.)
+ * 2. Pass enabled: true and optionally a tracer/meter to the telemetry config
  *
  * @example
  * ```typescript
- * const contextResult = await init({
- *   storage: memoryAdapter(),
- *   plugins: [geoPlugin()]
- * });
+ * // User sets up their own SDK before calling init
+ * import { NodeSDK } from '@opentelemetry/sdk-node';
+ * const sdk = new NodeSDK({ ... });
+ * sdk.start();
  *
- * // Handle success and error cases explicitly
- * contextResult.match(
- *   (context) => {
- *     // Use the successfully initialized context
+ * // Then pass telemetry config
+ * const instance = c15tInstance({
+ *   advanced: {
+ *     telemetry: {
+ *       enabled: true,
+ *       tracer: trace.getTracer('my-app'),
+ *       meter: metrics.getMeter('my-app'),
+ *     },
  *   },
- *   (error) => {
- *     // Handle the initialization error
- *     console.error('Failed to initialize:', error.message);
- *   }
- * );
+ * });
  * ```
  */
-export const init = async <P extends C15TPlugin[]>(
-	options: C15TOptions<P>
-): Promise<SDKResult<C15TContext>> => {
-	try {
-		// Type-safe handling of options with explicit type assertions
-		const loggerOptions = options.logger;
-		const baseUrlStr = options.baseURL;
-		const basePathStr = options.basePath as string | undefined;
-		const databaseHooks = (options.databaseHooks || []) as DatabaseHook[];
-		const appName = options.appName || 'c15t';
-
-		// Create a single logger instance early in the initialization process
-		// Initialize the global logger for use throughout the application
-		const logger = initLogger({
-			...loggerOptions,
-			appName: String(appName),
-		});
-
-		// Create telemetry options
-		const telemetryOptions = createTelemetryOptions(
-			String(appName),
-			options.telemetry as TelemetryConfig
-		);
-
-		// Initialize telemetry directly here instead of using a separate function
-		let telemetryInitialized = false;
-		try {
-			// Skip if SDK already initialized or telemetry is disabled
-			if (telemetrySdk) {
-				logger.debug('Telemetry SDK already initialized, skipping');
-				telemetryInitialized = true;
-			} else if (telemetryOptions?.disabled) {
-				logger.info('Telemetry is disabled by configuration');
-				telemetryInitialized = false;
-			} else {
-				// Create a telemetry resource with provided values or safe defaults
-				const resource = resourceFromAttributes({
-					'service.name': String(appName),
-					'service.version': String(version || '1.0.0'),
-					...(telemetryOptions?.defaultAttributes || {}),
-				});
-				logger.debug('Initializing telemetry with resource attributes', {
-					attributes: resource.attributes,
-				});
-
-				// Use provided tracer or fallback to console exporter
-				const traceExporter = telemetryOptions?.tracer
-					? undefined // SDK will use the provided tracer
-					: new ConsoleSpanExporter();
-
-				// Create and start the SDK
-				telemetrySdk = new NodeSDK({
-					resource,
-					traceExporter,
-				});
-
-				telemetrySdk.start();
-				logger.info('Telemetry successfully initialized');
-				telemetryInitialized = true;
-			}
-		} catch (error) {
-			// Log the error but don't crash the application
-			logger.error('Telemetry initialization failed', {
-				error: error instanceof Error ? error.message : String(error),
-				stack: error instanceof Error ? error.stack : undefined,
-			});
-			logger.warn('Continuing without telemetry');
-			telemetryInitialized = false;
-		}
-
-		// Log telemetry initialization status
-		if (telemetryOptions?.disabled) {
-			logger.info('Telemetry is disabled by configuration');
-		} else if (telemetryInitialized) {
-			logger.info('Telemetry initialized successfully');
-		} else {
-			logger.warn(
-				'Telemetry initialization failed, continuing without telemetry'
-			);
-		}
-
-		// Initialize core components
-		logger.info('Initializing adapter', {
-			storage:
-				options.storage && typeof options.storage === 'object'
-					? ((options.storage as Record<string, unknown>).type as string) ||
-						'unknown'
-					: 'unknown',
-			clientVersion: options.clientVersion || 'not provided',
-			appName,
-			baseURL: baseUrlStr,
-		});
-
-		const adapterResult = await promiseToResult(
-			getAdapter(options),
-			ERROR_CODES.INITIALIZATION_FAILED
-		);
-
-		// After getting adapter
-		logger.debug('Adapter initialization result', {
-			success: adapterResult.isOk(),
+export const init = (options: C15TOptions): C15TContext => {
+	const appName = options.appName || 'c15t';
+
+	const logger = initLogger({
+		...options.logger,
+		appName: String(appName),
+	});
+
+	// Create telemetry options (validates and merges with defaults)
+	const telemetryOptions = createTelemetryOptions(
+		String(appName),
+		options.advanced?.telemetry,
+		options.tenantId
+	);
+
+	// Log telemetry status
+	if (isTelemetryEnabled(options)) {
+		logger.debug('Telemetry is enabled', {
+			hasTracer: !!telemetryOptions?.tracer,
+			hasMeter: !!telemetryOptions?.meter,
+			attributes: telemetryOptions?.defaultAttributes,
 		});
+	} else {
+		logger.debug('Telemetry is disabled (opt-in required)');
+	}
 
-		return adapterResult.andThen((adapter) => {
-			const resolvedBaseURL = getBaseURL(baseUrlStr, basePathStr);
-
-			// Create normalized options directly with h3 patterns but no version field
-			const finalOptions: DoubleTieOptions = {
-				...options,
-				baseURL: resolvedBaseURL ? new URL(resolvedBaseURL).origin : '',
-				basePath: basePathStr || '/api/c15t',
-				plugins: [...(options.plugins || []), ...getInternalPlugins(options)],
-				telemetry: telemetryOptions,
-			};
-
-			// Create ID generator
-			const generateIdFunc = ({
-				model,
-				size = 16,
-			}: {
-				model: EntityName;
-				size?: number;
-			}) => {
-				return (
-					finalOptions?.advanced?.generateId?.({ model, size }) ||
-					generateId(getConsentTables(finalOptions)[model].entityPrefix)
-				);
-			};
-
-			// Create registry context
-			const registryContext: RegistryContext = {
-				adapter,
-				options: finalOptions,
-				logger,
-				hooks: databaseHooks,
-				generateId: generateIdFunc,
-			};
-
-			// Create full application context
-			const ctx: C15TContext = {
-				appName: String(appName),
-				options: finalOptions,
-				trustedOrigins: options.trustedOrigins || [],
-				baseURL: resolvedBaseURL || '',
+	// Initialize core components
+	const db = options.tablePrefix ? DB.names.prefix(options.tablePrefix) : DB;
+	const client = db.client(options.adapter);
+
+	const rawOrm = client.orm('2.0.0');
+	const orm = options.tenantId
+		? withTenantScope(rawOrm, options.tenantId)
+		: rawOrm;
+
+	const context: C15TContext = {
+		...options,
+		appName,
+		logger,
+		db: orm,
+		registry: createRegistry({
+			db: orm,
+			ctx: {
 				logger,
-				generateId: generateIdFunc,
-				adapter,
-				registry: createRegistry(registryContext),
-				tables: getConsentTables(options),
-			};
+			},
+		}),
+	};
 
-			// Initialize plugins and return
-			return runPluginInit(ctx);
-		});
-	} catch (error) {
-		// Use getLogger here since we might be in an error case before logger initialization
-		const errorLogger = getLogger(options.logger);
-		errorLogger.error('Initialization failed', {
-			error: error instanceof Error ? error.message : String(error),
-			stack: error instanceof Error ? error.stack : undefined,
-		});
-
-		return failAsync(
-			`Failed to initialize consent system: ${error instanceof Error ? error.message : String(error)}`,
-			{
-				code: ERROR_CODES.INITIALIZATION_FAILED,
-				meta: { error },
-			}
-		);
-	}
+	return context;
 };
-
-/**
- * Initializes all registered plugins using the Result pattern
- *
- * This function runs the init method of each plugin in sequence,
- * collecting any context or options modifications they provide.
- *
- * @param ctx - The current consent context
- * @returns A Result with the updated context after plugin initialization
- */
-function runPluginInit(ctx: C15TContext): SDKResult<C15TContext> {
-	try {
-		let options = ctx.options as unknown as C15TOptions<C15TPlugin[]>;
-		const plugins = options.plugins || [];
-		let context: C15TContext = ctx;
-
-		for (const plugin of plugins) {
-			// Type assertion for plugin to C15TPlugin
-			const typedPlugin = plugin as C15TPlugin;
-			if (typedPlugin.init) {
-				const result = typedPlugin.init(ctx);
-				if (typeof result === 'object') {
-					if (result.options) {
-						options = defu(result.options, options) as C15TOptions<
-							C15TPlugin[]
-						>;
-					}
-					if (result.context) {
-						context = {
-							...context,
-							...(result.context as Partial<C15TContext>),
-						};
-					}
-				}
-			}
-		}
-
-		context.options = options as unknown as DoubleTieOptions;
-		return ok(context);
-	} catch (error) {
-		return fail(
-			`Plugin initialization failed: ${error instanceof Error ? error.message : String(error)}`,
-			{
-				code: ERROR_CODES.PLUGIN_INITIALIZATION_FAILED,
-				meta: { error },
-			}
-		);
-	}
-}
-
-/**
- * Retrieves internal plugins based on configuration options
- *
- * This function determines which internal plugins should be automatically
- * included based on the provided options.
- *
- * @param options - The c15t configuration options
- * @returns An array of internal plugins to include
- */
-function getInternalPlugins(_options: C15TOptions): C15TPlugin[] {
-	const plugins: C15TPlugin[] = [];
-
-	return plugins;
-}

package/src/middleware/auth/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Authentication middleware exports.
+ *
+ * @packageDocumentation
+ */
+
+export {
+	extractBearerToken,
+	validateApiKey,
+	validateRequestAuth,
+} from './validate-api-key';

package/src/middleware/auth/validate-api-key.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import {
+	extractBearerToken,
+	validateApiKey,
+	validateRequestAuth,
+} from './validate-api-key';
+
+describe('extractBearerToken', () => {
+	it('should extract token from valid Bearer header', () => {
+		expect(extractBearerToken('Bearer sk_live_abc123')).toBe('sk_live_abc123');
+	});
+
+	it('should return null for non-Bearer auth', () => {
+		expect(extractBearerToken('Basic abc123')).toBeNull();
+	});
+
+	it('should return null for missing Bearer prefix', () => {
+		expect(extractBearerToken('sk_live_abc123')).toBeNull();
+	});
+
+	it('should return null for null header', () => {
+		expect(extractBearerToken(null)).toBeNull();
+	});
+
+	it('should return null for empty header', () => {
+		expect(extractBearerToken('')).toBeNull();
+	});
+
+	it('should handle extra spaces', () => {
+		expect(extractBearerToken('Bearer  abc123')).toBeNull(); // Two spaces
+	});
+});
+
+describe('validateApiKey', () => {
+	const validKeys = ['sk_live_abc123', 'sk_live_def456'];
+
+	it('should return true for valid key', () => {
+		expect(validateApiKey('sk_live_abc123', validKeys)).toBe(true);
+		expect(validateApiKey('sk_live_def456', validKeys)).toBe(true);
+	});
+
+	it('should return false for invalid key', () => {
+		expect(validateApiKey('sk_live_invalid', validKeys)).toBe(false);
+	});
+
+	it('should return false for null token', () => {
+		expect(validateApiKey(null, validKeys)).toBe(false);
+	});
+
+	it('should return false for undefined keys', () => {
+		expect(validateApiKey('sk_live_abc123', undefined)).toBe(false);
+	});
+
+	it('should return false for empty keys array', () => {
+		expect(validateApiKey('sk_live_abc123', [])).toBe(false);
+	});
+
+	it('should be case-sensitive', () => {
+		expect(validateApiKey('SK_LIVE_ABC123', validKeys)).toBe(false);
+	});
+});
+
+describe('validateRequestAuth', () => {
+	const validKeys = ['sk_live_abc123'];
+
+	it('should return true for valid Authorization header', () => {
+		const headers = new Headers();
+		headers.set('Authorization', 'Bearer sk_live_abc123');
+		expect(validateRequestAuth(headers, validKeys)).toBe(true);
+	});
+
+	it('should return false for invalid token', () => {
+		const headers = new Headers();
+		headers.set('Authorization', 'Bearer sk_live_invalid');
+		expect(validateRequestAuth(headers, validKeys)).toBe(false);
+	});
+
+	it('should return false for missing Authorization header', () => {
+		const headers = new Headers();
+		expect(validateRequestAuth(headers, validKeys)).toBe(false);
+	});
+
+	it('should return false for undefined headers', () => {
+		expect(validateRequestAuth(undefined, validKeys)).toBe(false);
+	});
+});

package/src/middleware/auth/validate-api-key.ts

@@ -0,0 +1,107 @@
+/**
+ * API key validation utilities.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extracts the Bearer token from an Authorization header.
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The token if valid Bearer format, null otherwise
+ *
+ * @example
+ * ```typescript
+ * extractBearerToken('Bearer sk_live_abc123'); // 'sk_live_abc123'
+ * extractBearerToken('Basic abc123'); // null
+ * extractBearerToken('sk_live_abc123'); // null
+ * ```
+ */
+export function extractBearerToken(authHeader: string | null): string | null {
+	if (!authHeader) {
+		return null;
+	}
+
+	const parts = authHeader.split(' ');
+	if (parts.length !== 2 || parts[0] !== 'Bearer') {
+		return null;
+	}
+
+	return parts[1] || null;
+}
+
+/**
+ * Validates an API key against the configured keys.
+ *
+ * @param token - The token to validate
+ * @param validKeys - Array of valid API keys
+ * @returns True if the token is valid
+ *
+ * @remarks
+ * Uses timing-safe comparison to prevent timing attacks.
+ * If no keys are configured, returns false.
+ */
+export function validateApiKey(
+	token: string | null,
+	validKeys: string[] | undefined
+): boolean {
+	if (!token || !validKeys || validKeys.length === 0) {
+		return false;
+	}
+
+	// Use timing-safe comparison to prevent timing attacks
+	return validKeys.some((key) => timingSafeEqual(token, key));
+}
+
+/**
+ * Timing-safe string comparison to prevent timing attacks.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns True if strings are equal
+ */
+function timingSafeEqual(a: string, b: string): boolean {
+	if (a.length !== b.length) {
+		// Still do comparison to maintain constant time
+		let result = 0;
+		for (let i = 0; i < a.length; i++) {
+			result |= a.charCodeAt(i) ^ (b.charCodeAt(i % b.length) || 0);
+		}
+		return false;
+	}
+
+	let result = 0;
+	for (let i = 0; i < a.length; i++) {
+		result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	}
+	return result === 0;
+}
+
+/**
+ * Validates authentication from request headers.
+ *
+ * @param headers - Request headers
+ * @param validKeys - Array of valid API keys
+ * @returns True if the request has a valid API key
+ *
+ * @example
+ * ```typescript
+ * const headers = new Headers();
+ * headers.set('Authorization', 'Bearer sk_live_abc123');
+ *
+ * validateRequestAuth(headers, ['sk_live_abc123']); // true
+ * validateRequestAuth(headers, ['sk_live_other']); // false
+ * ```
+ */
+export function validateRequestAuth(
+	headers: Headers | undefined,
+	validKeys: string[] | undefined
+): boolean {
+	if (!headers) {
+		return false;
+	}
+
+	const authHeader = headers.get('Authorization');
+	const token = extractBearerToken(authHeader);
+	return validateApiKey(token, validKeys);
+}