@c15t/backend 0.0.1-rc.10

package/src/api/routes/verify-consent.ts

@@ -0,0 +1,272 @@
+import { z } from 'zod';
+import type { EntityOutputFields } from '~/db/schema/definition';
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { C15TContext } from '../../types';
+import { createAuthEndpoint } from '../call';
+
+// Schema for the base verification criteria (at least domain is required)
+const baseVerificationSchema = z.object({
+	domain: z.string(),
+	requiredPreferences: z.record(z.string().datetime().nullable()).optional(),
+	requireExactMatch: z.boolean().optional().default(false),
+	policyVersion: z.string().optional(),
+});
+
+// Define schemas for the different identification methods
+// At least one identifier must be provided
+const identifierSchema = z
+	.object({
+		subjectId: z.string().optional(),
+		externalId: z.string().optional(),
+		ipAddress: z.string().optional(),
+	})
+	.refine(
+		(data) =>
+			data.subjectId !== undefined ||
+			data.externalId !== undefined ||
+			data.ipAddress !== undefined,
+		{
+			message:
+				'At least one identifier (subjectId, externalId, or ipAddress) must be provided',
+		}
+	);
+
+// Combine the schemas
+const verifyConsentSchema = baseVerificationSchema.and(identifierSchema);
+
+export interface VerifyConsentResponse {
+	success: boolean;
+	data: {
+		verified: boolean;
+		consentDetails: {
+			id: string;
+			givenAt: string;
+			policyVersion: string;
+			preferences: Record<string, string | null>;
+		} | null;
+		identifiedBy: string | null;
+		verificationResults: {
+			hasActiveConsent: boolean;
+			meetsPreferenceRequirements: boolean;
+			matchesPolicyVersion: boolean;
+		};
+	};
+}
+
+/**
+ * Endpoint for verifying if a subject has given consent.
+ *
+ * This endpoint allows checking if a subject has provided consent for a specific domain
+ * and verifies if the consent meets specific criteria (required preferences, policy version).
+ * Subjects can be identified by subjectId, externalId, or ipAddress.
+ *
+ * @endpoint GET /consent/verify
+ */
+export const verifyConsent = createAuthEndpoint(
+	'/consent/verify',
+	{
+		method: 'GET',
+		query: verifyConsentSchema,
+	},
+	async (ctx) => {
+		try {
+			const validatedData = verifyConsentSchema.safeParse(ctx.query);
+
+			if (!validatedData.success) {
+				throw new C15TError(
+					'The request data is invalid. Please ensure all required fields are correctly filled and formatted.',
+					{
+						code: BASE_ERROR_CODES.BAD_REQUEST,
+						status: 400,
+						data: {
+							details: validatedData.error.errors,
+						},
+					}
+				);
+			}
+
+			const params = validatedData.data;
+			const { registry } = ctx.context as C15TContext;
+
+			if (!registry) {
+				throw new C15TError(
+					'The registry service is currently unavailable. Please check the service status and try again later.',
+					{
+						code: BASE_ERROR_CODES.INITIALIZATION_FAILED,
+						status: 503,
+					}
+				);
+			}
+
+			// Find subject based on provided identifiers
+			let subjectRecord: EntityOutputFields<'subject'> | null = null;
+			let identifierUsed: string | null = null;
+
+			// Try to find subject by subjectId (most precise)
+			if (params.subjectId) {
+				subjectRecord = await registry.findSubjectById(params.subjectId);
+				if (subjectRecord) {
+					identifierUsed = 'subjectId';
+				}
+			}
+
+			// If not found and externalId provided, try that
+			if (!subjectRecord && params.externalId) {
+				subjectRecord = await registry.findSubjectByExternalId(
+					params.externalId
+				);
+				if (subjectRecord) {
+					identifierUsed = 'externalId';
+				}
+			}
+
+			// If no subject found, return negative verification
+			if (!subjectRecord) {
+				return {
+					success: true,
+					data: {
+						verified: false,
+						consentDetails: null,
+						identifiedBy: null,
+						verificationResults: {
+							hasActiveConsent: false,
+							meetsPreferenceRequirements: false,
+							matchesPolicyVersion: false,
+						},
+					},
+				};
+			}
+
+			// Find active consents for this subject
+			const subjectConsents = await registry.findConsents({
+				subjectId: subjectRecord.id,
+			});
+
+			// Filter for active consents that match the domain
+			const activeConsents = subjectConsents.filter(
+				(consent) =>
+					consent.status === 'active' && consent.domainId === params.domain
+			);
+
+			// Sort consents by givenAt date, most recent first
+			activeConsents.sort(
+				(a, b) => new Date(b.givenAt).getTime() - new Date(a.givenAt).getTime()
+			);
+
+			// Get the most recent active consent for this domain, if any
+			const record = activeConsents.length > 0 ? activeConsents[0] : null;
+
+			// If no consent found, return negative verification
+			if (!record) {
+				return {
+					success: true,
+					data: {
+						verified: false,
+						consentDetails: null,
+						identifiedBy: identifierUsed,
+						verificationResults: {
+							hasActiveConsent: false,
+							meetsPreferenceRequirements: false,
+							matchesPolicyVersion: false,
+						},
+					},
+				};
+			}
+
+			// Verify consent meets criteria if specified
+			let meetsPreferenceRequirements = true;
+			if (params.requiredPreferences) {
+				const preferences =
+					(record.metadata as Record<string, unknown>)?.preferences || {};
+
+				// Check if all required preferences are present and have the correct values
+				for (const [key, requiredValue] of Object.entries(
+					params.requiredPreferences
+				)) {
+					//@ts-expect-error
+					const hasPreference = key in preferences;
+					//@ts-expect-error
+					const preferenceEnabled = hasPreference && preferences[key] !== null;
+
+					if (params.requireExactMatch) {
+						// Exact match requires preference to exist and match value exactly
+						if (
+							!hasPreference ||
+							preferenceEnabled !== (requiredValue !== null)
+						) {
+							meetsPreferenceRequirements = false;
+							break;
+						}
+					} else if (requiredValue !== null && !preferenceEnabled) {
+						// Non-exact match only checks if required trues are true
+						meetsPreferenceRequirements = false;
+						break;
+					}
+				}
+			}
+
+			// Verify policy version if specified
+			const matchesPolicyVersion = params.policyVersion
+				? record.policyId === params.policyVersion
+				: true;
+
+			// Determine overall verification result
+			const verified =
+				record.status === 'active' &&
+				meetsPreferenceRequirements &&
+				matchesPolicyVersion;
+
+			// Return verification result
+			return {
+				success: true,
+				data: {
+					verified,
+					consentDetails: {
+						id: record.id,
+						givenAt: record.givenAt.toISOString(),
+						policyVersion: record.policyId || '',
+						preferences:
+							(record.metadata as Record<string, unknown>)?.preferences || {},
+					},
+					identifiedBy: identifierUsed,
+					verificationResults: {
+						hasActiveConsent: record.status === 'active',
+						meetsPreferenceRequirements,
+						matchesPolicyVersion,
+					},
+				},
+			};
+		} catch (error) {
+			const context = ctx.context as C15TContext;
+			context.logger?.error?.('Error verifying consent:', error);
+
+			if (error instanceof C15TError) {
+				throw error;
+			}
+			if (error instanceof z.ZodError) {
+				throw new C15TError(
+					'The request data is invalid. Please ensure all required fields are correctly filled and formatted.',
+					{
+						code: BASE_ERROR_CODES.BAD_REQUEST,
+						status: 400,
+						data: {
+							details: error.errors,
+						},
+					}
+				);
+			}
+
+			throw new C15TError(
+				'Failed to verify consent. Please try again later or contact support if the issue persists.',
+				{
+					code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+					status: 503,
+					data: {
+						details:
+							error instanceof Error ? { message: error.message } : { error },
+					},
+				}
+			);
+		}
+	}
+);

package/src/api/routes/withdraw-consent.ts

@@ -0,0 +1,293 @@
+import { z } from 'zod';
+import type { EntityOutputFields } from '~/db/schema/definition';
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { C15TContext } from '../../types';
+import { createAuthEndpoint } from '../call';
+
+// Define the schemas for validating request body
+// We'll have three different schemas for the three identification methods
+const withdrawByConsentIdSchema = z.object({
+	consentId: z.string(),
+	identifierType: z.literal('consentId'),
+	reason: z.string().optional(),
+	method: z.string().min(1).max(50),
+	actor: z.string().optional(),
+	metadata: z.record(z.any()).optional(),
+});
+
+const withdrawBySubjectIdSchema = z.object({
+	subjectId: z.string(),
+	domain: z.string(),
+	identifierType: z.literal('subjectId'),
+	reason: z.string().optional(),
+	method: z.string().min(1).max(50),
+	actor: z.string().optional(),
+	metadata: z.record(z.any()).optional(),
+});
+
+const withdrawByExternalIdSchema = z.object({
+	externalId: z.string(),
+	domain: z.string(),
+	identifierType: z.literal('externalId'),
+	reason: z.string().optional(),
+	method: z.string().min(1).max(50),
+	actor: z.string().optional(),
+	metadata: z.record(z.any()).optional(),
+});
+
+// Combined schema using discriminated union
+const withdrawConsentSchema = z.discriminatedUnion('identifierType', [
+	withdrawByConsentIdSchema,
+	withdrawBySubjectIdSchema,
+	withdrawByExternalIdSchema,
+]);
+
+export interface WithdrawConsentResponse {
+	success: boolean;
+	data: {
+		withdrawalIds: string[];
+		consentIds: string[];
+		revokedAt: string;
+	};
+}
+
+/**
+ * Endpoint for withdrawing previously given consent.
+ *
+ * This endpoint allows clients to revoke a subject's consent by specifying either:
+ * 1. The specific consent ID to withdraw
+ * 2. The subject ID and domain to withdraw all active consents for that subject on that domain
+ * 3. The external subject ID and domain to withdraw all active consents for that subject on that domain
+ *
+ * @endpoint POST /consent/withdraw
+ */
+export const withdrawConsent = createAuthEndpoint(
+	'/consent/withdraw',
+	{
+		method: 'POST',
+		body: withdrawConsentSchema,
+	},
+	async (ctx) => {
+		try {
+			const validatedData = withdrawConsentSchema.safeParse(ctx.body);
+
+			if (!validatedData.success) {
+				throw new C15TError(
+					'The request data is invalid. Please ensure all required fields are correctly filled and formatted.',
+					{
+						code: BASE_ERROR_CODES.BAD_REQUEST,
+						status: 400,
+						data: { details: validatedData.error.errors },
+					}
+				);
+			}
+
+			const params = validatedData.data;
+			const { registry } = ctx.context as C15TContext;
+
+			if (!registry) {
+				throw new C15TError(
+					'The registry service is currently unavailable. Please check the service status and try again later.',
+					{
+						code: BASE_ERROR_CODES.INITIALIZATION_FAILED,
+						status: 503,
+					}
+				);
+			}
+
+			// Find the consent records to withdraw based on the identifier type
+			let recordsToWithdraw: EntityOutputFields<'consent'>[] = [];
+
+			if (params.identifierType === 'consentId') {
+				// Find by consent ID
+				const record = await registry.findConsentById(params.consentId);
+
+				if (!record) {
+					throw new C15TError(
+						'The specified consent record could not be found. Please verify the consent ID and try again.',
+						{
+							code: BASE_ERROR_CODES.CONSENT_NOT_FOUND,
+							status: 404,
+							data: { consentId: params.consentId },
+						}
+					);
+				}
+
+				if (record.status !== 'active') {
+					throw new C15TError(
+						'The consent has already been withdrawn. No further action is required.',
+						{
+							code: BASE_ERROR_CODES.CONFLICT,
+							status: 409,
+							data: {
+								consentId: params.consentId,
+								currentStatus: record.status,
+							},
+						}
+					);
+				}
+
+				recordsToWithdraw = [record];
+			} else if (
+				params.identifierType === 'subjectId' ||
+				params.identifierType === 'externalId'
+			) {
+				// Find subject
+				let subjectRecord: EntityOutputFields<'subject'> | null = null;
+				if (params.identifierType === 'subjectId') {
+					subjectRecord = await registry.findSubjectById(params.subjectId);
+				} else {
+					subjectRecord = await registry.findSubjectByExternalId(
+						params.externalId
+					);
+				}
+
+				if (!subjectRecord) {
+					throw new C15TError(
+						'The specified subject could not be found. Please verify the subject ID or external ID and try again.',
+						{
+							code: BASE_ERROR_CODES.NOT_FOUND,
+							status: 404,
+							data:
+								params.identifierType === 'subjectId'
+									? { subjectId: params.subjectId }
+									: { externalId: params.externalId },
+						}
+					);
+				}
+
+				// Find all active consents for this subject and domain
+				const subjectConsents = await registry.findConsents({
+					subjectId: subjectRecord.id,
+				});
+
+				// Filter for active consents with matching domain
+				recordsToWithdraw = subjectConsents.filter(
+					(consent) =>
+						consent.status === 'active' && consent.domainId === params.domain
+				);
+
+				if (recordsToWithdraw.length === 0) {
+					throw new C15TError(
+						'No active consent records were found for this subject and domain. Please ensure the subject and domain are correct.',
+						{
+							code: BASE_ERROR_CODES.CONSENT_NOT_FOUND,
+							status: 404,
+							data: {
+								domain: params.domain,
+								...(params.identifierType === 'subjectId'
+									? { subjectId: params.subjectId }
+									: { externalId: params.externalId }),
+							},
+						}
+					);
+				}
+			}
+
+			// Get device info from request
+			const requestHeaders = ctx.request?.headers as
+				| Record<string, string>
+				| undefined;
+			const deviceInfo = requestHeaders?.['user-agent'] || '';
+			// @ts-expect-error
+			const ipAddress = ctx.request?.ip || '';
+
+			// Process each consent record to withdraw
+			const withdrawalResults: Array<{
+				id: string;
+				consentId: string;
+				revokedAt: string;
+			}> = [];
+
+			const currentTime = new Date();
+
+			for (const record of recordsToWithdraw) {
+				// Use the revokeConsent method from the internal adapter
+				const withdrawalResult = await registry.revokeConsent({
+					consentId: record.id,
+					reason: params.reason || '',
+					actor: params.actor || 'system',
+					metadata: params.metadata || {},
+				});
+
+				// Add consent record for the consentWithdrawal
+				await registry.createConsentRecord({
+					subjectId: record.subjectId,
+					consentId: record.id,
+					actionType: 'withdraw_consent',
+					details: {
+						reason: params.reason,
+						method: params.method,
+						identifierType: params.identifierType,
+						withdrawnAt: currentTime.toISOString(),
+					},
+					createdAt: currentTime,
+					updatedAt: currentTime,
+				});
+
+				// Log the action in the audit log
+				await registry.createAuditLog({
+					subjectId: record.subjectId,
+					entityType: 'consent',
+					entityId: record.id,
+					actionType: 'withdraw_consent',
+					changes: {
+						policyVersion: record.policyId,
+					},
+					metadata: {
+						source: 'api',
+						...params.metadata,
+					},
+					ipAddress,
+					userAgent: deviceInfo,
+					createdAt: currentTime,
+				});
+
+				withdrawalResults.push({
+					id: withdrawalResult?.id || `wdr_${record.id}`,
+					consentId: record.id,
+					revokedAt: currentTime.toISOString(),
+				});
+			}
+
+			// Return success response with consentWithdrawal details
+			return {
+				success: true,
+				data: {
+					withdrawalIds: withdrawalResults.map((wr) => wr.id),
+					consentIds: withdrawalResults.map((wr) => wr.consentId),
+					revokedAt:
+						withdrawalResults[0]?.revokedAt || currentTime.toISOString(),
+				},
+			};
+		} catch (error) {
+			const context = ctx.context as C15TContext;
+			context.logger?.error?.('Error withdrawing consent:', error);
+
+			if (error instanceof C15TError) {
+				throw error;
+			}
+			if (error instanceof z.ZodError) {
+				throw new C15TError(
+					'The request data is invalid. Please ensure all required fields are correctly filled and formatted.',
+					{
+						code: BASE_ERROR_CODES.BAD_REQUEST,
+						status: 400,
+						data: { details: error.errors },
+					}
+				);
+			}
+
+			throw new C15TError(
+				'Failed to withdraw consent. Please try again later or contact support if the issue persists.',
+				{
+					code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+					status: 503,
+					data: {
+						error: error instanceof Error ? error.message : String(error),
+					},
+				}
+			);
+		}
+	}
+);