feat(kyc): implement KYC document submission and verification status …

[Tekprecious]

…endpoints (#475)

Description

Implements KYC document submission, verification status checking, admin review transitions, and invoice submission gating as requested in Issue #475.

Scope & Key Implementation:

• POST /kyc/submit:
  • Accepts seller details (legalName, registrationNumber, jurisdiction, etc.) and IPFS document CIDs (documentCids, documentType, documentNumber, ipfsDocumentUrl).
  • Validates payload structure and stores document CIDs within verification records.
  • Transitions KYC status to PENDING.
  • Rejects duplicate submissions with HTTP 409 Conflict if a verification is already PENDING or APPROVED.
• GET /kyc/status:
  • Returns current verification status (PENDING, APPROVED, REJECTED) for the authenticated seller/wallet.
  • Returns rejectionReason when status is REJECTED, and null otherwise.
• Admin PATCH /kyc/:id/review:
  • Allows administrators (authenticated via x-admin-key header or admin JWT) to transition verification status to APPROVED or REJECTED.
  • Requires rejection reason when rejecting verification.
  • Emits structured audit logging via logKYCStatusChange and dispatches notifications (KYC_APPROVED / KYC_REJECTED).
  • Mounted on /kyc/:id/review and /admin/kyc/:id/review (both with and without /api/v1 prefix).
• Re-submission on REJECTED Status:
  • Allowed when the user's KYC status is REJECTED.
  • Archives the previous verification record in KycHistoryRepository.
  • Resets status to PENDING, updates document CIDs, and clears the previous rejection reason.
• Invoice Submission KYC Gating:
  • Invoice submission (POST /invoices and POST /api/v1/invoices) verifies seller KYC status.
  • Blocks wallets without approved KYC (user.kycStatus === 'approved' or user.isKycVerified === true) with HTTP 403 (KYC_APPROVAL_REQUIRED), unless skipVerification is enabled in configuration.
• Backward Compatibility:
  • All endpoints are available directly at /kyc/* as well as under /api/v1/kyc/*.
  • Legacy webhook and submission routes remain functional.

Closes #475

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update
• 🎨 UI/UX improvement
• ♻️ Code refactoring
• ✅ Test addition or update
• 🔧 Configuration change

Checklist

• All GitHub Actions workflows are green on this PR (required for merge)
• Commit messages follow Conventional Commits (feat:, fix:, chore:, etc.) — enforced by CI
• No secrets, API keys, .env, or credentials committed (see CONTRIBUTING.md)
• My code follows the code style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Testing

How to Test

1. Run the new KYC workflow unit test suite:

   npm test tests/unit/kyc-workflow.test.ts

[drips-wave]

@Tekprecious Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits