Thomas Steiner

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

Challenges with the current method

TheFile System Access APIallows developers to access files on the user's local hard disk in a reading and(optionally) writing manner. One popular app (amongmany others)that makes use of this API isVisual Studio Code (VSCode), Microsoft's IDE that runs directly in the browser. When you open VS Code,you're greeted with aWelcome screen where you can create a new file, oropen an existing file or a folder.

If you clickOpen Folder and choose one of the folders on your hard disk, thebrowser will ask you if you want VS Code to haveview access to thisfolder.

Once you grant access, you can navigate the folder hierarchy and open files inVS Code's editor. If you make a modification to any of the files, the browserwill ask you if you want to grantedit access to the folder.

If you allow this, the file icon in the address bar changes, and a little down arrowis added, indicating that the app has read and write permissions. To change thepermissions, click the icon and thenRemove access, so the app can no longeredit files.

Access lasts until you close the last tab of the origin. If you then close theapp and open it again, VS Codekind of lets you continue where you leftoff. When clickingOpen Recent, VS Code offers the previously opened folderfor reopening.

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

In the File System Access API, access to files and folders is managed throughFileSystemHandleobjects:FileSystemFileHandleobjects for files, andFileSystemDirectoryHandleobjects for folders (directories). Both can bestored in IndexedDB,and this is exactly what VS Code does. You can see this by opening ChromeDevTools, on theApplication tab navigate to the IndexedDB section, andselect the relevant tablevscode-filehandles-store in thevscode-web-dbdatabase.

The new way: what's changing and when

Chrome is launching new behavior to let users optionally grant permanent accessto 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, startingfrom Chrome 120, toggle the two flagschrome://flags/#file-system-access-persistent-permission andchrome://flags/#one-time-permission toEnabled.

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

This new three-way prompt has the following options:

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

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

This launch icon, when clicked, opens thePrivacy and security settings forthe app in question where the user sees a list of items for all the files andfolders the app has access to. Access can be revoked on a per-item basis byclicking the trashcan icon. Removing access per-item means the app can still begranted access to files in general. To revoke access in general, the user canclick 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 triggerthe new behavior with persistent permissions, there are three ways withdifferent preconditions that need to be met:

1. The user must have granted permission to a file or folder (or multiplefiles or folders) during the last visit to an origin and the app must havestored the correspondingFileSystemHandle objects in IndexedDB. Upon thenext visit to the origin, the app must have retrieved any one of the storedFileSystemHandle objects from IndexedDB and then have called itsFileSystemHandle.requestPermission() method. If these preconditions aremet, the new three-way prompt will be shown.
2. The origin must have called theFileSystemHandle.requestPermission()method on aFileSystemHandle to which access was granted before, butwhose access has been automatically revoked due to the tab beingbackgrounded for a while. (The automatic permission revocation works basedon the same logic as described in the articleOne-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 automaticallypersist permissions once the user grants access. In this case, thethree-way prompt won't be shown, instead the app gets the new behaviorby default.

In the first and the second case, the prompt lists allFileSystemHandleobjects the app previously had access to, not just the one for which therequestPermission() method is being called. Aligning with theway it works in one-time permissions,if the user denies or dismisses the prompt more than three times, it will nolonger 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, youcan test the new behavior inVS Code on the web. Open afolder and grant access, then close the tab and reopen it and clickOpenrecent (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 willshow. For a more reduced test case, check out thePersistent File System Accessdemo andcheck out its source code.

Conclusions

Persistent permissions for the File System Access API is one of themost requested featuresof the API and theimplementation bug is highlypopular, too, with many developers starring it. By bringing this feature intothe hands of developers, and foremost, the hands of users, an important featuregap compared to platform-specific apps is now closed.

Acknowledgments

This post was reviewed byChristineHollingsworth,AustinSullivan, andRachelAndrew.