@c15t/backend 0.0.1-rc.10

package/src/db/schema/audit-log/table.ts

@@ -0,0 +1,185 @@
+import { COMMON_TIMEZONES, type Field } from '~/db/core/fields';
+import type { C15TOptions } from '~/types';
+import { auditLogSchema } from './schema';
+
+/**
+ * Generates the database table configuration for the consent audit log entity.
+ *
+ * This function creates a schema definition that includes all standard audit log fields
+ * and any additional fields from plugins or configuration. The resulting schema is used
+ * for database migrations, schema validation, and query building.
+ *
+ * @param options - C15T configuration options that may contain audit log table customizations
+ * @param auditLogFields - Additional fields from plugins to include in the audit log table
+ * @returns A complete table schema definition with fields, model name, and metadata
+ *
+ * @example
+ * ```typescript
+ * const auditLogTableSchema = getAuditLogTable(c15tOptions);
+ * // Use the schema for migrations or data access
+ * const migrationPlans = generateMigrations(auditLogTableSchema);
+ * ```
+ */
+export function getAuditLogTable(
+	options: C15TOptions,
+	auditLogFields?: Record<string, Field>
+) {
+	const auditLogConfig = options.tables?.auditLog;
+	const subjectConfig = options.tables?.subject;
+
+	return {
+		/**
+		 * The name of the audit log table in the database, configurable through options
+		 */
+		entityName: auditLogConfig?.entityName || 'auditLog',
+
+		/**
+		 * The ID prefix for the audit log table
+		 * Used to generate unique prefixed IDs
+		 */
+		entityPrefix: auditLogConfig?.entityPrefix || 'log',
+
+		/**
+		 * The schema for the audit log table
+		 */
+		schema: auditLogSchema,
+
+		/**
+		 * Field definitions for the consent audit log table
+		 */
+		fields: {
+			/**
+			 * Type of entity this audit log entry is about (e.g., 'consent', 'subject', 'consentPurpose')
+			 */
+			entityType: {
+				type: 'string',
+				required: true,
+				fieldName: auditLogConfig?.fields?.entityType || 'entityType',
+			},
+
+			/**
+			 * ID of the entity this audit log entry is about
+			 */
+			entityId: {
+				type: 'string',
+				required: true,
+				fieldName: auditLogConfig?.fields?.entityId || 'entityId',
+			},
+
+			/**
+			 * Type of action that was performed on the entity
+			 * Common values: 'create', 'update', 'delete', 'view'
+			 */
+			actionType: {
+				type: 'string',
+				required: true,
+				fieldName: auditLogConfig?.fields?.actionType || 'actionType',
+			},
+
+			/**
+			 * Optional ID of the subject who performed the action
+			 */
+			subjectId: {
+				type: 'string',
+				required: false,
+				fieldName: auditLogConfig?.fields?.subjectId || 'subjectId',
+				references: {
+					model: subjectConfig?.entityName || 'subject',
+					field: 'id',
+				},
+			},
+
+			/**
+			 * IP address from which the action was performed
+			 */
+			ipAddress: {
+				type: 'string',
+				required: false,
+				fieldName: auditLogConfig?.fields?.ipAddress || 'ipAddress',
+			},
+
+			/**
+			 * Subject agent (browser/device) from which the action was performed
+			 */
+			userAgent: {
+				type: 'string',
+				required: false,
+				fieldName: auditLogConfig?.fields?.userAgent || 'userAgent',
+			},
+
+			/**
+			 * Detailed changes made to the entity
+			 * For updates, this typically contains before/after values
+			 */
+			changes: {
+				type: 'json',
+				required: false,
+				fieldName: auditLogConfig?.fields?.changes || 'changes',
+			},
+
+			/**
+			 * Additional metadata about the action
+			 */
+			metadata: {
+				type: 'json',
+				required: false,
+				fieldName: auditLogConfig?.fields?.metadata || 'metadata',
+			},
+
+			/**
+			 * When the audit log entry was created
+			 * Automatically set to current time by default
+			 */
+			createdAt: {
+				type: 'date',
+				defaultValue: () => new Date(),
+				required: true,
+				fieldName: auditLogConfig?.fields?.createdAt || 'createdAt',
+			},
+
+			/**
+			 * Timezone where the audit event occurred
+			 */
+			eventTimezone: {
+				type: 'timezone',
+				required: true,
+				defaultValue: COMMON_TIMEZONES.UTC,
+				fieldName: auditLogConfig?.fields?.eventTimezone || 'eventTimezone',
+			},
+
+			// Include additional fields from plugins
+			...(auditLogFields || {}),
+
+			// Include additional fields from configuration
+			...(auditLogConfig?.additionalFields || {}),
+		},
+
+		/**
+		 * Add indexes for better query performance
+		 */
+		indexes: [
+			{
+				name: 'entity_index',
+				fields: ['entityType', 'entityId'],
+			},
+			{
+				name: 'action_type_index',
+				fields: ['actionType'],
+			},
+			{
+				name: 'subject_id_index',
+				fields: ['subjectId'],
+			},
+			{
+				name: 'created_at_index',
+				fields: ['createdAt'],
+			},
+		],
+
+		/**
+		 * Execution order during migrations (lower numbers run first)
+		 * Audit log table needs to be created after the subject table it references
+		 */
+		order: 5,
+	};
+}

package/src/db/schema/audit-log/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Audit Log Entity Type Definitions
+ *
+ * This module contains type definitions specific to the audit log entity.
+ */
+import type { BaseEntityConfig } from '../types';
+
+/**
+ * Audit log entity configuration
+ * @default {entityName: "auditLog", entityPrefix: "log"}
+ *
+ * These defaults are applied when creating an audit log entity if not explicitly specified.
+ * See the entity creation utilities for implementation details.
+ */
+export interface AuditLogEntityConfig extends BaseEntityConfig {
+	fields?: Record<string, string> & {
+		id?: string;
+		timestamp: string;
+		action: string;
+		subjectId?: string;
+		resourceType: string;
+		resourceId?: string;
+		actor?: string;
+		changes?: string;
+		deviceInfo?: string;
+		ipAddress?: string;
+		createdAt?: string;
+	};
+}

package/src/db/schema/consent/index.ts

@@ -0,0 +1,3 @@
+export * from './registry';
+export * from './schema';
+export * from './table';

package/src/db/schema/consent/registry.ts

@@ -0,0 +1,381 @@
+import type { Where } from '~/db/adapters/types';
+import { getWithHooks } from '~/db/hooks';
+import type { GenericEndpointContext, RegistryContext } from '~/types';
+import { validateEntityOutput } from '../definition';
+import type { Consent } from './schema';
+
+export interface FindConsentsParams {
+	subjectId?: string;
+	domainId?: string;
+	status?: string;
+	purposeIds?: string[];
+	includeInactive?: boolean;
+}
+
+export interface RevokeConsentParams {
+	consentId: string;
+	reason: string;
+	actor: string;
+	metadata?: Record<string, unknown>;
+	context?: GenericEndpointContext;
+}
+
+/**
+ * Creates and returns a set of consent-related adapter methods to interact with the database.
+ * These methods provide a consistent interface for creating, finding, and updating
+ * consent records while applying hooks and enforcing data validation rules.
+ *
+ * @param adapter - The database adapter used for direct database operations
+ * @param ctx - The context object containing the database adapter, hooks, and options
+ * @returns An object containing type-safe consent operations
+ *
+ * @example
+ * ```typescript
+ * const consentAdapter = createConsentAdapter(
+ *   databaseAdapter,
+ *   createWithHooks,
+ *   updateWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new consent record
+ * const consent = await consentAdapter.createConsent({
+ *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
+ *   domainId: 'dom_x1pftyoufsm7xgo1kv',
+ *   purposeIds: ['pur_e8zyhgozr3im7xj59it'],
+ *   status: 'active'
+ * });
+ * ```
+ */
+export function consentRegistry({ adapter, ...ctx }: RegistryContext) {
+	const { createWithHooks, updateWithHooks } = getWithHooks(adapter, ctx);
+	const registry = {
+		/**
+		 * Creates a new consent record in the database.
+		 * Automatically sets creation timestamp and applies any
+		 * configured hooks during the creation process.
+		 *
+		 * @param consent - Consent data to create (without id and timestamp)
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The created consent with all fields populated
+		 * @throws May throw an error if hooks prevent creation or if database operations fail
+		 */
+		createConsent: async (
+			consent: Omit<Consent, 'id' | 'createdAt'> & Partial<Consent>,
+			context?: GenericEndpointContext
+		) => {
+			const createdConsent = await createWithHooks({
+				data: {
+					createdAt: new Date(),
+					...consent,
+				},
+				model: 'consent',
+				context,
+			});
+
+			if (!createdConsent) {
+				throw new Error('Failed to create consent - operation returned null');
+			}
+
+			return createdConsent as Consent;
+		},
+
+		/**
+		 * Finds all consents matching specified filters.
+		 * Returns consents with processed output fields according to the schema configuration.
+		 *
+		 * @param params - Filter parameters
+		 * @returns Array of consents matching the criteria
+		 */
+		findConsents: async (params: FindConsentsParams = {}) => {
+			const whereConditions: Where<'consent'> = [];
+
+			if (!params.includeInactive) {
+				whereConditions.push({
+					field: 'isActive',
+					value: true,
+				});
+			}
+
+			if (params.subjectId) {
+				whereConditions.push({
+					field: 'subjectId',
+					value: params.subjectId,
+				});
+			}
+
+			if (params.domainId) {
+				whereConditions.push({
+					field: 'domainId',
+					value: params.domainId,
+				});
+			}
+
+			if (params.status) {
+				whereConditions.push({
+					field: 'status',
+					value: params.status,
+				});
+			}
+
+			if (params.purposeIds && params.purposeIds.length > 0) {
+				whereConditions.push({
+					field: 'purposeIds',
+					operator: 'contains',
+					value: params.purposeIds,
+				});
+			}
+
+			const consents = await adapter.findMany({
+				model: 'consent',
+				where: whereConditions,
+				sortBy: {
+					field: 'givenAt',
+					direction: 'desc',
+				},
+			});
+
+			return consents.map((consent) =>
+				validateEntityOutput('consent', consent, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds a consent by its unique ID.
+		 * Returns the consent with processed output fields according to the schema configuration.
+		 *
+		 * @param consentId - The unique identifier of the consent
+		 * @returns The consent object if found, null otherwise
+		 */
+		findConsentById: async (consentId: string) => {
+			const consent = await adapter.findOne({
+				model: 'consent',
+				where: [
+					{
+						field: 'id',
+						value: consentId,
+					},
+				],
+			});
+			return consent
+				? validateEntityOutput('consent', consent, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Finds all consents for a specific subject.
+		 * Returns consents with processed output fields according to the schema configuration.
+		 *
+		 * @param subjectId - The subject ID to find consents for
+		 * @returns Array of consents associated with the subject
+		 */
+		findConsentsBySubjectId: async (subjectId: string) => {
+			const consents = await adapter.findMany({
+				model: 'consent',
+				where: [
+					{
+						field: 'subjectId',
+						value: subjectId,
+					},
+				],
+				sortBy: {
+					field: 'givenAt',
+					direction: 'desc',
+				},
+			});
+			return consents.map((consent) =>
+				validateEntityOutput('consent', consent, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds all consents for a specific domain.
+		 * Returns consents with processed output fields according to the schema configuration.
+		 *
+		 * @param domainId - The domain ID to find consents for
+		 * @returns Array of consents associated with the domain
+		 */
+		findConsentsByDomainId: async (domainId: string) => {
+			const consents = await adapter.findMany({
+				model: 'consent',
+				where: [
+					{
+						field: 'domainId',
+						value: domainId,
+					},
+				],
+				sortBy: {
+					field: 'givenAt',
+					direction: 'desc',
+				},
+			});
+			return consents.map((consent) =>
+				validateEntityOutput('consent', consent, ctx.options)
+			);
+		},
+
+		/**
+		 * Updates an existing consent record by ID.
+		 * Applies any configured hooks during the update process and
+		 * processes the output according to schema configuration.
+		 *
+		 * @param consentId - The unique identifier of the consent to update
+		 * @param data - The fields to update on the consent record
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The updated consent if successful, null if not found or hooks prevented update
+		 */
+		updateConsent: async (
+			consentId: string,
+			data: Partial<Consent>,
+			context?: GenericEndpointContext
+		) => {
+			const consent = await updateWithHooks<Consent>({
+				data: {
+					...data,
+				},
+				where: [
+					{
+						field: 'id',
+						value: consentId,
+					},
+				],
+				model: 'consent',
+				context,
+			});
+			return consent
+				? validateEntityOutput('consent', consent, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Updates consent status to withdrawn.
+		 * Also records the withdrawal reason if provided.
+		 *
+		 * @param consentId - The unique identifier of the consent to update
+		 * @param withdrawalReason - Optional reason for consentWithdrawal
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The updated consent with withdrawn status
+		 */
+		updateWithdrawal: async (
+			consentId: string,
+			withdrawalReason?: string,
+			context?: GenericEndpointContext
+		) => {
+			const updateData: Partial<Consent> = {
+				status: 'withdrawn',
+			};
+
+			if (withdrawalReason) {
+				updateData.withdrawalReason = withdrawalReason;
+			}
+
+			const consent = await updateWithHooks<Consent>({
+				data: updateData,
+				where: [
+					{
+						field: 'id',
+						value: consentId,
+					},
+				],
+				model: 'consent',
+				context,
+			});
+
+			return consent
+				? validateEntityOutput('consent', consent, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Revokes a consent and records the revocation details.
+		 *
+		 * @param params - Revocation parameters including reason and actor
+		 * @returns The updated consent with revocation details
+		 */
+		revokeConsent: async ({
+			consentId,
+			reason,
+			actor,
+			metadata,
+			context,
+		}: RevokeConsentParams) => {
+			const consent = await registry.findConsentById(consentId);
+			if (!consent) {
+				throw new Error('Consent not found');
+			}
+
+			const updateData: Partial<Consent> = {
+				status: 'withdrawn',
+				withdrawalReason: reason,
+				metadata: {
+					...(consent.metadata as Record<string, unknown>),
+					consentWithdrawal: {
+						actor,
+						timestamp: new Date().toISOString(),
+						...metadata,
+					},
+				},
+			};
+
+			return registry.updateConsent(consentId, updateData, context);
+		},
+
+		/**
+		 * Gets all records associated with a consent.
+		 *
+		 * @param consentId - The ID of the consent
+		 * @returns Array of records associated with the consent
+		 */
+		getRecords: async (consentId: string) => {
+			const records = await adapter.findMany({
+				model: 'consentRecord',
+				where: [
+					{
+						field: 'consentId',
+						value: consentId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+			});
+
+			return records.map((record) =>
+				validateEntityOutput('consentRecord', record, ctx.options)
+			);
+		},
+
+		/**
+		 * Gets all consentWithdrawals associated with a consent.
+		 *
+		 * @param consentId - The ID of the consent
+		 * @returns Array of consentWithdrawals associated with the consent
+		 */
+		getWithdrawals: async (consentId: string) => {
+			const consentWithdrawals = await adapter.findMany({
+				model: 'consentWithdrawal',
+				where: [
+					{
+						field: 'consentId',
+						value: consentId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+			});
+
+			return consentWithdrawals.map((consentWithdrawal) =>
+				validateEntityOutput(
+					'consentWithdrawal',
+					consentWithdrawal,
+					ctx.options
+				)
+			);
+		},
+	};
+
+	return registry;
+}

package/src/db/schema/consent/schema.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for validating consent entities.
+ *
+ * This defines the structure and validation rules for consent records:
+ * - Required fields: subjectId, domainId, purposeIds
+ * - Default value of 'active' for status
+ * - Default current date/time for creation timestamp
+ * - Includes audit trail of all changes
+ *
+ * @example
+ * ```typescript
+ * const consentData = {
+ *   id: 'cns_w5qufx2a66m7xkn3ty',
+ *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
+ *   domainId: 'dom_x1pftyoufsm7xgo1kv',
+ *   purposeIds: ['pur_e8zyhgozr3im7xj59it'],
+ *   status: 'active',
+ *   givenAt: new Date(),
+ *   isActive: true,
+ *   history: [
+ *     {
+ *       actionType: 'given',
+ *       timestamp: new Date(),
+ *       details: { ip: '192.168.1.1' }
+ *     }
+ *   ]
+ * };
+ * ```
+ */
+export const consentHistorySchema = z.object({
+	actionType: z.enum(['given', 'withdrawn', 'updated', 'expired']),
+	timestamp: z.date(),
+	details: z.record(z.unknown()).optional(),
+	previousState: z.record(z.unknown()).optional(),
+	newState: z.record(z.unknown()).optional(),
+});
+
+export const consentSchema = z.object({
+	id: z.string(),
+	subjectId: z.string(),
+	domainId: z.string(),
+	purposeIds: z.array(z.string()),
+	metadata: z.record(z.unknown()).optional(),
+	policyId: z.string().optional(),
+	ipAddress: z.string().optional(),
+	userAgent: z.string().optional(),
+	status: z.enum(['active', 'withdrawn', 'expired']).default('active'),
+	withdrawalReason: z.string().optional(),
+	givenAt: z.date().default(() => new Date()),
+	validUntil: z.date().optional(),
+	isActive: z.boolean().default(true),
+	history: z.array(consentHistorySchema).default([]),
+});
+
+/**
+ * Type definition for Consent
+ *
+ * This type represents the structure of a consent record
+ * as defined by the consentSchema. It includes all fields
+ * that are part of the consent entity and its history.
+ */
+export type Consent = z.infer<typeof consentSchema>;
+export type ConsentHistory = z.infer<typeof consentHistorySchema>;