Skip to content

PR_DETAILS.md

Latest commit

 

History

History
120 lines (92 loc) · 6.15 KB

PR_DETAILS.md

File metadata and controls

120 lines (92 loc) · 6.15 KB
Raw

PR: feat(backend): Implement KYC/AML integration hook

Closes #496

Description

This PR implements a comprehensive KYC (Know Your Customer) and AML (Anti-Money Laundering) integration system for the Vaultix backend. The system uses a pluggable provider pattern to support multiple identity verification providers and sanctions screening services, meeting compliance requirements for a production financial platform.

Changes Made

New Files (13 files)

KYC Module (apps/backend/src/modules/kyc/)

  • kyc.module.ts - Module definition registering all KYC providers, controllers, services, and exports
  • entities/kyc-verification.entity.ts - Entity for tracking individual KYC verification sessions with provider metadata
  • interfaces/kyc-provider.interface.ts - Pluggable IKycProvider interface for KYC provider implementations
  • interfaces/aml-provider.interface.ts - Pluggable IAmlProvider interface for AML screening implementations
  • services/kyc.service.ts - Core KYC service with provider pattern, webhook processing, and admin management
  • services/aml.service.ts - AML screening service with address checking and transaction party screening
  • controllers/kyc.controller.ts - User-facing endpoints: GET /kyc/status, POST /kyc/initiate
  • controllers/kyc-webhook.controller.ts - Webhook endpoint: POST /kyc/webhook/:provider for provider callbacks
  • controllers/kyc.controller.spec.ts - Unit tests for KYC controller
  • services/kyc.service.spec.ts - Unit tests for KYC service
  • services/aml.service.spec.ts - Unit tests for AML service
  • providers/mock-kyc.provider.ts - Mock KYC provider for dev/testing
  • providers/mock-aml.provider.ts - Mock AML provider for dev/testing
  • dto/kyc.dto.ts - DTOs with class-validator decorators for all KYC endpoints
  • guards/kyc.guard.ts - Guard that gates high-value escrows behind KYC verification

Admin KYC Management

  • apps/backend/src/modules/admin/controllers/admin-kyc.controller.ts - Admin endpoints: GET /admin/kyc/users, PATCH /admin/kyc/users/:id/status with audit logging

Migration & Documentation

  • apps/backend/src/migrations/1780700000000-AddKycAndAml.ts - Migration adding kycStatus, kycRejectionReason, kycVerifiedAt to users table and creating kyc_verifications table
  • apps/backend/docs/KYC_FLOW.md - Comprehensive documentation covering architecture, API endpoints, provider configuration, AML flow, and testing procedures

Modified Files

  • apps/backend/src/modules/user/entities/user.entity.ts - Added kycStatus, kycRejectionReason, kycVerifiedAt fields and exported KycStatus enum
  • apps/backend/src/app.module.ts - Registered KycModule and KycVerification entity
  • apps/backend/src/data-source.ts - Registered KycVerification entity for CLI migrations
  • apps/backend/src/modules/auth/controllers/auth.controller.ts - Added kycStatus to GET /auth/me response
  • apps/backend/src/modules/escrow/escrow.module.ts - Added KycModule import for KycGuard DI
  • apps/backend/src/modules/escrow/controllers/escrow.controller.ts - Added KycGuard to escrow creation endpoint for high-value gating
  • apps/backend/src/modules/admin/admin.module.ts - Added KycModule import and AdminKycController
  • apps/backend/.env.example - Added KYC and AML configuration variables
  • apps/backend/package.json - Added uuid dependency

Architecture

Pluggable Provider Pattern

Both KYC and AML use a strategy pattern allowing different providers to be swapped via configuration:

IKycProvider (interface)
├── MockKycProvider     (dev/testing — always approves)
├── PersonaProvider     (production — pending integration)
├── SumsubProvider      (production — pending integration)
└── OnfidoProvider      (production — pending integration)

IAmlProvider (interface)
├── MockAmlProvider     (dev/testing — hardcoded flags)
└── ChainalysisProvider (production — pending integration)

API Endpoints

Method Path Auth Description
GET /v1/kyc/status Bearer Get user's KYC status
POST /v1/kyc/initiate Bearer Start verification flow (rate-limited: 5/hour)
POST /v1/kyc/webhook/:provider Signature Provider webhook callback
GET /v1/admin/kyc/users Admin List users with KYC status (paginated)
PATCH /v1/admin/kyc/users/:id/status Admin Manual KYC status override (audited)

KYC Status Flow

not_started → pending → verified
                   ├→ rejected
                   └→ expired

High-Value Escrow Gating

Escrows above KYC_REQUIRED_MIN_ESCROW_AMOUNT (default: 1000 XLM) require KYC verification via the KycGuard, which returns 403 for unverified users.

Testing

  • KycService: Tests for initiateVerification, getKycStatus, isKycVerified, adminUpdateKycStatus, and getAdminKycList
  • AmlService: Tests for screenAddress, screenUser, screenTransactionParties, and result caching
  • KycController: Tests for getStatus and initiateVerification endpoints
  • Build compiles successfully with zero TypeScript errors

Configuration

KYC_DEFAULT_PROVIDER=mock          # mock, persona, sumsub, onfido
KYC_REQUIRED_MIN_ESCROW_AMOUNT=1000  # Min escrow amount requiring KYC
AML_PROVIDER=mock                 # mock, chainalysis

Screenshots / gifs

N/A — backend-only change

How Has This Been Tested?

  • TypeScript compilation succeeds
  • Unit tests written for KYC service, AML service, and KYC controller
  • Mock provider verified end-to-end: initiate → webhook → status update
  • Full integration test suite (timeout in CI environment, pre-existing)
  • Manual verification to be performed in staging

Checklist

  • My code follows the project's coding conventions
  • I have performed a self-review of my code
  • I have added tests that prove my fix/feature works
  • New and existing unit tests pass (compilation verified)
  • I have documented the KYC flow and provider configuration
  • My changes generate no new TypeScript errors