Add WAC-Allow definition and requirements

main/authorization.bs

@@ -3,12 +3,14 @@ Authorization {#authorization}
 
 ## Web Access Control ## {#web-access-control}
 
-Web Access Control (WAC) is a decentralized cross-domain access control
-system. The WAC mechanism is concerned with giving access to agents denoted by
-a [[#webid]] to perform various kinds of read-write operations on resources
-identified by URLs. The Access Control List (ACL) vocabulary is used to
-describe authorization policies about authorized agents with modes of access
-on target resources.
+Web Access Control (<abbr title="Web Access Control">WAC</abbr>) is a
+decentralized cross-domain access control system. The WAC mechanism is
+concerned with giving access to agents denoted by a [[#webid]] to perform
+various kinds of read-write operations on resources identified by URLs. The
+<cite><a href="http://www.w3.org/ns/auth/acl">Access Control List</a></cite>
+(<abbr title="Access Control List">ACL</abbr>) ontology is used to describe
+authorization policies about authorized agents with modes of access on target
+resources.
 
 Servers MUST conform to the Web Access Control specification [[!WAC]].
 
@@ -19,3 +21,47 @@ the HTTP `Link` header with a `rel` value of `acl` [[#acl]].
 In the event that a server can't apply an ACL to a resource, it MUST deny
 access.
 [[Source](https://github.com/solid/specification/issues/130#issue-532777017)]
+
+Servers exposing client's access privileges on a resource URL MUST advertise
+by including the `WAC-Allow` HTTP header in the response of HTTP `HEAD` and
+`GET` requests.
+
+The syntax for the `WAC-Allow` header, using the ABNF syntax defined in
+Section 1.2 of [[!RFC7231]], is:
+
+```
+wac-allow           = "WAC-Allow" ":" OWS #access-param OWS
+access-param        = permission-group OWS "=" OWS quoted-access-modes
+permission-group    = 1*ALPHA
+quoted-access-modes = DQUOTE OWS *1(access-mode *(RWS access-mode)) OWS DQUOTE
+access-mode         = "read" / "write" / "append" / "control"
+```
+
+The `WAC-Allow` HTTP header's field-value is a comma-separated list of
+`access-param`s. `access-param` is a whitespace-separated list of `access
+mode`s granted to a `permission-group`.
+
+This specification defines the following `permission-group`s:
+
+<dl>
+  <dt>`user`</dt>
+  <dd>Permissions granted to the agent requesting the resource.</dd>
+  <dt>`public`</dt>
+  <dd>Permissions granted to the public.</dd>
+</dl>
+
+`access-mode` corresponds to the modes of access as defined in the
+ACL ontology (`acl:Read`, `acl:Write`, `acl:Append`, `acl:Control`).
+
+Clients can discover access privileges on a resource by making an HTTP `HEAD`
+or `GET` request on the target URL, and checking the `WAC-Allow` header value
+for access parameters listing the allowed access modes per permission group.
+
+Clients' parsing algorithm for the `WAC-Allow` header should incorporate error
+handling. When the received message fails to match an allowed pattern, finds 
+unrecognised access parameters or access modes, clients MUST ignore the
+received `WAC-Allow` header-field.
+
+[[Source](https://github.com/solid/specification/issues/171)]
+[[Source](https://github.com/solid/specification/issues/170)]
+[[Source](https://github.com/solid/specification/issues/181)]