Table of Contents

• 1. Conformance
• 2. Dependencies
• 3. Scope of this document
• 4. Permission Registry
• 5. Permission definition
• 6. Status of a permission
• 7. Permissions interface
• 8. Examples
• A. Acknowledgments
• B. References
  • B.1 Normative references
  • B.2 Informative references

1. Conformance

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, and RECOMMENDED are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to expose the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL].

2. Dependencies

The following concepts and interfaces are defined in [HTML]:

• origin of a Document and a worker.
• queue a task
• fire a simple event
• event handler
• event handler event type
• Window
• global object

Promise objects are defined in [ECMASCRIPT].

4. Permission Registry

enum PermissionName {
    "geolocation",
    "notifications",
    "push-notifications",
    "midi-sysex"
};

The PermissionName enum defines the list of known permissions. These permissions are meant to be associated with a use case instead of one API. Thus, some permissions have a 1:1 relationship with an API while some others might include more than one API or even a subset of an API.

Specifications are welcome to request a new name to be added to this registry instead of trying to monkey patch it.

The geolocation permission is the permission associated with the usage of the [geolocation-API].

The notifications permission is the permission associated with the usage of the [notifications] API.

The push-notifications permission is the permission associated with the usage of the [push-api] in order to show notifications using the [notifications] API.

The midi-sysex permission is the permission associated with the usage of sysex messages in the [webmidi] API.

5. Permission definition

dictionary Permission {
    required PermissionName name;
};

A Permission dictionary MUST contain a name field which represents the permission's identifier.

If a permission has to be defined by more than its name, it is RECOMMENDED to inherit from Permission dictionary and add new fields.

6. Status of a permission

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

The steps to retrieve the permission state of a global object for a given permission are as follows:

1. If the user agent will allow the global object to try to access the features associated with the permission but will prompt the user to know whether the call should succeed or fail, the user agent MUST return prompt.
2. Otherwise, if the user agent will allow the global object to access the features associated with the permission without prompting the user, the user agent MUST return granted .
3. Otherwise, the user agent will not allow the global object to access the feature associated with permission and MUST return denied .

How the user agent decides whether a global object is allowed or not to access some features is left as an implementation details. However, the implementation MUST be consistent and not return different values unless something happened (user action, expiration).

It is RECOMMENDED for implementations to use the origins of the Document or Worker when making security decisions. Other factors MAY also apply like whether the permission is associated with a [powerful-features] or whether the Document is embedded.

[Exposed=(Window,Worker)]
interface PermissionStatus : EventTarget {
    readonly    attribute Permission      permission;
    readonly    attribute PermissionState status;
                attribute EventHandler    onchange;
};

The steps to update the status of a PermissionStatus instance are as follow:

1. Let status be the PermissionStatus instance being updated.
2. Run the steps to retrieve the permission state using the status' global object and permission attribute then set the result of those steps to the status attribute.

The steps to create a PermissionStatus for a given permission are as follow:

1. Let status be a PermissionStatus instance.
2. Set the permission attribute to permission.
3. Run the steps to update the status on status.
4. Return status.

The permission attribute MUST return the Permission it was initially set to at the object creation.

The status attribute MUST return the latest value that was set while running the update the status steps on the current instance.

The onchange attribute is an event handler whose corresponding event handler event type is change.

Whenever the user agent is aware that the status of a PermissionStatus instance has changed, it MUST asynchronously run the following steps:

1. Let permission-status be the PermissionStatus for which the status has changed.
2. Run the steps to update the status of permission-status.
3. Queue a task on the permission task source to fire a simple event named change at permission-status.

7. Permissions interface

[Exposed=(Window,Worker)]
interface Permissions {
    static Promise<PermissionStatus> query ((Permission or PermissionName) permission);
};

When the query() method is invoked, the user agent MUST run the following steps:

1. Let permission be permission argument if permission is of type Permission, otherwise, create a Permission instead for which name is set to the permission argument value.
2. Let promise be a newly-created Promise.
3. Return promise and continue those steps asynchronously.
4. Run the steps to create a PermissionStatus using the global object and permission and resolve promise with the result of those steps.