├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── LICENSE.md ├── README.md ├── security-self-review.md └── w3c.json /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/). 4 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Web Platform Incubator Community Group 2 | 3 | This repository is being used for work in the W3C Web Platform Incubator Community Group, governed by the [W3C Community License 4 | Agreement (CLA)](http://www.w3.org/community/about/agreements/cla/). To make substantive contributions, 5 | you must join the CG. 6 | 7 | If you are not the sole contributor to a contribution (pull request), please identify all 8 | contributors in the pull request comment. 9 | 10 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 11 | 12 | ``` 13 | +@github_username 14 | ``` 15 | 16 | If you added a contributor by mistake, you can remove them in a comment with: 17 | 18 | ``` 19 | -@github_username 20 | ``` 21 | 22 | If you are making a pull request on behalf of someone else but you had no part in designing the 23 | feature, you can remove yourself with the above syntax. 24 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | 203 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All Reports in this Repository are licensed by Contributors 2 | under the 3 | [W3C Software and Document License](http://www.w3.org/Consortium/Legal/2015/copyright-software-and-document). 4 | 5 | Contributions to Specifications are made under the 6 | [W3C CLA](https://www.w3.org/community/about/agreements/cla/). 7 | 8 | Contributions to Test Suites are made under the 9 | [W3C 3-clause BSD License](https://www.w3.org/Consortium/Legal/2008/03-bsd-license.html) 10 | 11 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Storage Foundation API Explainer 2 | 3 | > **Note:** We are working on a new API surface that will replace this proposal. 4 | > Check out [Access 5 | Handles](https://github.com/WICG/file-system-access/blob/main/AccessHandle.md) 6 | > to learn more. 7 | 8 | ## Authors 9 | 10 | * Emanuel Krivoy (fivedots@chromium.org) 11 | * Richard Stotz (rstz@chromium.org) 12 | * Jose Lopes (jabolopes@google.com, emeritus) 13 | 14 | ## Participate 15 | 16 | * [Issue Tracker](https://crbug.com/914488) 17 | * [Discussion forum](https://github.com/fivedots/storage-foundation-api-explainer/issues) 18 | 19 | ## What is this API about? 20 | 21 | The web platform increasingly offers developers the tools they need to build 22 | fined-tuned high-performance applications for the web. Most notably, WebAssembly 23 | has opened the doors to fast and powerful web applications, while technologies 24 | like Emscripten now allow developers to reuse tried and tested code on the web. 25 | In order to truly leverage this potential, developers must be given the same 26 | power and flexibility when it comes to storage. Other storage APIs often work 27 | great for the use-cases they were explicitly built for, but covering new needs 28 | through them often comes at a loss of performance and usability. 29 | 30 | This is where Storage Foundation API comes in. Storage Foundation API is a new 31 | fast and unopinionated storage API that unlocks new and much-requested 32 | use-cases for the web, such as implementing performant databases and gracefully 33 | managing large temporary files. With this new interface developers will be able 34 | to “Bring their Own Storage” to the web, reducing the feature gap between web 35 | and native. It will also complement the nascent ecosystem of performant-focused 36 | Wasm applications with a storage backend that matches its needs. 37 | 38 | Storage Foundation API is designed to resemble a very basic filesystem, aiming 39 | to give developers flexibility by providing generic, simple, and performant 40 | primitives upon which they can build higher-level components. Applications can 41 | take advantage of the best tool for their needs, finding the right balance 42 | between usability, performance, and reliability. 43 | 44 | A few examples of what could be done with Storage Foundation API: 45 | 46 | * Allow tried and true technologies to be performantly used as part of web 47 | applications e.g. using a port of your favorite storage library 48 | within a website 49 | * Distribute a Wasm module for WebSQL, allowing developers to use it across 50 | browsers and opening the door to removing the unsupported API from Chrome 51 | * Allow a music production website to operate on large amounts of media, by 52 | relying on Storage Foundation API’s performance and direct buffered access 53 | to offload sound segments to disk instead of holding them in memory 54 | * Provide a persistent [Emscripten](https://emscripten.org/) filesystem that 55 | outperforms 56 | [IDBFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#filesystem-api-idbfs) 57 | and has a simpler implementation 58 | 59 | Note: Storage Foundation API used to be called NativeIO. Some references to this 60 | name still remain, especially in the description of the interface and in code 61 | examples. They will be removed after the new name has landed on Chrome. 62 | 63 | ### Why does the web need another storage API? 64 | 65 | The web platform offers a number of storage options for developers, each of them 66 | built with specific use-cases in mind. Some of these options clearly do not 67 | overlap with this proposal as they only allow very small amounts of data to be 68 | stored (Cookies, [Web Storage 69 | API](https://html.spec.whatwg.org/multipage/webstorage.html#webstorage)) or are 70 | already deprecated for various reasons ([File and Directory Entries 71 | API](https://developer.mozilla.org/en-US/docs/Web/API/File_and_Directory_Entries_API/Firefox_support), 72 | [WebSQL](https://www.w3.org/TR/webdatabase/)). The [File System Access 73 | API](https://wicg.github.io/native-file-system/) has a similar API surface, but 74 | its main intended usage is to interface with the client’s filesystem and provide 75 | access to data that may be outside of the origin’s or even the browser’s 76 | ownership. This different focus comes with stricter security considerations and 77 | higher performance costs. 78 | 79 | [IndexedDB](https://w3c.github.io/IndexedDB/) can be used as a backend for some 80 | of the Storage Foundation API’s use-cases. For example, Emscripten includes 81 | [IDBFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#filesystem-api-idbfs), 82 | an IndexedDB-based persistent file system. However, since IndexedDB is 83 | fundamentally a key-value store, it comes with significant performance 84 | limitations. Furthermore, directly accessing sub-sections of a file is even more 85 | difficult and slower under IndexedDB. Finally, the [Cache 86 | API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) is widely 87 | supported, and is tuned for storing large-sized data such as web application 88 | resources, but the values are immutable. 89 | 90 | ## Interface and examples 91 | 92 | Note: We are currently exploring the tradeoffs between providing a synchronous 93 | vs. asynchronous API. The following interfaces are designed to be asynchronous 94 | as a temporary measure, they will be updated once a decision has been reached. 95 | 96 | There are two main parts to the API: 97 | 98 | * File handles, which provides read and write access to an existing file 99 | * Filesystem calls, which provides basic functionality to interact with files 100 | and file paths 101 | 102 | The following are our draft proposals for the interface, written in Web IDL. 103 | 104 | ### Filesystem calls 105 | 106 | All filesystem calls are accessible through a global Storage Foundation 107 | instance. 108 | 109 | 110 | ```webidl 111 | // IMPORTANT: filenames are restricted to lower-case alphanumeric and 112 | // underscore (a-z, 0-9, _). 113 | interface NativeIOFileManager { 114 | // Opens the file with the given name if it exists and otherwise creates a 115 | // new file. 116 | [RaisesException] Promise open(DOMString name); 117 | 118 | // Removes the file with the given name. 119 | [RaisesException] Promise delete(DOMString name); 120 | 121 | // Returns all existing file names. 122 | [RaisesException] Promise> getAll(); 123 | 124 | // Renames the file from old name to new name atomically. 125 | [RaisesException] Promise rename(DOMString old_name, 126 | DOMString new_name); 127 | 128 | // Requests new capacity (in bytes) for usage by the current execution 129 | // context. Returns the remaining amount of capacity available. 130 | [ CallWith = ScriptState, RaisesException ] Promise 131 | requestCapacity(unsigned long long requested_capacity); 132 | 133 | // Releases unused capacity (in bytes) from the current execution context. 134 | // Returns the remaining amount of capacity available. 135 | [ CallWith = ScriptState, RaisesException ] Promise 136 | releaseCapacity(unsigned long long requested_capacity); 137 | 138 | // Returns the capacity available for the current execution context. 139 | [ CallWith = ScriptState, RaisesException ] Promise 140 | getRemainingCapacity(); 141 | }; 142 | ``` 143 | 144 | For this API we opted to have a minimal set of functions. This reduces the 145 | surface area of the browser and simplifies the standardization process. More 146 | advanced filesystem-like functionality can be implemented by client libraries, 147 | as we've done with our prototype Emscripten filesystem. 148 | 149 | ### File handles 150 | 151 | The following functions are accessible after opening a FileHandle object. 152 | 153 | 154 | ```webidl 155 | dictionary NativeIOReadResult { 156 | // The result of transferring the buffer passed to read. It is of the same 157 | // type and length as source buffer. 158 | ArrayBufferView buffer; 159 | // The number of bytes that were successfully read into buffer. This may be 160 | // less than the buffer size, if errors occur or if the read range spans 161 | // beyond the end of the file. It is set to zero if the read range is beyond 162 | // the end of the file. 163 | unsigned long long readBytes; 164 | }; 165 | 166 | dictionary NativeIOWriteResult { 167 | // The result of transferring the buffer passed to write. It is of the same 168 | // type and length as source buffer. 169 | ArrayBufferView buffer; 170 | // The number of bytes that were successfully written into buffer. This may 171 | // be less than the buffer size if an error occurs. 172 | unsigned long long writtenBytes; 173 | }; 174 | 175 | interface NativeIOFile { 176 | Promise close(); 177 | 178 | // Synchronizes (i.e., flushes) a file's in-core state with the storage 179 | // device. 180 | // Note: flush() might be slow and we are exploring whether offering a 181 | // faster, less reliable variant would be useful. 182 | [RaisesException] Promise flush(); 183 | 184 | // Returns the length of the file in bytes. 185 | [RaisesException] Promise getLength(); 186 | 187 | // Sets the length of the file. If the new length is smaller than the current 188 | // one, bytes are removed starting from the end of the file. 189 | // Otherwise the file is extended with zero-valued bytes. 190 | [RaisesException] Promise setLength(unsigned long long length); 191 | 192 | // Reads the contents of the file at the given offset through a buffer that is 193 | // the result of transferring the given buffer, which is then left detached. 194 | // Returns a NativeIOReadResult with the transferred buffer and the the number 195 | // of bytes that were successfully read. 196 | [RaisesException] Promise read( 197 | ArrayBufferView buffer, 198 | unsigned long long file_offset); 199 | 200 | // Writes the contents of the given buffer into the file at the given offset. 201 | // The buffer is transferred before any data is written and is 202 | // therefore left detached. Returns a NativeIOWriteResult with the transferred 203 | // buffer and the number of bytes that were successfully written. The file 204 | // will be extended if the write range spans beyond its length. 205 | // 206 | // Important: write only guarantees that the data has been written to the 207 | // file but it does not guarantee that the data has been persisted to the 208 | // underlying storage. To ensure that no data loss occurs on system crash, 209 | // flush must be called and it must successfully return. 210 | [RaisesException] Promise write( 211 | ArrayBufferView buffer, 212 | unsigned long long file_offset); 213 | }; 214 | ``` 215 | 216 | ##### **Reads and writes** 217 | 218 | Open a file, write to it, read from it, and close it to guarantee integrity of 219 | the file’s contents. 220 | 221 | ```javascript 222 | const file = await storageFoundation.open("test_file"); // opens a file (creating 223 | // it if needed) 224 | try { 225 | await storageFoundation.requestCapacity(100); // request 100 bytes of 226 | // capacity for this context. 227 | 228 | const writeBuffer = new Uint8Array([64, 65, 66]); 229 | // result.buffer contains the transferred buffer, result.writtenBytes is 3, 230 | // the number of bytes written. writeBuffer is left detached. 231 | let result = await file.write(writeBuffer, 0); 232 | 233 | const readBuffer = new Uint8Array(3); 234 | // Reads at offset 1. result.buffer contains the transferred buffer, 235 | // result.readBytes is 2, the number of bytes read. readBuffer is left 236 | // detached. 237 | result = await file.read(readBuffer, 1); 238 | console.log(result.buffer); // Uint8Array(3) [65, 66, 0] 239 | } finally { 240 | file.close(); 241 | } 242 | ``` 243 | 244 | ##### **List files** 245 | 246 | Create/delete a few files and list them. 247 | 248 | ```javascript 249 | await storageFoundation.open("sunrise"); 250 | await storageFoundation.open("noon"); 251 | await storageFoundation.open("sunset"); 252 | await storageFoundation.getAll(); // ["sunset", "sunrise", "noon"] 253 | 254 | await storageFoundation.delete("noon"); 255 | await storageFoundation.getAll(); // ["sunrise", "noon"] 256 | ``` 257 | 258 | ## Design Decisions 259 | 260 | ### Sync vs. Async 261 | 262 | The decision to structure Storage Foundation API as a synchronous or 263 | asynchronous API will come from the trade-off between performance and usability 264 | vs. risks of blocking the execution flow. 265 | 266 | WebAssembly execution is synchronous but technologies like Emscripten's 267 | [Asyncify](https://emscripten.org/docs/porting/asyncify.html) allow modules to 268 | call asynchronous functions. This comes at a 269 | [cost](https://kripken.github.io/blog/wasm/2019/07/16/asyncify.html) though, a 270 | 50% increase to code size and execution time in the usual case and up to a 5x 271 | increase in extreme cases like SQLite. Existing workarounds (like having to call 272 | [FS.syncfs](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.syncfs) 273 | from an asynchronous context) lead to weak persistence guarantees and to data 274 | inconsistencies between tabs. 275 | 276 | We are currently prototyping and profiling different ways of interfacing Wasm 277 | modules with async code. We are also closely watching proposals for allowing 278 | asynchronous functions in Wasm. This section will be updated with the results 279 | and eventual design decision. 280 | 281 | ### Concurrent I/O 282 | 283 | The current prototype of Storage Foundation API allows any file to be opened 284 | only once. In particular, this means that files can not be shared between tabs. 285 | Allowing a file to be opened multiple times requires significant overhead to 286 | prevent concurrent, unsafe writes to the same file. Our current approach is 287 | therefore quite safe yet restrictive. We may revisit this decision based on 288 | developer feedback. 289 | 290 | ### Quota 291 | 292 | Storage Foundation achieves fast and predictable performance by implementing its 293 | own quota management system. 294 | 295 | The web application must explicitly ask for capacity before storing any new 296 | data. This request will be granted according to the browser's quota 297 | guidelines. The application can then use the capacity to execute write 298 | operations. The application can also delete or overwrite data to make space for 299 | new data without issuing a new request. 300 | 301 | This means that anytime an application starts a new Javascript execution context 302 | (e.g., new tab, new worker, reloading the page), it must make sure it owns 303 | sufficient capacity before writing new data. It must therefore either overwrite 304 | existing files, delete/shrink old files or request additional capacity. 305 | 306 | ## Trying It Out 307 | 308 | A prototype of Storage Foundation API is available in Chrome Canary. To enable 309 | it, launch Chrome with the `-enable-blink-features=StorageFoundationAPI` flag or 310 | enable “Experimental Web Platform feature” in 311 | ["chrome://flags"](chrome://flags). 312 | 313 | Storage Foundation API will be available in an [origin 314 | trial](https://web.dev/origin-trials/) starting with Chrome 315 | 90. [Sign up here to participate.](https://developer.chrome.com/origintrials/#/view_trial/2916080758722396161) 316 | 317 | To make it easier to try the API, we’ve developed an [Emscripten 318 | Filesystem](https://github.com/fivedots/storage-foundation-api-emscripten-fs) 319 | and a 320 | [tutorial](https://github.com/fivedots/storage-foundation-api-porting-tutorial) 321 | with an example use-case. We also provided a 322 | [wrapper](https://github.com/fivedots/storage-foundation-api-async-wrapper) that 323 | allows directly calling Storage Foundation API from C++ code. 324 | 325 | ## Security Considerations 326 | 327 | Following the same pattern as other modern storage web APIs, access to Storage 328 | Foundation API is origin-bound, meaning that an origin may only access 329 | self-created data. It is also limited to secure contexts e.g. Storage Foundation 330 | API is exposed to HTTPS- but not HTTP-served websites. 331 | 332 | Storage quota will be used to distribute access to disk space and to prevent 333 | abuse. Like other storage APIs, users must have the option of clearing the space 334 | taken by Storage Foundation API through their user agents. 335 | 336 | While no configuration information of the host is exposed through our interface, 337 | care must be taken during implementation, such as not to expose 338 | operating-system-specific behavior through the way file operations are executed. 339 | -------------------------------------------------------------------------------- /security-self-review.md: -------------------------------------------------------------------------------- 1 | # Storage Foundation API Security Self-Review 2 | 3 | https://www.w3.org/TR/2020/NOTE-security-privacy-questionnaire-20200508/ 4 | 5 | ## 2.1. What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary? 6 | 7 | Since this feature is a storage API, it does not expose any information that is 8 | not first created by the origin. 9 | 10 | ## 2.2. Is this specification exposing the minimum amount of information necessary to power the feature? 11 | 12 | Yes, we only expose data that was persisted by the origin. 13 | 14 | ## 2.3. How does this specification deal with personal information or personally-identifiable information or information derived thereof? 15 | 16 | This specification does not expose any personal information. 17 | 18 | ## 2.4. How does this specification deal with sensitive information? 19 | 20 | This specification does not deal with sensitive information. 21 | 22 | ## 2.5. Does this specification introduce new state for an origin that persists across browsing sessions? 23 | 24 | Yes, this specification introduces a new persistent storage mechanism where 25 | state may be kept. The risk of tracking must be mitigated by following similar 26 | strategies used in other storage APIs e.g. user agents should allow users to 27 | wipe stored data, an origin may only access files that are owned by it, access 28 | in third-party contexts should be governed by the same policy as other storage 29 | types, etc. 30 | 31 | ## 2.6. What information from the underlying platform, e.g. configuration data, is exposed by this specification to an origin? 32 | 33 | No information from the underlying platform is exposed. However care must be 34 | taken during implementation, such as not to expose operating-system-specific 35 | behavior through the way file operations are executed. 36 | 37 | ## 2.7. Does this specification allow an origin access to sensors on a user’s device 38 | 39 | This specification does not allow access to sensors. 40 | 41 | ## 2.8. What data does this specification expose to an origin? Please also document what data is identical to data exposed by other features, in the same or different contexts. 42 | 43 | The data exposed is only the one that was previously created by the origin. This 44 | is similar to other storage APIs 45 | 46 | ## 2.9. Does this specification enable new script execution/loading mechanisms? 47 | 48 | This specification does not enable new script execution/loading mechanisms. 49 | 50 | ## 2.10. Does this specification allow an origin to access other devices? 51 | 52 | This specification does not allow access to other devices. 53 | 54 | ## 2.11. Does this specification allow an origin some measure of control over a user agent’s native UI? 55 | 56 | This specification does not allow any control of a user agent’s UI. 57 | 58 | ## 2.12. What temporary identifiers might this specification create or expose to the web? 59 | 60 | This specification does not expose any temporary identifiers. 61 | 62 | ## 2.13. How does this specification distinguish between behavior in first-party and third-party contexts? 63 | 64 | This specification follows the same user-agent policies that apply to 65 | other storage types. It’s worth noting that the data accessible to each context 66 | will depend on the origin, and therefore a call from a third-party context would 67 | not be able to access first-party content. 68 | 69 | ## 2.14. How does this specification work in the context of a user agent’s Private Browsing or "incognito" mode? 70 | 71 | This specification will work mostly the same as in “regular” mode, except that 72 | stored information will not be persisted after a private session is finished. 73 | This should be indistinguishable from other storage APIs. 74 | 75 | ## 2.15. Does this specification have a "Security Considerations" and "Privacy Considerations" section? 76 | 77 | Yes. 78 | 79 | ## 2.16. Does this specification allow downgrading default security characteristics? 80 | 81 | This specification does not allow downgrading any security characteristics. 82 | 83 | ## 2.17. What should this questionnaire have asked? 84 | 85 | One of the privacy risks we’ve thought about comes from the way we assume most 86 | implementations would expose file operations: we were worried about OS-specific 87 | file errors or -patterns being observable through our API. This questionnaire 88 | could consider asking if there are any risks that should be especially mitigated 89 | in a “natural” or “common approach” implementation. 90 | -------------------------------------------------------------------------------- /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": [80485] 3 | , "contacts": ["yoavweiss"] 4 | , "repo-type": "cg-report" 5 | } 6 | --------------------------------------------------------------------------------