@fingerly/lynx 0.2.0 → 0.4.0

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.
package/README.md CHANGED
@@ -1,97 +1,153 @@
1
- # @fingerly/lynx
1
+ <p align="center">
2
+ <a href="https://fingerly.io">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/logo-dark.svg">
5
+ <img src="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/logo-light.svg" alt="Fingerly" height="44">
6
+ </picture>
7
+ </a>
8
+ </p>
2
9
 
3
- The Fingerly SDK for Lynx. It is a thin Native Module over the Fingerly iOS and
4
- Android SDKs; all collection, transport and scoring stays native.
10
+ <p align="center"><b>Fingerly for Lynx</b><br>Device intelligence and fraud signals in your Lynx app, through a thin Native Module over the Fingerly iOS and Android SDKs.</p>
5
11
 
6
- Lynx 4.1 and iOS/Android are supported in this first release. HarmonyOS, Web,
7
- Lynxtron and per-`LynxView` registration are not supported.
12
+ <p align="center">
13
+ <a href="https://www.npmjs.com/package/@fingerly/lynx"><img src="https://img.shields.io/npm/v/@fingerly/lynx?style=flat-square" alt="npm version"></a>
14
+ <a href="https://github.com/fingerly-io/sdk-lynx/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/fingerly-io/sdk-lynx/ci.yml?style=flat-square" alt="CI status"></a>
15
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="Licence: Apache-2.0"></a>
16
+ <img src="https://img.shields.io/badge/lynx-4.1-blue?style=flat-square" alt="Lynx 4.1">
17
+ <a href="https://docs.fingerly.io/docs/sdks/lynx"><img src="https://img.shields.io/badge/docs-docs.fingerly.io-informational?style=flat-square" alt="Documentation"></a>
18
+ </p>
8
19
 
9
- ## Install
20
+ <p align="center"><img src="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/banner.webp" alt="Fingerly" width="100%"></p>
10
21
 
11
- ```sh
12
- pnpm add @fingerly/lynx
13
- ```
22
+ ## What is this
23
+
24
+ `@fingerly/lynx` (`0.4.0`, `v: 3`) is the Fingerly SDK for Lynx. It is a thin Native Module over the Fingerly iOS and Android SDKs; all collection, transport and attestation stay native. You call `identify()` from Lynx background-thread scripting and get back a request ID and a visitor ID to send to your own backend, which decides what to do. [Fingerly](https://fingerly.io) is a device intelligence API that helps you protect signups, logins and payments from fraud and abuse.
25
+
26
+ Supported: Lynx 4.1 on iOS and Android. Not supported: HarmonyOS, Web, Lynxtron and per-`LynxView` registration.
27
+
28
+ ## Getting started
29
+
30
+ 1. **Get a key.** In the [Fingerly dashboard](https://dashboard.fingerly.io), open **Integration > SDK keys** and create a public key for your app. [How keys work](https://docs.fingerly.io/docs/api-keys).
31
+ 2. **Install the package.**
32
+
33
+ ```sh
34
+ pnpm add @fingerly/lynx@^0.4.0
35
+ ```
36
+
37
+ The host app must enable [Lynx Native Library Autolink](https://lynxjs.org/guide/autolink). See [Platform setup](#platform-setup) for the Android and iOS steps.
14
38
 
15
- The host app must enable [Lynx Native Library Autolink](https://lynxjs.org/guide/autolink):
39
+ 3. **Identify.** Native Modules are available from Lynx background-thread scripting, so call the SDK from an event handler, effect, or other background function.
16
40
 
17
- - Android: apply `org.lynxsdk.library-settings` in `settings.gradle` and
18
- `org.lynxsdk.library-build` in the app module, then sync and rebuild.
19
- - iOS: install `cocoapods-lynx-library`, add
20
- `plugin 'cocoapods-lynx-library'` and `use_lynx_library!` to the Podfile, run
21
- `pod install`, then rebuild.
41
+ ```ts
42
+ import { ConsentState, load } from '@fingerly/lynx'
22
43
 
23
- The Android module depends on `io.fingerly:fingerly:0.2.0` from Fingerly's Maven
24
- repository and declares no repositories of its own, so Android hosts add it to
25
- the repositories in `settings.gradle`:
44
+ // consent: only once you have consent (or another lawful basis)
45
+ const fingerly = await load({ apiKey: 'fly_pk_production_…', consent: ConsentState.Granted })
46
+ const result = await fingerly.identify({ tag: 'checkout' })
47
+
48
+ // Send result.requestId to your backend and make the decision there.
49
+ ```
50
+
51
+ ## Contents
52
+
53
+ - [Platform setup](#platform-setup)
54
+ - [Identify](#identify)
55
+ - [Named values](#named-values)
56
+ - [Consent](#consent)
57
+ - [Erasure](#erasure)
58
+ - [Why there is no JavaScript fallback](#why-there-is-no-javascript-fallback)
59
+ - [Native SDK dependencies](#native-sdk-dependencies)
60
+ - [Requirements](#requirements)
61
+ - [Documentation](#documentation)
62
+ - [Development](#development)
63
+ - [Help](#help)
64
+ - [Licence](#licence)
65
+
66
+ ## Platform setup
67
+
68
+ The package's `lynx.lib.json` registers the `Fingerly` Native Module. The host app must enable Lynx Native Library Autolink:
69
+
70
+ | Android | iOS |
71
+ | --- | --- |
72
+ | Apply `org.lynxsdk.library-settings` in `settings.gradle` and `org.lynxsdk.library-build` in the app module, then sync and rebuild. | Install `cocoapods-lynx-library`, add `plugin 'cocoapods-lynx-library'` and `use_lynx_library!` to the Podfile, run `pod install`, then rebuild. |
73
+
74
+ The Android module depends on `io.fingerly:fingerly:0.4.0` from Fingerly's Maven repository (`mavenLocal()` is also configured, for local artifact staging). Android hosts add Fingerly's repository to the repositories in `settings.gradle`:
26
75
 
27
76
  ```groovy
28
77
  maven { url 'https://maven.fingerly.io' }
29
78
  ```
30
79
 
31
- This bridge is licensed under Apache-2.0. The native SDK it depends on is a
32
- closed binary under the Fingerly SDK License.
33
-
34
- The package's `lynx.lib.json` registers the `Fingerly` Native Module. Native
35
- Modules are available from Lynx background-thread scripting, so call the SDK
36
- from an event handler, effect, or other background function.
37
-
38
80
  ## Identify
39
81
 
40
- ```ts
41
- import { load } from '@fingerly/lynx'
82
+ `load` reports `lynx-ios` or `lynx-android` (`SdkPlatform.LynxIos`, `SdkPlatform.LynxAndroid`), so the server selects the correct native risk profile and applies the right mobile checks. On any other platform it throws a `FingerlyError`. For production Android keys, configure `AllowedAndroidSigners` (64-hex SHA-256 signing certificate digests) alongside `AllowedAndroidPackages` in the dashboard.
42
83
 
43
- // consent: only once you have consent (or another lawful basis)
44
- const fingerly = await load({ apiKey: 'fly_pk_production_…', consent: 'granted' })
45
- const result = await fingerly.identify({ tag: 'checkout' })
84
+ `identify()` submits a single-pass `v: 3` identification (`1-RTT` steady state through cached `next_attestation` challenge offers) and resolves with what the server said: `requestId`, `visitorId` and, by default, `suspectScore` and `suspectLevel`.
46
85
 
47
- // Send result.requestId to your backend and make the decision there.
48
- ```
86
+ - When `identifiable` is `false` (`v: 3` Option B), `visitorId` is `""` and `visitorIsNew` is `false`.
87
+ - The score is a convenience for showing a result straight away. Each SDK key has a setting that hides it from apps, and then both fields are `null`, exactly as on a check nobody scored. An app cannot tell which it was, so read `null` as "no answer here", never as clean.
88
+ - The signals behind a score never reach the device. Read them on your backend, through the server-side event read by `requestId` or webhooks, or in the dashboard.
89
+ - `visitorConfidence`, `visitorIsNew`, `identifiable` and `duplicate` can be `null` when the server did not say, which is not the same as `0` or `false`.
90
+
91
+ | Option | What it does |
92
+ | --- | --- |
93
+ | `tag` | A string echoed back on the finished event, for your own correlation. |
94
+ | `submit: false` | Collect without sending. It resolves with `{ report }`, the raw report and nothing else. |
95
+ | `automatic: true` | For a call your app makes on its own (on start, on a timer, on returning to the foreground): it joins an identification already in flight instead of starting another, and waits out a transient failure instead of repeating it. |
49
96
 
50
- `load` reports `lynx-ios` or `lynx-android`, allowing the server to select the
51
- correct native risk profile. `identify()` defaults to submission and resolves
52
- with what the server said: `requestId`, `visitorId` and, by default,
53
- `suspectScore` and `suspectLevel`. The score is a convenience for showing a
54
- result straight away. Each SDK key has a setting that hides it from apps, and
55
- then both fields are `null`, exactly as on a check nobody scored: an app cannot
56
- tell which it was, so read `null` as "no answer here", never as clean. The
57
- signals behind a score never reach the device; read them on your backend,
58
- through the server-side event read by `requestId` or webhooks, or in the
59
- dashboard. `visitorConfidence`, `visitorIsNew`,
60
- `identifiable` and `duplicate` can be `null` when the server did not say, which
61
- is not the same as `0` or `false`. Pass `{ submit: false }` to collect without
62
- sending; it resolves with `{ report }`, the raw report and nothing else. Pass `{ automatic: true }` for
63
- a call your app makes on its own (on start, on a timer, on returning to the
64
- foreground): it joins an identification already in flight instead of starting
65
- another, and waits out a transient failure instead of repeating it. On Android
66
- it has no effect until the native Android SDK supports it. `collect()` returns
67
- the native signal report without submitting it.
97
+ `collect()` returns the native `SignalReport` without submitting it.
68
98
 
69
99
  ```ts
100
+ import { nativeVersion } from '@fingerly/lynx'
101
+
70
102
  const report = await fingerly.collect()
71
103
  const version = nativeVersion()
72
104
  ```
73
105
 
74
- Failures are surfaced as `FingerlyError`. `status` is populated only for a
75
- positive HTTP status returned by the native transport. When the server asked
76
- for a pause with `Retry-After`, `retryAfterMs` carries it: wait at least that
77
- long before identifying again. It is undefined when no wait was named, and on
78
- Android until the native Android bridge passes the header on.
106
+ `nativeVersion()` returns the version of the native SDK that did the collecting.
107
+
108
+ Failures are surfaced as `FingerlyError`. `status` is populated only for a positive HTTP status returned by the native transport. When the server asked for a pause with `Retry-After`, `retryAfterMs` carries it: wait at least that long before identifying again. It is undefined when no wait was named.
109
+
110
+ ## Named values
111
+
112
+ The fixed strings the API returns and the module accepts have names, the same objects `@fingerly/web-js` exports. Each is an `as const` object with a same-named type, and a member is its value in PascalCase, word by word (`SuspectLevel.High` is `'high'`, `Signal.FingerprintSuppressed` is `'fingerprint_suppressed'`):
113
+
114
+ ```ts
115
+ import { EventState, SuspectLevel } from '@fingerly/lynx'
116
+
117
+ const result = await fingerly.identify({ tag: 'checkout' })
118
+
119
+ if (result.state === EventState.Unavailable) {
120
+ // The network lookup could not run, so the check was not scored.
121
+ }
122
+ if (result.suspectLevel === SuspectLevel.High) {
123
+ // Show a step-up screen while your backend makes the decision.
124
+ }
125
+ ```
126
+
127
+ | Constant | Members | Where it appears |
128
+ | --- | --- | --- |
129
+ | `SuspectLevel` | `Low`, `Medium`, `High` | `suspectLevel` on the `identify()` answer. |
130
+ | `EventState` | `Enriched`, `Unavailable`, `Pending` | `state` on the `identify()` answer. An answer is never `Pending`, which only a server-side event read reports. |
131
+ | `ConsentState` | `Granted`, `Pending`, `Denied` | The `consent` option on `load`, `setConsent`, `consent` and `ConsentError.state`. |
132
+ | `SdkPlatform` | `LynxIos`, `LynxAndroid`, and the other SDKs' platforms | What the module reports itself as, and the SDK named on the event your backend reads. |
133
+ | `Signal` | Every signal group and detector the server reports, such as `Signal.Jailbreak` and `Signal.VpnPublic` | Triggers on the event your backend reads and in webhooks. The signals never reach the device. |
134
+ | `Confidence` | `Low`, `Medium`, `High` | A trigger's `confidence` on the event your backend reads. |
135
+
136
+ Comparing with the plain string compiles as well. The module hands on the server's values as they came, so a value a newer server adds reaches the app unchanged rather than being dropped.
79
137
 
80
138
  ## Consent
81
139
 
82
- The SDK identifies nobody until it is told consent is `'granted'`. The usual
83
- pattern is to load it at launch with the default `'pending'` and pass on the
84
- answer from your consent tool when it arrives:
140
+ The SDK identifies nobody until it is told consent is `'granted'`. The usual pattern is to load it at launch with the default `'pending'` and pass on the answer from your consent tool when it arrives:
85
141
 
86
142
  ```ts
87
- import { ConsentError, load } from '@fingerly/lynx'
143
+ import { ConsentError, ConsentState, load } from '@fingerly/lynx'
88
144
 
89
145
  const fingerly = await load({ apiKey: 'fly_pk_production_…' }) // consent is 'pending'
90
146
 
91
147
  // From your consent tool's callback:
92
- fingerly.setConsent(accepted ? 'granted' : 'denied')
148
+ fingerly.setConsent(accepted ? ConsentState.Granted : ConsentState.Denied)
93
149
 
94
- fingerly.consent // 'granted', 'pending' or 'denied'
150
+ fingerly.consent // ConsentState.Granted, ConsentState.Pending or ConsentState.Denied
95
151
  ```
96
152
 
97
153
  | Option / method | What it does |
@@ -100,36 +156,23 @@ fingerly.consent // 'granted', 'pending' or 'denied'
100
156
  | `setConsent(state)` | Records the decision. Synchronous and safe to call repeatedly. |
101
157
  | `consent` | The state last given to the native SDK, read-only. |
102
158
 
103
- The default is `'pending'`, so an integration that never mentions consent
104
- identifies nobody. Pass `consent: 'granted'` to `load` only when you already
105
- have consent, or another lawful basis. Anything other than the three states
106
- throws a `TypeError`.
159
+ The default is `'pending'`, so an integration that never mentions consent identifies nobody. Pass `consent: ConsentState.Granted` to `load` only when you already have consent, or another lawful basis. Anything other than the three states throws a `TypeError`.
107
160
 
108
- Until consent is `'granted'`, the native SDK runs no source, touches no storage
109
- for fingerprinting and sends nothing. `identify()` and `collect()` reject with
110
- `ConsentError`, a subclass of `FingerlyError` with `code: 'consent_required'`
111
- and the refusing `state`:
161
+ Until consent is `'granted'`, the native SDK runs no source, touches no container storage or attestation key state, and sends nothing. `identify()` and `collect()` reject with `ConsentError`, a subclass of `FingerlyError` with `code: 'consent_required'` and the refusing `state`:
112
162
 
113
163
  ```ts
114
164
  try {
115
165
  await fingerly.identify()
116
166
  } catch (error) {
117
167
  if (error instanceof ConsentError) {
118
- // error.state is 'pending' or 'denied'; nothing was collected or sent
168
+ // error.state is ConsentState.Pending or ConsentState.Denied; nothing was collected or sent
119
169
  }
120
170
  }
121
171
  ```
122
172
 
123
- Withdrawing consent also stops a call already in flight before its next source
124
- starts and before it submits, and that call rejects with `ConsentError`.
125
- Loading collects and sends nothing, whatever the state. The native SDK holds one
126
- state for the whole app, and each `load` sets it to the `consent` passed (or
127
- `'pending'`), so pass `consent` on every `load`.
173
+ Withdrawing consent also stops a call already in flight before its next source starts and before it submits, and that call rejects with `ConsentError`. Loading collects and sends nothing, whatever the state. The native SDK holds one state for the whole app, and each `load` sets it to the `consent` passed (or `'pending'`), so pass `consent` on every `load`.
128
174
 
129
- Every submission the native SDK sends carries the state it was collected under,
130
- `"consent": "granted"`, and the server refuses any other value with
131
- `422 consent_required`. The native SDK only sends while consent is granted, so
132
- that refusal should never be seen.
175
+ Every submission the native SDK sends carries `"consent": "granted"`, and the server refuses any other value with `422 consent_required`. The native SDK only sends while consent is granted, so that refusal should never be seen.
133
176
 
134
177
  ## Erasure
135
178
 
@@ -139,78 +182,84 @@ import { deleteStoredIdentity } from '@fingerly/lynx'
139
182
  await deleteStoredIdentity()
140
183
  ```
141
184
 
142
- Deletes the install record the native SDK keeps on the device, including the
143
- install ID the server recognises it by. Call it when a user asks for their data
144
- to be erased or deletes their account. It needs no `load` and no consent,
145
- sends nothing, and resolves once no record remains, including when there was
146
- none. It rejects with a `FingerlyError` when the delete fails. The next
147
- identification made with consent starts a new record; to stop identifying as
148
- well, set consent to `'denied'` first.
185
+ This call is **strictly for user-initiated GDPR or privacy right-to-erasure requests, or account deletion**. Never call it on routine logout, session expiry or user switching: repeated `install_id` resets on the same device trigger single-key churn telemetry (`>= 3` distinct IDs in 24 hours).
186
+
187
+ It deletes the local install record (`install_id`) and the local hardware attestation key state kept on the device:
188
+
189
+ - On iOS, the `Application Support/io.fingerly.sdk/` container files, kept with `isExcludedFromBackup = true`, and the App Attest key state.
190
+ - On Android, atomically, the install record and the persistent `AndroidKeyStore` v3 signing key `io.fingerly.sdk.attest.v3`.
191
+
192
+ It needs no `load` and no consent, sends nothing, and resolves once no local record or key state remains, including when there was none. It rejects with a `FingerlyError` when the delete fails. A later re-consented identification generates a fresh `install_id` and attests a fresh key, so the server mints an unlinked `visitorId`; to stop identifying altogether, set consent to `'denied'` first.
149
193
 
150
194
  ## Why there is no JavaScript fallback
151
195
 
152
- JavaScript cannot inspect the filesystem, loaded images, debugger flags,
153
- DeviceCheck, Android packages, or the native TLS connection. Falling back to a
154
- partial report could mark a compromised device as clean, so a missing Native
155
- Module is an actionable integration error.
196
+ JavaScript cannot inspect the filesystem, loaded Mach-O or ELF images, debugger flags, App Attest or Keystore hardware attestation, Android packages, or the native TLS connection. Falling back to a partial report could mark a compromised device as clean, so a missing Native Module is an actionable integration error.
156
197
 
157
198
  ## Native SDK dependencies
158
199
 
159
- On iOS, `pod install` downloads the matching `Fingerly.xcframework` from
160
- `https://maven.fingerly.io/ios/` and verifies its checksum, so the Podfile needs
161
- no entry for the native SDK. The same binary is published as a Swift package at
162
- [sdk-ios](https://github.com/fingerly-io/sdk-ios).
200
+ Both native dependencies are at `0.4.0`.
201
+
202
+ <details>
203
+ <summary><b>iOS</b></summary>
204
+
205
+ `pod install` downloads the matching `Fingerly.xcframework` (`0.4.0`) from `https://maven.fingerly.io/ios/` and verifies its SHA-256 checksum, so the Podfile needs no separate entry for the native SDK. The same binary is published as a Swift package at [sdk-ios](https://github.com/fingerly-io/sdk-ios).
206
+
207
+ The Play Integrity project number passed to `load` is ignored on iOS.
208
+
209
+ </details>
163
210
 
164
- On Android, the module resolves `io.fingerly:fingerly` from
165
- `https://maven.fingerly.io`, added to the host's repositories as shown above.
211
+ <details>
212
+ <summary><b>Android</b></summary>
166
213
 
167
- **Installed-app checks are opt-in on Android.** From the Android SDK release
168
- after 0.1.0, the checks for root managers, hooking frameworks and app cloners by
169
- package name ship in a separate artifact, `io.fingerly:fingerly-app-checks`,
170
- because Google Play treats the list of installed apps as personal and sensitive
171
- data. This bridge depends on `io.fingerly:fingerly` only. If your app can
172
- justify the package visibility in its Play review and wants these checks, add
173
- the artifact to your app's Android module, at the same version as
174
- `io.fingerly:fingerly`, and declare "App activity: Installed apps" in the Data
175
- safety form:
214
+ The module resolves `io.fingerly:fingerly:0.4.0` from `https://maven.fingerly.io`, added to the host's repositories as shown in [Platform setup](#platform-setup).
215
+
216
+ **Installed-app checks are opt-in (`io.fingerly:fingerly-app-checks:0.4.0`).** Core `io.fingerly:fingerly:0.4.0` declares zero `<queries>` entries in its manifest, because Google Play treats installed-app visibility as personal and sensitive data. If your app can justify package visibility for the 17 root managers, hooking frameworks and dual-space cloners in its Play review, add `io.fingerly:fingerly-app-checks:0.4.0` to your app's Android module and declare "App activity: Installed apps" in the Data safety form. The module finds the artifact and registers its provider on every `load`, so there is no native code to write:
176
217
 
177
218
  ```kotlin
219
+ // the app module's build.gradle.kts
178
220
  dependencies {
179
- implementation("io.fingerly:fingerly-app-checks:<same version as io.fingerly:fingerly>")
221
+ implementation("io.fingerly:fingerly-app-checks:0.4.0")
180
222
  }
181
223
  ```
182
224
 
183
- Without it, the report carries no installed-app fields and nothing about other
184
- apps leaves the device; whether the app itself runs inside a cloner is still
185
- reported.
225
+ Without it, the report carries no installed-app fields and nothing about other apps leaves the device; whether the app itself runs inside a cloner is still reported.
186
226
 
187
- **Play Integrity (Android, optional).** The Android SDK has an optional
188
- artifact, `io.fingerly:fingerly-play-integrity` (server ADR 0026), that adds
189
- Google Play Integrity verdicts to events. To use it, add the artifact to the
190
- app and pass your Google Cloud project number, the one linked to the app in
191
- Play Console, to `load`:
227
+ **Play Integrity (optional, `io.fingerly:fingerly-play-integrity:0.4.0`).** To add Google Play Integrity Standard tokens bound to the `v: 3` `statementDigest`, add the artifact to your app's Android module and pass your Google Cloud project number, the one linked to the app in Play Console, to `load`. The module finds the artifact and registers its provider with that project number:
192
228
 
193
229
  ```kotlin
194
230
  // the app module's build.gradle.kts
195
231
  dependencies {
196
- implementation("io.fingerly:fingerly-play-integrity:<same version as io.fingerly:fingerly>")
232
+ implementation("io.fingerly:fingerly-play-integrity:0.4.0")
197
233
  }
198
234
  ```
199
235
 
200
236
  ```ts
201
237
  const fingerly = await load({
202
238
  apiKey: 'fly_pk_production_…',
239
+ consent: ConsentState.Granted,
203
240
  playIntegrityCloudProjectNumber: 123456789012,
204
241
  })
205
242
  ```
206
243
 
207
- The native SDK finds the artifact on its own; this bridge does not depend on
208
- it. Without the artifact the number is ignored and nothing fails, and on iOS it
209
- is ignored. The rest of the setup (the service account uploaded to your
210
- Fingerly project, the daily budget) is in the Android SDK's
211
- `fingerly-play-integrity/README.md`. This needs the Android SDK
212
- release after 0.1.0, the first whose `FingerlyBridge.configure` takes a project
213
- number; Gradle refuses to pair the artifact with a core of another version.
244
+ A provider of your own, registered from native code with `FingerlyBridge.setPlayIntegrity(provider)` before `load`, is used in place of the artifact's.
245
+
246
+ A project number with neither is a configuration error: the module keeps the previous configuration, and every `identify` and `collect` rejects with a `FingerlyError` ("playIntegrityCloudProjectNumber was set but the io.fingerly:fingerly-play-integrity artifact is not on the classpath", native code `play_integrity_unavailable`) until a `load` without that mismatch replaces it. Without a project number, Play Integrity is off and nothing fails.
247
+
248
+ The rest of the setup, the service account uploaded to your Fingerly project and the daily budget, is covered by the Android SDK's [install notes](https://github.com/fingerly-io/sdk-android/blob/main/INSTALL.md#optional-play-integrity).
249
+
250
+ </details>
251
+
252
+ ## Requirements
253
+
254
+ | | Minimum |
255
+ | --- | --- |
256
+ | Lynx | 4.1 |
257
+ | iOS | 13.0 |
258
+ | Android | 6.0 (API 23) |
259
+
260
+ ## Documentation
261
+
262
+ Guides and the API reference: <https://docs.fingerly.io/docs/sdks/lynx>.
214
263
 
215
264
  ## Development
216
265
 
@@ -227,6 +276,12 @@ pnpm example:build
227
276
  ANDROID_HOME=/path/to/android-sdk ./android/gradlew -p android assembleDebug
228
277
  ```
229
278
 
230
- Generated bridge specifications are committed. After changing
231
- `types/platform-native-module.d.ts`, run codegen and commit the generated
232
- TypeScript, Java and Objective-C files together.
279
+ Generated bridge specifications are committed. After changing `types/platform-native-module.d.ts`, run codegen and commit the generated TypeScript, Java and Objective-C files together.
280
+
281
+ ## Help
282
+
283
+ Open an issue on this repository, or write to <support@fingerly.io>. Security issues: <security@fingerly.io>.
284
+
285
+ ## Licence
286
+
287
+ This bridge is licensed under [Apache-2.0](LICENSE). The native SDKs it depends on are closed binaries under the Fingerly SDK License.
@@ -2,6 +2,13 @@ plugins {
2
2
  id("com.android.library")
3
3
  }
4
4
 
5
+ repositories {
6
+ mavenLocal()
7
+ google()
8
+ mavenCentral()
9
+ maven("https://maven.fingerly.io")
10
+ }
11
+
5
12
  android {
6
13
  namespace = "io.fingerly.lynx"
7
14
  compileSdk = 36
@@ -21,5 +28,18 @@ dependencies {
21
28
  implementation("org.lynxsdk.lynx:lynx:4.1.0")
22
29
  implementation("org.lynxsdk.lynx:service-api:4.1.0")
23
30
  annotationProcessor("org.lynxsdk.lynx:lynx-processor:4.1.0")
24
- implementation("io.fingerly:fingerly:0.2.0")
31
+ implementation("io.fingerly:fingerly:0.4.0")
32
+
33
+ // The opt-in artifacts. `compileOnly` so the module can construct their providers when the
34
+ // host app links them, without adding `<queries>` or Play Services to an app that does not.
35
+ compileOnly("io.fingerly:fingerly-app-checks:0.4.0")
36
+ compileOnly("io.fingerly:fingerly-play-integrity:0.4.0")
37
+
38
+ testImplementation("junit:junit:4.13.2")
25
39
  }
40
+
41
+ // The unit tests cover the plain Java helpers only. The Lynx runtime is native code that never
42
+ // loads on the JVM, so the tests run without it.
43
+ configurations
44
+ .matching { it.name.endsWith("UnitTestRuntimeClasspath") }
45
+ .configureEach { exclude(group = "org.lynxsdk.lynx") }
@@ -10,11 +10,12 @@ pluginManagement {
10
10
  }
11
11
 
12
12
  dependencyResolutionManagement {
13
- repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
13
+ repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)
14
14
  repositories {
15
+ mavenLocal()
15
16
  google()
16
17
  mavenCentral()
17
- mavenLocal()
18
+ maven("https://maven.fingerly.io")
18
19
  }
19
20
  }
20
21
 
@@ -7,8 +7,10 @@ import com.lynx.jsbridge.LynxNativeModule;
7
7
  import com.lynx.react.bridge.Callback;
8
8
  import com.lynx.tasm.behavior.LynxContext;
9
9
  import io.fingerly.lynx.generated.FingerlySpec;
10
- import io.fingerly.sdk.bridge.FingerlyBridge;
10
+ import io.fingerly.sdk.AppChecksProvider;
11
+ import io.fingerly.sdk.PlayIntegrityProvider;
11
12
  import io.fingerly.sdk.bridge.BridgeCallback;
13
+ import io.fingerly.sdk.bridge.FingerlyBridge;
12
14
  import org.json.JSONException;
13
15
  import org.json.JSONObject;
14
16
 
@@ -17,6 +19,9 @@ import org.json.JSONObject;
17
19
  public final class Fingerly extends FingerlySpec {
18
20
  private final Context applicationContext;
19
21
 
22
+ /** Why the last `configure` was refused, or null when it was accepted. */
23
+ @Nullable private volatile String configurationError;
24
+
20
25
  public Fingerly(LynxContext context) {
21
26
  super(context);
22
27
  applicationContext = context.getContext().getApplicationContext();
@@ -33,11 +38,50 @@ public final class Fingerly extends FingerlySpec {
33
38
  // `src/index.ts` always sends a consent, `pending` when the app passed none,
34
39
  // so the state is set rather than left as it was.
35
40
  //
36
- // The project number is 0 when the app passed none. The Android SDK builds
37
- // the Play Integrity provider from the optional fingerly-play-integrity
38
- // artifact when the app has it, and ignores the number when it does not.
41
+ // The project number is 0 when the app passed none; `FingerlyBridge.configure`
42
+ // takes a nullable Long (`<= 0` or `null` leaves Play Integrity token requests off).
43
+ Long projectNumber =
44
+ playIntegrityCloudProjectNumber > 0
45
+ ? Long.valueOf((long) playIntegrityCloudProjectNumber)
46
+ : null;
47
+
48
+ // A project number with no provider to use it would leave Play Integrity off without a
49
+ // word. `configure` has no callback, so the configuration is refused, nothing is changed,
50
+ // and every later `identify` and `collect` fails with `play_integrity_unavailable` until a
51
+ // complete configuration replaces it.
52
+ PlayIntegrityProvider playIntegrity = OptionalProviders.playIntegrity();
53
+ String error =
54
+ OptionalProviders.playIntegrityError(
55
+ projectNumber, playIntegrity, FingerlyBridge.hasPlayIntegrityProvider());
56
+ configurationError = error;
57
+ if (error != null) {
58
+ return;
59
+ }
60
+
61
+ // The optional providers are registered whenever the app links their artifacts, as the
62
+ // React Native module does. A Play Integrity provider the app registered by hand is kept.
63
+ AppChecksProvider appChecks = OptionalProviders.appChecks();
64
+ if (appChecks != null) {
65
+ FingerlyBridge.setAppChecks(appChecks);
66
+ }
67
+ if (projectNumber != null
68
+ && playIntegrity != null
69
+ && !FingerlyBridge.hasPlayIntegrityProvider()) {
70
+ FingerlyBridge.setPlayIntegrity(playIntegrity, projectNumber);
71
+ }
72
+
39
73
  FingerlyBridge.configure(
40
- applicationContext, apiKey, endpoint, platform, consent, (long) playIntegrityCloudProjectNumber);
74
+ applicationContext, apiKey, endpoint, platform, consent, projectNumber);
75
+ }
76
+
77
+ /** Fails the call with the stored configuration error, if there is one. */
78
+ private boolean refuseUnconfigured(Object failure) {
79
+ String error = configurationError;
80
+ if (error == null) {
81
+ return false;
82
+ }
83
+ ((Callback) failure).invoke(errorJson(OptionalProviders.PLAY_INTEGRITY_UNAVAILABLE, error));
84
+ return true;
41
85
  }
42
86
 
43
87
  @Override
@@ -50,21 +94,26 @@ public final class Fingerly extends FingerlySpec {
50
94
  @LynxMethod
51
95
  public void identify(
52
96
  @Nullable String tag, boolean submit, boolean automatic, Object success, Object failure) {
53
- // `automatic` is not read: the native Android bridge has no such option
54
- // yet, so every call is identified as a user's call.
55
- FingerlyBridge.identify(tag, submit, settle(success, failure));
97
+ if (refuseUnconfigured(failure)) {
98
+ return;
99
+ }
100
+ FingerlyBridge.identify(tag, submit, automatic, settle(success, failure));
56
101
  }
57
102
 
58
103
  @Override
59
104
  @LynxMethod
60
105
  public void collect(Object success, Object failure) {
106
+ if (refuseUnconfigured(failure)) {
107
+ return;
108
+ }
61
109
  FingerlyBridge.collect(settle(success, failure));
62
110
  }
63
111
 
64
112
  /**
65
- * Deletes the install record, for a user's erasure or account deletion. Needs
66
- * neither `configure` nor consent. A failure is `delete_failed`, the code the
67
- * iOS adapter uses for the same thing.
113
+ * Atomically deletes the local install record and the persistent AndroidKeyStore v3
114
+ * attestation signing key. Strictly for user-initiated GDPR/privacy erasure (such as a
115
+ * right-to-erasure request or account deletion; never routine logout). Needs neither
116
+ * `configure` nor consent. A failure is `delete_failed`, matching the iOS adapter.
68
117
  */
69
118
  @Override
70
119
  @LynxMethod
@@ -0,0 +1,61 @@
1
+ package io.fingerly.lynx;
2
+
3
+ import androidx.annotation.Nullable;
4
+ import io.fingerly.sdk.AppChecksProvider;
5
+ import io.fingerly.sdk.PlayIntegrityProvider;
6
+ import io.fingerly.sdk.appchecks.FingerlyAppChecks;
7
+ import io.fingerly.sdk.playintegrity.FingerlyPlayIntegrity;
8
+
9
+ /**
10
+ * The optional {@code io.fingerly:fingerly-app-checks} and {@code
11
+ * io.fingerly:fingerly-play-integrity} providers, found the same way the React Native module
12
+ * finds them.
13
+ *
14
+ * <p>Both artifacts are {@code compileOnly} here, so the host app decides whether they ship. When
15
+ * the app links one, the constructor runs; when it does not, the class is missing at run time and
16
+ * the constructor throws a {@link LinkageError} ({@code NoClassDefFoundError}), which reads as
17
+ * "not installed".
18
+ */
19
+ final class OptionalProviders {
20
+ static final String PLAY_INTEGRITY_UNAVAILABLE = "play_integrity_unavailable";
21
+
22
+ static final String PLAY_INTEGRITY_UNAVAILABLE_MESSAGE =
23
+ "playIntegrityCloudProjectNumber was set but the io.fingerly:fingerly-play-integrity "
24
+ + "artifact is not on the classpath";
25
+
26
+ private OptionalProviders() {}
27
+
28
+ @Nullable
29
+ static AppChecksProvider appChecks() {
30
+ try {
31
+ return new FingerlyAppChecks();
32
+ } catch (LinkageError absent) {
33
+ return null;
34
+ }
35
+ }
36
+
37
+ @Nullable
38
+ static PlayIntegrityProvider playIntegrity() {
39
+ try {
40
+ return new FingerlyPlayIntegrity();
41
+ } catch (LinkageError absent) {
42
+ return null;
43
+ }
44
+ }
45
+
46
+ /**
47
+ * The configuration error for a project number that no provider can use, or null when the
48
+ * configuration is complete. A project number needs the artifact's {@code provider} or one the
49
+ * app registered by hand ({@code registeredByHand}). No project number is always complete: Play
50
+ * Integrity is simply off.
51
+ */
52
+ @Nullable
53
+ static String playIntegrityError(
54
+ @Nullable Long projectNumber,
55
+ @Nullable PlayIntegrityProvider provider,
56
+ boolean registeredByHand) {
57
+ return projectNumber != null && provider == null && !registeredByHand
58
+ ? PLAY_INTEGRITY_UNAVAILABLE_MESSAGE
59
+ : null;
60
+ }
61
+ }
@@ -0,0 +1,46 @@
1
+ package io.fingerly.lynx;
2
+
3
+ import static org.junit.Assert.assertEquals;
4
+ import static org.junit.Assert.assertNull;
5
+
6
+ import io.fingerly.sdk.PlayIntegrityProvider;
7
+ import java.lang.reflect.Proxy;
8
+ import org.junit.Test;
9
+
10
+ public final class OptionalProvidersTest {
11
+
12
+ /** The unit test classpath has no `compileOnly` artifact, as an app that did not link it. */
13
+ @Test
14
+ public void providersAreAbsentWhenTheArtifactsAreNotLinked() {
15
+ assertNull(OptionalProviders.playIntegrity());
16
+ assertNull(OptionalProviders.appChecks());
17
+ }
18
+
19
+ @Test
20
+ public void projectNumberWithoutProviderIsAConfigurationError() {
21
+ assertEquals(
22
+ OptionalProviders.PLAY_INTEGRITY_UNAVAILABLE_MESSAGE,
23
+ OptionalProviders.playIntegrityError(123456789L, null, false));
24
+ }
25
+
26
+ @Test
27
+ public void projectNumberWithProviderRegisteredByHandIsComplete() {
28
+ assertNull(OptionalProviders.playIntegrityError(123456789L, null, true));
29
+ }
30
+
31
+ @Test
32
+ public void noProjectNumberAndNoProviderIsComplete() {
33
+ assertNull(OptionalProviders.playIntegrityError(null, null, false));
34
+ }
35
+
36
+ @Test
37
+ public void projectNumberWithProviderIsComplete() {
38
+ PlayIntegrityProvider provider =
39
+ (PlayIntegrityProvider)
40
+ Proxy.newProxyInstance(
41
+ PlayIntegrityProvider.class.getClassLoader(),
42
+ new Class<?>[] {PlayIntegrityProvider.class},
43
+ (proxy, method, args) -> null);
44
+ assertNull(OptionalProviders.playIntegrityError(123456789L, provider, false));
45
+ }
46
+ }
@@ -1,43 +1,129 @@
1
1
  #!/bin/bash
2
2
  #
3
- # Puts Fingerly.xcframework in <pod root>/Frameworks. Run by the podspec.
3
+ # Puts Fingerly.xcframework in <pod root>/Frameworks. Run by the podspec or
4
+ # directly when staging local artifacts.
4
5
  #
5
- # fetch-fingerly-xcframework.sh <version> <sha256> <pod root>
6
+ # fetch-fingerly-xcframework.sh [version] [sha256] [pod root] [url] [team id]
7
+ #
8
+ # When FINGERLY_XCFRAMEWORK_PATH is set (pointing either to an unpacked
9
+ # .xcframework directory or a .xcframework.zip archive), copies or extracts it
10
+ # directly into <pod root>/Frameworks without any network request.
6
11
  #
7
12
  # The release writes the checksum of the published zip into fingerly-binary.json
8
13
  # before packing, so a package from npm only ever installs the exact binary it
9
- # was released against. The checksum is empty only in a git checkout.
14
+ # was released against. The binary must also be signed by the Apple team in
15
+ # `team_id` there.
10
16
  #
11
17
  # Stdout stays silent because `pod ipc spec` prints its JSON there.
12
18
  set -euo pipefail
13
19
 
14
- version="$1"
15
- sha256="$2"
16
- dest="$3/Frameworks"
17
- stamp="$dest/.fingerly-binary"
18
- wanted="$version $sha256"
20
+ script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
21
+ binary_json="$script_dir/fingerly-binary.json"
19
22
 
20
- if [ -d "$dest/Fingerly.xcframework" ] && [ "$(cat "$stamp" 2>/dev/null)" = "$wanted" ]; then
21
- exit 0
23
+ json_field() {
24
+ if [ -f "$2" ]; then
25
+ sed -n 's/^[[:space:]]*"'"$1"'"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$2" | head -n 1
26
+ fi
27
+ }
28
+
29
+ version="${1:-$(json_field version "$binary_json")}"
30
+ sha256="${2-$(json_field sha256 "$binary_json")}"
31
+ pod_root="${3:-$script_dir}"
32
+ url="${4:-$(json_field url "$binary_json")}"
33
+ team_id="${5-$(json_field team_id "$binary_json")}"
34
+
35
+ if [ -z "$version" ]; then
36
+ echo "error: missing Fingerly XCFramework version" >&2
37
+ exit 1
22
38
  fi
23
39
 
24
- url="https://maven.fingerly.io/ios/Fingerly-$version.xcframework.zip"
40
+ if [ -z "$url" ]; then
41
+ url="https://maven.fingerly.io/ios/Fingerly-$version.xcframework.zip"
42
+ fi
43
+
44
+ dest="$pod_root/Frameworks"
45
+ stamp="$dest/.fingerly-binary"
46
+ wanted="$version $sha256 $team_id"
47
+
25
48
  work="$(mktemp -d "${TMPDIR:-/tmp}/fingerly-xcframework.XXXXXX")"
26
49
  trap 'rm -rf "$work"' EXIT
27
50
 
51
+ if [ -n "${FINGERLY_XCFRAMEWORK_PATH:-}" ]; then
52
+ if [ -d "$FINGERLY_XCFRAMEWORK_PATH" ]; then
53
+ if [ ! -f "$FINGERLY_XCFRAMEWORK_PATH/Info.plist" ]; then
54
+ echo "error: $FINGERLY_XCFRAMEWORK_PATH is not a valid XCFramework (missing Info.plist)" >&2
55
+ exit 1
56
+ fi
57
+ mkdir -p "$work/expanded"
58
+ cp -R "$FINGERLY_XCFRAMEWORK_PATH" "$work/expanded/Fingerly.xcframework"
59
+ elif [ -f "$FINGERLY_XCFRAMEWORK_PATH" ]; then
60
+ unzip -q "$FINGERLY_XCFRAMEWORK_PATH" -d "$work/expanded"
61
+ if [ ! -d "$work/expanded/Fingerly.xcframework" ]; then
62
+ echo "error: $FINGERLY_XCFRAMEWORK_PATH does not contain Fingerly.xcframework" >&2
63
+ exit 1
64
+ fi
65
+ else
66
+ echo "error: FINGERLY_XCFRAMEWORK_PATH does not exist: $FINGERLY_XCFRAMEWORK_PATH" >&2
67
+ exit 1
68
+ fi
69
+
70
+ rm -rf "$dest"
71
+ mkdir -p "$dest"
72
+ mv "$work/expanded/Fingerly.xcframework" "$dest/"
73
+ # Never the pinned stamp: a later run without the variable replaces a local
74
+ # copy with the verified download instead of keeping it as if it were one.
75
+ printf '%s' "local:$FINGERLY_XCFRAMEWORK_PATH" > "$stamp"
76
+ exit 0
77
+ fi
78
+
79
+ # A download is only ever installed against a pinned checksum. An empty one is
80
+ # a broken package, not a reason to install whatever the host serves.
81
+ if ! printf '%s' "$sha256" | grep -qE '^[0-9a-f]{64}$'; then
82
+ echo "error: no valid checksum recorded for $url; refusing to install an unverified binary" >&2
83
+ exit 1
84
+ fi
85
+ if ! printf '%s' "$team_id" | grep -qE '^[A-Z0-9]{10}$'; then
86
+ echo "error: no valid Apple team identifier recorded for $url; refusing to install an unverified binary" >&2
87
+ exit 1
88
+ fi
89
+
90
+ # Refuses any framework that is not signed by the pinned Apple team: it needs a
91
+ # valid signature under an Apple-issued certificate whose leaf names the team,
92
+ # on the XCFramework and on every slice, and the signature must record the
93
+ # same team. Unsigned, ad hoc, altered and other-team binaries all fail.
94
+ verify_signature() {
95
+ local framework="$1" requirement code signer out
96
+ requirement="anchor apple generic and certificate leaf[subject.OU] = \"$team_id\""
97
+ for code in "$framework" "$framework"/*/Fingerly.framework; do
98
+ [ -e "$code" ] || continue
99
+ if ! out="$(codesign --verify --strict --deep -R="$requirement" "$code" 2>&1)"; then
100
+ echo "error: $code is not signed by Apple team $team_id: $(printf '%s' "$out" | tr '\n' ' ')" >&2
101
+ return 1
102
+ fi
103
+ signer="$(codesign -dv "$code" 2>&1 | sed -n 's/^TeamIdentifier=//p')"
104
+ if [ "$signer" != "$team_id" ]; then
105
+ echo "error: $code records team ${signer:-none}, expected $team_id" >&2
106
+ return 1
107
+ fi
108
+ done
109
+ }
110
+
111
+ # The stamp says what was installed; the signature is checked again, so a
112
+ # framework swapped in place of a verified one is not kept.
113
+ if [ -d "$dest/Fingerly.xcframework" ] && [ "$(cat "$stamp" 2>/dev/null)" = "$wanted" ] \
114
+ && verify_signature "$dest/Fingerly.xcframework" 2>/dev/null; then
115
+ exit 0
116
+ fi
117
+
28
118
  if ! curl --fail --silent --show-error --location --proto '=https' --retry 3 --output "$work/sdk.zip" "$url"; then
29
119
  echo "error: could not download $url" >&2
30
120
  exit 1
31
121
  fi
32
122
 
33
- if [ -n "$sha256" ]; then
34
- actual="$(shasum -a 256 "$work/sdk.zip" | cut -d' ' -f1)"
35
- if [ "$actual" != "$sha256" ]; then
36
- echo "error: $url has checksum $actual, expected $sha256" >&2
37
- exit 1
38
- fi
39
- else
40
- echo "warning: no checksum recorded, $url was not verified (expected only in a git checkout)" >&2
123
+ actual="$(shasum -a 256 "$work/sdk.zip" | cut -d' ' -f1)"
124
+ if [ "$actual" != "$sha256" ]; then
125
+ echo "error: $url has checksum $actual, expected $sha256" >&2
126
+ exit 1
41
127
  fi
42
128
 
43
129
  unzip -q "$work/sdk.zip" -d "$work/expanded"
@@ -45,6 +131,7 @@ if [ ! -d "$work/expanded/Fingerly.xcframework" ]; then
45
131
  echo "error: $url does not contain Fingerly.xcframework" >&2
46
132
  exit 1
47
133
  fi
134
+ verify_signature "$work/expanded/Fingerly.xcframework" || exit 1
48
135
 
49
136
  rm -rf "$dest"
50
137
  mkdir -p "$dest"
@@ -1,4 +1,6 @@
1
1
  {
2
- "version": "0.2.0",
3
- "sha256": "af5be333b61f1e125fe8dbd9ce7ee32f616378bb62f5061c864e03dad7100ba5"
2
+ "version": "0.4.0",
3
+ "url": "https://maven.fingerly.io/ios/Fingerly-0.4.0.xcframework.zip",
4
+ "sha256": "962dcded8374e162a095c9373d7044e66532a327a002889347c547868cc64460",
5
+ "team_id": "XGXX88HRR5"
4
6
  }
@@ -14,13 +14,14 @@ package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
14
14
  binary = JSON.parse(File.read(File.join(__dir__, 'fingerly-binary.json')))
15
15
 
16
16
  unless system('bash', File.join(__dir__, 'fetch-fingerly-xcframework.sh'),
17
- binary['version'], binary['sha256'].to_s, __dir__)
17
+ binary['version'], binary['sha256'].to_s, __dir__, binary['url'].to_s,
18
+ binary['team_id'].to_s)
18
19
  raise "Could not fetch Fingerly.xcframework #{binary['version']}. See the message above."
19
20
  end
20
21
 
21
22
  Pod::Spec.new do |s|
22
23
  s.name = 'fingerly-lynx'
23
- s.version = package['version']
24
+ s.version = package['version'] || '0.4.0'
24
25
  s.summary = 'Fingerly native bridge for Lynx'
25
26
  s.homepage = 'https://fingerly.io'
26
27
  s.license = { :type => 'Apache-2.0', :file => '../LICENSE' }
@@ -25,7 +25,8 @@
25
25
  playIntegrityCloudProjectNumber:(double)playIntegrityCloudProjectNumber {
26
26
  // `src/index.ts` always sends a consent, `pending` when the app passed none.
27
27
  // The native bridge reads anything it does not recognise as `pending`.
28
- // The Play Integrity project number is Android only and not read here.
28
+ // The Play Integrity project number is Android only and ignored on iOS.
29
+ (void)playIntegrityCloudProjectNumber;
29
30
  [FingerlyBridge configureWithApiKey:apiKey endpoint:endpoint platform:platform consent:consent];
30
31
  }
31
32
 
@@ -71,7 +72,9 @@
71
72
  }
72
73
 
73
74
  - (void)deleteStoredIdentity:(id)success failure:(id)failure {
74
- // A keychain delete, synchronous and quick. A refusal carries the
75
+ // Deletes the local install record and App Attest key state in the app's
76
+ // Application Support container. Strictly for user-initiated GDPR/privacy
77
+ // erasure or account deletion (never routine logout). A refusal carries the
75
78
  // `delete_failed` code in `userInfo`, which `errorJSON:` passes on.
76
79
  //
77
80
  // Both are Lynx callback blocks, `void (^)(id result)`, and are called with
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fingerly/lynx",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -28,7 +28,7 @@
28
28
  "README.md"
29
29
  ],
30
30
  "dependencies": {
31
- "@fingerly/types": "0.1.2"
31
+ "@fingerly/types": "0.4.0"
32
32
  },
33
33
  "devDependencies": {
34
34
  "@lynx-js/autolink-codegen": "0.6.0",
package/src/index.ts CHANGED
@@ -2,11 +2,11 @@
2
2
 
3
3
  import { requireFingerly } from '../generated/Fingerly'
4
4
 
5
+ import { ConsentState, SdkPlatform } from '@fingerly/types'
5
6
  import type {
6
7
  MobileFingerlyOptions,
7
8
  MobileIdentifyOptions,
8
9
  NativeIdentifyResult,
9
- SdkPlatform,
10
10
  SignalReport,
11
11
  } from '@fingerly/types'
12
12
 
@@ -34,13 +34,6 @@ interface FingerlyNativeModule {
34
34
  sdkVersion(): string
35
35
  }
36
36
 
37
- /**
38
- * Whether the user has agreed to be identified. Spelled as in `@fingerly/core`
39
- * and the native SDKs; declared here so this package builds against any copy of
40
- * `@fingerly/types`, including one that predates consent.
41
- */
42
- export type ConsentState = 'granted' | 'pending' | 'denied'
43
-
44
37
  export interface FingerlyOptions extends MobileFingerlyOptions {
45
38
  /**
46
39
  * The consent to start from, `pending` when omitted. Call `setConsent` once
@@ -52,11 +45,11 @@ export interface FingerlyOptions extends MobileFingerlyOptions {
52
45
  consent?: ConsentState
53
46
  /**
54
47
  * Android only: your Google Cloud project number, the one linked to the app
55
- * in Play Console, to add Play Integrity verdicts to events (server ADR
56
- * 0026). It takes effect only when the app also depends on the optional
57
- * `io.fingerly:fingerly-play-integrity` artifact; without it the number is
58
- * ignored and nothing fails. Ignored on iOS. Omit it to leave Play
59
- * Integrity off.
48
+ * in Play Console, to add Play Integrity Standard verdicts to v3 events
49
+ * (server ADR 0026). Used when the app also configures the optional
50
+ * `io.fingerly:fingerly-play-integrity` provider; without it the number is
51
+ * ignored and nothing fails. Ignored on iOS. Omit it to leave Play Integrity
52
+ * off.
60
53
  */
61
54
  playIntegrityCloudProjectNumber?: number
62
55
  }
@@ -67,8 +60,7 @@ export interface IdentifyOptions extends MobileIdentifyOptions {
67
60
  * user: on start, on a timer, on returning to the foreground. It joins an
68
61
  * identification already in flight instead of starting another, and waits
69
62
  * out a transient failure instead of repeating it at once. False when
70
- * omitted. On Android it has no effect until the native Android SDK
71
- * supports it.
63
+ * omitted.
72
64
  */
73
65
  automatic?: boolean
74
66
  }
@@ -91,8 +83,7 @@ export class FingerlyError extends Error {
91
83
  /**
92
84
  * How long the server asked the app to wait, in milliseconds, from its
93
85
  * `Retry-After`, when the native SDK gave up on a 429 or 503 that named
94
- * one. Undefined when no wait was named, and on Android until the native
95
- * Android bridge passes the header on.
86
+ * one. Undefined when no wait was named.
96
87
  */
97
88
  readonly retryAfterMs?: number,
98
89
  ) {
@@ -117,7 +108,7 @@ export class ConsentError extends FingerlyError {
117
108
 
118
109
  const CONSENT_REQUIRED = 'consent_required'
119
110
 
120
- const CONSENT_STATES: readonly ConsentState[] = ['granted', 'pending', 'denied']
111
+ const CONSENT_STATES: readonly ConsentState[] = Object.values(ConsentState)
121
112
 
122
113
  function isConsentState(value: unknown): value is ConsentState {
123
114
  return CONSENT_STATES.includes(value as ConsentState)
@@ -158,14 +149,14 @@ function refusedConsent(record: Record<string, unknown> | undefined, message: st
158
149
  const fromNative = record?.state
159
150
  if (isConsentState(fromNative)) return fromNative
160
151
  const fromMessage = /\(consent is (\w+)\)/.exec(message)?.[1]
161
- return isConsentState(fromMessage) ? fromMessage : 'pending'
152
+ return isConsentState(fromMessage) ? fromMessage : ConsentState.Pending
162
153
  }
163
154
 
164
155
  /**
165
156
  * The consent last handed to the native SDK. Module state because the native
166
157
  * bridge keeps one client per process, shared by every `FingerlyClient` here.
167
158
  */
168
- let currentConsent: ConsentState = 'pending'
159
+ let currentConsent: ConsentState = ConsentState.Pending
169
160
 
170
161
  const MISSING_NATIVE_MODULE =
171
162
  '@fingerly/lynx could not find its Fingerly native module. Enable Lynx Native ' +
@@ -189,8 +180,8 @@ function nativeModule(): FingerlyNativeModule {
189
180
 
190
181
  function platformName(): SdkPlatform {
191
182
  const platform = typeof SystemInfo === 'undefined' ? undefined : SystemInfo?.platform
192
- if (platform === 'Android') return 'lynx-android'
193
- if (platform === 'iOS') return 'lynx-ios'
183
+ if (platform === 'Android') return SdkPlatform.LynxAndroid
184
+ if (platform === 'iOS') return SdkPlatform.LynxIos
194
185
  throw new FingerlyError(
195
186
  `@fingerly/lynx supports iOS and Android only; received ${platform ?? 'an unknown platform'}.`,
196
187
  )
@@ -312,9 +303,18 @@ const NULLABLE_FIELDS = [
312
303
 
313
304
  function serverAnswer(parsed: Record<string, unknown>): NativeIdentifyResult {
314
305
  const answer = pick(parsed, SERVER_FIELDS)
306
+ answer.visitorId = typeof answer.visitorId === 'string' ? answer.visitorId : ''
315
307
  for (const field of NULLABLE_FIELDS) {
316
308
  if (answer[field] === undefined) answer[field] = null
317
309
  }
310
+ // v3 Option B invariant: unidentifiable checks emit `visitorId: ""` and
311
+ // `visitorIsNew: false`, and an empty `visitorId` is never marked newly minted.
312
+ if (answer.identifiable === false) {
313
+ answer.visitorId = ''
314
+ answer.visitorIsNew = false
315
+ } else if (answer.visitorId === '' && answer.visitorIsNew === true) {
316
+ answer.visitorIsNew = false
317
+ }
318
318
  return answer as unknown as NativeIdentifyResult
319
319
  }
320
320
 
@@ -347,9 +347,11 @@ export class FingerlyClient {
347
347
  }
348
348
 
349
349
  /**
350
- * Collects and submits, and resolves with the server's answer. With
351
- * `submit: false` nothing is sent and only the raw report comes back.
352
- * Rejects with a `ConsentError` while consent is not `granted`.
350
+ * Collects and submits on the single-pass `v: 3` wire contract, resolving
351
+ * with the server's answer (`visitorId` is `""` and `visitorIsNew` is `false`
352
+ * when `identifiable === false` per Option B). With `submit: false` nothing
353
+ * is sent and only `{ report }` comes back. Rejects with a `ConsentError`
354
+ * while consent is not `granted`.
353
355
  */
354
356
  identify(options: IdentifyOptions & { submit: false }): Promise<RawReportResult>
355
357
  identify(options?: IdentifyOptions & { submit?: true }): Promise<NativeIdentifyResult>
@@ -382,7 +384,7 @@ export class FingerlyClient {
382
384
  * here, or `pending` when there is none, replaces what the native SDK held.
383
385
  */
384
386
  export async function load(options: FingerlyOptions): Promise<FingerlyClient> {
385
- const consent = options.consent ?? 'pending'
387
+ const consent = options.consent ?? ConsentState.Pending
386
388
  assertConsentState(consent)
387
389
  const playIntegrity = options.playIntegrityCloudProjectNumber
388
390
  assertCloudProjectNumber(playIntegrity)
@@ -399,11 +401,21 @@ export async function load(options: FingerlyOptions): Promise<FingerlyClient> {
399
401
  }
400
402
 
401
403
  /**
402
- * Delete the install record the native SDK keeps on the device, for a user's
403
- * erasure request or account deletion. Needs no `load` and no consent, and
404
- * sends nothing; resolves once no record remains, including when there was
405
- * none. The next consented identification starts a new record, so set consent
406
- * to `'denied'` first to stop identifying as well. Rejects with a
404
+ * Delete the local install record (`install_id`) and local hardware attestation
405
+ * key state kept on the device (`Application Support` container + App Attest
406
+ * key state on iOS; atomic install record + `AndroidKeyStore` signing key on
407
+ * Android).
408
+ *
409
+ * Strictly for user-initiated GDPR / privacy right-to-erasure requests or
410
+ * account deletion. Do not call this on routine logout, session expiry, or
411
+ * user switching: repeatedly resetting `install_id` on the same device triggers
412
+ * single-key `install_id` churn telemetry (`>= 3` distinct IDs in 24 hours).
413
+ *
414
+ * Needs no `load` and no consent, and sends nothing; resolves once no local
415
+ * record or attestation key remains, including when there was none. A later
416
+ * re-consented identification generates a fresh `install_id` and attests a
417
+ * fresh key so the server mints an unlinked `visitorId`; set consent to
418
+ * `'denied'` first to stop identifying altogether. Rejects with a
407
419
  * `FingerlyError` when the delete fails or the native SDK predates this call.
408
420
  */
409
421
  export async function deleteStoredIdentity(): Promise<void> {
@@ -430,11 +442,34 @@ export function nativeVersion(): string | undefined {
430
442
  }
431
443
  }
432
444
 
445
+ // Runtime constants for the fixed values the API returns and the module
446
+ // accepts, the same objects `@fingerly/core` and `@fingerly/web-js` export, so
447
+ // `result.suspectLevel === SuspectLevel.High` reads the same in every
448
+ // JavaScript SDK. Each is also the type of its values. They are names for
449
+ // strings, not a filter: the module hands on the server's values as they came,
450
+ // so one a newer server adds still reaches the app unchanged.
451
+ export {
452
+ Confidence,
453
+ ConsentState,
454
+ EventState,
455
+ SdkPlatform,
456
+ Signal,
457
+ SuspectLevel,
458
+ } from '@fingerly/types'
459
+
433
460
  export type {
461
+ EngineIdentity,
462
+ IdentifyResult,
463
+ IdentifySubmission,
464
+ IdentifyTrigger,
434
465
  IntegrityReport,
435
466
  Lie,
467
+ LieKind,
468
+ MobileFingerlyOptions,
469
+ MobileIdentifyOptions,
436
470
  NativeIdentifyResult,
437
- SdkPlatform,
471
+ RiskSignal,
472
+ SignalName,
438
473
  SignalOutcome,
439
474
  SignalReport,
440
475
  SignalStatus,
package/types/index.d.ts CHANGED
@@ -1,2 +1,47 @@
1
- export { Fingerly } from '../generated/Fingerly';
2
-
1
+ export { Fingerly, requireFingerly, type FingerlySpec } from '../generated/Fingerly';
2
+ export {
3
+ ConsentError,
4
+ FingerlyClient,
5
+ FingerlyError,
6
+ /**
7
+ * Strictly for user-initiated GDPR / privacy right-to-erasure requests or
8
+ * account deletion (never routine logout). Deletes the local `install_id`
9
+ * record and hardware attestation key state on the device.
10
+ */
11
+ deleteStoredIdentity,
12
+ load,
13
+ nativeVersion,
14
+ } from '../src/index';
15
+ /**
16
+ * Named constants for the fixed values the API returns and the module accepts,
17
+ * the same objects `@fingerly/web-js` exports. Each is also the type of its
18
+ * values.
19
+ */
20
+ export {
21
+ Confidence,
22
+ ConsentState,
23
+ EventState,
24
+ SdkPlatform,
25
+ Signal,
26
+ SuspectLevel,
27
+ } from '../src/index';
28
+ export type {
29
+ EngineIdentity,
30
+ FingerlyOptions,
31
+ IdentifyOptions,
32
+ IdentifyResult,
33
+ IdentifySubmission,
34
+ IdentifyTrigger,
35
+ IntegrityReport,
36
+ Lie,
37
+ LieKind,
38
+ MobileFingerlyOptions,
39
+ MobileIdentifyOptions,
40
+ NativeIdentifyResult,
41
+ RawReportResult,
42
+ RiskSignal,
43
+ SignalName,
44
+ SignalOutcome,
45
+ SignalReport,
46
+ SignalStatus,
47
+ } from '../src/index';