-
Notifications
You must be signed in to change notification settings - Fork 94
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add documentation for Ethereum and Solana feature policies #62
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| { | ||
| "label": "Ethereum", | ||
| "position": 4 | ||
| "position": 5 | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
bbondy marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Top level `http://a.com` -> blocked (insecure) | ||
| - Top level `https://a.com` -> allowed | ||
| - Top level `https://a.com` with `<iframe src="http://a.com/">` -> blocked (insecure/3p) | ||
| - Top level `http://a.com` with `<iframe src="https://a.com/">` -> blocked (insecure/3p) | ||
| - Top level `https://a.com` with `<iframe src="https://a.com">` -> allowed | ||
| - Top level `https://a.com` with `<iframe src="https://b.com">` -> blocked (3p) | ||
| - Top level `https://b.com` with `<iframe src="http://a.com/">` with `<iframe src="https://b.com">` -> blocked (insecure) | ||
| - Top level `https://b.com` with `<iframe src="https://a.com">` with `<iframe src="https://b.com">` -> blocked (3p) | ||
| - Top level `https://a.com` with `<iframe src="https://b.a.com">` -> blocked (3p) | ||
| - Top level `https://a.com` with `<iframe src="https://b.a.com" allow="ethereum">` -> ethereum allowed, solana blocked | ||
| - Top level `https://a.com` with `<iframe src="https://b.com" allow="ethereum">` -> ethereum allowed, solana blocked | ||
| - Top level `https://a.com` with `<iframe src="https://b.a.com" allow="ethereum; solana">` -> ethereum allowed, solana allowed | ||
| - Top level `https://a.com` with `<iframe src="https://a.com" sandbox>` -> blocked (sandbox) | ||
| - Top level `https://a.com` with `<iframe src="https://a.com" sandbox="allow-same-origin allow-scripts">` -> allowed (but note this case is discouraged in https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-sandbox because it’d allow the iframe to remove its own sandbox attribute) | ||
| - Top level `data://foo with <iframe src="data://bar">` -> blocked (insecure) | ||
| - Top level `file://foo with <iframe src="file://bar">` -> blocked (3p) | ||
| - Top level `https://a.com` with `<iframe src="https://b.com" sandbox="allow-same-origin allow-scripts">` -> blocked (3p) | ||
| - Top level `https://a.com` with `<iframe src="https://b.com" sandbox="allow-scripts" allow="ethereum; solana">` -> ethereum allowed, solana allowed | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| sidebar_position: 2 | ||
| --- | ||
|
|
||
| # Provider objects | ||
|
|
||
| Dapps work by communicating with a special object named a provider object exposed to websites. | ||
| - For Ethereum that object is `window.ethereum`. | ||
| - For Solana that object is `window.braveSolana` (`window.solana` is an alias). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| { | ||
| "label": "Solana", | ||
| "position": 5 | ||
| "position": 6 | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is the first time I've seen
window.braveSolana. What's the motivation for moving this and keeping the alias or was it always like this in the first place?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is somewhat recent but not related to security. To get in Solana's wallet adapter repo they would not accept
window.solanaso we needed to rename towindow.braveSolanaand we retain an alias to that ofwindow.solanafor now.anza-xyz/wallet-adapter#445 (comment)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for linking to that thread, it's not fully clear to me about their motivations but it's excellent context for me if the conversation comes up again in the future and I need to reference back to it in order to find out more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep! Apologies for not highlighting that to you earlier.