@trustchex/react-native-sdk 1.478.7 → 1.481.1

package/src/Shared/EIDReader/eidReader.ts

@@ -9,6 +9,33 @@ import { Buffer } from 'buffer';
 import { MRZInfo } from './lds/icao/mrzInfo';
 import { InputStream } from './java/inputStream';
 import { debugLog } from '../Libs/debug.utils';
+import { diagnostics } from '../Libs/diagnostics';
+
+/**
+ * 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: string): string | undefined => {
+  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: string): string => {
+  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.
@@ -307,8 +334,40 @@ const eidReader = async (
     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: string, ok: boolean, error?: unknown) => {
+      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) {
@@ -320,15 +379,20 @@ const eidReader = async (
     // 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;
@@ -339,28 +403,33 @@ const eidReader = async (
     // 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: Buffer | null = 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;
@@ -369,6 +438,11 @@ const eidReader = async (
     }
 
     // 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);
@@ -378,6 +452,7 @@ const eidReader = async (
             '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());
@@ -387,15 +462,23 @@ const eidReader = async (
             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'
@@ -403,6 +486,7 @@ const eidReader = async (
         }
       } catch (paceError) {
         // PACE protocol exchange failed — fall back to BAC
+        diagnostics.nfcPaceFellBackToBac('pace_failed');
         const msg =
           paceError instanceof Error ? paceError.message : String(paceError);
         debugLog(
@@ -421,7 +505,16 @@ const eidReader = async (
     }
 
     // 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) {
@@ -436,8 +529,16 @@ const eidReader = async (
         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;
+        }
       }
     }
 
@@ -447,10 +548,18 @@ const eidReader = async (
     }
 
     // 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: 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) {
@@ -458,6 +567,7 @@ const eidReader = async (
     }
 
     // Read DG2 (Face Image)
+    const dg2Done = stepTimer();
     const dg2InputStream = passportService.getInputStream(EIDService.EF_DG2);
     await dg2InputStream.init();
     InputStream.onRead((totalBytesRead, fileLength) => {
@@ -471,7 +581,14 @@ const eidReader = async (
     let mimeType = '';
 
     const allFaceImageInfos: FaceImageInfo[] = [];
-    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());
     }
@@ -493,12 +610,15 @@ const eidReader = async (
       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/src/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/src/Shared/Libs/diagnosticReport.ts

@@ -0,0 +1,206 @@
+/**
+ * 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.
+ */
+import type { DiagnosticsSnapshot } from './diagnostics';
+import type { DeviceDetails } from './native-device-info.utils';
+import type { MRZFields } from '../Types/mrzFields';
+
+/** ICAO 9303 7-3-1 weighted check digit (local copy; mirrors mrz.utils). */
+const icaoCheckDigit = (str: string): string => {
+  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);
+};
+
+export interface ScanDataForReport {
+  documentType?: string;
+  dataSource?: string;
+  mrzText?: string | null;
+  mrzFields?: MRZFields | null;
+  barcodeValue?: string | null;
+  /** Which images were captured (presence only, used for the body summary). */
+  images?: {
+    mrzSide?: boolean;
+    front?: boolean;
+    face?: boolean;
+    nfcFace?: boolean;
+  };
+}
+
+interface Td1CheckResult {
+  checkDigits: Record<string, 'pass' | 'fail'>;
+  /** True when the Turkish leading-letter (digits-only) convention was applied. */
+  turkishLetterPrefix: boolean;
+}
+
+/** Compute per-field check-digit pass/fail for a TD1 MRZ (best-effort). */
+const computeTd1CheckDigits = (
+  mrzText?: string | null
+): Td1CheckResult | undefined => {
+  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: Record<string, 'pass' | 'fail'> = {};
+  const check = (data: string, printed: string) =>
+    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 };
+};
+
+export interface DiagnosticReportBundle {
+  /** Pretty-printed technical report. */
+  diagnosticsJson: string;
+  /** Pretty-printed scanned identity data (PII). */
+  scanDataJson: string;
+  /** Compact, size-bounded plain-text email body. */
+  body: string;
+  /** Suggested email subject. */
+  subject: string;
+}
+
+const MAX_BODY_BYTES = 4096;
+
+const yesNo = (b: boolean | undefined) => (b ? 'yes' : 'no');
+
+/** Assemble the full report bundle. Pure — no I/O, no native calls. */
+export const buildDiagnosticReport = (params: {
+  diag: DiagnosticsSnapshot;
+  device: DeviceDetails;
+  scan: ScanDataForReport;
+  sdkVersion: string;
+  sessionId?: string;
+}): DiagnosticReportBundle => {
+  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,
+  };
+};