Permissions

Editor’s Draft,

This version:
https://w3c.github.io/permissions/
Latest published version:
https://www.w3.org/TR/permissions/
Previous Versions:
Feedback:
public-webappsec@w3.org with subject line “[permissions] … message topic …
Issue Tracking:
GitHub
Inline In Spec
Editors:
Mounir Lamouri (Google Inc.)
Marcos Cáceres (Mozilla)
Jeffrey Yasskin (Google Inc.)
Participate:
We are on Github.
File a bug.
Commit history.
Implementation status:
Blink/Chromium
Gecko

Abstract

The Permissions Standard defines common infrastructure for other specifications that need to interact with browser permissions. It also defines an API to allow web applications to query and request changes to the status of a given permission.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Changes to this document may be tracked at https://github.com/w3c/webappsec.

The (archived) public mailing list public-webappsec@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “permissions” in the subject, preferably like this: “[permissions] …summary of comment…

This document was produced by the Web Application Security Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

1. Scope of this document

This section is non-normative.

This document specifies a model for permissions to use powerful features on the Web platform and an API to query the current permission state of those features.

Current Web APIs have different ways to deal with permissions. For example, the [notifications] API allows developers to request a permission and check the permission status explicitly. Others expose the status to web pages when they try to use the API, like the [geolocation-API] which fails if the permission was not granted without allowing the developer to check beforehand.

The query() function provides a tool for developers to control when permission prompts are shown.

The solution described in this document is meant to be extensible, but isn’t expected to be applicable to all the current and future permissions available in the web platform. Working Groups that are creating specifications whose permission model doesn’t fit in the model described in this document should contact the editors by filing an issue.

2. Privacy considerations

This section is non-normative.

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 permission request UI being presented to the end-user (if the permission was not already "granted"). Thus, 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. Thus, implementations are encouraged to have an option for users to block (globally or selectively) the querying of permission states.

3. Definitions

New information about the user’s intent
The UA may collect information about a user’s intentions in any way its authors believe is appropriate. 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.
The implicit signals could be, for example, the install status of a web application or frequency and recency of visits. A user that has installed a web application and used it frequently and recently is more likely to trust it. Implementations are advised to exercise caution when relying on implicit signals.
Powerful feature
A feature of a UA that some code might not be allowed to access, for example because its environment settings object doesn’t satisfy some criteria, or because the user hasn’t given permission.

4. Descriptions of permission requests

dictionary PermissionDescriptor {
  required PermissionName name;
};

Each powerful feature has one or more aspects that websites can request permission to access. To describe these aspects, each feature defines a subtype of PermissionDescriptor to be its permission descriptor type.

The "midi" feature has two aspects: access to normal messages, and access to system exclusive messages. Thus, its permission descriptor type is:

dictionary MidiPermissionDescriptor : PermissionDescriptor {
  boolean sysex = false;
};

The "bluetooth" feature lets sites request to access whatever Bluetooth devices are close to to the user’s device. Thus, its permission descriptor type is:

dictionary BluetoothPermissionDescriptor : PermissionDescriptor {
  DOMString deviceId;
  sequence<BluetoothLEScanFilterInit> filters;
  sequence<BluetoothServiceUUID> optionalServices = [];
  boolean acceptAllDevices = false;
};

General access to Bluetooth devices is represented by {name: 'bluetooth'}; access to a particular device is represented by {name: 'bluetooth', deviceId: "id"}; and access to a device with a particular service is represented by {name: 'bluetooth', filters: [{services: ['service']}]}

5. Permission states

The user agent is responsible for tracking what powerful features each 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.

Other specifications can also add more constraints on the UA’s behavior in these algorithms.

Within this section, descriptor is an instance of the permission descriptor type of the powerful feature named by descriptor.name.

5.1. Reading the current permission state

A descriptor’s permission state for an optional environment settings object settings is the result of the following algorithm, which returns one of "granted", "prompt", or "denied":

  1. If settings wasn’t passed, set it to the current settings object.
  2. If settings is a non-secure context and descriptor.name isn’t allowed in non-secure contexts, then return "denied".
  3. If there exists a policy-controlled feature identified by descriptor.name and settings has an associated Document named document, run the following step:
    1. If document is not allowed to use the feature identified by descriptor.name return "denied".
  4. If there was a previous invocation of this algorithm with the same descriptor and settings, returning previousResult, and the UA has not received new information about the user’s intent since that invocation, return previousResult.
  5. Return whichever of the following options most accurately reflects the user’s intent for the calling algorithm, taking into account any permission state constraints for descriptor.name:
    succeed without prompting the user
    "granted"
    show the user a prompt to decide whether to succeed
    "prompt"
    fail without prompting the user
    "denied"

Safari is the only known UA that returns different results from this algorithm for different settings objects with the same origin. We should test which of the several possible settings objects it uses.

As a shorthand, a PermissionName name’s permission state is the permission state of a PermissionDescriptor with its name member set to name.

Some powerful features have more information associated with them than just a PermissionState. For example, getUserMedia() needs to determine which cameras the user has granted the current realm permission to access. Each of these features defines an extra permission data type. If a PermissionName 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:

  1. If settings wasn’t passed, set it to the current settings object.
  2. If there was a previous invocation of this algorithm with the same name and settings, returning previousResult, and the UA has not received new information about the user’s intent since that invocation, return previousResult.
  3. Return the instance of name’s extra permission data type that matches the UA’s impression of the user’s intent, taking into account any extra permission data constraints for name.

5.2. Requesting more permission

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 "granted" or "denied".

  1. Let current state be the descriptor’s permission state.
  2. If current state is not "prompt", return current state and abort these steps.
  3. Ask the user’s permission for the calling algorithm to use the powerful feature described by descriptor.
  4. If the user grants permission, return "granted"; otherwise return "denied". The user’s interaction may provide new information about the user’s intent for this realm and other realms with the same origin.

    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 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 "denied" or one of the options.

  1. If descriptor’s permission state is "denied", return "denied" and abort these steps.
  2. If descriptor’s permission state is "granted", the UA may return one of options and abort these steps. If the UA returns without prompting, then subsequent prompts for the user to choose from the same set of options with the same descriptor must return the same option, unless the UA receives new information about the user’s intent.
  3. Ask the user to choose one of the options or deny permission, and wait for them to choose. If the calling algorithm specified extra information to include in the prompt, include it.
  4. If the user chose an option, return it; otherwise return "denied". If the user’s interaction indicates they intend this choice to apply to other realms, then treat this this as new information about the user’s intent for other realms with the same origin.

    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 name member set to name.

5.3. Reacting to users revoking permission

When the UA learns that the user no longer intends to grant permission for a realm to use a feature, it must queue a task on the Realm’s settings object’s responsible event loop to run that feature’s permission revocation algorithm.

6. Status of a permission

enum PermissionState {
  "granted",
  "denied",
  "prompt",
};

The "granted" state represents that the caller will be able to successfuly access the feature without having the user agent asking the user’s permission.

The "denied" state represents that the caller will not be able to access the feature.

The "prompt" state represents that the user agent will be asking the user’s permission if the caller tries to access the feature. The user might grant, deny or dismiss the request.

[Exposed=(Window,Worker)]
interface PermissionStatus : EventTarget {
  readonly attribute PermissionState state;
  attribute EventHandler onchange;
};

PermissionStatus instances are created with a [[query]] internal slot, which is an instance of a feature’s permission descriptor type.

To create a PermissionStatus for a given PermissionDescriptor permissionDesc, return a new instance of the permission result type for the feature named by permissionDesc.name, with the [[query]] internal slot initialized to permissionDesc.

The state attribute MUST return 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 MUST asynchronously run the following steps:

  1. Run status@[[query]].name’s permission query algorithm, passing status@[[query]] and status.
  2. Queue a task on the permission task source to fire an event named change at status.
[Exposed=(Window)]
partial interface Navigator {
  [SameObject] readonly attribute Permissions permissions;
};
[Exposed=(Worker)]
partial interface WorkerNavigator {
  [SameObject] readonly attribute Permissions permissions;
};

8. Permissions interface

[Exposed=(Window,Worker)]
interface Permissions {
  Promise<PermissionStatus> query(object permissionDesc);
};

When the query(permissionDesc) method is invoked, the user agent MUST run the following query a permission algorithm, passing the parameter permissionDesc:

  1. 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.
  2. 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.
  3. Let promise be a newly-created Promise.
  4. Return promise and continue the following steps asynchronously.
  5. Run the steps to create a PermissionStatus for typedDescriptor, and let status be the result.
  6. Run status@[[query]].name’s permission query algorithm, passing status@[[query]] and status.
  7. Resolve promise with status.
If a developer wants to check multiple permissions at once, the editors recommend the use of Promise.all(). An example can be found in the Examples section.

9. Common permission algorithms

The boolean permission query algorithm, given a PermissionDescriptor permissionDesc and a PermissionStatus status, runs the following steps:

  1. Set status.state to permissionDesc’s permission state.

10. Permission Registry

enum PermissionName {
  "geolocation",
  "notifications",
  "push",
  "midi",
  "camera",
  "microphone",
  "speaker",
  "device-info",
  "background-fetch",
  "background-sync",
  "bluetooth",
  "persistent-storage",
  "ambient-light-sensor",
  "accelerometer",
  "gyroscope",
  "magnetometer",
  "clipboard",
  "display-capture",
};

The enumeration values "accelerometer", "gyroscope" and "magnetometer" are considered provisional and are subject to change based on feedback from early implementations. See w3c/sensors#22 issue for more information.

Each enumeration value in the PermissionName enum identifies a powerful feature. Each powerful feature has the following permission-related flags, algorithms, and types:

An allowed in non-secure contexts flag
By default, only secure contexts can use powerful features. If this flag is set for a feature, the UA may grant access to it in non-secure contexts too.
A permission descriptor type

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 "granted", descriptorB’s permission state must also be "granted", and if descriptorB’s permission state is "denied", descriptorA’s permission state must also be "denied".

{name: "midi", sysex: true} ("midi-with-sysex") is 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.

Optional permission state constraints
Constraints on the values that the UA can return as a descriptor’s permission state. Defaults to no constraints beyond the user’s intent.
An optional extra permission data type
If specified, the extra permission data algorithm is usable for this feature.
Optional extra permission data constraints
Constraints on the values that the UA can return as a PermissionName's extra permission data. Defaults to no constraints beyond the user’s intent.
A permission result type
PermissionStatus or one of its subtypes. If unspecified, this defaults to PermissionStatus.
A permission query algorithm
Takes an instance of the permission descriptor type and a new or existing instance of the permission result type, and updates the permission result type instance with the query result. Used by Permissions' query(permissionDesc) method and the PermissionStatus update steps. If unspecified, this defaults to the boolean permission query algorithm.
A permission revocation algorithm
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 extra permission data. Run by § 5.3 Reacting to users revoking permission. If unspecified, this defaults to doing nothing.

A boolean feature is a powerful feature with all of the above types and algorithms defaulted.

10.1. Geolocation

The "geolocation" permission is the permission associated with the usage of the [geolocation-API]. It is a boolean feature and is allowed in non-secure contexts.

10.2. Notifications

The "notifications" permission is the permission associated with the usage of the [notifications] API. It is a boolean feature and is allowed in non-secure contexts.

10.3. Push

The "push" permission is the permission associated with the usage of the [push-api].

permission descriptor type
dictionary PushPermissionDescriptor : PermissionDescriptor {
  boolean userVisibleOnly = false;
};

{name: "push", userVisibleOnly: false} is stronger than {name: "push", userVisibleOnly: true}.

10.4. Midi

The "midi" permission is the permission associated with the usage of [webmidi]. "midi" is allowed in non-secure contexts.

permission descriptor type
dictionary MidiPermissionDescriptor : PermissionDescriptor {
  boolean sysex = false;
};

{name: "midi", sysex: true} is stronger than {name: "midi", sysex: false}.

10.5. Media Devices

The "camera", "microphone" , and "speaker" permissions are associated with permission to use media devices as specified in [GETUSERMEDIA] and [audio-output]. "speaker" is allowed in non-secure contexts. "camera" and "microphone" MAY be allowed in non-secure contexts.

permission descriptor type
dictionary DevicePermissionDescriptor : PermissionDescriptor {
  DOMString deviceId;
};

A permission covers access to the device given in the associated descriptor.

If the descriptor does not have a deviceId, its semantic is that it queries for access to all devices of that class. Thus, if a query for the "camera" permission with no deviceId returns "granted", the client knows that there will never be a permission prompt for a camera, and if "denied" is returned, it knows that no getUserMedia request for a camera will succeed.

If a permission state is present for access to some, but not all, cameras, a query without the deviceId will return "prompt".

Note that a "granted" permission is no guarantee that getUserMedia will succeed. It only guarantees that the user will not be prompted for permission. There are many other things (such as constraints or the camera being in use) that can cause getUserMedia to fail.

extra permission data type
A list of deviceId values for the devices the user has made a non-default decision on access to.
permission query algorithm
The permission query algorithm runs the following steps:
  1. If permissionDesc.deviceId exists in the extra permission data, set status.state to permissionDesc’s permission state and terminate these steps.
  2. Let global be a copy of permissionDesc with the deviceId member removed.
  3. Set status.state to global’s permission state.
permission request algorithm
The permission request algorithm runs the following steps:
  1. Let result be the result of running the boolean permission request algorithm.
  2. If result is "granted", the UA MUST set the "device-info" permission to "granted" for this realm.
  3. If result is "granted" and descriptor.name is either "camera" or "microphone", the UA MAY set the "direct-connection" permission to "granted" for this realm.
  4. The UA MAY treat result as new information about the user’s intent with respect to the "device-info" permission for this realm and other realms with the same origin, provided it doesn’t violate the previous step.
  5. Return result.
permission revocation algorithm
When permission for a device is revoked, the UA MUST run the algorithm to stop the track for any other reason than the stop() method being invoked for each MediaStreamTrack sourced from that device.

The "device-info" permission controls access to the name and capabilities associated with a deviceId, as well as whether devicechange events fire when the current browsing context is not in focus. The "device-info" permission MUST be revoked when deviceIds for an origin are reset.

10.6. Background Fetch

The "background-fetch" permission is the permission associated with the usage of [background-fetch].

10.7. Background Sync

The "background-sync" permission is the permission associated with the usage of [web-background-sync].

10.8. Ambient Light Sensor

The "ambient-light-sensor" permission is the permission associated with the usage of the [ambient-light] API.

Its permission revocation algorithm is the result of calling generic sensor permission revocation algorithm passing it "ambient-light-sensor" as argument.

10.9. Accelerometer

The "accelerometer" permission is the permission associated with the usage of the [accelerometer] API.

Its permission revocation algorithm is the result of calling generic sensor permission revocation algorithm passing it "accelerometer" as argument.

10.10. Gyroscope

The "gyroscope" permission is the permission associated with the usage of the [gyroscope] API.

Its permission revocation algorithm is the result of calling generic sensor permission revocation algorithm passing it "gyroscope" as argument.

10.11. Magnetometer

The "magnetometer" permission is the permission associated with the usage of the [magnetometer] API.

Its permission revocation algorithm is the result of calling generic sensor permission revocation algorithm passing it "magnetometer" as argument.

10.12. Clipboard

The "clipboard" permission is the permission associated with the usage of the asynchronous methods in the [clipboard-apis].

10.13. Screen Capture

The "display-capture" permission is the permission associated with the usage of [screen-capture].

permission state constraints
Valid values for this descriptor’s permission state are "prompt" and "denied". The user agent MUST NOT ever set this descriptor’s permission state to "granted".

10.14. Direct Connection

The "direct-connection" permission upgrades to a less strict IP handling mode of [rtcweb-ip-handling].

11. Automation

For the purposes of user-agent automation and application testing, this document defines the following extension command for the [WebDriver] specification.

dictionary PermissionSetParameters {
  required PermissionDescriptor descriptor;
  required PermissionState state;
  boolean oneRealm = false;
};

11.1. Set Permission

HTTP Method URI Template
POST /session/{session id}/permissions

The Set Permission extension command simulates user modification of a PermissionDescriptor's permission state.

The remote end steps are:

  1. Let parameters be the parameters argument, converted to an IDL value of type PermissionSetParameters. If this throws an exception, return a WebDriver error with WebDriver error code invalid argument.
  2. Let rootDesc be parameters.descriptor.
  3. Let typedDescriptor be the object rootDesc refers to, converted to an IDL value of rootDesc.name’s permission descriptor type. If this throws an exception, return a WebDriver error with WebDriver error code invalid argument.
  4. If parameters.state is an inappropriate permission state for any implementation-defined reason, return a WebDriver error with WebDriver error code invalid argument.

    For example, user agents that define the "midi" feature as "always on" may choose to reject command to set the permission state to "denied" at this step.

  5. Let settings be the environment settings object of the current browsing context’s active document.
  6. If settings is a non-secure context and rootDesc.name isn’t allowed in non-secure contexts, return a WebDriver error with WebDriver error code invalid argument.
  7. If parameters.oneRealm is true, let targets be a list whose sole member is settings.
  8. Otherwise, let targets be a list containing all environment settings objects whose origin is the same as the origin of settings.
  9. Let tasks be an empty list.
  10. For each environment settings object target in targets:
    1. Queue a task task on the permission task source of target’s responsible browsing context to perform the following step:
      1. Interpret parameters.state as if it were the result of an invocation of permission state for typedDescriptor with the argument target made at this moment.
    2. Append task to tasks.
  11. Wait for all tasks in tasks to have executed.
  12. Return success with data null.
To set permission for {name: "midi", sysex: true} of the current browsing context of the session with ID 23 to "granted", the local end would POST to /session/23/permissions with the body:
{
  "descriptor": {
    "name": "midi",
    "sysex": true
  },
  "state": "granted"
}

12. Examples

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.

navigator.permissions.query({ name: "geolocation" }).then(({ state }) => {
  switch (state) {
    case "granted":
      showLocalNewsWithGeolocation();
      break;
    case "prompt":
      showButtonToEnableLocalNews();
      break;
    default:
      // Don’t do anything if the permission was denied.
      break;
  }
});

This example is using the "notifications" permission for a chat application to show a notification button depending on the permission state.

function updateNotificationButton(state) {
  document.getElementById('chat-notification-button')
    .disabled = (state === 'denied');
}

navigator.permissions.query({ name: 'notifications' }).then((result) => {
  updateNotificationButton(result.state);
  result.addEventListener('change', () => {
    updateNotificationButton(result.state);
  });
});

This example is checking whether the page has the "geolocation" and the "notifications" permissions using Promise.all.

Promise.all([
  navigator.permissions.query({ name: "geolocation" }),
  navigator.permissions.query({ name: "notifications" })
])
.then(([{ state: geoState }, { state: notifState }]) => {
  console.log("Geolocation permission state is:", geoState);
  console.log("Notifications permission state is:", notifState);
});

This example is checking the permission state of the available cameras.

navigator.mediaDevices
  .enumerateDevices()
  .then(devices => {
    return Promise.all(devices
      // filter on video inputs
      .filter(({ kind }) => kind === "videoinput")
      // map to query object
      .map(({ deviceId }) => ({ name: "camera", deviceId }))
      // map to query promise
      .map(queryObj => navigator.permissions.query(queryObj))
    );
  })
  // log the state or each camera
  .then(results => results.forEach(
    ({ state }, i) => console.log(Camera ${i}: "${state}")
  ))
  .catch(
    err => console.error(err.stack)
  );

Acknowledgments

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.

Conformance

Document conventions

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:

This is an example of an informative example.

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.

Conformant Algorithms

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.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
[FEATURE-POLICY-1]
Ian Clelland. Feature Policy. 16 April 2019. WD. URL: https://www.w3.org/TR/feature-policy-1/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[PERMISSIONS-REQUEST]
Requesting Permissions. cg-draft. URL: https://wicg.github.io/permissions-request/
[PROMISES-GUIDE]
Domenic Denicola. Writing Promise-Using Specifications. 9 November 2018. TAG Finding. URL: https://www.w3.org/2001/tag/doc/promises-guide
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SECURE-CONTEXTS]
Mike West. Secure Contexts. 15 September 2016. CR. URL: https://www.w3.org/TR/secure-contexts/
[STORAGE]
Anne van Kesteren. Storage Standard. Living Standard. URL: https://storage.spec.whatwg.org/
[UIEVENTS]
Gary Kacmarcik; Travis Leithead; Doug Schepers. UI Events. 30 May 2019. WD. URL: https://www.w3.org/TR/uievents/
[WEB-BLUETOOTH]
Jeffrey Yasskin. Web Bluetooth. Draft Community Group Report. URL: https://webbluetoothcg.github.io/web-bluetooth/
[WebDriver]
Simon Stewart; David Burns. WebDriver. 5 June 2018. REC. URL: https://www.w3.org/TR/webdriver1/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

Informative References

[ACCELEROMETER]
Anssi Kostiainen. Accelerometer. 7 March 2019. WD. URL: https://www.w3.org/TR/accelerometer/
[AMBIENT-LIGHT]
Anssi Kostiainen. Ambient Light Sensor. 7 March 2019. WD. URL: https://www.w3.org/TR/ambient-light/
[AUDIO-OUTPUT]
Justin Uberti; Guido Urdaneta. Audio Output Devices API. 3 October 2017. CR. URL: https://www.w3.org/TR/audio-output/
[BACKGROUND-FETCH]
Background Fetch. cg-draft. URL: https://wicg.github.io/background-fetch/
[CLIPBOARD-APIS]
Gary Kacmarcik; Grisha Lyukshin. Clipboard API and events. 5 June 2019. WD. URL: https://www.w3.org/TR/clipboard-apis/
[geolocation-API]
Andrei Popescu. Geolocation API Specification 2nd Edition. 8 November 2016. REC. URL: https://www.w3.org/TR/geolocation-API/
[GETUSERMEDIA]
Daniel Burnett; et al. Media Capture and Streams. 2 July 2019. CR. URL: https://www.w3.org/TR/mediacapture-streams/
[GYROSCOPE]
Anssi Kostiainen. Gyroscope. 7 March 2019. WD. URL: https://www.w3.org/TR/gyroscope/
[MAGNETOMETER]
Anssi Kostiainen; Rijubrata Bhaumik. Magnetometer. 7 March 2019. WD. URL: https://www.w3.org/TR/magnetometer/
[NOTIFICATIONS]
Anne van Kesteren. Notifications API Standard. Living Standard. URL: https://notifications.spec.whatwg.org/
[PUSH-API]
Peter Beverloo; Martin Thomson. Push API. 24 July 2019. WD. URL: https://www.w3.org/TR/push-api/
[RTCWEB-IP-HANDLING]
Guo-wei Shieh; Justin Uberti. WebRTC IP Address Handling Recommendations. 20 March 2016. Active Internet-Draft. URL: https://tools.ietf.org/html/draft-ietf-rtcweb-ip-handling
[SCREEN-CAPTURE]
Martin Thomson; Keith Griffin. Screen Capture. 14 July 2016. WD. URL: https://www.w3.org/TR/screen-capture/
[WEB-BACKGROUND-SYNC]
Web Background Synchronization. cg-draft. URL: https://wicg.github.io/BackgroundSync/spec/
[WEBMIDI]
Chris Wilson; Jussi Kalliokoski. Web MIDI API. 17 March 2015. WD. URL: https://www.w3.org/TR/webmidi/

IDL Index

dictionary PermissionDescriptor {
  required PermissionName name;
};

enum PermissionState {
  "granted",
  "denied",
  "prompt",
};

[Exposed=(Window,Worker)]
interface PermissionStatus : EventTarget {
  readonly attribute PermissionState state;
  attribute EventHandler onchange;
};

[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 PushPermissionDescriptor : PermissionDescriptor {
  boolean userVisibleOnly = false;
};

dictionary MidiPermissionDescriptor : PermissionDescriptor {
  boolean sysex = false;
};

dictionary DevicePermissionDescriptor : PermissionDescriptor {
  DOMString deviceId;
};

dictionary PermissionSetParameters {
  required PermissionDescriptor descriptor;
  required PermissionState state;
  boolean oneRealm = false;
};

Issues Index

Safari is the only known UA that returns different results from this algorithm for different settings objects with the same origin. We should test which of the several possible settings objects it uses.