@trustchex/react-native-sdk 1.355.1 → 1.357.0

package/android/src/main/java/com/trustchex/reactnativesdk/mrz/MRZValidationModule.kt

@@ -0,0 +1,785 @@
+package com.trustchex.reactnativesdk.mrz
+
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.WritableNativeArray
+import com.facebook.react.bridge.WritableNativeMap
+
+/**
+ * Native MRZ Validation Module
+ * 
+ * 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://www2023.icao.int/publications/Documents/9303_p3_cons_en.pdf
+ */
+class MRZValidationModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String {
+        return "MRZValidation"
+    }
+
+    /**
+     * Primary MRZ validation with OCR corrections and composite checksum brute-force
+     * This is the main entry point for fast native processing
+     * 
+     * @param ocrText Raw OCR text from camera
+     * @param promise Promise resolving to validation result with field data
+     */
+    @ReactMethod
+    fun validateMRZWithCorrections(ocrText: String, promise: Promise) {
+        try {
+            // Fix and clean raw OCR text
+            val fixedText = fixMRZ(ocrText)
+            val lines = fixedText.trim().split("\n").map { it.trim() }
+            
+            if (lines.isEmpty() || fixedText.length < 60) {
+                promise.resolve(createInvalidResult("MRZ text too short"))
+                return
+            }
+
+            val format = detectMRZFormat(lines)
+            if (format == "UNKNOWN") {
+                promise.resolve(createInvalidResult("Unknown MRZ format"))
+                return
+            }
+
+            // Phase 1: Try parsing with position-aware corrections
+            var result = parseMRZ(fixedText)
+            if (result.getBoolean("valid") == true) {
+                promise.resolve(result)
+                return
+            }
+
+            // Phase 2: Try composite checksum brute-force if only composite is invalid
+            val checksums = result.getMap("checksums")
+            val invalidFields = checksums?.getArray("invalidFields")
+            
+            if (invalidFields != null && invalidFields.size() == 1) {
+                val field = invalidFields.getString(0)
+                if (field == "compositeCheckDigit") {
+                    // Try all 10 possible composite checksum digits
+                    val compositePos = when (format) {
+                        "TD1" -> Pair(1, 29)
+                        "TD2" -> Pair(1, 35)
+                        "TD3" -> Pair(1, 43)
+                        else -> null
+                    }
+
+                    if (compositePos != null) {
+                        val mutableLines = lines.toMutableList()
+                        val targetLine = mutableLines[compositePos.first]
+                        
+                        for (digit in 0..9) {
+                            val testLine = targetLine.substring(0, compositePos.second) + 
+                                          digit + 
+                                          targetLine.substring(compositePos.second + 1)
+                            mutableLines[compositePos.first] = testLine
+                            
+                            val testMRZ = mutableLines.joinToString("\n")
+                            val testResult = parseMRZ(testMRZ)
+                            
+                            if (testResult.getBoolean("valid") == true) {
+                                android.util.Log.d("MRZValidation", "[Native] Valid MRZ found via composite brute-force")
+                                promise.resolve(testResult)
+                                return
+                            }
+                        }
+                    }
+                }
+            }
+
+            // Phase 3: Try exhaustive O/0 permutations
+            android.util.Log.d("MRZValidation", "[Native] Position-aware corrections failed, trying O/0 permutations")
+            val o0Permutations = generateO0Permutations(fixedText)
+            
+            for ((index, permutation) in o0Permutations.withIndex()) {
+                val testResult = parseMRZ(permutation)
+                if (testResult.getBoolean("valid") == true) {
+                    android.util.Log.d("MRZValidation", "[Native] Valid MRZ found via O/0 permutation ${index + 1}/${o0Permutations.size}")
+                    promise.resolve(testResult)
+                    return
+                }
+            }
+
+            // Phase 4: Try I/1 permutations as last resort
+            android.util.Log.d("MRZValidation", "[Native] O/0 permutations failed, trying I/1 permutations")
+            val i1Permutations = generateI1Permutations(fixedText)
+            
+            for ((index, permutation) in i1Permutations.withIndex()) {
+                val testResult = parseMRZ(permutation)
+                if (testResult.getBoolean("valid") == true) {
+                    android.util.Log.d("MRZValidation", "[Native] Valid MRZ found via I/1 permutation ${index + 1}/${i1Permutations.size}")
+                    promise.resolve(testResult)
+                    return
+                }
+            }
+
+            // Return invalid result if all attempts failed
+            android.util.Log.d("MRZValidation", "[Native] All permutation attempts failed")
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("MRZ_VALIDATION_ERROR", "Failed to validate MRZ: ${e.message}", e)
+        }
+    }
+
+    /**
+     * Validates MRZ text and returns parse result with checksum validation
+     * 
+     * @param mrzText The MRZ text to validate (2 or 3 lines separated by \n)
+     * @param promise Promise resolving to validation result object
+     */
+    @ReactMethod
+    fun validateMRZ(mrzText: String, promise: Promise) {
+        try {
+            val result = parseMRZ(mrzText)
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("MRZ_VALIDATION_ERROR", "Failed to validate MRZ: ${e.message}", e)
+        }
+    }
+
+    /**
+     * Create invalid result response
+     */
+    private fun createInvalidResult(error: String): WritableNativeMap {
+        val result = WritableNativeMap()
+        result.putBoolean("valid", false)
+        result.putString("error", error)
+        result.putString("format", "UNKNOWN")
+        return result
+    }
+
+    /**
+     * Calculates checksum for MRZ field using 7-3-1 algorithm
+     * 
+     * @param data The field data to calculate checksum for
+     * @param promise Promise resolving to checksum character
+     */
+    @ReactMethod
+    fun calculateChecksum(data: String, promise: Promise) {
+        try {
+            val checksum = calculateMRZChecksum(data)
+            promise.resolve(checksum.toString())
+        } catch (e: Exception) {
+            promise.reject("CHECKSUM_ERROR", "Failed to calculate checksum: ${e.message}", e)
+        }
+    }
+
+    /**
+     * Fixes common OCR errors in MRZ text
+     * 
+     * @param mrzText Raw MRZ text from OCR
+     * @param promise Promise resolving to fixed MRZ text
+     */
+    @ReactMethod
+    fun fixMRZText(mrzText: String, promise: Promise) {
+        try {
+            val fixed = fixMRZ(mrzText)
+            promise.resolve(fixed)
+        } catch (e: Exception) {
+            promise.reject("MRZ_FIX_ERROR", "Failed to fix MRZ text: ${e.message}", e)
+        }
+    }
+
+    /**
+     * Main MRZ parser - validates format and checksums
+     */
+    private fun parseMRZ(rawText: String): WritableNativeMap {
+        val result = WritableNativeMap()
+        val lines = rawText.trim().split("\n").map { it.trim() }
+
+        // Detect format
+        val format = detectMRZFormat(lines)
+        result.putString("format", format)
+
+        if (format == "UNKNOWN") {
+            result.putBoolean("valid", false)
+            result.putString("error", "Unknown MRZ format")
+            return result
+        }
+
+        // Parse based on format
+        val fields = when (format) {
+            "TD1" -> parseTD1(lines)
+            "TD2" -> parseTD2(lines)
+            "TD3" -> parseTD3(lines)
+            else -> {
+                result.putBoolean("valid", false)
+                result.putString("error", "Unsupported format")
+                return result
+            }
+        }
+
+        result.putMap("fields", fields)
+        
+        // Validate all checksums
+        val checksumValidation = validateChecksums(format, lines)
+        result.putBoolean("valid", checksumValidation.getBoolean("allValid"))
+        result.putMap("checksums", checksumValidation)
+
+        return result
+    }
+
+    /**
+     * Detects MRZ format from line structure
+     */
+    private fun detectMRZFormat(lines: List<String>): String {
+        return when {
+            lines.size == 3 && lines.all { it.length == 30 } -> "TD1"
+            lines.size == 2 && lines.all { it.length == 36 } -> "TD2"
+            lines.size == 2 && lines.all { it.length == 44 } -> "TD3"
+            else -> "UNKNOWN"
+        }
+    }
+
+    /**
+     * Parse TD1 format (ID card, 3 lines of 30 chars)
+     */
+    private fun parseTD1(lines: List<String>): WritableNativeMap {
+        val fields = WritableNativeMap()
+        
+        // Line 1: Document code (2) + Issuing state (3) + Document number (9) + Check digit (1) + Optional (15)
+        fields.putString("documentCode", lines[0].substring(0, 2).replace('<', ' ').trim())
+        fields.putString("issuingState", lines[0].substring(2, 5).replace('<', ' ').trim())
+        fields.putString("documentNumber", lines[0].substring(5, 14).replace('<', ' ').trim())
+        fields.putString("documentNumberCheckDigit", lines[0].substring(14, 15))
+        fields.putString("optional1", lines[0].substring(15, 30).replace('<', ' ').trim())
+
+        // Line 2: Birth date (6) + Check digit (1) + Sex (1) + Expiry date (6) + Check digit (1) + Nationality (3) + Optional (11) + Composite check digit (1)
+        fields.putString("birthDate", lines[1].substring(0, 6))
+        fields.putString("birthDateCheckDigit", lines[1].substring(6, 7))
+        fields.putString("sex", lines[1].substring(7, 8))
+        fields.putString("expirationDate", lines[1].substring(8, 14))
+        fields.putString("expirationDateCheckDigit", lines[1].substring(14, 15))
+        fields.putString("nationality", lines[1].substring(15, 18).replace('<', ' ').trim())
+        fields.putString("optional2", lines[1].substring(18, 29).replace('<', ' ').trim())
+        fields.putString("compositeCheckDigit", lines[1].substring(29, 30))
+
+        // Line 3: Names
+        val names = lines[2].split("<<")
+        fields.putString("lastName", names[0].replace('<', ' ').trim())
+        fields.putString("firstName", if (names.size > 1) names[1].replace('<', ' ').trim() else "")
+
+        return fields
+    }
+
+    /**
+     * Parse TD2 format (ID card, 2 lines of 36 chars)
+     */
+    private fun parseTD2(lines: List<String>): WritableNativeMap {
+        val fields = WritableNativeMap()
+        
+        // Line 1: Document code (2) + Issuing state (3) + Names (31)
+        fields.putString("documentCode", lines[0].substring(0, 2).replace('<', ' ').trim())
+        fields.putString("issuingState", lines[0].substring(2, 5).replace('<', ' ').trim())
+        val names = lines[0].substring(5, 36).split("<<")
+        fields.putString("lastName", names[0].replace('<', ' ').trim())
+        fields.putString("firstName", if (names.size > 1) names[1].replace('<', ' ').trim() else "")
+
+        // Line 2: Document number (9) + Check digit (1) + Nationality (3) + Birth date (6) + Check digit (1) + Sex (1) + Expiry date (6) + Check digit (1) + Optional (7) + Composite check digit (1)
+        fields.putString("documentNumber", lines[1].substring(0, 9).replace('<', ' ').trim())
+        fields.putString("documentNumberCheckDigit", lines[1].substring(9, 10))
+        fields.putString("nationality", lines[1].substring(10, 13).replace('<', ' ').trim())
+        fields.putString("birthDate", lines[1].substring(13, 19))
+        fields.putString("birthDateCheckDigit", lines[1].substring(19, 20))
+        fields.putString("sex", lines[1].substring(20, 21))
+        fields.putString("expirationDate", lines[1].substring(21, 27))
+        fields.putString("expirationDateCheckDigit", lines[1].substring(27, 28))
+        fields.putString("optional1", lines[1].substring(28, 35).replace('<', ' ').trim())
+        fields.putString("compositeCheckDigit", lines[1].substring(35, 36))
+
+        return fields
+    }
+
+    /**
+     * Parse TD3 format (Passport, 2 lines of 44 chars)
+     */
+    private fun parseTD3(lines: List<String>): WritableNativeMap {
+        val fields = WritableNativeMap()
+        
+        // Line 1: Document code (2) + Issuing state (3) + Names (39)
+        fields.putString("documentCode", lines[0].substring(0, 2).replace('<', ' ').trim())
+        fields.putString("issuingState", lines[0].substring(2, 5).replace('<', ' ').trim())
+        val names = lines[0].substring(5, 44).split("<<")
+        fields.putString("lastName", names[0].replace('<', ' ').trim())
+        fields.putString("firstName", if (names.size > 1) names[1].replace('<', ' ').trim() else "")
+
+        // Line 2: Document number (9) + Check digit (1) + Nationality (3) + Birth date (6) + Check digit (1) + Sex (1) + Expiry date (6) + Check digit (1) + Personal number (14) + Check digit (1) + Composite check digit (1)
+        fields.putString("documentNumber", lines[1].substring(0, 9).replace('<', ' ').trim())
+        fields.putString("documentNumberCheckDigit", lines[1].substring(9, 10))
+        fields.putString("nationality", lines[1].substring(10, 13).replace('<', ' ').trim())
+        fields.putString("birthDate", lines[1].substring(13, 19))
+        fields.putString("birthDateCheckDigit", lines[1].substring(19, 20))
+        fields.putString("sex", lines[1].substring(20, 21))
+        fields.putString("expirationDate", lines[1].substring(21, 27))
+        fields.putString("expirationDateCheckDigit", lines[1].substring(27, 28))
+        fields.putString("optional1", lines[1].substring(28, 42).replace('<', ' ').trim())
+        fields.putString("optional1CheckDigit", lines[1].substring(42, 43))
+        fields.putString("compositeCheckDigit", lines[1].substring(43, 44))
+
+        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 fun validateChecksums(format: String, lines: List<String>): WritableNativeMap {
+        val result = WritableNativeMap()
+        val invalidFields = WritableNativeArray()
+        var allValid = true
+
+        when (format) {
+            "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
+                
+                // Document number checksum - ICAO 9303 Part 3, Section 4.9
+                val docNum = lines[0].substring(5, 14)  // Positions 5-13
+                val docNumCheck = lines[0][14]          // Position 14
+                val docNumValid = calculateMRZChecksum(docNum) == docNumCheck
+                result.putBoolean("documentNumberCheckDigit", docNumValid)
+                if (!docNumValid) {
+                    invalidFields.pushString("documentNumberCheckDigit")
+                    allValid = false
+                }
+
+                // Birth date checksum
+                val birthDate = lines[1].substring(0, 6)  // Positions 0-5
+                val birthDateCheck = lines[1][6]          // Position 6
+                val birthDateValid = calculateMRZChecksum(birthDate) == birthDateCheck
+                result.putBoolean("birthDateCheckDigit", birthDateValid)
+                if (!birthDateValid) {
+                    invalidFields.pushString("birthDateCheckDigit")
+                    allValid = false
+                }
+
+                // Expiry date checksum
+                val expiryDate = lines[1].substring(8, 14)  // Positions 8-13
+                val expiryDateCheck = lines[1][14]          // Position 14
+                val expiryDateValid = calculateMRZChecksum(expiryDate) == expiryDateCheck
+                result.putBoolean("expirationDateCheckDigit", expiryDateValid)
+                if (!expiryDateValid) {
+                    invalidFields.pushString("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
+                val composite = lines[0].substring(5, 30) + lines[1].substring(0, 7) + lines[1].substring(8, 15) + lines[1].substring(18, 29)
+                val compositeCheck = lines[1][29]  // Position 29
+                val compositeValid = calculateMRZChecksum(composite) == compositeCheck
+                result.putBoolean("compositeCheckDigit", compositeValid)
+                if (!compositeValid) {
+                    invalidFields.pushString("compositeCheckDigit")
+                    allValid = false
+                }
+            }
+            "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)
+                
+                val line = lines[1]
+                
+                // Document number checksum - ICAO 9303 Part 3, Section 4.9
+                val docNum = line.substring(0, 9)  // Positions 0-8
+                val docNumCheck = line[9]          // Position 9
+                val docNumValid = calculateMRZChecksum(docNum) == docNumCheck
+                result.putBoolean("documentNumberCheckDigit", docNumValid)
+                if (!docNumValid) {
+                    invalidFields.pushString("documentNumberCheckDigit")
+                    allValid = false
+                }
+
+                // Birth date checksum
+                val birthDate = line.substring(13, 19)  // Positions 13-18
+                val birthDateCheck = line[19]           // Position 19
+                val birthDateValid = calculateMRZChecksum(birthDate) == birthDateCheck
+                result.putBoolean("birthDateCheckDigit", birthDateValid)
+                if (!birthDateValid) {
+                    invalidFields.pushString("birthDateCheckDigit")
+                    allValid = false
+                }
+
+                // Expiry date checksum
+                val expiryDate = line.substring(21, 27)  // Positions 21-26
+                val expiryDateCheck = line[27]           // Position 27
+                val expiryDateValid = calculateMRZChecksum(expiryDate) == expiryDateCheck
+                result.putBoolean("expirationDateCheckDigit", expiryDateValid)
+                if (!expiryDateValid) {
+                    invalidFields.pushString("expirationDateCheckDigit")
+                    allValid = false
+                }
+
+                // TD3 has personal number checksum (optional field)
+                if (format == "TD3") {
+                    val personalNum = line.substring(28, 42)  // Positions 28-41
+                    val personalNumCheck = line[42]            // Position 42
+                    val personalNumValid = calculateMRZChecksum(personalNum) == personalNumCheck
+                    result.putBoolean("optional1CheckDigit", personalNumValid)
+                    if (!personalNumValid) {
+                        invalidFields.pushString("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
+                val compositeCheck = if (format == "TD2") line[35] else line[43]
+                val composite = if (format == "TD2") {
+                    // TD2: positions 0-9 + 13-19 + 21-34 (excluding composite at 35)
+                    line.substring(0, 10) + line.substring(13, 20) + line.substring(21, 35)
+                } else {
+                    // TD3: positions 0-9 + 13-19 + 21-42 (excluding composite at 43)
+                    line.substring(0, 10) + line.substring(13, 20) + line.substring(21, 43)
+                }
+                val compositeValid = calculateMRZChecksum(composite) == compositeCheck
+                result.putBoolean("compositeCheckDigit", compositeValid)
+                if (!compositeValid) {
+                    invalidFields.pushString("compositeCheckDigit")
+                    allValid = false
+                }
+            }
+        }
+
+        result.putBoolean("allValid", allValid)
+        result.putArray("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 fun calculateMRZChecksum(data: String): Char {
+        val weights = intArrayOf(7, 3, 1)
+        var sum = 0
+
+        for (i in data.indices) {
+            val char = data[i]
+            val value = when (char) {
+                in '0'..'9' -> char - '0'
+                in 'A'..'Z' -> char - 'A' + 10
+                '<' -> 0
+                else -> 0
+            }
+            sum += value * weights[i % 3]
+        }
+
+        return ('0' + (sum % 10))
+    }
+
+    /**
+     * Fix common OCR errors in MRZ text with mrz-fast inspired corrections
+     */
+    private fun fixMRZ(rawText: String): String {
+        var fixed = rawText
+            .replace(" ", "")  // Remove spaces
+            .replace("«", "")  // Remove « characters
+            .replace(Regex("<K+|r+K+|<r+K+"), "")  // Remove invalid patterns
+
+        // Fix common O/0 confusion in Turkish ID document numbers
+        fixed = fixed.replace(Regex("""\bI<TUR([A-Z0-9]{3})0([A-Z0-9]{6})\b"""), "I<TUR$1O$2")
+
+        val lines = fixed.split("\n")
+            .map { it.trim() }
+            .filter { it.contains('<') }
+
+        // Detect format and pad lines
+        val targetLength = when {
+            lines.all { it.length <= 30 } -> 30  // TD1
+            lines.all { it.length <= 36 } -> 36  // TD2
+            lines.all { it.length <= 44 } -> 44  // TD3
+            else -> return rawText  // Cannot detect format
+        }
+
+        val paddedLines = lines.map { line ->
+            if (line.length < targetLength) {
+                line.padEnd(targetLength, '<')
+            } else {
+                line
+            }
+        }
+
+        return applyOCRCorrections(paddedLines.joinToString("\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 fun applyOCRCorrections(mrzText: String): String {
+        val lines = mrzText.split("\n").toMutableList()
+        if (lines.isEmpty()) return mrzText
+
+        val format = detectMRZFormat(lines)
+        if (format == "UNKNOWN") return mrzText
+
+        when (format) {
+            "TD1" -> {
+                // Line 2: positions 0-5 (birth date), 8-13 (expiry date), 6,14,29 (check digits)
+                lines[1] = correctDigitPositions(lines[1], listOf(
+                    0..5, 8..13  // Date fields need digits
+                ))
+                lines[1] = correctCheckDigitPositions(lines[1], listOf(6, 14, 29))
+                // Nationality (15-17) needs letters
+                lines[1] = correctLetterPositions(lines[1], listOf(15..17))
+            }
+            "TD2" -> {
+                // Line 2: positions 13-18 (birth), 21-26 (expiry), 9,19,27,35 (checks)
+                lines[1] = correctDigitPositions(lines[1], listOf(
+                    13..18, 21..26
+                ))
+                lines[1] = correctCheckDigitPositions(lines[1], listOf(9, 19, 27, 35))
+                // Nationality (10-12) needs letters
+                lines[1] = correctLetterPositions(lines[1], listOf(10..12))
+            }
+            "TD3" -> {
+                // Line 2: positions 13-18 (birth), 21-26 (expiry), 9,19,27,42 (checks)
+                lines[1] = correctDigitPositions(lines[1], listOf(
+                    13..18, 21..26
+                ))
+                lines[1] = correctCheckDigitPositions(lines[1], listOf(9, 19, 27, 42))
+                // Nationality (10-12) needs letters
+                lines[1] = correctLetterPositions(lines[1], listOf(10..12))
+            }
+        }
+
+        return lines.joinToString("\n")
+    }
+
+    /**
+     * Correct positions that should contain digits (0-9)
+     */
+    private fun correctDigitPositions(line: String, ranges: List<IntRange>): String {
+        var corrected = line
+        ranges.forEach { range ->
+            range.forEach { pos ->
+                if (pos < corrected.length) {
+                    val char = corrected[pos]
+                    val replacement = when (char) {
+                        'O', 'o' -> '0'
+                        'I', 'l' -> '1'
+                        'Z' -> '2'
+                        'S' -> '5'
+                        'G' -> '6'
+                        'B' -> '8'
+                        'D', 'Q' -> '0'
+                        else -> char
+                    }
+                    if (replacement != char) {
+                        corrected = corrected.substring(0, pos) + replacement + corrected.substring(pos + 1)
+                    }
+                }
+            }
+        }
+        return corrected
+    }
+
+    /**
+     * Correct positions that should contain letters (A-Z) or <
+     */
+    private fun correctLetterPositions(line: String, ranges: List<IntRange>): String {
+        var corrected = line
+        ranges.forEach { range ->
+            range.forEach { pos ->
+                if (pos < corrected.length) {
+                    val char = corrected[pos]
+                    val replacement = when (char) {
+                        '0' -> 'O'
+                        '1' -> 'I'
+                        '5' -> 'S'
+                        '8' -> 'B'
+                        '2' -> 'Z'
+                        '6' -> 'G'
+                        else -> char
+                    }
+                    if (replacement != char) {
+                        corrected = corrected.substring(0, pos) + replacement + corrected.substring(pos + 1)
+                    }
+                }
+            }
+        }
+        return corrected
+    }
+
+    /**
+     * Correct check digit positions (should be 0-9 only)
+     */
+    private fun correctCheckDigitPositions(line: String, positions: List<Int>): String {
+        var corrected = line
+        positions.forEach { pos ->
+            if (pos < corrected.length) {
+                val char = corrected[pos]
+                val replacement = when (char) {
+                    'O', 'o' -> '0'
+                    'I', 'l' -> '1'
+                    'Z' -> '2'
+                    'S' -> '5'
+                    'G' -> '6'
+                    'B' -> '8'
+                    else -> char
+                }
+                if (replacement != char) {
+                    corrected = corrected.substring(0, pos) + replacement + corrected.substring(pos + 1)
+                }
+            }
+        }
+        return 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 List of all possible O/0 permutations
+     */
+    private fun generateO0Permutations(mrzText: String, maxPermutations: Int = 100): List<String> {
+        val permutations = mutableSetOf(mrzText)
+        
+        // Find all positions with O or 0
+        val ambiguousPositions = mrzText.indices.filter { 
+            val char = mrzText[it]
+            char == 'O' || char == 'o' || char == '0'
+        }
+        
+        // Limit positions to avoid combinatorial explosion
+        val positions = ambiguousPositions.take(minOf(7, ambiguousPositions.size))
+        
+        // Generate all combinations (2^n where n = number of positions)
+        val numCombinations = 1 shl positions.size // 2^n
+        val limit = minOf(numCombinations, maxPermutations)
+        
+        for (i in 0 until limit) {
+            var variant = mrzText
+            
+            // For each bit in the combination number, decide O or 0
+            positions.forEachIndexed { j, pos ->
+                val useZero = (i and (1 shl j)) != 0
+                val currentChar = variant[pos]
+                
+                // Replace with appropriate character
+                val replacement = if (useZero && currentChar != '0') {
+                    '0'
+                } else if (!useZero && currentChar != 'O') {
+                    'O'
+                } else {
+                    currentChar
+                }
+                
+                if (replacement != currentChar) {
+                    variant = variant.substring(0, pos) + replacement + variant.substring(pos + 1)
+                }
+            }
+            
+            permutations.add(variant)
+        }
+        
+        return permutations.toList()
+    }
+
+    /**
+     * Generate I/1 permutations for additional OCR confusion cases
+     */
+    private fun generateI1Permutations(mrzText: String, maxPermutations: Int = 50): List<String> {
+        val permutations = mutableSetOf(mrzText)
+        
+        // Find all positions with I or 1
+        val ambiguousPositions = mrzText.indices.filter {
+            val char = mrzText[it]
+            char == 'I' || char == 'i' || char == 'l' || char == '1'
+        }
+        
+        // Limit positions to avoid too many permutations
+        val positions = ambiguousPositions.take(minOf(6, ambiguousPositions.size))
+        
+        val numCombinations = 1 shl positions.size
+        val limit = minOf(numCombinations, maxPermutations)
+        
+        for (i in 0 until limit) {
+            var variant = mrzText
+            
+            positions.forEachIndexed { j, pos ->
+                val useOne = (i and (1 shl j)) != 0
+                val currentChar = variant[pos]
+                
+                val replacement = if (useOne && currentChar != '1') {
+                    '1'
+                } else if (!useOne && (currentChar == '1' || currentChar == 'l' || currentChar == 'i')) {
+                    'I'
+                } else {
+                    currentChar
+                }
+                
+                if (replacement != currentChar) {
+                    variant = variant.substring(0, pos) + replacement + variant.substring(pos + 1)
+                }
+            }
+            
+            permutations.add(variant)
+        }
+        
+        return permutations.toList()
+    }
+}