@myazahq/kyc-sdk-react-native 2.4.0 → 2.5.0

package/src/emrtd/stages.ts

@@ -23,6 +23,8 @@ export type NfcReadStage =
   | 'readingSecurity'
   /** Reading DG2 — the chip's portrait. */
   | 'readingPhoto'
+  /** Reading the optional detail groups (DG7/DG11/DG12) — small and quick. */
+  | 'readingDetails'
   /** Everything that could be read has been. */
   | 'done';
 
@@ -33,6 +35,7 @@ export const NFC_STAGE_ORDER: NfcReadStage[] = [
   'readingData',
   'readingSecurity',
   'readingPhoto',
+  'readingDetails',
   'done',
 ];
 
@@ -49,6 +52,8 @@ export function nfcStageLabel(stage: NfcReadStage): string {
       return 'Reading security data';
     case 'readingPhoto':
       return 'Reading photo';
+    case 'readingDetails':
+      return 'Reading extra details';
     case 'done':
       return 'Chip read complete';
   }
@@ -73,6 +78,8 @@ export function nfcStageDetail(stage: NfcReadStage): string {
       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 'readingDetails':
+      return 'Copying the optional details stored on the chip. These are small and quick.';
     case 'done':
       return 'Everything was read successfully.';
   }
@@ -98,6 +105,8 @@ export function nfcSheetMessage(stage: NfcReadStage): string {
       return 'Verifying security data — keep holding…';
     case 'readingPhoto':
       return 'Reading your photo — keep holding…';
+    case 'readingDetails':
+      return 'Almost done — keep holding…';
     case 'done':
       return 'Chip read complete';
   }
@@ -116,6 +125,8 @@ export function nfcStageProgress(stage: NfcReadStage): number {
       return 0.6;
     case 'readingPhoto':
       return 0.85;
+    case 'readingDetails':
+      return 0.95;
     case 'done':
       return 1;
   }

package/src/lib/contact-recovery.ts

@@ -0,0 +1,44 @@
+// Recovery from a submit refused over contact proofs. Mirrors the web SDK's
+// steps/contact-recovery.ts — keep the two in lockstep.
+//
+// Contact proof tokens are SINGLE-USE and expire ~30 minutes after the OTP is
+// checked, but they ride session progress and are restored on resume. A
+// resumed attempt therefore carries a proof the server will (rightly)
+// validate-and-drop at submit, while the contact step still shows "verified"
+// — and a plain retry resubmits the same dead token forever.
+//
+// The 422 is recoverable in-flow: clear the stale proofs, walk the person
+// back to the contact step (their data is untouched), and once re-verified
+// the step routes straight back to 'submitted', which auto-submits with the
+// fresh token.
+import { KYCApiError } from '../services/api';
+import type { KYCStep } from '../types/config';
+
+export type ContactChannel = 'email' | 'phone';
+
+/** The channels a 422 `contact_verification_required` names as missing. */
+export function expiredContactChannels(err: unknown): ContactChannel[] {
+  if (!(err instanceof KYCApiError) || err.code !== 'contact_verification_required') return [];
+  const missing = Array.isArray(err.body?.missing) ? (err.body.missing as unknown[]) : [];
+  return missing.filter((c): c is ContactChannel => c === 'email' || c === 'phone');
+}
+
+export function contactStepFor(channel: ContactChannel): KYCStep {
+  return channel === 'email' ? 'email-verification' : 'phone-verification';
+}
+
+/**
+ * Where the step routes once this channel is verified. Normally the ordinary
+ * forward step; in recovery it returns to 'submitted' (which auto-submits
+ * with the fresh proof) via any OTHER still-refused channel first — the
+ * person never re-walks steps they already completed.
+ */
+export function stepAfterContactVerified(opts: {
+  recovery: boolean;
+  expired: ContactChannel[];
+  channel: ContactChannel;
+}): KYCStep | null {
+  if (!opts.recovery) return null;
+  const remaining = opts.expired.find((c) => c !== opts.channel);
+  return remaining ? contactStepFor(remaining) : 'submitted';
+}

package/src/lib/multi-id.ts

@@ -0,0 +1,210 @@
+// Multi-ID flows on React Native. A PORT of the web SDK's lib/multi-id.ts,
+// kept byte-for-byte in its logic: the server validates the pick sequence the
+// client produced, so a client that computes options differently produces
+// submissions the server rejects. If you change a rule here, change it in
+// kyc-sdk-react/src/lib/multi-id.ts, kyc-core/src/lib/multi-id.ts and the
+// dashboard's required-ids-model.ts in the same commit.
+//
+// Multi-ID flows: a workflow's `multiId` block asks for SEVERAL ID checks in
+// one run — the applicant picks each slot's ID from what the admin allowed for
+// THEIR country (a picked ID disappears from later slots), ONE selfie covers
+// the whole run, and everything submits as ONE verification the server judges
+// by the pass policy.
+//
+// Multi-region works: the country-select step comes first as usual, and the
+// run then walks THAT country's slots (`countries[].multiIdSlots`). The pure
+// helpers here MIRROR the server's lib/multi-id.ts exactly — the safe-options
+// rule is what keeps an applicant from ever being offered a pick that would
+// strand a later slot, and the server validates the same sequence.
+
+export interface MultiIdConfig {
+  count: number;
+  minPassed: number;
+}
+
+export interface MultiIdCountry {
+  country: string;
+  idTypes?: string[];
+  /** This country's per-verification ID allowlists. */
+  multiIdSlots?: Array<{ idTypes?: string[] }>;
+}
+
+interface MultiIdSourceConfig {
+  multiId?: MultiIdConfig;
+  subjectType?: string;
+  /** The EFFECTIVE country (post country-select) — whose slots the run walks. */
+  country?: string;
+  countries?: MultiIdCountry[];
+  idTypes?: string[];
+}
+
+/** The workflow's multiId POLICY — null for ordinary flows and every KYB flow. */
+export function multiIdConfigFrom(config: MultiIdSourceConfig): MultiIdConfig | null {
+  if (config.subjectType === 'business') return null;
+  const block = config.multiId;
+  if (!block || typeof block.count !== 'number') return null;
+  const count = Math.trunc(block.count);
+  // REJECT an out-of-range count rather than clamping it. The server returns
+  // null here, so clamping made the client walk 3 checks for a config the
+  // server does not consider multi-ID at all — and clamping `minPassed`
+  // against the RAW count could ask for 9 of 3 to pass, which nothing can
+  // satisfy. Same rule, both sides, or the client builds submissions the
+  // server rejects.
+  if (!Number.isInteger(count) || count < 2 || count > 3) return null;
+  return {
+    count,
+    minPassed:
+      typeof block.minPassed === 'number' && Number.isInteger(block.minPassed)
+        ? Math.min(Math.max(block.minPassed, 1), count)
+        : count,
+  };
+}
+
+/** The country entry the run walks: the EFFECTIVE country's, else the legacy
+ *  single-country shape. */
+export function multiIdCountryEntry(config: MultiIdSourceConfig): MultiIdCountry | null {
+  const country = config.country;
+  if (config.countries && config.countries.length > 0) {
+    return config.countries.find((c) => c.country === country) ?? null;
+  }
+  return country ? { country, idTypes: config.idTypes } : null;
+}
+
+/**
+ * The ID types the picked country offers: its pinned list, else everything the
+ * server granted there.
+ */
+export function multiIdOfferedTypes(
+  config: MultiIdSourceConfig,
+  serverIdTypes: Array<{ country: string; idType: string }>,
+): string[] {
+  const entry = multiIdCountryEntry(config);
+  if (!entry) return [];
+  if (entry.idTypes && entry.idTypes.length > 0) return entry.idTypes;
+  return serverIdTypes.filter((row) => row.country === entry.country).map((row) => row.idType);
+}
+
+/** Per-slot option lists (a pinned slot keeps its list; others offer everything). */
+export function multiIdSlotOptions(
+  count: number,
+  slots: Array<{ idTypes?: string[] }> | undefined,
+  offered: string[],
+): string[][] {
+  const offeredSet = new Set(offered);
+  return Array.from({ length: count }, (_, i) => {
+    const pinned = slots?.[i]?.idTypes;
+    const base = pinned && pinned.length > 0 ? pinned : offered;
+    return base.filter((t) => offeredSet.has(t));
+  });
+}
+
+/** The first reachable dead-end across pick orders, or null. */
+export function multiIdFirstDeadEnd(
+  slotOptions: string[][],
+): { picks: string[]; slotIndex: number } | null {
+  const walk = (index: number, picked: string[]): { picks: string[]; slotIndex: number } | null => {
+    if (index >= slotOptions.length) return null;
+    const available = slotOptions[index]!.filter((t) => !picked.includes(t));
+    if (available.length === 0) return { picks: picked, slotIndex: index };
+    for (const pick of available) {
+      const deadEnd = walk(index + 1, [...picked, pick]);
+      if (deadEnd) return deadEnd;
+    }
+    return null;
+  };
+  return walk(0, []);
+}
+
+/** The picks a slot may SAFELY offer: unused AND non-stranding. */
+export function multiIdSafeOptions(
+  slotOptions: string[][],
+  slotIndex: number,
+  picked: string[],
+): string[] {
+  const remaining = slotOptions.slice(slotIndex + 1);
+  return (slotOptions[slotIndex] ?? [])
+    .filter((t) => !picked.includes(t))
+    .filter(
+      (t) =>
+        multiIdFirstDeadEnd(
+          remaining.map((opts) => opts.filter((o) => o !== t && !picked.includes(o))),
+        ) === null,
+    );
+}
+
+export interface MultiIdPlan {
+  count: number;
+  minPassed: number;
+  /** Which slot is being walked (clamped; equals count once every slot committed). */
+  index: number;
+  /** The current slot is the final one. */
+  last: boolean;
+  /** ID types committed so far, in order. */
+  picked: string[];
+  /** What the CURRENT slot's picker may offer. */
+  safeOptions: string[];
+}
+
+/** The active plan, or null for ordinary flows. */
+export function multiIdPlan(
+  config: MultiIdSourceConfig,
+  state: { multiIdSlotIndex: number; multiIdSlots: Array<{ idType: string }> },
+  serverIdTypes: Array<{ country: string; idType: string }>,
+): MultiIdPlan | null {
+  const cfg = multiIdConfigFrom(config);
+  if (!cfg) return null;
+  const offered = multiIdOfferedTypes(config, serverIdTypes);
+  const options = multiIdSlotOptions(cfg.count, multiIdCountryEntry(config)?.multiIdSlots, offered);
+  const picked = state.multiIdSlots.map((s) => s.idType);
+  const index = Math.min(Math.max(state.multiIdSlotIndex, 0), cfg.count);
+  return {
+    count: cfg.count,
+    minPassed: cfg.minPassed,
+    index,
+    last: index >= cfg.count - 1,
+    picked,
+    safeOptions: index < cfg.count ? multiIdSafeOptions(options, index, picked) : [],
+  };
+}
+
+/** Which evidence step one slot's ID opens on. */
+export function multiIdEvidenceStep(
+  def: { requiresDocumentCapture: boolean } | null | undefined,
+): 'id-input' | 'document-capture' {
+  return def && def.requiresDocumentCapture === false ? 'id-input' : 'document-capture';
+}
+
+/**
+ * The committed slots as the WIRE sees them — an explicit whitelist, because
+ * the slots also carry local preview images for the back journey and those must
+ * never reach the submission or the session-progress blob. Whitelist, not
+ * spread: a field added to the slot later cannot leak by default.
+ */
+export function multiIdWireSlots(
+  slots: Array<{
+    idType: string;
+    idNumber?: string;
+    documentFront?: string;
+    documentBack?: string;
+    documentFrontVideo?: string;
+    documentBackVideo?: string;
+  }>,
+): Array<{
+  idType: string;
+  idNumber?: string;
+  documentFront?: string;
+  documentBack?: string;
+  documentFrontVideo?: string;
+  documentBackVideo?: string;
+}> {
+  // The chip is attached by the caller after this whitelist (it is a payload,
+  // not a mediaId), so it is absent here and not stripped.
+  return slots.map((s) => ({
+    idType: s.idType,
+    ...(s.idNumber ? { idNumber: s.idNumber } : {}),
+    ...(s.documentFront ? { documentFront: s.documentFront } : {}),
+    ...(s.documentBack ? { documentBack: s.documentBack } : {}),
+    ...(s.documentFrontVideo ? { documentFrontVideo: s.documentFrontVideo } : {}),
+    ...(s.documentBackVideo ? { documentBackVideo: s.documentBackVideo } : {}),
+  }));
+}

package/src/lib/resubmit.ts

@@ -0,0 +1,130 @@
+// Narrowing a flow to the steps a reviewer asked the applicant to redo.
+//
+// A reviewer looked at a finished verification and sent it back — usually
+// because one thing was unreadable, not because everything was wrong. Making
+// somebody retake a passport photo is reasonable; making them redo consent, the
+// ID picker, liveness and a questionnaire to fix that photo is how you lose them.
+//
+// The instruction rides the session's config snapshot (`config.resubmit`), which
+// is how every other per-session flow instruction travels. An SDK that predates
+// this simply does not read the key and runs the whole flow, which is the safe
+// degradation: asking for too much is recoverable, silently skipping a step the
+// reviewer wanted is not.
+import type { KYCStep } from '../types/config';
+
+export interface ResubmitConfig {
+  /** Steps to redo, in flow order. Never empty — the server omits the key instead. */
+  steps: string[];
+  /** Reviewer's note to the applicant. */
+  message?: string | null;
+}
+
+/**
+ * Steps that are always kept, whatever the reviewer ticked.
+ *
+ * `consent` because a flow with no first screen is disorienting, and it is where
+ * the redo is explained. `submitted` because a flow has to end somewhere.
+ * Neither is something the applicant is being asked to redo — they are the
+ * frame around what is.
+ */
+const ALWAYS: KYCStep[] = ['consent', 'submitted'];
+
+/**
+ * One ID's evidence — a FAMILY, not alternatives a reviewer picks between.
+ *
+ * Which member a flow contains depends on the ID type: a number-only ID has
+ * `id-input`, a document ID has `document-capture` (and maybe `nfc`). At the
+ * moment the order is built nobody has chosen one yet, so the flow is shaped by
+ * a default. A plan naming `id-input` against an order still shaped for
+ * `document-capture` therefore matched NOTHING, fell through to the safety net
+ * below, and silently ran the entire flow — which is exactly the bug a reviewer
+ * sees as "I asked for the ID and it made them do everything again".
+ *
+ * Asking for one member asks for whichever this flow turns out to have.
+ */
+const EVIDENCE: KYCStep[] = ['id-input', 'document-capture', 'nfc'];
+
+/**
+ * Steps a narrowed flow keeps regardless, because without them it cannot
+ * produce a submission at all.
+ *
+ * A resubmission is a NEW verification on a FRESH session: nothing is carried
+ * forward from the one being redone, so the applicant must still say which ID
+ * this is and supply it. `POST /verify` requires an `idType`, and a number-only
+ * ID requires the number with it.
+ *
+ * So narrowing removes the things arranged AROUND the identity — liveness,
+ * proof of address, the questionnaire, contact checks — and never the identity
+ * itself. The alternative is a two-screen flow that collects a photo and then
+ * fails to submit, which is worse for the applicant than being asked for one
+ * extra screen.
+ */
+const INDIVIDUAL_REQUIRED: KYCStep[] = ['id-type', ...EVIDENCE];
+const BUSINESS_REQUIRED: KYCStep[] = ['business-details'];
+
+/**
+ * Narrow a full step order to the redo, preserving flow order.
+ *
+ * Order comes from `order`, never from the reviewer's list: they ticked
+ * checkboxes, and walking somebody through liveness before document capture
+ * because that is the order the boxes were ticked in would be nonsense.
+ *
+ * Returns the ORIGINAL order untouched when the instruction is absent, empty, or
+ * matches nothing we know. That last case matters: a server that learns a new
+ * step name before this SDK does must not produce a two-screen flow that
+ * collects nothing.
+ */
+export function applyResubmitSteps(
+  order: KYCStep[],
+  resubmit: ResubmitConfig | undefined | null,
+): KYCStep[] {
+  const asked = resubmit?.steps;
+  if (!asked?.length) return order;
+
+  const wantsEvidence = asked.some((step) => EVIDENCE.includes(step as KYCStep));
+
+  // Does the instruction name anything this flow actually has? If not, it came
+  // from a server that knows a step name this SDK does not — and narrowing on it
+  // would quietly drop whatever was really asked for. Checked BEFORE the
+  // required steps are added, or those alone would make every unknown plan look
+  // recognised and turn the safety net below into dead code.
+  const recognised = wantsEvidence || asked.some((step) => order.includes(step as KYCStep));
+  if (!recognised) return order;
+
+  const wanted = new Set<string>(asked);
+  if (wantsEvidence) for (const step of EVIDENCE) wanted.add(step);
+  for (const step of order.includes('business-details') ? BUSINESS_REQUIRED : INDIVIDUAL_REQUIRED) {
+    wanted.add(step);
+  }
+
+  const narrowed = order.filter((step) => wanted.has(step) || ALWAYS.includes(step));
+
+  // Nothing but the frame survived, so the instruction named steps this flow
+  // does not contain. Run everything rather than nothing.
+  const collects = narrowed.some((step) => !ALWAYS.includes(step));
+  return collects ? narrowed : order;
+}
+
+/** Whether this mount is a targeted redo, for the wording on screen. */
+export function isResubmission(resubmit: ResubmitConfig | undefined | null): boolean {
+  return Boolean(resubmit?.steps?.length);
+}
+
+/**
+ * The reviewer's note to the applicant, when this mount is a targeted redo.
+ *
+ * The dashboard's send-back dialog asks a reviewer to explain the problem — its
+ * placeholder is literally "Your document photo was too dark to read, please
+ * retake it in good light." The server stamps that note onto the session and
+ * every SDK parses it into config, and until now NONE of them displayed it. So
+ * a send-back reached the applicant as a flow that had silently lost most of
+ * its steps, with nothing saying why they were back or what to do differently.
+ *
+ * Returns null when there is nothing to show, so a caller can render this
+ * unconditionally.
+ */
+export function resubmitNote(resubmit: ResubmitConfig | undefined | null): string | null {
+  if (!isResubmission(resubmit)) return null;
+  const note = resubmit?.message?.trim();
+  return note && note.length > 0 ? note : null;
+}

package/src/lib/screen-corners.ts

@@ -0,0 +1,50 @@
+import { Dimensions, Platform } from 'react-native';
+import { initialWindowMetrics } from 'react-native-safe-area-context';
+
+// Apple's grammar for nested corners is CONCENTRIC: an inset card's radius is
+// the DISPLAY's corner radius minus the gap between card and screen edge —
+// that is why the system share sheet's curve runs parallel to the phone's.
+// No public API exposes the display radius, so iOS resolves it from the
+// model's logical screen size (the per-device values Apple ships, from
+// UIScreen's private _displayCornerRadius, in points). Unknown hardware falls
+// back on whether the display is rounded at all: home-indicator devices are,
+// square-corner devices are not.
+
+/** `short x long` logical points → display corner radius in points. */
+const IOS_RADII: Record<string, number> = {
+  // X / XS / 11 Pro are 39 on the same canvas as the 12–13 mini's 44; the
+  // minis are the ones still in pockets, so the shared key takes their value.
+  '375x812': 44,
+  '414x896': 41.5, // XR / 11 / XS Max / 11 Pro Max
+  '390x844': 47.33, // 12 / 12 Pro / 13 / 13 Pro / 14
+  '428x926': 53.33, // 12–13 Pro Max / 14 Plus
+  '393x852': 55, // 14 Pro / 15 / 15 Pro / 16 / 16e
+  '430x932': 55, // 14 Pro Max / 15 Plus / 15 Pro Max / 16 Plus
+  '402x874': 62, // 16 Pro
+  '440x956': 62, // 16 Pro Max
+};
+
+/**
+ * The display's own corner radius, in points/dp. 0 means a square-cornered
+ * screen (or one we cannot judge), and the caller picks its flat-world look.
+ */
+export function displayCornerRadius(): number {
+  const { width, height } = Dimensions.get('screen');
+  const key = `${Math.round(Math.min(width, height))}x${Math.round(Math.max(width, height))}`;
+  const bottomInset = initialWindowMetrics?.insets?.bottom ?? 0;
+
+  if (Platform.OS === 'ios') {
+    const known = IOS_RADII[key];
+    if (known != null) return known;
+    // Unlisted model: a home indicator means a rounded display; 47 is the
+    // middle of the modern range.
+    return bottomInset > 0 ? 47 : 0;
+  }
+
+  // Android has no cheap signal (the RoundedCorner API needs native code).
+  // A small bottom inset is gesture navigation — overwhelmingly the modern,
+  // rounded-display phones — while ~48dp is the opaque 3-button bar, which
+  // says nothing. Modest on purpose: an under-estimate still looks composed,
+  // an over-estimate looks like a mistake.
+  return bottomInset > 0 && bottomInset <= 32 ? 32 : 0;
+}

package/src/lib/step-log.ts

@@ -11,6 +11,20 @@
 export interface StepLogEntry {
   step: string;
   at: string;
+  /**
+   * Which multi-ID check the applicant was on (1-based). Absent on ordinary
+   * runs and on the first check.
+   *
+   * The SERVER cannot tell a slot advance from a back-press: a multi-ID run
+   * legitimately returns to the ID picker for its next ID, and by step name
+   * that is identical to pressing Back. Only the client knows a slot was
+   * committed, so only the client can say.
+   */
+  slot?: number;
+  /** The ID type selected AT THAT MOMENT — a slot's final pick is not what the
+   *  applicant was doing earlier in it (pick one ID, go back, settle on
+   *  another, and the earlier step would be named for an ID not yet chosen). */
+  idType?: string;
 }
 
 export interface StepLog {
@@ -29,10 +43,17 @@ export function resetStepLog(): void {
 
 /** Records a step visit. Consecutive duplicates are collapsed; back-and-forth
  *  navigation is kept — repeat visits are honest journey data. */
-export function recordStep(step: string): void {
+export function recordStep(step: string, slot?: number, idType?: string): void {
   if (entries.length >= MAX_ENTRIES) return;
-  if (entries[entries.length - 1]?.step === step) return;
-  entries.push({ step, at: new Date().toISOString() });
+  const last = entries[entries.length - 1];
+  // A revisit on a NEW check, or on a DIFFERENT ID, is a different visit.
+  if (last?.step === step && last.slot === slot && last.idType === idType) return;
+  entries.push({
+    step,
+    at: new Date().toISOString(),
+    ...(slot ? { slot } : {}),
+    ...(idType ? { idType } : {}),
+  });
 }
 
 /** Snapshot attached to the verify submission. Null when nothing was recorded

package/src/lib/use-multi-id-plan.ts

@@ -0,0 +1,29 @@
+import { useMemo } from 'react';
+
+import { multiIdPlan, type MultiIdPlan } from './multi-id';
+import { useEffectiveCountry, useKyc, useKycConfig } from '../components/runtime';
+
+/**
+ * The active multi-ID plan for the current state, or null on an ordinary run.
+ *
+ * One hook so the picker and the position strip cannot disagree about which
+ * check the applicant is on or what it may offer — the server validates the
+ * pick sequence, so two answers here means submissions it rejects.
+ */
+export function useMultiIdPlan(): MultiIdPlan | null {
+  const config = useKycConfig();
+  const country = useEffectiveCountry();
+  const multiIdSlotIndex = useKyc((s) => s.multiIdSlotIndex);
+  const multiIdSlots = useKyc((s) => s.multiIdSlots);
+  const serverConfig = useKyc((s) => s.serverConfig);
+
+  return useMemo(
+    () =>
+      multiIdPlan(
+        { ...config, country },
+        { multiIdSlotIndex, multiIdSlots },
+        serverConfig.status === 'ready' ? serverConfig.idTypes : [],
+      ),
+    [config, country, multiIdSlotIndex, multiIdSlots, serverConfig],
+  );
+}

package/src/liveness/useModelReady.ts

@@ -0,0 +1,65 @@
+import { useEffect, useRef, useState } from 'react';
+
+import { isFaceModelReady, primeFaceModel } from './visionCameraFaceDetector';
+
+// ─── Face-model readiness gate ────────────────────────────────────────────────
+//
+// Android fetches ML Kit's face model through Play Services rather than bundling
+// it, which keeps ~8 MB per device out of the APK but leaves a window where
+// detection cannot run: first launch before the download lands, or a device with
+// no Google Play Services at all.
+//
+// This has to be answered BEFORE the camera opens. `detectFace` reports through
+// `FaceResult`, where a missing model and an empty frame are both
+// `faceCount: 0` — so gating on the per-frame result would strand the user on
+// "position your face" indefinitely, with the SDK unable to say why. That is the
+// single failure mode this whole gate exists to prevent.
+//
+// iOS is always ready (Apple Vision is a system framework), so this resolves on
+// the first tick there and costs nothing.
+
+export type ModelReadyState = 'ready' | 'preparing' | 'unavailable';
+
+/** How long to wait for the model before calling it unavailable. */
+const MODEL_WAIT_MS = 20_000;
+/** Gap between readiness polls while the download is in flight. */
+const POLL_INTERVAL_MS = 500;
+
+/**
+ * Tracks whether on-device face detection can run.
+ *
+ * Returns `'preparing'` while Play Services fetches the model, `'ready'` once it
+ * can run, and `'unavailable'` when it could not be obtained within
+ * {@link MODEL_WAIT_MS} — no Play Services, no network, or a declined install.
+ *
+ * The flow primes the download at open (see `MyazaKYC.tsx`), so by the time the
+ * user reaches liveness this is normally already `'ready'` and no waiting screen
+ * is ever shown.
+ */
+export function useFaceModelReady(): ModelReadyState {
+  const [state, setState] = useState<ModelReadyState>(() =>
+    isFaceModelReady() ? 'ready' : 'preparing',
+  );
+  const startedAt = useRef(Date.now());
+
+  useEffect(() => {
+    if (state !== 'preparing') return;
+
+    // Re-prime rather than assume the open-time call ran: the step can be
+    // reached directly in a resumed flow, and prepareModel() is a no-op once
+    // the model is present.
+    primeFaceModel();
+
+    const id = setInterval(() => {
+      if (isFaceModelReady()) {
+        setState('ready');
+      } else if (Date.now() - startedAt.current > MODEL_WAIT_MS) {
+        setState('unavailable');
+      }
+    }, POLL_INTERVAL_MS);
+
+    return () => clearInterval(id);
+  }, [state]);
+
+  return state;
+}

package/src/liveness/visionCameraFaceDetector.ts

@@ -45,6 +45,41 @@ const boxedDetector: BoxedHybridObject<MyazaFaceDetector> | null = detector
   ? NitroModules.box(detector)
   : null;
 
+/**
+ * Start fetching the face model, so it is warm by the time liveness runs.
+ *
+ * Android fetches ML Kit's models through Play Services rather than bundling
+ * them, which keeps ~18.5 MB per device out of the APK but leaves a window on
+ * first launch where detection cannot work. Priming at flow start puts that
+ * download behind the consent and ID-type screens instead of in front of the
+ * camera.
+ *
+ * Best-effort and non-blocking, exactly like the web SDK's `primeFaceMesh()`:
+ * a failure here is not fatal, because {@link isFaceModelReady} is what the
+ * liveness step actually gates on. iOS resolves immediately (Apple Vision is a
+ * system framework).
+ */
+export function primeFaceModel(): void {
+  detector?.prepareModel().catch(() => {
+    /* best-effort: isFaceModelReady() is the real gate */
+  });
+}
+
+/**
+ * Whether face detection can run right now.
+ *
+ * Checked BEFORE the camera opens. `detectFace` cannot answer this — a missing
+ * model and an empty frame are both `faceCount: 0`, so gating on the per-frame
+ * result would strand the user on "position your face" with no explanation.
+ *
+ * `true` when the native module is absent entirely (Expo Go), because that path
+ * already degrades to the existing camera-unavailable screen and should not be
+ * reported as a model problem.
+ */
+export function isFaceModelReady(): boolean {
+  return detector?.isModelReady() ?? true;
+}
+
 /**
  * Maps the native {@link FaceResult} to a {@link LivenessFaceData}, or `null`
  * when no face is present (`faceCount === 0`). A worklet — runs on the camera