diff --git a/explainer.md b/explainer.md index 29e4e27..cd64522 100644 --- a/explainer.md +++ b/explainer.md @@ -1,5 +1,80 @@ # Page Embedded Permission Control (PEPC) +## tl;dr + +We propose a semantic permission element with styling constraints that ensures a +very high level of confidence concerning *user intent* to make a permission +decision. We believe this solves user problems related to accessibility, +context, regret, and more. + +The permission element is designed to be more [accessible](#accessibility) and +more secure than the current permission flows. Full page modal confirmation UI +reduces the risk of change blindness and makes it more difficult for sites to +manipulate the user's decision making by obscuring site content during the +critical decision moment of the journey. + +A semantic element and modal UI are connected in the same proposal as accurately +capturing user intent is essential to reducing the modal's potential for user +annoyance. + +While we believe improvements to existing capability based permission flows can +and should be explored, we believe there to be limited headroom for +optimization, and that this proposal offers a significantly better user +experience for users and developers. + +## Table of Contents + + +- [Introduction](#introduction) +- [Proposal](#proposal) +- [Goals & non-goals](#goals-non-goals) +- [Adoption ](#adoption) +- [Developer trials](#developer-trials) +- [Design considerations](#design-considerations) + * [HTML element](#html-element) + + [Usage](#usage) + + [Restrictions](#restrictions) + + [PEPC attributes](#pepc-attributes) + * [Permission UI](#permission-ui) + + [Standard UI](#standard-ui) + + [UI when the user can't change the permission](#ui-when-the-user-cant-change-the-permission) + + [UI when there is a mechanism that would block the request](#ui-when-there-is-a-mechanism-that-would-block-the-request) + + [UI when the permission is already granted](#ui-when-the-permission-is-already-granted) + * [Complexity ](#complexity) + * [Implementor portability, internationalization & upkeep](#implementor-portability-internationalization-upkeep) + * [Fallback solutions](#fallback-solutions) +- [Security](#security) + * [Threat model](#threat-model) + + [Safety](#safety) + + [Annoyance](#annoyance) + * [Fallbacks when constraints are not met](#fallbacks-when-constraints-are-not-met) + * [Locking the PEPC style](#locking-the-pepc-style) + * [One PEPC per permission type per page](#one-pepc-per-permission-type-per-page) + * [Conditions for usage in subframes](#conditions-for-usage-in-subframes) + * [Custom cursors](#custom-cursors) + * [Synthetic click events](#synthetic-click-events) +- [Privacy](#privacy) + * [Exposing user information bits](#exposing-user-information-bits) +- [Status quo elaboration](#status-quo-elaboration) + * [Permission prompts UX evaluation](#permission-prompts-ux-evaluation) + * [User Agent abuse mitigations](#user-agent-abuse-mitigations) +- [Alternatives considered](#alternatives-considered) + * [No platform changes](#no-platform-changes) + * [Improve existing usage triggered permission request journey](#improve-existing-usage-triggered-permission-request-journey) + * [Separate this into two proposals, (1) improved user intent signal and (2) modal permission prompts](#separate-this-into-two-proposals-1-improved-user-intent-signal-and-2-modal-permission-prompts) + * [Extending an existing element](#extending-an-existing-element) + * [Providing a registration JS API](#providing-a-registration-js-api) + * [Extending the Permissions API to provide an anchor point](#extending-the-permissions-api-to-provide-an-anchor-point) + * [Allowing recovery via the regular permission flow](#allowing-recovery-via-the-regular-permission-flow) + * [Implementing an origin based permission allow list registry](#implementing-an-origin-based-permission-allow-list-registry) +- [Extending the PEPC in the future](#extending-the-pepc-in-the-future) + * [PEPC for additional user agent settings](#pepc-for-additional-user-agent-settings) + * [Not "just" a button](#not-just-a-button) + + + + + ## Introduction When making decisions about whether or not to expose particularly powerful @@ -18,15 +93,17 @@ permanent "block" policies, or However these measures have limited effect [as indicated by metrics](#user-agent-abuse-mitigations). -There are four main challenges with the status quo: +Challenges with the status quo include: 1. **Insufficiency of existing mitigations**: The present day permissions spam and abuse mitigation approach has an architectural upper bound on user protection because the model relies on the website to choose when to trigger the permission request prompt rather than capturing a reliable signal of - user intent. Requiring a user gesture to [request permission to use a powerful feature](https://www.w3.org/TR/permissions/#dfn-request-permission-to-use) (or similar) - does not solve this problem as there are many ways of tricking a user into - providing a so called "[activation triggering input event](https://html.spec.whatwg.org/#activation-triggering-input-event)" + user intent. Requiring a user gesture to + [request permission to use a powerful feature](https://www.w3.org/TR/permissions/#dfn-request-permission-to-use) + (or similar) does not solve this problem as there are many ways of tricking + a user into providing a so called + "[activation triggering input event](https://html.spec.whatwg.org/#activation-triggering-input-event)" (i.e., a user gesture, such as clicking the mouse or pressing a key) . 1. **Context**: Ideally, a site's developer will request access as part of a @@ -38,10 +115,10 @@ There are four main challenges with the status quo: understanding of events taking place in the content area prior to the permission request. User agents could make better decisions and provide better prompts if they could make well-founded assumptions about the nature - of the user's interaction in the content area, and the user's intent. At - the moment user agents are limited to trying to make use of potentially - ambigous signals such as the time elapsed between page load and the - permission request. + of the user's interaction in the content area, and the user's intent. At the + moment user agents are limited to trying to make use of potentially ambigous + signals such as the time elapsed between page load and the permission + request. ![](images/image1.png) \ *Example 1. A notification permission prompt on a news site (contents @@ -91,6 +168,26 @@ There are four main challenges with the status quo: such as an important presentation, users will struggle to navigate the settings surfaces to change the permission decision.* +1. **Accessibility**: Permission UI for a + capability is triggered through the direct use of the capability. Typically + JavaScript invokes permission UI, presenting an issue for both screen + readers and magnification users. + + Script attached to an existing DOM element is not interpreted by the screen + reader. If the DOM element was not accessibility tested and does not provide + sufficient explanation to its function, there is no way for a screen reader + user to know that the purpose of that element is to initiate access to a + capability. Current permissions can be accessible if properly implemented + and tested, PEPC is *accessible by default*. + + Magnification users also struggle with the status quo. A page cannot detect + if a user is using OS level magnification tools (WAI for privacy reasons). A + user in a magnified state can easily miss the permission prompt if it falls + outside of their magnified viewport, and pages cannot assist these users. + With PEPC, the scrim and a contextually localized prompt greatly increase + the chance that the magnification user will observe the permission request + after interacting with the element. + Optimizing the trade-off between usability and interruptions hit practical limits because, fundamentally, user agents [still lack any understanding of the](#permission-prompts-ux-evaluation) @@ -105,6 +202,7 @@ capability access. This is especially important if user agents want to safely enable users to change their minds while still *respecting user's earlier permanent block decisions*. + ## Proposal *Summary: We propose a new HTML element to the web platform which will be used @@ -167,6 +265,11 @@ users and developers alike: - It allows users to **revert** a previous "deny" decision if they have changed their mind and are now interested in the feature that the site provides. +- It is more **accessible**. The PEPC can have standard, localized, screen + reader announcements that make the purpose of the element comprehensible and + consistent across websites. The scrim and a contextually localized prompt + greatly increase the chance that a magnification user will observe the + permission request after interacting with the element. Example usage: @@ -180,7 +283,6 @@ Example usage: @@ -212,6 +314,7 @@ agent). + ## Goals & non-goals The goal of this proposal is to provide a definition of a Page Embedded @@ -231,10 +334,34 @@ experience for the user and simplified developer ergonomics; the existing JS-only APIs can still be used when an in-page element solution does not fit the particular use case. + +## Adoption + +PEPC does not to replace existing permission journeys to benefit a large +fraction of the users who interact with permission gated capabilities. A relatively small number of sites account for a large +fraction of permission requests with real world benefit, for example : + +* Workplace collaboration & social sites requiring Camera/microphone access, such as popular video conferencing and chat apps with voice and/or video functions +* eCommerce sites with store locators + +We hope to establish through [developer trials](#developer-trials) whether PEPC sufficiently addresses user problems and meets developer needs to gain the traction needed to justify support for this feature. + + +## Developer trials + +We have done laboratory user experience testing of the user problems & solution +described in this document. However, we would like to validate whether we have +properly described the user problems and the appropriateness of the solution +with a developer trial of a minimally implemented version of the feature for a +subset of most frequently used permission types. + + ## Design considerations + ### HTML element + #### Usage The PEPC should be easy to integrate into the site and therefore it should be @@ -296,6 +423,12 @@ the user with a way forward to grant the required permission to the site, regardless of what permission state they currently find themselves in. Therefore only a `:granted` CSS pseudo-class is proposed. +Sites may wish to modify the appearance (or hide) the PEPC when it fails +validation. Therefore a `:invalid` CSS pseudo-class is also proposed. The +invalid pseudo-class is applied when the element's validation status changes +because of 'style' 'type_count' or 'illegal_subframe' reasons. The style should +not be set when the element is not valid for transient reasons. + The PEPC should be used in parallel with the Permissions API which already provides the necessary support to allow a site to respond to permission status changes. This is the encouraged pattern because it ensures that the site will @@ -322,6 +455,24 @@ cancelable. that continues allowing a permission on a [previously granted](#ui-when-the-permission-is-already-granted) type of UI). +- `onvalidationstatuschange` - raised when the PEPC switches from being + "valid" to "invalid". The PEPC is considered "valid" when the user agent + trusts the integrity of the signal if the user were to click on it, and + "invalid" otherwise. There are many reasons for which an element can become + "invalid" as detailed in the [Security](#security) section, but to enumerate + a few: element style is invalid, element is covered, element has recently + moved, element has changed size, element is not fully visible in the + viewport, etc. The following two attributes are added to the `permission` + object which are related to the validation status: + - `boolean is-valid` - indicates whether the status has transitioned to + "valid" or not. + - `string reason` - indicating the reason why the status is "invalid" (or + "" if it's valid), and can be one of the following values: + ["style"](#locking-the-pepc-style), + ["type_count"](#one-pepc-per-permission-type-per-page), + ["illegal_subframe"](#conditions-for-usage-in-subframes), + ["covered"](#threat-model), ["recently_moved"](#threat-model), + ["recently_created"](#threat-model). Example usage: @@ -353,6 +504,7 @@ Example usage: ``` + #### Restrictions It is crucial that the site is not able to easily abuse the PEPC to trigger a @@ -365,6 +517,7 @@ mitigate situations that would allow malevolent sites to obtain a click on the PEPC by using deceitful tactics. The [Security](#security) section elaborates on this aspect. + #### PEPC attributes @@ -378,59 +531,53 @@ this aspect. - - - - - + - - + + + + + + - +
onpromptdismiss onpromptactionEvent handlers as discussed above.
iconstyletype-ext - Used to allow the site to select different icon styles. Supported values: - - - - - - - - - - - - - -
solid - -
outline - -
none - -
+ Allows specifying additional parameters for certain permission types, in + the form of space-separate key: value pairs. + The supported key/values are: +
    +
  • sysex: true/false (for the + + midi permission type) +
    • +
  • precise:true/false (for the + + geolocation permission type) +
    • +
  • panTiltZoom:true/false (for the + + camera permission type) +
    • +
phrasing(?) - **Open question**: It could be reasonable to provide sites the ability to - pick from one of several predefined phrasings. - onpromptdismiss onpromptaction onvalidationstatuschangeEvent handlers as discussed above.
is-valid reasonAs discussed above.
lang(?)lang - **Open question**: Should the site be allowed to pick the language of the - PEPC? It can not be a fully free choice however as it needs to be a - language the user understands. The user agent can decide how to - [fallback](#fallbacks-when-constraints-are-not-met) if the language is not - one that the user speaks. + The global + lang + attribute has further purpose on the `permission` HTML element. Since the + contents of the PEPC is set by the user agent, this attribute will indicate + what language the text should be in. The user agent will attempt to provide + the text in that language if possible.

+ Note: This will only be used to determine the language of the HTML element, + not of the permission confirmation UI itself. The permission UI should use + the same language that the rest of the user agent uses on similar security + surfaces.
-Notes: there is prior art in this domain the iOS LocationButton which allows for -configuring the icon style out of more options, and hiding the text as well as -the icon. For interoperability considerations, the options here are more -limited. - + ### Permission UI After the user clicks on the PEPC, a confirmation UI should be presented to the @@ -446,6 +593,7 @@ considerations that should be taken into account: they have in place that would normally prevent permission request from reaching the user + #### Standard UI Since the user agent has the strong signal of the user's intent and current @@ -471,6 +619,7 @@ Key points to consider: - The confirmation UI should have an obvious way for the user to change their mind + #### UI when the user can't change the permission There are many user agents that offer mechanisms for permission granting that @@ -481,6 +630,7 @@ should clarify the situation to the user. For example: ![](images/image17.png) + #### UI when there is a mechanism that would block the request As discussed previously there are many mechanisms that user agents implement @@ -501,6 +651,7 @@ As an example, this is how a confirmation UI could look when the site is in a ![](images/image18.png) + #### UI when the permission is already granted When the permission is granted the PEPC text changes to reflect this. This also @@ -515,24 +666,83 @@ An example of how this could look: ![](images/image19.png) + +### Complexity +Most of the implementation complexity of the PEPC lies in the annoyance reduction mechanisms. As previously mentioned, the main security surface is the "Confirmation UI" which is straightforward to implement. + +This proposal describes a deliberately conservative set of annoyance reduction mechanisms with the aim to discovering in [developer trials](#developer-trials) which restrictions will be infeasible for users, developers or implementors. + + +### Implementor portability, internationalization & upkeep +Most browsers already have user recognizable iconography for common permissions such Camera/Microphone or Location and the PEPC can share strings used in the existing permission journey. + +Developers will need to handle the `onvalidationstatuschange` event, which helps to future proof websites against unexpected changes in browser implementor validation criteria. + + +### Fallback solutions + +Unsupported browsers will need to implement fallback solutions which will slow +adoption. However, we believe this is surmountable for two reasons: + +1. In many cases the polyfill will not be needed as the PEPC can augment + existing journeys. +1. In cases where the PEPC replaces existing journeys the polyfill is typically + straightforward, with a button linking to capability usage. +1. In UX testing we have found the PEPC significantly outperformed other + permission request flows for both user & developer preferred outcomes (lower + decision "regret", whether granted or blocked), and a much higher success + rate of users reverting past decisions they regretted. This makes the PEPC + appealing to developers in use cases where a permission is critical to a + specific user journey, such as a user interacting with a locator when trying + to find their hotel. + +We would like to validate whether our assumptions concerning fallback solutions +with real developer trials of a prototype implementation. + + ## Security + ### Threat model -The security of the proposal hinges on there being a permission prompt that is -used to confirm the user's decision to grant the permission. - The goal of user agents should be to ensure that the PEPC is not trivial to -abuse. Therefore the user agent should consider the following potentially -malicious tactics and mitigate them: +abuse. There are two primary types of abuse: safety, and user annoyance which we +will consider separately as they are addressed by the confirmation UI and by +constraints on the PEPC element respectively. + + +#### Safety + +The safety of PEPC hinges on there being a permission prompt that is used to +confirm the user's decision to grant the permission, we call this the +"Confirmation UI". The confirmation UI is strictly better than the existing +non-modal permission prompt implemented by most browsers because it: + +- (Same as current UI) is generated by the browser, with the only inputs + accepted from the website are permission(s) types requested. +- Modal, requiring explicit dismiss or decision gesture for the user journey + to continue, with website content obscured with a semi-opaque and blurred + scrim which prevents the site from manipulating the user's decision making + or obfuscating the modal content. + +The strict constraints of the confirmation UI make the PEPC minimally as safe +(and arguably safere) than existing non-modal UI. + + +#### Annoyance + +Mitigating annoyance by ensuring user intent is more complex than ensuring the +safety of the PEPC, but equally important to the goals of the proposal. Without +mitigating annoyance we don't believe it to be reasonable to impose the safer, +but more disruptive, modal confirmation UI. + +The site can use techniques to annoy the user by repeatedly triggering modals, +including: - The site could trick the user by choosing some misleading text (e.g. "Click here to proceed"). Therefore the text on the PEPC should not be able to be set by the site, instead the user agent should make sure to set it to - something comprehensive (e.g. "Share location" for a geolocation PEPC). \ - **Open question:**should there be a mechanism that allows the site to pick - one of several flavors of text (example: "Share location" vs "Use - location")? + something comprehensive (e.g. "Share location" for a geolocation PEPC). - The style of the PEPC can be set to obscure the purpose (e.g. setting the same text color and button color would make the text unreadable). Therefore the style should be verified, validated and overridden by the user agent as @@ -552,11 +762,12 @@ malicious tactics and mitigate them: that the PEPC has not been inserted into the DOM recently (e.g. in the past 500ms or so). -The user agent-rendered confirmation UI after the user clicks on the PEPC is -what makes the PEPC ultimately secure. User agents should take proper care to -ensure this confirmation UI is at least as secure as their current permission -prompt flow. +Reminder: the user agent-rendered confirmation UI after the user clicks on the +PEPC is what makes the PEPC ultimately secure. User agents should take proper +care to ensure this confirmation UI is at least as secure as their current +permission prompt flow. + ### Fallbacks when constraints are not met The [Security](#security) section has details on various mitigations and checks @@ -577,20 +788,8 @@ click is not assured: check or mitigation will self-correct itself (e.g. if the PEPC has moved recently there will be a short cooldown before the PEPC integrity is restored). -- The PEPC could be corrected by the user agent itself in order to preserve - its integrity. For example, if the style specified by the site sets the PEPC - font to be too small to read, this can be corrected by the user agent by - forcing a minimum font size on the PEPC. This should be considered primarily - in the case of CSS, which the user agent can override as it sees fit. **Open - question:** should there be a way for sites to specify whether they want to - allow the user agent to override the style? Some site authors might be - happier triggering the legacy prompt request flow, rather than have the PEPC - style be changed whereas others might prioritize the benefits of a PEPC - permission flow over making sure the style is exactly as desired. User - agents need to weigh in the additional flexibility afforded to site authors - against the potential user confusion of seeing the PEPC permission prompt vs - the regular permission prompt. + ### Locking the PEPC style User agents should lock down the styling of the PEPC in regards to the color, @@ -598,6 +797,13 @@ size, border, rounding, contents, icon, etc. of the PEPC, as outlined below. This provides protection against some of the clickjacking and social engineering attacks that bad actors might use to trick the user into clicking the element. +We are working with developers to ensure the correct tradeoff between sufficient +developer control over the look-and-feel of the PEPC, while ensuring that the +browser has captured user intent. The proposal in this explainer intentionally +errs on the side of being cautiously over-restrictive, as this will minimize the +threat surface area and acts as a forcing function for developer feedback on +proposed styling restrictions during trials. + @@ -698,11 +904,13 @@ For practical purposes it is recommended that user agents keep a curated list of style properties which are allowed, and any other style property is discarded by default. + ### One PEPC per permission type per page To prevent sites from tile-covering their site with PEPCs, there should be a limit of at most one PEPC per permission type, per page. + ### Conditions for usage in subframes Subframe usage will be allowed but several security constraints need to be @@ -714,11 +922,13 @@ enforced: be set to prevent clickjacking attacks where a malicious site embeds a legitimate site that uses a PEPC. + ### Custom cursors Custom cursors should be disabled when the cursor is hovering over the PEPC because they can have a potentially misleading hitpoint. + ### Synthetic click events Click events which are simulated by the site (e.g. via the `click()` function) @@ -727,8 +937,10 @@ should not be considered. Click-like event handlers (such as `onclick`, `onmousedown`, etc.) will function as expected. + ## Privacy + ### Exposing user information bits Extreme care needs to be taken to ensure that information is limited to what a @@ -743,8 +955,10 @@ have the PEPC text reflect this state, perhaps by setting the PEPC text to would otherwise not be privy to, namely that the user's settings are partially controlled by an administrator. + ## Status quo elaboration + ### Permission prompts UX evaluation Below are two examples of browser permission prompts. The prompts are triggered @@ -788,6 +1002,7 @@ considered: this makes it difficult for sites to recover from this state even if the user shows clear interest in the feature. + ### User Agent abuse mitigations The shortcomings of the current status quo of permission prompts practically has @@ -825,8 +1040,72 @@ issues. If the user initiates the permission request it ensures that: focus is likely in the area. Because of the above, it is unlikely that such a placement is interruptive or annoying. + ## Alternatives considered + +### No platform changes + +Sites could replicate most of this behavior currently by using a button that +triggers the permission request. Developers could be actively encouraged to use +this pattern via articles, communications etc. + +Disadvantages: + +1. There is no signal or guarantee indicating the user's intent. This means + that the user agent still needs to remain defensive about permission + requests. +1. It requires user experience design and consideration from the site's side. + There are many ways to get this wrong and provide a suboptimal user + experience. Also, providing a solution with best-practices built in helps + resource-constrained development teams more. + + +### Improve existing usage triggered permission request journey + +The existing permission request journey is triggered by usage of the relevant +capability, for example, `getUserMedia` triggering a Camera permission journey. +We agree there may be ways to improve the current journey and we intend to +explore these in parallel, however, there is an upper bound to improvements. +Specifically: + +1. Accessibility. Native HTML elements (such as the proposed permission element + in this explainer) come with built-in roles, properties, and keyboard + interaction behaviors understood by assistive technologies. While JavaScript + solutions can be *made* accessible, the PEPC can be accessible by default. +1. User intent. JavaScript triggered UI journeys will never be able to capture + user intent the way we believe is possible with PEPC. User gestures are + easily gamed by manipulative or malicious websites. It's difficult to see + how more advanced heuristics could be used to determine user intent, and we + believe that any heuristics to determine user intent would be significantly + more complicated that determining user intent for the semantic element. +1. Context. While sites *may* do a good job with providing context to the user + about why a permission journey is happening, the PEPC *ensures* the context + is present with consistent button UI and labels, and strong signal of user + intent. +1. Reconsideration. Sometimes users make a mistake in a permission decision. + It's undesirable for browsers to allow users to reconsider past decisions + with the usage-driven UI model, as enabling reconsideration would present + spammy or abusive websites the ability to repeatedly prompt users who block + a permission request. Help text directing users to navigate browser UI to + revisit past permission decisions requires web developers to provide users + with evergreen browser-specific directions on changes to the browser + permission settings. In practice this is a significant burden on web + developers, often results in stale directions, and users seldom succeed at + these journeys even when the directions are up-to-date and clear. + + +### Separate this into two proposals, (1) improved user intent signal and (2) modal permission prompts + +We believe these aspects of the proposal offer the most user utility when +bundled. If we only improve the user intent signal with a permission element, we +fail to solve for change blindness and accessibility problems for magnification +users. If we only introduce modal permission prompts without improving our +confidence in user intent and context we increase the level of interruption and +disruption in user journeys with blocking modals about which the user may have +little or no context for decision making. + + ### Extending an existing element Instead of adding a new element, existing HTML elements can be augmented to @@ -888,22 +1167,7 @@ Disadvantages: [type](https://html.spec.whatwg.org/multipage/input.html#attr-input-type) would be a poor design fit. -### No platform changes - -Sites could replicate most of this behavior currently by using a button that -triggers the permission request. Developers could be actively encouraged to use -this pattern via articles, communications etc. - -Disadvantages: - -1. There is no signal or guarantee indicating the user's intent. This means - that the user agent still needs to remain defensive about permission - requests. -1. It requires user experience design and consideration from the site's side. - There are many ways to get this wrong and provide a suboptimal user - experience. Also, providing a solution with best-practices built in helps - resource-constrained development teams more. - + ### Providing a registration JS API A JS API could be used to mark a particular HTML element as the PEPC of the @@ -915,7 +1179,6 @@ page.
Property