@fingerly/types 0.1.0 → 0.1.2
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.cts +35 -157
- package/dist/index.d.ts +35 -157
- package/package.json +13 -8
- package/src/index.ts +0 -572
package/dist/index.d.cts
CHANGED
|
@@ -109,7 +109,6 @@ interface Lie {
|
|
|
109
109
|
interface EngineIdentity {
|
|
110
110
|
claimed?: string;
|
|
111
111
|
observed?: string;
|
|
112
|
-
agrees?: boolean;
|
|
113
112
|
}
|
|
114
113
|
/** The tamper layer's findings. Raw; the server decides what they are worth. */
|
|
115
114
|
interface IntegrityReport {
|
|
@@ -139,141 +138,33 @@ interface SignalReport {
|
|
|
139
138
|
sources: Record<string, SignalOutcome>;
|
|
140
139
|
integrity: IntegrityReport;
|
|
141
140
|
}
|
|
142
|
-
/** How sure
|
|
141
|
+
/** How sure the server is of a finding. Matches its `*_confidence` fields. */
|
|
143
142
|
type Confidence = 'low' | 'medium' | 'high';
|
|
144
|
-
/**
|
|
145
|
-
* One detector's answer.
|
|
146
|
-
*
|
|
147
|
-
* `reasons` is the point of this type. A boolean that cannot say why it is
|
|
148
|
-
* true is not reviewable, and every one of these verdicts will eventually be
|
|
149
|
-
* argued with by a customer looking at a blocked user.
|
|
150
|
-
*/
|
|
151
|
-
interface Verdict {
|
|
152
|
-
value: boolean;
|
|
153
|
-
confidence: Confidence;
|
|
154
|
-
reasons: string[];
|
|
155
|
-
}
|
|
156
|
-
/**
|
|
157
|
-
* The verdicts the client can reach on its own.
|
|
158
|
-
*
|
|
159
|
-
* These are computed in the page for the caller's convenience - a login form
|
|
160
|
-
* that wants to step up to MFA should not have to wait for enrichment. They
|
|
161
|
-
* are *not* authoritative: the same functions run again on the server, over
|
|
162
|
-
* the stored report, with rules that can improve without an SDK release. A
|
|
163
|
-
* client-side verdict is advice; the server's is the answer.
|
|
164
|
-
*/
|
|
165
|
-
interface Verdicts {
|
|
166
|
-
incognito: Verdict;
|
|
167
|
-
/**
|
|
168
|
-
* Anti-fingerprinting countermeasures are rewriting this report's values.
|
|
169
|
-
*
|
|
170
|
-
* The one verdict here that is never a reason to challenge anyone. It says
|
|
171
|
-
* which of the other numbers are fabricated - Brave's farbling, Tor's RFP, an
|
|
172
|
-
* anti-detect build - so the detectors above it can decline to reason from
|
|
173
|
-
* them and the identity hash can decline to include them. A customer acting
|
|
174
|
-
* on this one is acting on "uses a privacy browser", which is not a finding.
|
|
175
|
-
*/
|
|
176
|
-
shields: Verdict;
|
|
177
|
-
tor: Verdict;
|
|
178
|
-
emulator: Verdict;
|
|
179
|
-
automation: Verdict;
|
|
180
|
-
/**
|
|
181
|
-
* Device farms are fundamentally a server-side finding - N identical devices
|
|
182
|
-
* behind one ASN - so this verdict only reports the client-observable half:
|
|
183
|
-
* a device that looks mass-provisioned or reset-fresh.
|
|
184
|
-
*/
|
|
185
|
-
farm: Verdict;
|
|
186
|
-
}
|
|
187
|
-
/**
|
|
188
|
-
* The verdicts a native application can reach, on either platform.
|
|
189
|
-
*
|
|
190
|
-
* Separate from [[Verdicts]] rather than an extension of it, because the two
|
|
191
|
-
* sets barely overlap. A page approximates `emulator` from a software renderer
|
|
192
|
-
* and a suspicious pixel ratio; an app reads `SIMULATOR_ROOT` out of its own
|
|
193
|
-
* environment and knows. A browser cannot look for an injected library at all.
|
|
194
|
-
* Folding them into one interface would mean every field optional, which would
|
|
195
|
-
* make "this platform cannot answer that" and "that answer was false" the same
|
|
196
|
-
* value — the distinction the whole `SignalStatus` design exists to preserve.
|
|
197
|
-
*/
|
|
198
|
-
interface NativeVerdicts {
|
|
199
|
-
/** Frida, Substrate, Substitute, ElleKit — anything rewriting the process. */
|
|
200
|
-
instrumentation: Verdict;
|
|
201
|
-
/** Something intercepting the app's own TLS. */
|
|
202
|
-
mitm: Verdict;
|
|
203
|
-
/** A debugger or a UI-test runner driving the process. */
|
|
204
|
-
automation: Verdict;
|
|
205
|
-
/** Hooked functions, injected images, a signature that is not the app's. */
|
|
206
|
-
tampering: Verdict;
|
|
207
|
-
/**
|
|
208
|
-
* A device that looks mass-provisioned or reset-fresh.
|
|
209
|
-
*
|
|
210
|
-
* The half one device can see about itself: no passcode, no biometry
|
|
211
|
-
* enrolled, every setting at its factory default, an empty disk. The
|
|
212
|
-
* conclusive half — N identical devices behind one address — is the server's.
|
|
213
|
-
*/
|
|
214
|
-
farm: Verdict;
|
|
215
|
-
}
|
|
216
|
-
/** What an iOS device can be asked. */
|
|
217
|
-
interface IosVerdicts extends NativeVerdicts {
|
|
218
|
-
jailbreak: Verdict;
|
|
219
|
-
simulator: Verdict;
|
|
220
|
-
}
|
|
221
|
-
/** What an Android device can be asked. */
|
|
222
|
-
interface AndroidVerdicts extends NativeVerdicts {
|
|
223
|
-
root: Verdict;
|
|
224
|
-
emulator: Verdict;
|
|
225
|
-
/** An app running under a cloning framework — one device, a hundred accounts. */
|
|
226
|
-
appCloner: Verdict;
|
|
227
|
-
}
|
|
228
|
-
/**
|
|
229
|
-
* Both platforms' verdicts in one shape, as the cross-platform SDKs return them.
|
|
230
|
-
*
|
|
231
|
-
* Not `IosVerdicts | AndroidVerdicts`. The union is more honest about the
|
|
232
|
-
* difference and it makes every call site narrow on the platform before it can
|
|
233
|
-
* read a field — which is the wrong trade for a binding whose entire purpose is
|
|
234
|
-
* writing the check once. `if (verdicts.jailbreak.value)` in code that runs on
|
|
235
|
-
* both platforms is the normal case, not the exception.
|
|
236
|
-
*
|
|
237
|
-
* The distinction is not lost, only moved. A member the platform cannot answer
|
|
238
|
-
* comes back as `{ value: false, confidence: 'low', reasons: [] }` — an empty
|
|
239
|
-
* `reasons` beside a false is what "this could not be asked" looks like, and it
|
|
240
|
-
* is the same convention `unknown()` uses in every detector in this codebase. A
|
|
241
|
-
* caller that needs to tell "we looked and found nothing" from "there was
|
|
242
|
-
* nothing to look at" reads `reasons.length`.
|
|
243
|
-
*
|
|
244
|
-
* The narrow types above remain, for a caller that has already established
|
|
245
|
-
* which platform it is on and wants the compiler to know.
|
|
246
|
-
*/
|
|
247
|
-
interface MobileVerdicts extends NativeVerdicts {
|
|
248
|
-
/** iOS. Unknown on Android. */
|
|
249
|
-
jailbreak: Verdict;
|
|
250
|
-
/** iOS. Unknown on Android. */
|
|
251
|
-
simulator: Verdict;
|
|
252
|
-
/** Android. Unknown on iOS. */
|
|
253
|
-
root: Verdict;
|
|
254
|
-
/** Android. Unknown on iOS. */
|
|
255
|
-
emulator: Verdict;
|
|
256
|
-
/** Android. Unknown on iOS. */
|
|
257
|
-
appCloner: Verdict;
|
|
258
|
-
}
|
|
259
143
|
/** What a native `identify()` resolves with. See [[IdentifyResult]]. */
|
|
260
144
|
interface NativeIdentifyResult {
|
|
261
145
|
requestId: string;
|
|
262
146
|
/** Who this visitor is. See [[IdentifyResult.visitorId]]. */
|
|
263
147
|
visitorId: string;
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
148
|
+
/** `null` when the server did not say, which is not the same as `false`. */
|
|
149
|
+
visitorIsNew: boolean | null;
|
|
150
|
+
/**
|
|
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]].
|
|
153
|
+
*/
|
|
154
|
+
visitorConfidence: number | null;
|
|
155
|
+
/** `null` when the server did not say. */
|
|
156
|
+
identifiable: boolean | null;
|
|
157
|
+
/**
|
|
158
|
+
* True when this submission was answered before; the fields above are empty.
|
|
159
|
+
* `null` when the server did not say.
|
|
160
|
+
*/
|
|
161
|
+
duplicate: boolean | null;
|
|
162
|
+
/** As [[IdentifyResult.state]]. */
|
|
270
163
|
state: string;
|
|
271
|
-
|
|
272
|
-
/** `null` when the submission was not scored, which is not the same as zero. */
|
|
164
|
+
/** `null` when absent: unscored, or hidden by the SDK key. Not the same as zero. */
|
|
273
165
|
suspectScore: number | null;
|
|
166
|
+
/** `null` when absent, for the same reasons as [[suspectScore]]. */
|
|
274
167
|
suspectLevel: string | null;
|
|
275
|
-
triggers: IdentifyTrigger[];
|
|
276
|
-
verdicts: MobileVerdicts;
|
|
277
168
|
report: SignalReport;
|
|
278
169
|
}
|
|
279
170
|
/** A submission, as the body of `POST /api/v1/ingest`. */
|
|
@@ -306,7 +197,6 @@ type DeferredIdentifyResult = {
|
|
|
306
197
|
status: 'submitted';
|
|
307
198
|
report: SignalReport;
|
|
308
199
|
combinedReport: SignalReport;
|
|
309
|
-
verdicts: Verdicts;
|
|
310
200
|
} | {
|
|
311
201
|
status: 'skipped';
|
|
312
202
|
/**
|
|
@@ -319,7 +209,6 @@ type DeferredIdentifyResult = {
|
|
|
319
209
|
error: Error;
|
|
320
210
|
report?: SignalReport;
|
|
321
211
|
combinedReport?: SignalReport;
|
|
322
|
-
verdicts?: Verdicts;
|
|
323
212
|
};
|
|
324
213
|
/**
|
|
325
214
|
* The answer.
|
|
@@ -375,49 +264,38 @@ interface IdentifyResult {
|
|
|
375
264
|
* could be identified", which is the opposite of what happened.
|
|
376
265
|
*/
|
|
377
266
|
duplicate: boolean;
|
|
378
|
-
/**
|
|
267
|
+
/**
|
|
268
|
+
* `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
|
+
*/
|
|
379
276
|
state: string;
|
|
380
|
-
/** Why enrichment did not happen, as a short stable token. Empty otherwise. */
|
|
381
|
-
reason: string;
|
|
382
277
|
/**
|
|
383
278
|
* The weighted sum of the signals that fired, under the weights in force when
|
|
384
279
|
* this submission was scored.
|
|
385
280
|
*
|
|
386
|
-
* `null` when the submission was not scored,
|
|
387
|
-
*
|
|
388
|
-
*
|
|
389
|
-
*
|
|
390
|
-
*
|
|
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.
|
|
391
287
|
*
|
|
392
288
|
* Not a percentage and not capped. Normalising it to 0-100 would discard the
|
|
393
289
|
* difference between "over the line" and "far over the line".
|
|
394
290
|
*/
|
|
395
291
|
suspectScore: number | null;
|
|
396
|
-
/** `low`, `medium` or `high`. `null`
|
|
292
|
+
/** `low`, `medium` or `high`. `null` when absent, as [[suspectScore]]. */
|
|
397
293
|
suspectLevel: string | null;
|
|
398
|
-
/** What fired, and what each was worth. */
|
|
399
|
-
triggers: IdentifyTrigger[];
|
|
400
|
-
/** The local verdicts, available before the round trip. Advisory; see [[Verdicts]]. */
|
|
401
|
-
verdicts: Verdicts;
|
|
402
294
|
/** The report that was sent, for debugging and for offline callers. */
|
|
403
295
|
report: SignalReport;
|
|
404
296
|
/** Completion of the non-authoritative second-tier collection and upload. */
|
|
405
297
|
deferred: Promise<DeferredIdentifyResult>;
|
|
406
298
|
}
|
|
407
|
-
/** One signal that fired on the server, and what it contributed. */
|
|
408
|
-
interface IdentifyTrigger {
|
|
409
|
-
signal: string;
|
|
410
|
-
/** The card this signal is reported under, such as `vpn` for `vpn_public`. */
|
|
411
|
-
group: string;
|
|
412
|
-
/**
|
|
413
|
-
* The weight as it was applied, under the profile in force at the time. A
|
|
414
|
-
* customer who lowers a weight has not changed what last week scored.
|
|
415
|
-
*/
|
|
416
|
-
weight: number;
|
|
417
|
-
confidence: string;
|
|
418
|
-
/** The tell that fired it, such as `known-tor-exit`. */
|
|
419
|
-
reason: string;
|
|
420
|
-
}
|
|
421
299
|
interface IdentificationConfidence {
|
|
422
300
|
score: number;
|
|
423
301
|
version: string;
|
|
@@ -521,4 +399,4 @@ interface FingerlyWebEvent extends FingerlyEventBase {
|
|
|
521
399
|
}
|
|
522
400
|
type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent;
|
|
523
401
|
|
|
524
|
-
export type {
|
|
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -109,7 +109,6 @@ interface Lie {
|
|
|
109
109
|
interface EngineIdentity {
|
|
110
110
|
claimed?: string;
|
|
111
111
|
observed?: string;
|
|
112
|
-
agrees?: boolean;
|
|
113
112
|
}
|
|
114
113
|
/** The tamper layer's findings. Raw; the server decides what they are worth. */
|
|
115
114
|
interface IntegrityReport {
|
|
@@ -139,141 +138,33 @@ interface SignalReport {
|
|
|
139
138
|
sources: Record<string, SignalOutcome>;
|
|
140
139
|
integrity: IntegrityReport;
|
|
141
140
|
}
|
|
142
|
-
/** How sure
|
|
141
|
+
/** How sure the server is of a finding. Matches its `*_confidence` fields. */
|
|
143
142
|
type Confidence = 'low' | 'medium' | 'high';
|
|
144
|
-
/**
|
|
145
|
-
* One detector's answer.
|
|
146
|
-
*
|
|
147
|
-
* `reasons` is the point of this type. A boolean that cannot say why it is
|
|
148
|
-
* true is not reviewable, and every one of these verdicts will eventually be
|
|
149
|
-
* argued with by a customer looking at a blocked user.
|
|
150
|
-
*/
|
|
151
|
-
interface Verdict {
|
|
152
|
-
value: boolean;
|
|
153
|
-
confidence: Confidence;
|
|
154
|
-
reasons: string[];
|
|
155
|
-
}
|
|
156
|
-
/**
|
|
157
|
-
* The verdicts the client can reach on its own.
|
|
158
|
-
*
|
|
159
|
-
* These are computed in the page for the caller's convenience - a login form
|
|
160
|
-
* that wants to step up to MFA should not have to wait for enrichment. They
|
|
161
|
-
* are *not* authoritative: the same functions run again on the server, over
|
|
162
|
-
* the stored report, with rules that can improve without an SDK release. A
|
|
163
|
-
* client-side verdict is advice; the server's is the answer.
|
|
164
|
-
*/
|
|
165
|
-
interface Verdicts {
|
|
166
|
-
incognito: Verdict;
|
|
167
|
-
/**
|
|
168
|
-
* Anti-fingerprinting countermeasures are rewriting this report's values.
|
|
169
|
-
*
|
|
170
|
-
* The one verdict here that is never a reason to challenge anyone. It says
|
|
171
|
-
* which of the other numbers are fabricated - Brave's farbling, Tor's RFP, an
|
|
172
|
-
* anti-detect build - so the detectors above it can decline to reason from
|
|
173
|
-
* them and the identity hash can decline to include them. A customer acting
|
|
174
|
-
* on this one is acting on "uses a privacy browser", which is not a finding.
|
|
175
|
-
*/
|
|
176
|
-
shields: Verdict;
|
|
177
|
-
tor: Verdict;
|
|
178
|
-
emulator: Verdict;
|
|
179
|
-
automation: Verdict;
|
|
180
|
-
/**
|
|
181
|
-
* Device farms are fundamentally a server-side finding - N identical devices
|
|
182
|
-
* behind one ASN - so this verdict only reports the client-observable half:
|
|
183
|
-
* a device that looks mass-provisioned or reset-fresh.
|
|
184
|
-
*/
|
|
185
|
-
farm: Verdict;
|
|
186
|
-
}
|
|
187
|
-
/**
|
|
188
|
-
* The verdicts a native application can reach, on either platform.
|
|
189
|
-
*
|
|
190
|
-
* Separate from [[Verdicts]] rather than an extension of it, because the two
|
|
191
|
-
* sets barely overlap. A page approximates `emulator` from a software renderer
|
|
192
|
-
* and a suspicious pixel ratio; an app reads `SIMULATOR_ROOT` out of its own
|
|
193
|
-
* environment and knows. A browser cannot look for an injected library at all.
|
|
194
|
-
* Folding them into one interface would mean every field optional, which would
|
|
195
|
-
* make "this platform cannot answer that" and "that answer was false" the same
|
|
196
|
-
* value — the distinction the whole `SignalStatus` design exists to preserve.
|
|
197
|
-
*/
|
|
198
|
-
interface NativeVerdicts {
|
|
199
|
-
/** Frida, Substrate, Substitute, ElleKit — anything rewriting the process. */
|
|
200
|
-
instrumentation: Verdict;
|
|
201
|
-
/** Something intercepting the app's own TLS. */
|
|
202
|
-
mitm: Verdict;
|
|
203
|
-
/** A debugger or a UI-test runner driving the process. */
|
|
204
|
-
automation: Verdict;
|
|
205
|
-
/** Hooked functions, injected images, a signature that is not the app's. */
|
|
206
|
-
tampering: Verdict;
|
|
207
|
-
/**
|
|
208
|
-
* A device that looks mass-provisioned or reset-fresh.
|
|
209
|
-
*
|
|
210
|
-
* The half one device can see about itself: no passcode, no biometry
|
|
211
|
-
* enrolled, every setting at its factory default, an empty disk. The
|
|
212
|
-
* conclusive half — N identical devices behind one address — is the server's.
|
|
213
|
-
*/
|
|
214
|
-
farm: Verdict;
|
|
215
|
-
}
|
|
216
|
-
/** What an iOS device can be asked. */
|
|
217
|
-
interface IosVerdicts extends NativeVerdicts {
|
|
218
|
-
jailbreak: Verdict;
|
|
219
|
-
simulator: Verdict;
|
|
220
|
-
}
|
|
221
|
-
/** What an Android device can be asked. */
|
|
222
|
-
interface AndroidVerdicts extends NativeVerdicts {
|
|
223
|
-
root: Verdict;
|
|
224
|
-
emulator: Verdict;
|
|
225
|
-
/** An app running under a cloning framework — one device, a hundred accounts. */
|
|
226
|
-
appCloner: Verdict;
|
|
227
|
-
}
|
|
228
|
-
/**
|
|
229
|
-
* Both platforms' verdicts in one shape, as the cross-platform SDKs return them.
|
|
230
|
-
*
|
|
231
|
-
* Not `IosVerdicts | AndroidVerdicts`. The union is more honest about the
|
|
232
|
-
* difference and it makes every call site narrow on the platform before it can
|
|
233
|
-
* read a field — which is the wrong trade for a binding whose entire purpose is
|
|
234
|
-
* writing the check once. `if (verdicts.jailbreak.value)` in code that runs on
|
|
235
|
-
* both platforms is the normal case, not the exception.
|
|
236
|
-
*
|
|
237
|
-
* The distinction is not lost, only moved. A member the platform cannot answer
|
|
238
|
-
* comes back as `{ value: false, confidence: 'low', reasons: [] }` — an empty
|
|
239
|
-
* `reasons` beside a false is what "this could not be asked" looks like, and it
|
|
240
|
-
* is the same convention `unknown()` uses in every detector in this codebase. A
|
|
241
|
-
* caller that needs to tell "we looked and found nothing" from "there was
|
|
242
|
-
* nothing to look at" reads `reasons.length`.
|
|
243
|
-
*
|
|
244
|
-
* The narrow types above remain, for a caller that has already established
|
|
245
|
-
* which platform it is on and wants the compiler to know.
|
|
246
|
-
*/
|
|
247
|
-
interface MobileVerdicts extends NativeVerdicts {
|
|
248
|
-
/** iOS. Unknown on Android. */
|
|
249
|
-
jailbreak: Verdict;
|
|
250
|
-
/** iOS. Unknown on Android. */
|
|
251
|
-
simulator: Verdict;
|
|
252
|
-
/** Android. Unknown on iOS. */
|
|
253
|
-
root: Verdict;
|
|
254
|
-
/** Android. Unknown on iOS. */
|
|
255
|
-
emulator: Verdict;
|
|
256
|
-
/** Android. Unknown on iOS. */
|
|
257
|
-
appCloner: Verdict;
|
|
258
|
-
}
|
|
259
143
|
/** What a native `identify()` resolves with. See [[IdentifyResult]]. */
|
|
260
144
|
interface NativeIdentifyResult {
|
|
261
145
|
requestId: string;
|
|
262
146
|
/** Who this visitor is. See [[IdentifyResult.visitorId]]. */
|
|
263
147
|
visitorId: string;
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
148
|
+
/** `null` when the server did not say, which is not the same as `false`. */
|
|
149
|
+
visitorIsNew: boolean | null;
|
|
150
|
+
/**
|
|
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]].
|
|
153
|
+
*/
|
|
154
|
+
visitorConfidence: number | null;
|
|
155
|
+
/** `null` when the server did not say. */
|
|
156
|
+
identifiable: boolean | null;
|
|
157
|
+
/**
|
|
158
|
+
* True when this submission was answered before; the fields above are empty.
|
|
159
|
+
* `null` when the server did not say.
|
|
160
|
+
*/
|
|
161
|
+
duplicate: boolean | null;
|
|
162
|
+
/** As [[IdentifyResult.state]]. */
|
|
270
163
|
state: string;
|
|
271
|
-
|
|
272
|
-
/** `null` when the submission was not scored, which is not the same as zero. */
|
|
164
|
+
/** `null` when absent: unscored, or hidden by the SDK key. Not the same as zero. */
|
|
273
165
|
suspectScore: number | null;
|
|
166
|
+
/** `null` when absent, for the same reasons as [[suspectScore]]. */
|
|
274
167
|
suspectLevel: string | null;
|
|
275
|
-
triggers: IdentifyTrigger[];
|
|
276
|
-
verdicts: MobileVerdicts;
|
|
277
168
|
report: SignalReport;
|
|
278
169
|
}
|
|
279
170
|
/** A submission, as the body of `POST /api/v1/ingest`. */
|
|
@@ -306,7 +197,6 @@ type DeferredIdentifyResult = {
|
|
|
306
197
|
status: 'submitted';
|
|
307
198
|
report: SignalReport;
|
|
308
199
|
combinedReport: SignalReport;
|
|
309
|
-
verdicts: Verdicts;
|
|
310
200
|
} | {
|
|
311
201
|
status: 'skipped';
|
|
312
202
|
/**
|
|
@@ -319,7 +209,6 @@ type DeferredIdentifyResult = {
|
|
|
319
209
|
error: Error;
|
|
320
210
|
report?: SignalReport;
|
|
321
211
|
combinedReport?: SignalReport;
|
|
322
|
-
verdicts?: Verdicts;
|
|
323
212
|
};
|
|
324
213
|
/**
|
|
325
214
|
* The answer.
|
|
@@ -375,49 +264,38 @@ interface IdentifyResult {
|
|
|
375
264
|
* could be identified", which is the opposite of what happened.
|
|
376
265
|
*/
|
|
377
266
|
duplicate: boolean;
|
|
378
|
-
/**
|
|
267
|
+
/**
|
|
268
|
+
* `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
|
+
*/
|
|
379
276
|
state: string;
|
|
380
|
-
/** Why enrichment did not happen, as a short stable token. Empty otherwise. */
|
|
381
|
-
reason: string;
|
|
382
277
|
/**
|
|
383
278
|
* The weighted sum of the signals that fired, under the weights in force when
|
|
384
279
|
* this submission was scored.
|
|
385
280
|
*
|
|
386
|
-
* `null` when the submission was not scored,
|
|
387
|
-
*
|
|
388
|
-
*
|
|
389
|
-
*
|
|
390
|
-
*
|
|
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.
|
|
391
287
|
*
|
|
392
288
|
* Not a percentage and not capped. Normalising it to 0-100 would discard the
|
|
393
289
|
* difference between "over the line" and "far over the line".
|
|
394
290
|
*/
|
|
395
291
|
suspectScore: number | null;
|
|
396
|
-
/** `low`, `medium` or `high`. `null`
|
|
292
|
+
/** `low`, `medium` or `high`. `null` when absent, as [[suspectScore]]. */
|
|
397
293
|
suspectLevel: string | null;
|
|
398
|
-
/** What fired, and what each was worth. */
|
|
399
|
-
triggers: IdentifyTrigger[];
|
|
400
|
-
/** The local verdicts, available before the round trip. Advisory; see [[Verdicts]]. */
|
|
401
|
-
verdicts: Verdicts;
|
|
402
294
|
/** The report that was sent, for debugging and for offline callers. */
|
|
403
295
|
report: SignalReport;
|
|
404
296
|
/** Completion of the non-authoritative second-tier collection and upload. */
|
|
405
297
|
deferred: Promise<DeferredIdentifyResult>;
|
|
406
298
|
}
|
|
407
|
-
/** One signal that fired on the server, and what it contributed. */
|
|
408
|
-
interface IdentifyTrigger {
|
|
409
|
-
signal: string;
|
|
410
|
-
/** The card this signal is reported under, such as `vpn` for `vpn_public`. */
|
|
411
|
-
group: string;
|
|
412
|
-
/**
|
|
413
|
-
* The weight as it was applied, under the profile in force at the time. A
|
|
414
|
-
* customer who lowers a weight has not changed what last week scored.
|
|
415
|
-
*/
|
|
416
|
-
weight: number;
|
|
417
|
-
confidence: string;
|
|
418
|
-
/** The tell that fired it, such as `known-tor-exit`. */
|
|
419
|
-
reason: string;
|
|
420
|
-
}
|
|
421
299
|
interface IdentificationConfidence {
|
|
422
300
|
score: number;
|
|
423
301
|
version: string;
|
|
@@ -521,4 +399,4 @@ interface FingerlyWebEvent extends FingerlyEventBase {
|
|
|
521
399
|
}
|
|
522
400
|
type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent;
|
|
523
401
|
|
|
524
|
-
export type {
|
|
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 };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fingerly/types",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
@@ -8,22 +8,27 @@
|
|
|
8
8
|
"license": "Apache-2.0",
|
|
9
9
|
"repository": {
|
|
10
10
|
"type": "git",
|
|
11
|
-
"url": "https://github.com/fingerly-io/
|
|
11
|
+
"url": "https://github.com/fingerly-io/sdks.git",
|
|
12
|
+
"directory": "client/web/types"
|
|
12
13
|
},
|
|
13
14
|
"type": "module",
|
|
14
15
|
"main": "./dist/index.cjs",
|
|
15
16
|
"module": "./dist/index.js",
|
|
16
|
-
"types": "./
|
|
17
|
+
"types": "./dist/index.d.ts",
|
|
17
18
|
"exports": {
|
|
18
19
|
".": {
|
|
19
|
-
"
|
|
20
|
-
|
|
21
|
-
|
|
20
|
+
"import": {
|
|
21
|
+
"types": "./dist/index.d.ts",
|
|
22
|
+
"default": "./dist/index.js"
|
|
23
|
+
},
|
|
24
|
+
"require": {
|
|
25
|
+
"types": "./dist/index.d.cts",
|
|
26
|
+
"default": "./dist/index.cjs"
|
|
27
|
+
}
|
|
22
28
|
}
|
|
23
29
|
},
|
|
24
30
|
"files": [
|
|
25
|
-
"dist"
|
|
26
|
-
"src"
|
|
31
|
+
"dist"
|
|
27
32
|
],
|
|
28
33
|
"sideEffects": false,
|
|
29
34
|
"devDependencies": {
|
package/src/index.ts
DELETED
|
@@ -1,572 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The shapes every Fingerly SDK speaks in.
|
|
3
|
-
*
|
|
4
|
-
* Nothing here touches the DOM. A type that only a browser can populate still
|
|
5
|
-
* belongs in this file, because the server and the mobile SDKs both need to
|
|
6
|
-
* name it; what does not belong here is the code that reads a `window`.
|
|
7
|
-
*/
|
|
8
|
-
|
|
9
|
-
/** Which SDK collected a report. Mirrors `schemas.SDKInfo` on the server. */
|
|
10
|
-
/**
|
|
11
|
-
* The cross-platform values name the host as well as the toolkit, because the
|
|
12
|
-
* server maps an SDK platform onto one of three scoring profiles by looking for
|
|
13
|
-
* `ios` or `android` in the string — see `models.RiskPlatformFor`. A React
|
|
14
|
-
* Native app reporting only `react-native` falls through to the browser
|
|
15
|
-
* profile, where `jailbreak` is not a signal at all and everything the native
|
|
16
|
-
* SDK went to the trouble of collecting is worth nothing.
|
|
17
|
-
*/
|
|
18
|
-
export type SdkPlatform =
|
|
19
|
-
| 'web'
|
|
20
|
-
| 'android'
|
|
21
|
-
| 'ios'
|
|
22
|
-
| 'react-native-ios'
|
|
23
|
-
| 'react-native-android'
|
|
24
|
-
| 'flutter-ios'
|
|
25
|
-
| 'flutter-android'
|
|
26
|
-
| 'lynx-ios'
|
|
27
|
-
| 'lynx-android'
|
|
28
|
-
|
|
29
|
-
/** Configuration shared by JavaScript-based native SDK facades. */
|
|
30
|
-
export interface MobileFingerlyOptions {
|
|
31
|
-
/** The SDK key, from the dashboard. */
|
|
32
|
-
apiKey: string
|
|
33
|
-
/** Origin of the API. Defaults to production. Submissions go to `/api/v1/ingest` under it. */
|
|
34
|
-
endpoint?: string
|
|
35
|
-
}
|
|
36
|
-
|
|
37
|
-
/** Identification options shared by JavaScript-based native SDK facades. */
|
|
38
|
-
export interface MobileIdentifyOptions {
|
|
39
|
-
/** Echoed back on the finished event, for the caller's own correlation. */
|
|
40
|
-
tag?: string
|
|
41
|
-
/** Collect and score without submitting when false. Defaults to true. */
|
|
42
|
-
submit?: boolean
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
/**
|
|
46
|
-
* Whether the visitor has agreed to be identified.
|
|
47
|
-
*
|
|
48
|
-
* `pending` is the default: an SDK identifies nobody until it is told
|
|
49
|
-
* `granted`. `pending` and `denied` mean the same thing to the SDK - run no
|
|
50
|
-
* source, touch no storage, send nothing, and fail `identify()` with a consent
|
|
51
|
-
* error - and
|
|
52
|
-
* are kept apart only because a consent tool reports them apart, and a page
|
|
53
|
-
* deciding whether to show its banner wants to know which one it has.
|
|
54
|
-
*/
|
|
55
|
-
export type ConsentState = 'granted' | 'pending' | 'denied'
|
|
56
|
-
|
|
57
|
-
/**
|
|
58
|
-
* How a source finished.
|
|
59
|
-
*
|
|
60
|
-
* Collapsing every failure into one `error` token would make a browser that
|
|
61
|
-
* lacks an API, a privacy extension that blocked it, and a throttled tab that
|
|
62
|
-
* ran out of time all hash identically. They are three different facts about a visitor:
|
|
63
|
-
*
|
|
64
|
-
* - `ok` the source produced a value.
|
|
65
|
-
* - `unsupported` the API is not present. A property of the device/browser.
|
|
66
|
-
* - `blocked` the API is present and refused, or returned deliberate noise.
|
|
67
|
-
* A property of the visitor's privacy posture, and most of what
|
|
68
|
-
* Tor and hardened-browser detection is made of.
|
|
69
|
-
* - `timeout` the source overran its slice of the budget. Says something
|
|
70
|
-
* about load and throttling, and nothing about the device.
|
|
71
|
-
* - `error` the source threw for a reason we did not anticipate.
|
|
72
|
-
*/
|
|
73
|
-
export type SignalStatus = 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error'
|
|
74
|
-
|
|
75
|
-
/**
|
|
76
|
-
* What one source reported.
|
|
77
|
-
*
|
|
78
|
-
* `ms` is recorded for every status, failures included. A source that took
|
|
79
|
-
* 3ms to be unsupported and one that took 300ms to be blocked are telling
|
|
80
|
-
* different stories, and the duration is frequently the more stable of the two
|
|
81
|
-
* numbers - timing is itself an entropy source, which is why it is kept rather
|
|
82
|
-
* than discarded on the failure path.
|
|
83
|
-
*/
|
|
84
|
-
export interface SignalOutcome<T = unknown> {
|
|
85
|
-
status: SignalStatus
|
|
86
|
-
/** Wall-clock milliseconds the source occupied, rounded to avoid a clock oracle. */
|
|
87
|
-
ms: number
|
|
88
|
-
/** Present when `status` is `ok`. */
|
|
89
|
-
value?: T
|
|
90
|
-
/**
|
|
91
|
-
* Why, for the statuses that have a why. A short stable token such as
|
|
92
|
-
* `SecurityError` or `audio-suspended` - never a stack trace, which is
|
|
93
|
-
* unstable across versions and would poison any matching built on it.
|
|
94
|
-
*/
|
|
95
|
-
reason?: string
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
/**
|
|
99
|
-
* When a source runs.
|
|
100
|
-
*
|
|
101
|
-
* `fast` sources are cheap and synchronous-ish, and every one of them must fit
|
|
102
|
-
* inside the fast budget because a page is waiting on the submission. `deferred`
|
|
103
|
-
* sources are the expensive ones - font measurement, audio rendering, WebGL
|
|
104
|
-
* shader precision - which are worth having but not worth blocking a checkout
|
|
105
|
-
* button for.
|
|
106
|
-
*/
|
|
107
|
-
export type SourceTier = 'fast' | 'deferred'
|
|
108
|
-
|
|
109
|
-
/** A native function, descriptor or prototype that is not what it should be. */
|
|
110
|
-
export interface Lie {
|
|
111
|
-
/** Stable identifier, such as `navigator.hardwareConcurrency.getter`. */
|
|
112
|
-
id: string
|
|
113
|
-
/** What kind of tampering was observed. */
|
|
114
|
-
kind: 'not-native' | 'descriptor' | 'prototype' | 'contradiction' | 'missing'
|
|
115
|
-
/** Optional short detail. Kept stable across versions or left off. */
|
|
116
|
-
detail?: string
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
/**
|
|
120
|
-
* What the browser is, as opposed to what it says it is.
|
|
121
|
-
*
|
|
122
|
-
* `claimed` comes from the user-agent and the UA-CH headers - a string anyone
|
|
123
|
-
* can set. `observed` is derived from engine behaviour that a spoofer has to
|
|
124
|
-
* patch a JS builtin to change, at which point `lies` catches them instead.
|
|
125
|
-
* A disagreement between the two is worth more than either one alone.
|
|
126
|
-
*/
|
|
127
|
-
export interface EngineIdentity {
|
|
128
|
-
claimed?: string
|
|
129
|
-
observed?: string
|
|
130
|
-
agrees?: boolean
|
|
131
|
-
}
|
|
132
|
-
|
|
133
|
-
/** The tamper layer's findings. Raw; the server decides what they are worth. */
|
|
134
|
-
export interface IntegrityReport {
|
|
135
|
-
/** Natives whose `toString()` is no longer `[native code]`. */
|
|
136
|
-
patched_natives: string[]
|
|
137
|
-
/** Everything else that did not add up. */
|
|
138
|
-
lies: Lie[]
|
|
139
|
-
engine: EngineIdentity
|
|
140
|
-
}
|
|
141
|
-
|
|
142
|
-
/**
|
|
143
|
-
* The whole client-side observation, as submitted.
|
|
144
|
-
*
|
|
145
|
-
* This is what lands in `signals` on the wire. The server types that field as
|
|
146
|
-
* `map[string]any` and deliberately does not interpret it (see
|
|
147
|
-
* `server/services/identify.go`), so this interface is the only place the
|
|
148
|
-
* shape is written down until the event store exists.
|
|
149
|
-
*/
|
|
150
|
-
export interface SignalReport {
|
|
151
|
-
/** Bumped when a field changes meaning, never when one is added. */
|
|
152
|
-
schema: number
|
|
153
|
-
/** The budget that was asked for, so a truncated report is legible as one. */
|
|
154
|
-
budget_ms: number
|
|
155
|
-
/** What collection actually cost. */
|
|
156
|
-
elapsed_ms: number
|
|
157
|
-
/** Which tiers ran. A fast-only report is not a degraded full one. */
|
|
158
|
-
tiers: SourceTier[]
|
|
159
|
-
sources: Record<string, SignalOutcome>
|
|
160
|
-
integrity: IntegrityReport
|
|
161
|
-
}
|
|
162
|
-
|
|
163
|
-
/** How sure a verdict is. Matches the server's `*_confidence` fields. */
|
|
164
|
-
export type Confidence = 'low' | 'medium' | 'high'
|
|
165
|
-
|
|
166
|
-
/**
|
|
167
|
-
* One detector's answer.
|
|
168
|
-
*
|
|
169
|
-
* `reasons` is the point of this type. A boolean that cannot say why it is
|
|
170
|
-
* true is not reviewable, and every one of these verdicts will eventually be
|
|
171
|
-
* argued with by a customer looking at a blocked user.
|
|
172
|
-
*/
|
|
173
|
-
export interface Verdict {
|
|
174
|
-
value: boolean
|
|
175
|
-
confidence: Confidence
|
|
176
|
-
reasons: string[]
|
|
177
|
-
}
|
|
178
|
-
|
|
179
|
-
/**
|
|
180
|
-
* The verdicts the client can reach on its own.
|
|
181
|
-
*
|
|
182
|
-
* These are computed in the page for the caller's convenience - a login form
|
|
183
|
-
* that wants to step up to MFA should not have to wait for enrichment. They
|
|
184
|
-
* are *not* authoritative: the same functions run again on the server, over
|
|
185
|
-
* the stored report, with rules that can improve without an SDK release. A
|
|
186
|
-
* client-side verdict is advice; the server's is the answer.
|
|
187
|
-
*/
|
|
188
|
-
export interface Verdicts {
|
|
189
|
-
incognito: Verdict
|
|
190
|
-
/**
|
|
191
|
-
* Anti-fingerprinting countermeasures are rewriting this report's values.
|
|
192
|
-
*
|
|
193
|
-
* The one verdict here that is never a reason to challenge anyone. It says
|
|
194
|
-
* which of the other numbers are fabricated - Brave's farbling, Tor's RFP, an
|
|
195
|
-
* anti-detect build - so the detectors above it can decline to reason from
|
|
196
|
-
* them and the identity hash can decline to include them. A customer acting
|
|
197
|
-
* on this one is acting on "uses a privacy browser", which is not a finding.
|
|
198
|
-
*/
|
|
199
|
-
shields: Verdict
|
|
200
|
-
tor: Verdict
|
|
201
|
-
emulator: Verdict
|
|
202
|
-
automation: Verdict
|
|
203
|
-
/**
|
|
204
|
-
* Device farms are fundamentally a server-side finding - N identical devices
|
|
205
|
-
* behind one ASN - so this verdict only reports the client-observable half:
|
|
206
|
-
* a device that looks mass-provisioned or reset-fresh.
|
|
207
|
-
*/
|
|
208
|
-
farm: Verdict
|
|
209
|
-
}
|
|
210
|
-
|
|
211
|
-
/**
|
|
212
|
-
* The verdicts a native application can reach, on either platform.
|
|
213
|
-
*
|
|
214
|
-
* Separate from [[Verdicts]] rather than an extension of it, because the two
|
|
215
|
-
* sets barely overlap. A page approximates `emulator` from a software renderer
|
|
216
|
-
* and a suspicious pixel ratio; an app reads `SIMULATOR_ROOT` out of its own
|
|
217
|
-
* environment and knows. A browser cannot look for an injected library at all.
|
|
218
|
-
* Folding them into one interface would mean every field optional, which would
|
|
219
|
-
* make "this platform cannot answer that" and "that answer was false" the same
|
|
220
|
-
* value — the distinction the whole `SignalStatus` design exists to preserve.
|
|
221
|
-
*/
|
|
222
|
-
export interface NativeVerdicts {
|
|
223
|
-
/** Frida, Substrate, Substitute, ElleKit — anything rewriting the process. */
|
|
224
|
-
instrumentation: Verdict
|
|
225
|
-
/** Something intercepting the app's own TLS. */
|
|
226
|
-
mitm: Verdict
|
|
227
|
-
/** A debugger or a UI-test runner driving the process. */
|
|
228
|
-
automation: Verdict
|
|
229
|
-
/** Hooked functions, injected images, a signature that is not the app's. */
|
|
230
|
-
tampering: Verdict
|
|
231
|
-
/**
|
|
232
|
-
* A device that looks mass-provisioned or reset-fresh.
|
|
233
|
-
*
|
|
234
|
-
* The half one device can see about itself: no passcode, no biometry
|
|
235
|
-
* enrolled, every setting at its factory default, an empty disk. The
|
|
236
|
-
* conclusive half — N identical devices behind one address — is the server's.
|
|
237
|
-
*/
|
|
238
|
-
farm: Verdict
|
|
239
|
-
}
|
|
240
|
-
|
|
241
|
-
/** What an iOS device can be asked. */
|
|
242
|
-
export interface IosVerdicts extends NativeVerdicts {
|
|
243
|
-
jailbreak: Verdict
|
|
244
|
-
simulator: Verdict
|
|
245
|
-
}
|
|
246
|
-
|
|
247
|
-
/** What an Android device can be asked. */
|
|
248
|
-
export interface AndroidVerdicts extends NativeVerdicts {
|
|
249
|
-
root: Verdict
|
|
250
|
-
emulator: Verdict
|
|
251
|
-
/** An app running under a cloning framework — one device, a hundred accounts. */
|
|
252
|
-
appCloner: Verdict
|
|
253
|
-
}
|
|
254
|
-
|
|
255
|
-
/**
|
|
256
|
-
* Both platforms' verdicts in one shape, as the cross-platform SDKs return them.
|
|
257
|
-
*
|
|
258
|
-
* Not `IosVerdicts | AndroidVerdicts`. The union is more honest about the
|
|
259
|
-
* difference and it makes every call site narrow on the platform before it can
|
|
260
|
-
* read a field — which is the wrong trade for a binding whose entire purpose is
|
|
261
|
-
* writing the check once. `if (verdicts.jailbreak.value)` in code that runs on
|
|
262
|
-
* both platforms is the normal case, not the exception.
|
|
263
|
-
*
|
|
264
|
-
* The distinction is not lost, only moved. A member the platform cannot answer
|
|
265
|
-
* comes back as `{ value: false, confidence: 'low', reasons: [] }` — an empty
|
|
266
|
-
* `reasons` beside a false is what "this could not be asked" looks like, and it
|
|
267
|
-
* is the same convention `unknown()` uses in every detector in this codebase. A
|
|
268
|
-
* caller that needs to tell "we looked and found nothing" from "there was
|
|
269
|
-
* nothing to look at" reads `reasons.length`.
|
|
270
|
-
*
|
|
271
|
-
* The narrow types above remain, for a caller that has already established
|
|
272
|
-
* which platform it is on and wants the compiler to know.
|
|
273
|
-
*/
|
|
274
|
-
export interface MobileVerdicts extends NativeVerdicts {
|
|
275
|
-
/** iOS. Unknown on Android. */
|
|
276
|
-
jailbreak: Verdict
|
|
277
|
-
/** iOS. Unknown on Android. */
|
|
278
|
-
simulator: Verdict
|
|
279
|
-
/** Android. Unknown on iOS. */
|
|
280
|
-
root: Verdict
|
|
281
|
-
/** Android. Unknown on iOS. */
|
|
282
|
-
emulator: Verdict
|
|
283
|
-
/** Android. Unknown on iOS. */
|
|
284
|
-
appCloner: Verdict
|
|
285
|
-
}
|
|
286
|
-
|
|
287
|
-
/** What a native `identify()` resolves with. See [[IdentifyResult]]. */
|
|
288
|
-
export interface NativeIdentifyResult {
|
|
289
|
-
requestId: string
|
|
290
|
-
|
|
291
|
-
/** Who this visitor is. See [[IdentifyResult.visitorId]]. */
|
|
292
|
-
visitorId: string
|
|
293
|
-
visitorIsNew: boolean
|
|
294
|
-
/** How sure the server is, 0 to 100. See [[IdentifyResult.visitorConfidence]]. */
|
|
295
|
-
visitorConfidence: number
|
|
296
|
-
identifiable: boolean
|
|
297
|
-
/** True when this submission was answered before; the fields above are empty. */
|
|
298
|
-
duplicate: boolean
|
|
299
|
-
|
|
300
|
-
state: string
|
|
301
|
-
reason: string
|
|
302
|
-
|
|
303
|
-
/** `null` when the submission was not scored, which is not the same as zero. */
|
|
304
|
-
suspectScore: number | null
|
|
305
|
-
suspectLevel: string | null
|
|
306
|
-
triggers: IdentifyTrigger[]
|
|
307
|
-
|
|
308
|
-
verdicts: MobileVerdicts
|
|
309
|
-
report: SignalReport
|
|
310
|
-
}
|
|
311
|
-
|
|
312
|
-
/** A submission, as the body of `POST /api/v1/ingest`. */
|
|
313
|
-
export interface IdentifySubmission {
|
|
314
|
-
sdk: { platform: SdkPlatform; version: string }
|
|
315
|
-
/**
|
|
316
|
-
* The SDK's consent state when it sent this. Always `granted`, since an SDK
|
|
317
|
-
* sends nothing otherwise; the server refuses any other value with a 422
|
|
318
|
-
* `consent_required`.
|
|
319
|
-
*/
|
|
320
|
-
consent: ConsentState
|
|
321
|
-
signals: SignalReport
|
|
322
|
-
tag?: string
|
|
323
|
-
}
|
|
324
|
-
|
|
325
|
-
/** A deferred source report attached to an already completed identification. */
|
|
326
|
-
export interface DeferredSubmission {
|
|
327
|
-
sdk: { platform: SdkPlatform; version: string }
|
|
328
|
-
/** As on [[IdentifySubmission.consent]]. */
|
|
329
|
-
consent: ConsentState
|
|
330
|
-
signals: SignalReport
|
|
331
|
-
token: string
|
|
332
|
-
}
|
|
333
|
-
|
|
334
|
-
export type DeferredIdentifyResult =
|
|
335
|
-
| {
|
|
336
|
-
status: 'submitted'
|
|
337
|
-
report: SignalReport
|
|
338
|
-
combinedReport: SignalReport
|
|
339
|
-
verdicts: Verdicts
|
|
340
|
-
}
|
|
341
|
-
| {
|
|
342
|
-
status: 'skipped'
|
|
343
|
-
/**
|
|
344
|
-
* `consent-withdrawn` when consent stopped being `granted` after the
|
|
345
|
-
* first response and before the supplement was sent.
|
|
346
|
-
*/
|
|
347
|
-
reason: 'not-submitted' | 'explicit-tiers' | 'duplicate' | 'unsupported-transport' | 'consent-withdrawn'
|
|
348
|
-
}
|
|
349
|
-
| {
|
|
350
|
-
status: 'failed'
|
|
351
|
-
error: Error
|
|
352
|
-
report?: SignalReport
|
|
353
|
-
combinedReport?: SignalReport
|
|
354
|
-
verdicts?: Verdicts
|
|
355
|
-
}
|
|
356
|
-
|
|
357
|
-
/**
|
|
358
|
-
* The answer.
|
|
359
|
-
*
|
|
360
|
-
* Note what is absent: there is no visitor identifier computed here, because
|
|
361
|
-
* the client does not compute one. Hashing components in the page would make
|
|
362
|
-
* the identity forgeable by the visitor and freeze the matching algorithm
|
|
363
|
-
* into whatever SDK version a customer deployed. Fingerly
|
|
364
|
-
* submits the raw report and lets the server decide who this is - and then
|
|
365
|
-
* tells you, in the same response.
|
|
366
|
-
*/
|
|
367
|
-
export interface IdentifyResult {
|
|
368
|
-
requestId: string
|
|
369
|
-
|
|
370
|
-
/**
|
|
371
|
-
* Who this visitor is, stable across their visits.
|
|
372
|
-
*
|
|
373
|
-
* Empty only when nothing was submitted (`submit: false`) or when the
|
|
374
|
-
* submission was a [[duplicate]]. Otherwise always present: a report too thin
|
|
375
|
-
* to match anyone still gets an identifier, minted rather than matched, so
|
|
376
|
-
* that every event has a key.
|
|
377
|
-
*/
|
|
378
|
-
visitorId: string
|
|
379
|
-
/** Whether this is the first time the server has seen this visitor. */
|
|
380
|
-
visitorIsNew: boolean
|
|
381
|
-
|
|
382
|
-
/**
|
|
383
|
-
* How sure the server is about [[visitorId]], from 0 to 100.
|
|
384
|
-
*
|
|
385
|
-
* 100 when this exact device has been seen before, 85-99 when it drifted -
|
|
386
|
-
* a browser update, a new monitor - and was recognised by similarity, and 0
|
|
387
|
-
* when the identifier was minted because nothing matched.
|
|
388
|
-
*
|
|
389
|
-
* Read this rather than inferring trust from [[identifiable]], which only
|
|
390
|
-
* says whether the report was rich enough to attempt a match.
|
|
391
|
-
*/
|
|
392
|
-
visitorConfidence: number
|
|
393
|
-
|
|
394
|
-
/**
|
|
395
|
-
* False when the report carried too little to identify anyone.
|
|
396
|
-
*
|
|
397
|
-
* A hardened browser produces this honestly; so does a client that would
|
|
398
|
-
* rather not be recognised. Either way the submission is still answered and
|
|
399
|
-
* still scored - more highly, because suppressing a fingerprint is itself
|
|
400
|
-
* evidence - and it is charged at a lower rate, because the address lookup
|
|
401
|
-
* happened and the identification did not.
|
|
402
|
-
*/
|
|
403
|
-
identifiable: boolean
|
|
404
|
-
|
|
405
|
-
/**
|
|
406
|
-
* True when this submission was answered before under the same idempotency
|
|
407
|
-
* key.
|
|
408
|
-
*
|
|
409
|
-
* The verdict belongs to that first submission and is not repeated, so the
|
|
410
|
-
* fields above are empty. Keep the first response, or fetch the event by
|
|
411
|
-
* [[requestId]]. Without this flag an empty visitor would read as "nobody
|
|
412
|
-
* could be identified", which is the opposite of what happened.
|
|
413
|
-
*/
|
|
414
|
-
duplicate: boolean
|
|
415
|
-
|
|
416
|
-
/** `enriched`, or `unavailable` when the address could not be looked up. */
|
|
417
|
-
state: string
|
|
418
|
-
/** Why enrichment did not happen, as a short stable token. Empty otherwise. */
|
|
419
|
-
reason: string
|
|
420
|
-
|
|
421
|
-
/**
|
|
422
|
-
* The weighted sum of the signals that fired, under the weights in force when
|
|
423
|
-
* this submission was scored.
|
|
424
|
-
*
|
|
425
|
-
* `null` when the submission was not scored, which is a different answer from
|
|
426
|
-
* zero: an ordinary visitor scores zero, and one whose enrichment never ran
|
|
427
|
-
* has no score at all. Anything computed as a share of your traffic divides
|
|
428
|
-
* by one of those two populations, so collapsing them makes the number
|
|
429
|
-
* plausible and wrong.
|
|
430
|
-
*
|
|
431
|
-
* Not a percentage and not capped. Normalising it to 0-100 would discard the
|
|
432
|
-
* difference between "over the line" and "far over the line".
|
|
433
|
-
*/
|
|
434
|
-
suspectScore: number | null
|
|
435
|
-
/** `low`, `medium` or `high`. `null` exactly when [[suspectScore]] is. */
|
|
436
|
-
suspectLevel: string | null
|
|
437
|
-
|
|
438
|
-
/** What fired, and what each was worth. */
|
|
439
|
-
triggers: IdentifyTrigger[]
|
|
440
|
-
|
|
441
|
-
/** The local verdicts, available before the round trip. Advisory; see [[Verdicts]]. */
|
|
442
|
-
verdicts: Verdicts
|
|
443
|
-
/** The report that was sent, for debugging and for offline callers. */
|
|
444
|
-
report: SignalReport
|
|
445
|
-
|
|
446
|
-
/** Completion of the non-authoritative second-tier collection and upload. */
|
|
447
|
-
deferred: Promise<DeferredIdentifyResult>
|
|
448
|
-
}
|
|
449
|
-
|
|
450
|
-
/** One signal that fired on the server, and what it contributed. */
|
|
451
|
-
export interface IdentifyTrigger {
|
|
452
|
-
signal: string
|
|
453
|
-
/** The card this signal is reported under, such as `vpn` for `vpn_public`. */
|
|
454
|
-
group: string
|
|
455
|
-
/**
|
|
456
|
-
* The weight as it was applied, under the profile in force at the time. A
|
|
457
|
-
* customer who lowers a weight has not changed what last week scored.
|
|
458
|
-
*/
|
|
459
|
-
weight: number
|
|
460
|
-
confidence: string
|
|
461
|
-
/** The tell that fired it, such as `known-tor-exit`. */
|
|
462
|
-
reason: string
|
|
463
|
-
}
|
|
464
|
-
|
|
465
|
-
// ---------------------------------------------------------------------------
|
|
466
|
-
// The stored event.
|
|
467
|
-
//
|
|
468
|
-
// The same submission as the server keeps it, fetched by `requestId` when
|
|
469
|
-
// somebody wants it again later - a support question, a backend double-checking
|
|
470
|
-
// what the browser was told. The verdict itself no longer waits for this: it
|
|
471
|
-
// comes back with the submission.
|
|
472
|
-
//
|
|
473
|
-
// The types live here because every SDK has to name them.
|
|
474
|
-
// ---------------------------------------------------------------------------
|
|
475
|
-
|
|
476
|
-
export interface IdentificationConfidence {
|
|
477
|
-
score: number
|
|
478
|
-
version: string
|
|
479
|
-
}
|
|
480
|
-
|
|
481
|
-
export interface Identification {
|
|
482
|
-
visitor_id: string
|
|
483
|
-
confidence: IdentificationConfidence
|
|
484
|
-
visitor_found: boolean
|
|
485
|
-
first_seen_at: number
|
|
486
|
-
last_seen_at: number
|
|
487
|
-
}
|
|
488
|
-
|
|
489
|
-
export interface IpGeolocation {
|
|
490
|
-
accuracy_radius: number
|
|
491
|
-
latitude: number
|
|
492
|
-
longitude: number
|
|
493
|
-
postal_code: string
|
|
494
|
-
timezone: string
|
|
495
|
-
city_name: string
|
|
496
|
-
country_code: string
|
|
497
|
-
country_name: string
|
|
498
|
-
continent_code: string
|
|
499
|
-
continent_name: string
|
|
500
|
-
subdivisions: { iso_code: string; name: string }[]
|
|
501
|
-
}
|
|
502
|
-
|
|
503
|
-
export interface IpInfoV4 {
|
|
504
|
-
address: string
|
|
505
|
-
geolocation: IpGeolocation
|
|
506
|
-
asn: string
|
|
507
|
-
asn_name: string
|
|
508
|
-
asn_network: string
|
|
509
|
-
asn_type: string
|
|
510
|
-
datacenter_result: boolean
|
|
511
|
-
}
|
|
512
|
-
|
|
513
|
-
export interface VelocityWindow {
|
|
514
|
-
'5_minutes': number
|
|
515
|
-
'1_hour': number
|
|
516
|
-
'24_hours': number
|
|
517
|
-
}
|
|
518
|
-
|
|
519
|
-
export interface Velocity {
|
|
520
|
-
distinct_ip: VelocityWindow
|
|
521
|
-
distinct_country: VelocityWindow
|
|
522
|
-
events: VelocityWindow
|
|
523
|
-
ip_events: VelocityWindow
|
|
524
|
-
}
|
|
525
|
-
|
|
526
|
-
/** Fields every platform reports. */
|
|
527
|
-
export interface FingerlyEventBase {
|
|
528
|
-
event_id: string
|
|
529
|
-
timestamp: number
|
|
530
|
-
source: 'device'
|
|
531
|
-
sdk: { platform: SdkPlatform; version: string }
|
|
532
|
-
replayed: boolean
|
|
533
|
-
identification: Identification
|
|
534
|
-
ip_address: string
|
|
535
|
-
ip_info: { v4: IpInfoV4 }
|
|
536
|
-
proxy: boolean
|
|
537
|
-
proxy_confidence: Confidence
|
|
538
|
-
vpn: boolean
|
|
539
|
-
vpn_confidence: Confidence
|
|
540
|
-
tampering: boolean
|
|
541
|
-
tampering_confidence: Confidence
|
|
542
|
-
suspect_score: number
|
|
543
|
-
velocity: Velocity
|
|
544
|
-
}
|
|
545
|
-
|
|
546
|
-
/**
|
|
547
|
-
* Signals only a native app can observe.
|
|
548
|
-
*
|
|
549
|
-
* Absent on web rather than `false`, because a browser cannot look for a root
|
|
550
|
-
* app and reporting "no" would be a claim nobody made.
|
|
551
|
-
*/
|
|
552
|
-
export interface FingerlyMobileEvent extends FingerlyEventBase {
|
|
553
|
-
sdk: { platform: 'android' | 'ios'; version: string }
|
|
554
|
-
package_name: string
|
|
555
|
-
emulator: boolean
|
|
556
|
-
root_apps: boolean
|
|
557
|
-
cloned_app: boolean
|
|
558
|
-
frida: boolean
|
|
559
|
-
developer_tools: boolean
|
|
560
|
-
factory_reset_timestamp?: number
|
|
561
|
-
active_call: boolean
|
|
562
|
-
}
|
|
563
|
-
|
|
564
|
-
export interface FingerlyWebEvent extends FingerlyEventBase {
|
|
565
|
-
sdk: { platform: 'web'; version: string }
|
|
566
|
-
browser_name: string
|
|
567
|
-
browser_version: string
|
|
568
|
-
incognito: boolean
|
|
569
|
-
ad_blocker: boolean
|
|
570
|
-
}
|
|
571
|
-
|
|
572
|
-
export type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent
|