MVP: KYC Verification Core requirements

[sameh-farouk]

Description:

Implement TFGrid KYC Verifier, a REST API service that integrates with Idenfy to verify users' identities (KYC) before they can access certain functionalities on the TFGrid platform. The service should securely manage the user verification process, store verification results, and expose endpoints for querying a user's verification status. It will act as the source of truth for user verification on TFGrid, enabling other tools to determine what a user can do on the grid.

Related issue:

• https://github.com/threefoldtech/tfgrid-kyc-verifier/issues/2

Functional Requirements:

1. KYC Verifier Core Endpoints:

   • Token Generation Endpoint: Accepts the user ID (typically the user's public key on TFChain, with proof such as a signature) and generates a token for the verification process.
   • Webhook Endpoint: Receives verification data from Idenfy, including both intermediate and final results.
   • Verification Status Query: Allows checking a user's verification status, which can be verified, unverified, rejected, or pending.
   • Data Retrieval: Enables users to access their verification data.

2. Token Management:

   • Prevent users from generating new tokens until the final verification result is received via the webhook or until the existing token has expired, to conserve credit usage.

3. Handling Suspicion:

   • Configure the system to consider a user as verified if their verification status is marked as "suspected," but individual components like the document and face are approved. This should be the default behavior.

4. Spam Prevention:

   • Require users to maintain a minimum TFT balance before starting the KYC process, with the balance requirement being configurable.
   • Limit the number of requests (e.g., token generation) from a single IP address within a specified time frame to prevent spam attempts, temporarily blocking access if the limit is exceeded. Store the related data in a database (not in memory) to support running multiple instances of the service.

5. Handling Document Expiration:

   • By default, users with expired documents should be considered unverified, but this setting should be configurable.

Non-Functional Requirements:

1. Service Reliability:

   • The service must handle potential downtimes and be capable of recovering pending verifications once it is back online.

2. Data Storage:

   • Store all data received through the webhook, even if it is extensive.

3. Scalability:

   • The solution must be stateless and scalable to handle an increasing number of verification requests while optimizing credit usage. It should support 100 TPS per instance for querying verification status, though token generation throughput may be limited by Idenfy's service capacity.

4. Validation:

   • Ensure that incoming webhook notifications are verified to prevent tampering.

5. Security:

   • Endpoints must use TLS encryption
   • Secure webhook endpoints using IP whitelisting to prevent unauthorized access.
   • Prevent users who have successfully completed verification from initiating another verification.
   • Implement rate-limiting for requests from the same client ID to prevent abuse.

Next Steps:

• [X] Finalize the functional and non-functional requirements.
• [X] Address the open questions with the development team to refine the service design.
• [X] Create a development timeline based on the finalized requirements.
• [ ] implement Core functionality

[xmonader]

Will handle the encryption transient only, not at rest.

[sameh-farouk]

Update

a personal testing instance deployed here https://kyc1.gent01.dev.grid.tf/docs

Completed:

Core Endpoints:

• [X] Token Generation Endpoint
• [X] Webhook Endpoint (verification update)
• [X] Verification Status Endpoint
• [X] Data Retrieval
• [X] Health endpoint

Token Management:

• [X] Prevent users from generating new tokens until the final verification result is received via the webhook or until the existing token has expired, to conserve credit usage.

Handling Suspicion:

• [X] Configure the system to consider a user as verified if their verification status is marked as "suspected," but individual components like the document and face are approved. This should be the default behavior.

Spam Prevention:

• [X] Require users to maintain a minimum TFT balance before starting the KYC process, with the balance requirement being configurable.
• [X] Limit the number of token requests from a single IP address
• [X] Limit the number of token requests per ClientID

Data Storage:

• [X] Store all data received through the webhook, even if it is extensive. Validation:
• [X] Ensure that incoming webhook notifications are verified to prevent tampering.

Network Separation:

• [X] iDenfy always receives a unique client ID consisting of {tfchain address}:{network}.

WIP

Core:

• [ ] Webhook Endpoint (Handle Doc Expiration)

Security:

• [ ] Secure webhook endpoints using IP whitelisting to prevent unauthorized access. (We already use a shared signing key but implementing IP whitelisting will provide higher security)

Service Reliability:

• [ ] The service must handle potential downtimes and be capable of recovering pending verifications once it is back online.