API for extensions to exclusion/deny list their content scripts

[Robbendebiene]

Basic Use Case: Users often want an exclusion/allow list functionality to disable add-ons on certain URLs.

Goal:

• run or not run code in tabs depending on user defined urls/patterns
• browser action icon should reflect whether the code runs or does not run
• ideally avoid the tabs permission as self-deactivation is not a main feature of an add-on. It is kinda contradictory that content script disabling requires loosening the permissions.

Attempts:

Block the content script injection:

Approach:

scripting.registerContentScripts() seems like a wonderful fit for this, because it provides the excludeMatches functionality wherefore no knowledge about the tab urls has to be exposed.

1. Store the exclusions in browser.storage.
2. Retrieve the exclusions in the background script.
3. Inside the background script call scripting.registerContentScripts() (or scripting.updateContentScripts()) with the exclusions as excludeMatches to register the content script.

Problems:

• scripting.registerContentScripts() does not inject the script into already existing tabs. Any workaround via scripting.executeScript() requires the tabs permission because it should only be called for tabs whose url is not listed in the exclusions.
• Adding an url/pattern to excludeMatches (via scripting.updateContentScripts()) does not remove/disable already injected content scripts.

Drawbacks:

• Detecting whether the content script is injected or not from the background page is only possible via messaging from/to the content script. So toggling the browser action icon state would be possible if the above problems were solved.

Block the code inside the content script:

Approach:

1. Register the content script via the content_scripts manifest key
2. Store the exclusions in the browser.storage.
3. Retrieve the exclusions in the content script.
4. Inside the content script check whether whether the tabs URL matches any exclusion and run or not run the main content script's code.

Problems:

• No direct access to the tab url in iframes (requires passing the window.location.href to background page and then back to all frames) or using the privacy unfriendly postMessage API.
• The browser action icon either requires passing the url from the content script to the background script since it does not have access to the tab url without the tabs permission, or some other messaging.

Drawbacks:

• Unnecessary injection/workload

Conclusion:

So far only the latter approach really works, but for a seemingly simple functionality as whitelisting/blacklisting it is cumbersome to implement. Also it feels wrong to rely on content script code while the goal is to avoid any content script injection.

Possible solutions:

• Allow scripting.registerContentScripts() to inject into existing tabs and also unloading it when it becomes excluded via excludeMatches.
  Related requests:
  • https://groups.google.com/a/chromium.org/g/chromium-extensions/c/l6hwu8YSR0w
  • https://stackoverflow.com/questions/75938303/is-there-a-way-how-to-run-registercontentscripts-immediately
  • https://bugzilla.mozilla.org/show_bug.cgi?id=1458947
  • https://bugzilla.mozilla.org/show_bug.cgi?id=1423323
• Provide the tab url regardless of the tabs permission if the add-on has host permissions for the respective tab. This would still require the content script to be injected at all times but at least require less implementation overhead for the background script code. Edit: This is already the case.

[fregante]

My solution for this has been this package for the past 9 years:

• https://github.com/fregante/webext-dynamic-content-scripts

In short: it listens to new host permissions and then it registers the manifest scripts on these new hosts. You don't need the tabs permission for what you're asking, but only scripting and the specific host you want to inject into.

However this has been a pain point for me forever. I've been asking for a way to declare content scripts as "injectable on any websites" and let the browser handle permissions, registration and injection.

Extensions in Safari actually are awfully close to this if you declare a content script with *://*/* but then it bugs the user on every website because "this extension is requesting access to this website." I wish the notice was changed to "this extension can be enabled on this website"

Chrome even has UI for this already in place, but it's disabled/unclickable:

[fregante]

Regarding your specific requests:

• Allow scripting.registerContentScripts() to inject into existing tabs and also unloading it when it becomes excluded via excludeMatches

You can't unload JavaScript once it's been run. CSS code is already unloaded in Firefox and Safari in this case (I think not in Chrome)

• Provide the tab url regardless of the tabs permission if the add-on has host permissions for the respective tab

That already happens. You will receive the tab URL if you have permission to access the website. See the output of chrome.tabs.query({}) in an extension that only has access to Github.com: screenshot

[Robbendebiene]

My solution for this has been this package for the past 9 years:

• https://github.com/fregante/webext-dynamic-content-scripts

In short: it listens to new host permissions and then it registers the manifest scripts on these new hosts. You don't need the tabs permission for what you're asking, but only scripting and the specific host you want to inject into.

However this has been a pain point for me forever. I've been asking for a way to declare content scripts as "injectable on any websites" and let the browser handle permissions, registration and injection.

Thanks for you answer. That looks like a decent solution for allow list scenarios. Unfortunately I'm more interested into the blocklist/exclusion scenario.

I would also prefer if this could be leveraged with the browsers host permission like your approach does. In fact the idea has been raised some time ago for Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=1745823
However it is still in a pretty undefined state with multiple open questions. Therefore enhancing scripting.registerContentScripts() sounded way easier to me. Also because at least one functionality I'm demanding has been requested multiple times and even seems to be something add-on developers expect "naturally" from the API.

You can't unload JavaScript once it's been run. CSS code is already unloaded in Firefox and Safari in this case (I think not in Chrome)

I'm not sure to which extend this is true. At least in Firefox if I remove/uninstall an extension the content script seems to be removed. This may be possible due to their X-Ray vision, but that is beyond my knowledge.

That already happens. You will receive the tab URL if you have permission to access the website. See the output of chrome.tabs.query({}) in an extension that only has access to Github.com: screenshot

You are right. My apologies. My tests case had an error.