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