@trustchex/react-native-sdk 1.487.0 → 1.489.0

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

@@ -0,0 +1,183 @@
+/**
+ * DH (modular exponentiation, non-EC) primitives for PACE Generic Mapping.
+ *
+ * Modern ePassports/eIDs use ECDH almost universally; a minority of documents
+ * negotiate classic DH PACE. This module provides the DH math as pure,
+ * unit-testable functions so it can be verified against the ICAO 9303 Part 11
+ * worked example before it ever touches a chip. It is deliberately separate from
+ * the EC path in paceProtocol.ts — the working ECDH handshake is not modified.
+ *
+ * References: ICAO Doc 9303 Part 11 §4.4.3.2 (Generic Mapping), BSI TR-03110
+ * Part 3 §3.3.1, RFC 5114 (standardized MODP groups), TR-03110 Table A.1
+ * (standardized domain parameter IDs 0–7).
+ */
+
+/** A DH group: safe-prime modulus p, generator g, and subgroup order q. */
+export interface DHGroup {
+  /** prime modulus */
+  p: bigint;
+  /** generator */
+  g: bigint;
+  /** subgroup order (q) — used to size exponents */
+  q: bigint;
+}
+
+const hx = (s: string): bigint => BigInt('0x' + s.replace(/\s+/g, ''));
+
+/**
+ * Standardized DH domain parameters by TR-03110 parameter ID.
+ *  0 → RFC 5114 §2.1  1024-bit MODP Group with 160-bit Prime Order Subgroup
+ *  1 → RFC 5114 §2.2  2048-bit MODP Group with 224-bit Prime Order Subgroup
+ *  2 → RFC 5114 §2.3  2048-bit MODP Group with 256-bit Prime Order Subgroup
+ * (IDs 3–7 are reserved/unused in practice; EC params start at 8.)
+ */
+export const DH_GROUPS: Record<number, DHGroup> = {
+  // RFC 5114 §2.1 — 1024-bit MODP, 160-bit subgroup (the ICAO worked-example group).
+  0: {
+    p: hx(
+      'B10B8F96 A080E01D DE92DE5E AE5D54EC 52C99FBC FB06A3C6' +
+        '9A6A9DCA 52D23B61 6073E286 75A23D18 9838EF1E 2EE652C0' +
+        '13ECB4AE A9061123 24975C3C D49B83BF ACCBDD7D 90C4BD70' +
+        '98488E9C 219A7372 4EFFD6FA E5644738 FAA31A4F F55BCCC0' +
+        'A151AF5F 0DC8B4BD 45BF37DF 365C1A65 E68CFDA7 6D4DA708' +
+        'DF1FB2BC 2E4A4371'
+    ),
+    g: hx(
+      'A4D1CBD5 C3FD3412 6765A442 EFB99905 F8104DD2 58AC507F' +
+        'D6406CFF 14266D31 266FEA1E 5C41564B 777E690F 5504F213' +
+        '160217B4 B01B886A 5E91547F 9E2749F4 D7FBD7D3 B9A92EE1' +
+        '909D0D22 63F80A76 A6A24C08 7A091F53 1DBF0A01 69B6A28A' +
+        'D662A4D1 8E73AFA3 2D779D59 18D08BC8 858F4DCE F97C2A24' +
+        '855E6EEB 22B3B2E5'
+    ),
+    q: hx('F518AA87 81A8DF27 8ABA4E7D 64B7CB9D 49462353'),
+  },
+  // RFC 5114 §2.2 — 2048-bit MODP, 224-bit subgroup.
+  1: {
+    p: hx(
+      'AD107E1E 9123A9D0 D660FAA7 9559C51F A20D64E5 683B9FD1' +
+        'B54B1597 B61D0A75 E6FA141D F95A56DB AF9A3C40 7BA1DF15' +
+        'EB3D688A 309C180E 1DE6B85A 1274A0A6 6D3F8152 AD6AC212' +
+        '9037C9ED EFDA4DF8 D91E8FEF 55B7394B 7AD5B7D0 B6C12207' +
+        'C9F98D11 ED34DBF6 C6BA0B2C 8BBC27BE 6A00E0A0 B9C49708' +
+        'B3BF8A31 70918836 81286130 BC8985DB 1602E714 415D9330' +
+        '278273C7 DE31EFDC 7310F712 1FD5A074 15987D9A DC0A486D' +
+        'CDF93ACC 44328387 315D75E1 98C641A4 80CD86A1 B9E587E8' +
+        'BE60E69C C928B2B9 C52172E4 13042E9B 23F10B0E 16E79763' +
+        'C9B53DCF 4BA80A29 E3FB73C1 6B8E75B9 7EF363E2 FFA31F71' +
+        'CF9DE538 4E71B81C 0AC4DFFE 0C10E64F'
+    ),
+    g: hx(
+      'AC4032EF 4F2D9AE3 9DF30B5C 8FFDAC50 6CDEBE7B 89998CAF' +
+        '74866A08 CFE4FFE3 A6824A4E 10B9A6F0 DD921F01 A70C4AFA' +
+        'AB739D77 00C29F52 C57DB17C 620A8652 BE5E9001 A8D66AD7' +
+        'C1766910 1999024A F4D02727 5AC1348B B8A762D0 521BC98A' +
+        'E2471504 22EA1ED4 09939D54 DA7460CD B5F6C6B2 50717CBE' +
+        'F180EB34 118E98D1 19529A45 D6F83456 6E3025E3 16A330EF' +
+        'BB77A86F 0C1AB15B 051AE3D4 28C8F8AC B70A8137 150B8EEB' +
+        '10E183ED D19963DD D9E263E4 770589EF 6AA21E7F 5F2FF381' +
+        'B539CCE3 409D13CD 566AFBB4 8D6C0191 81E1BCFE 94B30269' +
+        'EDFE72FE 9B6AA4BD 7B5A0F1C 71CFFF4C 19C418E1 F6EC0179' +
+        '81BC087F 2A7065B3 84B890D3 191F2BFA'
+    ),
+    q: hx('801C0D34 C58D93FE 99717710 1F80535A 4738CEBC BF389A99' + 'B36371EB'),
+  },
+  // RFC 5114 §2.3 — 2048-bit MODP, 256-bit subgroup.
+  2: {
+    p: hx(
+      '87A8E61D B4B6663C FFBBD19C 65195999 8CEEF608 660DD0F2' +
+        '5D2CEED4 435E3B00 E00DF8F1 D61957D4 FAF7DF45 61B2AA30' +
+        '16C3D911 34096FAA 3BF4296D 830E9A7C 209E0C64 97517ABD' +
+        '5A8A9D30 6BCF67ED 91F9E672 5B4758C0 22E0B1EF 4275BF7B' +
+        '6C5BFC11 D45F9088 B941F54E B1E59BB8 BC39A0BF 12307F5C' +
+        '4FDB70C5 81B23F76 B63ACAE1 CAA6B790 2D525267 35488A0E' +
+        'F13C6D9A 51BFA4AB 3AD83477 96524D8E F6A167B5 A41825D9' +
+        '67E144E5 14056425 1CCACB83 E6B486F6 B3CA3F79 71506026' +
+        'C0B857F6 89962856 DED4010A BD0BE621 C3A3960A 54E710C3' +
+        '75F26375 D7014103 A4B54330 C198AF12 6116D227 6E11715F' +
+        '693877FA D7EF09CA DB094AE9 1E1A1597'
+    ),
+    g: hx(
+      '3FB32C9B 73134D0B 2E775066 60EDBD48 4CA7B18F 21EF2054' +
+        '07F4793A 1A0BA125 10DBC150 77BE463F FF4FED4A AC0BB555' +
+        'BE3A6C1B 0C6B47B1 BC3773BF 7E8C6F62 901228F8 C28CBB18' +
+        'A55AE313 41000A65 0196F931 C77A57F2 DDF463E5 E9EC144B' +
+        '777DE62A AAB8A862 8AC376D2 82D6ED38 64E67982 428EBC83' +
+        '1D14348F 6F2F9193 B5045AF2 767164E1 DFC967C1 FB3F2E55' +
+        'A4BD1BFF E83B9C80 D052B985 D182EA0A DB2A3B73 13D3FE14' +
+        'C8484B1E 052588B9 B7D2BBD2 DF016199 ECD06E15 57CD0915' +
+        'B3353BBB 64E0EC37 7FD02837 0DF92B52 C7891428 CDC67EB6' +
+        '184B523D 1DB246C3 2F630784 90F00EF8 D647D148 D4795451' +
+        '5E2327CF EF98C582 664B4C0F 6CC41659'
+    ),
+    q: hx(
+      '8CF83642 A709A097 B4479976 40129DA2 99B1A47D 1EB3750B' +
+        'A308B0FE 64F5FBD3'
+    ),
+  },
+};
+
+/**
+ * PACE DH Generic Mapping (ICAO 9303 Part 11 §4.4.3.2):
+ *   shared secret  h  = PK_PICC ^ SK_PCD  mod p
+ *   mapped generator  g~ = g^s · h         mod p
+ * where s is the decrypted PICC nonce (a big-endian integer).
+ *
+ * Pure function over the group + the three inputs, so it can be checked against
+ * the ICAO worked example. `pkPicc` is the PICC mapping public key; `skPcd` the
+ * PCD mapping private key; `nonce` the decrypted nonce s.
+ */
+export const dhGenericMapping = (
+  group: DHGroup,
+  skPcd: bigint,
+  pkPicc: bigint,
+  nonce: bigint
+): { sharedH: bigint; mappedGenerator: bigint } => {
+  const sharedH = modPow(pkPicc, skPcd, group.p);
+  const gPowS = modPow(group.g, nonce, group.p);
+  const mappedGenerator = (gPowS * sharedH) % group.p;
+  return { sharedH, mappedGenerator };
+};
+
+/**
+ * DH key agreement with a mapped generator (PACE step 3):
+ *   PK = g~ ^ SK mod p   (public key to send)
+ *   K  = PK_PICC ^ SK mod p  (shared secret)
+ */
+export const dhPublicKey = (
+  group: DHGroup,
+  mappedGenerator: bigint,
+  sk: bigint
+): bigint => modPow(mappedGenerator, sk, group.p);
+
+export const dhSharedSecret = (
+  group: DHGroup,
+  pkPicc: bigint,
+  sk: bigint
+): bigint => modPow(pkPicc, sk, group.p);
+
+/** Square-and-multiply modular exponentiation (constant-shape, bigint). */
+export function modPow(base: bigint, exp: bigint, mod: bigint): bigint {
+  if (mod === 1n) return 0n;
+  let result = 1n;
+  base = ((base % mod) + mod) % mod;
+  let e = exp;
+  while (e > 0n) {
+    if (e & 1n) result = (result * base) % mod;
+    e >>= 1n;
+    base = (base * base) % mod;
+  }
+  return result;
+}
+
+/** Fixed-width big-endian byte encoding of a DH value (left-padded to p's size). */
+export const dhEncode = (value: bigint, group: DHGroup): Buffer => {
+  const byteLen = Math.ceil(group.p.toString(16).length / 2);
+  let h = value.toString(16);
+  if (h.length % 2) h = '0' + h;
+  const buf = Buffer.from(h, 'hex');
+  if (buf.length === byteLen) return buf;
+  const out = Buffer.alloc(byteLen);
+  buf.copy(out, byteLen - buf.length);
+  return out;
+};

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

@@ -0,0 +1,41 @@
+/**
+ * Typed PACE errors.
+ *
+ * The point is to let the caller distinguish a PACE CAPABILITY gap (this build
+ * cannot run the variant the chip advertises — e.g. DH agreement, CAM mapping,
+ * an unregistered curve) from a RUNTIME failure (wrong key, tag lost, APDU
+ * error). Both fall back to BAC, but the diagnostics reason must differ so we
+ * can tell "we don't support this document's PACE" from "the read went wrong".
+ */
+
+/** Why a PACE attempt could not even be run by this implementation. */
+export type PACEUnsupportedReason =
+  | 'agreement' // key-agreement algorithm not implemented (e.g. DH when only ECDH built)
+  | 'mapping' // mapping type not implemented (e.g. CAM)
+  | 'curve' // standardized domain parameter / curve not registered
+  | 'cipher'; // cipher not implemented for the chosen mapping
+
+/**
+ * Thrown when the chip advertises a PACE variant this build cannot perform.
+ * Carries a coarse, non-PII reason that maps directly to a diagnostics fallback
+ * reason (`pace_unsupported_<reason>`), so support can see exactly which
+ * capability was missing for a given document.
+ */
+export class PACEUnsupportedError extends Error {
+  readonly paceUnsupported = true;
+  readonly reason: PACEUnsupportedReason;
+
+  constructor(reason: PACEUnsupportedReason, detail: string) {
+    super(`PACE variant not supported (${reason}): ${detail}`);
+    this.name = 'PACEUnsupportedError';
+    this.reason = reason;
+  }
+}
+
+/** Type guard usable across module boundaries (instanceof is unreliable after
+ *  transpilation/bundling, so we also check the marker flag). */
+export const isPACEUnsupportedError = (e: unknown): e is PACEUnsupportedError =>
+  e instanceof PACEUnsupportedError ||
+  (typeof e === 'object' &&
+    e !== null &&
+    (e as { paceUnsupported?: boolean }).paceUnsupported === true);

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/jp2Decode.ts

@@ -0,0 +1,48 @@
+import { NativeModules, Platform } from 'react-native';
+import { Buffer } from 'buffer';
+
+/**
+ * Native JPEG2000 decoder bridge.
+ *
+ * The passport chip portrait (DG2) is frequently stored as JPEG2000
+ * (image/jp2). React Native's <Image> renders a JP2 data URI on Android (its
+ * Fresco/Skia pipeline decodes it) but NOT on iOS (UIImage-backed <Image>
+ * refuses the data URI), so the chip photo showed as a placeholder on iOS.
+ *
+ * iOS's ImageIO *can* decode JPEG2000, so the native `ImageDecoderModule`
+ * round-trips the JP2 to JPEG. We only need this on iOS; on Android the raw
+ * JP2 already renders, so there is no native counterpart and we no-op.
+ */
+interface ImageDecoderNativeModule {
+  decodeJp2ToJpeg(base64Jp2: string): Promise<string>;
+}
+
+const ImageDecoder = (
+  NativeModules as { ImageDecoderModule?: ImageDecoderNativeModule }
+).ImageDecoderModule;
+
+/**
+ * Decode a JPEG2000 buffer to JPEG using the native iOS decoder.
+ *
+ * Returns the JPEG bytes + mime type on success, or null when native decode is
+ * unavailable (Android, or the module isn't linked) or fails — callers should
+ * fall back to their existing behaviour (keep raw JP2).
+ */
+export async function decodeJp2ToJpeg(
+  jp2Buffer: Buffer
+): Promise<{ base64: string; mimeType: string } | null> {
+  if (Platform.OS !== 'ios' || !ImageDecoder?.decodeJp2ToJpeg) {
+    return null;
+  }
+  try {
+    const jpegBase64 = await ImageDecoder.decodeJp2ToJpeg(
+      jp2Buffer.toString('base64')
+    );
+    if (!jpegBase64) {
+      return null;
+    }
+    return { base64: jpegBase64, mimeType: 'image/jpeg' };
+  } catch {
+    return null;
+  }
+}

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

@@ -32,6 +32,21 @@ const normalizeDocumentCode = (
   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.
  *
@@ -821,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++) {
@@ -1388,14 +1407,16 @@ const validateMRZ = (
       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 {

package/src/Shared/Libs/mrzTransliteration.ts

@@ -94,12 +94,25 @@ export function buildDocumentName(
   dg11First?: string | null,
   dg11Last?: string | null
 ): DocumentName {
-  if (dg11First != null && dg11Last != null && (dg11First || dg11Last)) {
+  // Prefer DG11 (the chip's printed name in UTF-8) ONLY when it carries a proper
+  // two-part split — both a surname AND a given name. That is the authoritative
+  // correction for chips whose DG1 MRZ name lacks a `<<` separator (e.g. Turkish
+  // PACE passports), where the raw MRZ would otherwise put the full name into
+  // the surname.
+  //
+  // A one-sided DG11 result (only surname, or only given name) is NOT reliable —
+  // it usually means DG11 had no clear separator, so we don't know which part it
+  // is. Back-filling the missing side from the raw MRZ caused the given name to
+  // be duplicated into both fields, so we now fall through to the MRZ-based
+  // split instead, which is more trustworthy than mixing the two sources.
+  const hasFirst = (dg11First ?? '') !== '';
+  const hasLast = (dg11Last ?? '') !== '';
+  if (hasFirst && hasLast) {
     return {
       rawFirst,
       rawLast,
-      displayFirst: dg11First,
-      displayLast: dg11Last,
+      displayFirst: dg11First as string,
+      displayLast: dg11Last as string,
       source: 'dg11',
     };
   }