You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+48-73Lines changed: 48 additions & 73 deletions
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
<imgsrc="https://raw.githubusercontent.com/tomayac/cross-origin-storage/refs/heads/main/logo-cos.svg"alt="Cross-Origin Storage (COS) logo, consisting of a folder icon with a crossing person."width="100">
4
4
5
-
This proposal outlines the design of the **Cross-Origin Storage (COS)** API, which allows web applications to store and retrieve files across different origins with explicit user consent. Using concepts introduced in **File System Living Standard** defined by the WHATWG, the COS API facilitates secure cross-origin file storage and retrieval for large files, such as AI models, SQLite databases, offline storage archives, and WebAssembly (Wasm) modules. Taking inspiration from **Cache Digests for HTTP/2**, the API uses file hashes for integrity, while human-readable descriptions allow for permission management.
5
+
This proposal outlines the design of the **Cross-Origin Storage (COS)** API, which allows web applications to store and retrieve files across different origins with explicit user consent. Using concepts introduced in **File System Living Standard** defined by the WHATWG, the COS API facilitates secure cross-origin file storage and retrieval for large files, such as AI models, SQLite databases, offline storage archives, and WebAssembly (Wasm) modules. Taking inspiration from **Cache Digests for HTTP/2**, the API uses file hashes for integrity.
6
6
7
7
This proposal is an early design sketch by Chrome Developer Relations to describe the problem below and solicit feedback on the proposed solution. It has not been approved to ship in Chrome.
8
8
@@ -19,28 +19,25 @@ This proposal is an early design sketch by Chrome Developer Relations to describ
19
19
20
20
## Introduction
21
21
22
-
The **Cross-Origin Storage (COS)** API provides a cross-origin file storage and retrieval mechanism for web applications. It allows applications to store and access large files, such as AI models, SQLite databases, offline storage archives, and Wasm modules across different origins securely and with user consent. Taking inspiration from **Cache Digests for HTTP/2**, files are identified by their hashes to ensure integrity, and human-readable descriptions need to be assigned to files for permission management. The API uses concepts like `FileSystemFileHandle` from the **File System Living Standard** with a focus on cross-origin usage. Here is an example that shows the basic flow for retrieving a file from COS:
22
+
The **Cross-Origin Storage (COS)** API provides a cross-origin file storage and retrieval mechanism for web applications. It allows applications to store and access large files, such as AI models, SQLite databases, offline storage archives, and Wasm modules across different origins securely and with user consent. Taking inspiration from **Cache Digests for HTTP/2**, files are identified by their hashes to ensure integrity. The API uses concepts like `FileSystemFileHandle` from the **File System Living Standard** with a focus on cross-origin usage. Here is an example that shows the basic flow for retrieving a file from COS:
console.log('The user did not grant permission to access the file.');
@@ -62,8 +59,7 @@ COS aims to:
62
59
63
60
- Provide a cross-origin storage mechanism for web applications to store and retrieve large files like AI models, SQLite databases, offline storage archives (for example, complete website archives at the scale of Wikipedia), and Wasm modules.
64
61
- Ensure security and user control with explicit consent before accessing or storing files.
65
-
- Use SHA-256 hashes (see [Appendix B](#appendix-b-blob-hash-with-the-web-crypto-api)) for file identification, guaranteeing data integrity and consistency.
66
-
- Require developers to assign human-readable descriptions to files for permission management.
62
+
- Use SHA-256 hashes (see [Appendix B](#appendix-b-blob-hash-with-the-web-crypto-api)) for file identification, guaranteeing data integrity and consistency.
67
63
68
64
## Non-goals
69
65
@@ -111,14 +107,14 @@ Web applications that utilize large Wasm modules can store these modules using C
111
107
112
108
### File Storage Process
113
109
114
-
The **COS** API will be available through the `navigator.crossOriginStorage` interface. Files will be stored and retrieved using their hashes, ensuring that each file is uniquely identified. A human-readable description needs to be provided for permission management of files.
110
+
The **COS** API will be available through the `navigator.crossOriginStorage` interface. Files will be stored and retrieved using their hashes, ensuring that each file is uniquely identified.
115
111
116
112
#### Storing a file
117
113
118
-
1. Hash the contents of the file using SHA-256 (or an equivalent secure algorithm, see [AppendixB](#appendix-b-blob-hash-with-the-web-crypto-api)). The used hash algorithm is communicated as a valid [`HashAlgorithmIdentifier`](https://w3c.github.io/webcrypto/#dom-hashalgorithmidentifier).
119
-
1. Request a `FileSystemFileHandle` for the file, specifying the file's hash and a human-readable description. This will trigger a permission prompt if it's okay for the origin to check if the file is stored by the browser.
120
-
1.If a file with the hash already exists, return.
121
-
1.Else, store the file in the browser.
114
+
1. Hash the contents of the file using SHA-256 (or an equivalent secure algorithm, see [Appendix B](#appendix-b-blob-hash-with-the-web-crypto-api)). The used hash algorithm is communicated as a valid [`HashAlgorithmIdentifier`](https://w3c.github.io/webcrypto/#dom-hashalgorithmidentifier).
115
+
1. Request a `FileSystemFileHandle` for the file, specifying the file's hash.
116
+
1.The resulting `FileSystemFileHandle` can only be used for writing. Trying to read would fail with a `NotAllowed``DOMException`.
1. Request a file handle using the file's hash and a human-readable description. This will trigger a permission prompt if it's okay for the origin to check if the file is stored by the browser.
163
+
1. Request a file handle using the file's hash. This will trigger a permission prompt if it's okay for the origin to check if the file is stored by the browser.
170
164
1. Retrieve the file after the user has granted access.
#### Storing and retrieving a file across unrelated sites
211
203
212
-
To illustrate the capabilities of the COS API, consider the following example where two unrelated sites want to interact with the same large language model. The first site stores the model in COS, while the second site retrieves it, each using different human-readable descriptions, one in English and one in Spanish.
204
+
To illustrate the capabilities of the COS API, consider the following example where two unrelated sites want to interact with the same large language model. The first site stores the model in COS, while the second site retrieves it.
213
205
214
-
##### Site A: Storing a large language model with an English description
206
+
##### Site A: Storing a large language model
215
207
216
-
On Site A, a web application stores a large language model in COS with a human-readable English description, "Large AI Model."
208
+
On Site A, a web application stores a large language model in COS.
##### Site B: Retrieving the same model with a Spanish description
262
+
##### Site B: Retrieving the same model
273
263
274
-
On Site B, entirely unrelated to Site A, a different web application happens to retrieve the same model from COS, but refers to it with a human-readable Spanish description, "Modelo de IA Grande."
264
+
On Site B, entirely unrelated to Site A, a different web application happens to retrieve the same model from COS.
// This now logs the Spanish description, even if the file was stored with an English description by site A.
294
-
console.log(`File retrieved with description: ${description}`);
281
+
console.log('File retrieved', fileBlob);
295
282
// Use the fileBlob as needed.
296
283
} catch (err) {
297
284
if (err.name==='NotFoundError') {
@@ -307,35 +294,28 @@ try {
307
294
##### Key points
308
295
309
296
-**Unrelated sites:** The two sites belong to different origins and do not share any context, ensuring the example demonstrates cross-origin capabilities.
310
-
-**Human-readable descriptions:** Each site assigns its own human-readable description, localized to the user's context. The description isn't shared across origins.
311
-
-**Cross-origin sharing:** Despite the different descriptions and origins, the file is securely identified by its hash, demonstrating the API's ability to facilitate cross-origin file storage and retrieval.
297
+
-**Cross-origin sharing:** Despite the different origins, the file is securely identified by its hash, demonstrating the API's ability to facilitate cross-origin file storage and retrieval.
312
298
313
299
## Detailed design discussion
314
300
315
301
### User consent and permissions
316
302
317
-
The permission prompt must clearly display the file's description to ensure users understand what file they are being asked to store or retrieve. The goal is to strike a balance between providing sufficient technical details and maintaining user-friendly simplicity.
303
+
The permission prompt must clearly convey that the user agent is granting access to a shared file. The goal is to strike a balance between providing sufficient technical details and maintaining user-friendly simplicity.
318
304
319
-
An **access permission** will be shown every time the `navigator.crossOriginStorage.requestFileHandle(hash, { description })` method is called _without_ the `create` option set to `true`, which can happen to check for existence of the file and to obtain the handle to then get the actual file.
305
+
An **access permission** will be shown every time the `navigator.crossOriginStorage.requestFileHandle(hash)` method is called _without_ the `create` option set to `true`, which can happen to check for existence of the file and to obtain the handle to then get the actual file.
320
306
321
307
The resulting `FileSystemFileHandle` that the developer obtains when `create` is set to `true` can only be used for writing. Trying to call `FileSystemFileHandle.getFile()` would fail with a `NotAllowed``DOMException`.
322
308
323
-
The `description` will be part of the permission text. User agents can decide to allow this on every visit, or to explicitly ask upon each access attempt.
309
+
User agents can decide to allow access on every visit, or to explicitly ask upon each access attempt.
324
310
325
-
If the origin has stored the file before, the user agent can decide to not show a prompt.
311
+
If an origin itself has stored the file before, the user agent can decide to not show a prompt if the origin requests access to the file again.
326
312
327
313
If the user agent knows that the file exists, it can customize the permission prompt to differentiate the existence check and the access prompt:
328
314
329
315
- If the file doesn't exist:
330
-
```
331
-
example.com wants to check if the file "large file" is stored by your browser.
332
-
[Allow this time] [Allow on every visit] [Don't allow]
333
-
```
316
+

334
317
- If the file does exist:
335
-
```
336
-
example.com wants to access the file "large file" stored by your browser.
337
-
[Allow this time] [Allow on every visit] [Don't allow]
338
-
```
318
+

339
319
340
320
> [!IMPORTANT]
341
321
> The permission could mention other recent origins that have accessed the same file, but this may be misinterpreted by the user as information the current site may learn, which is never the case. Instead, the vision is that user agents would make information about origins that have (recently) accessed a file stored in COS available in special browser settings UI, as outlined in [Handling of eviction](#handling-of-eviction).
@@ -357,10 +337,6 @@ const hash = {
357
337
358
338
The current hashing algorithm is [SHA-256](https://w3c.github.io/webcrypto/#alg-sha-256), implemented by the **Web Crypto API**. If hashing best practices should change, COS will reflect the [implementers' recommendation](https://w3c.github.io/webcrypto/#algorithm-recommendations-implementers) in the Web Crypto API.
359
339
360
-
### Human-readable descriptions
361
-
362
-
A valid human-readable description is a string that is not an empty string and that doesn't contain linebreaks or control characters.
363
-
364
340
## Open questions
365
341
366
342
### Concurrency
@@ -431,7 +407,7 @@ Many thanks for valuable inspiration or ideas from:
0 commit comments