@trustchex/react-native-sdk 1.374.0 → 1.381.0

package/src/Shared/Components/IdentityDocumentCamera.flows.ts

@@ -0,0 +1,342 @@
+/**
+ * Document scanning flow handlers
+ *
+ * This file contains the logic for handling different document type flows:
+ *
+ * KEY DISTINGUISHING FEATURES:
+ * =============================
+ * PASSPORT: Has MRZ on FRONT with pattern P<XXX (e.g., P<TUR, P<USA)
+ * ID CARD:  Has NO MRZ on front; MRZ only on BACK with code 'I'
+ *
+ * IMPORTANT: Both passports and ID cards have signature sections!
+ * Signature presence is NOT a distinguishing feature between document types.
+ * The ONLY reliable distinguisher is the passport MRZ pattern (P<XXX).
+ *
+ * PASSPORT FLOW:
+ *   1. SCAN_ID_FRONT_OR_PASSPORT: Detect face + MRZ with code 'P' (passport MRZ pattern)
+ *   2. SCAN_HOLOGRAM (optional, skipped if onlyMRZScan): Collect hologram images
+ *   3. COMPLETED: No back side for passports
+ *
+ * ID CARD FLOW:
+ *   1. SCAN_ID_FRONT_OR_PASSPORT: Detect face + NO passport MRZ pattern
+ *   2. SCAN_HOLOGRAM: Collect hologram images from front
+ *   3. SCAN_ID_BACK: Detect MRZ with code 'I' + barcode
+ *   4. COMPLETED
+ *
+ * ID BACK DETECTION:
+ *   - Only occurs during SCAN_ID_BACK step
+ *   - No face, has MRZ with code 'I'
+ */
+
+import type { Face } from './IdentityDocumentCamera.types';
+import type { MRZFields } from '../Types/mrzFields';
+import { PASSPORT_MRZ_PATTERN } from './IdentityDocumentCamera.constants';
+import { debugLog, isDebugEnabled } from '../Libs/debug.utils';
+
+/**
+ * After this many retry attempts for ID_FRONT flow, proceed with face detection alone
+ * even if signature text OCR fails. This prevents blocking users due to OCR limitations.
+ */
+const SIGNATURE_RETRY_THRESHOLD = 10;
+
+export interface PassportFlowResult {
+  shouldProceed: boolean;
+  reason?: string;
+  nextAction?:
+    | 'WAIT_FOR_ELEMENTS'
+    | 'WAIT_FOR_MRZ'
+    | 'PROCEED_TO_HOLOGRAM'
+    | 'PROCEED_TO_COMPLETED';
+}
+
+export interface IDFrontFlowResult {
+  shouldProceed: boolean;
+  reason?: string;
+  nextAction?:
+    | 'WAIT_FOR_ELEMENTS'
+    | 'REJECT_AS_PASSPORT'
+    | 'PROCEED_TO_HOLOGRAM';
+}
+
+export interface IDBackFlowResult {
+  shouldProceed: boolean;
+  reason?: string;
+  nextAction?: 'WAIT_FOR_MRZ' | 'WAIT_FOR_BARCODE' | 'PROCEED_TO_COMPLETED';
+}
+
+/**
+ * Handle PASSPORT flow during SCAN_ID_FRONT_OR_PASSPORT step
+ *
+ * Requirements:
+ * - Face must be detected AND captured
+ * - MRZ must be present with document code 'P'
+ * - MRZ must be stable (consistent reads) even in normal mode
+ * - All required MRZ fields must be present
+ */
+export function handlePassportFlow(
+  faces: Face[],
+  mrzText: string | null,
+  mrzFields: MRZFields | undefined,
+  mrzStableAndValid: boolean,
+  onlyMRZScan: boolean,
+  hasRequiredFields: boolean,
+  faceCaptured: boolean
+): PassportFlowResult {
+  const hasFace = faces.length > 0;
+  const hasMRZ = !!mrzText;
+
+  // Check all required elements are in frame
+  if (!hasFace || !hasMRZ) {
+    return {
+      shouldProceed: false,
+      reason: 'Waiting for face + MRZ in frame',
+      nextAction: 'WAIT_FOR_ELEMENTS',
+    };
+  }
+
+  // Verify MRZ definitively identifies this as passport
+  if (!mrzFields?.documentCode || mrzFields.documentCode !== 'P') {
+    return {
+      shouldProceed: false,
+      reason: `MRZ not confirmed as passport (code: ${mrzFields?.documentCode || 'none'})`,
+      nextAction: 'WAIT_FOR_MRZ',
+    };
+  }
+
+  // Check required MRZ fields
+  if (!hasRequiredFields) {
+    return {
+      shouldProceed: false,
+      reason: 'Waiting for complete MRZ fields',
+      nextAction: 'WAIT_FOR_MRZ',
+    };
+  }
+
+  // Check MRZ stability - required for both modes
+  if (!mrzStableAndValid) {
+    return {
+      shouldProceed: false,
+      reason: 'Waiting for stable MRZ reads',
+      nextAction: 'WAIT_FOR_MRZ',
+    };
+  }
+
+  // For onlyMRZScan mode, skip face capture and hologram
+  if (onlyMRZScan) {
+    return {
+      shouldProceed: true,
+      reason: 'Passport MRZ validated',
+      nextAction: 'PROCEED_TO_COMPLETED',
+    };
+  }
+
+  // Normal mode: ensure face is captured before proceeding to hologram
+  if (!faceCaptured) {
+    return {
+      shouldProceed: false,
+      reason: 'Waiting for face to be captured',
+      nextAction: 'WAIT_FOR_ELEMENTS',
+    };
+  }
+
+  // All requirements met - proceed to hologram
+  return {
+    shouldProceed: true,
+    reason: 'Passport confirmed with face and valid MRZ',
+    nextAction: 'PROCEED_TO_HOLOGRAM',
+  };
+}
+
+/**
+ * Handle ID CARD FRONT flow during SCAN_ID_FRONT_OR_PASSPORT step
+ *
+ * CRITICAL: The KEY distinguishing feature is the ABSENCE of passport MRZ pattern.
+ * Both passports and ID cards have signatures, so signature is NOT used to distinguish
+ * between document types. Signature is only checked to ensure we're viewing the front
+ * side of the document (not the back).
+ *
+ * Requirements:
+ * - Face must be detected (front side indicator)
+ * - Must NOT have passport MRZ pattern (P<XXX) - this is the CRITICAL check
+ * - Signature text should be present (confirms front side, or retry threshold reached)
+ * - If MRZ code is present, it must be 'I' (ID card) not 'P' (passport)
+ */
+export function handleIDFrontFlow(
+  faces: Face[],
+  text: string,
+  mrzText: string | null,
+  mrzFields: MRZFields | undefined,
+  retryCount: number
+): IDFrontFlowResult {
+  // ============================================================================
+  // STEP 1: Check for PASSPORT MRZ pattern - THE CRITICAL DISTINGUISHER
+  // ============================================================================
+  // If passport MRZ pattern (P<XXX) is detected, this is a PASSPORT not an ID card
+  // This check must happen FIRST before any other validation
+
+  if (mrzFields?.documentCode === 'P') {
+    // Parsed MRZ shows passport code
+    return {
+      shouldProceed: false,
+      reason: 'Detected as ID_FRONT but MRZ shows passport (code P)',
+      nextAction: 'REJECT_AS_PASSPORT',
+    };
+  }
+
+  if (mrzText && PASSPORT_MRZ_PATTERN.test(mrzText)) {
+    // Passport MRZ pattern visible even if not fully parsed
+    return {
+      shouldProceed: false,
+      reason: 'Passport MRZ pattern visible - not an ID card',
+      nextAction: 'REJECT_AS_PASSPORT',
+    };
+  }
+
+  // ============================================================================
+  // STEP 2: Verify face present (confirms we're viewing front side)
+  // ============================================================================
+  const hasFace = faces.length > 0;
+  if (!hasFace) {
+    return {
+      shouldProceed: false,
+      reason: 'Waiting for face detection (front side)',
+      nextAction: 'WAIT_FOR_ELEMENTS',
+    };
+  }
+
+  // ============================================================================
+  // STEP 3: Check for signature (optional front side confirmation)
+  // ============================================================================
+  // Note: Both passports and ID cards have signatures! This is NOT used to
+  // distinguish document types. It only confirms we're viewing the front side.
+  // After retry threshold, we proceed with face alone (signature OCR may fail).
+  const hasSignature = /signature|imza|İmza/i.test(text);
+  const allowFaceOnly = retryCount > SIGNATURE_RETRY_THRESHOLD;
+
+  if (!hasSignature && !allowFaceOnly) {
+    return {
+      shouldProceed: false,
+      reason: 'Waiting for signature text (front side confirmation)',
+      nextAction: 'WAIT_FOR_ELEMENTS',
+    };
+  }
+
+  // ============================================================================
+  // STEP 4: Final MRZ code check (if present, must be 'I' not 'P')
+  // ============================================================================
+  // ID cards should NOT have MRZ on front, but if detected, verify it's not passport
+  if (mrzFields?.documentCode && mrzFields.documentCode !== 'I') {
+    return {
+      shouldProceed: false,
+      reason: `MRZ shows unexpected document code: ${mrzFields.documentCode}`,
+      nextAction: 'REJECT_AS_PASSPORT',
+    };
+  }
+
+  return {
+    shouldProceed: true,
+    reason: 'ID card front validated',
+    nextAction: 'PROCEED_TO_HOLOGRAM',
+  };
+}
+
+/**
+ * Handle ID CARD BACK flow during SCAN_ID_BACK step
+ *
+ * Requirements:
+ * - MRZ must be present, valid, stable, and have all required fields
+ * - Barcode must be in frame (unless onlyMRZScan)
+ * - Barcode must match MRZ optional1 serial number (lenient comparison)
+ */
+export function handleIDBackFlow(
+  mrzText: string | null,
+  mrzFields: MRZFields | undefined,
+  mrzValid: boolean,
+  mrzStableAndValid: boolean,
+  hasRequiredFields: boolean,
+  barcodeValue: string | undefined,
+  onlyMRZScan: boolean
+): IDBackFlowResult {
+  const hasMRZ = !!mrzText;
+  const hasBarcode = !!barcodeValue;
+
+  // Both MRZ and barcode must be in frame (unless MRZ-only mode)
+  if (!hasMRZ || (!hasBarcode && !onlyMRZScan)) {
+    return {
+      shouldProceed: false,
+      reason: !hasMRZ ? 'Waiting for MRZ' : 'Waiting for barcode in frame',
+      nextAction: !hasMRZ ? 'WAIT_FOR_MRZ' : 'WAIT_FOR_BARCODE',
+    };
+  }
+
+  // MRZ validation: valid checksum + required fields + stable reads
+  const mrzAccepted = mrzValid && hasRequiredFields && mrzStableAndValid;
+  if (!mrzAccepted) {
+    return {
+      shouldProceed: false,
+      reason: !hasRequiredFields
+        ? 'Incomplete MRZ fields'
+        : !mrzValid
+          ? 'MRZ checksum invalid'
+          : 'Waiting for stable MRZ',
+      nextAction: 'WAIT_FOR_MRZ',
+    };
+  }
+
+  // In MRZ-only mode, skip barcode cross-validation
+  if (onlyMRZScan) {
+    return {
+      shouldProceed: true,
+      reason: 'MRZ validated (MRZ-only mode)',
+      nextAction: 'PROCEED_TO_COMPLETED',
+    };
+  }
+
+  // Validate barcode matches MRZ optional1 (serial number)
+  // Accept exact match OR partial containment (handles encoding differences)
+  const trimmedBarcode = barcodeValue?.trim() || '';
+  const trimmedOptional1 = mrzFields?.optional1?.trim() || '';
+  const barcodeAccepted =
+    trimmedBarcode === trimmedOptional1 ||
+    (!!trimmedBarcode &&
+      (trimmedBarcode.includes(trimmedOptional1) ||
+        trimmedOptional1.includes(trimmedBarcode)));
+
+  if (!barcodeAccepted) {
+    return {
+      shouldProceed: false,
+      reason: 'Barcode does not match MRZ optional1',
+      nextAction: 'WAIT_FOR_BARCODE',
+    };
+  }
+
+  return {
+    shouldProceed: true,
+    reason: 'ID card back validated',
+    nextAction: 'PROCEED_TO_COMPLETED',
+  };
+}
+
+/**
+ * Determine next step after SCAN_HOLOGRAM based on document type
+ *
+ * PASSPORT: → COMPLETED (no back side)
+ * ID CARD: → SCAN_ID_BACK
+ */
+export function getNextStepAfterHologram(
+  detectedDocumentType: 'ID_FRONT' | 'ID_BACK' | 'PASSPORT' | 'UNKNOWN',
+  currentFrameDocType: 'ID_FRONT' | 'ID_BACK' | 'PASSPORT' | 'UNKNOWN',
+  mrzDocCode: string | undefined
+): 'COMPLETED' | 'SCAN_ID_BACK' {
+  // Check multiple sources to determine if it's a passport
+  const isPassport =
+    detectedDocumentType === 'PASSPORT' ||
+    currentFrameDocType === 'PASSPORT' ||
+    mrzDocCode === 'P';
+
+  if (isPassport) {
+    return 'COMPLETED';
+  }
+
+  return 'SCAN_ID_BACK';
+}