@trustchex/react-native-sdk 1.486.0 → 1.488.0

package/src/Shared/EIDReader/eidReader.ts

@@ -2,6 +2,7 @@ import { BACKey } from './bacKey';
 import { PACEKeySpec } from './paceKeySpec';
 import { NFCManagerCardService } from './nfcManagerCardService';
 import { EIDService } from './eidService';
+import { isPACEUnsupportedError } from './protocol/paceErrors';
 import { DG1File } from './lds/icao/dg1File';
 import { DG2File } from './lds/icao/dg2File';
 import { DG11File } from './lds/icao/dg11File';
@@ -38,6 +39,54 @@ const categorizeNfcError = (msg: string): string => {
   return 'reading_error';
 };
 
+/** Short, stable code per category for the user-facing reportable error code. */
+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',
+};
+
+/** Short, stable token per read step, so the error code names WHERE it failed.
+ *  A generic NFC-READ is not actionable; NFC-READ-DG2-6982 tells support the
+ *  read failed reading the face image (DG2) with APDU status 6982. */
+const NFC_STEP_CODE: Record<string, string> = {
+  open: 'OPEN',
+  selectApplet: 'SELAPP',
+  selectMF: 'SELMF',
+  readCardAccess: 'CARDACCESS',
+  paceAuth: 'PACE',
+  bacAuth: 'BAC',
+  readDG1: 'DG1',
+  readDG2: 'DG2',
+  readDG11: 'DG11',
+};
+
+/**
+ * Build a stable, reportable error code from a categorised NFC failure that
+ * names the failing STEP, e.g. `NFC-READ-DG2-6982` (reading the face image
+ * failed, APDU status 6982) or `NFC-AUTH-PACE-6300` (PACE auth rejected). Falls
+ * back to `NFC-<category>` when neither step nor status word is known.
+ * Non-PII by construction: only the bucket + step name + the chip's 4-hex
+ * status word. A user can quote it to pinpoint exactly where the read failed.
+ */
+const buildNfcErrorCode = (
+  category: string,
+  msg: string,
+  step?: string,
+  stepSw?: string
+): string => {
+  const part = NFC_CATEGORY_CODE[category] ?? 'READ';
+  const stepTok = step ? NFC_STEP_CODE[step] : undefined;
+  // Prefer the status word recorded against the failing step; fall back to one
+  // parsed from the error message.
+  const sw = stepSw ?? extractStatusWord(msg);
+  return [`NFC-${part}`, stepTok, sw].filter(Boolean).join('-');
+};
+
 // --- Minimal PNG encoder (pure JS, no native deps) ---
 // Uses deflate stored (uncompressed) blocks for O(n) encoding speed.
 // A naive DCT-based JPEG encoder would be O(n²) and freeze the JS thread
@@ -182,6 +231,14 @@ function pixelsToPng(
  * If the image is JPEG 2000, decode and convert to PNG so React Native can display it.
  * Returns { base64, mimeType } with the converted image, or the original if not JP2.
  */
+// Largest JP2 face image we will attempt to decode in pure JS on the UI thread.
+// The `jpeg2000` decoder's parse() is SYNCHRONOUS and roughly quadratic, so a
+// large image (some passports store 20–30 KB+ JPEG2000 portraits) blocks the JS
+// thread for many seconds or indefinitely — the German-passport "stuck at face
+// conversion" hang. A JS timeout cannot interrupt a synchronous call, so we must
+// gate BEFORE decoding. ~12 KB decodes fast; beyond that we keep the raw JP2.
+const MAX_JP2_DECODE_BYTES = 12 * 1024;
+
 function convertJP2IfNeeded(
   imageBuffer: Buffer,
   mimeType: string
@@ -190,6 +247,18 @@ function convertJP2IfNeeded(
     return { base64: imageBuffer.toString('base64'), mimeType };
   }
 
+  // Too large to decode synchronously without freezing the UI — keep the raw
+  // JP2. The face image is still captured (the verification backend / face-match
+  // accept JPEG2000); only the on-screen preview can't render it. This lets the
+  // NFC read COMPLETE instead of hanging.
+  if (imageBuffer.length > MAX_JP2_DECODE_BYTES) {
+    debugLog(
+      'EID',
+      `[EID] JP2 face image is ${imageBuffer.length} bytes (> ${MAX_JP2_DECODE_BYTES}); skipping in-JS decode to avoid blocking, keeping raw JP2`
+    );
+    return { base64: imageBuffer.toString('base64'), mimeType };
+  }
+
   debugLog('EID', '[EID] Face image is JP2, attempting conversion…');
   try {
     // Lazy-load jpeg2000 to avoid crashing if it fails to import
@@ -349,7 +418,12 @@ const eidReader = async (
   const stepTimer = () => {
     const t0 = Date.now();
     return (step: string, ok: boolean, error?: unknown) => {
-      const msg = error instanceof Error ? error.message : error ? String(error) : undefined;
+      const msg =
+        error instanceof Error
+          ? error.message
+          : error
+            ? String(error)
+            : undefined;
       // Store only the APDU status word and a COARSE category — never the raw
       // error text, which could in theory embed field/PII values. The SW + step
       // name + category carry all the actionable signal.
@@ -472,12 +546,38 @@ const eidReader = async (
 
           const done = stepTimer();
           try {
-            await passportService.doPACE(
-              paceKey,
-              paceInfo.oid,
-              paceInfo.parameterId,
-              progressCallback
-            );
+            // PACE runs many APDU round-trips; on iOS the CoreNFC tag connection
+            // can drop mid-handshake (empty/lost-tag error). A restart can't
+            // resume PACE (the on-chip state is gone), so on a CONNECTION-DROP
+            // (not a crypto/capability failure) restart the session and retry
+            // the WHOLE PACE handshake from scratch a few times. A real failure
+            // (wrong key, unsupported variant) is rethrown immediately.
+            const MAX_PACE_ATTEMPTS = 3;
+            for (let paceAttempt = 1; ; paceAttempt++) {
+              try {
+                await passportService.doPACE(
+                  paceKey,
+                  paceInfo.oid,
+                  paceInfo.parameterId,
+                  progressCallback
+                );
+                break;
+              } catch (attemptErr) {
+                const lost = nfcManagerCardService.isTagLost(attemptErr);
+                if (!lost || paceAttempt >= MAX_PACE_ATTEMPTS) {
+                  throw attemptErr;
+                }
+                debugLog(
+                  'EID',
+                  `[EID] PACE attempt ${paceAttempt} lost the tag; restarting session and retrying`
+                );
+                await nfcManagerCardService.restartSession();
+                await new Promise((r) => setTimeout(r, 200 * paceAttempt));
+                // Re-select MF + re-read EF.CardAccess so the next PACE starts
+                // from the same clean state as the first attempt.
+                await passportService.sendSelectMF();
+              }
+            }
             hasPACESucceeded = true;
             done('paceAuth', true);
             debugLog('EID', '[EID] PACE succeeded');
@@ -493,13 +593,19 @@ const eidReader = async (
           );
         }
       } catch (paceError) {
-        // PACE protocol exchange failed — fall back to BAC
-        diagnostics.nfcPaceFellBackToBac('pace_failed');
+        // PACE could not complete — fall back to BAC. Distinguish a CAPABILITY
+        // gap (this build can't run the variant the chip advertises) from a
+        // RUNTIME failure (wrong key, tag lost, APDU error) so diagnostics show
+        // exactly why, e.g. pace_unsupported_curve vs pace_failed.
+        const reason = isPACEUnsupportedError(paceError)
+          ? `pace_unsupported_${paceError.reason}`
+          : 'pace_failed';
+        diagnostics.nfcPaceFellBackToBac(reason);
         const msg =
           paceError instanceof Error ? paceError.message : String(paceError);
         debugLog(
           'EID',
-          `[EID] PACE protocol failed (${msg}), falling back to BAC`
+          `[EID] PACE could not complete (${reason}: ${msg}), falling back to BAC`
         );
         if (paceError instanceof Error && paceError.stack) {
           debugLog('EID', '[EID] PACE error stack:', paceError.stack);
@@ -555,6 +661,13 @@ const eidReader = async (
       progressCallback(progress);
     }
 
+    // Authentication is complete — enable iOS CoreNFC session-restart recovery
+    // for the data-group reads. It must stay OFF during PACE/BAC (the auth state
+    // lives on the chip; a mid-handshake restart destroys it). Reads are
+    // idempotent and their secure-messaging state lives in our JS wrapper, so a
+    // session restart between blocks is safe here.
+    nfcManagerCardService.setSessionRestartEnabled(true);
+
     // Read DG1 (MRZ Info)
     const dg1Done = stepTimer();
     let mrzInfo: MRZInfo;
@@ -592,21 +705,23 @@ const eidReader = async (
 
     // Read DG2 (Face Image)
     const dg2Done = stepTimer();
-    const dg2InputStream = passportService.getInputStream(EIDService.EF_DG2);
-    await dg2InputStream.init();
-    InputStream.onRead((totalBytesRead, fileLength) => {
-      progress = 30 + (totalBytesRead / fileLength) * 70;
-      if (progressCallback) {
-        progressCallback(progress);
-      }
-    });
-    const dg2File = new DG2File([], dg2InputStream);
     let imageAsBase64 = '';
     let mimeType = '';
-
     const allFaceImageInfos: FaceImageInfo[] = [];
     let faceInfos;
     try {
+      // init() selects EF.DG2 and reads its header over secure messaging; keep
+      // it INSIDE the try so a failure here is still recorded as the readDG2
+      // step (it was previously outside, so an early DG2 failure went unlabelled).
+      const dg2InputStream = passportService.getInputStream(EIDService.EF_DG2);
+      await dg2InputStream.init();
+      InputStream.onRead((totalBytesRead, fileLength) => {
+        progress = 30 + (totalBytesRead / fileLength) * 70;
+        if (progressCallback) {
+          progressCallback(progress);
+        }
+      });
+      const dg2File = new DG2File([], dg2InputStream);
       faceInfos = await dg2File.getFaceInfos();
       dg2Done('readDG2', true);
     } catch (e) {
@@ -644,8 +759,26 @@ const eidReader = async (
     };
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
-    diagnostics.nfcResult(false, categorizeNfcError(msg));
+    const category = categorizeNfcError(msg);
+    diagnostics.nfcResult(false, category);
     debugLog('EID', 'Error reading passport data', error);
+    // Rethrow so the caller can surface an accurate, actionable message. Swallowing
+    // here returned `undefined`, which the UI mis-reported as "invalid MRZ fields"
+    // (e.g. a German passport whose BAC/PACE auth or chip read actually failed).
+    // The category is attached for the UI to map to a specific message.
+    const rethrown = error instanceof Error ? error : new Error(msg);
+    const tagged = rethrown as Error & {
+      nfcCategory?: string;
+      nfcCode?: string;
+    };
+    tagged.nfcCategory = category;
+    tagged.nfcCode = buildNfcErrorCode(
+      category,
+      msg,
+      diagnostics.getFailureStep(),
+      diagnostics.getFailureStatusWord()
+    );
+    throw tagged;
   } finally {
     await passportService.close();
   }

package/src/Shared/EIDReader/lds/icao/dg11File.ts

@@ -75,20 +75,35 @@ export class DG11File extends DataGroup {
    * Strips trailing filler `<` within each segment.
    */
   private parseName(nameString: string): void {
-    const delimIndex = nameString.indexOf('<<');
-    if (delimIndex < 0) {
-      this.lastName = nameString.replace(/<+$/, '').trim();
-      this.firstName = '';
+    const fillerToSpace = (s: string): string =>
+      s
+        .replace(/<+$/, '') // drop trailing filler
+        .replace(/</g, ' ') // internal filler = word separator
+        .replace(/\s+/g, ' ')
+        .trim();
+
+    const dblIndex = nameString.indexOf('<<');
+    if (dblIndex >= 0) {
+      // Standard ICAO layout: PRIMARY<<SECONDARY.
+      this.lastName = fillerToSpace(nameString.substring(0, dblIndex));
+      this.firstName = fillerToSpace(nameString.substring(dblIndex + 2));
       return;
     }
-    this.lastName = nameString
-      .substring(0, delimIndex)
-      .replace(/<+$/, '')
-      .trim();
-    this.firstName = nameString
-      .substring(delimIndex + 2)
-      .replace(/<$/, ' ')
-      .replace(/<+$/, '')
-      .trim();
+
+    // No `<<` separator. Some chips (e.g. certain Turkish PACE passports) store
+    // DG11 0x5F0E as SURNAME<GIVEN1<GIVEN2 with single fillers. Split on the
+    // FIRST single filler: surname = first token, given names = the rest. With
+    // no filler at all the field is a single token we cannot reliably split into
+    // surname/given, so leave firstName empty and let the caller decide (the MRZ
+    // split is then more trustworthy than a guess).
+    const singleIndex = nameString.replace(/<+$/, '').indexOf('<');
+    if (singleIndex >= 0) {
+      this.lastName = fillerToSpace(nameString.substring(0, singleIndex));
+      this.firstName = fillerToSpace(nameString.substring(singleIndex + 1));
+      return;
+    }
+
+    this.lastName = fillerToSpace(nameString);
+    this.firstName = '';
   }
 }

package/src/Shared/EIDReader/nfcManagerCardService.ts

@@ -4,6 +4,36 @@ import { CommandAPDU } from './smartcards/commandAPDU';
 import { ResponseAPDU } from './smartcards/responseAPDU';
 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: number) => new Promise((r) => setTimeout(r, ms));
+
+const isTagLostError = (e: unknown): boolean => {
+  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 {
   private isOpened = false;
   public async open(): Promise<void> {
@@ -24,29 +54,77 @@ export class NFCManagerCardService extends CardService {
     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.
+  private sessionRestartEnabled = false;
+
+  public setSessionRestartEnabled(enabled: boolean): void {
+    this.sessionRestartEnabled = enabled;
+  }
+
   public async transmit(commandAPDU: CommandAPDU): Promise<ResponseAPDU> {
-    let response: number[];
+    const bytes = Array.from(commandAPDU.getBytes());
 
-    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())
-      );
+    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]);
     }
 
-    return new ResponseAPDU(response);
+    // 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: unknown;
+    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));
+      }
+    }
+    throw lastError;
   }
 
   public getATR(): Uint8Array {
     throw new Error('Method not implemented.');
   }
 
-  public getIsConnectionLost(_error: Error): boolean {
-    return !this.isOpened;
+  public getIsConnectionLost(error: Error): boolean {
+    // 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). */
+  public isTagLost(error: unknown): boolean {
+    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. */
+  public async restartSession(): Promise<void> {
+    if (Platform.OS === 'ios') {
+      await NFCManager.restartTechnologyRequestIOS();
+    }
   }
 
   public async close(): Promise<void> {

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);