1. Use cases and requirements

This document attempts to address the requirements from the Review of Apps that Use Network Information . Those are:

• Provide access to the connection type the system is using to communicate with the network (e.g., cellular, bluetooth, ethernet, wifi, other, or none). This information needs to be available either immediately on page load or as close as possible to it.
• Provide a means for scripts to be notified if the connection type changes. This is to allow developers to make dynamic changes to the DOM and/or inform the user that the network connection type has changed (and that it could impact them in some way).

3. Definitions

For clarity, a megabit is 1,000,000 bits, and megabits per second is equivalent to transferring:

• 1,000,000 bits per second
• 1,000 kilobits per second
• 125,000 bytes per second
• 125 kilobytes per second
• and so on...

4. Connection types

enum ConnectionType {
    "bluetooth",
    "cellular",
    "ethernet",
    "mixed",
    "none",
    "other",
    "unknown",
    "wifi",
    "wimax"
};

enum EffectiveConnectionType {
    "2g",
    "3g",
    "4g",
    "slow-2g"
};

5. NavigatorNetworkInformation interface

The NavigatorNetworkInformation interface exposes access to NetworkInformation interface by extending the Navigator and WorkerNavigator interface.

[NoInterfaceObject,
 Exposed=(Window,Worker)]
interface NavigatorNetworkInformation {
    readonly attribute NetworkInformation connection;
};
Navigator implements NavigatorNetworkInformation;
WorkerNavigator implements NavigatorNetworkInformation;

6. NetworkInformation interface

The NetworkInformation interface provides a means to access information about the network connection the user agent is currently using. The EventTarget is defined in [ DOM ].

[Exposed=(Window,Worker)]
interface NetworkInformation : EventTarget {
    readonly attribute ConnectionType          type;
    readonly attribute EffectiveConnectionType effectiveType;
    readonly attribute Megabit                 downlinkMax;
    readonly attribute Megabit                 downlink;
    readonly attribute Millisecond             rtt;
             attribute EventHandler            onchange;
};
typedef unrestricted double Megabit;
typedef unsigned long long Millisecond;

7. Underlying connection technology

The relationship between an underlying connection technology and its upper bound on the downlink speed of the first network hop is determined by the available network interfaces that may be used to fulfill new network requests.

The downlinkMax for an available interface is determined via the standardized, or generally accepted, maximum download data rate captured in the table of maximum downlink speeds . Where possible, this value may be refined to report a more accurate upper bound based on current properties of the interface - e.g. signal strength, modulation algorithm, and other "network weather" variables.

The upper bound on the downlink speed of the first network hop is determined by the rules described in handling changes to the underlying connection .

8. Privacy Considerations

The Network Information API exposes information about the observed network bandwidth, latency and the first network hop between the user agent and the server; specifically, the type of connection and the upper bound of the downlink speed, as well as signals whenever this information changes. Such information may be used to:

• Fingerprint a user based on characteristics of a particular network (e.g. type and downlink estimates) at a point in time, and by observing change in such characteristics over a period of time.
• Fingerprint a user based on transitions between one or more networks (e.g. based on order of transitions by type, downlink estimates, and time).
• Infer user location (e.g. are they home, at work, or in transit) based on above criteria.

However, above considerations are not new, and sufficiently motivated attackers may already obtain such information using other technologies:

• The attacker can use JavaScript to observe the duration (e.g. time from start of fetch to onload event) of any network fetch on the client, and may get more detailed timing data about the same fetch via the Resource Timing API.
• The attacker can use WebRTC to identify client's public and private IP addresses via STUN, or similar mechanisms.
• The attacker can observe the client IP, fetch duration, RTT, transfer speed, and other low-level socket metrics of a fetch on the server.

Further, by repeating one of the above strategies (e.g. via invoking periodic fetch or refresh of a resource; via periodic SSE or WebSocket messages; via periodic STUN requests, etc.), the attacker can observe changes over time in the performance characteristics of client's connection and IP address. Such data can then be used to refine the user fingerprint, infer users location (e.g. are they home, at work, or in transit), and extract various behavioral patterns.

The above list is not a complete overview. However, as the above examples illustrate, the attacks are possible both from the sender and the receiver:

• If the attacker can initiate or observe a network fetch of any kind from the client, then they can observe its performance characteristics and how they change over time.
• If the attacker can convince the client to fetch a resource from their server, then they can similarly observe the performance characteristics of the fetch and how they change over time.

Mitigating such attacks initiated from the client requires preventing the attacker from observing and initiating network requests - e.g., use HTTPS to prevent trivial content injection by malicious parties; disable JavaScript to prevent scripted resource fetch of any kind. Mitigating attacks from the sender is possible via the use of a VPN or an HTTP proxy - e.g. to hide the client's true IP address, to introduce additional latency, and so on.

As such, while the Network Information API makes it easier to obtain information about the first network hop, by avoiding the need to observe or make network requests, it does not expose anything that is not already available to a sufficiently-motivated attacker.

If the client wants to mitigate this class of attacks, they should disable JavaScript, monitor that all outbound requests are made to trusted origins, and make diligent use of anonymizing VPN/proxy services.

9. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY and MUST are to be interpreted as described in [ RFC2119 ].

There is only one class of product that can claim conformance to this specification: a user agent .