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

package/src/emrtd/session.ts

@@ -0,0 +1,200 @@
+import { fromBase64, toBase64 } from './bytes';
+import { buildBacChallenge, completeBac } from './bac';
+import { primitivesFromNative, type EmrtdPrimitives, type MrzKeyFields } from './crypto';
+import { EF, readFile, type Transceive } from './files';
+import { readOptionalFile } from './optionalRead';
+import { SecureMessagingSession } from './secureMessaging';
+import type { NfcReadStage } from './stages';
+
+// ---------------------------------------------------------------------------
+// Reading a chip, end to end.
+//
+// Select the application, run BAC, then read the files. What comes back is
+// handed to the SERVER, which is where authenticity is decided: the server
+// hashes DG1 against the signed security object and checks the document
+// signer's signature. Nothing here may conclude that a chip is genuine — a
+// client-side "authentic" flag is a claim an attacker controls.
+//
+// So the job of this file is narrow and honest: get the bytes off the chip, and
+// report clearly when it could not.
+// ---------------------------------------------------------------------------
+
+/** The eMRTD application identifier — selected before anything else works. */
+const AID = new Uint8Array([0xa0, 0x00, 0x00, 0x02, 0x47, 0x10, 0x01]);
+
+const SW_OK = 0x9000;
+
+export class EmrtdSessionError extends Error {
+  constructor(
+    message: string,
+    /** A stable token the UI branches on, rather than matching prose. */
+    readonly code: 'select_failed' | 'bac_failed' | 'read_failed' | 'transport',
+  ) {
+    super(message);
+    this.name = 'EmrtdSessionError';
+    Object.setPrototypeOf(this, EmrtdSessionError.prototype);
+  }
+}
+
+/** What a successful read yields, all base64 for the submission. */
+export interface EmrtdReadResult {
+  /** DG1 — the MRZ as the chip stores it. Always present on success. */
+  dg1: string;
+  /** EF.SOD — the signed security object. The server needs it to verify DG1. */
+  sod?: string;
+  /** DG2 — the portrait. Best-effort; the largest file and the likeliest to drop. */
+  dg2?: string;
+  /** How the chip was unlocked. */
+  chipAuth: 'bac';
+}
+
+/** The raw transport, before secure messaging wraps it. */
+export interface EmrtdTransport {
+  /** Send an APDU, get data + status word back. */
+  transceive(apduBase64: string): Promise<{ data: string; statusWord: number }>;
+}
+
+/** SELECT the eMRTD application. Nothing else responds until this succeeds. */
+async function selectApplication(transport: EmrtdTransport): Promise<void> {
+  const apdu = new Uint8Array([0x00, 0xa4, 0x04, 0x0c, AID.length, ...AID]);
+  const { statusWord } = await transport.transceive(toBase64(apdu));
+  if (statusWord !== SW_OK) {
+    throw new EmrtdSessionError(
+      `The chip did not accept the passport application (0x${statusWord.toString(16)}).`,
+      'select_failed',
+    );
+  }
+}
+
+/** GET CHALLENGE — the chip's 8-byte nonce, which starts BAC. */
+async function getChallenge(transport: EmrtdTransport): Promise<Uint8Array> {
+  const { data, statusWord } = await transport.transceive(
+    toBase64(new Uint8Array([0x00, 0x84, 0x00, 0x00, 0x08])),
+  );
+  if (statusWord !== SW_OK) {
+    throw new EmrtdSessionError(
+      `The chip refused to issue a challenge (0x${statusWord.toString(16)}).`,
+      'bac_failed',
+    );
+  }
+  return fromBase64(data);
+}
+
+/**
+ * Run BAC and open a secure-messaging session.
+ *
+ * A failure here means the MRZ was read wrong, or the thing answering is not
+ * the document — NOT that the read should be retried with the same key.
+ */
+async function openSession(
+  p: EmrtdPrimitives,
+  transport: EmrtdTransport,
+  mrz: MrzKeyFields,
+): Promise<SecureMessagingSession> {
+  const rndIc = await getChallenge(transport);
+  const challenge = buildBacChallenge(p, mrz, rndIc);
+
+  const apdu = new Uint8Array([
+    0x00,
+    0x82,
+    0x00,
+    0x00,
+    challenge.command.length,
+    ...challenge.command,
+    0x28,
+  ]);
+  const { data, statusWord } = await transport.transceive(toBase64(apdu));
+  if (statusWord !== SW_OK) {
+    throw new EmrtdSessionError(
+      'The chip rejected the key derived from the document. Check the scanned details.',
+      'bac_failed',
+    );
+  }
+
+  const { keys, ssc } = completeBac(p, challenge, fromBase64(data));
+  return new SecureMessagingSession(p, keys, ssc);
+}
+
+/**
+ * Read the chip.
+ *
+ * DG1 is required — without the MRZ there is nothing to verify. EF.SOD and DG2
+ * are BEST-EFFORT and in that order: the SOD is what makes DG1 trustworthy, and
+ * DG2 is only worth reading if the SOD arrived, since an unverifiable portrait
+ * is one an attacker could have substituted.
+ */
+export async function readChip(
+  native: Parameters<typeof primitivesFromNative>[0] & EmrtdTransport,
+  mrz: MrzKeyFields,
+  /**
+   * Progress, so the UI can narrate a read that is otherwise invisible. Each
+   * call marks the step ABOUT to run, not the one just finished — the user
+   * needs to know what is happening now, and EF.SOD in particular takes long
+   * enough that silence reads as failure and prompts them to lift the document.
+   */
+  onStage?: (stage: NfcReadStage) => void,
+): Promise<EmrtdReadResult> {
+  const p = primitivesFromNative(native);
+
+  onStage?.('authenticating');
+  // SELECT + BAC are retried ONCE in place, on the same live connection.
+  // On Android the tag is routinely dispatched while the platform is still
+  // settling the link, so the first exchange dies with the chip right there —
+  // and an immediate second attempt succeeds with the phone untouched. The
+  // Flutter SDK documents and fixes this exact failure the same way
+  // (nfc_reader_emrtd.dart); a full session teardown cannot fix it, because
+  // Android never re-dispatches a tag that stayed in the field, so the outer
+  // retry loop just waited for a re-tap nobody knew to perform.
+  let sm: Awaited<ReturnType<typeof openSession>> | null = null;
+  for (let attempt = 0; sm === null; attempt += 1) {
+    try {
+      await selectApplication(native);
+      sm = await openSession(p, native, mrz);
+    } catch (err) {
+      if (attempt >= 1) throw err;
+    }
+  }
+
+  const transceive: Transceive = async (command) => {
+    const { data, statusWord } = await native.transceive(toBase64(command));
+    // The wrapped response is what secure messaging verifies; the outer status
+    // word is not covered by the MAC and is not the one that counts.
+    const body = fromBase64(data);
+    const out = new Uint8Array(body.length + 2);
+    out.set(body);
+    out[body.length] = (statusWord >> 8) & 0xff;
+    out[body.length + 1] = statusWord & 0xff;
+    return out;
+  };
+
+  onStage?.('readingData');
+  let dg1: Uint8Array;
+  try {
+    dg1 = await readFile(sm, transceive, EF.DG1);
+  } catch (err) {
+    throw new EmrtdSessionError(
+      err instanceof Error ? err.message : 'The chip stopped responding.',
+      'read_failed',
+    );
+  }
+
+  // From here on, a failure costs a signal rather than the read. A chip that
+  // gave up its MRZ has already proven it holds the BAC key. Optional reads
+  // get a second in-session try and NAME their failure — see optionalRead.ts.
+  onStage?.('readingSecurity');
+  const sod = await readOptionalFile(sm, transceive, EF.SOD, 'EF.SOD');
+
+  let dg2: Uint8Array | null = null;
+  if (sod) {
+    onStage?.('readingPhoto');
+    dg2 = await readOptionalFile(sm, transceive, EF.DG2, 'DG2');
+  }
+  onStage?.('done');
+
+  return {
+    dg1: toBase64(dg1),
+    ...(sod ? { sod: toBase64(sod) } : {}),
+    ...(dg2 ? { dg2: toBase64(dg2) } : {}),
+    chipAuth: 'bac',
+  };
+}

package/src/emrtd/stages.ts

@@ -0,0 +1,122 @@
+// ---------------------------------------------------------------------------
+// How far a chip read has got.
+//
+// iOS puts a system sheet over the whole read and narrates it. Android has NO
+// system NFC UI at all, so the same read is otherwise a bare spinner: the user
+// cannot tell whether the chip has even been detected, let alone that three
+// data groups are being pulled off it — and the natural response to that
+// silence is to lift the document, which aborts the read.
+//
+// The wording is deliberately identical to the iOS sheet's, so both platforms
+// narrate the read the same way. Ported from the Flutter SDK's NfcReadStage —
+// keep the two in step.
+// ---------------------------------------------------------------------------
+
+export type NfcReadStage =
+  /** Session open, waiting for the user to actually present the chip. */
+  | 'waiting'
+  /** Chip detected; opening the BAC session with the MRZ key. */
+  | 'authenticating'
+  /** Reading DG1 — the document's printed details. */
+  | 'readingData'
+  /** Reading EF.SOD — kilobytes, so the long one, and the step users abandon. */
+  | 'readingSecurity'
+  /** Reading DG2 — the chip's portrait. */
+  | 'readingPhoto'
+  /** Everything that could be read has been. */
+  | 'done';
+
+/** Order of the read, used to decide which steps are already complete. */
+export const NFC_STAGE_ORDER: NfcReadStage[] = [
+  'waiting',
+  'authenticating',
+  'readingData',
+  'readingSecurity',
+  'readingPhoto',
+  'done',
+];
+
+/** Short label for the step list. */
+export function nfcStageLabel(stage: NfcReadStage): string {
+  switch (stage) {
+    case 'waiting':
+      return 'Waiting for the chip';
+    case 'authenticating':
+      return 'Unlocking the chip';
+    case 'readingData':
+      return 'Reading document details';
+    case 'readingSecurity':
+      return 'Reading security data';
+    case 'readingPhoto':
+      return 'Reading photo';
+    case 'done':
+      return 'Chip read complete';
+  }
+}
+
+/**
+ * One line on what the phone is actually doing.
+ *
+ * A chip read is invisible — no shutter, no preview — so the detail is what
+ * stops a pause reading as a failure and prompting the user to lift the
+ * document.
+ */
+export function nfcStageDetail(stage: NfcReadStage): string {
+  switch (stage) {
+    case 'waiting':
+      return 'Hold the top edge of your document flat against the back of your phone.';
+    case 'authenticating':
+      return 'Opening a secure session using the code printed on your photo page.';
+    case 'readingData':
+      return 'Copying the details stored on the chip.';
+    case 'readingSecurity':
+      return 'Downloading the chip’s digital signature. This is the largest part and takes the longest — keep holding.';
+    case 'readingPhoto':
+      return 'Copying the photo stored on the chip.';
+    case 'done':
+      return 'Everything was read successfully.';
+  }
+}
+
+/**
+ * The line shown on iOS's system NFC sheet while a stage runs.
+ *
+ * The sheet COVERS the app during the read, so this is the only narration an
+ * iOS user gets. Terser than the in-app detail — the sheet truncates — and the
+ * long transfers say "keep holding", because lifting during them is exactly
+ * how the security file and the photo get lost.
+ */
+export function nfcSheetMessage(stage: NfcReadStage): string {
+  switch (stage) {
+    case 'waiting':
+      return 'Hold your phone near the passport';
+    case 'authenticating':
+      return 'Chip found — unlocking it…';
+    case 'readingData':
+      return 'Reading document details…';
+    case 'readingSecurity':
+      return 'Verifying security data — keep holding…';
+    case 'readingPhoto':
+      return 'Reading your photo — keep holding…';
+    case 'done':
+      return 'Chip read complete';
+  }
+}
+
+/** Position in the read, 0..1 — drives the progress bar. */
+export function nfcStageProgress(stage: NfcReadStage): number {
+  switch (stage) {
+    case 'waiting':
+      return 0;
+    case 'authenticating':
+      return 0.15;
+    case 'readingData':
+      return 0.35;
+    case 'readingSecurity':
+      return 0.6;
+    case 'readingPhoto':
+      return 0.85;
+    case 'done':
+      return 1;
+  }
+}

package/src/index.ts

@@ -14,6 +14,7 @@ export type { MyazaKYCProps, UseMyazaKYCReturn } from './MyazaKYC';
 // Public config + callback types
 export type {
   MyazaKYCConfig,
+  ResolvedKYCConfig,
   SupportedCountry,
   IdType,
   IdTypeForCountry,
@@ -24,7 +25,36 @@ export type {
   KYCSuccessContent,
   VoiceGuidanceConfig,
   VoiceGuidanceOption,
+  // Workflow-driven blocks — normally authored in the dashboard builder and
+  // delivered by `workflowId`, but settable as props too.
+  EmailVerificationConfig,
+  PhoneVerificationConfig,
+  ProofOfAddressConfig,
+  PoaDocumentType,
+  QuestionnaireConfig,
+  QuestionnaireField,
+  QuestionnaireFieldOption,
+  QuestionnaireAnswerValue,
+  OtpInputStyle,
+  NfcConfig,
+  LivenessMode,
+  WorkflowCountry,
+  WorkflowIdOption,
 } from './types/config';
+export type {
+  SubjectType,
+  ApplicantRole,
+  KeyPersonRole,
+  KeyPeopleLevel,
+  BusinessDocumentKey,
+  CompanyInfoField,
+  CompanyInfoMode,
+  WorkflowBusinessConfig,
+  WorkflowKeyPeopleConfig,
+  WorkflowBusinessDocumentsConfig,
+  WorkflowBusinessDocumentTypeConfig,
+  WorkflowBusinessApplicantConfig,
+} from './types/business';
 export type { KYCSubmission, KYCErrorCode, KYCErrorDetails } from './types/verification';
 export { KYCError } from './types/verification';
 
@@ -35,8 +65,51 @@ export {
   isNumberOnlyIdType,
   requiresDocumentCapture,
   getScanSides,
+  supportsNfcChip,
 } from './config/idTypes';
 
+// Flow shape — the single ordered list navigation, the back button and the
+// progress indicator all read.
+export {
+  buildStepOrder,
+  getStepProgress,
+  nextStepInOrder,
+  previousStepInOrder,
+  type StepOrderOptions,
+} from './config/stepOrder';
+
+// Business (KYB) product catalogue + application gates
+export {
+  BUSINESS_PRODUCTS,
+  DEFAULT_BUSINESS_PRODUCT,
+  businessCountriesFor,
+  businessProductsFor,
+  businessProductsForCountry,
+  companyInfoFieldModes,
+  getBusinessProductDef,
+  isBusinessFlow,
+  type BusinessProductDef,
+} from './config/business';
+export {
+  businessSectionSteps,
+  hasApplicantVerification,
+  hasBusinessDocumentsStep,
+  hasKeyPeopleCollection,
+  keyPeopleMinEntries,
+  resolveBusinessDocumentTypes,
+  type BusinessSectionStep,
+  type ResolvedBusinessDocumentType,
+} from './config/businessSteps';
+
+// Optional-step gates — the same helpers the step order reads, exported so a
+// consumer can reason about which steps a given config will run.
+export { hasActiveQuestionnaire, questionnaireAnswerKeys } from './config/questionnaire';
+export { hasEmailVerificationStep, hasPhoneVerificationStep } from './config/contact';
+export { hasProofOfAddressStep, poaDocumentTypes, poaTypeLabel } from './config/proofOfAddress';
+
+// Country grouping for multi-region flows
+export { groupCountriesByRegion, regionCountryName, type Region } from './config/regions';
+
 // Client-side validation
 export { validateIdNumber, maskIdNumber, type ValidationResult } from './services/validators';
 
@@ -50,5 +123,42 @@ export {
   hasFaceDetectorFactory,
 } from './liveness/faceDetector';
 
+// Device Intelligence — the fingerprint the server scores. Exported so a
+// consumer can see exactly what is collected.
+export {
+  collectFingerprint,
+  type ClientFingerprint,
+  type FingerprintComponents,
+} from './services/fingerprint';
+
+// MRZ reading (ICAO 9303) — exported so a consumer can parse a document's
+// machine-readable zone with the same check-digit validation the SDK uses.
+export { mrzCheckDigit, parseMrz, type MrzScan } from './mrz/parse';
+// Capability probes, so a consumer can tell "this build cannot read text" from
+// "this document has no MRZ" — the two look identical from the outside, and
+// only the first is worth reporting as a build problem.
+export { hasTextRecognizer } from './mrz/textRecognizer';
+export { hasRectDetector } from './capture/rectDetector';
+export { extractMrz, sanitizeMrzLine } from './mrz/extract';
+
+// eMRTD chip reading. The SERVER decides authenticity — it hashes DG1 against
+// the signed security object and verifies the document signer. Nothing here
+// concludes that a chip is genuine.
+export {
+  isNfcAvailable,
+  readPassportChip,
+  EmrtdSessionError,
+  type EmrtdReadResult,
+} from './emrtd';
+
+// Flash (screen-reflection) liveness — the palette and correlation are a
+// contract with the server's own re-analysis of the recorded video.
+export {
+  FLASH_PALETTE,
+  generateFlashSequence,
+  type FlashColor,
+  type FlashResult,
+} from './liveness/flashDetector';
+
 // SDK version
 export { SDK_VERSION } from './services/deviceMetadata';

package/src/lib/calendar.ts

@@ -0,0 +1,71 @@
+/**
+ * PURE month-grid math for the date picker — no RN imports, so it is unit
+ * testable. Dates are handled as plain {year, month0, day} numbers and ISO
+ * `YYYY-MM-DD` strings; never Date objects at the edges, because
+ * `new Date('YYYY-MM-DD')` parses as UTC midnight and shifts a birthday by a
+ * day for every user west of Greenwich.
+ */
+
+export const MONTH_NAMES = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+] as const;
+
+export const WEEKDAY_INITIALS = ['S', 'M', 'T', 'W', 'T', 'F', 'S'] as const;
+
+export interface CalendarDate {
+  year: number;
+  /** 0-based, matching Date#getMonth. */
+  month0: number;
+  day: number;
+}
+
+export function daysInMonth(year: number, month0: number): number {
+  return new Date(year, month0 + 1, 0).getDate();
+}
+
+/**
+ * The weeks of one month, Sunday-first, padded with nulls so every row is
+ * seven cells — the shape a calendar grid renders directly.
+ */
+export function monthMatrix(year: number, month0: number): (number | null)[][] {
+  const firstWeekday = new Date(year, month0, 1).getDay();
+  const total = daysInMonth(year, month0);
+
+  const cells: (number | null)[] = [
+    ...Array.from({ length: firstWeekday }, () => null),
+    ...Array.from({ length: total }, (_, i) => i + 1),
+  ];
+  while (cells.length % 7 !== 0) cells.push(null);
+
+  const weeks: (number | null)[][] = [];
+  for (let i = 0; i < cells.length; i += 7) weeks.push(cells.slice(i, i + 7));
+  return weeks;
+}
+
+export function toIsoDate({ year, month0, day }: CalendarDate): string {
+  const mm = String(month0 + 1).padStart(2, '0');
+  const dd = String(day).padStart(2, '0');
+  return `${year}-${mm}-${dd}`;
+}
+
+/** Strictly `YYYY-MM-DD` and a real calendar day — anything else is null. */
+export function parseIsoDate(value: string | undefined | null): CalendarDate | null {
+  if (!value) return null;
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value.trim());
+  if (!m) return null;
+  const year = Number(m[1]);
+  const month0 = Number(m[2]) - 1;
+  const day = Number(m[3]);
+  if (month0 < 0 || month0 > 11) return null;
+  if (day < 1 || day > daysInMonth(year, month0)) return null;
+  return { year, month0, day };
+}
+
+/** Step a (year, month0) cursor by ±1 month, carrying across year edges. */
+export function addMonth(year: number, month0: number, delta: 1 | -1): { year: number; month0: number } {
+  const next = month0 + delta;
+  if (next < 0) return { year: year - 1, month0: 11 };
+  if (next > 11) return { year: year + 1, month0: 0 };
+  return { year, month0: next };
+}

package/src/lib/use-keyboard-inset.ts

@@ -0,0 +1,34 @@
+import { useEffect, useState } from 'react';
+import { Keyboard, Platform } from 'react-native';
+
+/**
+ * The height the software keyboard currently covers, as a bottom inset.
+ *
+ * Exists for ANDROID. The flow presents inside a `statusBarTranslucent`
+ * `<Modal>`, and on Android that combination disables `adjustResize` — the
+ * window never shrinks for the keyboard, so a ScrollView inside it never
+ * learns the bottom half of the screen is gone and the focused input stays
+ * buried. (iOS doesn't use this: the ScrollView's
+ * `automaticallyAdjustKeyboardInsets` is the platform's own, better handling —
+ * it insets AND reveals the focused input.)
+ *
+ * Padding the scroll content by this amount restores what adjustResize would
+ * have done: everything above the keyboard is reachable by scrolling.
+ */
+export function useKeyboardInset(): number {
+  const [inset, setInset] = useState(0);
+
+  useEffect(() => {
+    if (Platform.OS !== 'android') return undefined;
+    const show = Keyboard.addListener('keyboardDidShow', (e) =>
+      setInset(e.endCoordinates.height),
+    );
+    const hide = Keyboard.addListener('keyboardDidHide', () => setInset(0));
+    return () => {
+      show.remove();
+      hide.remove();
+    };
+  }, []);
+
+  return inset;
+}

package/src/liveness/challengeManager.ts

@@ -10,6 +10,7 @@ import {
   type ChallengeConfig,
   type LivenessChallenge,
   type LivenessConfig,
+  type LivenessMode,
 } from './types';
 
 // Gestures within a similarity group should never appear together — one can
@@ -29,9 +30,34 @@ function shuffle<T>(arr: readonly T[]): T[] {
   return copy;
 }
 
-/** Picks `challengeCount` non-similar challenges from the pool, in random order. */
+/**
+ * Whether the workflow's liveness mode runs gesture challenges at all.
+ *
+ * `flash` means the screen-reflection sequence IS the check, so gestures are
+ * skipped entirely — only `both` runs gestures and then flash. Kept in step
+ * with the Flutter SDK's `runsGestures` and the web SDK.
+ */
+export function modeRunsGestures(mode: LivenessMode | undefined): boolean {
+  return mode !== 'flash';
+}
+
+/**
+ * Picks `challengeCount` non-similar challenges from the pool, in random order.
+ *
+ * Returns NOTHING in flash-only mode. This is gated here, at the single place
+ * challenges are chosen, rather than at the call sites: `useLiveness` rebuilds
+ * the tracker in three separate places (mount, retry, face-change reset), and a
+ * check in one of them would leave the others silently running gestures a
+ * flash-only workflow explicitly turned off.
+ *
+ * Deliberately keyed on the mode rather than `challengeCount: 0` — the count is
+ * clamped to at least one on purpose, so that a stray zero in a consumer's
+ * config can never quietly disable gesture liveness. Skipping gestures has to
+ * be asked for.
+ */
 export function pickChallenges(config: Partial<LivenessConfig> = {}): ChallengeConfig[] {
   const merged = { ...DEFAULT_LIVENESS_CONFIG, ...config };
+  if (!modeRunsGestures(merged.mode)) return [];
 
   let pool = CHALLENGE_POOL;
   if (merged.challengePool && merged.challengePool.length > 0) {