@fingerly/lynx 0.2.0 → 0.3.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,87 +1,114 @@
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.3.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.3.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.
38
+
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.
40
+
41
+ ```ts
42
+ import { load } from '@fingerly/lynx'
43
+
44
+ // consent: only once you have consent (or another lawful basis)
45
+ const fingerly = await load({ apiKey: 'fly_pk_production_…', consent: 'granted' })
46
+ const result = await fingerly.identify({ tag: 'checkout' })
47
+
48
+ // Send result.requestId to your backend and make the decision there.
49
+ ```
14
50
 
15
- The host app must enable [Lynx Native Library Autolink](https://lynxjs.org/guide/autolink):
51
+ ## Contents
16
52
 
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.
53
+ - [Platform setup](#platform-setup)
54
+ - [Identify](#identify)
55
+ - [Consent](#consent)
56
+ - [Erasure](#erasure)
57
+ - [Why there is no JavaScript fallback](#why-there-is-no-javascript-fallback)
58
+ - [Native SDK dependencies](#native-sdk-dependencies)
59
+ - [Requirements](#requirements)
60
+ - [Documentation](#documentation)
61
+ - [Development](#development)
62
+ - [Help](#help)
63
+ - [Licence](#licence)
22
64
 
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`:
65
+ ## Platform setup
66
+
67
+ The package's `lynx.lib.json` registers the `Fingerly` Native Module. The host app must enable Lynx Native Library Autolink:
68
+
69
+ | Android | iOS |
70
+ | --- | --- |
71
+ | 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. |
72
+
73
+ The Android module depends on `io.fingerly:fingerly:0.3.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
74
 
27
75
  ```groovy
28
76
  maven { url 'https://maven.fingerly.io' }
29
77
  ```
30
78
 
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
79
  ## Identify
39
80
 
40
- ```ts
41
- import { load } from '@fingerly/lynx'
81
+ `load` reports `lynx-ios` or `lynx-android`, 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
82
 
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' })
83
+ `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
84
 
47
- // Send result.requestId to your backend and make the decision there.
48
- ```
85
+ - When `identifiable` is `false` (`v: 3` Option B), `visitorId` is `""` and `visitorIsNew` is `false`.
86
+ - 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.
87
+ - 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.
88
+ - `visitorConfidence`, `visitorIsNew`, `identifiable` and `duplicate` can be `null` when the server did not say, which is not the same as `0` or `false`.
49
89
 
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.
90
+ | Option | What it does |
91
+ | --- | --- |
92
+ | `tag` | A string echoed back on the finished event, for your own correlation. |
93
+ | `submit: false` | Collect without sending. It resolves with `{ report }`, the raw report and nothing else. |
94
+ | `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. |
95
+
96
+ `collect()` returns the native `SignalReport` without submitting it.
68
97
 
69
98
  ```ts
99
+ import { nativeVersion } from '@fingerly/lynx'
100
+
70
101
  const report = await fingerly.collect()
71
102
  const version = nativeVersion()
72
103
  ```
73
104
 
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.
105
+ `nativeVersion()` returns the version of the native SDK that did the collecting.
106
+
107
+ 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.
79
108
 
80
109
  ## Consent
81
110
 
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:
111
+ 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
112
 
86
113
  ```ts
87
114
  import { ConsentError, load } from '@fingerly/lynx'
@@ -100,15 +127,9 @@ fingerly.consent // 'granted', 'pending' or 'denied'
100
127
  | `setConsent(state)` | Records the decision. Synchronous and safe to call repeatedly. |
101
128
  | `consent` | The state last given to the native SDK, read-only. |
102
129
 
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`.
130
+ The default is `'pending'`, so an integration that never mentions consent identifies nobody. Pass `consent: 'granted'` to `load` only when you already have consent, or another lawful basis. Anything other than the three states throws a `TypeError`.
107
131
 
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`:
132
+ 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
133
 
113
134
  ```ts
114
135
  try {
@@ -120,16 +141,9 @@ try {
120
141
  }
121
142
  ```
122
143
 
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`.
144
+ 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
145
 
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.
146
+ 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
147
 
134
148
  ## Erasure
135
149
 
@@ -139,78 +153,84 @@ import { deleteStoredIdentity } from '@fingerly/lynx'
139
153
  await deleteStoredIdentity()
140
154
  ```
141
155
 
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.
156
+ 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).
157
+
158
+ It deletes the local install record (`install_id`) and the local hardware attestation key state kept on the device:
159
+
160
+ - On iOS, the `Application Support/io.fingerly.sdk/` container files, kept with `isExcludedFromBackup = true`, and the App Attest key state.
161
+ - On Android, atomically, the install record and the persistent `AndroidKeyStore` v3 signing key `io.fingerly.sdk.attest.v3`.
162
+
163
+ 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
164
 
150
165
  ## Why there is no JavaScript fallback
151
166
 
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.
167
+ 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
168
 
157
169
  ## Native SDK dependencies
158
170
 
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).
171
+ Both native dependencies are at `0.3.0`.
172
+
173
+ <details>
174
+ <summary><b>iOS</b></summary>
175
+
176
+ `pod install` downloads the matching `Fingerly.xcframework` (`0.3.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).
163
177
 
164
- On Android, the module resolves `io.fingerly:fingerly` from
165
- `https://maven.fingerly.io`, added to the host's repositories as shown above.
178
+ The Play Integrity project number passed to `load` is ignored on iOS.
166
179
 
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:
180
+ </details>
181
+
182
+ <details>
183
+ <summary><b>Android</b></summary>
184
+
185
+ The module resolves `io.fingerly:fingerly:0.3.0` from `https://maven.fingerly.io`, added to the host's repositories as shown in [Platform setup](#platform-setup).
186
+
187
+ **Installed-app checks are opt-in (`io.fingerly:fingerly-app-checks:0.3.0`).** Core `io.fingerly:fingerly:0.3.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.3.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
188
 
177
189
  ```kotlin
190
+ // the app module's build.gradle.kts
178
191
  dependencies {
179
- implementation("io.fingerly:fingerly-app-checks:<same version as io.fingerly:fingerly>")
192
+ implementation("io.fingerly:fingerly-app-checks:0.3.0")
180
193
  }
181
194
  ```
182
195
 
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.
196
+ 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
197
 
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`:
198
+ **Play Integrity (optional, `io.fingerly:fingerly-play-integrity:0.3.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
199
 
193
200
  ```kotlin
194
201
  // the app module's build.gradle.kts
195
202
  dependencies {
196
- implementation("io.fingerly:fingerly-play-integrity:<same version as io.fingerly:fingerly>")
203
+ implementation("io.fingerly:fingerly-play-integrity:0.3.0")
197
204
  }
198
205
  ```
199
206
 
200
207
  ```ts
201
208
  const fingerly = await load({
202
209
  apiKey: 'fly_pk_production_…',
210
+ consent: 'granted',
203
211
  playIntegrityCloudProjectNumber: 123456789012,
204
212
  })
205
213
  ```
206
214
 
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.
215
+ A provider of your own, registered from native code with `FingerlyBridge.setPlayIntegrity(provider)` before `load`, is used in place of the artifact's.
216
+
217
+ 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.
218
+
219
+ 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).
220
+
221
+ </details>
222
+
223
+ ## Requirements
224
+
225
+ | | Minimum |
226
+ | --- | --- |
227
+ | Lynx | 4.1 |
228
+ | iOS | 13.0 |
229
+ | Android | 6.0 (API 23) |
230
+
231
+ ## Documentation
232
+
233
+ Guides and the API reference: <https://docs.fingerly.io/docs/sdks/lynx>.
214
234
 
215
235
  ## Development
216
236
 
@@ -227,6 +247,12 @@ pnpm example:build
227
247
  ANDROID_HOME=/path/to/android-sdk ./android/gradlew -p android assembleDebug
228
248
  ```
229
249
 
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.
250
+ 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.
251
+
252
+ ## Help
253
+
254
+ Open an issue on this repository, or write to <support@fingerly.io>. Security issues: <security@fingerly.io>.
255
+
256
+ ## Licence
257
+
258
+ 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.3.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.3.0")
36
+ compileOnly("io.fingerly:fingerly-play-integrity:0.3.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.3.0",
3
+ "url": "https://maven.fingerly.io/ios/Fingerly-0.3.0.xcframework.zip",
4
+ "sha256": "b3288cc4539b6c5b8bae226854a586473b2457489e69b2ac1f26e9f84f6add27",
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.3.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.3.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.3.0"
32
32
  },
33
33
  "devDependencies": {
34
34
  "@lynx-js/autolink-codegen": "0.6.0",
package/src/index.ts CHANGED
@@ -52,11 +52,11 @@ export interface FingerlyOptions extends MobileFingerlyOptions {
52
52
  consent?: ConsentState
53
53
  /**
54
54
  * 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.
55
+ * in Play Console, to add Play Integrity Standard verdicts to v3 events
56
+ * (server ADR 0026). Used when the app also configures the optional
57
+ * `io.fingerly:fingerly-play-integrity` provider; without it the number is
58
+ * ignored and nothing fails. Ignored on iOS. Omit it to leave Play Integrity
59
+ * off.
60
60
  */
61
61
  playIntegrityCloudProjectNumber?: number
62
62
  }
@@ -67,8 +67,7 @@ export interface IdentifyOptions extends MobileIdentifyOptions {
67
67
  * user: on start, on a timer, on returning to the foreground. It joins an
68
68
  * identification already in flight instead of starting another, and waits
69
69
  * 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.
70
+ * omitted.
72
71
  */
73
72
  automatic?: boolean
74
73
  }
@@ -91,8 +90,7 @@ export class FingerlyError extends Error {
91
90
  /**
92
91
  * How long the server asked the app to wait, in milliseconds, from its
93
92
  * `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.
93
+ * one. Undefined when no wait was named.
96
94
  */
97
95
  readonly retryAfterMs?: number,
98
96
  ) {
@@ -312,9 +310,18 @@ const NULLABLE_FIELDS = [
312
310
 
313
311
  function serverAnswer(parsed: Record<string, unknown>): NativeIdentifyResult {
314
312
  const answer = pick(parsed, SERVER_FIELDS)
313
+ answer.visitorId = typeof answer.visitorId === 'string' ? answer.visitorId : ''
315
314
  for (const field of NULLABLE_FIELDS) {
316
315
  if (answer[field] === undefined) answer[field] = null
317
316
  }
317
+ // v3 Option B invariant: unidentifiable checks emit `visitorId: ""` and
318
+ // `visitorIsNew: false`, and an empty `visitorId` is never marked newly minted.
319
+ if (answer.identifiable === false) {
320
+ answer.visitorId = ''
321
+ answer.visitorIsNew = false
322
+ } else if (answer.visitorId === '' && answer.visitorIsNew === true) {
323
+ answer.visitorIsNew = false
324
+ }
318
325
  return answer as unknown as NativeIdentifyResult
319
326
  }
320
327
 
@@ -347,9 +354,11 @@ export class FingerlyClient {
347
354
  }
348
355
 
349
356
  /**
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`.
357
+ * Collects and submits on the single-pass `v: 3` wire contract, resolving
358
+ * with the server's answer (`visitorId` is `""` and `visitorIsNew` is `false`
359
+ * when `identifiable === false` per Option B). With `submit: false` nothing
360
+ * is sent and only `{ report }` comes back. Rejects with a `ConsentError`
361
+ * while consent is not `granted`.
353
362
  */
354
363
  identify(options: IdentifyOptions & { submit: false }): Promise<RawReportResult>
355
364
  identify(options?: IdentifyOptions & { submit?: true }): Promise<NativeIdentifyResult>
@@ -399,11 +408,21 @@ export async function load(options: FingerlyOptions): Promise<FingerlyClient> {
399
408
  }
400
409
 
401
410
  /**
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
411
+ * Delete the local install record (`install_id`) and local hardware attestation
412
+ * key state kept on the device (`Application Support` container + App Attest
413
+ * key state on iOS; atomic install record + `AndroidKeyStore` signing key on
414
+ * Android).
415
+ *
416
+ * Strictly for user-initiated GDPR / privacy right-to-erasure requests or
417
+ * account deletion. Do not call this on routine logout, session expiry, or
418
+ * user switching: repeatedly resetting `install_id` on the same device triggers
419
+ * single-key `install_id` churn telemetry (`>= 3` distinct IDs in 24 hours).
420
+ *
421
+ * Needs no `load` and no consent, and sends nothing; resolves once no local
422
+ * record or attestation key remains, including when there was none. A later
423
+ * re-consented identification generates a fresh `install_id` and attests a
424
+ * fresh key so the server mints an unlinked `visitorId`; set consent to
425
+ * `'denied'` first to stop identifying altogether. Rejects with a
407
426
  * `FingerlyError` when the delete fails or the native SDK predates this call.
408
427
  */
409
428
  export async function deleteStoredIdentity(): Promise<void> {
@@ -431,11 +450,21 @@ export function nativeVersion(): string | undefined {
431
450
  }
432
451
 
433
452
  export type {
453
+ Confidence,
454
+ EngineIdentity,
455
+ IdentifyResult,
456
+ IdentifySubmission,
457
+ IdentifyTrigger,
434
458
  IntegrityReport,
435
459
  Lie,
460
+ LieKind,
461
+ MobileFingerlyOptions,
462
+ MobileIdentifyOptions,
436
463
  NativeIdentifyResult,
464
+ RiskSignal,
437
465
  SdkPlatform,
438
466
  SignalOutcome,
439
467
  SignalReport,
440
468
  SignalStatus,
469
+ SuspectLevel,
441
470
  } from '@fingerly/types'
package/types/index.d.ts CHANGED
@@ -1,2 +1,37 @@
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
+ export type {
16
+ Confidence,
17
+ ConsentState,
18
+ EngineIdentity,
19
+ FingerlyOptions,
20
+ IdentifyOptions,
21
+ IdentifyResult,
22
+ IdentifySubmission,
23
+ IdentifyTrigger,
24
+ IntegrityReport,
25
+ Lie,
26
+ LieKind,
27
+ MobileFingerlyOptions,
28
+ MobileIdentifyOptions,
29
+ NativeIdentifyResult,
30
+ RawReportResult,
31
+ RiskSignal,
32
+ SdkPlatform,
33
+ SignalOutcome,
34
+ SignalReport,
35
+ SignalStatus,
36
+ SuspectLevel,
37
+ } from '../src/index';