Permissions

A permission represents a user's decision to allow a web application to use a powerful feature . This decision is represented as a permission state .

Express permission refers to the user granting the web application the ability to use a powerful feature .

Conceptually, a permission for a powerful feature can be in one of the following states :

Denied :

The user, or the user agent or an administrator on the user's behalf, has denied access to this powerful feature . The caller will can't use the feature.

Granted :

The user, or the user agent or an administrator on the user's behalf, has given express permission to use a powerful feature . The caller will can use the feature possibly without having the user agent asking the user's permission.

Prompt :

The user has not given express permission to use the feature (i.e., it's the same as denied ). It also means that if a caller attempts to use the feature, the user agent will either be prompting the user for permission or access to the feature will be denied .

To ascertain new information about the user's intent , a user agent MAY collect and interpret information about a user's intentions. 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.

Every permission has a lifetime , which is the duration for which a particular permission remains granted before it reverts back to its default state . A lifetime could be until a particular Realm is destroyed, until a particular top-level browsing context is destroyed, a particular amount of time, or be infinite. The lifetime is negotiated between the end-user and the user agent when the user gives express permission to use a feature —usually via some permission UI or user-agent defined policy.

Every permission has a default state (usually prompt ), which is the state that the permission is in when the user has not yet given express permission to use the feature or it has been reset because its lifetime has expired.

The user agent maintains a single permission store which is a list of permission store entries . Each particular entry denoted by its descriptor and key can only appear at most once in this list.

The user agent MAY remove entries from the permission store when their respective permission 's lifetime has expired.

A permission store entry is a tuple of PermissionDescriptor descriptor , permission key key , and state state .

To get a permission store entry given a PermissionDescriptor descriptor and permission key key :

1. If the user agent's permission store contains an entry whose descriptor is descriptor , and whose key is equal to key given descriptor , return that entry.
2. Return null.

To set a permission store entry given a PermissionDescriptor descriptor , a permission key key , and a state state , run these steps:

1. Let newEntry be a new permission store entry whose descriptor is descriptor , and whose key is key , and whose state is state .
2. If the user agent's permission store contains an entry whose descriptor is descriptor , and whose key is equal to key given descriptor , replace that entry with newEntry and abort these steps.
3. Append newEntry to the user agent's permission store .

To remove a permission store entry given a PermissionDescriptor descriptor and permission key key , run these steps:

1. Remove the entry whose descriptor is descriptor , and whose key is equal to key given descriptor , from the user agent's permission store .

A permission key has its type defined by a feature's permission key type .

To determine whether a permission key key1 is equal to a permission key key2 , given a PermissionDescriptor descriptor , run the following steps:

1. If key1 is not of descriptor 's permission key type or key2 is not of descriptor 's permission key type , return false.
2. Return the result of running the permission key comparison algorithm for the feature named by descriptor 's name , passing key1 and key2 .

A powerful feature is a web platform feature (usually an API) for which a user gives express permission before the feature can be used. Except for a few notable exceptions (e.g., the Notifications API Standard ), most powerful features are also policy-controlled features . For powerful features that are also policy-controlled features , [ Permissions-Policy ] controls whether a document is allowed to use a given feature. That is, a powerful feature can only request express permission from a user if the document has permission delegated to it via the corresponding policy-controlled feature (see example below). Subsequent access to the feature is determined by the user having granted permission, or by satisfying some criteria that is equivalent to a permission grant .

A powerful feature is identified by its name , which is a string literal (e.g., "geolocation").

The user agent tracks which powerful features the user has permission to use via the environment settings object .

The permissions task source is a task source used to perform permissions-related tasks in this specification.

To get the current permission state , given a name name and an optional environment settings object settings , run the following steps. This algorithm returns a PermissionState enum value.

1. Let descriptor be a newly-created PermissionDescriptor with name initialized to name .
2. Return the permission state of descriptor with settings .

A descriptor 's permission state , given an optional environment settings object settings is the result of the following algorithm. It returns a PermissionState enum value:

1. If settings wasn't passed, set it to the current settings object .
2. If settings is a non-secure context , return " denied ".
3. Let feature be descriptor 's name .
4. If there exists a policy-controlled feature for feature and settings ' relevant global object has an associated Document run the following step:
   1. Let document be settings ' relevant global object 's associated Document .
   2. If document is not allowed to use feature , return " denied ".
5. Let key be the result of generating a permission key for descriptor with settings .
6. Let entry be the result of getting a permission store entry with descriptor and key .
7. If entry is not null, return a PermissionState enum value from entry 's state .
8. Return the PermissionState enum value that represents the permission state of feature , taking into account any permission state constraints for descriptor 's name .

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

To request permission to use a descriptor , the user agent 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. If an administrator has configured the implementation to grant or deny permission for the calling algorithm to use the powerful feature described by descriptor :
   1. Set current state to " granted " if the administrator granted permission; otherwise to " denied ".
   2. Inform the user of the administrator 's configuration.
4. Otherwise:
   1. Ask the user for express permission for the calling algorithm to use the powerful feature described by descriptor .
   2. If the user gives express permission to use the powerful feature, set current state to " granted "; otherwise to " denied ". The user's interaction may provide new information about the user's intent for the origin .
      Note

      This is intentionally vague about the details of the permission UI and how the user agent infers user intent. User agents should be able to explore lots of UI within this framework.

5. Let key be the result of generating a permission key with the current settings object .
6. Queue a task on the current settings object 's responsible event loop to set a permission store entry with descriptor , key , and current state .
7. Return current state .

As a shorthand, requesting permission to use a DOMString 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 or more options associated with a given descriptor and an optional boolean allowMultiple (default false), the user agent must perform the following steps. This algorithm returns either " denied " or the user's selection.

1. If descriptor 's permission state is " denied ", return " denied " and abort these steps.
2. If descriptor 's permission state is " granted ", the user agent may return one (or more if allowMultiple is true) of options chosen by the user and abort these steps. If the user agent 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(s), unless the user agent receives new information about the user's intent .
3. Ask the user to choose one or more options or deny permission, and wait for them to choose:
   1. If the calling algorithm specified extra information to include in the prompt, include it.
   2. If allowMultiple is false, restrict selection to a single item from options ; otherwise, any number may be selected by the user.
4. If the user chose one or more options, return them; otherwise return " denied ".
   Note

   This is intentionally vague about the details of the permission UI and how the user agent infers user intent. User agents should be able to explore lots of UI within this framework.

As a shorthand, prompting the user to choose from options associated with a DOMString name , is the same as prompting the user to choose from those options associated with a PermissionDescriptor with its name member set to name .

When the user agent learns that the user no longer intends to grant permission to use a feature described by the PermissionDescriptor descriptor in the context described by the permission key key , react to the user revoking permission by running these steps:

1. Run descriptor 's name 's permission revocation algorithm .
2. Remove a permission store entry with descriptor and key .

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

WebIDL[Exposed=(Window,Worker)]
interface Permissions {
  Promise<PermissionStatus> query(object permissionDesc);
};
dictionary PermissionDescriptor {
  required DOMString name;
};

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

  "granted",
  "denied",
  "prompt",
};

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

The " granted ", " denied ", and " prompt " enum values represent the concepts of granted , denied , and prompt respectively.

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 an invalid argument error .
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 invalid argument error .
4. If parameters . state is an inappropriate permission state for any implementation-defined reason, return a invalid argument error .
   Note

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

5. Let settings be the current settings object .
6. Let targets be a list containing all environment settings objects whose origin is the same as the origin of settings .
7. Let tasks be an empty list .
8. For each environment settings object target in targets :
   1. Queue a task task on the permissions task source of target 's relevant settings object 's global object 's 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 .
9. Wait for all tasks in tasks to have executed.
10. Return success with data null .