Optional-only permissions (#36988)

* Optional only permissions * Apply suggestions from review Co-authored-by: Rob Wu <[email protected]> * Updates for feedback * Apply suggestions from review Co-authored-by: Rob Wu <[email protected]> --------- Co-authored-by: Rob Wu <[email protected]>
mdn · Dec 24, 2024 · 509fa54 · 509fa54
1 parent 86aba12
commit 509fa54
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 19 deletions.
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/permissions/request/index.md b/files/en-us/mozilla/add-ons/webextensions/api/permissions/request/index.md
@@ -7,15 +7,17 @@ browser-compat: webextensions.api.permissions.request
 
 {{AddonSidebar}}
 
-Ask for the set of permissions listed in the given {{WebExtAPIRef("permissions.Permissions")}} object.
+Asks the user for the permissions listed in the {{WebExtAPIRef("permissions.Permissions")}} object.
 
-The `Permissions` argument may contain either an `origins` property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both. Permissions must come from the set of permissions defined in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key. The `origins` property may include permissions that match a subset of the hosts matched by an optional permission: for example, if optional_permissions include "\*://mozilla.org/", then `permissions.origins` may include "https\://developer.mozilla.org/".
+The `Permissions` argument can contain an `origins` property, an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), a `permissions` property, an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both.
 
-The request can only be made inside the handler for a [user action](/en-US/docs/Mozilla/Add-ons/WebExtensions/User_actions).
+Requested permissions must be defined in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key. The `origins` property can include permissions matching a subset of the hosts matched by an optional permission. For example, if `optional_permissions` include `"*://mozilla.org/"`, then `permissions.origins` can include `"https://developer.mozilla.org/"`.
 
-Depending on a circumstances, the browser will probably handle the request by asking the user whether to grant the requested permissions. Only a single request is made for all requested permissions: thus either all permissions are granted or none of them are.
+Requests for [optional-only permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions#optional-only_permissions) can't include any other optional permissions.
 
-Any permissions granted are retained by the extension, even over upgrade and disable/enable cycling.
+The request can only be made inside the handler for a [user action](/en-US/docs/Mozilla/Add-ons/WebExtensions/User_actions). Unless all the permissions requested are ones granted silently, the browser asks the user whether to grant the requested permissions. One request is made for all requested permissions: either all permissions are granted or none are.
+
+The extension retains any permissions granted, even over upgrade and disable and enable cycling.
 
 This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 
@@ -34,15 +36,15 @@ let requesting = browser.permissions.request(
 
 ### Return value
 
-A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with `true` if the extension is now granted all the permissions listed in the `permissions` argument, or `false` otherwise.
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with `true` if the extension is granted the permissions listed in the `permissions` argument, or `false` otherwise.
 
 ## Browser compatibility
 
 {{Compat}}
 
 ## Examples
 
-This code adds a click handler that asks for various permissions, then logs the result of the request and the extension's permissions after the request completed.
+This code adds a click handler that asks for various permissions, then logs the result of the request and the extension's permissions after the request completes.
 
 ```js
 const permissionsToRequest = {
@@ -73,8 +75,5 @@ document
 
 {{WebExtExamples}}
 
-> [!NOTE]
-> Currently has a [bug with requesting origins](https://bugzil.la/1411873) and [requesting permissions on the about:addons page](https://bugzil.la/1382953).
-
 > [!NOTE]
 > This API is based on Chromium's [`chrome.permissions`](https://developer.chrome.com/docs/extensions/reference/api/permissions) API.
diff --git a/...en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md b/...en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md
@@ -33,26 +33,26 @@ browser-compat: webextensions.manifest.optional_permissions
   </tbody>
 </table>
 
-Use the `optional_permissions` key to list permissions that you want to ask for at runtime, after your extension has been installed.
+Use the `optional_permissions` key to list permissions you want to ask for at runtime, after your extension has been installed.
 
-The [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) key lists permissions that your extension needs before it can be installed. In contrast, `optional_permissions` lists permissions that your extension doesn't need at install time but it may ask for after it has been installed. To ask for a permission, use the {{webextapiref("permissions")}} API. Asking for a permission may present the user with a dialog requesting them to grant the permission to your extension.
+The [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) key lists permissions that your extension needs before it can be installed. In contrast, `optional_permissions` lists permissions that your extension doesn't need at install time but can ask for after installation. To ask for a permission, use the {{webextapiref("permissions.request()")}} API. Asking for a permission presents the user with a dialog requesting them to grant the permission to your extension, unless all the permissions requested are granted silently.
 
 For advice on designing your request for runtime permissions, to maximize the likelihood that users grant them, see [Request permissions at runtime](https://extensionworkshop.com/documentation/develop/request-the-right-permissions/#request_permissions_at_runtime).
 
-Starting with Firefox 84, users can manage optional permissions from the Firefox Add-ons Manager. Extensions that use optional permissions can listen for [browser.permissions.onAdded](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onAdded) and [browser.permissions.onRemoved](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onRemoved) API events to know when a user grants or revokes these permissions.
+Starting with Firefox 84, users can manage optional permissions from the Firefox Add-ons Manager. Extensions that use optional permissions can check for the permissions granted by the user with {{webextapiref("permissions.getAll()")}} and listen for {{webextapiref("permissions.onAdded")}} and {{webextapiref("permissions.onRemoved")}} to know when a user grants or revokes permissions.
 
-The key can contain two kinds of permissions: host permissions and API permissions.
+The key can contain host permissions and API permissions.
 
 ## Host permissions
 
 These are the same as the host permissions you can specify in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) key.
 
 > [!NOTE]
-> When using Manifest V3 or higher optional host permissions should be specified using the [`optional_host_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_host_permissions) manifest key. Firefox introduced `optional_host_permissions` in release 128, see [bug 1766026](https://bugzil.la/1766026), and allows for the continued use of `optional_permissions` to specify optional hosts. Use of `optional_host_permissions` however is recommended.
+> When using Manifest V3 or higher, optional host permissions should be specified using the [`optional_host_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_host_permissions) manifest key. Firefox introduced `optional_host_permissions` in release 128, see [bug 1766026](https://bugzil.la/1766026), and allows the continued use of `optional_permissions` to specify optional hosts. Use of `optional_host_permissions`, however, is recommended.
 
 ## API permissions
 
-You can include any of the following here, but not in all browsers: check the compatibility table for browser-specific details.
+The optional API permissions are:
 
 - `activeTab`
 - `background`
@@ -94,9 +94,9 @@ You can include any of the following here, but not in all browsers: check the co
 - `webRequestFilterResponse`
 - `webRequestFilterResponse.serviceWorkerScript`
 
-Note that this is a subset of the API permissions allowed in [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions).
+Check the compatibility table for browser-specific support details.
 
-Of this set, the following permissions are granted silently, without a user prompt:
+These optional permissions are granted silently, without a user prompt:
 
 - `activeTab`
 - `cookies`
@@ -106,7 +106,14 @@ Of this set, the following permissions are granted silently, without a user prom
 - `webRequestFilterResponse`
 - `webRequestFilterResponse.serviceWorkerScript`
 
-## Example
+### Optional-only permissions
+
+Optional permissions are generally available for use in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions) key so they can be requested at install time. However, some browsers support the concept of optional-only permissions, permissions that can only be requested at runtime using the {{webextapiref("permissions.request()")}} API. In addition, optional-only permissions must be requested individually and alone through the {{webextapiref("permissions.request()")}} API.
+
+> [!NOTE]
+> No optional-only permissions were generally available at the time of writing, December 2024.
+
+## Examples
 
 ```json
  "optional_permissions": ["*://developer.mozilla.org/*"]