@trustchex/react-native-sdk 1.478.7 → 1.481.1

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

@@ -9,6 +9,33 @@ import { DG2File } from "./lds/icao/dg2File.js";
 import { Buffer } from 'buffer';
 import { InputStream } from "./java/inputStream.js";
 import { debugLog } from "../Libs/debug.utils.js";
+import { diagnostics } from "../Libs/diagnostics.js";
+
+/**
+ * Extract an APDU status word (hex, e.g. "6982") from an error message if the
+ * protocol layer included one. Returns undefined when none is present. Kept
+ * deliberately loose — the protocol senders embed "SW=...." / "(6982)" forms.
+ */
+const extractStatusWord = msg => {
+  const m = msg.match(/\b(?:SW[:= ]?)?([0-9a-fA-F]{4})\b/);
+  return m ? m[1].toUpperCase() : undefined;
+};
+
+/** Categorise an NFC error message into a coarse, non-PII bucket. */
+const categorizeNfcError = msg => {
+  const m = msg.toLowerCase();
+  if (m.includes('cancel')) return 'user_cancelled';
+  if (m.includes('lost') || m.includes('steady')) return 'tag_lost';
+  if (m.includes('timeout')) return 'timeout';
+  if (m.includes('not supported') || m.includes('unsupported')) {
+    return 'unsupported';
+  }
+  if (m.includes('not enabled') || m.includes('disabled')) return 'not_enabled';
+  if (m.includes('auth') || m.includes('mutual') || m.includes('security')) {
+    return 'auth_failed';
+  }
+  return 'reading_error';
+};
 
 // --- Minimal PNG encoder (pure JS, no native deps) ---
 // Uses deflate stored (uncompressed) blocks for O(n) encoding speed.
@@ -275,8 +302,40 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
   let progress = 0;
   const nfcManagerCardService = new NFCManagerCardService();
   const passportService = new EIDService(nfcManagerCardService, EIDService.NORMAL_MAX_TRANSCEIVE_LENGTH, EIDService.DEFAULT_MAX_BLOCKSIZE, false, true);
+
+  // Structured NFC diagnostics: record each step's outcome + timing + APDU SW
+  // into the session collector so the result screen can surface device-specific
+  // read failures. Best-effort and side-effect-only — never alters the flow.
+  diagnostics.nfcAttemptStarted();
+  const stepTimer = () => {
+    const t0 = Date.now();
+    return (step, ok, error) => {
+      const msg = error instanceof Error ? error.message : error ? String(error) : undefined;
+      // Store only the APDU status word and a COARSE category — never the raw
+      // error text, which could in theory embed field/PII values. The SW + step
+      // name + category carry all the actionable signal.
+      diagnostics.nfcStep({
+        step,
+        ok,
+        ms: Date.now() - t0,
+        sw: msg ? extractStatusWord(msg) : undefined,
+        error: msg ? categorizeNfcError(msg) : undefined
+      });
+    };
+  };
   try {
-    await passportService.open();
+    {
+      const done = stepTimer();
+      try {
+        await passportService.open();
+        // Reaching open() without throwing means the chip powered on / was seen.
+        diagnostics.nfcChipDetected();
+        done('open', true);
+      } catch (e) {
+        done('open', false, e);
+        throw e;
+      }
+    }
     progress = 1;
     if (progressCallback) {
       progressCallback(progress);
@@ -286,12 +345,17 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
     // Explicitly SELECT MF first so the SFI=0x1C context is correct,
     // regardless of which application the chip activates on power-on.
     let hasPACESucceeded = false;
-    try {
-      await passportService.sendSelectMF();
-      debugLog('EID', '[EID] SELECT MF OK');
-    } catch (mfErr) {
-      const mfMsg = mfErr instanceof Error ? mfErr.message : String(mfErr);
-      debugLog('EID', `[EID] SELECT MF failed (${mfMsg}), continuing with SFI read anyway`);
+    {
+      const done = stepTimer();
+      try {
+        await passportService.sendSelectMF();
+        done('selectMF', true);
+        debugLog('EID', '[EID] SELECT MF OK');
+      } catch (mfErr) {
+        done('selectMF', false, mfErr);
+        const mfMsg = mfErr instanceof Error ? mfErr.message : String(mfErr);
+        debugLog('EID', `[EID] SELECT MF failed (${mfMsg}), continuing with SFI read anyway`);
+      }
     }
     progress = 2;
     if (progressCallback) {
@@ -301,19 +365,24 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
     // Read EF.CardAccess — kept in a separate try/catch so we can distinguish
     // "file read failure" from "PACE protocol failure" in the logs.
     let cardAccessBuf = null;
-    try {
-      const cardAccessStream = passportService.getInputStream(EIDService.EF_CARD_ACCESS);
-      await cardAccessStream.init();
-      const cardAccessLen = cardAccessStream.getLength();
-      const buf = Buffer.alloc(cardAccessLen);
-      for (let i = 0; i < cardAccessLen; i++) {
-        buf[i] = await cardAccessStream.read();
+    {
+      const done = stepTimer();
+      try {
+        const cardAccessStream = passportService.getInputStream(EIDService.EF_CARD_ACCESS);
+        await cardAccessStream.init();
+        const cardAccessLen = cardAccessStream.getLength();
+        const buf = Buffer.alloc(cardAccessLen);
+        for (let i = 0; i < cardAccessLen; i++) {
+          buf[i] = await cardAccessStream.read();
+        }
+        cardAccessBuf = buf;
+        done('readCardAccess', true);
+        debugLog('EID', `[EID] EF.CardAccess read OK: ${cardAccessLen} bytes = ${cardAccessBuf.toString('hex')}`);
+      } catch (readErr) {
+        done('readCardAccess', false, readErr);
+        const readMsg = readErr instanceof Error ? readErr.message : String(readErr);
+        debugLog('EID', `[EID] EF.CardAccess read FAILED: ${readMsg} — falling back to BAC`);
       }
-      cardAccessBuf = buf;
-      debugLog('EID', `[EID] EF.CardAccess read OK: ${cardAccessLen} bytes = ${cardAccessBuf.toString('hex')}`);
-    } catch (readErr) {
-      const readMsg = readErr instanceof Error ? readErr.message : String(readErr);
-      debugLog('EID', `[EID] EF.CardAccess read FAILED: ${readMsg} — falling back to BAC`);
     }
     progress = 3;
     if (progressCallback) {
@@ -321,11 +390,17 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
     }
 
     // If EF.CardAccess was read successfully, attempt PACE.
+    if (cardAccessBuf === null) {
+      // EF.CardAccess unreadable (the readCardAccess step already recorded the
+      // failure/SW) → PACE can't be attempted; BAC will be used.
+      diagnostics.nfcPaceFellBackToBac('no_card_access');
+    }
     if (cardAccessBuf !== null) {
       try {
         const paceInfo = parsePACEInfoFromCardAccess(cardAccessBuf);
         if (paceInfo) {
           debugLog('EID', `[EID] PACE available: oid=${paceInfo.oid} parameterId=${paceInfo.parameterId}`);
+          diagnostics.nfcSetAuth('PACE', paceInfo.oid);
           // PACE is available - derive key from MRZ and perform PACE
           const bacKey = new BACKey(documentNumber, dateOfBirth, dateOfExpiry);
           const paceKey = PACEKeySpec.createMRZKey(bacKey.getKeySeedForPACE());
@@ -333,14 +408,23 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
           if (progressCallback) {
             progressCallback(progress);
           }
-          await passportService.doPACE(paceKey, paceInfo.oid, paceInfo.parameterId, progressCallback);
-          hasPACESucceeded = true;
-          debugLog('EID', '[EID] PACE succeeded');
+          const done = stepTimer();
+          try {
+            await passportService.doPACE(paceKey, paceInfo.oid, paceInfo.parameterId, progressCallback);
+            hasPACESucceeded = true;
+            done('paceAuth', true);
+            debugLog('EID', '[EID] PACE succeeded');
+          } catch (paceErr) {
+            done('paceAuth', false, paceErr);
+            throw paceErr;
+          }
         } else {
+          diagnostics.nfcPaceFellBackToBac('no_pace_info');
           debugLog('EID', '[EID] EF.CardAccess read OK but no PACE SecurityInfo found — document does not support PACE, falling back to BAC');
         }
       } catch (paceError) {
         // PACE protocol exchange failed — fall back to BAC
+        diagnostics.nfcPaceFellBackToBac('pace_failed');
         const msg = paceError instanceof Error ? paceError.message : String(paceError);
         debugLog('EID', `[EID] PACE protocol failed (${msg}), falling back to BAC`);
         if (paceError instanceof Error && paceError.stack) {
@@ -354,7 +438,16 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
     }
 
     // Select Applet for MRTD
-    await passportService.sendSelectApplet(hasPACESucceeded);
+    {
+      const done = stepTimer();
+      try {
+        await passportService.sendSelectApplet(hasPACESucceeded);
+        done('selectApplet', true);
+      } catch (e) {
+        done('selectApplet', false, e);
+        throw e;
+      }
+    }
     progress = 10;
     if (progressCallback) {
       progressCallback(progress);
@@ -367,8 +460,16 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
         await efComStream.read();
       } catch (error) {
         // EF_COM not available -> try to do BAC
+        diagnostics.nfcSetAuth('BAC');
         const bacKey = new BACKey(documentNumber, dateOfBirth, dateOfExpiry);
-        await passportService.doBAC(bacKey);
+        const done = stepTimer();
+        try {
+          await passportService.doBAC(bacKey);
+          done('bacAuth', true);
+        } catch (e) {
+          done('bacAuth', false, e);
+          throw e;
+        }
       }
     }
     progress = 20;
@@ -377,16 +478,25 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
     }
 
     // Read DG1 (MRZ Info)
-    const dg1InputStream = passportService.getInputStream(EIDService.EF_DG1);
-    await dg1InputStream.init();
-    const dg1File = new DG1File(undefined, dg1InputStream);
-    const mrzInfo = await dg1File.getMRZInfo();
+    const dg1Done = stepTimer();
+    let mrzInfo;
+    try {
+      const dg1InputStream = passportService.getInputStream(EIDService.EF_DG1);
+      await dg1InputStream.init();
+      const dg1File = new DG1File(undefined, dg1InputStream);
+      mrzInfo = await dg1File.getMRZInfo();
+      dg1Done('readDG1', true);
+    } catch (e) {
+      dg1Done('readDG1', false, e);
+      throw e;
+    }
     progress = 30;
     if (progressCallback) {
       progressCallback(progress);
     }
 
     // Read DG2 (Face Image)
+    const dg2Done = stepTimer();
     const dg2InputStream = passportService.getInputStream(EIDService.EF_DG2);
     await dg2InputStream.init();
     InputStream.onRead((totalBytesRead, fileLength) => {
@@ -399,7 +509,14 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
     let imageAsBase64 = '';
     let mimeType = '';
     const allFaceImageInfos = [];
-    const faceInfos = await dg2File.getFaceInfos();
+    let faceInfos;
+    try {
+      faceInfos = await dg2File.getFaceInfos();
+      dg2Done('readDG2', true);
+    } catch (e) {
+      dg2Done('readDG2', false, e);
+      throw e;
+    }
     for (let faceInfo of faceInfos) {
       allFaceImageInfos.push(...faceInfo.getFaceImageInfos());
     }
@@ -418,12 +535,15 @@ const eidReader = async (documentNumber, dateOfBirth, dateOfExpiry, progressCall
     if (progressCallback) {
       progressCallback(progress);
     }
+    diagnostics.nfcResult(true);
     return {
       mrz: mrzInfo,
       faceImage: imageAsBase64,
       mimeType: mimeType
     };
   } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    diagnostics.nfcResult(false, categorizeNfcError(msg));
     debugLog('EID', 'Error reading passport data', error);
   } finally {
     await passportService.close();

package/lib/module/Shared/Libs/MRZ_KNOWN_ISSUES.md

@@ -118,6 +118,13 @@ Covered by the "real letters in names are not eaten" tests in `mrz.utils.test.ts
   30–44-char MRZ line below that floor, so the native pipeline **crops to the
   on-screen scan frame and upscales + grayscale/contrast-enhances** before OCR.
   The MRZ band must be reasonably filled within the on-screen guide.
+  - Two distinct regions exist in the native code (don't confuse them):
+    the **MRZ-OCR crop** (`buildScanFrameRoiImage`: top 25% / bottom 12% / sides
+    4%, upscaled ≤2.5× to ≤2200px, grayscale, contrast 1.6×) and the
+    **brightness-sampling region** (the on-screen guide: 36% / 36% / 5%). Both are
+    the same on iOS and Android. The diagnostic report records the measured MRZ
+    band pixel height so you can tell when a device leaves the band below the
+    ~16 px/char floor.
 - **Glare / lamination.** Heavy glare on a glossy laminated card still degrades
   OCR; the enhancement helps but does not eliminate it. Steadying the card and
   reducing direct glare improves convergence.

package/lib/module/Shared/Libs/diagnosticReport.js

@@ -0,0 +1,133 @@
+"use strict";
+
+/**
+ * Builds the support diagnostic report from a scan session.
+ *
+ * Produces three things the result screen turns into a reviewable email:
+ *  - `diagnostics.json`  — technical signals (device, camera, MRZ, NFC steps).
+ *  - `scan-data.json`    — the scanned identity data + raw MRZ (PII; the user
+ *                          reviews it in the draft and chooses to send).
+ *  - a short, size-bounded plain-text BODY summary that always fits an email.
+ *
+ * The full detail lives in the JSON attachments; the email body is intentionally
+ * compact so the draft opens reliably on every mail client.
+ */
+
+/** ICAO 9303 7-3-1 weighted check digit (local copy; mirrors mrz.utils). */
+const icaoCheckDigit = str => {
+  const weights = [7, 3, 1];
+  let sum = 0;
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    const v = c === '<' ? 0 : c >= '0' && c <= '9' ? c.charCodeAt(0) - 48 : c.charCodeAt(0) - 55;
+    sum = (sum + weights[i % 3] * v) % 10;
+  }
+  return String(sum);
+};
+/** Compute per-field check-digit pass/fail for a TD1 MRZ (best-effort). */
+const computeTd1CheckDigits = mrzText => {
+  if (!mrzText) return undefined;
+  const lines = mrzText.split('\n').map(l => l.trim()).filter(Boolean);
+  if (lines.length < 2 || lines[0].length < 30 || lines[1].length < 30) {
+    return undefined; // only TD1 handled here; other formats omitted from summary
+  }
+  const l1 = lines[0];
+  const l2 = lines[1];
+  const result = {};
+  const check = (data, printed) => icaoCheckDigit(data) === printed ? 'pass' : 'fail';
+
+  // Turkish convention: a doc number may carry a leading serial LETTER, and the
+  // doc-number check digit is computed over the DIGITS ONLY (letter dropped).
+  // The TD1 composite then also diverges from strict ICAO for such cards (no
+  // interpretation of the letter reproduces it). To avoid reporting a misleading
+  // "fail" on a card the SDK legitimately accepted, detect the letter-prefix and
+  // treat both the doc-number and composite as validated under that convention.
+  const docData = l1.slice(5, 14);
+  const docPrinted = l1[14];
+  const hasLetterPrefix = /^[A-Z]/.test(docData);
+  const strictDocOk = icaoCheckDigit(docData) === docPrinted;
+  const turkishDocOk = hasLetterPrefix && icaoCheckDigit(docData.slice(1)) === docPrinted;
+  const docOk = strictDocOk || turkishDocOk;
+  result.documentNumber = docOk ? 'pass' : 'fail';
+  result.birthDate = check(l2.slice(0, 6), l2[6]);
+  result.expiry = check(l2.slice(8, 14), l2[14]);
+  const composite = l1.slice(5, 30) + l2.slice(0, 7) + l2.slice(8, 15) + l2.slice(18, 29);
+  const compStrict = check(composite, l2[29]);
+  // If the strict composite fails ONLY because of the Turkish letter-prefix
+  // doc number (which itself passed under the digits-only rule), don't surface a
+  // misleading failure — the SDK accepts these cards.
+  result.composite = compStrict === 'fail' && hasLetterPrefix && docOk ? 'pass' : compStrict;
+  // The Turkish convention was the deciding factor only when strict ICAO would
+  // have failed the doc number but the digits-only rule passes it.
+  const turkishLetterPrefix = !strictDocOk && turkishDocOk;
+  return {
+    checkDigits: result,
+    turkishLetterPrefix
+  };
+};
+const MAX_BODY_BYTES = 4096;
+const yesNo = b => b ? 'yes' : 'no';
+
+/** Assemble the full report bundle. Pure — no I/O, no native calls. */
+export const buildDiagnosticReport = params => {
+  const {
+    diag,
+    device,
+    scan,
+    sdkVersion,
+    sessionId
+  } = params;
+  const computed = computeTd1CheckDigits(scan.mrzText);
+  const checkDigits = diag.mrz.checkDigits ?? computed?.checkDigits;
+  // Set the Turkish-letter-prefix flag from the final accepted MRZ (the collector
+  // can't know it during scanning; the report does, from the MRZ text).
+  const turkishLetterPrefixApplied = diag.mrz.turkishLetterPrefixApplied || computed?.turkishLetterPrefix === true;
+
+  // --- diagnostics.json (technical, low-PII) ---
+  const diagnosticsObj = {
+    schemaVersion: diag.schemaVersion,
+    generatedAt: diag.generatedAt,
+    sessionId: sessionId ?? null,
+    sdk: {
+      platform: device.platform,
+      sdkVersion,
+      buildNumber: device.buildNumber
+    },
+    device,
+    scan: {
+      documentType: scan.documentType ?? diag.documentType ?? null,
+      dataSource: scan.dataSource ?? diag.dataSource ?? null,
+      totalDurationMs: diag.totalDurationMs,
+      camera: diag.camera
+    },
+    mrz: {
+      ...diag.mrz,
+      checkDigits: checkDigits ?? null,
+      turkishLetterPrefixApplied
+    },
+    nfc: diag.nfc,
+    errors: diag.errors
+  };
+
+  // --- scan-data.json (PII; user reviews before sending) ---
+  const scanDataObj = {
+    documentType: scan.documentType ?? diag.documentType ?? null,
+    dataSource: scan.dataSource ?? diag.dataSource ?? null,
+    mrzText: scan.mrzText ?? null,
+    fields: scan.mrzFields ?? null,
+    barcodeValue: scan.barcodeValue ?? null
+  };
+
+  // --- compact email body (always under MAX_BODY_BYTES) ---
+  const nfc = diag.nfc;
+  const nfcLine = nfc.attempted ? `${nfc.authProtocol}${nfc.paceFellBackToBac ? '→BAC' : ''} · ${nfc.succeeded ? 'success' : `failed at ${nfc.failureStep ?? '?'} (${nfc.errorCategory ?? 'error'})`}` : 'not attempted';
+  const checksLine = checkDigits ? Object.entries(checkDigits).map(([k, v]) => `${k}:${v}`).join(' ') : 'n/a';
+  const body = ['TRUSTCHEX SCAN REPORT', `Device: ${device.brand} ${device.model} · ${device.systemName} ${device.systemVersion}${device.apiLevel ? ` (API ${device.apiLevel})` : ''}`, `SDK: ${sdkVersion} (build ${device.buildNumber}) · ${device.manufacturer} · ${device.deviceId}`, `Document: ${scanDataObj.documentType ?? 'unknown'} · source: ${scanDataObj.dataSource ?? 'unknown'}`, `MRZ: ${diag.mrz.reachedStable ? 'stable' : 'NOT stable'} after ${diag.mrz.framesProcessed} frames · checks: ${checksLine}`, `Camera: ${diag.camera.frames} frames · brightness ${diag.camera.avgBrightness} (low:${yesNo(diag.camera.hadLowBrightness)} blur:${yesNo(diag.camera.hadBlurryFrames)})`, `NFC: ${nfcLine}`, sessionId ? `Session: ${sessionId}` : '', '', 'Describe the issue here:', '', '', '— Full diagnostics and document images are attached. Please review before sending; do not edit the attachments. —'].filter(Boolean).join('\n');
+  const subject = `Trustchex scan report — ${scanDataObj.documentType ?? 'doc'} — ${device.brand} ${device.model} — v${sdkVersion}${sessionId ? ` — ${sessionId}` : ''}`;
+  return {
+    diagnosticsJson: JSON.stringify(diagnosticsObj, null, 2),
+    scanDataJson: JSON.stringify(scanDataObj, null, 2),
+    body: body.length > MAX_BODY_BYTES ? body.slice(0, MAX_BODY_BYTES - 1) + '…' : body,
+    subject
+  };
+};

package/lib/module/Shared/Libs/diagnostics.js

@@ -0,0 +1,171 @@
+"use strict";
+
+/**
+ * Diagnostics collector for the "Report a scanning issue" feature.
+ *
+ * Accumulates a PII-light technical snapshot of a single scan session — camera
+ * quality, MRZ consensus, and (the highest-value, most device-specific part) a
+ * structured per-step NFC/eID read log. The result screen serialises this into
+ * the diagnostic email the user reviews and sends to support.
+ *
+ * Design notes:
+ * - This is a MODULE-LEVEL SINGLETON so the deep camera/EID call stack can record
+ *   into it without threading a prop/context through every layer. Call `reset()`
+ *   at the start of a scan flow.
+ * - It stores only TECHNICAL signals (counts, timings, brightness, APDU status
+ *   words, pass/fail). It deliberately holds NO identity data, images, MRZ text,
+ *   keys, or nonces — the scanned identity/images shown to the user come from the
+ *   result screen's own state, not from here, and are attached separately with
+ *   the user's explicit review in the email draft.
+ */
+
+/** A single step of the NFC/eID read, with its outcome and timing. */
+
+const emptyCamera = () => ({
+  frames: 0,
+  frameW: 0,
+  frameH: 0,
+  avgBrightness: 0,
+  minBrightness: 0,
+  maxBrightness: 0,
+  hadLowBrightness: false,
+  hadBlurryFrames: false
+});
+const emptyMrz = () => ({
+  framesProcessed: 0,
+  reachedStable: false,
+  stabilityFrames: 0,
+  minContestedMargin: 0,
+  turkishLetterPrefixApplied: false
+});
+const emptyNfc = () => ({
+  attempted: false,
+  chipDetected: false,
+  authProtocol: 'none',
+  paceFellBackToBac: false,
+  steps: [],
+  retryCount: 0,
+  succeeded: false
+});
+
+/**
+ * Accumulates one scan session's diagnostics. A single shared instance is
+ * exported below; tests can construct their own.
+ */
+export class DiagnosticsCollector {
+  startedAtMs = 0;
+  camera = emptyCamera();
+  mrz = emptyMrz();
+  nfc = emptyNfc();
+  errors = [];
+
+  /** Begin a fresh session — call when a scan flow starts. */
+  reset(nowMs) {
+    this.startedAtMs = nowMs;
+    this.documentType = undefined;
+    this.dataSource = undefined;
+    this.camera = emptyCamera();
+    this.mrz = emptyMrz();
+    this.nfc = emptyNfc();
+    this.errors = [];
+  }
+  setDocument(documentType, dataSource) {
+    if (documentType) this.documentType = documentType;
+    if (dataSource) this.dataSource = dataSource;
+  }
+
+  /** Merge a camera snapshot (called periodically as frames arrive). */
+  setCamera(c) {
+    this.camera = {
+      ...this.camera,
+      ...c
+    };
+  }
+
+  /** Merge MRZ consensus metrics. `reachedStable` is STICKY (once true, stays
+   * true) so a later frame's flicker can't unset that the scan did stabilise;
+   * `maxMrzBandHeightPx` keeps the largest seen. */
+  setMrz(m) {
+    const reachedStable = this.mrz.reachedStable || m.reachedStable === true;
+    const maxMrzBandHeightPx = Math.max(this.mrz.maxMrzBandHeightPx ?? 0, m.maxMrzBandHeightPx ?? 0) || undefined;
+    this.mrz = {
+      ...this.mrz,
+      ...m,
+      reachedStable,
+      maxMrzBandHeightPx
+    };
+  }
+
+  // ---- NFC: the structured per-step log ----
+
+  nfcAttemptStarted() {
+    // A fresh attempt: bump retry count if a previous attempt left steps.
+    if (this.nfc.attempted) this.nfc.retryCount += 1;
+    this.nfc.attempted = true;
+  }
+  nfcChipDetected() {
+    this.nfc.chipDetected = true;
+  }
+  nfcSetAuth(protocol, oid) {
+    this.nfc.authProtocol = protocol;
+    if (oid) this.nfc.paceOid = oid;
+  }
+  nfcPaceFellBackToBac(reason) {
+    this.nfc.paceFellBackToBac = true;
+    if (reason && !this.nfc.paceFallbackReason) {
+      this.nfc.paceFallbackReason = reason;
+    }
+  }
+
+  /** Record one completed step. Keep messages short and free of PII. */
+  nfcStep(step) {
+    this.nfc.steps.push(step);
+    if (!step.ok && !this.nfc.failureStep) {
+      this.nfc.failureStep = step.step;
+    }
+  }
+  nfcResult(succeeded, errorCategory) {
+    this.nfc.succeeded = succeeded;
+    if (succeeded) {
+      // The read ultimately succeeded — transient per-attempt failures (e.g. a
+      // recovered DG2 retry, or the expected EF.CardAccess 6982 on a BAC-only
+      // card) must NOT be reported as the outcome. Clear the failure markers.
+      this.nfc.failureStep = undefined;
+      this.nfc.errorCategory = undefined;
+    } else if (errorCategory) {
+      this.nfc.errorCategory = errorCategory;
+    }
+  }
+  addError(e) {
+    this.errors.push(e);
+  }
+
+  /** Build the serialisable snapshot. */
+  snapshot(nowMs, isoNow) {
+    return {
+      schemaVersion: 1,
+      generatedAt: isoNow,
+      documentType: this.documentType,
+      dataSource: this.dataSource,
+      totalDurationMs: this.startedAtMs ? Math.max(0, nowMs - this.startedAtMs) : 0,
+      camera: {
+        ...this.camera
+      },
+      mrz: {
+        ...this.mrz
+      },
+      nfc: {
+        ...this.nfc,
+        steps: this.nfc.steps.map(s => ({
+          ...s
+        }))
+      },
+      errors: this.errors.map(e => ({
+        ...e
+      }))
+    };
+  }
+}
+
+/** Shared session-scoped collector used across the scan flow. */
+export const diagnostics = new DiagnosticsCollector();

package/lib/module/Shared/Libs/mrzFrameAggregator.js

@@ -40,6 +40,12 @@ const FORMAT_GEOMETRY = {
   }
 };
 const MRZ_CHAR = /^[A-Z0-9<]$/;
+/**
+ * Floor applied to a frame's confidence multiplier. A frame ML Kit was very
+ * unsure about still contributes (it may carry the only reading of a cell), but
+ * at a fraction of a confident frame's weight.
+ */
+const MIN_CONFIDENCE_WEIGHT = 0.25;
 /**
  * Reconstructs fixed-width MRZ candidate line-sets for a frame's raw OCR text.
  * Reuses the same reconstruction the single-frame validator uses, so the
@@ -181,7 +187,12 @@ export class MRZFrameAggregator {
    * consensus is returned.
    */
   addFrame(input) {
-    const weight = input.weight && input.weight > 0 ? input.weight : 1;
+    const baseWeight = input.weight && input.weight > 0 ? input.weight : 1;
+    // Fold OCR confidence into the weight (clamped to [floor, 1]). Absent
+    // confidence leaves the weight unchanged, so callers without per-symbol
+    // confidence (e.g. iOS ML Kit) keep the prior sharpness-only behaviour.
+    const confidenceFactor = typeof input.confidence === 'number' && Number.isFinite(input.confidence) ? Math.min(1, Math.max(MIN_CONFIDENCE_WEIGHT, input.confidence)) : 1;
+    const weight = baseWeight * confidenceFactor;
     const lines = linesForFrame(input.text);
     if (lines) {
       // Determine the format this frame's lines fit (by line count + width).
@@ -244,18 +255,30 @@ export class MRZFrameAggregator {
    * is what turns "looks valid this frame" into "the camera agrees across frames".
    */
   consensusIsConfident(format) {
+    return this.minContestedMargin(format) >= this.minMargin;
+  }
+
+  /**
+   * Smallest winning vote margin across all CONTESTED cells (where >1 distinct
+   * char was voted). Returns Infinity when no cell is contested. Used both to
+   * gate confidence and to surface a diagnostic of how narrowly a look-alike was
+   * resolved at acceptance.
+   */
+  minContestedMargin(format) {
     const geom = FORMAT_GEOMETRY[format];
     const tally = this.tallies[format];
+    let min = Infinity;
     for (let li = 0; li < geom.lines; li++) {
       for (let ci = 0; ci < geom.width; ci++) {
         const cell = tally[li][ci];
         const weights = Object.values(cell);
         if (weights.length < 2) continue; // uncontested cell — no ambiguity
         weights.sort((a, b) => b - a);
-        if (weights[0] - weights[1] < this.minMargin) return false;
+        const margin = weights[0] - weights[1];
+        if (margin < min) min = margin;
       }
     }
-    return true;
+    return min;
   }
 
   /** Read out the winning character per cell for a format. */
@@ -293,7 +316,9 @@ export class MRZFrameAggregator {
         mrz: null,
         validation: null,
         frames: this.frameCount,
-        stable: false
+        stable: false,
+        stableStreak: 0,
+        minContestedMargin: Infinity
       };
     }
     let bestMrz = null;
@@ -338,7 +363,9 @@ export class MRZFrameAggregator {
       mrz: bestMrz,
       validation: bestValidation,
       frames: this.frameCount,
-      stable: bestValid && confident && this.stableStreak >= this.stabilityTarget
+      stable: bestValid && confident && this.stableStreak >= this.stabilityTarget,
+      stableStreak: this.stableStreak,
+      minContestedMargin: bestFormat != null ? this.minContestedMargin(bestFormat) : Infinity
     };
   }
 }