Controlling Access to Powerful Web Platform Features

Author: Contributors:,


Fugu is a renewed effort to bring powerful new capabilities to the web -- e.g. filesystem read/write access. Allowing users to control which sites are able to access such APIs is crucial for maintaining the security and privacy properties of the web. The impact of restrictions on the developer ergonomics and user utility of the API and the web platform overall must also be considered.

This document explores approaches to guarding powerful APIs, e.g. using installed web app state or some other proxy for high user engagement. The following general principles summarise the overall approach of the Chromium project to evaluating how powerful new features should be controlled on the web:

  • Access to powerful APIs should be available to the entire web platform of secure contexts, with control managed exclusively by choosers, prompts, or other user consent UX at time-of-use.
  • API-specific restrictions on the scope of access may also be used to guard against potential abuse (e.g. constraints on available directories / files, no access without a currently open foreground tab).
  • Usage of powerful APIs should be clearly disclosed to users, ideally using a central hub that offers users control over what sites can use which capabilities.
  • Installing a web app is associated with persistence, and thus persistent and/or background access to powerful APIs may only be granted (possibly subject to additional requirements) to installed web apps. Non-installed sites may still request and be granted permission to use powerful APIs, but should not have their access persisted.
  • Installation or engagement alone should not act as a vote of trust for either granting access or enabling the ability to ask for access to powerful APIs.
  • Separately, efforts should be made to curtail the existing persistency on the web platform outside of installed web apps, e.g. time-limiting permission grants, more aggressively expiring cookies, and restricting background task execution.

The remainder of this document explains the reasoning behind these principles, and summarises why alternative proposals were not taken up.

Definition of Terms

  • Powerful Web Platform APIs are capabilities which carry inherent security or privacy risks when used, but also provide users of web apps with significant utility. A canonical example is local file system access (i.e. allowing web sites to directly read and write from certain locations on the user's device). Many such capabilities already exist on the web in every browser (e.g. access to camera and microphone hardware), while new capabilities are under constant development.
  • Installation is the process where a web site may be elevated to run with a more native UX treatment on a given platform and device. It is usually tied with being granted a presence in the platform launcher (e.g. the desktop).
  • Progressive Web Apps (PWAs) are web sites which are designed to be installable.
  • Engagement is a mechanism for measuring how much users interact with a site. Higher engagement may be a signal that the user derives significant utility from a site.

Principles for Access to Powerful APIs

This section outlines the general principles that the Chromium team believes are critical when designing access to powerful new web platform APIs. These principles will be considered when evaluating how new APIs are designed.

Control and Transparency

  • Users must be able to see when the powerful APIs in use, and what sites are using them.
  • Users may revoke access to powerful APIs at any time, and preferably, the revocation UI should be intuitive to locate based on how permission is granted and/or disclosed to the user.
  • The principle of least privilege should apply as broadly as possible: users should not have to grant access to more resources than necessary to achieve their goals.

User Ergonomics

  • The web platform should be fully functional without requiring installation.
  • Sites must not be able to easily socially-engineer the user into granting permissions they wouldn't otherwise want to.
  • As much as is practical, users should not be bombarded with permission prompts, as this leads to decision fatigue.

Developer Predictability

  • Developers must be able to know when they can and cannot access powerful APIs.
  • Access mechanisms should be cross-browser compatible.


Baseline: secure contexts, top-level frames, user gesture

Minimally, all new powerful APIs must only be available in secure contexts. Ideally, availability is restricted to top-level frames and requires a user gesture to trigger. When a webpage is running in a secure context in a top-level frame with an active user gesture, we call this situation a baseline context.

Browser extensions are also included as a baseline context, as they can already make use of web platform APIs (subject to the same access checks as web sites).

The permission delegation mechanism may be used to extend privileges to iframes on a page if it makes sense for a powerful capability to be delegated in this way.

The entire web platform may access new powerful APIs

In general, any baseline context may access powerful APIs, regardless of its windowing state (in the tabbed browser or in a standalone app window), installation state (installed or not), or user engagement (highly interacted with or not). This avoids the fragmentation of the web into different, sometimes unpredictable states, and encourages careful consideration of new API surfaces such that they are exposed in a way that is safe for the web at large.

Session-based access is granted by direct user consent

In general, access to powerful APIs must be mediated by direct, informed user consent while the requesting site is open in a foreground tab via mechanisms which may include:

  • choosers
  • prompts

These mechanisms must clearly disclose the origin of the request, and follow Chromium's guidelines on displaying URLs. Implementations may be tested using tools such as Trickuri.

As much as possible, APIs should avoid a “double prompt”, e.g. a permission prompt requesting access to the file system, followed by a chooser to pick the file/directory to access. There is little security or privacy benefit to such a double prompt, and it detrimentally affects user and developer ergonomics.

There are cases where double prompts are unavoidable, e.g. a web site may request access to contact information, and if the user grants access, the browser may need to request OS-level permission to service the request.

In some cases, Chromium may implicitly grant access to an API if it is not particularly dangerous or does not make sense to guard behind a permission consent. An example of this is the Badging API, which only works for installed web apps, and results in a subtle badging effect on the installed app icon that is not invasive or privacy-sensitive. These cases should be relatively rare considering the powerful APIs that are covered by this document.

The scope of access to APIs follows the web's same-origin model.

Persistent and/or background access is restricted to installed apps

The only definite capability granted by installation is persistence. By installing, the user has explicitly indicated that they want the web app to have a persistent presence on their system.

New powerful APIs should exclusively use session-based permissions for web sites that are not installed. In particular, there should be no access while the site is not open in a tab, and access cannot be requested from a non-foreground tab. When the site is closed or navigated away from, it loses any granted access to powerful APIs it had, and must re-ask for access the next time the user visits.

Installed web sites may instead receive a permanent grant, which is removed when the site is uninstalled. In this way, installed web sites may be granted the ability to access capabilities in the background, depending on the particular details of each capability. It also avoids overloading the installation decision with consequences that users may not expect.

Persistency for installed web sites may have other requirements, but non-installed sites may never receive persistent grants to access powerful new APIs.

Some powerful APIs act as a proxy for persistence (e.g. a web site with permission to write files to disk). We distinguish persistence via a currently granted capability from persistent access to the capability itself; it is the latter privilege which is granted by being installed.

Disclose access and provide obvious user controls

It should be obvious to users when sites are using powerful APIs, and they should be given the tools needed to effectively manage and revoke access when necessary.

Improve permissions and installation UX to avoid decision fatigue

Removing persistent access from the drive-by web may drive up decision fatigue due to overprompting. However, we anticipate that many of these capabilities will have relatively niche applications that the drive-by web should not commonly access.

Repeated granting of access to powerful APIs can be used as a signal for installation. For instance, after two successful powerful permission grants, Chromium could present the user with the option to install the app on the third permission request.

Administrator policies may override prompts and enforce persistence

Powerful new capabilities may be paired with Chromium policies which permit administrators to enforce persisted access to capabilities without prompts. Capabilities may also be restricted or blocked by such policies. This is in line with how many existing permissions have admin policy overrides.

Explore ways of curtailing the lifetime of existing persistence

Currently, web sites which are not installed have access to significant persistence mechanisms:

  • all existing permissions have their decisions persisted indefinitely
  • cookie and local storage lifetime may be indefinite

To better align the existing web to the proposal presented here, we suggest a parallel effort to apply new lifetime limits on existing persistence mechanisms. For example, some of the following measures could be explored:

  • forget any granted permissions if the site has not been visited in X weeks
    • this could be challenging to apply for some capabilities such as push notifications, where there is a use case for a site being able to send informative notifications without ever needing to be opened.
  • ignore cookie Max-Age headers for non-installed sites, and erase cookies when the associated URL is no longer in browser history.
  • restrict durable/persistent storage to installed apps.
  • limit the storage quota available to sites unless they are installed (and conversely, raise storage quota limits for installed sites).
  • restrict what Service Workers may do in the background unless they control a site that is installed.

Case Study -- File System Access

We describe a high level case study based on the principles in this document for granting a web site access to a) read any file in a certain directory; b) write files to a directory.

Granting access

  • The user must give direct consent via a file picker.
  • The browser should disclose that access to the chosen file or directory will be granted to the web site.
  • A non-installed site will trigger the picker each page load that the API to read or write to a directory is invoked.
  • An installed site will have its access to reading or writing persisted.

Additional considerations for writing to a directory

  • Existing Downloads UI and protections (e.g. malicious file scanning) could be employed to ensure sites cannot use writing to a directory as a bypass.
  • Where such scanning isn't accessible, confirmation prompts for opening dangerous files in the Downloads UI may be employed instead to ensure the user knows if a potentially malicious file type is being stored.
  • Non-installed sites may have additional restrictions on which folders are available to choose (e.g. only allowing the user‘s Downloads directory, or excluding the user’s Documents directory).

Alternatives Considered

Guard API Access Behind Installation

Apps on any desktop or mobile platform require installation to run, and when installed, apps are automatically granted many privileges. We could extend this concept to the web by restricting powerful APIs like the File System Access API only to installed web apps. That is, the drive-by web could not even ask for permission to access an API -- the site would need to be installed.

A key argument for using installation in this manner is that some APIs are simply so powerful that the drive-by web should not be able to ask for them. However, this document takes the position that installation alone as a restriction is undesirable.


  • This is a simple model that is both user controllable and developer-accessible (via installation APIs such as beforeinstallpromptevent).
  • Installation is already synonymous with some amount of elevated privilege on most platforms.


  • Fragments the web platform into installed and not installed, with different APIs available depending on installed state.
  • Disempowers the drive-by web, and undermines the “try-before-you-buy” ability that the web affords today. Users may also not be willing to install a site from which they cannot ascertain any benefit.
  • Forces users to install a site to use it, even if they don't want to install.
  • May encourage web sites to prompt users on every visit to install the PWA to get access to powerful features.
  • Creates confusing scenarios when web apps are running in tabs:
    • If a web app is installed but the user opens the site in a tab, does it get access to the capability or not?
    • What about if the web app starts off in a standalone window, but the user reparents it into a tab? Or if a user sets an installed app to open in a tab?
  • Platforms where installation grants privilege all incur additional friction during installation that the web currently does not exhibit. Examples include:
    • requiring something to be downloaded,
    • requiring a confirmation prompt, installer, or some explicit privilege or grant during installation,
    • requiring an explicit display of permissions that are implicitly granted.
  • The implicit granting of privilege by installation has proven to be a security and privacy challenge on many platforms, e.g. Android native apps can access many powerful features with no permission prompt and without user recourse to revoke access.
  • The amount of friction generated by PWA installation over the drive-by web is unclear, and gating APIs behind installation increases the incentive for tricking users into installing.

Security considerations:

Restricting APIs to installed web apps is not a meaningful security improvement for users for several reasons:

  • While it eliminates the drive-by web as an attack surface, per-API security mitigations (e.g. restricting which directories are accessible for reading and writing) would still be necessary to protect users of installed web apps.
  • The effectiveness of installation as a gate on access to powerful APIs weakens as the installed web app model becomes more successful.
  • Developers are incentivised to ask for installation to utilise powerful capabilities, contributing to the erosion of installation as an effective security mitigation.
  • Per-API permission requests would still be necessary in the installed state, making installation effectively equivalent to an implicit permission grant to ask for permission to access powerful features. We should simply ask users directly if they wish to grant permission, rather than use such a two-tiered requirement.

Guard API Access Behind Engagement

This is a more general concept than installation: that continual, significant usage of a web site should allow that site to access more powerful APIs.


  • Continual usage of a web site can be taken as a signal of trust


  • Engagement is not standardised or exposed to the web platform, making it a highly unpredictable and unergonomic mechanism of controlling access.
    • Standardisation and a web-exposed API would both be requirements for using engagement in this way. Chromium's current engagement implementation is local-only and not web-exposed. There are serious privacy questions about exposing such data to the web.
  • Solving the first-run problem is non-trivial: engagement requires usage to accumulate, but there are apps which legitimately require access to a powerful API immediately to function (e.g. an editor -> files, or a weather site -> location).

Security considerations:

  • There is no real evidence to support the implicit assumption under this model that continual usage of a web site correlates with user consent to access powerful features.
    • Consider users who frequently use some web site for which location data is useful, but denies that site persistent, background access to geolocation permission.
    • A proportion of web traffic goes to sites which users may interact with frequently, but may not necessarily want to grant powerful capabilities.

Similar to installation, the Chromium team does not regard engagement as a robust way of controlling access to APIs.