From db1b0eb91b33f9a4d88a6a1568d20fa61f4068a5 Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Tue, 23 Apr 2024 14:19:12 -0700 Subject: [PATCH 01/20] Fork @gudahtt 's proposal --- ...rowser_extension_provider_communication.md | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 caip-browser_extension_provider_communication.md diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md new file mode 100644 index 00000000..feb4f73b --- /dev/null +++ b/caip-browser_extension_provider_communication.md @@ -0,0 +1,123 @@ +--- +# Every document starts with a front matter in YAML enclosed by triple dashes. +# See https://jekyllrb.com/docs/front-matter/ to learn more about this concept. +caip: +title: Web extension provider communication +author: Mark Stacey (@Gudahtt), Jiexi Luan (@jiexi) +discussions-to: +status: Draft +type: Standard +created: 2022-11-28 +--- + + + +## Simple Summary + +This CAIP establishes a standard way for JSON-RPC providers to communicate with web extensions. + +## Abstract + +This CAIP establishes how providers can communicate with web extensions. Two overall strategies are described, one for `externally_connectable` web extensions, and one for `contentscript` web extensions. + +## Motivation + +Web extensions today will typically inject a JavaScript provider API into websites as a global variable. For example, in the Ethereum ecosystem this provider API is standardized in EIP-1193, and is conventionally injected as `window.ethereum`. + +This injected API strategy has some advantages: +* For websites developers, using a global variable is simple and requires no effort on their part to setup. +* It allows websites to support any web extension following this standard with no additional effort. + +However, the injected API strategy has many disadvantages: +* It depends upon the web extension having read and write access to every website, which is a scary permission that web extension authors might otherwise be able to avoid asking for. +* It slows down every website by injecting additional code to be parsed and executed. It even slows down the initial page load in most cases, because many web extensions inject the provider synchronously to maintain compatibility with websites that expect it to be available immediately. +* Injecting code into a website can break it. +* It provides no way for web extension authors to safely make breaking changes to their provider API, resulting in even more code being injected to support legacy APIs. + +An alternative strategy would be for a website to embed its own provider. A provider could be offered as a library, to be embedded by the website author. This strategy can address all disadvantages of the injected provider approach: +* If this strategy became widespread enough, it would allow some web extensions to stop asking for write access to all pages. +* The website author can control when the provider is initialized, and fine-tune performance. +* No code needs to be injected, so websites would no longer be broken by injected code. +* The provider library can be published with breaking changes, allowing changes to the API without needing to embed legacy code in each website. + +A provider library can be similarly easy to use for website authors as well, requiring nothing more than a single script tag to import a library and get an equivalent experience to using an the injected provider. + +Web extension inter-operability is a challenge for embeded providers though. That is what this proposal means to address. Today there is no way to write a provider such that it is compatible with any web extension. Web extensions differ today in how they communicate with wallets, from the messaging system used to the messaging format. These details often aren't publicly documented or treated as a public-facing API, so they can change without notice, making it risky even to embed support for popular conventions used today. + +A standard method for providers to communicate with web extebsions would allow website authors to embed their own providers without losing web extension inter-operability. + +## Specification + + +### Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" written in +uppercase in this document are to be interpreted as described in [RFC +2119](https://www.ietf.org/rfc/rfc2119.txt) + +### Summary + +Two strategies are described below; one for `externally_connectable` web extensions, and one for `contentscript` web extensions. Each strategy is intended to work with a different web extension permission. + +A web extension MUST support at least one of these strategies. A web extension MAY support multiple strategies. + +Both strategies use the same message format. + +### Message format + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/caip-x/schemas/provider-request.schema.json", + "title": "Provider / Web Extension message", + "description": "A request sent between a provider and a web extension.", + "type": "object", + "properties": { + "type": { + "description": "The message type, used to identify this as a CAIP-X message", + "const": "caip-x" + }, + "data": { + "description": "A JSON-RPC message", + "type": "object" + } + }, + "required": ["type", "data"] +} +``` + +### `externally_connectable` web extensions + +A web extension can use the `externally_connectable` manifest field to accept messages from websites. This permission can be configured to limit which sites can message the web extension. How this permission is configured is out-of-scope for this proposal; this proposal only concerns sites that the web extension allows messages from. + +A web extension can receive messages using `browser.runtime.onMessage`. Incoming messages should be validated according to the + + +The `target` field MUST be unset for all messages from either the provider or the web extension. + +The provider should send messages using `runtime.sendMessage`. + +The web extension should recieve messages using `runtime.onMessage`. + + +### `contentscript` web extensions + +The provider should send messages using the format + + +## Rationale + + + +## Backwards Compatibility + + +## Test Cases + + +## Links + + +## Copyright +Copyright and related rights waived via [CC0](../LICENSE). From b96b182e074ffa9abf81b888e6280242768fffed Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Tue, 23 Apr 2024 15:27:25 -0700 Subject: [PATCH 02/20] WIP --- ...rowser_extension_provider_communication.md | 38 ++++++++++--------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index feb4f73b..9acbf00a 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -18,7 +18,7 @@ This CAIP establishes a standard way for JSON-RPC providers to communicate with ## Abstract -This CAIP establishes how providers can communicate with web extensions. Two overall strategies are described, one for `externally_connectable` web extensions, and one for `contentscript` web extensions. +This CAIP establishes how providers can communicate with web extensions over `externally_connectable`. ## Motivation @@ -36,6 +36,7 @@ However, the injected API strategy has many disadvantages: An alternative strategy would be for a website to embed its own provider. A provider could be offered as a library, to be embedded by the website author. This strategy can address all disadvantages of the injected provider approach: * If this strategy became widespread enough, it would allow some web extensions to stop asking for write access to all pages. + * NOTE: Should mention discovery somewhere since that will require injection still * The website author can control when the provider is initialized, and fine-tune performance. * No code needs to be injected, so websites would no longer be broken by injected code. * The provider library can be published with breaking changes, allowing changes to the API without needing to embed legacy code in each website. @@ -58,11 +59,7 @@ uppercase in this document are to be interpreted as described in [RFC ### Summary -Two strategies are described below; one for `externally_connectable` web extensions, and one for `contentscript` web extensions. Each strategy is intended to work with a different web extension permission. - -A web extension MUST support at least one of these strategies. A web extension MAY support multiple strategies. - -Both strategies use the same message format. +... ### Message format @@ -87,23 +84,26 @@ Both strategies use the same message format. } ``` -### `externally_connectable` web extensions - -A web extension can use the `externally_connectable` manifest field to accept messages from websites. This permission can be configured to limit which sites can message the web extension. How this permission is configured is out-of-scope for this proposal; this proposal only concerns sites that the web extension allows messages from. - -A web extension can receive messages using `browser.runtime.onMessage`. Incoming messages should be validated according to the +### `externally_connectable` +A web extension can use the [`externally_connectable`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/externally_connectable) manifest field to accept messages from websites and other extensions. This permission can be configured to limit which sites and other extensions can send messages to the web extension. How this permission is configured is out-of-scope for this proposal; this proposal only concerns sites that the web extension allows messages from. -The `target` field MUST be unset for all messages from either the provider or the web extension. -The provider should send messages using `runtime.sendMessage`. +The web extension can: +* handle a connection from the website or other extensions by using `chrome.runtime.onConnectExternal.addListener((port) => {...})` +* send messages by using `port.posMessage()` +* receive messages by using `port.onMessage.addListener()` + * incoming messages should be validated according to the message format specification above -The web extension should recieve messages using `runtime.onMessage`. +The provider can: +* initiate a connection with the web extension by using `port = browser.runtime.connect()` +* send messages by using `port.postMessage()` +* receive messages by using `port.onMessage.addListener()` - -### `contentscript` web extensions - -The provider should send messages using the format +Caveats: +* No firefox support yet +* Extension Ids may be different across different family of browsers + * Discoverability should address this ## Rationale @@ -113,6 +113,8 @@ The provider should send messages using the format ## Backwards Compatibility +This is meant to eventually replace connection over contentscript... + ## Test Cases From 240ed2ae16b68d31901b42e78852a64dcecfd09e Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Wed, 24 Apr 2024 13:10:56 -0700 Subject: [PATCH 03/20] fleshing caip out more --- ...rowser_extension_provider_communication.md | 22 +++++++++++++------ 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 9acbf00a..fc9bbeb5 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -14,7 +14,7 @@ created: 2022-11-28 ## Simple Summary -This CAIP establishes a standard way for JSON-RPC providers to communicate with web extensions. +The proposal aims to standardize how JSON-RPC providers with web extensions communicate, making the process more efficient and secure. ## Abstract @@ -59,7 +59,7 @@ uppercase in this document are to be interpreted as described in [RFC ### Summary -... +Web extensions should expose a standard interface over [`externally_connectable`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/externally_connectable) to enable the inter-operability of embedded providers. ### Message format @@ -84,14 +84,19 @@ uppercase in this document are to be interpreted as described in [RFC } ``` +TODO: should type be more defined here? Seems weird to specify the envelop but no types it can be used with? +Does `data` need to be a JSON-RPC message specifically? +Should `type` be something besides `caip-x`? + + ### `externally_connectable` -A web extension can use the [`externally_connectable`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/externally_connectable) manifest field to accept messages from websites and other extensions. This permission can be configured to limit which sites and other extensions can send messages to the web extension. How this permission is configured is out-of-scope for this proposal; this proposal only concerns sites that the web extension allows messages from. +A web extension can use the `externally_connectable` manifest field to accept messages from websites and other extensions. This permission can be configured to limit which sites and other extensions can send messages to the web extension. How this permission is configured is out-of-scope for this proposal; this proposal only concerns sites that the web extension allows messages from. The web extension can: * handle a connection from the website or other extensions by using `chrome.runtime.onConnectExternal.addListener((port) => {...})` -* send messages by using `port.posMessage()` +* send messages by using `port.postMessage()` * receive messages by using `port.onMessage.addListener()` * incoming messages should be validated according to the message format specification above @@ -101,25 +106,28 @@ The provider can: * receive messages by using `port.onMessage.addListener()` Caveats: -* No firefox support yet +* No firefox support yet, but they are considering implementing it * Extension Ids may be different across different family of browsers * Discoverability should address this ## Rationale +While web extensions could realize the benefits of `externally_connectable` without using it with a standardized interface, this would mean that every web extension would have to ship a provider library that worked specifically for their interface and that Dapps would need to import them. It wouldn't be feasible for Dapps to import every single web extension's specific provider implementation, making this approach non-viable as it would not see widespread adoption. +Web extension inter-operability is the key to enabling generalized provider implementations. This allows Dapps to import a single library to connect to numerous web extensions. ## Backwards Compatibility - -This is meant to eventually replace connection over contentscript... +This CAIP does not require discontinuing usage of contentscript. It is RECOMMENDED that wallets start implementing this alternative connection strategy and encouraging it's usage so that the ecosystem can eventually remove contentscript injection entirely. As an optional transitionary step, wallets can migrate their injected provider to start making connections over `externally_connectable` with no user-facing impact (not sure if true since this has caveats). ## Test Cases ## Links +* [externally_connectable](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/externally_connectable) +* [Mozilla bug report: "Implement externally_connectable from a website"](https://bugzilla.mozilla.org/show_bug.cgi?id=1319168) ## Copyright Copyright and related rights waived via [CC0](../LICENSE). From c6095927b59f23e426c3f804b1e7e83d0d43a914 Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Wed, 24 Apr 2024 13:54:52 -0700 Subject: [PATCH 04/20] Rationale. Add missing sections --- caip-browser_extension_provider_communication.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index fc9bbeb5..bbba28ba 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -113,17 +113,23 @@ Caveats: ## Rationale -While web extensions could realize the benefits of `externally_connectable` without using it with a standardized interface, this would mean that every web extension would have to ship a provider library that worked specifically for their interface and that Dapps would need to import them. It wouldn't be feasible for Dapps to import every single web extension's specific provider implementation, making this approach non-viable as it would not see widespread adoption. +While web extensions could realize the benefits of `externally_connectable` without using it with a standardized interface, this would mean that every web extension would have to ship a provider library that worked specifically for their interface and that Dapps would need to import them. It wouldn't be feasible for Dapps to import every single web extension's specific provider implementation, making this approach less viable. -Web extension inter-operability is the key to enabling generalized provider implementations. This allows Dapps to import a single library to connect to numerous web extensions. +Web extension inter-operability is the key to enabling generalized provider implementations. Generalized provider implementations allows for convenient adoption by Dapps, leading to more wide spread adoption of the standard as a result. + +## Test Cases + + +## Security Considerations + + +## Privacy Considerations + ## Backwards Compatibility This CAIP does not require discontinuing usage of contentscript. It is RECOMMENDED that wallets start implementing this alternative connection strategy and encouraging it's usage so that the ecosystem can eventually remove contentscript injection entirely. As an optional transitionary step, wallets can migrate their injected provider to start making connections over `externally_connectable` with no user-facing impact (not sure if true since this has caveats). -## Test Cases - - ## Links * [externally_connectable](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/externally_connectable) From 79f777c2ffe7fb90d03b4c745263dd6e308cfd53 Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Wed, 24 Apr 2024 14:21:26 -0700 Subject: [PATCH 05/20] Security and Privacy --- caip-browser_extension_provider_communication.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index bbba28ba..e31aef32 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -122,9 +122,11 @@ Web extension inter-operability is the key to enabling generalized provider impl ## Security Considerations +`externally_connectable` has seen a decade of usage via extensions on Chrome. It has a strictly better security when compared to postMessage over contentscript. ## Privacy Considerations +Exposing the wallet API over `externally_connectable` opens a migration path towards a bring-your-own provider model in which web extensions can reduce their fingerprint by no longer having to inject their own provider into every webpage. ## Backwards Compatibility From 6641dd411cd6302efbf1b0c81b9941ae819c78ae Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Fri, 26 Apr 2024 11:14:19 -0700 Subject: [PATCH 06/20] remove json-rpc providers from summary. update abstract --- caip-browser_extension_provider_communication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index e31aef32..838bffa4 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -14,11 +14,11 @@ created: 2022-11-28 ## Simple Summary -The proposal aims to standardize how JSON-RPC providers with web extensions communicate, making the process more efficient and secure. +The proposal aims to standardize how providers communicate with web extensions, making the process more efficient and secure. ## Abstract -This CAIP establishes how providers can communicate with web extensions over `externally_connectable`. +This CAIP establishes how providers can communicate with web extensions over `externally_connectable` in an extensible manner. ## Motivation From 6fad470dca49f42576b709bdbd84ab27a5cac4a1 Mon Sep 17 00:00:00 2001 From: jiexi Date: Tue, 30 Apr 2024 13:36:41 -0700 Subject: [PATCH 07/20] Update caip-browser_extension_provider_communication.md Co-authored-by: Alex Donesky --- caip-browser_extension_provider_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 838bffa4..6a8e2580 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -29,7 +29,7 @@ This injected API strategy has some advantages: * It allows websites to support any web extension following this standard with no additional effort. However, the injected API strategy has many disadvantages: -* It depends upon the web extension having read and write access to every website, which is a scary permission that web extension authors might otherwise be able to avoid asking for. +* It depends upon the web extension having read and write access to every website the user visits, which is a scary permission that web extension authors might otherwise be able to avoid asking for. * It slows down every website by injecting additional code to be parsed and executed. It even slows down the initial page load in most cases, because many web extensions inject the provider synchronously to maintain compatibility with websites that expect it to be available immediately. * Injecting code into a website can break it. * It provides no way for web extension authors to safely make breaking changes to their provider API, resulting in even more code being injected to support legacy APIs. From c0e298c32a3ee89a84117f4c1e5f4247633f5eb3 Mon Sep 17 00:00:00 2001 From: jiexi Date: Tue, 30 Apr 2024 13:36:55 -0700 Subject: [PATCH 08/20] Update caip-browser_extension_provider_communication.md Co-authored-by: Alex Donesky --- caip-browser_extension_provider_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 6a8e2580..2bcb3518 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -45,7 +45,7 @@ A provider library can be similarly easy to use for website authors as well, req Web extension inter-operability is a challenge for embeded providers though. That is what this proposal means to address. Today there is no way to write a provider such that it is compatible with any web extension. Web extensions differ today in how they communicate with wallets, from the messaging system used to the messaging format. These details often aren't publicly documented or treated as a public-facing API, so they can change without notice, making it risky even to embed support for popular conventions used today. -A standard method for providers to communicate with web extebsions would allow website authors to embed their own providers without losing web extension inter-operability. +A standard method for providers to communicate with web extensions would allow website authors to embed their own providers without losing web extension inter-operability. ## Specification From 6396b512345b6ef4c6b02ccad49c0f3030d721b1 Mon Sep 17 00:00:00 2001 From: jiexi Date: Tue, 30 Apr 2024 13:37:07 -0700 Subject: [PATCH 09/20] Update caip-browser_extension_provider_communication.md Co-authored-by: Alex Donesky --- caip-browser_extension_provider_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 2bcb3518..ce49c94d 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -43,7 +43,7 @@ An alternative strategy would be for a website to embed its own provider. A prov A provider library can be similarly easy to use for website authors as well, requiring nothing more than a single script tag to import a library and get an equivalent experience to using an the injected provider. -Web extension inter-operability is a challenge for embeded providers though. That is what this proposal means to address. Today there is no way to write a provider such that it is compatible with any web extension. Web extensions differ today in how they communicate with wallets, from the messaging system used to the messaging format. These details often aren't publicly documented or treated as a public-facing API, so they can change without notice, making it risky even to embed support for popular conventions used today. +Web extension inter-operability is a challenge for embedded providers though. That is what this proposal means to address. Today there is no way to write a provider such that it is compatible with any web extension. Web extensions differ today in how they communicate with wallets, from the messaging system used to the messaging format. These details often aren't publicly documented or treated as a public-facing API, so they can change without notice, making it risky even to embed support for popular conventions used today. A standard method for providers to communicate with web extensions would allow website authors to embed their own providers without losing web extension inter-operability. From 518c27ec7477b1ea85ecde11fd865f9a1d8b9a86 Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Wed, 1 May 2024 14:30:18 -0700 Subject: [PATCH 10/20] update injecting code breakage text --- caip-browser_extension_provider_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 838bffa4..4a0f7da1 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -31,7 +31,7 @@ This injected API strategy has some advantages: However, the injected API strategy has many disadvantages: * It depends upon the web extension having read and write access to every website, which is a scary permission that web extension authors might otherwise be able to avoid asking for. * It slows down every website by injecting additional code to be parsed and executed. It even slows down the initial page load in most cases, because many web extensions inject the provider synchronously to maintain compatibility with websites that expect it to be available immediately. -* Injecting code into a website can break it. +* In some cases, injecting code into a webpage may break its original intended behaviors. * It provides no way for web extension authors to safely make breaking changes to their provider API, resulting in even more code being injected to support legacy APIs. An alternative strategy would be for a website to embed its own provider. A provider could be offered as a library, to be embedded by the website author. This strategy can address all disadvantages of the injected provider approach: From 1cff079ea4534b91c92e20f173bf5e3d9cf20047 Mon Sep 17 00:00:00 2001 From: jiexi Date: Wed, 29 May 2024 15:19:02 -0700 Subject: [PATCH 11/20] Update caip-browser_extension_provider_communication.md Co-authored-by: Alex Donesky --- caip-browser_extension_provider_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index f2bd20bc..635c7f86 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -22,7 +22,7 @@ This CAIP establishes how providers can communicate with web extensions over `ex ## Motivation -Web extensions today will typically inject a JavaScript provider API into websites as a global variable. For example, in the Ethereum ecosystem this provider API is standardized in EIP-1193, and is conventionally injected as `window.ethereum`. +Web extension wallets today will typically inject a JavaScript provider API into websites as a global variable. For example, in the Ethereum ecosystem this provider API is standardized in EIP-1193, and is conventionally injected as `window.ethereum`. This injected API strategy has some advantages: * For websites developers, using a global variable is simple and requires no effort on their part to setup. From e7a8390561715af4f3cb8e6705a9fc94bf8d8ce4 Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Fri, 31 May 2024 13:52:56 -0700 Subject: [PATCH 12/20] Update firefox caveat. Remove different extension id text --- caip-browser_extension_provider_communication.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 635c7f86..1035cef9 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -105,11 +105,8 @@ The provider can: * send messages by using `port.postMessage()` * receive messages by using `port.onMessage.addListener()` -Caveats: -* No firefox support yet, but they are considering implementing it -* Extension Ids may be different across different family of browsers - * Discoverability should address this - +### Caveats +Currently Firefox does not support `externally_connectable` yet, but they are [considering implementing it](https://bugzilla.mozilla.org/show_bug.cgi?id=1319168). Meanwhile, extension wallets on Firefox will need to continue injecting an inpage provider for the dApp. ## Rationale From a2c083a6246d221786366f5cd7d839958bfe04f7 Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Fri, 31 May 2024 14:09:56 -0700 Subject: [PATCH 13/20] reword 'no safely make breaking changes' text --- caip-browser_extension_provider_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 1035cef9..45d28c9f 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -32,7 +32,7 @@ However, the injected API strategy has many disadvantages: * It depends upon the web extension having read and write access to every website the user visits, which is a scary permission that web extension authors might otherwise be able to avoid asking for. * It slows down every website by injecting additional code to be parsed and executed. It even slows down the initial page load in most cases, because many web extensions inject the provider synchronously to maintain compatibility with websites that expect it to be available immediately. * In some cases, injecting code into a webpage may break its original intended behaviors. -* It provides no way for web extension authors to safely make breaking changes to their provider API, resulting in even more code being injected to support legacy APIs. +* It provides no way for web extension authors to safely make breaking changes to their provider API without having to also inject extra code for the purposes of maintaining backwards compability for dApps that may still rely on those legacy APIs. An alternative strategy would be for a website to embed its own provider. A provider could be offered as a library, to be embedded by the website author. This strategy can address all disadvantages of the injected provider approach: * If this strategy became widespread enough, it would allow some web extensions to stop asking for write access to all pages. From 4205dc5646d82c65c1901a821f240a09d0d2f83c Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Fri, 31 May 2024 14:12:20 -0700 Subject: [PATCH 14/20] use 'inpage injected providers' in summary and abstract --- caip-browser_extension_provider_communication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 45d28c9f..19de9cfe 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -14,11 +14,11 @@ created: 2022-11-28 ## Simple Summary -The proposal aims to standardize how providers communicate with web extensions, making the process more efficient and secure. +The proposal aims to standardize how inpage injected providers communicate with web extensions, making the process more efficient and secure. ## Abstract -This CAIP establishes how providers can communicate with web extensions over `externally_connectable` in an extensible manner. +This CAIP establishes how inpage injected providers can communicate with web extensions over `externally_connectable` in an extensible manner. ## Motivation From 5f093b1e2a8a598ed27aaf027c48d4a88df036fa Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Tue, 25 Jun 2024 13:34:50 -0700 Subject: [PATCH 15/20] Update simple summary and abstract --- caip-browser_extension_provider_communication.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 19de9cfe..33eec8c4 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -14,11 +14,15 @@ created: 2022-11-28 ## Simple Summary -The proposal aims to standardize how inpage injected providers communicate with web extensions, making the process more efficient and secure. +This CAIP discusses the motivation, specification, and rationale for a proposal aimed at improving how web extension wallets interact with websites, particularly focusing on the Ethereum ecosystem. It outlines the current method of injecting JavaScript provider APIs into websites, its advantages, and its numerous disadvantages, such as security concerns, performance issues, and the risk of breaking websites. An alternative strategy is proposed that specifies a standard communication specification over a new transport layer which enables websites to be able to embed their own provider as a library, addressing the disadvantages of injecting providers into websites and improving web extension interoperability as a whole. ## Abstract -This CAIP establishes how inpage injected providers can communicate with web extensions over `externally_connectable` in an extensible manner. +In the current web extension wallet ecosystem, the prevalent approach involves injecting a JavaScript provider API, such as `window.ethereum`, directly into websites as a global variable. This method offers simplicity for web developers and ensures compatibility across extensions but raises significant concerns regarding security, performance, and potential disruption of website functionality due to the need for extensive permissions and the injection of additional code. An alternative approach involves websites embedding their own provider libraries, which could mitigate these issues by reducing required permissions, enhancing performance, and providing developers with greater control over provider integration. To make this approach feasible, a communication protocol must be standardized for the purpose. + +This proposal addresses the challenge of maintaining interoperability and extensibility between web extensions and websites by standardizing the communication protocol through the `externally_connectable` interface. This standardization aims to facilitate seamless interaction across different web extensions, ensuring a consistent and secure method of communication. This proposal outlines a specific message format for this communication and discusses the use of `externally_connectable` to allow web extensions to send and receive messages with authorized websites and extensions. + +Despite the lack of current support for `externally_connectable` in Firefox, the proposal underscores the importance of interoperability and standardized communication for the future of web extension wallets, advocating for a transition away from contentscript injection. ## Motivation From 1ac953f030ec92588a8101bd958f238c01fb1c23 Mon Sep 17 00:00:00 2001 From: jiexi Date: Wed, 26 Jun 2024 10:04:52 -0700 Subject: [PATCH 16/20] Update caip-browser_extension_provider_communication.md Co-authored-by: Alex Donesky --- caip-browser_extension_provider_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 33eec8c4..e4d9a77d 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -14,7 +14,7 @@ created: 2022-11-28 ## Simple Summary -This CAIP discusses the motivation, specification, and rationale for a proposal aimed at improving how web extension wallets interact with websites, particularly focusing on the Ethereum ecosystem. It outlines the current method of injecting JavaScript provider APIs into websites, its advantages, and its numerous disadvantages, such as security concerns, performance issues, and the risk of breaking websites. An alternative strategy is proposed that specifies a standard communication specification over a new transport layer which enables websites to be able to embed their own provider as a library, addressing the disadvantages of injecting providers into websites and improving web extension interoperability as a whole. +This CAIP discusses the motivation, specification, and rationale for a proposal aimed at improving how web extension wallets interact with websites. It outlines the current method of injecting JavaScript provider APIs into websites, its advantages, and its numerous disadvantages, such as security concerns, performance issues, and the risk of breaking websites. An alternative strategy is proposed that specifies a standard communication specification over a new transport layer which enables websites to be able to embed their own provider as a library, addressing the disadvantages of injecting providers into websites and improving web extension interoperability as a whole. ## Abstract From 0136d896f0eba77b08954d275d644aa9efc7df51 Mon Sep 17 00:00:00 2001 From: jiexi Date: Wed, 26 Jun 2024 10:08:43 -0700 Subject: [PATCH 17/20] Update caip-browser_extension_provider_communication.md Co-authored-by: Alex Donesky --- caip-browser_extension_provider_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index e4d9a77d..673b38be 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -104,7 +104,7 @@ The web extension can: * receive messages by using `port.onMessage.addListener()` * incoming messages should be validated according to the message format specification above -The provider can: +The webpage embedded provider can: * initiate a connection with the web extension by using `port = browser.runtime.connect()` * send messages by using `port.postMessage()` * receive messages by using `port.onMessage.addListener()` From fea150552ebef6a29748ad9211836b40313760b9 Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Wed, 26 Jun 2024 14:07:23 -0700 Subject: [PATCH 18/20] Remove message format todo --- caip-browser_extension_provider_communication.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index 33eec8c4..45715413 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -88,11 +88,6 @@ Web extensions should expose a standard interface over [`externally_connectable` } ``` -TODO: should type be more defined here? Seems weird to specify the envelop but no types it can be used with? -Does `data` need to be a JSON-RPC message specifically? -Should `type` be something besides `caip-x`? - - ### `externally_connectable` A web extension can use the `externally_connectable` manifest field to accept messages from websites and other extensions. This permission can be configured to limit which sites and other extensions can send messages to the web extension. How this permission is configured is out-of-scope for this proposal; this proposal only concerns sites that the web extension allows messages from. From 6d14374ede59ce8b712ecc36f5f3ef1d6bd49e05 Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Thu, 10 Apr 2025 08:50:08 -0700 Subject: [PATCH 19/20] update json schema --- caip-browser_extension_provider_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index e974045c..b0664df8 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -80,7 +80,7 @@ Web extensions should expose a standard interface over [`externally_connectable` "const": "caip-x" }, "data": { - "description": "A JSON-RPC message", + "description": "A CAIP-25/27/285/312/319 JSON-RPC message", "type": "object" } }, From 649f8563f85681e9306f95c688ba5d642544358a Mon Sep 17 00:00:00 2001 From: Jiexi Luan Date: Thu, 10 Apr 2025 09:10:48 -0700 Subject: [PATCH 20/20] add privacy fingerprint considerations --- caip-browser_extension_provider_communication.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/caip-browser_extension_provider_communication.md b/caip-browser_extension_provider_communication.md index b0664df8..270c1de6 100644 --- a/caip-browser_extension_provider_communication.md +++ b/caip-browser_extension_provider_communication.md @@ -124,6 +124,8 @@ Web extension inter-operability is the key to enabling generalized provider impl Exposing the wallet API over `externally_connectable` opens a migration path towards a bring-your-own provider model in which web extensions can reduce their fingerprint by no longer having to inject their own provider into every webpage. +It should be noted however that this API is still fingerprintable based on the return values from a CAIP-25 request. A malicious actor could make several CAIP-25 requests with a single scope and/or account ID to determine what scopes and/or accounts the wallet supports based on whether that request returns immediately with an unsupported error or not. This can be mostly mitigated by rate liming and disallowing concurrent CAIP-25 requests from the same origin. It is no worse than the current status quo with EVM methods. + ## Backwards Compatibility This CAIP does not require discontinuing usage of contentscript. It is RECOMMENDED that wallets start implementing this alternative connection strategy and encouraging it's usage so that the ecosystem can eventually remove contentscript injection entirely. As an optional transitionary step, wallets can migrate their injected provider to start making connections over `externally_connectable` with no user-facing impact (not sure if true since this has caveats).