🌍 Country Support

Supported Countries

Full support: OCR extraction + MRZ parsing + face match + biometric proof + all 6 credentials available.
Partial support: Document number validation + basic OCR; face match and biometric proof may have reduced accuracy.

Countries Planned (Phase 6)

• 🇪🇸 Spain — DNI (XXXXXXXX-X) / NIE (X-XXXXXXX-X)
• 🇮🇳 India — Aadhaar (XXXX XXXX XXXX)
• 🇳🇬 Nigeria — NIN (XXXXXXXXXXX)
• 🇿🇦 South Africa — SA ID (YYMMDD XXXX X XX)
• 🇵🇭 Philippines — PhilSys ID (XXXX-XXXX-XXXX)

Add Your Country — Contributor Guide

Adding a new country requires implementing a Document Adapter in the soulprint-verify package. Here's how:

1. Fork the repository

git clone https://github.com/manuelariasfz/soulprint
cd soulprint
npm install
cd packages/verify && npm install

2. Create the document adapter

// packages/verify/src/adapters/XX.ts  (replace XX with country code)

import { DocumentAdapter, ExtractedIdentity } from "../types";

export const XXAdapter: DocumentAdapter = {
  countryCode: "XX",
  documentName: "Your Country ID Name",

  // Validate format of the document number
  validate(docNumber: string): boolean {
    return /^[A-Z0-9]{8,12}$/.test(docNumber.replace(/[\s\-\.]/g, ""));
  },

  // Extract fields from OCR text
  extract(ocrText: string): Partial<ExtractedIdentity> {
    const docMatch = ocrText.match(/YOUR_REGEX_HERE/);
    return {
      documentNumber: docMatch?.[1] ?? null,
      fullName: extractName(ocrText),
      dateOfBirth: extractDOB(ocrText),
      nationality: "XX"
    };
  }
};

3. Register the adapter

// packages/verify/src/adapters/index.ts
import { XXAdapter } from "./XX";

export const ADAPTERS = {
  CO: COAdapter,
  MX: MXAdapter,
  // ... existing
  XX: XXAdapter, // ← add your country
};

4. Add tests

// packages/verify/tests/adapters/XX.test.ts
import { XXAdapter } from "../../src/adapters/XX";

test("validates XX document number", () => {
  expect(XXAdapter.validate("VALID_SAMPLE")).toBe(true);
  expect(XXAdapter.validate("INVALID")).toBe(false);
});

test("extracts fields from OCR", () => {
  const result = XXAdapter.extract("... sample OCR text ...");
  expect(result.documentNumber).toBe("VALID_SAMPLE");
});

5. Open a Pull Request

Open a PR against main with:

• The adapter file (packages/verify/src/adapters/XX.ts)
• Registration in index.ts
• At least 5 test cases (valid formats, edge cases, invalid formats)
• Update to README.md country support table

PR template: PULL_REQUEST_TEMPLATE.md

Document Format Registry

Country code 2-letter codes follow ISO 3166-1 alpha-2. The document number format for each country is used to derive the identity hash — only the normalized number (digits only, no separators) is used in the hash computation.