idnits 2.17.1 draft-dejong-remotestorage-06.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 (30 November 2015) is 3062 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-06 Mozilla 3 F. Kooman 4 Intended Status: Proposed Standard (independent) 5 Expires: 2 June 2016 30 November 2015 7 remoteStorage 9 Abstract 11 This draft describes a protocol by which client-side applications, 12 running inside a web browser, can communicate with a data storage 13 server that is hosted on a different domain name. This way, the 14 provider of a web application need not also play the role of data 15 storage provider. The protocol supports storing, retrieving, and 16 removing individual documents, as well as listing the contents of an 17 individual folder, and access control is based on bearer tokens. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 2 June 2016. 36 Copyright Notice 38 Copyright (c) 2015 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction...................................................2 54 2. Terminology....................................................3 55 3. Storage model..................................................3 56 4. Requests.......................................................4 57 5. Response codes.................................................7 58 6. Versioning.....................................................8 59 7. CORS headers...................................................8 60 8. Session description............................................9 61 9. Bearer tokens and access control...............................9 62 10. Application-first bearer token issuance.......................10 63 11. Storage-first bearer token issuance...........................11 64 12. Example wire transcripts......................................12 65 12.1. WebFinger................................................12 66 12.2. OAuth dialog form........................................13 67 12.3. OAuth dialog form submission.............................14 68 12.4. OPTIONS preflight........................................15 69 12.5. Initial PUT..............................................15 70 12.6. Subsequent PUT...........................................16 71 12.7. GET......................................................17 72 12.8. DELETE...................................................17 73 13. Distributed versioning........................................17 74 14. Security Considerations.......................................19 75 15. IANA Considerations...........................................20 76 16. Acknowledgments...............................................21 77 17. References....................................................21 78 17.1. Normative References.....................................21 79 17.2. Informative References...................................21 80 18. Authors' addresses............................................22 82 1. Introduction 84 Many services for data storage are available over the Internet. This 85 specification describes a vendor-independent interface for such 86 services. It is based on HTTPS, CORS and bearer tokens. The 87 metaphor for addressing data on the storage is that of folders 88 containing documents and subfolders. The actions the interface 89 exposes are: 91 * GET a folder: retrieve the names and current versions of the 92 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 136 For a document, the server stores, and should be able to produce: 138 * current version 139 * content type 140 * content length 141 * content 143 4. Requests 145 Client-to-server requests SHOULD be made over HTTPS [HTTPS], and 146 servers MUST comply with HTTP/1.1 [HTTP]. Specifically, they 147 MUST support chunked transfer coding on PUT requests. Servers MAY 148 also offer an optional switch to HTTP/2 [HTTP/2]. 150 A request is considered successful if the HTTP response code is in 151 the 2xx range (e.g. 200 OK, 201 Created), and unsuccessful if an 152 error occurred or a condition was not met, e.g. response code 404 153 Not Found, 304 Not Modified. 155 The root folder of the storage tree is represented by the following 156 URL: 158 URI_ENCODE( '/' ) 160 Subsequently, let be the URL of a folder, i.e. ends 161 with a '/', then the URL of an item contained in it is: 163 URI_ENCODE( ) 165 for a document, or: 167 URI_ENCODE( '/' ) 169 for a folder. 171 Item names MAY contain all characters, before URI_ENCODE, except '/' 172 and the null character '\0' and MUST NOT have zero length. Item 173 names MUST NOT be equal to '.' or to '..', as those have a special 174 semantic in URIs (Section 5.2.4 of [URI]). 176 A document description is a map containing one string-valued 'ETag' 177 field, one string-valued 'Content-Type' and one integer-valued 178 'Content-Length' field. They represent the document's current 179 version, its content type, and its content length respectively. Note 180 that content length is measured in octets (bytes), not in 181 characters. 183 A folder description is a map containing a string-valued 'ETag' 184 field, representing the folder's current version. 186 A successful GET request to a folder MUST be responded to with a 187 JSON-LD [JSON-LD] document (content type 'application/ld+json'), 188 containing as its 'items' field a map in which contained documents 189 appear as entries to a document description, and 190 contained non-empty folders appear as entries '/' to a 191 folder description. It MUST also contain an '@context' field with 192 the value 'http://remotestorage.io/spec/folder-description'. For 193 instance: 195 { 196 "@context": "http://remotestorage.io/spec/folder-description", 197 "items": { 198 "abc": { 199 "ETag": "DEADBEEFDEADBEEFDEADBEEF", 200 "Content-Type": "image/jpeg", 201 "Content-Length": 82352 202 }, 203 "def/": { 204 "ETag": "1337ABCD1337ABCD1337ABCD" 205 } 206 } 207 } 209 GET requests to empty folders SHOULD be responded to with a folder 210 description with no items (the items field set to '{}'). However, an 211 empty folder MUST NOT be listed as an item in its parent folder. 213 PUT and DELETE requests only need to be made to documents, and never 214 to folders. A document PUT will make all ancestor folders along its 215 path become non-empty; deleting the last document from a subtree 216 will make that whole subtree become empty. Folders will therefore 217 show up in their parent folder descriptions if and only if their 218 subtree contains at least one document. 220 In contexts outside of this document, non-empty folders may be 221 called 'existent', while empty folders may be called 'non-existent'. 223 A successful GET request to a document SHOULD be responded to with 224 the full document contents in the body, the document's content type 225 in a 'Content-Type' header, its content length in octets (not in 226 characters) in a 'Content-Length' header, and the document's current 227 version as a strong ETag in an 'ETag' header. 229 Note that the use of strong ETags prohibits changing the response 230 body based on request headers; in particular, the server will not be 231 able to serve the same document uncompressed to some clients and 232 compressed to other clients when requested, since the two bodies 233 would not be identical byte-for-byte. 235 Servers MAY support Content-Range headers [RANGE] on GET requests, 236 but whether or not they do SHOULD be announced both through the 237 "http://tools.ietf.org/html/rfc7233" option mentioned below in 238 section 10 and through the HTTP 'Accept-Ranges' response header. 240 A successful PUT request to a document MUST result in: 242 * the request body being stored as the document's new content, 243 * parent and further ancestor folders being silently created as 244 necessary, with the document (name and version) being added to 245 its parent folder, and each folder added to its subsequent 246 parent, 247 * the value of its Content-Type header being stored as the 248 document's new content type, 249 * its version being updated, as well as that of its parent folder 250 and further ancestor folders, using a strong validator [HTTP, 251 section 7.2]. 253 If not exactly one Content-Type header was received as part of a 254 PUT request, the Content-Type header value contains non-ASCII 255 characters, or it is unreasonably long, the server MAY refuse to 256 process the request, and instead respond with a descriptive error 257 message in the body, and a http response code from the 4xx range. 259 The response MUST contain a strong ETag header, with the document's 260 new version (for instance a hash of its contents) as its value. 262 A successful DELETE request to a document MUST result in: 264 * the deletion of that document from the storage, and from its 265 parent folder, 266 * silent deletion of the parent folder if it is left empty by 267 this, and so on for further ancestor folders, 268 * the version of its parent folder being updated, as well as that 269 of further ancestor folders. 271 A successful HEAD request SHOULD be responded to like to the 272 equivalent GET request, but omitting the response body. 274 A successful OPTIONS request SHOULD be responded to as described in 275 the CORS section below. 277 5. Response codes 279 Response codes SHOULD be given as defined by [HTTP, section 6] and 280 [BEARER, section 3.1]. The following is a non-normative list of 281 status codes that are likely to occur in practice: 283 * 500 if an internal server error occurred, 284 * 429 if the client makes too frequent requests or is suspected 285 of malicious activity, 286 * 414 if the request URI is too long, 287 * 416 if Range requests are supported by the server and the Range 288 request can not be satisfied, 289 * 401 for all requests that require a valid bearer token and 290 where no valid one was sent (see also [BEARER, section 291 3.1]), 292 * 403 for all requests that have insufficient scope, e.g. 293 accessing a for which no scope was obtained, or 294 accessing data outside the user's , 295 * 404 for all DELETE, GET and HEAD requests to documents that do 296 not exist on the storage, 297 * 304 for a conditional GET request whose precondition 298 fails (see "Versioning" below), 299 * 409 for a PUT request where any folder name in the path 300 clashes with an existing document's name at the same 301 level, or where the document name coincides with an 302 existing folder's name at the same level. 303 * 412 for a conditional PUT or DELETE request whose precondition 304 fails (see "Versioning" below), 305 * 507 in case the account is over its storage quota, 306 * 4xx for all malformed requests, e.g. reserved characters in the 307 path [URI, section 2.2], as well as for all PUT and DELETE 308 requests to folders, 309 * 2xx for all successful requests. 311 Clients SHOULD also handle the case where a response takes too long 312 to arrive, or where no response is received at all. 314 6. Versioning 316 All successful GET, HEAD, PUT and DELETE requests MUST return an 317 'ETag' header [HTTP] with, in the case of GET and HEAD the current 318 version, in the case of PUT, the new version, and in case of DELETE, 319 the version that was deleted. All successful GET requests MUST 320 return a 'Cache-Control: no-cache' header. PUT and DELETE requests 321 MAY have an 'If-Match' request header [COND], and MUST fail with a 322 412 response code if that does not match the document's current 323 version. 325 All successful requests MUST return an 'ETag' header [HTTP] with, in 326 the case of GET, the current version, in the case of PUT, the new 327 version, and in case of DELETE, the version that was deleted. All 328 successful GET requests MUST return an 'Cache-Control: no-cache' 329 header. PUT and DELETE requests MAY have an 'If-Match' request 330 header [COND], and MUST fail with a 412 response code if that 331 does not match the document's current version. 333 GET requests MAY have a comma-separated list of revisions in an 334 'If-None-Match' header [COND], and SHOULD be responded to with a 304 335 response if that list includes the document or folder's current 336 version. A PUT request MAY have an 'If-None-Match: *' header [COND], 337 in which case it MUST fail with a 412 response code if the document 338 already exists. 340 In all 'ETag', 'If-Match' and 'If-None-Match' headers, revision 341 strings, except '*', should appear inside double quotes ("). 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-06' 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 "...": "...", 437 } 438 } 440 A common way of identifying persons as at is through a 441 URI of the format "acct:@". Persons who use a personal 442 domain name, not shared with any other users, can be identified by 443 a URI of the format "http:///" (see [WEBFINGER, section 4.1]). 445 Here and are as per "Session 446 description" above, and SHOULD be either null or a 447 URL where an OAuth 2.0 implicit-grant flow dialog [OAUTH] is 448 presented. 450 If is a URL, the user can supply their credentials 451 for accessing the account (how, is out of scope), and allow or 452 reject a request by the connecting application to obtain a bearer 453 token for a certain list of access scopes. Note that an account 454 will often belong to just one human user, but may also belong to a 455 group of multiple users (the remoteStorage of at ). 457 If is null, the client will not have a way to obtain 458 an access token, and SHOULD send all requests without Authorization 459 header, and rely on Kerberos [KERBEROS] instead for requests that 460 would normally be sent with a bearer token, but servers SHOULD NOT 461 impose any such access barriers for resources that would normally 462 not require an access token. 464 The '...' ellipses indicate that more properties may be present. 465 Non-breaking examples that have been proposed so far, include a 466 "http://tools.ietf.org/html/rfc6750#section-2.3" property, set to 467 the string value "true" if the server supports passing the bearer 468 token in the URI query parameter as per section 2.3 of [BEARER], 469 instead of in the request header. 471 Another example is "http://tools.ietf.org/html/rfc7233" with a 472 string value of "GET" if Content-Range headers are supported for 473 GET requests as per [RANGE]. 475 Both these proposals are non-breaking extensions, since the client 476 will have a way to work around it if these features are not present 477 (e.g. retrieve the protected resource asynchronously in the first 478 case, or request the entire resource in the second case). 480 A "http://remotestorage.io/spec/web-authoring" property has been 481 proposed with a string value of the fully qualified domain name to 482 which web authoring content is published if the server supports web 483 authoring as per [AUTHORING]. Note that this extension is a breaking 484 extension in the sense that it divides users into "haves", whose 485 remoteStorage accounts allow them to author web content, and 486 "have-nots", whose remoteStorage account does not support this 487 functionality. 489 The server MAY expire bearer tokens, and MAY require the user to 490 register applications as OAuth clients before first use; if no 491 client registration is required, then the server MAY ignore the 492 value of the client_id parameter, it MUST still be sent and valid, 493 in favor of relying on the origin of the redirect_uri parameter 494 for unique client identification. See section 4 of [ORIGIN] for 495 computing the Origin. 497 11. Storage-first bearer token issuance 499 The provider MAY also present a dashboard to the user, where they 500 have some way to add open web app manifests [MANIFEST]. Adding a 501 manifest to the dashboard is considered equivalent to clicking 502 'accept' in the dialog of the application-first flow. Removing one 503 is considered equivalent to revoking its access token. 505 As an equivalent to OAuth's 'scope' parameter, a 'datastores-access' 506 field SHOULD be present in the root of such an application manifest 507 document, with entries -> '{"access": "readonly"}' for 508 'r' or '{"access": "readwrite"}' for 'rw', as 509 prescribed in [DATASTORE]. 511 When the user gestures they want to use a certain application whose 512 manifest is present on the dashboard, the dashboard SHOULD redirect 513 to the application or open it in a new window. To mimic coming back 514 from the OAuth dialog, it MAY add 'access_token' and 'scope' 515 fields to the URL fragment. 517 Regardless of whether 'access_token' and 'scope' are specified, it 518 SHOULD add a 'remotestorage' field to the URL fragment, with a 519 value of the form '@' . When the application detects 520 this parameter, it SHOULD resolve the WebFinger record for 521 at and extract the and 522 information. 524 If no access_token was given, then the application SHOULD also 525 extract the information from WebFinger, and continue 526 as per application-first bearer token issuance. 528 Note that whereas a remoteStorage server SHOULD offer support for 529 the application-first flow with WebFinger and OAuth, it MAY choose 530 not to support the storage-first flow, provided that users will 531 easily remember their '@' WebFinger address at that 532 provider. Applications SHOULD, however, support both flows, which 533 means checking the URL for a 'remotestorage' parameter, but giving 534 the user a way to specify the WebFinger address if there is none. 536 If a server provides an application manifest dashboard, then it 537 SHOULD merge the list of applications there with the list of 538 issued access tokens as specified by OAuth into one list. Also, 539 the interface for revoking an access token as specified by OAuth 540 SHOULD coincide with removing an application from the dashboard. 542 Servers MAY also provide a way to create access tokens directly from 543 their user interface. Such functionality would be aimed mainly at 544 developers, to manually copy and paste a token into a script or 545 debug tool, thus bypassing the need for an OAuth dance. Clients 546 SHOULD NOT rely on this in production. 548 12. Example wire transcripts 550 The following examples are not normative ("\" indicates a line was 551 wrapped). 553 12.1. WebFinger 555 In application-first, an in-browser application might issue the 556 following request, using XMLHttpRequest and CORS: 558 GET /.well-known/webfinger?resource=acct:michiel@michielbdejon\ 559 g.com HTTP/1.1 560 Host: michielbdejong.com 562 and the server's response might look like this: 564 HTTP/1.1 200 OK 565 Access-Control-Allow-Origin: * 566 Content-Type: application/jrd+json 568 { 569 "links":[{ 570 "href": "https://michielbdejong.com:7678/inbox", 571 "rel": "post-me-anything" 572 }, { 573 "href": "https://michielbdejong.com/me.jpg", 574 "rel": "avatar" 575 }, { 576 "href": "https://3pp.io:4439/storage/michiel", 577 "rel": "http://tools.ietf.org/id/draft-dejong-remotestorag\ 578 e", 579 "properties": { 580 "http://remotestorage.io/spec/version": "draft-dejong-re\ 581 motestorage-06", 582 "http://tools.ietf.org/html/rfc6749#section-4.2": "https\ 583 ://3pp.io:4439/oauth/michiel", 584 "http://tools.ietf.org/html/rfc6750#section-2.3": null, 585 "http://tools.ietf.org/html/rfc7233": null, 586 "http://remotestorage.io/spec/web-authoring": null 587 } 588 }] 589 } 591 12.2. OAuth dialog form 593 Once the in-browser application has discovered the server's OAuth 594 end-point, it will typically redirect the user to this URL, in 595 order to obtain a bearer token. Say the application is hosted on 596 https://drinks-unhosted.5apps.com/ and wants read-write access to 597 the account's "myfavoritedrinks" scope: 599 GET /oauth/michiel?redirect_uri=https%3A%2F%2Fdrinks-unhosted.5\ 600 apps.com%2F&scope=myfavoritedrinks%3Arw&client_id=https%3A%2F%2Fdrinks-\ 601 unhosted.5apps.com&response_type=token HTTP/1.1 602 Host: 3pp.io 604 The server's response might look like this (truncated for brevity): 606 HTTP/1.1 200 OK 608 609 610 611 Allow access? 612 ... 614 12.3. OAuth dialog form submission 616 When the user submits the form, the request would look something 617 like this: 619 POST /oauth HTTP/1.1 620 Host: 3pp.io:4439 621 Origin: https://3pp.io:4439 622 Content-Type: application/x-www-form-urlencoded 623 Referer: https://3pp.io:4439/oauth/michiel?redirect_uri=https%3\ 624 A%2F%2Fdrinks-unhosted.5apps.com%2F&scope=myfavoritedrinks%3Arw&client_\ 625 id=https%3A%2F%2Fdrinks-unhosted.5apps.com&response_type=token 627 client_id=https%3A%2F%2Fdrinks-unhosted.5apps.com&redirect_uri=\ 628 https%3A%2F%2Fdrinks-unhosted.5apps.com%2F&response_type=token&scope=my\ 629 favoritedrinks%3Arw&username=michiel&password=something&allow=Al\ 630 low 632 To which the server could respond with a 302 redirect, back to the 633 origin of the requesting application: 635 HTTP/1.1 302 Found 636 Location: https://drinks-unhosted.5apps.com/#access_token=j2YnG\ 637 tXjzzzHNjkd1CJxoQubA1o%3D&token_type=bearer 639 12.4. OPTIONS preflight 641 When an in-browser application makes a cross-origin request which 642 may affect the server-state, the browser will make a preflight 643 request first, with the OPTIONS verb, for instance: 645 OPTIONS /storage/michiel/myfavoritedrinks/ HTTP/1.1 646 Host: 3pp.io:4439 647 Access-Control-Request-Method: GET 648 Origin: https://drinks-unhosted.5apps.com 649 Access-Control-Request-Headers: Authorization 650 Referer: https://drinks-unhosted.5apps.com/ 652 To which the server can for instance respond: 654 HTTP/1.1 200 OK 655 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 656 Access-Control-Allow-Methods: GET, PUT, DELETE 657 Access-Control-Allow-Headers: Authorization, Content-Length, Co\ 658 ntent-Type, Origin, X-Requested-With, If-Match, If-None-Match 660 12.5. Initial PUT 662 An initial PUT may contain an 'If-None-Match: *' header, like this: 664 PUT /storage/michiel/myfavoritedrinks/test HTTP/1.1 665 Host: 3pp.io:4439 666 Content-Length: 91 667 Origin: https://drinks-unhosted.5apps.com 668 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 669 Content-Type: application/json; charset=UTF-8 670 Referer: https://drinks-unhosted.5apps.com/? 671 If-None-Match: * 673 {"name":"test","@context":"http://remotestorage.io/spec/modules\ 674 /myfavoritedrinks/drink"} 676 And the server may respond with either a 201 Created or a 200 OK 677 status: 679 HTTP/1.1 201 Created 680 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 681 ETag: "1382694045000" 683 12.6. Subsequent PUT 685 A subsequent PUT may contain an 'If-Match' header referring to the 686 ETag previously returned, like this: 688 PUT /storage/michiel/myfavoritedrinks/test HTTP/1.1 689 Host: 3pp.io:4439 690 Content-Length: 91 691 Origin: https://drinks-unhosted.5apps.com 692 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 693 Content-Type: application/json; charset=UTF-8 694 Referer: https://drinks-unhosted.5apps.com/ 695 If-Match: "1382694045000" 697 {"name":"test", "updated":true, "@context":"http://remotestorag\ 698 e.io/spec/modules/myfavoritedrinks/drink"} 700 And the server may respond with a 412 Conflict or a 200 OK status: 702 HTTP/1.1 200 OK 703 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 704 ETag: "1382694048000" 706 12.7. GET 708 A GET request would also include the bearer token, and optionally 709 an If-None-Match header: 711 GET /storage/michiel/myfavoritedrinks/test HTTP/1.1 712 Host: 3pp.io:4439 713 Origin: https://drinks-unhosted.5apps.com 714 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 715 Referer: https://drinks-unhosted.5apps.com/ 716 If-None-Match: "1382694045000", "1382694048000" 718 And the server may respond with a 304 Not Modified status: 720 HTTP/1.1 304 Not Modified 721 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 722 ETag: "1382694048000" 724 Or a 200 OK status, plus a response body: 726 HTTP/1.1 200 OK 727 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 728 Content-Type: application/json; charset=UTF-8 729 Content-Length: 106 730 ETag: "1382694048000" 731 Cache-Control: no-cache 733 {"name":"test", "updated":true, "@context":"http://remotestora\ 734 ge.io/spec/modules/myfavoritedrinks/drink"} 736 If the GET URL would have been "/storage/michiel/myfavoritedrinks/", 737 a 200 OK response would have a folder description as the response 738 body: 740 HTTP/1.1 200 OK 741 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 742 Content-Type: application/ld+json 743 Content-Length: 171 744 ETag: "1382694048000" 745 Cache-Control: no-cache 747 {"@context":"http://remotestorage.io/spec/folder-version","ite\ 748 ms":{"test":{"ETag":"1382694048000","Content-Type":"application/json; \ 749 charset=UTF-8","Content-Length":106}}} 751 If the GET URL would have been a non-existing document like 752 "/storage/michiel/myfavoritedrinks/x", the response would have a 404 753 Not Found status, and no ETag header: 755 HTTP/1.1 404 Not Found 756 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 758 12.8. DELETE 760 A DELETE request may look like this: 762 DELETE /storage/michiel/myfavoritedrinks/test HTTP/1.1 763 Host: 3pp.io:4439 764 Origin: https://drinks-unhosted.5apps.com 765 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 766 Content-Type: application/json; charset=UTF-8 767 Referer: https://drinks-unhosted.5apps.com/ 768 If-Match: "1382694045000" 770 And the server may respond with a 412 Conflict or a 200 OK status: 772 HTTP/1.1 412 Conflict 773 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 774 ETag: "1382694048000" 776 13. Distributed versioning 778 This section is non-normative, and is intended to explain some of 779 the design choices concerning ETags and folder listings. At the 780 same time it will hopefully help readers who intend to develop an 781 application that uses remoteStorage as its per-user data storage. 782 When multiple clients have read/write access to the same document, 783 versioning conflicts may occur. For instance, client A may make 784 a PUT request that changes the document from version 1 to version 785 2, after which client B may make a PUT request attempting to change 786 the same document from version 1 to version 3. 788 In this case, client B can add an 'If-Match: "1"' header, which 789 would trigger a 412 Conflict response code, since the current 790 version ("2") does not match the version required as a condition by 791 the header If-Match header ("1"). 793 Client B is now aware of the conflict, and may consult the user, 794 saying the update to version 3 failed. The user may then choose, 795 through the user interface of client B, whether version 2 or 796 version 3 should be kept, or maybe the document should be reverted 797 on the server to version 1, or a merged version 4 is needed. Client 798 B may then make a request that puts the document to the version the 799 user wishes; this time setting an 'If-Match: "2"' header instead. 801 Both client A and client B would periodically poll the root 802 folder of each scope they have access to, to see if the version 803 of the root folder changed. If it did, then one of the versions 804 listed in there will necessarily have changed, and the client can 805 make a GET request to that child folder or document, to obtain 806 its latest version. 808 Because an update in a document will result in a version change of 809 its containing folder, and that change will propagate all the way 810 to the root folder, it is not necessary to poll each document for 811 changes individually. 813 As an example, the root folder may contain 10 directories, 814 each of which contain 10 directories, which each contain 10 815 documents, so their paths would be for instance '/0/0/1', '/0/0/2', 816 etcetera. Then one GET request to the root folder '/' will be 817 enough to know if any of these 1000 documents has changed. 819 Say document '/7/9/2' has changed; then the GET request to '/' will 820 come back with a different ETag, and entry '7/' will have a 821 different value in its JSON content. The client could then request 822 '/7/', '/7/9/', and '/7/9/2' to narrow down the one document that 823 caused the root folder's ETag to change. 825 Note that the remoteStorage server does not get involved in the 826 conflict resolution. It keeps the canonical current version at all 827 times, and allows clients to make conditional GET and PUT requests, 828 but it is up to whichever client discovers a given version 829 conflict, to resolve it. 831 14. Security Considerations 833 To prevent man-in-the-middle attacks, the use of HTTPS instead of 834 http is important for both the interface itself and all end-points 835 involved in WebFinger, OAuth, and (if present) the storage-first 836 application launch dashboard. 838 A malicious party could link to an application, but specifying a 839 remoteStorage account address that it controls, thus tricking the 840 user into using a trusted application to send sensitive data to the 841 wrong remoteStorage server. To mitigate this, applications SHOULD 842 clearly display to which remoteStorage server they are sending the 843 user's data. 845 Applications could request scopes that the user did not intend to 846 give access to. The user SHOULD always be prompted to carefully 847 review which scopes an application is requesting. 849 An application may upload malicious HTML pages and then trick the 850 user into visiting them, or upload malicious client-side scripts, 851 that take advantage of being hosted on the user's domain name. The 852 origin on which the remoteStorage server has its interface SHOULD 853 therefore NOT be used for anything else, and the user SHOULD be 854 warned not to visit any web pages on that origin. In particular, the 855 OAuth dialog and launch dashboard or token revocation interface 856 SHOULD be on a different origin than the remoteStorage interface. 858 Where the use of bearer tokens is impractical, a user may choose to 859 store documents on hard-to-guess URLs [CAPABILITIES] whose path 860 after starts with '/public/', while sharing this URL 861 only with the intended audience. That way, only parties who know the 862 document's hard-to-guess URL, can access it. The server SHOULD 863 therefore make an effort to detect and stop brute-force attacks that 864 attempt to guess the location of such documents. 866 The server SHOULD also detect and stop denial-of-service attacks 867 that aim to overwhelm its interface with too much traffic. 869 15. IANA Considerations 871 This document registers the following WebFinger properties: 872 * "http://remotestorage.io/spec/version" 873 * "http://tools.ietf.org/html/rfc6749#section-4.2" 874 * "http://tools.ietf.org/html/rfc6750#section-2.3" 875 * "http://tools.ietf.org/html/rfc7233" 876 * "http://remotestorage.io/spec/web-authoring" 878 16. Acknowledgements 880 The authors would like to thank everybody who contributed to the 881 development of this protocol, including Kenny Bentley, Javier Diaz, 882 Daniel Groeber, Bjarni Runar, Jan Wildeboer, Charles Schultz, Peter 883 Svensson, Valer Mischenko, Michiel Leenaars, Jan-Christoph 884 Borchardt, Garret Alfert, Sebastian Kippe, Max Wiehle, Melvin 885 Carvalho, Martin Stadler, Geoffroy Couprie, Niklas Cathor, Marco 886 Stahl, James Coglan, Ken Eucker, Daniel Brolund, elf Pavlik, Nick 887 Jennings, Markus Sabadello, Steven te Brinke, Matthias Treydte, 888 Rick van Rein, Mark Nottingham, Julian Reschke, Markus Lanthaler, 889 and Markus Unterwaditzer, among many others. 891 17. References 893 17.1. Normative References 895 [WORDS] 896 Bradner, S., "Key words for use in RFCs to Indicate Requirement 897 Levels", BCP 14, RFC 2119, March 1997. 899 [IRI] 900 Duerst, M., "Internationalized Resource Identifiers (IRIs)", 901 RFC 3987, January 2005. 903 [URI] 904 Fielding, R., "Uniform Resource Identifier (URI): Generic 905 Syntax", RFC 3986, January 2005. 907 [WEBFINGER] 908 Jones, P., Salguerio, G., Jones, M, and Smarr, J., 909 "WebFinger", RFC7033, September 2013. 911 [OAUTH] 912 "Section 4.2: Implicit Grant", in: Hardt, D. (ed), "The OAuth 913 2.0 Authorization Framework", RFC6749, October 2012. 915 [ORIGIN] 916 "Section 4: Origin of a URI", in: Barth, A., "The Web Origin 917 Concept", RFC6454, December 2011. 919 17.2. Informative References 921 [HTTPS] 922 Rescorla, E., "HTTP Over TLS", RFC2818, May 2000. 924 [HTTP] 925 Fielding et al., "Hypertext Transfer Protocol (HTTP/1.1): 926 Semantics and Content", RFC7231, June 2014. 928 [COND] 929 Fielding et al., "Hypertext Transfer Protocol (HTTP/1.1): 930 Conditional Requests", RFC7232, June 2014. 932 [RANGE] 933 Fielding et al., "Hypertext Transfer Protocol (HTTP/1.1): 934 Conditional Requests", RFC7233, June 2014. 936 [HTTP/2] 937 M. Belshe, R. Peon, M. Thomson, Ed. "Hypertext Transfer Protocol 938 Version 2 (HTTP/2)", RFC7540, May 2015. 940 [JSON-LD] 941 M. Sporny, G. Kellogg, M. Lanthaler, "JSON-LD 1.0", W3C 942 Proposed Recommendation, 943 http://www.w3.org/TR/2014/REC-json-ld-20140116/, January 2014. 945 [CORS] 946 van Kesteren, Anne (ed), "Cross-Origin Resource Sharing -- 947 W3C Candidate Recommendation 29 January 2013", 948 http://www.w3.org/TR/cors/, January 2013. 950 [MANIFEST] 951 Mozilla Developer Network (ed), "App manifest -- Revision 952 330541", https://developer.mozilla.org/en- 953 US/Apps/Build/Manifest$revision/566677, April 2014. 955 [DATASTORE] 956 "WebAPI/DataStore", MozillaWiki, retrieved May 2014. 957 https://wiki.mozilla.org/WebAPI/DataStore#Manifest 959 [KERBEROS] 960 C. Neuman et al., "The Kerberos Network Authentication Service 961 (V5)", RFC4120, July 2005. 963 [BEARER] 964 M. Jones, D. Hardt, "The OAuth 2.0 Authorization Framework: 965 Bearer Token Usage", RFC6750, October 2012. 967 [AUTHORING] 968 "Using remoteStorage for web authoring", reSite wiki, retrieved 969 September 2014. https://github.com/michielbdejong/resite/wiki 970 /Using-remoteStorage-for-web-authoring 972 [CAPABILITIES] 973 J. Tennison (ed.), "Good Practices for Capability URLs", 974 http://www.w3.org/TR/capability-urls/, February 2014. 976 18. Authors' addresses 978 Michiel B. de Jong 979 Mozilla 981 Email: michiel@mozilla.com 983 F. Kooman 984 (independent) 986 Email: fkooman@tuxed.net