feat: integrate KYC verification provider with identity provider abstraction

[Abdul-dev-creator]

Overview

This PR integrates the first KYC (Know Your Customer) verification provider into the new Identity Provider abstraction. It introduces a provider-swappable IIdentityProvider interface with a mock provider implementation, enabling individual identity verification while exposing a standardized API to the rest of the platform.

Related Issue

Closes #72

Changes

⚙️ Identity Provider Abstraction

• [ADD] src/kyc/interfaces/identity-provider.interface.ts

• Added the IIdentityProvider interface defining createSession, getStatus, and processWebhook.

• Supports provider-swappable architecture — replace the provider implementation without changing business logic.

• [ADD] src/kyc/interfaces/kyc.types.ts

• Defined the KycStatus enum: pending, in_review, �erified,
  ejected, �xpired.

• Added shared interfaces for KYC sessions and database rows.

🤖 Mock KYC Provider

• [ADD] src/kyc/providers/mock-kyc.provider.ts
• Implemented the first KYC provider backed by an in-memory store.
• Supports full state machine transitions via webhook events.
• Handles verification failures and expiration.

🌐 KYC API Surface

• [ADD] src/kyc/kyc.controller.ts

• POST /kyc/session — Create a new KYC verification session (authenticated).

• GET /kyc/status/:userId — Retrieve verification status for a user.

• POST /kyc/webhook — Receive verification results from the provider.

• [ADD] src/kyc/kyc.service.ts

• Orchestrates provider calls and persists verification metadata to Supabase.

• Syncs provider-side status with the local database on status checks.

🗄️ Database

• [ADD] scripts/002_create_kyc_verifications.sql
• Creates kyc_verifications table with columns: provider, provider_verification_id, status, metadata, verified_at.
• Includes RLS policies and indexes.

🔧 Module Registration

• [ADD] src/kyc/kyc.module.ts — NestJS module wired with Supabase and Auth dependencies.
• [MOD] src/app.module.ts — Registered KycModule.
• [MOD] .env.example — Added KYC_PROVIDER environment variable placeholder.

Verification

• npm run lint ✅ (0 errors, pre-existing warnings only)
• npm run build ✅ passed
• npm test ✅ 48/48 tests passed

[vercel]

@Abdul-dev-creator is attempting to deploy a commit to the ManuelJG's projects Team on Vercel.

A member of the Team first needs to authorize it.

[Kalchaqui]

Review — changes requested (do not merge yet)

Thanks @Abdul-dev-creator — the sketch (abstraction + Nest module + endpoints) is in the right direction for #72. Several blockers before this can land.

Blockers

1. Migration numbering / collision with main

   • main already has scripts/002_create_kyb_verifications.sql (KYB).
   • This PR adds another 002_create_kyc_verifications.sql.
   • Rename to the next free number (e.g. 003_… / 005_… depending on what else lands — coordinate with Add TW retry queue and wire it into webhooks and escrows #103 retry-queue scripts).

2. Confirm the user FK against the real Thalos schema

   • SQL uses REFERENCES auth.users(id) (same pattern as KYB’s migration).
   • Nest JWT subjects live in public.auth_users. Confirm those IDs actually exist in auth.users in your Supabase project — if not, inserts will fail at runtime. Prefer the FK that matches how identities are stored in staging.

3. Security gaps on public routes

   • GET /kyc/status/:userId has no JWT → anyone can read any user’s KYC status (IDOR).
   • POST /kyc/webhook has no shared-secret / signature check → anyone can forge verified.
   • Gate status reads (caller must be the user or admin). Webhook must verify a provider secret (even for mock: e.g. KYC_WEBHOOK_SECRET header), same idea as Trustless Work webhooks.

4. No tests

   • Add at least unit/integration coverage for: create session, status sync from provider, webhook success/failure, unauthorized status access.

Design / consistency with existing KYB

5. main already has an Identity Provider abstraction under src/kyb/ (IdentityProvider + KYB_PROVIDER token + manual provider).

   • Don’t invent a second parallel IIdentityProvider without explaining how KYC and KYB share (or intentionally diverge). Prefer one shared contract or a clear KYC-specific interface that follows the same DI token pattern.

6. Provider binding is hardcoded

   • KycService constructor always takes MockKycProvider. KYB uses a Symbol token so the provider is swappable via module binding — please match that so a real vendor (Persona/Sumsub/…) is a one-line DI change.

7. sessionUrl incomplete

   • Service destructures sessionUrl from createSession, but MockKycProvider does not return it. Align the interface + mock (or stop advertising sessionUrl until a real provider exists).

What looks good

• Status enum covers pending / in_review / verified / rejected / expired
• Endpoints match the issue shape (POST /kyc/session, GET /kyc/status/:userId)
• Persistence of provider + verification id + status + timestamps
• Mock provider is fine as a first plug-in after the security/FK/DI fixes — call out clearly in the PR that it is not a production vendor

Happy to re-review after migration rename + FK fix + auth on status/webhook + tests.