Skip to content

Add specification for externally_connectable. #873

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.

Sign up for GitHub

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add specification for externally_connectable. #873

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion specification/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,19 @@ This key may be present.

### Key `externally_connectable`

This key may be present.
The <a href="#key-externally_connectable">`externally_connectable`</a> key declares which extensions and web pages can establish connections to the extension using [=runtime.connect()=] and [=runtime.sendMessage()=]. If omitted, all extensions may connect, but no web pages can connect.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'm not sure if this is the correct way to reference these two APIs. also, will the documentation for these live in this doc or are we planning to have separate docs for each API namespace? if the latter, then i'm not sure what's the best way to reference them here

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should at least mention that these keys control what is allowed to trigger the runtime.onMessageExternal and runtime.onConnectExternal events. This is a worthy callout because ordinarily, the runtime.connect and runtime.sendMessage trigger runtime.onMessage and runtime.onConnect instead.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since these messaging APIs are web-exposed, I wonder whether we should make an effort to write down the namespace and methods that are expected to be supported, part of https://github.com/w3c/webextensions/blob/main/specification/window.browser.bs (or a separate doc, linked from there)


This key may be present and may include the following optional keys:

#### Key `ids`

A [=list=] of [=extension IDs=] that specifies which extensions can communicate with the extension. To allow all extensions, include the pattern `*` in the list. If left empty or omitted, no extensions can connect.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question:
Should we emphasize that there are two ways to allow ANY extension to connect:

  • externally_connectable is omitted altogether
  • externally_connectable is specified and ids: ["*"] is set

You already mentioned in the introduction that omitting externally_connectable altogether allows any extension to connect, but it might be too easy to overlook that and conclude that nobody can connect when they read the "If left empty or omitted, no extensions can connect." here.


#### Key `matches`

A [=list=] of [=match patterns=] that specifies which web pages can communicate with the extension. If left empty or omitted, no web pages can connect.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is an edge case where document URLs cannot be described by a match pattern. For these cases, we specified an algorithm to determine the URL to use for matching content scripts, at specification/index.bs: "Determine the URL for matching a document".

Can we point to this?

@oliverdunk Could you confirm that this is what Chrome does (or intends to use)?


Any [=match patterns=] that include wildcard domains, or wildcard subdomains of a top-level domain, must be ignored.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wildcard domains is, arguably, the most important think that externally_connectable should support, and people have been asking for it for ~8 years. See https://bugzilla.mozilla.org/show_bug.cgi?id=1319168 for a long history, but the TL;DR is:

An extension can extend the built-in browser API via externall_connectable by enabling a wildcard externally_connectable. Websites can then probe to see if APIs of interest are exposed by any installed extensions and communicate with the extension without the extension needing to inject content scripts into the page which is currently the only way to achieve this behavior.


### Key `devtools_page`

Expand Down