This specification defines common infrastructure that other specifications can use to interact with browser permissions that allow or deny access to powerful features on the web platform. For developers, the specification defines an API to query the permission state of a powerful feature, or be notified if a permission for a powerful feature changes state.
This is a work in progress.
Some features in this specification are supported by only one user agent, and as such, are marked as at risk.
This example uses the Permissions API to decide whether local news should be shown using the Geolocation API or with a button offering to add the feature.
const { state } = await navigator.permissions.query({
name: "geolocation"
});
switch (state) {
case "granted":
showLocalNewsWithGeolocation();
break;
case "prompt":
showButtonToEnableLocalNews();
break;
case "denied":
showNationalNews();
break;
}
This example simultaneously checks the state of the `"geolocation"` and `"notifications"` [=powerful features=]:
const queryPromises = ["geolocation", "notifications"].map(
name => navigator.permissions.query({ name })
);
for await (const status of queryPromises) {
console.log(`${status.name}: ${status.state}`);
}
This example is checking the permission state of the available cameras.
const devices = await navigator.mediaDevices.enumerateDevices();
// filter on video inputs, and map to query object
const queries = devices
.filter(({ kind }) => kind === "videoinput")
.map(({ deviceId }) => ({ name: "camera", deviceId }));
const promises = queries.map((queryObj) =>
navigator.permissions.query(queryObj)
);
try {
const results = await Promise.all(promises);
// log the state of each camera
results.forEach(({ state }, i) => console.log("Camera", i, state));
} catch (error) {
console.error(error);
}
This section specifies a model for [=permissions=] to use [=powerful features=] on the Web platform.
A permission represents a user's decision as to whether a web application can use a [=powerful feature=]. The decision is represented as a permission [=permission/state=].
Express permission refers to an act by the user, e.g. via user interface or host device platform features, through which the user [=permission/grants=] [=permission=] for use of a feature by a web application.
Conceptually, a [=permission=] for a [=powerful feature=] can be in one of the following states:
To ascertain new information about the user's intent, a user agent MAY collect information about a user's intentions. This information can come from explicit user action, aggregate behavior of both the relevant user and other users, or implicit signals this specification hasn't anticipated.
Every [=permission=] has a lifetime, which is the duration for which a particular permission remains [=permission/granted=] before it reverts back to its [=permission/default state=]. A [=permission/lifetime=] could be until a particular Realm is destroyed, until a particular [=top-level browsing context=] is destroyed, an amount of time, or infinite. The lifetime is negotiated between the end-user and the [=user agent=] when the user gives [=express permission=] to use a [=feature=]—usually via some permission UI or user-agent defined policy.
Every permission has a default state (usually [=permission/prompt=]), which is the [=permission/state=] that the permission is in when the user has not yet given [=express permission=] to use the [=feature=] or it has been reset because its [=permission/lifetime=] has expired.
A powerful feature is a web platform feature (usually an API) for which a user gives [=express permission=] before the feature can be used. Access to the feature is determined by the environment settings object by the user having [=permission/granted=] permission via UI, or by satisfying some criteria that is equivalent to a permission [=permission/grant=].
A [=powerful feature=] is identified by its name, which is a string literal (e.g., "geolocation").
The user agent is responsible for tracking what powerful features each [=global object/realm=] has the user's [=permission=] to use. Other specifications can use the operations defined in this section to retrieve the UA's notion of what permissions are granted or denied, and to ask the user to grant or deny more permissions.
Each powerful feature can define zero or more additional aspects that websites can request permission to access.
To describe an [=powerful feature/aspect=], a specification MUST define a WebIDL [=dictionary=] that [=dictionary/inherits=] from {{PermissionDescriptor}}, and have that interface be its [=powerful feature/permission descriptor type=].
To get the current permission state, given a [=powerful feature/name=] |name| and an optional [=environment settings object=] |settings|:
A |descriptor|'s permission state for an optional environment settings object |settings| is the result of the following algorithm, which returns one of {{PermissionState/"granted"}}, {{PermissionState/"prompt"}}, or {{PermissionState/"denied"}}:
As a shorthand, a {{PermissionName}} |name|'s permission state is the permission state of a {{PermissionDescriptor}} with its {{PermissionDescriptor/name}} member set to |name|.
Spec authors, please note that algorithms in this section can wait for user input; so they shouldn't be used from other algorithms running on the main thread.
To request permission to use a |descriptor|, the UA must perform the following steps. This algorithm returns either {{PermissionState/"granted"}} or {{PermissionState/"denied"}}.
This is intentionally vague about the details of the permission UI and how the UA infers user intent. UAs should be able to explore lots of UI within this framework.
As a shorthand, requesting permission to use a {{PermissionName}} |name|, is the same as requesting permission to use a {{PermissionDescriptor}} with its {{PermissionDescriptor/name}} member set to |name|.
To prompt the user to choose one of several |options| associated with a |descriptor|, the UA must perform the following steps. This algorithm returns either {{PermissionState/"denied"}} or one of the options.
This is intentionally vague about the details of the permission UI and how the UA infers user intent. UAs should be able to explore lots of UI within this framework.
As a shorthand, prompting the user to choose from options associated with a {{PermissionName}} |name|, is the same as prompting the user to choose from those options associated with a {{PermissionDescriptor}} with its {{PermissionDescriptor/name}} member set to |name|.
When the UA learns that the user no longer intends to grant permission for a [=global object/realm=] to use a feature, react to the user revoking permission by:
Please register newly specified [=powerful features=] in the [[[powerful-feature-registry]]]. Doing so also provides this Working Group an opportunity to provide feedback and check that integration with this specification is done effectively.
Each powerful feature has the following permission-related algorithms and types. When the defaults are not suitable for a particular [=powerful feature=], a specification MAY override below algorithms and types below.
{{PermissionDescriptor}} or one of its subtypes. If unspecified, this defaults to {{PermissionDescriptor}}.
The feature can define a partial order on descriptor instances. If |descriptorA| is stronger than |descriptorB|, then if |descriptorA|'s permission state is {{PermissionState/"granted"}}, |descriptorB|'s permission state must also be {{PermissionState/"granted"}}, and if |descriptorB|'s permission state is {{PermissionState/"denied"}}, |descriptorA|'s permission state must also be {{PermissionState/"denied"}}.
{name: "midi", sysex: true} ("midi-with-sysex") is
[=PermissionDescriptor/stronger than=] {name: "midi", sysex: false}
("midi-without-sysex"), so if the user denies access to midi-without-sysex, the UA must
also deny access to midi-with-sysex, and similarly if the user grants access to
midi-with-sysex, the UA must also grant access to midi-without-sysex.
Some powerful features have more information associated with them than just a {{PermissionState}}. For example, {{MediaDevices/getUserMedia()}} needs to determine which cameras the user has granted [=ECMAScript/the current realm record=] permission to access. Each of these features defines an [=powerful feature/extra permission data type=]. If a {{DOMString}} |name| names one of these features, then |name|'s extra permission data for an optional environment settings object |settings| is the result of the following algorithm:
If specified, the [=powerful feature/extra permission data=] algorithm is usable for this feature.
Takes an instance of the [=powerful feature/permission descriptor type=] and a new or existing instance of the [=powerful feature/permission result type=], and updates the [=powerful feature/permission result type=] instance with the query result. Used by {{Permissions}}' {{Permissions/query(permissionDesc)}} method and the [=`PermissionStatus` update steps=]. If unspecified, this defaults to the default permission query algorithm.
The default permission query algorithm, given a {{PermissionDescriptor}} permissionDesc and a {{PermissionStatus}} |status|, runs the following steps:
|status|.state to |permissionDesc|'s permission state.
Takes no arguments. Updates any other parts of the implementation that need to be kept in sync with changes in the results of permission states or [=powerful feature/extra permission data=], and then [=react to the user revoking permission=].
If unspecified, this defaults to running [=react to the user revoking permission=].
Specifications that define one or more [=powerful features=] SHOULD suggest a [=permission=] [=permission/lifetime=] that is best suited for the particular feature. Some guidance on determining the lifetime of a permission is noted below, with a strong emphasis on user privacy. If no [=permission/lifetime=] is specified, the user agent provides one.
When the permission [=permission/lifetime=] expires for an origin:
An {{PermissionState}} value that serves as a [=permission=]'s [=permission/default state=] of a [=powerful feature=].
If not specified, the [=permission=]'s [=permission/default state=] is {{PermissionState/"prompt"}}.
A default powerful feature is a powerful feature with all of the above types and algorithms defaulted.
[Exposed=(Window)]
partial interface Navigator {
[SameObject] readonly attribute Permissions permissions;
};
[Exposed=(Worker)]
partial interface WorkerNavigator {
[SameObject] readonly attribute Permissions permissions;
};
[Exposed=(Window,Worker)]
interface Permissions {
Promise<PermissionStatus> query(object permissionDesc);
};
dictionary PermissionDescriptor {
required PermissionName name;
};
When the query() method is invoked, the user agent MUST run the following query a permission algorithm, passing the parameter permissionDesc:
[Exposed=(Window,Worker)]
interface PermissionStatus : EventTarget {
readonly attribute PermissionState state;
readonly attribute PermissionName name;
attribute EventHandler onchange;
};
enum PermissionState {
"granted",
"denied",
"prompt",
};
{{PermissionStatus}} instances are created with a [[\query]] internal slot, which is an instance of a feature's [=powerful feature/permission descriptor type=].
The "granted", "denied", and "prompt" enum values represent the concepts of [=permission/granted=], [=permission/denied=], and [=permission/prompt=] respectively.
To create a `PermissionStatus` for a given {{PermissionDescriptor}} |permissionDesc|:
The name attribute returns the value it was initialized to.
The state attribute returns the latest value that was set on the current instance.
The onchange attribute is an event handler whose corresponding
event handler event type is change.
Whenever the [=user agent=] is aware that the state of a {{PermissionStatus}} instance |status| has changed, it asynchronously runs the `PermissionStatus` update steps:
change at |status|.
A {{PermissionStatus}} object MUST NOT be garbage collected if it has an [=event listener=] whose type is `change`.
enum PermissionName {
"accelerometer",
"ambient-light-sensor",
"background-fetch",
"background-sync",
"bluetooth",
"camera",
"display-capture",
"geolocation",
"gyroscope",
"magnetometer",
"microphone",
"midi",
"nfc",
"notifications",
"persistent-storage",
"push",
"screen-wake-lock",
"speaker-selection",
"xr-spatial-tracking",
};
Each enumeration value in the {{PermissionName}} enum identifies a powerful feature.
The accelerometer enum value identifies the [[[?accelerometer]]] API [=powerful feature=].
The ambient-light-sensor enum value identifies the [[[?ambient-light]]] [=powerful feature=].
The background-fetch enum value identifies the [[[?background-fetch]]] [=powerful feature=].
The background-sync enum value identifies the [[[?web-background-sync]]] [=powerful feature=].
The bluetooth enum value identifies the [[[?web-bluetooth]]] [=powerful feature=].
The camera and microphone enum values identify the [[[?mediacapture-streams]]] [=powerful features=].
The display-capture enum value identifies the [[[?screen-capture]]] [=powerful feature=].
The geolocation enum value identifies the [[[?Geolocation]]] [=powerful feature=].
The gyroscope enum value identifies the [[[?gyroscope]]] API [=powerful feature=].
The magnetometer enum value identifies the [[[?magnetometer]]] API [=powerful feature=].
The midi enum value identifies the [[[?webmidi]]] [=powerful feature=].
The nfc enum value identifies the [[[?web-nfc]]] [=powerful feature=].
The notifications enum value identifies the [[[?notifications]]] [=powerful feature=].
The persistent-storage enum value identifies the [[[?storage]]] [=powerful feature=].
The push enum value identifies the [[[?push-api]]] [=powerful feature=].
The speaker-selection enum value identifies the [[[?audio-output]]] [=powerful feature=].
The xr-spatial-tracking enum value identifies the [[[?webxr]]] Device API [=powerful feature=].
The screen-wake-lock enum value identifies the [[[screen-wake-lock]]] [=powerful feature=]. It is a [=default powerful feature=].
This [=powerful feature=] only has a single implementation, and therefore, as per the W3C Process, it is [=at risk=].
Although technically this specification and the [[[Permissions-Policy]]] specification deal with "permissions", each specification serves a distinct purpose in the platform. Nevertheless, the two specifications do explicitly overlap.
On the one hand, this specification exclusively concerns itself with [=powerful features=] whose access is managed through a user-agent mediated permissions UI (i.e., permissions where the user gives express consent before that feature can be used, and where the user retains the ability to deny that permission at any time for any reason). These powerful features are registered in the [[[powerful-feature-registry]]].
On the other hand, the [[[Permissions-Policy]]] specification allows developers to selectively enable and disable [=powerful features=] through a "[=Document/permissions policy=]" (be it a HTTP header or a the [^iframe/allow^] attribute). The APIs and features in scope for the [[[Permissions-Policy]]] specification go beyond those identified in the [[[powerful-feature-registry]]] (e.g., "sync-xhr" and "gamepad"). In that sense, the Permissions Policy subsumes this specification in that [[[Permissions-Policy]]] governs whether a feature is available at all, independently of this specification.
A powerful feature that has been disabled by the [[[Permissions-Policy]]] specification always has its [=permission state=] reflected as "denied" by this specification. This occurs because [=getting the current permission state|reading the current permission=] relies on [[HTML]]'s "[=allowed to use=]" check, which itself calls into the [[[Permissions-Policy]]] specification. Important to note here is the sharing of permission names across both specifications. Both this specification and the [[[Permissions-Policy]]] specification rely on other specifications defining the names of the permission and [=powerful feature/name=], and they are usually named the same thing (e.g., "geolocation" of the [[[Geolocation]]], and so on).
Finally, it's not possible for a powerful feature to ever become "granted" through any means provided by the [[[Permissions-Policy]]] specification. The only way that a [=powerful feature=] can be [=permission/granted=] is by the user giving [=express permission=] or by some user agent policy.
Automated testing of this specification is performed using the API provided by the Permissions Automation document.
An adversary could use a permission state as an element in creating a "fingerprint" corresponding to an end-user. Although an adversary can already determine the state of a permission by actually using the API, that often leads to a UI prompt being presented to the end-user (if the permission was not already [=permission/granted=]). Even though this API doesn't expose new fingerprinting information to websites, it makes it easier for an adversary to have discreet access to this information.
A user agent SHOULD provide a means for the user to review, update, and reset the [=permission=] [=permission/state=] of [=powerful features=] associated with a realm or origin.
There are no documented security considerations at this time. Readers are instead encouraged to read section [[[#privacy-considerations]]].
The editors would like to thank Adrienne Porter Felt, Anne van Kesteren, Domenic Denicola, Jake Archibald and Wendy Seltzer for their help with the API design and editorial work.