@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 +169 -95
- package/android/build.gradle.kts +21 -1
- package/android/settings.gradle.kts +3 -2
- package/android/src/main/java/io/fingerly/lynx/Fingerly.java +68 -9
- package/android/src/main/java/io/fingerly/lynx/OptionalProviders.java +61 -0
- package/android/src/main/java/io/fingerly/lynx/generated/FingerlySpec.java +1 -1
- package/android/src/test/java/io/fingerly/lynx/OptionalProvidersTest.java +46 -0
- package/generated/Fingerly.ts +1 -1
- package/ios/fetch-fingerly-xcframework.sh +106 -19
- package/ios/fingerly-binary.json +4 -2
- package/ios/fingerly-lynx.podspec +3 -2
- package/ios/src/Fingerly.m +10 -5
- package/ios/src/generated/FingerlySpec.h +1 -1
- package/package.json +2 -2
- package/src/index.ts +75 -14
- package/types/index.d.ts +37 -2
- package/types/platform-native-module.d.ts +1 -1
package/README.md
CHANGED
|
@@ -1,87 +1,114 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
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
|
-
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
|
|
12
|
-
|
|
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
|
-
|
|
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
|
-
|
|
18
|
-
|
|
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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
75
|
-
|
|
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
|
|
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
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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
|
-
|
|
165
|
-
|
|
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
|
-
|
|
184
|
-
|
|
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.
|
package/android/build.gradle.kts
CHANGED
|
@@ -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.
|
|
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.
|
|
13
|
+
repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)
|
|
14
14
|
repositories {
|
|
15
|
+
mavenLocal()
|
|
15
16
|
google()
|
|
16
17
|
mavenCentral()
|
|
17
|
-
|
|
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.
|
|
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(
|
|
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
|
-
|
|
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
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
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
|
+
}
|
package/generated/Fingerly.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
-
|
|
15
|
-
|
|
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
|
-
|
|
21
|
-
|
|
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
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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"
|
package/ios/fingerly-binary.json
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "0.
|
|
3
|
-
"
|
|
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' }
|
package/ios/src/Fingerly.m
CHANGED
|
@@ -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
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
//
|
|
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.
|
|
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.
|
|
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(
|
|
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.
|
|
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
|
|
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
|
|
322
|
-
*
|
|
323
|
-
*
|
|
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
|
-
|
|
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
|
|
371
|
-
*
|
|
372
|
-
*
|
|
373
|
-
*
|
|
374
|
-
*
|
|
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;
|