Questions re: chrome.userScripts documentation

16,533 views
Skip to first unread message

Brenton Partridge

unread,
Nov 17, 2023, 2:46:02 PM11/17/23
to Chromium Extensions
Very excited to see the development of the userScripts API - it was one of the key gaps of MV3, and it opens up incredible possibilities for users to customize their browser experience.

That said - and I understand things are in progress - the documentation on https://developer.chrome.com/docs/extensions/reference/userScripts/ could use more information about what capabilities the various execution worlds have.

I came across this proposal https://github.com/w3c/webextensions/blob/main/proposals/user-scripts-api.md#user_script-world but I'm not sure if the details there are still valid in this implementation. Namely:

- can a userscript in the USER_SCRIPT world do window.postMessage and have it seen by a userscript in the MAIN world, and vice versa?
- do both worlds share the same DOM?
- if configureWorld({messaging: true}) does that mean that both MAIN and USER_SCRIPT world userscripts can call runtime.sendMessage?
- will a script running in the USER_SCRIPT world have the ability to access fetch, XHR APIs, etc. to access remote content (subject to whatever connect-src CSP is specified in configureWorld)?
- if configureWorld sets an 'unsafe-eval' CSP, can scripts in the USER_SCRIPT world use eval()?

More generally, bringing a bunch of the rationale from that proposal into the documentation could go a long way towards clarifying how the API should be used.

Looking forward to seeing this go live in Chrome 120, and getting clarity on the capabilities!

wOxxOm

unread,
Nov 17, 2023, 4:29:55 PM11/17/23
to Chromium Extensions, Brenton Partridge
Indeed it would be helpful to clarify all these points in the documentation.

> can a userscript in the USER_SCRIPT world do window.postMessage and have it seen by a userscript in the MAIN world, and vice versa?

Yes, because this is not what gets isolated per world: only JS variables/functions/expandos are isolated.

Note that using window.postMessage is generally a bad idea here because you can break a site that's using this mechanism with data of a certain shape. You should use it only to cooperate with a site's onmessage listener intentionally or when your extension targets a specific site which you can test for compatibility, otherwise it's safer to use CustomEvent to transfer structured-clone-compatible objects or MouseEvent + relatedNode to transfer DOM nodes. The id of the event should be random ideally if you want to reduce the risk of collisions, chrome.runtime.id might work as well in the non-MAIN worlds (in the MAIN world you can pass it via args in executeScript).

> do both worlds share the same DOM?

Yes, world separation works the same as for the default (ISOLATED) content scripts vs page scripts: everything except JS stuff is shared, like the standard DOM properties (i.e. not JS expandos), timer ids, RAF ids, events, etc.

> if configureWorld({messaging: true}) does that mean that both MAIN and USER_SCRIPT world userscripts can call runtime.sendMessage?

configureWorld is only for USER_SCRIPT world.
In the MAIN world it's available when at least one extension's externally_connectable matches the document's URL.

> will a script running in the USER_SCRIPT world have the ability to access fetch, XHR APIs, etc. to access remote content (subject to whatever connect-src CSP is specified in configureWorld)?

Guess it should be impossible, the same as in the default ISOLATED world, because CORB enforcement for content scripts doesn't depend on the internal CSP for content scripts.

> if configureWorld sets an 'unsafe-eval' CSP, can scripts in the USER_SCRIPT world use eval()?

Guess it should be possible as the USER_SCRIPT world was designed to allow running arbitrary code strings.

> Looking forward to seeing this go live in Chrome 120

It's already live in Chrome Canary, it uses a separate user profile, so you can install it safely.
There are also non-optimized and buggier trunk snapshots of Chromium released every several hours.
Message has been deleted

Pavel Aronovich

unread,
Nov 18, 2023, 9:51:05 AM11/18/23
to Chromium Extensions, wOxxOm, Brenton Partridge
Developer mode is still needed if the extension is installed by the ExtensionSettings policy?

Usually in companies, the developer mode is prohibited by policy!

суббота, 18 ноября 2023 г. в 00:29:55 UTC+3, wOxxOm:

wOxxOm

unread,
Nov 18, 2023, 10:16:43 AM11/18/23
to Chromium Extensions, Pavel Aronovich, wOxxOm, Brenton Partridge
Yes, and there are more problems:
  • The devmode switch also enables other features e.g. chrome.declarativeNetRequest.onRuleMatchedDebug which may severely reduce the performance of the content blocking extensions, depending on how it's used.

  • The users won't know that they need to enable the devmode switch unless the extension says it, so every such extension will have to waste translation team effort to present the explanation in multiple languages.

  • There's no global indication in the browser for whether devmode is enabled, so people may have enabled it to test something out and then forgot to disable it, which leaves them vulnerable to accidentally installing a malicious extension that has "userScripts" permission among others, e.g. many extension developers have devmode switch constantly enabled. The only workaround is user-unfriendly: ExtensionSettings policy with blocked_permissions for "*" and allowed_permissions for the individual extensions.
Overall, the devmode switch is a no go in the long term, it's conceptually the same as chrome://flags/#enable-experimental-web-platform-features, which is only for testers of the new features, so hopefully a proper solution will be implemented once userScripts API graduates from this experimental stage. What about a dedicated option in the extension's icon context menu like "Allow running userScripts" when the extension has "userScripts" permission maybe even with an additional indicator?

Joe Floe

unread,
Nov 21, 2023, 12:56:14 PM11/21/23
to Chromium Extensions, wOxxOm, Pavel Aronovich, Brenton Partridge, olive...@google.com
I second that Developer mode will be an issue for customers of our extension, because of policies restrictions.
Is it posible to review this requirement from Chromium side?

Stryder Crown

unread,
Nov 22, 2023, 2:18:25 PM11/22/23
to Joe Floe, Chromium Extensions, wOxxOm, Pavel Aronovich, Brenton Partridge, olive...@google.com
Additional questions re: Developer mode;

If a user enables developer mode, is that enabled for all extensions or only ones the user trusts?  Not trying to overly criticize, but it seems short-sighted to create a security restriction like this due to concerns about malicious extensions only to make it an 'All or Nothing' setting. i.e. a user might know they can trust extension A, but requiring them to sacrifice a measure of protection against all extensions for one they know is safe makes a user not only less secure, but also puts developers who might otherwise be building Good Things at a significant disadvantage. I don't want my users entire security profile to be compromised just because I utilize this One Weird Trick that they love. Putting me in that position means my users have to decide between my Awesome Extension and their potential security.

--
You received this message because you are subscribed to the Google Groups "Chromium Extensions" group.
To unsubscribe from this group and stop receiving emails from it, send an email to chromium-extens...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-extensions/36c73692-5adf-4cb7-9b6e-cecfad4e41den%40chromium.org.

Seema Habib

unread,
Nov 22, 2023, 5:13:22 PM11/22/23
to Stryder Crown, Joe Floe, Chromium Extensions, wOxxOm, Pavel Aronovich, Brenton Partridge, Oliver Dunk

Oliver Dunk

unread,
Nov 23, 2023, 6:06:59 AM11/23/23
to Stryder Crown, Joe Floe, Chromium Extensions, wOxxOm, Pavel Aronovich, Brenton Partridge
If a user enables developer mode, is that enabled for all extensions or only ones the user trusts?

Yes, developer mode is a global setting which applies to all extensions. There's definitely a tradeoff here as you say.

As a general note, I just wanted to say that we've been keeping an eye on feedback, including everything in this thread. We'll continue to discuss it internally, we certainly want to spend more time on the User Scripts API over the next few months :)
Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

hrg...@gmail.com

unread,
Nov 23, 2023, 9:59:20 AM11/23/23
to Chromium Extensions, Oliver Dunk, Joe Floe, Chromium Extensions, wOxxOm, Pavel Aronovich, Brenton Partridge, Stryder Crown
May I ask what is the motivation for having two user-authorization mechanisms (the userScripts permission and the developer mode checkbox) behind the userScripts API?
Why is the userScripts permission not enough authorization?

Kamt Schatka

unread,
Nov 27, 2023, 3:00:27 AM11/27/23
to Chromium Extensions, hrg...@gmail.com, Oliver Dunk, Joe Floe, Chromium Extensions, wOxxOm, Pavel Aronovich, Brenton Partridge, Stryder Crown
We are also developing an extension that is rolled out by most of our customers using registry keys. They can't require users to manually enable developer mode, for them it is often a legal requirement to have it enabled on their users machines.

Oliver Dunk

unread,
Nov 27, 2023, 6:31:46 AM11/27/23
to hrg...@gmail.com, Chromium Extensions, Joe Floe, wOxxOm, Pavel Aronovich, Brenton Partridge, Stryder Crown
May I ask what is the motivation for having two user-authorization mechanisms (the userScripts permission and the developer mode checkbox) behind the userScripts API? Why is the userScripts permission not enough authorization?

The `userScripts` permission doesn't currently have an associated warning, so it isn't presented to users at install time. Instead, we rely on host permissions (which is similar to what we do in the `scripting` API for example). Host permissions are used for lots of other things, though, so it felt like additional steps were needed to reduce the chance this feature is used by a user that doesn't fully understand the risks.

There's definitely a lot of discussion here, and I agree with some of the concerns which I'll definitely raise with the team, but that's the context behind what we have now :)

Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

hrg...@gmail.com

unread,
Nov 27, 2023, 12:32:43 PM11/27/23
to Chromium Extensions, Oliver Dunk, Chromium Extensions, Joe Floe, wOxxOm, Pavel Aronovich, Brenton Partridge, Stryder Crown, hrg...@gmail.com
I see.
It really looks like that mechanism for user approval could be improved.
Id like to suggest the following idea:
  1. Make the userScripts permission strictly optional. i.e. it cannot be asked at install time, only after installation.
  2. Require that the userScripts permission can only be asked alone, not as part of a group
  3. Give the userScripts permission its own warning
  4. Eliminate the "Developer mode" requirement

RATIONALE:
Asking the userScripts permission after installation forces the user to pay attention to the request; whereas asking the permission at install-time as part of a set of permissions is easily overlooked because users tend to accept any install-time dialogs without much hesitation.
If the userScripts permission has its own dialog box which shows up once the user opens the options page, then this permission request cannot be overlooked. The user is forced to read the dialog box and approve the userScripts permission explicitly. And, therefore, there's no need for the "Developer mode" requirement.
Message has been deleted

Pavel Aronovich

unread,
Nov 28, 2023, 5:09:10 AM11/28/23
to Chromium Extensions, hrg...@gmail.com, Oliver Dunk, Chromium Extensions, Joe Floe, wOxxOm, Pavel Aronovich, Brenton Partridge, Stryder Crown
If the extension is installed by policy, then you do not need to require anything additional for userScripts to work.

понедельник, 27 ноября 2023 г. в 20:32:43 UTC+3, hrg...@gmail.com:

Joe Floe

unread,
Nov 29, 2023, 8:30:02 AM11/29/23
to Chromium Extensions, Pavel Aronovich, hrg...@gmail.com, Oliver Dunk, Chromium Extensions, Joe Floe, wOxxOm, Brenton Partridge, Stryder Crown
We have an extension that may be used in --headless=new mode for running automated test (chrome profile is created from scratch for each test), and we want to use userScript API there. 
How may we achieve this goal, givent that enabling Developer Mode requires manual interaction?

wOxxOm

unread,
Nov 29, 2023, 8:37:00 AM11/29/23
to Chromium Extensions, Joe Floe, Pavel Aronovich, hrg...@gmail.com, Oliver Dunk, Chromium Extensions, wOxxOm, Brenton Partridge, Stryder Crown
>  --headless=new mode

If the automation driver allows setting options, 1) set "extensions.ui.developer_mode" to true.
Otherwise 2) use "master_preferences" file or 3) patch the Preferences file in the user data directory or 4) navigate to chrome://extensions and click() the switch element.

Lionel Rowe

unread,
Dec 7, 2023, 11:27:01 PM12/7/23
to Chromium Extensions, wOxxOm, Joe Floe, Pavel Aronovich, hrg...@gmail.com, Oliver Dunk, Chromium Extensions, Brenton Partridge, Stryder Crown
At my company, we maintain a number of userscripts to provide various functionality to users both inside and outside of our organization (so any workaround that requires setting enterprise-level policies won't work for us). Requiring developer mode would place a significant burden on adoption, as most of the users are non-technical. I'd support a change making user-script permissions prompts more explicit and intuitive for users to understand the risks, but requiring developer mode is really a non-starter from our point of view.

nascent

unread,
Dec 8, 2023, 3:28:55 AM12/8/23
to Chromium Extensions, Lionel Rowe, wOxxOm, Joe Floe, Pavel Aronovich, hrg...@gmail.com, Oliver Dunk, Chromium Extensions, Brenton Partridge, Stryder Crown
As Lionel,  we use TamperMonkey at work, and forcing dependency on developer mode would mean we can no longer use it. That'd be devastating for us.

Oliver Dunk

unread,
Dec 8, 2023, 5:52:44 AM12/8/23
to nascent, Chromium Extensions, Lionel Rowe, wOxxOm, Joe Floe, Pavel Aronovich, hrg...@gmail.com, Brenton Partridge, Stryder Crown
I appreciate all of the feedback here. We're continuing to pass it on to the engineering and product teams.
Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

Henrik Jensen

unread,
Dec 10, 2023, 7:12:31 PM12/10/23
to Chromium Extensions, Oliver Dunk, Chromium Extensions, Lionel Rowe, wOxxOm, Joe Floe, Pavel Aronovich, hrg...@gmail.com, Brenton Partridge, Stryder Crown, nascent
Forcing a global state to manage a local problem is just bad design. Please don't do there.

Christian Walde (Mithaldu)

unread,
Dec 13, 2023, 8:06:10 PM12/13/23
to Chromium Extensions, Henrik Jensen, Oliver Dunk, Chromium Extensions, Lionel Rowe, wOxxOm, Joe Floe, Pavel Aronovich, hrg...@gmail.com, Brenton Partridge, Stryder Crown, nascent
Warning users is a good thing. Locking users out of a feature they may have very intentionally chosen is just harmful.

This feels like a problem was identified and then the first and most simple solution chosen with zero consideration of effects on users.

Cassie Conger

unread,
Dec 14, 2023, 11:24:29 AM12/14/23
to Chromium Extensions, Chromium Extensions
I can't even find how to enable developer mode! I rely on Tampermonkey! I've searched... I've gone through every page of settings... if we can't easily figure out how to set it to developer mode, how are we supposed to be able to continue using an extension we have come to rely on? You need to put something about developer mode so it can be searched at the VERY least... but it doesn't make sense that something so obscure is going to be required. Not everyone is tech savvy. I had to have someone talk me through Tampermonkey. It's like you don't care if we get to use what we've downloaded. 

Patrick Kettner

unread,
Dec 14, 2023, 11:31:59 AM12/14/23
to Cassie Conger, Chromium Extensions
Hi Cassie,
You can enable developer mode by going to chrome://extensions. There is a toggle in the upper right corner of the page. 

Deco

unread,
Dec 14, 2023, 11:42:36 AM12/14/23
to Patrick Kettner, Cassie Conger, Chromium Extensions
So I have been following this thread with relative interest due to the ramifications that it has on end user points.

Due to the privilege that the userScripts is naturally inheriting I understand the rationale behind having it enabled by the Developer mode only for the prototype stage, however when deployed this results in a anti-pattern for even considering to be used at all for this restriction. 

I think Cassie's overall point is the restriction is far too severe to even consider the potential to use it to begin with, which I agree with.

The developer mode was primarily made for loading unsigned extensions and has never in memory that I can recall been used for permission escalation directly. 

This check assumes that the user themselves is a "developer", and if stuck to presents a lot more danger than may initially meet the eye, in the pursuit of attempting to stop malicious executions, it is actually making it easier by exposing the ability to do to begin with.

The dependency has to be removed, the user prompt for permission acceptance should be used for this, not having to switch on a manual toggle for this behaviour to function.

Patrick Kettner

unread,
Dec 14, 2023, 1:05:24 PM12/14/23
to Deco, Cassie Conger, Chromium Extensions
I just wanted to say I really appreciate the feedback, and it is absolutely something the team is taking into account and discussing.

Cassie Conger

unread,
Dec 14, 2023, 1:38:01 PM12/14/23
to Chromium Extensions, Patrick Kettner, Chromium Extensions, Cassie Conger
You never helped me... I don't know where to turn it on in BRAVE

Patrick Kettner

unread,
Dec 14, 2023, 1:45:32 PM12/14/23
to Cassie Conger, Chromium Extensions
Hi Cassie,
Apologies, I wasn't aware you were using Brave. The same steps are true, just using brave://extensions rather than chrome://extensions.

image.png

Kamt Schatka

unread,
Apr 13, 2024, 3:11:27 AMApr 13
to Chromium Extensions, Pavel Aronovich, hrg...@gmail.com, Oliver Dunk, Chromium Extensions, Joe Floe, wOxxOm, Brenton Partridge, Stryder Crown

Is it a fact that you do not need developer mode if it is installed by policy, or is that wishful thinking?
On Tuesday, November 28, 2023 at 11:09:10 AM UTC+1 Pavel Aronovich wrote:

Oliver Dunk

unread,
Apr 15, 2024, 5:59:58 AMApr 15
to Kamt Schatka, Chromium Extensions, Pavel Aronovich, hrg...@gmail.com, Joe Floe, wOxxOm, Brenton Partridge, Stryder Crown
Hi Kamt,

There isn't currently an exception for policy-installed extensions.

If you have a strong use case, I'd love to hear. This isn't something we are necessarily against but just something we haven't implemented yet.

Thanks,
Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

wOxxOm

unread,
Apr 15, 2024, 6:05:39 AMApr 15
to Chromium Extensions, Oliver Dunk, Chromium Extensions, Pavel Aronovich, hrg...@gmail.com, Joe Floe, wOxxOm, Brenton Partridge, Stryder Crown, Kamt Schatka
The requirement itself should be removed altogether for a variety of reasons explained by multiple developers. Chrome team hasn't provided any coherent answer to those arguments yet.

Kamt Schatka

unread,
Apr 15, 2024, 6:48:10 AMApr 15
to Chromium Extensions, wOxxOm, Oliver Dunk, Chromium Extensions, Pavel Aronovich, hrg...@gmail.com, Joe Floe, Brenton Partridge, Stryder Crown, Kamt Schatka
I have already provided my use case before:
"We are also developing an extension that is rolled out by most of our customers using registry keys. They can't require users to manually enable developer mode, for them it is often a legal requirement to have it enabled on their users machines."

I was just reacting to the message by "Pavel Aronovich" wo claims "If the extension is installed by policy, then you do not need to require anything additional for userScripts to work."

TBH this communication is a complete mess up to now. We received an update on the google store policy on Saturday that the policy has changed to make the use of external code possible again (via debugger API and userscript API), but at this point, the UserScript API is completely unusable due to the requirement to have the developer mode active. This is not something that works with policies and this is not something that works reasonably well for end users. 
The end of MV2 is only months away and we still have to deal with this huge uncertainty. I would really expect more from a huge company like google, but obviously I was mistaken.

Oliver Dunk

unread,
Apr 15, 2024, 6:54:13 AMApr 15
to Kamt Schatka, Chromium Extensions, wOxxOm, Pavel Aronovich, hrg...@gmail.com, Joe Floe, Brenton Partridge, Stryder Crown
I was just reacting to the message by "Pavel Aronovich" who claims "If the extension is installed by policy, then you do not need to require anything additional for userScripts to work."

This is something we've discussed, but right now I believe you do need to manually enable developer mode in all cases. I'll follow-up with the team on policy installed extensions to see if we are still open to changes there.

TBH this communication is a complete mess up to now. We received an update on the google store policy on Saturday that the policy has changed to make the use of external code possible again (via debugger API and userscript API), but at this point, the UserScript API is completely unusable due to the requirement to have the developer mode active. This is not something that works with policies and this is not something that works reasonably well for end users.

Would you be able to clarify your concern with the policy change? In practice, we have always allowed Remote Hosted Code with the User Scripts API - this policy update was simply to reflect that and make sure our policy was in line with what we were enforcing in practice. The hope is to try and make things as clear as possible. I appreciate that needing to enable the developer mode toggle does not work for your use case - as mentioned, that is definitely something I appreciate and hope we can solve.
Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB
Message has been deleted

Kamt Schatka

unread,
Apr 15, 2024, 7:15:12 AMApr 15
to Chromium Extensions, Oliver Dunk, Chromium Extensions, wOxxOm, Pavel Aronovich, hrg...@gmail.com, Joe Floe, Brenton Partridge, Stryder Crown, Kamt Schatka
No concern regarding the update, I was just assuming that if you send out such an update for something that was known to developers for some time now, that there would actually be solutions to the concerns people have been voicing since the introduction of this move to MV3 (years ago). But nothing has changed, people are left hanging and it is now mid April, when this change is rolling out starting in June.

hrg...@gmail.com

unread,
Apr 15, 2024, 7:46:42 AMApr 15
to Chromium Extensions, Kamt Schatka, Oliver Dunk, Chromium Extensions, wOxxOm, Pavel Aronovich, hrg...@gmail.com, Joe Floe, Brenton Partridge, Stryder Crown
Given that you deploy your extension using the registry, you have the option to enable the ExtensionManifestV2Availability policy which will keep MV2 support until June 2025. Hopefully that will be enough time for the various MV3 annoyances to be solved by then.

Ximing Chen

unread,
Apr 26, 2024, 11:17:42 AMApr 26
to Chromium Extensions, hrg...@gmail.com, Kamt Schatka, Oliver Dunk, Chromium Extensions, wOxxOm, Pavel Aronovich, Joe Floe, Brenton Partridge, Stryder Crown
With only a few months left until end users are disabled with the MV2 extension, why hasn’t this issue been fixed yet?

Oliver Dunk

unread,
Apr 29, 2024, 8:31:19 AMApr 29
to Ximing Chen, Chromium Extensions, hrg...@gmail.com, Kamt Schatka, wOxxOm, Pavel Aronovich, Joe Floe, Brenton Partridge, Stryder Crown
Hi Ximing,

Did you have a specific concern?

We know there is still feedback around policy installed extensions, but there is a policy available to extend MV2 support for an additional year.

We're also keeping in mind the feedback around the developer mode requirement. This shouldn't stop anyone from using the API in the meantime, but I'm certainly hopeful that we can make some changes based on it. Patrick and I are continuing to pass along this feedback and if there are any updates we'll be sure to share them.
Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

Valve

unread,
May 16, 2024, 2:50:26 AMMay 16
to Chromium Extensions, Oliver Dunk, Chromium Extensions, hrg...@gmail.com, Kamt Schatka, wOxxOm, Pavel Aronovich, Joe Floe, Brenton Partridge, Stryder Crown, Ximing Chen
I'm finding the docs out of date or not clear right now. The `matches` property is listed as optional, but Chrome keeps saying it's required. The `includeGlobs` property feels like it does nothing or I'm just not sure how to use it.

Oliver Dunk

unread,
May 16, 2024, 6:29:47 AMMay 16