idnits 2.17.1 draft-dejong-remotestorage-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (9 June 2020) is 1417 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Obsolete informational reference (is this intentional?): RFC 2818 (ref. 'HTTPS') (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7231 (ref. 'HTTP') (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7232 (ref. 'COND') (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7233 (ref. 'RANGE') (Obsoleted by RFC 9110) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET DRAFT Michiel B. de Jong 2 Document: draft-dejong-remotestorage-15 (independent) 3 F. Kooman 4 (independent) 5 S. Kippe 6 Intended Status: Proposed Standard (independent) 7 Expires: 1 December 2020 9 June 2020 9 remoteStorage 11 Abstract 13 This draft describes a protocol by which client-side applications, 14 running inside a web browser, can communicate with a data storage 15 server that is hosted on a different domain name. This way, the 16 provider of a web application need not also play the role of data 17 storage provider. The protocol supports storing, retrieving, and 18 removing individual documents, as well as listing the contents of an 19 individual folder, and access control is based on bearer tokens. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on 1 December 2020. 38 Copyright Notice 40 Copyright (c) 2020 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction...................................................2 55 2. Terminology....................................................3 56 3. Storage model..................................................3 57 4. Requests.......................................................4 58 5. Response codes.................................................7 59 6. Versioning.....................................................8 60 7. CORS headers...................................................8 61 8. Session description............................................9 62 9. Bearer tokens and access control...............................9 63 10. Application-first bearer token issuance.......................10 64 11. Storage-first bearer token issuance...........................12 65 12. Example wire transcripts......................................12 66 12.1. WebFinger................................................12 67 12.2. OAuth dialog form........................................13 68 12.3. OAuth dialog form submission.............................14 69 12.4. OPTIONS preflight........................................14 70 12.5. Initial PUT..............................................15 71 12.6. Subsequent PUT...........................................15 72 12.7. GET......................................................16 73 12.8. DELETE...................................................17 74 13. Distributed versioning........................................18 75 14. Security Considerations.......................................19 76 15. IANA Considerations...........................................20 77 16. Acknowledgments...............................................20 78 17. References....................................................20 79 17.1. Normative References.....................................20 80 17.2. Informative References...................................21 81 18. Authors' addresses............................................22 83 1. Introduction 85 Many services for data storage are available over the Internet. This 86 specification describes a vendor-independent interface for such 87 services. It is based on HTTPS, CORS and bearer tokens. The 88 metaphor for addressing data on the storage is that of folders 89 containing documents and subfolders. The actions the interface 90 exposes are: 92 * GET a folder: retrieve the names and current versions of the 93 documents and subfolders currently contained by the folder 94 * GET a document: retrieve its content type, current version, 95 and contents 97 * PUT a document: store a new version, its content type, and 98 contents, conditional on the current version 100 * DELETE a document: remove it from the storage, conditional on 101 the current version 103 * HEAD a folder or document: like GET, but omitting the response 104 body 106 The exact details of these five actions are described in this 107 specification. 109 2. Terminology 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in RFC 2119 [WORDS]. 115 "SHOULD" and "SHOULD NOT" are appropriate when valid exceptions to a 116 general requirement are known to exist or appear to exist, and it is 117 infeasible or impractical to enumerate all of them. However, they 118 should not be interpreted as permitting implementors to fail to 119 implement the general requirement when such failure would result in 120 interoperability failure. 122 3. Storage model 124 The server stores data in nodes that form a tree structure. 125 Internal nodes are called 'folders' and leaf nodes are called 126 'documents'. For a folder, the server stores references to nodes 127 contained in the folder, and it should be able to produce a list of 128 them, with for each contained item: 130 * item name 131 * item type (folder or document) 132 * current version 133 * content type 134 * content length 135 * last-modified date 137 For a document, the server stores, and should be able to produce: 139 * current version 140 * content type 141 * content length 142 * content 144 4. Requests 146 Client-to-server requests SHOULD be made over HTTPS [HTTPS], and 147 servers MUST comply with HTTP/1.1 [HTTP]. Specifically, they 148 MUST support chunked transfer coding on PUT requests. Servers MAY 149 also offer an optional switch to HTTP/2 [HTTP/2]. 151 A request is considered successful if the HTTP response code is in 152 the 2xx range (e.g. 200 OK, 201 Created), and unsuccessful if an 153 error occurred or a condition was not met, e.g. response code 404 154 Not Found, 304 Not Modified. 156 The root folder of the storage tree is represented by the following 157 URL: 159 URI_ENCODE( '/' ) 161 Subsequently, let be the URL of a folder, i.e. ends 162 with a '/', then the URL of an item contained in it is: 164 URI_ENCODE( ) 166 for a document, or: 168 URI_ENCODE( '/' ) 170 for a folder. 172 If a document with document_name exists, then no folder with 173 folder_name can exist in the same parent folder, and vice versa. 175 Item names MAY contain all characters, before URI_ENCODE, except '/' 176 and the null character '\0' and MUST NOT have zero length. Item 177 names MUST NOT be equal to '.' or to '..', as those have a special 178 semantic in URIs (Section 5.2.4 of [URI]). 180 A document description is a map containing one string-valued 'ETag' 181 field, one string-valued 'Content-Type', one integer-valued 182 'Content-Length' field, and one string-valued 'Last-Modified' field. 183 They represent the document's current version, its content type, its 184 content length, and last-modfied date respectively. The 185 last-modified date MUST be formatted as HTTP-date (Section 7.1.1.1 186 of [HTTP]). Note that content length is measured in octets (bytes), 187 not in characters. 189 A folder description is a map containing a string-valued 'ETag' 190 field, representing the folder's current version. 192 A successful GET request to a folder MUST be responded to with a 193 JSON-LD [JSON-LD] document (content type 'application/ld+json'), 194 containing as its 'items' field a map in which contained documents 195 appear as entries to a document description, and 196 contained non-empty folders appear as entries '/' to a 197 folder description. It MUST also contain an '@context' field with 198 the value 'http://remotestorage.io/spec/folder-description'. For 199 instance: 201 { 202 "@context": "http://remotestorage.io/spec/folder-description", 203 "items": { 204 "abc": { 205 "ETag": "DEADBEEFDEADBEEFDEADBEEF", 206 "Content-Type": "image/jpeg", 207 "Content-Length": 82352, 208 "Last-Modified": "Sat, 2 Jun 2018 15:58:23 GMT" 209 }, 210 "def/": { 211 "ETag": "1337ABCD1337ABCD1337ABCD" 212 } 213 } 214 } 216 GET requests to empty folders SHOULD be responded to with a folder 217 description with no items (the items field set to '{}'). However, an 218 empty folder MUST NOT be listed as an item in its parent folder. 220 PUT and DELETE requests only need to be made to documents, and never 221 to folders. A document PUT will make all ancestor folders along its 222 path become non-empty; deleting the last document from a subtree 223 will make that whole subtree become empty. Folders will therefore 224 show up in their parent folder descriptions if and only if their 225 subtree contains at least one document. 227 In contexts outside of this document, non-empty folders may be 228 called 'existent', while empty folders may be called 'non-existent'. 230 A successful GET request to a document SHOULD be responded to with 231 the full document contents in the body, the document's content type 232 in a 'Content-Type' header, its content length in octets (not in 233 characters) in a 'Content-Length' header, and the document's current 234 version as a strong ETag in an 'ETag' header. 236 Note that the use of strong ETags prohibits changing the response 237 body based on request headers; in particular, the server will not be 238 able to serve the same document uncompressed to some clients and 239 compressed to other clients when requested, since the two bodies 240 would not be identical byte-for-byte. 242 Servers MAY support Content-Range headers [RANGE] on GET requests, 243 but whether or not they do SHOULD be announced both through the 244 "http://tools.ietf.org/html/rfc7233" option mentioned below in 245 section 10 and through the HTTP 'Accept-Ranges' response header. 247 A successful PUT request to a document MUST result in: 249 * the request body being stored as the document's new content, 250 * parent and further ancestor folders being silently created as 251 necessary, with the document (name and version) being added to 252 its parent folder, and each folder added to its subsequent 253 parent, 254 * the value of its Content-Type header being stored as the 255 document's new content type, 256 * its version being updated, as well as that of its parent folder 257 and further ancestor folders, using a strong validator [HTTP, 258 section 7.2]. 260 If no valid Content-Type header was received as part of a PUT 261 request, the server MAY refuse to process the request, and instead 262 respond with a descriptive error message in the body, as well as a 263 http response code from the 4xx range. 265 RemoteStorage does not place any restrictions on the value of 266 Content-Type other than what is defined in [HTTP, section 3.1.1.5]. 268 The response MUST contain a strong ETag header, with the document's 269 new version (for instance a hash of its contents) as its value. 271 A successful DELETE request to a document MUST result in: 273 * the deletion of that document from the storage, and from its 274 parent folder, 275 * silent deletion of the parent folder if it is left empty by 276 this, and so on for further ancestor folders, 277 * the version of its parent folder being updated, as well as that 278 of further ancestor folders. 280 A successful HEAD request SHOULD be responded to like to the 281 equivalent GET request, but omitting the response body. 283 A successful OPTIONS request SHOULD be responded to as described in 284 the CORS section below. 286 5. Response codes 288 Response codes SHOULD be given as defined by [HTTP, section 6] and 289 [BEARER, section 3.1]. The following is a non-normative list of 290 status codes that are likely to occur in practice: 292 * 2xx for all successful requests. 293 * 304 for a conditional GET request whose precondition 294 fails (see "Versioning" below), 295 * 401 for all requests that require a valid bearer token and 296 where no valid one was sent (see also [BEARER, section 297 3.1]), 298 * 403 for all requests that have insufficient scope, e.g. 299 accessing a for which no scope was obtained, or 300 accessing data outside the user's , 301 * 404 for all DELETE, GET and HEAD requests to documents that do 302 not exist on the storage, 303 * 409 for a PUT request where any folder name in the path 304 clashes with an existing document's name at the same 305 level, or where the document name coincides with an 306 existing folder's name at the same level. 307 * 412 for a conditional PUT or DELETE request whose precondition 308 fails (see "Versioning" below), 309 * 413 if the payload is too large, e.g. when the server has a 310 maximum upload size for documents 311 * 414 if the request URI is too long, 312 * 416 if Range requests are supported by the server and the Range 313 request can not be satisfied, 314 * 429 if the client makes too frequent requests or is suspected 315 of malicious activity, 316 * 4xx for all malformed requests, e.g. reserved characters in the 317 path [URI, section 2.2], as well as for all PUT and DELETE 318 requests to folders, 319 * 500 if an internal server error occurred, 320 * 507 in case the account is over its storage quota, 322 Clients SHOULD also handle the case where a response takes too long 323 to arrive, or where no response is received at all. 325 6. Versioning 327 All successful GET, HEAD, PUT and DELETE requests MUST return an 328 'ETag' header [HTTP] with, in the case of GET and HEAD the current 329 version, in the case of PUT, the new version, and in case of DELETE, 330 the version that was deleted. All successful GET requests MUST 331 return a 'Cache-Control: no-cache' header. PUT and DELETE requests 332 MAY have an 'If-Match' request header [COND], and MUST fail with a 333 412 response code if that does not match the document's current 334 version. 336 GET requests MAY have a comma-separated list of revisions in an 337 'If-None-Match' header [COND], and SHOULD be responded to with a 304 338 response if that list includes the document or folder's current 339 version. A PUT request MAY have an 'If-None-Match: *' header [COND], 340 in which case it MUST fail with a 412 response code if the document 341 already exists. 343 A provider MAY offer version rollback functionality to its users, 344 but this specification does not define the interface for that. 346 7. CORS headers 348 All responses MUST carry CORS headers [CORS]. The server MUST also 349 reply to preflight OPTIONS requests as per CORS. 351 8. Session description 353 The information that a client needs to receive in order to be able 354 to connect to a server SHOULD reach the client as described in the 355 'bearer token issuance' sections below. It consists of: 357 * , consisting of 'https://' followed by a server 358 host, and optionally a server port and a path prefix as per 359 [IRI]. Examples: 360 * 'https://example.com' (host only) 361 * 'https://example.com:8080' (host and port) 362 * 'https://example.com/path/to/storage' (host, port and 363 path prefix; note there is no trailing slash) 364 * as per [OAUTH]. The token SHOULD be hard to 365 guess and SHOULD NOT be reused from one client to another. It 366 can however be reused in subsequent interactions with the same 367 client, as long as that client is still trusted. Example: 368 'ofb24f1ac3973e70j6vts19qr9v2eei' 369 * , always 'draft-dejong-remotestorage-15' for this 370 alternative version of the specification. 372 The client can make its requests using HTTPS with CORS and bearer 373 tokens, to the URL that is the concatenation of with 374 '/' plus one or more '/' strings indicating a path in the 375 folder tree, followed by zero or one strings, indicating 376 a document. For example, if is 377 "https://storage.example.com/bob", then to retrieve the folder 378 contents of the /public/documents/ folder, or to retrieve a 379 'draft.txt' document from that folder, the client would make 380 requests to, respectively: 382 * https://storage.example.com/bob/public/documents/ 383 * https://storage.example.com/bob/public/documents/draft.txt 385 9. Bearer tokens and access control 387 A bearer token represents one or more access scopes. These access 388 scopes are represented as strings of the form , 389 where the string SHOULD be lower-case alphanumerical, other 390 than the reserved word 'public', and can be ':r' or ':rw'. 391 The access the bearer token gives is the sum of its access scopes, 392 with each access scope representing the following permissions: 394 '*:rw') any request, 396 '*:r') any GET or HEAD request, 398 ':rw') any requests to paths relative to 399 that start with '/' '/' or 400 '/public/' '/', 402 ':r') any GET or HEAD requests to paths relative to 403 that start with 404 '/' '/' or '/public/' '/', 406 As a special exceptions, GET and HEAD requests to a document (but 407 not a folder) whose path starts with '/public/' are always allowed. 408 They, as well as OPTIONS requests, can be made without a bearer 409 token. Unless [KERBEROS] is used (see section 10 below), all other 410 requests SHOULD present a bearer token with sufficient access scope, 411 using a header of the following form (no double quotes here): 413 Authorization: Bearer 415 In addition, providing the access token via a HTTP query parameter 416 for GET requests MAY be supported by the server, although its use 417 is not recommended, due to its security deficiencies; see [BEARER, 418 section 2.3]. If supported, this SHOULD be announce through the 419 "http://tools.ietf.org/html/rfc6750#section-2.3" WebFinger property 420 as per section 10 below. 422 10. Application-first bearer token issuance 424 To make a remoteStorage server available as 'the remoteStorage of 425 the person identified by ', exactly one link of the following 426 format SHOULD be added to the WebFinger record [WEBFINGER] for 427 : 429 { 430 "href": , 431 "rel": "http://tools.ietf.org/id/draft-dejong-remotestorage", 432 "properties": { 433 "http://remotestorage.io/spec/version": , 434 "http://tools.ietf.org/html/rfc6749#section-4.2": , 435 "...": "...", 436 } 437 } 439 A common way of identifying persons as at is through a 440 URI of the format "acct:@". Persons who use a personal 441 domain name, not shared with any other users, can be identified by 442 a URI of the format "http:///" (see [WEBFINGER, section 4.1]). 444 Here and are as per "Session 445 description" above, and SHOULD be either null or a 446 URL where an OAuth 2.0 implicit-grant flow dialog [OAUTH] is 447 presented. 449 If is a URL, the user can supply their credentials 450 for accessing the account (how, is out of scope), and allow or 451 reject a request by the connecting application to obtain a bearer 452 token for a certain list of access scopes. Note that an account 453 will often belong to just one human user, but may also belong to a 454 group of multiple users (the remoteStorage of at ). 456 If is null, the client will not have a way to obtain 457 an access token, and SHOULD send all requests without Authorization 458 header, and rely on Kerberos [KERBEROS] instead for requests that 459 would normally be sent with a bearer token, but servers SHOULD NOT 460 impose any such access barriers for resources that would normally 461 not require an access token. 463 The '...' ellipses indicate that more properties may be present. 464 Non-breaking examples that have been proposed so far, include a 465 "http://tools.ietf.org/html/rfc6750#section-2.3" property, set to 466 the string value "true" if the server supports passing the bearer 467 token in the URI query parameter as per section 2.3 of [BEARER], 468 instead of in the request header. 470 Another example is "http://tools.ietf.org/html/rfc7233" with a 471 string value of "GET" if Content-Range headers are supported for 472 GET requests as per [RANGE]. 474 Both these proposals are non-breaking extensions, since the client 475 will have a way to work around it if these features are not present 476 (e.g. retrieve the protected resource asynchronously in the first 477 case, or request the entire resource in the second case). 479 A "http://remotestorage.io/spec/web-authoring" property has been 480 proposed with a string value of the fully qualified domain name to 481 which web authoring content is published if the server supports web 482 authoring as per [AUTHORING]. Note that this extension is a breaking 483 extension in the sense that it divides users into "haves", whose 484 remoteStorage accounts allow them to author web content, and 485 "have-nots", whose remoteStorage account does not support this 486 functionality. 488 The server MAY expire bearer tokens, and MAY require the user to 489 register applications as OAuth clients before first use; if no 490 client registration is required, the server MUST ignore the value of 491 the client_id parameter in favor of relying on the origin of the 492 redirect_uri parameter for unique client identification. See section 493 4 of [ORIGIN] for computing the origin. 495 11. Storage-first bearer token issuance 497 To request that the application connects to the user account 498 ' ' , providers MAY redirect to applications with a 499 'remotestorage' field in the URL fragment, with the user account as 500 value. 502 The appplication MUST make sure this request is intended by the 503 user. It SHOULD ask for confirmation from the user whether they want 504 to connect to the given provider account. After confirmation, it 505 SHOULD connect to the given provider account, as defined in Section 506 10. 508 If the 'remotestorage' field exists in the URL fragment, the 509 application SHOULD ignore any other parameters such as 510 'access_token' or 'state', to ensure compatibility with servers 511 that implement older versions of this specification. 513 12. Example wire transcripts 515 The following examples are not normative ("\" indicates a line was 516 wrapped). 518 12.1. WebFinger 519 In application-first, an in-browser application might issue the 520 following request, using XMLHttpRequest and CORS: 522 GET /.well-known/webfinger?resource=acct:michiel@michielbdejon\ 523 g.com HTTP/1.1 524 Host: michielbdejong.com 526 and the server's response might look like this: 528 HTTP/1.1 200 OK 529 Access-Control-Allow-Origin: * 530 Content-Type: application/jrd+json 532 { 533 "links":[{ 534 "href": "https://michielbdejong.com:7678/inbox", 535 "rel": "post-me-anything" 536 }, { 537 "href": "https://michielbdejong.com/me.jpg", 538 "rel": "avatar" 539 }, { 540 "href": "https://3pp.io:4439/storage/michiel", 541 "rel": "http://tools.ietf.org/id/draft-dejong-remotestorag\ 542 e", 543 "properties": { 544 "http://remotestorage.io/spec/version": "draft-dejong-re\ 545 motestorage-15", 546 "http://tools.ietf.org/html/rfc6749#section-4.2": "https\ 547 ://3pp.io:4439/oauth/michiel", 548 "http://tools.ietf.org/html/rfc6750#section-2.3": null, 549 "http://tools.ietf.org/html/rfc7233": null, 550 "http://remotestorage.io/spec/web-authoring": null 551 } 552 }] 553 } 555 12.2. OAuth dialog form 557 Once the in-browser application has discovered the server's OAuth 558 end-point, it will typically redirect the user to this URL, in 559 order to obtain a bearer token. Say the application is hosted on 560 https://drinks-unhosted.5apps.com/ and wants read-write access to 561 the account's "myfavoritedrinks" scope: 563 GET /oauth/michiel?redirect_uri=https%3A%2F%2Fdrinks-unhosted.5\ 564 apps.com%2F&scope=myfavoritedrinks%3Arw&client_id=https%3A%2F%2Fdrinks-\ 565 unhosted.5apps.com&response_type=token HTTP/1.1 566 Host: 3pp.io 568 The server's response might look like this (truncated for brevity): 570 HTTP/1.1 200 OK 572 573 574 575 Allow access? 576 ... 578 12.3. OAuth dialog form submission 580 When the user submits the form, the request would look something 581 like this: 583 POST /oauth HTTP/1.1 584 Host: 3pp.io:4439 585 Origin: https://3pp.io:4439 586 Content-Type: application/x-www-form-urlencoded 587 Referer: https://3pp.io:4439/oauth/michiel?redirect_uri=https%3\ 588 A%2F%2Fdrinks-unhosted.5apps.com%2F&scope=myfavoritedrinks%3Arw&client_\ 589 id=https%3A%2F%2Fdrinks-unhosted.5apps.com&response_type=token 591 client_id=https%3A%2F%2Fdrinks-unhosted.5apps.com&redirect_uri=\ 592 https%3A%2F%2Fdrinks-unhosted.5apps.com%2F&response_type=token&scope=my\ 593 favoritedrinks%3Arw&username=michiel&password=something&allow=Al\ 594 low 596 To which the server could respond with a 302 redirect, back to the 597 origin of the requesting application: 599 HTTP/1.1 302 Found 600 Location: https://drinks-unhosted.5apps.com/#access_token=j2YnG\ 601 tXjzzzHNjkd1CJxoQubA1o%3D&token_type=bearer 603 12.4. OPTIONS preflight 604 When an in-browser application makes a cross-origin request which 605 may affect the server-state, the browser will make a preflight 606 request first, with the OPTIONS verb, for instance: 608 OPTIONS /storage/michiel/myfavoritedrinks/ HTTP/1.1 609 Host: 3pp.io:4439 610 Access-Control-Request-Method: GET 611 Origin: https://drinks-unhosted.5apps.com 612 Access-Control-Request-Headers: Authorization 613 Referer: https://drinks-unhosted.5apps.com/ 615 To which the server can for instance respond: 617 HTTP/1.1 200 OK 618 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 619 Access-Control-Allow-Methods: GET, PUT, DELETE 620 Access-Control-Allow-Headers: Authorization, Content-Length, Co\ 621 ntent-Type, Origin, X-Requested-With, If-Match, If-None-Match 623 12.5. Initial PUT 625 An initial PUT may contain an 'If-None-Match: *' header, like this: 627 PUT /storage/michiel/myfavoritedrinks/test HTTP/1.1 628 Host: 3pp.io:4439 629 Content-Length: 91 630 Origin: https://drinks-unhosted.5apps.com 631 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 632 Content-Type: application/json; charset=UTF-8 633 Referer: https://drinks-unhosted.5apps.com/? 634 If-None-Match: * 636 {"name":"test","@context":"http://remotestorage.io/spec/modules\ 637 /myfavoritedrinks/drink"} 639 And the server may respond with either a 201 Created or a 200 OK 640 status: 642 HTTP/1.1 201 Created 643 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 644 ETag: "1382694045000" 646 In case the document already exists on the server, it would respond 647 with something like: 649 HTTP/1.1 412 Precondition Failed 650 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 651 ETag: "2182694048000" 653 12.6. Subsequent PUT 655 A subsequent PUT may contain an 'If-Match' header referring to the 656 ETag previously returned, like this: 658 PUT /storage/michiel/myfavoritedrinks/test HTTP/1.1 659 Host: 3pp.io:4439 660 Content-Length: 91 661 Origin: https://drinks-unhosted.5apps.com 662 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 663 Content-Type: application/json; charset=UTF-8 664 Referer: https://drinks-unhosted.5apps.com/ 665 If-Match: "1382694045000" 667 {"name":"test", "updated":true, "@context":"http://remotestorag\ 668 e.io/spec/modules/myfavoritedrinks/drink"} 670 And the server may respond with a 412 Precondition Failed or a 671 200 OK status: 673 HTTP/1.1 200 OK 674 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 675 ETag: "2182694048000" 677 12.7. GET 679 A GET request would also include the bearer token, and optionally 680 an If-None-Match header: 682 GET /storage/michiel/myfavoritedrinks/test HTTP/1.1 683 Host: 3pp.io:4439 684 Origin: https://drinks-unhosted.5apps.com 685 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 686 Referer: https://drinks-unhosted.5apps.com/ 687 If-None-Match: "1382694045000", "1382694048000" 689 And the server may respond with a 304 Not Modified status: 691 HTTP/1.1 304 Not Modified 692 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 693 ETag: "1382694048000" 695 Or a 200 OK status, plus a response body: 697 HTTP/1.1 200 OK 698 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 699 Content-Type: application/json; charset=UTF-8 700 Content-Length: 106 701 ETag: "1382694048000" 702 Cache-Control: no-cache 704 {"name":"test", "updated":true, "@context":"http://remotestora\ 705 ge.io/spec/modules/myfavoritedrinks/drink"} 707 If the GET URL would have been "/storage/michiel/myfavoritedrinks/", 708 a 200 OK response would have a folder description as the response 709 body: 711 HTTP/1.1 200 OK 712 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 713 Content-Type: application/ld+json 714 Content-Length: 171 715 ETag: "1382694048000" 716 Cache-Control: no-cache 718 {"@context":"http://remotestorage.io/spec/folder-version","ite\ 719 ms":{"test":{"ETag":"1382694048000","Content-Type":"application/json; \ 720 charset=UTF-8","Content-Length":106,"Last-Modified":"Sat, 2 Jun 2018 1\ 721 5:58:23 GMT"}}} 723 If the GET URL would have been a non-existing document like 724 "/storage/michiel/myfavoritedrinks/x", the response would have a 404 725 Not Found status, and no ETag header: 727 HTTP/1.1 404 Not Found 728 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 730 12.8. DELETE 731 A DELETE request may look like this: 733 DELETE /storage/michiel/myfavoritedrinks/test HTTP/1.1 734 Host: 3pp.io:4439 735 Origin: https://drinks-unhosted.5apps.com 736 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 737 Content-Type: application/json; charset=UTF-8 738 Referer: https://drinks-unhosted.5apps.com/ 739 If-Match: "1382694045000" 741 And the server may respond with a 412 Precondition Failed or a 200 742 OK status: 744 HTTP/1.1 412 Precondition Failed 745 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 746 ETag: "2182694048000" 748 13. Distributed versioning 750 This section is non-normative, and is intended to explain some of 751 the design choices concerning ETags and folder listings. At the 752 same time it will hopefully help readers who intend to develop an 753 application that uses remoteStorage as its per-user data storage. 754 When multiple clients have read/write access to the same document, 755 versioning conflicts may occur. For instance, client A may make 756 a PUT request that changes the document from version 1 to version 757 2, after which client B may make a PUT request attempting to change 758 the same document from version 1 to version 3. 760 In this case, client B can add an 'If-Match: "1"' header, which 761 would trigger a 412 Precondition Failed response code, since the 762 current version ("2") does not match the version required as a 763 condition by the header If-Match header ("1"). 765 Client B is now aware of the conflict, and may consult the user, 766 saying the update to version 3 failed. The user may then choose, 767 through the user interface of client B, whether version 2 or 768 version 3 should be kept, or maybe the document should be reverted 769 on the server to version 1, or a merged version 4 is needed. Client 770 B may then make a request that puts the document to the version the 771 user wishes; this time setting an 'If-Match: "2"' header instead. 773 Both client A and client B would periodically poll the root 774 folder of each scope they have access to, to see if the version 775 of the root folder changed. If it did, then one of the versions 776 listed in there will necessarily have changed, and the client can 777 make a GET request to that child folder or document, to obtain 778 its latest version. 780 Because an update in a document will result in a version change of 781 its containing folder, and that change will propagate all the way 782 to the root folder, it is not necessary to poll each document for 783 changes individually. 785 As an example, the root folder may contain 10 directories, 786 each of which contain 10 directories, which each contain 10 787 documents, so their paths would be for instance '/0/0/1', '/0/0/2', 788 etcetera. Then one GET request to the root folder '/' will be 789 enough to know if any of these 1000 documents has changed. 791 Say document '/7/9/2' has changed; then the GET request to '/' will 792 come back with a different ETag, and entry '7/' will have a 793 different value in its JSON content. The client could then request 794 '/7/', '/7/9/', and '/7/9/2' to narrow down the one document that 795 caused the root folder's ETag to change. 797 Note that the remoteStorage server does not get involved in the 798 conflict resolution. It keeps the canonical current version at all 799 times, and allows clients to make conditional GET and PUT requests, 800 but it is up to whichever client discovers a given version 801 conflict, to resolve it. 803 14. Security Considerations 805 To prevent man-in-the-middle attacks, the use of HTTPS instead of 806 http is important for both the interface itself and all end-points 807 involved in WebFinger, OAuth, and (if present) the storage-first 808 application launch dashboard. 810 A malicious party could link to an application, but specifying a 811 remoteStorage account address that it controls, thus tricking the 812 user into using a trusted application to send sensitive data to the 813 wrong remoteStorage server. To mitigate this, applications SHOULD 814 clearly display to which remoteStorage server they are sending the 815 user's data. 817 Applications could request scopes that the user did not intend to 818 give access to. The user SHOULD always be prompted to carefully 819 review which scopes an application is requesting. 821 An application may upload malicious HTML pages and then trick the 822 user into visiting them, or upload malicious client-side scripts, 823 that take advantage of being hosted on the user's domain name. The 824 origin on which the remoteStorage server has its interface SHOULD 825 therefore NOT be used for anything else, and the user SHOULD be 826 warned not to visit any web pages on that origin. In particular, the 827 OAuth dialog and launch dashboard or token revocation interface 828 SHOULD be on a different origin than the remoteStorage interface. 830 Where the use of bearer tokens is impractical, a user may choose to 831 store documents on hard-to-guess URLs [CAPABILITIES] whose path 832 after starts with '/public/', while sharing this URL 833 only with the intended audience. That way, only parties who know the 834 document's hard-to-guess URL, can access it. The server SHOULD 835 therefore make an effort to detect and stop brute-force attacks that 836 attempt to guess the location of such documents. 838 The server SHOULD also detect and stop denial-of-service attacks 839 that aim to overwhelm its interface with too much traffic. 841 15. IANA Considerations 843 This document registers the following WebFinger properties: 844 * "http://remotestorage.io/spec/version" 845 * "http://tools.ietf.org/html/rfc6749#section-4.2" 846 * "http://tools.ietf.org/html/rfc6750#section-2.3" 847 * "http://tools.ietf.org/html/rfc7233" 848 * "http://remotestorage.io/spec/web-authoring" 850 16. Acknowledgements 852 The authors would like to thank everybody who contributed to the 853 development of this protocol, including Kenny Bentley, Javier Diaz, 854 Daniel Groeber, Bjarni Runar, Jan Wildeboer, Charles Schultz, Peter 855 Svensson, Valer Mischenko, Michiel Leenaars, Jan-Christoph 856 Borchardt, Garret Alfert, Sebastian Kippe, Max Wiehle, Melvin 857 Carvalho, Martin Stadler, Geoffroy Couprie, Niklas Cathor, Marco 858 Stahl, James Coglan, Ken Eucker, Daniel Brolund, elf Pavlik, Nick 859 Jennings, Markus Sabadello, Steven te Brinke, Matthias Treydte, 860 Rick van Rein, Mark Nottingham, Julian Reschke, Markus Lanthaler, 861 and Markus Unterwaditzer, among many others. 863 17. References 865 17.1. Normative References 867 [WORDS] 868 Bradner, S., "Key words for use in RFCs to Indicate Requirement 869 Levels", BCP 14, RFC 2119, March 1997. 871 [IRI] 872 Duerst, M., "Internationalized Resource Identifiers (IRIs)", 873 RFC 3987, January 2005. 875 [URI] 876 Fielding, R., "Uniform Resource Identifier (URI): Generic 877 Syntax", RFC 3986, January 2005. 879 [WEBFINGER] 880 Jones, P., Salguerio, G., Jones, M, and Smarr, J., 881 "WebFinger", RFC7033, September 2013. 883 [OAUTH] 884 "Section 4.2: Implicit Grant", in: Hardt, D. (ed), "The OAuth 885 2.0 Authorization Framework", RFC6749, October 2012. 887 [ORIGIN] 888 "Section 4: Origin of a URI", in: Barth, A., "The Web Origin 889 Concept", RFC6454, December 2011. 891 17.2. Informative References 893 [HTTPS] 894 Rescorla, E., "HTTP Over TLS", RFC2818, May 2000. 896 [HTTP] 897 Fielding et al., "Hypertext Transfer Protocol (HTTP/1.1): 898 Semantics and Content", RFC7231, June 2014. 900 [COND] 901 Fielding et al., "Hypertext Transfer Protocol (HTTP/1.1): 902 Conditional Requests", RFC7232, June 2014. 904 [RANGE] 905 Fielding et al., "Hypertext Transfer Protocol (HTTP/1.1): 906 Conditional Requests", RFC7233, June 2014. 908 [HTTP/2] 909 M. Belshe, R. Peon, M. Thomson, Ed. "Hypertext Transfer Protocol 910 Version 2 (HTTP/2)", RFC7540, May 2015. 912 [JSON-LD] 913 M. Sporny, G. Kellogg, M. Lanthaler, "JSON-LD 1.0", W3C 914 Proposed Recommendation, 915 http://www.w3.org/TR/2014/REC-json-ld-20140116/, January 2014. 917 [CORS] 918 van Kesteren, Anne (ed), "Cross-Origin Resource Sharing -- 919 W3C Candidate Recommendation 29 January 2013", 920 http://www.w3.org/TR/cors/, January 2013. 922 [KERBEROS] 923 C. Neuman et al., "The Kerberos Network Authentication Service 924 (V5)", RFC4120, July 2005. 926 [BEARER] 927 M. Jones, D. Hardt, "The OAuth 2.0 Authorization Framework: 928 Bearer Token Usage", RFC6750, October 2012. 930 [AUTHORING] 931 "Using remoteStorage for web authoring", reSite wiki, retrieved 932 September 2014. https://github.com/michielbdejong/resite/wiki 933 /Using-remoteStorage-for-web-authoring 935 [CAPABILITIES] 936 J. Tennison (ed.), "Good Practices for Capability URLs", 937 http://www.w3.org/TR/capability-urls/, February 2014. 939 18. Authors' addresses 941 Michiel B. de Jong 942 (independent) 943 Email: michiel@unhosted.org 945 F. Kooman 946 (independent) 948 Email: fkooman@tuxed.net 950 S. Kippe 951 (independent) 953 Email: sebastian@kip.pe