@trustchex/react-native-sdk 1.500.2 → 1.501.0

package/src/Shared/EIDReader/passiveAuth/sodParser.ts

@@ -0,0 +1,142 @@
+import {
+  readNode,
+  readChildren,
+  decodeOid,
+  decodeInteger,
+  toHex,
+  type DerNode,
+} from './der';
+
+/**
+ * Parse EF.SOD (ICAO 9303-11 §5.1) to extract the LDSSecurityObject: the digest
+ * algorithm and the per-data-group hash list the chip's issuer signed. This is
+ * the input to the on-device integrity check (recompute each read DG's hash and
+ * compare). Signature verification + CSCA chaining is done server-side.
+ *
+ * Dependency-free DER walking so it is fully unit-testable from hex fixtures.
+ */
+
+/** Map of OID → digest algorithm name used for DG hashing. */
+const DIGEST_OIDS: Record<string, string> = {
+  '1.3.14.3.2.26': 'SHA-1',
+  '2.16.840.1.101.3.4.2.1': 'SHA-256',
+  '2.16.840.1.101.3.4.2.2': 'SHA-384',
+  '2.16.840.1.101.3.4.2.3': 'SHA-512',
+  '2.16.840.1.101.3.4.2.4': 'SHA-224',
+};
+
+const OID_SIGNED_DATA = '1.2.840.113549.1.7.2';
+
+export interface SodSecurityObject {
+  /** Digest algorithm name, e.g. "SHA-256". */
+  digestAlgorithm: string;
+  /** Per-DG hashes from the SOD: dataGroupNumber → lowercase hex hash. */
+  dataGroupHashes: Record<number, string>;
+}
+
+const TAG_SEQUENCE = 0x10;
+const TAG_OID = 0x06;
+const TAG_OCTET_STRING = 0x04;
+const TAG_INTEGER = 0x02;
+const TAG_SET = 0x11;
+
+/** Find the first child whose masked tag number equals `tagNumber`. */
+function findChild(children: DerNode[], tagNumber: number): DerNode | undefined {
+  return children.find((c) => c.tagNumber === tagNumber);
+}
+
+/**
+ * Parse the EF.SOD bytes (with or without the outer 0x77 application wrapper).
+ * Throws on a malformed structure.
+ */
+export function parseSod(sodBytes: Uint8Array): SodSecurityObject {
+  let root = readNode(sodBytes, 0);
+
+  // Unwrap the [APPLICATION 23] (0x77) wrapper if present.
+  if (root.tag === 0x77) {
+    root = readNode(root.content, 0);
+  }
+
+  // root = ContentInfo SEQUENCE { OID id-signedData, [0] SignedData }
+  if (root.tagNumber !== TAG_SEQUENCE) {
+    throw new Error('SOD: expected ContentInfo SEQUENCE');
+  }
+  const contentInfo = readChildren(root.content);
+  const ciOid = findChild(contentInfo, TAG_OID);
+  if (!ciOid || decodeOid(ciOid.content) !== OID_SIGNED_DATA) {
+    throw new Error('SOD: ContentInfo is not signedData');
+  }
+  // [0] explicit wrapper around SignedData.
+  const signedDataWrapper = contentInfo.find((c) => c.constructed && c.tag === 0xa0);
+  if (!signedDataWrapper) throw new Error('SOD: missing SignedData wrapper');
+  const signedData = readNode(signedDataWrapper.content, 0);
+  if (signedData.tagNumber !== TAG_SEQUENCE) {
+    throw new Error('SOD: SignedData not a SEQUENCE');
+  }
+
+  // SignedData = { version, digestAlgorithms SET, encapContentInfo SEQUENCE, ... }
+  const sdChildren = readChildren(signedData.content);
+  // encapContentInfo is the first SEQUENCE after the digestAlgorithms SET.
+  const setIdx = sdChildren.findIndex((c) => c.tagNumber === TAG_SET);
+  const encap = sdChildren
+    .slice(setIdx + 1)
+    .find((c) => c.tagNumber === TAG_SEQUENCE);
+  if (!encap) throw new Error('SOD: missing encapContentInfo');
+
+  // encapContentInfo = { eContentType OID, [0] eContent OCTET STRING }
+  const encapChildren = readChildren(encap.content);
+  const eContentWrapper = encapChildren.find((c) => c.constructed && c.tag === 0xa0);
+  if (!eContentWrapper) throw new Error('SOD: missing eContent');
+  const eContentOctet = readNode(eContentWrapper.content, 0);
+  if (eContentOctet.tagNumber !== TAG_OCTET_STRING) {
+    throw new Error('SOD: eContent not an OCTET STRING');
+  }
+
+  return parseLdsSecurityObject(eContentOctet.content);
+}
+
+/**
+ * Parse the LDSSecurityObject:
+ *   SEQUENCE { version INTEGER, hashAlgorithm AlgorithmIdentifier,
+ *              SEQUENCE OF DataGroupHash { number INTEGER, hash OCTET STRING } }
+ */
+function parseLdsSecurityObject(bytes: Uint8Array): SodSecurityObject {
+  const lds = readNode(bytes, 0);
+  if (lds.tagNumber !== TAG_SEQUENCE) {
+    throw new Error('SOD: LDSSecurityObject not a SEQUENCE');
+  }
+  const children = readChildren(lds.content);
+
+  // hashAlgorithm AlgorithmIdentifier = SEQUENCE { OID, params? }
+  const algId = children.find((c) => c.tagNumber === TAG_SEQUENCE);
+  if (!algId) throw new Error('SOD: missing hashAlgorithm');
+  const algOidNode = findChild(readChildren(algId.content), TAG_OID);
+  if (!algOidNode) throw new Error('SOD: missing hashAlgorithm OID');
+  const digestAlgorithm = DIGEST_OIDS[decodeOid(algOidNode.content)];
+  if (!digestAlgorithm) {
+    throw new Error(`SOD: unsupported digest OID ${decodeOid(algOidNode.content)}`);
+  }
+
+  // dataGroupHashValues — the SEQUENCE OF after the hashAlgorithm.
+  const algIdx = children.indexOf(algId);
+  const hashSeq = children
+    .slice(algIdx + 1)
+    .find((c) => c.tagNumber === TAG_SEQUENCE);
+  if (!hashSeq) throw new Error('SOD: missing dataGroupHashValues');
+
+  const dataGroupHashes: Record<number, string> = {};
+  for (const dgh of readChildren(hashSeq.content)) {
+    if (dgh.tagNumber !== TAG_SEQUENCE) continue;
+    const parts = readChildren(dgh.content);
+    const numNode = parts.find((p) => p.tagNumber === TAG_INTEGER);
+    const hashNode = parts.find((p) => p.tagNumber === TAG_OCTET_STRING);
+    if (!numNode || !hashNode) continue;
+    dataGroupHashes[decodeInteger(numNode.content)] = toHex(hashNode.content);
+  }
+
+  if (Object.keys(dataGroupHashes).length === 0) {
+    throw new Error('SOD: no data-group hashes found');
+  }
+
+  return { digestAlgorithm, dataGroupHashes };
+}

package/src/Shared/Libs/chipVizMatch.ts

@@ -0,0 +1,149 @@
+import type { DocumentData } from '../Types/documentData';
+
+/**
+ * Verdict of comparing the NFC chip-read (DG1) identity data against the
+ * camera-OCR-read (printed / VIZ) identity data.
+ *
+ * Required by MASAK Tebliğ No. 32, Article 4/C(1)(b): for remote identity
+ * verification of non-Turkish nationals via NFC passport, the chip data must be
+ * verified — via NFC — to match the data printed on the passport. If it cannot
+ * be verified (`MISMATCH` or `UNVERIFIABLE`), no business relationship may be
+ * established through the remote flow.
+ *
+ * - `MATCH`        — every identity-critical field is equal.
+ * - `MISMATCH`     — at least one identity-critical field differs.
+ * - `UNVERIFIABLE` — one of the two sources is missing, so no comparison is possible.
+ */
+export type ChipVizVerdict = 'MATCH' | 'MISMATCH' | 'UNVERIFIABLE';
+
+/** Why a comparison came back `UNVERIFIABLE`. */
+export type ChipVizUnverifiableReason =
+  | 'missing-ocr-source'
+  | 'missing-chip-source';
+
+export interface ChipVizMatchResult {
+  verdict: ChipVizVerdict;
+  /**
+   * Fields that differed (empty on `MATCH` / `UNVERIFIABLE`). Used for
+   * diagnostics and server-side review — never surfaced to the user, to avoid
+   * coaching fraud.
+   */
+  mismatchedFields: Array<keyof DocumentData>;
+  /** Present only when `verdict === 'UNVERIFIABLE'`. */
+  reason?: ChipVizUnverifiableReason;
+}
+
+export interface ChipVizCompareOptions {
+  /**
+   * When `true`, a difference in the raw MRZ name (first/last) alone flips the
+   * verdict to `MISMATCH`. When `false` (default), name differences are
+   * recorded in `mismatchedFields` but do not by themselves cause a mismatch —
+   * a single-character OCR slip on a name should not hard-block on its own.
+   * The identity-critical fields below always drive the verdict regardless.
+   */
+  strictNames?: boolean;
+  /**
+   * Raw MRZ ASCII names (OCR-B, before Unicode/DG11 display conversion). The
+   * normalized `DocumentData.firstName/lastName` are overwritten with the
+   * display form in the read path, so the raw forms must be passed in
+   * explicitly for an apples-to-apples comparison.
+   */
+  chipName?: { first: string; last: string };
+  vizName?: { first: string; last: string };
+}
+
+/**
+ * Identity-critical fields. These are the ICAO check-digit-protected MRZ fields
+ * plus the core identity claim; any difference here is a hard mismatch.
+ */
+const IDENTITY_CRITICAL_FIELDS: Array<keyof DocumentData> = [
+  'documentNumber',
+  'dateOfBirth',
+  'dateOfExpiry',
+  'nationality',
+  'sex',
+];
+
+/** Uppercase, strip `<` filler and surrounding whitespace. */
+function normalizeField(value: string | null | undefined): string {
+  if (!value) return '';
+  return value.replace(/</g, '').trim().toUpperCase();
+}
+
+/** Collapse internal whitespace runs and strip `<` filler, for name comparison. */
+function normalizeName(value: string | null | undefined): string {
+  if (!value) return '';
+  return value
+    .replace(/</g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toUpperCase();
+}
+
+/**
+ * Compare the chip-read (DG1) document data against the OCR-read (printed/VIZ)
+ * document data and produce a match verdict.
+ *
+ * Both inputs are the normalized {@link DocumentData} shape, so they are
+ * directly comparable regardless of which read path produced them. Pass raw MRZ
+ * names via {@link ChipVizCompareOptions} — the `firstName`/`lastName` on
+ * `DocumentData` may already be the Unicode display form, which legitimately
+ * diverges between paths and would cause false mismatches.
+ *
+ * @param chip Chip-read data (from `normalizeFromMRZInfo`), or `undefined` if NFC did not complete.
+ * @param viz  OCR-read data (from `normalizeFromMRZFields`), or `undefined` if no OCR step ran.
+ */
+export function compareChipToViz(
+  chip: DocumentData | undefined,
+  viz: DocumentData | undefined,
+  options: ChipVizCompareOptions = {}
+): ChipVizMatchResult {
+  if (!chip) {
+    return {
+      verdict: 'UNVERIFIABLE',
+      mismatchedFields: [],
+      reason: 'missing-chip-source',
+    };
+  }
+  if (!viz) {
+    return {
+      verdict: 'UNVERIFIABLE',
+      mismatchedFields: [],
+      reason: 'missing-ocr-source',
+    };
+  }
+
+  const mismatchedFields: Array<keyof DocumentData> = [];
+
+  for (const field of IDENTITY_CRITICAL_FIELDS) {
+    if (normalizeField(chip[field] as string) !== normalizeField(viz[field] as string)) {
+      mismatchedFields.push(field);
+    }
+  }
+
+  // Names: compare the raw MRZ ASCII when provided, otherwise fall back to the
+  // (possibly display-form) DocumentData names. Recorded always; only flips the
+  // verdict when strictNames is enabled.
+  const chipFirst = options.chipName?.first ?? chip.firstName;
+  const chipLast = options.chipName?.last ?? chip.lastName;
+  const vizFirst = options.vizName?.first ?? viz.firstName;
+  const vizLast = options.vizName?.last ?? viz.lastName;
+
+  const firstDiffers = normalizeName(chipFirst) !== normalizeName(vizFirst);
+  const lastDiffers = normalizeName(chipLast) !== normalizeName(vizLast);
+
+  const nameMismatchedFields: Array<keyof DocumentData> = [];
+  if (firstDiffers) nameMismatchedFields.push('firstName');
+  if (lastDiffers) nameMismatchedFields.push('lastName');
+  mismatchedFields.push(...nameMismatchedFields);
+
+  // Identity-critical fields always drive the verdict; names only when strict.
+  const hardMismatch =
+    mismatchedFields.some((f) => IDENTITY_CRITICAL_FIELDS.includes(f)) ||
+    (options.strictNames === true && nameMismatchedFields.length > 0);
+
+  return {
+    verdict: hardMismatch ? 'MISMATCH' : 'MATCH',
+    mismatchedFields,
+  };
+}

package/src/Shared/Libs/country-allow.ts

@@ -0,0 +1,17 @@
+/**
+ * Country allow-list check for a workflow step's `allowedCountries`.
+ *
+ * Semantics (mirrors the server engine): an empty or unset list means ALL
+ * countries are allowed; a non-empty list allows ONLY those ICAO-3 codes.
+ * Matching is case-insensitive. `allowedCountries` carries any ICAO-3 code
+ * (server-driven), so the client treats the values as opaque strings.
+ */
+export function isCountryAllowed(
+  issuingState: string | null | undefined,
+  allowedCountries: string[] | null | undefined
+): boolean {
+  if (!allowedCountries || allowedCountries.length === 0) return true;
+  const code = issuingState?.toUpperCase();
+  if (!code) return false;
+  return allowedCountries.map((c) => c.toUpperCase()).includes(code);
+}

package/src/Shared/Libs/documentDataNormalizer.ts

@@ -3,26 +3,39 @@ import type { DocumentData } from '../Types/documentData';
 import type { MRZInfo } from '../EIDReader/lds/icao/mrzInfo';
 
 /**
- * Expand a 2-digit MRZ year to a 4-digit calendar year.
- * ICAO 9303: YY >= 30 → 19YY, YY < 30 → 20YY.
- * (Threshold 30 keeps all current valid documents in range.)
+ * Expand a 2-digit MRZ year to a 4-digit calendar year, using a century rule
+ * appropriate to the kind of date:
+ *
+ * - `'birth'`: a birth date is never in the future. Any YY greater than the
+ *   current 2-digit year must be the previous century (e.g. in 2026, "85" →
+ *   1985, "20" → 2020). This is the ICAO-style sliding window pegged to "now".
+ * - `'expiry'`: a travel/ID document's expiry is recent-past-to-future and no
+ *   document valid today expired in the 1900s, so expiry years are always 20YY
+ *   (e.g. "36" → 2036, not 1936 — the previous fixed-threshold bug).
  */
-function expandYear(yy: string): string {
+function expandYear(yy: string, kind: 'birth' | 'expiry'): string {
+  if (kind === 'expiry') return `20${yy}`;
   const n = parseInt(yy, 10);
-  return n >= 30 ? `19${yy}` : `20${yy}`;
+  // Current 2-digit year as the sliding pivot (e.g. 26 in 2026). Years after it
+  // can't be a birth this century, so they belong to the 1900s.
+  const pivot = new Date().getFullYear() % 100;
+  return n > pivot ? `19${yy}` : `20${yy}`;
 }
 
 /**
  * Convert a YYMMDD MRZ date string to ISO 8601 YYYY-MM-DD.
  * Returns null for empty, null, or malformed input.
  */
-function mrzDateToISO(raw: string | null | undefined): string | null {
+function mrzDateToISO(
+  raw: string | null | undefined,
+  kind: 'birth' | 'expiry'
+): string | null {
   if (!raw || raw.length !== 6) return null;
   const yy = raw.slice(0, 2);
   const mm = raw.slice(2, 4);
   const dd = raw.slice(4, 6);
   if (!/^\d{6}$/.test(raw)) return null;
-  return `${expandYear(yy)}-${mm}-${dd}`;
+  return `${expandYear(yy, kind)}-${mm}-${dd}`;
 }
 
 /**
@@ -84,8 +97,8 @@ export function normalizeFromMRZInfo(mrz: MRZInfo): DocumentData {
     lastName: mrz.getPrimaryIdentifier().trim(),
     firstName: mrz.getSecondaryIdentifier().trim(),
     sex: normalizeSex(mrz.getGender().getStrCode()),
-    dateOfBirth: mrzDateToISO(mrz.getDateOfBirth()),
-    dateOfExpiry: mrzDateToISO(mrz.getDateOfExpiry()),
+    dateOfBirth: mrzDateToISO(mrz.getDateOfBirth(), 'birth'),
+    dateOfExpiry: mrzDateToISO(mrz.getDateOfExpiry(), 'expiry'),
   };
 }
 
@@ -102,7 +115,7 @@ export function normalizeFromMRZFields(fields: MRZFields): DocumentData {
     lastName: clean(fields.lastName) ?? '',
     firstName: clean(fields.firstName) ?? '',
     sex: normalizeSex(fields.sex),
-    dateOfBirth: mrzDateToISO(fields.birthDate),
-    dateOfExpiry: mrzDateToISO(fields.expirationDate),
+    dateOfBirth: mrzDateToISO(fields.birthDate, 'birth'),
+    dateOfExpiry: mrzDateToISO(fields.expirationDate, 'expiry'),
   };
 }

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

@@ -0,0 +1,87 @@
+import { Platform, NativeModules, PermissionsAndroid } from 'react-native';
+import { debugError } from './debug.utils';
+
+/**
+ * Coarse geolocation capture for the MASAK Tebliğ No. 32 Article 4/C(1)(e)
+ * technical-data requirement. Invoked when a workflow step enables
+ * collectGeolocation.
+ *
+ * Implemented entirely with the platform's native location framework via the
+ * SDK's own native modules (iOS Core Location through PermissionModule, Android
+ * LocationManager through GeolocationModule) — no third-party module. The host
+ * app must declare the OS permission strings (iOS
+ * `NSLocationWhenInUseUsageDescription`, Android `ACCESS_COARSE_LOCATION`).
+ *
+ * Everything is fail-soft: if the native module is missing, services are off,
+ * permission is denied, or the fix times out, this returns null and the flow
+ * proceeds — the backend treats a missing geolocation as "not provided".
+ *
+ * @returns "lat,lng" rounded to ~city-block precision (~110 m), or null.
+ */
+export async function captureCoarseGeolocation(
+  timeoutMs = 8000
+): Promise<string | null> {
+  try {
+    if (Platform.OS === 'android') {
+      const granted = await requestAndroidLocationPermission();
+      if (!granted) return null;
+      const mod = NativeModules.GeolocationModule;
+      if (!mod?.getCoarseLocation) return null;
+      return normalize(
+        await withJsBackstop(mod.getCoarseLocation(timeoutMs), timeoutMs)
+      );
+    }
+
+    // iOS: Core Location (via the existing PermissionModule) requests
+    // when-in-use authorization itself given the Info.plist usage string.
+    const mod = NativeModules.PermissionModule;
+    if (!mod?.getCoarseLocation) return null;
+    return normalize(
+      await withJsBackstop(mod.getCoarseLocation(timeoutMs), timeoutMs)
+    );
+  } catch (e) {
+    debugError('geolocation.utils', 'native capture failed', e);
+    return null;
+  }
+}
+
+function normalize(value: string | null | undefined): string | null {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  return value;
+}
+
+/**
+ * JS-side backstop: the native side enforces its own timeout, but if a native
+ * regression left the promise unsettled, this resolves null so the flow can't
+ * hang. The margin keeps the native timeout authoritative on the happy path.
+ */
+async function withJsBackstop(
+  native: Promise<string | null>,
+  timeoutMs: number
+): Promise<string | null> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const backstop = new Promise<string | null>((resolve) => {
+    timer = setTimeout(() => resolve(null), timeoutMs + 2000);
+  });
+  try {
+    return await Promise.race([native, backstop]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Request coarse location permission on Android. The host app must declare
+ * ACCESS_COARSE_LOCATION in its manifest. iOS handles its own prompt through
+ * Core Location, so this is Android-only.
+ */
+async function requestAndroidLocationPermission(): Promise<boolean> {
+  try {
+    const result = await PermissionsAndroid.request(
+      PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION
+    );
+    return result === PermissionsAndroid.RESULTS.GRANTED;
+  } catch {
+    return false;
+  }
+}

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

@@ -18,6 +18,17 @@ const runWithRetry = async <T>(
       }
       return result;
     } catch (error) {
+      // Non-retryable errors (e.g. a server-instructed session termination,
+      // MASAK 4/C(1)(e)) must propagate immediately, with their flags intact —
+      // retrying can't help and would just delay surfacing the outcome.
+      if (
+        error &&
+        typeof error === 'object' &&
+        ((error as { sessionTerminated?: boolean }).sessionTerminated ||
+          (error as { nonRetryable?: boolean }).nonRetryable)
+      ) {
+        throw error;
+      }
       lastError = error;
       retries++;
       console.error(

package/src/Shared/Services/DataUploadService.ts

@@ -74,12 +74,35 @@ export class DataUploadService {
       gender: this.getGenderEnumType(mrzFields.sex),
       number: mrzFields.documentNumber,
       country: mrzFields.issuingState,
+      // Raw ICAO nationality (for the MASAK 4/C(3) risky-country block and the
+      // server chip↔VIZ nationality comparison).
+      nationality: mrzFields.nationality,
       barcodeValue: scannedDocument.barcodeValue,
       personalNumber: mrzFields.personalNumber || mrzFields.optional1,
       birthDate: mrzUtils.convertMRZDateToISODate(mrzFields.birthDate),
       expiryDate: mrzUtils.convertMRZDateToISODate(mrzFields.expirationDate),
       dataSource: scannedDocument.dataSource,
       mrzText: scannedDocument.mrzText,
+      // Chip↔VIZ match (MASAK 4/C(1)(b)). Send the client verdict (advisory)
+      // plus the printed/VIZ MRZ comparison fields so the server can
+      // independently re-derive the authoritative verdict. Recorded for every
+      // EID scan as a security signal; absent on non-EID submissions.
+      chipVizMatch: scannedDocument.chipVizMatch,
+      vizMrz: scannedDocument.vizMrzFields
+        ? {
+            number: scannedDocument.vizMrzFields.documentNumber,
+            birthDate: mrzUtils.convertMRZDateToISODate(
+              scannedDocument.vizMrzFields.birthDate
+            ),
+            expiryDate: mrzUtils.convertMRZDateToISODate(
+              scannedDocument.vizMrzFields.expirationDate
+            ),
+            nationality: scannedDocument.vizMrzFields.nationality,
+            gender: this.getGenderEnumType(scannedDocument.vizMrzFields.sex),
+            name: scannedDocument.vizMrzFields.firstName,
+            surname: scannedDocument.vizMrzFields.lastName,
+          }
+        : undefined,
     };
 
     debugLog(

package/src/Shared/Types/documentData.ts

@@ -49,4 +49,12 @@ export interface DocumentData {
    * Null if the document does not encode it.
    */
   dateOfExpiry: string | null;
+
+  /**
+   * Holder's permanent address as read from the chip's DG11 (NFC path only),
+   * normalized to a comma-separated line. Null when the chip does not provide
+   * it (most passports) or on the OCR path. Used to pre-fill the address step
+   * (MASAK 4/C(1)(d)).
+   */
+  address?: string | null;
 }

package/src/Shared/Types/documentReadResult.ts

@@ -1,4 +1,5 @@
 import type { DocumentData } from './documentData';
+import type { ChipVizMatchResult } from '../Libs/chipVizMatch';
 
 /**
  * How the display name was derived from the raw MRZ ASCII name.
@@ -44,4 +45,23 @@ export interface DocumentReadResult {
    * face image was successfully obtained.
    */
   face?: DocumentFaceImage;
+  /**
+   * Result of comparing this chip read against a prior camera-OCR (printed/VIZ)
+   * read, when one is available. Present only on the NFC path in the
+   * MASAK 4/C remote-passport flow. The client verdict is advisory — the server
+   * re-derives the authoritative verdict from the uploaded fields.
+   */
+  chipVizMatch?: ChipVizMatchResult;
+  /**
+   * Passive Authentication result (ICAO 9303-11 §5.1), present only on the NFC
+   * path when the eID step enabled passiveAuth. `integrityStatus` is the
+   * on-device DG-hash check (MATCH/TAMPERED/INCOMPLETE); full signature + CSCA
+   * verification is performed server-side from the SOD.
+   */
+  passiveAuth?: {
+    integrityStatus: 'MATCH' | 'TAMPERED' | 'INCOMPLETE' | null;
+    /** Raw EF.SOD (base64) for server-side signature + CSCA chaining. */
+    sodBase64?: string | null;
+    error?: string;
+  };
 }