EIPs/eip-1102.md at 33454e3e749bb24e789558c9801f56555fbb64cb

5.1 KiB

Raw Blame History

eip	title	author	discussions-to	status	type	category	created
1102	Opt-in web3 access	Paul Bouchon <mail@bitpshr.net>	https://ethereum-magicians.org/t/opt-in-web3-access/414	Draft	Standards Track	Interface	2018-05-04

Simple summary

This proposal describes a new way for DOM environments to expose the web3 API that requires user approval.

Abstract

MetaMask and most other tools that provide access to web3-enabled environments do so automatically and without user consent. This exposes users of such environments to fingerprinting attacks since untrusted websites can check for a web3 object and reliably identify web3-enabled clients.

This proposal outlines a new protocol in which dapps request access to the web3 API instead of relying on its preexistence in a given DOM environment.

Specification

Typical dapp initialization

START dapp
IF web3 is defined
    CONTINUE dapp
IF web3 is undefined
    STOP dapp

Proposed dapp initialization

START dapp
IF web3 is defined
    CONTINUE dapp
IF web3 is undefined
    REQUEST[1] web3 API
    IF user approves
        INJECT[2] web3 API
        NOTIFY[3] dapp
        CONTINUE dapp
    IF user rejects
    IF non-web3 environment
        NOOP[4]

`[1] REQUEST`

Dapps MUST request the web3 API by sending a message using window.postMessage API. This message MUST be sent with a payload object containing a type property with a value of “WEB3_API_REQUEST” and an optional id property corresponding to an identifier of a specific wallet provider, such as "METAMASK".

`[2] INJECT`

Dapp browsers should inject the web3 API using an implementation-specific strategy that can expose the web3 API to the user’s browser context, such as HTML script tag injection.

`[3] NOTIFY`

Dapps browsers MUST notify dapps of successful web3 exposure by sending a message using window.postMessage API. This message MUST be sent with a payload object containing a type property with a value of “WEB3_API_SUCCESS" and an optional id property corresponding to an identifier of a specific wallet provider, such as "METAMASK".

`[4] NOOP`

If a user rejects web3 access on an untrusted site, the site itself MUST NOT be notified in any way; notification of a rejection would allow third-party tools to still identify that a client is web3-enabled despite not being granted web3 access.

Example implementation: `postMessage`

The following example demonstrates one possible implementation of this strategy in a browser-based DOM environment. Note that web3 environments on other platforms would most likely use platform-specific native messaging protocols, not postMessage.

if (typeof web3 !== 'undefined') {
    // web3 API defined, start dapp
} else {
    window.addEventListener('message', function (event) {
        if (!event.data || !event.data.type) { return; }
        if (event.data.type === 'WEB3_API_SUCCESS') {
            // web3 API defined, start dapp
        }
    });
    // request web3 API
    window.postMessage({ type: 'WEB3_API_REQUEST' });
}

Rationale

An open issue against the MetaMask extension has received community upvotes and Richard Burton of the Balance team published a well-received blog post discussing these potential changes.

Constraints

Web3 MUST NOT be exposed to websites by default.
Dapps MUST request web3 if it does not exist.
Users MUST be able to approve or reject web3 access.
Web3 MUST be exposed to websites after user consent.
Environments MAY continue auto-exposing web3 if users can disable this behavior.

Immediate value-add

Users can reject web3 access on untrusted sites to prevent web3 fingerprinting.

Long-term value-add

Dapps could request specific account information based on user consent.
Dapps could request specific user information based on user consent (uPort, DIDs).
Dapps could request a specific network based on user consent.
Dapps could request multiple instances of the above based on user consent.

Backwards compatibility

This proposal impacts dapp authors and requires that they request access to the web3 API before using it. This proposal also impacts developers of web3-enabled environments or dapp browsers as these tools should no longer auto-expose the web3 API; instead, they should only do so if a website requests the API and if the user consents to its access. Environments may continue to auto-expose the web3 API as long as users have the ability to disable this behavior.

Implementation

The MetaMask team is currently working an MVP implementation of the strategy described above and expects to begin limited user testing soon.

5.1 KiB Raw Blame History Unescape Escape