@myazahq/kyc-sdk-react-native 2.0.0

package/src/index.ts

@@ -0,0 +1,54 @@
+// ---------------------------------------------------------------------------
+// @myazahq/kyc-sdk-react-native — public API barrel.
+//
+// Mirrors the Flutter SDK's `kyc_sdk_flutter.dart`. The UI entry points
+// (`MyazaKYC`, `useMyazaKYC`) are added in Step 2; this currently exports the
+// public types, the ID-type matrix, validators, the typed error, and the
+// liveness face-detector registry (for custom/test detector overrides).
+// ---------------------------------------------------------------------------
+
+// UI entry points
+export { MyazaKYC, useMyazaKYC } from './MyazaKYC';
+export type { MyazaKYCProps, UseMyazaKYCReturn } from './MyazaKYC';
+
+// Public config + callback types
+export type {
+  MyazaKYCConfig,
+  SupportedCountry,
+  IdType,
+  IdTypeForCountry,
+  IdTypeDefinition,
+  KYCStep,
+  KYCAppearance,
+  KYCConsentContent,
+  KYCSuccessContent,
+  VoiceGuidanceConfig,
+  VoiceGuidanceOption,
+} from './types/config';
+export type { KYCSubmission, KYCErrorCode, KYCErrorDetails } from './types/verification';
+export { KYCError } from './types/verification';
+
+// ID-type matrix + helpers
+export {
+  ID_TYPES,
+  COUNTRY_LABELS,
+  isNumberOnlyIdType,
+  requiresDocumentCapture,
+  getScanSides,
+} from './config/idTypes';
+
+// Client-side validation
+export { validateIdNumber, maskIdNumber, type ValidationResult } from './services/validators';
+
+// Liveness — types + the face-detector seam (custom/test detector override)
+export type { LivenessChallenge, LivenessConfig, LivenessFaceData } from './liveness/types';
+export {
+  type FaceDetectorService,
+  StubFaceDetectorService,
+  registerFaceDetectorFactory,
+  createFaceDetectorService,
+  hasFaceDetectorFactory,
+} from './liveness/faceDetector';
+
+// SDK version
+export { SDK_VERSION } from './services/deviceMetadata';

package/src/liveness/challengeManager.ts

@@ -0,0 +1,130 @@
+// ---------------------------------------------------------------------------
+// Challenge manager — randomly picks 2–3 challenges and tracks progress.
+// Port of the web SDK's `challenge-manager.ts`, adapted to the RN/Flutter
+// `ChallengeConfig` shape.
+// ---------------------------------------------------------------------------
+
+import {
+  CHALLENGE_POOL,
+  DEFAULT_LIVENESS_CONFIG,
+  type ChallengeConfig,
+  type LivenessChallenge,
+  type LivenessConfig,
+} from './types';
+
+// Gestures within a similarity group should never appear together — one can
+// accidentally satisfy the other (head motion overlaps).
+const SIMILARITY_GROUPS: LivenessChallenge[][] = [['nod', 'turn']];
+
+function areSimilar(a: LivenessChallenge, b: LivenessChallenge): boolean {
+  return SIMILARITY_GROUPS.some((group) => group.includes(a) && group.includes(b));
+}
+
+function shuffle<T>(arr: readonly T[]): T[] {
+  const copy = [...arr];
+  for (let i = copy.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [copy[i], copy[j]] = [copy[j]!, copy[i]!];
+  }
+  return copy;
+}
+
+/** Picks `challengeCount` non-similar challenges from the pool, in random order. */
+export function pickChallenges(config: Partial<LivenessConfig> = {}): ChallengeConfig[] {
+  const merged = { ...DEFAULT_LIVENESS_CONFIG, ...config };
+
+  let pool = CHALLENGE_POOL;
+  if (merged.challengePool && merged.challengePool.length > 0) {
+    const allowed = new Set<LivenessChallenge>(merged.challengePool);
+    pool = CHALLENGE_POOL.filter((c) => allowed.has(c.type));
+  }
+
+  const count = Math.min(merged.challengeCount, pool.length);
+  const shuffled = shuffle(pool);
+
+  // Greedily pick challenges that aren't similar to already-picked ones.
+  const picked: ChallengeConfig[] = [];
+  for (const candidate of shuffled) {
+    if (picked.length >= count) break;
+    if (!picked.some((p) => areSimilar(p.type, candidate.type))) {
+      picked.push({ ...candidate, timeoutSeconds: merged.timeoutPerChallenge });
+    }
+  }
+
+  // Fallback: if similarity rules were too strict, fill remaining slots.
+  if (picked.length < count) {
+    for (const candidate of shuffled) {
+      if (picked.length >= count) break;
+      if (!picked.some((p) => p.type === candidate.type)) {
+        picked.push({ ...candidate, timeoutSeconds: merged.timeoutPerChallenge });
+      }
+    }
+  }
+
+  return picked;
+}
+
+// ---------------------------------------------------------------------------
+// Progress tracker
+// ---------------------------------------------------------------------------
+
+export type ChallengeProgress = 'pending' | 'active' | 'passed' | 'failed';
+
+export interface ChallengeEntry {
+  config: ChallengeConfig;
+  progress: ChallengeProgress;
+}
+
+export class ChallengeTracker {
+  private entries: ChallengeEntry[];
+  private _currentIndex: number;
+
+  constructor(challenges: ChallengeConfig[]) {
+    this.entries = challenges.map((config, i) => ({
+      config,
+      progress: i === 0 ? 'active' : 'pending',
+    }));
+    this._currentIndex = 0;
+  }
+
+  get current(): ChallengeEntry | null {
+    return this.entries[this._currentIndex] ?? null;
+  }
+
+  get currentIndex(): number {
+    return this._currentIndex;
+  }
+
+  get all(): readonly ChallengeEntry[] {
+    return this.entries;
+  }
+
+  get isComplete(): boolean {
+    return this.entries.every((e) => e.progress === 'passed');
+  }
+
+  get totalCount(): number {
+    return this.entries.length;
+  }
+
+  markCurrentPassed(): void {
+    const entry = this.entries[this._currentIndex];
+    if (entry) entry.progress = 'passed';
+  }
+
+  markCurrentFailed(): void {
+    const entry = this.entries[this._currentIndex];
+    if (entry) entry.progress = 'failed';
+  }
+
+  /** Advances to the next challenge; returns true if more remain. */
+  advance(): boolean {
+    this._currentIndex++;
+    const next = this.entries[this._currentIndex];
+    if (next) {
+      next.progress = 'active';
+      return true;
+    }
+    return false;
+  }
+}

package/src/liveness/faceDetector.ts

@@ -0,0 +1,79 @@
+// ---------------------------------------------------------------------------
+// FaceDetectorService — the clean native boundary for liveness.
+//
+// This is the ONLY thing the liveness screen/store sees. It mirrors the Flutter
+// SDK's `FaceDetectorService`: the core SDK depends on this interface, never on
+// a concrete ML library, so liveness math, anti-spoofing thresholds, and camera
+// assumptions never leak into screens — and a shared native core can be
+// extracted later without touching the flow.
+//
+// Implementations:
+//   • VisionCameraFaceDetector (default, wired in Step 4) — a
+//     react-native-vision-camera frame-processor plugin: Apple Vision on iOS,
+//     Google ML Kit on Android. No cross-platform ML Kit iOS pod, so it builds
+//     on Apple-Silicon iOS simulators.
+//   • StubFaceDetectorService — no-op fallback (always "no face"). The Step-1/2
+//     default and the test override.
+// ---------------------------------------------------------------------------
+
+import type { LivenessFaceData } from './types';
+
+/**
+ * An opaque camera frame. Typed as `unknown` here so the core stays free of the
+ * react-native-vision-camera dependency; the native detector narrows it to a
+ * VisionCamera `Frame` inside its worklet.
+ */
+export type FaceDetectorFrame = unknown;
+
+export interface FaceDetectorService {
+  /** Prepares the detector for use. Called once before {@link detect}. */
+  initialize(): void;
+
+  /**
+   * Processes a single camera frame and returns the dominant face's gesture
+   * data, or `null` when no usable face is present (or this is the stub).
+   * Runs in a frame-processor worklet, so it is synchronous.
+   */
+  detect(frame: FaceDetectorFrame): LivenessFaceData | null;
+
+  /** Releases any native resources. Safe to call multiple times. */
+  dispose(): void;
+}
+
+/** No-op detector — always reports "no face", so liveness never self-advances. */
+export class StubFaceDetectorService implements FaceDetectorService {
+  initialize(): void {}
+  detect(): LivenessFaceData | null {
+    return null;
+  }
+  dispose(): void {}
+}
+
+// ---------------------------------------------------------------------------
+// Detector registry — a process-wide factory hook.
+// ---------------------------------------------------------------------------
+
+let faceDetectorFactory: (() => FaceDetectorService) | null = null;
+
+/**
+ * Overrides the factory used to create the SDK's {@link FaceDetectorService}.
+ * Optional — call once at startup, before launching the KYC flow. Used by the
+ * native detector to install itself, and by tests to install the stub.
+ */
+export function registerFaceDetectorFactory(factory: () => FaceDetectorService): void {
+  faceDetectorFactory = factory;
+}
+
+/** Whether a host/native module has overridden the detector factory. */
+export function hasFaceDetectorFactory(): boolean {
+  return faceDetectorFactory !== null;
+}
+
+/**
+ * Creates a {@link FaceDetectorService} — the registered factory if one is set,
+ * otherwise the {@link StubFaceDetectorService}. (Step 4 registers the
+ * VisionCamera detector as the default at module load.)
+ */
+export function createFaceDetectorService(): FaceDetectorService {
+  return (faceDetectorFactory ?? (() => new StubFaceDetectorService()))();
+}

package/src/liveness/gestureDetector.ts

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// Gesture detection — pure functions over native face signals.
+//
+// Direct port of the Flutter SDK's gesture functions (face_detection.dart). They
+// operate on `LivenessFaceData`-derived histories (degrees / probabilities), so
+// the thresholds match Flutter's on-device-tuned values — NOT the web SDK's
+// normalized-landmark thresholds. Kept pure so they unit-test without a camera.
+//
+// Histories are sliding windows (~20 frames) maintained by the liveness store.
+// ---------------------------------------------------------------------------
+
+/**
+ * Detects a nod: `headEulerAngleX` (pitch) dips below −10° then recovers above
+ * −5°. The caller maintains `xHistory` as a sliding window. ≥2 frames required.
+ */
+export function detectNod(xHistory: readonly number[]): boolean {
+  if (xHistory.length < 2) return false;
+  const minAngle = Math.min(...xHistory);
+  const currentAngle = xHistory[xHistory.length - 1]!;
+  return minAngle < -10 && currentAngle > -5;
+}
+
+/** Detects a head turn when `headEulerAngleY` (yaw) exceeds ±25°. Single frame. */
+export function detectTurn(eulerY: number): boolean {
+  return Math.abs(eulerY) > 25;
+}
+
+/**
+ * Detects a blink: the average eye-open probability drops below 0.2 then
+ * recovers above 0.5. ≥2 frames required. (Threshold relaxed 0.15→0.2 from
+ * on-device data, where a real blink only briefly bottoms out.)
+ */
+export function detectBlink(earHistory: readonly number[]): boolean {
+  if (earHistory.length < 2) return false;
+  const hadClose = earHistory.some((v) => v < 0.2);
+  const recovered = earHistory[earHistory.length - 1]! > 0.5;
+  return hadClose && recovered;
+}
+
+/** Detects a smile when `smilingProbability` exceeds 0.5. Single frame. */
+export function detectSmile(smilingProbability: number): boolean {
+  return smilingProbability > 0.5;
+}
+
+import type { LivenessChallenge, LivenessFaceData } from './types';
+import { eyeAverageOpenProbability } from './types';
+
+/**
+ * Evaluates whether the given challenge passes for the current frame/history.
+ * `xHistory` is the pitch window (nod); `earHistory` is the avg-eye-open window
+ * (blink). Single-frame gestures (turn/smile) read the latest `face`.
+ */
+export function evaluateChallenge(
+  challenge: LivenessChallenge,
+  face: LivenessFaceData,
+  xHistory: readonly number[],
+  earHistory: readonly number[],
+): boolean {
+  switch (challenge) {
+    case 'nod':
+      return detectNod(xHistory);
+    case 'turn':
+      return detectTurn(face.headEulerAngleY);
+    case 'blink':
+      return detectBlink(earHistory);
+    case 'smile':
+      return detectSmile(face.smilingProbability);
+    default:
+      return false;
+  }
+}
+
+/** Appends to a sliding window, trimming to `maxLen` (default 20 frames). */
+export function pushHistory(history: number[], value: number, maxLen = 20): number[] {
+  const next = [...history, value];
+  return next.length > maxLen ? next.slice(next.length - maxLen) : next;
+}
+
+/** Re-export so callers can read the eye-open average without reaching into types. */
+export { eyeAverageOpenProbability };

package/src/liveness/speech.ts

@@ -0,0 +1,66 @@
+// ---------------------------------------------------------------------------
+// Spoken liveness guidance — TTS OUTPUT ONLY (no microphone). Mirrors the web
+// SDK's liveness/speech.ts and the Flutter SDK's _TtsService. Backed by
+// expo-speech. Voice guidance exists for accessibility; it never records audio,
+// so there is no microphone permission and no microphone error code.
+// ---------------------------------------------------------------------------
+
+import * as Speech from 'expo-speech';
+
+import type { VoiceGuidanceOption } from '../types/config';
+
+export interface ResolvedVoiceGuidance {
+  enabled: boolean;
+  language: string;
+}
+
+/** Normalises the `voiceGuidance` config (bool | object | undefined) → object. */
+export function resolveVoiceGuidance(option: VoiceGuidanceOption | undefined): ResolvedVoiceGuidance {
+  if (option === false) return { enabled: false, language: 'en-US' };
+  if (option === true || option == null) return { enabled: true, language: 'en-US' };
+  return { enabled: option.enabled !== false, language: option.language ?? 'en-US' };
+}
+
+/**
+ * A tiny speaker that de-dupes consecutive identical phrases (so a guidance
+ * string repeated every frame is only spoken once) and no-ops when disabled.
+ * One instance per liveness session.
+ */
+export class LivenessSpeaker {
+  private readonly enabled: boolean;
+  private readonly language: string;
+  private lastSpoken: string | null = null;
+
+  constructor(option: VoiceGuidanceOption | undefined) {
+    const resolved = resolveVoiceGuidance(option);
+    this.enabled = resolved.enabled;
+    this.language = resolved.language;
+  }
+
+  /** Speaks `text` unless guidance is off or it equals the last phrase spoken. */
+  speak(text: string): void {
+    if (!this.enabled || !text || text === this.lastSpoken) return;
+    this.lastSpoken = text;
+    try {
+      Speech.stop();
+      Speech.speak(text, { language: this.language });
+    } catch {
+      /* TTS is best-effort — a failure must never block the flow */
+    }
+  }
+
+  /** Clears the de-dupe memory so the next `speak` always plays (e.g. on retry). */
+  reset(): void {
+    this.lastSpoken = null;
+  }
+
+  /** Stops any in-flight speech. Call when the liveness screen unmounts. */
+  stop(): void {
+    this.lastSpoken = null;
+    try {
+      Speech.stop();
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/src/liveness/types.ts

@@ -0,0 +1,99 @@
+// ---------------------------------------------------------------------------
+// Liveness challenge types, state machine, and the per-frame face signal.
+//
+// Mirrors the Flutter SDK's `liveness_types.dart` + the `LivenessFaceData` value
+// object. The RN SDK consumes the SAME native signals as Flutter (head euler
+// angles + smile/eye probabilities from Apple Vision / ML Kit) — NOT the web
+// SDK's MediaPipe landmarks — so the gesture thresholds match Flutter's.
+// ---------------------------------------------------------------------------
+
+export type LivenessChallenge = 'nod' | 'turn' | 'blink' | 'smile';
+
+export interface ChallengeConfig {
+  type: LivenessChallenge;
+  instruction: string;
+  timeoutSeconds: number;
+}
+
+/** Default challenge pool — same instructions/timeouts as the Flutter + web SDKs. */
+export const CHALLENGE_POOL: ChallengeConfig[] = [
+  { type: 'nod', instruction: 'Kindly nod your head', timeoutSeconds: 8 },
+  { type: 'turn', instruction: 'Kindly turn your head', timeoutSeconds: 8 },
+  { type: 'blink', instruction: 'Blink your eyes', timeoutSeconds: 6 },
+  { type: 'smile', instruction: 'Smile please', timeoutSeconds: 6 },
+];
+
+// ---------------------------------------------------------------------------
+// State machine (mirrors Flutter's LivenessPhase)
+// ---------------------------------------------------------------------------
+
+export type LivenessPhase =
+  | 'loading' // Initializing camera + detector
+  | 'positioning' // "Position your face in the circle"
+  | 'challenge' // Active gesture challenge
+  | 'challenge_passed' // Brief green flash
+  | 'capturing' // Auto-capturing selfie
+  | 'complete' // All done — selfie review
+  | 'failed'; // Timeout or face lost
+
+export type LivenessFailureReason = 'timeout' | 'face_lost' | 'no_camera' | 'load_error';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface LivenessConfig {
+  challengeCount: 2 | 3;
+  challengePool?: LivenessChallenge[];
+  timeoutPerChallenge: number;
+  positioningTimeout: number;
+}
+
+export const DEFAULT_LIVENESS_CONFIG: LivenessConfig = {
+  challengeCount: 2,
+  timeoutPerChallenge: 8,
+  positioningTimeout: 15,
+};
+
+// ---------------------------------------------------------------------------
+// LivenessFaceData — per-frame signals from the native detector (both platforms)
+// ---------------------------------------------------------------------------
+
+/**
+ * A snapshot of the face attributes from a single camera frame. Intentionally
+ * free of any ML Kit / Vision dependency so the gesture logic stays pure and
+ * unit-testable. The native VisionCamera frame-processor plugin produces this:
+ * Apple Vision on iOS, Google ML Kit on Android.
+ */
+export interface LivenessFaceData {
+  /** Head pitch (degrees): positive = up, negative = down. Drives nod detection. */
+  headEulerAngleX: number;
+  /** Head yaw (degrees): positive = left, negative = right. Drives turn detection. */
+  headEulerAngleY: number;
+  /** Head roll/tilt (degrees). Available but unused for gesture detection. */
+  headEulerAngleZ: number;
+  /** 0.0 (not smiling) → 1.0 (smiling). */
+  smilingProbability: number;
+  /** 0.0 (closed) → 1.0 (open). */
+  leftEyeOpenProbability: number;
+  /** 0.0 (closed) → 1.0 (open). */
+  rightEyeOpenProbability: number;
+  /** Face width / frame width (0–1): <0.2 too far, >0.7 too close. */
+  faceSizeRatio: number;
+  /** # faces in frame. `> 1` pauses challenges. Defaults to 1 for older plugins. */
+  faceCount: number;
+  /** Mean frame luma (0–255). Feeds the low-light gate (<62 dark, >200 bright). */
+  brightness: number;
+}
+
+/** Convenience: average of both eye-open probabilities. */
+export function eyeAverageOpenProbability(face: LivenessFaceData): number {
+  return (face.leftEyeOpenProbability + face.rightEyeOpenProbability) / 2;
+}
+
+// ---------------------------------------------------------------------------
+// Face positioning thresholds (distance), mirroring Flutter
+// ---------------------------------------------------------------------------
+
+export const FACE_TOO_FAR_RATIO = 0.2;
+export const FACE_TOO_CLOSE_RATIO = 0.7;