Permissions

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.

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

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

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.

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.

7. Navigator and WorkerNavigator extension

[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.

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.

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;
};

{
  "descriptor": {
    "name": "midi",
    "sysex": true
  },
  "state": "granted"
}