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

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 (124) hide show
  1. package/CHANGELOG.md +23 -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/i18n/strings/en.js +2 -0
  12. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  13. package/lib/commonjs/i18n/strings/es.js +2 -0
  14. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  15. package/lib/commonjs/steps/FingerprintStep.js +1 -0
  16. package/lib/commonjs/steps/FingerprintStep.js.map +1 -1
  17. package/lib/commonjs/steps/LivenessMatchStep.js +107 -12
  18. package/lib/commonjs/steps/LivenessMatchStep.js.map +1 -1
  19. package/lib/commonjs/steps/livenessGuidance.js +88 -0
  20. package/lib/commonjs/steps/livenessGuidance.js.map +1 -0
  21. package/lib/commonjs/steps/livenessRestart.js +32 -0
  22. package/lib/commonjs/steps/livenessRestart.js.map +1 -0
  23. package/lib/commonjs/transport/api.js +17 -1
  24. package/lib/commonjs/transport/api.js.map +1 -1
  25. package/lib/commonjs/transport/irisWebSocket.js +3 -0
  26. package/lib/commonjs/transport/irisWebSocket.js.map +1 -1
  27. package/lib/commonjs/types/index.js +12 -0
  28. package/lib/commonjs/types/index.js.map +1 -1
  29. package/lib/commonjs/utils/appId.js +22 -0
  30. package/lib/commonjs/utils/appId.js.map +1 -0
  31. package/lib/commonjs/utils/deviceFingerprint.js +1 -1
  32. package/lib/commonjs/utils/deviceFingerprint.js.map +1 -1
  33. package/lib/commonjs/utils/deviceIntegrity.js +103 -0
  34. package/lib/commonjs/utils/deviceIntegrity.js.map +1 -0
  35. package/lib/commonjs/utils/deviceKey.js +53 -0
  36. package/lib/commonjs/utils/deviceKey.js.map +1 -0
  37. package/lib/commonjs/utils/frameChain.js +55 -0
  38. package/lib/commonjs/utils/frameChain.js.map +1 -0
  39. package/lib/commonjs/utils/hmac.js +6 -4
  40. package/lib/commonjs/utils/hmac.js.map +1 -1
  41. package/lib/commonjs/utils/jpegFromUri.js.map +1 -1
  42. package/lib/module/core/VelionOnboarding.js +4 -1
  43. package/lib/module/core/VelionOnboarding.js.map +1 -1
  44. package/lib/module/i18n/strings/en.js +2 -0
  45. package/lib/module/i18n/strings/en.js.map +1 -1
  46. package/lib/module/i18n/strings/es.js +2 -0
  47. package/lib/module/i18n/strings/es.js.map +1 -1
  48. package/lib/module/steps/FingerprintStep.js +1 -0
  49. package/lib/module/steps/FingerprintStep.js.map +1 -1
  50. package/lib/module/steps/LivenessMatchStep.js +107 -12
  51. package/lib/module/steps/LivenessMatchStep.js.map +1 -1
  52. package/lib/module/steps/livenessGuidance.js +80 -0
  53. package/lib/module/steps/livenessGuidance.js.map +1 -0
  54. package/lib/module/steps/livenessRestart.js +28 -0
  55. package/lib/module/steps/livenessRestart.js.map +1 -0
  56. package/lib/module/transport/api.js +17 -1
  57. package/lib/module/transport/api.js.map +1 -1
  58. package/lib/module/transport/irisWebSocket.js +3 -0
  59. package/lib/module/transport/irisWebSocket.js.map +1 -1
  60. package/lib/module/types/index.js +13 -0
  61. package/lib/module/types/index.js.map +1 -1
  62. package/lib/module/utils/appId.js +18 -0
  63. package/lib/module/utils/appId.js.map +1 -0
  64. package/lib/module/utils/deviceFingerprint.js +1 -1
  65. package/lib/module/utils/deviceFingerprint.js.map +1 -1
  66. package/lib/module/utils/deviceIntegrity.js +99 -0
  67. package/lib/module/utils/deviceIntegrity.js.map +1 -0
  68. package/lib/module/utils/deviceKey.js +46 -0
  69. package/lib/module/utils/deviceKey.js.map +1 -0
  70. package/lib/module/utils/frameChain.js +52 -0
  71. package/lib/module/utils/frameChain.js.map +1 -0
  72. package/lib/module/utils/hmac.js +6 -4
  73. package/lib/module/utils/hmac.js.map +1 -1
  74. package/lib/module/utils/jpegFromUri.js.map +1 -1
  75. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  76. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  77. package/lib/typescript/i18n/strings/es.d.ts +2 -0
  78. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  79. package/lib/typescript/steps/FingerprintStep.d.ts.map +1 -1
  80. package/lib/typescript/steps/LivenessMatchStep.d.ts.map +1 -1
  81. package/lib/typescript/steps/livenessGuidance.d.ts +58 -0
  82. package/lib/typescript/steps/livenessGuidance.d.ts.map +1 -0
  83. package/lib/typescript/steps/livenessRestart.d.ts +25 -0
  84. package/lib/typescript/steps/livenessRestart.d.ts.map +1 -0
  85. package/lib/typescript/steps/types.d.ts +2 -0
  86. package/lib/typescript/steps/types.d.ts.map +1 -1
  87. package/lib/typescript/transport/api.d.ts.map +1 -1
  88. package/lib/typescript/transport/irisWebSocket.d.ts +8 -0
  89. package/lib/typescript/transport/irisWebSocket.d.ts.map +1 -1
  90. package/lib/typescript/types/index.d.ts +34 -0
  91. package/lib/typescript/types/index.d.ts.map +1 -1
  92. package/lib/typescript/utils/appId.d.ts +8 -0
  93. package/lib/typescript/utils/appId.d.ts.map +1 -0
  94. package/lib/typescript/utils/deviceFingerprint.d.ts +2 -0
  95. package/lib/typescript/utils/deviceFingerprint.d.ts.map +1 -1
  96. package/lib/typescript/utils/deviceIntegrity.d.ts +20 -0
  97. package/lib/typescript/utils/deviceIntegrity.d.ts.map +1 -0
  98. package/lib/typescript/utils/deviceKey.d.ts +13 -0
  99. package/lib/typescript/utils/deviceKey.d.ts.map +1 -0
  100. package/lib/typescript/utils/frameChain.d.ts +15 -0
  101. package/lib/typescript/utils/frameChain.d.ts.map +1 -0
  102. package/lib/typescript/utils/hmac.d.ts +3 -1
  103. package/lib/typescript/utils/hmac.d.ts.map +1 -1
  104. package/lib/typescript/utils/jpegFromUri.d.ts +1 -1
  105. package/lib/typescript/utils/jpegFromUri.d.ts.map +1 -1
  106. package/package.json +14 -9
  107. package/src/core/VelionOnboarding.ts +4 -1
  108. package/src/i18n/strings/en.ts +4 -0
  109. package/src/i18n/strings/es.ts +4 -0
  110. package/src/steps/FingerprintStep.tsx +1 -0
  111. package/src/steps/LivenessMatchStep.tsx +119 -13
  112. package/src/steps/livenessGuidance.ts +103 -0
  113. package/src/steps/livenessRestart.ts +32 -0
  114. package/src/steps/types.ts +2 -0
  115. package/src/transport/api.ts +17 -0
  116. package/src/transport/irisWebSocket.ts +9 -0
  117. package/src/types/index.ts +37 -0
  118. package/src/utils/appId.ts +15 -0
  119. package/src/utils/deviceFingerprint.ts +3 -1
  120. package/src/utils/deviceIntegrity.ts +102 -0
  121. package/src/utils/deviceKey.ts +52 -0
  122. package/src/utils/frameChain.ts +56 -0
  123. package/src/utils/hmac.ts +8 -5
  124. package/src/utils/jpegFromUri.ts +1 -1
@@ -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
+ }
@@ -0,0 +1,56 @@
1
+ /**
2
+ * @fileoverview Hash chain of the frames sent to Iris, signed by batches with
3
+ * the hardware key (ADR-061): a frame added, dropped or reordered breaks it, and
4
+ * capture never waits for the hardware. Must match `DeviceSignatures` in Iris:
5
+ *
6
+ * link(0) = sha256_hex("iris-frame-chain-v1\n" + sessionId)
7
+ * link(n) = sha256_hex(link(n-1) + "\n" + canonical frame line)
8
+ * signed = "iris-frame-batch-v1\n" + sessionId + "\n" + frameId + "\n" + link(frameId)
9
+ */
10
+
11
+ import { sha256 } from '@noble/hashes/sha256';
12
+ import { bytesToHexLower } from './base64';
13
+ import { log } from './log';
14
+
15
+ /** A placeholder until signing is measured on real devices, as ADR-061 asks. */
16
+ const BATCH_INTERVAL_MS = 1_000;
17
+
18
+ function sha256Hex(text: string): string {
19
+ return bytesToHexLower(sha256(new TextEncoder().encode(text)));
20
+ }
21
+
22
+ export function createFrameChain(
23
+ sessionId: string,
24
+ sign: (message: string) => Promise<string>,
25
+ send: (json: string) => void,
26
+ now: () => number = Date.now,
27
+ ) {
28
+ let link = sha256Hex(`iris-frame-chain-v1\n${sessionId}`);
29
+ let lastBatchAt = Number.NEGATIVE_INFINITY;
30
+ let signing = false;
31
+
32
+ async function signBatch(frameId: number, frameLink: string): Promise<void> {
33
+ signing = true;
34
+ lastBatchAt = now();
35
+ try {
36
+ const signature = await sign(`iris-frame-batch-v1\n${sessionId}\n${frameId}\n${frameLink}`);
37
+ send(JSON.stringify({ type: 'FRAME_BATCH', lastFrameId: frameId, signature }));
38
+ } catch (err) {
39
+ log.warn('[FrameChain] could not sign the batch', err);
40
+ } finally {
41
+ signing = false;
42
+ }
43
+ }
44
+
45
+ return {
46
+ /** Links a frame just sent. Signing runs on its own, so capture never waits for it. */
47
+ addFrame(frameId: number, canonicalLine: string): void {
48
+ link = sha256Hex(`${link}\n${canonicalLine}`);
49
+ if (!signing && now() - lastBatchAt >= BATCH_INTERVAL_MS) {
50
+ void signBatch(frameId, link);
51
+ }
52
+ },
53
+ };
54
+ }
55
+
56
+ export type FrameChain = ReturnType<typeof createFrameChain>;
package/src/utils/hmac.ts CHANGED
@@ -34,28 +34,31 @@ export function importHmacKey(base64: string): HmacKey {
34
34
  * Returns the JSON string ready to `ws.send`.
35
35
  */
36
36
  export function buildSignedFrameEnvelope(args: {
37
- key: HmacKey;
37
+ /** `null` builds the same envelope without `mac`, for a session Iris gave no key. */
38
+ key: HmacKey | null;
38
39
  sessionId: string;
39
40
  frameId: number;
40
41
  jpegBytes: Uint8Array;
41
42
  jpegBase64: string;
42
43
  /** Defaults to `Date.now()`. */
43
44
  timestamp?: number;
44
- }): { json: string; timestamp: number } {
45
+ }): { json: string; timestamp: number; canonical: string } {
45
46
  const ts = args.timestamp ?? Date.now();
46
47
  const digest = sha256(args.jpegBytes);
47
48
  const digestHex = bytesToHexLower(digest);
48
49
  const canonical = `${args.sessionId}\n${args.frameId}\n${ts}\n${digestHex}`;
49
- const mac = hmac(sha256, args.key.raw, new TextEncoder().encode(canonical));
50
- const macHex = bytesToHexLower(mac);
50
+ const macHex = args.key
51
+ ? bytesToHexLower(hmac(sha256, args.key.raw, new TextEncoder().encode(canonical)))
52
+ : undefined;
51
53
  return {
52
54
  json: JSON.stringify({
53
55
  type: 'FRAME',
54
56
  frameId: args.frameId,
55
57
  timestamp: ts,
56
58
  image: args.jpegBase64,
57
- mac: macHex,
59
+ ...(macHex !== undefined && { mac: macHex }),
58
60
  }),
59
61
  timestamp: ts,
62
+ canonical,
60
63
  };
61
64
  }
@@ -50,7 +50,7 @@ function normalise(uri: string): string {
50
50
  * uploads, for instance. It skips the base64 encoding, which is pure waste for
51
51
  * a multi-megabyte video.
52
52
  */
53
- export async function readBytesFromUri(uri: string): Promise<Uint8Array> {
53
+ export async function readBytesFromUri(uri: string): Promise<Uint8Array<ArrayBuffer>> {
54
54
  const buf = await new File(normalise(uri)).arrayBuffer();
55
55
  return new Uint8Array(buf);
56
56
  }