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

package/src/liveness/faceContinuity.ts

@@ -0,0 +1,153 @@
+import type { LivenessFaceData } from './types';
+
+// ─── Face continuity ──────────────────────────────────────────────────────────
+//
+// "Is this the same face it was a moment ago?"
+//
+// Liveness proves a live human performed the challenges. It proves nothing about
+// WHO unless the face that performed them is the face that gets captured —
+// otherwise one person can nod and blink while another is photographed, and
+// every gesture check passes on the wrong person.
+//
+// Nothing here identifies anyone. It tracks whether the face in frame is
+// CONTINUOUS with the one before it, which is all that is needed to reject a
+// substitution:
+//
+//   • a jump — the face leaps across the frame or changes size abruptly. Real
+//     heads move continuously at 15–30fps; a cut to another person does not.
+//   • a gap — the face left and a different one arrived. After a loss nothing
+//     vouches that the returning face is the same person, so progress earned
+//     before the gap is not carried across it.
+//   • a changed tracking id, where the platform provides one (Android ML Kit;
+//     Apple Vision has no cross-frame equivalent). Proof rather than inference,
+//     so it is used when present and never depended upon.
+//
+// Ported from the Flutter SDK's lib/src/liveness/face_continuity.dart — same
+// thresholds, same reasoning. Pure logic, so the thresholds are testable.
+
+export type FaceContinuity =
+  /** Same face, still tracked. */
+  | 'same'
+  /**
+   * A different face. The session cannot carry on: whoever performed the
+   * challenges is not who is in frame now.
+   */
+  | 'substituted'
+  /**
+   * The face returned after being absent. Not proof of substitution — people
+   * look away — but nothing vouches for it either, so anything already earned
+   * must be re-earned.
+   */
+  | 'reacquired';
+
+export interface FaceContinuityOptions {
+  /**
+   * How far the face centre may travel between consecutive frames, as a share
+   * of the frame. Generous: at 15fps a real head covers ground, and the cost of
+   * a false positive is a user being told to start again.
+   */
+  maxCentreJump?: number;
+  /**
+   * Largest allowed frame-to-frame change in face size, as a ratio. A face that
+   * suddenly measures 1.6× its previous size is a different face, not someone
+   * leaning in.
+   */
+  maxSizeRatioChange?: number;
+  /**
+   * A gap longer than this means the returning face is unvouched for. Short
+   * enough to catch a camera pan between two people, long enough to survive the
+   * dropped frames a colour flash causes.
+   */
+  maxGapMs?: number;
+}
+
+export class FaceContinuityGuard {
+  private readonly maxCentreJump: number;
+  private readonly maxSizeRatioChange: number;
+  private readonly maxGapMs: number;
+
+  private centreX: number | null = null;
+  private centreY: number | null = null;
+  private size: number | null = null;
+  private trackingId: number | null = null;
+  private lastSeen: number | null = null;
+
+  constructor(options: FaceContinuityOptions = {}) {
+    this.maxCentreJump = options.maxCentreJump ?? 0.35;
+    this.maxSizeRatioChange = options.maxSizeRatioChange ?? 1.6;
+    this.maxGapMs = options.maxGapMs ?? 900;
+  }
+
+  /**
+   * Forget everything — call when the flow restarts and the previous face is no
+   * longer the reference.
+   */
+  reset(): void {
+    this.centreX = null;
+    this.centreY = null;
+    this.size = null;
+    this.trackingId = null;
+    this.lastSeen = null;
+  }
+
+  /**
+   * Records that no face was visible. The stored position is KEPT: it is the
+   * comparison point for whatever comes back, and it is `lastSeen` ageing that
+   * turns an absence into a gap.
+   */
+  reportNoFace(): void {}
+
+  /** Feeds a frame and reports what it means for continuity. */
+  update(data: LivenessFaceData, nowMs: number): FaceContinuity {
+    const lastSeen = this.lastSeen;
+    const prevX = this.centreX;
+    const prevY = this.centreY;
+    const prevSize = this.size;
+    const prevTrack = this.trackingId;
+
+    this.lastSeen = nowMs;
+    this.centreX = data.faceCenterX ?? null;
+    this.centreY = data.faceCenterY ?? null;
+    this.size = data.faceSizeRatio;
+    if (data.trackingId != null && data.trackingId >= 0) {
+      this.trackingId = data.trackingId;
+    }
+
+    // Nothing to compare against yet.
+    if (lastSeen === null) return 'same';
+
+    // A tracking id that changed is proof, where the platform offers one.
+    if (
+      prevTrack != null &&
+      data.trackingId != null &&
+      data.trackingId >= 0 &&
+      data.trackingId !== prevTrack
+    ) {
+      return 'substituted';
+    }
+
+    // A gap: the face was away long enough that nothing vouches for its return.
+    if (nowMs - lastSeen > this.maxGapMs) return 'reacquired';
+
+    // A jump: continuous frames, discontinuous face.
+    if (
+      prevX != null &&
+      prevY != null &&
+      data.faceCenterX != null &&
+      data.faceCenterY != null
+    ) {
+      const dx = Math.abs(data.faceCenterX - prevX);
+      const dy = Math.abs(data.faceCenterY - prevY);
+      if (dx > this.maxCentreJump || dy > this.maxCentreJump) return 'substituted';
+    }
+
+    if (prevSize != null && prevSize > 0.01 && data.faceSizeRatio > 0.01) {
+      const ratio = data.faceSizeRatio / prevSize;
+      if (ratio > this.maxSizeRatioChange || ratio < 1 / this.maxSizeRatioChange) {
+        return 'substituted';
+      }
+    }
+
+    return 'same';
+  }
+}

package/src/liveness/flashDetector.ts

@@ -0,0 +1,145 @@
+// ---------------------------------------------------------------------------
+// Flash (screen-reflection) liveness — the pure correlation core.
+//
+// The screen emits a short RANDOMIZED colour sequence while the camera records;
+// a live face physically reflects those colours in that order. A replayed
+// video, an injected feed, or a screen held up to the camera emits its own
+// light and cannot match a sequence that did not exist until this session
+// started. That is the whole anti-replay property, and it is why the sequence
+// must be generated fresh per session and never reused.
+//
+// No camera or native dependency here: the caller feeds face-region RGB
+// samples. That is what makes the physics testable with synthetic numbers.
+//
+// The palette names and the dominance formula are a CONTRACT WITH THE SERVER.
+// `src/docbio/analysis.ts` re-analyses the recorded video with the same palette
+// and the same test, then LCS-matches what it detects against the sequence the
+// client claims. If the two sides measured different things, an honest client
+// would look like a mismatch — so this mirrors the server exactly, including
+// using the positive-shift SHARE rather than a vector projection.
+// ---------------------------------------------------------------------------
+
+export interface FlashColor {
+  /** Stable name — this is what the claim and the server's analysis compare. */
+  name: string;
+  /** Colour painted over the screen. */
+  css: string;
+  /** Which RGB channels a live reflection should shift along. */
+  boost: [number, number, number];
+}
+
+/** High-luminance primaries — maximum reflected signal per channel. */
+export const FLASH_PALETTE: readonly FlashColor[] = [
+  { name: 'red', css: '#ff2020', boost: [1, 0, 0] },
+  { name: 'green', css: '#20ff40', boost: [0, 1, 0] },
+  { name: 'blue', css: '#2050ff', boost: [0, 0, 1] },
+  { name: 'magenta', css: '#ff20d0', boost: [1, 0, 1] },
+  { name: 'cyan', css: '#20ffe0', boost: [0, 1, 1] },
+];
+
+/**
+ * Minimum shift magnitude (0–255 scale) for a flash to be measurable. Below it
+ * the ambient light drowned the reflection — inconclusive, not failed.
+ */
+export const MIN_SHIFT_MAGNITUDE = 3;
+
+/** The share of the positive shift that must lie on the boosted channels. */
+export const DOMINANCE_THRESHOLD = 0.55;
+
+/** Colours in a sequence. More is harder to spoof but longer to sit through. */
+export const MIN_FLASH_SEQUENCE = 2;
+export const MAX_FLASH_SEQUENCE = 5;
+export const DEFAULT_FLASH_SEQUENCE = 4;
+
+export type Rgb = readonly [number, number, number];
+
+/**
+ * A fresh random sequence.
+ *
+ * `random` is injectable so tests can pin the order; production must use real
+ * randomness — a predictable sequence is a replayable one, which defeats the
+ * entire check.
+ */
+export function generateFlashSequence(
+  count = DEFAULT_FLASH_SEQUENCE,
+  random: () => number = Math.random,
+): FlashColor[] {
+  const pool = [...FLASH_PALETTE];
+  for (let i = pool.length - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1));
+    [pool[i], pool[j]] = [pool[j]!, pool[i]!];
+  }
+  const n = Math.min(MAX_FLASH_SEQUENCE, Math.max(MIN_FLASH_SEQUENCE, Math.round(count)));
+  return pool.slice(0, n);
+}
+
+export interface FlashSample {
+  /** The ambient light drowned the flash — no verdict either way. */
+  inconclusive: boolean;
+  matched: boolean;
+  /** Boosted-channel share of the positive shift (0–1); 0 when inconclusive. */
+  dominance: number;
+}
+
+/**
+ * Correlate one flash: did the face's colour shift the way this flash should
+ * have made it shift?
+ *
+ * `baseline` and `lit` are mean face-region RGB (0–255) from immediately before
+ * and during the flash. Taking the baseline per-flash rather than once tracks
+ * ambient drift — someone walking under a light mid-sequence would otherwise
+ * look like a failure.
+ */
+export function correlateFlash(baseline: Rgb, lit: Rgb, boost: Rgb): FlashSample {
+  const shift = [lit[0] - baseline[0], lit[1] - baseline[1], lit[2] - baseline[2]];
+  const magnitude = Math.abs(shift[0]!) + Math.abs(shift[1]!) + Math.abs(shift[2]!);
+  if (magnitude < MIN_SHIFT_MAGNITUDE) {
+    return { inconclusive: true, matched: false, dominance: 0 };
+  }
+
+  // Only the POSITIVE shift counts: a flash adds light, it never removes it, so
+  // a channel that dropped is noise (or the previous flash decaying) rather
+  // than evidence about this one.
+  const totalPositive = shift.reduce((acc, v) => acc + Math.max(0, v!), 0);
+  const boosted = shift.reduce((acc, v, i) => acc + Math.max(0, v!) * boost[i]!, 0);
+  const dominance = totalPositive > 0 ? boosted / totalPositive : 0;
+
+  return { inconclusive: false, matched: dominance >= DOMINANCE_THRESHOLD, dominance };
+}
+
+export interface FlashResult {
+  passed: boolean;
+  /** Matched / measurable (0–1). */
+  score: number;
+  matched: number;
+  total: number;
+  inconclusive: number;
+  /** The colours emitted, in order — the claim the server checks the video against. */
+  sequence: string[];
+}
+
+/**
+ * Aggregate the per-flash samples.
+ *
+ * Two thirds of the MEASURABLE flashes must match. Flashes the ambient light
+ * drowned are excluded rather than counted against the user: a phone in direct
+ * sunlight cannot reflect a screen, and failing people for standing outdoors
+ * would be a worse error than missing a spoof — which is why an all-inconclusive
+ * run passes soft. Paper-photo and mask attacks are the gesture checks' job.
+ */
+export function evaluateFlashSequence(
+  sequence: readonly FlashColor[],
+  samples: readonly FlashSample[],
+): FlashResult {
+  const measurable = samples.filter((s) => !s.inconclusive);
+  const matched = measurable.filter((s) => s.matched).length;
+  const inconclusive = samples.length - measurable.length;
+  return {
+    passed: measurable.length === 0 || matched >= Math.ceil(measurable.length * 0.66),
+    score: measurable.length === 0 ? 0 : matched / measurable.length,
+    matched,
+    total: samples.length,
+    inconclusive,
+    sequence: sequence.map((c) => c.name),
+  };
+}

package/src/liveness/flashReadyGate.ts

@@ -0,0 +1,106 @@
+// ---------------------------------------------------------------------------
+// Flash-ready gate — decides WHEN a flash-only sequence may start.
+//
+// Pure logic, no camera and no component, so the timing is unit-tested rather
+// than tuned on a device.
+//
+// It exists because flash-only mode otherwise flashes the instant a face is at
+// a good distance, off a SINGLE frame, before lighting has been confirmed. That
+// is survivable in the gesture flow — the challenges take seconds and re-check
+// framing throughout — but flash mode has no such buffer: nothing follows the
+// flash, so the "come closer / more light" guidance never gets a chance to show
+// and the screen flashes at a face that was merely passing through frame.
+//
+// Three conditions, each earning its place:
+//   • FRAMED  — the face is at the right distance (no position warning).
+//   • LIT     — no lighting warning. But "no warning" is ambiguous until the
+//     brightness sampler has produced a reading: during warm-up lighting is
+//     UNKNOWN, not confirmed-good, so a dim room would read as fine and flash
+//     with no "more light" prompt. Hence `lightingConfirmed` gates separately.
+//   • DWELL   — framed+lit held CONTINUOUSLY for a visible moment, so a face
+//     crossing through the right distance doesn't trigger, and the guidance and
+//     a "hold still" beat land before the screen lights up.
+//
+// Ported from the Flutter SDK's FlashReadyGate — keep the two in step.
+// ---------------------------------------------------------------------------
+
+/** How long framed+lit must hold before flashing. */
+export const FLASH_READY_DWELL_MS = 1200;
+
+/**
+ * Safety valve: if framing is good but the sampler NEVER confirms lighting
+ * (sampling unsupported or failing on this device), proceed anyway after this
+ * so the user is never stuck on a permanent "hold still".
+ *
+ * Longer than the dwell AND the sampler's warm-up, so a healthy device always
+ * confirms lighting first and this never fires in the normal case.
+ */
+export const FLASH_LIGHTING_WAIT_MS = 3000;
+
+/** The gate's verdict for one frame. */
+export interface FlashReadyState {
+  /** Start the flash now. */
+  ready: boolean;
+  /** 0..1 across the dwell, for a "getting ready" indicator. */
+  progress: number;
+}
+
+const NOT_READY: FlashReadyState = { ready: false, progress: 0 };
+
+/**
+ * Tracks the framed+lit hold across frames. One instance per liveness attempt;
+ * `reset()` reuses it for a retry.
+ */
+export class FlashReadyGate {
+  private heldSince: number | null = null;
+
+  constructor(
+    private readonly dwellMs: number = FLASH_READY_DWELL_MS,
+    private readonly lightingWaitMs: number = FLASH_LIGHTING_WAIT_MS,
+  ) {}
+
+  reset(): void {
+    this.heldSince = null;
+  }
+
+  /**
+   * Feed one frame's verdict.
+   *
+   * @param framed            face at the right distance (no position warning)
+   * @param lit               no lighting warning — note this is also true while
+   *                          lighting is still UNKNOWN, which is why
+   *                          `lightingConfirmed` is separate
+   * @param lightingConfirmed the sampler has produced at least one real reading
+   * @param now               injected clock, so tests are deterministic
+   */
+  update({
+    framed,
+    lit,
+    lightingConfirmed,
+    now,
+  }: {
+    framed: boolean;
+    lit: boolean;
+    lightingConfirmed: boolean;
+    now: number;
+  }): FlashReadyState {
+    // Any break in framing or lighting restarts the hold — the point is a
+    // CONTINUOUS steady moment, not a cumulative one.
+    if (!framed || !lit) {
+      this.heldSince = null;
+      return NOT_READY;
+    }
+
+    if (this.heldSince === null) this.heldSince = now;
+    const held = now - this.heldSince;
+
+    // Lighting still unmeasured: keep holding, but don't hold forever on a
+    // device whose sampler never reports.
+    if (!lightingConfirmed && held < this.lightingWaitMs) {
+      return { ready: false, progress: Math.min(held / this.dwellMs, 0.99) };
+    }
+
+    if (held >= this.dwellMs) return { ready: true, progress: 1 };
+    return { ready: false, progress: held / this.dwellMs };
+  }
+}

package/src/liveness/flashRunner.ts

@@ -0,0 +1,118 @@
+import {
+  correlateFlash,
+  evaluateFlashSequence,
+  generateFlashSequence,
+  type FlashColor,
+  type FlashResult,
+  type FlashSample,
+  type Rgb,
+} from './flashDetector';
+
+// ---------------------------------------------------------------------------
+// Driving the flash sequence.
+//
+// The detector knows the physics; this knows the choreography — paint a colour,
+// wait for the screen and camera to catch up, average the face's colour over a
+// window, and compare it with the neutral moment immediately before.
+//
+// The baseline is re-taken BEFORE EACH FLASH rather than once at the start.
+// Ambient light drifts (someone walks past a window, an auto-exposure kicks
+// in), and a single stale baseline would turn that drift into a fake shift on
+// every subsequent flash.
+// ---------------------------------------------------------------------------
+
+/** How long each phase of one flash takes. */
+export const FLASH_TIMING = {
+  /** Neutral settle before measuring the baseline. */
+  neutralMs: 150,
+  /** Baseline measurement window. */
+  baselineMs: 300,
+  /**
+   * Screen paint → camera exposure latency. Measuring during this window would
+   * average lit frames together with unlit ones and dilute the shift.
+   */
+  litSettleMs: 200,
+  /** Lit measurement window. */
+  litMs: 450,
+} as const;
+
+/** Roughly one sample per camera frame at 15fps. */
+const SAMPLE_INTERVAL_MS = 66;
+
+export interface FlashRunnerDeps {
+  /** Paints the fullscreen overlay; null clears it back to neutral. */
+  setColor: (css: string | null) => void;
+  /** The most recent face RGB, or null when the face was not sampled. */
+  readFaceRgb: () => Rgb | null;
+  /** False once the caller has gone away (unmount, retry, abort). */
+  isActive: () => boolean;
+  /** Injectable for tests; production uses setTimeout. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const realSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Average the face RGB over a window, or null if nothing could be read. */
+async function sampleWindow(
+  deps: FlashRunnerDeps,
+  durationMs: number,
+  sleep: (ms: number) => Promise<void>,
+): Promise<Rgb | null> {
+  const samples: Rgb[] = [];
+  let elapsed = 0;
+  while (elapsed < durationMs && deps.isActive()) {
+    const rgb = deps.readFaceRgb();
+    if (rgb) samples.push(rgb);
+    await sleep(SAMPLE_INTERVAL_MS);
+    elapsed += SAMPLE_INTERVAL_MS;
+  }
+  if (samples.length === 0) return null;
+  const total = samples.reduce<[number, number, number]>(
+    (acc, s) => [acc[0] + s[0], acc[1] + s[1], acc[2] + s[2]],
+    [0, 0, 0],
+  );
+  return [total[0] / samples.length, total[1] / samples.length, total[2] / samples.length];
+}
+
+/**
+ * Run the whole sequence and return the verdict.
+ *
+ * The overlay is ALWAYS cleared on the way out, including on an abort — leaving
+ * a full-screen colour painted over a stopped flow would strand the user on a
+ * red screen with no way back.
+ */
+export async function runFlashSequence(
+  deps: FlashRunnerDeps,
+  sequence: FlashColor[] = generateFlashSequence(),
+): Promise<FlashResult> {
+  const sleep = deps.sleep ?? realSleep;
+  const samples: FlashSample[] = [];
+
+  try {
+    for (const flash of sequence) {
+      if (!deps.isActive()) break;
+
+      deps.setColor(null);
+      await sleep(FLASH_TIMING.neutralMs);
+      const baseline = await sampleWindow(deps, FLASH_TIMING.baselineMs, sleep);
+
+      deps.setColor(flash.css);
+      await sleep(FLASH_TIMING.litSettleMs);
+      const lit = await sampleWindow(deps, FLASH_TIMING.litMs, sleep);
+
+      if (!baseline || !lit) {
+        // The face left the frame, or the platform cannot sample RGB at all.
+        // Unmeasured is not failed — it joins the inconclusive pile, which
+        // fails soft.
+        samples.push({ inconclusive: true, matched: false, dominance: 0 });
+        continue;
+      }
+      samples.push(correlateFlash(baseline, lit, flash.boost));
+    }
+  } finally {
+    deps.setColor(null);
+  }
+
+  return evaluateFlashSequence(sequence, samples);
+}

package/src/liveness/integritySignals.ts

@@ -0,0 +1,60 @@
+import type { FlashResult } from './flashDetector';
+import type { LivenessMode } from './types';
+
+// ---------------------------------------------------------------------------
+// Capture-integrity signals.
+//
+// What the client observed while capturing, sent as context alongside the
+// verification. The server persists these on `deviceMetadata.integrity` and —
+// crucially — re-analyses the recorded liveness video against the flash
+// SEQUENCE claimed here. That check is why the claim matters: a client can
+// report whatever it likes, but it cannot make a video reflect colours it never
+// emitted.
+//
+// So none of this is trusted as a verdict. It is the claim the server audits.
+// ---------------------------------------------------------------------------
+
+export interface LivenessIntegrity {
+  mode: LivenessMode;
+  /** How many consecutive-frame discontinuities the continuity guard saw. */
+  faceGlitches: number;
+  flash?: {
+    passed: boolean;
+    score: number;
+    matched: number;
+    total: number;
+    inconclusive: boolean;
+    /** The colours emitted, in order — what the server checks the video for. */
+    sequence: string[];
+  };
+}
+
+export interface CaptureIntegrity {
+  liveness: LivenessIntegrity;
+}
+
+export function buildLivenessIntegrity(
+  mode: LivenessMode,
+  faceGlitches: number,
+  flash: FlashResult | null,
+): LivenessIntegrity {
+  return {
+    mode,
+    faceGlitches,
+    ...(flash
+      ? {
+          flash: {
+            passed: flash.passed,
+            score: flash.score,
+            matched: flash.matched,
+            total: flash.total,
+            // Collapsed to a boolean for the wire: the server only needs to
+            // know whether the run was unmeasurable, not how many individual
+            // flashes were drowned.
+            inconclusive: flash.total > 0 && flash.inconclusive === flash.total,
+            sequence: flash.sequence,
+          },
+        }
+      : {}),
+  };
+}