EIP: Opt-in web3 access (#1102)

* Initial draft * Strengthen constraint language and add noop logic path * Add identifier property to web3 request payload * Update example to remove error case * Add identifier to web3 response payload for filtering * Concretely detail DOM-specific APIs * Update and rename eip-web3-access.md to eip-1102.md * Remove unnecessary constraint link
2025-01-27 07:05:47 +00:00 · 2018-06-01 06:42:51 -04:00 · 2018-06-01 06:42:51 -04:00 · a130a27220
commit a130a27220
parent 3d00a3b97d
1 changed files with 119 additions and 0 deletions
--- a/EIPS/eip-1102.md
+++ b/EIPS/eip-1102.md
@ -0,0 +1,119 @@
+---
+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/).