@c15t/backend 1.8.0 → 2.0.0-rc.0

package/src/handlers/subject/post.handler.test.ts

@@ -0,0 +1,294 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { postSubjectHandler } from './post.handler';
+
+vi.mock('~/utils/metrics', () => ({
+	getMetrics: vi.fn(() => ({
+		recordConsentCreated: vi.fn(),
+		recordConsentAccepted: vi.fn(),
+		recordConsentRejected: vi.fn(),
+	})),
+}));
+
+vi.mock('~/db/registry/utils', () => ({
+	generateUniqueId: vi.fn().mockResolvedValue('con_new'),
+}));
+
+const GIVEN_AT = 1700000000000;
+const GIVEN_AT_DATE = new Date(GIVEN_AT);
+
+const baseInput = {
+	type: 'cookie_consent',
+	subjectId: 'sub_user1',
+	domain: 'example.com',
+	givenAt: GIVEN_AT,
+	metadata: { source: 'banner' },
+};
+
+const mockSubject = { id: 'sub_user1' };
+const mockDomain = { id: 'dom_1', name: 'example.com' };
+const mockPolicy = { id: 'pol_1', isActive: true };
+
+function createMockRegistry() {
+	return {
+		findOrCreateSubject: vi.fn().mockResolvedValue(mockSubject),
+		findOrCreateDomain: vi.fn().mockResolvedValue(mockDomain),
+		findOrCreatePolicy: vi.fn().mockResolvedValue(mockPolicy),
+		findConsentPolicyById: vi.fn(),
+		findOrCreateConsentPurposeByCode: vi.fn(),
+	};
+}
+
+function createMockDb(findFirstResult: unknown = null) {
+	return {
+		findFirst: vi.fn().mockResolvedValue(findFirstResult),
+		transaction: vi.fn(async (fn: (tx: unknown) => unknown) => {
+			const tx = {
+				create: vi.fn().mockResolvedValue({
+					id: 'con_new',
+					givenAt: GIVEN_AT_DATE,
+				}),
+			};
+			return fn(tx);
+		}),
+	};
+}
+
+function createMockContext(db: unknown, registry: unknown) {
+	const logger = {
+		info: vi.fn(),
+		debug: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+	};
+
+	const ctx = {
+		db,
+		registry,
+		logger,
+		ipAddress: '127.0.0.1',
+		userAgent: 'TestAgent/1.0',
+	};
+
+	let jsonData: unknown;
+
+	return {
+		get: (key: string) => {
+			if (key === 'c15tContext') return ctx;
+			return undefined;
+		},
+		json: vi.fn((data) => {
+			jsonData = data;
+			return data;
+		}),
+		req: {
+			json: vi.fn().mockResolvedValue(baseInput),
+		},
+		getJsonData: () => jsonData,
+		_ctx: ctx,
+	};
+}
+
+describe('postSubjectHandler idempotency', () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+		vi.restoreAllMocks();
+	});
+
+	it('should return existing consent on duplicate submission', async () => {
+		const existingConsent = {
+			id: 'con_existing',
+			givenAt: GIVEN_AT_DATE,
+		};
+		const db = createMockDb(existingConsent);
+		const registry = createMockRegistry();
+		const mockCtx = createMockContext(db, registry);
+
+		// @ts-expect-error - simplified test context
+		await postSubjectHandler(mockCtx);
+
+		const result = mockCtx.getJsonData() as {
+			consentId: string;
+			subjectId: string;
+		};
+
+		expect(result.consentId).toBe('con_existing');
+		expect(result.subjectId).toBe('sub_user1');
+		expect(db.findFirst).toHaveBeenCalledWith('consent', {
+			where: expect.any(Function),
+		});
+		expect(db.transaction).not.toHaveBeenCalled();
+	});
+
+	it('should create new consent when no duplicate exists', async () => {
+		const db = createMockDb(null);
+		const registry = createMockRegistry();
+		const mockCtx = createMockContext(db, registry);
+
+		// @ts-expect-error - simplified test context
+		await postSubjectHandler(mockCtx);
+
+		const result = mockCtx.getJsonData() as {
+			consentId: string;
+			subjectId: string;
+		};
+
+		expect(result.consentId).toBe('con_new');
+		expect(db.findFirst).toHaveBeenCalled();
+		expect(db.transaction).toHaveBeenCalled();
+	});
+
+	it('should create separate records for different givenAt timestamps', async () => {
+		const db = createMockDb(null);
+		const registry = createMockRegistry();
+
+		// First call
+		const mockCtx1 = createMockContext(db, registry);
+		// @ts-expect-error - simplified test context
+		await postSubjectHandler(mockCtx1);
+
+		// Second call with different givenAt
+		const mockCtx2 = createMockContext(db, registry);
+		mockCtx2.req.json = vi.fn().mockResolvedValue({
+			...baseInput,
+			givenAt: GIVEN_AT + 1000,
+		});
+		// @ts-expect-error - simplified test context
+		await postSubjectHandler(mockCtx2);
+
+		// Both calls should go through the transaction (findFirst returns null)
+		expect(db.transaction).toHaveBeenCalledTimes(2);
+	});
+
+	it('should persist metadata and uiSource in consent record', async () => {
+		const inputWithMeta = {
+			...baseInput,
+			metadata: { customKey: 'customValue' },
+			uiSource: 'banner',
+		};
+		const db = createMockDb(null);
+		const registry = createMockRegistry();
+		const mockCtx = createMockContext(db, registry);
+		mockCtx.req.json = vi.fn().mockResolvedValue(inputWithMeta);
+
+		// @ts-expect-error - simplified test context
+		await postSubjectHandler(mockCtx);
+
+		// Get the tx.create call
+		const transactionFn = db.transaction.mock.calls[0][0];
+		const tx = {
+			create: vi
+				.fn()
+				.mockResolvedValue({ id: 'con_new', givenAt: GIVEN_AT_DATE }),
+		};
+		await transactionFn(tx);
+
+		expect(tx.create).toHaveBeenCalledWith(
+			'consent',
+			expect.objectContaining({
+				metadata: { json: { customKey: 'customValue' } },
+				uiSource: 'banner',
+			})
+		);
+	});
+
+	it('should include uiSource in response for new consent', async () => {
+		const inputWithSource = {
+			...baseInput,
+			uiSource: 'dialog',
+		};
+		const db = createMockDb(null);
+		const registry = createMockRegistry();
+		const mockCtx = createMockContext(db, registry);
+		mockCtx.req.json = vi.fn().mockResolvedValue(inputWithSource);
+
+		// @ts-expect-error - simplified test context
+		await postSubjectHandler(mockCtx);
+
+		const result = mockCtx.getJsonData() as {
+			uiSource: string;
+		};
+
+		expect(result.uiSource).toBe('dialog');
+	});
+
+	it('should include uiSource in response for duplicate consent', async () => {
+		const inputWithSource = {
+			...baseInput,
+			uiSource: 'widget',
+		};
+		const existingConsent = {
+			id: 'con_existing',
+			givenAt: GIVEN_AT_DATE,
+		};
+		const db = createMockDb(existingConsent);
+		const registry = createMockRegistry();
+		const mockCtx = createMockContext(db, registry);
+		mockCtx.req.json = vi.fn().mockResolvedValue(inputWithSource);
+
+		// @ts-expect-error - simplified test context
+		await postSubjectHandler(mockCtx);
+
+		const result = mockCtx.getJsonData() as {
+			uiSource: string;
+		};
+
+		expect(result.uiSource).toBe('widget');
+	});
+
+	it('should omit metadata from consent record when not provided', async () => {
+		const inputNoMeta = {
+			type: 'cookie_consent',
+			subjectId: 'sub_user1',
+			domain: 'example.com',
+			givenAt: GIVEN_AT,
+		};
+		const db = createMockDb(null);
+		const registry = createMockRegistry();
+		const mockCtx = createMockContext(db, registry);
+		mockCtx.req.json = vi.fn().mockResolvedValue(inputNoMeta);
+
+		// @ts-expect-error - simplified test context
+		await postSubjectHandler(mockCtx);
+
+		// Get the tx.create call
+		const transactionFn = db.transaction.mock.calls[0][0];
+		const tx = {
+			create: vi
+				.fn()
+				.mockResolvedValue({ id: 'con_new', givenAt: GIVEN_AT_DATE }),
+		};
+		await transactionFn(tx);
+
+		expect(tx.create).toHaveBeenCalledWith(
+			'consent',
+			expect.objectContaining({
+				metadata: undefined,
+			})
+		);
+	});
+
+	it('should not record metrics for duplicate submissions', async () => {
+		const { getMetrics } = await import('~/utils/metrics');
+		const mockMetrics = {
+			recordConsentCreated: vi.fn(),
+			recordConsentAccepted: vi.fn(),
+			recordConsentRejected: vi.fn(),
+		};
+		vi.mocked(getMetrics).mockReturnValue(mockMetrics as never);
+
+		const existingConsent = {
+			id: 'con_existing',
+			givenAt: GIVEN_AT_DATE,
+		};
+		const db = createMockDb(existingConsent);
+		const registry = createMockRegistry();
+		const mockCtx = createMockContext(db, registry);
+
+		// @ts-expect-error - simplified test context
+		await postSubjectHandler(mockCtx);
+
+		expect(mockMetrics.recordConsentCreated).not.toHaveBeenCalled();
+		expect(mockMetrics.recordConsentAccepted).not.toHaveBeenCalled();
+		expect(mockMetrics.recordConsentRejected).not.toHaveBeenCalled();
+	});
+});

package/src/handlers/subject/post.handler.ts

@@ -0,0 +1,254 @@
+/**
+ * POST /subjects handler - Records consent (append-only).
+ *
+ * @packageDocumentation
+ */
+
+import type { PostSubjectInput } from '@c15t/schema';
+import type { Context } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import { generateUniqueId } from '~/db/registry/utils';
+import type { C15TContext } from '~/types';
+import { extractErrorMessage } from '~/utils/extract-error-message';
+import { getMetrics } from '~/utils/metrics';
+
+/**
+ * Handles the creation of a new consent record for a subject.
+ *
+ * This handler processes consent submissions with client-generated subject IDs.
+ * Each call creates a new consent record (append-only), preserving the full audit trail.
+ */
+export const postSubjectHandler = async (c: Context) => {
+	const ctx = c.get('c15tContext') as C15TContext;
+	const logger = ctx.logger;
+	logger.info('Handling POST /subjects request');
+
+	const { db, registry } = ctx;
+
+	const input = await c.req.json<PostSubjectInput>();
+
+	const {
+		type,
+		subjectId,
+		identityProvider,
+		externalSubjectId,
+		domain,
+		metadata,
+		givenAt: givenAtEpoch,
+	} = input;
+
+	const preferences = 'preferences' in input ? input.preferences : undefined;
+	const givenAt = new Date(givenAtEpoch);
+
+	logger.debug('Request parameters', {
+		type,
+		subjectId,
+		identityProvider,
+		externalSubjectId,
+		domain,
+	});
+
+	try {
+		// Find or create subject with the client-provided ID
+		const subject = await registry.findOrCreateSubject({
+			subjectId,
+			externalSubjectId,
+			identityProvider,
+			ipAddress: ctx.ipAddress,
+		});
+
+		if (!subject) {
+			throw new HTTPException(500, {
+				message: 'Failed to create subject',
+				cause: { code: 'SUBJECT_CREATION_FAILED', subjectId },
+			});
+		}
+
+		logger.debug('Subject found/created', { subjectId: subject.id });
+
+		const domainRecord = await registry.findOrCreateDomain(domain);
+
+		if (!domainRecord) {
+			throw new HTTPException(500, {
+				message: 'Failed to create domain',
+				cause: { code: 'DOMAIN_CREATION_FAILED', domain },
+			});
+		}
+
+		let policyId: string | undefined;
+		let purposeIds: string[] = [];
+
+		const inputPolicyId =
+			'policyId' in input ? (input.policyId as string | undefined) : undefined;
+		if (inputPolicyId) {
+			policyId = inputPolicyId;
+
+			// Verify the policy exists and is active
+			const policy = await registry.findConsentPolicyById(inputPolicyId);
+			if (!policy) {
+				throw new HTTPException(404, {
+					message: 'Policy not found',
+					cause: { code: 'POLICY_NOT_FOUND', policyId, type },
+				});
+			}
+			if (!policy.isActive) {
+				throw new HTTPException(400, {
+					message: 'Policy is inactive',
+					cause: { code: 'POLICY_INACTIVE', policyId, type },
+				});
+			}
+		} else {
+			const policy = await registry.findOrCreatePolicy(type);
+			if (!policy) {
+				throw new HTTPException(500, {
+					message: 'Failed to create policy',
+					cause: { code: 'POLICY_CREATION_FAILED', type },
+				});
+			}
+			policyId = policy.id;
+		}
+
+		// Handle purposes if they exist
+		if (preferences) {
+			const consentedPurposes = Object.entries(preferences)
+				.filter(([_, isConsented]) => isConsented)
+				.map(([purposeCode]) => purposeCode);
+
+			logger.debug('Consented purposes', { consentedPurposes });
+
+			// Batch fetch all existing purposes
+			const purposesRaw = await Promise.all(
+				consentedPurposes.map((purposeCode) =>
+					registry.findOrCreateConsentPurposeByCode(purposeCode)
+				)
+			);
+
+			const purposes = purposesRaw
+				.map((purpose) => purpose?.id ?? null)
+				.filter((id): id is string => Boolean(id));
+
+			logger.debug('Filtered purposes', { purposes });
+
+			if (purposes.length === 0) {
+				logger.warn(
+					'No valid purpose IDs found after filtering. Using empty list.',
+					{ consentedPurposes }
+				);
+			}
+
+			purposeIds = purposes;
+		}
+
+		// Check for duplicate consent (idempotency)
+		const existingConsent = await db.findFirst('consent', {
+			where: (b) =>
+				b.and(
+					b('subjectId', '=', subject.id),
+					b('domainId', '=', domainRecord.id),
+					b('policyId', '=', policyId),
+					b('givenAt', '=', givenAt)
+				),
+		});
+
+		if (existingConsent) {
+			logger.debug('Duplicate consent detected, returning existing record', {
+				consentId: existingConsent.id,
+			});
+			return c.json({
+				subjectId: subject.id,
+				consentId: existingConsent.id,
+				domainId: domainRecord.id,
+				domain: domainRecord.name,
+				type,
+				metadata,
+				uiSource: input.uiSource,
+				givenAt: existingConsent.givenAt,
+			});
+		}
+
+		const result = await db.transaction(async (tx) => {
+			logger.debug('Creating consent record', {
+				subjectId: subject.id,
+				domainId: domainRecord.id,
+				policyId,
+				purposeIds,
+			});
+
+			// Always create a new consent record (append-only)
+			const consentRecord = await tx.create('consent', {
+				id: await generateUniqueId(tx, 'consent', ctx),
+				subjectId: subject.id,
+				domainId: domainRecord.id,
+				policyId,
+				purposeIds: { json: purposeIds },
+				metadata: metadata ? { json: metadata } : undefined,
+				ipAddress: ctx.ipAddress,
+				userAgent: ctx.userAgent,
+				jurisdiction: input.jurisdiction,
+				jurisdictionModel: input.jurisdictionModel,
+				tcString: input.tcString,
+				uiSource: input.uiSource,
+				givenAt,
+			});
+
+			logger.debug('Created consent', { consentRecord: consentRecord.id });
+
+			if (!consentRecord) {
+				throw new HTTPException(500, {
+					message: 'Failed to create consent',
+					cause: {
+						code: 'CONSENT_CREATION_FAILED',
+						subjectId: subject.id,
+						domain,
+					},
+				});
+			}
+
+			return {
+				consent: consentRecord,
+			};
+		});
+
+		// Record telemetry metrics
+		const metrics = getMetrics();
+		if (metrics) {
+			const jurisdiction = input.jurisdiction;
+			metrics.recordConsentCreated({ type, jurisdiction });
+
+			// Determine accepted vs rejected based on preferences
+			const hasAccepted =
+				preferences && Object.values(preferences).some(Boolean);
+			if (hasAccepted) {
+				metrics.recordConsentAccepted({ type, jurisdiction });
+			} else {
+				metrics.recordConsentRejected({ type, jurisdiction });
+			}
+		}
+
+		// Return the response
+		return c.json({
+			subjectId: subject.id,
+			consentId: result.consent.id,
+			domainId: domainRecord.id,
+			domain: domainRecord.name,
+			type,
+			metadata,
+			uiSource: input.uiSource,
+			givenAt: result.consent.givenAt,
+		});
+	} catch (error) {
+		logger.error('Error in POST /subjects handler', {
+			error: extractErrorMessage(error),
+			errorType: error instanceof Error ? error.constructor.name : typeof error,
+		});
+
+		if (error instanceof HTTPException) {
+			throw error;
+		}
+
+		throw new HTTPException(500, {
+			message: 'Internal server error',
+			cause: { code: 'INTERNAL_SERVER_ERROR' },
+		});
+	}
+};