@c15t/backend 1.8.0 → 2.0.0-rc.0

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

@@ -0,0 +1,199 @@
+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,8 +1,15 @@
-import { os } from './contracts';
-import { consentHandlers } from './handlers/consent';
-import { metaHandlers } from './handlers/meta';
+/**
+ * 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 const router = os.router({
-	consent: consentHandlers,
-	meta: metaHandlers,
-});
+export {
+	createConsentRoutes,
+	createInitRoute,
+	createStatusRoute,
+	createSubjectRoutes,
+} from './routes';

package/src/routes/consent.ts

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

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

package/src/routes/init.ts

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

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

@@ -0,0 +1,152 @@
+/**
+ * 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,3 +1,19 @@
+/**
+ * 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
  *
@@ -29,5 +45,4 @@ export type ApiPath =
 	| `${ApiPathBase}/consent`
 	| `${ApiPathBase}/consent/:id`
 	| `${ApiPathBase}/jurisdictions`
-	| `${ApiPathBase}/jurisdictions/:code`
-	| `${ApiPathBase}/plugins/:id`;
+	| `${ApiPathBase}/jurisdictions/:code`;