File System Access API Documentation

The API is designed to support several distinct patterns of file interaction:

Single-file Editor

• Opening, editing, and saving individual files.
• Auto-saving changes during a browsing session.
• Concurrent access (files can be opened in native and web apps at the same time).
• Persistence (accessing the same files in future sessions).
• Creating new files and auto-saving them to temporary locations before a final name/location is picked.

Multi-file Editor

• Opening a directory and representing its contents as a hierarchical tree.
• Finding and editing multiple files and sub-directories within that tree.
• Accessing new files created in the directory by other applications after the root directory was opened.

File Libraries

• Opening directories containing large collections of files (e.g., photo or music managers).
• Monitoring or accessing files within a library, including new files added by other applications.

The Cloud Identifier API acts as a bridge between a web application and a Cloud Storage Provider's (CSP) local sync client.

The Workflow:

1. Registration: A CSP client registers itself with the browser, providing its executable path and the directories it syncs.
2. Request: The web app calls getCloudIdentifiers() on a FileSystemHandle.
3. Discovery: The browser identifies registered CSP clients that manage the file's path.
4. Token Exchange: The browser launches the CSP's local executable, passing the file path and the web app's origin. The CSP client then requests a token from the CSP backend and returns it to the browser.
5. Resolution: The browser bundles these tokens into FileSystemCloudIdentifier objects and resolves the promise.

Important Limitations:

• The API does not provide permissions to the files.
• The API does not allow you to interact with (fetch/modify) the files directly via the browser; you must use the CSP's own backend APIs with the provided id.
• The API does not provide metadata like sync status.

The File System Access API is designed with several security and privacy guardrails:

• Explicit User Consent: No files or directories are exposed unless the user explicitly selects them via a picker.
• Secure Contexts Only: The API is only available in secure contexts (HTTPS).
• Third-Party Restrictions: Third-party iframes (cross-origin from the top-level frame) cannot trigger native pickers or permission prompts. They can only access data previously granted to them by a top-level same-origin frame.
• Platform Protection: User agents may maintain a block list of sensitive directories (e.g., browser profile directories or platform configuration data) to prevent accidental exposure.
• Sensor Access: The API does not grant access to device sensors unless those sensors are exposed as files or directories by the underlying platform (and even then, user agents are encouraged to block such access, e.g., /dev on Linux).

The AccessHandle API provides high-performance, in-place, and exclusive write access to files within the Origin Private File System (OPFS). It is designed for use cases like Wasm-based databases (e.g., SQLite) or media processing where direct buffered access is required.

Key Features

• Exclusive Write Lock: Creating an AccessHandle prevents other access handles or WritableFileStreams from being created, ensuring data consistency.
• Unflushed Reads: You can consistently read data that has been written but not yet persisted to disk via flush().
• Zero-Copy Potential: In the asynchronous surface, it uses SharedArrayBuffer and BYOB (Bring Your Own Buffer) readers to avoid data copies.
• Persistence: Changes are not guaranteed to be persistent until flush() is called.

// In all contexts
const accessHandle = await fileHandle.createAccessHandle();
await accessHandle.writable.getWriter().write(buffer);
const reader = accessHandle.readable.getReader({ mode: "byob" });
// Assumes seekable streams and SharedArrayBuffer support are available
await reader.read(buffer, { at: 1 });

When using Cloud Identifiers, developers should be aware of two primary security and privacy implications:

Fingerprinting Risks

If a Cloud Service Provider (CSP) provides stable identifiers, web applications could potentially use them for fingerprinting the files or directories they have access to.

While existing methods like hashing file contents or using FileSystemHandle.getUniqueId() are available, they are less stable:

• Hashing contents: The identifier changes whenever the file content changes.
• FileSystemHandle.getUniqueId(): This identifier is reset when the user clears their browsing data.

Furthermore, fingerprinting via Cloud Identifiers requires the web application to have repeated access to the same FileSystemHandle, either through re-granting access or by storing the handle in IndexedDB (which is also subject to being cleared by the user).

Modification via read-only permission

A web application might only hold read permission for a FileSystemHandle locally, but if that same file is accessible via CSP backend APIs with write permissions, the application could modify the cloud-stored version. This modification would then sync to the device. However, in a scenario where a user has a sync client, they have implicitly allowed local files to be modified by the cloud state.

Creating an AccessHandle implements an exclusive lock on the file to prevent concurrent modifications from different execution contexts.

Lock Rules

• createAccessHandle(): Takes an exclusive write lock. This prevents the creation of any other AccessHandle or FileSystemWritableFileStream until the handle is closed.
• createWritable(): Takes a shared write lock. This blocks the creation of AccessHandles, but allows multiple WritableFileStreams to exist simultaneously.
• Releasing the lock: The lock is released when accessHandle.close() is called.

Error Handling

If you attempt to create an access handle while one is already active, the operation will fail (throw an error).

const accessHandle1 = await fileHandle.createAccessHandle();
try {
  const accessHandle2 = await fileHandle.createAccessHandle();
} catch (e) {
  // This catch will always be executed, since an open access handle exists
}
await accessHandle1.close();
// Now a new access handle may be created