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 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 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.

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 is responsible for tracking which powerful features each realm has the user's permission to use via the environment settings object.

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. If there was a previous invocation of this algorithm with the same descriptor and settings, returning previousResult, and the user agent has not received new information about the user's intent since that invocation, return previousResult.
6. 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. Ask the user for express permission for the calling algorithm to use the powerful feature described by descriptor.
4. If the user gives express permission to use the powerful feature, 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 user agent infers user intent. User agents should be able to explore lots of UI within this framework.

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". 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 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 for a realm to use a feature, react to the user revoking permission by running these steps:

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 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. If parameters.oneRealm is true, let targets be a list whose sole member is settings.
7. Otherwise, let targets be a list containing all environment settings objects whose origin is the same as the origin of settings.
8. Let tasks be an empty list.
9. 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.
10. Wait for all tasks in tasks to have executed.
11. Return success with data null.