Requesting Permissions

Draft Community Group Report,

This version:
https://jyasskin.github.io/permissions-request
Issue Tracking:
GitHub
Inline In Spec
Editor:
Jeffrey Yasskin (Google Inc.)
Tests:
web-platform-tests permissions-request/ (ongoing work)

Abstract

This specification extends the Permissions API to provide a uniform function for requesting permission to use powerful features.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

This document specifies a function to request permission to use powerful features on the Web platform.

Different Web APIs have disparate ways to signal a developer’s intent to use them:

It’s easier for developers to design their permission-related code if they have a single pattern to follow for all powerful features.

2. Request API

partial interface Permissions {
  Promise<PermissionStatus> request(object permissionDesc);
};

When the request(permissionDesc) method is invoked, the user agent MUST run the following algorithm, passing the parameter permissionDesc:

  1. Let rootDesc be the object permissionDesc refers to, converted to an IDL value of type PermissionDescriptor. If this throws an exception, return a promise rejected with that exception and abort these steps.

  2. Let typedDescriptor be the object permissionDesc refers to, converted to an IDL value of rootDesc.name’s permission descriptor type. If this throws an exception, return a promise rejected with that exception and abort these steps.

  3. Let promise be a newly-created Promise.

  4. Return promise and continue the following steps asynchronously.

  5. Run the steps to create a PermissionStatus for typedDescriptor, and let status be the result.

  6. Run the permission request algorithm of the feature named typedDescriptor.name with typedDescriptor and status as arguments.

  7. If the previous step threw an exception, reject promise with that exception.

  8. Otherwise resolve promise with status.

3. Additional fields in the Permission Registry

Powerful features in the Permission Registry additionally define a permission request algorithm:

Input
Behavior

Uses the algorithms in Requesting more permission to show the user any necessary prompt to try to increase permissions, and updates the instance of the permission result type to match.

Returns

Nothing, but may throw an exception if the request can fail exceptionally. (Merely being denied permission is not exceptional.)

Example callers
Default

If unspecified, this defaults to the boolean permission request algorithm.

3.1. Default request algorithm

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

  1. Run the boolean permission query algorithm on permissionDesc and status.

  2. If status.state is not "prompt", abort these steps.

  3. Request permission to use permissionDesc.

  4. Run the boolean permission query algorithm again on permissionDesc and status.

    On browsers that don’t store permissions persistently within an environment settings object, this will always return "prompt", but still show the user an unnecessary prompt. That may mean that no permissions should use the boolean permission request algorithm, since it can never return an appropriate object-capability.

4. Security Considerations

No security considerations have been identified.

5. Privacy Considerations

No privacy considerations have been identified.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[PERMISSIONS]
Mounir Lamouri; Marcos Caceres; Jeffrey Yasskin. Permissions. 25 September 2017. WD. URL: https://www.w3.org/TR/permissions/
[PROMISES-GUIDE]
Domenic Denicola. Writing Promise-Using Specifications. 16 February 2016. Finding of the W3C TAG. URL: https://www.w3.org/2001/tag/doc/promises-guide
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

Informative References

[geolocation-API]
Andrei Popescu. Geolocation API Specification 2nd Edition. 8 November 2016. REC. URL: https://www.w3.org/TR/geolocation-API/
[NOTIFICATIONS]
Anne van Kesteren. Notifications API Standard. Living Standard. URL: https://notifications.spec.whatwg.org/

IDL Index

partial interface Permissions {
  Promise<PermissionStatus> request(object permissionDesc);
};

Issues Index

On browsers that don’t store permissions persistently within an environment settings object, this will always return "prompt", but still show the user an unnecessary prompt. That may mean that no permissions should use the boolean permission request algorithm, since it can never return an appropriate object-capability.