@velion-la/onboarding-sdk-react-native 1.0.0-beta.3 → 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 (35) 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/steps/DocumentsOcrStep.js +8 -4
  6. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  7. package/lib/commonjs/steps/LivenessMatchStep.js +435 -11
  8. package/lib/commonjs/steps/LivenessMatchStep.js.map +1 -1
  9. package/lib/commonjs/types/index.js +16 -0
  10. package/lib/commonjs/types/index.js.map +1 -1
  11. package/lib/module/camera/LivenessCamera.js +86 -7
  12. package/lib/module/camera/LivenessCamera.js.map +1 -1
  13. package/lib/module/core/VelionOnboarding.js +3 -0
  14. package/lib/module/core/VelionOnboarding.js.map +1 -1
  15. package/lib/module/steps/DocumentsOcrStep.js +9 -5
  16. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  17. package/lib/module/steps/LivenessMatchStep.js +434 -11
  18. package/lib/module/steps/LivenessMatchStep.js.map +1 -1
  19. package/lib/module/types/index.js +19 -0
  20. package/lib/module/types/index.js.map +1 -1
  21. package/lib/typescript/camera/LivenessCamera.d.ts +18 -1
  22. package/lib/typescript/camera/LivenessCamera.d.ts.map +1 -1
  23. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  24. package/lib/typescript/steps/LivenessMatchStep.d.ts.map +1 -1
  25. package/lib/typescript/steps/types.d.ts +7 -1
  26. package/lib/typescript/steps/types.d.ts.map +1 -1
  27. package/lib/typescript/types/index.d.ts +57 -0
  28. package/lib/typescript/types/index.d.ts.map +1 -1
  29. package/package.json +1 -1
  30. package/src/camera/LivenessCamera.tsx +100 -3
  31. package/src/core/VelionOnboarding.ts +3 -0
  32. package/src/steps/DocumentsOcrStep.tsx +7 -3
  33. package/src/steps/LivenessMatchStep.tsx +449 -11
  34. package/src/steps/types.ts +7 -1
  35. package/src/types/index.ts +61 -0
@@ -16,11 +16,21 @@
16
16
 
17
17
  import { useCallback, useEffect, useRef, useState } from 'react';
18
18
  import { ScrollView, StyleSheet, Text, View } from 'react-native';
19
+ // `expo-file-system` v19's `File` class wraps a `file://` path with a Blob-
20
+ // compatible API (`arrayBuffer`, `size`, `delete`). We read the recorded mp4
21
+ // to bytes in JS and PUT them with the global `fetch`. For the typical
22
+ // 1–5 MB session video this is well within the bridge budget; if the
23
+ // recorded files grow significantly we can switch to a streaming uploader
24
+ // without changing the call sites.
25
+ import { File as FsFile } from 'expo-file-system';
19
26
  import * as ImageManipulator from 'expo-image-manipulator';
20
27
  import {
21
28
  SdkErrorCode,
22
29
  type LivenessSessionResponse,
30
+ type LivenessVerifyVideoMeta,
31
+ type LivenessVideoRef,
23
32
  type SdkError,
33
+ type VideoUpload,
24
34
  } from '../types';
25
35
  import { Banner } from '../ui/primitives/Banner';
26
36
  import { Button } from '../ui/primitives/Button';
@@ -49,6 +59,7 @@ import {
49
59
  type LivenessCameraHandle,
50
60
  type LivenessOvalCue,
51
61
  } from '../camera/LivenessCamera';
62
+ import type { VideoFile } from 'react-native-vision-camera';
52
63
  import type { ApiCaller } from '../transport/api';
53
64
  import type { StepDeps, StepModule } from './types';
54
65
 
@@ -65,6 +76,30 @@ const PROGRESS_WATCHDOG_MS = 25_000;
65
76
  const LIVENESS_VERIFY_TIMEOUT_MS = 20_000;
66
77
  const FRAME_MAX_LONG_EDGE = 720;
67
78
  const FRAME_QUALITY = 0.55;
79
+ /**
80
+ * Hard ceiling for the video upload PUT to GCS that runs between SESSION_COMPLETE
81
+ * and POST /liveness-verify. Long enough for a 5 MB upload on a slow mobile link
82
+ * but short enough that a stalled connection can't keep the user on the
83
+ * analyzing overlay indefinitely. On timeout we fall back to verify-without-body.
84
+ */
85
+ /**
86
+ * Hard ceiling for the video upload PUT to GCS that runs between
87
+ * SESSION_COMPLETE and POST /liveness-verify. The signed URL TTL is 10 min,
88
+ * so 60 s leaves comfortable headroom for a typical 1–5 MB session video
89
+ * over a slow mobile uplink. On timeout we fall back to verify-without-body.
90
+ */
91
+ const VIDEO_UPLOAD_TIMEOUT_MS = 60_000;
92
+ // Upper bound for vision-camera to deliver `onRecordingFinished` after
93
+ // `stopRecording()` resolves. Observed ~50–200 ms in practice; we set the
94
+ // cap generously so a slow flush on older Androids doesn't strand the
95
+ // failure path waiting for a signal that's just running late.
96
+ const RECORDING_FINISH_TIMEOUT_MS = 3_000;
97
+ const VIDEO_CONTENT_TYPE = 'video/mp4';
98
+
99
+ /** Returns the first 80 chars of a URL — enough to spot the bucket without dumping the V4 signature. */
100
+ function truncateUrl(url: string): string {
101
+ return url.length <= 80 ? url : `${url.slice(0, 80)}…`;
102
+ }
68
103
 
69
104
  export class LivenessMatchStep implements StepModule {
70
105
  private resolveStep!: () => void;
@@ -85,6 +120,7 @@ export class LivenessMatchStep implements StepModule {
85
120
  calibrationLabel={this.deps.livenessCalibrationLabel}
86
121
  showIntro
87
122
  showBackButton
123
+ onVideoUploaded={this.deps.onLivenessVideoUploaded}
88
124
  onComplete={() => {
89
125
  if (this.destroyed) return;
90
126
  this.deps.ui.setNode(null);
@@ -114,6 +150,8 @@ interface ViewProps {
114
150
  calibrationLabel?: string | undefined;
115
151
  showIntro: boolean;
116
152
  showBackButton: boolean;
153
+ /** Best-effort: fires only on a successful video upload (HTTP 200 from GCS). */
154
+ onVideoUploaded?: ((ref: LivenessVideoRef) => void) | undefined;
117
155
  onComplete: () => void;
118
156
  onCancel: (err: SdkError) => void;
119
157
  }
@@ -127,6 +165,7 @@ function LivenessMatchView({
127
165
  calibrationLabel,
128
166
  showIntro,
129
167
  showBackButton,
168
+ onVideoUploaded,
130
169
  onComplete,
131
170
  onCancel,
132
171
  }: ViewProps) {
@@ -176,6 +215,38 @@ function LivenessMatchView({
176
215
  // warnings flash in <2s and the user couldn't read them).
177
216
  const activeToastRef = useRef<{ kind: 'success' | 'warning'; message: string } | null>(null);
178
217
 
218
+ // ── Video recording state (OSDKR-4) ─────────────────────────────────────
219
+ // `videoUploadRef` holds the signed URL returned by /liveness-init when the
220
+ // backend enabled video capture for this session. `null` → skip recording.
221
+ const videoUploadRef = useRef<VideoUpload | null>(null);
222
+ // Current state of the video pipeline. Best-effort: any value other than
223
+ // `'uploaded'` ends up calling /liveness-verify WITHOUT a body — liveness
224
+ // still completes normally.
225
+ type VideoOutcome = 'none' | 'recording' | 'failed' | 'uploaded';
226
+ const videoOutcomeRef = useRef<VideoOutcome>('none');
227
+ // Filled in when the GCS PUT returns 200; consumed by the verify call.
228
+ const videoMetaRef = useRef<LivenessVerifyVideoMeta | null>(null);
229
+ // Resolves when the upload (success or failure path) is fully settled. The
230
+ // SESSION_COMPLETE handler awaits this with a bounded timeout before calling
231
+ // /liveness-verify so the metadata, if any, makes it into the body.
232
+ const videoUploadPromiseRef = useRef<Promise<void> | null>(null);
233
+ // Resolves as soon as vision-camera fires `onRecordingFinished` (i.e. when
234
+ // the mp4 file is fully written and `uploadRecordedVideo` has been kicked
235
+ // off — fetch is in flight but not yet complete). `failWith` awaits this with
236
+ // a short timeout so the upload's underlying fetch is *started* before the
237
+ // step is torn down. After the unmount the fetch closure keeps its own refs
238
+ // alive and the PUT to GCS completes in the background.
239
+ const videoRecordingFinishedPromiseRef = useRef<Promise<void> | null>(null);
240
+ // Local file system path of the temp mp4. Tracked so the unmount cleanup
241
+ // can delete it if the user backs out before the upload finished.
242
+ const videoTempPathRef = useRef<string | null>(null);
243
+ // Cached so `failWith` / unmount can invoke the callback with the prop
244
+ // captured at start, even if the host re-renders.
245
+ const onVideoUploadedRef = useRef<typeof onVideoUploaded>(onVideoUploaded);
246
+ useEffect(() => {
247
+ onVideoUploadedRef.current = onVideoUploaded;
248
+ }, [onVideoUploaded]);
249
+
179
250
  // Each toast stays on screen at least this long. The orchestrator can spam
180
251
  // WARNINGs (POSITIONING_REQUIRED, SPOOF_RISK_HIGH, …) several times per
181
252
  // second; without a floor the user literally cannot read them.
@@ -223,19 +294,282 @@ function LivenessMatchView({
223
294
  inFlightRef.current = false;
224
295
  }, []);
225
296
 
297
+ // ── Video upload pipeline (OSDKR-4) ─────────────────────────────────────
298
+ // Everything below is best-effort: never throws into the caller; never
299
+ // blocks liveness completion. The worst case is `videoOutcomeRef = 'failed'`
300
+ // and verify being called without a body.
301
+ const deleteVideoTemp = useCallback((path: string | null) => {
302
+ if (!path) return;
303
+ try {
304
+ // `File.delete()` is synchronous in expo-file-system v19.
305
+ new FsFile(path).delete();
306
+ } catch {
307
+ // Best-effort cleanup; we can't do much if rm fails.
308
+ }
309
+ }, []);
310
+
311
+ const uploadRecordedVideo = useCallback(
312
+ async (video: VideoFile): Promise<void> => {
313
+ const target = videoUploadRef.current;
314
+ videoTempPathRef.current = video.path;
315
+ if (!target) {
316
+ log.warn('[Liveness] video upload skipped: no signed URL in init response');
317
+ videoOutcomeRef.current = 'failed';
318
+ deleteVideoTemp(video.path);
319
+ videoTempPathRef.current = null;
320
+ return;
321
+ }
322
+ const durationMs =
323
+ typeof video.duration === 'number' && isFinite(video.duration)
324
+ ? Math.round(video.duration * 1000)
325
+ : null;
326
+ let sizeBytes: number | null = null;
327
+ let file: FsFile | null = null;
328
+ try {
329
+ file = new FsFile(video.path);
330
+ sizeBytes = typeof file.size === 'number' ? file.size : null;
331
+ } catch (err) {
332
+ log.warn('[Liveness] could not stat video file before upload', err);
333
+ }
334
+ log.info('[Liveness] video upload starting', {
335
+ url: truncateUrl(target.upload_url),
336
+ method: target.method,
337
+ contentType: VIDEO_CONTENT_TYPE,
338
+ path: video.path,
339
+ sizeBytes,
340
+ durationMs,
341
+ });
342
+ const t0 = Date.now();
343
+ try {
344
+ // Build a NATIVE React Native Blob from the `file://` URI: fetching
345
+ // the local path returns a Response whose `.blob()` is the BlobModule
346
+ // implementation that the bridge actually knows how to upload. Using
347
+ // the expo-file-system `File` directly silently sends an empty body
348
+ // (GCS responds 200 with a 0-byte object — exactly what we hit
349
+ // before). Reading the bytes through the native Blob keeps the data
350
+ // on the native side and uploads streamed from disk.
351
+ const fileUri = video.path.startsWith('file://')
352
+ ? video.path
353
+ : `file://${video.path}`;
354
+ const nativeBlob = await (await fetch(fileUri)).blob();
355
+ log.info('[Liveness] video upload body prepared', {
356
+ blobSize: nativeBlob.size,
357
+ blobType: nativeBlob.type,
358
+ });
359
+ const result = await fetch(target.upload_url, {
360
+ method: 'PUT',
361
+ headers: { 'Content-Type': VIDEO_CONTENT_TYPE },
362
+ body: nativeBlob,
363
+ });
364
+ const elapsedMs = Date.now() - t0;
365
+ if (result.ok) {
366
+ log.info('[Liveness] video upload ok', { status: result.status, elapsedMs, sizeBytes });
367
+ videoOutcomeRef.current = 'uploaded';
368
+ videoMetaRef.current = {
369
+ content_type: VIDEO_CONTENT_TYPE,
370
+ duration_ms: durationMs,
371
+ };
372
+ // Invoke the host callback BEFORE cleanup so the path stays valid
373
+ // for any synchronous host work (rare, but cheap to guarantee).
374
+ try {
375
+ onVideoUploadedRef.current?.({
376
+ upload_url: target.upload_url,
377
+ content_type: VIDEO_CONTENT_TYPE,
378
+ duration_ms: durationMs,
379
+ size_bytes: sizeBytes,
380
+ });
381
+ } catch (err) {
382
+ log.warn('[Liveness] onLivenessVideoUploaded threw', err);
383
+ }
384
+ } else {
385
+ // Try to extract the GCS error XML — its body tells us exactly which
386
+ // permission / signature param failed (otherwise we are blind).
387
+ let responseSnippet = '';
388
+ try {
389
+ responseSnippet = (await result.text()).slice(0, 400);
390
+ } catch {
391
+ /* body not readable; status alone is the signal */
392
+ }
393
+ log.warn('[Liveness] video upload non-200', {
394
+ status: result.status,
395
+ elapsedMs,
396
+ sizeBytes,
397
+ body: responseSnippet,
398
+ });
399
+ videoOutcomeRef.current = 'failed';
400
+ }
401
+ } catch (err) {
402
+ log.warn('[Liveness] video upload error', {
403
+ elapsedMs: Date.now() - t0,
404
+ sizeBytes,
405
+ err,
406
+ });
407
+ videoOutcomeRef.current = 'failed';
408
+ } finally {
409
+ deleteVideoTemp(video.path);
410
+ videoTempPathRef.current = null;
411
+ }
412
+ },
413
+ [deleteVideoTemp],
414
+ );
415
+
416
+ const startVideoRecordingIfEnabled = useCallback(() => {
417
+ if (!videoUploadRef.current) {
418
+ log.info('[Liveness] video skipped: no video_upload in liveness-init');
419
+ return;
420
+ }
421
+ const camera = cameraRef.current;
422
+ if (!camera) {
423
+ log.warn('[Liveness] video skipped: LivenessCamera ref not ready at SESSION_READY');
424
+ return;
425
+ }
426
+ log.info('[Liveness] video recording starting', {
427
+ uploadUrl: truncateUrl(videoUploadRef.current.upload_url),
428
+ expiresAt: videoUploadRef.current.expires_at,
429
+ });
430
+ // Pre-assign the upload promise BEFORE calling startRecording. vision-camera
431
+ // dispatches `onRecordingFinished` on a separate microtask from the
432
+ // `stopRecording()` resolution, so a "set the promise inside the callback"
433
+ // pattern races SESSION_COMPLETE — the verify POST fires before
434
+ // `uploadRecordedVideo` is even invoked, and the body ends up empty.
435
+ // The Deferred resolves once the recording's success/error path is fully
436
+ // settled (including the upload PUT and the cleanup).
437
+ let settle: () => void = () => {};
438
+ let settled = false;
439
+ videoUploadPromiseRef.current = new Promise<void>((resolve) => {
440
+ settle = () => {
441
+ if (settled) return;
442
+ settled = true;
443
+ resolve();
444
+ };
445
+ });
446
+ let signalRecordingFinished: () => void = () => {};
447
+ let recordingFinishedSettled = false;
448
+ videoRecordingFinishedPromiseRef.current = new Promise<void>((resolve) => {
449
+ signalRecordingFinished = () => {
450
+ if (recordingFinishedSettled) return;
451
+ recordingFinishedSettled = true;
452
+ resolve();
453
+ };
454
+ });
455
+ try {
456
+ camera.startVideoRecording({
457
+ onRecordingFinished: (video) => {
458
+ log.info('[Liveness] video recording finished', {
459
+ path: video.path,
460
+ durationSec: video.duration,
461
+ });
462
+ // Signal `failWith` (and anyone else waiting for the file to be
463
+ // ready) BEFORE awaiting the upload. The fetch closure keeps the
464
+ // upload alive past any unmount, so it's safe to let the component
465
+ // tear down once the recording-finished signal has fired.
466
+ uploadRecordedVideo(video).finally(() => {
467
+ settle();
468
+ });
469
+ signalRecordingFinished();
470
+ },
471
+ onRecordingError: (err) => {
472
+ log.warn('[Liveness] video recording error', err);
473
+ videoOutcomeRef.current = 'failed';
474
+ signalRecordingFinished();
475
+ settle();
476
+ },
477
+ });
478
+ log.info('[Liveness] video recording started');
479
+ videoOutcomeRef.current = 'recording';
480
+ } catch (err) {
481
+ log.warn('[Liveness] failed to start video recording', err);
482
+ videoOutcomeRef.current = 'failed';
483
+ // No callback will ever fire → unblock anyone awaiting either Deferred.
484
+ signalRecordingFinished();
485
+ settle();
486
+ }
487
+ }, [uploadRecordedVideo]);
488
+
489
+ const stopVideoRecordingIfActive = useCallback(async () => {
490
+ if (videoOutcomeRef.current !== 'recording') {
491
+ log.info('[Liveness] video stop skipped', { outcome: videoOutcomeRef.current });
492
+ return;
493
+ }
494
+ const camera = cameraRef.current;
495
+ if (!camera) {
496
+ log.warn('[Liveness] video stop skipped: LivenessCamera ref gone');
497
+ return;
498
+ }
499
+ log.info('[Liveness] video recording stopping');
500
+ try {
501
+ // Returns when vision-camera flushed the file; the upload Deferred
502
+ // (set in startVideoRecordingIfEnabled) is what actually tells us when
503
+ // the PUT + cleanup are done — the SESSION_COMPLETE handler awaits it.
504
+ await camera.stopVideoRecording();
505
+ log.info('[Liveness] video recording stop resolved (onRecordingFinished will follow)');
506
+ } catch (err) {
507
+ log.warn('[Liveness] failed to stop video recording', err);
508
+ videoOutcomeRef.current = 'failed';
509
+ }
510
+ }, []);
511
+
226
512
  const failWith = useCallback(
227
513
  (err: SdkError) => {
228
514
  stopWatchdog();
229
515
  stopCapture();
230
- try {
231
- wsRef.current?.close(1000, 'fail');
232
- } catch {
233
- /* ignore */
516
+ // OSDKR-4 requirement: the video must upload on EVERY outcome,
517
+ // including LIVENESS_FAILED, so back-office reviewers can audit
518
+ // what happened in declined sessions. To make that work we need
519
+ // `onRecordingFinished` to fire *before* the component unmounts —
520
+ // once the file is flushed and `uploadRecordedVideo` has kicked
521
+ // off, the fetch closure carries the upload through to completion
522
+ // on its own, no matter how quickly the UI is torn down.
523
+ //
524
+ // We don't wait for the GCS PUT to complete (that can take
525
+ // seconds and the user shouldn't sit on the error screen for it),
526
+ // just for the recording-finished signal.
527
+ const recordingWasActive = videoOutcomeRef.current === 'recording';
528
+ const finish = () => {
529
+ if (videoTempPathRef.current && !recordingWasActive) {
530
+ // Only delete the temp file when there was no recording in
531
+ // flight; otherwise `uploadRecordedVideo` is responsible for
532
+ // deleting it after the PUT settles.
533
+ const path = videoTempPathRef.current;
534
+ videoTempPathRef.current = null;
535
+ void deleteVideoTemp(path);
536
+ }
537
+ try {
538
+ wsRef.current?.close(1000, 'fail');
539
+ } catch {
540
+ /* ignore */
541
+ }
542
+ wsRef.current = null;
543
+ onCancel(err);
544
+ };
545
+ if (!recordingWasActive) {
546
+ finish();
547
+ return;
234
548
  }
235
- wsRef.current = null;
236
- onCancel(err);
549
+ const finishedPromise = videoRecordingFinishedPromiseRef.current;
550
+ void (async () => {
551
+ await stopVideoRecordingIfActive();
552
+ if (finishedPromise) {
553
+ // Bound the wait so a misbehaving recorder can't strand the
554
+ // user on the camera screen forever. `RECORDING_FINISH_TIMEOUT_MS`
555
+ // is conservative — vision-camera typically lands the callback
556
+ // tens of milliseconds after stopRecording resolves.
557
+ let finishTimer: ReturnType<typeof setTimeout> | null = null;
558
+ const timeoutPromise = new Promise<void>((resolve) => {
559
+ finishTimer = setTimeout(() => {
560
+ log.warn(
561
+ '[Liveness] recording-finished signal timed out — proceeding to fail without ensuring the upload kicked off',
562
+ );
563
+ resolve();
564
+ }, RECORDING_FINISH_TIMEOUT_MS);
565
+ });
566
+ await Promise.race([finishedPromise, timeoutPromise]);
567
+ if (finishTimer) clearTimeout(finishTimer);
568
+ }
569
+ finish();
570
+ })();
237
571
  },
238
- [onCancel, stopCapture, stopWatchdog],
572
+ [deleteVideoTemp, onCancel, stopCapture, stopVideoRecordingIfActive, stopWatchdog],
239
573
  );
240
574
 
241
575
  const captureAndSend = useCallback(async () => {
@@ -246,9 +580,18 @@ function LivenessMatchView({
246
580
  try {
247
581
  const photo = await cameraRef.current?.takeFrame();
248
582
  if (!photo || !ws.isOpen()) return;
583
+ // Front-camera frames come back mirrored (vision-camera's default for
584
+ // front cam, which we keep so the recorded mp4 has a correct rotation
585
+ // matrix — see the `isMirrored` comment in LivenessCamera). For Iris,
586
+ // we want the un-mirrored yaw so TURN_LEFT/RIGHT challenges map to
587
+ // real-world directions, so we flip the JPEG horizontally here before
588
+ // signing and sending.
249
589
  const compressed = await ImageManipulator.manipulateAsync(
250
590
  photo.path.startsWith('file://') ? photo.path : `file://${photo.path}`,
251
- [{ resize: { width: FRAME_MAX_LONG_EDGE } }],
591
+ [
592
+ { resize: { width: FRAME_MAX_LONG_EDGE } },
593
+ { flip: ImageManipulator.FlipType.Horizontal },
594
+ ],
252
595
  { compress: FRAME_QUALITY, format: ImageManipulator.SaveFormat.JPEG },
253
596
  );
254
597
  if (!ws.isOpen()) return;
@@ -363,6 +706,10 @@ function LivenessMatchView({
363
706
  setChallengeText(t.liveness.centerFace);
364
707
  showToast('success', t.liveness.getReady);
365
708
  startCaptureLoop(FRAME_MS_DEFAULT);
709
+ // Start the local mp4 recording in parallel with the frame loop, if
710
+ // the backend opted in via `video_upload` in /liveness-init. Pure
711
+ // best-effort: any failure here is logged and never blocks liveness.
712
+ startVideoRecordingIfEnabled();
366
713
  resetWatchdog();
367
714
  return;
368
715
  }
@@ -421,10 +768,26 @@ function LivenessMatchView({
421
768
  // can take several seconds to land while the worker drains
422
769
  // its queue; without this the user would stare at the camera
423
770
  // and the stale instruction the whole time.
771
+ //
772
+ // CRITICAL: the video recording MUST be stopped before the phase
773
+ // change. Switching phase unmounts <LivenessCamera>, which makes
774
+ // vision-camera tear down the recording mid-flush — the
775
+ // `onRecordingFinished` callback never fires and the upload
776
+ // promise stays pending until the 60 s timeout. We stop first,
777
+ // then unmount.
424
778
  const meta = lastChallengeMetaRef.current;
425
779
  if (meta && meta.index >= meta.total - 1) {
780
+ log.info('[Liveness] last challenge complete — preparing to finalize', {
781
+ index: meta.index,
782
+ total: meta.total,
783
+ videoOutcome: videoOutcomeRef.current,
784
+ });
426
785
  stopCapture();
427
- setPhase('finalizing');
786
+ (async () => {
787
+ await stopVideoRecordingIfActive();
788
+ log.info('[Liveness] last challenge: switching phase to finalizing');
789
+ setPhase('finalizing');
790
+ })();
428
791
  }
429
792
  resetWatchdog();
430
793
  return;
@@ -519,8 +882,47 @@ function LivenessMatchView({
519
882
  /* ignore */
520
883
  }
521
884
  wsRef.current = null;
522
- setPhase('finalizing');
885
+ // IMPORTANT: do NOT setPhase('finalizing') yet. Switching phase
886
+ // unmounts LivenessCamera, which cancels the in-flight video
887
+ // recording mid-flush and prevents `onRecordingFinished` from
888
+ // firing — the upload would never start. We stop the recording
889
+ // first (camera still mounted, ref valid), then transition phase
890
+ // and run the verify pipeline.
523
891
  (async () => {
892
+ // ── Settle the video pipeline before /liveness-verify ─────────
893
+ // Best-effort: stop the recording (if still running), then await
894
+ // the upload promise with a hard timeout. Whatever the outcome
895
+ // (uploaded / failed / timeout), we proceed to verify — the body
896
+ // is only attached when the upload actually succeeded.
897
+ await stopVideoRecordingIfActive();
898
+ // Safe to unmount LivenessCamera now: the recording has been
899
+ // flushed and `onRecordingFinished` has been scheduled.
900
+ setPhase('finalizing');
901
+ if (videoUploadPromiseRef.current) {
902
+ log.info('[Liveness] awaiting video upload settle', {
903
+ timeoutMs: VIDEO_UPLOAD_TIMEOUT_MS,
904
+ });
905
+ const uploadPromise = videoUploadPromiseRef.current;
906
+ let uploadTimer: ReturnType<typeof setTimeout> | null = null;
907
+ const timeoutPromise = new Promise<void>((resolve) => {
908
+ uploadTimer = setTimeout(() => {
909
+ log.warn('[Liveness] video upload timed out — verify will go without body');
910
+ videoOutcomeRef.current = 'failed';
911
+ resolve();
912
+ }, VIDEO_UPLOAD_TIMEOUT_MS);
913
+ });
914
+ await Promise.race([uploadPromise, timeoutPromise]);
915
+ if (uploadTimer) clearTimeout(uploadTimer);
916
+ }
917
+ const verifyBody =
918
+ videoOutcomeRef.current === 'uploaded' && videoMetaRef.current
919
+ ? { video: videoMetaRef.current }
920
+ : {};
921
+ log.info('[Liveness] POST /liveness-verify', {
922
+ outcome: videoOutcomeRef.current,
923
+ hasBody: 'video' in verifyBody,
924
+ });
925
+
524
926
  // Bound the verify call with an explicit timeout. SESSION_COMPLETE
525
927
  // already turned the progress watchdog off, so if this POST hangs
526
928
  // (the dev network shows recurring HTTP/2 INTERNAL_ERROR resets)
@@ -535,7 +937,7 @@ function LivenessMatchView({
535
937
  try {
536
938
  await api.post(
537
939
  `/sessions/${sessionId}/liveness-verify`,
538
- {},
940
+ verifyBody,
539
941
  { signal: verifyController.signal },
540
942
  );
541
943
  clearTimeout(verifyTimeout);
@@ -579,7 +981,9 @@ function LivenessMatchView({
579
981
  sessionId,
580
982
  showToast,
581
983
  startCaptureLoop,
984
+ startVideoRecordingIfEnabled,
582
985
  stopCapture,
986
+ stopVideoRecordingIfActive,
583
987
  stopWatchdog,
584
988
  t.liveness.getReady,
585
989
  t.liveness.positioningReady,
@@ -640,6 +1044,27 @@ function LivenessMatchView({
640
1044
  hmacRef.current = null;
641
1045
  }
642
1046
  }
1047
+ // Reset the video pipeline state for this attempt (the host may retry).
1048
+ // We honour `video_upload` even when the host did not register the
1049
+ // `onLivenessVideoUploaded` callback — the upload still happens, only
1050
+ // the host notification is skipped. `outcome` stays `'none'` until
1051
+ // `startVideoRecordingIfEnabled` confirms the recording actually started;
1052
+ // see that callback for why we cannot trust `init.video_upload` alone.
1053
+ videoUploadRef.current = init.video_upload ?? null;
1054
+ videoOutcomeRef.current = 'none';
1055
+ videoMetaRef.current = null;
1056
+ videoUploadPromiseRef.current = null;
1057
+ videoRecordingFinishedPromiseRef.current = null;
1058
+ videoTempPathRef.current = null;
1059
+ if (init.video_upload) {
1060
+ log.info('[Liveness] init.video_upload received', {
1061
+ url: truncateUrl(init.video_upload.upload_url),
1062
+ expiresAt: init.video_upload.expires_at,
1063
+ method: init.video_upload.method,
1064
+ });
1065
+ } else {
1066
+ log.info('[Liveness] init.video_upload absent — recording disabled for this session');
1067
+ }
643
1068
 
644
1069
  setStatusText(t.liveness.preparingCamera);
645
1070
  let connection: IrisConnection;
@@ -735,6 +1160,19 @@ function LivenessMatchView({
735
1160
  stopCapture();
736
1161
  stopWatchdog();
737
1162
  if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
1163
+ // Best-effort video pipeline shutdown on unmount. Stop the recording
1164
+ // if it's still running (vision-camera deletes its temp file when the
1165
+ // <Camera> tears down anyway, but we explicitly stop to flush). Then
1166
+ // delete any temp file we own, so a backed-out user doesn't leak
1167
+ // storage.
1168
+ if (videoOutcomeRef.current === 'recording') {
1169
+ void stopVideoRecordingIfActive();
1170
+ }
1171
+ const leftoverPath = videoTempPathRef.current;
1172
+ videoTempPathRef.current = null;
1173
+ if (leftoverPath) {
1174
+ void deleteVideoTemp(leftoverPath);
1175
+ }
738
1176
  try {
739
1177
  wsRef.current?.close(1000, 'unmount');
740
1178
  } catch {
@@ -8,7 +8,7 @@
8
8
 
9
9
  import type { ReactNode } from 'react';
10
10
  import type { ApiCaller } from '../transport/api';
11
- import type { OnboardingStep, SdkError } from '../types';
11
+ import type { LivenessVideoRef, OnboardingStep, SdkError } from '../types';
12
12
 
13
13
  /**
14
14
  * Internal contract every step module must implement. The orchestrator awaits
@@ -63,6 +63,12 @@ export interface StepDeps {
63
63
  * `LivenessMatchStep`.
64
64
  */
65
65
  livenessCalibrationLabel?: string;
66
+ /**
67
+ * Forwarded `VelionConfig.onLivenessVideoUploaded` callback. Invoked by
68
+ * `LivenessMatchStep` only when the recorded session video uploaded
69
+ * successfully to GCS. Other steps ignore it.
70
+ */
71
+ onLivenessVideoUploaded?: (ref: LivenessVideoRef) => void;
66
72
  }
67
73
 
68
74
  /**
@@ -531,6 +531,16 @@ export interface VelionCallbacks {
531
531
  * (only when the final result screen is shown). `onSuccess` has already run.
532
532
  */
533
533
  onFinalResultScreenDismiss?: () => void;
534
+
535
+ /**
536
+ * Fires when the LIVENESS_MATCH step successfully uploaded the recorded
537
+ * session video to the onboarding storage (GCS PUT returned 200). Best-effort:
538
+ * if the upload failed or the session had no `video_upload` URL, the
539
+ * callback is not invoked — liveness still completes normally.
540
+ *
541
+ * @param ref - URL and metadata of the uploaded video.
542
+ */
543
+ onLivenessVideoUploaded?: (ref: LivenessVideoRef) => void;
534
544
  }
535
545
 
536
546
  // ─────────────────────────────────────────────────────────────────────────────
@@ -887,6 +897,57 @@ export interface LivenessSessionResponse {
887
897
  * frame in a JSON envelope (canonical line: `sessionId\nframeId\nts\nsha256hex(jpeg)`).
888
898
  */
889
899
  frame_integrity_key_base64?: string;
900
+ /**
901
+ * Signed PUT URL the SDK uses to upload the locally-recorded liveness video
902
+ * directly to the onboarding GCS bucket. `null` when video recording is
903
+ * disabled or the signing failed — the SDK should skip the upload silently
904
+ * (liveness still works without the video; only the back-office loses the
905
+ * playback evidence).
906
+ */
907
+ video_upload?: VideoUpload | null;
908
+ }
909
+
910
+ /**
911
+ * Signed-upload payload returned by `POST /liveness-init`. Mirrors the backend
912
+ * `LivenessInitResponseDto.VideoUpload`. The SDK PUTs the recorded mp4 bytes
913
+ * to `upload_url` (Content-Type matching `video/mp4`) before calling
914
+ * `POST /liveness-verify` with the resulting metadata.
915
+ */
916
+ export interface VideoUpload {
917
+ /** Absolute https://storage.googleapis.com/... URL with V4 signature params. */
918
+ upload_url: string;
919
+ /** ISO-8601 instant after which GCS rejects the signature. */
920
+ expires_at: string;
921
+ /** HTTP method to use. Always `"PUT"` today; future-proofing. */
922
+ method: 'PUT' | string;
923
+ }
924
+
925
+ /**
926
+ * Optional body of `POST /liveness-verify`. The SDK only includes it when the
927
+ * recorded video uploaded successfully (HTTP 200 from GCS). When omitted, the
928
+ * backend completes liveness based on the Iris score only.
929
+ */
930
+ export interface LivenessVerifyVideoMeta {
931
+ /** MIME type that was sent in the PUT `Content-Type` header. */
932
+ content_type: string;
933
+ /** Recorded video duration in milliseconds, or `null` if vision-camera did not report it. */
934
+ duration_ms: number | null;
935
+ }
936
+
937
+ /**
938
+ * Payload delivered to the optional `onLivenessVideoUploaded` callback after a
939
+ * successful upload of the liveness video. Best-effort: the callback only
940
+ * fires when the GCS PUT returned 200.
941
+ */
942
+ export interface LivenessVideoRef {
943
+ /** Signed `upload_url` the SDK PUT the video to (without the signature query). */
944
+ upload_url: string;
945
+ /** MIME type used in the PUT. */
946
+ content_type: string;
947
+ /** Recorded video duration in milliseconds, or `null` when unknown. */
948
+ duration_ms: number | null;
949
+ /** Recorded file size in bytes, or `null` when unknown. */
950
+ size_bytes: number | null;
890
951
  }
891
952
 
892
953
  /**