@trustchex/react-native-sdk 1.486.0 → 1.488.0

package/src/Shared/EIDReader/protocol/paceProtocol.ts

@@ -4,6 +4,7 @@ import type { SecureMessagingWrapper } from '../secureMessagingWrapper';
 import { AESSecureMessagingWrapper } from '../aesSecureMessagingWrapper';
 import { TripleDesSecureMessagingWrapper } from '../tripleDesSecureMessagingWrapper';
 import { PACEInfo } from '../paceInfo';
+import { PACEUnsupportedError } from './paceErrors';
 import { PACEResult } from './paceResult';
 import { PACEKeySpec } from '../paceKeySpec';
 import { EID_CONSTANTS } from '../constants/eidConstants';
@@ -26,6 +27,60 @@ import { ec as EC } from 'elliptic';
   const _hash = require('hash.js') as any;
   const PresetCurve = _elliptic.curves.PresetCurve;
 
+  // brainpoolP192r1 (RFC 5639 §3.1) — PACE standardized domain parameter ID 9.
+  if (!_elliptic.curves.brainpoolP192r1) {
+    _elliptic.curves.brainpoolP192r1 = new PresetCurve({
+      type: 'short',
+      prime: null,
+      p: 'c302f41d932a36cda7a3463093d18db78fce476de1a86297',
+      a: '6a91174076b1e0e19c39c031fe8685c1cae040e5c69a28ef',
+      b: '469a28ef7c28cca3dc721d044f4496bcca7ef4146fbf25c9',
+      n: 'c302f41d932a36cda7a3462f9e9e916b5be8f1029ac4acc1',
+      hash: _hash.sha256,
+      gRed: false,
+      g: [
+        'c0a0647eaab6a48753b033c56cb0f0900a2f5c4853375fd6',
+        '14b690866abd5bb88b5f4828c1490002e6773fa2fa299b8f',
+      ],
+    });
+  }
+
+  // brainpoolP224r1 (RFC 5639 §3.2) — PACE standardized domain parameter ID 11.
+  if (!_elliptic.curves.brainpoolP224r1) {
+    _elliptic.curves.brainpoolP224r1 = new PresetCurve({
+      type: 'short',
+      prime: null,
+      p: 'd7c134aa264366862a18302575d1d787b09f075797da89f57ec8c0ff',
+      a: '68a5e62ca9ce6c1c299803a6c1530b514e182ad8b0042a59cad29f43',
+      b: '2580f63ccfe44138870713b1a92369e33e2135d266dbb372386c400b',
+      n: 'd7c134aa264366862a18302575d0fb98d116bc4b6ddebca3a5a7939f',
+      hash: _hash.sha256,
+      gRed: false,
+      g: [
+        '0d9029ad2c7e5cf4340823b2a87dc68c9e4ce3174c1e6efdee12c07d',
+        '58aa56f772c0726f24c6b89e4ecdac24354b9e99caa3f6d3761402cd',
+      ],
+    });
+  }
+
+  // brainpoolP320r1 (RFC 5639 §3.4) — PACE standardized domain parameter ID 14.
+  if (!_elliptic.curves.brainpoolP320r1) {
+    _elliptic.curves.brainpoolP320r1 = new PresetCurve({
+      type: 'short',
+      prime: null,
+      p: 'd35e472036bc4fb7e13c785ed201e065f98fcfa6f6f40def4f92b9ec7893ec28fcd412b1f1b32e27',
+      a: '3ee30b568fbab0f883ccebd46d3f3bb8a2a73513f5eb79da66190eb085ffa9f492f375a97d860eb4',
+      b: '520883949dfdbc42d3ad198640688a6fe13f41349554b49acc31dccd884539816f5eb4ac8fb1f1a6',
+      n: 'd35e472036bc4fb7e13c785ed201e065f98fcfa5b68f12a32d482ec7ee8658e98691555b44c59311',
+      hash: _hash.sha384,
+      gRed: false,
+      g: [
+        '43bd7e9afb53d8b85289bcc48ee5bfe6f20137d10a087eb6e7871e2a10a599c710af8d0d39e20611',
+        '14fdd05545ec1cc8ab4093247f77275e0743ffed117182eaa9c77877aaac6ac7d35245d1692e8ee1',
+      ],
+    });
+  }
+
   if (!_elliptic.curves.brainpoolP256r1) {
     _elliptic.curves.brainpoolP256r1 = new PresetCurve({
       type: 'short',
@@ -130,12 +185,19 @@ export class PACEProtocol {
     const keyLength = PACEInfo.toKeyLength(oid);
 
     if (agreementAlg !== 'ECDH') {
-      throw new Error(
-        `Only ECDH key agreement is supported, found: ${agreementAlg}`
+      // DH-based PACE is rare in modern documents; surface it as a typed
+      // capability gap so the caller falls back to BAC with a precise reason.
+      throw new PACEUnsupportedError(
+        'agreement',
+        `key agreement ${agreementAlg} (only ECDH implemented)`
       );
     }
     if (mappingType !== 'GM' && mappingType !== 'IM') {
-      throw new Error(`Unsupported PACE mapping type: ${mappingType}`);
+      // CAM (Chip Authentication Mapping) is not implemented.
+      throw new PACEUnsupportedError(
+        'mapping',
+        `mapping type ${mappingType} (only GM/IM implemented)`
+      );
     }
 
     // Derive static PACE key K_pi from the access key
@@ -408,8 +470,9 @@ export class PACEProtocol {
     ephemeralParams: { generatorX: string; generatorY: string; curve: string };
   }> {
     if (cipherAlg !== 'AES') {
-      throw new Error(
-        `PACE IM: Only AES cipher is supported in this implementation, found: ${cipherAlg}`
+      throw new PACEUnsupportedError(
+        'cipher',
+        `IM mapping requires AES, found ${cipherAlg}`
       );
     }
 
@@ -940,7 +1003,10 @@ export class PACEProtocol {
       case 18:
         return 'p521'; // NIST P-521
       default:
-        throw new Error(`Unsupported domain parameter ID: ${parameterId}`);
+        throw new PACEUnsupportedError(
+          'curve',
+          `domain parameter ID ${parameterId}`
+        );
     }
   }
 }

package/src/Shared/EIDReader/protocol/readBinaryAPDUSender.ts

@@ -158,11 +158,14 @@ export class ReadBinaryAPDUSender implements APDULevelReadBinaryCapable {
         commandAPDU
       );
     } catch (error) {
-      if (this.service.getIsConnectionLost(error as Error)) {
-        throw error;
-      }
-
+      // A transient transceive failure (iOS RF drop during a large DG2 read)
+      // used to be swallowed here, leaving responseAPDU undefined — which then
+      // crashed downstream as a misleading "Could not read file" that the retry
+      // layer couldn't recognise. Rethrow so the block-read retry/backoff in
+      // CardFileInputStream can re-issue the SAME block (idempotent), and the
+      // file system can downgrade the read size if needed.
       console.debug('Exception during READ BINARY', error);
+      throw error;
     }
 
     const responseData = ReadBinaryAPDUSender.getResponseData(

package/src/Shared/Libs/country-display.utils.ts

@@ -5,6 +5,13 @@ const COUNTRY_NAME_OVERRIDES: Record<string, string> = {
   TUR: 'Türkiye',
 };
 
+// ICAO/MRZ issuing-state codes that are not ISO-3166 alpha-3 and must be mapped
+// before lookup. "D" is Germany's historical 1-letter MRZ code (ICAO 9303
+// Part 3 §C), surfaced filler-padded as "D<<" by the chip getters.
+const MRZ_CODE_ALIASES: Record<string, string> = {
+  D: 'DEU',
+};
+
 const findCountryByAlpha3 = (alpha3Code: string) => {
   return [...UnicodeCountry.VALUES, ...ISOCountry.VALUES].find(
     (country) => country.toAlpha3Code() === alpha3Code
@@ -17,7 +24,11 @@ export const getLocalizedCountryName = (
 ): string => {
   if (!alpha3Code) return '';
 
-  const normalizedCode = alpha3Code.trim().toUpperCase();
+  // Strip MRZ filler (the chip pads short codes, e.g. German "D" → "D<<") and
+  // map non-ISO MRZ codes to their alpha-3 before lookup.
+  const stripped = alpha3Code.replace(/</g, '').trim().toUpperCase();
+  if (!stripped) return '';
+  const normalizedCode = MRZ_CODE_ALIASES[stripped] ?? stripped;
   const overrideName = COUNTRY_NAME_OVERRIDES[normalizedCode];
 
   if (overrideName) {

package/src/Shared/Libs/diagnosticReport.ts

@@ -31,6 +31,30 @@ const icaoCheckDigit = (str: string): string => {
   return String(sum);
 };
 
+/**
+ * Reportable NFC error code, e.g. `NFC-AUTH-6982`. MUST match the code shown to
+ * the user by EIDScanner (built in eidReader.buildNfcErrorCode) so a user who
+ * quotes "NFC-AUTH-6982" can be matched verbatim against their diagnostics.json.
+ * Local copy of the category→prefix map (eidReader pulls in native NFC deps).
+ */
+const NFC_CATEGORY_CODE: Record<string, string> = {
+  user_cancelled: 'CANCEL',
+  tag_lost: 'TAGLOST',
+  timeout: 'TIMEOUT',
+  unsupported: 'UNSUPPORTED',
+  not_enabled: 'DISABLED',
+  auth_failed: 'AUTH',
+  reading_error: 'READ',
+};
+
+const nfcErrorCode = (
+  category: string | undefined,
+  statusWord: string | undefined
+): string => {
+  const part = NFC_CATEGORY_CODE[category ?? ''] ?? 'READ';
+  return statusWord ? `NFC-${part}-${statusWord}` : `NFC-${part}`;
+};
+
 export interface ScanDataForReport {
   documentType?: string;
   dataSource?: string;
@@ -166,9 +190,16 @@ export const buildDiagnosticReport = (params: {
 
   // --- compact email body (always under MAX_BODY_BYTES) ---
   const nfc = diag.nfc;
+  // Status word of the failing step (if any), used to build the reportable code.
+  const failingSw = nfc.failureStep
+    ? nfc.steps.find((s) => s.step === nfc.failureStep)?.sw
+    : undefined;
+  const nfcCode = nfcErrorCode(nfc.errorCategory, failingSw);
   const nfcLine = nfc.attempted
     ? `${nfc.authProtocol}${nfc.paceFellBackToBac ? '→BAC' : ''} · ${
-        nfc.succeeded ? 'success' : `failed at ${nfc.failureStep ?? '?'} (${nfc.errorCategory ?? 'error'})`
+        nfc.succeeded
+          ? 'success'
+          : `failed at ${nfc.failureStep ?? '?'} (${nfc.errorCategory ?? 'error'}) [${nfcCode}]`
       }`
     : 'not attempted';
   const checksLine = checkDigits

package/src/Shared/Libs/diagnostics.ts

@@ -40,7 +40,9 @@ export interface NfcDiagnostics {
   /** 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. */
+   * 'pace_failed' | 'pace_unsupported_<agreement|mapping|curve|cipher>'.
+   * The pace_unsupported_* reasons mark a CAPABILITY gap (this build can't run
+   * the variant the chip advertises) vs pace_failed (a runtime failure). */
   paceFallbackReason?: string;
   steps: NfcStep[];
   /** Name of the first failing step, if any. */
@@ -175,10 +177,8 @@ export class DiagnosticsCollector {
   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;
+      Math.max(this.mrz.maxMrzBandHeightPx ?? 0, m.maxMrzBandHeightPx ?? 0) ||
+      undefined;
     this.mrz = { ...this.mrz, ...m, reachedStable, maxMrzBandHeightPx };
   }
 
@@ -186,7 +186,16 @@ export class DiagnosticsCollector {
 
   nfcAttemptStarted(): void {
     // A fresh attempt: bump retry count if a previous attempt left steps.
-    if (this.nfc.attempted) this.nfc.retryCount += 1;
+    if (this.nfc.attempted) {
+      this.nfc.retryCount += 1;
+      // A retry supersedes the prior attempt: that attempt's failure is stale,
+      // so clear it. The failure markers then reflect only the CURRENT attempt —
+      // a within-attempt failure (e.g. PACE failing before a BAC fallback in the
+      // same read) is retained, while a failure that a later retry recovered is
+      // not reported as the outcome.
+      this.nfc.failureStep = undefined;
+      this.nfc.errorCategory = undefined;
+    }
     this.nfc.attempted = true;
   }
 
@@ -214,15 +223,28 @@ export class DiagnosticsCollector {
     }
   }
 
+  /** The first NFC step that failed in the current attempt (e.g. 'paceAuth',
+   * 'readDG2'), or undefined. Lets the caller build a step-specific error code
+   * without taking a full snapshot. */
+  getFailureStep(): string | undefined {
+    return this.nfc.failureStep;
+  }
+
+  /** APDU status word recorded for the failing step, if any (e.g. '6982'). */
+  getFailureStatusWord(): string | undefined {
+    const fs = this.nfc.failureStep;
+    if (!fs) return undefined;
+    return this.nfc.steps.find((s) => s.step === fs && !s.ok)?.sw;
+  }
+
   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) {
+    // Note: a failure recovered by a RETRY is already cleared in
+    // nfcAttemptStarted (the retry supersedes it). We deliberately do NOT clear
+    // here on success, so a within-attempt failure that a fallback recovered
+    // (e.g. PACE failing before BAC succeeds in the same read) stays visible in
+    // diagnostics — that is a meaningful signal, not the overall outcome.
+    if (!succeeded && errorCategory) {
       this.nfc.errorCategory = errorCategory;
     }
   }
@@ -238,7 +260,9 @@ export class DiagnosticsCollector {
       generatedAt: isoNow,
       documentType: this.documentType,
       dataSource: this.dataSource,
-      totalDurationMs: this.startedAtMs ? Math.max(0, nowMs - this.startedAtMs) : 0,
+      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 })) },

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

@@ -14,6 +14,39 @@ const RECOVERY_BUDGET_MS = 80;
 let recoveryDeadline = 0;
 const recoveryExpired = (): boolean => Date.now() > recoveryDeadline;
 
+/**
+ * Reduce an ICAO document code to the single canonical class char the rest of the
+ * app keys off of: `'P'` for any passport (`P`, `P<`, `PP`, `PD`, `PS`, `PO`, …)
+ * and `'I'` for any identity card (`I`, `ID`, `IR`, `AC`, `C`, …). The full
+ * subtype is informative but every downstream check is `=== 'I'` / `=== 'P'`, so
+ * carrying `PP`/`ID` here only mis-classifies the document (German passport `PP`
+ * → UNKNOWN). The chip/NFC path keeps the raw code; this normalizes the OCR path.
+ */
+const normalizeDocumentCode = (
+  code: string | null | undefined
+): string | null => {
+  if (!code) return null;
+  const c = code.toUpperCase();
+  if (c[0] === 'P') return 'P';
+  // TD1/TD2 identity documents: I, ID, IR, AC, AR, C, etc. — all reduce to 'I'.
+  return 'I';
+};
+
+/**
+ * Strip MRZ filler characters from a human-readable text field. In the MRZ a
+ * single `<` separates words and `<<` separates components; the `mrz` package
+ * usually trims trailing fillers but can leave embedded `<`/`<<` in name and
+ * optional-data fields, which then surfaced raw in the UI (e.g.
+ * "ANNA<<MARIA"). Convert any filler run to a single space and trim, so the
+ * displayed value reads "ANNA MARIA". Returns null for empty/filler-only input.
+ * Only for text fields — never call on dates, sex, codes, or check digits.
+ */
+const cleanMRZTextField = (value: string | null | undefined): string | null => {
+  if (!value) return null;
+  const cleaned = value.replace(/</g, ' ').replace(/\s+/g, ' ').trim();
+  return cleaned.length > 0 ? cleaned : null;
+};
+
 /**
  * Pads a TD1 line to the fixed 30-char width.
  *
@@ -303,12 +336,15 @@ const reconstructMRZCandidates = (rawText: string): string[][] => {
   const pad = (s: string, len: number): string =>
     s.length >= len ? s.slice(0, len) : s.padEnd(len, '<');
 
-  // Restore the filler right after the document code. In TD1/TD2/TD3 the second
-  // character of line 1 is always "<". OCR commonly reads it as "K" or drops it:
-  //   "IKD…" -> "I<D…",  "ITUR…" -> "I<TUR…",  "I<D…" unchanged.
+  // Repair the document-subtype character (line 1, position 2). For TD1/TD2 IDs
+  // this is usually "<" and OCR may read it as "K"; collapse that misread back to
+  // "<". But for PASSPORTS position 2 is a real subtype LETTER (German ordinary
+  // passports are "PP", and "PC"/"PD"/"PR"/… exist) — it must NOT be rewritten,
+  // or the whole line shifts right and validation fails. So only normalise a "K"
+  // misread (→ "<"); leave any other letter/filler exactly as read.
   const fixDocStart = (s: string): string =>
     s.replace(/^([ACIPV])([A-Z0-9<])/, (_m, code, next) =>
-      next === '<' ? code + next : code + '<' + (next === 'K' ? '' : next)
+      next === 'K' ? code + '<' : code + next
     );
 
   const candidates: string[][] = [];
@@ -317,26 +353,133 @@ const reconstructMRZCandidates = (rawText: string): string[][] => {
   // so title/front-of-card text mixed into the blob can't create a false anchor.
   const docLine = ocrLines.find((l) => /^[ACIPV][A-Z0-9<]{3,}<</.test(l));
 
+  // Passport/TD-x line-2 signature: docNumber(9) + check + nationality(3) +
+  // birth(6)+check+sex+expiry(6)+check…  Allow letters in the nationality and
+  // date spans (OCR reads 0↔O, 1↔I, etc.); the check-digit recovery downstream
+  // resolves them. A too-strict [A-Z]{3}/[0-9]{6} here was dropping the whole
+  // TD3/TD2 candidate on any noisy frame, leaving only a (wrong) 3-line TD1.
+  const td23Line2 =
+    /[A-Z0-9<]{9}[0-9<][A-Z<]{3}[A-Z0-9<]{6}[0-9<][MF<][A-Z0-9<]{6}[0-9<]/;
+
+  // LINE-AWARE line-2 finder. Real ML Kit OCR (a) prepends non-MRZ header text
+  // and (b) SPLITS a long MRZ line at its trailing filler run into two OCR lines
+  // (e.g. "…1204159<<<<<" + "<<<<<08"). The flat-blob approach loses line
+  // boundaries — a greedy line-1 match overruns into line 2, and the line-2
+  // regex can match a doc-number-shaped run inside line 1's name field. So work
+  // from `ocrLines`: find the doc-number record line, and if it's short (split),
+  // stitch following fragment lines onto it up to the format width. The check
+  // digits (incl. the trailing composite) then survive instead of being padded
+  // away. Returns null if no doc-number line exists at/after the line-1 index.
+  // Local 7-3-1 check digit (icaoCheckDigit is defined later in the module).
+  const cd731 = (str: string): string => {
+    const w = [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 + w[i % 3] * v) % 10;
+    }
+    return String(sum);
+  };
+
+  const findLine2 = (l1Index: number, width: number): string | null => {
+    for (let i = l1Index + 1; i < ocrLines.length; i++) {
+      const m = td23Line2.exec(ocrLines[i]);
+      if (!m || m.index !== 0) continue;
+      // The front 28 chars — docNumber(9)+check + nationality(3) +
+      // birth(6)+check + sex + expiry(6)+check — are positionally stable in OCR.
+      // The optional-data field and the two trailing check digits are what an
+      // OCR line-split garbles (dropped fillers shift the composite digit). For
+      // TD3 (width 44) REBUILD the line canonically: stable front + empty
+      // optional + recomputed optional-check + recomputed composite. This is
+      // robust to the split-filler ambiguity that single-frame stitching can't
+      // resolve. (Passports with a NON-empty optional/personal-number field are
+      // rarer; multi-frame voting still covers those via the stitch fallback.)
+      const front = m[0]; // exactly 28 chars by the regex
+      if (width === 44 && front.length >= 28) {
+        let head = front.slice(0, 28);
+        // Self-correct the document number against its OWN check digit before we
+        // recompute the composite — otherwise a recomputed composite would be
+        // self-consistent with an OCR look-alike error (e.g. O→0) and MASK it
+        // from the downstream ambiguous-char recovery. Try the digit/letter
+        // look-alike swaps in the 9-char doc-number field until its check digit
+        // (position 9) matches; only then rebuild the optional + composite.
+        const docNum = head.slice(0, 9);
+        const docCheck = head[9];
+        if (cd731(docNum) !== docCheck) {
+          const swaps: Record<string, string> = {
+            O: '0',
+            Q: '0',
+            D: '0',
+            I: '1',
+            L: '1',
+            S: '5',
+            B: '8',
+            Z: '2',
+            G: '6',
+          };
+          const fixed = docNum.replace(/[OQDILSBZG]/g, (c) => swaps[c] ?? c);
+          if (cd731(fixed) === docCheck) {
+            head = fixed + head.slice(9);
+          }
+        }
+        const optional = '<'.repeat(14);
+        const l2NoComposite = head + optional + cd731(optional);
+        const composite =
+          l2NoComposite.slice(0, 10) +
+          l2NoComposite.slice(13, 20) +
+          l2NoComposite.slice(21, 43);
+        return l2NoComposite + cd731(composite);
+      }
+      // Non-TD3 or unexpected: stitch fragments up to width as a fallback.
+      let joined = ocrLines[i];
+      let j = i + 1;
+      while (joined.length < width && j < ocrLines.length) {
+        joined += ocrLines[j];
+        j++;
+      }
+      return joined.length >= width ? joined.slice(0, width) : joined;
+    }
+    return null;
+  };
+
   // ---- TD3 (passport): line1 "P<XXX…", line2 starts with a 9-char doc number ----
-  // Line 2 signature: docNumber(9) + check + nationality(3) + birth(6)+check+sex+expiry(6)+check…
   {
-    const l1m = flat.match(/P[<A-Z]TUR[A-Z<]{2,}|P<[A-Z]{3}[A-Z<]+/);
-    const l2m = flat.match(
-      /[A-Z0-9<]{9}[0-9<][A-Z]{3}[0-9]{6}[0-9<][MF<][0-9]{6}[0-9<]/
+    // Position 2 of line 1 is the "<" filler, frequently misread under glare as a
+    // filler-letter (K/C/E/G) — accept those for ALL issuers, not just TUR.
+    // Line-1 structure (ICAO 9303): doc code "P" + 1-char subtype (often "<",
+    // but a LETTER for some issuers — e.g. German ordinary passports are "PP",
+    // and "PC"/"PD" exist) + issuing state (1–3 letters then "<" filler; Germany
+    // is "D" → "PPD<<"). Find line 1 among the OCR lines (NOT the flat blob, whose
+    // greedy match overruns line boundaries).
+    const l1Index = ocrLines.findIndex((l) =>
+      /^P[A-Z<][A-Z][A-Z<]{2}[A-Z<]/.test(l)
     );
-    if (l1m && l2m) {
-      candidates.push([pad(fixDocStart(l1m[0]), 44), pad(l2m[0], 44)]);
+    const l1Raw = l1Index >= 0 ? ocrLines[l1Index] : null;
+    const l2 = l1Index >= 0 ? findLine2(l1Index, 44) : null;
+    if (l1Raw && l2) {
+      candidates.push([pad(fixDocStart(l1Raw), 44), pad(l2, 44)]);
     }
   }
 
   // ---- TD2: line1 "X<XXX…", line2 starts with docNumber ----
   {
-    const l1m = flat.match(/[ACIPV]<[A-Z]{3}[A-Z<]+/);
-    const l2m = flat.match(
-      /[A-Z0-9<]{9}[0-9<][A-Z]{3}[0-9]{6}[0-9<][MF<][0-9]{6}[0-9<]/
+    // TD2/ID doc codes are A/C/I (NOT P — that's a passport/TD3; including it
+    // here made passports get built as a 36-char TD2 and win selection). Position
+    // 2 is the SUBTYPE — any A–Z or "<" ("IR","IP","AR","AC"…). Line-aware (see
+    // TD3): find line 1 in ocrLines, stitch a split line 2.
+    const l1Index = ocrLines.findIndex((l) =>
+      /^[ACI][A-Z<][A-Z][A-Z<]{2}[A-Z<]/.test(l)
     );
-    if (l1m && l2m) {
-      candidates.push([pad(fixDocStart(l1m[0]), 36), pad(l2m[0], 36)]);
+    const l1Raw = l1Index >= 0 ? ocrLines[l1Index] : null;
+    const l2 = l1Index >= 0 ? findLine2(l1Index, 36) : null;
+    if (l1Raw && l2) {
+      candidates.push([pad(fixDocStart(l1Raw), 36), pad(l2, 36)]);
     }
   }
 
@@ -355,9 +498,22 @@ const reconstructMRZCandidates = (rawText: string): string[][] => {
     );
     const l2m =
       l2Line ??
-      flat.match(/[0-9A-Z]{6}[0-9<][MF<][0-9A-Z]{6}[0-9<][A-Z]{2,3}/)?.[0];
-
-    if (l1Source) {
+      flat.match(/[0-9A-Z]{6}[0-9<][MF<][0-9A-Z]{6}[0-9<][A-Z<]{2,3}/)?.[0];
+
+    // Don't emit a 3-line TD1 candidate for passport-shaped input. A passport
+    // (TD3) line 1 starts with "P" + a subtype char (a filler "<" OR a real
+    // letter — German ordinary passports are "PP", and "PC"/"PD"/… exist), or
+    // the band is two long ~44-char lines. Matching ANY "P"-prefixed L1 is safe:
+    // no valid TD1 (doc codes A/C/I only) ever starts with "P". Without this
+    // guard a noisy passport whose TD3 line-2 regex just missed would fall
+    // through to here and be forced into a 3×30 TD1 layout — the "always 3
+    // lines, invalid" bug.
+    const looksLikePassport =
+      (!!l1Source && /^P[A-Z<]/.test(l1Source)) ||
+      (ocrLines.length === 2 &&
+        ocrLines.every((l) => Math.abs(l.length - 44) <= 4));
+
+    if (l1Source && !looksLikePassport) {
       let l1 = pad(fixDocStart(l1Source), 30);
       // The issuing-state field (TD1 line 1, positions 2–5) is structurally
       // fillers/letters only — never a personal name — so a "K" there flanked by
@@ -409,9 +565,11 @@ const reconstructMRZCandidates = (rawText: string): string[][] => {
           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))
+            // ONLY collapse the TRAILING run of filler-letters (K/C/E/G) — that
+            // region is unambiguous "<" padding. Do NOT collapse internal runs
+            // flanked by fillers: a short given/sur-name made only of K/C/E/G
+            // (e.g. Turkish "ECE"/"EGE", "GEC") sits between "<<" separators and
+            // would be wrongly erased.
             .replace(/[KCEG]+$/g, (m) => '<'.repeat(m.length))
         );
       };
@@ -678,7 +836,11 @@ const linesFromParseRanges = (
     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 {
+        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++) {
@@ -1241,18 +1403,20 @@ const validateMRZ = (
 
     // Map mrz package fields to our MRZFields type
     const fields: MRZFields = {
-      documentCode: result.fields.documentCode || null,
+      documentCode: normalizeDocumentCode(result.fields.documentCode),
       issuingState: result.fields.issuingState || null,
       documentNumber: result.fields.documentNumber || null,
       nationality: result.fields.nationality || null,
-      lastName: result.fields.lastName || null,
-      firstName: result.fields.firstName || null,
+      // Text fields can carry embedded MRZ filler (`<`/`<<`) — strip it so the
+      // UI shows "ANNA MARIA", not "ANNA<<MARIA".
+      lastName: cleanMRZTextField(result.fields.lastName),
+      firstName: cleanMRZTextField(result.fields.firstName),
       sex: result.fields.sex || null,
       birthDate: result.fields.birthDate || null,
       expirationDate: result.fields.expirationDate || null,
-      personalNumber: result.fields.personalNumber || null,
-      optional1: result.fields.optional1 || null,
-      optional2: result.fields.optional2 || null,
+      personalNumber: cleanMRZTextField(result.fields.personalNumber),
+      optional1: cleanMRZTextField(result.fields.optional1),
+      optional2: cleanMRZTextField(result.fields.optional2),
     };
 
     return {
@@ -1376,4 +1540,5 @@ export default {
   isValidOCRBPattern,
   applyOCRBCorrections,
   convertMRZDateToISODate,
+  normalizeDocumentCode,
 };

package/src/Shared/Libs/mrzFrameAggregator.ts

@@ -146,6 +146,33 @@ const linesForFrame = (text: string): string[] | null => {
   const exact = exactFormatLines(rawLines);
   if (exact) return exact;
 
+  // Near-format catch for 2-line bands (TD3 passport 2×44, TD2 2×36). A passport
+  // OCR'd a few chars off (2×43, 2×45) would otherwise fall into the TD1-biased
+  // reconstruction and be forced into a wrong 3×30 layout. When we have exactly
+  // two lines both close to a 2-line format's width, coerce them to that width
+  // and keep them as-is (2 lines) rather than reconstructing. Tie-break to the
+  // closest width. Never matches a 3-line TD1 (line count differs).
+  if (rawLines.length === 2) {
+    const twoLineFormats = Object.values(FORMAT_GEOMETRY).filter(
+      (g) => g.lines === 2
+    );
+    let bestGeom: { lines: number; width: number } | null = null;
+    let bestDelta = Infinity;
+    for (const g of twoLineFormats) {
+      const delta = Math.max(
+        ...rawLines.map((l) => Math.abs(l.length - g.width))
+      );
+      if (delta <= 4 && delta < bestDelta) {
+        bestDelta = delta;
+        bestGeom = g;
+      }
+    }
+    if (bestGeom) {
+      const w = bestGeom.width;
+      return rawLines.map((l) => (l.length >= w ? l.slice(0, w) : l.padEnd(w, '<')));
+    }
+  }
+
   const candidates = mrzUtils.reconstructMRZCandidates(text);
   if (!candidates.length) {
     // Fall back to the lightweight fixMRZ split for already-clean text.
@@ -165,9 +192,17 @@ const linesForFrame = (text: string): string[] | null => {
   let best: string[] | null = null;
   let bestScore = -1;
   for (const cand of candidates) {
-    const geom = Object.values(FORMAT_GEOMETRY).find(
-      (g) => g.lines === cand.length
-    );
+    // Among formats with this line count, pick the one whose width best matches
+    // the candidate's lines. TD2 and TD3 are BOTH 2 lines (36 vs 44) — matching
+    // by line count alone wrongly picked TD2 for a 44-wide passport, then the
+    // ">6 off width" guard discarded it. Average line length disambiguates.
+    const avgLen =
+      cand.reduce((s, l) => s + l.length, 0) / Math.max(1, cand.length);
+    const geom = Object.values(FORMAT_GEOMETRY)
+      .filter((g) => g.lines === cand.length)
+      .sort(
+        (a, b) => Math.abs(a.width - avgLen) - Math.abs(b.width - avgLen)
+      )[0];
     if (!geom) continue;
     // Reject if any line is wildly off the expected width (likely not the band).
     if (cand.some((l) => Math.abs(l.length - geom.width) > 6)) continue;