This module implements a modular identity verification system for VoxPop, allowing verification of users from different countries using country-specific verification methods.

Design

The system is built around the following components:

VerificationProvider Interface: Defines the contract for all country-specific verification providers
Country-Specific Providers:
- USVerificationProvider - Implements US-specific verification using Privado ID
- PlaceholderVerificationProvider - Used for countries without specific implementation
VerificationService: Manages verification process and provider registration
HTTP Handler: Exposes the verification API

API Endpoints

Verify Identity

Endpoint: POST /verify

Request Body:

{
  "country": "US",
  "userData": {
    "privadoProof": "user-privado-proof-12345"
  },
  "selfAttestedEligible": "true"
}

Response:

{
  "status": "Fully Eligible",
  "citizenshipVerified": true,
  "eligibilityVerified": true
}

Status Levels

Unverified: User has not passed any verification
Verified: User's citizenship is verified but not necessarily eligible
Fully Eligible: User is both verified and eligible to participate

Example Usage

US Verification

// Request
{
  "country": "US",
  "userData": {
    "privadoProof": "user-privado-proof-12345"
  },
  "selfAttestedEligible": "true"
}

// Response
{
  "status": "Fully Eligible",
  "citizenshipVerified": true,
  "eligibilityVerified": true
}

Partially Verified US User (Citizenship only)

// Request
{
  "country": "US",
  "userData": {
    "privadoProof": "user-privado-proof-12345"
  },
  "selfAttestedEligible": "false"
}

// Response
{
  "status": "Verified",
  "citizenshipVerified": true,
  "eligibilityVerified": false
}

Other Country Verification

// Request
{
  "country": "CA",
  "userData": {}
}

// Response
{
  "status": "Fully Eligible",
  "citizenshipVerified": true,
  "eligibilityVerified": true
}

Adding New Providers

To add a new country-specific provider:

Create a new type that implements the VerificationProvider interface
Update the GetVerificationProvider function to return your provider for the appropriate country code

Example:

// CanadaVerificationProvider implements verification for Canadian citizens
type CanadaVerificationProvider struct{}

func (p *CanadaVerificationProvider) VerifyCitizenship(userData map[string]string) (bool, error) {
    // Canada-specific verification logic
    return true, nil
}

func (p *CanadaVerificationProvider) VerifyEligibility(userData map[string]string) (bool, error) {
    // Canada-specific eligibility logic
    return true, nil
}

func (p *CanadaVerificationProvider) GetCountry() string {
    return "CA"
}

// Update the factory function
func GetVerificationProvider(country string) VerificationProvider {
    switch country {
    case "US":
        return &USVerificationProvider{}
    case "CA":
        return &CanadaVerificationProvider{}
    default:
        return NewPlaceholderVerificationProvider(country)
    }
}