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 other sources this specification hasn’t anticipated.

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<BluetoothRequestDeviceFilter> filters;
  sequence<BluetoothServiceUUID> optionalServices = [];
};

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 {
  readonly attribute Permissions permissions;
};

[Exposed=(Worker)]
partial interface WorkerNavigator {
  readonly attribute Permissions permissions;
};

8. Permissions interface

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

  Promise<PermissionStatus> request(PermissionDescriptor permissionDesc);

  Promise<PermissionStatus> revoke(PermissionDescriptor permissionDesc);
};

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

1. If permissionDesc.name has a permission descriptor type other than PermissionDescriptor, convert the underlying ECMAScript object to the permission descriptor type dictionary as described in [WEBIDL], then:
   • If that operation failed, return a Promise rejected with a TypeError and abort these steps.
   • Otherwise, set permissionDesc to the result of the operation.
2. Let promise be a newly-created Promise.
3. Return promise and continue the following steps asynchronously.
4. Run the steps to create a PermissionStatus for permissionDesc, and let status be the result.
5. Run status@[[query]].name’s permission query algorithm, passing status@[[query]] and status.
6. Resolve promise with status.

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

1. If permissionDesc.name has a permission descriptor type other than PermissionDescriptor, convert the underlying ECMAScript object to the permission descriptor type dictionary as described in [WEBIDL], then:
   • If that operation failed, return a Promise rejected with a TypeError and abort these steps.
   • Otherwise, set permissionDesc to the result of the operation.
2. Let promise be a newly-created Promise.
3. Return promise and continue the following steps asynchronously.
4. Run the steps to create a PermissionStatus for permissionDesc, and let status be the result.
5. Run the permission request algorithm of the feature named permissionDesc.name with permissionDesc and status as arguments.
6. If the previous step threw an exception, reject promise with that exception.
7. Otherwise resolve promise with status.

When the revoke(permissionDesc) method is invoked, this constitutes new information about the user’s intent. The UA must return a new promise promise and run the following steps in parallel:

1. If any tasks run due to § 5.3 Reacting to users revoking permission, wait for them to finish.
2. Resolve promise with the result of query(permissionDesc).

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.

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

1. Run the boolean permission query algorithm on permissionDesc and status.
2. If status.state is not "prompt", abort these steps.
3. Request permission to use permissionDesc.
4. Run the boolean 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 boolean permission request algorithm, since it can never return an appropriate object-capability.

10. Permission Registry

enum PermissionName {
  "geolocation",
  "notifications",
  "push",
  "midi",
  "camera",
  "microphone",
  "speaker",
  "device-info",
  "background-sync",
  "bluetooth",
  "persistent-storage",
};

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.

An optional extra permission data type

If specified, the extra permission data algorithm is usable for this feature. The feature will specify any constraints on the values this algorithm can return.

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() method and the PermissionStatus update steps. If unspecified, this defaults to the boolean permission query algorithm.

A permission request algorithm

Takes an instance of the permission descriptor type and a newly-created instance of the permission result type. Uses the algorithms in § 5.2 Requesting more permission to show the user any necessary prompt to try to increase permissions, and updates the instance permission result type to match. May throw an exception if the request can fail exceptionally. (Merely being denied permission is not exceptional.) Used by Permissions' request() method. If unspecified, this defaults to the boolean permission request 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 Permissions' revoke() method and run when the UA receives new information about the user’s intent. If unspecified, this defaults to doing nothing.

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