@fingerly/lynx 0.1.1 → 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.
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 { load } from '@fingerly/lynx'
22
43
 
23
- The Android module depends on `io.fingerly:fingerly:0.1.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: '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
+ - [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)
64
+
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`.
89
+
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. |
49
95
 
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.
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,30 +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.
179
+
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:
188
+
189
+ ```kotlin
190
+ // the app module's build.gradle.kts
191
+ dependencies {
192
+ implementation("io.fingerly:fingerly-app-checks:0.3.0")
193
+ }
194
+ ```
195
+
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.
197
+
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:
199
+
200
+ ```kotlin
201
+ // the app module's build.gradle.kts
202
+ dependencies {
203
+ implementation("io.fingerly:fingerly-play-integrity:0.3.0")
204
+ }
205
+ ```
206
+
207
+ ```ts
208
+ const fingerly = await load({
209
+ apiKey: 'fly_pk_production_…',
210
+ consent: 'granted',
211
+ playIntegrityCloudProjectNumber: 123456789012,
212
+ })
213
+ ```
214
+
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>.
166
234
 
167
235
  ## Development
168
236
 
@@ -179,6 +247,12 @@ pnpm example:build
179
247
  ANDROID_HOME=/path/to/android-sdk ./android/gradlew -p android assembleDebug
180
248
  ```
181
249
 
182
- Generated bridge specifications are committed. After changing
183
- `types/platform-native-module.d.ts`, run codegen and commit the generated
184
- 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.1.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();
@@ -24,10 +29,59 @@ public final class Fingerly extends FingerlySpec {
24
29
 
25
30
  @Override
26
31
  @LynxMethod
27
- public void configure(String apiKey, String endpoint, String platform, String consent) {
32
+ public void configure(
33
+ String apiKey,
34
+ String endpoint,
35
+ String platform,
36
+ String consent,
37
+ double playIntegrityCloudProjectNumber) {
28
38
  // `src/index.ts` always sends a consent, `pending` when the app passed none,
29
39
  // so the state is set rather than left as it was.
30
- FingerlyBridge.configure(applicationContext, apiKey, endpoint, platform, consent);
40
+ //
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
+
73
+ FingerlyBridge.configure(
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;
31
85
  }
32
86
 
33
87
  @Override
@@ -40,21 +94,26 @@ public final class Fingerly extends FingerlySpec {
40
94
  @LynxMethod
41
95
  public void identify(
42
96
  @Nullable String tag, boolean submit, boolean automatic, Object success, Object failure) {
43
- // `automatic` is not read: the native Android bridge has no such option
44
- // yet, so every call is identified as a user's call.
45
- FingerlyBridge.identify(tag, submit, settle(success, failure));
97
+ if (refuseUnconfigured(failure)) {
98
+ return;
99
+ }
100
+ FingerlyBridge.identify(tag, submit, automatic, settle(success, failure));
46
101
  }
47
102
 
48
103
  @Override
49
104
  @LynxMethod
50
105
  public void collect(Object success, Object failure) {
106
+ if (refuseUnconfigured(failure)) {
107
+ return;
108
+ }
51
109
  FingerlyBridge.collect(settle(success, failure));
52
110
  }
53
111
 
54
112
  /**
55
- * Deletes the install record, for a user's erasure or account deletion. Needs
56
- * neither `configure` nor consent. A failure is `delete_failed`, the code the
57
- * 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.
58
117
  */
59
118
  @Override
60
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
+ }
@@ -12,7 +12,7 @@ public abstract class FingerlySpec extends LynxContextModule {
12
12
  }
13
13
 
14
14
  @LynxMethod
15
- public abstract void configure(String apiKey, String endpoint, String platform, String consent);
15
+ public abstract void configure(String apiKey, String endpoint, String platform, String consent, double playIntegrityCloudProjectNumber);
16
16
 
17
17
  @LynxMethod
18
18
  public abstract void setConsent(String state);
@@ -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
+ }
@@ -3,7 +3,7 @@
3
3
  const ADDON_NAME = "Fingerly";
4
4
 
5
5
  export interface FingerlySpec {
6
- configure(apiKey: string, endpoint: string, platform: string, consent: string): void;
6
+ configure(apiKey: string, endpoint: string, platform: string, consent: string, playIntegrityCloudProjectNumber: number): void;
7
7
  setConsent(state: string): void;
8
8
  identify(tag: string | null, submit: boolean, automatic: boolean, success: (json: string) => void, failure: (error: string) => void): void;
9
9
  collect(success: (json: string) => void, failure: (error: string) => void): void;
@@ -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.1.0",
3
- "sha256": "c792d46d43ed21d67b7cca8731f616bfe1f7296a7a161ddaad1358b38ba096cf"
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' }
@@ -9,7 +9,7 @@
9
9
 
10
10
  + (NSDictionary<NSString *, NSString *> *)methodLookup {
11
11
  return @{
12
- @"configure" : NSStringFromSelector(@selector(configure:endpoint:platform:consent:)),
12
+ @"configure" : NSStringFromSelector(@selector(configure:endpoint:platform:consent:playIntegrityCloudProjectNumber:)),
13
13
  @"setConsent" : NSStringFromSelector(@selector(setConsent:)),
14
14
  @"identify" : NSStringFromSelector(@selector(identify:submit:automatic:success:failure:)),
15
15
  @"collect" : NSStringFromSelector(@selector(collect:failure:)),
@@ -19,11 +19,14 @@
19
19
  }
20
20
 
21
21
  - (void)configure:(NSString *)apiKey
22
- endpoint:(NSString *)endpoint
23
- platform:(NSString *)platform
24
- consent:(NSString *)consent {
22
+ endpoint:(NSString *)endpoint
23
+ platform:(NSString *)platform
24
+ consent:(NSString *)consent
25
+ playIntegrityCloudProjectNumber:(double)playIntegrityCloudProjectNumber {
25
26
  // `src/index.ts` always sends a consent, `pending` when the app passed none.
26
27
  // The native bridge reads anything it does not recognise as `pending`.
28
+ // The Play Integrity project number is Android only and ignored on iOS.
29
+ (void)playIntegrityCloudProjectNumber;
27
30
  [FingerlyBridge configureWithApiKey:apiKey endpoint:endpoint platform:platform consent:consent];
28
31
  }
29
32
 
@@ -69,7 +72,9 @@
69
72
  }
70
73
 
71
74
  - (void)deleteStoredIdentity:(id)success failure:(id)failure {
72
- // 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
73
78
  // `delete_failed` code in `userInfo`, which `errorJSON:` passes on.
74
79
  //
75
80
  // Both are Lynx callback blocks, `void (^)(id result)`, and are called with
@@ -6,7 +6,7 @@ NS_ASSUME_NONNULL_BEGIN
6
6
 
7
7
  @protocol FingerlySpec <LynxModule>
8
8
 
9
- - (void)configure:(NSString *)apiKey endpoint:(NSString *)endpoint platform:(NSString *)platform consent:(NSString *)consent;
9
+ - (void)configure:(NSString *)apiKey endpoint:(NSString *)endpoint platform:(NSString *)platform consent:(NSString *)consent playIntegrityCloudProjectNumber:(double)playIntegrityCloudProjectNumber;
10
10
  - (void)setConsent:(NSString *)state;
11
11
  - (void)identify:(nullable NSString *)tag submit:(BOOL)submit automatic:(BOOL)automatic success:(id)success failure:(id)failure;
12
12
  - (void)collect:(id)success failure:(id)failure;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fingerly/lynx",
3
- "version": "0.1.1",
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
@@ -13,7 +13,13 @@ import type {
13
13
  declare const SystemInfo: { platform?: string } | undefined
14
14
 
15
15
  interface FingerlyNativeModule {
16
- configure(apiKey: string, endpoint: string, platform: string, consent: ConsentState): void
16
+ configure(
17
+ apiKey: string,
18
+ endpoint: string,
19
+ platform: string,
20
+ consent: ConsentState,
21
+ playIntegrityCloudProjectNumber: number,
22
+ ): void
17
23
  setConsent(state: ConsentState): void
18
24
  identify(
19
25
  tag: string | null,
@@ -44,6 +50,15 @@ export interface FingerlyOptions extends MobileFingerlyOptions {
44
50
  * where another lawful basis applies.
45
51
  */
46
52
  consent?: ConsentState
53
+ /**
54
+ * Android only: your Google Cloud project number, the one linked to the app
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
+ */
61
+ playIntegrityCloudProjectNumber?: number
47
62
  }
48
63
 
49
64
  export interface IdentifyOptions extends MobileIdentifyOptions {
@@ -52,8 +67,7 @@ export interface IdentifyOptions extends MobileIdentifyOptions {
52
67
  * user: on start, on a timer, on returning to the foreground. It joins an
53
68
  * identification already in flight instead of starting another, and waits
54
69
  * out a transient failure instead of repeating it at once. False when
55
- * omitted. On Android it has no effect until the native Android SDK
56
- * supports it.
70
+ * omitted.
57
71
  */
58
72
  automatic?: boolean
59
73
  }
@@ -76,8 +90,7 @@ export class FingerlyError extends Error {
76
90
  /**
77
91
  * How long the server asked the app to wait, in milliseconds, from its
78
92
  * `Retry-After`, when the native SDK gave up on a 429 or 503 that named
79
- * one. Undefined when no wait was named, and on Android until the native
80
- * Android bridge passes the header on.
93
+ * one. Undefined when no wait was named.
81
94
  */
82
95
  readonly retryAfterMs?: number,
83
96
  ) {
@@ -120,6 +133,20 @@ function assertConsentState(state: unknown): asserts state is ConsentState {
120
133
  }
121
134
  }
122
135
 
136
+ /**
137
+ * A Google Cloud project number is a positive whole number. Anything else is a
138
+ * typo the app should hear about at `load`, not a Play Integrity setup that
139
+ * silently does nothing.
140
+ */
141
+ function assertCloudProjectNumber(value: unknown): asserts value is number | undefined {
142
+ if (value === undefined) return
143
+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
144
+ throw new TypeError(
145
+ `Fingerly playIntegrityCloudProjectNumber must be a positive whole number (received ${JSON.stringify(value)})`,
146
+ )
147
+ }
148
+ }
149
+
123
150
  /**
124
151
  * The state behind a native `consent_required` failure. iOS sends it as
125
152
  * `state`; Android sends only the message, which ends with it in a fixed form.
@@ -283,9 +310,18 @@ const NULLABLE_FIELDS = [
283
310
 
284
311
  function serverAnswer(parsed: Record<string, unknown>): NativeIdentifyResult {
285
312
  const answer = pick(parsed, SERVER_FIELDS)
313
+ answer.visitorId = typeof answer.visitorId === 'string' ? answer.visitorId : ''
286
314
  for (const field of NULLABLE_FIELDS) {
287
315
  if (answer[field] === undefined) answer[field] = null
288
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
+ }
289
325
  return answer as unknown as NativeIdentifyResult
290
326
  }
291
327
 
@@ -318,9 +354,11 @@ export class FingerlyClient {
318
354
  }
319
355
 
320
356
  /**
321
- * Collects and submits, and resolves with the server's answer. With
322
- * `submit: false` nothing is sent and only the raw report comes back.
323
- * 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`.
324
362
  */
325
363
  identify(options: IdentifyOptions & { submit: false }): Promise<RawReportResult>
326
364
  identify(options?: IdentifyOptions & { submit?: true }): Promise<NativeIdentifyResult>
@@ -355,10 +393,13 @@ export class FingerlyClient {
355
393
  export async function load(options: FingerlyOptions): Promise<FingerlyClient> {
356
394
  const consent = options.consent ?? 'pending'
357
395
  assertConsentState(consent)
396
+ const playIntegrity = options.playIntegrityCloudProjectNumber
397
+ assertCloudProjectNumber(playIntegrity)
358
398
 
359
399
  const native = nativeModule()
360
400
  try {
361
- native.configure(options.apiKey, options.endpoint ?? '', platformName(), consent)
401
+ // 0 means no Play Integrity; the iOS module accepts the argument and ignores it.
402
+ native.configure(options.apiKey, options.endpoint ?? '', platformName(), consent, playIntegrity ?? 0)
362
403
  } catch (error) {
363
404
  throw parseNativeError(error)
364
405
  }
@@ -367,11 +408,21 @@ export async function load(options: FingerlyOptions): Promise<FingerlyClient> {
367
408
  }
368
409
 
369
410
  /**
370
- * Delete the install record the native SDK keeps on the device, for a user's
371
- * erasure request or account deletion. Needs no `load` and no consent, and
372
- * sends nothing; resolves once no record remains, including when there was
373
- * none. The next consented identification starts a new record, so set consent
374
- * 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
375
426
  * `FingerlyError` when the delete fails or the native SDK predates this call.
376
427
  */
377
428
  export async function deleteStoredIdentity(): Promise<void> {
@@ -399,11 +450,21 @@ export function nativeVersion(): string | undefined {
399
450
  }
400
451
 
401
452
  export type {
453
+ Confidence,
454
+ EngineIdentity,
455
+ IdentifyResult,
456
+ IdentifySubmission,
457
+ IdentifyTrigger,
402
458
  IntegrityReport,
403
459
  Lie,
460
+ LieKind,
461
+ MobileFingerlyOptions,
462
+ MobileIdentifyOptions,
404
463
  NativeIdentifyResult,
464
+ RiskSignal,
405
465
  SdkPlatform,
406
466
  SignalOutcome,
407
467
  SignalReport,
408
468
  SignalStatus,
469
+ SuspectLevel,
409
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';
@@ -1,6 +1,6 @@
1
1
  /** @lynxmodule */
2
2
  export declare class Fingerly {
3
- configure(apiKey: string, endpoint: string, platform: string, consent: string): void;
3
+ configure(apiKey: string, endpoint: string, platform: string, consent: string, playIntegrityCloudProjectNumber: number): void;
4
4
  setConsent(state: string): void;
5
5
  identify(tag: string | null, submit: boolean, automatic: boolean, success: (json: string) => void, failure: (error: string) => void): void;
6
6
  collect(success: (json: string) => void, failure: (error: string) => void): void;