The Permissions API

3. Permission descriptor

dictionary PermissionDescriptor#dictdef-permissiondescriptorReferenced in:3. 
    Permission descriptor
  4. 
    Permission Registry
   (2)4.3. 
      Push
    4.4. 
      Midi
    4.5. 
      Media Devices
    6. 
    Status of a permission
   (2)8. 
    Permissions interface
   (2) (3)9. 
    Common permission algorithms
   (2) {
  required PermissionName name#dom-permissiondescriptor-nameReferenced in:6. 
    Status of a permission
   (2);
};

A permission is defined by a name and other properties that depend on the name. The simplest permissions require only a name, but some others will require more information, in which case, they should have an associated PermissionDescriptor dictionary that inherits from PermissionDescriptor.

4. Permission Registry

enum PermissionName#enumdef-permissionnameReferenced in:3. 
    Permission descriptor
  4. 
    Permission Registry
  5. 
    Permission Store
  6. 
    Status of a permission
   {
  "geolocation",
  "notifications",
  "push",
  "midi",
  "camera",
  "microphone",
  "speaker",
  "device-info",
  "background-sync",
};

Each enumeration value in the PermissionName enum identifies a permission#permissionReferenced in:4. Permission Registry (2)6. Status of a permission (2) (3)8. Permissions interface , which consists of the following algorithms and types:

An associated PermissionDescriptor#associated-permissiondescriptorReferenced in:3. Permission descriptor 4. Permission Registry (2)4.3. Push 4.4. Midi 4.5. Media Devices 8. Permissions interface (2) (3) (4) (5) (6)

PermissionDescriptor or one of its subtypes. If unspecified, this defaults to PermissionDescriptor.

A permission storage type#permission-storage-typeReferenced in:4. Permission Registry (2) (3)4.5. Media Devices

PermissionStorage or one of its subtypes. If unspecified, this defaults to PermissionStorage.

A permission result type#permission-result-typeReferenced in:4. Permission Registry (2) (3) (4)4.5. Media Devices 6. Status of a permission

PermissionResult or one of its subtypes. If unspecified, this defaults to PermissionResult.

A permission query algorithm#permission-query-algorithmReferenced in:4.5. Media Devices 6. Status of a permission

Takes an instance of the associated PermissionDescriptor type, an instance of the permission storage type that’s currently stored for this permission, 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 PermissionResult update steps. If unspecified, this defaults to the boolean permission query algorithm.

A permission request algorithm#permission-request-algorithmReferenced in:4.5. Media Devices 8. Permissions interface

Takes the previously-stored instance of the permission storage type, an instance of the associated PermissionDescriptor, and a newly-created instance of the permission result type. Shows the user any necessary prompt to try to increase permissions, and updates the instances of the permission storage type and permission result type to match. May return a Promise if the request can fail exceptionally. (Merely being denied permission is not exceptional.) Used by Permissions' request() method, which handles reading and writing the permission store. If unspecified, this defaults to the boolean permission request algorithm.

A permission revocation algorithm#permission-revocation-algorithmReferenced in:4.5. Media Devices 8. Permissions interface

Takes no arguments. Updates any other parts of the implementation that need to be kept in sync after an entry is removed from the permission store. Triggered by Permissions' revoke() method. If unspecified, this defaults to doing nothing.

A boolean permission#boolean-permissionReferenced in:4.1. Geolocation 4.2. Notifications is a permission with all types and algorithms defaulted.

5. Permission Store #permission-storeReferenced in:4. Permission Registry

User agents MAY use a form of storage to keep track of web site permissions. When they do, they MUST have a permission storage identifier#permission-storage-identifierReferenced in:5. Permission Store (2) (3) (4) (5) (6) which is linked to a PermissionStorage instance or one of its subtypes.

To get a permission storage identifier#get-a-permission-storage-identifierReferenced in:6. Status of a permission 8. Permissions interface (2) for a PermissionName name and an environment settings object settings, the UA MUST return a tuple consisting of:

1. name
2. settings’ origin
3. optional UA-specific data like whether settings’ browsing context has a parent browsing context, or settings’ top-level browsing context’s origin

dictionary PermissionStorage#dictdef-permissionstorageReferenced in:4. 
    Permission Registry
   (2)5. 
    Permission Store
   (2) (3) (4) (5) (6) (7)9. 
    Common permission algorithms
   {
  // PermissionStorage is just an explanatory device.
  // Instances are never received from or passed to Javascript code.

  required PermissionState state;
};

The steps to retrieve a permission storage entry#retrieve-a-permission-storage-entryReferenced in:6. Status of a permission of a permission storage identifier are as follows:

1. If the user agent has a PermissionStorage associated with the permission storage identifier in its permission store, it MUST return the PermissionStorage.
2. Otherwise, it MUST return undefined.

The steps to create a permission storage entry#create-a-permission-storage-entryReferenced in:8. Permissions interface for a permission storage identifier are as follows:

1. If the user agent has a PermissionStorage associated with the permission storage identifier in its permission store, it MUST overwrite it to the given PermissionStorage.
2. Otherwise, it MUST write the new PermissionStorage to its permission store.

The steps to delete a permission storage entry#delete-a-permission-storage-entryReferenced in:8. Permissions interface of a permission storage identifier are as follows:

1. If the user agent has a PermissionStorage associated with the permission storage identifier in its permission store, it MUST remove it.

6. Status of a permission

enum PermissionState#enumdef-permissionstateReferenced in:5. 
    Permission Store
  6. 
    Status of a permission
   {
  "granted",
  "denied",
  "prompt",
};

The "granted"#dom-permissionstate-grantedReferenced in:4.5. Media Devices 6. Status of a permission 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"#dom-permissionstate-deniedReferenced in:4.5. Media Devices 6. Status of a permission state represents that the caller will not be able to access the feature.

The "prompt"#dom-permissionstate-promptReferenced in:4.5. Media Devices 6. Status of a permission (2) 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.

The steps to retrieve the permission storage#retrieve-the-permission-storageReferenced in:6. Status of a permission 8. Permissions interface for a given PermissionName name are as follows:

1. Get a permission storage identifier for name and the current environment settings object, and let identifier be the result.
2. Run the steps to retrieve a permission storage entry of identifier.
3. If the result of those steps are not undefined, return it and abort these steps.
4. Otherwise, the user agent MUST return a default value based on user agent’s defined heuristics. For example, {state: "prompt"} can be a default value, but it can also be based on frequency of visits.

[Exposed=(Window,Worker)]
interface PermissionResult#permissionresultReferenced in:4. 
    Permission Registry
   (2)6. 
    Status of a permission
   (2) (3)8. 
    Permissions interface
   (2) (3)9. 
    Common permission algorithms
   (2) : EventTarget {
  readonly attribute PermissionState state;
  attribute EventHandler onchange;
};

PermissionResult instances are created with the following internal slots:

[[permission]]#dom-permissionresult-permission-slotReferenced in:6. Status of a permission (2) (3)

A permission. [[permission]] is always the permission named [[query]].name.

[[query]]#dom-permissionresult-query-slotReferenced in:6. Status of a permission (2) (3) (4)

A PermissionDescriptor.

The steps to update the state#update-the-stateReferenced in:6. Status of a permission 8. Permissions interface (2) of a PermissionResult instance result are as follows:

1. Run the steps to retrieve the permission storage for result@[[query]].name, and let storage be the result.
2. Run result@[[permission]]’s permission query algorithm, passing result@[[query]], storage, and result.

The steps to create a PermissionResult#create-a-permissionresultReferenced in:8. Permissions interface (2) (3) for a given PermissionDescriptor permissionDesc are as follow:

1. Let permission be the permission named by permissionDesc.name.
2. Let result be a new instance of permission’s permission result type, with the internal slots filled as:

   Slot	Value
   [[permission]]	permission
   [[query]]	permissionDesc

3. Return result.

The state#dom-permissionresult-stateReferenced in:6. Status of a permission attribute MUST return the latest value that was set on the current instance.

The onchange#dom-permissionresult-onchangeReferenced in:6. Status of a permission attribute is an event handler whose corresponding event handler event type is change.

Whenever the user agent is aware that the state of a PermissionResult instance result has changed, it MUST asynchronously run the following steps:

1. Run the steps to update the state of result.
2. Queue a task on the permission task source to fire an event named change at result.

7. Navigator and WorkerNavigator extension

A Permissions instance is exposed on the navigator object for Window and Worker contexts.

[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#permissionsReferenced in:4. 
    Permission Registry
   (2) (3)7. 
    Navigator and WorkerNavigator extension
   (2) (3) {
  Promise<PermissionResult> query(PermissionDescriptor permissionDesc);

  Promise<PermissionResult> request(PermissionDescriptor permissionDesc);

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

When the query()#dom-permissions-queryReferenced in:4. Permission Registry 8. Permissions interface method is invoked, the user agent MUST run the following query a permission algorithm, passing the parameter permissionDesc:

1. If permissionDesc.name has an associated PermissionDescriptor, convert the underlying ECMAScript object to the associated PermissionDescriptor 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 PermissionResult for permissionDesc, and let result be the result.
5. Run the steps to update the state on result.
6. Resolve promise with result.

When the request()#dom-permissions-requestReferenced in:4. Permission Registry 8. Permissions interface method is invoked, the user agent MUST run the following request a permission algorithm, passing the parameter permissionDesc:

1. If permissionDesc.name has an associated PermissionDescriptor, convert the underlying ECMAScript object to the associated PermissionDescriptor 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. Let permission be the permission named by permissionDesc.name.
5. Run the steps to create a PermissionResult for permissionDesc, and let result be the result.
6. Run the steps to retrieve the permission storage for permission, and let storage be the result.
7. Let requestPromise be the result of promise-calling permission’s permission request algorithm with storage, permissionDesc, and result as arguments.
8. Resolve promise with the result of transforming requestPromise with a fulfillment handler that runs the following steps.
9. Get a permission storage identifier for permissionDesc.name and the current environment settings object, and create a permission storage entry mapping this identifier to storage.
10. Return result.

When the revoke()#dom-permissions-revokeReferenced in:4. Permission Registry 8. Permissions interface method is invoked, the user agent MUST run the following revoke a permission algorithm, passing the parameter permissionDesc:

1. If permissionDesc.name has an associated PermissionDescriptor, convert the underlying ECMAScript object to the associated PermissionDescriptor 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. Get a permission storage identifier for permission.name and the current environment settings object, and let identifier be the result.
5. Run the steps to delete a permission storage entry using identifier.
6. Run permissionDesc.name’s permission revocation algorithm.
7. Run the steps to create a PermissionResult for permissionDesc, and let result be the result.
8. Run the steps to update the state on result.
9. Resolve promise with result.

9. Common permission algorithms

The boolean permission query algorithm#boolean-permission-query-algorithmReferenced in:4. Permission Registry , given a PermissionDescriptor permissionDesc, a PermissionStorage storage, and a PermissionResult result, runs the following steps:

1. Set result.state to storage.state

The boolean permission request algorithm#boolean-permission-request-algorithmReferenced in:4. Permission Registry , given a PermissionDescriptor permission and a PermissionResult result, runs the following steps:

1. TODO