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

package/src/liveness/livenessState.ts

@@ -0,0 +1,139 @@
+import type {
+  LivenessChallenge,
+  LivenessConfig,
+  LivenessFaceData,
+  LivenessFailureReason,
+  LivenessPhase,
+} from './types';
+import type { FlashResult } from './flashDetector';
+
+// ---------------------------------------------------------------------------
+// The liveness machine's vocabulary: its UI state, its options, its guidance
+// strings and the two phase predicates the handlers branch on.
+//
+// Split out of useLiveness (200-line rule). Deliberately free of the hook, so
+// the phase predicates below can be read — and reasoned about — without the
+// state machine around them. They are load-bearing: `isSettled` decides where
+// guidance is suppressed, and getting its scope wrong is what once left the
+// flash and the capture without a multiple-face check.
+// ---------------------------------------------------------------------------
+
+export const INTEGRITY_FAILED_PATCH = {
+  phase: 'failed' as const,
+  failureReason: 'face_swap' as const,
+  instruction: 'Let\u2019s start over \u2014 please stay in frame.',
+  activeChallenge: null,
+  positionGuidance: null,
+};
+
+import { LivenessSpeaker } from './speech';
+import type { VoiceGuidanceOption } from '../types/config';
+
+export const CHALLENGE_PASSED_MS = 700; // brief "Great!" before the next challenge
+export const POSITION_TOO_FAR = 'too_far';
+export const POSITION_TOO_CLOSE = 'too_close';
+export const MULTIPLE_FACES_GUIDANCE = 'Make sure only your face is visible';
+
+export type PositionGuidance = typeof POSITION_TOO_FAR | typeof POSITION_TOO_CLOSE;
+export type LightingGuidance = 'dark' | 'bright';
+
+export interface LivenessUiState {
+  phase: LivenessPhase;
+  instruction: string;
+  activeChallenge: LivenessChallenge | null;
+  timeoutRemaining: number;
+  completedCount: number;
+  totalCount: number;
+  positionGuidance: PositionGuidance | null;
+  lightingGuidance: LightingGuidance | null;
+  multipleFaces: boolean;
+  wrongGesture: boolean;
+  faceDetected: boolean;
+  failureReason: LivenessFailureReason | null;
+}
+
+export interface UseLivenessOptions {
+  config?: Partial<LivenessConfig>;
+  voiceGuidance?: VoiceGuidanceOption;
+  /** Fires once when all challenges pass and the phase enters `capturing`. */
+  onReadyToCapture?: () => void;
+  /**
+   * Whether the step is actually on screen and the user has started.
+   *
+   * The machine is constructed while the readiness primer is still up — hooks
+   * cannot be called conditionally — so without this it announces "Position
+   * your face in the circle" to someone still reading the primer, before they
+   * have tapped anything. Guidance for a screen the user cannot see is worse
+   * than none: it is a voice from nowhere.
+   *
+   * Defaults true so a consumer that never sets it behaves as before.
+   */
+  announce?: boolean;
+}
+
+export interface UseLivenessReturn extends LivenessUiState {
+  /** Push a face frame into the machine (call from the frame processor via runOnJS). */
+  onFace: (data: LivenessFaceData) => void;
+  /** Push a "no face this frame" signal. */
+  onNoFace: () => void;
+  /**
+   * Resolves true once a face is detected AFTER the call, or false on timeout.
+   * The capture gate uses this so an empty frame is never photographed.
+   */
+  awaitFreshFace: (timeoutMs: number) => Promise<boolean>;
+  /** Feed live lighting quality (null = ok). */
+  setLighting: (guidance: LightingGuidance | null) => void;
+  /** Mark the selfie captured → phase `complete`. */
+  markComplete: () => void;
+  /** Restart the session with a fresh random challenge set. */
+  reset: () => void;
+  /** True while the machine wants a still captured (phase === 'capturing'). */
+  shouldCapture: boolean;
+  /** True while the screen should be running the flash sequence. */
+  shouldFlash: boolean;
+  /** Called by the screen when the flash sequence finishes. */
+  completeFlash: (result: FlashResult) => void;
+  /** The flash verdict, once run — carried into the submission as context. */
+  flashResult: FlashResult | null;
+  /** How many face discontinuities the continuity guard saw this session. */
+  faceGlitches: number;
+  /**
+   * True once the session can no longer vouch for who is in frame. The capture
+   * path reads this AFTER the still is taken: a substitution detected during
+   * `capturing` is recorded silently (so nothing re-lays out mid-capture) and
+   * acted on here.
+   */
+  integrityBroken: boolean;
+  /** Live read of the integrity flag — see `isCompromised` in the hook. */
+  isCompromised: () => boolean;
+  /** Surfaces a failure that was detected mid-capture and deliberately held. */
+  reportIntegrityFailure: () => void;
+}
+
+/** Position guidance text (spoken + shown), matching the Flutter SDK exactly. */
+export function positionGuidanceText(g: PositionGuidance): string {
+  return g === POSITION_TOO_FAR ? 'Kindly move closer' : 'Kindly move further away';
+}
+/** Lighting warning banner text — the full Flutter strings (shown, not spoken). */
+export function lightingGuidanceText(g: LightingGuidance): string {
+  return g === 'dark'
+    ? 'It looks dark here. Move to a brighter area or near a light source for better detection.'
+    : 'Too bright — reduce glare or move away from direct light for better detection.';
+}
+
+/**
+ * Phases during which the screen must NOT change layout.
+ *
+ * While capturing, a re-layout moves the subject mid-shutter. While flashing,
+ * the overlay's cutout is measured once when the flash starts, so shifting the
+ * preview underneath it leaves the hole in the wrong place — the exact bug the
+ * Flutter SDK hit. Guidance banners are also meaningless during a flash, since
+ * the screen is deliberately painting the "wrong" light.
+ */
+export function isSettled(phase: LivenessPhase): boolean {
+  return phase === 'capturing' || phase === 'flash';
+}
+
+export function isTerminal(phase: LivenessPhase): boolean {
+  return phase === 'complete' || phase === 'failed';
+}

package/src/liveness/speech.ts

@@ -30,11 +30,23 @@ export class LivenessSpeaker {
   private readonly enabled: boolean;
   private readonly language: string;
   private lastSpoken: string | null = null;
+  private spokeBefore = false;
 
   constructor(option: VoiceGuidanceOption | undefined) {
     const resolved = resolveVoiceGuidance(option);
     this.enabled = resolved.enabled;
     this.language = resolved.language;
+    if (this.enabled) {
+      // Warm the engine NOW, not at the first phrase. Android's TextToSpeech
+      // initialises asynchronously, and when the user is well-positioned from
+      // the start the first thing this session ever says is the first GESTURE
+      // COMMAND — which then races engine init and loses: exactly the phrase
+      // a user holding the phone at arm's length cannot afford to miss. Any
+      // expo-speech call triggers init; voices is the harmless one. By the
+      // time positioning settles the engine is ready and the command plays
+      // immediately. iOS initialises synchronously and ignores the warm-up.
+      void Speech.getAvailableVoicesAsync().catch(() => undefined);
+    }
   }
 
   /** Speaks `text` unless guidance is off or it equals the last phrase spoken. */
@@ -42,7 +54,13 @@ export class LivenessSpeaker {
     if (!this.enabled || !text || text === this.lastSpoken) return;
     this.lastSpoken = text;
     try {
-      Speech.stop();
+      // stop() exists to cut off a STALE phrase so guidance stays current.
+      // Before anything has been spoken there is nothing to cut off — and on
+      // Android calling stop() against a still-initialising engine is exactly
+      // the poke that can eat the first queued utterance. Skip it until a
+      // phrase has actually been issued.
+      if (this.spokeBefore) Speech.stop();
+      this.spokeBefore = true;
       Speech.speak(text, { language: this.language });
     } catch {
       /* TTS is best-effort — a failure must never block the flow */

package/src/liveness/types.ts

@@ -32,11 +32,25 @@ export type LivenessPhase =
   | 'positioning' // "Position your face in the circle"
   | 'challenge' // Active gesture challenge
   | 'challenge_passed' // Brief green flash
+  // Screen-reflection liveness: the display emits a randomised colour sequence
+  // and the camera watches the face reflect it. Runs as the FINAL challenge, so
+  // by the time it starts the face is already positioned and steady.
+  | 'flash'
   | 'capturing' // Auto-capturing selfie
   | 'complete' // All done — selfie review
   | 'failed'; // Timeout or face lost
 
-export type LivenessFailureReason = 'timeout' | 'face_lost' | 'no_camera' | 'load_error';
+export type LivenessFailureReason =
+  | 'timeout'
+  | 'face_lost'
+  | 'no_camera'
+  | 'load_error'
+  /**
+   * A different face appeared mid-session. Liveness proves a live human
+   * performed the challenges; only continuity ties that human to the one being
+   * captured. Matches the web SDK's `face_swap`.
+   */
+  | 'face_swap';
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -47,12 +61,24 @@ export interface LivenessConfig {
   challengePool?: LivenessChallenge[];
   timeoutPerChallenge: number;
   positioningTimeout: number;
+  /**
+   * Which liveness method runs. 'gestures' (default) is the randomised head
+   * movements; 'flash' is screen reflection; 'both' runs gestures then flash,
+   * because each catches what the other misses — gestures defeat a static
+   * photo, flash defeats a replayed video.
+   */
+  mode?: LivenessMode;
+  /** Colours in the flash sequence (2–5, default 4). Flash modes only. */
+  flashSequenceLength?: number;
 }
 
+export type LivenessMode = 'gestures' | 'flash' | 'both';
+
 export const DEFAULT_LIVENESS_CONFIG: LivenessConfig = {
   challengeCount: 2,
   timeoutPerChallenge: 8,
   positioningTimeout: 15,
+  mode: 'gestures',
 };
 
 // ---------------------------------------------------------------------------
@@ -84,6 +110,27 @@ export interface LivenessFaceData {
   faceCount: number;
   /** Mean frame luma (0–255). Feeds the low-light gate (<62 dark, >200 bright). */
   brightness: number;
+  /**
+   * Face centre in normalised frame coordinates (0–1), when the detector
+   * reports it. Together with {@link faceSizeRatio} this is what distinguishes
+   * "the same face moved" from "a different face appeared" — size alone cannot,
+   * since two people at the same distance measure alike.
+   */
+  faceCenterX?: number;
+  faceCenterY?: number;
+  /**
+   * ML Kit's per-face tracking id (Android only; absent on iOS, whose Vision
+   * framework has no cross-frame equivalent). When present a CHANGE is proof of
+   * a different face — which is why it supplements the geometric continuity
+   * guard rather than being relied on alone.
+   */
+  trackingId?: number;
+  /**
+   * Mean RGB of the face region (0–255 each), for flash liveness. Absent when
+   * the platform could not sample it — flash then degrades to inconclusive,
+   * which fails soft, rather than to a wrong verdict.
+   */
+  faceRgb?: readonly [number, number, number];
 }
 
 /** Convenience: average of both eye-open probabilities. */

package/src/liveness/useFlashPhase.ts

@@ -0,0 +1,78 @@
+import { useCallback, useRef } from 'react';
+
+import type { FlashResult } from './flashDetector';
+import type { LivenessMode } from './types';
+import type { LivenessUiState } from './useLiveness';
+
+// ---------------------------------------------------------------------------
+// The flash phase's own state.
+//
+// Split out of useLiveness (200-line rule). Everything here is a REF rather
+// than state on purpose: the pending check is read from inside the challenge
+// transition, and a stale closure there would either skip the flash entirely or
+// run it twice.
+// ---------------------------------------------------------------------------
+
+export interface FlashPhase {
+  /** Whether the flash sequence still has to run. */
+  pending: () => boolean;
+  /** Called by the screen once the sequence finishes. */
+  complete: (result: FlashResult) => void;
+  /** The verdict, once run. */
+  result: () => FlashResult | null;
+  /** Face discontinuities seen this session. */
+  glitches: () => number;
+  recordGlitch: () => void;
+  /** Clears everything for a retry — including the colour sequence. */
+  reset: () => void;
+}
+
+export function useFlashPhase(
+  mode: LivenessMode | undefined,
+  setState: (updater: (s: LivenessUiState) => LivenessUiState) => void,
+): FlashPhase {
+  const doneRef = useRef(false);
+  const resultRef = useRef<FlashResult | null>(null);
+  const glitchesRef = useRef(0);
+
+  const pending = useCallback(
+    () => (mode === 'flash' || mode === 'both') && !doneRef.current,
+    [mode],
+  );
+
+  /**
+   * The result is carried into the submission as context, NOT used to fail the
+   * step: an inconclusive flash (sunlight, or a platform that cannot sample
+   * RGB) must not block a user, and the server re-analyses the recorded video
+   * regardless. A definite mismatch is what the server acts on.
+   */
+  const complete = useCallback(
+    (result: FlashResult) => {
+      doneRef.current = true;
+      resultRef.current = result;
+      setState((s) =>
+        s.phase === 'flash' ? { ...s, phase: 'capturing', instruction: 'Hold still…' } : s,
+      );
+    },
+    [setState],
+  );
+
+  const reset = useCallback(() => {
+    // A retry runs the whole check again, INCLUDING a fresh colour sequence —
+    // reusing the previous one would hand an attacker the answer.
+    doneRef.current = false;
+    resultRef.current = null;
+    glitchesRef.current = 0;
+  }, []);
+
+  return {
+    pending,
+    complete,
+    result: () => resultRef.current,
+    glitches: () => glitchesRef.current,
+    recordGlitch: () => {
+      glitchesRef.current += 1;
+    },
+    reset,
+  };
+}