diff --git a/docs/default-wallet.md b/docs/default-wallet.md index c2cf7cc..2166ff1 100644 --- a/docs/default-wallet.md +++ b/docs/default-wallet.md @@ -1,18 +1,18 @@ --- -sidebar_position: 3 +sidebar_position: 5 --- # Default Wallet setting -Dapps work by communicating with a special object that Brave Wallet and extensions like MetaMask provide named `window.ethereum`. -Only one wallet can provide `window.ethereum` to websites. -In Brave, we expose a setting in `brave://settings/wallet` to be able to change which wallet provides `window.ethereum`. +We expose a setting in `brave://settings/wallet` to control how Brave makes the provider objects available (`window.ethereum` and `window.braveSolana` and its alias `window.solana`) + +Since extensions sometimes also provide these objects, this setting will help decide which wallet handles these objects. Here's a description of each setting: -- Brave Wallet (Prefer extensions) - This is the default. Brave Wallet will expose `window.ethereum` but allow other extensions such as MetaMask to overwrite it. -- Brave Wallet - Exposes `window.ethereum` and prevents sites and extensions from changing `window.ethereum`. -- Crypto Wallets (Deprecated) - Gives access to the old deprecated wallet. This option is not compatible with other extensions such as MetaMask. -- None - `window.ethereum` will not be provided by Brave Wallet at all. If you have enabled an extension such as MetaMask, it is free to use `window.ethereum`. +- `Brave Wallet (Prefer extensions)` - This is the default. Brave Wallet will expose `window.ethereum` and `window.braveSolana` but allow other extensions such as MetaMask to overwrite it. +- `Brave Wallet` - Exposes `window.ethereum` and `window.braveSolana` and prevents sites and extensions from changing them. +- `Crypto Wallets (Deprecated)` - Gives access to the old deprecated wallet. This option is not compatible with other extensions such as MetaMask. +- `None` - `window.ethereum` and `window.braveSolana` will not be provided by Brave Wallet at all. If you have enabled an extension such as MetaMask, it is free to use the provider object. After changing the default wallet, it is best to restart your browser. Why? - If you had Crypto Wallets loaded, it won't be unloaded until the next restart. When Crypto Wallets is loaded it will not work properly with other extensions trying to access `window.ethereum`. diff --git a/docs/ethereum/_category_.json b/docs/ethereum/_category_.json index 6ded37c..28ef1bc 100644 --- a/docs/ethereum/_category_.json +++ b/docs/ethereum/_category_.json @@ -1,4 +1,4 @@ { "label": "Ethereum", - "position": 4 + "position": 5 } diff --git a/docs/ethereum/overview.md b/docs/ethereum/overview.md index 029c79d..ce772d0 100644 --- a/docs/ethereum/overview.md +++ b/docs/ethereum/overview.md @@ -5,7 +5,8 @@ slug: /ethereum # Overview -Brave injects a `windows.ethereum` provider object on all pages. +Brave injects a `windows.ethereum` provider object on secure sites [in these cases](/provider-availability). + This object is defined by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193). The in-page provider will not be provided by Brave in private and Tor window. diff --git a/docs/provider-availability.md b/docs/provider-availability.md new file mode 100644 index 0000000..fee62f4 --- /dev/null +++ b/docs/provider-availability.md @@ -0,0 +1,58 @@ +--- +sidebar_position: 3 +--- + +# Restrictions for providers +The provider objects (e.g. `window.ethereum` and `window.braveSolana`) are not provided in all contexts. + +Historically the web has had a notion of “powerful" APIs like geolocation and camera/microphone, which are subject to additional security restrictions. See for instance https://www.w3.org/TR/secure-contexts/. + +Because they allow websites to request access to user funds, new web3 APIs like `window.ethereum` and `window.braveSolana` are subject to the same restrictions as other powerful APIs like `geolocation` in Brave. +As a rule of thumb, if a context is not allowed to request access to geolocation, `window.ethereum` and `window.braveSolana` are `undefined` in the same contexts. + +Provider objects are not accessible in private and Tor window. + + +## Restrictions for insecure contexts + +Only “secure origins" as defined in https://www.chromium.org/Home/chromium-security/prefer-secure-origins-for-powerful-new-features/#definitions have access to `window.ethereum` and `window.braveSolana`. +This can be checked using `window.isSecureContext`, including inside iframes. +Secure contexts include sites that are served from HTTPS but also HTTP `localhost`. + +## Restrictions in iframes + +By default the provider objects are not exposed to 3p iframes. +Brave exposes 2 new [feature policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Feature_Policy/Using_Feature_Policy) for Ethereum and Solana named `ethereum` and `solana` respectively. + +`window.ethereum` and `window.braveSolana` are blocked in an iframe if `window.isSecureContext` is `false` in that iframe. + +In addition: + +1. If the iframe is third party to the top-level origin, it will be blocked UNLESS the iframe has the `allow="{solana/ethereum}"` attribute (where “solana" and “ethereum" values control the corresponding API permissions). +2. If the iframe is first party to the top-level origin AND the `sandbox` attribute is set on the iframe, it will be blocked UNLESS `sandbox="allow-same-origin"` is set. Note "allow-same-origin"` does nothing if the iframe is third-party. +3. For security-conscious users, we add a setting to block window.{ethereum,solana} in ALL iframes, regardless of origin or attributes. This matches the default behavior on iOS. + +### iOS +Currently on iOS, `window.ethereum` and `window.braveSolana` are both undefined in all iframes. + +## Example cases + +In all these cases, the `window.ethereum` or `window.braveSolana` request is coming from the innermost iframe. +- Top level `http://a.com` -> blocked (insecure) +- Top level `https://a.com` -> allowed +- Top level `https://a.com` with `