@fingerly/types 0.1.0 → 0.1.1

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 CHANGED
@@ -109,6 +109,10 @@ interface Lie {
109
109
  interface EngineIdentity {
110
110
  claimed?: string;
111
111
  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
+ */
112
116
  agrees?: boolean;
113
117
  }
114
118
  /** The tamper layer's findings. Raw; the server decides what they are worth. */
@@ -139,141 +143,38 @@ interface SignalReport {
139
143
  sources: Record<string, SignalOutcome>;
140
144
  integrity: IntegrityReport;
141
145
  }
142
- /** How sure a verdict is. Matches the server's `*_confidence` fields. */
146
+ /** How sure the server is of a finding. Matches its `*_confidence` fields. */
143
147
  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
148
  /** What a native `identify()` resolves with. See [[IdentifyResult]]. */
260
149
  interface NativeIdentifyResult {
261
150
  requestId: string;
262
151
  /** Who this visitor is. See [[IdentifyResult.visitorId]]. */
263
152
  visitorId: string;
264
- visitorIsNew: boolean;
265
- /** How sure the server is, 0 to 100. See [[IdentifyResult.visitorConfidence]]. */
266
- visitorConfidence: number;
267
- identifiable: boolean;
268
- /** True when this submission was answered before; the fields above are empty. */
269
- duplicate: boolean;
153
+ /** `null` when the server did not say, which is not the same as `false`. */
154
+ visitorIsNew: boolean | null;
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]].
158
+ */
159
+ visitorConfidence: number | null;
160
+ /** `null` when the server did not say. */
161
+ identifiable: boolean | null;
162
+ /**
163
+ * True when this submission was answered before; the fields above are empty.
164
+ * `null` when the server did not say.
165
+ */
166
+ duplicate: boolean | null;
270
167
  state: string;
271
- reason: string;
272
- /** `null` when the submission was not scored, which is not the same as zero. */
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
+ /** `null` when absent: unscored, or hidden by the SDK key. Not the same as zero. */
273
175
  suspectScore: number | null;
176
+ /** `null` when absent, for the same reasons as [[suspectScore]]. */
274
177
  suspectLevel: string | null;
275
- triggers: IdentifyTrigger[];
276
- verdicts: MobileVerdicts;
277
178
  report: SignalReport;
278
179
  }
279
180
  /** A submission, as the body of `POST /api/v1/ingest`. */
@@ -306,7 +207,6 @@ type DeferredIdentifyResult = {
306
207
  status: 'submitted';
307
208
  report: SignalReport;
308
209
  combinedReport: SignalReport;
309
- verdicts: Verdicts;
310
210
  } | {
311
211
  status: 'skipped';
312
212
  /**
@@ -319,7 +219,6 @@ type DeferredIdentifyResult = {
319
219
  error: Error;
320
220
  report?: SignalReport;
321
221
  combinedReport?: SignalReport;
322
- verdicts?: Verdicts;
323
222
  };
324
223
  /**
325
224
  * The answer.
@@ -377,47 +276,38 @@ interface IdentifyResult {
377
276
  duplicate: boolean;
378
277
  /** `enriched`, or `unavailable` when the address could not be looked up. */
379
278
  state: string;
380
- /** Why enrichment did not happen, as a short stable token. Empty otherwise. */
381
- reason: string;
279
+ /**
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.
287
+ */
288
+ reason?: string;
382
289
  /**
383
290
  * The weighted sum of the signals that fired, under the weights in force when
384
291
  * this submission was scored.
385
292
  *
386
- * `null` when the submission was not scored, which is a different answer from
387
- * zero: an ordinary visitor scores zero, and one whose enrichment never ran
388
- * has no score at all. Anything computed as a share of your traffic divides
389
- * by one of those two populations, so collapsing them makes the number
390
- * plausible and wrong.
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.
391
299
  *
392
300
  * Not a percentage and not capped. Normalising it to 0-100 would discard the
393
301
  * difference between "over the line" and "far over the line".
394
302
  */
395
303
  suspectScore: number | null;
396
- /** `low`, `medium` or `high`. `null` exactly when [[suspectScore]] is. */
304
+ /** `low`, `medium` or `high`. `null` when absent, as [[suspectScore]]. */
397
305
  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
306
  /** The report that was sent, for debugging and for offline callers. */
403
307
  report: SignalReport;
404
308
  /** Completion of the non-authoritative second-tier collection and upload. */
405
309
  deferred: Promise<DeferredIdentifyResult>;
406
310
  }
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
311
  interface IdentificationConfidence {
422
312
  score: number;
423
313
  version: string;
@@ -521,4 +411,4 @@ interface FingerlyWebEvent extends FingerlyEventBase {
521
411
  }
522
412
  type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent;
523
413
 
524
- export type { AndroidVerdicts, Confidence, ConsentState, DeferredIdentifyResult, DeferredSubmission, EngineIdentity, FingerlyEvent, FingerlyEventBase, FingerlyMobileEvent, FingerlyWebEvent, Identification, IdentificationConfidence, IdentifyResult, IdentifySubmission, IdentifyTrigger, IntegrityReport, IosVerdicts, IpGeolocation, IpInfoV4, Lie, MobileFingerlyOptions, MobileIdentifyOptions, MobileVerdicts, NativeIdentifyResult, NativeVerdicts, SdkPlatform, SignalOutcome, SignalReport, SignalStatus, SourceTier, Velocity, VelocityWindow, Verdict, Verdicts };
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 };
package/dist/index.d.ts CHANGED
@@ -109,6 +109,10 @@ interface Lie {
109
109
  interface EngineIdentity {
110
110
  claimed?: string;
111
111
  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
+ */
112
116
  agrees?: boolean;
113
117
  }
114
118
  /** The tamper layer's findings. Raw; the server decides what they are worth. */
@@ -139,141 +143,38 @@ interface SignalReport {
139
143
  sources: Record<string, SignalOutcome>;
140
144
  integrity: IntegrityReport;
141
145
  }
142
- /** How sure a verdict is. Matches the server's `*_confidence` fields. */
146
+ /** How sure the server is of a finding. Matches its `*_confidence` fields. */
143
147
  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
148
  /** What a native `identify()` resolves with. See [[IdentifyResult]]. */
260
149
  interface NativeIdentifyResult {
261
150
  requestId: string;
262
151
  /** Who this visitor is. See [[IdentifyResult.visitorId]]. */
263
152
  visitorId: string;
264
- visitorIsNew: boolean;
265
- /** How sure the server is, 0 to 100. See [[IdentifyResult.visitorConfidence]]. */
266
- visitorConfidence: number;
267
- identifiable: boolean;
268
- /** True when this submission was answered before; the fields above are empty. */
269
- duplicate: boolean;
153
+ /** `null` when the server did not say, which is not the same as `false`. */
154
+ visitorIsNew: boolean | null;
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]].
158
+ */
159
+ visitorConfidence: number | null;
160
+ /** `null` when the server did not say. */
161
+ identifiable: boolean | null;
162
+ /**
163
+ * True when this submission was answered before; the fields above are empty.
164
+ * `null` when the server did not say.
165
+ */
166
+ duplicate: boolean | null;
270
167
  state: string;
271
- reason: string;
272
- /** `null` when the submission was not scored, which is not the same as zero. */
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
+ /** `null` when absent: unscored, or hidden by the SDK key. Not the same as zero. */
273
175
  suspectScore: number | null;
176
+ /** `null` when absent, for the same reasons as [[suspectScore]]. */
274
177
  suspectLevel: string | null;
275
- triggers: IdentifyTrigger[];
276
- verdicts: MobileVerdicts;
277
178
  report: SignalReport;
278
179
  }
279
180
  /** A submission, as the body of `POST /api/v1/ingest`. */
@@ -306,7 +207,6 @@ type DeferredIdentifyResult = {
306
207
  status: 'submitted';
307
208
  report: SignalReport;
308
209
  combinedReport: SignalReport;
309
- verdicts: Verdicts;
310
210
  } | {
311
211
  status: 'skipped';
312
212
  /**
@@ -319,7 +219,6 @@ type DeferredIdentifyResult = {
319
219
  error: Error;
320
220
  report?: SignalReport;
321
221
  combinedReport?: SignalReport;
322
- verdicts?: Verdicts;
323
222
  };
324
223
  /**
325
224
  * The answer.
@@ -377,47 +276,38 @@ interface IdentifyResult {
377
276
  duplicate: boolean;
378
277
  /** `enriched`, or `unavailable` when the address could not be looked up. */
379
278
  state: string;
380
- /** Why enrichment did not happen, as a short stable token. Empty otherwise. */
381
- reason: string;
279
+ /**
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.
287
+ */
288
+ reason?: string;
382
289
  /**
383
290
  * The weighted sum of the signals that fired, under the weights in force when
384
291
  * this submission was scored.
385
292
  *
386
- * `null` when the submission was not scored, which is a different answer from
387
- * zero: an ordinary visitor scores zero, and one whose enrichment never ran
388
- * has no score at all. Anything computed as a share of your traffic divides
389
- * by one of those two populations, so collapsing them makes the number
390
- * plausible and wrong.
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.
391
299
  *
392
300
  * Not a percentage and not capped. Normalising it to 0-100 would discard the
393
301
  * difference between "over the line" and "far over the line".
394
302
  */
395
303
  suspectScore: number | null;
396
- /** `low`, `medium` or `high`. `null` exactly when [[suspectScore]] is. */
304
+ /** `low`, `medium` or `high`. `null` when absent, as [[suspectScore]]. */
397
305
  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
306
  /** The report that was sent, for debugging and for offline callers. */
403
307
  report: SignalReport;
404
308
  /** Completion of the non-authoritative second-tier collection and upload. */
405
309
  deferred: Promise<DeferredIdentifyResult>;
406
310
  }
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
311
  interface IdentificationConfidence {
422
312
  score: number;
423
313
  version: string;
@@ -521,4 +411,4 @@ interface FingerlyWebEvent extends FingerlyEventBase {
521
411
  }
522
412
  type FingerlyEvent = FingerlyMobileEvent | FingerlyWebEvent;
523
413
 
524
- export type { AndroidVerdicts, Confidence, ConsentState, DeferredIdentifyResult, DeferredSubmission, EngineIdentity, FingerlyEvent, FingerlyEventBase, FingerlyMobileEvent, FingerlyWebEvent, Identification, IdentificationConfidence, IdentifyResult, IdentifySubmission, IdentifyTrigger, IntegrityReport, IosVerdicts, IpGeolocation, IpInfoV4, Lie, MobileFingerlyOptions, MobileIdentifyOptions, MobileVerdicts, NativeIdentifyResult, NativeVerdicts, SdkPlatform, SignalOutcome, SignalReport, SignalStatus, SourceTier, Velocity, VelocityWindow, Verdict, Verdicts };
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 };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fingerly/types",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
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/sdk-types.git"
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": "./src/index.ts",
17
+ "types": "./dist/index.d.ts",
17
18
  "exports": {
18
19
  ".": {
19
- "types": "./src/index.ts",
20
- "import": "./dist/index.js",
21
- "require": "./dist/index.cjs"
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