Support userScripts permission in the permissions API

[Rob--W]

The userScripts API is currently implemented by Chrome and Firefox, and both require express user consent to enable the API.

In Chrome, this is currently implemented as requiring the user to check the "Developer Mode" checkbox. If not checked, an attempt to access the chrome.userScripts namespace throws an error (https://developer.chrome.com/docs/extensions/reference/api/userScripts#developer_mode_for_extension_users). There is no way for extension developers to know whether the user checked the checkbox (feature request: https://issues.chromium.org/issues/40942783).

In Firefox, this is implemented by requiring "userScripts" to be in optional_permissions (not in permissions), so that the user can either use the built-in extension permission management UI, or call permissions.request() to request the permission. This permission request has additional requirements to make sure that users cannot mindlessly approve the permission request, as shown in the screenshots at https://bugzilla.mozilla.org/show_bug.cgi?id=1917000

When "userScripts" access is modeled as an optional permission, extension developers can use the standard permissions.contains(), permissions.onAdded and permissions.onRemoved APIs to be notified of access changes, and react accordingly.

The behavior of permissions.request() can be customized depending on what the browser wants:

• In Firefox, the user sees an additional warning and checkbox before they can confirm the permission request, as seen in the screenshots at https://bugzilla.mozilla.org/show_bug.cgi?id=1917000 . The permission can also not be requested with other permissions at the same time, to ensure that the displayed permission prompt can be unambiguous.
• If a browser does not want to support extension-triggered permission requests, they can automatically reject the API call.

I'm proposing for the "userScripts" opt-in to be modeled as an optional permission, so that the permissions API can be used to detect and monitor the availability of the userScripts API.

[erosman]

The single-step optional_permissions approach should be more practical than the multi-step permission approach.

In order to avoid having to asynchronously request permissions.contains() on each operation (as users can revoke the permission anytime via the browser interface) , would developers be able to test the permission by checking if browser.userScript is defined?

[Rob--W]

The single-step optional_permissions approach should be more practical than the multi-step permission approach.

The userScripts API is designed for a specific purpose. The extra step in the permission prompt flow exists to reduce the risk of users granting access without understanding its implications.

In order to avoid having to asynchronously request permissions.contains() on each operation (as users can revoke the permission anytime via the browser interface) , would developers be able to test the permission by checking if browser.userScript is defined?

The usual behavior is to hide API namespaces and/or methods when the required permission has been revoked. Firefox implements that behavior in the userScripts API, which does indeed mean that browser.userScripts becomes undefined. User scripts that have already executed in documents may still be running (because there is no fully effective way to undo the effects of script execution), but in new document loads the script won't run.

Chrome's current behavior when access has not been granted is to throw an error when the chrome.userScripts namespace is accessed. It would be a backwards-incompatible change to stop throwing, so a potential backwards-compatible way for Chrome to adopt this proposal is as follows:

• when "userScripts" is only present in optional_permissions, support the usual permissions API. This includes the possibility of auto-rejecting permissions.request() when Chrome-specific constraints have not been met (e.g. the current Developer Mode requirement). The browser.userScripts namespace would be undefined if not granted.
• when "userScripts" is only present in permissions, throw an error if browser.userScripts is accessed, for backwards-compatibility. Integration in the permissions API is not guaranteed and optional, whatever makes most sense with Chrome's internals.
• when "userScripts" is present in optional_permissions AND permissions, support the proposed integration in the permissions API. If the risk of breaking backwards-compatibility is low, let browser.userScripts be undefined too, and throw an error otherwise.