@c15t/backend 0.0.1-rc.10

package/src/api/call.ts

@@ -0,0 +1,177 @@
+import { createEndpoint, createMiddleware } from 'better-call';
+import type { C15TContext } from '~/types';
+
+/**
+ * Middleware that provides access to the C15T context
+ *
+ * This middleware is used as a base for all endpoint handlers to provide
+ * access to the C15T context.
+ *
+ * @returns A Promise resolving to the C15T context
+ * @internal This is primarily meant for internal use by the C15T system
+ *
+ * @remarks
+ * This middleware serves as the foundation for context propagation throughout
+ * the consent management system. It's typically not used directly but is
+ * composed within other middleware and endpoint factories.
+ *
+ * @example
+ * ```typescript
+ * // This middleware is typically used internally by createAuthMiddleware and createAuthEndpoint
+ * const myMiddleware = createMiddleware.create({
+ *   use: [optionsMiddleware]
+ * });
+ * ```
+ */
+export const optionsMiddleware = createMiddleware(async () => {
+	/**
+	 * This will be passed on the instance of
+	 * the context. Used to infer the type
+	 * here.
+	 * @internal
+	 */
+	return {} as C15TContext;
+});
+
+/**
+ * Creates an authentication middleware with pre-configured context access
+ *
+ * This factory combines the options middleware with post-hook functionality,
+ * allowing handlers to modify responses by setting headers.
+ *
+ * @returns A configured middleware for authentication endpoints
+ * @throws May propagate errors from underlying middleware implementations
+ * @throws Errors from your middleware handler will be propagated unless explicitly caught
+ *
+ * @remarks
+ * The middleware created by this factory automatically receives the C15T context
+ * and manages response header manipulation. It's particularly useful for
+ * authentication, authorization, and other cross-cutting concerns.
+ *
+ * @example
+ * ```typescript
+ * // Create a custom authentication middleware
+ * const verifySubjectMiddleware = createAuthMiddleware(async (context) => {
+ *   const { subjectId } = context.params;
+ *
+ *   // Verify the subject exists
+ *   const subject = await getSubjectById(subjectId);
+ *   if (!subject) {
+ *     throw new APIError({
+ *       message: 'Subject not found',
+ *       status: 'NOT_FOUND'
+ *     });
+ *   }
+ *
+ *   // Add subject to context
+ *   return {
+ *     context: {
+ *       subject
+ *     }
+ *   };
+ * });
+ *
+ * // Apply the middleware to specific routes in router configuration
+ * router.use('/subjects/**', verifySubjectMiddleware);
+ * ```
+ */
+export const createAuthMiddleware = createMiddleware.create({
+	use: [
+		optionsMiddleware,
+		/**
+		 * Only use for post hooks
+		 * @internal
+		 */
+		createMiddleware(async () => {
+			return {} as {
+				returned?: unknown;
+				responseHeaders?: Headers;
+			};
+		}),
+	],
+});
+
+/**
+ * Creates an authentication endpoint with pre-configured context access
+ *
+ * This factory provides a standardized way to create endpoints with access
+ * to the C15T context.
+ *
+ * @returns A configured endpoint creator for authentication endpoints
+ * @throws May propagate errors from endpoint handler implementations
+ * @throws Any uncaught errors in the endpoint handler will be propagated through the system
+ *
+ * @remarks
+ * Endpoints created with this factory are automatically configured with
+ * the C15T context, making them ideal for building consent management APIs.
+ * These endpoints can be used in route configurations or with the toEndpoints
+ * function for automatic API generation.
+ *
+ * @example
+ * ```typescript
+ * // Create a consent status endpoint
+ * export const getConsentStatus = createAuthEndpoint(async (context) => {
+ *   const { subjectId, domain } = context.params;
+ *
+ *   // Get consent status from storage
+ *   const status = await context.context.storage.getConsentStatus(subjectId, domain);
+ *
+ *   return {
+ *     subjectId,
+ *     domain,
+ *     hasConsented: status.consented,
+ *     purposes: status.purposes,
+ *     updatedAt: status.timestamp
+ *   };
+ * });
+ *
+ * // Create a consent update endpoint with error handling
+ * export const updateConsent = createAuthEndpoint(async (context) => {
+ *   const { subjectId, domain, purposes } = context.params;
+ *
+ *   try {
+ *     // Update consent status in storage
+ *     await context.context.storage.updateConsentStatus(subjectId, domain, {
+ *       consented: true,
+ *       purposes,
+ *       timestamp: new Date().toISOString()
+ *     });
+ *
+ *     return { success: true, subjectId, domain };
+ *   } catch (error) {
+ *     throw new APIError({
+ *       message: 'Failed to update consent status',
+ *       status: 'INTERNAL_SERVER_ERROR',
+ *       cause: error
+ *     });
+ *   }
+ * });
+ * ```
+ */
+export const createAuthEndpoint = createEndpoint.create({
+	use: [optionsMiddleware],
+});
+
+/**
+ * Type definition for a C15T endpoint handler
+ *
+ * Represents the function signature returned by createAuthEndpoint.
+ * Used for type checking when building API endpoints.
+ *
+ * @remarks
+ * This type is used extensively in the toEndpoints function and
+ * when defining route handlers for the consent management system.
+ */
+export type C15TEndpoint = ReturnType<typeof createAuthEndpoint>;
+
+/**
+ * Type definition for a C15T middleware handler
+ *
+ * Represents the function signature returned by createAuthMiddleware.
+ * Used for type checking when building middleware chains.
+ *
+ * @remarks
+ * This type is used when defining hooks and custom middleware
+ * for the consent management system pipeline.
+ */
+export type C15TMiddleware = ReturnType<typeof createAuthMiddleware>;

package/src/api/index.ts

@@ -0,0 +1,303 @@
+import {
+	APIError,
+	type Endpoint,
+	type Middleware,
+	type UnionToIntersection,
+	createRouter,
+} from 'better-call';
+import type { C15TContext, C15TOptions, C15TPlugin } from '~/types';
+import { getIp } from '~/utils/ip';
+
+import { logger } from '~/utils/logger';
+import { originCheckMiddleware } from './middlewares/origin-check';
+import { validateContextMiddleware } from './middlewares/validate-context';
+import { baseEndpoints } from './routes';
+import { ok } from './routes/ok';
+import { toEndpoints } from './to-endpoints';
+
+/**
+ * Retrieves and configures endpoints from plugins and core functionality
+ *
+ * This function collects endpoints from plugins, combines them with
+ * base endpoints, and builds an API object with properly configured
+ * handlers.
+ *
+ * @remarks
+ * Plugin endpoints are merged with core endpoints, with core endpoints
+ * taking precedence in case of naming conflicts.
+ *
+ * @typeParam ContextType - The specific context type extending C15TContext
+ * @typeParam OptionsType - Configuration options type extending C15TOptions
+ * @param ctx - The consent management context (or promise resolving to it)
+ * @param options - Configuration options for the consent system
+ * @returns Object containing API handlers and middleware configurations
+ *
+ * @example
+ * ```typescript
+ * const { api, middlewares } = getEndpoints(contextInstance, {
+ *   plugins: [analyticsPlugin(), geoPlugin()]
+ * });
+ *
+ * // Use the configured API
+ * const response = await api.getConsentStatus({
+ *   params: { subjectId: "sub_x1pftyoufsm7xgo1kv" }
+ * });
+ * ```
+ */
+export function getEndpoints<
+	ContextType extends C15TContext,
+	OptionsType extends C15TOptions,
+>(ctx: Promise<ContextType> | ContextType, options: OptionsType) {
+	const pluginEndpoints = options.plugins?.reduce<Record<string, Endpoint>>(
+		(acc, plugin) => {
+			if (plugin.endpoints) {
+				Object.assign(acc, plugin.endpoints);
+			}
+			return acc;
+		},
+		{}
+	);
+
+	/**
+	 * Type representing the intersection of all plugin endpoint types
+	 *
+	 * @internal
+	 */
+	type PluginEndpoint = UnionToIntersection<
+		OptionsType['plugins'] extends Array<infer PluginType>
+			? PluginType extends C15TPlugin
+				? PluginType extends {
+						endpoints: infer EndpointType;
+					}
+					? EndpointType
+					: Record<string, never>
+				: Record<string, never>
+			: Record<string, never>
+	>;
+
+	const middlewares =
+		options.plugins
+			?.map((plugin) =>
+				plugin.middlewares?.map((m) => {
+					const middleware = (async (context: { context: ContextType }) => {
+						return m.middleware({
+							...context,
+							context: {
+								...ctx,
+								...context.context,
+							},
+						});
+					}) as Middleware;
+					middleware.options = m.middleware.options;
+					return {
+						path: m.path,
+						middleware,
+					};
+				})
+			)
+			.filter(
+				(plugin): plugin is NonNullable<typeof plugin> => plugin !== undefined
+			)
+			.flat() || [];
+
+	const endpoints = {
+		...baseEndpoints,
+		...pluginEndpoints,
+		ok,
+		// error,
+	};
+	const api = toEndpoints(endpoints, ctx);
+	return {
+		api: api as typeof endpoints & PluginEndpoint,
+		middlewares,
+	};
+}
+
+/**
+ * Creates a router for handling API requests
+ *
+ * Sets up routing with proper error handling, CORS, and response processing.
+ * Integrates plugin-provided middlewares and response handlers.
+ *
+ * @remarks
+ * This router automatically applies the origin check middleware to all routes
+ * and handles error conditions appropriately based on configuration.
+ *
+ * @typeParam ContextType - The specific context type extending C15TContext
+ * @typeParam OptionsType - Configuration options type extending C15TOptions
+ * @param ctx - The initialized consent management context
+ * @param options - Configuration options for the consent system
+ * @returns A configured router with handler and endpoint functions
+ * @throws May throw errors in the onError handler if options.onAPIError.throw is true
+ *
+ * @example
+ * ```typescript
+ * const consentRouter = router(contextInstance, {
+ *   logger: { level: 'error' },
+ *   plugins: [analyticsPlugin()]
+ * });
+ *
+ * // Use the router to handle incoming requests
+ * app.use('/api/consent', async (req, res) => {
+ *   const response = await consentRouter.handler(
+ *     new Request(`https://example.com${req.url}`, {
+ *       method: req.method,
+ *       headers: req.headers,
+ *       body: req.body ? JSON.stringify(req.body) : undefined
+ *     })
+ *   );
+ *
+ *   // Send the response back
+ *   res.status(response.status);
+ *   response.headers.forEach((value, key) => {
+ *     res.setHeader(key, value);
+ *   });
+ *   const body = await response.text();
+ *   res.send(body);
+ * });
+ * ```
+ */
+export const router = <
+	ContextType extends C15TContext,
+	OptionsType extends C15TOptions,
+>(
+	ctx: ContextType,
+	options: OptionsType
+) => {
+	const { api, middlewares } = getEndpoints(ctx, options);
+
+	// Check for baseURL and properly handle it
+	let basePath = '';
+	try {
+		if (ctx.baseURL) {
+			const url = new URL(ctx.baseURL);
+			basePath = url.pathname;
+		}
+	} catch {
+		basePath = '/api/c15t';
+	}
+	// Ensure we have a valid basePath
+	if (!basePath || basePath === '/') {
+		basePath = '/api/c15t';
+	}
+
+	/**
+	 * Configure and create the router instance
+	 *
+	 * @internal
+	 */
+	const routerInstance = createRouter(api, {
+		routerContext: ctx,
+		openapi: {
+			disabled: false,
+		},
+		basePath,
+		routerMiddleware: [
+			{
+				path: '/**',
+				middleware: validateContextMiddleware,
+			},
+			{
+				path: '/**',
+				middleware: originCheckMiddleware,
+			},
+			...middlewares,
+		],
+		async onRequest(req) {
+			// Add IP address to context
+			(ctx as C15TContext).ipAddress = getIp(req, options);
+			(ctx as C15TContext).userAgent = req.headers.get('user-agent');
+
+			for (const plugin of ctx.options.plugins || []) {
+				if (plugin.onRequest) {
+					const response = await plugin.onRequest(req, ctx);
+					if (response && 'response' in response) {
+						return response.response;
+					}
+				}
+			}
+			return req;
+		},
+
+		/**
+		 * Handle response processing through plugins
+		 *
+		 * @internal
+		 * @param res - The response to process
+		 * @returns The processed response
+		 */
+		async onResponse(res) {
+			for (const plugin of ctx.options.plugins || []) {
+				if (plugin.onResponse) {
+					const response = await plugin.onResponse(res, ctx);
+					if (response) {
+						return response.response;
+					}
+				}
+			}
+			return res;
+		},
+
+		/**
+		 * Handle errors that occur during request processing
+		 *
+		 * @internal
+		 * @param e - The error that occurred
+		 */
+		onError(e) {
+			if (e instanceof APIError && e.status === 'FOUND') {
+				return;
+			}
+			if (options.onAPIError?.throw) {
+				throw e;
+			}
+			if (options.onAPIError?.onError) {
+				options.onAPIError.onError(e, ctx);
+				return;
+			}
+
+			const optLogLevel = options.logger?.level;
+			const log =
+				optLogLevel === 'error' ||
+				optLogLevel === 'warn' ||
+				optLogLevel === 'debug'
+					? logger
+					: undefined;
+			if (options.logger?.disabled !== true) {
+				if (
+					e &&
+					typeof e === 'object' &&
+					'message' in e &&
+					typeof e.message === 'string' &&
+					(e.message.includes('no column') ||
+						e.message.includes('column') ||
+						e.message.includes('relation') ||
+						e.message.includes('table') ||
+						e.message.includes('does not exist'))
+				) {
+					ctx.logger?.error(e.message);
+					return;
+				}
+
+				if (e instanceof APIError) {
+					if (e.status === 'INTERNAL_SERVER_ERROR') {
+						ctx.logger.error(e.status, e);
+					}
+					log?.error(e.message);
+				} else {
+					ctx.logger?.error(
+						e && typeof e === 'object' && 'name' in e ? (e.name as string) : '',
+						e
+					);
+				}
+			}
+		},
+	});
+
+	return routerInstance;
+};
+
+// export * from './routes';
+// export * from './middlewares';
+export * from './call';
+export { APIError } from 'better-call';

package/src/api/middlewares/index.ts

@@ -0,0 +1,38 @@
+/**
+ * C15T Middleware Exports
+ *
+ * This barrel file exports all middlewares used by the C15T consent management system.
+ * Middlewares handle cross-cutting concerns like security, validation, and context
+ * enrichment for API endpoints.
+ *
+ * @module middlewares
+ *
+ * @remarks
+ * The middlewares in this directory implement various security and validation
+ * requirements for the consent management API. They can be applied globally to
+ * all routes or selectively to specific endpoint groups.
+ *
+ * Currently included middlewares:
+ * - Origin check middleware: Validates URLs against trusted origins to prevent CSRF
+ *   and open redirect vulnerabilities
+ *
+ * @example
+ * ```typescript
+ * // Import all middlewares
+ * import { originCheckMiddleware, originCheck } from '~/api/middlewares';
+ *
+ * // Apply middleware to a router
+ * const router = createRouter(endpoints, {
+ *   routerMiddleware: [
+ *     {
+ *       path: '/**',
+ *       middleware: originCheckMiddleware
+ *     }
+ *   ]
+ * });
+ *
+ * // Create a targeted middleware for a specific field
+ * const validateReturnUrl = originCheck(ctx => ctx.body?.returnUrl);
+ * ```
+ */
+export * from './origin-check';