@fingerly/types 0.1.2 → 0.4.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/dist/index.d.ts CHANGED
@@ -4,17 +4,62 @@
4
4
  * Nothing here touches the DOM. A type that only a browser can populate still
5
5
  * belongs in this file, because the server and the mobile SDKs both need to
6
6
  * name it; what does not belong here is the code that reads a `window`.
7
+ *
8
+ * Every closed set of values is an `as const` object with a same-named type,
9
+ * so `result.suspectLevel === SuspectLevel.High` and
10
+ * `result.suspectLevel === 'high'` both type-check. A member is its value in
11
+ * PascalCase, word by word: `fingerprint_suppressed` is
12
+ * `Signal.FingerprintSuppressed`, `react-native-ios` is
13
+ * `SdkPlatform.ReactNativeIos`.
7
14
  */
8
15
  /** Which SDK collected a report. Mirrors `schemas.SDKInfo` on the server. */
16
+ declare const SdkPlatform: {
17
+ readonly Web: "web";
18
+ readonly Android: "android";
19
+ readonly Ios: "ios";
20
+ readonly ReactNativeIos: "react-native-ios";
21
+ readonly ReactNativeAndroid: "react-native-android";
22
+ readonly FlutterIos: "flutter-ios";
23
+ readonly FlutterAndroid: "flutter-android";
24
+ readonly LynxIos: "lynx-ios";
25
+ readonly LynxAndroid: "lynx-android";
26
+ };
27
+ /** One of the platforms in {@link SdkPlatform}. */
28
+ type SdkPlatform = (typeof SdkPlatform)[keyof typeof SdkPlatform];
9
29
  /**
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.
30
+ * Whether opt-in extended incognito probes (such as Chromium IndexedDB
31
+ * durability timing) execute alongside zero-write standard probes.
16
32
  */
17
- type SdkPlatform = 'web' | 'android' | 'ios' | 'react-native-ios' | 'react-native-android' | 'flutter-ios' | 'flutter-android' | 'lynx-ios' | 'lynx-android';
33
+ declare const IncognitoDetection: {
34
+ readonly Standard: "standard";
35
+ readonly Extended: "extended";
36
+ };
37
+ /** One of the modes in {@link IncognitoDetection}. */
38
+ type IncognitoDetection = (typeof IncognitoDetection)[keyof typeof IncognitoDetection];
39
+ /** Minimal runtime-agnostic `AbortSignal` contract (compiles under pure ES2020 without DOM). */
40
+ interface AbortSignalLike {
41
+ readonly aborted: boolean;
42
+ readonly reason?: unknown;
43
+ addEventListener(type: 'abort', listener: () => void, options?: {
44
+ once?: boolean;
45
+ }): void;
46
+ removeEventListener(type: 'abort', listener: () => void): void;
47
+ }
48
+ /** Options for offline signal collection (`collect()`). */
49
+ interface CollectOptions {
50
+ /** Cancels collection (`AbortSignal`). */
51
+ signal?: AbortSignalLike;
52
+ /**
53
+ * Controls whether opt-in extended incognito probes run (`'extended'`) or
54
+ * only standard zero-write probes run (`'standard'`). Defaults to `'standard'`.
55
+ */
56
+ incognitoDetection?: IncognitoDetection;
57
+ }
58
+ /** Options for single-pass identification (`identify()`). */
59
+ interface IdentifyOptions extends CollectOptions {
60
+ /** Echoed back on the finished event, for the caller's own correlation. */
61
+ tag?: string;
62
+ }
18
63
  /** Configuration shared by JavaScript-based native SDK facades. */
19
64
  interface MobileFingerlyOptions {
20
65
  /** The SDK key, from the dashboard. */
@@ -26,7 +71,7 @@ interface MobileFingerlyOptions {
26
71
  interface MobileIdentifyOptions {
27
72
  /** Echoed back on the finished event, for the caller's own correlation. */
28
73
  tag?: string;
29
- /** Collect and score without submitting when false. Defaults to true. */
74
+ /** Collect without submitting when false (native mobile bridges). Defaults to true. */
30
75
  submit?: boolean;
31
76
  }
32
77
  /**
@@ -35,36 +80,27 @@ interface MobileIdentifyOptions {
35
80
  * `pending` is the default: an SDK identifies nobody until it is told
36
81
  * `granted`. `pending` and `denied` mean the same thing to the SDK - run no
37
82
  * 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.
83
+ * error - and are kept apart only because a consent tool reports them apart.
41
84
  */
42
- type ConsentState = 'granted' | 'pending' | 'denied';
85
+ declare const ConsentState: {
86
+ readonly Granted: "granted";
87
+ readonly Pending: "pending";
88
+ readonly Denied: "denied";
89
+ };
90
+ /** One of the states in {@link ConsentState}. */
91
+ type ConsentState = (typeof ConsentState)[keyof typeof ConsentState];
43
92
  /**
44
93
  * How a source finished.
45
94
  *
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
95
  * - `ok` the source produced a value.
51
96
  * - `unsupported` the API is not present. A property of the device/browser.
52
97
  * - `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.
98
+ * - `timeout` the source overran its slice of the budget.
99
+ * - `error` the source threw for an unexpected reason.
58
100
  */
59
101
  type SignalStatus = 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
60
102
  /**
61
103
  * 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
104
  */
69
105
  interface SignalOutcome<T = unknown> {
70
106
  status: SignalStatus;
@@ -74,37 +110,29 @@ interface SignalOutcome<T = unknown> {
74
110
  value?: T;
75
111
  /**
76
112
  * 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.
113
+ * `SecurityError` or `rfp-canvas-prompt-avoided`.
79
114
  */
80
115
  reason?: string;
81
116
  }
82
117
  /**
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.
118
+ * Internal two-stage browser scheduler barrier:
119
+ * - `prerequisite` runs first (`engine` + Gecko RFP timer gate).
120
+ * - `collect` runs second with access to completed prerequisite outcomes.
90
121
  */
91
- type SourceTier = 'fast' | 'deferred';
92
- /** A native function, descriptor or prototype that is not what it should be. */
122
+ type SourceStage = 'prerequisite' | 'collect';
123
+ /** Kinds of runtime prototype, descriptor, brand, or native-code tampering. */
124
+ type LieKind = 'not-native' | 'descriptor' | 'prototype' | 'contradiction' | 'missing' | 'brand' | 'to-string-threw' | 'unverified_realm';
125
+ /** A native function, descriptor, brand, or prototype that is not what it should be. */
93
126
  interface Lie {
94
127
  /** Stable identifier, such as `navigator.hardwareConcurrency.getter`. */
95
128
  id: string;
96
129
  /** What kind of tampering was observed. */
97
- kind: 'not-native' | 'descriptor' | 'prototype' | 'contradiction' | 'missing';
130
+ kind: LieKind;
98
131
  /** Optional short detail. Kept stable across versions or left off. */
99
132
  detail?: string;
100
133
  }
101
134
  /**
102
135
  * 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
136
  */
109
137
  interface EngineIdentity {
110
138
  claimed?: string;
@@ -119,12 +147,7 @@ interface IntegrityReport {
119
147
  engine: EngineIdentity;
120
148
  }
121
149
  /**
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.
150
+ * The whole client-side observation, as submitted inside `signals`.
128
151
  */
129
152
  interface SignalReport {
130
153
  /** Bumped when a field changes meaning, never when one is added. */
@@ -133,270 +156,261 @@ interface SignalReport {
133
156
  budget_ms: number;
134
157
  /** What collection actually cost. */
135
158
  elapsed_ms: number;
136
- /** Which tiers ran. A fast-only report is not a degraded full one. */
137
- tiers: SourceTier[];
138
159
  sources: Record<string, SignalOutcome>;
139
160
  integrity: IntegrityReport;
140
161
  }
141
162
  /** How sure the server is of a finding. Matches its `*_confidence` fields. */
142
- type Confidence = 'low' | 'medium' | 'high';
163
+ declare const Confidence: {
164
+ readonly Low: "low";
165
+ readonly Medium: "medium";
166
+ readonly High: "high";
167
+ };
168
+ /** One of the grades in {@link Confidence}. */
169
+ type Confidence = (typeof Confidence)[keyof typeof Confidence];
170
+ /** Categorical risk band returned by the server. */
171
+ declare const SuspectLevel: {
172
+ readonly Low: "low";
173
+ readonly Medium: "medium";
174
+ readonly High: "high";
175
+ };
176
+ /** One of the levels in {@link SuspectLevel}. */
177
+ type SuspectLevel = (typeof SuspectLevel)[keyof typeof SuspectLevel];
178
+ /**
179
+ * Every signal group and raw detector identifier the server reports, the same
180
+ * list as `Signal` in `@fingerly/node`. A trigger's `signal` is a raw
181
+ * detector, such as `vpn_public`; its `group` is the group it is reported
182
+ * under, such as `vpn`.
183
+ */
184
+ declare const Signal: {
185
+ readonly Tor: "tor";
186
+ readonly DatacenterProxy: "datacenter_proxy";
187
+ readonly Proxy: "proxy";
188
+ readonly DatacenterIp: "datacenter_ip";
189
+ readonly ResidentialProxy: "residential_proxy";
190
+ readonly ResidentialProxyLowConfidence: "residential_proxy_low_confidence";
191
+ readonly ResidentialProxyMediumConfidence: "residential_proxy_medium_confidence";
192
+ readonly ResidentialProxyHighConfidence: "residential_proxy_high_confidence";
193
+ readonly Vpn: "vpn";
194
+ readonly VpnPublic: "vpn_public";
195
+ readonly VpnTimezone: "vpn_timezone";
196
+ readonly VpnRelay: "vpn_relay";
197
+ readonly VpnMobile: "vpn_mobile";
198
+ readonly VpnOsMismatch: "vpn_os_mismatch";
199
+ readonly VpnLowConfidence: "vpn_low_confidence";
200
+ readonly VpnMediumConfidence: "vpn_medium_confidence";
201
+ readonly VpnHighConfidence: "vpn_high_confidence";
202
+ readonly IpBlocklist: "ip_blocklist";
203
+ readonly IpBlocklistEmailSpam: "ip_blocklist_email_spam";
204
+ readonly IpBlocklistAttackSource: "ip_blocklist_attack_source";
205
+ readonly IpReputation: "ip_reputation";
206
+ readonly IpAbuser: "ip_abuser";
207
+ readonly NetworkAnomaly: "network_anomaly";
208
+ readonly BogonIp: "bogon_ip";
209
+ readonly AnycastIp: "anycast_ip";
210
+ readonly LocationSpoofing: "location_spoofing";
211
+ readonly GeoMismatch: "geo_mismatch";
212
+ readonly IosSimulator: "ios_simulator";
213
+ readonly Simulator: "simulator";
214
+ readonly AndroidEmulator: "android_emulator";
215
+ readonly Emulator: "emulator";
216
+ readonly VirtualMachine: "virtual_machine";
217
+ readonly JailbrokenDevice: "jailbroken_device";
218
+ readonly Jailbreak: "jailbreak";
219
+ readonly RootedDevice: "rooted_device";
220
+ readonly RootApps: "root_apps";
221
+ readonly PlayDeviceIntegrityFailed: "play_device_integrity_failed";
222
+ readonly ClonedApp: "cloned_app";
223
+ readonly AppCloner: "app_cloner";
224
+ readonly PlayAppUnrecognized: "play_app_unrecognized";
225
+ readonly DeviceFarm: "device_farm";
226
+ readonly RepeatedReinstall: "repeated_reinstall";
227
+ readonly DeviceActivityHigh: "device_activity_high";
228
+ readonly DeviceActivityVeryHigh: "device_activity_very_high";
229
+ readonly MitmAttack: "mitm_attack";
230
+ readonly FridaDetected: "frida_detected";
231
+ readonly Frida: "frida";
232
+ readonly BrowserTampering: "browser_tampering";
233
+ readonly Tampering: "tampering";
234
+ readonly AntidetectBrowser: "antidetect_browser";
235
+ readonly FingerprintSuppressed: "fingerprint_suppressed";
236
+ readonly DeveloperTools: "developer_tools";
237
+ readonly RemoteControl: "remote_control";
238
+ readonly Bot: "bot";
239
+ readonly Automation: "automation";
240
+ readonly BadBot: "bad_bot";
241
+ readonly FetchMetadataMissing: "fetch_metadata_missing";
242
+ readonly WebTicketMissing: "web_ticket_missing";
243
+ readonly WebTicketInvalid: "web_ticket_invalid";
244
+ readonly HighActivity: "high_activity";
245
+ readonly IncognitoMode: "incognito_mode";
246
+ readonly Incognito: "incognito";
247
+ readonly PrivacySettings: "privacy_settings";
248
+ readonly EmbeddedWebView: "embedded_web_view";
249
+ readonly ActiveCall: "active_call";
250
+ readonly AttestationMissing: "attestation_missing";
251
+ readonly AttestationFailed: "attestation_failed";
252
+ readonly AttestationDowngrade: "attestation_downgrade";
253
+ readonly DeviceInconsistent: "device_inconsistent";
254
+ readonly ReportIncomplete: "report_incomplete";
255
+ readonly ProbeErrors: "probe_errors";
256
+ readonly CustomRootCa: "custom_root_ca";
257
+ readonly SecondaryUserProfile: "secondary_user_profile";
258
+ };
259
+ /** One of the signals in {@link Signal}. */
260
+ type Signal = (typeof Signal)[keyof typeof Signal];
261
+ /**
262
+ * One of the signals in {@link Signal}, or a value a newer server added, so
263
+ * code built today still compiles against it.
264
+ */
265
+ type SignalName = Signal | (string & {});
266
+ /** The canonical v3 risk signal catalogue: the closed {@link Signal} list. */
267
+ type RiskSignal = Signal;
268
+ /**
269
+ * An identification's `state`, the same list as `EventState` in
270
+ * `@fingerly/node`: `Enriched` when it was fully processed, `Unavailable`
271
+ * when the network lookup could not run, so it was not scored. `Pending` is
272
+ * a server read's "not recorded yet"; an identify answer is never pending.
273
+ */
274
+ declare const EventState: {
275
+ readonly Pending: "pending";
276
+ readonly Enriched: "enriched";
277
+ readonly Unavailable: "unavailable";
278
+ };
279
+ /** One of the states in {@link EventState}. */
280
+ type EventState = (typeof EventState)[keyof typeof EventState];
281
+ /** One active risk trigger (`IdentifyTriggerOut` in OpenAPI). */
282
+ interface IdentifyTrigger {
283
+ signal: SignalName;
284
+ group?: SignalName;
285
+ weight?: number | null;
286
+ confidence?: Confidence | (string & {});
287
+ }
143
288
  /** What a native `identify()` resolves with. See [[IdentifyResult]]. */
144
289
  interface NativeIdentifyResult {
145
290
  requestId: string;
146
- /** Who this visitor is. See [[IdentifyResult.visitorId]]. */
291
+ /** Who this visitor is (`""` when `identifiable === false`). */
147
292
  visitorId: string;
148
293
  /** `null` when the server did not say, which is not the same as `false`. */
149
294
  visitorIsNew: boolean | null;
150
295
  /**
151
- * How sure the server is, 0 to 100. `null` when it did not say, which is not
152
- * the same as zero. See [[IdentifyResult.visitorConfidence]].
296
+ * How sure the server is, 0 to 100 (`0` when `visitorId === ""`). `null`
297
+ * when it did not say.
153
298
  */
154
299
  visitorConfidence: number | null;
155
300
  /** `null` when the server did not say. */
156
301
  identifiable: boolean | null;
157
302
  /**
158
- * True when this submission was answered before; the fields above are empty.
159
- * `null` when the server did not say.
303
+ * True when this submission was answered before under the same idempotency
304
+ * key and the stored verdict was replayed. `null` when the server did not say.
160
305
  */
161
306
  duplicate: boolean | null;
162
307
  /** As [[IdentifyResult.state]]. */
163
- state: string;
308
+ state: EventState | (string & {});
164
309
  /** `null` when absent: unscored, or hidden by the SDK key. Not the same as zero. */
165
310
  suspectScore: number | null;
166
311
  /** `null` when absent, for the same reasons as [[suspectScore]]. */
167
- suspectLevel: string | null;
312
+ suspectLevel: SuspectLevel | null;
168
313
  report: SignalReport;
169
314
  }
170
- /** A submission, as the body of `POST /api/v1/ingest`. */
315
+ /** A v3 submission, as the body of `POST /api/v1/ingest`. */
171
316
  interface IdentifySubmission {
317
+ /** Wire envelope version. Must equal `3`. */
318
+ v: 3;
172
319
  sdk: {
173
320
  platform: SdkPlatform;
174
321
  version: string;
175
322
  };
176
323
  /**
177
324
  * 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 a 422
179
- * `consent_required`.
325
+ * sends nothing otherwise; the server refuses any other value with `consent_required`.
180
326
  */
181
327
  consent: ConsentState;
182
328
  signals: SignalReport;
183
329
  tag?: string;
330
+ /**
331
+ * A single-use freshness ticket the server issued to this page (web only).
332
+ * Omitted when none could be fetched; the server then scores
333
+ * `web_ticket_missing` and still answers.
334
+ */
335
+ ticket?: string;
336
+ /**
337
+ * The proof of work for `ticket`, as a decimal nonce, when the ticket asked
338
+ * for one (`pow_bits` above 0) and it was solved within the budget.
339
+ */
340
+ ticket_pow?: string;
184
341
  }
185
- /** A deferred source report attached to an already completed identification. */
186
- interface DeferredSubmission {
342
+ /**
343
+ * The body of a web ticket request, posted to the same path as a report.
344
+ */
345
+ interface TicketRequest {
346
+ v: 3;
347
+ op: 'ticket';
187
348
  sdk: {
188
- platform: SdkPlatform;
349
+ platform: 'web';
189
350
  version: string;
190
351
  };
191
- /** As on [[IdentifySubmission.consent]]. */
192
- consent: ConsentState;
193
- signals: SignalReport;
194
- token: string;
195
352
  }
196
- type DeferredIdentifyResult = {
197
- status: 'submitted';
198
- report: SignalReport;
199
- combinedReport: SignalReport;
200
- } | {
201
- status: 'skipped';
353
+ /**
354
+ * A single-use web freshness ticket: the answer to a ticket request, and the
355
+ * `next_ticket` of a web identification answer.
356
+ */
357
+ interface FreshnessTicket {
358
+ /** Unpadded base64url. Opaque to the SDK. */
359
+ ticket: string;
360
+ /** RFC 3339 UTC. */
361
+ expires_at: string;
202
362
  /**
203
- * `consent-withdrawn` when consent stopped being `granted` after the
204
- * first response and before the supplement was sent.
363
+ * Leading zero bits the ticket's proof of work needs (1 to 22). Absent or 0
364
+ * when the SDK key does not ask for one.
205
365
  */
206
- reason: 'not-submitted' | 'explicit-tiers' | 'duplicate' | 'unsupported-transport' | 'consent-withdrawn';
207
- } | {
208
- status: 'failed';
209
- error: Error;
210
- report?: SignalReport;
211
- combinedReport?: SignalReport;
212
- };
366
+ pow_bits?: number;
367
+ }
213
368
  /**
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.
369
+ * The server's v3 identification answer (`IdentifyOut`).
222
370
  */
223
371
  interface IdentifyResult {
224
372
  requestId: string;
225
373
  /**
226
- * Who this visitor is, stable across their visits.
227
- *
228
- * Empty only when nothing was submitted (`submit: false`) or when the
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.
374
+ * Stable project-scoped visitor identifier, or `""` whenever
375
+ * `identifiable === false`, the report came from a genuine embedded WebView,
376
+ * or an unmatched Web report is high-risk (Option B).
232
377
  */
233
378
  visitorId: string;
234
- /** Whether this is the first time the server has seen this visitor. */
379
+ /**
380
+ * `true` only when a new visitor row was minted; always `false` when
381
+ * `visitorId === ""`.
382
+ */
235
383
  visitorIsNew: boolean;
236
384
  /**
237
- * How sure the server is about [[visitorId]], from 0 to 100.
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.
385
+ * Match confidence from 0 to 100 (`0` when `visitorId === ""` or freshly minted).
245
386
  */
246
387
  visitorConfidence: number;
247
388
  /**
248
- * False when the report carried too little to identify anyone.
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.
389
+ * `false` when the report carried too little independent entropy to identify
390
+ * a device.
255
391
  */
256
392
  identifiable: boolean;
257
393
  /**
258
- * True when this submission was answered before under the same idempotency
259
- * key.
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.
394
+ * `true` when this submission replayed a cached verdict under the same
395
+ * `Idempotency-Key`.
265
396
  */
266
- duplicate: boolean;
397
+ duplicate?: boolean;
267
398
  /**
268
399
  * `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
400
  */
276
- state: string;
401
+ state: EventState | (string & {});
277
402
  /**
278
- * The weighted sum of the signals that fired, under the weights in force when
279
- * this submission was scored.
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".
403
+ * Weighted sum of the signals that fired, or `null` when unscored or hidden
404
+ * by `hide_client_score` on public keys.
290
405
  */
291
406
  suspectScore: number | null;
292
- /** `low`, `medium` or `high`. `null` when absent, as [[suspectScore]]. */
293
- suspectLevel: string | null;
294
- /** The report that was sent, for debugging and for offline callers. */
295
- report: SignalReport;
296
- /** Completion of the non-authoritative second-tier collection and upload. */
297
- deferred: Promise<DeferredIdentifyResult>;
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;
407
+ /** `low`, `medium`, or `high`; `null` whenever [[suspectScore]] is `null`. */
408
+ suspectLevel: SuspectLevel | null;
409
+ /**
410
+ * Active risk signals and weights (populated only for direct secret-key
411
+ * callers; omitted on public browser keys).
412
+ */
413
+ triggers?: IdentifyTrigger[];
399
414
  }
400
- type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent;
401
415
 
402
- 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 };
416
+ export { type AbortSignalLike, type CollectOptions, Confidence, ConsentState, type EngineIdentity, EventState, type FreshnessTicket, type IdentifyOptions, type IdentifyResult, type IdentifySubmission, type IdentifyTrigger, IncognitoDetection, type IntegrityReport, type Lie, type LieKind, type MobileFingerlyOptions, type MobileIdentifyOptions, type NativeIdentifyResult, type RiskSignal, SdkPlatform, Signal, type SignalName, type SignalOutcome, type SignalReport, type SignalStatus, type SourceStage, SuspectLevel, type TicketRequest };