@axova/shared 1.0.0

package/src/schemas/compliance/kyc-schema.ts

@@ -0,0 +1,649 @@
+import { createId } from "@paralleldrive/cuid2";
+import { relations } from "drizzle-orm";
+import {
+	boolean,
+	decimal,
+	index,
+	integer,
+	jsonb,
+	pgTable,
+	text,
+	timestamp,
+	unique,
+	varchar,
+} from "drizzle-orm/pg-core";
+import { storeCompliance } from "./compliance-schema";
+
+// Store KYC Records - Main table for KYC verification per store
+export const storeKyc = pgTable(
+	"store_kyc",
+	{
+		id: text("id")
+			.primaryKey()
+			.$defaultFn(() => createId()),
+		storeId: text("store_id").notNull(),
+		userId: text("user_id").notNull(),
+
+		// Didit Integration
+		diditSessionId: text("didit_session_id"),
+		diditWorkflowId: text("didit_workflow_id"),
+		diditVerificationUrl: text("didit_verification_url"),
+
+		// KYC Status
+		kycStatus: varchar("kyc_status", { length: 30 })
+			.notNull()
+			.default("NOT_STARTED")
+			.$type<
+				| "NOT_STARTED"
+				| "IN_PROGRESS"
+				| "PENDING_REVIEW"
+				| "APPROVED"
+				| "REJECTED"
+				| "REQUIRES_RESUBMISSION"
+				| "EXPIRED"
+				| "CANCELLED"
+			>(),
+
+		kycLevel: varchar("kyc_level", { length: 20 })
+			.$type<"BASIC" | "INTERMEDIATE" | "ADVANCED" | "ENHANCED">()
+			.default("BASIC"),
+
+		verificationTier: varchar("verification_tier", { length: 30 })
+			.$type<
+				| "TIER_0_UNVERIFIED"
+				| "TIER_1_EMAIL_PHONE"
+				| "TIER_2_BASIC_ID"
+				| "TIER_3_ENHANCED_ID"
+				| "TIER_4_FULL_KYC"
+			>()
+			.default("TIER_0_UNVERIFIED"),
+
+		// Verification Types Completed
+		verificationsCompleted: jsonb("verifications_completed")
+			.$type<{
+				idVerification?: boolean;
+				faceMatch?: boolean;
+				ageVerification?: boolean;
+				proofOfAddress?: boolean;
+				amlScreening?: boolean;
+				databaseValidation?: boolean;
+				phoneVerification?: boolean;
+				emailVerification?: boolean;
+				passiveLiveness?: boolean;
+			}>()
+			.default({}),
+
+		// Verification Scores
+		verificationScore: decimal("verification_score", {
+			precision: 5,
+			scale: 2,
+		}), // 0-100
+		confidenceScore: decimal("confidence_score", { precision: 5, scale: 2 }), // 0-100
+		riskScore: decimal("risk_score", { precision: 5, scale: 2 }), // 0-100
+
+		// Risk Assessment
+		riskLevel: varchar("risk_level", { length: 20 })
+			.$type<"VERY_LOW" | "LOW" | "MEDIUM" | "HIGH" | "VERY_HIGH" | "CRITICAL">()
+			.default("MEDIUM"),
+
+		riskFlags: jsonb("risk_flags")
+			.$type<{
+				sanctionsList?: boolean;
+				pepList?: boolean;
+				adverseMedia?: boolean;
+				fraudIndicators?: boolean;
+				documentIssues?: boolean;
+				faceMismatch?: boolean;
+				livenessCheckFailed?: boolean;
+				ageRestriction?: boolean;
+				jurisdictionRestriction?: boolean;
+			}>()
+			.default({}),
+
+		// Personal Information (from Didit)
+		personalInfo: jsonb("personal_info")
+			.$type<{
+				firstName?: string;
+				lastName?: string;
+				middleName?: string;
+				dateOfBirth?: string;
+				nationality?: string;
+				countryOfResidence?: string;
+				gender?: string;
+			}>()
+			.default({}),
+
+		// Document Information
+		documentInfo: jsonb("document_info")
+			.$type<{
+				documentType?: string; // PASSPORT, ID_CARD, DRIVER_LICENSE, etc.
+				documentNumber?: string;
+				issuingCountry?: string;
+				issueDate?: string;
+				expiryDate?: string;
+				documentImages?: string[]; // URLs to encrypted document images
+			}>()
+			.default({}),
+
+		// Address Information
+		addressInfo: jsonb("address_info")
+			.$type<{
+				fullAddress?: string;
+				street?: string;
+				city?: string;
+				state?: string;
+				postalCode?: string;
+				country?: string;
+				verificationDate?: string;
+				proofOfAddressType?: string; // UTILITY_BILL, BANK_STATEMENT, etc.
+			}>()
+			.default({}),
+
+		// Biometric Data (hashed/encrypted references)
+		biometricData: jsonb("biometric_data")
+			.$type<{
+				faceImageUrl?: string;
+				faceMatchScore?: number;
+				livenessScore?: number;
+				livenessCheckPassed?: boolean;
+				biometricHash?: string; // For deduplication
+			}>()
+			.default({}),
+
+		// AML/Sanctions Screening Results
+		amlResults: jsonb("aml_results")
+			.$type<{
+				screeningDate?: string;
+				sanctionsMatch?: boolean;
+				pepMatch?: boolean;
+				adverseMediaMatch?: boolean;
+				matchDetails?: Array<{
+					listName: string;
+					matchScore: number;
+					matchType: string;
+					details: string;
+				}>;
+				clearanceLevel?: "CLEAR" | "REVIEW_REQUIRED" | "REJECTED";
+			}>()
+			.default({}),
+
+		// Phone & Email Verification
+		contactVerification: jsonb("contact_verification")
+			.$type<{
+				phoneNumber?: string;
+				phoneVerified?: boolean;
+				phoneVerifiedAt?: string;
+				email?: string;
+				emailVerified?: boolean;
+				emailVerifiedAt?: string;
+			}>()
+			.default({}),
+
+		// Submission & Review Tracking
+		submittedAt: timestamp("submitted_at", { withTimezone: true }),
+		submittedBy: text("submitted_by"),
+		reviewedAt: timestamp("reviewed_at", { withTimezone: true }),
+		reviewedBy: text("reviewed_by"),
+		reviewerNotes: text("reviewer_notes"),
+
+		approvedAt: timestamp("approved_at", { withTimezone: true }),
+		approvedBy: text("approved_by"),
+		rejectedAt: timestamp("rejected_at", { withTimezone: true }),
+		rejectedBy: text("rejected_by"),
+		rejectionReason: text("rejection_reason"),
+
+		// Expiry & Renewal
+		expiryDate: timestamp("expiry_date", { withTimezone: true }),
+		requiresRenewal: boolean("requires_renewal").notNull().default(false),
+		lastRenewalDate: timestamp("last_renewal_date", { withTimezone: true }),
+		nextRenewalDate: timestamp("next_renewal_date", { withTimezone: true }),
+
+		// Compliance & Regulations
+		complianceChecks: jsonb("compliance_checks")
+			.$type<{
+				gdprCompliant?: boolean;
+				ccpaCompliant?: boolean;
+				kycCompliant?: boolean;
+				amlCompliant?: boolean;
+				ofacCompliant?: boolean;
+				jurisdictionCompliant?: boolean;
+				complianceNotes?: string;
+			}>()
+			.default({}),
+
+		regulatoryStatus: varchar("regulatory_status", { length: 30 })
+			.$type<"COMPLIANT" | "PENDING" | "NON_COMPLIANT" | "UNDER_REVIEW">()
+			.default("PENDING"),
+
+		// Verification Attempts & History
+		attemptCount: integer("attempt_count").notNull().default(0),
+		lastAttemptAt: timestamp("last_attempt_at", { withTimezone: true }),
+		maxAttemptsReached: boolean("max_attempts_reached")
+			.notNull()
+			.default(false),
+
+		// Metadata & Configuration
+		verificationMetadata: jsonb("verification_metadata")
+			.$type<{
+				ipAddress?: string;
+				userAgent?: string;
+				deviceId?: string;
+				location?: {
+					country?: string;
+					city?: string;
+					coordinates?: [number, number];
+				};
+				sessionDuration?: number;
+				verificationMethod?: string;
+				additionalInfo?: Record<string, unknown>;
+			}>()
+			.default({}),
+
+		// Internal Notes & Flags
+		internalNotes: text("internal_notes"),
+		flags: jsonb("flags")
+			.$type<{
+				manualReviewRequired?: boolean;
+				escalated?: boolean;
+				fraudSuspected?: boolean;
+				documentExpired?: boolean;
+				duplicateDetected?: boolean;
+				highRisk?: boolean;
+				vipCustomer?: boolean;
+			}>()
+			.default({}),
+
+		// Store-specific KYC Requirements
+		storeKycRequirements: jsonb("store_kyc_requirements")
+			.$type<{
+				minimumTier?: string;
+				requiredVerifications?: string[];
+				additionalDocuments?: string[];
+				customRequirements?: Record<string, unknown>;
+			}>()
+			.default({}),
+
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		updatedAt: timestamp("updated_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+	},
+	(table) => ({
+		storeIdIndex: index("idx_kyc_store_id").on(table.storeId),
+		userIdIndex: index("idx_kyc_user_id").on(table.userId),
+		statusIndex: index("idx_kyc_status").on(table.kycStatus),
+		diditSessionIndex: index("idx_kyc_didit_session").on(table.diditSessionId),
+		tierIndex: index("idx_kyc_tier").on(table.verificationTier),
+		riskLevelIndex: index("idx_kyc_risk_level").on(table.riskLevel),
+		expiryIndex: index("idx_kyc_expiry").on(
+			table.expiryDate,
+			table.requiresRenewal,
+		),
+		storeUserUnique: unique("unique_store_user_kyc").on(
+			table.storeId,
+			table.userId,
+		),
+	}),
+);
+
+// KYC Verification History - Track all verification attempts and changes
+export const kycVerificationHistory = pgTable(
+	"kyc_verification_history",
+	{
+		id: text("id")
+			.primaryKey()
+			.$defaultFn(() => createId()),
+		kycId: text("kyc_id")
+			.notNull()
+			.references(() => storeKyc.id, { onDelete: "cascade" }),
+		storeId: text("store_id").notNull(),
+		userId: text("user_id").notNull(),
+
+		// Event Details
+		eventType: varchar("event_type", { length: 50 })
+			.notNull()
+			.$type<
+				| "VERIFICATION_STARTED"
+				| "VERIFICATION_SUBMITTED"
+				| "STATUS_CHANGED"
+				| "DOCUMENT_UPLOADED"
+				| "REVIEW_COMPLETED"
+				| "APPROVED"
+				| "REJECTED"
+				| "RESUBMISSION_REQUESTED"
+				| "EXPIRED"
+				| "RENEWED"
+				| "CANCELLED"
+			>(),
+
+		previousStatus: varchar("previous_status", { length: 30 }),
+		newStatus: varchar("new_status", { length: 30 }),
+
+		// Change Details
+		changeDetails: jsonb("change_details").$type<{
+			field?: string;
+			oldValue?: unknown;
+			newValue?: unknown;
+			reason?: string;
+			performedBy?: string;
+			metadata?: Record<string, unknown>;
+		}>(),
+
+		diditEventData: jsonb("didit_event_data").$type<Record<string, unknown>>(),
+
+		performedBy: text("performed_by"),
+		performedByType: varchar("performed_by_type", { length: 20 }).$type<
+			"SYSTEM" | "USER" | "ADMIN" | "DIDIT_WEBHOOK" | "AUTOMATED_PROCESS"
+		>(),
+
+		notes: text("notes"),
+
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+	},
+	(table) => ({
+		kycIdIndex: index("idx_kyc_history_kyc_id").on(table.kycId),
+		storeIdIndex: index("idx_kyc_history_store_id").on(table.storeId),
+		eventTypeIndex: index("idx_kyc_history_event_type").on(table.eventType),
+		createdAtIndex: index("idx_kyc_history_created_at").on(table.createdAt),
+	}),
+);
+
+// KYC Documents - Store references to verification documents
+export const kycDocuments = pgTable(
+	"kyc_documents",
+	{
+		id: text("id")
+			.primaryKey()
+			.$defaultFn(() => createId()),
+		kycId: text("kyc_id")
+			.notNull()
+			.references(() => storeKyc.id, { onDelete: "cascade" }),
+		storeId: text("store_id").notNull(),
+		userId: text("user_id").notNull(),
+
+		// Document Classification
+		documentType: varchar("document_type", { length: 50 })
+			.notNull()
+			.$type<
+				| "PASSPORT"
+				| "ID_CARD"
+				| "DRIVER_LICENSE"
+				| "RESIDENCE_PERMIT"
+				| "PROOF_OF_ADDRESS"
+				| "BANK_STATEMENT"
+				| "UTILITY_BILL"
+				| "SELFIE"
+				| "FACE_PHOTO"
+				| "OTHER"
+			>(),
+
+		documentCategory: varchar("document_category", { length: 30 }).$type<
+			"IDENTITY" | "ADDRESS" | "BIOMETRIC" | "FINANCIAL" | "ADDITIONAL"
+		>(),
+
+		// Document Details
+		fileName: varchar("file_name", { length: 255 }),
+		fileUrl: text("file_url").notNull(),
+		encryptedFileUrl: text("encrypted_file_url"),
+		fileSize: integer("file_size"),
+		mimeType: varchar("mime_type", { length: 50 }),
+
+		// Document Verification
+		verificationStatus: varchar("verification_status", { length: 30 })
+			.notNull()
+			.default("PENDING")
+			.$type<
+				| "PENDING"
+				| "VERIFIED"
+				| "REJECTED"
+				| "EXPIRED"
+				| "REQUIRES_RESUBMISSION"
+			>(),
+
+		verifiedBy: text("verified_by"),
+		verifiedAt: timestamp("verified_at", { withTimezone: true }),
+		verificationNotes: text("verification_notes"),
+
+		// Document Metadata
+		documentMetadata: jsonb("document_metadata").$type<{
+			documentNumber?: string;
+			issueDate?: string;
+			expiryDate?: string;
+			issuingAuthority?: string;
+			issuingCountry?: string;
+			extractedData?: Record<string, unknown>;
+			ocrConfidence?: number;
+		}>(),
+
+		// Security & Compliance
+		isEncrypted: boolean("is_encrypted").notNull().default(true),
+		encryptionMethod: varchar("encryption_method", { length: 50 }),
+		accessLog: jsonb("access_log")
+			.$type<
+				Array<{
+					accessedBy: string;
+					accessedAt: string;
+					purpose: string;
+					ipAddress?: string;
+				}>
+			>()
+			.default([]),
+
+		// Retention & Deletion
+		retentionPeriod: integer("retention_period"), // days
+		scheduledDeletionDate: timestamp("scheduled_deletion_date", {
+			withTimezone: true,
+		}),
+		deletedAt: timestamp("deleted_at", { withTimezone: true }),
+		deletedBy: text("deleted_by"),
+
+		uploadedAt: timestamp("uploaded_at", { withTimezone: true }).defaultNow(),
+		uploadedBy: text("uploaded_by"),
+
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		updatedAt: timestamp("updated_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+	},
+	(table) => ({
+		kycIdIndex: index("idx_kyc_docs_kyc_id").on(table.kycId),
+		storeIdIndex: index("idx_kyc_docs_store_id").on(table.storeId),
+		documentTypeIndex: index("idx_kyc_docs_type").on(table.documentType),
+		verificationStatusIndex: index("idx_kyc_docs_verification_status").on(
+			table.verificationStatus,
+		),
+		scheduledDeletionIndex: index("idx_kyc_docs_scheduled_deletion").on(
+			table.scheduledDeletionDate,
+		),
+	}),
+);
+
+// KYC Analytics - Track KYC metrics and analytics per store
+export const kycAnalytics = pgTable(
+	"kyc_analytics",
+	{
+		id: text("id")
+			.primaryKey()
+			.$defaultFn(() => createId()),
+		storeId: text("store_id").notNull().unique(),
+
+		// Verification Statistics
+		totalVerifications: integer("total_verifications").notNull().default(0),
+		approvedVerifications: integer("approved_verifications")
+			.notNull()
+			.default(0),
+		rejectedVerifications: integer("rejected_verifications")
+			.notNull()
+			.default(0),
+		pendingVerifications: integer("pending_verifications").notNull().default(0),
+
+		// Success Rates
+		approvalRate: decimal("approval_rate", { precision: 5, scale: 2 }), // percentage
+		rejectionRate: decimal("rejection_rate", { precision: 5, scale: 2 }),
+		averageVerificationTime: integer("average_verification_time"), // minutes
+
+		// Risk Distribution
+		lowRiskCount: integer("low_risk_count").notNull().default(0),
+		mediumRiskCount: integer("medium_risk_count").notNull().default(0),
+		highRiskCount: integer("high_risk_count").notNull().default(0),
+		criticalRiskCount: integer("critical_risk_count").notNull().default(0),
+
+		// Tier Distribution
+		tier0Count: integer("tier0_count").notNull().default(0),
+		tier1Count: integer("tier1_count").notNull().default(0),
+		tier2Count: integer("tier2_count").notNull().default(0),
+		tier3Count: integer("tier3_count").notNull().default(0),
+		tier4Count: integer("tier4_count").notNull().default(0),
+
+		// Document Statistics
+		totalDocumentsUploaded: integer("total_documents_uploaded")
+			.notNull()
+			.default(0),
+		averageDocumentsPerVerification: decimal(
+			"average_documents_per_verification",
+			{ precision: 5, scale: 2 },
+		),
+
+		// Compliance Statistics
+		amlScreeningsCompleted: integer("aml_screenings_completed")
+			.notNull()
+			.default(0),
+		sanctionsMatchesFound: integer("sanctions_matches_found")
+			.notNull()
+			.default(0),
+		pepMatchesFound: integer("pep_matches_found").notNull().default(0),
+
+		// Fraud Indicators
+		fraudSuspectedCount: integer("fraud_suspected_count").notNull().default(0),
+		duplicateDetectedCount: integer("duplicate_detected_count")
+			.notNull()
+			.default(0),
+
+		// Performance Metrics
+		averageConfidenceScore: decimal("average_confidence_score", {
+			precision: 5,
+			scale: 2,
+		}),
+		averageRiskScore: decimal("average_risk_score", { precision: 5, scale: 2 }),
+
+		// Time-based Metrics
+		verificationsThisMonth: integer("verifications_this_month")
+			.notNull()
+			.default(0),
+		verificationsLastMonth: integer("verifications_last_month")
+			.notNull()
+			.default(0),
+
+		lastCalculatedAt: timestamp("last_calculated_at", { withTimezone: true }),
+
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		updatedAt: timestamp("updated_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+	},
+	(table) => ({
+		storeIdIndex: index("idx_kyc_analytics_store_id").on(table.storeId),
+	}),
+);
+
+// KYC Webhooks Log - Track all Didit webhook events
+export const kycWebhooksLog = pgTable(
+	"kyc_webhooks_log",
+	{
+		id: text("id")
+			.primaryKey()
+			.$defaultFn(() => createId()),
+		diditSessionId: text("didit_session_id"),
+		storeId: text("store_id"),
+		kycId: text("kyc_id").references(() => storeKyc.id),
+
+		// Webhook Event Details
+		eventType: varchar("event_type", { length: 50 })
+			.notNull()
+			.$type<"status.updated" | "data.updated" | "session.completed">(),
+
+		webhookPayload: jsonb("webhook_payload")
+			.notNull()
+			.$type<Record<string, unknown>>(),
+
+		// Processing Status
+		processingStatus: varchar("processing_status", { length: 30 })
+			.notNull()
+			.default("PENDING")
+			.$type<"PENDING" | "PROCESSING" | "PROCESSED" | "FAILED" | "RETRYING">(),
+
+		processedAt: timestamp("processed_at", { withTimezone: true }),
+		failureReason: text("failure_reason"),
+		retryCount: integer("retry_count").notNull().default(0),
+		maxRetriesReached: boolean("max_retries_reached").notNull().default(false),
+
+		// Request Details
+		requestHeaders: jsonb("request_headers").$type<Record<string, string>>(),
+		requestIp: varchar("request_ip", { length: 45 }),
+		signatureValid: boolean("signature_valid"),
+
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+	},
+	(table) => ({
+		sessionIdIndex: index("idx_kyc_webhooks_session_id").on(
+			table.diditSessionId,
+		),
+		kycIdIndex: index("idx_kyc_webhooks_kyc_id").on(table.kycId),
+		processingStatusIndex: index("idx_kyc_webhooks_processing_status").on(
+			table.processingStatus,
+		),
+		createdAtIndex: index("idx_kyc_webhooks_created_at").on(table.createdAt),
+	}),
+);
+
+// Relations
+export const storeKycRelations = relations(storeKyc, ({ one, many }) => ({
+	compliance: one(storeCompliance, {
+		fields: [storeKyc.storeId],
+		references: [storeCompliance.storeId],
+	}),
+	history: many(kycVerificationHistory),
+	documents: many(kycDocuments),
+	webhooks: many(kycWebhooksLog),
+}));
+
+export const kycVerificationHistoryRelations = relations(
+	kycVerificationHistory,
+	({ one }) => ({
+		kyc: one(storeKyc, {
+			fields: [kycVerificationHistory.kycId],
+			references: [storeKyc.id],
+		}),
+	}),
+);
+
+export const kycDocumentsRelations = relations(kycDocuments, ({ one }) => ({
+	kyc: one(storeKyc, {
+		fields: [kycDocuments.kycId],
+		references: [storeKyc.id],
+	}),
+}));
+
+export const kycWebhooksLogRelations = relations(kycWebhooksLog, ({ one }) => ({
+	kyc: one(storeKyc, {
+		fields: [kycWebhooksLog.kycId],
+		references: [storeKyc.id],
+	}),
+}));
+
+export const kycAnalyticsRelations = relations(kycAnalytics, ({ one }) => ({
+	compliance: one(storeCompliance, {
+		fields: [kycAnalytics.storeId],
+		references: [storeCompliance.storeId],
+	}),
+}));