@fingerly/web-js 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,13 +1,8 @@
1
1
  import { Source, SignalOutcome, IntegrityReport, FingerlyClientOptions, FingerlyClient } from '@fingerly/core';
2
- export { Confidence, ConsentError, ConsentState, FingerlyClient, FingerlyEvent, FingerlyWebEvent, IdentifyOptions, IdentifyResult, IntegrityReport, Lie, SOURCE, SignalOutcome, SignalReport, SignalStatus, TransportError, isSuspiciousLevel } from '@fingerly/core';
2
+ export { CollectOptions, Confidence, ConsentError, ConsentState, EventState, FingerlyClient, IdentifyOptions, IdentifyResult, IdentifySubmission, IdentifyTrigger, IncognitoDetection, IntegrityReport, Lie, LieKind, RiskSignal, SOURCE, SdkPlatform, Signal, SignalOutcome, SignalReport, SignalStatus, SourceOptIn, SourceStage, SuspectLevel, TransportError, WorkerRealmSignal, isSuspiciousLevel } from '@fingerly/core';
3
3
 
4
4
  /**
5
- * The browser source set.
6
- *
7
- * Order within a tier does not matter - the scheduler runs them concurrently up
8
- * to its cap - but the tier does. `fast` sources are cheap reads that a page
9
- * can afford to block a click on; `deferred` sources render, measure layout or
10
- * await hardware, and are worth having only because the budget bounds them.
5
+ * The single-pass two-stage browser source set (`prerequisite` -> `collect`).
11
6
  */
12
7
 
13
8
  declare const browserSources: readonly Source[];
@@ -18,8 +13,24 @@ declare const browserSources: readonly Source[];
18
13
  * A page inside a customer's own app is the app reading the device. Apple's
19
14
  * agreement forbids an app to "derive any data from a device for the purpose
20
15
  * of uniquely identifying it", naming the properties of a web browser among
21
- * that data, so the browser SDK collects nothing there. Use the iOS or Android
22
- * SDK in an app instead.
16
+ * that data, so the browser SDK runs no device-fingerprinting source there.
17
+ * Use the iOS or Android SDK in an app instead.
18
+ *
19
+ * What it does collect in an app is the embedded profile
20
+ * (`EMBEDDED_SAFE_SOURCES` in `@fingerly/core`), which exists so the server
21
+ * can tell a genuine app WebView from a desktop or automated browser that
22
+ * claims to be one:
23
+ *
24
+ * - `embedding`: the kind of app detected (`{ kind }`), nothing else.
25
+ * - `engine`, `math`, `errors`: how the JavaScript engine behaves (error
26
+ * message lengths, maths results, CSS support), no device values.
27
+ * - `navigator`: `user_agent`, `platform` and `webdriver` only.
28
+ * - `worker_realm`: the worker's `user_agent` and `platform` only.
29
+ * - `automation`: `webdriver` and the names of automation globals present.
30
+ * - the integrity block: which natives and descriptors were tampered with.
31
+ *
32
+ * Core count, device memory, languages, time zone, plugins, screen, GPU,
33
+ * canvas, audio, fonts and storage are not read in an app.
23
34
  *
24
35
  * The rules are the table in the server's ADR 0024 (Appendix B), which the
25
36
  * server applies to every report as well. Rows shared with the server are
@@ -45,47 +56,20 @@ interface EmbeddingEnvironment {
45
56
  declare function detectEmbedding(environment?: EmbeddingEnvironment): string | undefined;
46
57
 
47
58
  /**
48
- * The tamper layer.
49
- *
50
- * Runs after collection, over the outcomes, and produces the
51
- * [[IntegrityReport]] that goes on the wire beside them. It is not a source,
52
- * for two reasons: it reads what the other sources produced, so it cannot run
53
- * beside them; and a tamper check that competed for the budget could be starved
54
- * by a slow source, which is precisely the outcome an attacker would arrange.
59
+ * The tamper layer (`F-11`).
55
60
  *
56
- * What it reports is raw: which natives are patched, which properties were
57
- * redefined. Whether the reported values contradict each other - a user agent
58
- * claiming a phone that hovers, a language that is not the first of its own
59
- * languages - is the server's reading of the same sources, not something the
60
- * page decides.
61
+ * Runs after collection over the gathered outcomes and produces the
62
+ * [[IntegrityReport]] that goes on the wire alongside `sources`.
61
63
  */
62
64
 
63
65
  declare function inspectIntegrity(sources: Record<string, SignalOutcome>): IntegrityReport;
64
66
 
65
67
  /**
66
- * @fingerly/web-js - the browser SDK.
68
+ * @fingerly/web-js - the browser SDK (`v: 3`, single-pass).
67
69
  *
68
70
  * Wires the browser source set and the tamper layer into `@fingerly/core`'s
69
- * client. Everything platform-specific is in this package; scheduling and
70
- * transport are in the kernel, and scoring is on the server, where customers
71
- * set the weights and a page cannot read or edit them.
72
- *
73
- * ```ts
74
- * import { load } from '@fingerly/web-js'
75
- *
76
- * const fingerly = await load({ apiKey: 'fly_pk_production_…' })
77
- * const { visitorId, visitorIsNew, suspectLevel } = await fingerly.identify()
78
- *
79
- * // The server's answer, in the same round trip. Everything about the score
80
- * // lives on the server, under the weights you set. `suspectLevel` is null
81
- * // when absent, which is not a clean result. Signals are read on your backend.
82
- * if (suspectLevel === 'high') {
83
- * // step up to a challenge
84
- * }
85
- * ```
86
- *
87
- * Nothing about that decision happens in the page. This package collects and
88
- * submits; the server scores.
71
+ * single-pass v3 client. Everything platform-specific is in this package;
72
+ * scheduling and transport are in the kernel, and scoring is on the server.
89
73
  */
90
74
 
91
75
  interface FingerlyOptions extends Omit<FingerlyClientOptions, 'sources' | 'integrity' | 'platform' | 'embedding'> {
@@ -97,18 +81,6 @@ interface FingerlyOptions extends Omit<FingerlyClientOptions, 'sources' | 'integ
97
81
  }
98
82
  /**
99
83
  * Build a client with the browser sources installed.
100
- *
101
- * Async, and returns a promise, even though there is currently nothing to
102
- * await. That is deliberate: the shape callers write today is the shape that
103
- * still works when this needs to warm a worker or wait for a document to be
104
- * ready, and changing `load()` from sync to async later would break every
105
- * integration at once.
106
- *
107
- * Loading collects nothing and sends nothing, whatever `consent` is: no
108
- * source runs until `identify()` or `collect()` is called, and those refuse
109
- * while consent is not `granted`. Consent defaults to `pending`, so a page can
110
- * load early and call `setConsent('granted')` from its consent tool, or pass
111
- * `consent: 'granted'` once it already has consent (or know none is required here; see docs/privacy.md §4).
112
84
  */
113
85
  declare function load(options: FingerlyOptions): Promise<FingerlyClient>;
114
86
 
package/dist/index.d.ts CHANGED
@@ -1,13 +1,8 @@
1
1
  import { Source, SignalOutcome, IntegrityReport, FingerlyClientOptions, FingerlyClient } from '@fingerly/core';
2
- export { Confidence, ConsentError, ConsentState, FingerlyClient, FingerlyEvent, FingerlyWebEvent, IdentifyOptions, IdentifyResult, IntegrityReport, Lie, SOURCE, SignalOutcome, SignalReport, SignalStatus, TransportError, isSuspiciousLevel } from '@fingerly/core';
2
+ export { CollectOptions, Confidence, ConsentError, ConsentState, EventState, FingerlyClient, IdentifyOptions, IdentifyResult, IdentifySubmission, IdentifyTrigger, IncognitoDetection, IntegrityReport, Lie, LieKind, RiskSignal, SOURCE, SdkPlatform, Signal, SignalOutcome, SignalReport, SignalStatus, SourceOptIn, SourceStage, SuspectLevel, TransportError, WorkerRealmSignal, isSuspiciousLevel } from '@fingerly/core';
3
3
 
4
4
  /**
5
- * The browser source set.
6
- *
7
- * Order within a tier does not matter - the scheduler runs them concurrently up
8
- * to its cap - but the tier does. `fast` sources are cheap reads that a page
9
- * can afford to block a click on; `deferred` sources render, measure layout or
10
- * await hardware, and are worth having only because the budget bounds them.
5
+ * The single-pass two-stage browser source set (`prerequisite` -> `collect`).
11
6
  */
12
7
 
13
8
  declare const browserSources: readonly Source[];
@@ -18,8 +13,24 @@ declare const browserSources: readonly Source[];
18
13
  * A page inside a customer's own app is the app reading the device. Apple's
19
14
  * agreement forbids an app to "derive any data from a device for the purpose
20
15
  * of uniquely identifying it", naming the properties of a web browser among
21
- * that data, so the browser SDK collects nothing there. Use the iOS or Android
22
- * SDK in an app instead.
16
+ * that data, so the browser SDK runs no device-fingerprinting source there.
17
+ * Use the iOS or Android SDK in an app instead.
18
+ *
19
+ * What it does collect in an app is the embedded profile
20
+ * (`EMBEDDED_SAFE_SOURCES` in `@fingerly/core`), which exists so the server
21
+ * can tell a genuine app WebView from a desktop or automated browser that
22
+ * claims to be one:
23
+ *
24
+ * - `embedding`: the kind of app detected (`{ kind }`), nothing else.
25
+ * - `engine`, `math`, `errors`: how the JavaScript engine behaves (error
26
+ * message lengths, maths results, CSS support), no device values.
27
+ * - `navigator`: `user_agent`, `platform` and `webdriver` only.
28
+ * - `worker_realm`: the worker's `user_agent` and `platform` only.
29
+ * - `automation`: `webdriver` and the names of automation globals present.
30
+ * - the integrity block: which natives and descriptors were tampered with.
31
+ *
32
+ * Core count, device memory, languages, time zone, plugins, screen, GPU,
33
+ * canvas, audio, fonts and storage are not read in an app.
23
34
  *
24
35
  * The rules are the table in the server's ADR 0024 (Appendix B), which the
25
36
  * server applies to every report as well. Rows shared with the server are
@@ -45,47 +56,20 @@ interface EmbeddingEnvironment {
45
56
  declare function detectEmbedding(environment?: EmbeddingEnvironment): string | undefined;
46
57
 
47
58
  /**
48
- * The tamper layer.
49
- *
50
- * Runs after collection, over the outcomes, and produces the
51
- * [[IntegrityReport]] that goes on the wire beside them. It is not a source,
52
- * for two reasons: it reads what the other sources produced, so it cannot run
53
- * beside them; and a tamper check that competed for the budget could be starved
54
- * by a slow source, which is precisely the outcome an attacker would arrange.
59
+ * The tamper layer (`F-11`).
55
60
  *
56
- * What it reports is raw: which natives are patched, which properties were
57
- * redefined. Whether the reported values contradict each other - a user agent
58
- * claiming a phone that hovers, a language that is not the first of its own
59
- * languages - is the server's reading of the same sources, not something the
60
- * page decides.
61
+ * Runs after collection over the gathered outcomes and produces the
62
+ * [[IntegrityReport]] that goes on the wire alongside `sources`.
61
63
  */
62
64
 
63
65
  declare function inspectIntegrity(sources: Record<string, SignalOutcome>): IntegrityReport;
64
66
 
65
67
  /**
66
- * @fingerly/web-js - the browser SDK.
68
+ * @fingerly/web-js - the browser SDK (`v: 3`, single-pass).
67
69
  *
68
70
  * Wires the browser source set and the tamper layer into `@fingerly/core`'s
69
- * client. Everything platform-specific is in this package; scheduling and
70
- * transport are in the kernel, and scoring is on the server, where customers
71
- * set the weights and a page cannot read or edit them.
72
- *
73
- * ```ts
74
- * import { load } from '@fingerly/web-js'
75
- *
76
- * const fingerly = await load({ apiKey: 'fly_pk_production_…' })
77
- * const { visitorId, visitorIsNew, suspectLevel } = await fingerly.identify()
78
- *
79
- * // The server's answer, in the same round trip. Everything about the score
80
- * // lives on the server, under the weights you set. `suspectLevel` is null
81
- * // when absent, which is not a clean result. Signals are read on your backend.
82
- * if (suspectLevel === 'high') {
83
- * // step up to a challenge
84
- * }
85
- * ```
86
- *
87
- * Nothing about that decision happens in the page. This package collects and
88
- * submits; the server scores.
71
+ * single-pass v3 client. Everything platform-specific is in this package;
72
+ * scheduling and transport are in the kernel, and scoring is on the server.
89
73
  */
90
74
 
91
75
  interface FingerlyOptions extends Omit<FingerlyClientOptions, 'sources' | 'integrity' | 'platform' | 'embedding'> {
@@ -97,18 +81,6 @@ interface FingerlyOptions extends Omit<FingerlyClientOptions, 'sources' | 'integ
97
81
  }
98
82
  /**
99
83
  * Build a client with the browser sources installed.
100
- *
101
- * Async, and returns a promise, even though there is currently nothing to
102
- * await. That is deliberate: the shape callers write today is the shape that
103
- * still works when this needs to warm a worker or wait for a document to be
104
- * ready, and changing `load()` from sync to async later would break every
105
- * integration at once.
106
- *
107
- * Loading collects nothing and sends nothing, whatever `consent` is: no
108
- * source runs until `identify()` or `collect()` is called, and those refuse
109
- * while consent is not `granted`. Consent defaults to `pending`, so a page can
110
- * load early and call `setConsent('granted')` from its consent tool, or pass
111
- * `consent: 'granted'` once it already has consent (or know none is required here; see docs/privacy.md §4).
112
84
  */
113
85
  declare function load(options: FingerlyOptions): Promise<FingerlyClient>;
114
86