@trustchex/react-native-sdk 1.495.10 → 1.495.11

package/android/build.gradle

@@ -92,6 +92,16 @@ dependencies {
 
   // OpenCV for hologram detection and image processing
   implementation 'org.opencv:opencv:4.12.0'
+
+  // Pure-Java JPEG2000 decoder (jj2000, edu.ucar 5.2) — vendored as a local jar
+  // so it resolves fully offline with no Maven coordinate. Android's image
+  // pipeline cannot decode JPEG2000, but passport chip portraits (DG2) are
+  // frequently JP2; this lets ImageDecoderModule decode them to JPEG for display.
+  // No java.awt / javax.imageio usage, so it runs on Android.
+  implementation files("libs/jj2000-5.2.jar")
+
+  // Plain-JVM unit tests for the framework-free JP2 decode logic (Jp2PgxDecoder).
+  testImplementation "junit:junit:4.13.2"
 }
 
 react {

package/android/src/main/java/com/trustchex/reactnativesdk/ImageDecoderModule.kt

@@ -0,0 +1,88 @@
+package com.trustchex.reactnativesdk
+
+import android.graphics.Bitmap
+import android.util.Base64
+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 java.io.ByteArrayOutputStream
+import java.io.File
+
+/**
+ * Decodes images that React Native's <Image> cannot render directly on Android.
+ *
+ * The driving case is the passport chip portrait (DG2), which is frequently
+ * stored as JPEG2000 (image/jp2). Android's Fresco/Skia image pipeline does NOT
+ * decode JPEG2000, so the chip photo showed as a blank/white placeholder. This
+ * module decodes the JP2 with the pure-Java jj2000 decoder (vendored jar, no
+ * NDK, no javax.imageio) and re-encodes it as JPEG so the JS <Image> can render
+ * it — mirroring the iOS ImageDecoderModule (which uses ImageIO).
+ *
+ * jj2000's [Decoder] is file-based and only writes raw PGX (one file per image
+ * component) headlessly — its PPM writer rejects many real codestreams. So we
+ * decode to "<base>-N.pgx" components and recombine: 3 components → RGB, 1 →
+ * grayscale. PGX samples may be >8-bit and big- or little-endian; we normalise
+ * to 8-bit. Handles both the JP2 container and a raw J2K codestream (DG2 ships
+ * as either).
+ */
+class ImageDecoderModule(reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName(): String = NAME
+
+  /**
+   * Decode a base64 JPEG2000 image to a base64 JPEG. Resolves with the JPEG
+   * base64 string, or rejects on any failure (the JS caller falls back to the
+   * raw JP2, exactly as it does when the native module is unavailable).
+   */
+  @ReactMethod
+  fun decodeJp2ToJpeg(base64Jp2: String, promise: Promise) {
+    val cacheDir = reactApplicationContext.cacheDir
+    val token = System.nanoTime().toString()
+    val input = File(cacheDir, "jp2_decode_$token.jp2")
+    // jj2000 derives component filenames from this base ("<base>-1.pgx", …).
+    val outBase = File(cacheDir, "jp2_decode_$token.pgx")
+    try {
+      val jp2Bytes = Base64.decode(base64Jp2, Base64.DEFAULT)
+        ?: throw IllegalArgumentException("Could not base64-decode JP2 input")
+      input.writeBytes(jp2Bytes)
+
+      Jp2PgxDecoder.decodeToPgx(input, outBase)
+
+      val componentFiles = Jp2PgxDecoder.collectComponentFiles(outBase)
+      if (componentFiles.isEmpty()) {
+        throw IllegalStateException("jj2000 produced no component output")
+      }
+
+      val decoded = Jp2PgxDecoder.componentsToRgb(componentFiles.map { it.readBytes() })
+      val pixels = IntArray(decoded.rgb.size) { 0xFF000000.toInt() or decoded.rgb[it] }
+      val bitmap = Bitmap.createBitmap(
+        pixels,
+        decoded.width,
+        decoded.height,
+        Bitmap.Config.ARGB_8888
+      )
+      val jpeg = ByteArrayOutputStream().use { out ->
+        // Re-encode as baseline JPEG so the chip portrait is a format BOTH the
+        // on-screen <Image> AND the verification backend accept (the backend
+        // face-match expects JPEG/PNG, not raw JPEG2000).
+        bitmap.compress(Bitmap.CompressFormat.JPEG, 95, out)
+        out.toByteArray()
+      }
+      bitmap.recycle()
+
+      promise.resolve(Base64.encodeToString(jpeg, Base64.NO_WRAP))
+    } catch (e: Throwable) {
+      promise.reject("DECODE_FAILED", e.message, e)
+    } finally {
+      input.delete()
+      Jp2PgxDecoder.collectComponentFiles(outBase).forEach { it.delete() }
+      outBase.delete()
+    }
+  }
+
+  companion object {
+    const val NAME = "ImageDecoderModule"
+  }
+}

package/android/src/main/java/com/trustchex/reactnativesdk/Jp2PgxDecoder.kt

@@ -0,0 +1,135 @@
+package com.trustchex.reactnativesdk
+
+import jj2000.j2k.decoder.Decoder
+import jj2000.j2k.util.ParameterList
+import java.io.File
+
+/**
+ * Pure (Android-free) half of the JPEG2000 decode: drive jj2000 to PGX
+ * components and turn those into a flat RGB pixel array. Kept separate from
+ * [ImageDecoderModule] so the parsing/recombination logic — the only novel,
+ * bug-prone part — is unit-testable on a plain JVM without Robolectric (no
+ * android.graphics.Bitmap / Color dependency here).
+ *
+ * jj2000's PGX output:
+ *  - colour (multi-component): "<base>-1.pgx", "<base>-2.pgx", "<base>-3.pgx"
+ *  - grayscale (single-component): "<base>.pgx" (no "-N" suffix)
+ *  - each PGX: ASCII header `PG <ML|LM> [<+|->] <depth> <w> <h>\n` then raw
+ *    big-/little-endian samples of `ceil(depth/8)` bytes each.
+ */
+object Jp2PgxDecoder {
+
+  /** A decoded image as packed 0xRRGGBB ints plus its dimensions. */
+  class DecodedImage(val width: Int, val height: Int, val rgb: IntArray)
+
+  /** Run jj2000's file-based decoder, writing per-component PGX next to [outBase]. */
+  fun decodeToPgx(input: File, outBase: File) {
+    val defaults = ParameterList()
+    for (param in Decoder.getAllParameters()) {
+      // i / o have no default (null); everything else seeds the defaults list.
+      if (param[3] != null) defaults.put(param[0], param[3])
+    }
+    val pl = ParameterList(defaults).apply {
+      put("i", input.absolutePath)
+      put("o", outBase.absolutePath)
+      put("debug", "off")
+      put("verbose", "off")
+    }
+    Decoder(pl).run()
+  }
+
+  /**
+   * The decoded component PGX files in component order. Colour → "<base>-N.pgx"
+   * sorted by N; grayscale → the base "<base>.pgx" itself.
+   */
+  fun collectComponentFiles(outBase: File): List<File> {
+    val dir = outBase.parentFile ?: return emptyList()
+    val stem = outBase.name.removeSuffix(".pgx")
+    val multi = (dir.listFiles() ?: emptyArray())
+      .filter { it.name.startsWith("$stem-") && it.name.endsWith(".pgx") }
+      .sortedBy {
+        it.name.removePrefix("$stem-").removeSuffix(".pgx").toIntOrNull() ?: 0
+      }
+    if (multi.isNotEmpty()) return multi
+    return if (outBase.exists() && outBase.length() > 0) listOf(outBase) else emptyList()
+  }
+
+  /** Recombine component PGX byte arrays into a packed-RGB image. */
+  fun componentsToRgb(components: List<ByteArray>): DecodedImage {
+    require(components.isNotEmpty()) { "No PGX components" }
+    val comps = components.map { parsePgx(it) }
+    val width = comps[0].width
+    val height = comps[0].height
+    require(width > 0 && height > 0) { "Invalid PGX dimensions ${width}x$height" }
+
+    val rgb = IntArray(width * height)
+    val n = comps.size
+    for (idx in 0 until width * height) {
+      val r: Int
+      val g: Int
+      val b: Int
+      if (n >= 3) {
+        r = comps[0].sampleAt(idx)
+        g = comps[1].sampleAt(idx)
+        b = comps[2].sampleAt(idx)
+      } else {
+        val v = comps[0].sampleAt(idx)
+        r = v; g = v; b = v
+      }
+      rgb[idx] = (r shl 16) or (g shl 8) or b
+    }
+    return DecodedImage(width, height, rgb)
+  }
+
+  internal class Pgx(
+    val width: Int,
+    val height: Int,
+    val depth: Int,
+    val bigEndian: Boolean,
+    val dataOffset: Int,
+    val bytes: ByteArray
+  ) {
+    /** One normalised 8-bit sample at pixel index [idx]. */
+    fun sampleAt(idx: Int): Int {
+      val bytesPer = (depth + 7) / 8
+      val p = dataOffset + idx * bytesPer
+      var v = if (bytesPer <= 1) {
+        bytes[p].toInt() and 0xFF
+      } else {
+        val a = bytes[p].toInt() and 0xFF
+        val b = bytes[p + 1].toInt() and 0xFF
+        if (bigEndian) (a shl 8) or b else (b shl 8) or a
+      }
+      if (depth > 8) v = v shr (depth - 8) else if (depth < 8) v = v shl (8 - depth)
+      return v and 0xFF
+    }
+  }
+
+  /**
+   * Parse a PGX header: "PG <ML|LM> [<+|->] <depth> <width> <height>\n" followed
+   * by raw samples. The sign and the leading '+'/'-' are optional and may be
+   * glued to the depth ("+16"); we tolerate both. "ML" = big-endian.
+   */
+  internal fun parsePgx(d: ByteArray): Pgx {
+    var i = 0
+    val sb = StringBuilder()
+    while (i < d.size && d[i].toInt().toChar() != '\n') {
+      sb.append((d[i].toInt() and 0xFF).toChar())
+      i++
+    }
+    val dataOffset = i + 1
+    val raw = sb.toString().trim().split(Regex("\\s+"))
+    val bigEndian = raw.getOrNull(1) == "ML"
+    val nums = ArrayList<Int>()
+    for (k in 2 until raw.size) {
+      var s = raw[k]
+      if (s == "+" || s == "-") continue
+      s = s.removePrefix("+").removePrefix("-")
+      s.toIntOrNull()?.let { nums.add(it) }
+    }
+    val depth = nums.getOrNull(0) ?: 8
+    val width = nums.getOrNull(1) ?: 0
+    val height = nums.getOrNull(2) ?: 0
+    return Pgx(width, height, depth, bigEndian, dataOffset, d)
+  }
+}

package/android/src/main/java/com/trustchex/reactnativesdk/TrustchexSDKPackage.kt

@@ -18,6 +18,7 @@ class TrustchexSDKPackage : BaseReactPackage() {
       "DeviceBrightness" -> DeviceBrightnessModule(reactContext)
       "MLKitModule" -> MLKitModule(reactContext)
       "OpenCVModule" -> OpenCVModule(reactContext)
+      ImageDecoderModule.NAME -> ImageDecoderModule(reactContext)
       else -> null
     }
   }
@@ -74,6 +75,17 @@ class TrustchexSDKPackage : BaseReactPackage() {
                       false // isTurboModule
               )
 
+      // JPEG2000 image decoder module (passport DG2 portrait → JPEG)
+      moduleInfos[ImageDecoderModule.NAME] =
+              ReactModuleInfo(
+                      ImageDecoderModule.NAME,
+                      ImageDecoderModule.NAME,
+                      false, // canOverrideExistingModule
+                      false, // needsEagerInit
+                      false, // isCxxModule
+                      false // isTurboModule
+              )
+
       moduleInfos
     }
   }

package/android/src/test/java/com/trustchex/reactnativesdk/Jp2PgxDecoderTest.kt

@@ -0,0 +1,143 @@
+package com.trustchex.reactnativesdk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.io.File
+import java.nio.file.Files
+
+/**
+ * Plain-JVM tests for the JPEG2000 → RGB decode logic that backs the Android
+ * ImageDecoderModule (the fix for the "white face" on German passports).
+ *
+ * Runs the real vendored jj2000 decoder against committed JP2 fixtures and
+ * verifies the recombined pixels, plus the PGX header parsing edge cases. No
+ * android.graphics dependency, so no Robolectric is needed.
+ *
+ * Fixtures (android/src/test/resources/jp2):
+ *  - solid_color.jp2 : 64×64, every pixel rgb(200,40,60)  [JP2 container, colour]
+ *  - solid_color.j2k : same image as a raw J2K codestream (DG2 ships as either)
+ *  - gray.jp2        : 64×64 black→white horizontal gradient [single-component]
+ */
+class Jp2PgxDecoderTest {
+
+  private fun fixture(name: String): File {
+    val url = javaClass.classLoader!!.getResource("jp2/$name")
+      ?: error("Missing test fixture jp2/$name")
+    return File(url.toURI())
+  }
+
+  /** Decode a fixture end-to-end through the production code path. */
+  private fun decode(fixtureName: String): Jp2PgxDecoder.DecodedImage {
+    val tmpDir = Files.createTempDirectory("jp2test").toFile()
+    try {
+      val input = File(tmpDir, "in.jp2").apply { writeBytes(fixture(fixtureName).readBytes()) }
+      val outBase = File(tmpDir, "out.pgx")
+      Jp2PgxDecoder.decodeToPgx(input, outBase)
+      val comps = Jp2PgxDecoder.collectComponentFiles(outBase)
+      assertTrue("expected at least one component for $fixtureName", comps.isNotEmpty())
+      return Jp2PgxDecoder.componentsToRgb(comps.map { it.readBytes() })
+    } finally {
+      tmpDir.deleteRecursively()
+    }
+  }
+
+  private fun Jp2PgxDecoder.DecodedImage.pixelAt(x: Int, y: Int) = rgb[y * width + x]
+  private fun r(p: Int) = (p shr 16) and 0xFF
+  private fun g(p: Int) = (p shr 8) and 0xFF
+  private fun b(p: Int) = p and 0xFF
+
+  @Test
+  fun decodesColorJp2ContainerToCorrectRgb() {
+    val img = decode("solid_color.jp2")
+    assertEquals(64, img.width)
+    assertEquals(64, img.height)
+    // Every pixel is the same solid colour; check a few spread-out ones. JP2 is
+    // lossy so allow a small tolerance.
+    for ((x, y) in listOf(0 to 0, 63 to 0, 0 to 63, 63 to 63, 32 to 32)) {
+      val p = img.pixelAt(x, y)
+      assertClose("R@($x,$y)", 200, r(p))
+      assertClose("G@($x,$y)", 40, g(p))
+      assertClose("B@($x,$y)", 60, b(p))
+    }
+  }
+
+  @Test
+  fun decodesRawJ2kCodestreamSameAsContainer() {
+    // DG2 may be a bare codestream rather than a .jp2 box; must decode identically.
+    val img = decode("solid_color.j2k")
+    assertEquals(64, img.width)
+    val p = img.pixelAt(10, 10)
+    assertClose("R", 200, r(p))
+    assertClose("G", 40, g(p))
+    assertClose("B", 60, b(p))
+  }
+
+  @Test
+  fun decodesGrayscaleJp2AsSingleComponentToGray() {
+    // Single-component output is written as "<base>.pgx" with no "-N" suffix; the
+    // collector must still find it, and grayscale must expand to R==G==B.
+    val img = decode("gray.jp2")
+    assertEquals(64, img.width)
+    // ImageMagick `gradient:black-white` is a VERTICAL ramp (top dark → bottom
+    // bright), constant across each row. Check top vs bottom, and that every
+    // channel is equal (true grayscale expansion).
+    val top = img.pixelAt(32, 1)
+    val bottom = img.pixelAt(32, 62)
+    assertEquals("top should be gray", r(top), g(top))
+    assertEquals("top should be gray", g(top), b(top))
+    assertEquals("bottom should be gray", r(bottom), g(bottom))
+    assertTrue("gradient should brighten top→bottom", r(bottom) > r(top))
+  }
+
+  @Test
+  fun parsesBigEndian16BitPgxAndScalesTo8Bit() {
+    // "PG ML + 16 2 1\n" then one 16-bit big-endian sample 0xFF00 (=65280) and
+    // one 0x0100 (=256). depth 16 → >>8 → 255 and 1.
+    val header = "PG ML + 16 2 1\n".toByteArray(Charsets.US_ASCII)
+    val body = byteArrayOf(0xFF.toByte(), 0x00, 0x01, 0x00)
+    val pgx = Jp2PgxDecoder.parsePgx(header + body)
+    assertEquals(2, pgx.width)
+    assertEquals(1, pgx.height)
+    assertEquals(255, pgx.sampleAt(0))
+    assertEquals(1, pgx.sampleAt(1))
+  }
+
+  @Test
+  fun parsesLittleEndian8BitPgx() {
+    // "PG LM + 8 3 1\n" then bytes 10, 20, 30 — 8-bit, no scaling.
+    val header = "PG LM + 8 3 1\n".toByteArray(Charsets.US_ASCII)
+    val body = byteArrayOf(10, 20, 30)
+    val pgx = Jp2PgxDecoder.parsePgx(header + body)
+    assertEquals(10, pgx.sampleAt(0))
+    assertEquals(20, pgx.sampleAt(1))
+    assertEquals(30, pgx.sampleAt(2))
+  }
+
+  @Test
+  fun parsesHeaderWithSignGluedToDepth() {
+    // Some writers emit "+16" with no space; the parser must still read depth 16.
+    val header = "PG ML +16 1 1\n".toByteArray(Charsets.US_ASCII)
+    val body = byteArrayOf(0x80.toByte(), 0x00) // 0x8000 >> 8 = 128
+    val pgx = Jp2PgxDecoder.parsePgx(header + body)
+    assertEquals(128, pgx.sampleAt(0))
+  }
+
+  @Test
+  fun grayscaleComponentExpandsToEqualRgbChannels() {
+    val header = "PG ML + 8 1 1\n".toByteArray(Charsets.US_ASCII)
+    val body = byteArrayOf(123)
+    val img = Jp2PgxDecoder.componentsToRgb(listOf(header + body))
+    val p = img.rgb[0]
+    assertEquals(123, r(p))
+    assertEquals(123, g(p))
+    assertEquals(123, b(p))
+  }
+
+  private fun assertClose(label: String, expected: Int, actual: Int, tol: Int = 12) {
+    assertTrue(
+      "$label expected ~$expected (±$tol) but was $actual",
+      kotlin.math.abs(expected - actual) <= tol
+    )
+  }
+}

package/lib/module/Shared/Components/EIDScanner.js

@@ -458,11 +458,14 @@ const EIDScanner = ({
               style: styles.idCardPhotoContainer,
               children: /*#__PURE__*/_jsx(View, {
                 style: styles.idCardPhotoFrame,
-                children: documentFaceImage && (documentFaceImageMimeType === 'image/jpeg' || documentFaceImageMimeType === 'image/png' ||
-                // Android's <Image> decodes a raw JP2 data URI; on iOS
-                // the chip JP2 is converted to JPEG before this point
-                // (native ImageIO), so iOS never reaches here as jp2.
-                documentFaceImageMimeType === 'image/jp2') ? /*#__PURE__*/_jsx(Image, {
+                children: documentFaceImage && (
+                // The chip portrait (DG2) is JPEG2000, which RN's <Image>
+                // can't render on either platform — the native decoder
+                // (iOS ImageIO / Android jj2000) converts it to JPEG (or
+                // the small-image JS fallback to PNG) before this point.
+                // A raw image/jp2 would render as a blank box, so we only
+                // accept the decoded formats and otherwise show '?'.
+                documentFaceImageMimeType === 'image/jpeg' || documentFaceImageMimeType === 'image/png') ? /*#__PURE__*/_jsx(Image, {
                   source: {
                     uri: `data:${documentFaceImageMimeType};base64,${documentFaceImage}`
                   },

package/lib/module/Shared/Components/IdentityDocumentCamera.flows.js

@@ -31,7 +31,7 @@
  */
 
 import { PASSPORT_MRZ_PATTERN } from "./IdentityDocumentCamera.constants.js";
-import { isIDCardDocumentCode } from "./IdentityDocumentCamera.utils.js";
+import { isIDCardDocumentCode, isPassportDocumentCode, documentHasBackSide } from "./IdentityDocumentCamera.utils.js";
 
 /**
  * After this many retry attempts for ID_FRONT flow, proceed with face detection alone
@@ -283,20 +283,23 @@ export function handleIDBackFlow(mrzText, mrzFields, mrzValid, mrzStableAndValid
  * self-corrects: SCAN_ID_BACK simply won't find an ID-back MRZ/barcode and the
  * user can cancel, which is far better than skipping the back of every real ID.
  */
-export function getNextStepAfterHologram(detectedDocumentType, currentFrameDocType, mrzDocCode) {
-  // Any positive passport signal → done (no back side).
-  const isPassport = detectedDocumentType === 'PASSPORT' || currentFrameDocType === 'PASSPORT' || mrzDocCode === 'P';
-  if (isPassport) {
-    return 'COMPLETED';
-  }
-
-  // Positive ID-card evidence → scan the back. Either a non-'P' MRZ code, or a
-  // front classified as ID_FRONT (an ID front legitimately has no MRZ, so the
-  // classification is the only signal we get).
-  const hasIdCardMrzCode = !!mrzDocCode && mrzDocCode !== 'P';
+export function getNextStepAfterHologram(detectedDocumentType, currentFrameDocType, mrzDocCode,
+// True if a passport MRZ pattern / 'P' code was seen in ANY front frame this
+// session — not just the accepting one. The passport MRZ is dense and often
+// OCRs a few frames AFTER the face + signature, so a passport can get locked
+// as ID_FRONT before its MRZ is read. Latching the signal across frames is
+// what stops that passport from being wrongly routed to SCAN_ID_BACK here.
+sawPassportSignal = false) {
+  // Resolve to a single document type, passport-biased: any positive passport
+  // signal wins (a passport must never wait for a back that does not exist),
+  // then positive ID-card evidence (a non-'P' MRZ code, or an ID_FRONT
+  // classification — an ID front legitimately has no MRZ, so the classification
+  // is the only signal we get), else UNKNOWN.
+  const isPassport = sawPassportSignal || detectedDocumentType === 'PASSPORT' || currentFrameDocType === 'PASSPORT' || isPassportDocumentCode(mrzDocCode);
+  const hasIdCardMrzCode = !!mrzDocCode && !isPassportDocumentCode(mrzDocCode);
   const isIdFront = detectedDocumentType === 'ID_FRONT' || currentFrameDocType === 'ID_FRONT';
-  if (hasIdCardMrzCode || isIdFront) {
-    return 'SCAN_ID_BACK';
-  }
-  return 'COMPLETED';
+  const resolved = isPassport ? 'PASSPORT' : hasIdCardMrzCode || isIdFront ? 'ID_FRONT' : 'UNKNOWN';
+
+  // Single source of truth for "is there a back side left to scan?".
+  return documentHasBackSide(resolved) ? 'SCAN_ID_BACK' : 'COMPLETED';
 }

package/lib/module/Shared/Components/IdentityDocumentCamera.js

@@ -21,7 +21,7 @@ import { speak, resetLastMessage } from "../Libs/tts.utils.js";
 import AppContext from "../Contexts/AppContext.js";
 import { useTheme } from "../Contexts/ThemeContext.js";
 import DebugOverlay, { TestModePanel } from "./DebugOverlay.js";
-import { getStatusMessage, getFrameToScreenTransform, transformBoundsToScreen, getScanAreaBounds, angleBetweenPoints, detectDocumentType, determineDocumentTypeToSet, areMRZFieldsEqual, hasRequiredMRZFields, validateFacePosition } from "./IdentityDocumentCamera.utils.js";
+import { getStatusMessage, getFrameToScreenTransform, transformBoundsToScreen, getScanAreaBounds, angleBetweenPoints, detectDocumentType, determineDocumentTypeToSet, areMRZFieldsEqual, hasRequiredMRZFields, validateFacePosition, isPassportDocumentCode } from "./IdentityDocumentCamera.utils.js";
 import { handlePassportFlow, handleIDFrontFlow, handleIDBackFlow, getNextStepAfterHologram } from "./IdentityDocumentCamera.flows.js";
 import { HOLOGRAM_IMAGE_COUNT, HOLOGRAM_DETECTION_THRESHOLD, HOLOGRAM_DETECTION_RETRY_COUNT, HOLOGRAM_CAPTURE_INTERVAL, HOLOGRAM_MAX_FRAMES_WITHOUT_FACE, MIN_BRIGHTNESS_THRESHOLD, MAX_BRIGHTNESS_THRESHOLD, FACE_EDGE_MARGIN_PERCENT, MAX_CONSECUTIVE_QUALITY_FAILURES, REQUIRED_CONSISTENT_DOCTYPE_DETECTIONS, SIGNATURE_TEXT_REGEX, MRZ_BLOCK_PATTERN, PASSPORT_MRZ_PATTERN, MIN_CARD_FACE_SIZE_PERCENT } from "./IdentityDocumentCamera.constants.js";
 
@@ -104,6 +104,15 @@ const IdentityDocumentCamera = ({
   const lastDetectedDocType = useRef('UNKNOWN');
   const consistentDocTypeCount = useRef(0);
 
+  // Latches true the moment a passport MRZ pattern / 'P' document code is seen in
+  // ANY front frame this session. The passport MRZ is dense and often OCRs a few
+  // frames AFTER the face + signature, so without this a passport can be locked
+  // as ID_FRONT (which has no MRZ on its front) and then wrongly asked for a back
+  // side that does not exist. Once latched, the front is never accepted as
+  // ID_FRONT and the post-hologram routing always completes instead of scanning
+  // a back. Reset only when a brand-new scan session starts.
+  const sawPassportSignal = useRef(false);
+
   // Frame quality tracking - persist across callbacks
   const lastFrameQuality = useRef({
     hasAcceptableQuality: true,
@@ -197,6 +206,7 @@ const IdentityDocumentCamera = ({
       lastValidMRZText.current = null;
       lastValidMRZFields.current = null;
       validMRZConsecutiveCount.current = 0;
+      sawPassportSignal.current = false;
       mrzAggregator.current.reset();
       setMrzReliable(false);
       // Start a fresh diagnostics session for the support report.
@@ -441,6 +451,15 @@ const IdentityDocumentCamera = ({
 
     // Reset MRZ retry counter for each new step so retries start fresh
     mrzDetectionCurrentRetryCount.current = 0;
+    // A transition back to the initial front step means a brand-new document
+    // scan is starting, so the sticky passport signal from any previous
+    // document must NOT carry over — otherwise an ID card scanned after a
+    // passport (without the camera unfocusing) would be forced into the
+    // passport flow and skip its back side. (The focus-based reset above only
+    // fires when the camera goes inactive.)
+    if (nextStepType === 'SCAN_ID_FRONT_OR_PASSPORT') {
+      sawPassportSignal.current = false;
+    }
     // Only clear MRZ text when entering SCAN_ID_BACK (new MRZ expected).
     // Preserve across SCAN_HOLOGRAM so passport completion has MRZ data.
     if (nextStepType === 'SCAN_ID_BACK') {
@@ -1195,7 +1214,7 @@ const IdentityDocumentCamera = ({
 
         // Use scannedData.mrzFields which we just ensured has preserved MRZ
         const mrzDocCode = scannedData.mrzFields?.documentCode;
-        const nextStepAfterHologram = getNextStepAfterHologram(detectedDocumentType, documentType, mrzDocCode);
+        const nextStepAfterHologram = getNextStepAfterHologram(detectedDocumentType, documentType, mrzDocCode, sawPassportSignal.current);
         transitionStepWithCallback(nextStepAfterHologram, 'SCAN_HOLOGRAM', scannedData);
         return;
       }
@@ -1207,10 +1226,30 @@ const IdentityDocumentCamera = ({
     // INITIAL SCAN STEP - Detect document type and validate
     // ============================================================================
     if (nextStep === 'SCAN_ID_FRONT_OR_PASSPORT') {
+      // Latch ANY passport signal seen in a front frame — the parsed 'P' code
+      // OR the raw passport MRZ pattern (which survives even when full MRZ
+      // parsing fails). The passport MRZ often OCRs a few frames after the
+      // face + signature, so we remember it across frames; once latched, this
+      // front can never be accepted as an ID card / asked for a back side.
+      // Only AUTHORITATIVE passport signals latch — a parsed MRZ document code
+      // of 'P', or a settled PASSPORT classification. We deliberately do NOT
+      // latch on a raw PASSPORT_MRZ_PATTERN substring match against OCR text:
+      // that loose test can fire on ID-card MRZ noise, and because the latch is
+      // sticky and one-directional a single false match would force the
+      // passport flow for the rest of the session and silently skip the ID
+      // card's back side. The parsed 'P' code still covers the lagging-MRZ case
+      // (it just requires the MRZ to have actually parsed first).
+      if (isPassportDocumentCode(parsedMRZData?.fields?.documentCode) || documentType === 'PASSPORT' || detectedDocumentType === 'PASSPORT') {
+        sawPassportSignal.current = true;
+      }
+
       // Determine which flow handler to use.
       // Current-frame passport detection always takes precedence over a locked
-      // ID_FRONT — passport MRZ may not appear until later frames.
-      const flowDocumentType = documentType === 'PASSPORT' ? 'PASSPORT' : detectedDocumentType !== 'UNKNOWN' ? detectedDocumentType : documentType;
+      // ID_FRONT — passport MRZ may not appear until later frames. A latched
+      // passport signal also forces the passport flow, so a passport that was
+      // momentarily locked as ID_FRONT (before its MRZ was read) is corrected
+      // instead of being driven into the ID-card back-side flow.
+      const flowDocumentType = documentType === 'PASSPORT' || sawPassportSignal.current ? 'PASSPORT' : detectedDocumentType !== 'UNKNOWN' ? detectedDocumentType : documentType;
       const handlePassportInitialStep = async () => {
         const flowResult = handlePassportFlow(primaryFaces, mrzText, parsedMRZData?.fields, mrzStableAndValid, onlyMRZScan, hasRequiredMRZFields(parsedMRZData?.fields), !!faceImageToUse);
         if (!flowResult.shouldProceed) {

package/lib/module/Shared/Components/IdentityDocumentCamera.utils.js

@@ -13,6 +13,28 @@ export function isIDCardDocumentCode(code) {
   return code.startsWith('I') || code.startsWith('A') || code.startsWith('C');
 }
 
+/**
+ * Checks if a document code represents a passport (ICAO TD3).
+ * Per ICAO 9303 Part 4, the first character of a passport MRZ document code is
+ * 'P' — for the ordinary `P<`, the German `PP`, and the diplomatic/service/
+ * official `PD`/`PS`/`PO` variants alike.
+ */
+export function isPassportDocumentCode(code) {
+  if (!code) return false;
+  return code.startsWith('P');
+}
+
+/**
+ * Single source of truth for "does this document have a second side left to
+ * scan?". A passport's data all lives on one page, so it has no back; an ID
+ * card's MRZ lives on the back, so an ID front always does. Used by the
+ * post-front / post-hologram routing so the "ask for the back side?" decision
+ * is never re-derived ad-hoc (the bug where passports were sent to SCAN_ID_BACK).
+ */
+export function documentHasBackSide(documentType) {
+  return documentType === 'ID_FRONT';
+}
+
 /**
  * Frame-to-screen coordinate transform using FILL_CENTER scaling
  */

package/lib/module/Shared/EIDReader/eidReader.js

@@ -229,21 +229,23 @@ async function convertJP2IfNeeded(imageBuffer, mimeType) {
     };
   }
 
-  // Prefer the native decoder (iOS ImageIO). It decodes JPEG2000 of any size
-  // without blocking the JS thread, so it both fixes the iOS preview (RN's
-  // <Image> can't render a raw image/jp2 data URI) and avoids the slow pure-JS
-  // decoder entirely. Returns null on Android / when unavailable → fall through.
+  // Prefer the native decoder (iOS ImageIO / Android jj2000). It decodes
+  // JPEG2000 of any size off the JS thread, so it fixes the on-screen preview on
+  // BOTH platforms (RN's <Image> can't render a raw image/jp2 data URI on either)
+  // and avoids the slow pure-JS decoder entirely. Returns null only when the
+  // native module is unavailable/unlinked or it fails → fall through.
   const native = await decodeJp2ToJpeg(imageBuffer);
   if (native) {
     debugLog('EID', `[EID] JP2 decoded natively → ${native.mimeType} (${native.base64.length} base64 chars)`);
     return native;
   }
 
-  // Too large to decode synchronously without freezing the UI — keep the raw
-  // JP2. The face image is still captured (the verification backend / face-match
-  // accept JPEG2000); only the on-screen preview can't render it. This lets the
-  // NFC read COMPLETE instead of hanging. (On Android the raw JP2 still renders
-  // in <Image>; on iOS the native path above normally handles it.)
+  // Native decode unavailable AND too large to decode synchronously in JS
+  // without freezing the UI — keep the raw JP2. The face image is still captured
+  // (the verification backend / face-match accept JPEG2000); only the on-screen
+  // preview can't render it. This lets the NFC read COMPLETE instead of hanging.
+  // In normal operation the native path above handles this on both platforms; we
+  // only reach here if the native module failed or isn't linked.
   if (imageBuffer.length > MAX_JP2_DECODE_BYTES) {
     debugLog('EID', `[EID] JP2 face image is ${imageBuffer.length} bytes (> ${MAX_JP2_DECODE_BYTES}); skipping in-JS decode to avoid blocking, keeping raw JP2`);
     return {