@myazahq/kyc-sdk-react-native 2.0.2 → 2.1.0

package/src/emrtd/dg2.ts

@@ -0,0 +1,111 @@
+import { fromBase64, toBase64 } from './bytes';
+
+// ---------------------------------------------------------------------------
+// The chip's portrait (DG2).
+//
+// DG2 is a CBEFF container, not an image file: the picture sits somewhere
+// inside a biometric header, and the only dependable way to find it is to scan
+// for the image's own magic bytes. That is what this does.
+//
+// Two encodings occur in practice, and the difference decides whether anything
+// can be shown at all:
+//
+//   • JPEG (FF D8 FF) — renders anywhere, so it becomes a data URI.
+//   • JPEG 2000 (JP2 / raw J2K codestream) — the COMMON case on passports, and
+//     React Native cannot decode it. There is no shame in that: the read still
+//     stands, the bytes still go to the server, and the panel simply shows the
+//     generic success mark instead of a face.
+//
+// So a missing preview is NEVER an error. The portrait is a confirmation for
+// the user, not evidence — the server is what verifies DG2 against the signed
+// security object.
+// ---------------------------------------------------------------------------
+
+export type PortraitFormat = 'jpeg' | 'jp2' | 'unknown';
+
+export interface ChipPortrait {
+  format: PortraitFormat;
+  /** A `data:` URI, only when the format is one RN can actually render. */
+  dataUri: string | null;
+  /**
+   * The IMAGE bytes, base64, sliced out of the CBEFF container — for handing to
+   * a platform decoder when RN cannot render the format itself.
+   *
+   * This is not the same as the DG2 blob. DG2 is a biometric container with a
+   * header in front of the picture; passing the whole thing to an image decoder
+   * asks it to recognise a file format that is not there, and it will decline.
+   * The offset is already known here, so the slice is free.
+   */
+  imageBase64: string | null;
+}
+
+const JPEG_MAGIC = [0xff, 0xd8, 0xff];
+// JP2 container: the 12-byte signature box.
+const JP2_MAGIC = [0x00, 0x00, 0x00, 0x0c, 0x6a, 0x50, 0x20, 0x20];
+// Raw JPEG 2000 codestream (SOC + SIZ), which some chips store unwrapped.
+const J2K_MAGIC = [0xff, 0x4f, 0xff, 0x51];
+
+function indexOfBytes(haystack: Uint8Array, needle: number[], from = 0): number {
+  outer: for (let i = from; i <= haystack.length - needle.length; i += 1) {
+    for (let j = 0; j < needle.length; j += 1) {
+      if (haystack[i + j] !== needle[j]) continue outer;
+    }
+    return i;
+  }
+  return -1;
+}
+
+/**
+ * Find the portrait inside a DG2 elementary file.
+ *
+ * Scanning for magic bytes rather than walking the CBEFF/BIT structure is
+ * deliberate: the header layout varies between issuers, and a parser that is
+ * wrong about one of them returns nothing, while the magic bytes are fixed by
+ * the image formats themselves.
+ */
+export function extractChipPortrait(dg2Base64: string | undefined): ChipPortrait {
+  if (!dg2Base64) return { format: 'unknown', dataUri: null, imageBase64: null };
+
+  let bytes: Uint8Array;
+  try {
+    bytes = fromBase64(dg2Base64);
+  } catch {
+    return { format: 'unknown', dataUri: null, imageBase64: null };
+  }
+
+  // EARLIEST signature wins, exactly like the Flutter SDK. Checking formats in
+  // preference order instead was subtly wrong: 20KB of compressed JPEG 2000
+  // wavelet data can contain a spurious `FF D8 FF` by chance, and preferring
+  // JPEG meant slicing at that garbage offset — producing a "jpeg" data URI
+  // that renders as nothing, while the real, decodable JP2 header sat earlier
+  // in the file, never consulted. The image's true start is the FIRST magic in
+  // the container.
+  const candidates: Array<[PortraitFormat, number[]]> = [
+    ['jpeg', JPEG_MAGIC],
+    ['jp2', JP2_MAGIC],
+    ['jp2', J2K_MAGIC],
+  ];
+  let format: PortraitFormat = 'unknown';
+  let at = -1;
+  for (const [candidate, magic] of candidates) {
+    const index = indexOfBytes(bytes, magic);
+    if (index >= 0 && (at < 0 || index < at)) {
+      at = index;
+      format = candidate;
+    }
+  }
+
+  if (at < 0) return { format: 'unknown', dataUri: null, imageBase64: null };
+
+  // Sliced from the magic bytes onward: a renderer or platform decoder needs
+  // the image FILE, not the biometric container it is wrapped in.
+  const imageBase64 = toBase64(bytes.subarray(at));
+  return {
+    format,
+    // Only baseline JPEG renders directly in RN; JP2 is reported honestly so a
+    // caller can hand it to the platform decoder — and so "no preview" is
+    // distinguishable from a DG2 that failed to parse at all.
+    dataUri: format === 'jpeg' ? `data:image/jpeg;base64,${imageBase64}` : null,
+    imageBase64,
+  };
+}

package/src/emrtd/files.ts

@@ -0,0 +1,215 @@
+import { concat } from './bytes';
+import { readTlvHeader } from './der';
+import type { SecureMessagingSession } from './secureMessaging';
+
+// ---------------------------------------------------------------------------
+// Reading elementary files off the chip.
+//
+// SELECT the file, read its TLV header to learn the length, then READ BINARY in
+// chunks. Three details make the difference between this working on one
+// passport and working on all of them:
+//
+//   • The READ LENGTH IS ADAPTIVE. Chips disagree about how much they will
+//     return in one go, and one that is asked for too much answers 0x6CXX with
+//     the length it WILL accept. Starting optimistic and stepping down on
+//     refusal reads a 30KB DG2 in a fraction of the round trips a conservative
+//     fixed size would need.
+//   • Offsets past 0x7FFF do not fit the short READ BINARY form, so DG2 —
+//     which routinely exceeds 32KB — needs the extended form with the offset in
+//     the command data. Masking it into the short form instead reads the WRONG
+//     BYTES and silently returns a corrupt portrait.
+//   • The status comes from inside secure messaging, not the outer word.
+// ---------------------------------------------------------------------------
+
+/** Elementary file identifiers. */
+export const EF = {
+  COM: 0x011e,
+  DG1: 0x0101,
+  DG2: 0x0102,
+  SOD: 0x011d,
+} as const;
+
+const SW_OK = 0x9000;
+/** "Wrong length — use this one instead", with the acceptable length in SW2. */
+const SW_WRONG_LE = 0x6c00;
+/** Some chips report end-of-file this way rather than returning fewer bytes. */
+const SW_EOF = 0x6282;
+/** "Part of the returned data may be corrupted" — a warning that carries data. */
+const SW_CORRUPT_WARNING = 0x6281;
+
+/**
+ * Status words whose response still carries usable data. `61XX` ("more bytes
+ * available") and the corruption warning were being ladder-stepped like hard
+ * errors, discarding data the chip HAD returned — the Flutter reader accepts
+ * both, and chips that answer this way exist.
+ */
+function carriesData(statusWord: number): boolean {
+  return (
+    statusWord === SW_OK ||
+    statusWord === SW_EOF ||
+    statusWord === SW_CORRUPT_WARNING ||
+    (statusWord & 0xff00) === 0x6100
+  );
+}
+
+/**
+ * Chunk sizes to try, largest first.
+ *
+ * The ladder exists because chips do not agree and do not advertise: the only
+ * way to find the limit is to ask and be told no.
+ */
+const READ_LADDER = [224, 160, 128, 96, 64, 32, 16, 8, 1];
+const DEFAULT_READ = 112;
+
+export class EmrtdFileError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'EmrtdFileError';
+    Object.setPrototypeOf(this, EmrtdFileError.prototype);
+  }
+}
+
+/** Sends one wrapped APDU and returns the unwrapped answer. */
+export type Transceive = (command: Uint8Array) => Promise<Uint8Array>;
+
+async function send(
+  sm: SecureMessagingSession,
+  transceive: Transceive,
+  apdu: Parameters<SecureMessagingSession['protect']>[0],
+): Promise<{ data: Uint8Array; statusWord: number }> {
+  return sm.unprotect(await transceive(sm.protect(apdu)));
+}
+
+/** SELECT an elementary file by identifier. */
+export async function selectFile(
+  sm: SecureMessagingSession,
+  transceive: Transceive,
+  fileId: number,
+): Promise<void> {
+  const { statusWord } = await send(sm, transceive, {
+    cla: 0x00,
+    ins: 0xa4,
+    p1: 0x02,
+    p2: 0x0c,
+    data: new Uint8Array([(fileId >> 8) & 0xff, fileId & 0xff]),
+  });
+  if (statusWord !== SW_OK) {
+    throw new EmrtdFileError(
+      `The chip refused to select file ${fileId.toString(16)} (0x${statusWord.toString(16)}).`,
+    );
+  }
+}
+
+/** One READ BINARY at an offset, using whichever command form the offset needs. */
+async function readAt(
+  sm: SecureMessagingSession,
+  transceive: Transceive,
+  offset: number,
+  length: number,
+): Promise<{ data: Uint8Array; statusWord: number }> {
+  if (offset < 0x8000) {
+    return send(sm, transceive, {
+      cla: 0x00,
+      ins: 0xb0,
+      p1: (offset >> 8) & 0x7f,
+      p2: offset & 0xff,
+      le: length,
+    });
+  }
+
+  // Beyond 32KB the offset no longer fits the header, so it moves into the
+  // command data as a DO'54' — the extended form. Masking it into the short
+  // form would read from the wrong place and return a corrupt file.
+  return send(sm, transceive, {
+    cla: 0x00,
+    ins: 0xb1,
+    p1: 0x00,
+    p2: 0x00,
+    data: new Uint8Array([0x54, 0x02, (offset >> 8) & 0xff, offset & 0xff]),
+    le: length,
+  });
+}
+
+/**
+ * Read the currently-selected file in full.
+ *
+ * `expectedLength` comes from the file's own TLV header, read first.
+ */
+async function readSelected(
+  sm: SecureMessagingSession,
+  transceive: Transceive,
+  expectedLength: number,
+  alreadyRead: Uint8Array,
+): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [alreadyRead];
+  let offset = alreadyRead.length;
+  let chunkSize = DEFAULT_READ;
+
+  while (offset < expectedLength) {
+    const want = Math.min(chunkSize, expectedLength - offset);
+    const { data, statusWord } = await readAt(sm, transceive, offset, want);
+
+    if (statusWord === SW_WRONG_LE || (statusWord & 0xff00) === SW_WRONG_LE) {
+      // The chip named the length it will accept. Honour it exactly rather
+      // than guessing again.
+      const allowed = statusWord & 0x00ff;
+      if (allowed > 0) {
+        chunkSize = allowed;
+        continue;
+      }
+    }
+
+    if (!carriesData(statusWord)) {
+      // Step down the ladder and retry; a chip that will not answer at ANY
+      // size is a real failure, which the exhausted ladder reports below.
+      const next = READ_LADDER.find((n) => n < chunkSize);
+      if (next === undefined) {
+        throw new EmrtdFileError(
+          `The chip stopped responding at offset ${offset} (0x${statusWord.toString(16)}).`,
+        );
+      }
+      chunkSize = next;
+      continue;
+    }
+
+    if (data.length === 0) break; // End of file.
+    chunks.push(data);
+    offset += data.length;
+  }
+
+  return concat(...chunks);
+}
+
+/**
+ * Select and read an elementary file.
+ *
+ * The first read is small and deliberate: it fetches the TLV header, which
+ * carries the file's real length. Reading blind until the chip stops is slower
+ * and, on chips that pad, returns trailing rubbish.
+ */
+export async function readFile(
+  sm: SecureMessagingSession,
+  transceive: Transceive,
+  fileId: number,
+): Promise<Uint8Array> {
+  await selectFile(sm, transceive, fileId);
+
+  // Four bytes is enough for a tag plus a long-form length of up to 0xFFFF.
+  const head = await readAt(sm, transceive, 0, 4);
+  if (!carriesData(head.statusWord)) {
+    throw new EmrtdFileError(
+      `The chip refused to read file ${fileId.toString(16)} (0x${head.statusWord.toString(16)}).`,
+    );
+  }
+  if (head.data.length === 0) return new Uint8Array(0);
+
+  // The header names the file's true size. A header that does not parse from
+  // four bytes is not a failure — the length field can extend past them — so
+  // the fallback reads until the chip stops, which is slower but never wrong.
+  const header = readTlvHeader(head.data);
+  const expected = header
+    ? header.headerLength + header.valueLength
+    : Number.MAX_SAFE_INTEGER;
+
+  return readSelected(sm, transceive, expected, head.data);
+}

package/src/emrtd/index.ts

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// The eMRTD engine's public surface.
+//
+// Barrel-only by design (the docbio rule): nothing outside this directory
+// reaches into the protocol internals. What escapes is a single call that takes
+// the MRZ fields and returns the chip's files, plus the availability check the
+// step order needs.
+//
+// A build without the native module leaves everything unavailable and the chip
+// step skips — the same null-degrade posture the rest of the platform uses for
+// optional native capabilities.
+//
+// Layout: native.ts resolves the Nitro module and answers capability
+// questions; read.ts owns the session/retry loop; session.ts downward is the
+// protocol itself (BAC, secure messaging, file reads), tested against ICAO
+// 9303's worked examples in CI.
+// ---------------------------------------------------------------------------
+
+export type { EmrtdReadResult } from './session';
+export { EmrtdSessionError } from './session';
+export type { MrzKeyFields } from './crypto';
+export type { NfcReadStage } from './stages';
+export {
+  NFC_STAGE_ORDER,
+  nfcStageDetail,
+  nfcStageLabel,
+  nfcStageProgress,
+} from './stages';
+export { decodeChipImage, isNfcAvailable, nfcUnavailableReason } from './native';
+export { cancelChipRead, readPassportChip, type ChipReadOptions } from './read';

package/src/emrtd/mrzKey.ts

@@ -0,0 +1,54 @@
+import { fromAscii } from './bytes';
+import type { EmrtdPrimitives } from './crypto';
+
+// ---------------------------------------------------------------------------
+// The BAC key, derived from the printed MRZ.
+//
+// This is what makes Basic Access Control work at all: the chip will only talk
+// to someone who has physically seen the document, because the key comes from
+// the strip printed on it.
+//
+// Split from crypto.ts (200-line rule) because it is the one part that is about
+// the DOCUMENT rather than the ciphers.
+// ---------------------------------------------------------------------------
+
+/** ICAO 7-3-1 weighted check digit over the MRZ alphabet. */
+function checkDigit(value: string): number {
+  const weights = [7, 3, 1];
+  let sum = 0;
+  for (let i = 0; i < value.length; i++) {
+    const ch = value.charCodeAt(i);
+    const v = ch >= 0x30 && ch <= 0x39 ? ch - 0x30 : ch >= 0x41 && ch <= 0x5a ? ch - 0x41 + 10 : 0;
+    sum += v * weights[i % 3]!;
+  }
+  return sum % 10;
+}
+
+export interface MrzKeyFields {
+  documentNumber: string;
+  /** YYMMDD, as it appears in the MRZ. */
+  dateOfBirth: string;
+  dateOfExpiry: string;
+}
+
+/**
+ * The MRZ information BAC hashes: document number, date of birth and expiry,
+ * each followed by its own check digit.
+ *
+ * The document number is filler-padded to nine characters FIRST, and the check
+ * digit is computed over the padded form — getting that order wrong yields a
+ * key the chip rejects with no explanation.
+ */
+export function mrzKeySeedInput(fields: MrzKeyFields): string {
+  const field = (v: string): string => `${v}${checkDigit(v)}`;
+  return (
+    field(fields.documentNumber.padEnd(9, '<')) +
+    field(fields.dateOfBirth) +
+    field(fields.dateOfExpiry)
+  );
+}
+
+/** Kseed: the first 16 bytes of SHA-1 over the MRZ information. */
+export function keySeed(p: EmrtdPrimitives, fields: MrzKeyFields): Uint8Array {
+  return p.sha1(fromAscii(mrzKeySeedInput(fields))).subarray(0, 16);
+}

package/src/emrtd/native.ts

@@ -0,0 +1,79 @@
+import { NitroModules } from 'react-native-nitro-modules';
+
+import type { MyazaEmrtd } from '../specs/MyazaEmrtd.nitro';
+
+// ---------------------------------------------------------------------------
+// Resolving the native eMRTD module, and the capability questions that only it
+// can answer. The read loop lives in read.ts; this file owns the registry
+// lookup so both have one source of truth for "is there a native side at all".
+// ---------------------------------------------------------------------------
+
+/**
+ * The native module, resolved LAZILY and re-tried until it appears.
+ *
+ * It used to be created at module load. That is fragile in a way that fails
+ * SILENTLY and permanently: if this module happens to evaluate before Nitro's
+ * registry is populated — which Fast Refresh causes routinely — the reference
+ * is null for the rest of the session, `isNfcAvailable()` reports false, and
+ * the chip step quietly skips itself. Nothing logs, and the flow looks like a
+ * device without an NFC radio.
+ *
+ * Resolving on demand costs one registry lookup and cannot get stuck.
+ */
+let cached: MyazaEmrtd | null = null;
+export function nativeModule(): MyazaEmrtd | null {
+  if (cached) return cached;
+  try {
+    if (!NitroModules.hasHybridObject('MyazaEmrtd')) return null;
+    cached = NitroModules.createHybridObject<MyazaEmrtd>('MyazaEmrtd');
+    return cached;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Why NFC is unavailable, when it is.
+ *
+ * Two very different failures both surface as "no NFC": the Nitro registry not
+ * having the object yet (a JS-side race, recoverable — a retry moments later
+ * succeeds), and the device/entitlement genuinely not supporting reads (final).
+ * Collapsing them into one boolean sent debugging to the wrong layer once
+ * already, so the distinction is reported.
+ */
+export function nfcUnavailableReason(): 'module_not_registered' | 'device_unsupported' | null {
+  try {
+    const mod = nativeModule();
+    if (!mod) return 'module_not_registered';
+    return mod.isAvailable() ? null : 'device_unsupported';
+  } catch {
+    return 'module_not_registered';
+  }
+}
+
+/**
+ * Decode an image the JS side cannot render, returning base64 JPEG.
+ *
+ * Used for JPEG 2000 chip portraits (DG2), which React Native has no decoder
+ * for. Null when the platform declines the format — the preview is a courtesy
+ * and the chip read stands without it.
+ */
+export async function decodeChipImage(dataBase64: string): Promise<string | null> {
+  try {
+    // The native side reports "could not decode" as an empty string; normalise
+    // it to null so callers have one absent value to check.
+    const jpeg = await nativeModule()?.decodeImage(dataBase64);
+    return jpeg ? jpeg : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether this build and device can read a chip at all. */
+export function isNfcAvailable(): boolean {
+  try {
+    return nativeModule()?.isAvailable() ?? false;
+  } catch {
+    return false;
+  }
+}

package/src/emrtd/optionalRead.ts

@@ -0,0 +1,42 @@
+import { readFile, type Transceive } from './files';
+import type { SecureMessagingSession } from './secureMessaging';
+
+// ---------------------------------------------------------------------------
+// Best-effort file reads (EF.SOD, DG2).
+//
+// These files are optional by CONTRACT — the read stands without them — but
+// they are not optional in VALUE: without the SOD the server cannot verify
+// DG1 against the issuer, and without DG2 there is no portrait. A transient
+// wobble a few chunks into a kilobyte transfer was costing both, silently:
+// one bare `.catch(() => null)` threw away the file AND the reason.
+//
+// So an optional read gets a second in-session attempt (the file is
+// re-selected from scratch, so a clean retry is protocol-safe — the
+// send-sequence counter advances per exchange either way), and every failure
+// is named in dev builds instead of vanishing.
+// ---------------------------------------------------------------------------
+
+/** In-session tries per optional file, including the first. */
+const OPTIONAL_READ_TRIES = 2;
+
+export async function readOptionalFile(
+  sm: SecureMessagingSession,
+  transceive: Transceive,
+  fileId: number,
+  name: string,
+): Promise<Uint8Array | null> {
+  for (let attempt = 1; attempt <= OPTIONAL_READ_TRIES; attempt += 1) {
+    try {
+      return await readFile(sm, transceive, fileId);
+    } catch (err) {
+      // A dead session fails the retry instantly, so trying again costs
+      // nothing when it cannot help — and saves the file when the failure was
+      // a single misread chunk.
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        const raw = err instanceof Error ? err.message : String(err ?? '');
+        console.log(`[myaza] nfc ${name} read failed (try ${attempt}/${OPTIONAL_READ_TRIES}): ${raw}`);
+      }
+    }
+  }
+  return null;
+}