@trustchex/react-native-sdk 1.478.7 → 1.483.4

package/src/Shared/Libs/diagnostics.ts

@@ -0,0 +1,251 @@
+/**
+ * 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. */
+export interface NfcStep {
+  /** Step name: 'open' | 'selectMF' | 'readCardAccess' | 'paceAuth' | 'bacAuth'
+   * | 'selectApplet' | 'readDG1' | 'readDG2' | … */
+  step: string;
+  ok: boolean;
+  ms: number;
+  /** APDU status word (hex, e.g. "6982") when the step failed at the APDU level. */
+  sw?: string;
+  /** Coarse, non-PII error CATEGORY when the step failed (e.g. "auth_failed",
+   * "tag_lost", "reading_error") — never the raw error text. */
+  error?: string;
+}
+
+export interface NfcDiagnostics {
+  attempted: boolean;
+  chipDetected: boolean;
+  /** 'PACE' | 'BAC' | 'none' */
+  authProtocol: 'PACE' | 'BAC' | 'none';
+  paceFellBackToBac: boolean;
+  /** PACE object identifier string when PACE was attempted. */
+  paceOid?: string;
+  /** Why PACE wasn't used / fell back: 'no_card_access' | 'no_pace_info' |
+   * 'pace_failed'. Distinguishes device/chip-specific PACE issues. */
+  paceFallbackReason?: string;
+  steps: NfcStep[];
+  /** Name of the first failing step, if any. */
+  failureStep?: string;
+  /** Coarse category: 'auth_failed' | 'tag_lost' | 'timeout' | 'unsupported'
+   * | 'not_enabled' | 'user_cancelled' | 'reading_error' | null */
+  errorCategory?: string;
+  retryCount: number;
+  succeeded: boolean;
+}
+
+export interface CameraDiagnostics {
+  frames: number;
+  frameW: number;
+  frameH: number;
+  avgBrightness: number;
+  minBrightness: number;
+  maxBrightness: number;
+  hadLowBrightness: boolean;
+  hadBlurryFrames: boolean;
+  /**
+   * The thresholds the measured values were judged against, so support can read
+   * "117 measured vs 65 floor" rather than just a pass/fail flag. Recorded once.
+   */
+  thresholds?: {
+    brightnessLow?: number;
+    brightnessHigh?: number;
+    minBrightness?: number;
+    blur?: number;
+  };
+}
+
+export interface MrzDiagnostics {
+  framesProcessed: number;
+  reachedStable: boolean;
+  stabilityFrames: number;
+  /** Smallest winning vote margin across contested cells at acceptance. */
+  minContestedMargin: number;
+  /**
+   * Largest MRZ-band pixel height seen (max OCR'd text-block height). Compared
+   * to the ~16px/character ML Kit floor, this explains "scans on device A,
+   * fails on device B" — a smaller band falls below the OCR resolution floor.
+   */
+  maxMrzBandHeightPx?: number;
+  format?: string;
+  /** Per-field check-digit outcomes: 'pass' | 'fail' (no values, no PII). */
+  checkDigits?: Record<string, 'pass' | 'fail'>;
+  /** True when the Turkish leading-serial-letter check-digit convention was used
+   * to accept the document number (set at report-build time from the final MRZ). */
+  turkishLetterPrefixApplied: boolean;
+}
+
+export interface DiagnosticsSnapshot {
+  schemaVersion: number;
+  generatedAt: string;
+  documentType?: string;
+  dataSource?: string;
+  totalDurationMs: number;
+  camera: CameraDiagnostics;
+  mrz: MrzDiagnostics;
+  nfc: NfcDiagnostics;
+  /** Sanitised, non-PII error entries collected during the session. */
+  errors: Array<{ code?: string; category?: string; screen?: string }>;
+}
+
+const emptyCamera = (): CameraDiagnostics => ({
+  frames: 0,
+  frameW: 0,
+  frameH: 0,
+  avgBrightness: 0,
+  minBrightness: 0,
+  maxBrightness: 0,
+  hadLowBrightness: false,
+  hadBlurryFrames: false,
+});
+
+const emptyMrz = (): MrzDiagnostics => ({
+  framesProcessed: 0,
+  reachedStable: false,
+  stabilityFrames: 0,
+  minContestedMargin: 0,
+  turkishLetterPrefixApplied: false,
+});
+
+const emptyNfc = (): NfcDiagnostics => ({
+  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 {
+  private startedAtMs = 0;
+  private documentType?: string;
+  private dataSource?: string;
+  private camera = emptyCamera();
+  private mrz = emptyMrz();
+  private nfc = emptyNfc();
+  private errors: DiagnosticsSnapshot['errors'] = [];
+
+  /** Begin a fresh session — call when a scan flow starts. */
+  reset(nowMs: number): void {
+    this.startedAtMs = nowMs;
+    this.documentType = undefined;
+    this.dataSource = undefined;
+    this.camera = emptyCamera();
+    this.mrz = emptyMrz();
+    this.nfc = emptyNfc();
+    this.errors = [];
+  }
+
+  setDocument(documentType?: string, dataSource?: string): void {
+    if (documentType) this.documentType = documentType;
+    if (dataSource) this.dataSource = dataSource;
+  }
+
+  /** Merge a camera snapshot (called periodically as frames arrive). */
+  setCamera(c: Partial<CameraDiagnostics>): void {
+    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: Partial<MrzDiagnostics>): void {
+    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(): void {
+    // 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(): void {
+    this.nfc.chipDetected = true;
+  }
+
+  nfcSetAuth(protocol: 'PACE' | 'BAC' | 'none', oid?: string): void {
+    this.nfc.authProtocol = protocol;
+    if (oid) this.nfc.paceOid = oid;
+  }
+
+  nfcPaceFellBackToBac(reason?: string): void {
+    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: NfcStep): void {
+    this.nfc.steps.push(step);
+    if (!step.ok && !this.nfc.failureStep) {
+      this.nfc.failureStep = step.step;
+    }
+  }
+
+  nfcResult(succeeded: boolean, errorCategory?: string): void {
+    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: { code?: string; category?: string; screen?: string }): void {
+    this.errors.push(e);
+  }
+
+  /** Build the serialisable snapshot. */
+  snapshot(nowMs: number, isoNow: string): DiagnosticsSnapshot {
+    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/src/Shared/Libs/documentDataNormalizer.ts

@@ -0,0 +1,108 @@
+import type { MRZFields } from '../Types/mrzFields';
+import type { DocumentData } from '../Types/documentData';
+import type { MRZInfo } from '../EIDReader/lds/icao/mrzInfo';
+
+/**
+ * Expand a 2-digit MRZ year to a 4-digit calendar year.
+ * ICAO 9303: YY >= 30 → 19YY, YY < 30 → 20YY.
+ * (Threshold 30 keeps all current valid documents in range.)
+ */
+function expandYear(yy: string): string {
+  const n = parseInt(yy, 10);
+  return n >= 30 ? `19${yy}` : `20${yy}`;
+}
+
+/**
+ * Convert a YYMMDD MRZ date string to ISO 8601 YYYY-MM-DD.
+ * Returns null for empty, null, or malformed input.
+ */
+function mrzDateToISO(raw: string | null | undefined): string | null {
+  if (!raw || raw.length !== 6) return null;
+  const yy = raw.slice(0, 2);
+  const mm = raw.slice(2, 4);
+  const dd = raw.slice(4, 6);
+  if (!/^\d{6}$/.test(raw)) return null;
+  return `${expandYear(yy)}-${mm}-${dd}`;
+}
+
+/**
+ * Normalize the MRZ document-code field to a single-letter form.
+ * The `mrz` npm package returns "ID" for TD1, while the chip returns "I".
+ */
+function normalizeDocumentType(raw: string | null | undefined): string {
+  if (!raw) return 'I';
+  const upper = raw.trim().toUpperCase();
+  if (upper === 'ID') return 'I';
+  // TD2 can be "IR", "AC", etc — take only the first character
+  return upper.charAt(0);
+}
+
+/**
+ * Normalize the sex field to a single uppercase letter.
+ * NFC chip: "M" | "F" | "U" | "X"
+ * mrz package: "male" | "female" | "" | null
+ */
+function normalizeSex(raw: string | null | undefined): 'M' | 'F' | 'X' | 'U' {
+  if (!raw) return 'U';
+  switch (raw.trim().toLowerCase()) {
+    case 'm':
+    case 'male':
+      return 'M';
+    case 'f':
+    case 'female':
+      return 'F';
+    case 'x':
+    case 'unspecified':
+      return 'X';
+    default:
+      return 'U';
+  }
+}
+
+/**
+ * Trim a string and return null if empty or only filler chars.
+ */
+function clean(val: string | null | undefined): string | null {
+  if (!val) return null;
+  const t = val.replace(/</g, '').trim();
+  return t.length > 0 ? t : null;
+}
+
+/**
+ * Build a DocumentData from a chip-read MRZInfo object (NFC path).
+ */
+export function normalizeFromMRZInfo(mrz: MRZInfo): DocumentData {
+  const rawPersonal =
+    mrz.getPersonalNumber() ?? clean(mrz.getOptionalData1());
+
+  return {
+    documentType: normalizeDocumentType(mrz.getDocumentCode()),
+    issuingCountry: mrz.getIssuingState().replace(/<$/, '').trim(),
+    nationality: mrz.getNationality().replace(/<$/, '').trim(),
+    documentNumber: mrz.getDocumentNumber().trim(),
+    personalNumber: clean(rawPersonal),
+    lastName: mrz.getPrimaryIdentifier().trim(),
+    firstName: mrz.getSecondaryIdentifier().trim(),
+    sex: normalizeSex(mrz.getGender().getStrCode()),
+    dateOfBirth: mrzDateToISO(mrz.getDateOfBirth()),
+    dateOfExpiry: mrzDateToISO(mrz.getDateOfExpiry()),
+  };
+}
+
+/**
+ * Build a DocumentData from an MRZFields object (camera OCR path).
+ */
+export function normalizeFromMRZFields(fields: MRZFields): DocumentData {
+  return {
+    documentType: normalizeDocumentType(fields.documentCode),
+    issuingCountry: clean(fields.issuingState) ?? '',
+    nationality: clean(fields.nationality) ?? '',
+    documentNumber: clean(fields.documentNumber) ?? '',
+    personalNumber: clean(fields.personalNumber),
+    lastName: clean(fields.lastName) ?? '',
+    firstName: clean(fields.firstName) ?? '',
+    sex: normalizeSex(fields.sex),
+    dateOfBirth: mrzDateToISO(fields.birthDate),
+    dateOfExpiry: mrzDateToISO(fields.expirationDate),
+  };
+}

package/src/Shared/Libs/mrz.utils.ts

@@ -1244,18 +1244,13 @@ const validateMRZ = (
       documentCode: result.fields.documentCode || null,
       issuingState: result.fields.issuingState || null,
       documentNumber: result.fields.documentNumber || null,
-      documentNumberCheckDigit: result.fields.documentNumberCheckDigit || null,
       nationality: result.fields.nationality || null,
       lastName: result.fields.lastName || null,
       firstName: result.fields.firstName || null,
       sex: result.fields.sex || null,
       birthDate: result.fields.birthDate || null,
-      birthDateCheckDigit: result.fields.birthDateCheckDigit || null,
       expirationDate: result.fields.expirationDate || null,
-      expirationDateCheckDigit: result.fields.expirationDateCheckDigit || null,
       personalNumber: result.fields.personalNumber || null,
-      personalNumberCheckDigit: result.fields.personalNumberCheckDigit || null,
-      compositeCheckDigit: result.fields.compositeCheckDigit || null,
       optional1: result.fields.optional1 || null,
       optional2: result.fields.optional2 || null,
     };

package/src/Shared/Libs/mrzFrameAggregator.ts

@@ -43,8 +43,29 @@ export interface MRZFrameInput {
    * focus-weighted voting beats unweighted.
    */
   weight?: number;
+  /**
+   * Optional OCR confidence for this frame, in [0, 1] — e.g. ML Kit's mean
+   * per-symbol confidence over the MRZ characters (Android bundled library only;
+   * iOS ML Kit exposes no symbol confidence). When present it MULTIPLIES `weight`,
+   * so a frame the recognizer was unsure about contributes proportionally fewer
+   * votes than a confident one of the same sharpness. This is the per-frame form
+   * of confidence-weighted voting: it can't misalign cells (unlike threading
+   * per-column confidence through the column-shifting line reconstruction), yet
+   * still lets confident frames dominate look-alike ties (A↔4, S↔5, B↔8).
+   *
+   * A confidence floor is applied so a single near-zero frame is down-weighted
+   * but never fully silenced (it may still hold the only vote for some cell).
+   */
+  confidence?: number;
 }
 
+/**
+ * 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;
+
 export interface MRZConsensus {
   /** Best consensus MRZ (newline-joined fixed-width lines), or null if none yet. */
   mrz: string | null;
@@ -57,6 +78,18 @@ export interface MRZConsensus {
    * last `stabilityTarget` contributing frames. Callers should advance only then.
    */
   stable: boolean;
+  /**
+   * How many consecutive contributing frames the current (valid) consensus has
+   * stayed unchanged. Diagnostic: convergence speed across devices.
+   */
+  stableStreak: number;
+  /**
+   * Smallest winning vote margin across all CONTESTED cells of the best format
+   * (cells where >1 distinct char was voted). Higher = more confident reading;
+   * a low value at acceptance means a look-alike was barely resolved. Infinity
+   * when no cell is contested (a perfectly clean read). Diagnostic only.
+   */
+  minContestedMargin: number;
 }
 
 export interface MRZFrameAggregatorOptions {
@@ -244,7 +277,15 @@ export class MRZFrameAggregator {
    * consensus is returned.
    */
   addFrame(input: MRZFrameInput): MRZConsensus {
-    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) {
@@ -311,18 +352,30 @@ export class MRZFrameAggregator {
    * is what turns "looks valid this frame" into "the camera agrees across frames".
    */
   private consensusIsConfident(format: string): boolean {
+    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.
+   */
+  private minContestedMargin(format: string): number {
     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. */
@@ -365,6 +418,8 @@ export class MRZFrameAggregator {
         validation: null,
         frames: this.frameCount,
         stable: false,
+        stableStreak: 0,
+        minContestedMargin: Infinity,
       };
     }
 
@@ -415,6 +470,9 @@ export class MRZFrameAggregator {
       frames: this.frameCount,
       stable:
         bestValid && confident && this.stableStreak >= this.stabilityTarget,
+      stableStreak: this.stableStreak,
+      minContestedMargin:
+        bestFormat != null ? this.minContestedMargin(bestFormat) : Infinity,
     };
   }
 }

package/src/Shared/Libs/mrzTransliteration.ts

@@ -0,0 +1,131 @@
+import type { DocumentName } from '../Types/documentReadResult';
+
+type DigraphMap = [string, string][];
+
+// ICAO 9303 digraphs safe to apply universally — these appear across many
+// national variants and are unlikely to collide with real letter sequences.
+// SS→ß, TH→Þ etc. are excluded: too ambiguous (HASSAN, THOMAS).
+const UNIVERSAL: DigraphMap = [
+  ['OE', 'Ö'],
+  ['UE', 'Ü'],
+];
+
+const GERMAN: DigraphMap = [
+  ['AE', 'Ä'],
+  ['OE', 'Ö'],
+  ['UE', 'Ü'],
+  ['SS', 'ß'],
+];
+
+const SWEDISH: DigraphMap = [
+  ['AA', 'Å'],
+  ['AE', 'Æ'],
+  ['OE', 'Ø'],
+];
+
+const DANISH: DigraphMap = [
+  ['AA', 'Å'],
+  ['AE', 'Æ'],
+  ['OE', 'Ø'],
+];
+
+const NORWEGIAN: DigraphMap = [
+  ['AA', 'Å'],
+  ['AE', 'Æ'],
+  ['OE', 'Ø'],
+];
+
+const FRENCH: DigraphMap = [
+  ['OE', 'Œ'],
+  ['AE', 'Æ'],
+];
+
+const ICELANDIC: DigraphMap = [
+  ['AE', 'Æ'],
+  ['OE', 'Ö'],
+  ['TH', 'Þ'],
+  ['D', 'Ð'],
+];
+
+const COUNTRY_MAP: Record<string, DigraphMap> = {
+  DEU: GERMAN,
+  AUT: GERMAN,
+  CHE: GERMAN,
+  SWE: SWEDISH,
+  DNK: DANISH,
+  NOR: NORWEGIAN,
+  FRA: FRENCH,
+  LUX: FRENCH,
+  ISL: ICELANDIC,
+};
+
+function applyDigraphMap(token: string, map: DigraphMap): string {
+  let result = '';
+  let i = 0;
+  while (i < token.length) {
+    let matched = false;
+    for (const [digraph, unicode] of map) {
+      if (token.startsWith(digraph, i)) {
+        result += unicode;
+        i += digraph.length;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      result += token[i];
+      i++;
+    }
+  }
+  return result;
+}
+
+function convertName(rawName: string, map: DigraphMap): string {
+  return rawName
+    .split(' ')
+    .map((word) => applyDigraphMap(word, map))
+    .join(' ');
+}
+
+export function buildDocumentName(
+  rawFirst: string,
+  rawLast: string,
+  issuingState: string | null | undefined,
+  dg11First?: string | null,
+  dg11Last?: string | null
+): DocumentName {
+  if (dg11First != null && dg11Last != null && (dg11First || dg11Last)) {
+    return {
+      rawFirst,
+      rawLast,
+      displayFirst: dg11First,
+      displayLast: dg11Last,
+      source: 'dg11',
+    };
+  }
+
+  const country = (issuingState ?? '').toUpperCase().trim();
+  const map = COUNTRY_MAP[country];
+
+  if (map) {
+    return {
+      rawFirst,
+      rawLast,
+      displayFirst: convertName(rawFirst, map),
+      displayLast: convertName(rawLast, map),
+      source: 'reverse_table',
+    };
+  }
+
+  // No country-specific table: apply OE→Ö and UE→Ü universally.
+  const displayFirst = convertName(rawFirst, UNIVERSAL);
+  const displayLast = convertName(rawLast, UNIVERSAL);
+  const changed = displayFirst !== rawFirst || displayLast !== rawLast;
+  return {
+    rawFirst,
+    rawLast,
+    displayFirst,
+    displayLast,
+    source: changed ? 'reverse_table' : 'raw',
+  };
+}