Persistent permissions for the File System Access API

Thomas Steiner

There's now a way to get persistent read and write access to files and folders without having to grant permissions repeatedly. This post explains how it works. Before diving into the details, a quick recap of the status quo and the problem that's being solved.

Challenges with the current method

The File System Access API allows developers to access files on the user's local hard disk in a reading and (optionally) writing manner. One popular app (among many others) that makes use of this API is Visual Studio Code (VS Code), Microsoft's IDE that runs directly in the browser. When you open VS Code, you're greeted with a Welcome screen where you can create a new file, or open an existing file or a folder.

If you click Open Folder and choose one of the folders on your hard disk, the browser will ask you if you want VS Code to have view access to this folder.

Once you grant access, you can navigate the folder hierarchy and open files in VS Code's editor. If you make a modification to any of the files, the browser will ask you if you want to grant edit access to the folder.

If you allow this, the file icon in the address bar changes, and a little down arrow is added, indicating that the app has read and write permissions. To change the permissions, click the icon and then Remove access, so the app can no longer edit files.

Access lasts until you close the last tab of the origin. If you then close the app and open it again, VS Code kind of lets you continue where you left off. When clicking Open Recent, VS Code offers the previously opened folder for reopening.

But even if you have granted write permission to the folder before, you now need to grant access again. This gets tiring really quickly. Before diving into the solution, that is, persistent permissions for the File System Access API, how does VS Code even manage to remember recent folders?

In the File System Access API, access to files and folders is managed through FileSystemHandle objects: FileSystemFileHandle objects for files, and FileSystemDirectoryHandle objects for folders (directories). Both can be stored in IndexedDB, and this is exactly what VS Code does. You can see this by opening Chrome DevTools, on the Application tab navigate to the IndexedDB section, and select the relevant table vscode-filehandles-store in the vscode-web-db database.

The new way: what's changing and when

Chrome is launching new behavior to let users optionally grant permanent access to their files and folders, avoiding the need to re-prompt the user constantly. The new behavior can be observed as of Chrome 122. To test it earlier, starting from Chrome 120, toggle the two flags chrome://flags/#file-system-access-persistent-permission and chrome://flags/#one-time-permission to Enabled.

Firstly, the new behavior consists of a new three-way permission prompt that optionally lets users grant apps access to selected files and folders on each visit.

This new three-way prompt has the following options:

• Allow this time: Allows the app to have access to files for the current session. (This corresponds to the existing behavior.)
• Allow on every visit: Allows the app to have indefinite access unless access is revoked. Once the app has been granted persistent access, newly opened files and folders will be accessible persistently, too.
• Don't allow: Doesn't allow the app to have access to files. (This corresponds to the existing behavior.)

Secondly, the new behavior entails a new section in the site settings, which users can reach through a launch icon next to the File editing toggle.

This launch icon, when clicked, opens the Privacy and security settings for the app in question where the user sees a list of items for all the files and folders the app has access to. Access can be revoked on a per-item basis by clicking the trashcan icon. Removing access per-item means the app can still be granted access to files in general. To revoke access in general, the user can click the icon in the address bar, as previously described.

How to trigger the new behavior

There are no developer-facing changes to the File System Access API. To trigger the new behavior with persistent permissions, there are three ways with different preconditions that need to be met:

1. The user must have granted permission to a file or folder (or multiple files or folders) during the last visit to an origin and the app must have stored the corresponding FileSystemHandle objects in IndexedDB. Upon the next visit to the origin, the app must have retrieved any one of the stored FileSystemHandle objects from IndexedDB and then have called its FileSystemHandle.requestPermission() method. If these preconditions are met, the new three-way prompt will be shown.
2. The origin must have called the FileSystemHandle.requestPermission() method on a FileSystemHandle to which access was granted before, but whose access has been automatically revoked due to the tab being backgrounded for a while. (The automatic permission revocation works based on the same logic as described in the article One-time permissions in Chrome.) If these preconditions are met, the new three-way prompt will be shown.
3. The user must have installed the app. Installed apps will automatically persist permissions once the user grants access. In this case, the three-way prompt won't be shown, instead the app gets the new behavior by default.

In the first and the second case, the prompt lists all FileSystemHandle objects the app previously had access to, not just the one for which the requestPermission() method is being called. Aligning with the way it works in one-time permissions, if the user denies or dismisses the prompt more than three times, it will no longer trigger, and instead the regular permission prompt will show.

Try the new behavior

If you have a supporting version of Chrome or have the required flags set, you can test the new behavior in VS Code on the web. Open a folder and grant access, then close the tab and reopen it and click Open recent (note that immediate reloading doesn't work for triggering the prompt, all tabs need to be closed). Choose the previous folder and the new prompt will show. For a more reduced test case, check out the Persistent File System Access demo and check out its source code.

Conclusions

Persistent permissions for the File System Access API is one of the most requested features of the API and the implementation bug is highly popular, too, with many developers starring it. By bringing this feature into the hands of developers, and foremost, the hands of users, an important feature gap compared to platform-specific apps is now closed.

Acknowledgments

This post was reviewed by Christine Hollingsworth, Austin Sullivan, and Rachel Andrew.