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

package/src/emrtd/read.ts

@@ -0,0 +1,224 @@
+import { Platform } from 'react-native';
+
+import { nativeModule } from './native';
+import { readChip, type EmrtdReadResult, EmrtdSessionError } from './session';
+import {
+  MAX_CHIP_ATTEMPTS,
+  chipRetryDelayMs,
+  isRetryableChipError,
+  isRetryableStartError,
+} from './retry';
+import { nfcSheetMessage, type NfcReadStage } from './stages';
+import type { MrzKeyFields } from './crypto';
+
+// ---------------------------------------------------------------------------
+// The read loop: open the session, run BAC with the MRZ key, read the files,
+// close the session — and when the chip drops, do the whole thing again.
+//
+// A dropped session is retried by opening a NEW one, because that is the only
+// recovery there is: iOS tears the session down and secure messaging dies with
+// it — the BAC-derived keys and the send-sequence counter cannot outlive the
+// session, so there is nothing to resume into.
+//
+// The session is ALWAYS closed, including on failure — a session left open
+// holds iOS's NFC sheet on screen over a flow that has already moved on, and
+// on Android keeps reader mode attached to a dead activity.
+//
+// Nothing here concludes that a chip is genuine. The files go to the server,
+// which hashes DG1 against the signed security object and checks the document
+// signer's signature. A client-side "authentic" flag would be a claim an
+// attacker controls.
+// ---------------------------------------------------------------------------
+
+export interface ChipReadOptions {
+  /** Shown in iOS's system NFC sheet. Android has none and ignores it. */
+  alertMessage?: string;
+  /** Shown when the read finishes, on iOS. */
+  successMessage?: string;
+  /** Read progress, so the UI can narrate an otherwise invisible operation. */
+  onStage?: (stage: NfcReadStage) => void;
+}
+
+/**
+ * Read generation. Each read claims a fresh value; `cancelChipRead` (and any
+ * newer read) bumps it, and a loop that wakes from its between-attempt sleep
+ * to find the world has moved on stops INSTEAD of reopening a session over
+ * whatever screen the user is on now. Closing the current session alone cannot
+ * do that — the loop's whole job is to open another one.
+ */
+let generation = 0;
+
+/**
+ * Abandon a read that is still in progress.
+ *
+ * Necessary because opening the session BLOCKS until a document is presented —
+ * on Android for up to a minute. A user who leaves the step during that wait
+ * cannot be rescued by `readPassportChip`'s own cleanup: that runs in the catch
+ * around `readChip`, which is never reached while the session is still waiting
+ * for a tap. Without this, reader mode stays attached to an activity the flow
+ * has already left, and on iOS the system sheet sits over the next screen.
+ *
+ * Safe to call when nothing is running — closing an already-closed session is a
+ * no-op, so callers do not have to track whether a read is live.
+ */
+export async function cancelChipRead(): Promise<void> {
+  generation += 1;
+  const native = nativeModule();
+  if (!native) return;
+  try {
+    await native.stopSession('Cancelled');
+  } catch {
+    // Nothing to cancel, or the session had already gone. Either way there is
+    // nothing left to clean up and nobody to report it to.
+  }
+}
+
+export async function readPassportChip(
+  mrz: MrzKeyFields,
+  options: ChipReadOptions = {},
+): Promise<EmrtdReadResult> {
+  const native = nativeModule();
+  if (!native) {
+    throw new EmrtdSessionError('This build cannot read NFC chips.', 'transport');
+  }
+
+  const run = ++generation;
+  const abandoned = (): boolean => generation !== run;
+  const settle = (): Promise<void> =>
+    new Promise((resolve) => setTimeout(resolve, chipRetryDelayMs(Platform.OS)));
+
+  // The stage the read died at is the single most diagnostic fact a failure
+  // carries — 'waiting' is a session/detection problem, 'authenticating' is
+  // SELECT/BAC (first contact), the read stages are a mid-transfer drop — so
+  // it is tracked here and logged with the RAW platform error per attempt.
+  // The same wrapper narrates the iOS system sheet, which COVERS the app
+  // during the read: without it the sheet sits on its opening line while
+  // three files transfer, and the silence reads as a hang (Flutter updates
+  // its sheet per stage; this is that, for RN).
+  let lastStage: NfcReadStage = 'waiting';
+  const onStage = (stage: NfcReadStage): void => {
+    lastStage = stage;
+    if (stage !== 'waiting' && stage !== 'done') {
+      try {
+        // Older installed builds predate this native method — narration is a
+        // courtesy, never a reason to fail a read.
+        void native.updateSessionMessage(nfcSheetMessage(stage)).catch(() => undefined);
+      } catch {
+        // Method absent on this build.
+      }
+    }
+    options.onStage?.(stage);
+  };
+
+  // A read that got DG1 but not the SOD is usable yet WORTH RETRYING: without
+  // the security object the server cannot verify the chip against the issuer,
+  // and the portrait is never fetched. Bank the partial and spend remaining
+  // attempts going for the complete read — settle for the partial only when
+  // the budget is exhausted.
+  let partial: EmrtdReadResult | null = null;
+
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= MAX_CHIP_ATTEMPTS; attempt += 1) {
+    try {
+      // A completeness retry re-presents the sheet moments after it closed on
+      // what looked like a finished read — without an explanation, the natural
+      // move is to take the document away, which forfeits the retry.
+      await native.startSession(
+        partial
+          ? 'Almost done — keep the document against your phone to finish'
+          : options.alertMessage ?? 'Hold your phone near the passport',
+      );
+    } catch (err) {
+      // Opening can be refused TRANSIENTLY: iOS reports an immediate
+      // `Code=202` for a session begun while the previous sheet is still
+      // dismissing — the very failure this loop exists to recover from, and
+      // exactly what a reopen straight after a drop runs into. Those get the
+      // settle-and-retry treatment like any other drop; a refusal another
+      // attempt cannot change (cancelled sheet, no document presented, no
+      // radio) is reported as-is.
+      lastError = err;
+      devLog(attempt, 'session-open', err);
+      // startSession can fail AFTER arming the radio (Android enables reader
+      // mode before discovery/connect can still throw), so the session must be
+      // torn down on this path too — or reader mode outlives the attempt,
+      // attached to the activity with a dead callback.
+      await native.stopSession('').catch(() => undefined);
+      if (attempt >= MAX_CHIP_ATTEMPTS || !isRetryableStartError(err)) throw err;
+      await settle();
+      if (abandoned()) throw cancelledError();
+      continue;
+    }
+
+    try {
+      onStage('waiting');
+      const result = await readChip(native, mrz, onStage);
+      if (!result.sod && attempt < MAX_CHIP_ATTEMPTS && !abandoned()) {
+        partial = result;
+        devLog(attempt, 'security-file', new Error('EF.SOD missing — retrying for a complete read'));
+        await native.stopSession('').catch(() => undefined);
+        onStage('waiting');
+        await settle();
+        if (abandoned()) throw cancelledError();
+        continue;
+      }
+      await native.stopSession(options.successMessage ?? 'Passport read');
+      return result;
+    } catch (err) {
+      lastError = err;
+      devLog(attempt, lastStage, err);
+      const willRetry = attempt < MAX_CHIP_ATTEMPTS && isRetryableChipError(err) && !abandoned();
+      // Between attempts the sheet is dismissed QUIETLY — painting it with an
+      // error the next attempt may erase reads as a crash mid-recovery. The
+      // message is reserved for the terminal failure, where it is the user's
+      // only feedback on iOS (the system sheet covers the app) — unless a
+      // banked partial makes this a success after all.
+      await native
+        .stopSession(
+          willRetry || partial
+            ? ''
+            : err instanceof EmrtdSessionError
+              ? err.message
+              : 'Could not read the chip',
+        )
+        .catch(() => undefined);
+
+      if (!willRetry) {
+        // A banked DG1-only read beats surfacing an error: the user already
+        // saw their data come off the chip once this run.
+        if (partial) return partial;
+        throw err;
+      }
+
+      // Back to the start: the next attempt re-runs BAC from scratch, which is
+      // what a new session requires. The pause lets iOS finish dismissing the
+      // sheet and the user reseat the document.
+      onStage('waiting');
+      await settle();
+      if (abandoned()) throw cancelledError();
+    }
+  }
+
+  // The attempt budget ran out — a banked partial is still a read.
+  if (partial) return partial;
+  // Unreachable — the loop either returns or throws — but it keeps the function
+  // honest about always producing a result.
+  throw lastError ?? new EmrtdSessionError('Could not read the chip.', 'transport');
+}
+
+/** The read was abandoned mid-loop (step left, or a newer read superseded it). */
+function cancelledError(): EmrtdSessionError {
+  return new EmrtdSessionError('The chip read was cancelled.', 'transport');
+}
+
+/**
+ * Per-attempt failure diagnostics, dev builds only.
+ *
+ * The friendly on-screen message deliberately hides the platform error, which
+ * makes field debugging impossible without this line: the STAGE names where in
+ * the protocol the read died, and the raw string names why.
+ */
+function devLog(attempt: number, stage: string, err: unknown): void {
+  if (typeof __DEV__ === 'undefined' || !__DEV__) return;
+  const raw = err instanceof Error ? err.message : String(err ?? '');
+  console.log(`[myaza] nfc attempt ${attempt} failed at '${stage}': ${raw}`);
+}

package/src/emrtd/retry.ts

@@ -0,0 +1,98 @@
+import { EmrtdSessionError } from './session';
+
+// ---------------------------------------------------------------------------
+// Which chip-read failures are worth another session.
+//
+// A dropped session is NOT recoverable in place. iOS tears the whole thing down
+// (`NFCError 202`), so there is no session left to retry an APDU into — and
+// secure messaging cannot survive it either, because the session keys and the
+// send-sequence counter are established by BAC and die with it. The only
+// recovery is a NEW session from the top, which is why this is a decision about
+// restarting rather than about resending.
+//
+// Restarting is the right default because the usual cause is physical: the chip
+// sits in the cover or centre spread of a booklet, and a few millimetres of
+// movement breaks the link. The user has not done anything wrong and the
+// document is fine — asking them to press a button to try what we could simply
+// try again is friction for its own sake.
+//
+// What must NOT be retried is anything a second attempt cannot change:
+//   • the user cancelling — they meant it, and reopening the sheet fights them;
+//   • BAC failing — the MRZ is check-digit validated before it is used as a
+//     key, so a mismatch means this chip belongs to a different document. A
+//     retry produces the same failure and wastes the user's time twice.
+// ---------------------------------------------------------------------------
+
+/** Total session attempts, including the first. */
+export const MAX_CHIP_ATTEMPTS = 3;
+
+/**
+ * Pause before reopening the session, per platform.
+ *
+ * iOS: the system sheet takes well over a second to animate away after
+ * `invalidate()`, and a new `NFCTagReaderSession` begun while it is still
+ * dismissing is refused with an immediate `Code=202 "Session invalidated
+ * unexpectedly"` — the very error the retry exists to recover from. The
+ * previous 700ms sat inside that window, so the recovery attempt died before
+ * its sheet ever appeared and the user was shown the 202 message for a blip
+ * that was entirely recoverable. The pause also gives them time to reseat the
+ * document — the thing most likely to make the next attempt succeed.
+ *
+ * Android has no sheet to dismiss; it only needs the reseat beat.
+ */
+export function chipRetryDelayMs(os: string): number {
+  return os === 'ios' ? 2200 : 700;
+}
+
+/**
+ * iOS session-level `NFCReaderError` codes that justify another session.
+ * 200 (user cancelled) is deliberately absent.
+ */
+const RETRYABLE_IOS_SESSION = /Code=(201|202|203)\b/;
+
+/**
+ * iOS transceive-level codes — how a physical drop surfaces while a command is
+ * IN FLIGHT: 100 tag connection lost, 101 retry exceeded, 102 tag response
+ * error, 103 session invalidated, 104 tag not connected. During SELECT and BAC
+ * — the first seconds of contact, where most drops happen — these arrive RAW,
+ * because nothing has wrapped them in an EmrtdSessionError yet. 105 (packet too
+ * long) is deliberately absent: that is a protocol bug, and a new session
+ * reproduces it exactly.
+ */
+const RETRYABLE_IOS_TRANSCEIVE = /Code=(10[0-4])\b/;
+
+/** Android's IsoDep raises `TagLostException("Tag was lost.")` on a drop. */
+const RETRYABLE_ANDROID = /tag was lost/i;
+
+/** Whether a failed chip read is worth reopening the session for. */
+export function isRetryableChipError(err: unknown): boolean {
+  if (err instanceof EmrtdSessionError) {
+    // A chip that stopped answering mid-read is the physical case: the document
+    // moved. `bac_failed` and `select_failed` are about WHICH document this is,
+    // and a new session cannot change that.
+    return err.code === 'read_failed' || err.code === 'transport';
+  }
+  const raw = err instanceof Error ? err.message : String(err ?? '');
+  return (
+    RETRYABLE_IOS_SESSION.test(raw) ||
+    RETRYABLE_IOS_TRANSCEIVE.test(raw) ||
+    RETRYABLE_ANDROID.test(raw)
+  );
+}
+
+/**
+ * Whether a failure to OPEN a session is worth another try.
+ *
+ * Narrower than the mid-read set, because here the codes mean different
+ * things: 202 is the radio refusing a session while the previous sheet is
+ * still tearing down, and 203 is the radio busy elsewhere — both are states
+ * that pass on their own. 201 means the user never presented a document in the
+ * whole wait, and 200 that they dismissed the sheet; reopening it fights them.
+ */
+export function isRetryableStartError(err: unknown): boolean {
+  const raw = err instanceof Error ? err.message : String(err ?? '');
+  // Android: a drop between discovery and connect() surfaces here as
+  // TagLostException. Without this arm every Android start failure was
+  // terminal — the 3-attempt budget only ever applied to iOS.
+  return /Code=(202|203)\b/.test(raw) || RETRYABLE_ANDROID.test(raw);
+}

package/src/emrtd/secureMessaging.ts

@@ -0,0 +1,178 @@
+import { concat, padToBlock, timingSafeEqual, unpadFromBlock } from './bytes';
+import { encodeTlv, readTlvSequence } from './der';
+import {
+  BLOCK_SIZE,
+  decrypt3Des,
+  encrypt3Des,
+  macWithPadding,
+  type EmrtdPrimitives,
+  type SessionKeys,
+} from './crypto';
+
+// ---------------------------------------------------------------------------
+// Secure messaging (ICAO 9303 Part 11 §9.8).
+//
+// After BAC every command and response is wrapped: the data encrypted under
+// KSenc, the whole thing MACed under KSmac, and a send-sequence counter mixed
+// in so neither side can replay a message from earlier in the session.
+//
+// The SSC is the part that is easy to get subtly wrong. It is incremented
+// BEFORE each command and again BEFORE checking the response, so one command
+// consumes two values. Getting that out of step produces a MAC failure on the
+// second command of a session — which looks like a wrong key rather than an
+// off-by-one, and is why it is centralised here in one small object.
+// ---------------------------------------------------------------------------
+
+const DO87 = 0x87; // Encrypted data, with a padding-content indicator
+const DO85 = 0x85; // Encrypted data, no indicator (some chips use this)
+const DO97 = 0x97; // Expected response length
+const DO99 = 0x99; // Processing status (SW1 SW2)
+const DO8E = 0x8e; // Cryptographic checksum
+
+export class SecureMessagingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SecureMessagingError';
+    Object.setPrototypeOf(this, SecureMessagingError.prototype);
+  }
+}
+
+/** An APDU, before wrapping. */
+export interface CommandApdu {
+  cla: number;
+  ins: number;
+  p1: number;
+  p2: number;
+  data?: Uint8Array;
+  /** Expected response length. Undefined means the command expects none. */
+  le?: number;
+}
+
+/**
+ * A secure-messaging session: the keys plus the counter.
+ *
+ * Stateful ON PURPOSE — the SSC has to advance in lockstep with the exchange,
+ * and threading it through every call site is how it drifts.
+ */
+export class SecureMessagingSession {
+  private ssc: Uint8Array;
+
+  constructor(
+    private readonly p: EmrtdPrimitives,
+    private readonly keys: SessionKeys,
+    initialSsc: Uint8Array,
+  ) {
+    this.ssc = new Uint8Array(initialSsc);
+  }
+
+  /** Increment the counter as a big-endian integer, with wraparound. */
+  private incrementSsc(): void {
+    for (let i = this.ssc.length - 1; i >= 0; i--) {
+      this.ssc[i] = (this.ssc[i]! + 1) & 0xff;
+      if (this.ssc[i] !== 0) break;
+    }
+  }
+
+  /** Wrap a command for transmission. Consumes one SSC value. */
+  protect(apdu: CommandApdu): Uint8Array {
+    this.incrementSsc();
+
+    // The class byte gains the secure-messaging bits, and the MAC is computed
+    // over the PADDED header — a detail the standard is easy to misread.
+    const cla = apdu.cla | 0x0c;
+    const header = padToBlock(
+      new Uint8Array([cla, apdu.ins, apdu.p1, apdu.p2]),
+      BLOCK_SIZE,
+    );
+
+    const parts: Uint8Array[] = [];
+
+    if (apdu.data && apdu.data.length > 0) {
+      const encrypted = encrypt3Des(this.p, this.keys.ksEnc, padToBlock(apdu.data, BLOCK_SIZE));
+      // The leading 0x01 is the padding-content indicator: "ISO 9797-1 method
+      // 2 was used". Omitting it is a common source of chips rejecting DO'87'.
+      parts.push(encodeTlv(DO87, concat(new Uint8Array([0x01]), encrypted)));
+    }
+
+    if (apdu.le !== undefined) {
+      const le =
+        apdu.le > 0xff
+          ? new Uint8Array([(apdu.le >> 8) & 0xff, apdu.le & 0xff])
+          : new Uint8Array([apdu.le & 0xff]);
+      parts.push(encodeTlv(DO97, le));
+    }
+
+    const body = concat(...parts);
+    const mac = macWithPadding(this.p, this.keys.ksMac, concat(this.ssc, header, body));
+    const checksum = encodeTlv(DO8E, mac);
+
+    const payload = concat(body, checksum);
+    // Le of 0x00 asks for the maximum: the wrapped response is longer than the
+    // wrapped command, and a short Le silently truncates it.
+    return concat(
+      new Uint8Array([cla, apdu.ins, apdu.p1, apdu.p2, payload.length]),
+      payload,
+      new Uint8Array([0x00]),
+    );
+  }
+
+  /**
+   * Unwrap a response. Consumes one SSC value.
+   *
+   * Throws when the checksum is absent or does not verify — an unauthenticated
+   * response is not data, it is whatever the channel decided to hand back.
+   */
+  unprotect(response: Uint8Array): { data: Uint8Array; statusWord: number } {
+    this.incrementSsc();
+
+    const parsed = readTlvSequence(response);
+    const checksumIndex = parsed.findIndex((o) => o.tag === DO8E);
+    if (checksumIndex < 0) throw new SecureMessagingError('The response carried no checksum.');
+    const checksum = parsed[checksumIndex]!;
+
+    // The MAC covers the objects BEFORE DO'8E' — everything after it is outside
+    // the protected data. Taking a prefix rather than filtering matters: a
+    // response that still carries its outer status word parses `9000` as a
+    // perfectly valid empty TLV, and folding that into the MAC fails every
+    // verification for a reason nothing about the message reveals.
+    const objects = parsed.slice(0, checksumIndex);
+    const macInput = concat(
+      this.ssc,
+      ...objects.map((o) => encodeTlv(o.tag, o.value)),
+    );
+    const expected = macWithPadding(this.p, this.keys.ksMac, macInput);
+    if (!timingSafeEqual(expected, checksum.value)) {
+      throw new SecureMessagingError('The response failed its integrity check.');
+    }
+
+    const statusObject = objects.find((o) => o.tag === DO99);
+    // The status comes from DO'99', NOT from the outer status word. A chip can
+    // return 0x9000 on the wrapper while reporting a failure inside — reading
+    // the outer word treats that as success.
+    const statusWord =
+      statusObject && statusObject.value.length >= 2
+        ? (statusObject.value[0]! << 8) | statusObject.value[1]!
+        : 0x0000;
+
+    const encrypted = objects.find((o) => o.tag === DO87 || o.tag === DO85);
+    if (!encrypted) return { data: new Uint8Array(0), statusWord };
+
+    // DO'87' carries the padding-content indicator as its first byte; DO'85'
+    // does not.
+    const body =
+      encrypted.tag === DO87 ? encrypted.value.subarray(1) : encrypted.value;
+    if (body.length === 0 || body.length % BLOCK_SIZE !== 0) {
+      throw new SecureMessagingError('The response ciphertext was misaligned.');
+    }
+
+    return {
+      data: unpadFromBlock(decrypt3Des(this.p, this.keys.ksEnc, body), BLOCK_SIZE),
+      statusWord,
+    };
+  }
+
+  /** The current counter — for diagnostics and tests only. */
+  get sendSequenceCounter(): Uint8Array {
+    return new Uint8Array(this.ssc);
+  }
+}