@trustchex/react-native-sdk 1.475.1 → 1.481.1

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,
+  };
+};

package/src/Shared/Libs/diagnostics.ts

@@ -0,0 +1,251 @@
+/**
+ * Diagnostics collector for the "Report a scanning issue" feature.
+ *
+ * Accumulates a PII-light technical snapshot of a single scan session — camera
+ * quality, MRZ consensus, and (the highest-value, most device-specific part) a
+ * structured per-step NFC/eID read log. The result screen serialises this into
+ * the diagnostic email the user reviews and sends to support.
+ *
+ * Design notes:
+ * - This is a MODULE-LEVEL SINGLETON so the deep camera/EID call stack can record
+ *   into it without threading a prop/context through every layer. Call `reset()`
+ *   at the start of a scan flow.
+ * - It stores only TECHNICAL signals (counts, timings, brightness, APDU status
+ *   words, pass/fail). It deliberately holds NO identity data, images, MRZ text,
+ *   keys, or nonces — the scanned identity/images shown to the user come from the
+ *   result screen's own state, not from here, and are attached separately with
+ *   the user's explicit review in the email draft.
+ */
+
+/** A single step of the NFC/eID read, with its outcome and timing. */
+export interface NfcStep {
+  /** Step name: 'open' | 'selectMF' | 'readCardAccess' | 'paceAuth' | 'bacAuth'
+   * | 'selectApplet' | 'readDG1' | 'readDG2' | … */
+  step: string;
+  ok: boolean;
+  ms: number;
+  /** APDU status word (hex, e.g. "6982") when the step failed at the APDU level. */
+  sw?: string;
+  /** Coarse, non-PII error CATEGORY when the step failed (e.g. "auth_failed",
+   * "tag_lost", "reading_error") — never the raw error text. */
+  error?: string;
+}
+
+export interface NfcDiagnostics {
+  attempted: boolean;
+  chipDetected: boolean;
+  /** 'PACE' | 'BAC' | 'none' */
+  authProtocol: 'PACE' | 'BAC' | 'none';
+  paceFellBackToBac: boolean;
+  /** 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. */
+  paceFallbackReason?: string;
+  steps: NfcStep[];
+  /** Name of the first failing step, if any. */
+  failureStep?: string;
+  /** Coarse category: 'auth_failed' | 'tag_lost' | 'timeout' | 'unsupported'
+   * | 'not_enabled' | 'user_cancelled' | 'reading_error' | null */
+  errorCategory?: string;
+  retryCount: number;
+  succeeded: boolean;
+}
+
+export interface CameraDiagnostics {
+  frames: number;
+  frameW: number;
+  frameH: number;
+  avgBrightness: number;
+  minBrightness: number;
+  maxBrightness: number;
+  hadLowBrightness: boolean;
+  hadBlurryFrames: boolean;
+  /**
+   * The thresholds the measured values were judged against, so support can read
+   * "117 measured vs 65 floor" rather than just a pass/fail flag. Recorded once.
+   */
+  thresholds?: {
+    brightnessLow?: number;
+    brightnessHigh?: number;
+    minBrightness?: number;
+    blur?: number;
+  };
+}
+
+export interface MrzDiagnostics {
+  framesProcessed: number;
+  reachedStable: boolean;
+  stabilityFrames: number;
+  /** Smallest winning vote margin across contested cells at acceptance. */
+  minContestedMargin: number;
+  /**
+   * Largest MRZ-band pixel height seen (max OCR'd text-block height). Compared
+   * to the ~16px/character ML Kit floor, this explains "scans on device A,
+   * fails on device B" — a smaller band falls below the OCR resolution floor.
+   */
+  maxMrzBandHeightPx?: number;
+  format?: string;
+  /** Per-field check-digit outcomes: 'pass' | 'fail' (no values, no PII). */
+  checkDigits?: Record<string, 'pass' | 'fail'>;
+  /** True when the Turkish leading-serial-letter check-digit convention was used
+   * to accept the document number (set at report-build time from the final MRZ). */
+  turkishLetterPrefixApplied: boolean;
+}
+
+export interface DiagnosticsSnapshot {
+  schemaVersion: number;
+  generatedAt: string;
+  documentType?: string;
+  dataSource?: string;
+  totalDurationMs: number;
+  camera: CameraDiagnostics;
+  mrz: MrzDiagnostics;
+  nfc: NfcDiagnostics;
+  /** Sanitised, non-PII error entries collected during the session. */
+  errors: Array<{ code?: string; category?: string; screen?: string }>;
+}
+
+const emptyCamera = (): CameraDiagnostics => ({
+  frames: 0,
+  frameW: 0,
+  frameH: 0,
+  avgBrightness: 0,
+  minBrightness: 0,
+  maxBrightness: 0,
+  hadLowBrightness: false,
+  hadBlurryFrames: false,
+});
+
+const emptyMrz = (): MrzDiagnostics => ({
+  framesProcessed: 0,
+  reachedStable: false,
+  stabilityFrames: 0,
+  minContestedMargin: 0,
+  turkishLetterPrefixApplied: false,
+});
+
+const emptyNfc = (): NfcDiagnostics => ({
+  attempted: false,
+  chipDetected: false,
+  authProtocol: 'none',
+  paceFellBackToBac: false,
+  steps: [],
+  retryCount: 0,
+  succeeded: false,
+});
+
+/**
+ * Accumulates one scan session's diagnostics. A single shared instance is
+ * exported below; tests can construct their own.
+ */
+export class DiagnosticsCollector {
+  private startedAtMs = 0;
+  private documentType?: string;
+  private dataSource?: string;
+  private camera = emptyCamera();
+  private mrz = emptyMrz();
+  private nfc = emptyNfc();
+  private errors: DiagnosticsSnapshot['errors'] = [];
+
+  /** Begin a fresh session — call when a scan flow starts. */
+  reset(nowMs: number): void {
+    this.startedAtMs = nowMs;
+    this.documentType = undefined;
+    this.dataSource = undefined;
+    this.camera = emptyCamera();
+    this.mrz = emptyMrz();
+    this.nfc = emptyNfc();
+    this.errors = [];
+  }
+
+  setDocument(documentType?: string, dataSource?: string): void {
+    if (documentType) this.documentType = documentType;
+    if (dataSource) this.dataSource = dataSource;
+  }
+
+  /** Merge a camera snapshot (called periodically as frames arrive). */
+  setCamera(c: Partial<CameraDiagnostics>): void {
+    this.camera = { ...this.camera, ...c };
+  }
+
+  /** Merge MRZ consensus metrics. `reachedStable` is STICKY (once true, stays
+   * true) so a later frame's flicker can't unset that the scan did stabilise;
+   * `maxMrzBandHeightPx` keeps the largest seen. */
+  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;
+    this.mrz = { ...this.mrz, ...m, reachedStable, maxMrzBandHeightPx };
+  }
+
+  // ---- NFC: the structured per-step log ----
+
+  nfcAttemptStarted(): void {
+    // A fresh attempt: bump retry count if a previous attempt left steps.
+    if (this.nfc.attempted) this.nfc.retryCount += 1;
+    this.nfc.attempted = true;
+  }
+
+  nfcChipDetected(): void {
+    this.nfc.chipDetected = true;
+  }
+
+  nfcSetAuth(protocol: 'PACE' | 'BAC' | 'none', oid?: string): void {
+    this.nfc.authProtocol = protocol;
+    if (oid) this.nfc.paceOid = oid;
+  }
+
+  nfcPaceFellBackToBac(reason?: string): void {
+    this.nfc.paceFellBackToBac = true;
+    if (reason && !this.nfc.paceFallbackReason) {
+      this.nfc.paceFallbackReason = reason;
+    }
+  }
+
+  /** Record one completed step. Keep messages short and free of PII. */
+  nfcStep(step: NfcStep): void {
+    this.nfc.steps.push(step);
+    if (!step.ok && !this.nfc.failureStep) {
+      this.nfc.failureStep = step.step;
+    }
+  }
+
+  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) {
+      this.nfc.errorCategory = errorCategory;
+    }
+  }
+
+  addError(e: { code?: string; category?: string; screen?: string }): void {
+    this.errors.push(e);
+  }
+
+  /** Build the serialisable snapshot. */
+  snapshot(nowMs: number, isoNow: string): DiagnosticsSnapshot {
+    return {
+      schemaVersion: 1,
+      generatedAt: isoNow,
+      documentType: this.documentType,
+      dataSource: this.dataSource,
+      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 })) },
+      errors: this.errors.map((e) => ({ ...e })),
+    };
+  }
+}
+
+/** Shared session-scoped collector used across the scan flow. */
+export const diagnostics = new DiagnosticsCollector();

package/src/Shared/Libs/http-client.ts

@@ -1,4 +1,5 @@
 import { trackApiCall, trackError } from './analytics.utils';
+import { debugLog } from './debug.utils';
 
 interface ErrorResponse {
   message: string;
@@ -46,6 +47,17 @@ export class InternalServerError extends HttpClientError {
   }
 }
 
+// Short-lived per-verification token issued by the backend during the session
+// key exchange; sent on every subsequent call. Older backends don't issue one,
+// in which case requests go out without the header (backwards compatible).
+let sessionToken: string | null = null;
+
+export const setSessionToken = (token: string | null) => {
+  sessionToken = token;
+};
+
+export const getSessionToken = () => sessionToken;
+
 const request = async <TResponse, TBody>(
   httpMethod: 'GET' | 'POST' | 'PUT' | 'DELETE',
   url: string,
@@ -64,10 +76,11 @@ const request = async <TResponse, TBody>(
   let statusCode = 0;
   let success = false;
 
-  console.log(`[HTTP] ${httpMethod} ${url}`);
+  debugLog('HTTP', `${httpMethod} ${url}`);
   if (body) {
-    console.log(
-      '[HTTP] Request body:',
+    debugLog(
+      'HTTP',
+      'Request body:',
       JSON.stringify(body).substring(0, 200) + '...'
     );
   }
@@ -77,14 +90,16 @@ const request = async <TResponse, TBody>(
       method: httpMethod,
       headers: {
         'Content-Type': 'application/json',
+        ...(sessionToken ? { 'X-Session-Token': sessionToken } : {}),
       },
       body: body ? JSON.stringify(body) : undefined,
     });
 
     statusCode = response.status;
     success = response.ok;
-    console.log(
-      `[HTTP] Response status: ${statusCode} ${response.ok ? '✓' : '✗'}`
+    debugLog(
+      'HTTP',
+      `Response status: ${statusCode} ${response.ok ? '✓' : '✗'}`
     );
 
     let responseJson = null;
@@ -92,14 +107,15 @@ const request = async <TResponse, TBody>(
     try {
       responseJson = await response.json();
       if (responseJson) {
-        console.log(
-          '[HTTP] Response body:',
+        debugLog(
+          'HTTP',
+          'Response body:',
           JSON.stringify(responseJson).substring(0, 200) + '...'
         );
       }
     } catch (error) {
       // Invalid JSON response
-      console.log('[HTTP] Response body: (non-JSON)');
+      debugLog('HTTP', 'Response body: (non-JSON)');
     }
 
     // Track API call performance (non-blocking)