@velion-la/onboarding-sdk-react-native 1.0.0-beta.2 → 1.0.0-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/lib/commonjs/camera/LivenessCamera.js +85 -6
  2. package/lib/commonjs/camera/LivenessCamera.js.map +1 -1
  3. package/lib/commonjs/core/VelionOnboarding.js +3 -0
  4. package/lib/commonjs/core/VelionOnboarding.js.map +1 -1
  5. package/lib/commonjs/i18n/strings/en.js +1 -0
  6. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  7. package/lib/commonjs/i18n/strings/es.js +1 -0
  8. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  9. package/lib/commonjs/steps/DocumentsOcrStep.js +8 -4
  10. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  11. package/lib/commonjs/steps/LivenessMatchStep.js +493 -16
  12. package/lib/commonjs/steps/LivenessMatchStep.js.map +1 -1
  13. package/lib/commonjs/types/index.js +16 -0
  14. package/lib/commonjs/types/index.js.map +1 -1
  15. package/lib/module/camera/LivenessCamera.js +86 -7
  16. package/lib/module/camera/LivenessCamera.js.map +1 -1
  17. package/lib/module/core/VelionOnboarding.js +3 -0
  18. package/lib/module/core/VelionOnboarding.js.map +1 -1
  19. package/lib/module/i18n/strings/en.js +1 -0
  20. package/lib/module/i18n/strings/en.js.map +1 -1
  21. package/lib/module/i18n/strings/es.js +1 -0
  22. package/lib/module/i18n/strings/es.js.map +1 -1
  23. package/lib/module/steps/DocumentsOcrStep.js +9 -5
  24. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  25. package/lib/module/steps/LivenessMatchStep.js +492 -16
  26. package/lib/module/steps/LivenessMatchStep.js.map +1 -1
  27. package/lib/module/types/index.js +19 -0
  28. package/lib/module/types/index.js.map +1 -1
  29. package/lib/typescript/camera/LivenessCamera.d.ts +18 -1
  30. package/lib/typescript/camera/LivenessCamera.d.ts.map +1 -1
  31. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  32. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  33. package/lib/typescript/i18n/strings/es.d.ts +1 -0
  34. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  35. package/lib/typescript/steps/LivenessMatchStep.d.ts.map +1 -1
  36. package/lib/typescript/steps/types.d.ts +7 -1
  37. package/lib/typescript/steps/types.d.ts.map +1 -1
  38. package/lib/typescript/types/index.d.ts +57 -0
  39. package/lib/typescript/types/index.d.ts.map +1 -1
  40. package/package.json +1 -1
  41. package/src/camera/LivenessCamera.tsx +100 -3
  42. package/src/core/VelionOnboarding.ts +3 -0
  43. package/src/i18n/strings/en.ts +1 -0
  44. package/src/i18n/strings/es.ts +1 -0
  45. package/src/steps/DocumentsOcrStep.tsx +7 -3
  46. package/src/steps/LivenessMatchStep.tsx +522 -17
  47. package/src/steps/types.ts +7 -1
  48. package/src/types/index.ts +61 -0
@@ -18,6 +18,13 @@
18
18
 
19
19
  import { useCallback, useEffect, useRef, useState } from 'react';
20
20
  import { ScrollView, StyleSheet, Text, View } from 'react-native';
21
+ // `expo-file-system` v19's `File` class wraps a `file://` path with a Blob-
22
+ // compatible API (`arrayBuffer`, `size`, `delete`). We read the recorded mp4
23
+ // to bytes in JS and PUT them with the global `fetch`. For the typical
24
+ // 1–5 MB session video this is well within the bridge budget; if the
25
+ // recorded files grow significantly we can switch to a streaming uploader
26
+ // without changing the call sites.
27
+ import { File as FsFile } from 'expo-file-system';
21
28
  import * as ImageManipulator from 'expo-image-manipulator';
22
29
  import { SdkErrorCode } from '../types';
23
30
  import { Banner } from '../ui/primitives/Banner';
@@ -38,8 +45,39 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
38
45
  const FRAME_MS_DEFAULT = 350;
39
46
  const FRAME_MS_TURN = 220;
40
47
  const PROGRESS_WATCHDOG_MS = 25_000;
48
+ /**
49
+ * Hard ceiling for the POST /liveness-verify call that runs after
50
+ * SESSION_COMPLETE. The progress watchdog is already off by then, so an
51
+ * unbounded fetch (the dev network shows recurring HTTP/2 stream resets)
52
+ * would strand the user on the analyzing overlay forever.
53
+ */
54
+ const LIVENESS_VERIFY_TIMEOUT_MS = 20_000;
41
55
  const FRAME_MAX_LONG_EDGE = 720;
42
56
  const FRAME_QUALITY = 0.55;
57
+ /**
58
+ * Hard ceiling for the video upload PUT to GCS that runs between SESSION_COMPLETE
59
+ * and POST /liveness-verify. Long enough for a 5 MB upload on a slow mobile link
60
+ * but short enough that a stalled connection can't keep the user on the
61
+ * analyzing overlay indefinitely. On timeout we fall back to verify-without-body.
62
+ */
63
+ /**
64
+ * Hard ceiling for the video upload PUT to GCS that runs between
65
+ * SESSION_COMPLETE and POST /liveness-verify. The signed URL TTL is 10 min,
66
+ * so 60 s leaves comfortable headroom for a typical 1–5 MB session video
67
+ * over a slow mobile uplink. On timeout we fall back to verify-without-body.
68
+ */
69
+ const VIDEO_UPLOAD_TIMEOUT_MS = 60_000;
70
+ // Upper bound for vision-camera to deliver `onRecordingFinished` after
71
+ // `stopRecording()` resolves. Observed ~50–200 ms in practice; we set the
72
+ // cap generously so a slow flush on older Androids doesn't strand the
73
+ // failure path waiting for a signal that's just running late.
74
+ const RECORDING_FINISH_TIMEOUT_MS = 3_000;
75
+ const VIDEO_CONTENT_TYPE = 'video/mp4';
76
+
77
+ /** Returns the first 80 chars of a URL — enough to spot the bucket without dumping the V4 signature. */
78
+ function truncateUrl(url) {
79
+ return url.length <= 80 ? url : `${url.slice(0, 80)}…`;
80
+ }
43
81
  export class LivenessMatchStep {
44
82
  destroyed = false;
45
83
  constructor(deps) {
@@ -56,6 +94,7 @@ export class LivenessMatchStep {
56
94
  calibrationLabel: this.deps.livenessCalibrationLabel,
57
95
  showIntro: true,
58
96
  showBackButton: true,
97
+ onVideoUploaded: this.deps.onLivenessVideoUploaded,
59
98
  onComplete: () => {
60
99
  if (this.destroyed) return;
61
100
  this.deps.ui.setNode(null);
@@ -81,6 +120,7 @@ function LivenessMatchView({
81
120
  calibrationLabel,
82
121
  showIntro,
83
122
  showBackButton,
123
+ onVideoUploaded,
84
124
  onComplete,
85
125
  onCancel
86
126
  }) {
@@ -121,6 +161,38 @@ function LivenessMatchView({
121
161
  // warnings flash in <2s and the user couldn't read them).
122
162
  const activeToastRef = useRef(null);
123
163
 
164
+ // ── Video recording state (OSDKR-4) ─────────────────────────────────────
165
+ // `videoUploadRef` holds the signed URL returned by /liveness-init when the
166
+ // backend enabled video capture for this session. `null` → skip recording.
167
+ const videoUploadRef = useRef(null);
168
+ // Current state of the video pipeline. Best-effort: any value other than
169
+ // `'uploaded'` ends up calling /liveness-verify WITHOUT a body — liveness
170
+ // still completes normally.
171
+
172
+ const videoOutcomeRef = useRef('none');
173
+ // Filled in when the GCS PUT returns 200; consumed by the verify call.
174
+ const videoMetaRef = useRef(null);
175
+ // Resolves when the upload (success or failure path) is fully settled. The
176
+ // SESSION_COMPLETE handler awaits this with a bounded timeout before calling
177
+ // /liveness-verify so the metadata, if any, makes it into the body.
178
+ const videoUploadPromiseRef = useRef(null);
179
+ // Resolves as soon as vision-camera fires `onRecordingFinished` (i.e. when
180
+ // the mp4 file is fully written and `uploadRecordedVideo` has been kicked
181
+ // off — fetch is in flight but not yet complete). `failWith` awaits this with
182
+ // a short timeout so the upload's underlying fetch is *started* before the
183
+ // step is torn down. After the unmount the fetch closure keeps its own refs
184
+ // alive and the PUT to GCS completes in the background.
185
+ const videoRecordingFinishedPromiseRef = useRef(null);
186
+ // Local file system path of the temp mp4. Tracked so the unmount cleanup
187
+ // can delete it if the user backs out before the upload finished.
188
+ const videoTempPathRef = useRef(null);
189
+ // Cached so `failWith` / unmount can invoke the callback with the prop
190
+ // captured at start, even if the host re-renders.
191
+ const onVideoUploadedRef = useRef(onVideoUploaded);
192
+ useEffect(() => {
193
+ onVideoUploadedRef.current = onVideoUploaded;
194
+ }, [onVideoUploaded]);
195
+
124
196
  // Each toast stays on screen at least this long. The orchestrator can spam
125
197
  // WARNINGs (POSITIONING_REQUIRED, SPOOF_RISK_HIGH, …) several times per
126
198
  // second; without a floor the user literally cannot read them.
@@ -167,17 +239,275 @@ function LivenessMatchView({
167
239
  }
168
240
  inFlightRef.current = false;
169
241
  }, []);
242
+
243
+ // ── Video upload pipeline (OSDKR-4) ─────────────────────────────────────
244
+ // Everything below is best-effort: never throws into the caller; never
245
+ // blocks liveness completion. The worst case is `videoOutcomeRef = 'failed'`
246
+ // and verify being called without a body.
247
+ const deleteVideoTemp = useCallback(path => {
248
+ if (!path) return;
249
+ try {
250
+ // `File.delete()` is synchronous in expo-file-system v19.
251
+ new FsFile(path).delete();
252
+ } catch {
253
+ // Best-effort cleanup; we can't do much if rm fails.
254
+ }
255
+ }, []);
256
+ const uploadRecordedVideo = useCallback(async video => {
257
+ const target = videoUploadRef.current;
258
+ videoTempPathRef.current = video.path;
259
+ if (!target) {
260
+ log.warn('[Liveness] video upload skipped: no signed URL in init response');
261
+ videoOutcomeRef.current = 'failed';
262
+ deleteVideoTemp(video.path);
263
+ videoTempPathRef.current = null;
264
+ return;
265
+ }
266
+ const durationMs = typeof video.duration === 'number' && isFinite(video.duration) ? Math.round(video.duration * 1000) : null;
267
+ let sizeBytes = null;
268
+ let file = null;
269
+ try {
270
+ file = new FsFile(video.path);
271
+ sizeBytes = typeof file.size === 'number' ? file.size : null;
272
+ } catch (err) {
273
+ log.warn('[Liveness] could not stat video file before upload', err);
274
+ }
275
+ log.info('[Liveness] video upload starting', {
276
+ url: truncateUrl(target.upload_url),
277
+ method: target.method,
278
+ contentType: VIDEO_CONTENT_TYPE,
279
+ path: video.path,
280
+ sizeBytes,
281
+ durationMs
282
+ });
283
+ const t0 = Date.now();
284
+ try {
285
+ // Build a NATIVE React Native Blob from the `file://` URI: fetching
286
+ // the local path returns a Response whose `.blob()` is the BlobModule
287
+ // implementation that the bridge actually knows how to upload. Using
288
+ // the expo-file-system `File` directly silently sends an empty body
289
+ // (GCS responds 200 with a 0-byte object — exactly what we hit
290
+ // before). Reading the bytes through the native Blob keeps the data
291
+ // on the native side and uploads streamed from disk.
292
+ const fileUri = video.path.startsWith('file://') ? video.path : `file://${video.path}`;
293
+ const nativeBlob = await (await fetch(fileUri)).blob();
294
+ log.info('[Liveness] video upload body prepared', {
295
+ blobSize: nativeBlob.size,
296
+ blobType: nativeBlob.type
297
+ });
298
+ const result = await fetch(target.upload_url, {
299
+ method: 'PUT',
300
+ headers: {
301
+ 'Content-Type': VIDEO_CONTENT_TYPE
302
+ },
303
+ body: nativeBlob
304
+ });
305
+ const elapsedMs = Date.now() - t0;
306
+ if (result.ok) {
307
+ log.info('[Liveness] video upload ok', {
308
+ status: result.status,
309
+ elapsedMs,
310
+ sizeBytes
311
+ });
312
+ videoOutcomeRef.current = 'uploaded';
313
+ videoMetaRef.current = {
314
+ content_type: VIDEO_CONTENT_TYPE,
315
+ duration_ms: durationMs
316
+ };
317
+ // Invoke the host callback BEFORE cleanup so the path stays valid
318
+ // for any synchronous host work (rare, but cheap to guarantee).
319
+ try {
320
+ onVideoUploadedRef.current?.({
321
+ upload_url: target.upload_url,
322
+ content_type: VIDEO_CONTENT_TYPE,
323
+ duration_ms: durationMs,
324
+ size_bytes: sizeBytes
325
+ });
326
+ } catch (err) {
327
+ log.warn('[Liveness] onLivenessVideoUploaded threw', err);
328
+ }
329
+ } else {
330
+ // Try to extract the GCS error XML — its body tells us exactly which
331
+ // permission / signature param failed (otherwise we are blind).
332
+ let responseSnippet = '';
333
+ try {
334
+ responseSnippet = (await result.text()).slice(0, 400);
335
+ } catch {
336
+ /* body not readable; status alone is the signal */
337
+ }
338
+ log.warn('[Liveness] video upload non-200', {
339
+ status: result.status,
340
+ elapsedMs,
341
+ sizeBytes,
342
+ body: responseSnippet
343
+ });
344
+ videoOutcomeRef.current = 'failed';
345
+ }
346
+ } catch (err) {
347
+ log.warn('[Liveness] video upload error', {
348
+ elapsedMs: Date.now() - t0,
349
+ sizeBytes,
350
+ err
351
+ });
352
+ videoOutcomeRef.current = 'failed';
353
+ } finally {
354
+ deleteVideoTemp(video.path);
355
+ videoTempPathRef.current = null;
356
+ }
357
+ }, [deleteVideoTemp]);
358
+ const startVideoRecordingIfEnabled = useCallback(() => {
359
+ if (!videoUploadRef.current) {
360
+ log.info('[Liveness] video skipped: no video_upload in liveness-init');
361
+ return;
362
+ }
363
+ const camera = cameraRef.current;
364
+ if (!camera) {
365
+ log.warn('[Liveness] video skipped: LivenessCamera ref not ready at SESSION_READY');
366
+ return;
367
+ }
368
+ log.info('[Liveness] video recording starting', {
369
+ uploadUrl: truncateUrl(videoUploadRef.current.upload_url),
370
+ expiresAt: videoUploadRef.current.expires_at
371
+ });
372
+ // Pre-assign the upload promise BEFORE calling startRecording. vision-camera
373
+ // dispatches `onRecordingFinished` on a separate microtask from the
374
+ // `stopRecording()` resolution, so a "set the promise inside the callback"
375
+ // pattern races SESSION_COMPLETE — the verify POST fires before
376
+ // `uploadRecordedVideo` is even invoked, and the body ends up empty.
377
+ // The Deferred resolves once the recording's success/error path is fully
378
+ // settled (including the upload PUT and the cleanup).
379
+ let settle = () => {};
380
+ let settled = false;
381
+ videoUploadPromiseRef.current = new Promise(resolve => {
382
+ settle = () => {
383
+ if (settled) return;
384
+ settled = true;
385
+ resolve();
386
+ };
387
+ });
388
+ let signalRecordingFinished = () => {};
389
+ let recordingFinishedSettled = false;
390
+ videoRecordingFinishedPromiseRef.current = new Promise(resolve => {
391
+ signalRecordingFinished = () => {
392
+ if (recordingFinishedSettled) return;
393
+ recordingFinishedSettled = true;
394
+ resolve();
395
+ };
396
+ });
397
+ try {
398
+ camera.startVideoRecording({
399
+ onRecordingFinished: video => {
400
+ log.info('[Liveness] video recording finished', {
401
+ path: video.path,
402
+ durationSec: video.duration
403
+ });
404
+ // Signal `failWith` (and anyone else waiting for the file to be
405
+ // ready) BEFORE awaiting the upload. The fetch closure keeps the
406
+ // upload alive past any unmount, so it's safe to let the component
407
+ // tear down once the recording-finished signal has fired.
408
+ uploadRecordedVideo(video).finally(() => {
409
+ settle();
410
+ });
411
+ signalRecordingFinished();
412
+ },
413
+ onRecordingError: err => {
414
+ log.warn('[Liveness] video recording error', err);
415
+ videoOutcomeRef.current = 'failed';
416
+ signalRecordingFinished();
417
+ settle();
418
+ }
419
+ });
420
+ log.info('[Liveness] video recording started');
421
+ videoOutcomeRef.current = 'recording';
422
+ } catch (err) {
423
+ log.warn('[Liveness] failed to start video recording', err);
424
+ videoOutcomeRef.current = 'failed';
425
+ // No callback will ever fire → unblock anyone awaiting either Deferred.
426
+ signalRecordingFinished();
427
+ settle();
428
+ }
429
+ }, [uploadRecordedVideo]);
430
+ const stopVideoRecordingIfActive = useCallback(async () => {
431
+ if (videoOutcomeRef.current !== 'recording') {
432
+ log.info('[Liveness] video stop skipped', {
433
+ outcome: videoOutcomeRef.current
434
+ });
435
+ return;
436
+ }
437
+ const camera = cameraRef.current;
438
+ if (!camera) {
439
+ log.warn('[Liveness] video stop skipped: LivenessCamera ref gone');
440
+ return;
441
+ }
442
+ log.info('[Liveness] video recording stopping');
443
+ try {
444
+ // Returns when vision-camera flushed the file; the upload Deferred
445
+ // (set in startVideoRecordingIfEnabled) is what actually tells us when
446
+ // the PUT + cleanup are done — the SESSION_COMPLETE handler awaits it.
447
+ await camera.stopVideoRecording();
448
+ log.info('[Liveness] video recording stop resolved (onRecordingFinished will follow)');
449
+ } catch (err) {
450
+ log.warn('[Liveness] failed to stop video recording', err);
451
+ videoOutcomeRef.current = 'failed';
452
+ }
453
+ }, []);
170
454
  const failWith = useCallback(err => {
171
455
  stopWatchdog();
172
456
  stopCapture();
173
- try {
174
- wsRef.current?.close(1000, 'fail');
175
- } catch {
176
- /* ignore */
457
+ // OSDKR-4 requirement: the video must upload on EVERY outcome,
458
+ // including LIVENESS_FAILED, so back-office reviewers can audit
459
+ // what happened in declined sessions. To make that work we need
460
+ // `onRecordingFinished` to fire *before* the component unmounts —
461
+ // once the file is flushed and `uploadRecordedVideo` has kicked
462
+ // off, the fetch closure carries the upload through to completion
463
+ // on its own, no matter how quickly the UI is torn down.
464
+ //
465
+ // We don't wait for the GCS PUT to complete (that can take
466
+ // seconds and the user shouldn't sit on the error screen for it),
467
+ // just for the recording-finished signal.
468
+ const recordingWasActive = videoOutcomeRef.current === 'recording';
469
+ const finish = () => {
470
+ if (videoTempPathRef.current && !recordingWasActive) {
471
+ // Only delete the temp file when there was no recording in
472
+ // flight; otherwise `uploadRecordedVideo` is responsible for
473
+ // deleting it after the PUT settles.
474
+ const path = videoTempPathRef.current;
475
+ videoTempPathRef.current = null;
476
+ void deleteVideoTemp(path);
477
+ }
478
+ try {
479
+ wsRef.current?.close(1000, 'fail');
480
+ } catch {
481
+ /* ignore */
482
+ }
483
+ wsRef.current = null;
484
+ onCancel(err);
485
+ };
486
+ if (!recordingWasActive) {
487
+ finish();
488
+ return;
177
489
  }
178
- wsRef.current = null;
179
- onCancel(err);
180
- }, [onCancel, stopCapture, stopWatchdog]);
490
+ const finishedPromise = videoRecordingFinishedPromiseRef.current;
491
+ void (async () => {
492
+ await stopVideoRecordingIfActive();
493
+ if (finishedPromise) {
494
+ // Bound the wait so a misbehaving recorder can't strand the
495
+ // user on the camera screen forever. `RECORDING_FINISH_TIMEOUT_MS`
496
+ // is conservative — vision-camera typically lands the callback
497
+ // tens of milliseconds after stopRecording resolves.
498
+ let finishTimer = null;
499
+ const timeoutPromise = new Promise(resolve => {
500
+ finishTimer = setTimeout(() => {
501
+ log.warn('[Liveness] recording-finished signal timed out — proceeding to fail without ensuring the upload kicked off');
502
+ resolve();
503
+ }, RECORDING_FINISH_TIMEOUT_MS);
504
+ });
505
+ await Promise.race([finishedPromise, timeoutPromise]);
506
+ if (finishTimer) clearTimeout(finishTimer);
507
+ }
508
+ finish();
509
+ })();
510
+ }, [deleteVideoTemp, onCancel, stopCapture, stopVideoRecordingIfActive, stopWatchdog]);
181
511
  const captureAndSend = useCallback(async () => {
182
512
  if (inFlightRef.current) return;
183
513
  const ws = wsRef.current;
@@ -186,10 +516,18 @@ function LivenessMatchView({
186
516
  try {
187
517
  const photo = await cameraRef.current?.takeFrame();
188
518
  if (!photo || !ws.isOpen()) return;
519
+ // Front-camera frames come back mirrored (vision-camera's default for
520
+ // front cam, which we keep so the recorded mp4 has a correct rotation
521
+ // matrix — see the `isMirrored` comment in LivenessCamera). For Iris,
522
+ // we want the un-mirrored yaw so TURN_LEFT/RIGHT challenges map to
523
+ // real-world directions, so we flip the JPEG horizontally here before
524
+ // signing and sending.
189
525
  const compressed = await ImageManipulator.manipulateAsync(photo.path.startsWith('file://') ? photo.path : `file://${photo.path}`, [{
190
526
  resize: {
191
527
  width: FRAME_MAX_LONG_EDGE
192
528
  }
529
+ }, {
530
+ flip: ImageManipulator.FlipType.Horizontal
193
531
  }], {
194
532
  compress: FRAME_QUALITY,
195
533
  format: ImageManipulator.SaveFormat.JPEG
@@ -288,6 +626,10 @@ function LivenessMatchView({
288
626
  setChallengeText(t.liveness.centerFace);
289
627
  showToast('success', t.liveness.getReady);
290
628
  startCaptureLoop(FRAME_MS_DEFAULT);
629
+ // Start the local mp4 recording in parallel with the frame loop, if
630
+ // the backend opted in via `video_upload` in /liveness-init. Pure
631
+ // best-effort: any failure here is logged and never blocks liveness.
632
+ startVideoRecordingIfEnabled();
291
633
  resetWatchdog();
292
634
  return;
293
635
  }
@@ -336,10 +678,26 @@ function LivenessMatchView({
336
678
  // can take several seconds to land while the worker drains
337
679
  // its queue; without this the user would stare at the camera
338
680
  // and the stale instruction the whole time.
681
+ //
682
+ // CRITICAL: the video recording MUST be stopped before the phase
683
+ // change. Switching phase unmounts <LivenessCamera>, which makes
684
+ // vision-camera tear down the recording mid-flush — the
685
+ // `onRecordingFinished` callback never fires and the upload
686
+ // promise stays pending until the 60 s timeout. We stop first,
687
+ // then unmount.
339
688
  const meta = lastChallengeMetaRef.current;
340
689
  if (meta && meta.index >= meta.total - 1) {
690
+ log.info('[Liveness] last challenge complete — preparing to finalize', {
691
+ index: meta.index,
692
+ total: meta.total,
693
+ videoOutcome: videoOutcomeRef.current
694
+ });
341
695
  stopCapture();
342
- setPhase('finalizing');
696
+ (async () => {
697
+ await stopVideoRecordingIfActive();
698
+ log.info('[Liveness] last challenge: switching phase to finalizing');
699
+ setPhase('finalizing');
700
+ })();
343
701
  }
344
702
  resetWatchdog();
345
703
  return;
@@ -350,6 +708,22 @@ function LivenessMatchView({
350
708
  presentTerminalRetry(msg.code, msg.message);
351
709
  return;
352
710
  }
711
+ // The orchestrator aborted the running challenge because capture
712
+ // quality dropped mid-gesture (face drifted too far, lighting
713
+ // fell). Drop back to positioning-style guidance — no progress
714
+ // bar, neutral oval, persistent hint — and let the SAME challenge
715
+ // re-arrive on its own once the user is well positioned again.
716
+ if (msg.code === 'CHALLENGE_REPOSITION') {
717
+ currentChallengeRef.current = null;
718
+ adjustFps(FRAME_MS_DEFAULT);
719
+ setProgress(null);
720
+ setOvalCue('NEUTRAL');
721
+ const repositionText = msg.message ?? t.liveness.repositioning;
722
+ setChallengeText(repositionText);
723
+ showToast('warning', repositionText);
724
+ resetWatchdog();
725
+ return;
726
+ }
353
727
  const isPositioningReady = msg.code === 'POSITIONING_READY';
354
728
  // Per-code SDK-side fallback used when the orchestrator forwarded a
355
729
  // code but no localised text (e.g. older orchestrator versions, or
@@ -423,15 +797,66 @@ function LivenessMatchView({
423
797
  /* ignore */
424
798
  }
425
799
  wsRef.current = null;
426
- setPhase('finalizing');
800
+ // IMPORTANT: do NOT setPhase('finalizing') yet. Switching phase
801
+ // unmounts LivenessCamera, which cancels the in-flight video
802
+ // recording mid-flush and prevents `onRecordingFinished` from
803
+ // firing — the upload would never start. We stop the recording
804
+ // first (camera still mounted, ref valid), then transition phase
805
+ // and run the verify pipeline.
427
806
  (async () => {
807
+ // ── Settle the video pipeline before /liveness-verify ─────────
808
+ // Best-effort: stop the recording (if still running), then await
809
+ // the upload promise with a hard timeout. Whatever the outcome
810
+ // (uploaded / failed / timeout), we proceed to verify — the body
811
+ // is only attached when the upload actually succeeded.
812
+ await stopVideoRecordingIfActive();
813
+ // Safe to unmount LivenessCamera now: the recording has been
814
+ // flushed and `onRecordingFinished` has been scheduled.
815
+ setPhase('finalizing');
816
+ if (videoUploadPromiseRef.current) {
817
+ log.info('[Liveness] awaiting video upload settle', {
818
+ timeoutMs: VIDEO_UPLOAD_TIMEOUT_MS
819
+ });
820
+ const uploadPromise = videoUploadPromiseRef.current;
821
+ let uploadTimer = null;
822
+ const timeoutPromise = new Promise(resolve => {
823
+ uploadTimer = setTimeout(() => {
824
+ log.warn('[Liveness] video upload timed out — verify will go without body');
825
+ videoOutcomeRef.current = 'failed';
826
+ resolve();
827
+ }, VIDEO_UPLOAD_TIMEOUT_MS);
828
+ });
829
+ await Promise.race([uploadPromise, timeoutPromise]);
830
+ if (uploadTimer) clearTimeout(uploadTimer);
831
+ }
832
+ const verifyBody = videoOutcomeRef.current === 'uploaded' && videoMetaRef.current ? {
833
+ video: videoMetaRef.current
834
+ } : {};
835
+ log.info('[Liveness] POST /liveness-verify', {
836
+ outcome: videoOutcomeRef.current,
837
+ hasBody: 'video' in verifyBody
838
+ });
839
+
840
+ // Bound the verify call with an explicit timeout. SESSION_COMPLETE
841
+ // already turned the progress watchdog off, so if this POST hangs
842
+ // (the dev network shows recurring HTTP/2 INTERNAL_ERROR resets)
843
+ // nothing else would rescue the user — the app would sit on the
844
+ // analyzing overlay forever. On timeout we abort and route through
845
+ // failWith so the retry dialog is shown.
846
+ const verifyController = new AbortController();
847
+ const verifyTimeout = setTimeout(() => verifyController.abort(), LIVENESS_VERIFY_TIMEOUT_MS);
428
848
  try {
429
- await api.post(`/sessions/${sessionId}/liveness-verify`, {});
849
+ await api.post(`/sessions/${sessionId}/liveness-verify`, verifyBody, {
850
+ signal: verifyController.signal
851
+ });
852
+ clearTimeout(verifyTimeout);
430
853
  onComplete();
431
854
  } catch (err) {
432
- const message = err && typeof err === 'object' && 'message' in err ? String(err.message) : 'Failed to notify the backend that liveness completed.';
855
+ clearTimeout(verifyTimeout);
856
+ const aborted = verifyController.signal.aborted || err != null && typeof err === 'object' && 'name' in err && err.name === 'AbortError';
857
+ const message = aborted ? 'The verification request timed out. Check your connection and try again.' : err && typeof err === 'object' && 'message' in err ? String(err.message) : 'Failed to notify the backend that liveness completed.';
433
858
  failWith({
434
- code: SdkErrorCode.LIVENESS_FAILED,
859
+ code: aborted ? SdkErrorCode.NETWORK_ERROR : SdkErrorCode.LIVENESS_FAILED,
435
860
  message,
436
861
  cause: err
437
862
  });
@@ -442,7 +867,7 @@ function LivenessMatchView({
442
867
  default:
443
868
  return;
444
869
  }
445
- }, [adjustFps, api, challengeLabel, failWith, onComplete, presentTerminalRetry, resetWatchdog, sessionId, showToast, startCaptureLoop, stopCapture, stopWatchdog, t.liveness.getReady, t.liveness.positioningReady, t.liveness.warningConsecutiveMisses, t.liveness.warningGeneric]);
870
+ }, [adjustFps, api, challengeLabel, failWith, onComplete, presentTerminalRetry, resetWatchdog, sessionId, showToast, startCaptureLoop, startVideoRecordingIfEnabled, stopCapture, stopVideoRecordingIfActive, stopWatchdog, t.liveness.getReady, t.liveness.positioningReady, t.liveness.repositioning, t.liveness.warningConsecutiveMisses, t.liveness.warningGeneric]);
446
871
  const startVerification = useCallback(async () => {
447
872
  setBannerError(null);
448
873
  setRetry(null);
@@ -487,6 +912,27 @@ function LivenessMatchView({
487
912
  hmacRef.current = null;
488
913
  }
489
914
  }
915
+ // Reset the video pipeline state for this attempt (the host may retry).
916
+ // We honour `video_upload` even when the host did not register the
917
+ // `onLivenessVideoUploaded` callback — the upload still happens, only
918
+ // the host notification is skipped. `outcome` stays `'none'` until
919
+ // `startVideoRecordingIfEnabled` confirms the recording actually started;
920
+ // see that callback for why we cannot trust `init.video_upload` alone.
921
+ videoUploadRef.current = init.video_upload ?? null;
922
+ videoOutcomeRef.current = 'none';
923
+ videoMetaRef.current = null;
924
+ videoUploadPromiseRef.current = null;
925
+ videoRecordingFinishedPromiseRef.current = null;
926
+ videoTempPathRef.current = null;
927
+ if (init.video_upload) {
928
+ log.info('[Liveness] init.video_upload received', {
929
+ url: truncateUrl(init.video_upload.upload_url),
930
+ expiresAt: init.video_upload.expires_at,
931
+ method: init.video_upload.method
932
+ });
933
+ } else {
934
+ log.info('[Liveness] init.video_upload absent — recording disabled for this session');
935
+ }
490
936
  setStatusText(t.liveness.preparingCamera);
491
937
  let connection;
492
938
  try {
@@ -538,13 +984,45 @@ function LivenessMatchView({
538
984
 
539
985
  // Effect: when the user enters the capture phase (intro skipped or
540
986
  // confirmed), run the start sequence.
987
+ //
988
+ // NOTE: this effect must NOT tear down the WebSocket in its cleanup.
989
+ // Its dependency is `[phase]`, so the cleanup runs on every phase change
990
+ // — including capturing → finalizing. Closing the WS there killed it
991
+ // ~250 ms after the last CHALLENGE_COMPLETE, i.e. *before* Iris emitted
992
+ // SESSION_COMPLETE (~440 ms later), so the SDK never received it and
993
+ // never sent /liveness-verify. Session teardown lives in the unmount-only
994
+ // effect below.
541
995
  useEffect(() => {
542
996
  if (phase !== 'capturing') return;
543
997
  void startVerification();
998
+ // We intentionally only re-run when phase flips into capturing — the
999
+ // first start; the retry path is handled by `restartVerification`.
1000
+ // eslint-disable-next-line react-hooks/exhaustive-deps
1001
+ }, [phase]);
1002
+
1003
+ // Effect: real component teardown. Runs once, on unmount only — so the
1004
+ // WebSocket survives in-flow phase changes (capturing → finalizing) and
1005
+ // stays open long enough to receive SESSION_COMPLETE. The SESSION_COMPLETE
1006
+ // / fail / terminal-retry handlers already close the WS explicitly when
1007
+ // the flow ends normally; this is the safety net for an actual unmount.
1008
+ useEffect(() => {
544
1009
  return () => {
545
1010
  stopCapture();
546
1011
  stopWatchdog();
547
1012
  if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
1013
+ // Best-effort video pipeline shutdown on unmount. Stop the recording
1014
+ // if it's still running (vision-camera deletes its temp file when the
1015
+ // <Camera> tears down anyway, but we explicitly stop to flush). Then
1016
+ // delete any temp file we own, so a backed-out user doesn't leak
1017
+ // storage.
1018
+ if (videoOutcomeRef.current === 'recording') {
1019
+ void stopVideoRecordingIfActive();
1020
+ }
1021
+ const leftoverPath = videoTempPathRef.current;
1022
+ videoTempPathRef.current = null;
1023
+ if (leftoverPath) {
1024
+ void deleteVideoTemp(leftoverPath);
1025
+ }
548
1026
  try {
549
1027
  wsRef.current?.close(1000, 'unmount');
550
1028
  } catch {
@@ -552,10 +1030,8 @@ function LivenessMatchView({
552
1030
  }
553
1031
  wsRef.current = null;
554
1032
  };
555
- // We intentionally only re-run when phase flips into capturing — the
556
- // first start; the retry path is handled by `restartVerification`.
557
1033
  // eslint-disable-next-line react-hooks/exhaustive-deps
558
- }, [phase]);
1034
+ }, []);
559
1035
  if (retry) {
560
1036
  return /*#__PURE__*/_jsx(RetryDialog, {
561
1037
  title: t.liveness.terminalRetryTitle,