@trustchex/react-native-sdk 1.355.1 → 1.357.0

package/ios/MRZValidation.swift

@@ -0,0 +1,802 @@
+import Foundation
+import React
+
+/**
+ * Native MRZ Validation Module for iOS
+ *
+ * Performs high-performance MRZ detection and validation with checksum verification
+ * according to ICAO 9303 standards. This native implementation is significantly faster
+ * than JavaScript parsing, especially for real-time camera frame processing.
+ *
+ * ICAO 9303 Compliance:
+ * - TD1: Identity cards (3 lines × 30 characters)
+ * - TD2: Identity cards (2 lines × 36 characters)  
+ * - TD3: Passports (2 lines × 44 characters)
+ * - Check digit algorithm: 7-3-1 weighted modulo 10
+ * - Character values: 0-9 = 0-9, A-Z = 10-35, < = 0
+ * - Validates: document number, birth date, expiry date, optional/personal number, composite checksums
+ *
+ * Key features:
+ * - Native checksum calculation (7-3-1 algorithm)
+ * - MRZ format detection (TD1, TD2, TD3)
+ * - Field extraction and validation
+ * - OCR correction with position-aware character mapping
+ * - Composite checksum brute-force correction
+ *
+ * @see https://www.icao.int/publications/Documents/9303_p3_cons_en.pdf
+ */
+@objc(MRZValidation)
+class MRZValidation: NSObject {
+  
+  enum MRZFormat: String {
+    case TD1 = "TD1"    // ID card, 3 lines of 30 chars
+    case TD2 = "TD2"    // ID card, 2 lines of 36 chars
+    case TD3 = "TD3"    // Passport, 2 lines of 44 chars
+    case UNKNOWN = "UNKNOWN"
+  }
+  
+  /**
+   * Primary MRZ validation with OCR corrections and composite checksum brute-force
+   * This is the main entry point for fast native processing
+   */
+  @objc
+  func validateMRZWithCorrections(_ ocrText: String, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+    do {
+      // Fix and clean raw OCR text
+      let fixedText = fixMRZ(ocrText)
+      var lines = fixedText.trimmingCharacters(in: .whitespacesAndNewlines)
+        .components(separatedBy: "\n")
+        .map { $0.trimmingCharacters(in: .whitespaces) }
+      
+      if lines.isEmpty || fixedText.count < 60 {
+        resolve(createInvalidResult(error: "MRZ text too short"))
+        return
+      }
+
+      let format = detectMRZFormat(lines)
+      guard format != .UNKNOWN else {
+        resolve(createInvalidResult(error: "Unknown MRZ format"))
+        return
+      }
+
+      // Phase 1: Try parsing with position-aware OCR corrections
+      print("[MRZ Debug] Phase 1: Attempting position-aware OCR corrections")
+      var result = try parseMRZ(fixedText)
+      if let valid = result["valid"] as? Bool, valid == true {
+        print("[MRZ Debug] Phase 1: Valid MRZ found via position-aware corrections")
+        resolve(result)
+        return
+      }
+
+      // Phase 2: Try composite checksum brute-force if only composite is invalid
+      if let checksums = result["checksums"] as? [String: Any],
+         let invalidFields = checksums["invalidFields"] as? [String],
+         invalidFields.count == 1,
+         invalidFields[0] == "compositeCheckDigit" {
+        
+        print("[MRZ Debug] Phase 2: Attempting composite checksum brute-force")
+        
+        let compositePos: (line: Int, pos: Int)?
+        switch format {
+        case .TD1: compositePos = (1, 29)
+        case .TD2: compositePos = (1, 35)
+        case .TD3: compositePos = (1, 43)
+        case .UNKNOWN: compositePos = nil
+        }
+
+        if let pos = compositePos {
+          for digit in 0...9 {
+            var testLines = lines
+            let targetLine = testLines[pos.line]
+            let startIdx = targetLine.index(targetLine.startIndex, offsetBy: pos.pos)
+            let endIdx = targetLine.index(startIdx, offsetBy: 1)
+            var chars = Array(targetLine)
+            chars[pos.pos] = Character(String(digit))
+            testLines[pos.line] = String(chars)
+            
+            let testMRZ = testLines.joined(separator: "\n")
+            let testResult = try parseMRZ(testMRZ)
+            
+            if let valid = testResult["valid"] as? Bool, valid == true {
+              print("[MRZ Debug] Phase 2: Valid MRZ found via composite digit \(digit)")
+              resolve(testResult)
+              return
+            }
+          }
+        }
+      }
+
+      // Phase 3: Try O/0 permutations
+      print("[MRZ Debug] Phase 3: Attempting O/0 permutations")
+      let o0Permutations = generateO0Permutations(fixedText, maxPermutations: 100)
+      for (index, permutation) in o0Permutations.enumerated() {
+        let testResult = try parseMRZ(permutation)
+        if let valid = testResult["valid"] as? Bool, valid == true {
+          print("[MRZ Debug] Phase 3: Valid MRZ found via O/0 permutation \(index + 1)/\(o0Permutations.count)")
+          resolve(testResult)
+          return
+        }
+      }
+
+      // Phase 4: Try I/1 permutations as last resort
+      print("[MRZ Debug] Phase 4: Attempting I/1 permutations")
+      let i1Permutations = generateI1Permutations(fixedText, maxPermutations: 50)
+      for (index, permutation) in i1Permutations.enumerated() {
+        let testResult = try parseMRZ(permutation)
+        if let valid = testResult["valid"] as? Bool, valid == true {
+          print("[MRZ Debug] Phase 4: Valid MRZ found via I/1 permutation \(index + 1)/\(i1Permutations.count)")
+          resolve(testResult)
+          return
+        }
+      }
+
+      // Return invalid result if all attempts failed
+      print("[MRZ Debug] All correction phases failed")
+      resolve(result)
+    } catch {
+      reject("MRZ_VALIDATION_ERROR", "Failed to validate MRZ: \(error.localizedDescription)", error)
+    }
+  }
+  
+  /**
+   * Validates MRZ text and returns parse result with checksum validation
+   */
+  @objc
+  func validateMRZ(_ mrzText: String, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+    do {
+      let result = try parseMRZ(mrzText)
+      resolve(result)
+    } catch {
+      reject("MRZ_VALIDATION_ERROR", "Failed to validate MRZ: \(error.localizedDescription)", error)
+    }
+  }
+  
+  /**
+   * Create invalid result response
+   */
+  private func createInvalidResult(error: String) -> [String: Any] {
+    return [
+      "valid": false,
+      "error": error,
+      "format": "UNKNOWN"
+    ]
+  }
+  
+  /**
+   * Calculates checksum for MRZ field using 7-3-1 algorithm
+   */
+  @objc
+  func calculateChecksum(_ data: String, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+    do {
+      let checksum = try calculateMRZChecksum(data)
+      resolve(String(checksum))
+    } catch {
+      reject("CHECKSUM_ERROR", "Failed to calculate checksum: \(error.localizedDescription)", error)
+    }
+  }
+  
+  /**
+   * Fixes common OCR errors in MRZ text
+   */
+  @objc
+  func fixMRZText(_ mrzText: String, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+    do {
+      let fixed = fixMRZ(mrzText)
+      resolve(fixed)
+    } catch {
+      reject("MRZ_FIX_ERROR", "Failed to fix MRZ text: \(error.localizedDescription)", error)
+    }
+  }
+  
+  // MARK: - Private Methods
+  
+  /**
+   * Main MRZ parser - validates format and checksums
+   */
+  private func parseMRZ(_ rawText: String) throws -> [String: Any] {
+    var result: [String: Any] = [:]
+    let lines = rawText.trimmingCharacters(in: .whitespacesAndNewlines)
+      .components(separatedBy: "\n")
+      .map { $0.trimmingCharacters(in: .whitespaces) }
+    
+    // Detect format
+    let format = detectMRZFormat(lines)
+    result["format"] = format.rawValue
+    
+    guard format != .UNKNOWN else {
+      result["valid"] = false
+      result["error"] = "Unknown MRZ format"
+      return result
+    }
+    
+    // Parse based on format
+    let fields: [String: Any]
+    switch format {
+    case .TD1:
+      fields = try parseTD1(lines)
+    case .TD2:
+      fields = try parseTD2(lines)
+    case .TD3:
+      fields = try parseTD3(lines)
+    case .UNKNOWN:
+      result["valid"] = false
+      result["error"] = "Unsupported format"
+      return result
+    }
+    
+    result["fields"] = fields
+    
+    // Validate all checksums
+    let checksumValidation = try validateChecksums(format: format, lines: lines)
+    result["valid"] = checksumValidation["allValid"] as? Bool ?? false
+    result["checksums"] = checksumValidation
+    
+    return result
+  }
+  
+  /**
+   * Detects MRZ format from line structure
+   */
+  private func detectMRZFormat(_ lines: [String]) -> MRZFormat {
+    if lines.count == 3 && lines.allSatisfy({ $0.count == 30 }) {
+      return .TD1
+    } else if lines.count == 2 && lines.allSatisfy({ $0.count == 36 }) {
+      return .TD2
+    } else if lines.count == 2 && lines.allSatisfy({ $0.count == 44 }) {
+      return .TD3
+    }
+    return .UNKNOWN
+  }
+  
+  /**
+   * Parse TD1 format (ID card, 3 lines of 30 chars)
+   */
+  private func parseTD1(_ lines: [String]) throws -> [String: Any] {
+    guard lines.count >= 3 else {
+      throw NSError(domain: "MRZValidation", code: 1, userInfo: [NSLocalizedDescriptionKey: "Invalid TD1 format"])
+    }
+    
+    var fields: [String: Any] = [:]
+    
+    // Line 1
+    let line1 = lines[0]
+    fields["documentCode"] = String(line1.prefix(2)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["issuingState"] = String(line1.dropFirst(2).prefix(3)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["documentNumber"] = String(line1.dropFirst(5).prefix(9)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["documentNumberCheckDigit"] = String(line1.dropFirst(14).prefix(1))
+    fields["optional1"] = String(line1.dropFirst(15)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    
+    // Line 2
+    let line2 = lines[1]
+    fields["birthDate"] = String(line2.prefix(6))
+    fields["birthDateCheckDigit"] = String(line2.dropFirst(6).prefix(1))
+    fields["sex"] = String(line2.dropFirst(7).prefix(1))
+    fields["expirationDate"] = String(line2.dropFirst(8).prefix(6))
+    fields["expirationDateCheckDigit"] = String(line2.dropFirst(14).prefix(1))
+    fields["nationality"] = String(line2.dropFirst(15).prefix(3)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["optional2"] = String(line2.dropFirst(18).prefix(11)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["compositeCheckDigit"] = String(line2.dropFirst(29).prefix(1))
+    
+    // Line 3 - Names
+    let line3 = lines[2]
+    let names = line3.components(separatedBy: "<<")
+    fields["lastName"] = names[0].replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["firstName"] = names.count > 1 ? names[1].replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces) : ""
+    
+    return fields
+  }
+  
+  /**
+   * Parse TD2 format (ID card, 2 lines of 36 chars)
+   */
+  private func parseTD2(_ lines: [String]) throws -> [String: Any] {
+    guard lines.count >= 2 else {
+      throw NSError(domain: "MRZValidation", code: 1, userInfo: [NSLocalizedDescriptionKey: "Invalid TD2 format"])
+    }
+    
+    var fields: [String: Any] = [:]
+    
+    // Line 1
+    let line1 = lines[0]
+    fields["documentCode"] = String(line1.prefix(2)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["issuingState"] = String(line1.dropFirst(2).prefix(3)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    let names = String(line1.dropFirst(5)).components(separatedBy: "<<")
+    fields["lastName"] = names[0].replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["firstName"] = names.count > 1 ? names[1].replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces) : ""
+    
+    // Line 2
+    let line2 = lines[1]
+    fields["documentNumber"] = String(line2.prefix(9)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["documentNumberCheckDigit"] = String(line2.dropFirst(9).prefix(1))
+    fields["nationality"] = String(line2.dropFirst(10).prefix(3)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["birthDate"] = String(line2.dropFirst(13).prefix(6))
+    fields["birthDateCheckDigit"] = String(line2.dropFirst(19).prefix(1))
+    fields["sex"] = String(line2.dropFirst(20).prefix(1))
+    fields["expirationDate"] = String(line2.dropFirst(21).prefix(6))
+    fields["expirationDateCheckDigit"] = String(line2.dropFirst(27).prefix(1))
+    fields["optional1"] = String(line2.dropFirst(28).prefix(7)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["compositeCheckDigit"] = String(line2.dropFirst(35).prefix(1))
+    
+    return fields
+  }
+  
+  /**
+   * Parse TD3 format (Passport, 2 lines of 44 chars)
+   */
+  private func parseTD3(_ lines: [String]) throws -> [String: Any] {
+    guard lines.count >= 2 else {
+      throw NSError(domain: "MRZValidation", code: 1, userInfo: [NSLocalizedDescriptionKey: "Invalid TD3 format"])
+    }
+    
+    var fields: [String: Any] = [:]
+    
+    // Line 1
+    let line1 = lines[0]
+    fields["documentCode"] = String(line1.prefix(2)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["issuingState"] = String(line1.dropFirst(2).prefix(3)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    let names = String(line1.dropFirst(5)).components(separatedBy: "<<")
+    fields["lastName"] = names[0].replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["firstName"] = names.count > 1 ? names[1].replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces) : ""
+    
+    // Line 2
+    let line2 = lines[1]
+    fields["documentNumber"] = String(line2.prefix(9)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["documentNumberCheckDigit"] = String(line2.dropFirst(9).prefix(1))
+    fields["nationality"] = String(line2.dropFirst(10).prefix(3)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["birthDate"] = String(line2.dropFirst(13).prefix(6))
+    fields["birthDateCheckDigit"] = String(line2.dropFirst(19).prefix(1))
+    fields["sex"] = String(line2.dropFirst(20).prefix(1))
+    fields["expirationDate"] = String(line2.dropFirst(21).prefix(6))
+    fields["expirationDateCheckDigit"] = String(line2.dropFirst(27).prefix(1))
+    fields["optional1"] = String(line2.dropFirst(28).prefix(14)).replacingOccurrences(of: "<", with: " ").trimmingCharacters(in: .whitespaces)
+    fields["optional1CheckDigit"] = String(line2.dropFirst(42).prefix(1))
+    fields["compositeCheckDigit"] = String(line2.dropFirst(43).prefix(1))
+    
+    return fields
+  }
+  
+  /**
+   * Validates all checksums in MRZ according to ICAO 9303 Part 3
+   * 
+   * ICAO 9303 Check Digit Calculation:
+   * - Weights: 7, 3, 1 (cycling)
+   * - Character values: 0-9 = 0-9, A-Z = 10-35, < (filler) = 0
+   * - Result: (sum of weighted values) mod 10
+   * 
+   * @see https://www2023.icao.int/publications/Documents/9303_p3_cons_en.pdf Section 4.9
+   */
+  private func validateChecksums(format: MRZFormat, lines: [String]) throws -> [String: Any] {
+    var result: [String: Any] = [:]
+    var invalidFields: [String] = []
+    var allValid = true
+    
+    switch format {
+    case .TD1:
+      // TD1 Format (ID card, 3 lines × 30 characters)
+      // Line 1: Document code(2) + Issuing state(3) + Document number(9) + Check(1) + Optional(15)
+      // Line 2: Birth date(6) + Check(1) + Sex(1) + Expiry(6) + Check(1) + Nationality(3) + Optional(11) + Composite check(1)
+      // Line 3: Names
+      
+      let line1 = lines[0]
+      let line2 = lines[1]
+      
+      // Document number checksum - ICAO 9303 Part 3, Section 4.9
+      let docNum = String(line1.dropFirst(5).prefix(9))  // Positions 5-13
+      let docNumCheck = line1[line1.index(line1.startIndex, offsetBy: 14)]  // Position 14
+      let docNumValid = try calculateMRZChecksum(docNum) == docNumCheck
+      result["documentNumberCheckDigit"] = docNumValid
+      if !docNumValid {
+        invalidFields.append("documentNumberCheckDigit")
+        allValid = false
+      }
+      
+      // Birth date checksum
+      let birthDate = String(line2.prefix(6))  // Positions 0-5
+      let birthDateCheck = line2[line2.index(line2.startIndex, offsetBy: 6)]  // Position 6
+      let birthDateValid = try calculateMRZChecksum(birthDate) == birthDateCheck
+      result["birthDateCheckDigit"] = birthDateValid
+      if !birthDateValid {
+        invalidFields.append("birthDateCheckDigit")
+        allValid = false
+      }
+      
+      // Expiry date checksum
+      let expiryDate = String(line2.dropFirst(8).prefix(6))  // Positions 8-13
+      let expiryDateCheck = line2[line2.index(line2.startIndex, offsetBy: 14)]  // Position 14
+      let expiryDateValid = try calculateMRZChecksum(expiryDate) == expiryDateCheck
+      result["expirationDateCheckDigit"] = expiryDateValid
+      if !expiryDateValid {
+        invalidFields.append("expirationDateCheckDigit")
+        allValid = false
+      }
+      
+      // Composite checksum - ICAO 9303 Part 3, Section 4.9
+      // TD1 Composite = Line1(5-29) + Line2(0-6) + Line2(8-14) + Line2(18-28)
+      // This includes: doc number(9) + check(1) + optional(15) + birth(6) + check(1) + expiry(6) + check(1) + optional(11)
+      // Total: 50 characters
+      let composite = String(line1.dropFirst(5)) + String(line2.prefix(7)) + String(line2.dropFirst(8).prefix(7)) + String(line2.dropFirst(18).prefix(11))
+      let compositeCheck = line2[line2.index(line2.startIndex, offsetBy: 29)]  // Position 29
+      let compositeValid = try calculateMRZChecksum(composite) == compositeCheck
+      result["compositeCheckDigit"] = compositeValid
+      if !compositeValid {
+        invalidFields.append("compositeCheckDigit")
+        allValid = false
+      }
+      
+    case .TD2, .TD3:
+      // TD2 Format (ID card, 2 lines × 36 characters)
+      // Line 1: Document code(2) + Issuing state(3) + Names(31)
+      // Line 2: Doc number(9) + Check(1) + Nationality(3) + Birth(6) + Check(1) + Sex(1) + Expiry(6) + Check(1) + Optional(7) + Composite check(1)
+      //
+      // TD3 Format (Passport, 2 lines × 44 characters)  
+      // Line 1: Document code(2) + Issuing state(3) + Names(39)
+      // Line 2: Doc number(9) + Check(1) + Nationality(3) + Birth(6) + Check(1) + Sex(1) + Expiry(6) + Check(1) + Personal number(14) + Check(1) + Composite check(1)
+      
+      let line = lines[1]
+      
+      // Document number checksum - ICAO 9303 Part 3, Section 4.9
+      let docNum = String(line.prefix(9))  // Positions 0-8
+      let docNumCheck = line[line.index(line.startIndex, offsetBy: 9)]  // Position 9
+      let docNumValid = try calculateMRZChecksum(docNum) == docNumCheck
+      result["documentNumberCheckDigit"] = docNumValid
+      if !docNumValid {
+        invalidFields.append("documentNumberCheckDigit")
+        allValid = false
+      }
+      
+      // Birth date checksum
+      let birthDate = String(line.dropFirst(13).prefix(6))  // Positions 13-18
+      let birthDateCheck = line[line.index(line.startIndex, offsetBy: 19)]  // Position 19
+      let birthDateValid = try calculateMRZChecksum(birthDate) == birthDateCheck
+      result["birthDateCheckDigit"] = birthDateValid
+      if !birthDateValid {
+        invalidFields.append("birthDateCheckDigit")
+        allValid = false
+      }
+      
+      // Expiry date checksum
+      let expiryDate = String(line.dropFirst(21).prefix(6))  // Positions 21-26
+      let expiryDateCheck = line[line.index(line.startIndex, offsetBy: 27)]  // Position 27
+      let expiryDateValid = try calculateMRZChecksum(expiryDate) == expiryDateCheck
+      result["expirationDateCheckDigit"] = expiryDateValid
+      if !expiryDateValid {
+        invalidFields.append("expirationDateCheckDigit")
+        allValid = false
+      }
+      
+      // TD3 has personal number checksum (optional field)
+      if format == .TD3 {
+        let personalNum = String(line.dropFirst(28).prefix(14))  // Positions 28-41
+        let personalNumCheck = line[line.index(line.startIndex, offsetBy: 42)]  // Position 42
+        let personalNumValid = try calculateMRZChecksum(personalNum) == personalNumCheck
+        result["optional1CheckDigit"] = personalNumValid
+        if !personalNumValid {
+          invalidFields.append("optional1CheckDigit")
+          allValid = false
+        }
+      }
+      
+      // Composite checksum - ICAO 9303 Part 3, Section 4.9
+      // TD2: Doc number(9) + check(1) + Birth(6) + check(1) + Expiry(6) + check(1) + Optional(7) = 31 chars
+      // TD3: Doc number(9) + check(1) + Birth(6) + check(1) + Expiry(6) + check(1) + Personal(14) + check(1) = 39 chars
+      let compositeCheck = line[line.index(line.startIndex, offsetBy: format == .TD2 ? 35 : 43)]
+      let composite: String
+      if format == .TD2 {
+        // TD2: positions 0-9 + 13-19 + 21-34 (excluding composite at 35)
+        composite = String(line.prefix(10)) + String(line.dropFirst(13).prefix(7)) + String(line.dropFirst(21).prefix(14))
+      } else {
+        // TD3: positions 0-9 + 13-19 + 21-42 (excluding composite at 43)
+        composite = String(line.prefix(10)) + String(line.dropFirst(13).prefix(7)) + String(line.dropFirst(21).prefix(22))
+      }
+      let compositeValid = try calculateMRZChecksum(composite) == compositeCheck
+      result["compositeCheckDigit"] = compositeValid
+      if !compositeValid {
+        invalidFields.append("compositeCheckDigit")
+        allValid = false
+      }
+      
+    case .UNKNOWN:
+      break
+    }
+    
+    result["allValid"] = allValid
+    result["invalidFields"] = invalidFields
+    
+    return result
+  }
+  
+  /**
+   * Calculate MRZ checksum using 7-3-1 weighted algorithm per ICAO 9303
+   *
+   * ICAO 9303 Part 3, Section 4.9 - Check Digit Calculation:
+   *
+   * Algorithm:
+   * 1. Assign numerical values to characters:
+   *    - Digits 0-9: values 0-9
+   *    - Letters A-Z: values 10-35 (A=10, B=11, ..., Z=35)
+   *    - Filler character '<': value 0
+   *
+   * 2. Apply weights [7, 3, 1] cyclically to each character position
+   *
+   * 3. Calculate: sum = Σ(character_value × weight) for all positions
+   *
+   * 4. Check digit = sum mod 10
+   *
+   * Example: "AB2134<"
+   *   A(10)×7 + B(11)×3 + 2(2)×1 + 1(1)×7 + 3(3)×3 + 4(4)×1 + <(0)×7
+   *   = 70 + 33 + 2 + 7 + 9 + 4 + 0 = 125
+   *   Check digit = 125 mod 10 = 5
+   *
+   * @param data The string to calculate checksum for
+   * @return The check digit as a character ('0'-'9')
+   * @see https://www2023.icao.int/publications/Documents/9303_p3_cons_en.pdf
+   */
+  private func calculateMRZChecksum(_ data: String) throws -> Character {
+    let weights = [7, 3, 1]
+    var sum = 0
+    
+    for (index, char) in data.enumerated() {
+      let value: Int
+      switch char {
+      case "0"..."9":
+        value = Int(char.asciiValue! - Character("0").asciiValue!)
+      case "A"..."Z":
+        value = Int(char.asciiValue! - Character("A").asciiValue!) + 10
+      case "<":
+        value = 0
+      default:
+        value = 0
+      }
+      sum += value * weights[index % 3]
+    }
+    
+    let checksumDigit = sum % 10
+    return Character(String(checksumDigit))
+  }
+  
+  /**
+   * Fix common OCR errors in MRZ text with mrz-fast inspired corrections
+   */
+  private func fixMRZ(_ rawText: String) -> String {
+    var fixed = rawText
+      .replacingOccurrences(of: " ", with: "")
+      .replacingOccurrences(of: "«", with: "")
+    
+    // Remove invalid patterns
+    if let regex = try? NSRegularExpression(pattern: "<K+|r+K+|<r+K+", options: []) {
+      fixed = regex.stringByReplacingMatches(in: fixed, options: [], range: NSRange(fixed.startIndex..., in: fixed), withTemplate: "")
+    }
+    
+    // Fix common O/0 confusion in Turkish ID document numbers
+    if let regex = try? NSRegularExpression(pattern: "\\bI<TUR([A-Z0-9]{3})0([A-Z0-9]{6})\\b", options: []) {
+      fixed = regex.stringByReplacingMatches(in: fixed, options: [], range: NSRange(fixed.startIndex..., in: fixed), withTemplate: "I<TUR$1O$2")
+    }
+    
+    let lines = fixed.components(separatedBy: "\n")
+      .map { $0.trimmingCharacters(in: .whitespaces) }
+      .filter { $0.contains("<") }
+    
+    // Detect format and pad lines
+    let targetLength: Int
+    if lines.allSatisfy({ $0.count <= 30 }) {
+      targetLength = 30  // TD1
+    } else if lines.allSatisfy({ $0.count <= 36 }) {
+      targetLength = 36  // TD2
+    } else if lines.allSatisfy({ $0.count <= 44 }) {
+      targetLength = 44  // TD3
+    } else {
+      return rawText  // Cannot detect format
+    }
+    
+    let paddedLines = lines.map { line in
+      line.count < targetLength ? line.padding(toLength: targetLength, withPad: "<", startingAt: 0) : line
+    }
+    
+    return applyOCRCorrections(paddedLines.joined(separator: "\n"))
+  }
+  
+  /**
+   * Apply position-aware OCR corrections inspired by mrz-fast
+   * Character confusion mapping: O↔0, I↔1↔l, S↔5, B↔8, Z↔2, G↔6
+   */
+  private func applyOCRCorrections(_ mrzText: String) -> String {
+    var lines = mrzText.components(separatedBy: "\n")
+    if lines.isEmpty { return mrzText }
+    
+    let format = detectMRZFormat(lines)
+    if format == .UNKNOWN { return mrzText }
+    
+    switch format {
+    case .TD1:
+      // Line 2: positions 0-5 (birth date), 8-13 (expiry date), 6,14,29 (check digits)
+      lines[1] = correctDigitPositions(lines[1], ranges: [
+        0...5, 8...13  // Date fields need digits
+      ])
+      lines[1] = correctCheckDigitPositions(lines[1], positions: [6, 14, 29])
+      // Nationality (15-17) needs letters
+      lines[1] = correctLetterPositions(lines[1], ranges: [15...17])
+      
+    case .TD2:
+      // Line 2: positions 13-18 (birth), 21-26 (expiry), 9,19,27,35 (checks)
+      lines[1] = correctDigitPositions(lines[1], ranges: [
+        13...18, 21...26
+      ])
+      lines[1] = correctCheckDigitPositions(lines[1], positions: [9, 19, 27, 35])
+      // Nationality (10-12) needs letters
+      lines[1] = correctLetterPositions(lines[1], ranges: [10...12])
+      
+    case .TD3:
+      // Line 2: positions 13-18 (birth), 21-26 (expiry), 9,19,27,42 (checks)
+      lines[1] = correctDigitPositions(lines[1], ranges: [
+        13...18, 21...26
+      ])
+      lines[1] = correctCheckDigitPositions(lines[1], positions: [9, 19, 27, 42])
+      // Nationality (10-12) needs letters
+      lines[1] = correctLetterPositions(lines[1], ranges: [10...12])
+      
+    case .UNKNOWN:
+      break
+    }
+    
+    return lines.joined(separator: "\n")
+  }
+  
+  /**
+   * Correct positions that should contain digits (0-9)
+   */
+  private func correctDigitPositions(_ line: String, ranges: [ClosedRange<Int>]) -> String {
+    var corrected = Array(line)
+    ranges.forEach { range in
+      range.forEach { pos in
+        if pos < corrected.count {
+          let char = corrected[pos]
+          let replacement: Character
+          switch char {
+          case "O", "o": replacement = "0"
+          case "I", "l": replacement = "1"
+          case "Z": replacement = "2"
+          case "S": replacement = "5"
+          case "G": replacement = "6"
+          case "B": replacement = "8"
+          case "D", "Q": replacement = "0"
+          default: replacement = char
+          }
+          corrected[pos] = replacement
+        }
+      }
+    }
+    return String(corrected)
+  }
+  
+  /**
+   * Correct positions that should contain letters (A-Z) or <
+   */
+  private func correctLetterPositions(_ line: String, ranges: [ClosedRange<Int>]) -> String {
+    var corrected = Array(line)
+    ranges.forEach { range in
+      range.forEach { pos in
+        if pos < corrected.count {
+          let char = corrected[pos]
+          let replacement: Character
+          switch char {
+          case "0": replacement = "O"
+          case "1": replacement = "I"
+          case "5": replacement = "S"
+          case "8": replacement = "B"
+          case "2": replacement = "Z"
+          case "6": replacement = "G"
+          default: replacement = char
+          }
+          corrected[pos] = replacement
+        }
+      }
+    }
+    return String(corrected)
+  }
+  
+  /**
+   * Correct check digit positions (should be 0-9 only)
+   */
+  private func correctCheckDigitPositions(_ line: String, positions: [Int]) -> String {
+    var corrected = Array(line)
+    positions.forEach { pos in
+      if pos < corrected.count {
+        let char = corrected[pos]
+        let replacement: Character
+        switch char {
+        case "O", "o": replacement = "0"
+        case "I", "l": replacement = "1"
+        case "Z": replacement = "2"
+        case "S": replacement = "5"
+        case "G": replacement = "6"
+        case "B": replacement = "8"
+        default: replacement = char
+        }
+        corrected[pos] = replacement
+      }
+    }
+    return String(corrected)
+  }
+  
+  /**
+   * Generate all possible O/0 permutations for MRZ text
+   * This handles the most common OCR confusion between O and 0
+   *
+   * @param mrzText Original MRZ text
+   * @param maxPermutations Maximum number of permutations to generate (default: 100)
+   * @return Array of all possible O/0 permutations
+   */
+  private func generateO0Permutations(_ mrzText: String, maxPermutations: Int = 100) -> [String] {
+    var permutations = Set<String>([mrzText])
+    
+    // Find all positions with O or 0
+    let ambiguousPositions = mrzText.enumerated().compactMap { (index, char) in
+      (char == "O" || char == "o" || char == "0") ? index : nil
+    }
+    
+    // Limit positions to avoid combinatorial explosion
+    let positions = Array(ambiguousPositions.prefix(min(7, ambiguousPositions.count)))
+    
+    // Generate all combinations (2^n where n = number of positions)
+    let numCombinations = 1 << positions.count // 2^n
+    let limit = min(numCombinations, maxPermutations)
+    
+    for i in 0..<limit {
+      var variant = Array(mrzText)
+      
+      // For each bit in the combination number, decide O or 0
+      for (j, pos) in positions.enumerated() {
+        let useZero = (i & (1 << j)) != 0
+        let currentChar = variant[pos]
+        
+        // Replace with appropriate character
+        if useZero && currentChar != "0" {
+          variant[pos] = "0"
+        } else if !useZero && currentChar != "O" {
+          variant[pos] = "O"
+        }
+      }
+      
+      permutations.insert(String(variant))
+    }
+    
+    return Array(permutations)
+  }
+  
+  /**
+   * Generate I/1 permutations for additional OCR confusion cases
+   */
+  private func generateI1Permutations(_ mrzText: String, maxPermutations: Int = 50) -> [String] {
+    var permutations = Set<String>([mrzText])
+    
+    // Find all positions with I or 1
+    let ambiguousPositions = mrzText.enumerated().compactMap { (index, char) in
+      (char == "I" || char == "i" || char == "l" || char == "1") ? index : nil
+    }
+    
+    // Limit positions to avoid too many permutations
+    let positions = Array(ambiguousPositions.prefix(min(6, ambiguousPositions.count)))
+    
+    let numCombinations = 1 << positions.count
+    let limit = min(numCombinations, maxPermutations)
+    
+    for i in 0..<limit {
+      var variant = Array(mrzText)
+      
+      for (j, pos) in positions.enumerated() {
+        let useOne = (i & (1 << j)) != 0
+        let currentChar = variant[pos]
+        
+        if useOne && currentChar != "1" {
+          variant[pos] = "1"
+        } else if !useOne && (currentChar == "1" || currentChar == "l" || currentChar == "i") {
+          variant[pos] = "I"
+        }
+      }
+      
+      permutations.insert(String(variant))
+    }
+    
+    return Array(permutations)
+  }
+}