mention group accounts as well as single-user accounts

Author: michielbdejong

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
 

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,15 +147,14 @@ 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]
 
 Internet-Draft              remoteStorage                  December 2014
 
 
-    For a document, the server stores, and should be able to produce:
 
        * current version
        * content type
@@ -198,14 +197,14 @@ 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]
 
 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,14 +247,14 @@ 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]
 
 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
-    <user> at <host>', exactly one link of the following format SHOULD
-    be added to the WebFinger record [WEBFINGER] of <user> at <host>:
+    <account> at <host>', exactly one link of the following format
+    SHOULD be added to the WebFinger record [WEBFINGER] of <account> at
+    <host>:
 
     {
       "href": <storage_root>,
@@ -478,9 +479,11 @@ Internet-Draft              remoteStorage                  December 2014
     presented.
 
     If <auth-dialog> 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 <group> at <host>).
 
     If <auth-dialog> 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,21 +548,22 @@ 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]
 
 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 <user> '@' <host>. When the application detects
-    this parameter, it SHOULD resolve the WebFinger record for <user> at
-    <host> and extract the <storage_root> and <storage_api> information.
+    value of the form <account> '@' <host>. When the application detects
+    this parameter, it SHOULD resolve the WebFinger record for <account>
+    at <host> and extract the <storage_root> and <storage_api>
+    information.
 
     If no access_token was given, then the application SHOULD also
     extract the <auth_endpoint> 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 <user> '@' <host> WebFinger address at that
+    easily remember their <account> '@' <host> 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,17 +647,17 @@ 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]
 
 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
             <title>Allow access?</title>
         ...
 
-
 12.3. OAuth dialog form submission
 
     When the user submits the form, the request would look something
@@ -696,15 +698,15 @@ 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]
 
 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,14 +798,14 @@ 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]
 
 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,14 +848,14 @@ 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]
 
 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,14 +898,14 @@ 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]
 
 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,14 +948,14 @@ 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]
 
 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]