@myazahq/kyc-sdk-react-native 2.0.0

package/src/services/deviceMetadata.ts

@@ -0,0 +1,185 @@
+// Device & SDK metadata collected at verify time. Sent as `metadata.device` in
+// the verify payload — the server merges it with server-side facts (real IP,
+// X-SDK-Version header) before persisting. Mirrors the web SDK's
+// `utils/device-metadata.ts` and the Flutter SDK's `device_metadata_service.dart`.
+
+import { OS } from '../utils/platform';
+
+export const SDK_TYPE = 'react-native' as const;
+
+/** Coarse device class, consistent with the Web/Flutter SDKs' `device.type`. */
+export type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
+
+/**
+ * Single source of truth for the SDK version — also used by `services/api.ts`
+ * for the `X-SDK-Version` header. Keep in sync with `package.json`.
+ */
+export const SDK_VERSION = '2.0.0';
+
+export interface ReactNativeDeviceMetadata {
+  sdkType: 'react-native';
+  sdkVersion: string;
+  sdkPlatform: 'ios' | 'android' | 'other';
+  capturedAt: string;
+  device: {
+    /**
+     * Coarse device class the dashboard reads first to classify a verification.
+     * Matches the Web/Flutter SDKs' `device.type`.
+     */
+    type: DeviceType;
+    /** Device maker (from expo-device's `brand`); the dashboard reads `vendor`. */
+    vendor?: string;
+    brand?: string;
+    manufacturer?: string;
+    model?: string;
+    isDevice?: boolean;
+  };
+  os: {
+    name: string;
+    version?: string;
+  };
+  app?: {
+    version?: string;
+    buildVersion?: string;
+    bundleId?: string;
+  };
+  locale?: string;
+  timezone?: string;
+}
+
+/**
+ * Runs a literal `require(...)` loader, returning `undefined` if it throws.
+ * Metro needs the module name to be a STRING LITERAL (no `require(variable)`),
+ * so each caller passes its own literal loader. Under the Node test runner the
+ * native modules aren't resolvable and the loader throws — caught here.
+ */
+function tryRequire<T>(loader: () => T): T | undefined {
+  try {
+    return loader();
+  } catch {
+    return undefined;
+  }
+}
+
+function sdkPlatform(): ReactNativeDeviceMetadata['sdkPlatform'] {
+  if (OS === 'ios') return 'ios';
+  if (OS === 'android') return 'android';
+  return 'other';
+}
+
+/**
+ * Clean OS name. expo-device's `osName` is unreliable on Android — on many devices
+ * (Samsung, Xiaomi, …) it returns the build FINGERPRINT, e.g.
+ * "samsung/e1q:16/BP2A…/S921U1…:user/release-keys", instead of "Android". So derive
+ * the name from the platform (matching the Flutter SDK, which hardcodes "Android");
+ * iOS reports "iOS"/"iPadOS" reliably, so keep expo-device's value there.
+ */
+function resolveOsName(device: ExpoDeviceModule | undefined): string {
+  if (OS === 'android') return 'Android';
+  if (OS === 'ios') return device?.osName ?? 'iOS';
+  return device?.osName ?? OS;
+}
+
+function safeTimezone(): string | undefined {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+    return undefined;
+  }
+}
+
+interface ExpoDeviceModule {
+  brand?: string | null;
+  manufacturer?: string | null;
+  modelName?: string | null;
+  isDevice?: boolean;
+  osName?: string | null;
+  osVersion?: string | null;
+  /**
+   * expo-device's `DeviceType` enum value (numeric):
+   * UNKNOWN=0, PHONE=1, TABLET=2, DESKTOP=3, TV=4. `null` when undeterminable.
+   */
+  deviceType?: number | null;
+}
+
+/**
+ * Maps expo-device's numeric `DeviceType` to our coarse class, mirroring the
+ * Flutter/Web SDKs (PHONE→mobile, TABLET→tablet, DESKTOP→desktop,
+ * TV/UNKNOWN→unknown). When expo-device is unavailable or can't determine a type,
+ * falls back to the platform: ios/android → 'mobile', otherwise 'unknown'.
+ */
+export function inferDeviceType(device: { deviceType?: number | null } | undefined): DeviceType {
+  switch (device?.deviceType) {
+    case 1:
+      return 'mobile'; // PHONE
+    case 2:
+      return 'tablet'; // TABLET
+    case 3:
+      return 'desktop'; // DESKTOP
+    case 0: // UNKNOWN
+    case 4: // TV
+      return 'unknown';
+    default:
+      // expo-device unavailable / deviceType null — use the platform.
+      return OS === 'ios' || OS === 'android' ? 'mobile' : 'unknown';
+  }
+}
+
+interface ExpoApplicationModule {
+  nativeApplicationVersion?: string | null;
+  nativeBuildVersion?: string | null;
+  applicationId?: string | null;
+}
+
+interface ExpoLocalizationModule {
+  getLocales?: () => Array<{ languageTag?: string }>;
+}
+
+/**
+ * Collects best-effort device metadata. Every field degrades gracefully — if
+ * `expo-device` / `expo-application` / `expo-localization` aren't installed (or
+ * under a Node test runner), the relevant fields are simply omitted.
+ */
+export function collectDeviceMetadata(): ReactNativeDeviceMetadata {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const device = tryRequire<ExpoDeviceModule>(() => require('expo-device'));
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const application = tryRequire<ExpoApplicationModule>(() => require('expo-application'));
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const localization = tryRequire<ExpoLocalizationModule>(() => require('expo-localization'));
+
+  const meta: ReactNativeDeviceMetadata = {
+    sdkType: SDK_TYPE,
+    sdkVersion: SDK_VERSION,
+    sdkPlatform: sdkPlatform(),
+    capturedAt: new Date().toISOString(),
+    device: {
+      type: inferDeviceType(device),
+      vendor: device?.brand ?? undefined,
+      brand: device?.brand ?? undefined,
+      manufacturer: device?.manufacturer ?? undefined,
+      model: device?.modelName ?? undefined,
+      isDevice: device?.isDevice,
+    },
+    os: {
+      name: resolveOsName(device),
+      version: device?.osVersion ?? undefined,
+    },
+    timezone: safeTimezone(),
+  };
+
+  if (application) {
+    meta.app = {
+      version: application.nativeApplicationVersion ?? undefined,
+      buildVersion: application.nativeBuildVersion ?? undefined,
+      bundleId: application.applicationId ?? undefined,
+    };
+  }
+
+  const locales = localization?.getLocales?.();
+  if (locales && locales.length > 0) {
+    meta.locale = locales[0]?.languageTag;
+  }
+
+  return meta;
+}

package/src/services/errors.ts

@@ -0,0 +1,92 @@
+// ---------------------------------------------------------------------------
+// mapToKycError — turn a raw network/API error into a typed KYCError
+//
+// Used at every server call site (upload, verify) so the `onError` callback
+// always receives a documented, typed `code`. Mirrors the web SDK's
+// `lib/errors.ts` and the Flutter SDK's `kyc_error_mapper.dart` so all
+// platforms surface the same codes.
+// ---------------------------------------------------------------------------
+
+import { KYCApiError } from './api';
+import { KYCError, type KYCErrorCode } from '../types/verification';
+
+/** Which operation failed — picks the fallback code for non-HTTP failures. */
+export type ErrorContext = 'upload' | 'verify';
+
+/**
+ * Invokes the consumer's `onError` handler defensively — a handler that throws
+ * must never crash the SDK flow. Swallows the throw and warns instead.
+ */
+export function safeReportError(
+  onError: ((error: KYCError) => void) | undefined,
+  error: KYCError,
+): void {
+  if (!onError) return;
+  try {
+    onError(error);
+  } catch (err) {
+    if (typeof console !== 'undefined') {
+      console.warn('[MyazaKYC] onError handler threw and was ignored:', err);
+    }
+  }
+}
+
+function toNum(v: unknown): number | undefined {
+  if (typeof v === 'number') return v;
+  if (typeof v === 'string') {
+    const n = parseFloat(v);
+    return Number.isNaN(n) ? undefined : n;
+  }
+  return undefined;
+}
+
+/**
+ * Maps an unknown error thrown by the API client to a typed {@link KYCError}
+ * with a user-facing message. `context` selects the fallback code when the
+ * failure isn't a specific HTTP status (a bare network failure during an upload
+ * becomes `upload_failed`, during verify becomes `network_error`).
+ */
+export function mapToKycError(err: unknown, context: ErrorContext): KYCError {
+  if (err instanceof KYCApiError) {
+    if (err.statusCode === 401) {
+      return new KYCError('invalid_api_key', 'Invalid API key. Please contact support.');
+    }
+    if (err.statusCode === 402) {
+      const body = err.body ?? {};
+      const required = toNum(body.required);
+      const balance = toNum(body.balance);
+      const currency = typeof body.currency === 'string' ? body.currency : undefined;
+      const message =
+        required !== undefined && balance !== undefined
+          ? `Insufficient credits. Required: $${required.toFixed(2)}, Available: $${balance.toFixed(2)}`
+          : 'Insufficient credits to process this verification.';
+      return new KYCError('insufficient_credits', message, { required, balance, currency });
+    }
+    if (err.statusCode === 403) {
+      const feature = typeof err.body?.feature === 'string' ? err.body.feature : null;
+      const message =
+        err.code === 'id_type_not_allowed'
+          ? "This ID type isn't enabled for your organization. Contact your administrator to request access."
+          : feature === 'document_verification'
+            ? 'Document verification is currently disabled for your organization.'
+            : feature === 'gov_db_check'
+              ? 'Government database verification is currently disabled for your organization.'
+              : err.message || 'This verification feature is currently disabled for your organization.';
+      return new KYCError('feature_disabled', message);
+    }
+    if (err.statusCode >= 500 || err.statusCode === 0) {
+      // Transient server error that survived retries.
+      const code: KYCErrorCode = context === 'upload' ? 'upload_failed' : 'network_error';
+      return new KYCError(code, 'A server error occurred. Please try again in a moment.');
+    }
+    // Other 4xx — pass the server message through under the context's code.
+    const code: KYCErrorCode = context === 'upload' ? 'upload_failed' : 'unknown';
+    return new KYCError(code, err.message);
+  }
+  // fetch() throws a TypeError on network failure (offline / DNS).
+  if (err instanceof TypeError) {
+    return new KYCError('network_error', 'Network error. Please check your connection and try again.');
+  }
+  const code: KYCErrorCode = context === 'upload' ? 'upload_failed' : 'unknown';
+  return new KYCError(code, err instanceof Error ? err.message : 'Something went wrong. Please try again.');
+}

package/src/services/mediaCompress.ts

@@ -0,0 +1,129 @@
+import { Image } from 'react-native';
+import * as ImageManipulator from 'expo-image-manipulator';
+import { Video } from 'react-native-compressor';
+
+import {
+  DOCUMENT_IMAGE_QUALITY,
+  DOCUMENT_MAX_DIMENSION,
+  SELFIE_IMAGE_QUALITY,
+  VIDEO_COMPRESS_BITRATE,
+  VIDEO_COMPRESS_MAX_SIZE,
+} from '../config/captureSettings';
+import { cardCropRect, type CropRect } from './cardCrop';
+
+export type { CropRect } from './cardCrop';
+
+/**
+ * Transcodes a recorded clip down to a small evidence video (best-effort).
+ * VisionCamera v5 records at the document camera's high-res 4K session format on
+ * iOS and ignores the bitrate/resolution hints, so the raw file is far too large;
+ * this shrinks it (mirrors the Flutter SDK's video_compress). On failure it returns
+ * the original URI — the caller's size guard then drops it if still over the cap.
+ */
+export async function compressVideo(uri: string): Promise<string> {
+  try {
+    const out = await Video.compress(uri, {
+      compressionMethod: 'manual',
+      maxSize: VIDEO_COMPRESS_MAX_SIZE,
+      bitrate: VIDEO_COMPRESS_BITRATE,
+    });
+    return out.startsWith('file://') ? out : `file://${out}`;
+  } catch {
+    return uri;
+  }
+}
+
+// Post-capture still-image compression — the RN mirror of the Flutter SDK's
+// media_compress_service.dart (and the web SDK's useImageCompress). Effort scales
+// to need:
+//   • DOCUMENT — conservative (OCR-critical): JPEG q0.9, only downscaled when the
+//     longest edge exceeds DOCUMENT_MAX_DIMENSION, so small text stays legible.
+//   • SELFIE   — moderate: JPEG q0.8, capped to ~1280 px.
+// Runs natively via expo-image-manipulator (off the JS thread).
+
+export function imageSize(uri: string): Promise<{ width: number; height: number }> {
+  return new Promise((resolve, reject) =>
+    Image.getSize(uri, (width, height) => resolve({ width, height }), reject),
+  );
+}
+
+/**
+ * Crop [uri] to [rect] (source-image pixels) and return a new high-quality JPEG
+ * URI — the RN mirror of the Flutter SDK's `cropAndCompress` / `cropCardRegion`.
+ * Kept near-lossless here (q0.95); OCR-grade sizing happens in
+ * `compressDocumentImage` afterwards, exactly like Flutter.
+ */
+export async function cropImage(uri: string, rect: CropRect): Promise<string> {
+  const result = await ImageManipulator.manipulateAsync(
+    uri,
+    [{ crop: { originX: Math.round(rect.originX), originY: Math.round(rect.originY), width: Math.round(rect.width), height: Math.round(rect.height) } }],
+    { compress: 0.95, format: ImageManipulator.SaveFormat.JPEG },
+  );
+  return result.uri;
+}
+
+/**
+ * Crop a live-camera capture to the card-guide rectangle painted over the
+ * viewfinder — the RN mirror of the Flutter SDK's `cropCardRegion`.
+ *
+ * The CameraViewfinder shows the preview `BoxFit.cover` inside a fixed 3:4 box,
+ * with the guide centred at 88% width and `aspect` height (mirrors the SVG
+ * overlay). So the crop is computed purely from the photo's pixel size + those
+ * fractions — no absolute viewfinder size needed:
+ *   1. the 3:4 box shows a centred 3:4 slice of the photo (cover),
+ *   2. the guide is a sub-rect of that slice (88% wide, `aspect` ratio, centred).
+ */
+/**
+ * Crop a live-camera capture to the card-guide rectangle painted over the
+ * viewfinder — the RN mirror of the Flutter SDK's `cropCardRegion`. The
+ * CameraViewfinder shows the preview `BoxFit.cover` in a fixed 3:4 box with the
+ * guide centred at 88% width and `aspect` height (mirrors the SVG overlay).
+ */
+export async function cropCardRegion(uri: string, aspect: number): Promise<string> {
+  const { width, height } = await imageSize(uri);
+  return cropImage(uri, cardCropRect(width, height, aspect));
+}
+
+/** Compress a document still for OCR. Returns a new file URI. */
+export async function compressDocumentImage(uri: string): Promise<string> {
+  let actions: ImageManipulator.Action[] = [];
+  try {
+    const { width, height } = await imageSize(uri);
+    const longest = Math.max(width, height);
+    if (longest > DOCUMENT_MAX_DIMENSION) {
+      actions = [
+        width >= height
+          ? { resize: { width: DOCUMENT_MAX_DIMENSION } }
+          : { resize: { height: DOCUMENT_MAX_DIMENSION } },
+      ];
+    }
+  } catch {
+    /* size unknown — recompress without resizing */
+  }
+  const result = await ImageManipulator.manipulateAsync(uri, actions, {
+    compress: DOCUMENT_IMAGE_QUALITY,
+    format: ImageManipulator.SaveFormat.JPEG,
+  });
+  return result.uri;
+}
+
+/** Compress a selfie still (moderate). Returns a new file URI. */
+export async function compressSelfieImage(uri: string): Promise<string> {
+  let actions: ImageManipulator.Action[] = [];
+  try {
+    const { width, height } = await imageSize(uri);
+    const longest = Math.max(width, height);
+    if (longest > 1280) {
+      actions = [
+        width >= height ? { resize: { width: 1280 } } : { resize: { height: 1280 } },
+      ];
+    }
+  } catch {
+    /* size unknown — recompress without resizing */
+  }
+  const result = await ImageManipulator.manipulateAsync(uri, actions, {
+    compress: SELFIE_IMAGE_QUALITY,
+    format: ImageManipulator.SaveFormat.JPEG,
+  });
+  return result.uri;
+}

package/src/services/resolveUrl.ts

@@ -0,0 +1,98 @@
+// ---------------------------------------------------------------------------
+// Automatic environment detection from the API key prefix
+//
+// The environment is encoded in the key prefix — the single source of truth
+// (there is no manual environment option). The prefix carries scope
+// (`pk` publishable / `sk` secret) and environment (`dev`/`test`/`live`); we
+// read ONLY the environment portion, so detection works for both key types.
+// Mirrors the web SDK's `resolve-url.ts` and the Flutter SDK's `resolve_url.dart`:
+//
+//   pk_dev_…  / sk_dev_…   → development
+//   pk_test_… / sk_test_…  → sandbox
+//   pk_live_… / sk_live_…  → production
+// ---------------------------------------------------------------------------
+
+import { isAndroid } from '../utils/platform';
+
+/** Internal environment the SDK resolves a base URL for. Not a public option. */
+export type SdkEnvironment = 'development' | 'sandbox' | 'production';
+
+/** Canonical base URLs for the non-development environments. */
+const BASE_URLS: Record<Exclude<SdkEnvironment, 'development'>, string> = {
+  sandbox: 'https://sandbox.identity.myaza.app',
+  production: 'https://identity.myaza.app',
+};
+
+/**
+ * Default base URL used for development keys when no `devUrl` is provided.
+ * Android emulators reach the host machine via `10.0.2.2`; everywhere else
+ * (iOS simulator, desktop) `localhost` works directly.
+ */
+function defaultDevUrl(): string {
+  return isAndroid ? 'http://10.0.2.2:3001' : 'http://localhost:3001';
+}
+
+// Matches the environment slot of a Myaza API key prefix, regardless of the
+// pk_/sk_ scope.
+const KEY_ENV_RE = /^(?:pk|sk)_(dev|test|live)_/;
+
+const ENV_BY_PREFIX: Record<'dev' | 'test' | 'live', SdkEnvironment> = {
+  dev: 'development',
+  test: 'sandbox',
+  live: 'production',
+};
+
+/**
+ * Derives the environment from the API key prefix. Throws a clear error on an
+ * unrecognized / malformed key — never silently defaults (defaulting to
+ * production would be dangerous).
+ */
+export function detectEnvironment(apiKey: string): SdkEnvironment {
+  const match = typeof apiKey === 'string' ? apiKey.match(KEY_ENV_RE) : null;
+  if (!match) {
+    throw new Error(
+      'Invalid Myaza API key: expected a dev, test, or live key prefix ' +
+        '(e.g. pk_dev_…, pk_test_…, or pk_live_…).',
+    );
+  }
+  return ENV_BY_PREFIX[match[1] as 'dev' | 'test' | 'live'];
+}
+
+/**
+ * Resolves the API base URL from the API key. The environment is detected from
+ * the key prefix:
+ * - development → `devUrl` if provided, otherwise a platform-aware localhost.
+ * - sandbox / production → the hardcoded URL (`devUrl` is ignored).
+ *
+ * Throws on an invalid key (via {@link detectEnvironment}).
+ */
+export function resolveBaseUrl(apiKey: string, devUrl?: string): string {
+  const environment = detectEnvironment(apiKey);
+  if (environment === 'development') {
+    return devUrl ?? defaultDevUrl();
+  }
+  return BASE_URLS[environment];
+}
+
+// Hosts that mean "this machine" but resolve differently per platform — a local
+// dev server reachable as `localhost` on the iOS sim and `10.0.2.2` on the
+// Android emulator.
+const LOCAL_HOST_RE = /^https?:\/\/(localhost|127\.0\.0\.1|10\.0\.2\.2)(:\d+)?/i;
+
+/**
+ * Normalizes a server-provided absolute asset URL (e.g. the branding logo) for
+ * local development. The dev server often returns a hardcoded `localhost` origin,
+ * which the Android emulator can't reach. When the SDK is pointed at a local dev
+ * server (an `http://` base) and the asset points at a localhost-family host, its
+ * origin is rewritten to the SDK's base origin so it loads on every platform.
+ *
+ * Production / sandbox URLs (`https://`) and assets on any other host (e.g. a
+ * public CDN) are returned untouched.
+ */
+export function normalizeDevAssetUrl(url: string | undefined, baseUrl: string): string | undefined {
+  if (!url) return url;
+  // Only ever rewrite for a local (http) dev base — never production CDNs.
+  if (!baseUrl.startsWith('http://')) return url;
+  if (!LOCAL_HOST_RE.test(url)) return url;
+  return url.replace(LOCAL_HOST_RE, baseUrl.replace(/\/+$/, ''));
+}

package/src/services/retry.ts

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// withRetry — shared retry/backoff for the SDK's network operations
+//
+// Wraps the SDK's network calls (media upload, verify submission) so transient
+// failures — lost connection, timeouts, 5xx — are retried with exponential
+// backoff + jitter before giving up. Terminal failures (4xx auth / credits /
+// forbidden) are NOT retried; they surface immediately.
+//
+// Mirrors the web SDK's `lib/retry.ts` and the Flutter SDK's `retry.dart` so all
+// platforms behave identically. After retries are exhausted the original error
+// is rethrown — the caller maps it to a typed KYCError for `onError`.
+// ---------------------------------------------------------------------------
+
+import { KYCApiError } from './api';
+
+export interface RetryOptions {
+  /** Total attempts including the first try. Default 3. */
+  retries?: number;
+  /** Base delay before the first retry (ms). Default 500. */
+  baseDelayMs?: number;
+  /** Backoff multiplier between attempts. Default 2. */
+  factor?: number;
+  /** Max delay cap (ms). Default 4000. */
+  maxDelayMs?: number;
+  /** Notified before each retry with the upcoming attempt number (2-based) + total. */
+  onRetry?: (attempt: number, total: number) => void;
+}
+
+/**
+ * Whether an error is transient (worth retrying). A `KYCApiError` is transient
+ * only for 5xx (or 0); 4xx are terminal. A `TypeError` from `fetch()` is a
+ * network failure — transient. Anything else is terminal.
+ */
+export function isTransientError(err: unknown): boolean {
+  if (err instanceof KYCApiError) {
+    return err.statusCode >= 500 || err.statusCode === 0;
+  }
+  // fetch() rejects with a TypeError on network failure.
+  if (err instanceof TypeError) return true;
+  return false;
+}
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/**
+ * Runs `fn`, retrying on transient errors with exponential backoff + jitter.
+ * Rethrows the last error once attempts are exhausted (or immediately for a
+ * terminal error).
+ */
+export async function withRetry<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
+  const { retries = 3, baseDelayMs = 500, factor = 2, maxDelayMs = 4000, onRetry } = options;
+
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      const hasMore = attempt < retries;
+      if (!hasMore || !isTransientError(err)) throw err;
+
+      onRetry?.(attempt + 1, retries);
+      const backoff = Math.min(baseDelayMs * factor ** (attempt - 1), maxDelayMs);
+      // Full jitter — spread retries so a flaky network doesn't see synchronized bursts.
+      const delay = Math.random() * backoff;
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}

package/src/services/validators.ts

@@ -0,0 +1,103 @@
+import type { IdType, SupportedCountry } from '../types/config';
+
+// Per-ID-type format validation — identical rules to the web SDK's
+// `utils/validators.ts` and the Flutter SDK's `validators.dart`.
+
+export interface ValidationResult {
+  valid: boolean;
+  message?: string;
+}
+
+const DIGITS_ONLY = /^\d+$/;
+
+function digitsExact(value: string, count: number, label: string): ValidationResult {
+  if (!DIGITS_ONLY.test(value)) {
+    return { valid: false, message: `${label} must contain only digits` };
+  }
+  if (value.length !== count) {
+    return { valid: false, message: `${label} must be exactly ${count} digits` };
+  }
+  return { valid: true };
+}
+
+function matchesPattern(value: string, pattern: RegExp, label: string, hint: string): ValidationResult {
+  if (!pattern.test(value)) {
+    return { valid: false, message: `Invalid ${label} format (${hint})` };
+  }
+  return { valid: true };
+}
+
+// ---------------------------------------------------------------------------
+// Per-ID-type validators (country-prefixed where a key is shared across countries)
+// ---------------------------------------------------------------------------
+
+const validators: Record<string, (value: string) => ValidationResult> = {
+  // Nigeria
+  bvn: (v) => digitsExact(v, 11, 'BVN'),
+  nin: (v) => digitsExact(v, 11, 'NIN'),
+  vnin: (v) => {
+    if (v.length !== 16) {
+      return { valid: false, message: 'vNIN must be exactly 16 characters' };
+    }
+    return { valid: true };
+  },
+  'ng-passport': (v) => matchesPattern(v, /^[A-Z]\d{8}$/, 'Passport', 'e.g. A12345678'),
+  'ng-drivers-license': (v) => matchesPattern(v, /^[A-Z]{3}\d{5,12}$/, "Driver's License", 'e.g. ABC12345'),
+  pvc: (v) => digitsExact(v, 19, "Voter's Card (PVC)"),
+
+  // Ghana
+  'ghana-card': (v) => matchesPattern(v, /^GHA-\d{9}-\d$/, 'Ghana Card', 'e.g. GHA-123456789-0'),
+  'gh-voters': (v) => digitsExact(v, 10, "Voter's Card"),
+  ssnit: (v) => digitsExact(v, 13, 'SSNIT'),
+  'gh-passport': (v) => matchesPattern(v, /^[A-Z]\d{7}$/, 'Passport', 'e.g. A1234567'),
+
+  // Kenya
+  'ke-national-id': (v) => digitsExact(v, 8, 'National ID'),
+
+  // South Africa
+  'za-national-id': (v) => digitsExact(v, 13, 'National ID'),
+};
+
+function resolveKey(country: SupportedCountry, idType: IdType): string {
+  // Some ID types share a name across countries (passport, drivers-license,
+  // national-id, voters). Prefix those with the country code so they map to the
+  // country-specific validator.
+  const needsPrefix: Record<string, Set<string>> = {
+    passport: new Set(['NG', 'GH']),
+    'drivers-license': new Set(['NG']),
+    'national-id': new Set(['KE', 'ZA']),
+    voters: new Set(['GH']),
+  };
+
+  const prefixSet = needsPrefix[idType];
+  if (prefixSet?.has(country)) {
+    return `${country.toLowerCase()}-${idType}`;
+  }
+  return idType;
+}
+
+export function validateIdNumber(
+  country: SupportedCountry,
+  idType: IdType,
+  value: string,
+): ValidationResult {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return { valid: false, message: 'ID number is required' };
+  }
+  const validator = validators[resolveKey(country, idType)];
+  if (!validator) {
+    // No specific validator — accept non-empty input.
+    return { valid: true };
+  }
+  return validator(trimmed);
+}
+
+/** Masks an ID number for display — never log the raw value. */
+export function maskIdNumber(idNumber: string): string {
+  if (idNumber.length <= 7) return idNumber;
+  const first4 = idNumber.slice(0, 4);
+  const last3 = idNumber.slice(-3);
+  const masked = '*'.repeat(idNumber.length - 7);
+  return `${first4}${masked}${last3}`;
+}