@trustchex/react-native-sdk 1.478.7 → 1.483.4

package/src/Shared/EIDReader/eidReader.ts

@@ -4,11 +4,39 @@ import { NFCManagerCardService } from './nfcManagerCardService';
 import { EIDService } from './eidService';
 import { DG1File } from './lds/icao/dg1File';
 import { DG2File } from './lds/icao/dg2File';
+import { DG11File } from './lds/icao/dg11File';
 import { FaceImageInfo } from './lds/iso19794/faceImageInfo';
 import { Buffer } from 'buffer';
 import { MRZInfo } from './lds/icao/mrzInfo';
 import { InputStream } from './java/inputStream';
 import { debugLog } from '../Libs/debug.utils';
+import { diagnostics } from '../Libs/diagnostics';
+
+/**
+ * Extract an APDU status word (hex, e.g. "6982") from an error message if the
+ * protocol layer included one. Returns undefined when none is present. Kept
+ * deliberately loose — the protocol senders embed "SW=...." / "(6982)" forms.
+ */
+const extractStatusWord = (msg: string): string | undefined => {
+  const m = msg.match(/\b(?:SW[:= ]?)?([0-9a-fA-F]{4})\b/);
+  return m ? m[1].toUpperCase() : undefined;
+};
+
+/** Categorise an NFC error message into a coarse, non-PII bucket. */
+const categorizeNfcError = (msg: string): string => {
+  const m = msg.toLowerCase();
+  if (m.includes('cancel')) return 'user_cancelled';
+  if (m.includes('lost') || m.includes('steady')) return 'tag_lost';
+  if (m.includes('timeout')) return 'timeout';
+  if (m.includes('not supported') || m.includes('unsupported')) {
+    return 'unsupported';
+  }
+  if (m.includes('not enabled') || m.includes('disabled')) return 'not_enabled';
+  if (m.includes('auth') || m.includes('mutual') || m.includes('security')) {
+    return 'auth_failed';
+  }
+  return 'reading_error';
+};
 
 // --- Minimal PNG encoder (pure JS, no native deps) ---
 // Uses deflate stored (uncompressed) blocks for O(n) encoding speed.
@@ -295,7 +323,14 @@ const eidReader = async (
   dateOfExpiry: string,
   progressCallback?: (progress: number) => void
 ): Promise<
-  { mrz?: MRZInfo; faceImage: string; mimeType: string } | undefined
+  | {
+      mrz?: MRZInfo;
+      faceImage: string;
+      mimeType: string;
+      dg11FirstName: string | null;
+      dg11LastName: string | null;
+    }
+  | undefined
 > => {
   let progress = 0;
   const nfcManagerCardService = new NFCManagerCardService();
@@ -307,8 +342,40 @@ const eidReader = async (
     true
   );
 
+  // Structured NFC diagnostics: record each step's outcome + timing + APDU SW
+  // into the session collector so the result screen can surface device-specific
+  // read failures. Best-effort and side-effect-only — never alters the flow.
+  diagnostics.nfcAttemptStarted();
+  const stepTimer = () => {
+    const t0 = Date.now();
+    return (step: string, ok: boolean, error?: unknown) => {
+      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.
+      diagnostics.nfcStep({
+        step,
+        ok,
+        ms: Date.now() - t0,
+        sw: msg ? extractStatusWord(msg) : undefined,
+        error: msg ? categorizeNfcError(msg) : undefined,
+      });
+    };
+  };
+
   try {
-    await passportService.open();
+    {
+      const done = stepTimer();
+      try {
+        await passportService.open();
+        // Reaching open() without throwing means the chip powered on / was seen.
+        diagnostics.nfcChipDetected();
+        done('open', true);
+      } catch (e) {
+        done('open', false, e);
+        throw e;
+      }
+    }
 
     progress = 1;
     if (progressCallback) {
@@ -320,15 +387,20 @@ const eidReader = async (
     // regardless of which application the chip activates on power-on.
     let hasPACESucceeded = false;
 
-    try {
-      await passportService.sendSelectMF();
-      debugLog('EID', '[EID] SELECT MF OK');
-    } catch (mfErr) {
-      const mfMsg = mfErr instanceof Error ? mfErr.message : String(mfErr);
-      debugLog(
-        'EID',
-        `[EID] SELECT MF failed (${mfMsg}), continuing with SFI read anyway`
-      );
+    {
+      const done = stepTimer();
+      try {
+        await passportService.sendSelectMF();
+        done('selectMF', true);
+        debugLog('EID', '[EID] SELECT MF OK');
+      } catch (mfErr) {
+        done('selectMF', false, mfErr);
+        const mfMsg = mfErr instanceof Error ? mfErr.message : String(mfErr);
+        debugLog(
+          'EID',
+          `[EID] SELECT MF failed (${mfMsg}), continuing with SFI read anyway`
+        );
+      }
     }
 
     progress = 2;
@@ -339,28 +411,33 @@ const eidReader = async (
     // Read EF.CardAccess — kept in a separate try/catch so we can distinguish
     // "file read failure" from "PACE protocol failure" in the logs.
     let cardAccessBuf: Buffer | null = null;
-    try {
-      const cardAccessStream = passportService.getInputStream(
-        EIDService.EF_CARD_ACCESS
-      );
-      await cardAccessStream.init();
-      const cardAccessLen = cardAccessStream.getLength();
-      const buf = Buffer.alloc(cardAccessLen);
-      for (let i = 0; i < cardAccessLen; i++) {
-        buf[i] = await cardAccessStream.read();
+    {
+      const done = stepTimer();
+      try {
+        const cardAccessStream = passportService.getInputStream(
+          EIDService.EF_CARD_ACCESS
+        );
+        await cardAccessStream.init();
+        const cardAccessLen = cardAccessStream.getLength();
+        const buf = Buffer.alloc(cardAccessLen);
+        for (let i = 0; i < cardAccessLen; i++) {
+          buf[i] = await cardAccessStream.read();
+        }
+        cardAccessBuf = buf;
+        done('readCardAccess', true);
+        debugLog(
+          'EID',
+          `[EID] EF.CardAccess read OK: ${cardAccessLen} bytes = ${cardAccessBuf.toString('hex')}`
+        );
+      } catch (readErr) {
+        done('readCardAccess', false, readErr);
+        const readMsg =
+          readErr instanceof Error ? readErr.message : String(readErr);
+        debugLog(
+          'EID',
+          `[EID] EF.CardAccess read FAILED: ${readMsg} — falling back to BAC`
+        );
       }
-      cardAccessBuf = buf;
-      debugLog(
-        'EID',
-        `[EID] EF.CardAccess read OK: ${cardAccessLen} bytes = ${cardAccessBuf.toString('hex')}`
-      );
-    } catch (readErr) {
-      const readMsg =
-        readErr instanceof Error ? readErr.message : String(readErr);
-      debugLog(
-        'EID',
-        `[EID] EF.CardAccess read FAILED: ${readMsg} — falling back to BAC`
-      );
     }
 
     progress = 3;
@@ -369,6 +446,11 @@ const eidReader = async (
     }
 
     // If EF.CardAccess was read successfully, attempt PACE.
+    if (cardAccessBuf === null) {
+      // EF.CardAccess unreadable (the readCardAccess step already recorded the
+      // failure/SW) → PACE can't be attempted; BAC will be used.
+      diagnostics.nfcPaceFellBackToBac('no_card_access');
+    }
     if (cardAccessBuf !== null) {
       try {
         const paceInfo = parsePACEInfoFromCardAccess(cardAccessBuf);
@@ -378,6 +460,7 @@ const eidReader = async (
             'EID',
             `[EID] PACE available: oid=${paceInfo.oid} parameterId=${paceInfo.parameterId}`
           );
+          diagnostics.nfcSetAuth('PACE', paceInfo.oid);
           // PACE is available - derive key from MRZ and perform PACE
           const bacKey = new BACKey(documentNumber, dateOfBirth, dateOfExpiry);
           const paceKey = PACEKeySpec.createMRZKey(bacKey.getKeySeedForPACE());
@@ -387,15 +470,23 @@ const eidReader = async (
             progressCallback(progress);
           }
 
-          await passportService.doPACE(
-            paceKey,
-            paceInfo.oid,
-            paceInfo.parameterId,
-            progressCallback
-          );
-          hasPACESucceeded = true;
-          debugLog('EID', '[EID] PACE succeeded');
+          const done = stepTimer();
+          try {
+            await passportService.doPACE(
+              paceKey,
+              paceInfo.oid,
+              paceInfo.parameterId,
+              progressCallback
+            );
+            hasPACESucceeded = true;
+            done('paceAuth', true);
+            debugLog('EID', '[EID] PACE succeeded');
+          } catch (paceErr) {
+            done('paceAuth', false, paceErr);
+            throw paceErr;
+          }
         } else {
+          diagnostics.nfcPaceFellBackToBac('no_pace_info');
           debugLog(
             'EID',
             '[EID] EF.CardAccess read OK but no PACE SecurityInfo found — document does not support PACE, falling back to BAC'
@@ -403,6 +494,7 @@ const eidReader = async (
         }
       } catch (paceError) {
         // PACE protocol exchange failed — fall back to BAC
+        diagnostics.nfcPaceFellBackToBac('pace_failed');
         const msg =
           paceError instanceof Error ? paceError.message : String(paceError);
         debugLog(
@@ -421,7 +513,16 @@ const eidReader = async (
     }
 
     // Select Applet for MRTD
-    await passportService.sendSelectApplet(hasPACESucceeded);
+    {
+      const done = stepTimer();
+      try {
+        await passportService.sendSelectApplet(hasPACESucceeded);
+        done('selectApplet', true);
+      } catch (e) {
+        done('selectApplet', false, e);
+        throw e;
+      }
+    }
 
     progress = 10;
     if (progressCallback) {
@@ -436,8 +537,16 @@ const eidReader = async (
         await efComStream.read();
       } catch (error) {
         // EF_COM not available -> try to do BAC
+        diagnostics.nfcSetAuth('BAC');
         const bacKey = new BACKey(documentNumber, dateOfBirth, dateOfExpiry);
-        await passportService.doBAC(bacKey);
+        const done = stepTimer();
+        try {
+          await passportService.doBAC(bacKey);
+          done('bacAuth', true);
+        } catch (e) {
+          done('bacAuth', false, e);
+          throw e;
+        }
       }
     }
 
@@ -447,17 +556,42 @@ const eidReader = async (
     }
 
     // Read DG1 (MRZ Info)
-    const dg1InputStream = passportService.getInputStream(EIDService.EF_DG1);
-    await dg1InputStream.init();
-    const dg1File = new DG1File(undefined, dg1InputStream);
-    const mrzInfo = await dg1File.getMRZInfo();
+    const dg1Done = stepTimer();
+    let mrzInfo: MRZInfo;
+    try {
+      const dg1InputStream = passportService.getInputStream(EIDService.EF_DG1);
+      await dg1InputStream.init();
+      const dg1File = new DG1File(undefined, dg1InputStream);
+      mrzInfo = await dg1File.getMRZInfo();
+      dg1Done('readDG1', true);
+    } catch (e) {
+      dg1Done('readDG1', false, e);
+      throw e;
+    }
 
     progress = 30;
     if (progressCallback) {
       progressCallback(progress);
     }
 
+    // Read DG11 (Additional Personal Data — printed name in UTF-8, optional)
+    let dg11FirstName: string | null = null;
+    let dg11LastName: string | null = null;
+    try {
+      const dg11InputStream = passportService.getInputStream(
+        EIDService.EF_DG11
+      );
+      await dg11InputStream.init();
+      const dg11File = new DG11File(dg11InputStream);
+      await dg11File.read();
+      dg11FirstName = dg11File.getFirstName();
+      dg11LastName = dg11File.getLastName();
+    } catch {
+      // DG11 is optional — not all chips have it, and access may be denied
+    }
+
     // Read DG2 (Face Image)
+    const dg2Done = stepTimer();
     const dg2InputStream = passportService.getInputStream(EIDService.EF_DG2);
     await dg2InputStream.init();
     InputStream.onRead((totalBytesRead, fileLength) => {
@@ -471,7 +605,14 @@ const eidReader = async (
     let mimeType = '';
 
     const allFaceImageInfos: FaceImageInfo[] = [];
-    const faceInfos = await dg2File.getFaceInfos();
+    let faceInfos;
+    try {
+      faceInfos = await dg2File.getFaceInfos();
+      dg2Done('readDG2', true);
+    } catch (e) {
+      dg2Done('readDG2', false, e);
+      throw e;
+    }
     for (let faceInfo of faceInfos) {
       allFaceImageInfos.push(...faceInfo.getFaceImageInfos());
     }
@@ -493,12 +634,17 @@ const eidReader = async (
       progressCallback(progress);
     }
 
+    diagnostics.nfcResult(true);
     return {
       mrz: mrzInfo,
       faceImage: imageAsBase64,
       mimeType: mimeType,
+      dg11FirstName,
+      dg11LastName,
     };
   } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    diagnostics.nfcResult(false, categorizeNfcError(msg));
     debugLog('EID', 'Error reading passport data', error);
   } finally {
     await passportService.close();

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

@@ -0,0 +1,94 @@
+import { Buffer } from 'buffer';
+import { InputStream } from '../../java/inputStream';
+import { TLVInputStream } from '../../tlv/tlvInputStream';
+import { DataGroup } from '../dataGroup';
+
+/**
+ * DG11 — Additional Personal Data (ICAO 9303-10 §4.6.6).
+ *
+ * We only extract tag 0x5F0E (Name of Holder), which contains the full name
+ * exactly as printed on the document, in UTF-8, using the same `<<` primary/
+ * secondary delimiter as the MRZ (but with native Unicode characters).
+ *
+ * Example: "ÖZTÜRK<<GÖKHAN MEHMET" → lastName="ÖZTÜRK", firstName="GÖKHAN MEHMET"
+ *
+ * The file is optional on the chip — if absent or unreadable we return null
+ * so the caller can fall back to reverse transliteration.
+ */
+export class DG11File extends DataGroup {
+  private static readonly DG11_TAG = 0x6b;
+  private static readonly TAG_LIST_TAG = 0x5c;
+  private static readonly NAME_OF_HOLDER_TAG = 0x5f0e;
+
+  private firstName: string | null = null;
+  private lastName: string | null = null;
+
+  constructor(is?: InputStream) {
+    super(DG11File.DG11_TAG, is);
+  }
+
+  /** Returns the first name from DG11, or null if not present. */
+  getFirstName(): string | null {
+    return this.firstName;
+  }
+
+  /** Returns the last name from DG11, or null if not present. */
+  getLastName(): string | null {
+    return this.lastName;
+  }
+
+  async read(): Promise<void> {
+    await super.readObject();
+  }
+
+  protected async readContent(inputStream: InputStream): Promise<void> {
+    const tlvIn =
+      inputStream instanceof TLVInputStream
+        ? inputStream
+        : new TLVInputStream(inputStream);
+
+    // Skip the tag list (0x5C) — we only care about 0x5F0E
+    // The tag list tells us which optional tags are present; we probe directly.
+    try {
+      await tlvIn.skipToTag(DG11File.NAME_OF_HOLDER_TAG);
+    } catch {
+      // Tag not present in this chip's DG11
+      return;
+    }
+
+    const length = await tlvIn.readLength();
+    if (length <= 0) return;
+
+    const bytes = new Uint8Array(length);
+    await inputStream.readBytesWithOffset(bytes, 0, length);
+
+    const nameString = Buffer.from(bytes).toString('utf8').trim();
+    this.parseName(nameString);
+  }
+
+  protected writeContent(): void {
+    // Write not needed for reading
+  }
+
+  /**
+   * Split "PRIMARY<<SECONDARY" into last/first name components.
+   * 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 = '';
+      return;
+    }
+    this.lastName = nameString
+      .substring(0, delimIndex)
+      .replace(/<+$/, '')
+      .trim();
+    this.firstName = nameString
+      .substring(delimIndex + 2)
+      .replace(/<$/, ' ')
+      .replace(/<+$/, '')
+      .trim();
+  }
+}

package/src/Shared/Libs/MRZ_KNOWN_ISSUES.md

@@ -118,6 +118,13 @@ Covered by the "real letters in names are not eaten" tests in `mrz.utils.test.ts
   30–44-char MRZ line below that floor, so the native pipeline **crops to the
   on-screen scan frame and upscales + grayscale/contrast-enhances** before OCR.
   The MRZ band must be reasonably filled within the on-screen guide.
+  - Two distinct regions exist in the native code (don't confuse them):
+    the **MRZ-OCR crop** (`buildScanFrameRoiImage`: top 25% / bottom 12% / sides
+    4%, upscaled ≤2.5× to ≤2200px, grayscale, contrast 1.6×) and the
+    **brightness-sampling region** (the on-screen guide: 36% / 36% / 5%). Both are
+    the same on iOS and Android. The diagnostic report records the measured MRZ
+    band pixel height so you can tell when a device leaves the band below the
+    ~16 px/char floor.
 - **Glare / lamination.** Heavy glare on a glossy laminated card still degrades
   OCR; the enhancement helps but does not eliminate it. Steadying the card and
   reducing direct glare improves convergence.

package/src/Shared/Libs/diagnosticReport.ts

@@ -0,0 +1,206 @@
+/**
+ * Builds the support diagnostic report from a scan session.
+ *
+ * Produces three things the result screen turns into a reviewable email:
+ *  - `diagnostics.json`  — technical signals (device, camera, MRZ, NFC steps).
+ *  - `scan-data.json`    — the scanned identity data + raw MRZ (PII; the user
+ *                          reviews it in the draft and chooses to send).
+ *  - a short, size-bounded plain-text BODY summary that always fits an email.
+ *
+ * The full detail lives in the JSON attachments; the email body is intentionally
+ * compact so the draft opens reliably on every mail client.
+ */
+import type { DiagnosticsSnapshot } from './diagnostics';
+import type { DeviceDetails } from './native-device-info.utils';
+import type { MRZFields } from '../Types/mrzFields';
+
+/** ICAO 9303 7-3-1 weighted check digit (local copy; mirrors mrz.utils). */
+const icaoCheckDigit = (str: string): string => {
+  const weights = [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 + weights[i % 3] * v) % 10;
+  }
+  return String(sum);
+};
+
+export interface ScanDataForReport {
+  documentType?: string;
+  dataSource?: string;
+  mrzText?: string | null;
+  mrzFields?: MRZFields | null;
+  barcodeValue?: string | null;
+  /** Which images were captured (presence only, used for the body summary). */
+  images?: {
+    mrzSide?: boolean;
+    front?: boolean;
+    face?: boolean;
+    nfcFace?: boolean;
+  };
+}
+
+interface Td1CheckResult {
+  checkDigits: Record<string, 'pass' | 'fail'>;
+  /** True when the Turkish leading-letter (digits-only) convention was applied. */
+  turkishLetterPrefix: boolean;
+}
+
+/** Compute per-field check-digit pass/fail for a TD1 MRZ (best-effort). */
+const computeTd1CheckDigits = (
+  mrzText?: string | null
+): Td1CheckResult | undefined => {
+  if (!mrzText) return undefined;
+  const lines = mrzText
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  if (lines.length < 2 || lines[0].length < 30 || lines[1].length < 30) {
+    return undefined; // only TD1 handled here; other formats omitted from summary
+  }
+  const l1 = lines[0];
+  const l2 = lines[1];
+  const result: Record<string, 'pass' | 'fail'> = {};
+  const check = (data: string, printed: string) =>
+    icaoCheckDigit(data) === printed ? 'pass' : 'fail';
+
+  // Turkish convention: a doc number may carry a leading serial LETTER, and the
+  // doc-number check digit is computed over the DIGITS ONLY (letter dropped).
+  // The TD1 composite then also diverges from strict ICAO for such cards (no
+  // interpretation of the letter reproduces it). To avoid reporting a misleading
+  // "fail" on a card the SDK legitimately accepted, detect the letter-prefix and
+  // treat both the doc-number and composite as validated under that convention.
+  const docData = l1.slice(5, 14);
+  const docPrinted = l1[14];
+  const hasLetterPrefix = /^[A-Z]/.test(docData);
+  const strictDocOk = icaoCheckDigit(docData) === docPrinted;
+  const turkishDocOk =
+    hasLetterPrefix && icaoCheckDigit(docData.slice(1)) === docPrinted;
+  const docOk = strictDocOk || turkishDocOk;
+  result.documentNumber = docOk ? 'pass' : 'fail';
+  result.birthDate = check(l2.slice(0, 6), l2[6]);
+  result.expiry = check(l2.slice(8, 14), l2[14]);
+
+  const composite =
+    l1.slice(5, 30) + l2.slice(0, 7) + l2.slice(8, 15) + l2.slice(18, 29);
+  const compStrict = check(composite, l2[29]);
+  // If the strict composite fails ONLY because of the Turkish letter-prefix
+  // doc number (which itself passed under the digits-only rule), don't surface a
+  // misleading failure — the SDK accepts these cards.
+  result.composite =
+    compStrict === 'fail' && hasLetterPrefix && docOk ? 'pass' : compStrict;
+  // The Turkish convention was the deciding factor only when strict ICAO would
+  // have failed the doc number but the digits-only rule passes it.
+  const turkishLetterPrefix = !strictDocOk && turkishDocOk;
+  return { checkDigits: result, turkishLetterPrefix };
+};
+
+export interface DiagnosticReportBundle {
+  /** Pretty-printed technical report. */
+  diagnosticsJson: string;
+  /** Pretty-printed scanned identity data (PII). */
+  scanDataJson: string;
+  /** Compact, size-bounded plain-text email body. */
+  body: string;
+  /** Suggested email subject. */
+  subject: string;
+}
+
+const MAX_BODY_BYTES = 4096;
+
+const yesNo = (b: boolean | undefined) => (b ? 'yes' : 'no');
+
+/** Assemble the full report bundle. Pure — no I/O, no native calls. */
+export const buildDiagnosticReport = (params: {
+  diag: DiagnosticsSnapshot;
+  device: DeviceDetails;
+  scan: ScanDataForReport;
+  sdkVersion: string;
+  sessionId?: string;
+}): DiagnosticReportBundle => {
+  const { diag, device, scan, sdkVersion, sessionId } = params;
+
+  const computed = computeTd1CheckDigits(scan.mrzText);
+  const checkDigits = diag.mrz.checkDigits ?? computed?.checkDigits;
+  // Set the Turkish-letter-prefix flag from the final accepted MRZ (the collector
+  // can't know it during scanning; the report does, from the MRZ text).
+  const turkishLetterPrefixApplied =
+    diag.mrz.turkishLetterPrefixApplied || computed?.turkishLetterPrefix === true;
+
+  // --- diagnostics.json (technical, low-PII) ---
+  const diagnosticsObj = {
+    schemaVersion: diag.schemaVersion,
+    generatedAt: diag.generatedAt,
+    sessionId: sessionId ?? null,
+    sdk: { platform: device.platform, sdkVersion, buildNumber: device.buildNumber },
+    device,
+    scan: {
+      documentType: scan.documentType ?? diag.documentType ?? null,
+      dataSource: scan.dataSource ?? diag.dataSource ?? null,
+      totalDurationMs: diag.totalDurationMs,
+      camera: diag.camera,
+    },
+    mrz: {
+      ...diag.mrz,
+      checkDigits: checkDigits ?? null,
+      turkishLetterPrefixApplied,
+    },
+    nfc: diag.nfc,
+    errors: diag.errors,
+  };
+
+  // --- scan-data.json (PII; user reviews before sending) ---
+  const scanDataObj = {
+    documentType: scan.documentType ?? diag.documentType ?? null,
+    dataSource: scan.dataSource ?? diag.dataSource ?? null,
+    mrzText: scan.mrzText ?? null,
+    fields: scan.mrzFields ?? null,
+    barcodeValue: scan.barcodeValue ?? null,
+  };
+
+  // --- 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';
+  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}` : ''}`;
+
+  return {
+    diagnosticsJson: JSON.stringify(diagnosticsObj, null, 2),
+    scanDataJson: JSON.stringify(scanDataObj, null, 2),
+    body: body.length > MAX_BODY_BYTES ? body.slice(0, MAX_BODY_BYTES - 1) + '…' : body,
+    subject,
+  };
+};