Permissions

This section specifies a model for permissions to use powerful features on the Web platform.

When a conforming specification specifies a powerful feature it:

1. MUST give the powerful feature a name in the form of a ascii lowercase string.
2. MAY define a permission descriptor type that inherits from PermissionDescriptor.
3. MAY define zero or more aspects.
4. MAY override the algorithms and types given below if the defaults are not suitable for a particular powerful feature.
5. MUST register the powerful feature in the Permissions Registry.

Registering the newly specified powerful features in the Permissions Registry gives this Working Group an opportunity to provide feedback and check that integration with this specification is done effectively.

A permission descriptor type:

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

The feature can define a partial order on descriptor instances. If descriptorA is stronger than descriptorB, then if descriptorA's permission state is "granted", descriptorB's permission state must also be "granted", and if descriptorB's permission state is "denied", descriptorA's permission state must also be "denied".

permission state constraints:

Constraints on the values that the user agent can return as a descriptor's permission state. Defaults to no constraints beyond the user's intent.

extra permission data type:

Some powerful features have more information associated with them than just a PermissionState. Each of these features defines an extra permission data type.

Note

For example, getUserMedia() needs to determine which cameras the user has granted permission to access.

If a DOMString name names one of these features, then name's extra permission data for an optional environment settings object settings is the result of the following algorithm:

1. If settings wasn't passed, set it to the current settings object.
2. If there was a previous invocation of this algorithm with the same name and settings, returning previousResult, and the user agent has not received new information about the user's intent since that invocation, return previousResult.
3. Return the instance of name's extra permission data type that matches the UA's impression of the user's intent, taking into account any extra permission data constraints for name.

If specified, the extra permission data algorithm is usable for this feature.

Optional extra permission data constraints:

Constraints on the values that the user agent can return as a powerful feature's extra permission data. Defaults to no constraints beyond the user's intent.

A permission result type:

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

A permission query algorithm:

Takes an instance of the permission descriptor type 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(permissionDesc) method and the PermissionStatus update steps. If unspecified, this defaults to the default permission query algorithm.

The default permission query algorithm, given a PermissionDescriptor permissionDesc and a PermissionStatus status, runs the following steps:

1. Set status's state to permissionDesc's permission state.

A permission key type:

The type of permission key used by the feature. Defaults to origin. A feature that specifies a custom permission key type MUST also specify a permission key generation algorithm.

A permission key generation algorithm:

Takes an environment settings object, and returns a new permission key. If unspecified, this defaults to the default permission key generation algorithm. A feature that specifies a custom permission key generation algorithm MUST also specify a permission key comparison algorithm.

The default permission key generation algorithm, given an environment settings object settings, runs the following steps:

1. Return settings's top-level origin.

Note: Permission Delegation

A permission key comparison algorithm:

Takes two permission keys and returns a boolean that shows whether the two keys are equal. If unspecified, this defaults to the default permission key comparison algorithm.

The default permission key comparison algorithm, given permission keys key1 and key2, runs the following steps:

1. Return key1 is same origin with key2.

A permission revocation algorithm:

Takes no arguments. Updates any other parts of the implementation that need to be kept in sync with changes in the results of permission states or extra permission data.

If unspecified, this defaults to running react to the user revoking permission.

A permission lifetime:

Specifications that define one or more powerful features SHOULD suggest a permission lifetime that is best suited for the particular feature. Some guidance on determining the lifetime of a permission is noted below, with a strong emphasis on user privacy. If no lifetime is specified, the user agent provides one.

When the permission lifetime expires for an origin:

1. Set the permission back to its default permission state (e.g., by setting it back to "prompt").
2. For each browsing context associated with the origin (if any), queue a global task on the permissions task source with the browsing context's global object to run the permission revocation algorithm.

Note: Determining the lifetime of a permission

Default permission state:

An PermissionState value that serves as a permission's default state of a powerful feature.

If not specified, the permission's default state is "prompt".

A default powerful feature is a powerful feature with all of the above types and algorithms defaulted.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Two classes of product can claim conformance to this specification: user agents and other specifications (i.e., a technical report that specifies a powerful feature in a manner that conforms to the requirements of this specification).

For the purposes of user-agent automation and application testing, this document defines extensions to the [WebDriver] and [WebDriver-BiDi] specifications. It is OPTIONAL for a user agent to support them.

WebIDLdictionary PermissionSetParameters {
  required object descriptor;
  required PermissionState state;
};

PermissionsCommand = (
  permissions.setPermission
)

permissions.PermissionDescriptor = {
  name: text,
}

permissions.PermissionState = "granted" / "denied" / "prompt"

There are no documented security considerations at this time. Readers are instead encouraged to read section D. Privacy considerations.

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

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

[Exposed=(Window,Worker)]
interface Permissions {
  Promise<PermissionStatus> query(object permissionDesc);
};

dictionary PermissionDescriptor {
  required DOMString name;
};

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

enum PermissionState {
  "granted",
  "denied",
  "prompt",
};

dictionary PermissionSetParameters {
  required object descriptor;
  required PermissionState state;
};