@trustchex/react-native-sdk 1.475.1 → 1.481.1

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/http-client.js

@@ -1,6 +1,7 @@
 "use strict";
 
 import { trackApiCall, trackError } from "./analytics.utils.js";
+import { debugLog } from "./debug.utils.js";
 export class HttpClientError extends Error {
   constructor(message) {
     super(message);
@@ -36,6 +37,15 @@ export class InternalServerError extends HttpClientError {
     super(message ?? 'Internal server error');
   }
 }
+
+// Short-lived per-verification token issued by the backend during the session
+// key exchange; sent on every subsequent call. Older backends don't issue one,
+// in which case requests go out without the header (backwards compatible).
+let sessionToken = null;
+export const setSessionToken = token => {
+  sessionToken = token;
+};
+export const getSessionToken = () => sessionToken;
 const request = async (httpMethod, url, body, simulatedResponse) => {
   if (simulatedResponse) {
     return new Promise(resolve => {
@@ -47,30 +57,33 @@ const request = async (httpMethod, url, body, simulatedResponse) => {
   const startTime = Date.now();
   let statusCode = 0;
   let success = false;
-  console.log(`[HTTP] ${httpMethod} ${url}`);
+  debugLog('HTTP', `${httpMethod} ${url}`);
   if (body) {
-    console.log('[HTTP] Request body:', JSON.stringify(body).substring(0, 200) + '...');
+    debugLog('HTTP', 'Request body:', JSON.stringify(body).substring(0, 200) + '...');
   }
   try {
     const response = await fetch(url, {
       method: httpMethod,
       headers: {
-        'Content-Type': 'application/json'
+        'Content-Type': 'application/json',
+        ...(sessionToken ? {
+          'X-Session-Token': sessionToken
+        } : {})
       },
       body: body ? JSON.stringify(body) : undefined
     });
     statusCode = response.status;
     success = response.ok;
-    console.log(`[HTTP] Response status: ${statusCode} ${response.ok ? '✓' : '✗'}`);
+    debugLog('HTTP', `Response status: ${statusCode} ${response.ok ? '✓' : '✗'}`);
     let responseJson = null;
     try {
       responseJson = await response.json();
       if (responseJson) {
-        console.log('[HTTP] Response body:', JSON.stringify(responseJson).substring(0, 200) + '...');
+        debugLog('HTTP', 'Response body:', JSON.stringify(responseJson).substring(0, 200) + '...');
       }
     } catch (error) {
       // Invalid JSON response
-      console.log('[HTTP] Response body: (non-JSON)');
+      debugLog('HTTP', 'Response body: (non-JSON)');
     }
 
     // Track API call performance (non-blocking)

package/lib/module/Shared/Libs/mrz.utils.js

@@ -14,6 +14,34 @@ const RECOVERY_BUDGET_MS = 80;
 let recoveryDeadline = 0;
 const recoveryExpired = () => 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, isDateRecord = false) => {
+  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
  */
@@ -291,11 +319,14 @@ const reconstructMRZCandidates = rawText => {
       l1 = l1.slice(0, 2) + l1.slice(2, 5).replace(/K(?=<)|(?<=<)K|(?<=[A-Z])K$/g, '<') + l1.slice(5);
       let l2;
       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 mostly-letters+filler OCR line that is NOT the
       // doc or date line. OCR mangles the name line too — a leading "O" reads as
@@ -547,6 +578,112 @@ const icaoCheckDigit = str => {
   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, width, lineCount) => {
+  const buffers = 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;
+      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 => {
+  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
@@ -557,6 +694,17 @@ const fixTD1Composite = lines => {
   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;
@@ -580,18 +728,24 @@ const fixTD1Composite = lines => {
  *  - 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.
  */
 const recoverTD1ByIndel = lines => {
   if (lines.length < 3) return null;
-  const pad30 = s => 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, li) => 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;
   try {
-    base = parse(lines.map(pad30));
+    base = parse(lines.map((l, li) => pad30(l, li)));
   } catch {
     return null;
   }
@@ -612,15 +766,26 @@ const recoverTD1ByIndel = lines => {
   // Build all single-deletion candidates up front.
   const candidates = [];
   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.
@@ -809,26 +974,7 @@ const correctedMrzFromParse = result => {
   const width = widths[result.format ?? ''];
   if (!width) return undefined;
   const lineCount = result.format === 'TD1' ? 3 : 2;
-  const buffers = 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;
-      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');
 };
 
 /**
@@ -862,6 +1008,10 @@ const validateMRZ = (mrzText, autocorrect = true) => {
     // 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 = 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
@@ -891,6 +1041,16 @@ const validateMRZ = (mrzText, autocorrect = true) => {
       }
     }
 
+    // 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
@@ -899,7 +1059,7 @@ const validateMRZ = (mrzText, autocorrect = true) => {
     // 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);
@@ -912,7 +1072,7 @@ const validateMRZ = (mrzText, autocorrect = true) => {
     // 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
@@ -936,7 +1096,7 @@ const validateMRZ = (mrzText, autocorrect = true) => {
     // 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 —
@@ -957,7 +1117,7 @@ const validateMRZ = (mrzText, autocorrect = true) => {
         }
       }
     }
-    if (!result || !result.valid) {
+    if (!result || !result.valid && !turkishLetterPrefixAccepted) {
       return {
         valid: false,
         format: 'UNKNOWN',