Draft Community Group Report, 9 May 2022
Copyright © 2022 the Contributors to the Requesting Permissions Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.
This specification extends the Permissions API to provide a uniform function for requesting permission to use powerful features.
This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.
This document specifies a function to request permission to use powerful features on the Web platform.
Different Web APIs have disparate ways to signal a developer’s intent to use them:
The [notifications] API allows developers to request a permission and check the permission status explicitly.
The [geolocation-API] conflates the permission request with a location request.
It’s easier for developers to design their permission-related code if they have a single pattern to follow for all powerful features.
When the request(permissionDesc) method is invoked, the user agent MUST run the following algorithm, passing the parameter permissionDesc:
Let rootDesc be the object permissionDesc refers to, converted to an IDL value of type PermissionDescriptor. If this throws an exception, return a promise rejected with that exception and abort these steps.
Let typedDescriptor be the object permissionDesc refers to, converted to an IDL value of rootDesc.name’s permission descriptor type. If this throws an exception, return a promise rejected with that exception and abort these steps.
Let promise be a newly-created Promise.
Return promise and continue the following steps asynchronously.
Run the steps to create a PermissionStatus for typedDescriptor, and let status be the result.
Run the permission request algorithm of the feature named typedDescriptor.name with typedDescriptor and status as arguments.
If the previous step threw an exception, reject promise with that exception.
Otherwise resolve promise with status.
Powerful features in the Permission Registry additionally define a permission request algorithm:
InputAn instance of the permission descriptor type
A newly-created instance of the permission result type.
Uses the algorithms in Requesting more permission to show the user any necessary prompt to try to increase permissions, and updates the instance of the permission result type to match.
ReturnsNothing, but may throw an exception if the request can fail exceptionally. (Merely being denied permission is not exceptional.)
Example callers DefaultIf unspecified, this defaults to the default permission request algorithm.
The default permission request algorithm, given a PermissionDescriptor permissionDesc and a PermissionStatus status, runs the following steps:
Run the default permission query algorithm on permissionDesc and status.
If status.state is not "prompt", abort these steps.
Request permission to use permissionDesc.
Run the default permission query algorithm again on permissionDesc and status.
On browsers that don’t store permissions persistently within an environment settings object, this will always return "prompt", but still show the user an unnecessary prompt. That may mean that no permissions should use the default permission request algorithm, since it can never return an appropriate object-capability.
No security considerations have been identified.
No privacy considerations have been identified.
Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.
All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:
Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:
Note, this is an informative note.
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.