WebExtensions/Filesystem: Difference between revisions
(Created page with "== Overview == The ability to read and write from the file system has been one of the more controversial topics with WebExtensions. In the past this has been available to leg...") |
(→Chrome: Remove repeated word (typo)) |
||
| (5 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
Status: '''THIS IS A DRAFT, more to come.''' | |||
== Overview == | == Overview == | ||
The ability to | The ability for extensions to interact directly with the filesystem has been one of the more controversial topics with WebExtensions. In the past this ability has been available to legacy extensions through APIs like [https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/OSFile.jsm OS.File and OS.File.DirectoryIterator] and this has allowed those extensions to read and write from the filesystem with no limits. | ||
... and this has allowed extensions to read and write from the | |||
Firefox is adopting a sandboxed, multi-process model to provide a safer and more secure environment for our users. As this model is implemented over the next several months, the access Firefox has - including the content it processes - to a host operating environment will continue to be reduced. | |||
Extensions are executed within Firefox, and will have similar access restrictions that are enforced by the sandbox model. Providing extensions with the ability to access the filesystem arbitrarily provides a direct challenge to the integrity of the sandbox, and any potential access outside the content sandbox provided via the WebExtension API needs to be carefully considered. | |||
This document was created to clarify [https://bugzilla.mozilla.org/show_bug.cgi?id=1246236 this bug]. | |||
In current browser products, filesystem access is provided as follows: | |||
=== Chrome === | === Chrome === | ||
Chrome provides the | While Chrome currently provides the Filesystem Storage API as documented at the [https://developer.chrome.com/apps/app_storage Chrome developer site], its use was required explicit user permission and was targeted at Chrome apps primarily. Chrome apps are being phased out of Chrome proper in favor of [https://developers.google.com/web/progressive-web-apps/ progressive web apps], and the Filesystem Storage API is being removed as part of that process, and no replacement is planned. | ||
However this API is targeted at Chrome OS and will be removed in Chrome. Currently 1,424 apps out of 37,652 ask for | However this API is targeted at Chrome OS and will be removed in Chrome. Currently 1,424 apps out of 37,652 ask for filesystem access. No word has been given of a replacement at this time. | ||
Firefox has not been implementing app APIs for extensions, but only implementing extension APIs. | |||
File access is provided through the [https://developer.chrome.com/extensions/extension#method-isAllowedFileSchemeAccess isAllowedFileSchemeAccess API], and allows extensions to read the contents of any file:// locations, as they can other protocols (e.g. http:// and https://), but write access is not provided. Additionally, a user must explicitly permit this behaviour for a given extension through the Chrome preferences pane in chrome://extensions. This API has very low use, with 55 out of approximately 58,000 extensions on the Chrome store using it (as of 03/2017). | |||
=== Firefox === | === Firefox === | ||
==== WebAPI ==== | |||
Currently there is the [https://developer.mozilla.org/en-US/docs/Web/API/File_and_Directory_Entries_API File and Directory Entries API], which is a non-standard API based off of Chrome’s implementation. Outside creation and modification of a virtual filesystem for a given app, it permits read access to a file when using an <input> element or drag and drop. | |||
==== | ==== Legacy Extensions ==== | ||
Per above, there are several existing extensions that use OS.File and other APIs to provide direct access to the filesystem. Features that rely on these APIs will no longer function with the shift to WebExtensions exclusively. | |||
==== Opera ==== | |||
Similar to Chrome, Opera supports the isAllowedFileSchemeAccess API, although its support has not been validated. Minimal testing with an extension that made use of this API caused Opera to crash. | |||
==== Edge ==== | |||
Per [https://docs.microsoft.com/en-us/microsoft-edge/extensions/api-support/supported-apis Microsoft documentation], isAllowedFileSchemeAccess is not supported. | |||
== What to Do? == | |||
Per above, providing arbitrary filesystem access in WebExtensions is not currently planned. Implementing Filesystem Storage API is also not planned, given the sandboxing concerns outlined and other platforms removing this API in the near future. Any file access should maintain the integrity of Firefox’s sandboxing initiative, and focus on user security and control. | |||
There have been a number of suggestions on how best to approach filesystem access from a general case. | |||
=== | === Just add a big button === | ||
The most popular suggestion for permitting filesystem access is to “just add a big button” that permits users to grant an extension arbitrary filesystem access. This presents a number of challenges, as it is important for users to understand the risk of the permissions they are granting to the extension. An extension with a general permission could read from or write to any content that user has privileges to access, including profile and account information for Firefox and the Operating System. Given the goals of sandboxing, the potential for misuse, and the need to ensure users can make informed decisions and maintain control over what Firefox and its components - including extensions - have access to, this approach is not something that will be considered at this time. | |||
=== Just copy Chrome === | |||
The | Effectively, this would entail providing isAllowedFileSchemeAccess only, as the Filesystem API will be removed in early 2018. The isAllowedFileSchemeAccess gives read-only access to any file in the operating environment that a user has permission to access, including system files. Neither the isAllowedFileSchemeAccess nor the Filesystem API being considered for implemention at this time as a WebExtension API given the security concerns and planned obsolescence, respectively. | ||
=== Explicit user interaction === | |||
If an extension is going to interact with a specific file and/or directory, that interaction should be performed in a way that is clear and understandable to the user. The focus would be on explicit user actions, like dragging and dropping files, or using a file picker that the user controls exclusively. These are workflows that the user is already familiar with, provides for most of the use cases that have been articulated by developers, and meet the goals of sandboxing and user control. This is the area that WebExtensions API development will focus on. | |||
== Use Cases == | |||
=== | === Accessing file:// in tabs and content scripts === | ||
This enables add-ons to read files from the filesystem. Mostly for things like configurations files (uBlock Origin) or data files (ePub Reader). | |||
Chrome: can call file URLs in tabs APIs, e.g.: tabs.create or tabs.update. However it can't then attach content scripts to those tabs so you can't get the content of the file unless you check "Allow file system access". This allows you to open a file:// URL and then through the content script read the contents. | |||
Firefox: cannot call file URLs in tabs APIs, e.g.: tabs.create or tabs.update. Can attach a content script to those tabs. This means that you can't open a file:// URL and then read through the contents, unless you can get the user to open the file:// for you. | |||
== | === iframing file urls === | ||
In Chrome the "Allow file system access" allows you to iframe a file:/// URL on an extension page. | |||
=== The downloads API === | === The downloads API === | ||
It should be noted that Firefox currently implements the | It should be noted that Firefox currently implements the [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/downloads downloads API]. This allows add-ons to write files and data to the filesystem in a consistent manner with an understandable user interface. Files are only written into the users downloads directory. Further on some operating systems files downloaded in this manner trigger OS level notifications. | ||
This allows add-ons to write files and data to the | |||
The downloads API is not accessible from the content process, preserving the file system sandboxing requirements. | The downloads API is not accessible from the content process, preserving the file system sandboxing requirements. | ||
| Line 64: | Line 82: | ||
=== Streaming downloads into the downloads directory === | === Streaming downloads into the downloads directory === | ||
If you have an extension which assists in downloading large files, using the download API can be cumbersome as you might have to read the file into memory before processing it further. By implementing a streaming API for Firefox, we hope to allow | If you have an extension which assists in downloading large files, using the download API can be cumbersome as you might have to read the file into memory before processing it further. By implementing a streaming API for Firefox, we hope to allow [https://bugzilla.mozilla.org/show_bug.cgi?id=1323414 efficient processing of large downloads] in Firefox. | ||
https://bugzilla.mozilla.org/show_bug.cgi?id=1323414 | |||
=== Choosing location in the downloads directory === | === Choosing location in the downloads directory === | ||
Currently an extension cannot choose to download a file into a particular location for file name based on rules from the extension. For this, Firefox will need to implement the | Currently an extension cannot choose to download a file into a particular location for file name based on rules from the extension. For this, Firefox will need to implement the [https://bugzilla.mozilla.org/show_bug.cgi?id=1245652 onDeterminingFilename API] that Chrome supports. | ||
https://bugzilla.mozilla.org/show_bug.cgi?id=1245652 | |||
=== Writing outside the downloads directory === | === Writing outside the downloads directory === | ||
| Line 78: | Line 92: | ||
The downloads API is limited to just the downloads directory. If the downloads could write outside the directory, then you’ve effectively got write access anywhere that the process can write too. | The downloads API is limited to just the downloads directory. If the downloads could write outside the directory, then you’ve effectively got write access anywhere that the process can write too. | ||
The problem here is giving a prompt that is understandable to the user. There is quite a difference from the user picking a directory and the extension presenting a directory to the user. | The problem here is giving a prompt that is understandable to the user. There is quite a difference from the user picking a directory and the extension presenting a directory to the user. Currently this is not something we plan to implement. | ||
=== Blob storage === | === Blob storage === | ||
Some extensions just want somewhere to store data in a profile and have persist between restarts of Firefox. Example extensions are photo editors. For this we have an indexedDB store | Some extensions just want somewhere to store data in a profile and have it persist between restarts of Firefox. Example extensions are photo editors. For this we have an indexedDB store. That can store a large amount of data with user permission, [https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Browser_storage_limits_and_eviction_criteria although there are limits]. | ||
The extension is then able to store, load and manipulate those files efficiently and remain securely inside the WebExtensions and Firefox sandbox. | The extension is then able to store, load and manipulate those files efficiently and remain securely inside the WebExtensions and Firefox sandbox. | ||
We’d like to ensure that a large storage is available, with | We’d like to ensure that a large storage is available, with [https://bugzilla.mozilla.org/show_bug.cgi?id=1331618 appropriate prompting] for the user. We’d like to [https://github.com/mdn/webextensions-examples/pull/171 provide a library] that makes using this storage easy from an extension. | ||
https://bugzilla.mozilla.org/show_bug.cgi?id=1331618 | |||
https://github.com/mdn/webextensions-examples/pull/171 | |||
=== Drag and drop, file picker support === | === Drag and drop, file picker support === | ||
Drag and drop and file picker support currently exists for providing read access to files and directories. One known limitation is that drag and drop only works on a content element that can receive a file drop event. It would be nice to enable it across the entire browser. This would require modification of content handlers. | |||
== Engineering Plan == | == Engineering Plan == | ||
Latest revision as of 22:53, 12 March 2019
Status: THIS IS A DRAFT, more to come.
Overview
The ability for extensions to interact directly with the filesystem has been one of the more controversial topics with WebExtensions. In the past this ability has been available to legacy extensions through APIs like OS.File and OS.File.DirectoryIterator and this has allowed those extensions to read and write from the filesystem with no limits.
Firefox is adopting a sandboxed, multi-process model to provide a safer and more secure environment for our users. As this model is implemented over the next several months, the access Firefox has - including the content it processes - to a host operating environment will continue to be reduced.
Extensions are executed within Firefox, and will have similar access restrictions that are enforced by the sandbox model. Providing extensions with the ability to access the filesystem arbitrarily provides a direct challenge to the integrity of the sandbox, and any potential access outside the content sandbox provided via the WebExtension API needs to be carefully considered.
This document was created to clarify this bug.
In current browser products, filesystem access is provided as follows:
Chrome
While Chrome currently provides the Filesystem Storage API as documented at the Chrome developer site, its use was required explicit user permission and was targeted at Chrome apps primarily. Chrome apps are being phased out of Chrome proper in favor of progressive web apps, and the Filesystem Storage API is being removed as part of that process, and no replacement is planned.
However this API is targeted at Chrome OS and will be removed in Chrome. Currently 1,424 apps out of 37,652 ask for filesystem access. No word has been given of a replacement at this time.
Firefox has not been implementing app APIs for extensions, but only implementing extension APIs.
File access is provided through the isAllowedFileSchemeAccess API, and allows extensions to read the contents of any file:// locations, as they can other protocols (e.g. http:// and https://), but write access is not provided. Additionally, a user must explicitly permit this behaviour for a given extension through the Chrome preferences pane in chrome://extensions. This API has very low use, with 55 out of approximately 58,000 extensions on the Chrome store using it (as of 03/2017).
Firefox
WebAPI
Currently there is the File and Directory Entries API, which is a non-standard API based off of Chrome’s implementation. Outside creation and modification of a virtual filesystem for a given app, it permits read access to a file when using an <input> element or drag and drop.
Legacy Extensions
Per above, there are several existing extensions that use OS.File and other APIs to provide direct access to the filesystem. Features that rely on these APIs will no longer function with the shift to WebExtensions exclusively.
Opera
Similar to Chrome, Opera supports the isAllowedFileSchemeAccess API, although its support has not been validated. Minimal testing with an extension that made use of this API caused Opera to crash.
Edge
Per Microsoft documentation, isAllowedFileSchemeAccess is not supported.
What to Do?
Per above, providing arbitrary filesystem access in WebExtensions is not currently planned. Implementing Filesystem Storage API is also not planned, given the sandboxing concerns outlined and other platforms removing this API in the near future. Any file access should maintain the integrity of Firefox’s sandboxing initiative, and focus on user security and control.
There have been a number of suggestions on how best to approach filesystem access from a general case.
Just add a big button
The most popular suggestion for permitting filesystem access is to “just add a big button” that permits users to grant an extension arbitrary filesystem access. This presents a number of challenges, as it is important for users to understand the risk of the permissions they are granting to the extension. An extension with a general permission could read from or write to any content that user has privileges to access, including profile and account information for Firefox and the Operating System. Given the goals of sandboxing, the potential for misuse, and the need to ensure users can make informed decisions and maintain control over what Firefox and its components - including extensions - have access to, this approach is not something that will be considered at this time.
Just copy Chrome
Effectively, this would entail providing isAllowedFileSchemeAccess only, as the Filesystem API will be removed in early 2018. The isAllowedFileSchemeAccess gives read-only access to any file in the operating environment that a user has permission to access, including system files. Neither the isAllowedFileSchemeAccess nor the Filesystem API being considered for implemention at this time as a WebExtension API given the security concerns and planned obsolescence, respectively.
Explicit user interaction
If an extension is going to interact with a specific file and/or directory, that interaction should be performed in a way that is clear and understandable to the user. The focus would be on explicit user actions, like dragging and dropping files, or using a file picker that the user controls exclusively. These are workflows that the user is already familiar with, provides for most of the use cases that have been articulated by developers, and meet the goals of sandboxing and user control. This is the area that WebExtensions API development will focus on.
Use Cases
Accessing file:// in tabs and content scripts
This enables add-ons to read files from the filesystem. Mostly for things like configurations files (uBlock Origin) or data files (ePub Reader).
Chrome: can call file URLs in tabs APIs, e.g.: tabs.create or tabs.update. However it can't then attach content scripts to those tabs so you can't get the content of the file unless you check "Allow file system access". This allows you to open a file:// URL and then through the content script read the contents.
Firefox: cannot call file URLs in tabs APIs, e.g.: tabs.create or tabs.update. Can attach a content script to those tabs. This means that you can't open a file:// URL and then read through the contents, unless you can get the user to open the file:// for you.
iframing file urls
In Chrome the "Allow file system access" allows you to iframe a file:/// URL on an extension page.
The downloads API
It should be noted that Firefox currently implements the downloads API. This allows add-ons to write files and data to the filesystem in a consistent manner with an understandable user interface. Files are only written into the users downloads directory. Further on some operating systems files downloaded in this manner trigger OS level notifications.
The downloads API is not accessible from the content process, preserving the file system sandboxing requirements.
Streaming downloads into the downloads directory
If you have an extension which assists in downloading large files, using the download API can be cumbersome as you might have to read the file into memory before processing it further. By implementing a streaming API for Firefox, we hope to allow efficient processing of large downloads in Firefox.
Choosing location in the downloads directory
Currently an extension cannot choose to download a file into a particular location for file name based on rules from the extension. For this, Firefox will need to implement the onDeterminingFilename API that Chrome supports.
Writing outside the downloads directory
The downloads API is limited to just the downloads directory. If the downloads could write outside the directory, then you’ve effectively got write access anywhere that the process can write too.
The problem here is giving a prompt that is understandable to the user. There is quite a difference from the user picking a directory and the extension presenting a directory to the user. Currently this is not something we plan to implement.
Blob storage
Some extensions just want somewhere to store data in a profile and have it persist between restarts of Firefox. Example extensions are photo editors. For this we have an indexedDB store. That can store a large amount of data with user permission, although there are limits.
The extension is then able to store, load and manipulate those files efficiently and remain securely inside the WebExtensions and Firefox sandbox.
We’d like to ensure that a large storage is available, with appropriate prompting for the user. We’d like to provide a library that makes using this storage easy from an extension.
Drag and drop, file picker support
Drag and drop and file picker support currently exists for providing read access to files and directories. One known limitation is that drag and drop only works on a content element that can receive a file drop event. It would be nice to enable it across the entire browser. This would require modification of content handlers.
Engineering Plan
Firefox 57
These are the things we plan on doing by Firefox 57:
- Streaming downloads
- A library based on indexedDB for blob storage and the appropriate support.
- Providing documentation on:
- What choices are available and why
- How to handle drag and drop in an extension
- How to use file picker support
- How to use the indexedDB blob storage library
- How to use nativeMessaging with downloads API to do processing
Not planned
These might be possible, but are too large to reasonably commit too and have too many unanswered security and usability questions:
- Writing outside the downloads directory
- Access to file:// URLs or reading files without any explicit user input