@trustchex/react-native-sdk 1.486.0 → 1.488.0

package/lib/module/Shared/EIDReader/nfcManagerCardService.js

@@ -4,6 +4,24 @@ import NFCManager, { NfcTech } from 'react-native-nfc-manager';
 import { CardService } from "./cardService.js";
 import { ResponseAPDU } from "./smartcards/responseAPDU.js";
 import { Platform } from 'react-native';
+
+// iOS CoreNFC "Tag connection lost" (NFCError 100) is a well-known issue whose
+// likelihood scales with the number of APDU round-trips in a session — a large
+// file like DG2 (face image) needs dozens, so the tag is regularly lost
+// mid-read. The session itself can be re-established with
+// restartTechnologyRequestIOS() WITHOUT losing our PACE/BAC secure-messaging
+// state (keys + send-sequence-counter live in our JS wrapper), so a lost-tag
+// transmit can recover by restarting the session and re-issuing the SAME APDU
+// (idempotent — a failed read advances no SM state, and the caller rewinds the
+// SSC). See react-native-nfc-manager#358.
+const IOS_MAX_RECONNECTS = 3;
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+const isTagLostError = e => {
+  const msg = (e instanceof Error ? e.message : typeof e === 'string' ? e : '').toLowerCase();
+  // The native bridge surfaces these for a dropped/timed-out CoreNFC session;
+  // an empty message is also treated as a lost tag (the observed DG2 failure).
+  return msg === '' || msg.includes('lost') || msg.includes('not connected') || msg.includes('tag was') || msg.includes('session') || msg.includes('invalidated') || msg.includes('timeout') || msg.includes('100');
+};
 export class NFCManagerCardService extends CardService {
   isOpened = false;
   async open() {
@@ -18,21 +36,73 @@ export class NFCManagerCardService extends CardService {
   getIsOpen() {
     return this.isOpened;
   }
+
+  // Session-restart recovery is SAFE only for idempotent data-group reads, NOT
+  // during PACE/BAC: the authentication state machine lives on the chip, so
+  // restarting the CoreNFC session mid-handshake destroys it ("Not even
+  // registered"). The reader turns this on AFTER authentication succeeds.
+  sessionRestartEnabled = false;
+  setSessionRestartEnabled(enabled) {
+    this.sessionRestartEnabled = enabled;
+  }
   async transmit(commandAPDU) {
-    let response;
-    if (Platform.OS === 'ios') {
-      const iosResponse = await NFCManager.sendCommandAPDUIOS(Array.from(commandAPDU.getBytes()));
-      response = [...iosResponse.response, iosResponse.sw1, iosResponse.sw2];
-    } else {
-      response = await NFCManager.transceive(Array.from(commandAPDU.getBytes()));
+    const bytes = Array.from(commandAPDU.getBytes());
+    if (Platform.OS !== 'ios') {
+      return new ResponseAPDU(await NFCManager.transceive(bytes));
+    }
+
+    // During auth (restart disabled) just send once — never restart mid-PACE.
+    if (!this.sessionRestartEnabled) {
+      const r = await NFCManager.sendCommandAPDUIOS(bytes);
+      return new ResponseAPDU([...r.response, r.sw1, r.sw2]);
+    }
+
+    // Post-auth data reads: on a lost-tag error restart the CoreNFC session and
+    // retry the same command (secure-messaging state is preserved by the caller).
+    let lastError;
+    for (let attempt = 0; attempt <= IOS_MAX_RECONNECTS; attempt++) {
+      try {
+        const r = await NFCManager.sendCommandAPDUIOS(bytes);
+        return new ResponseAPDU([...r.response, r.sw1, r.sw2]);
+      } catch (e) {
+        lastError = e;
+        if (attempt >= IOS_MAX_RECONNECTS || !isTagLostError(e)) {
+          throw e;
+        }
+        // Re-establish the session, then pause briefly so the RF field settles
+        // before re-issuing (immediate re-send after a drop usually fails again).
+        try {
+          await NFCManager.restartTechnologyRequestIOS();
+        } catch {
+          // If restart itself fails the session is unrecoverable for now —
+          // surface the original lost-tag error to the caller.
+          throw e;
+        }
+        await sleep(150 * (attempt + 1));
+      }
     }
-    return new ResponseAPDU(response);
+    throw lastError;
   }
   getATR() {
     throw new Error('Method not implemented.');
   }
-  getIsConnectionLost(_error) {
-    return !this.isOpened;
+  getIsConnectionLost(error) {
+    // Lost if the session was closed, or the error looks like a dropped tag.
+    return !this.isOpened || isTagLostError(error);
+  }
+
+  /** True if the error looks like a dropped/timed-out CoreNFC tag connection
+   *  (as opposed to a real APDU/crypto failure). */
+  isTagLost(error) {
+    return isTagLostError(error);
+  }
+
+  /** Re-establish the CoreNFC session (iOS) so a fresh handshake can be retried
+   *  after a tag drop. No-op on Android. Best-effort. */
+  async restartSession() {
+    if (Platform.OS === 'ios') {
+      await NFCManager.restartTechnologyRequestIOS();
+    }
   }
   async close() {
     await NFCManager.cancelTechnologyRequest();

package/lib/module/Shared/EIDReader/protocol/paceDH.js

@@ -0,0 +1,101 @@
+"use strict";
+
+/**
+ * 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. */
+
+const hx = s => 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 = {
+  // 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, skPcd, pkPicc, nonce) => {
+  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, mappedGenerator, sk) => modPow(mappedGenerator, sk, group.p);
+export const dhSharedSecret = (group, pkPicc, sk) => modPow(pkPicc, sk, group.p);
+
+/** Square-and-multiply modular exponentiation (constant-shape, bigint). */
+export function modPow(base, exp, mod) {
+  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, group) => {
+  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/lib/module/Shared/EIDReader/protocol/paceErrors.js

@@ -0,0 +1,34 @@
+"use strict";
+
+/**
+ * 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. */
+
+// 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 {
+  paceUnsupported = true;
+  constructor(reason, detail) {
+    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 => e instanceof PACEUnsupportedError || typeof e === 'object' && e !== null && e.paceUnsupported === true;

package/lib/module/Shared/EIDReader/protocol/paceProtocol.js

@@ -3,6 +3,7 @@
 import { AESSecureMessagingWrapper } from "../aesSecureMessagingWrapper.js";
 import { TripleDesSecureMessagingWrapper } from "../tripleDesSecureMessagingWrapper.js";
 import { PACEInfo } from "../paceInfo.js";
+import { PACEUnsupportedError } from "./paceErrors.js";
 import { PACEResult } from "./paceResult.js";
 import { PACEKeySpec } from "../paceKeySpec.js";
 import { EID_CONSTANTS } from "../constants/eidConstants.js";
@@ -18,6 +19,51 @@ import { ec as EC } from 'elliptic';
   const _elliptic = require('elliptic');
   const _hash = require('hash.js');
   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',
@@ -91,10 +137,13 @@ export class PACEProtocol {
     const digestAlg = PACEInfo.toDigestAlgorithm(oid);
     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
@@ -252,7 +301,7 @@ export class PACEProtocol {
    */
   async doPACEStep2IM(curveName, piccNonceHex, cipherAlg) {
     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}`);
     }
     const curve = new EC(curveName);
 
@@ -649,7 +698,7 @@ export class PACEProtocol {
         return 'p521';
       // NIST P-521
       default:
-        throw new Error(`Unsupported domain parameter ID: ${parameterId}`);
+        throw new PACEUnsupportedError('curve', `domain parameter ID ${parameterId}`);
     }
   }
 }

package/lib/module/Shared/EIDReader/protocol/readBinaryAPDUSender.js

@@ -59,10 +59,14 @@ export class ReadBinaryAPDUSender {
     try {
       responseAPDU = await this.secureMessagingSender.transmit(wrapper, commandAPDU);
     } catch (error) {
-      if (this.service.getIsConnectionLost(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(responseAPDU, isTLVEncodedOffsetNeeded);
     ReadBinaryAPDUSender.checkStatusWordAfterFileOperation(commandAPDU, responseAPDU);

package/lib/module/Shared/Libs/country-display.utils.js

@@ -5,12 +5,24 @@ import { UnicodeCountry } from "../EIDReader/data/unicodeCountry.js";
 const COUNTRY_NAME_OVERRIDES = {
   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 = {
+  D: 'DEU'
+};
 const findCountryByAlpha3 = alpha3Code => {
   return [...UnicodeCountry.VALUES, ...ISOCountry.VALUES].find(country => country.toAlpha3Code() === alpha3Code);
 };
 export const getLocalizedCountryName = (alpha3Code, _language) => {
   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) {
     return overrideName;

package/lib/module/Shared/Libs/diagnosticReport.js

@@ -24,6 +24,26 @@ const icaoCheckDigit = str => {
   }
   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 = {
+  user_cancelled: 'CANCEL',
+  tag_lost: 'TAGLOST',
+  timeout: 'TIMEOUT',
+  unsupported: 'UNSUPPORTED',
+  not_enabled: 'DISABLED',
+  auth_failed: 'AUTH',
+  reading_error: 'READ'
+};
+const nfcErrorCode = (category, statusWord) => {
+  const part = NFC_CATEGORY_CODE[category ?? ''] ?? 'READ';
+  return statusWord ? `NFC-${part}-${statusWord}` : `NFC-${part}`;
+};
 /** Compute per-field check-digit pass/fail for a TD1 MRZ (best-effort). */
 const computeTd1CheckDigits = mrzText => {
   if (!mrzText) return undefined;
@@ -120,7 +140,10 @@ export const buildDiagnosticReport = params => {
 
   // --- compact email body (always under MAX_BODY_BYTES) ---
   const nfc = diag.nfc;
-  const nfcLine = nfc.attempted ? `${nfc.authProtocol}${nfc.paceFellBackToBac ? '→BAC' : ''} · ${nfc.succeeded ? 'success' : `failed at ${nfc.failureStep ?? '?'} (${nfc.errorCategory ?? 'error'})`}` : 'not attempted';
+  // 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'}) [${nfcCode}]`}` : 'not attempted';
   const checksLine = checkDigits ? Object.entries(checkDigits).map(([k, v]) => `${k}:${v}`).join(' ') : 'n/a';
   const body = ['TRUSTCHEX SCAN REPORT', `Device: ${device.brand} ${device.model} · ${device.systemName} ${device.systemVersion}${device.apiLevel ? ` (API ${device.apiLevel})` : ''}`, `SDK: ${sdkVersion} (build ${device.buildNumber}) · ${device.manufacturer} · ${device.deviceId}`, `Document: ${scanDataObj.documentType ?? 'unknown'} · source: ${scanDataObj.dataSource ?? 'unknown'}`, `MRZ: ${diag.mrz.reachedStable ? 'stable' : 'NOT stable'} after ${diag.mrz.framesProcessed} frames · checks: ${checksLine}`, `Camera: ${diag.camera.frames} frames · brightness ${diag.camera.avgBrightness} (low:${yesNo(diag.camera.hadLowBrightness)} blur:${yesNo(diag.camera.hadBlurryFrames)})`, `NFC: ${nfcLine}`, sessionId ? `Session: ${sessionId}` : '', '', 'Describe the issue here:', '', '', '— Full diagnostics and document images are attached. Please review before sending; do not edit the attachments. —'].filter(Boolean).join('\n');
   const subject = `Trustchex scan report — ${scanDataObj.documentType ?? 'doc'} — ${device.brand} ${device.model} — v${sdkVersion}${sessionId ? ` — ${sessionId}` : ''}`;

package/lib/module/Shared/Libs/diagnostics.js

@@ -100,7 +100,16 @@ export class DiagnosticsCollector {
 
   nfcAttemptStarted() {
     // 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;
   }
   nfcChipDetected() {
@@ -124,15 +133,28 @@ export class DiagnosticsCollector {
       this.nfc.failureStep = step.step;
     }
   }
+
+  /** 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() {
+    return this.nfc.failureStep;
+  }
+
+  /** APDU status word recorded for the failing step, if any (e.g. '6982'). */
+  getFailureStatusWord() {
+    const fs = this.nfc.failureStep;
+    if (!fs) return undefined;
+    return this.nfc.steps.find(s => s.step === fs && !s.ok)?.sw;
+  }
   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) {
+    // 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;
     }
   }