@trustchex/react-native-sdk 1.475.0 → 1.478.7

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

@@ -14,6 +14,34 @@ const RECOVERY_BUDGET_MS = 80;
 let recoveryDeadline = 0;
 const recoveryExpired = (): boolean => Date.now() > recoveryDeadline;
 
+/**
+ * Pads a TD1 line to the fixed 30-char width.
+ *
+ * The naive `s.padEnd(30, '<')` is WRONG for the date record (line 2): its last
+ * character is the composite check digit, preceded by an 11-char optional-data
+ * filler run. OCR routinely UNDER-COUNTS that low-contrast `<<<` run, so the OCR
+ * string arrives short AND ending in the composite digit (e.g. a 28-char
+ * `…TUR<<<<<<<<<6`). `padEnd` then appends fillers AFTER the digit
+ * (`…6<<`), stranding the composite mid-line: the parser absorbs it into the
+ * optional field and the composite check fails, after which a recompute writes a
+ * WRONG digit over the misaligned layout — a plausible-but-malformed MRZ.
+ *
+ * The fix is layout-aware: when a short line ends in a digit, that digit is the
+ * trailing check digit, so re-grow the filler region BEFORE it. We only do this
+ * for the date record (`isDateRecord`); the doc record (line 1) ends in optional
+ * data, not a check digit, so plain right-padding is correct there.
+ */
+const padTD1Line = (s: string, isDateRecord: boolean = false): string => {
+  if (s.length >= 30) return s.slice(0, 30);
+  const last = s[s.length - 1];
+  if (isDateRecord && last >= '0' && last <= '9') {
+    // Trailing digit is the composite check digit — insert the dropped fillers
+    // BEFORE it so it lands at position 29.
+    return s.slice(0, -1).padEnd(29, '<') + last;
+  }
+  return s.padEnd(30, '<');
+};
+
 /**
  * MRZ Format Types according to ICAO 9303
  */
@@ -341,23 +369,55 @@ const reconstructMRZCandidates = (rawText: string): string[][] => {
         l1.slice(5);
       let l2: string;
       if (l2m) {
-        // Use the matched date record, padded to 30.
-        l2 = pad(l2m, 30);
+        // Use the matched date record. It is the TD1 line whose trailing char is
+        // the composite check digit, so pad layout-aware: a short line ending in
+        // a digit gets its dropped filler run restored BEFORE that digit (a
+        // plain right-pad would strand the composite mid-line). See padTD1Line.
+        l2 = padTD1Line(l2m, true);
       } else {
         const after = flat.indexOf(l1Source) + l1Source.length;
-        l2 = pad(flat.slice(after, after + 30), 30);
+        l2 = padTD1Line(flat.slice(after, after + 30), true);
       }
-      // Line 3 (name): the longest letter+filler OCR line that is NOT the doc or
-      // date line — exclude obvious front-of-card title words by requiring fillers.
-      const nameRuns = ocrLines.filter(
-        (l) =>
-          l !== l1Source &&
-          l !== l2Line &&
-          /^[A-Z<]+$/.test(l) &&
-          /</.test(l) &&
-          l.length >= 5
-      );
-      const l3 = pad(nameRuns.sort((a, b) => b.length - a.length)[0] ?? '', 30);
+      // Line 3 (name): the longest mostly-letters+filler OCR line that is NOT the
+      // doc or date line. OCR mangles the name line too — a leading "O" reads as
+      // "0", and the trailing "<" fillers read as K/C — so we DON'T require a
+      // pure [A-Z<] line (that wrongly drops "0ZCAN<<ERDAL…" entirely). Accept a
+      // line that is predominantly letters/fillers, then normalise it.
+      const isNameLike = (l: string): boolean => {
+        if (l === l1Source || l === l2Line || l.length < 5) return false;
+        if (!/</.test(l)) return false; // must have at least one filler
+        // Must look like "SURNAME<<NAMES…": starts with a letter (or its digit
+        // look-alike) and is dominated by letters/fillers, not a numeric record.
+        if (!/^[A-Z0-9]/.test(l)) return false;
+        const letters = (l.match(/[A-Z]/g) || []).length;
+        const digits = (l.match(/[0-9]/g) || []).length;
+        // A date/doc record is digit-heavy; a name is letter-heavy.
+        return letters >= 3 && letters >= digits;
+      };
+      // Normalise a name line: digit look-alikes back to letters (O/I/S/B/Z/G),
+      // and the filler-letter run misreads (K/C/E/G adjacent to fillers) to "<".
+      const normaliseName = (l: string): string => {
+        const digitToLetter: Record<string, string> = {
+          '0': 'O',
+          '1': 'I',
+          '5': 'S',
+          '8': 'B',
+          '2': 'Z',
+          '6': 'G',
+        };
+        return (
+          l
+            // digit look-alikes inside the name → letters
+            .replace(/[015862]/g, (d) => digitToLetter[d] ?? d)
+            // a run of filler-letters (K/C/E/G) flanked by fillers or at the tail
+            // is the trailing/internal filler region
+            .replace(/(?<=<)[KCEG]+(?=<|$)/g, (m) => '<'.repeat(m.length))
+            .replace(/[KCEG]+$/g, (m) => '<'.repeat(m.length))
+        );
+      };
+      const nameRuns = ocrLines.filter(isNameLike);
+      const bestName = nameRuns.sort((a, b) => b.length - a.length)[0] ?? '';
+      const l3 = pad(normaliseName(bestName), 30);
       candidates.push([l1, l2, l3]);
     }
   }
@@ -599,6 +659,118 @@ const icaoCheckDigit = (str: string): string => {
   return String(sum);
 };
 
+/**
+ * Rebuilds the fixed-width MRZ lines from a parse result's per-field `ranges`,
+ * which carry the actual characters at known line/column spans. Works for both
+ * valid and invalid parses (the `mrz` library populates ranges either way), so
+ * callers can read the PRINTED characters — e.g. a check digit the parser
+ * rejected — straight from the reconstructed line. Lines default to all-filler.
+ */
+const linesFromParseRanges = (
+  result: ReturnType<typeof parse>,
+  width: number,
+  lineCount: number
+): string[] => {
+  const buffers: string[][] = Array.from({ length: lineCount }, () =>
+    new Array(width).fill('<')
+  );
+  for (const detail of result.details ?? []) {
+    for (const range of detail.ranges ?? []) {
+      // `raw` (the actual characters at this span) exists at runtime but isn't in
+      // the `mrz` Range type.
+      const { line, start, raw = '' } = range as typeof range & { raw?: string };
+      const buf = buffers[line];
+      if (!buf) continue;
+      for (let i = 0; i < raw.length && start + i < width; i++) {
+        buf[start + i] = raw[i];
+      }
+    }
+  }
+  return buffers.map((b) => b.join(''));
+};
+
+/**
+ * Accepts a TD1 parse that the `mrz` library marks invalid SOLELY because of the
+ * Turkish e-ID document-number check-digit convention. (Full writeup: §2a in
+ * MRZ_KNOWN_ISSUES.md.)
+ *
+ * Turkish identity cards put a SERIAL LETTER at the start of the 9-char document
+ * number (e.g. "A53032352", "A49M38410"). Empirically — verified against real
+ * cards — Türkiye computes the document-number check digit over the number with
+ * that LEADING letter EXCLUDED (interior letters are kept), which diverges from
+ * strict ICAO 9303 (where A=10 is included). So a genuine card like "A53032352"
+ * (printed check digit 5) FAILS the strict check (which wants 7) even though the
+ * card is valid — `icaoCheckDigit("53032352") === "5"`.
+ *
+ * Without this, the downstream ambiguous-char recovery "fixes" the failing check
+ * by rewriting the real leading letter to a digit (A→4), corrupting the document
+ * number. This function instead recognises the legitimate Turkish reading and
+ * accepts the parse AS-IS, preserving the letter.
+ *
+ * It is deliberately narrow: it only fires for a TUR-issued TD1 whose document
+ * number starts with a letter, when the document-number check digit is failing
+ * (its signature) and the only OTHER failure permitted is the composite (the
+ * date checks must pass — an impossible date is real OCR damage, not this
+ * convention), and the leading-letter-dropped recomputation matches the printed
+ * document-number check digit.
+ *
+ * The leading serial letter MUST be preserved: the NFC eID chip derives its
+ * BAC/PACE access key from the document number exactly as stored on the chip
+ * (which includes the letter, e.g. "A53032352"). Rewriting it to a digit ("4…")
+ * — as the ambiguous-char recovery would, to satisfy strict ICAO — makes the
+ * chip read FAIL. So a real card must keep its letter even though the chip's
+ * MRZ carries a non-standard composite check digit that strict ICAO rejects.
+ *
+ * The TD1 COMPOSITE is therefore NOT required to match: on Turkish eIDs the
+ * composite is computed over the document-number region with the serial letter
+ * weighted in a way that diverges from strict ICAO (it cannot be reproduced by
+ * either including A=10 or dropping the letter), so it is not a reliable anchor
+ * here. The document-number check digit under the drop-leading-letter rule
+ * uniquely pins the numeric portion, and the letter is verbatim from OCR — the
+ * authoritative confirmation is the subsequent NFC read, which only succeeds
+ * with the correct (letter-preserving) document number.
+ */
+const acceptsTurkishLetterPrefix = (
+  result: ReturnType<typeof parse> | null
+): boolean => {
+  if (!result || result.valid || result.format !== 'TD1') return false;
+  const fields = result.fields ?? {};
+  if (fields.issuingState !== 'TUR') return false;
+  const docNumber = fields.documentNumber ?? '';
+  // Must start with a serial LETTER (the Turkish convention this handles).
+  if (!/^[A-Z]/.test(docNumber)) return false;
+
+  const failing = new Set(
+    (result.details ?? []).filter((d) => !d.valid).map((d) => d.field)
+  );
+  // Only the document-number and/or composite checks may be off — any other
+  // failing check digit (dates) means real OCR damage, not this convention.
+  const allowed = new Set(['documentNumberCheckDigit', 'compositeCheckDigit']);
+  if (failing.size === 0) return false;
+  for (const f of failing) if (!allowed.has(f)) return false;
+  // The document-number check digit MUST be among the failures — that is the
+  // signature of the letter-prefix convention. If only the composite is off, this
+  // is a different problem (handled by fixTD1Composite / indel recovery).
+  if (!failing.has('documentNumberCheckDigit')) return false;
+
+  // Rebuild the fixed-width lines from the parse ranges. We read the PRINTED
+  // check digit straight from the line (the parsed `documentNumberCheckDigit`
+  // field is null when the check fails, so it can't be relied on here).
+  const lines = linesFromParseRanges(result, 30, 3);
+  const l1 = lines[0] ?? '';
+  if (l1.length < 30) return false;
+
+  // The printed document-number check digit (TD1 line 1, position 14) must equal
+  // the check digit computed over the document number WITHOUT its leading letter.
+  // This uniquely identifies the numeric portion; the leading letter is kept
+  // verbatim (NFC requires it). The composite is deliberately NOT checked here.
+  const printedDocCheck = l1[14];
+  const digitsAfterLetter = docNumber.slice(1);
+  if (icaoCheckDigit(digitsAfterLetter) !== printedDocCheck) return false;
+
+  return true;
+};
+
 /**
  * When a TD1 MRZ fails ONLY on its composite check digit (every per-field check
  * digit is valid), the composite is deterministically derivable from the other
@@ -609,6 +781,17 @@ const fixTD1Composite = (lines: string[]): ReturnType<typeof parse> | null => {
   if (lines.length < 3 || lines[0].length !== 30 || lines[1].length !== 30) {
     return null;
   }
+  // Guard against a MISPLACED composite: when OCR drops filler(s) from the line-2
+  // optional run, a layout-naive right-pad lands the composite digit mid-line and
+  // pads the tail with "<". The result is length-30 but structurally wrong, and
+  // recomputing over it writes a bogus digit (a plausible-but-malformed MRZ). If
+  // the composite slot [29] is "<" yet a digit sits in the optional window
+  // [18..29), the line is misaligned — refuse the recompute and let the indel
+  // (filler-insertion) recovery realign it first.
+  const l2line = lines[1];
+  if (l2line[29] === '<' && /[0-9]/.test(l2line.slice(18, 29))) {
+    return null;
+  }
   const r = parse(lines);
   const bad = (r.details ?? []).filter((d) => !d.valid);
   if (bad.length !== 1 || bad[0].field !== 'compositeCheckDigit') return null;
@@ -633,7 +816,10 @@ const fixTD1Composite = (lines: string[]): ReturnType<typeof parse> | null => {
  *  - line 2 (date record): delete each char in the birth..expiry-check window
  *    [0..15) (then right-pad to 30) — undoes a spurious inserted digit;
  *  - line 1 (doc record): delete each char in the doc-number..check window
- *    [5..15) — undoes an inserted char in the serial.
+ *    [5..15) — undoes an inserted char in the serial;
+ *  - line 2 (date record): when OCR DROPPED filler(s) from the optional run, the
+ *    line arrives short — insert a "<" across the optional window [18..29) to
+ *    restore width 30 with the composite at position 29.
  * Each candidate is re-padded to 30, the composite is recomputed, and only a
  * fully check-digit-valid parse is accepted, so a wrong edit can never pass.
  */
@@ -641,13 +827,16 @@ const recoverTD1ByIndel = (
   lines: string[]
 ): ReturnType<typeof parse> | null => {
   if (lines.length < 3) return null;
-  const pad30 = (s: string) =>
-    s.length >= 30 ? s.slice(0, 30) : s.padEnd(30, '<');
+  // Layout-aware: line 2 (index 1) is the date record whose trailing char is the
+  // composite check digit, so a short line must have its dropped fillers restored
+  // BEFORE that digit, not appended after it (padEnd would strand the composite).
+  const pad30 = (s: string, li?: number) =>
+    s.length >= 30 ? s.slice(0, 30) : padTD1Line(s, li === 1);
 
   // Which line/window to try edits in, based on which check digit is failing.
   let base: ReturnType<typeof parse>;
   try {
-    base = parse(lines.map(pad30));
+    base = parse(lines.map((l, li) => pad30(l, li)));
   } catch {
     return null;
   }
@@ -677,15 +866,26 @@ const recoverTD1ByIndel = (
   // Build all single-deletion candidates up front.
   const candidates: string[][] = [];
   for (const [li, from, to] of regions) {
-    const original = pad30(lines[li] ?? '');
+    const original = pad30(lines[li] ?? '', li);
     for (let i = from; i < to && i < original.length; i++) {
-      const edited = pad30(original.slice(0, i) + original.slice(i + 1));
-      const candidate = lines.map(pad30);
+      const edited = pad30(original.slice(0, i) + original.slice(i + 1), li);
+      const candidate = lines.map((l, idx) => pad30(l, idx));
       candidate[li] = edited;
       candidates.push(candidate);
     }
   }
 
+  // Dropped-filler insertion: when OCR under-counts the line-2 optional filler
+  // run, the date record arrives SHORT. The layout-aware pad30 already restores
+  // it (fillers before the trailing composite digit), so include the raw padded
+  // date record as an explicit candidate — this repairs the common Turkish-ID
+  // case (`…TUR<<<<<<<<<6` read with 9 fillers instead of 11) by INSERTION, not a
+  // bogus composite recompute over a misaligned line.
+  if ((lines[1]?.length ?? 30) < 30) {
+    const padded = lines.map((l, idx) => pad30(l, idx));
+    candidates.push(padded);
+  }
+
   // Cheap pass first: a plain parse or a composite recompute resolves the common
   // case (a dropped/duplicated digit) in microseconds — try ALL deletions this
   // way before paying for any substitution search.
@@ -882,26 +1082,22 @@ const correctedMrzFromParse = (
   const width = widths[result.format ?? ''];
   if (!width) return undefined;
   const lineCount = result.format === 'TD1' ? 3 : 2;
-  const buffers: string[][] = Array.from({ length: lineCount }, () =>
-    new Array(width).fill('<')
-  );
-  for (const detail of result.details ?? []) {
-    for (const range of detail.ranges ?? []) {
-      // `raw` (the actual characters at this span) exists at runtime but isn't in
-      // the `mrz` Range type.
-      const {
-        line,
-        start,
-        raw = '',
-      } = range as typeof range & { raw?: string };
-      const buf = buffers[line];
-      if (!buf) continue;
-      for (let i = 0; i < raw.length && start + i < width; i++) {
-        buf[start + i] = raw[i];
-      }
-    }
-  }
-  return buffers.map((b) => b.join('')).join('\n');
+  return linesFromParseRanges(result, width, lineCount).join('\n');
+};
+
+/**
+ * Heuristic: does a parsed result's name look like it still carries OCR noise
+ * (a digit where a name letter belongs, or a run of filler-confusable letters
+ * that should have been "<")? Names are letters only, so any digit is noise; a
+ * 3+ run of K/C/E/G is very likely misread fillers leaking into the given names.
+ */
+const nameLooksNoisy = (r: ReturnType<typeof parse>): boolean => {
+  const name = `${r.fields?.lastName ?? ''} ${r.fields?.firstName ?? ''}`;
+  // A DIGIT in a name is unambiguous OCR noise (MRZ names are letters only).
+  // A 5+ run of filler-confusable letters is almost certainly misread padding —
+  // real given names like "ECE"/"GECE" are short, so keep the threshold high to
+  // avoid false positives on legitimate names.
+  return /[0-9]/.test(name) || /[KCEG]{5,}/.test(name);
 };
 
 /**
@@ -923,12 +1119,47 @@ const validateMRZ = (
     // line + fragments). That must NOT short-circuit the recovery/reconstruction
     // path below — treat a throw here as "no valid parse yet" and keep going.
     let result: ReturnType<typeof parse> | null = null;
+    // Set when a TUR card is accepted under the Turkish serial-letter convention
+    // (strict ICAO marks it invalid, but the leading-letter-dropped check passes).
+    // Treated as valid downstream so the real letter is preserved, not corrected.
+    let turkishLetterPrefixAccepted = false;
     try {
       result = parse(fixedText, { autocorrect });
     } catch {
       result = null;
     }
 
+    // The direct parse can validate (the name field has no check digit) while the
+    // name line still carries OCR noise — a leading "O" read as "0", or trailing
+    // "<" fillers read as K/C/E/G that leak into the given names. The
+    // reconstruction path normalises the name line; when the direct result's name
+    // looks noisy, prefer a reconstructed candidate that validates with a cleaner
+    // name. This only ever swaps in another fully check-digit-valid reading.
+    if (result?.valid && nameLooksNoisy(result)) {
+      for (const reLines of reconstructMRZCandidates(mrzText)) {
+        let cand: ReturnType<typeof parse>;
+        try {
+          cand = parse(reLines);
+        } catch {
+          continue;
+        }
+        if (cand.valid && !nameLooksNoisy(cand)) {
+          result = cand;
+          break;
+        }
+      }
+    }
+
+    // Turkish e-ID serial-letter convention: a genuine TUR card whose document
+    // number starts with a serial LETTER (e.g. "A53032352") fails the strict
+    // ICAO check (Türkiye omits the leading letter from the check-digit math). If
+    // the card validates under that convention, accept it AS-IS — the leading
+    // letter is REAL and must be preserved, NOT rewritten to a digit by the
+    // ambiguous-char recovery below. See acceptsTurkishLetterPrefix.
+    if (result && !result.valid && acceptsTurkishLetterPrefix(result)) {
+      turkishLetterPrefixAccepted = true;
+    }
+
     // Primary recovery: exhaustive, CHECK-DIGIT-DRIVEN correction scoped to the
     // fields whose check digit actually fails. It tries every OCR-ambiguous
     // permutation within those fields — ordered by how likely the OCR error is
@@ -937,7 +1168,7 @@ const validateMRZ = (
     // digits all pass). This both (a) fixes a misread document number before the
     // caller advances to the NFC/next screen, and (b) prefers the genuinely
     // correct correction over an arbitrary check-digit-satisfying one.
-    if (!result || !result.valid) {
+    if (!turkishLetterPrefixAccepted && (!result || !result.valid)) {
       const fixedLines = fixedText.split('\n').filter((l) => l.trim());
       if (fixedLines.length >= 2) {
         const recovered = recoverByFailingFields(fixedLines);
@@ -950,7 +1181,7 @@ const validateMRZ = (
     // Last-resort fallback: the older whole-string ambiguous sweep, only for
     // inputs the field-scoped recovery can't address (e.g. an unrecognised
     // format with no check-digit span map). Still requires a fully-valid parse.
-    if (!result || !result.valid) {
+    if (!turkishLetterPrefixAccepted && (!result || !result.valid)) {
       const variants = generateAmbiguousVariants(fixedText);
       for (const variant of variants) {
         if (recoveryExpired()) break; // bail before blocking the JS thread
@@ -972,7 +1203,7 @@ const validateMRZ = (
     // or broke a field with spaces). Reconstruct fixed-width line-sets for every
     // supported format (TD1/TD2/TD3) and validate each WITH CHECK DIGITS, keeping
     // only one that passes — a wrong reconstruction can never leak through.
-    if (!result || !result.valid) {
+    if (!turkishLetterPrefixAccepted && (!result || !result.valid)) {
       for (const reLines of reconstructMRZCandidates(mrzText)) {
         // A reconstructed candidate for the wrong format (e.g. a 2-line TD2 guess
         // built from a TD1 frame) makes the `mrz` parser THROW on line count —
@@ -994,7 +1225,7 @@ const validateMRZ = (
       }
     }
 
-    if (!result || !result.valid) {
+    if (!result || (!result.valid && !turkishLetterPrefixAccepted)) {
       return {
         valid: false,
         format: 'UNKNOWN',

package/src/Shared/Libs/mrzFrameAggregator.ts

@@ -67,6 +67,12 @@ export interface MRZFrameAggregatorOptions {
   stabilityTarget?: number;
   /** Drop the running tallies after this many frames to bound memory. Default 60. */
   maxFrames?: number;
+  /**
+   * Minimum winning vote margin a contested cell needs before the consensus can
+   * be considered stable. Higher = more frames required to resolve a look-alike
+   * ambiguity (A↔4, S↔5) before accepting. Default 2.
+   */
+  minMargin?: number;
 }
 
 interface CellVotes {
@@ -157,6 +163,10 @@ const linesForFrame = (text: string): string[] | null => {
 export class MRZFrameAggregator {
   private readonly stabilityTarget: number;
   private readonly maxFrames: number;
+  // Minimum winning vote margin a CONTESTED cell needs before the consensus is
+  // considered confident (and thus eligible to be "stable"). Guards against an
+  // early look-alike misread (A↔4, S↔5, B↔8) locking in on a 1-vote lead.
+  private readonly minMargin: number;
   // format -> per-line, per-column vote tallies
   private tallies: Record<string, CellVotes[][]> = {};
   private frameCount = 0;
@@ -168,6 +178,7 @@ export class MRZFrameAggregator {
   constructor(options: MRZFrameAggregatorOptions = {}) {
     this.stabilityTarget = Math.max(1, options.stabilityTarget ?? 2);
     this.maxFrames = Math.max(1, options.maxFrames ?? 60);
+    this.minMargin = Math.max(0, options.minMargin ?? 2);
   }
 
   reset(): void {
@@ -285,6 +296,35 @@ export class MRZFrameAggregator {
     this.frameCount = Math.ceil(this.frameCount / 2);
   }
 
+  /**
+   * Is every CONTESTED cell of this format decided by a clear margin?
+   *
+   * A cell is contested when more than one distinct character has received votes
+   * (e.g. position 5 of a Turkish doc number gets both "A" and the look-alike
+   * "4"). Per-character voting alone reports the consensus "stable" the instant an
+   * early misread takes a 1-vote lead and stays unchanged — so a transient
+   * "A"→"4" confusion locks in before the correct glyph accumulates enough votes.
+   *
+   * Requiring the winner to lead the runner-up by `minMargin` weight on every
+   * contested cell defers stability until the vote has genuinely settled: a 2-vs-1
+   * early lead is NOT confident; a 4-vs-1 (or clean uncontested) reading is. This
+   * is what turns "looks valid this frame" into "the camera agrees across frames".
+   */
+  private consensusIsConfident(format: string): boolean {
+    const geom = FORMAT_GEOMETRY[format];
+    const tally = this.tallies[format];
+    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;
+      }
+    }
+    return true;
+  }
+
   /** Read out the winning character per cell for a format. */
   private consensusLines(format: string): string[] {
     const geom = FORMAT_GEOMETRY[format];
@@ -331,6 +371,7 @@ export class MRZFrameAggregator {
     let bestMrz: string | null = null;
     let bestValidation: MRZValidationResult | null = null;
     let bestValid = false;
+    let bestFormat: string | null = null;
 
     for (const format of formats) {
       const lines = this.consensusLines(format);
@@ -342,9 +383,11 @@ export class MRZFrameAggregator {
         bestValid = true;
         bestMrz = validation.correctedMrz ?? mrz;
         bestValidation = validation;
+        bestFormat = format;
       } else if (!bestValid && bestMrz === null) {
         bestMrz = mrz;
         bestValidation = validation;
+        bestFormat = format;
       }
     }
 
@@ -358,11 +401,20 @@ export class MRZFrameAggregator {
     }
     this.lastConsensusMrz = stableKey;
 
+    // "Stable" requires BOTH an unchanged streak AND a confident vote: every
+    // contested cell must have resolved by a clear margin. The streak alone lets
+    // an early look-alike misread (A↔4) lock in the instant it takes a 1-vote
+    // lead and stops changing — the confidence gate defers acceptance until the
+    // correct glyph has genuinely won, not merely arrived first.
+    const confident =
+      bestValid && bestFormat != null && this.consensusIsConfident(bestFormat);
+
     return {
       mrz: bestMrz,
       validation: bestValidation,
       frames: this.frameCount,
-      stable: bestValid && this.stableStreak >= this.stabilityTarget,
+      stable:
+        bestValid && confident && this.stableStreak >= this.stabilityTarget,
     };
   }
 }

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

@@ -1,3 +1,4 @@
+import { debugLog } from './debug.utils';
 const runWithRetry = async <T>(
   fn: () => Promise<T>,
   maxRetries: number = 3,
@@ -9,26 +10,31 @@ const runWithRetry = async <T>(
   while (retries < maxRetries) {
     try {
       if (retries > 0) {
-        console.log(`[Retry] Attempt ${retries + 1}/${maxRetries}...`);
+        debugLog('Retry', `[Retry] Attempt ${retries + 1}/${maxRetries}...`);
       }
       result = await fn();
       if (retries > 0) {
-        console.log(`[Retry] ✓ Success on attempt ${retries + 1}`);
+        debugLog('Retry', `[Retry] ✓ Success on attempt ${retries + 1}`);
       }
       return result;
     } catch (error) {
       lastError = error;
       retries++;
-      console.error(`[Retry] ✗ Attempt ${retries}/${maxRetries} failed:`, error instanceof Error ? error.message : error);
+      console.error(
+        `[Retry] ✗ Attempt ${retries}/${maxRetries} failed:`,
+        error instanceof Error ? error.message : error
+      );
       if (retries < maxRetries) {
         const waitTime = delay * retries;
-        console.log(`[Retry] Waiting ${waitTime}ms before retry...`);
+        debugLog('Retry', `[Retry] Waiting ${waitTime}ms before retry...`);
         await new Promise((resolve) => setTimeout(resolve, waitTime));
       }
     }
   }
   console.error('[Retry] ✗ All retries exhausted. Last error:', lastError);
-  throw new Error(`Max retries (${maxRetries}) exceeded. Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+  throw new Error(
+    `Max retries (${maxRetries}) exceeded. Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+  );
 };
 
 export { runWithRetry };

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

@@ -0,0 +1,15 @@
+import 'react-native-get-random-values';
+
+// Unbiased Fisher–Yates shuffle backed by a CSPRNG. Used for the liveness
+// instruction order, which acts as an anti-replay challenge and must not be
+// predictable.
+export const secureShuffle = <T>(items: T[]): T[] => {
+  const result = [...items];
+  const random = new Uint32Array(1);
+  for (let i = result.length - 1; i > 0; i--) {
+    crypto.getRandomValues(random);
+    const j = random[0] % (i + 1);
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+};

package/src/Shared/Services/AnalyticsService.ts

@@ -318,7 +318,13 @@ class AnalyticsService implements IAnalyticsService {
           throw new Error('Rate limit exceeded');
         }
 
-        // For other 4xx errors (Bad Request, Unauthorized, etc.), do NOT retry.
+        // Auth failures are transient from the SDK's perspective (e.g. a token
+        // rollout); throw so the batch is retried instead of silently dropped.
+        if (response.status === 401 || response.status === 403) {
+          throw new Error(`Authentication error: ${response.status}`);
+        }
+
+        // For other 4xx errors (Bad Request, etc.), do NOT retry.
         // We return successfully so the bad events are removed from the queue.
         if (response.status >= 400 && response.status < 500) {
           if (__DEV__)
@@ -450,6 +456,16 @@ class AnalyticsService implements IAnalyticsService {
       'password',
       'apikey',
       'accesstoken',
+      'documentnumber',
+      'personalnumber',
+      'nationalid',
+      'tckimlik',
+      'mrz',
+      'mrztext',
+      'birthdate',
+      'dateofbirth',
+      'sessionkey',
+      'sessiontoken',
     ];
 
     for (const [key, value] of Object.entries(metadata)) {