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) (4) (5) (6)9. 
    Common permission algorithms
   (2) {
  required PermissionName name#dom-permissiondescriptor-nameReferenced in:6. 
    Status of a permission
   (2);
};

A permission is described by a name and other properties that depend on the name. The simplest permissions require only a name, but some others have more detailed structure that requires more information to describe it. In that case, they should define a customized permission descriptor type 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:

A permission descriptor type#permission-descriptor-typeReferenced 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

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

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

Takes an instance of the permission descriptor 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 PermissionStatus 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 permission descriptor type, 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 PermissionStatus#permissionstatusReferenced 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;
};

PermissionStatus instances are created with the following internal slots:

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

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

[[query]]#dom-permissionstatus-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 PermissionStatus instance status are as follows:

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

The steps to create a PermissionStatus#create-a-permissionstatusReferenced 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 status be a new instance of permission’s permission result type, with the internal slots filled as:

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

3. Return status.

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

The onchange#dom-permissionstatus-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 PermissionStatus instance status has changed, it MUST asynchronously run the following steps:

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

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<PermissionStatus> query(PermissionDescriptor permissionDesc);

  Promise<PermissionStatus> request(PermissionDescriptor permissionDesc);

  Promise<PermissionStatus> 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 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 steps to update the state on status.
6. Resolve promise with status.

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 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. Let permission be the permission named by permissionDesc.name.
5. Run the steps to create a PermissionStatus for permissionDesc, and let status be the result.
6. Run the steps to retrieve the permission storage for permission, and let storage be the result.
7. Let result be the result of promise-calling permission’s permission request algorithm with storage, permissionDesc, and status as arguments.
8. Resolve promise with the result of transforming result 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 status.

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 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. 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 PermissionStatus for permissionDesc, and let status be the result.
8. Run the steps to update the state on status.
9. Resolve promise with status.

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 PermissionStatus status, runs the following steps:

1. Set status.state to storage.state

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

1. TODO