Permissions

A permission represents a user's decision as to whether a web application can use a powerful feature. The decision is represented as a permission state.

Express permission refers to an act by the user, e.g. via user interface or host device platform features, through which the user grants permission for use of a feature by a web application.

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

Denied:

The user, or the user agent on the user's behalf, has denied access to this powerful feature. The caller will not be able to use the feature.

Granted:

The user, or the user agent on the user's behalf, has given express permission to use a powerful feature. The caller will be able to 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 a denied). It also means that if 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 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, an amount of time, or 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.

A powerful feature is a web platform feature (usually an API) for which a user gives express permission before the feature can be used. Access to the feature is determined by the environment settings object by the user having granted permission via UI, 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 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.

To get the current permission state, given a name name and an optional environment settings object settings:

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

A descriptor's permission state for an optional environment settings object settings is the result of the following algorithm, which returns one of "granted", "prompt", or "denied":

1. If settings wasn't passed, set it to the current settings object.
2. If settings is a non-secure context, return "denied".
3. If there exists a policy-controlled feature identified by descriptor's name and settings has an associated Document named document, run the following step:
   1. If document is not allowed to use the feature identified by descriptor's name return "denied".
4. If there was a previous invocation of this algorithm with the same descriptor and settings, returning previousResult, and the UA has not received new information about the user's intent since that invocation, return previousResult.
5. Return whichever of the following options most accurately reflects the user's intent for the calling algorithm, taking into account any permission state constraints for descriptor's name:

   succeed without prompting the user

   "granted"

   show the user a prompt to decide whether to succeed

   "prompt"

   fail without prompting the user

   "denied"

As a shorthand, a PermissionName 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 UA 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. Ask the user for express permission for the calling algorithm to use the powerful feature described by descriptor.
4. If the user grants permission, return "granted"; otherwise return "denied". The user's interaction may provide new information about the user's intent for this realm and other realms with the same origin.
   Note

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

As a shorthand, requesting permission to use a PermissionName 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 of several options associated with a descriptor, the UA must perform the following steps. This algorithm returns either "denied" or one of the options.

1. If descriptor's permission state is "denied", return "denied" and abort these steps.
2. If descriptor's permission state is "granted", the UA may return one of options and abort these steps. If the UA 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, unless the UA receives new information about the user's intent.
3. Ask the user to choose one of the options or deny permission, and wait for them to choose. If the calling algorithm specified extra information to include in the prompt, include it.
4. If the user chose an option, return it; otherwise return "denied". If the user's interaction indicates they intend this choice to apply to other realms, then treat this this as new information about the user's intent for other realms with the same origin.
   Note

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

As a shorthand, prompting the user to choose from options associated with a PermissionName 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 UA learns that the user no longer intends to grant permission for a realm to use a feature, react to the user revoking permission by:

1. Queue a task on the Realm's settings object's responsible event loop to run that feature's permission revocation algorithm.

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

WebIDL[Exposed=(Window,Worker)]
interface PermissionStatus : EventTarget {
  readonly attribute PermissionState state;
  readonly attribute PermissionName 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 screen-wake-lock enum value identifies the Screen Wake Lock API powerful feature. It is a default powerful feature.