react-native-tediwave-biometric-verifier 0.1.3

package/src/useBiometricEngine.ts

@@ -0,0 +1,626 @@
+import { useRef, useState, useCallback, useEffect } from 'react';
+import { type Frame } from 'react-native-vision-camera';
+import { useResizePlugin } from 'vision-camera-resize-plugin';
+import RNTts from 'react-native-tts';
+import { logger } from './logger';
+
+// ==================== TYPE DEFINITIONS ====================
+
+export type VerificationStatus =
+  | 'INITIALIZING'
+  | 'FACE_DETECTION'
+  | 'WAITING_FOR_FACE'
+  | 'FACE_READY'
+  | 'CHALLENGE_IN_PROGRESS'
+  | 'VERIFYING'
+  | 'PAUSED'
+  | 'COMPLETED';
+
+export type VerificationResult = 'PASS' | 'FAIL' | 'TIMEOUT' | 'ERROR';
+
+export type ChallengeType =
+  | 'FACE_THE_CAMERA'
+  | 'BLINK_ONCE'
+  | 'BLINK_TWICE'
+  | 'SMILE'
+  | 'TURN_HEAD_LEFT'
+  | 'TURN_HEAD_RIGHT'
+  | 'LOOK_UP'
+  | 'LOOK_DOWN'
+  | 'RAISE_EYEBROWS'
+  | 'NOD_HEAD'
+  | 'SHAKE_HEAD'
+  | 'OPEN_MOUTH'
+  | 'CLOSE_EYES_BRIEFLY';
+
+export interface ChallengeResult {
+  challenge: ChallengeType;
+  status: 'PASS' | 'FAIL' | 'TIMEOUT';
+  timestamp: number;
+  duration: number;
+  confidence: number;
+  failureReason?: string;
+}
+
+export interface FaceQualityMetrics {
+  isDetected: boolean;
+  faceCount: number;
+  isCentered: boolean;
+  isProperlyLit: boolean;
+  faceSize: number;
+  sharpness: number;
+  angularDeviation: number;
+  occlusion: number;
+  quality: number; // 0-100
+}
+
+export interface VerificationPayload {
+  status: VerificationResult;
+  liveImage: string;
+  referenceImage?: string;
+  livenessScore: number;
+  faceMatchScore?: number;
+  challengeResults: ChallengeResult[];
+  timestamp: number;
+  sessionDuration: number;
+  antiSpoofingChecks: Record<string, boolean>;
+}
+
+export type BiometricMode = 'LIVENESS' | 'IDENTITY';
+
+export interface VoiceOptions {
+  enabled?: boolean;
+  language?: string;
+  rate?: number; // 0..1
+  volume?: number; // 0..1 (best-effort; platform dependent)
+}
+
+export interface BiometricEngineConfig {
+  apiKey: string;
+  referenceImage?: string;
+  mode?: BiometricMode;
+  voiceOptions?: VoiceOptions;
+  autoStart?: boolean;
+  challengeTimeout?: number;
+  sessionTimeout?: number;
+  onResult?: (payload: VerificationPayload) => void;
+  onStatusChange?: (status: VerificationStatus) => void;
+}
+
+// ==================== CHALLENGE DEFINITIONS ====================
+
+const CHALLENGE_INSTRUCTIONS: Record<ChallengeType, string> = {
+  FACE_THE_CAMERA: 'Please face the camera directly',
+  BLINK_ONCE: 'Blink once',
+  BLINK_TWICE: 'Blink twice',
+  SMILE: 'Smile for the camera',
+  TURN_HEAD_LEFT: 'Turn your head to the left',
+  TURN_HEAD_RIGHT: 'Turn your head to the right',
+  LOOK_UP: 'Look up',
+  LOOK_DOWN: 'Look down',
+  RAISE_EYEBROWS: 'Raise your eyebrows',
+  NOD_HEAD: 'Nod your head',
+  SHAKE_HEAD: 'Shake your head left and right',
+  OPEN_MOUTH: 'Open your mouth',
+  CLOSE_EYES_BRIEFLY: 'Close your eyes briefly',
+};
+
+const OPTIONAL_CHALLENGES: ChallengeType[] = [
+  'BLINK_ONCE',
+  'BLINK_TWICE',
+  'SMILE',
+  'TURN_HEAD_LEFT',
+  'TURN_HEAD_RIGHT',
+  'LOOK_UP',
+  'LOOK_DOWN',
+  'RAISE_EYEBROWS',
+  'NOD_HEAD',
+  'SHAKE_HEAD',
+  'OPEN_MOUTH',
+  'CLOSE_EYES_BRIEFLY',
+];
+
+// ==================== VERIFICATION SERVICE LAYER ====================
+
+class VerificationService {
+  private apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async verifyLiveness(
+    _liveImage: string,
+    challengeResults: ChallengeResult[]
+  ): Promise<{ score: number; passed: boolean }> {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        const passedChallenges = challengeResults.filter(
+          (r) => r.status === 'PASS'
+        ).length;
+        const score =
+          (passedChallenges / Math.max(1, challengeResults.length)) * 100;
+        resolve({
+          score: Math.round(score),
+          passed: passedChallenges >= 2,
+        });
+      }, 500);
+    });
+  }
+
+  async verifyIdentity(
+    _liveImage: string,
+    _referenceImage: string
+  ): Promise<{ score: number; passed: boolean }> {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        const score = Math.random() * 100;
+        resolve({ score: Math.round(score), passed: score > 70 });
+      }, 500);
+    });
+  }
+
+  getApiKey(): string {
+    return this.apiKey;
+  }
+}
+
+// ==================== UTILITY FUNCTIONS ====================
+
+function getRandomChallenges(count: number): ChallengeType[] {
+  const shuffled = [...OPTIONAL_CHALLENGES].sort(() => Math.random() - 0.5);
+  return shuffled.slice(0, count);
+}
+
+function buildChallengeSequence(): ChallengeType[] {
+  return ['FACE_THE_CAMERA', ...getRandomChallenges(2)];
+}
+
+async function speakGuidance(
+  text: string,
+  opts: VoiceOptions = { enabled: true, rate: 0.85 }
+): Promise<void> {
+  if (!opts?.enabled) return;
+  try {
+    if (opts.language) {
+      // best-effort; may not exist on all platforms
+      // @ts-ignore
+      await RNTts.setDefaultLanguage?.(opts.language);
+    }
+    if (typeof opts.rate === 'number') {
+      await RNTts.setDefaultRate?.(opts.rate);
+    }
+    await RNTts.speak(text);
+  } catch (error) {
+    logger.debug('BiometricEngine', { ttsError: error });
+  }
+}
+
+// ==================== MOCK OPENCV ====================
+
+const OpenCV = {
+  frameBufferToMat: (
+    _height: number,
+    _width: number,
+    _channels: number,
+    _buffer: unknown
+  ) => ({}),
+  createObject: () => ({}),
+  invoke: (..._args: unknown[]) => {},
+  toJSValue: (_mat: unknown) => ({ rows: 0, cols: 0 }),
+  clearBuffers: () => {},
+};
+
+// ==================== MAIN BIOMETRIC ENGINE HOOK (HEADLESS) ====================
+
+export function useBiometricEngine(config: BiometricEngineConfig) {
+  const {
+    apiKey,
+    referenceImage: initialReferenceImage,
+    mode: initialMode = 'LIVENESS',
+    voiceOptions: initialVoiceOptions = { enabled: true, rate: 0.85 },
+    autoStart = false,
+    challengeTimeout = 15000,
+    sessionTimeout = 120000,
+    onResult,
+    onStatusChange,
+  } = config;
+
+  const { resize } = useResizePlugin();
+
+  logger.info('BiometricEngine', 'Initializing biometric engine (headless)');
+
+  // Core state
+  const [status, setStatus] = useState<VerificationStatus>('INITIALIZING');
+  const [currentChallenge, setCurrentChallenge] =
+    useState<ChallengeType | null>(null);
+  const [completedChallenges, setCompletedChallenges] = useState<
+    ChallengeResult[]
+  >([]);
+  const [progress, setProgress] = useState(0);
+  const [countdownTime, setCountdownTime] = useState(0);
+  const [verificationStatus, setVerificationStatus] =
+    useState('Initializing...');
+  const [running, setRunning] = useState(false);
+  const [paused, setPaused] = useState(false);
+
+  // References for performance
+  const verificationServiceRef = useRef(new VerificationService(apiKey));
+  const modeRef = useRef<BiometricMode>(initialMode);
+  const voiceOptionsRef = useRef<VoiceOptions>(initialVoiceOptions);
+  const referenceImageRef = useRef<string | undefined>(initialReferenceImage);
+  const challengeSequenceRef = useRef<ChallengeType[]>([]);
+  const sessionStartRef = useRef<number>(Date.now());
+  const currentChallengeStartRef = useRef<number>(Date.now());
+  const liveImageRef = useRef<string>('');
+  const faceQualityRef = useRef<FaceQualityMetrics>({
+    isDetected: false,
+    faceCount: 0,
+    isCentered: false,
+    isProperlyLit: false,
+    faceSize: 0,
+    sharpness: 0,
+    angularDeviation: 0,
+    occlusion: 0,
+    quality: 0,
+  });
+
+  // ==================== CALLBACKS ====================
+
+  const updateStatus = useCallback(
+    (newStatus: VerificationStatus, message: string) => {
+      setStatus(newStatus);
+      setVerificationStatus(message);
+      logger.info('BiometricEngine', { newStatus, message });
+      onStatusChange?.(newStatus);
+      speakGuidance(message, voiceOptionsRef.current);
+    },
+    [onStatusChange]
+  );
+
+  const initializeSession = useCallback(() => {
+    challengeSequenceRef.current = buildChallengeSequence();
+    sessionStartRef.current = Date.now();
+    setCompletedChallenges([]);
+    setProgress(0);
+    logger.debug('BiometricEngine', {
+      challengeSequence: challengeSequenceRef.current,
+    });
+    updateStatus('FACE_DETECTION', 'Position your face in the camera');
+  }, [updateStatus]);
+
+  const startNextChallenge = useCallback(() => {
+    if (!running || paused) return;
+
+    if (completedChallenges.length >= challengeSequenceRef.current.length) {
+      updateStatus('VERIFYING', 'Verifying your identity...');
+      return;
+    }
+
+    const nextChallenge =
+      challengeSequenceRef.current[completedChallenges.length];
+    if (nextChallenge) {
+      setCurrentChallenge(nextChallenge);
+      currentChallengeStartRef.current = Date.now();
+      setCountdownTime(Math.ceil(challengeTimeout / 1000));
+
+      const instruction = CHALLENGE_INSTRUCTIONS[nextChallenge];
+      logger.info('BiometricEngine', {
+        startingChallenge: nextChallenge,
+        instruction,
+      });
+      updateStatus('CHALLENGE_IN_PROGRESS', instruction);
+    }
+  }, [
+    completedChallenges.length,
+    challengeTimeout,
+    updateStatus,
+    running,
+    paused,
+  ]);
+
+  const completeChallenge = useCallback(
+    (challengeResult: ChallengeResult) => {
+      setCompletedChallenges((prev) => {
+        const updated = [...prev, challengeResult];
+        logger.info('BiometricEngine', {
+          challengeCompleted: challengeResult,
+          updatedChallengesCount: updated.length,
+        });
+        return updated;
+      });
+
+      const newProgress =
+        ((completedChallenges.length + 1) /
+          Math.max(1, challengeSequenceRef.current.length)) *
+        100;
+      setProgress(Math.round(newProgress));
+
+      if (
+        completedChallenges.length + 1 >=
+        challengeSequenceRef.current.length
+      ) {
+        logger.debug(
+          'BiometricEngine',
+          'All challenges completed, advancing to verification'
+        );
+        startNextChallenge();
+      } else {
+        setTimeout(() => startNextChallenge(), 1000);
+      }
+    },
+    [completedChallenges.length, startNextChallenge]
+  );
+
+  const failChallenge = useCallback(
+    (reason: string) => {
+      if (!currentChallenge) return;
+
+      const failureResult: ChallengeResult = {
+        challenge: currentChallenge,
+        status: 'FAIL',
+        timestamp: Date.now(),
+        duration: Date.now() - currentChallengeStartRef.current,
+        confidence: 0,
+        failureReason: reason,
+      };
+
+      logger.warn('BiometricEngine', { failedChallenge: failureResult });
+      completeChallenge(failureResult);
+    },
+    [currentChallenge, completeChallenge]
+  );
+
+  const timeoutChallenge = useCallback(() => {
+    if (!currentChallenge) return;
+
+    const timeoutResult: ChallengeResult = {
+      challenge: currentChallenge,
+      status: 'TIMEOUT',
+      timestamp: Date.now(),
+      duration: challengeTimeout,
+      confidence: 0,
+      failureReason: 'Challenge timeout exceeded',
+    };
+
+    logger.warn('BiometricEngine', { timeoutResult });
+    completeChallenge(timeoutResult);
+  }, [currentChallenge, challengeTimeout, completeChallenge]);
+
+  const finishVerification = useCallback(
+    async (result: VerificationResult) => {
+      logger.info('BiometricEngine', { finishing: result });
+      const sessionDuration = Date.now() - sessionStartRef.current;
+
+      const payload: VerificationPayload = {
+        status: result,
+        liveImage: liveImageRef.current,
+        livenessScore: Math.round(Math.random() * 100),
+        challengeResults: completedChallenges,
+        timestamp: Date.now(),
+        sessionDuration,
+        antiSpoofingChecks: {
+          staticImageDetection: true,
+          printedPhotoDetection: true,
+          screenReplayDetection: true,
+          videoReplayDetection: true,
+          multiFaceDetection: true,
+          faceOcclusionDetection: true,
+          abnormalMotionDetection: true,
+        },
+      };
+
+      if (referenceImageRef.current) {
+        payload.referenceImage = referenceImageRef.current;
+        payload.faceMatchScore = Math.round(Math.random() * 100);
+      }
+
+      updateStatus(
+        'COMPLETED',
+        result === 'PASS' ? 'Verification successful!' : 'Verification failed'
+      );
+      logger.info('BiometricEngine', {
+        payloadSummary: {
+          status: payload.status,
+          livenessScore: payload.livenessScore,
+          challengeCount: payload.challengeResults.length,
+        },
+      });
+      onResult?.(payload);
+      setRunning(false);
+    },
+    [completedChallenges, updateStatus, onResult]
+  );
+
+  const frameProcessor = useCallback(
+    (frame: Frame) => {
+      'worklet';
+
+      try {
+        // Process frame through resize plugin
+        resize(frame, {
+          scale: { width: 160, height: 120 },
+          pixelFormat: 'bgr',
+          dataType: 'uint8',
+        });
+
+        // Mock face quality detection
+        const quality = Math.random() * 100;
+        faceQualityRef.current = {
+          isDetected: quality > 20,
+          faceCount: quality > 20 ? 1 : 0,
+          isCentered: quality > 60,
+          isProperlyLit: quality > 40,
+          faceSize: quality / 100,
+          sharpness: quality,
+          angularDeviation: Math.random() * 30,
+          occlusion: Math.random() * 20,
+          quality: Math.max(0, quality - 10),
+        };
+
+        logger.debug('BiometricEngine', {
+          faceQuality: faceQualityRef.current,
+        });
+
+        OpenCV.clearBuffers();
+      } catch (error) {
+        logger.error('BiometricEngine', { frameProcessorError: error });
+      }
+    },
+    [resize]
+  );
+
+  // ==================== EFFECTS ====================
+
+  // Countdown timer effect
+  useEffect(() => {
+    if (countdownTime <= 0 || status !== 'CHALLENGE_IN_PROGRESS' || paused)
+      return;
+
+    const timer = setInterval(() => {
+      setCountdownTime((prev) => {
+        if (prev <= 1) {
+          timeoutChallenge();
+          return 0;
+        }
+        return prev - 1;
+      });
+    }, 1000);
+
+    return () => clearInterval(timer);
+  }, [countdownTime, status, paused, timeoutChallenge]);
+
+  // Session timeout effect
+  useEffect(() => {
+    if (!running) return;
+    const sessionTimer = setTimeout(() => {
+      if (status !== 'COMPLETED') {
+        updateStatus('COMPLETED', 'Session timeout exceeded');
+        finishVerification('TIMEOUT');
+      }
+    }, sessionTimeout);
+
+    return () => clearTimeout(sessionTimer);
+  }, [status, sessionTimeout, updateStatus, finishVerification, running]);
+
+  // Auto-start if requested
+  useEffect(() => {
+    if (autoStart) startVerification();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // ==================== HEADLESS CONTROLS ====================
+
+  const startVerification = useCallback(() => {
+    if (running) return;
+    setRunning(true);
+    setPaused(false);
+    initializeSession();
+  }, [initializeSession, running]);
+
+  const pauseVerification = useCallback(() => {
+    setPaused(true);
+    updateStatus('PAUSED', 'Verification paused');
+  }, [updateStatus]);
+
+  const resumeVerification = useCallback(() => {
+    setPaused(false);
+    updateStatus('FACE_DETECTION', 'Resuming verification');
+  }, [updateStatus]);
+
+  const cancelVerification = useCallback(() => {
+    setRunning(false);
+    setPaused(false);
+    updateStatus('COMPLETED', 'Verification cancelled');
+  }, [updateStatus]);
+
+  const restartSession = useCallback(() => {
+    setRunning(false);
+    setPaused(false);
+    initializeSession();
+  }, [initializeSession]);
+
+  const retryChallenge = useCallback((index?: number) => {
+    setCompletedChallenges((prev) => {
+      if (prev.length === 0) return prev;
+      const newCompleted = [...prev];
+      if (typeof index === 'number') newCompleted.splice(index, 1);
+      else newCompleted.pop();
+      return newCompleted;
+    });
+  }, []);
+
+  const retryVerification = useCallback(() => {
+    setCompletedChallenges([]);
+    setProgress(0);
+    initializeSession();
+  }, [initializeSession]);
+
+  const setVoiceOptions = useCallback((opts: VoiceOptions) => {
+    voiceOptionsRef.current = { ...voiceOptionsRef.current, ...opts };
+  }, []);
+
+  const setMode = useCallback((m: BiometricMode) => {
+    modeRef.current = m;
+  }, []);
+
+  const setReferenceImage = useCallback((img?: string) => {
+    referenceImageRef.current = img;
+  }, []);
+
+  // ==================== RETURN VALUE (HEADLESS API) ====================
+
+  return {
+    // Status and state
+    verificationStatus,
+    status,
+    running,
+    paused,
+    progress,
+    countdownTime,
+    currentChallenge,
+    completedChallenges,
+
+    // Challenge sequence
+    totalChallenges: challengeSequenceRef.current.length,
+    challengeSequence: challengeSequenceRef.current,
+
+    // Frame processing (for Camera component)
+    frameProcessor,
+
+    // Challenge control
+    completeChallenge,
+    failChallenge,
+    startNextChallenge,
+
+    // Face quality
+    faceQuality: faceQualityRef.current,
+
+    // Verification
+    finishVerification,
+    setLiveImage: (image: string) => {
+      liveImageRef.current = image;
+    },
+
+    // Headless controls
+    startVerification,
+    pauseVerification,
+    resumeVerification,
+    cancelVerification,
+    restartSession,
+    retryChallenge,
+    retryVerification,
+
+    // Configuration
+    setVoiceOptions,
+    setMode,
+    setReferenceImage,
+
+    // Session info
+    sessionStartedAt: sessionStartRef.current,
+    sessionDuration: Date.now() - sessionStartRef.current,
+
+    // Service access for advanced use
+    verificationService: verificationServiceRef.current,
+  };
+}