diff --git a/CHANGELOG.md b/CHANGELOG.md index debd498..8aa9b61 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ * Servers may now offer any extension features they want. * Several mistakes in the text and wire examples were fixed. * Several confusing formulations in the text were improved. +* Mention "group accounts", to which multiple human users have access. # draft-dejong-remotestorage-03.txt diff --git a/draft-dejong-remotestorage-04.txt b/draft-dejong-remotestorage-04.txt index e4ff754..3a5f964 100644 --- a/draft-dejong-remotestorage-04.txt +++ b/draft-dejong-remotestorage-04.txt @@ -72,17 +72,17 @@ Table of Contents 12.1. WebFinger................................................12 12.2. OAuth dialog form........................................13 12.3. OAuth dialog form submission.............................14 - 12.4. OPTIONS preflight........................................14 + 12.4. OPTIONS preflight........................................15 12.5. Initial PUT..............................................15 - 12.6. Subsequent PUT...........................................15 + 12.6. Subsequent PUT...........................................16 12.7. GET......................................................16 12.8. DELETE...................................................17 13. Distributed versioning........................................17 14. Security Considerations.......................................19 15. IANA Considerations...........................................20 16. Acknowledgments...............................................20 - 17. References....................................................20 - 17.1. Normative References.....................................20 + 17. References....................................................21 + 17.1. Normative References.....................................21 17.2. Informative References...................................21 18. Authors' addresses............................................22 @@ -147,7 +147,7 @@ Internet-Draft remoteStorage December 2014 * content type * content length - + For a document, the server stores, and should be able to produce: de Jong [Page 3] @@ -155,7 +155,6 @@ de Jong [Page 3] Internet-Draft remoteStorage December 2014 - For a document, the server stores, and should be able to produce: * current version * content type @@ -198,6 +197,7 @@ Internet-Draft remoteStorage December 2014 that content length is measured in octets (bytes), not in characters. + A folder description is a map containing a string-valued 'ETag' de Jong [Page 4] @@ -205,7 +205,6 @@ de Jong [Page 4] Internet-Draft remoteStorage December 2014 - A folder description is a map containing a string-valued 'ETag' field, representing the folder's current version. A successful GET request to a folder MUST be responded to with a @@ -248,6 +247,7 @@ Internet-Draft remoteStorage December 2014 the full document contents in the body, the document's content type in a 'Content-Type' header, its content length in octets (not in characters) in a 'Content-Length' header, and the document's current + version as a strong ETag in an 'ETag' header. de Jong [Page 5] @@ -255,7 +255,6 @@ de Jong [Page 5] Internet-Draft remoteStorage December 2014 - version as a strong ETag in an 'ETag' header. Note that the use of strong ETags prohibits changing the response body based on request headers; in particular, the server will not be @@ -300,6 +299,7 @@ Internet-Draft remoteStorage December 2014 + de Jong [Page 6] Internet-Draft remoteStorage December 2014 @@ -329,7 +329,7 @@ Internet-Draft remoteStorage December 2014 existing folder's name at the same level. * 412 for a conditional PUT or DELETE request whose pre-condition fails (see "Versioning" below), - * 507 in case the user's account is over its storage quota, + * 507 in case the account is over its storage quota, * 4xx for all malformed requests (e.g. foreign characters in the path), as well as for all PUT and DELETE requests to folders, @@ -459,8 +459,9 @@ Internet-Draft remoteStorage December 2014 10. Application-first bearer token issuance To make a remoteStorage server available as 'the remoteStorage of - at ', exactly one link of the following format SHOULD - be added to the WebFinger record [WEBFINGER] of at : + at ', exactly one link of the following format + SHOULD be added to the WebFinger record [WEBFINGER] of at + : { "href": , @@ -478,9 +479,11 @@ Internet-Draft remoteStorage December 2014 presented. If is a URL, the user can supply their credentials - there (how, is out of scope), and allow or reject a request by the - connecting application to obtain a bearer token for a certain list - of access scopes. + for accessing the account (how, is out of scope), and allow or + reject a request by the connecting application to obtain a bearer + token for a certain list of access scopes. Note that an account + will often belong to just one human user, but may also belong to a + group of multiple users (the remoteStorage of at ). If is null, the client will not have a way to obtain an access token, and SHOULD send all requests without Authorization @@ -496,15 +499,15 @@ Internet-Draft remoteStorage December 2014 token in the URI query parameter as per section 2.3 of [BEARER], instead of in the request header. - Another example is "http://tools.ietf.org/html/rfc7233" with a - string value of "GET" if Content-Range headers are supported for - de Jong [Page 10] Internet-Draft remoteStorage December 2014 + + Another example is "http://tools.ietf.org/html/rfc7233" with a + string value of "GET" if Content-Range headers are supported for GET requests as per [RANGE], "PUT" if they are supported for PUT requests, and "GET,PUT" if supported for both. @@ -528,7 +531,6 @@ Internet-Draft remoteStorage December 2014 client_id parameter in favor of relying on the redirect_uri parameter for client identification. - 11. Storage-first bearer token issuance The provider MAY also present a dashboard to the user, where they @@ -546,8 +548,6 @@ Internet-Draft remoteStorage December 2014 When the user gestures they want to use a certain application whose manifest is present on the dashboard, the dashboard SHOULD redirect to the application or open it in a new window. To mimic coming back - from the OAuth dialog, it MAY add 'access_token' and 'scope' - fields to the URL fragment. de Jong [Page 11] @@ -555,12 +555,15 @@ de Jong [Page 11] Internet-Draft remoteStorage December 2014 + from the OAuth dialog, it MAY add 'access_token' and 'scope' + fields to the URL fragment. Regardless of whether 'access_token' and 'scope' are specified, it SHOULD add a 'remotestorage' field to the URL fragment, with a - value of the form '@' . When the application detects - this parameter, it SHOULD resolve the WebFinger record for at - and extract the and information. + value of the form '@' . When the application detects + this parameter, it SHOULD resolve the WebFinger record for + at and extract the and + information. If no access_token was given, then the application SHOULD also extract the information from WebFinger, and continue @@ -569,10 +572,10 @@ Internet-Draft remoteStorage December 2014 Note that whereas a remoteStorage server SHOULD offer support for the application-first flow with WebFinger and OAuth, it MAY choose not to support the storage-first flow, provided that users will - easily remember their '@' WebFinger address at that + easily remember their '@' WebFinger address at that provider. Applications SHOULD, however, support both flows, which means checking the URL for a 'remotestorage' parameter, but giving - the user a way to specify their WebFinger address if there is none. + the user a way to specify the WebFinger address if there is none. If a server provides an application manifest dashboard, then it SHOULD merge the list of applications there with the list of @@ -596,15 +599,15 @@ Internet-Draft remoteStorage December 2014 In application-first, an in-browser application might issue the following request, using XMLHttpRequest and CORS: - GET /.well-known/webfinger?resource=acct:michiel@michielbdejon\ -g.com HTTP/1.1 - de Jong [Page 12] Internet-Draft remoteStorage December 2014 + + GET /.well-known/webfinger?resource=acct:michiel@michielbdejon\ +g.com HTTP/1.1 Host: michielbdejong.com and the server's response might look like this: @@ -644,10 +647,7 @@ motestorage-04", end-point, it will typically redirect the user to this URL, in order to obtain a bearer token. Say the application is hosted on https://drinks-unhosted.5apps.com/ and wants read-write access to - the user's "myfavoritedrinks" scope: - - GET /oauth/michiel?redirect_uri=https%3A%2F%2Fdrinks-unhosted.5\ -apps.com%2F&scope=myfavoritedrinks%3Arw&client_id=https%3A%2F%2Fdrinks-\ + the account's "myfavoritedrinks" scope: de Jong [Page 13] @@ -655,6 +655,9 @@ de Jong [Page 13] Internet-Draft remoteStorage December 2014 + + GET /oauth/michiel?redirect_uri=https%3A%2F%2Fdrinks-unhosted.5\ +apps.com%2F&scope=myfavoritedrinks%3Arw&client_id=https%3A%2F%2Fdrinks-\ unhosted.5apps.com&response_type=token HTTP/1.1 Host: 3pp.io @@ -668,7 +671,6 @@ unhosted.5apps.com&response_type=token HTTP/1.1 Allow access? ... - 12.3. OAuth dialog form submission When the user submits the form, the request would look something @@ -696,8 +698,6 @@ XjzzzHNjkd1CJxoQubA1o%3D&token_type=bearer&state= 12.4. OPTIONS preflight - When an in-browser application makes a cross-origin request which - may affect the server-state, the browser will make a preflight de Jong [Page 14] @@ -705,6 +705,8 @@ de Jong [Page 14] Internet-Draft remoteStorage December 2014 + When an in-browser application makes a cross-origin request which + may affect the server-state, the browser will make a preflight request first, with the OPTIONS verb, for instance: OPTIONS /storage/michiel/myfavoritedrinks/ HTTP/1.1 @@ -722,7 +724,6 @@ Internet-Draft remoteStorage December 2014 Access-Control-Allow-Headers: Authorization, Content-Length, Co\ ntent-Type, Origin, X-Requested-With, If-Match, If-None-Match - 12.5. Initial PUT An initial PUT may contain an 'If-None-Match: *' header, like this: @@ -749,12 +750,12 @@ ntent-Type, Origin, X-Requested-With, If-Match, If-None-Match 12.6. Subsequent PUT - de Jong [Page 15] Internet-Draft remoteStorage December 2014 + A subsequent PUT may contain an 'If-Match' header referring to the ETag previously returned, like this: @@ -797,7 +798,6 @@ e.io/spec/modules/myfavoritedrinks/drink"} Or a 200 OK status, plus a response body: HTTP/1.1 200 OK - Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com de Jong [Page 16] @@ -805,6 +805,7 @@ de Jong [Page 16] Internet-Draft remoteStorage December 2014 + Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com Content-Type: application/json; charset=UTF-8 Content-Length: 106 ETag: "1382694048000" @@ -847,7 +848,6 @@ charset=UTF-8","Content-Length":106}}} Referer: https://drinks-unhosted.5apps.com/? If-Match: "1382694045000" - And the server may respond with a 412 Conflict or a 200 OK status: de Jong [Page 17] @@ -855,6 +855,7 @@ de Jong [Page 17] Internet-Draft remoteStorage December 2014 + And the server may respond with a 412 Conflict or a 200 OK status: HTTP/1.1 412 Conflict Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com @@ -897,7 +898,6 @@ Internet-Draft remoteStorage December 2014 to the root folder, it is not necessary to poll each document for changes individually. - As an example, the root folder may contain 10 directories, de Jong [Page 18] @@ -905,6 +905,7 @@ de Jong [Page 18] Internet-Draft remoteStorage December 2014 + As an example, the root folder may contain 10 directories, each of which contain 10 directories, which each contain 10 documents, so their paths would be for instance '/0/0/1', '/0/0/2', etcetera. Then one GET request to the root folder '/' will be @@ -930,11 +931,11 @@ Internet-Draft remoteStorage December 2014 application launch dashboard. A malicious party could link to an application, but specifying a - remoteStorage user address that it controls, thus tricking the user - into using a trusted application to send sensitive data to the wrong - remoteStorage server. To mitigate this, applications SHOULD clearly - display to which remoteStorage server they are sending the user's - data. + remoteStorage account address that it controls, thus tricking the + user into using a trusted application to send sensitive data to the + wrong remoteStorage server. To mitigate this, applications SHOULD + clearly display to which remoteStorage server they are sending the + user's data. Applications could request scopes that the user did not intend to give access to. The user SHOULD always be prompted to carefully @@ -947,7 +948,6 @@ Internet-Draft remoteStorage December 2014 therefore NOT be used for anything else, and the user SHOULD be warned not to visit any web pages on that origin. In particular, the OAuth dialog and launch dashboard or token revokation interface - SHOULD be on a different origin than the remoteStorage interface. de Jong [Page 19] @@ -955,6 +955,7 @@ de Jong [Page 19] Internet-Draft remoteStorage December 2014 + SHOULD be on a different origin than the remoteStorage interface. Where the use of bearer tokens is impractical, a user may choose to store documents on hard-to-guess URLs whose path after @@ -999,12 +1000,12 @@ Internet-Draft remoteStorage December 2014 Levels", BCP 14, RFC 2119, March 1997. - de Jong [Page 20] Internet-Draft remoteStorage December 2014 + [IRI] Duerst, M., "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005. @@ -1017,7 +1018,6 @@ Internet-Draft remoteStorage December 2014 "Section 4.2: Implicit Grant", in: Hardt, D. (ed), "The OAuth 2.0 Authorization Framework", RFC6749, October 2012. - 17.2. Informative References [HTTPS] diff --git a/source.txt b/source.txt index 3d31856..0fc8923 100644 --- a/source.txt +++ b/source.txt @@ -65,17 +65,17 @@ Table of Contents 12.1. WebFinger................................................12 12.2. OAuth dialog form........................................13 12.3. OAuth dialog form submission.............................14 - 12.4. OPTIONS preflight........................................14 + 12.4. OPTIONS preflight........................................15 12.5. Initial PUT..............................................15 - 12.6. Subsequent PUT...........................................15 + 12.6. Subsequent PUT...........................................16 12.7. GET......................................................16 12.8. DELETE...................................................17 13. Distributed versioning........................................17 14. Security Considerations.......................................19 15. IANA Considerations...........................................20 16. Acknowledgments...............................................20 - 17. References....................................................20 - 17.1. Normative References.....................................20 + 17. References....................................................21 + 17.1. Normative References.....................................21 17.2. Informative References...................................21 18. Authors' addresses............................................22 @@ -133,7 +133,6 @@ Table of Contents * content type * content length - For a document, the server stores, and should be able to produce: * current version @@ -263,6 +262,7 @@ Table of Contents A successful HEAD request SHOULD be responded to like to the equivalent GET request, but omitting the response body. + 5. Response codes Response codes SHOULD be given as defined by [HTTP, section 6] and @@ -287,7 +287,7 @@ Table of Contents existing folder's name at the same level. * 412 for a conditional PUT or DELETE request whose pre-condition fails (see "Versioning" below), - * 507 in case the user's account is over its storage quota, + * 507 in case the account is over its storage quota, * 4xx for all malformed requests (e.g. foreign characters in the path), as well as for all PUT and DELETE requests to folders, @@ -396,8 +396,9 @@ Table of Contents 10. Application-first bearer token issuance To make a remoteStorage server available as 'the remoteStorage of - at ', exactly one link of the following format SHOULD - be added to the WebFinger record [WEBFINGER] of at : + at ', exactly one link of the following format + SHOULD be added to the WebFinger record [WEBFINGER] of at + : { "href": , @@ -415,9 +416,11 @@ Table of Contents presented. If is a URL, the user can supply their credentials - there (how, is out of scope), and allow or reject a request by the - connecting application to obtain a bearer token for a certain list - of access scopes. + for accessing the account (how, is out of scope), and allow or + reject a request by the connecting application to obtain a bearer + token for a certain list of access scopes. Note that an account + will often belong to just one human user, but may also belong to a + group of multiple users (the remoteStorage of at ). If is null, the client will not have a way to obtain an access token, and SHOULD send all requests without Authorization @@ -458,7 +461,6 @@ Table of Contents client_id parameter in favor of relying on the redirect_uri parameter for client identification. - 11. Storage-first bearer token issuance The provider MAY also present a dashboard to the user, where they @@ -481,9 +483,10 @@ Table of Contents Regardless of whether 'access_token' and 'scope' are specified, it SHOULD add a 'remotestorage' field to the URL fragment, with a - value of the form '@' . When the application detects - this parameter, it SHOULD resolve the WebFinger record for at - and extract the and information. + value of the form '@' . When the application detects + this parameter, it SHOULD resolve the WebFinger record for + at and extract the and + information. If no access_token was given, then the application SHOULD also extract the information from WebFinger, and continue @@ -492,10 +495,10 @@ Table of Contents Note that whereas a remoteStorage server SHOULD offer support for the application-first flow with WebFinger and OAuth, it MAY choose not to support the storage-first flow, provided that users will - easily remember their '@' WebFinger address at that + easily remember their '@' WebFinger address at that provider. Applications SHOULD, however, support both flows, which means checking the URL for a 'remotestorage' parameter, but giving - the user a way to specify their WebFinger address if there is none. + the user a way to specify the WebFinger address if there is none. If a server provides an application manifest dashboard, then it SHOULD merge the list of applications there with the list of @@ -560,7 +563,7 @@ motestorage-04", end-point, it will typically redirect the user to this URL, in order to obtain a bearer token. Say the application is hosted on https://drinks-unhosted.5apps.com/ and wants read-write access to - the user's "myfavoritedrinks" scope: + the account's "myfavoritedrinks" scope: GET /oauth/michiel?redirect_uri=https%3A%2F%2Fdrinks-unhosted.5\ apps.com%2F&scope=myfavoritedrinks%3Arw&client_id=https%3A%2F%2Fdrinks-\ @@ -577,7 +580,6 @@ unhosted.5apps.com&response_type=token HTTP/1.1 Allow access? ... - 12.3. OAuth dialog form submission When the user submits the form, the request would look something @@ -624,7 +626,6 @@ XjzzzHNjkd1CJxoQubA1o%3D&token_type=bearer&state= Access-Control-Allow-Headers: Authorization, Content-Length, Co\ ntent-Type, Origin, X-Requested-With, If-Match, If-None-Match - 12.5. Initial PUT An initial PUT may contain an 'If-None-Match: *' header, like this: @@ -804,11 +805,11 @@ charset=UTF-8","Content-Length":106}}} application launch dashboard. A malicious party could link to an application, but specifying a - remoteStorage user address that it controls, thus tricking the user - into using a trusted application to send sensitive data to the wrong - remoteStorage server. To mitigate this, applications SHOULD clearly - display to which remoteStorage server they are sending the user's - data. + remoteStorage account address that it controls, thus tricking the + user into using a trusted application to send sensitive data to the + wrong remoteStorage server. To mitigate this, applications SHOULD + clearly display to which remoteStorage server they are sending the + user's data. Applications could request scopes that the user did not intend to give access to. The user SHOULD always be prompted to carefully @@ -877,7 +878,6 @@ charset=UTF-8","Content-Length":106}}} "Section 4.2: Implicit Grant", in: Hardt, D. (ed), "The OAuth 2.0 Authorization Framework", RFC6749, October 2012. - 17.2. Informative References [HTTPS]