@fingerly/types 0.1.2 → 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 +92 -4
- package/dist/index.d.cts +121 -247
- package/dist/index.d.ts +121 -247
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,14 +1,102 @@
|
|
|
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
|
-
The canonical TypeScript contracts shared by Fingerly's browser and mobile SDKs
|
|
10
|
+
<p align="center"><b>Fingerly shared TypeScript types</b><br>The canonical TypeScript contracts shared by Fingerly's browser and mobile SDKs.</p>
|
|
4
11
|
|
|
5
|
-
|
|
6
|
-
|
|
12
|
+
<p align="center">
|
|
13
|
+
<a href="https://www.npmjs.com/package/@fingerly/types"><img src="https://img.shields.io/npm/v/@fingerly/types?style=flat-square" alt="npm version"></a>
|
|
14
|
+
<a href="https://github.com/fingerly-io/sdk-types/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/fingerly-io/sdk-types/ci.yml?branch=main&style=flat-square&label=ci" alt="CI"></a>
|
|
15
|
+
<a href="LICENSE"><img src="https://img.shields.io/github/license/fingerly-io/sdk-types?style=flat-square" alt="License"></a>
|
|
16
|
+
<a href="https://docs.fingerly.io/docs/sdks"><img src="https://img.shields.io/badge/docs-docs.fingerly.io-blue?style=flat-square" alt="Documentation"></a>
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
<p align="center"><img src="https://raw.githubusercontent.com/fingerly-io/.github/main/assets/banner.webp" alt="Fingerly" width="100%"></p>
|
|
20
|
+
|
|
21
|
+
## What is this
|
|
22
|
+
|
|
23
|
+
`@fingerly/types` holds the canonical TypeScript `v: 3` wire contracts that every Fingerly client
|
|
24
|
+
SDK agrees on: what a browser or an app submits and what the Fingerly API answers. It is shared by
|
|
25
|
+
the browser SDKs (`@fingerly/core`, `@fingerly/web-js`, and the framework bindings) and the
|
|
26
|
+
TypeScript mobile bridges (`@fingerly/react-native`, `@fingerly/lynx`).
|
|
27
|
+
[Fingerly](https://fingerly.io) is device intelligence for fraud prevention.
|
|
28
|
+
|
|
29
|
+
This package contains TypeScript declarations only (`ES2020`, zero DOM globals, zero runtime
|
|
30
|
+
code). Collection, transport, hardware attestation, and scoring belong to the platform SDKs and
|
|
31
|
+
the Fingerly server. Stored events are read server-side with a secret key, so their types live in
|
|
32
|
+
the server SDKs. You do not need this package to use Fingerly: the browser and framework packages
|
|
33
|
+
already depend on it. Install it when you want to type your own code against the same shapes.
|
|
34
|
+
|
|
35
|
+
## Getting started
|
|
36
|
+
|
|
37
|
+
1. Prerequisites: a Fingerly account and a project key. See
|
|
38
|
+
[API keys](https://docs.fingerly.io/docs/api-keys).
|
|
39
|
+
2. Install:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
npm install -D @fingerly/types@^0.3.0
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
3. Import the types you need:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import type { IdentifyResult } from '@fingerly/types'
|
|
49
|
+
|
|
50
|
+
function describe(result: IdentifyResult): string {
|
|
51
|
+
return `${result.visitorId}: ${result.suspectLevel ?? 'not scored'}`
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The package ships ESM and CommonJS entry points with declarations (`dist` only).
|
|
56
|
+
|
|
57
|
+
## What lives here
|
|
58
|
+
|
|
59
|
+
- **Single-pass `v: 3` ingest envelope (`IdentifySubmission`):** `v: 3`, `sdk`,
|
|
60
|
+
`consent`, `signals` (`SignalReport` carrying `schema`, `budget_ms`,
|
|
61
|
+
`elapsed_ms`, `sources`, and `integrity`), and optional `tag`, `ticket` and
|
|
62
|
+
`ticket_pow`.
|
|
63
|
+
- **Web freshness ticket (`TicketRequest`, `FreshnessTicket`):** the
|
|
64
|
+
`op: 'ticket'` request body and the `{ ticket, expires_at, pow_bits? }`
|
|
65
|
+
answer, also returned as `next_ticket` on a web identification answer.
|
|
66
|
+
- **Collection options (`CollectOptions`, `IdentifyOptions`):** `signal`
|
|
67
|
+
(`AbortSignalLike`), `incognitoDetection: 'standard' | 'extended'`, and `tag`.
|
|
68
|
+
- **1-RTT server answer (`IdentifyResult`, `NativeIdentifyResult`):** `requestId`,
|
|
69
|
+
`visitorId` (`""` with `visitorIsNew: false` whenever `identifiable === false`,
|
|
70
|
+
inside an embedded WebView, or on high-risk unmatched Web traffic),
|
|
71
|
+
`visitorConfidence`, `identifiable`, `duplicate`, `state`, `suspectScore`
|
|
72
|
+
and `suspectLevel`. The signal report is what `collect()` returns.
|
|
73
|
+
- **Canonical v3 risk signal union (`RiskSignal`).**
|
|
7
74
|
|
|
8
75
|
## Development
|
|
9
76
|
|
|
77
|
+
This repository is mounted in the [`sdks`](https://github.com/fingerly-io/sdks) monorepo at
|
|
78
|
+
`client/web/types`, where the package is built and published.
|
|
79
|
+
|
|
10
80
|
```sh
|
|
11
81
|
pnpm install
|
|
12
82
|
pnpm lint
|
|
13
83
|
pnpm build
|
|
84
|
+
pnpm test
|
|
14
85
|
```
|
|
86
|
+
|
|
87
|
+
`pnpm lint` also type-checks `tests/`, which needs `@types/node`; that package only comes from the
|
|
88
|
+
`sdks` workspace, so run lint there.
|
|
89
|
+
|
|
90
|
+
## Documentation
|
|
91
|
+
|
|
92
|
+
See the [SDK overview](https://docs.fingerly.io/docs/sdks) on docs.fingerly.io and the
|
|
93
|
+
[API reference](https://docs.fingerly.io/reference/overview).
|
|
94
|
+
|
|
95
|
+
## Help
|
|
96
|
+
|
|
97
|
+
Open an issue on this repository, or write to [support@fingerly.io](mailto:support@fingerly.io).
|
|
98
|
+
Security issues: [security@fingerly.io](mailto:security@fingerly.io).
|
|
99
|
+
|
|
100
|
+
## Licence
|
|
101
|
+
|
|
102
|
+
Apache-2.0, see [LICENSE](LICENSE).
|
package/dist/index.d.cts
CHANGED
|
@@ -6,15 +6,36 @@
|
|
|
6
6
|
* name it; what does not belong here is the code that reads a `window`.
|
|
7
7
|
*/
|
|
8
8
|
/** Which SDK collected a report. Mirrors `schemas.SDKInfo` on the server. */
|
|
9
|
+
type SdkPlatform = 'web' | 'android' | 'ios' | 'react-native-ios' | 'react-native-android' | 'flutter-ios' | 'flutter-android' | 'lynx-ios' | 'lynx-android';
|
|
9
10
|
/**
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
* `ios` or `android` in the string — see `models.RiskPlatformFor`. A React
|
|
13
|
-
* Native app reporting only `react-native` falls through to the browser
|
|
14
|
-
* profile, where `jailbreak` is not a signal at all and everything the native
|
|
15
|
-
* SDK went to the trouble of collecting is worth nothing.
|
|
11
|
+
* Whether opt-in extended incognito probes (such as Chromium IndexedDB
|
|
12
|
+
* durability timing) execute alongside zero-write standard probes.
|
|
16
13
|
*/
|
|
17
|
-
type
|
|
14
|
+
type IncognitoDetection = 'standard' | 'extended';
|
|
15
|
+
/** Minimal runtime-agnostic `AbortSignal` contract (compiles under pure ES2020 without DOM). */
|
|
16
|
+
interface AbortSignalLike {
|
|
17
|
+
readonly aborted: boolean;
|
|
18
|
+
readonly reason?: unknown;
|
|
19
|
+
addEventListener(type: 'abort', listener: () => void, options?: {
|
|
20
|
+
once?: boolean;
|
|
21
|
+
}): void;
|
|
22
|
+
removeEventListener(type: 'abort', listener: () => void): void;
|
|
23
|
+
}
|
|
24
|
+
/** Options for offline signal collection (`collect()`). */
|
|
25
|
+
interface CollectOptions {
|
|
26
|
+
/** Cancels collection (`AbortSignal`). */
|
|
27
|
+
signal?: AbortSignalLike;
|
|
28
|
+
/**
|
|
29
|
+
* Controls whether opt-in extended incognito probes run (`'extended'`) or
|
|
30
|
+
* only standard zero-write probes run (`'standard'`). Defaults to `'standard'`.
|
|
31
|
+
*/
|
|
32
|
+
incognitoDetection?: IncognitoDetection;
|
|
33
|
+
}
|
|
34
|
+
/** Options for single-pass identification (`identify()`). */
|
|
35
|
+
interface IdentifyOptions extends CollectOptions {
|
|
36
|
+
/** Echoed back on the finished event, for the caller's own correlation. */
|
|
37
|
+
tag?: string;
|
|
38
|
+
}
|
|
18
39
|
/** Configuration shared by JavaScript-based native SDK facades. */
|
|
19
40
|
interface MobileFingerlyOptions {
|
|
20
41
|
/** The SDK key, from the dashboard. */
|
|
@@ -26,7 +47,7 @@ interface MobileFingerlyOptions {
|
|
|
26
47
|
interface MobileIdentifyOptions {
|
|
27
48
|
/** Echoed back on the finished event, for the caller's own correlation. */
|
|
28
49
|
tag?: string;
|
|
29
|
-
/** Collect
|
|
50
|
+
/** Collect without submitting when false (native mobile bridges). Defaults to true. */
|
|
30
51
|
submit?: boolean;
|
|
31
52
|
}
|
|
32
53
|
/**
|
|
@@ -35,36 +56,21 @@ interface MobileIdentifyOptions {
|
|
|
35
56
|
* `pending` is the default: an SDK identifies nobody until it is told
|
|
36
57
|
* `granted`. `pending` and `denied` mean the same thing to the SDK - run no
|
|
37
58
|
* source, touch no storage, send nothing, and fail `identify()` with a consent
|
|
38
|
-
* error - and
|
|
39
|
-
* are kept apart only because a consent tool reports them apart, and a page
|
|
40
|
-
* deciding whether to show its banner wants to know which one it has.
|
|
59
|
+
* error - and are kept apart only because a consent tool reports them apart.
|
|
41
60
|
*/
|
|
42
61
|
type ConsentState = 'granted' | 'pending' | 'denied';
|
|
43
62
|
/**
|
|
44
63
|
* How a source finished.
|
|
45
64
|
*
|
|
46
|
-
* Collapsing every failure into one `error` token would make a browser that
|
|
47
|
-
* lacks an API, a privacy extension that blocked it, and a throttled tab that
|
|
48
|
-
* ran out of time all hash identically. They are three different facts about a visitor:
|
|
49
|
-
*
|
|
50
65
|
* - `ok` the source produced a value.
|
|
51
66
|
* - `unsupported` the API is not present. A property of the device/browser.
|
|
52
67
|
* - `blocked` the API is present and refused, or returned deliberate noise.
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
* - `timeout` the source overran its slice of the budget. Says something
|
|
56
|
-
* about load and throttling, and nothing about the device.
|
|
57
|
-
* - `error` the source threw for a reason we did not anticipate.
|
|
68
|
+
* - `timeout` the source overran its slice of the budget.
|
|
69
|
+
* - `error` the source threw for an unexpected reason.
|
|
58
70
|
*/
|
|
59
71
|
type SignalStatus = 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
|
|
60
72
|
/**
|
|
61
73
|
* What one source reported.
|
|
62
|
-
*
|
|
63
|
-
* `ms` is recorded for every status, failures included. A source that took
|
|
64
|
-
* 3ms to be unsupported and one that took 300ms to be blocked are telling
|
|
65
|
-
* different stories, and the duration is frequently the more stable of the two
|
|
66
|
-
* numbers - timing is itself an entropy source, which is why it is kept rather
|
|
67
|
-
* than discarded on the failure path.
|
|
68
74
|
*/
|
|
69
75
|
interface SignalOutcome<T = unknown> {
|
|
70
76
|
status: SignalStatus;
|
|
@@ -74,37 +80,29 @@ interface SignalOutcome<T = unknown> {
|
|
|
74
80
|
value?: T;
|
|
75
81
|
/**
|
|
76
82
|
* Why, for the statuses that have a why. A short stable token such as
|
|
77
|
-
* `SecurityError` or `
|
|
78
|
-
* unstable across versions and would poison any matching built on it.
|
|
83
|
+
* `SecurityError` or `rfp-canvas-prompt-avoided`.
|
|
79
84
|
*/
|
|
80
85
|
reason?: string;
|
|
81
86
|
}
|
|
82
87
|
/**
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
* `
|
|
86
|
-
* inside the fast budget because a page is waiting on the submission. `deferred`
|
|
87
|
-
* sources are the expensive ones - font measurement, audio rendering, WebGL
|
|
88
|
-
* shader precision - which are worth having but not worth blocking a checkout
|
|
89
|
-
* button for.
|
|
88
|
+
* Internal two-stage browser scheduler barrier:
|
|
89
|
+
* - `prerequisite` runs first (`engine` + Gecko RFP timer gate).
|
|
90
|
+
* - `collect` runs second with access to completed prerequisite outcomes.
|
|
90
91
|
*/
|
|
91
|
-
type
|
|
92
|
-
/**
|
|
92
|
+
type SourceStage = 'prerequisite' | 'collect';
|
|
93
|
+
/** Kinds of runtime prototype, descriptor, brand, or native-code tampering. */
|
|
94
|
+
type LieKind = 'not-native' | 'descriptor' | 'prototype' | 'contradiction' | 'missing' | 'brand' | 'to-string-threw' | 'unverified_realm';
|
|
95
|
+
/** A native function, descriptor, brand, or prototype that is not what it should be. */
|
|
93
96
|
interface Lie {
|
|
94
97
|
/** Stable identifier, such as `navigator.hardwareConcurrency.getter`. */
|
|
95
98
|
id: string;
|
|
96
99
|
/** What kind of tampering was observed. */
|
|
97
|
-
kind:
|
|
100
|
+
kind: LieKind;
|
|
98
101
|
/** Optional short detail. Kept stable across versions or left off. */
|
|
99
102
|
detail?: string;
|
|
100
103
|
}
|
|
101
104
|
/**
|
|
102
105
|
* What the browser is, as opposed to what it says it is.
|
|
103
|
-
*
|
|
104
|
-
* `claimed` comes from the user-agent and the UA-CH headers - a string anyone
|
|
105
|
-
* can set. `observed` is derived from engine behaviour that a spoofer has to
|
|
106
|
-
* patch a JS builtin to change, at which point `lies` catches them instead.
|
|
107
|
-
* A disagreement between the two is worth more than either one alone.
|
|
108
106
|
*/
|
|
109
107
|
interface EngineIdentity {
|
|
110
108
|
claimed?: string;
|
|
@@ -119,12 +117,7 @@ interface IntegrityReport {
|
|
|
119
117
|
engine: EngineIdentity;
|
|
120
118
|
}
|
|
121
119
|
/**
|
|
122
|
-
* The whole client-side observation, as submitted
|
|
123
|
-
*
|
|
124
|
-
* This is what lands in `signals` on the wire. The server types that field as
|
|
125
|
-
* `map[string]any` and deliberately does not interpret it (see
|
|
126
|
-
* `server/services/identify.go`), so this interface is the only place the
|
|
127
|
-
* shape is written down until the event store exists.
|
|
120
|
+
* The whole client-side observation, as submitted inside `signals`.
|
|
128
121
|
*/
|
|
129
122
|
interface SignalReport {
|
|
130
123
|
/** Bumped when a field changes meaning, never when one is added. */
|
|
@@ -133,30 +126,42 @@ interface SignalReport {
|
|
|
133
126
|
budget_ms: number;
|
|
134
127
|
/** What collection actually cost. */
|
|
135
128
|
elapsed_ms: number;
|
|
136
|
-
/** Which tiers ran. A fast-only report is not a degraded full one. */
|
|
137
|
-
tiers: SourceTier[];
|
|
138
129
|
sources: Record<string, SignalOutcome>;
|
|
139
130
|
integrity: IntegrityReport;
|
|
140
131
|
}
|
|
141
132
|
/** How sure the server is of a finding. Matches its `*_confidence` fields. */
|
|
142
133
|
type Confidence = 'low' | 'medium' | 'high';
|
|
134
|
+
/** Categorical risk band returned by the server. */
|
|
135
|
+
type SuspectLevel = 'low' | 'medium' | 'high';
|
|
136
|
+
/**
|
|
137
|
+
* Canonical v3 risk signal catalogue (`sdks/contract/openapi.json` &
|
|
138
|
+
* `sdks/contract/v3-manifest.json`).
|
|
139
|
+
*/
|
|
140
|
+
type RiskSignal = 'high_activity' | 'tampering' | 'device_farm' | 'developer_tools' | 'geo_mismatch' | 'device_inconsistent' | 'report_incomplete' | 'fingerprint_suppressed' | 'tor' | 'proxy' | 'residential_proxy' | 'residential_proxy_low_confidence' | 'residential_proxy_medium_confidence' | 'residential_proxy_high_confidence' | 'vpn_public' | 'vpn_timezone' | 'vpn_relay' | 'vpn_mobile' | 'vpn_os_mismatch' | 'vpn_low_confidence' | 'vpn_medium_confidence' | 'vpn_high_confidence' | 'ip_blocklist_email_spam' | 'ip_blocklist_attack_source' | 'ip_abuser' | 'datacenter_ip' | 'bogon_ip' | 'anycast_ip' | 'incognito' | 'bad_bot' | 'automation' | 'fetch_metadata_missing' | 'web_ticket_missing' | 'web_ticket_invalid' | 'antidetect_browser' | 'virtual_machine' | 'privacy_settings' | 'embedded_web_view' | 'remote_control' | 'emulator' | 'root_apps' | 'app_cloner' | 'jailbreak' | 'simulator' | 'frida' | 'mitm_attack' | 'active_call' | 'attestation_missing' | 'attestation_downgrade' | 'app_attest_key_churn' | 'play_device_integrity_failed' | 'play_app_unrecognized' | 'attestation_failed' | 'probe_errors' | 'custom_root_ca' | 'secondary_user_profile';
|
|
141
|
+
/** One active risk trigger (`IdentifyTriggerOut` in OpenAPI). */
|
|
142
|
+
interface IdentifyTrigger {
|
|
143
|
+
signal: RiskSignal | (string & {});
|
|
144
|
+
group?: string;
|
|
145
|
+
weight?: number | null;
|
|
146
|
+
confidence?: Confidence | (string & {});
|
|
147
|
+
}
|
|
143
148
|
/** What a native `identify()` resolves with. See [[IdentifyResult]]. */
|
|
144
149
|
interface NativeIdentifyResult {
|
|
145
150
|
requestId: string;
|
|
146
|
-
/** Who this visitor is
|
|
151
|
+
/** Who this visitor is (`""` when `identifiable === false`). */
|
|
147
152
|
visitorId: string;
|
|
148
153
|
/** `null` when the server did not say, which is not the same as `false`. */
|
|
149
154
|
visitorIsNew: boolean | null;
|
|
150
155
|
/**
|
|
151
|
-
* How sure the server is, 0 to 100
|
|
152
|
-
*
|
|
156
|
+
* How sure the server is, 0 to 100 (`0` when `visitorId === ""`). `null`
|
|
157
|
+
* when it did not say.
|
|
153
158
|
*/
|
|
154
159
|
visitorConfidence: number | null;
|
|
155
160
|
/** `null` when the server did not say. */
|
|
156
161
|
identifiable: boolean | null;
|
|
157
162
|
/**
|
|
158
|
-
* True when this submission was answered before
|
|
159
|
-
* `null` when the server did not say.
|
|
163
|
+
* True when this submission was answered before under the same idempotency
|
|
164
|
+
* key and the stored verdict was replayed. `null` when the server did not say.
|
|
160
165
|
*/
|
|
161
166
|
duplicate: boolean | null;
|
|
162
167
|
/** As [[IdentifyResult.state]]. */
|
|
@@ -164,239 +169,108 @@ interface NativeIdentifyResult {
|
|
|
164
169
|
/** `null` when absent: unscored, or hidden by the SDK key. Not the same as zero. */
|
|
165
170
|
suspectScore: number | null;
|
|
166
171
|
/** `null` when absent, for the same reasons as [[suspectScore]]. */
|
|
167
|
-
suspectLevel:
|
|
172
|
+
suspectLevel: SuspectLevel | null;
|
|
168
173
|
report: SignalReport;
|
|
169
174
|
}
|
|
170
|
-
/** A submission, as the body of `POST /api/v1/ingest`. */
|
|
175
|
+
/** A v3 submission, as the body of `POST /api/v1/ingest`. */
|
|
171
176
|
interface IdentifySubmission {
|
|
177
|
+
/** Wire envelope version. Must equal `3`. */
|
|
178
|
+
v: 3;
|
|
172
179
|
sdk: {
|
|
173
180
|
platform: SdkPlatform;
|
|
174
181
|
version: string;
|
|
175
182
|
};
|
|
176
183
|
/**
|
|
177
184
|
* The SDK's consent state when it sent this. Always `granted`, since an SDK
|
|
178
|
-
* sends nothing otherwise; the server refuses any other value with
|
|
179
|
-
* `consent_required`.
|
|
185
|
+
* sends nothing otherwise; the server refuses any other value with `consent_required`.
|
|
180
186
|
*/
|
|
181
187
|
consent: ConsentState;
|
|
182
188
|
signals: SignalReport;
|
|
183
189
|
tag?: string;
|
|
190
|
+
/**
|
|
191
|
+
* A single-use freshness ticket the server issued to this page (web only).
|
|
192
|
+
* Omitted when none could be fetched; the server then scores
|
|
193
|
+
* `web_ticket_missing` and still answers.
|
|
194
|
+
*/
|
|
195
|
+
ticket?: string;
|
|
196
|
+
/**
|
|
197
|
+
* The proof of work for `ticket`, as a decimal nonce, when the ticket asked
|
|
198
|
+
* for one (`pow_bits` above 0) and it was solved within the budget.
|
|
199
|
+
*/
|
|
200
|
+
ticket_pow?: string;
|
|
184
201
|
}
|
|
185
|
-
/**
|
|
186
|
-
|
|
202
|
+
/**
|
|
203
|
+
* The body of a web ticket request, posted to the same path as a report.
|
|
204
|
+
*/
|
|
205
|
+
interface TicketRequest {
|
|
206
|
+
v: 3;
|
|
207
|
+
op: 'ticket';
|
|
187
208
|
sdk: {
|
|
188
|
-
platform:
|
|
209
|
+
platform: 'web';
|
|
189
210
|
version: string;
|
|
190
211
|
};
|
|
191
|
-
/** As on [[IdentifySubmission.consent]]. */
|
|
192
|
-
consent: ConsentState;
|
|
193
|
-
signals: SignalReport;
|
|
194
|
-
token: string;
|
|
195
212
|
}
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
213
|
+
/**
|
|
214
|
+
* A single-use web freshness ticket: the answer to a ticket request, and the
|
|
215
|
+
* `next_ticket` of a web identification answer.
|
|
216
|
+
*/
|
|
217
|
+
interface FreshnessTicket {
|
|
218
|
+
/** Unpadded base64url. Opaque to the SDK. */
|
|
219
|
+
ticket: string;
|
|
220
|
+
/** RFC 3339 UTC. */
|
|
221
|
+
expires_at: string;
|
|
202
222
|
/**
|
|
203
|
-
*
|
|
204
|
-
*
|
|
223
|
+
* Leading zero bits the ticket's proof of work needs (1 to 22). Absent or 0
|
|
224
|
+
* when the SDK key does not ask for one.
|
|
205
225
|
*/
|
|
206
|
-
|
|
207
|
-
}
|
|
208
|
-
status: 'failed';
|
|
209
|
-
error: Error;
|
|
210
|
-
report?: SignalReport;
|
|
211
|
-
combinedReport?: SignalReport;
|
|
212
|
-
};
|
|
226
|
+
pow_bits?: number;
|
|
227
|
+
}
|
|
213
228
|
/**
|
|
214
|
-
* The answer.
|
|
215
|
-
*
|
|
216
|
-
* Note what is absent: there is no visitor identifier computed here, because
|
|
217
|
-
* the client does not compute one. Hashing components in the page would make
|
|
218
|
-
* the identity forgeable by the visitor and freeze the matching algorithm
|
|
219
|
-
* into whatever SDK version a customer deployed. Fingerly
|
|
220
|
-
* submits the raw report and lets the server decide who this is - and then
|
|
221
|
-
* tells you, in the same response.
|
|
229
|
+
* The server's v3 identification answer (`IdentifyOut`).
|
|
222
230
|
*/
|
|
223
231
|
interface IdentifyResult {
|
|
224
232
|
requestId: string;
|
|
225
233
|
/**
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
* submission was a [[duplicate]]. Otherwise always present: a report too thin
|
|
230
|
-
* to match anyone still gets an identifier, minted rather than matched, so
|
|
231
|
-
* that every event has a key.
|
|
234
|
+
* Stable project-scoped visitor identifier, or `""` whenever
|
|
235
|
+
* `identifiable === false`, the report came from a genuine embedded WebView,
|
|
236
|
+
* or an unmatched Web report is high-risk (Option B).
|
|
232
237
|
*/
|
|
233
238
|
visitorId: string;
|
|
234
|
-
/**
|
|
239
|
+
/**
|
|
240
|
+
* `true` only when a new visitor row was minted; always `false` when
|
|
241
|
+
* `visitorId === ""`.
|
|
242
|
+
*/
|
|
235
243
|
visitorIsNew: boolean;
|
|
236
244
|
/**
|
|
237
|
-
*
|
|
238
|
-
*
|
|
239
|
-
* 100 when this exact device has been seen before, 85-99 when it drifted -
|
|
240
|
-
* a browser update, a new monitor - and was recognised by similarity, and 0
|
|
241
|
-
* when the identifier was minted because nothing matched.
|
|
242
|
-
*
|
|
243
|
-
* Read this rather than inferring trust from [[identifiable]], which only
|
|
244
|
-
* says whether the report was rich enough to attempt a match.
|
|
245
|
+
* Match confidence from 0 to 100 (`0` when `visitorId === ""` or freshly minted).
|
|
245
246
|
*/
|
|
246
247
|
visitorConfidence: number;
|
|
247
248
|
/**
|
|
248
|
-
*
|
|
249
|
-
*
|
|
250
|
-
* A hardened browser produces this honestly; so does a client that would
|
|
251
|
-
* rather not be recognised. Either way the submission is still answered and
|
|
252
|
-
* still scored - more highly, because suppressing a fingerprint is itself
|
|
253
|
-
* evidence - and it is charged at a lower rate, because the address lookup
|
|
254
|
-
* happened and the identification did not.
|
|
249
|
+
* `false` when the report carried too little independent entropy to identify
|
|
250
|
+
* a device.
|
|
255
251
|
*/
|
|
256
252
|
identifiable: boolean;
|
|
257
253
|
/**
|
|
258
|
-
*
|
|
259
|
-
*
|
|
260
|
-
*
|
|
261
|
-
* The verdict belongs to that first submission and is not repeated, so the
|
|
262
|
-
* fields above are empty. Keep the first response, or fetch the event by
|
|
263
|
-
* [[requestId]]. Without this flag an empty visitor would read as "nobody
|
|
264
|
-
* could be identified", which is the opposite of what happened.
|
|
254
|
+
* `true` when this submission replayed a cached verdict under the same
|
|
255
|
+
* `Idempotency-Key`.
|
|
265
256
|
*/
|
|
266
|
-
duplicate
|
|
257
|
+
duplicate?: boolean;
|
|
267
258
|
/**
|
|
268
259
|
* `enriched`, or `unavailable` when the address could not be looked up.
|
|
269
|
-
*
|
|
270
|
-
* Why an `unavailable` submission went unscored describes the service's own
|
|
271
|
-
* infrastructure, which is nothing a visitor's page should be able to read,
|
|
272
|
-
* so it is not on this result. Your backend reads it as `reason` on the
|
|
273
|
-
* server-side event read (`GET /api/v1/events/{request_id}` with a secret
|
|
274
|
-
* key), by [[requestId]].
|
|
275
260
|
*/
|
|
276
261
|
state: string;
|
|
277
262
|
/**
|
|
278
|
-
*
|
|
279
|
-
*
|
|
280
|
-
*
|
|
281
|
-
* `null` when the submission was not scored, or when the SDK key hides the
|
|
282
|
-
* score from public callers: the page is not told which, and your backend
|
|
283
|
-
* still reads the score on the event. Either is a different answer from
|
|
284
|
-
* zero: an ordinary visitor scores zero. Anything computed as a share of your
|
|
285
|
-
* traffic divides by one of those populations, so collapsing them makes the
|
|
286
|
-
* number plausible and wrong.
|
|
287
|
-
*
|
|
288
|
-
* Not a percentage and not capped. Normalising it to 0-100 would discard the
|
|
289
|
-
* difference between "over the line" and "far over the line".
|
|
263
|
+
* Weighted sum of the signals that fired, or `null` when unscored or hidden
|
|
264
|
+
* by `hide_client_score` on public keys.
|
|
290
265
|
*/
|
|
291
266
|
suspectScore: number | null;
|
|
292
|
-
/** `low`, `medium
|
|
293
|
-
suspectLevel:
|
|
294
|
-
/**
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
interface IdentificationConfidence {
|
|
300
|
-
score: number;
|
|
301
|
-
version: string;
|
|
302
|
-
}
|
|
303
|
-
interface Identification {
|
|
304
|
-
visitor_id: string;
|
|
305
|
-
confidence: IdentificationConfidence;
|
|
306
|
-
visitor_found: boolean;
|
|
307
|
-
first_seen_at: number;
|
|
308
|
-
last_seen_at: number;
|
|
309
|
-
}
|
|
310
|
-
interface IpGeolocation {
|
|
311
|
-
accuracy_radius: number;
|
|
312
|
-
latitude: number;
|
|
313
|
-
longitude: number;
|
|
314
|
-
postal_code: string;
|
|
315
|
-
timezone: string;
|
|
316
|
-
city_name: string;
|
|
317
|
-
country_code: string;
|
|
318
|
-
country_name: string;
|
|
319
|
-
continent_code: string;
|
|
320
|
-
continent_name: string;
|
|
321
|
-
subdivisions: {
|
|
322
|
-
iso_code: string;
|
|
323
|
-
name: string;
|
|
324
|
-
}[];
|
|
325
|
-
}
|
|
326
|
-
interface IpInfoV4 {
|
|
327
|
-
address: string;
|
|
328
|
-
geolocation: IpGeolocation;
|
|
329
|
-
asn: string;
|
|
330
|
-
asn_name: string;
|
|
331
|
-
asn_network: string;
|
|
332
|
-
asn_type: string;
|
|
333
|
-
datacenter_result: boolean;
|
|
334
|
-
}
|
|
335
|
-
interface VelocityWindow {
|
|
336
|
-
'5_minutes': number;
|
|
337
|
-
'1_hour': number;
|
|
338
|
-
'24_hours': number;
|
|
339
|
-
}
|
|
340
|
-
interface Velocity {
|
|
341
|
-
distinct_ip: VelocityWindow;
|
|
342
|
-
distinct_country: VelocityWindow;
|
|
343
|
-
events: VelocityWindow;
|
|
344
|
-
ip_events: VelocityWindow;
|
|
345
|
-
}
|
|
346
|
-
/** Fields every platform reports. */
|
|
347
|
-
interface FingerlyEventBase {
|
|
348
|
-
event_id: string;
|
|
349
|
-
timestamp: number;
|
|
350
|
-
source: 'device';
|
|
351
|
-
sdk: {
|
|
352
|
-
platform: SdkPlatform;
|
|
353
|
-
version: string;
|
|
354
|
-
};
|
|
355
|
-
replayed: boolean;
|
|
356
|
-
identification: Identification;
|
|
357
|
-
ip_address: string;
|
|
358
|
-
ip_info: {
|
|
359
|
-
v4: IpInfoV4;
|
|
360
|
-
};
|
|
361
|
-
proxy: boolean;
|
|
362
|
-
proxy_confidence: Confidence;
|
|
363
|
-
vpn: boolean;
|
|
364
|
-
vpn_confidence: Confidence;
|
|
365
|
-
tampering: boolean;
|
|
366
|
-
tampering_confidence: Confidence;
|
|
367
|
-
suspect_score: number;
|
|
368
|
-
velocity: Velocity;
|
|
369
|
-
}
|
|
370
|
-
/**
|
|
371
|
-
* Signals only a native app can observe.
|
|
372
|
-
*
|
|
373
|
-
* Absent on web rather than `false`, because a browser cannot look for a root
|
|
374
|
-
* app and reporting "no" would be a claim nobody made.
|
|
375
|
-
*/
|
|
376
|
-
interface FingerlyMobileEvent extends FingerlyEventBase {
|
|
377
|
-
sdk: {
|
|
378
|
-
platform: 'android' | 'ios';
|
|
379
|
-
version: string;
|
|
380
|
-
};
|
|
381
|
-
package_name: string;
|
|
382
|
-
emulator: boolean;
|
|
383
|
-
root_apps: boolean;
|
|
384
|
-
cloned_app: boolean;
|
|
385
|
-
frida: boolean;
|
|
386
|
-
developer_tools: boolean;
|
|
387
|
-
factory_reset_timestamp?: number;
|
|
388
|
-
active_call: boolean;
|
|
389
|
-
}
|
|
390
|
-
interface FingerlyWebEvent extends FingerlyEventBase {
|
|
391
|
-
sdk: {
|
|
392
|
-
platform: 'web';
|
|
393
|
-
version: string;
|
|
394
|
-
};
|
|
395
|
-
browser_name: string;
|
|
396
|
-
browser_version: string;
|
|
397
|
-
incognito: boolean;
|
|
398
|
-
ad_blocker: boolean;
|
|
267
|
+
/** `low`, `medium`, or `high`; `null` whenever [[suspectScore]] is `null`. */
|
|
268
|
+
suspectLevel: SuspectLevel | null;
|
|
269
|
+
/**
|
|
270
|
+
* Active risk signals and weights (populated only for direct secret-key
|
|
271
|
+
* callers; omitted on public browser keys).
|
|
272
|
+
*/
|
|
273
|
+
triggers?: IdentifyTrigger[];
|
|
399
274
|
}
|
|
400
|
-
type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent;
|
|
401
275
|
|
|
402
|
-
export type {
|
|
276
|
+
export type { AbortSignalLike, CollectOptions, Confidence, ConsentState, EngineIdentity, FreshnessTicket, IdentifyOptions, IdentifyResult, IdentifySubmission, IdentifyTrigger, IncognitoDetection, IntegrityReport, Lie, LieKind, MobileFingerlyOptions, MobileIdentifyOptions, NativeIdentifyResult, RiskSignal, SdkPlatform, SignalOutcome, SignalReport, SignalStatus, SourceStage, SuspectLevel, TicketRequest };
|
package/dist/index.d.ts
CHANGED
|
@@ -6,15 +6,36 @@
|
|
|
6
6
|
* name it; what does not belong here is the code that reads a `window`.
|
|
7
7
|
*/
|
|
8
8
|
/** Which SDK collected a report. Mirrors `schemas.SDKInfo` on the server. */
|
|
9
|
+
type SdkPlatform = 'web' | 'android' | 'ios' | 'react-native-ios' | 'react-native-android' | 'flutter-ios' | 'flutter-android' | 'lynx-ios' | 'lynx-android';
|
|
9
10
|
/**
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
* `ios` or `android` in the string — see `models.RiskPlatformFor`. A React
|
|
13
|
-
* Native app reporting only `react-native` falls through to the browser
|
|
14
|
-
* profile, where `jailbreak` is not a signal at all and everything the native
|
|
15
|
-
* SDK went to the trouble of collecting is worth nothing.
|
|
11
|
+
* Whether opt-in extended incognito probes (such as Chromium IndexedDB
|
|
12
|
+
* durability timing) execute alongside zero-write standard probes.
|
|
16
13
|
*/
|
|
17
|
-
type
|
|
14
|
+
type IncognitoDetection = 'standard' | 'extended';
|
|
15
|
+
/** Minimal runtime-agnostic `AbortSignal` contract (compiles under pure ES2020 without DOM). */
|
|
16
|
+
interface AbortSignalLike {
|
|
17
|
+
readonly aborted: boolean;
|
|
18
|
+
readonly reason?: unknown;
|
|
19
|
+
addEventListener(type: 'abort', listener: () => void, options?: {
|
|
20
|
+
once?: boolean;
|
|
21
|
+
}): void;
|
|
22
|
+
removeEventListener(type: 'abort', listener: () => void): void;
|
|
23
|
+
}
|
|
24
|
+
/** Options for offline signal collection (`collect()`). */
|
|
25
|
+
interface CollectOptions {
|
|
26
|
+
/** Cancels collection (`AbortSignal`). */
|
|
27
|
+
signal?: AbortSignalLike;
|
|
28
|
+
/**
|
|
29
|
+
* Controls whether opt-in extended incognito probes run (`'extended'`) or
|
|
30
|
+
* only standard zero-write probes run (`'standard'`). Defaults to `'standard'`.
|
|
31
|
+
*/
|
|
32
|
+
incognitoDetection?: IncognitoDetection;
|
|
33
|
+
}
|
|
34
|
+
/** Options for single-pass identification (`identify()`). */
|
|
35
|
+
interface IdentifyOptions extends CollectOptions {
|
|
36
|
+
/** Echoed back on the finished event, for the caller's own correlation. */
|
|
37
|
+
tag?: string;
|
|
38
|
+
}
|
|
18
39
|
/** Configuration shared by JavaScript-based native SDK facades. */
|
|
19
40
|
interface MobileFingerlyOptions {
|
|
20
41
|
/** The SDK key, from the dashboard. */
|
|
@@ -26,7 +47,7 @@ interface MobileFingerlyOptions {
|
|
|
26
47
|
interface MobileIdentifyOptions {
|
|
27
48
|
/** Echoed back on the finished event, for the caller's own correlation. */
|
|
28
49
|
tag?: string;
|
|
29
|
-
/** Collect
|
|
50
|
+
/** Collect without submitting when false (native mobile bridges). Defaults to true. */
|
|
30
51
|
submit?: boolean;
|
|
31
52
|
}
|
|
32
53
|
/**
|
|
@@ -35,36 +56,21 @@ interface MobileIdentifyOptions {
|
|
|
35
56
|
* `pending` is the default: an SDK identifies nobody until it is told
|
|
36
57
|
* `granted`. `pending` and `denied` mean the same thing to the SDK - run no
|
|
37
58
|
* source, touch no storage, send nothing, and fail `identify()` with a consent
|
|
38
|
-
* error - and
|
|
39
|
-
* are kept apart only because a consent tool reports them apart, and a page
|
|
40
|
-
* deciding whether to show its banner wants to know which one it has.
|
|
59
|
+
* error - and are kept apart only because a consent tool reports them apart.
|
|
41
60
|
*/
|
|
42
61
|
type ConsentState = 'granted' | 'pending' | 'denied';
|
|
43
62
|
/**
|
|
44
63
|
* How a source finished.
|
|
45
64
|
*
|
|
46
|
-
* Collapsing every failure into one `error` token would make a browser that
|
|
47
|
-
* lacks an API, a privacy extension that blocked it, and a throttled tab that
|
|
48
|
-
* ran out of time all hash identically. They are three different facts about a visitor:
|
|
49
|
-
*
|
|
50
65
|
* - `ok` the source produced a value.
|
|
51
66
|
* - `unsupported` the API is not present. A property of the device/browser.
|
|
52
67
|
* - `blocked` the API is present and refused, or returned deliberate noise.
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
* - `timeout` the source overran its slice of the budget. Says something
|
|
56
|
-
* about load and throttling, and nothing about the device.
|
|
57
|
-
* - `error` the source threw for a reason we did not anticipate.
|
|
68
|
+
* - `timeout` the source overran its slice of the budget.
|
|
69
|
+
* - `error` the source threw for an unexpected reason.
|
|
58
70
|
*/
|
|
59
71
|
type SignalStatus = 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
|
|
60
72
|
/**
|
|
61
73
|
* What one source reported.
|
|
62
|
-
*
|
|
63
|
-
* `ms` is recorded for every status, failures included. A source that took
|
|
64
|
-
* 3ms to be unsupported and one that took 300ms to be blocked are telling
|
|
65
|
-
* different stories, and the duration is frequently the more stable of the two
|
|
66
|
-
* numbers - timing is itself an entropy source, which is why it is kept rather
|
|
67
|
-
* than discarded on the failure path.
|
|
68
74
|
*/
|
|
69
75
|
interface SignalOutcome<T = unknown> {
|
|
70
76
|
status: SignalStatus;
|
|
@@ -74,37 +80,29 @@ interface SignalOutcome<T = unknown> {
|
|
|
74
80
|
value?: T;
|
|
75
81
|
/**
|
|
76
82
|
* Why, for the statuses that have a why. A short stable token such as
|
|
77
|
-
* `SecurityError` or `
|
|
78
|
-
* unstable across versions and would poison any matching built on it.
|
|
83
|
+
* `SecurityError` or `rfp-canvas-prompt-avoided`.
|
|
79
84
|
*/
|
|
80
85
|
reason?: string;
|
|
81
86
|
}
|
|
82
87
|
/**
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
* `
|
|
86
|
-
* inside the fast budget because a page is waiting on the submission. `deferred`
|
|
87
|
-
* sources are the expensive ones - font measurement, audio rendering, WebGL
|
|
88
|
-
* shader precision - which are worth having but not worth blocking a checkout
|
|
89
|
-
* button for.
|
|
88
|
+
* Internal two-stage browser scheduler barrier:
|
|
89
|
+
* - `prerequisite` runs first (`engine` + Gecko RFP timer gate).
|
|
90
|
+
* - `collect` runs second with access to completed prerequisite outcomes.
|
|
90
91
|
*/
|
|
91
|
-
type
|
|
92
|
-
/**
|
|
92
|
+
type SourceStage = 'prerequisite' | 'collect';
|
|
93
|
+
/** Kinds of runtime prototype, descriptor, brand, or native-code tampering. */
|
|
94
|
+
type LieKind = 'not-native' | 'descriptor' | 'prototype' | 'contradiction' | 'missing' | 'brand' | 'to-string-threw' | 'unverified_realm';
|
|
95
|
+
/** A native function, descriptor, brand, or prototype that is not what it should be. */
|
|
93
96
|
interface Lie {
|
|
94
97
|
/** Stable identifier, such as `navigator.hardwareConcurrency.getter`. */
|
|
95
98
|
id: string;
|
|
96
99
|
/** What kind of tampering was observed. */
|
|
97
|
-
kind:
|
|
100
|
+
kind: LieKind;
|
|
98
101
|
/** Optional short detail. Kept stable across versions or left off. */
|
|
99
102
|
detail?: string;
|
|
100
103
|
}
|
|
101
104
|
/**
|
|
102
105
|
* What the browser is, as opposed to what it says it is.
|
|
103
|
-
*
|
|
104
|
-
* `claimed` comes from the user-agent and the UA-CH headers - a string anyone
|
|
105
|
-
* can set. `observed` is derived from engine behaviour that a spoofer has to
|
|
106
|
-
* patch a JS builtin to change, at which point `lies` catches them instead.
|
|
107
|
-
* A disagreement between the two is worth more than either one alone.
|
|
108
106
|
*/
|
|
109
107
|
interface EngineIdentity {
|
|
110
108
|
claimed?: string;
|
|
@@ -119,12 +117,7 @@ interface IntegrityReport {
|
|
|
119
117
|
engine: EngineIdentity;
|
|
120
118
|
}
|
|
121
119
|
/**
|
|
122
|
-
* The whole client-side observation, as submitted
|
|
123
|
-
*
|
|
124
|
-
* This is what lands in `signals` on the wire. The server types that field as
|
|
125
|
-
* `map[string]any` and deliberately does not interpret it (see
|
|
126
|
-
* `server/services/identify.go`), so this interface is the only place the
|
|
127
|
-
* shape is written down until the event store exists.
|
|
120
|
+
* The whole client-side observation, as submitted inside `signals`.
|
|
128
121
|
*/
|
|
129
122
|
interface SignalReport {
|
|
130
123
|
/** Bumped when a field changes meaning, never when one is added. */
|
|
@@ -133,30 +126,42 @@ interface SignalReport {
|
|
|
133
126
|
budget_ms: number;
|
|
134
127
|
/** What collection actually cost. */
|
|
135
128
|
elapsed_ms: number;
|
|
136
|
-
/** Which tiers ran. A fast-only report is not a degraded full one. */
|
|
137
|
-
tiers: SourceTier[];
|
|
138
129
|
sources: Record<string, SignalOutcome>;
|
|
139
130
|
integrity: IntegrityReport;
|
|
140
131
|
}
|
|
141
132
|
/** How sure the server is of a finding. Matches its `*_confidence` fields. */
|
|
142
133
|
type Confidence = 'low' | 'medium' | 'high';
|
|
134
|
+
/** Categorical risk band returned by the server. */
|
|
135
|
+
type SuspectLevel = 'low' | 'medium' | 'high';
|
|
136
|
+
/**
|
|
137
|
+
* Canonical v3 risk signal catalogue (`sdks/contract/openapi.json` &
|
|
138
|
+
* `sdks/contract/v3-manifest.json`).
|
|
139
|
+
*/
|
|
140
|
+
type RiskSignal = 'high_activity' | 'tampering' | 'device_farm' | 'developer_tools' | 'geo_mismatch' | 'device_inconsistent' | 'report_incomplete' | 'fingerprint_suppressed' | 'tor' | 'proxy' | 'residential_proxy' | 'residential_proxy_low_confidence' | 'residential_proxy_medium_confidence' | 'residential_proxy_high_confidence' | 'vpn_public' | 'vpn_timezone' | 'vpn_relay' | 'vpn_mobile' | 'vpn_os_mismatch' | 'vpn_low_confidence' | 'vpn_medium_confidence' | 'vpn_high_confidence' | 'ip_blocklist_email_spam' | 'ip_blocklist_attack_source' | 'ip_abuser' | 'datacenter_ip' | 'bogon_ip' | 'anycast_ip' | 'incognito' | 'bad_bot' | 'automation' | 'fetch_metadata_missing' | 'web_ticket_missing' | 'web_ticket_invalid' | 'antidetect_browser' | 'virtual_machine' | 'privacy_settings' | 'embedded_web_view' | 'remote_control' | 'emulator' | 'root_apps' | 'app_cloner' | 'jailbreak' | 'simulator' | 'frida' | 'mitm_attack' | 'active_call' | 'attestation_missing' | 'attestation_downgrade' | 'app_attest_key_churn' | 'play_device_integrity_failed' | 'play_app_unrecognized' | 'attestation_failed' | 'probe_errors' | 'custom_root_ca' | 'secondary_user_profile';
|
|
141
|
+
/** One active risk trigger (`IdentifyTriggerOut` in OpenAPI). */
|
|
142
|
+
interface IdentifyTrigger {
|
|
143
|
+
signal: RiskSignal | (string & {});
|
|
144
|
+
group?: string;
|
|
145
|
+
weight?: number | null;
|
|
146
|
+
confidence?: Confidence | (string & {});
|
|
147
|
+
}
|
|
143
148
|
/** What a native `identify()` resolves with. See [[IdentifyResult]]. */
|
|
144
149
|
interface NativeIdentifyResult {
|
|
145
150
|
requestId: string;
|
|
146
|
-
/** Who this visitor is
|
|
151
|
+
/** Who this visitor is (`""` when `identifiable === false`). */
|
|
147
152
|
visitorId: string;
|
|
148
153
|
/** `null` when the server did not say, which is not the same as `false`. */
|
|
149
154
|
visitorIsNew: boolean | null;
|
|
150
155
|
/**
|
|
151
|
-
* How sure the server is, 0 to 100
|
|
152
|
-
*
|
|
156
|
+
* How sure the server is, 0 to 100 (`0` when `visitorId === ""`). `null`
|
|
157
|
+
* when it did not say.
|
|
153
158
|
*/
|
|
154
159
|
visitorConfidence: number | null;
|
|
155
160
|
/** `null` when the server did not say. */
|
|
156
161
|
identifiable: boolean | null;
|
|
157
162
|
/**
|
|
158
|
-
* True when this submission was answered before
|
|
159
|
-
* `null` when the server did not say.
|
|
163
|
+
* True when this submission was answered before under the same idempotency
|
|
164
|
+
* key and the stored verdict was replayed. `null` when the server did not say.
|
|
160
165
|
*/
|
|
161
166
|
duplicate: boolean | null;
|
|
162
167
|
/** As [[IdentifyResult.state]]. */
|
|
@@ -164,239 +169,108 @@ interface NativeIdentifyResult {
|
|
|
164
169
|
/** `null` when absent: unscored, or hidden by the SDK key. Not the same as zero. */
|
|
165
170
|
suspectScore: number | null;
|
|
166
171
|
/** `null` when absent, for the same reasons as [[suspectScore]]. */
|
|
167
|
-
suspectLevel:
|
|
172
|
+
suspectLevel: SuspectLevel | null;
|
|
168
173
|
report: SignalReport;
|
|
169
174
|
}
|
|
170
|
-
/** A submission, as the body of `POST /api/v1/ingest`. */
|
|
175
|
+
/** A v3 submission, as the body of `POST /api/v1/ingest`. */
|
|
171
176
|
interface IdentifySubmission {
|
|
177
|
+
/** Wire envelope version. Must equal `3`. */
|
|
178
|
+
v: 3;
|
|
172
179
|
sdk: {
|
|
173
180
|
platform: SdkPlatform;
|
|
174
181
|
version: string;
|
|
175
182
|
};
|
|
176
183
|
/**
|
|
177
184
|
* The SDK's consent state when it sent this. Always `granted`, since an SDK
|
|
178
|
-
* sends nothing otherwise; the server refuses any other value with
|
|
179
|
-
* `consent_required`.
|
|
185
|
+
* sends nothing otherwise; the server refuses any other value with `consent_required`.
|
|
180
186
|
*/
|
|
181
187
|
consent: ConsentState;
|
|
182
188
|
signals: SignalReport;
|
|
183
189
|
tag?: string;
|
|
190
|
+
/**
|
|
191
|
+
* A single-use freshness ticket the server issued to this page (web only).
|
|
192
|
+
* Omitted when none could be fetched; the server then scores
|
|
193
|
+
* `web_ticket_missing` and still answers.
|
|
194
|
+
*/
|
|
195
|
+
ticket?: string;
|
|
196
|
+
/**
|
|
197
|
+
* The proof of work for `ticket`, as a decimal nonce, when the ticket asked
|
|
198
|
+
* for one (`pow_bits` above 0) and it was solved within the budget.
|
|
199
|
+
*/
|
|
200
|
+
ticket_pow?: string;
|
|
184
201
|
}
|
|
185
|
-
/**
|
|
186
|
-
|
|
202
|
+
/**
|
|
203
|
+
* The body of a web ticket request, posted to the same path as a report.
|
|
204
|
+
*/
|
|
205
|
+
interface TicketRequest {
|
|
206
|
+
v: 3;
|
|
207
|
+
op: 'ticket';
|
|
187
208
|
sdk: {
|
|
188
|
-
platform:
|
|
209
|
+
platform: 'web';
|
|
189
210
|
version: string;
|
|
190
211
|
};
|
|
191
|
-
/** As on [[IdentifySubmission.consent]]. */
|
|
192
|
-
consent: ConsentState;
|
|
193
|
-
signals: SignalReport;
|
|
194
|
-
token: string;
|
|
195
212
|
}
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
213
|
+
/**
|
|
214
|
+
* A single-use web freshness ticket: the answer to a ticket request, and the
|
|
215
|
+
* `next_ticket` of a web identification answer.
|
|
216
|
+
*/
|
|
217
|
+
interface FreshnessTicket {
|
|
218
|
+
/** Unpadded base64url. Opaque to the SDK. */
|
|
219
|
+
ticket: string;
|
|
220
|
+
/** RFC 3339 UTC. */
|
|
221
|
+
expires_at: string;
|
|
202
222
|
/**
|
|
203
|
-
*
|
|
204
|
-
*
|
|
223
|
+
* Leading zero bits the ticket's proof of work needs (1 to 22). Absent or 0
|
|
224
|
+
* when the SDK key does not ask for one.
|
|
205
225
|
*/
|
|
206
|
-
|
|
207
|
-
}
|
|
208
|
-
status: 'failed';
|
|
209
|
-
error: Error;
|
|
210
|
-
report?: SignalReport;
|
|
211
|
-
combinedReport?: SignalReport;
|
|
212
|
-
};
|
|
226
|
+
pow_bits?: number;
|
|
227
|
+
}
|
|
213
228
|
/**
|
|
214
|
-
* The answer.
|
|
215
|
-
*
|
|
216
|
-
* Note what is absent: there is no visitor identifier computed here, because
|
|
217
|
-
* the client does not compute one. Hashing components in the page would make
|
|
218
|
-
* the identity forgeable by the visitor and freeze the matching algorithm
|
|
219
|
-
* into whatever SDK version a customer deployed. Fingerly
|
|
220
|
-
* submits the raw report and lets the server decide who this is - and then
|
|
221
|
-
* tells you, in the same response.
|
|
229
|
+
* The server's v3 identification answer (`IdentifyOut`).
|
|
222
230
|
*/
|
|
223
231
|
interface IdentifyResult {
|
|
224
232
|
requestId: string;
|
|
225
233
|
/**
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
* submission was a [[duplicate]]. Otherwise always present: a report too thin
|
|
230
|
-
* to match anyone still gets an identifier, minted rather than matched, so
|
|
231
|
-
* that every event has a key.
|
|
234
|
+
* Stable project-scoped visitor identifier, or `""` whenever
|
|
235
|
+
* `identifiable === false`, the report came from a genuine embedded WebView,
|
|
236
|
+
* or an unmatched Web report is high-risk (Option B).
|
|
232
237
|
*/
|
|
233
238
|
visitorId: string;
|
|
234
|
-
/**
|
|
239
|
+
/**
|
|
240
|
+
* `true` only when a new visitor row was minted; always `false` when
|
|
241
|
+
* `visitorId === ""`.
|
|
242
|
+
*/
|
|
235
243
|
visitorIsNew: boolean;
|
|
236
244
|
/**
|
|
237
|
-
*
|
|
238
|
-
*
|
|
239
|
-
* 100 when this exact device has been seen before, 85-99 when it drifted -
|
|
240
|
-
* a browser update, a new monitor - and was recognised by similarity, and 0
|
|
241
|
-
* when the identifier was minted because nothing matched.
|
|
242
|
-
*
|
|
243
|
-
* Read this rather than inferring trust from [[identifiable]], which only
|
|
244
|
-
* says whether the report was rich enough to attempt a match.
|
|
245
|
+
* Match confidence from 0 to 100 (`0` when `visitorId === ""` or freshly minted).
|
|
245
246
|
*/
|
|
246
247
|
visitorConfidence: number;
|
|
247
248
|
/**
|
|
248
|
-
*
|
|
249
|
-
*
|
|
250
|
-
* A hardened browser produces this honestly; so does a client that would
|
|
251
|
-
* rather not be recognised. Either way the submission is still answered and
|
|
252
|
-
* still scored - more highly, because suppressing a fingerprint is itself
|
|
253
|
-
* evidence - and it is charged at a lower rate, because the address lookup
|
|
254
|
-
* happened and the identification did not.
|
|
249
|
+
* `false` when the report carried too little independent entropy to identify
|
|
250
|
+
* a device.
|
|
255
251
|
*/
|
|
256
252
|
identifiable: boolean;
|
|
257
253
|
/**
|
|
258
|
-
*
|
|
259
|
-
*
|
|
260
|
-
*
|
|
261
|
-
* The verdict belongs to that first submission and is not repeated, so the
|
|
262
|
-
* fields above are empty. Keep the first response, or fetch the event by
|
|
263
|
-
* [[requestId]]. Without this flag an empty visitor would read as "nobody
|
|
264
|
-
* could be identified", which is the opposite of what happened.
|
|
254
|
+
* `true` when this submission replayed a cached verdict under the same
|
|
255
|
+
* `Idempotency-Key`.
|
|
265
256
|
*/
|
|
266
|
-
duplicate
|
|
257
|
+
duplicate?: boolean;
|
|
267
258
|
/**
|
|
268
259
|
* `enriched`, or `unavailable` when the address could not be looked up.
|
|
269
|
-
*
|
|
270
|
-
* Why an `unavailable` submission went unscored describes the service's own
|
|
271
|
-
* infrastructure, which is nothing a visitor's page should be able to read,
|
|
272
|
-
* so it is not on this result. Your backend reads it as `reason` on the
|
|
273
|
-
* server-side event read (`GET /api/v1/events/{request_id}` with a secret
|
|
274
|
-
* key), by [[requestId]].
|
|
275
260
|
*/
|
|
276
261
|
state: string;
|
|
277
262
|
/**
|
|
278
|
-
*
|
|
279
|
-
*
|
|
280
|
-
*
|
|
281
|
-
* `null` when the submission was not scored, or when the SDK key hides the
|
|
282
|
-
* score from public callers: the page is not told which, and your backend
|
|
283
|
-
* still reads the score on the event. Either is a different answer from
|
|
284
|
-
* zero: an ordinary visitor scores zero. Anything computed as a share of your
|
|
285
|
-
* traffic divides by one of those populations, so collapsing them makes the
|
|
286
|
-
* number plausible and wrong.
|
|
287
|
-
*
|
|
288
|
-
* Not a percentage and not capped. Normalising it to 0-100 would discard the
|
|
289
|
-
* difference between "over the line" and "far over the line".
|
|
263
|
+
* Weighted sum of the signals that fired, or `null` when unscored or hidden
|
|
264
|
+
* by `hide_client_score` on public keys.
|
|
290
265
|
*/
|
|
291
266
|
suspectScore: number | null;
|
|
292
|
-
/** `low`, `medium
|
|
293
|
-
suspectLevel:
|
|
294
|
-
/**
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
interface IdentificationConfidence {
|
|
300
|
-
score: number;
|
|
301
|
-
version: string;
|
|
302
|
-
}
|
|
303
|
-
interface Identification {
|
|
304
|
-
visitor_id: string;
|
|
305
|
-
confidence: IdentificationConfidence;
|
|
306
|
-
visitor_found: boolean;
|
|
307
|
-
first_seen_at: number;
|
|
308
|
-
last_seen_at: number;
|
|
309
|
-
}
|
|
310
|
-
interface IpGeolocation {
|
|
311
|
-
accuracy_radius: number;
|
|
312
|
-
latitude: number;
|
|
313
|
-
longitude: number;
|
|
314
|
-
postal_code: string;
|
|
315
|
-
timezone: string;
|
|
316
|
-
city_name: string;
|
|
317
|
-
country_code: string;
|
|
318
|
-
country_name: string;
|
|
319
|
-
continent_code: string;
|
|
320
|
-
continent_name: string;
|
|
321
|
-
subdivisions: {
|
|
322
|
-
iso_code: string;
|
|
323
|
-
name: string;
|
|
324
|
-
}[];
|
|
325
|
-
}
|
|
326
|
-
interface IpInfoV4 {
|
|
327
|
-
address: string;
|
|
328
|
-
geolocation: IpGeolocation;
|
|
329
|
-
asn: string;
|
|
330
|
-
asn_name: string;
|
|
331
|
-
asn_network: string;
|
|
332
|
-
asn_type: string;
|
|
333
|
-
datacenter_result: boolean;
|
|
334
|
-
}
|
|
335
|
-
interface VelocityWindow {
|
|
336
|
-
'5_minutes': number;
|
|
337
|
-
'1_hour': number;
|
|
338
|
-
'24_hours': number;
|
|
339
|
-
}
|
|
340
|
-
interface Velocity {
|
|
341
|
-
distinct_ip: VelocityWindow;
|
|
342
|
-
distinct_country: VelocityWindow;
|
|
343
|
-
events: VelocityWindow;
|
|
344
|
-
ip_events: VelocityWindow;
|
|
345
|
-
}
|
|
346
|
-
/** Fields every platform reports. */
|
|
347
|
-
interface FingerlyEventBase {
|
|
348
|
-
event_id: string;
|
|
349
|
-
timestamp: number;
|
|
350
|
-
source: 'device';
|
|
351
|
-
sdk: {
|
|
352
|
-
platform: SdkPlatform;
|
|
353
|
-
version: string;
|
|
354
|
-
};
|
|
355
|
-
replayed: boolean;
|
|
356
|
-
identification: Identification;
|
|
357
|
-
ip_address: string;
|
|
358
|
-
ip_info: {
|
|
359
|
-
v4: IpInfoV4;
|
|
360
|
-
};
|
|
361
|
-
proxy: boolean;
|
|
362
|
-
proxy_confidence: Confidence;
|
|
363
|
-
vpn: boolean;
|
|
364
|
-
vpn_confidence: Confidence;
|
|
365
|
-
tampering: boolean;
|
|
366
|
-
tampering_confidence: Confidence;
|
|
367
|
-
suspect_score: number;
|
|
368
|
-
velocity: Velocity;
|
|
369
|
-
}
|
|
370
|
-
/**
|
|
371
|
-
* Signals only a native app can observe.
|
|
372
|
-
*
|
|
373
|
-
* Absent on web rather than `false`, because a browser cannot look for a root
|
|
374
|
-
* app and reporting "no" would be a claim nobody made.
|
|
375
|
-
*/
|
|
376
|
-
interface FingerlyMobileEvent extends FingerlyEventBase {
|
|
377
|
-
sdk: {
|
|
378
|
-
platform: 'android' | 'ios';
|
|
379
|
-
version: string;
|
|
380
|
-
};
|
|
381
|
-
package_name: string;
|
|
382
|
-
emulator: boolean;
|
|
383
|
-
root_apps: boolean;
|
|
384
|
-
cloned_app: boolean;
|
|
385
|
-
frida: boolean;
|
|
386
|
-
developer_tools: boolean;
|
|
387
|
-
factory_reset_timestamp?: number;
|
|
388
|
-
active_call: boolean;
|
|
389
|
-
}
|
|
390
|
-
interface FingerlyWebEvent extends FingerlyEventBase {
|
|
391
|
-
sdk: {
|
|
392
|
-
platform: 'web';
|
|
393
|
-
version: string;
|
|
394
|
-
};
|
|
395
|
-
browser_name: string;
|
|
396
|
-
browser_version: string;
|
|
397
|
-
incognito: boolean;
|
|
398
|
-
ad_blocker: boolean;
|
|
267
|
+
/** `low`, `medium`, or `high`; `null` whenever [[suspectScore]] is `null`. */
|
|
268
|
+
suspectLevel: SuspectLevel | null;
|
|
269
|
+
/**
|
|
270
|
+
* Active risk signals and weights (populated only for direct secret-key
|
|
271
|
+
* callers; omitted on public browser keys).
|
|
272
|
+
*/
|
|
273
|
+
triggers?: IdentifyTrigger[];
|
|
399
274
|
}
|
|
400
|
-
type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent;
|
|
401
275
|
|
|
402
|
-
export type {
|
|
276
|
+
export type { AbortSignalLike, CollectOptions, Confidence, ConsentState, EngineIdentity, FreshnessTicket, IdentifyOptions, IdentifyResult, IdentifySubmission, IdentifyTrigger, IncognitoDetection, IntegrityReport, Lie, LieKind, MobileFingerlyOptions, MobileIdentifyOptions, NativeIdentifyResult, RiskSignal, SdkPlatform, SignalOutcome, SignalReport, SignalStatus, SourceStage, SuspectLevel, TicketRequest };
|