@velion-la/onboarding-sdk-react-native 1.3.0-beta.2 → 1.3.0-beta.20

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 (97) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +66 -1
  3. package/android/build.gradle +15 -0
  4. package/android/src/main/java/la/velion/onboarding/sdk/devicekey/VelionDeviceKeyModule.kt +94 -0
  5. package/app.plugin.js +19 -2
  6. package/expo-module.config.json +9 -0
  7. package/ios/VelionDeviceKey.podspec +25 -0
  8. package/ios/VelionDeviceKeyModule.swift +76 -0
  9. package/lib/commonjs/core/VelionOnboarding.js +4 -1
  10. package/lib/commonjs/core/VelionOnboarding.js.map +1 -1
  11. package/lib/commonjs/steps/FingerprintStep.js +1 -0
  12. package/lib/commonjs/steps/FingerprintStep.js.map +1 -1
  13. package/lib/commonjs/steps/LivenessMatchStep.js +53 -8
  14. package/lib/commonjs/steps/LivenessMatchStep.js.map +1 -1
  15. package/lib/commonjs/steps/livenessRestart.js +32 -0
  16. package/lib/commonjs/steps/livenessRestart.js.map +1 -0
  17. package/lib/commonjs/transport/api.js +17 -1
  18. package/lib/commonjs/transport/api.js.map +1 -1
  19. package/lib/commonjs/types/index.js +12 -0
  20. package/lib/commonjs/types/index.js.map +1 -1
  21. package/lib/commonjs/utils/appId.js +22 -0
  22. package/lib/commonjs/utils/appId.js.map +1 -0
  23. package/lib/commonjs/utils/deviceFingerprint.js +1 -1
  24. package/lib/commonjs/utils/deviceFingerprint.js.map +1 -1
  25. package/lib/commonjs/utils/deviceIntegrity.js +103 -0
  26. package/lib/commonjs/utils/deviceIntegrity.js.map +1 -0
  27. package/lib/commonjs/utils/deviceKey.js +53 -0
  28. package/lib/commonjs/utils/deviceKey.js.map +1 -0
  29. package/lib/commonjs/utils/frameChain.js +55 -0
  30. package/lib/commonjs/utils/frameChain.js.map +1 -0
  31. package/lib/commonjs/utils/hmac.js +6 -4
  32. package/lib/commonjs/utils/hmac.js.map +1 -1
  33. package/lib/commonjs/utils/jpegFromUri.js.map +1 -1
  34. package/lib/module/core/VelionOnboarding.js +4 -1
  35. package/lib/module/core/VelionOnboarding.js.map +1 -1
  36. package/lib/module/steps/FingerprintStep.js +1 -0
  37. package/lib/module/steps/FingerprintStep.js.map +1 -1
  38. package/lib/module/steps/LivenessMatchStep.js +53 -8
  39. package/lib/module/steps/LivenessMatchStep.js.map +1 -1
  40. package/lib/module/steps/livenessRestart.js +28 -0
  41. package/lib/module/steps/livenessRestart.js.map +1 -0
  42. package/lib/module/transport/api.js +17 -1
  43. package/lib/module/transport/api.js.map +1 -1
  44. package/lib/module/types/index.js +13 -0
  45. package/lib/module/types/index.js.map +1 -1
  46. package/lib/module/utils/appId.js +18 -0
  47. package/lib/module/utils/appId.js.map +1 -0
  48. package/lib/module/utils/deviceFingerprint.js +1 -1
  49. package/lib/module/utils/deviceFingerprint.js.map +1 -1
  50. package/lib/module/utils/deviceIntegrity.js +99 -0
  51. package/lib/module/utils/deviceIntegrity.js.map +1 -0
  52. package/lib/module/utils/deviceKey.js +46 -0
  53. package/lib/module/utils/deviceKey.js.map +1 -0
  54. package/lib/module/utils/frameChain.js +52 -0
  55. package/lib/module/utils/frameChain.js.map +1 -0
  56. package/lib/module/utils/hmac.js +6 -4
  57. package/lib/module/utils/hmac.js.map +1 -1
  58. package/lib/module/utils/jpegFromUri.js.map +1 -1
  59. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  60. package/lib/typescript/steps/FingerprintStep.d.ts.map +1 -1
  61. package/lib/typescript/steps/LivenessMatchStep.d.ts.map +1 -1
  62. package/lib/typescript/steps/livenessRestart.d.ts +25 -0
  63. package/lib/typescript/steps/livenessRestart.d.ts.map +1 -0
  64. package/lib/typescript/steps/types.d.ts +2 -0
  65. package/lib/typescript/steps/types.d.ts.map +1 -1
  66. package/lib/typescript/transport/api.d.ts.map +1 -1
  67. package/lib/typescript/types/index.d.ts +34 -0
  68. package/lib/typescript/types/index.d.ts.map +1 -1
  69. package/lib/typescript/utils/appId.d.ts +8 -0
  70. package/lib/typescript/utils/appId.d.ts.map +1 -0
  71. package/lib/typescript/utils/deviceFingerprint.d.ts +2 -0
  72. package/lib/typescript/utils/deviceFingerprint.d.ts.map +1 -1
  73. package/lib/typescript/utils/deviceIntegrity.d.ts +20 -0
  74. package/lib/typescript/utils/deviceIntegrity.d.ts.map +1 -0
  75. package/lib/typescript/utils/deviceKey.d.ts +13 -0
  76. package/lib/typescript/utils/deviceKey.d.ts.map +1 -0
  77. package/lib/typescript/utils/frameChain.d.ts +15 -0
  78. package/lib/typescript/utils/frameChain.d.ts.map +1 -0
  79. package/lib/typescript/utils/hmac.d.ts +3 -1
  80. package/lib/typescript/utils/hmac.d.ts.map +1 -1
  81. package/lib/typescript/utils/jpegFromUri.d.ts +1 -1
  82. package/lib/typescript/utils/jpegFromUri.d.ts.map +1 -1
  83. package/package.json +14 -9
  84. package/src/core/VelionOnboarding.ts +4 -1
  85. package/src/steps/FingerprintStep.tsx +1 -0
  86. package/src/steps/LivenessMatchStep.tsx +57 -8
  87. package/src/steps/livenessRestart.ts +32 -0
  88. package/src/steps/types.ts +2 -0
  89. package/src/transport/api.ts +17 -0
  90. package/src/types/index.ts +37 -0
  91. package/src/utils/appId.ts +15 -0
  92. package/src/utils/deviceFingerprint.ts +3 -1
  93. package/src/utils/deviceIntegrity.ts +102 -0
  94. package/src/utils/deviceKey.ts +52 -0
  95. package/src/utils/frameChain.ts +56 -0
  96. package/src/utils/hmac.ts +8 -5
  97. package/src/utils/jpegFromUri.ts +1 -1
@@ -1 +1 @@
1
- {"version":3,"file":"jpegFromUri.d.ts","sourceRoot":"","sources":["../../../src/utils/jpegFromUri.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAYD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGvE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAIvE"}
1
+ {"version":3,"file":"jpegFromUri.d.ts","sourceRoot":"","sources":["../../../src/utils/jpegFromUri.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAYD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAGpF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAIvE"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velion-la/onboarding-sdk-react-native",
3
- "version": "1.3.0-beta.2",
3
+ "version": "1.3.0-beta.20",
4
4
  "description": "Native React Native SDK for the Velion Onboarding (KYC) flow: ID document OCR, passive + active liveness, device fingerprint, OTP verification, address picker, and personal / legal information forms.",
5
5
  "main": "./lib/commonjs/index.js",
6
6
  "module": "./lib/module/index.js",
@@ -21,6 +21,10 @@
21
21
  "src",
22
22
  "lib",
23
23
  "app.plugin.js",
24
+ "expo-module.config.json",
25
+ "ios",
26
+ "android",
27
+ "!android/build",
24
28
  "CHANGELOG.md",
25
29
  "LICENSE",
26
30
  "README.md",
@@ -57,20 +61,21 @@
57
61
  "registry": "https://registry.npmjs.org/"
58
62
  },
59
63
  "dependencies": {
64
+ "@expo/app-integrity": "~57.0.2",
60
65
  "@noble/hashes": "^1.5.0",
61
- "expo-application": "~57.0.2",
66
+ "expo-application": "~57.0.3",
62
67
  "expo-constants": "~57.0.17",
63
- "expo-crypto": "~57.0.2",
64
- "expo-device": "~57.0.1",
68
+ "expo-crypto": "~57.0.4",
69
+ "expo-device": "~57.0.2",
65
70
  "expo-file-system": "~57.0.6",
66
- "expo-image-manipulator": "~57.0.16",
71
+ "expo-image-manipulator": "~57.0.21",
67
72
  "expo-keep-awake": "~57.0.1",
68
- "expo-location": "~57.0.16",
73
+ "expo-location": "~57.0.22",
69
74
  "react-native-sse": "^1.2.1"
70
75
  },
71
76
  "peerDependencies": {
72
77
  "@expo/vector-icons": ">=15.0.0",
73
- "@fingerprintjs/fingerprintjs-pro-react-native": ">=3.0.0",
78
+ "@fingerprintjs/fingerprintjs-pro-react-native": "^3.17.1",
74
79
  "expo": ">=57.0.0",
75
80
  "react": ">=19.2.0",
76
81
  "react-native": ">=0.86.0",
@@ -102,8 +107,8 @@
102
107
  "del-cli": "^6.0.0",
103
108
  "jest": "^29.7.0",
104
109
  "react-native-builder-bob": "^0.40.0",
105
- "ts-jest": "^29.2.5",
106
- "typescript": "~5.8.3"
110
+ "ts-jest": "^29.4.15",
111
+ "typescript": "~5.9.3"
107
112
  },
108
113
  "react-native-builder-bob": {
109
114
  "source": "src",
@@ -361,7 +361,7 @@ export class VelionOnboarding {
361
361
  );
362
362
  } catch (err) {
363
363
  this.showLoading(null);
364
- if (isSessionTokenAuthSdkError(err)) {
364
+ if (isSessionTokenAuthSdkError(err) || (err as SdkError | null)?.code === SdkErrorCode.APP_NOT_ALLOWED) {
365
365
  throw err;
366
366
  }
367
367
  throw {
@@ -646,6 +646,9 @@ export class VelionOnboarding {
646
646
  ...(this.config.fingerprintTimeoutMs !== undefined && {
647
647
  fingerprintTimeoutMs: this.config.fingerprintTimeoutMs,
648
648
  }),
649
+ ...(this.config.googleCloudProjectNumber !== undefined && {
650
+ googleCloudProjectNumber: this.config.googleCloudProjectNumber,
651
+ }),
649
652
  ...(this.config.livenessCalibrationLabel !== undefined && {
650
653
  livenessCalibrationLabel: this.config.livenessCalibrationLabel,
651
654
  }),
@@ -48,6 +48,7 @@ export class FingerprintStep implements StepModule {
48
48
  let result: DeviceFingerprintResult;
49
49
  try {
50
50
  result = await generateDeviceFingerprint({
51
+ sessionId: this.deps.sessionId,
51
52
  endpoint: this.deps.fingerprintEndpoint ?? DEFAULT_FINGERPRINT_ENDPOINT,
52
53
  ...(this.deps.fingerprintApiKey !== undefined && {
53
54
  apiKey: this.deps.fingerprintApiKey,
@@ -40,6 +40,9 @@ import { StepShell } from '../ui/StepShell';
40
40
  import { StepIcon } from '../ui/icons/StepIcon';
41
41
  import { mixHex, useTheme } from '../ui/theme';
42
42
  import { getStrings } from '../i18n';
43
+ import { submitDeviceIntegrity } from '../utils/deviceIntegrity';
44
+ import { destroyDeviceKey, signWithDeviceKey } from '../utils/deviceKey';
45
+ import { createFrameChain, type FrameChain } from '../utils/frameChain';
43
46
  import { log } from '../utils/log';
44
47
  import {
45
48
  byteLengthOfUri,
@@ -60,6 +63,7 @@ import {
60
63
  type IrisConnection,
61
64
  type IrisServerMessage,
62
65
  } from '../transport/irisWebSocket';
66
+ import { planLivenessRestart, type LivenessPhase } from './livenessRestart';
63
67
  import {
64
68
  LivenessCamera,
65
69
  type LivenessCameraHandle,
@@ -301,6 +305,7 @@ export class LivenessMatchStep implements StepModule {
301
305
  sessionId={this.deps.sessionId}
302
306
  locale={this.deps.locale}
303
307
  calibrationLabel={this.deps.livenessCalibrationLabel}
308
+ googleCloudProjectNumber={this.deps.googleCloudProjectNumber}
304
309
  showIntro
305
310
  showBackButton
306
311
  onVideoUploaded={this.deps.onLivenessVideoUploaded}
@@ -331,6 +336,7 @@ interface ViewProps {
331
336
  locale: string;
332
337
  /** Optional Iris calibration label forwarded to /liveness-init body. */
333
338
  calibrationLabel?: string | undefined;
339
+ googleCloudProjectNumber?: string | undefined;
334
340
  showIntro: boolean;
335
341
  showBackButton: boolean;
336
342
  /** Best-effort: fires only on a successful video upload (HTTP 200 from GCS). */
@@ -339,13 +345,14 @@ interface ViewProps {
339
345
  onCancel: (err: SdkError) => void;
340
346
  }
341
347
 
342
- type Phase = 'intro' | 'capturing' | 'finalizing';
348
+ type Phase = LivenessPhase;
343
349
 
344
350
  function LivenessMatchView({
345
351
  api,
346
352
  sessionId,
347
353
  locale,
348
354
  calibrationLabel,
355
+ googleCloudProjectNumber,
349
356
  showIntro,
350
357
  showBackButton,
351
358
  onVideoUploaded,
@@ -357,6 +364,9 @@ function LivenessMatchView({
357
364
  const cameraRef = useRef<LivenessCameraHandle>(null);
358
365
 
359
366
  const [phase, setPhase] = useState<Phase>(showIntro ? 'intro' : 'capturing');
367
+ // Bumped on every verification attempt, so work scheduled by one attempt
368
+ // (the async switch to `finalizing`) cannot land on the next one.
369
+ const attemptRef = useRef(0);
360
370
  const [statusText, setStatusText] = useState<string | null>(null);
361
371
  const [challengeText, setChallengeText] = useState<string | null>(null);
362
372
  const [ovalCue, setOvalCue] = useState<LivenessOvalCue>('NEUTRAL');
@@ -375,6 +385,7 @@ function LivenessMatchView({
375
385
  // triggering re-renders: kept in refs.
376
386
  const wsRef = useRef<IrisConnection | null>(null);
377
387
  const hmacRef = useRef<HmacKey | null>(null);
388
+ const frameChainRef = useRef<FrameChain | null>(null);
378
389
  const livenessSessionIdRef = useRef<string | null>(null);
379
390
  const currentChallengeRef = useRef<IrisChallenge | null>(null);
380
391
  // Tracks the position of the active challenge inside the session sequence
@@ -419,6 +430,8 @@ function LivenessMatchView({
419
430
  // warnings flash in <2s and the user couldn't read them).
420
431
  const activeToastRef = useRef<{ kind: 'success' | 'warning'; message: string } | null>(null);
421
432
 
433
+ const unmountedRef = useRef(false);
434
+
422
435
  // ── Video recording state (OSDKR-4) ─────────────────────────────────────
423
436
  // `videoUploadRef` holds the signed URL returned by /liveness-init when the
424
437
  // backend enabled video capture for this session. `null` → skip recording.
@@ -842,7 +855,8 @@ function LivenessMatchView({
842
855
  });
843
856
  }
844
857
  const key = hmacRef.current;
845
- if (key) {
858
+ const frameChain = frameChainRef.current;
859
+ if (key || frameChain) {
846
860
  const envelope = buildSignedFrameEnvelope({
847
861
  key,
848
862
  sessionId: livenessSessionIdRef.current ?? sessionId,
@@ -851,6 +865,7 @@ function LivenessMatchView({
851
865
  jpegBase64: jpeg.base64,
852
866
  });
853
867
  ws.sendJson(envelope.json);
868
+ frameChain?.addFrame(framesSentRef.current, envelope.canonical);
854
869
  } else {
855
870
  // Vision-camera + RN's WebSocket need an ArrayBuffer for binary frames.
856
871
  // `Uint8Array.buffer` is a `SharedArrayBuffer` on some Hermes versions
@@ -1080,8 +1095,13 @@ function LivenessMatchView({
1080
1095
  videoOutcome: videoOutcomeRef.current,
1081
1096
  });
1082
1097
  stopCapture();
1098
+ const attempt = attemptRef.current;
1083
1099
  (async () => {
1084
1100
  await stopVideoRecordingIfActive();
1101
+ // A terminal WARNING can arrive while the recording flushes and
1102
+ // the user may already have retried: leaving the new attempt
1103
+ // without a camera is OSDKR-39 again.
1104
+ if (attempt !== attemptRef.current) return;
1085
1105
  log.info('[Liveness] last challenge: switching phase to finalizing');
1086
1106
  setPhase('finalizing');
1087
1107
  })();
@@ -1306,6 +1326,7 @@ function LivenessMatchView({
1306
1326
  );
1307
1327
 
1308
1328
  const startVerification = useCallback(async () => {
1329
+ attemptRef.current += 1;
1309
1330
  setBannerError(null);
1310
1331
  setRetry(null);
1311
1332
  setStatusText(t.liveness.connecting);
@@ -1317,6 +1338,14 @@ function LivenessMatchView({
1317
1338
  frameMsRef.current = FRAME_MS_DEFAULT;
1318
1339
  hmacRef.current = null;
1319
1340
 
1341
+ frameChainRef.current = null;
1342
+ const hasDeviceKey = await submitDeviceIntegrity(api, sessionId, googleCloudProjectNumber);
1343
+ // Attestation can take seconds: the user may have left the step meanwhile.
1344
+ if (unmountedRef.current) {
1345
+ destroyDeviceKey();
1346
+ return;
1347
+ }
1348
+
1320
1349
  let init: LivenessSessionResponse;
1321
1350
  try {
1322
1351
  // `calibration_label` is the wire name expected by the backend
@@ -1349,6 +1378,11 @@ function LivenessMatchView({
1349
1378
  return;
1350
1379
  }
1351
1380
  livenessSessionIdRef.current = init.liveness_session_id;
1381
+ if (hasDeviceKey) {
1382
+ frameChainRef.current = createFrameChain(init.liveness_session_id, signWithDeviceKey, (json) => {
1383
+ wsRef.current?.sendJson(json);
1384
+ });
1385
+ }
1352
1386
  if (init.frame_integrity_key_base64) {
1353
1387
  try {
1354
1388
  hmacRef.current = importHmacKey(init.frame_integrity_key_base64);
@@ -1437,6 +1471,7 @@ function LivenessMatchView({
1437
1471
  }, [
1438
1472
  api,
1439
1473
  calibrationLabel,
1474
+ googleCloudProjectNumber,
1440
1475
  failWith,
1441
1476
  handleWsMessage,
1442
1477
  locale,
@@ -1449,15 +1484,26 @@ function LivenessMatchView({
1449
1484
  t.liveness.terminalRetryFallback,
1450
1485
  ]);
1451
1486
 
1452
- // Re-run after a terminal retry — same cleanup as start, but reuses the
1453
- // mounted camera (no DOM teardown).
1487
+ // Re-run after a terminal retry. The retry dialog replaced the camera, and
1488
+ // the step may have reached `finalizing` before the session failed, so the
1489
+ // phase has to go back to `capturing` or the new WebSocket gets no frames
1490
+ // (OSDKR-39). Entering `capturing` starts the verification through the
1491
+ // phase effect; only when the phase is already `capturing` do we start it.
1454
1492
  const restartVerification = useCallback(async () => {
1455
1493
  setRetry(null);
1456
1494
  setProgress(null);
1457
1495
  setChallengeText(null);
1458
1496
  setOvalCue('NEUTRAL');
1459
- await startVerification();
1460
- }, [startVerification]);
1497
+ const plan = planLivenessRestart(phase);
1498
+ if (plan.startNow) {
1499
+ await startVerification();
1500
+ return;
1501
+ }
1502
+ // Invalidate the previous attempt now: its pending switch to `finalizing`
1503
+ // must not undo this phase change before the effect starts the new one.
1504
+ attemptRef.current += 1;
1505
+ setPhase(plan.phase);
1506
+ }, [phase, startVerification]);
1461
1507
 
1462
1508
  // Effect: when the user enters the capture phase (intro skipped or
1463
1509
  // confirmed), run the start sequence.
@@ -1472,8 +1518,8 @@ function LivenessMatchView({
1472
1518
  useEffect(() => {
1473
1519
  if (phase !== 'capturing') return;
1474
1520
  void startVerification();
1475
- // We intentionally only re-run when phase flips into capturing — the
1476
- // first start; the retry path is handled by `restartVerification`.
1521
+ // We intentionally only re-run when phase flips into capturing: the first
1522
+ // start, and a retry from `finalizing` (see `restartVerification`).
1477
1523
  // eslint-disable-next-line react-hooks/exhaustive-deps
1478
1524
  }, [phase]);
1479
1525
 
@@ -1483,7 +1529,10 @@ function LivenessMatchView({
1483
1529
  // / fail / terminal-retry handlers already close the WS explicitly when
1484
1530
  // the flow ends normally; this is the safety net for an actual unmount.
1485
1531
  useEffect(() => {
1532
+ unmountedRef.current = false;
1486
1533
  return () => {
1534
+ unmountedRef.current = true;
1535
+ destroyDeviceKey();
1487
1536
  stopCapture();
1488
1537
  stopWatchdog();
1489
1538
  if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Where the liveness step has to be for a retry to actually capture frames.
3
+ *
4
+ * The camera is only mounted in the `capturing` phase: `intro` shows the tips
5
+ * and `finalizing` shows the analyzing overlay. A terminal WARNING can land
6
+ * after the last CHALLENGE_COMPLETE already switched the step to `finalizing`
7
+ * — Iris only reports CHALLENGE_NOT_CONFIRMED once the whole sequence ran, so
8
+ * a challenge that timed out earlier fails the session after the last one
9
+ * passed. Restarting the verification from there opened a fresh WebSocket
10
+ * with no camera behind it: Iris received no frames and the user was stuck on
11
+ * the overlay until the watchdog fired (OSDKR-39).
12
+ */
13
+
14
+ export type LivenessPhase = 'intro' | 'capturing' | 'finalizing';
15
+
16
+ export interface LivenessRestartPlan {
17
+ /** Phase the step must be in for the new attempt. */
18
+ phase: LivenessPhase;
19
+ /**
20
+ * Whether the caller starts the verification itself. `false` when the phase
21
+ * changes, because entering `capturing` already starts it — starting it here
22
+ * too would open two Iris sessions.
23
+ */
24
+ startNow: boolean;
25
+ }
26
+
27
+ export function planLivenessRestart(current: LivenessPhase): LivenessRestartPlan {
28
+ if (current === 'capturing') {
29
+ return { phase: 'capturing', startNow: true };
30
+ }
31
+ return { phase: 'capturing', startNow: false };
32
+ }
@@ -78,6 +78,8 @@ export interface StepDeps {
78
78
  * `LivenessMatchStep`.
79
79
  */
80
80
  livenessCalibrationLabel?: string;
81
+ /** See `VelionConfig.googleCloudProjectNumber`. Only read by `LivenessMatchStep`. */
82
+ googleCloudProjectNumber?: string;
81
83
  /**
82
84
  * Forwarded `VelionConfig.onLivenessVideoUploaded` callback. Invoked by
83
85
  * `LivenessMatchStep` only when the recorded session video uploaded
@@ -17,6 +17,7 @@
17
17
 
18
18
  import { SdkErrorCode, type SdkError } from '../types';
19
19
  import { isSecureHttpUrl } from './secureUrl';
20
+ import { getAppId } from '../utils/appId';
20
21
  import { log } from '../utils/log';
21
22
  import { SDK_VERSION } from '../utils/sdkVersion';
22
23
 
@@ -25,6 +26,9 @@ const CLOCK_SKEW_WARN_HOURS = 24;
25
26
 
26
27
  const SESSION_EXPIRED_CODE = SdkErrorCode.SESSION_EXPIRED;
27
28
 
29
+ /** Backend code for an app outside the organization's enforced allowed apps. */
30
+ const APP_ID_NOT_ALLOWED_BACKEND_CODE = 'VOB-40302';
31
+
28
32
  interface BackendErrorBody {
29
33
  message?: string;
30
34
  code?: string;
@@ -88,6 +92,7 @@ export function createApiCaller(
88
92
  let currentToken = sessionToken;
89
93
  let currentExpiresAt = expiresAt;
90
94
  let clockSkewWarned = false;
95
+ const appId = getAppId();
91
96
 
92
97
  function ensureTokenValid(): void {
93
98
  if (!currentExpiresAt) return;
@@ -121,6 +126,7 @@ export function createApiCaller(
121
126
  ...extra,
122
127
  Authorization: `Bearer ${currentToken}`,
123
128
  'X-Velion-SDK-Version': SDK_VERSION,
129
+ ...(appId !== null && { 'X-App-Id': appId }),
124
130
  };
125
131
  }
126
132
 
@@ -165,6 +171,17 @@ export function createApiCaller(
165
171
  // Body may not be JSON (e.g., a 502 from a proxy). That's fine.
166
172
  }
167
173
 
174
+ if (errorBody.code === APP_ID_NOT_ALLOWED_BACKEND_CODE) {
175
+ throw {
176
+ code: SdkErrorCode.APP_NOT_ALLOWED,
177
+ message:
178
+ `App "${appId ?? 'unknown'}" is not allowed for this organization. ` +
179
+ 'Register it in the allowed apps of the SDK settings in the Velion portal.',
180
+ cause: errorBody,
181
+ httpStatus: response.status,
182
+ } satisfies SdkError;
183
+ }
184
+
168
185
  throw buildApiError(
169
186
  errorBody.message ??
170
187
  `Backend returned ${response.status} on ${endpoint}.`,
@@ -289,6 +289,12 @@ export enum SdkErrorCode {
289
289
  SESSION_INVALID = 'SESSION_INVALID',
290
290
  /** The sessionToken has expired (typically a 401 after initial validation). */
291
291
  SESSION_EXPIRED = 'SESSION_EXPIRED',
292
+ /**
293
+ * The organization enforces its allowed apps and this app is not on the list
294
+ * (403 `VOB-40302` on `GET /sessions/:id`). The message names the app id to
295
+ * register; retrying does not help.
296
+ */
297
+ APP_NOT_ALLOWED = 'APP_NOT_ALLOWED',
292
298
  /** Could not fetch the initial session state from the backend. */
293
299
  SESSION_FETCH_FAILED = 'SESSION_FETCH_FAILED',
294
300
  /** Backend sent SESSION_DECLINED over SSE; session ended before completion. */
@@ -803,6 +809,14 @@ export interface VelionConfig extends VelionCallbacks {
803
809
  */
804
810
  routingTimeoutMs?: number;
805
811
 
812
+ /**
813
+ * Number of the Google Cloud project linked to your app in Play Console, used
814
+ * to request Play Integrity tokens on Android. Without it the session reports
815
+ * no attestation and the workflow's integrity policy decides. iOS needs the
816
+ * `appAttestEnvironment` option of the config plugin instead.
817
+ */
818
+ googleCloudProjectNumber?: string;
819
+
806
820
  /**
807
821
  * Google Maps Platform API key (Maps JavaScript API + Places). Required for the
808
822
  * {@code ADDRESS_INFO} step to show the map, search, and geocoding. Omit only if
@@ -1069,6 +1083,29 @@ export interface VideoUpload {
1069
1083
  * recorded video uploaded successfully (HTTP 200 from GCS). When omitted, the
1070
1084
  * backend completes liveness based on the Iris score only.
1071
1085
  */
1086
+ /** `POST /sessions/:id/integrity-challenge` response. Single use, valid for 5 minutes. */
1087
+ export interface IntegrityChallengeResponse {
1088
+ challenge: string;
1089
+ }
1090
+
1091
+ /**
1092
+ * `POST /sessions/:id/integrity` body. `token` is absent when the device could
1093
+ * not attest; otherwise it is the Play Integrity token on Android and
1094
+ * `<key id>.<attestation object in base64>` on iOS, both over the challenge.
1095
+ */
1096
+ export interface SubmitIntegrityPayload {
1097
+ challenge: string;
1098
+ platform: 'IOS' | 'ANDROID';
1099
+ token?: string;
1100
+ /**
1101
+ * SPKI of the hardware key that signs the frames, in base64. When present,
1102
+ * the attestation is made over `<challenge>.<sha256 hex of this value>`.
1103
+ */
1104
+ device_public_key?: string;
1105
+ /** Risk codes such as `ROOTED` or `EMULATOR`. They never stop the flow. */
1106
+ capture_signals?: string[];
1107
+ }
1108
+
1072
1109
  export interface LivenessVerifyVideoMeta {
1073
1110
  /** MIME type that was sent in the PUT `Content-Type` header. */
1074
1111
  content_type: string;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * @fileoverview Identifies the host app to the backend, in the format of the
3
+ * organization's `allowed_app_ids`. It can be forged: this keeps accidental
4
+ * integrations and basic scripts out, and proves nothing about the app.
5
+ */
6
+
7
+ import * as Application from 'expo-application';
8
+ import { Platform } from 'react-native';
9
+
10
+ /** `ios:<bundle id>` or `android:<package name>`; `null` when there is no native id to read. */
11
+ export function getAppId(): string | null {
12
+ if (Platform.OS !== 'ios' && Platform.OS !== 'android') return null;
13
+ const id = Application.applicationId;
14
+ return id ? `${Platform.OS}:${id}` : null;
15
+ }
@@ -29,6 +29,8 @@ export interface DeviceFingerprintResult {
29
29
  }
30
30
 
31
31
  export interface DeviceFingerprintOptions {
32
+ /** Onboarding session the event belongs to; sent as `linkedId` so the backend can refuse an event from another one. */
33
+ sessionId: string;
32
34
  /** Custom endpoint subdomain (proxied through Velion infra). */
33
35
  endpoint: string;
34
36
  /** Optional override for the public Fingerprint Pro key. */
@@ -138,7 +140,7 @@ export async function generateDeviceFingerprint(
138
140
  let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
139
141
  try {
140
142
  visitorData = await Promise.race([
141
- agent.getVisitorData(),
143
+ agent.getVisitorData(undefined, options.sessionId),
142
144
  new Promise<never>((_resolve, reject) => {
143
145
  timeoutHandle = setTimeout(
144
146
  () =>
@@ -0,0 +1,102 @@
1
+ /**
2
+ * @fileoverview Attests the app before liveness (ADR-062). Best-effort: the
3
+ * workflow's policy decides what a missing attestation means, so nothing here
4
+ * may stop the flow.
5
+ *
6
+ * iOS attests a new key per attempt instead of keeping one for assertions, so
7
+ * the SDK stores nothing on the device and the backend keeps no key per install.
8
+ *
9
+ * App Attest keys only sign assertions and Play Integrity has none, so frames are
10
+ * signed with a separate hardware key. The attestation covers its hash: that is
11
+ * what ties the key to the genuine app.
12
+ */
13
+
14
+ import * as AppIntegrity from '@expo/app-integrity';
15
+ import { Platform } from 'react-native';
16
+ import type { ApiCaller } from '../transport/api';
17
+ import { sha256 } from '@noble/hashes/sha256';
18
+ import type { IntegrityChallengeResponse, SubmitIntegrityPayload } from '../types';
19
+ import { bytesToHexLower } from './base64';
20
+ import { createDeviceKey, getDeviceRiskSignals } from './deviceKey';
21
+ import { log } from './log';
22
+
23
+ /** The first iOS attestation can take seconds, but it must not hold the user for long. */
24
+ const ATTESTATION_TIMEOUT_MS = 10_000;
25
+
26
+ /** Leaves room for the attestation and the two calls around it. */
27
+ const REPORT_TIMEOUT_MS = 15_000;
28
+
29
+ async function attest(challenge: string, googleCloudProjectNumber?: string): Promise<string | undefined> {
30
+ if (Platform.OS === 'ios') {
31
+ if (!AppIntegrity.isSupported) return undefined;
32
+ const keyId = await AppIntegrity.generateKeyAsync();
33
+ const attestation = await AppIntegrity.attestKeyAsync(keyId, challenge);
34
+ return `${keyId}.${attestation}`;
35
+ }
36
+ if (!googleCloudProjectNumber) return undefined;
37
+ await AppIntegrity.prepareIntegrityTokenProviderAsync(googleCloudProjectNumber);
38
+ return AppIntegrity.requestIntegrityCheckAsync(challenge);
39
+ }
40
+
41
+ /** Resolves to `undefined` past the limit, so neither a device nor the network can hold the flow. */
42
+ async function within<T>(work: Promise<T>, limitMs: number): Promise<T | undefined> {
43
+ let timer: ReturnType<typeof setTimeout> | undefined;
44
+ const timeout = new Promise<undefined>((resolve) => {
45
+ timer = setTimeout(() => resolve(undefined), limitMs);
46
+ });
47
+ try {
48
+ return await Promise.race([work, timeout]);
49
+ } finally {
50
+ clearTimeout(timer);
51
+ }
52
+ }
53
+
54
+ async function attestOrSkip(challenge: string, googleCloudProjectNumber?: string): Promise<string | undefined> {
55
+ try {
56
+ return await within(attest(challenge, googleCloudProjectNumber), ATTESTATION_TIMEOUT_MS);
57
+ } catch (err) {
58
+ log.warn('[Integrity] attestation unavailable', err);
59
+ return undefined;
60
+ }
61
+ }
62
+
63
+ async function report(api: ApiCaller, sessionId: string, googleCloudProjectNumber?: string): Promise<boolean> {
64
+ const { challenge } = await api.post<IntegrityChallengeResponse>(
65
+ `/sessions/${sessionId}/integrity-challenge`,
66
+ {},
67
+ );
68
+ const devicePublicKey = await createDeviceKey();
69
+ const attested = devicePublicKey
70
+ ? `${challenge}.${bytesToHexLower(sha256(new TextEncoder().encode(devicePublicKey)))}`
71
+ : challenge;
72
+ const token = await attestOrSkip(attested, googleCloudProjectNumber);
73
+ const signals = getDeviceRiskSignals();
74
+ const payload: SubmitIntegrityPayload = {
75
+ challenge,
76
+ platform: Platform.OS === 'ios' ? 'IOS' : 'ANDROID',
77
+ ...(token !== undefined && { token }),
78
+ ...(devicePublicKey && { device_public_key: devicePublicKey }),
79
+ ...(signals.length > 0 && { capture_signals: signals }),
80
+ };
81
+ await api.post(`/sessions/${sessionId}/integrity`, payload);
82
+ return devicePublicKey !== null;
83
+ }
84
+
85
+ /**
86
+ * Reports the attestation of the session; a device that cannot attest reports without a token.
87
+ *
88
+ * @returns whether the session has a hardware key to sign its frames with
89
+ */
90
+ export async function submitDeviceIntegrity(
91
+ api: ApiCaller,
92
+ sessionId: string,
93
+ googleCloudProjectNumber?: string,
94
+ ): Promise<boolean> {
95
+ if (Platform.OS !== 'ios' && Platform.OS !== 'android') return false;
96
+ try {
97
+ return (await within(report(api, sessionId, googleCloudProjectNumber), REPORT_TIMEOUT_MS)) ?? false;
98
+ } catch (err) {
99
+ log.warn('[Integrity] could not report the attestation', err);
100
+ return false;
101
+ }
102
+ }
@@ -0,0 +1,52 @@
1
+ /**
2
+ * @fileoverview The hardware key that signs liveness frames (ADR-061), and the
3
+ * device's risk signals. The native side is optional: a host without a rebuilt
4
+ * binary, or a device without the hardware, simply goes on without a key.
5
+ */
6
+
7
+ import { requireOptionalNativeModule } from 'expo';
8
+ import { log } from './log';
9
+
10
+ interface DeviceKeyModule {
11
+ generateKeyAsync(): Promise<string>;
12
+ signAsync(message: string): Promise<string>;
13
+ destroyKey(): void;
14
+ getRiskSignals(): string[];
15
+ }
16
+
17
+ const native = requireOptionalNativeModule<DeviceKeyModule>('VelionDeviceKey');
18
+
19
+ /** Creates the key of this attempt; `null` when the device cannot. Returns its SPKI in base64. */
20
+ export async function createDeviceKey(): Promise<string | null> {
21
+ if (!native) return null;
22
+ try {
23
+ return await native.generateKeyAsync();
24
+ } catch (err) {
25
+ log.warn('[DeviceKey] no hardware key available', err);
26
+ return null;
27
+ }
28
+ }
29
+
30
+ /** Signs with ECDSA P-256 over SHA-256. Returns the DER signature in base64. */
31
+ export function signWithDeviceKey(message: string): Promise<string> {
32
+ if (!native) return Promise.reject(new Error('Device key module unavailable'));
33
+ return native.signAsync(message);
34
+ }
35
+
36
+ export function destroyDeviceKey(): void {
37
+ try {
38
+ native?.destroyKey();
39
+ } catch (err) {
40
+ log.warn('[DeviceKey] could not destroy the key', err);
41
+ }
42
+ }
43
+
44
+ /** Hints a capable attacker can hide: they are reported, and never stop the flow. */
45
+ export function getDeviceRiskSignals(): string[] {
46
+ try {
47
+ return native?.getRiskSignals() ?? [];
48
+ } catch (err) {
49
+ log.warn('[DeviceKey] could not read the risk signals', err);
50
+ return [];
51
+ }
52
+ }