@fingerly/types 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,14 +1,102 @@
1
- # @fingerly/types
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
- This package contains types only. Runtime collection, transport, and scoring
6
- belong to the platform SDKs.
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
- * The cross-platform values name the host as well as the toolkit, because the
11
- * server maps an SDK platform onto one of three scoring profiles by looking for
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 SdkPlatform = 'web' | 'android' | 'ios' | 'react-native-ios' | 'react-native-android' | 'flutter-ios' | 'flutter-android' | 'lynx-ios' | 'lynx-android';
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 and score without submitting when false. Defaults to true. */
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
- * A property of the visitor's privacy posture, and most of what
54
- * Tor and hardened-browser detection is made of.
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,46 +80,33 @@ 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 `audio-suspended` - never a stack trace, which is
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
- * When a source runs.
84
- *
85
- * `fast` sources are cheap and synchronous-ish, and every one of them must fit
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 SourceTier = 'fast' | 'deferred';
92
- /** A native function, descriptor or prototype that is not what it should be. */
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: 'not-native' | 'descriptor' | 'prototype' | 'contradiction' | 'missing';
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;
111
109
  observed?: string;
112
- /**
113
- * @deprecated Not sent since 0.1.1. The server compares [[claimed]] and
114
- * [[observed]] itself; kept so a report stored by an older SDK still types.
115
- */
116
- agrees?: boolean;
117
110
  }
118
111
  /** The tamper layer's findings. Raw; the server decides what they are worth. */
119
112
  interface IntegrityReport {
@@ -124,12 +117,7 @@ interface IntegrityReport {
124
117
  engine: EngineIdentity;
125
118
  }
126
119
  /**
127
- * The whole client-side observation, as submitted.
128
- *
129
- * This is what lands in `signals` on the wire. The server types that field as
130
- * `map[string]any` and deliberately does not interpret it (see
131
- * `server/services/identify.go`), so this interface is the only place the
132
- * shape is written down until the event store exists.
120
+ * The whole client-side observation, as submitted inside `signals`.
133
121
  */
134
122
  interface SignalReport {
135
123
  /** Bumped when a field changes meaning, never when one is added. */
@@ -138,277 +126,151 @@ interface SignalReport {
138
126
  budget_ms: number;
139
127
  /** What collection actually cost. */
140
128
  elapsed_ms: number;
141
- /** Which tiers ran. A fast-only report is not a degraded full one. */
142
- tiers: SourceTier[];
143
129
  sources: Record<string, SignalOutcome>;
144
130
  integrity: IntegrityReport;
145
131
  }
146
132
  /** How sure the server is of a finding. Matches its `*_confidence` fields. */
147
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
+ }
148
148
  /** What a native `identify()` resolves with. See [[IdentifyResult]]. */
149
149
  interface NativeIdentifyResult {
150
150
  requestId: string;
151
- /** Who this visitor is. See [[IdentifyResult.visitorId]]. */
151
+ /** Who this visitor is (`""` when `identifiable === false`). */
152
152
  visitorId: string;
153
153
  /** `null` when the server did not say, which is not the same as `false`. */
154
154
  visitorIsNew: boolean | null;
155
155
  /**
156
- * How sure the server is, 0 to 100. `null` when it did not say, which is not
157
- * the same as zero. See [[IdentifyResult.visitorConfidence]].
156
+ * How sure the server is, 0 to 100 (`0` when `visitorId === ""`). `null`
157
+ * when it did not say.
158
158
  */
159
159
  visitorConfidence: number | null;
160
160
  /** `null` when the server did not say. */
161
161
  identifiable: boolean | null;
162
162
  /**
163
- * True when this submission was answered before; the fields above are empty.
164
- * `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.
165
165
  */
166
166
  duplicate: boolean | null;
167
+ /** As [[IdentifyResult.state]]. */
167
168
  state: string;
168
- /**
169
- * @deprecated An app is no longer told why a submission went unscored, so
170
- * this is `undefined`. Read `reason` on the server-side event read. See
171
- * [[IdentifyResult.reason]].
172
- */
173
- reason?: string;
174
169
  /** `null` when absent: unscored, or hidden by the SDK key. Not the same as zero. */
175
170
  suspectScore: number | null;
176
171
  /** `null` when absent, for the same reasons as [[suspectScore]]. */
177
- suspectLevel: string | null;
172
+ suspectLevel: SuspectLevel | null;
178
173
  report: SignalReport;
179
174
  }
180
- /** A submission, as the body of `POST /api/v1/ingest`. */
175
+ /** A v3 submission, as the body of `POST /api/v1/ingest`. */
181
176
  interface IdentifySubmission {
177
+ /** Wire envelope version. Must equal `3`. */
178
+ v: 3;
182
179
  sdk: {
183
180
  platform: SdkPlatform;
184
181
  version: string;
185
182
  };
186
183
  /**
187
184
  * The SDK's consent state when it sent this. Always `granted`, since an SDK
188
- * sends nothing otherwise; the server refuses any other value with a 422
189
- * `consent_required`.
185
+ * sends nothing otherwise; the server refuses any other value with `consent_required`.
190
186
  */
191
187
  consent: ConsentState;
192
188
  signals: SignalReport;
193
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;
194
201
  }
195
- /** A deferred source report attached to an already completed identification. */
196
- interface DeferredSubmission {
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';
197
208
  sdk: {
198
- platform: SdkPlatform;
209
+ platform: 'web';
199
210
  version: string;
200
211
  };
201
- /** As on [[IdentifySubmission.consent]]. */
202
- consent: ConsentState;
203
- signals: SignalReport;
204
- token: string;
205
212
  }
206
- type DeferredIdentifyResult = {
207
- status: 'submitted';
208
- report: SignalReport;
209
- combinedReport: SignalReport;
210
- } | {
211
- status: 'skipped';
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;
212
222
  /**
213
- * `consent-withdrawn` when consent stopped being `granted` after the
214
- * first response and before the supplement was sent.
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.
215
225
  */
216
- reason: 'not-submitted' | 'explicit-tiers' | 'duplicate' | 'unsupported-transport' | 'consent-withdrawn';
217
- } | {
218
- status: 'failed';
219
- error: Error;
220
- report?: SignalReport;
221
- combinedReport?: SignalReport;
222
- };
226
+ pow_bits?: number;
227
+ }
223
228
  /**
224
- * The answer.
225
- *
226
- * Note what is absent: there is no visitor identifier computed here, because
227
- * the client does not compute one. Hashing components in the page would make
228
- * the identity forgeable by the visitor and freeze the matching algorithm
229
- * into whatever SDK version a customer deployed. Fingerly
230
- * submits the raw report and lets the server decide who this is - and then
231
- * tells you, in the same response.
229
+ * The server's v3 identification answer (`IdentifyOut`).
232
230
  */
233
231
  interface IdentifyResult {
234
232
  requestId: string;
235
233
  /**
236
- * Who this visitor is, stable across their visits.
237
- *
238
- * Empty only when nothing was submitted (`submit: false`) or when the
239
- * submission was a [[duplicate]]. Otherwise always present: a report too thin
240
- * to match anyone still gets an identifier, minted rather than matched, so
241
- * 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).
242
237
  */
243
238
  visitorId: string;
244
- /** Whether this is the first time the server has seen this visitor. */
239
+ /**
240
+ * `true` only when a new visitor row was minted; always `false` when
241
+ * `visitorId === ""`.
242
+ */
245
243
  visitorIsNew: boolean;
246
244
  /**
247
- * How sure the server is about [[visitorId]], from 0 to 100.
248
- *
249
- * 100 when this exact device has been seen before, 85-99 when it drifted -
250
- * a browser update, a new monitor - and was recognised by similarity, and 0
251
- * when the identifier was minted because nothing matched.
252
- *
253
- * Read this rather than inferring trust from [[identifiable]], which only
254
- * says whether the report was rich enough to attempt a match.
245
+ * Match confidence from 0 to 100 (`0` when `visitorId === ""` or freshly minted).
255
246
  */
256
247
  visitorConfidence: number;
257
248
  /**
258
- * False when the report carried too little to identify anyone.
259
- *
260
- * A hardened browser produces this honestly; so does a client that would
261
- * rather not be recognised. Either way the submission is still answered and
262
- * still scored - more highly, because suppressing a fingerprint is itself
263
- * evidence - and it is charged at a lower rate, because the address lookup
264
- * happened and the identification did not.
249
+ * `false` when the report carried too little independent entropy to identify
250
+ * a device.
265
251
  */
266
252
  identifiable: boolean;
267
253
  /**
268
- * True when this submission was answered before under the same idempotency
269
- * key.
270
- *
271
- * The verdict belongs to that first submission and is not repeated, so the
272
- * fields above are empty. Keep the first response, or fetch the event by
273
- * [[requestId]]. Without this flag an empty visitor would read as "nobody
274
- * 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`.
275
256
  */
276
- duplicate: boolean;
277
- /** `enriched`, or `unavailable` when the address could not be looked up. */
278
- state: string;
257
+ duplicate?: boolean;
279
258
  /**
280
- * @deprecated Browsers no longer receive this, so it is `undefined`.
281
- *
282
- * Why an `unavailable` submission went unscored describes the service's own
283
- * infrastructure, which is nothing a visitor's page should be able to read.
284
- * Your backend reads it as `reason` on the server-side event read (`GET
285
- * /api/v1/events/{request_id}` with a secret key), by [[requestId]]. Kept,
286
- * optional, so code written against 0.1.0 still compiles.
259
+ * `enriched`, or `unavailable` when the address could not be looked up.
287
260
  */
288
- reason?: string;
261
+ state: string;
289
262
  /**
290
- * The weighted sum of the signals that fired, under the weights in force when
291
- * this submission was scored.
292
- *
293
- * `null` when the submission was not scored, or when the SDK key hides the
294
- * score from public callers: the page is not told which, and your backend
295
- * still reads the score on the event. Either is a different answer from
296
- * zero: an ordinary visitor scores zero. Anything computed as a share of your
297
- * traffic divides by one of those populations, so collapsing them makes the
298
- * number plausible and wrong.
299
- *
300
- * Not a percentage and not capped. Normalising it to 0-100 would discard the
301
- * 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.
302
265
  */
303
266
  suspectScore: number | null;
304
- /** `low`, `medium` or `high`. `null` when absent, as [[suspectScore]]. */
305
- suspectLevel: string | null;
306
- /** The report that was sent, for debugging and for offline callers. */
307
- report: SignalReport;
308
- /** Completion of the non-authoritative second-tier collection and upload. */
309
- deferred: Promise<DeferredIdentifyResult>;
310
- }
311
- interface IdentificationConfidence {
312
- score: number;
313
- version: string;
314
- }
315
- interface Identification {
316
- visitor_id: string;
317
- confidence: IdentificationConfidence;
318
- visitor_found: boolean;
319
- first_seen_at: number;
320
- last_seen_at: number;
321
- }
322
- interface IpGeolocation {
323
- accuracy_radius: number;
324
- latitude: number;
325
- longitude: number;
326
- postal_code: string;
327
- timezone: string;
328
- city_name: string;
329
- country_code: string;
330
- country_name: string;
331
- continent_code: string;
332
- continent_name: string;
333
- subdivisions: {
334
- iso_code: string;
335
- name: string;
336
- }[];
337
- }
338
- interface IpInfoV4 {
339
- address: string;
340
- geolocation: IpGeolocation;
341
- asn: string;
342
- asn_name: string;
343
- asn_network: string;
344
- asn_type: string;
345
- datacenter_result: boolean;
346
- }
347
- interface VelocityWindow {
348
- '5_minutes': number;
349
- '1_hour': number;
350
- '24_hours': number;
351
- }
352
- interface Velocity {
353
- distinct_ip: VelocityWindow;
354
- distinct_country: VelocityWindow;
355
- events: VelocityWindow;
356
- ip_events: VelocityWindow;
357
- }
358
- /** Fields every platform reports. */
359
- interface FingerlyEventBase {
360
- event_id: string;
361
- timestamp: number;
362
- source: 'device';
363
- sdk: {
364
- platform: SdkPlatform;
365
- version: string;
366
- };
367
- replayed: boolean;
368
- identification: Identification;
369
- ip_address: string;
370
- ip_info: {
371
- v4: IpInfoV4;
372
- };
373
- proxy: boolean;
374
- proxy_confidence: Confidence;
375
- vpn: boolean;
376
- vpn_confidence: Confidence;
377
- tampering: boolean;
378
- tampering_confidence: Confidence;
379
- suspect_score: number;
380
- velocity: Velocity;
381
- }
382
- /**
383
- * Signals only a native app can observe.
384
- *
385
- * Absent on web rather than `false`, because a browser cannot look for a root
386
- * app and reporting "no" would be a claim nobody made.
387
- */
388
- interface FingerlyMobileEvent extends FingerlyEventBase {
389
- sdk: {
390
- platform: 'android' | 'ios';
391
- version: string;
392
- };
393
- package_name: string;
394
- emulator: boolean;
395
- root_apps: boolean;
396
- cloned_app: boolean;
397
- frida: boolean;
398
- developer_tools: boolean;
399
- factory_reset_timestamp?: number;
400
- active_call: boolean;
401
- }
402
- interface FingerlyWebEvent extends FingerlyEventBase {
403
- sdk: {
404
- platform: 'web';
405
- version: string;
406
- };
407
- browser_name: string;
408
- browser_version: string;
409
- incognito: boolean;
410
- 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[];
411
274
  }
412
- type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent;
413
275
 
414
- export type { Confidence, ConsentState, DeferredIdentifyResult, DeferredSubmission, EngineIdentity, FingerlyEvent, FingerlyEventBase, FingerlyMobileEvent, FingerlyWebEvent, Identification, IdentificationConfidence, IdentifyResult, IdentifySubmission, IntegrityReport, IpGeolocation, IpInfoV4, Lie, MobileFingerlyOptions, MobileIdentifyOptions, NativeIdentifyResult, SdkPlatform, SignalOutcome, SignalReport, SignalStatus, SourceTier, Velocity, VelocityWindow };
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
- * The cross-platform values name the host as well as the toolkit, because the
11
- * server maps an SDK platform onto one of three scoring profiles by looking for
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 SdkPlatform = 'web' | 'android' | 'ios' | 'react-native-ios' | 'react-native-android' | 'flutter-ios' | 'flutter-android' | 'lynx-ios' | 'lynx-android';
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 and score without submitting when false. Defaults to true. */
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
- * A property of the visitor's privacy posture, and most of what
54
- * Tor and hardened-browser detection is made of.
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,46 +80,33 @@ 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 `audio-suspended` - never a stack trace, which is
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
- * When a source runs.
84
- *
85
- * `fast` sources are cheap and synchronous-ish, and every one of them must fit
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 SourceTier = 'fast' | 'deferred';
92
- /** A native function, descriptor or prototype that is not what it should be. */
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: 'not-native' | 'descriptor' | 'prototype' | 'contradiction' | 'missing';
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;
111
109
  observed?: string;
112
- /**
113
- * @deprecated Not sent since 0.1.1. The server compares [[claimed]] and
114
- * [[observed]] itself; kept so a report stored by an older SDK still types.
115
- */
116
- agrees?: boolean;
117
110
  }
118
111
  /** The tamper layer's findings. Raw; the server decides what they are worth. */
119
112
  interface IntegrityReport {
@@ -124,12 +117,7 @@ interface IntegrityReport {
124
117
  engine: EngineIdentity;
125
118
  }
126
119
  /**
127
- * The whole client-side observation, as submitted.
128
- *
129
- * This is what lands in `signals` on the wire. The server types that field as
130
- * `map[string]any` and deliberately does not interpret it (see
131
- * `server/services/identify.go`), so this interface is the only place the
132
- * shape is written down until the event store exists.
120
+ * The whole client-side observation, as submitted inside `signals`.
133
121
  */
134
122
  interface SignalReport {
135
123
  /** Bumped when a field changes meaning, never when one is added. */
@@ -138,277 +126,151 @@ interface SignalReport {
138
126
  budget_ms: number;
139
127
  /** What collection actually cost. */
140
128
  elapsed_ms: number;
141
- /** Which tiers ran. A fast-only report is not a degraded full one. */
142
- tiers: SourceTier[];
143
129
  sources: Record<string, SignalOutcome>;
144
130
  integrity: IntegrityReport;
145
131
  }
146
132
  /** How sure the server is of a finding. Matches its `*_confidence` fields. */
147
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
+ }
148
148
  /** What a native `identify()` resolves with. See [[IdentifyResult]]. */
149
149
  interface NativeIdentifyResult {
150
150
  requestId: string;
151
- /** Who this visitor is. See [[IdentifyResult.visitorId]]. */
151
+ /** Who this visitor is (`""` when `identifiable === false`). */
152
152
  visitorId: string;
153
153
  /** `null` when the server did not say, which is not the same as `false`. */
154
154
  visitorIsNew: boolean | null;
155
155
  /**
156
- * How sure the server is, 0 to 100. `null` when it did not say, which is not
157
- * the same as zero. See [[IdentifyResult.visitorConfidence]].
156
+ * How sure the server is, 0 to 100 (`0` when `visitorId === ""`). `null`
157
+ * when it did not say.
158
158
  */
159
159
  visitorConfidence: number | null;
160
160
  /** `null` when the server did not say. */
161
161
  identifiable: boolean | null;
162
162
  /**
163
- * True when this submission was answered before; the fields above are empty.
164
- * `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.
165
165
  */
166
166
  duplicate: boolean | null;
167
+ /** As [[IdentifyResult.state]]. */
167
168
  state: string;
168
- /**
169
- * @deprecated An app is no longer told why a submission went unscored, so
170
- * this is `undefined`. Read `reason` on the server-side event read. See
171
- * [[IdentifyResult.reason]].
172
- */
173
- reason?: string;
174
169
  /** `null` when absent: unscored, or hidden by the SDK key. Not the same as zero. */
175
170
  suspectScore: number | null;
176
171
  /** `null` when absent, for the same reasons as [[suspectScore]]. */
177
- suspectLevel: string | null;
172
+ suspectLevel: SuspectLevel | null;
178
173
  report: SignalReport;
179
174
  }
180
- /** A submission, as the body of `POST /api/v1/ingest`. */
175
+ /** A v3 submission, as the body of `POST /api/v1/ingest`. */
181
176
  interface IdentifySubmission {
177
+ /** Wire envelope version. Must equal `3`. */
178
+ v: 3;
182
179
  sdk: {
183
180
  platform: SdkPlatform;
184
181
  version: string;
185
182
  };
186
183
  /**
187
184
  * The SDK's consent state when it sent this. Always `granted`, since an SDK
188
- * sends nothing otherwise; the server refuses any other value with a 422
189
- * `consent_required`.
185
+ * sends nothing otherwise; the server refuses any other value with `consent_required`.
190
186
  */
191
187
  consent: ConsentState;
192
188
  signals: SignalReport;
193
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;
194
201
  }
195
- /** A deferred source report attached to an already completed identification. */
196
- interface DeferredSubmission {
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';
197
208
  sdk: {
198
- platform: SdkPlatform;
209
+ platform: 'web';
199
210
  version: string;
200
211
  };
201
- /** As on [[IdentifySubmission.consent]]. */
202
- consent: ConsentState;
203
- signals: SignalReport;
204
- token: string;
205
212
  }
206
- type DeferredIdentifyResult = {
207
- status: 'submitted';
208
- report: SignalReport;
209
- combinedReport: SignalReport;
210
- } | {
211
- status: 'skipped';
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;
212
222
  /**
213
- * `consent-withdrawn` when consent stopped being `granted` after the
214
- * first response and before the supplement was sent.
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.
215
225
  */
216
- reason: 'not-submitted' | 'explicit-tiers' | 'duplicate' | 'unsupported-transport' | 'consent-withdrawn';
217
- } | {
218
- status: 'failed';
219
- error: Error;
220
- report?: SignalReport;
221
- combinedReport?: SignalReport;
222
- };
226
+ pow_bits?: number;
227
+ }
223
228
  /**
224
- * The answer.
225
- *
226
- * Note what is absent: there is no visitor identifier computed here, because
227
- * the client does not compute one. Hashing components in the page would make
228
- * the identity forgeable by the visitor and freeze the matching algorithm
229
- * into whatever SDK version a customer deployed. Fingerly
230
- * submits the raw report and lets the server decide who this is - and then
231
- * tells you, in the same response.
229
+ * The server's v3 identification answer (`IdentifyOut`).
232
230
  */
233
231
  interface IdentifyResult {
234
232
  requestId: string;
235
233
  /**
236
- * Who this visitor is, stable across their visits.
237
- *
238
- * Empty only when nothing was submitted (`submit: false`) or when the
239
- * submission was a [[duplicate]]. Otherwise always present: a report too thin
240
- * to match anyone still gets an identifier, minted rather than matched, so
241
- * 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).
242
237
  */
243
238
  visitorId: string;
244
- /** Whether this is the first time the server has seen this visitor. */
239
+ /**
240
+ * `true` only when a new visitor row was minted; always `false` when
241
+ * `visitorId === ""`.
242
+ */
245
243
  visitorIsNew: boolean;
246
244
  /**
247
- * How sure the server is about [[visitorId]], from 0 to 100.
248
- *
249
- * 100 when this exact device has been seen before, 85-99 when it drifted -
250
- * a browser update, a new monitor - and was recognised by similarity, and 0
251
- * when the identifier was minted because nothing matched.
252
- *
253
- * Read this rather than inferring trust from [[identifiable]], which only
254
- * says whether the report was rich enough to attempt a match.
245
+ * Match confidence from 0 to 100 (`0` when `visitorId === ""` or freshly minted).
255
246
  */
256
247
  visitorConfidence: number;
257
248
  /**
258
- * False when the report carried too little to identify anyone.
259
- *
260
- * A hardened browser produces this honestly; so does a client that would
261
- * rather not be recognised. Either way the submission is still answered and
262
- * still scored - more highly, because suppressing a fingerprint is itself
263
- * evidence - and it is charged at a lower rate, because the address lookup
264
- * happened and the identification did not.
249
+ * `false` when the report carried too little independent entropy to identify
250
+ * a device.
265
251
  */
266
252
  identifiable: boolean;
267
253
  /**
268
- * True when this submission was answered before under the same idempotency
269
- * key.
270
- *
271
- * The verdict belongs to that first submission and is not repeated, so the
272
- * fields above are empty. Keep the first response, or fetch the event by
273
- * [[requestId]]. Without this flag an empty visitor would read as "nobody
274
- * 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`.
275
256
  */
276
- duplicate: boolean;
277
- /** `enriched`, or `unavailable` when the address could not be looked up. */
278
- state: string;
257
+ duplicate?: boolean;
279
258
  /**
280
- * @deprecated Browsers no longer receive this, so it is `undefined`.
281
- *
282
- * Why an `unavailable` submission went unscored describes the service's own
283
- * infrastructure, which is nothing a visitor's page should be able to read.
284
- * Your backend reads it as `reason` on the server-side event read (`GET
285
- * /api/v1/events/{request_id}` with a secret key), by [[requestId]]. Kept,
286
- * optional, so code written against 0.1.0 still compiles.
259
+ * `enriched`, or `unavailable` when the address could not be looked up.
287
260
  */
288
- reason?: string;
261
+ state: string;
289
262
  /**
290
- * The weighted sum of the signals that fired, under the weights in force when
291
- * this submission was scored.
292
- *
293
- * `null` when the submission was not scored, or when the SDK key hides the
294
- * score from public callers: the page is not told which, and your backend
295
- * still reads the score on the event. Either is a different answer from
296
- * zero: an ordinary visitor scores zero. Anything computed as a share of your
297
- * traffic divides by one of those populations, so collapsing them makes the
298
- * number plausible and wrong.
299
- *
300
- * Not a percentage and not capped. Normalising it to 0-100 would discard the
301
- * 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.
302
265
  */
303
266
  suspectScore: number | null;
304
- /** `low`, `medium` or `high`. `null` when absent, as [[suspectScore]]. */
305
- suspectLevel: string | null;
306
- /** The report that was sent, for debugging and for offline callers. */
307
- report: SignalReport;
308
- /** Completion of the non-authoritative second-tier collection and upload. */
309
- deferred: Promise<DeferredIdentifyResult>;
310
- }
311
- interface IdentificationConfidence {
312
- score: number;
313
- version: string;
314
- }
315
- interface Identification {
316
- visitor_id: string;
317
- confidence: IdentificationConfidence;
318
- visitor_found: boolean;
319
- first_seen_at: number;
320
- last_seen_at: number;
321
- }
322
- interface IpGeolocation {
323
- accuracy_radius: number;
324
- latitude: number;
325
- longitude: number;
326
- postal_code: string;
327
- timezone: string;
328
- city_name: string;
329
- country_code: string;
330
- country_name: string;
331
- continent_code: string;
332
- continent_name: string;
333
- subdivisions: {
334
- iso_code: string;
335
- name: string;
336
- }[];
337
- }
338
- interface IpInfoV4 {
339
- address: string;
340
- geolocation: IpGeolocation;
341
- asn: string;
342
- asn_name: string;
343
- asn_network: string;
344
- asn_type: string;
345
- datacenter_result: boolean;
346
- }
347
- interface VelocityWindow {
348
- '5_minutes': number;
349
- '1_hour': number;
350
- '24_hours': number;
351
- }
352
- interface Velocity {
353
- distinct_ip: VelocityWindow;
354
- distinct_country: VelocityWindow;
355
- events: VelocityWindow;
356
- ip_events: VelocityWindow;
357
- }
358
- /** Fields every platform reports. */
359
- interface FingerlyEventBase {
360
- event_id: string;
361
- timestamp: number;
362
- source: 'device';
363
- sdk: {
364
- platform: SdkPlatform;
365
- version: string;
366
- };
367
- replayed: boolean;
368
- identification: Identification;
369
- ip_address: string;
370
- ip_info: {
371
- v4: IpInfoV4;
372
- };
373
- proxy: boolean;
374
- proxy_confidence: Confidence;
375
- vpn: boolean;
376
- vpn_confidence: Confidence;
377
- tampering: boolean;
378
- tampering_confidence: Confidence;
379
- suspect_score: number;
380
- velocity: Velocity;
381
- }
382
- /**
383
- * Signals only a native app can observe.
384
- *
385
- * Absent on web rather than `false`, because a browser cannot look for a root
386
- * app and reporting "no" would be a claim nobody made.
387
- */
388
- interface FingerlyMobileEvent extends FingerlyEventBase {
389
- sdk: {
390
- platform: 'android' | 'ios';
391
- version: string;
392
- };
393
- package_name: string;
394
- emulator: boolean;
395
- root_apps: boolean;
396
- cloned_app: boolean;
397
- frida: boolean;
398
- developer_tools: boolean;
399
- factory_reset_timestamp?: number;
400
- active_call: boolean;
401
- }
402
- interface FingerlyWebEvent extends FingerlyEventBase {
403
- sdk: {
404
- platform: 'web';
405
- version: string;
406
- };
407
- browser_name: string;
408
- browser_version: string;
409
- incognito: boolean;
410
- 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[];
411
274
  }
412
- type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent;
413
275
 
414
- export type { Confidence, ConsentState, DeferredIdentifyResult, DeferredSubmission, EngineIdentity, FingerlyEvent, FingerlyEventBase, FingerlyMobileEvent, FingerlyWebEvent, Identification, IdentificationConfidence, IdentifyResult, IdentifySubmission, IntegrityReport, IpGeolocation, IpInfoV4, Lie, MobileFingerlyOptions, MobileIdentifyOptions, NativeIdentifyResult, SdkPlatform, SignalOutcome, SignalReport, SignalStatus, SourceTier, Velocity, VelocityWindow };
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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fingerly/types",
3
- "version": "0.1.1",
3
+ "version": "0.3.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },