mirror of https://github.com/status-im/EIPs.git
120 lines
5.1 KiB
Markdown
120 lines
5.1 KiB
Markdown
---
|
||
eip: 1102
|
||
title: Opt-in web3 access
|
||
author: Paul Bouchon <mail@bitpshr.net>
|
||
discussions-to: https://ethereum-magicians.org/t/opt-in-web3-access/414
|
||
status: Draft
|
||
type: Standards Track
|
||
category: Interface
|
||
created: 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`](https://developer.mozilla.org/en-US/docs/Web/API/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`](https://developer.mozilla.org/en-US/docs/Web/API/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`.
|
||
|
||
```js
|
||
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](https://github.com/MetaMask/metamask-extension/issues/714) against the [MetaMask](https://github.com/MetaMask/metamask-extension) extension has received community upvotes and Richard Burton of the [Balance](https://github.com/balance-io) team published a well-received [blog post](https://medium.com/@ricburton/metamask-walletconnect-js-b47857efb4f7) 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](https://github.com/MetaMask/metamask-extension/issues/3930) of the strategy described above and expects to begin limited user testing soon.
|
||
|
||
## Copyright
|
||
|
||
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
|