Permission API updates

files/en-us/web/api/geolocation/getcurrentposition/index.md

@@ -10,6 +10,10 @@ browser-compat: api.Geolocation.getCurrentPosition
 
 The **`getCurrentPosition()`** method of the {{domxref("Geolocation")}} interface is used to get the current position of the device.
 
+Note that in addition to requiring a secure context this feature may be blocked by the [`geolocation`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/geolocation) `Permissions-Policy`, and also requires that explicit permission be granted by the user.
+If required, the user will be prompted when this method is called.
+The permission state can be queried using the `geolocation` user permission in the [Permissions API](/en-US/docs/Web/API/Permissions_API).
+
 ## Syntax
 
 ```js-nolint

files/en-us/web/api/geolocation/watchposition/index.md

@@ -11,6 +11,10 @@ browser-compat: api.Geolocation.watchPosition
 The **`watchPosition()`** method of the {{domxref("Geolocation")}} interface is used to register a handler function that will be called automatically each time the position of the device changes.
 You can also, optionally, specify an error handling callback function.
 
+Note that in addition to requiring a secure context this feature may be blocked by the [`geolocation`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/geolocation) `Permissions-Policy`, and also requires that explicit permission be granted by the user.
+If required, the user will be prompted when this method is called.
+The permission state can be queried using the `geolocation` user permission in the [Permissions API](/en-US/docs/Web/API/Permissions_API).
+
 ## Syntax
 
 ```js-nolint

files/en-us/web/api/geolocation_api/index.md

@@ -46,6 +46,28 @@ For further information on Geolocation usage, read [Using the Geolocation API](/
 - {{domxref("Navigator.geolocation")}}
   - : The entry point into the API. Returns a {{domxref("Geolocation")}} object instance, from which all other functionality can be accessed.
 
+## Security considerations
+
+The Geolocation API allows users to programmatically access location information in [secure contexts](/en-US/docs/Web/Security/Secure_Contexts).
+
+Access may further be controlled by the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/geolocation","geolocation")}}.
+The default allowlist for `geolocation` is `self`, which allows access to position information only same-origin nested frames.
+Third party usage can be enabled by the server first setting the `Permissions-Policy` header to grant permission a particular third party origin:
+
+```http
+Permissions-Policy: geolocation=(self b.example.com)
+```
+
+Then the `allow="geolocation"` attribute must be added the frame container element for sources from that origin:
+
+```html
+<iframe src="https://b.example.com" allow="geolocation"/></iframe>
+```
+
+Geolocation is a powerful feature, and end users must additionally grant explicit permission via a prompt when either {{domxref("Geolocation.getCurrentPosition()")}} or {{domxref("Geolocation.watchPosition()")}} is called (unless the permission state is already `granted` or `denied`).
+The lifetime of a granted permission depends on the user agent, and may be time based, session based, or even permanent.
+The [Permissions API](/en-US/docs/Web/API/Permissions_API) `geolocation` permission can be used to test whether access to use location information is `granted`, `denied` or `prompt` (requires user acknowledgement of a prompt).
+
 ## Examples
 
 See [Using the Geolocation API](/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API#examples) for example code.

files/en-us/web/api/permissions/query/index.md

@@ -10,6 +10,11 @@ browser-compat: api.Permissions.query
 
 The **`query()`** method of the {{domxref("Permissions")}} interface returns the state of a user permission on the global scope.
 
+The user permission names are defined in the respective specifications for each feature.
+The permissions supported by different browser versions are listed in the [compatibility data of the `Permissions` interface](/en-US/docs/Web/API/Permissions#browser_compatibility) (see also the relevant source code for [Firefox values](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10), [Chromium values](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl), and [WebKit values](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl)).
+
+The APIs that are gated by each permission are listed in [Permission-aware APIs](/en-US/docs/Web/API/Permissions_API#permission-aware_apis) in the [Permissions API](/en-US/docs/Web/API/Permissions_API) overview topic.
+
 ## Syntax
 
 ```js-nolint
@@ -20,20 +25,26 @@ query(permissionDescriptor)
 
 - `permissionDescriptor`
 
-  - : An object that sets options for the `query` operation consisting of a comma-separated list of name-value pairs. The available options are:
+  - : An object that sets options for the `query` operation.
+    The available options for this descriptor depend on the permission type.
+
+    All permissions have a name:
 
     - `name`
-      - : The name of the API whose permissions you want to query. Each browser supports a different set of values. You'll find Firefox values [there](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10), Chromium values [there](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl), and WebKit values [there](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl).
-    - `userVisibleOnly`
-      - : (Push only, not supported in Firefox — see the Browser Support section below) Indicates whether you want to show a notification for every message or be able to send silent push notifications. The default is `false`.
-    - `sysex` (MIDI only)
-      - : Indicates whether you need and/or receive system exclusive messages. The default is `false`.
+      - : A string containing the name of the API whose permissions you want to query, such as `camera`, `bluetooth`, `camera`, `geolocation` (see [`Permissions`](/en-US/docs/Web/API/Permissions#browser_compatibility) for a more complete list).
+        The returned {{jsxref("Promise")}} will reject with a {{jsxref("TypeError")}} if the permission name is not supported by the browser.
+
+    For the `push` permissions you can also specify:
+
+    - `userVisibleOnly` {{optional_inline}}
+      - : (Push only, not supported in Firefox — see the Browser Support section below) Indicates whether you want to show a notification for every message or be able to send silent push notifications.
+        The default is `false`.
 
-> [!NOTE]
-> As of Firefox 44, the permissions for [Notifications](/en-US/docs/Web/API/Notifications_API) and [Push](/en-US/docs/Web/API/Push_API) have been merged. If permission is granted (e.g. by the user, in the relevant permissions dialog), `navigator.permissions.query()` will return `true` for both `notifications` and `push`.
+    For the `midi` permission you can also specify:
 
-> [!NOTE]
-> The `persistent-storage` permission allows an origin to use a persistent box (i.e., [persistent storage](https://storage.spec.whatwg.org/#persistence)) for its storage, as per the [Storage API](https://storage.spec.whatwg.org/).
+    - `sysex` {{optional_inline}}
+      - : Indicates whether you need and/or receive system exclusive messages.
+        The default is `false`.
 
 ### Return value
 

files/en-us/web/api/permissions/revoke/index.md

@@ -10,66 +10,56 @@ browser-compat: api.Permissions.revoke
 
 {{APIRef("Permissions API")}}{{AvailableInWorkers}}{{deprecated_header}}
 
-The **`revoke()`** method of the
-{{domxref("Permissions")}} interface reverts a currently set permission back to its
-default state, which is usually `prompt`.
-This method is called on the global {{domxref("Permissions")}} object
-{{domxref("navigator.permissions")}}.
+The **`revoke()`** method of the {{domxref("Permissions")}} interface reverts a currently set permission back to its default state, which is usually `prompt`.
+This method is called on the global {{domxref("Permissions")}} object {{domxref("navigator.permissions")}}.
 
-This method is removed from the main permissions API specification because its use case is unclear. Permissions are managed by the browser and the current permission model does not involve the site developer being able to imperatively request or revoke permissions. Browsers have shipped this API behind preferences but it's unlikely to reach the standards track. For more context, see the [original discussion to remove `permissions.revoke()`](https://github.com/w3c/permissions/issues/46).
+This method is removed from the main permissions API specification because its use case is unclear.
+Permissions are managed by the browser and the current permission model does not involve the site developer being able to imperatively request or revoke permissions. Browsers have shipped this API behind preferences but it's unlikely to reach the standards track.
+For more context, see the [original discussion to remove `permissions.revoke()`](https://github.com/w3c/permissions/issues/46).
 
 ## Syntax
 
 ```js-nolint
-revoke(descriptor)
+revoke(permissionDescriptor)
 ```
 
 ### Parameters
 
-- `descriptor`
+- `permissionDescriptor`
 
-  - : An object based on the `PermissionDescriptor` dictionary that sets
-    options for the operation consisting of a comma-separated list of name-value pairs.
-    The available options are:
+  - : An object that sets options for the `revoke` operation.
+    The available options for this descriptor depend on the permission type.
+
+    All permissions have a name:
 
     - `name`
-      - : The name of the API whose permissions you want to query. Each browser supports a different set of values. You can consult the [Firefox values](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10), the [Chromium values](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl), and the [WebKit values](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl).
-    - `userVisibleOnly`
-      - : (Push only, not supported in Firefox — see the
-        [Browser compatibility](#browser_compatibility) section below) Indicates whether you want to
-        show a notification for every message or be able to send silent push
-        notifications. The default is `false`.
-    - `sysex` (MIDI only)
-      - : Indicates whether you need and/or receive system
-        exclusive messages. The default is `false`.
-
-> [!NOTE]
-> As of Firefox 44, the permissions for [Notifications](/en-US/docs/Web/API/Notifications_API) and [Push](/en-US/docs/Web/API/Push_API) have been merged. If permission is
-> granted (e.g. by the user, in the relevant permissions dialog),
-> `navigator.permissions.query()` will return `true` for both
-> `notifications` and `push`.
-
-> [!NOTE]
-> The `persistent-storage` permission allows an
-> origin to use a persistent box (i.e., [persistent storage](https://storage.spec.whatwg.org/#persistence)) for its
-> storage, as per the [Storage API](https://storage.spec.whatwg.org/).
+      - : A string containing the name of the API whose permissions you want to query.
+        The returned {{jsxref("Promise")}} will reject with a {{jsxref("TypeError")}} if the permission name is not supported by the browser.
+
+    For the `push` permissions you can also specify:
+
+    - `userVisibleOnly` {{optional_inline}}
+      - : (Push only, not supported in Firefox — see the Browser Support section below) Indicates whether you want to show a notification for every message or be able to send silent push notifications.
+        The default is `false`.
+
+    For the `midi` permission you can also specify:
+
+    - `sysex` {{optional_inline}}
+      - : Indicates whether you need and/or receive system exclusive messages.
+        The default is `false`.
 
 ### Return value
 
-A {{jsxref("Promise")}} that calls its fulfillment handler with a
-{{domxref("PermissionStatus")}} object indicating the result of the request.
+A {{jsxref("Promise")}} that calls its fulfillment handler with a {{domxref("PermissionStatus")}} object indicating the result of the request.
 
 ### Exceptions
 
 - {{jsxref("TypeError")}}
-  - : Retrieving the `PermissionDescriptor` information failed in some way, or
-    the permission doesn't exist or is currently unsupported (e.g. `midi`, or
-    `push` with `userVisibleOnly`).
+  - : Retrieving the `PermissionDescriptor` information failed in some way, or the permission doesn't exist or is currently unsupported (e.g. `midi`, or `push` with `userVisibleOnly`).
 
 ## Examples
 
-This function can be used by an app to request that its own Geolocation API permission
-be revoked.
+This function can be used by an app to request that its own Geolocation API permission be revoked.
 
 ```js
 function revokePermission() {