@c15t/backend 2.0.0-rc.0 → 2.0.0-rc.10

package/src/middleware/process-ip/index.ts

@@ -1,199 +0,0 @@
-import type { C15TOptions } from '~/types';
-
-const DEFAULT_IP_HEADERS = [
-	'x-client-ip',
-	'x-forwarded-for',
-	'cf-connecting-ip',
-	'fastly-client-ip',
-	'x-real-ip',
-	'x-cluster-client-ip',
-	'x-forwarded',
-	'forwarded-for',
-	'forwarded',
-];
-
-/**
- * Expands a compressed IPv6 address to its full form.
- * For example: "2001:db8::1" -> "2001:0db8:0000:0000:0000:0000:0000:0001"
- */
-function expandIPv6(ip: string): string {
-	// Handle IPv4-mapped IPv6 addresses (e.g., ::ffff:192.168.1.1)
-	if (ip.includes('.')) {
-		return ip;
-	}
-
-	const parts = ip.split(':');
-	const emptyIndex = parts.indexOf('');
-
-	if (emptyIndex !== -1) {
-		// Count how many groups we need to insert
-		const nonEmptyParts = parts.filter((p) => p !== '');
-		const missingGroups = 8 - nonEmptyParts.length;
-		const zeros = Array(missingGroups).fill('0000');
-
-		// Handle leading ::
-		if (emptyIndex === 0) {
-			parts.shift();
-			if (parts[0] === '') {
-				parts.shift();
-			}
-			parts.unshift(...zeros);
-		}
-		// Handle trailing ::
-		else if (emptyIndex === parts.length - 1) {
-			parts.pop();
-			if (parts[parts.length - 1] === '') {
-				parts.pop();
-			}
-			parts.push(...zeros);
-		}
-		// Handle middle ::
-		else {
-			parts.splice(emptyIndex, 1, ...zeros);
-		}
-	}
-
-	// Pad each group to 4 characters
-	return parts.map((p) => p.padStart(4, '0')).join(':');
-}
-
-/**
- * Compresses an IPv6 address by removing leading zeros and using :: for consecutive zero groups.
- */
-function compressIPv6(ip: string): string {
-	// Remove leading zeros from each group
-	const groups = ip.split(':').map((g) => g.replace(/^0+/, '') || '0');
-
-	// Find the longest run of consecutive zeros
-	let longestStart = -1;
-	let longestLength = 0;
-	let currentStart = -1;
-	let currentLength = 0;
-
-	for (let i = 0; i < groups.length; i++) {
-		if (groups[i] === '0') {
-			if (currentStart === -1) {
-				currentStart = i;
-				currentLength = 1;
-			} else {
-				currentLength++;
-			}
-		} else {
-			if (currentLength > longestLength) {
-				longestStart = currentStart;
-				longestLength = currentLength;
-			}
-			currentStart = -1;
-			currentLength = 0;
-		}
-	}
-
-	// Check final run
-	if (currentLength > longestLength) {
-		longestStart = currentStart;
-		longestLength = currentLength;
-	}
-
-	// Replace longest run with ::
-	if (longestLength > 1) {
-		const before = groups.slice(0, longestStart);
-		const after = groups.slice(longestStart + longestLength);
-
-		if (before.length === 0 && after.length === 0) {
-			return '::';
-		}
-		if (before.length === 0) {
-			return `::${after.join(':')}`;
-		}
-		if (after.length === 0) {
-			return `${before.join(':')}::`;
-		}
-		return `${before.join(':')}::${after.join(':')}`;
-	}
-
-	return groups.join(':');
-}
-
-/**
- * Masks an IP address to reduce PII.
- * - IPv4: Replaces last octet with 0 (e.g., 192.168.1.100 -> 192.168.1.0)
- * - IPv6: Masks last 80 bits (e.g., 2001:db8:85a3::1 -> 2001:db8:85a3::)
- *
- * @param ip - The IP address to mask
- * @returns The masked IP address
- */
-export function maskIpAddress(ip: string | null): string | null {
-	if (!ip) {
-		return null;
-	}
-
-	// IPv4 detection (no colons, has dots)
-	if (ip.includes('.') && !ip.includes(':')) {
-		const parts = ip.split('.');
-		if (parts.length === 4) {
-			parts[3] = '0';
-			return parts.join('.');
-		}
-		return ip;
-	}
-
-	// IPv6 detection
-	if (ip.includes(':')) {
-		// Handle IPv4-mapped IPv6 (::ffff:192.168.1.100)
-		if (ip.includes('.')) {
-			const lastColon = ip.lastIndexOf(':');
-			const ipv4Part = ip.substring(lastColon + 1);
-			const ipv6Prefix = ip.substring(0, lastColon + 1);
-
-			const ipv4Parts = ipv4Part.split('.');
-			if (ipv4Parts.length === 4) {
-				ipv4Parts[3] = '0';
-				return ipv6Prefix + ipv4Parts.join('.');
-			}
-			return ip;
-		}
-
-		// Pure IPv6 - mask last 80 bits (keep first 48 bits / 3 groups)
-		const expanded = expandIPv6(ip);
-		const groups = expanded.split(':');
-
-		// Zero out groups 4-8 (indices 3-7)
-		for (let i = 3; i < 8; i++) {
-			groups[i] = '0000';
-		}
-
-		return compressIPv6(groups.join(':'));
-	}
-
-	return ip;
-}
-
-export function getIpAddress(
-	req: Request | Headers,
-	options: C15TOptions
-): string | null {
-	const ipAddressConfig = options.advanced?.ipAddress;
-
-	if (ipAddressConfig?.tracking === false) {
-		return null;
-	}
-
-	const ipHeaders = ipAddressConfig?.ipAddressHeaders || DEFAULT_IP_HEADERS;
-
-	const headers = req instanceof Request ? req.headers : req;
-
-	for (const key of ipHeaders) {
-		const value = headers.get(key);
-		if (value) {
-			const ip = value.split(',')[0]?.trim();
-			if (ip) {
-				if (ipAddressConfig?.masking !== false) {
-					return maskIpAddress(ip);
-				}
-				return ip;
-			}
-		}
-	}
-
-	return null;
-}

package/src/router.ts

@@ -1,15 +0,0 @@
-/**
- * Router exports
- *
- * Note: The router is now integrated into the Hono app in core.ts.
- * This file exports the route creators for direct usage.
- *
- * @packageDocumentation
- */
-
-export {
-	createConsentRoutes,
-	createInitRoute,
-	createStatusRoute,
-	createSubjectRoutes,
-} from './routes';

package/src/routes/consent.ts

@@ -1,52 +0,0 @@
-/**
- * Consent routes - Check consent status.
- *
- * @packageDocumentation
- */
-
-import {
-	checkConsentOutputSchema,
-	checkConsentQuerySchema,
-} from '@c15t/schema';
-import { Hono } from 'hono';
-import { describeRoute, resolver, validator as vValidator } from 'hono-openapi';
-import { checkConsentHandler } from '~/handlers/consent/check.handler';
-import type { C15TContext } from '~/types';
-
-/**
- * Creates the consent routes
- */
-export const createConsentRoutes = () => {
-	const app = new Hono<{ Variables: { c15tContext: C15TContext } }>();
-
-	// GET /consents/check - Check consent status for an external ID
-	app.get(
-		'/check',
-		describeRoute({
-			summary: 'Check consent by external user ID',
-			description: `Pre-banner cross-device consent check. Use to avoid showing the banner when the user has already consented on another device.
-
-**Query parameters:**
-- \`externalId\` – External user ID to check
-- \`type\` – Consent type(s) to check (comma-separated)`,
-			tags: ['Consent'],
-			responses: {
-				200: {
-					description: 'Consent check result per requested type(s)',
-					content: {
-						'application/json': {
-							schema: resolver(checkConsentOutputSchema),
-						},
-					},
-				},
-				422: {
-					description: 'Invalid or missing query parameters',
-				},
-			},
-		}),
-		vValidator('query', checkConsentQuerySchema),
-		checkConsentHandler
-	);
-
-	return app;
-};

package/src/routes/index.ts

@@ -1,10 +0,0 @@
-/**
- * Route exports
- *
- * @packageDocumentation
- */
-
-export { createConsentRoutes } from './consent';
-export { createInitRoute } from './init';
-export { createStatusRoute } from './status';
-export { createSubjectRoutes } from './subject';

package/src/routes/init.ts

@@ -1,102 +0,0 @@
-/**
- * Init route - Initializes the consent manager and returns the initial state.
- *
- * @packageDocumentation
- */
-
-import { initOutputSchema } from '@c15t/schema';
-import { Hono } from 'hono';
-import { describeRoute, resolver } from 'hono-openapi';
-import { createGVLResolver } from '~/cache/gvl-resolver';
-import { getJurisdiction, getLocation } from '~/handlers/init/geo';
-import { getTranslationsData } from '~/handlers/init/translations';
-import type { C15TContext, C15TOptions } from '~/types';
-import { getMetrics } from '~/utils/metrics';
-
-/**
- * Creates the init route handler
- */
-export const createInitRoute = (options: C15TOptions) => {
-	const app = new Hono<{ Variables: { c15tContext: C15TContext } }>();
-
-	app.get(
-		'/',
-		describeRoute({
-			summary: 'Get initial consent manager state',
-			description: `Returns the initial state required to render the consent manager.
-
-- **Jurisdiction** – User's jurisdiction (defaults to GDPR if geo-location is disabled)
-- **Location** – User's location (null if geo-location is disabled)
-- **Translations** – Consent manager copy (from \`Accept-Language\` header)
-- **Branding** – Configured branding key
-- **GVL** – Global Vendor List when enabled
-
-Use for geo-targeted consent banners and regional compliance.`,
-			tags: ['Init'],
-			responses: {
-				200: {
-					description:
-						'Initialization payload (jurisdiction, location, translations, branding, GVL)',
-					content: {
-						'application/json': {
-							schema: resolver(initOutputSchema),
-						},
-					},
-				},
-			},
-		}),
-		async (c) => {
-			const request = c.req.raw;
-
-			// Get accept-language header
-			const acceptLanguage = request.headers.get('accept-language') || 'en';
-
-			// Get location and jurisdiction
-			const location = await getLocation(request, options);
-			const jurisdiction = getJurisdiction(location, options);
-
-			// Get translations
-			const translationsResult = getTranslationsData(
-				acceptLanguage,
-				options.advanced?.customTranslations
-			);
-
-			// Get GVL if enabled
-			let gvl = null;
-			if (options.advanced?.gvl?.enabled) {
-				const language = translationsResult.language.split('-')[0] || 'en';
-				const gvlResolver = createGVLResolver({
-					appName: options.appName || 'c15t',
-					bundled: options.advanced.gvl.bundled,
-					cacheAdapter: options.advanced.cache?.adapter,
-					vendorIds: options.advanced.gvl.vendorIds,
-					endpoint: options.advanced.gvl.endpoint,
-				});
-				gvl = await gvlResolver.get(language);
-			}
-
-			// Get custom vendors if configured
-			const customVendors = options.advanced?.gvl?.customVendors;
-
-			// Record init metric
-			const gpc = request.headers.get('sec-gpc') === '1';
-			getMetrics()?.recordInit({
-				jurisdiction,
-				country: location?.countryCode ?? undefined,
-				region: location?.regionCode ?? undefined,
-				gpc,
-			});
-
-			return c.json({
-				jurisdiction,
-				location,
-				translations: translationsResult,
-				branding: options.advanced?.branding || 'c15t',
-				gvl,
-				customVendors,
-			});
-		}
-	);
-
-	return app;
-};

package/src/routes/status.ts

@@ -1,46 +0,0 @@
-/**
- * Status route - Health check and status endpoint.
- *
- * @packageDocumentation
- */
-
-import { statusOutputSchema } from '@c15t/schema';
-import { Hono } from 'hono';
-import { describeRoute, resolver } from 'hono-openapi';
-import { statusHandler } from '~/handlers/status/status.handler';
-import type { C15TContext } from '~/types';
-
-/**
- * Creates the status route
- */
-export const createStatusRoute = () => {
-	const app = new Hono<{ Variables: { c15tContext: C15TContext } }>();
-
-	// GET /status - Health check and status endpoint
-	app.get(
-		'/',
-		describeRoute({
-			summary: 'Health check and API status',
-			description: `Returns API version, timestamp, and client info (IP, region, user agent).
-
-Use for health checks, load balancer probes, and debugging. Performs a lightweight DB check; returns 503 if the database is unreachable.`,
-			tags: ['Status'],
-			responses: {
-				200: {
-					description: 'API is healthy (version, timestamp, client info)',
-					content: {
-						'application/json': {
-							schema: resolver(statusOutputSchema),
-						},
-					},
-				},
-				503: {
-					description: 'Service unavailable (e.g. database unreachable)',
-				},
-			},
-		}),
-		statusHandler
-	);
-
-	return app;
-};

package/src/routes/subject.ts

@@ -1,152 +0,0 @@
-/**
- * Subject routes - CRUD operations for consent subjects.
- *
- * @packageDocumentation
- */
-
-import {
-	getSubjectInputSchema,
-	getSubjectOutputSchema,
-	listSubjectsOutputSchema,
-	listSubjectsQuerySchema,
-	patchSubjectOutputSchema,
-	postSubjectInputSchema,
-	postSubjectOutputSchema,
-	subjectIdSchema,
-} from '@c15t/schema';
-import { Hono } from 'hono';
-import { describeRoute, resolver, validator as vValidator } from 'hono-openapi';
-import * as v from 'valibot';
-import { getSubjectHandler } from '~/handlers/subject/get.handler';
-import { listSubjectsHandler } from '~/handlers/subject/list.handler';
-import { patchSubjectHandler } from '~/handlers/subject/patch.handler';
-import { postSubjectHandler } from '~/handlers/subject/post.handler';
-import type { C15TContext } from '~/types';
-
-/**
- * Creates the subject routes
- */
-export const createSubjectRoutes = () => {
-	const app = new Hono<{ Variables: { c15tContext: C15TContext } }>();
-
-	// GET /subjects/:id - Get a subject's consent status
-	app.get(
-		'/:id',
-		describeRoute({
-			summary: 'Get subject consent status',
-			description: `Returns the subject's consent status for this device. Use to check if the subject has valid consent for given policy types.
-
-**Query:** \`type\` – Filter by consent type(s), comma-separated (e.g. \`privacy_policy,cookie_banner\`).
-
-**Response:** \`subject\`, \`consents\` (matching filter), \`isValid\` (valid consent for requested type(s)).`,
-			tags: ['Subject', 'Consent'],
-			responses: {
-				200: {
-					description: 'Subject and consent records for the requested type(s)',
-					content: {
-						'application/json': {
-							schema: resolver(getSubjectOutputSchema),
-						},
-					},
-				},
-				404: {
-					description: 'Subject not found for the given ID',
-				},
-			},
-		}),
-		vValidator('param', getSubjectInputSchema),
-		getSubjectHandler
-	);
-
-	// POST /subjects - Create a new consent record
-	app.post(
-		'/',
-		describeRoute({
-			summary: 'Record consent for a subject',
-			description: `Creates a new consent record (append-only). Creates the subject if it does not exist.
-
-**Request body by \`type\`:**
-- \`cookie_banner\` – Requires \`preferences\` object
-- \`privacy_policy\`, \`dpa\`, \`terms_and_conditions\` – Optional \`policyId\`
-- \`marketing_communications\`, \`age_verification\`, \`other\` – Optional \`preferences\``,
-			tags: ['Subject', 'Consent'],
-			responses: {
-				200: {
-					description: 'Consent recorded; subject and consent in response',
-					content: {
-						'application/json': {
-							schema: resolver(postSubjectOutputSchema),
-						},
-					},
-				},
-				422: {
-					description: 'Invalid request body (schema or validation failed)',
-				},
-			},
-		}),
-		vValidator('json', postSubjectInputSchema),
-		postSubjectHandler
-	);
-
-	// PATCH /subjects/:id - Link external ID to subject
-	app.patch(
-		'/:id',
-		describeRoute({
-			summary: 'Link external ID to subject',
-			description:
-				'Associates an external user ID with an existing subject (e.g. after login). Enables cross-device consent sync.',
-			tags: ['Subject'],
-			responses: {
-				200: {
-					description: 'Subject updated with external ID',
-					content: {
-						'application/json': {
-							schema: resolver(patchSubjectOutputSchema),
-						},
-					},
-				},
-				404: {
-					description: 'Subject not found for the given ID',
-				},
-			},
-		}),
-		vValidator('param', v.object({ id: subjectIdSchema })),
-		vValidator(
-			'json',
-			v.object({
-				externalId: v.string(),
-				identityProvider: v.optional(v.string()),
-			})
-		),
-		patchSubjectHandler
-	);
-
-	// GET /subjects - List all subjects by external ID (requires API key)
-	app.get(
-		'/',
-		describeRoute({
-			summary: 'List subjects by external ID (API key required)',
-			description:
-				'Returns all subjects linked to the given external ID. Requires Bearer token (API key). Use for server-side consent lookups.',
-			tags: ['Subject'],
-			security: [{ bearerAuth: [] }],
-			responses: {
-				200: {
-					description: 'List of subjects for the external ID',
-					content: {
-						'application/json': {
-							schema: resolver(listSubjectsOutputSchema),
-						},
-					},
-				},
-				401: {
-					description: 'Missing or invalid API key',
-				},
-			},
-		}),
-		vValidator('query', listSubjectsQuerySchema),
-		listSubjectsHandler
-	);
-
-	return app;
-};

package/src/types/api.ts

@@ -1,48 +0,0 @@
-/**
- * Jurisdiction code type for privacy regulations
- */
-export type JurisdictionCode =
-	| 'UK_GDPR' // United Kingdom's GDPR
-	| 'GDPR' // European Union's GDPR (includes EEA)
-	| 'CH'
-	| 'BR'
-	| 'PIPEDA'
-	| 'AU'
-	| 'APPI'
-	| 'PIPA'
-	| 'CCPA'
-	| 'QC_LAW25' // Quebec's Bill 25
-	| 'NONE';
-
-/**
- * Base API path template literal for c15t consent endpoints
- *
- * This type defines the base path for all consent API routes in the c15t system.
- * Used as a foundation for building type-safe consent API route paths.
- *
- * @see ApiPath for complete path patterns
- */
-export type ApiPathBase = `/api/c15t`;
-
-/**
- * Consent API route path with strict type checking
- *
- * This type union represents all valid consent API paths in the system.
- * It enforces type safety when defining routes or middlewares to
- * prevent typos and ensure consistency.
- *
- * @example
- * ```ts
- * // Valid consent API path
- * const consentPath: ApiPath = '/api/c15t/consent';
- *
- * // Invalid - would cause a type error
- * const invalidPath: ApiPath = '/api/c15t/unknown-endpoint';
- * ```
- */
-export type ApiPath =
-	| `${ApiPathBase}`
-	| `${ApiPathBase}/consent`
-	| `${ApiPathBase}/consent/:id`
-	| `${ApiPathBase}/jurisdictions`
-	| `${ApiPathBase}/jurisdictions/:code`;