Add CORS section

main/index.bs

@@ -5,6 +5,7 @@ Level: 1
 Status: w3c/ED
 Group: Solid Community Group
 URL: https://solid.github.io/specification/
+Markup Shorthands: markdown yes
 Max ToC Depth: 2
 Editor: Your Name, Your Company http://example.com/your-company, [email protected], http://example.com/your-personal-website
 Abstract:

main/introduction.bs

@@ -12,4 +12,8 @@ Issue: Explain that this specification is not documentation;
 
 ## Definitions ## {#definitions}
 
-Issue: Write Definitions section.
+A <dfn export>data pod</dfn> is a place for storing documents,
+with mechanisms for controlling who can access what.
+
+A <dfn export>Solid app</dfn> is an application
+that reads or writes data from one or more [=data pods=].

main/resource-access.bs

@@ -41,6 +41,94 @@ A Solid data pod MUST conform to the Web Access Control specification [[!WAC]].
 
 ## Cross-Origin Resource Sharing ## {#cors}
 
-Issue: Write Cross-Origin Resource Sharing section.
-
-A Solid data pod MUST conform to the CORS specification [[!FETCH]].
+### Background and Need ### {#cors-need}
+<em>This section is non-normative.</em>
+
+[=Solid apps=] typically access data from multiple sources.
+However,
+Web browsers by default prevent apps that run on one origin
+from accessing data on other origins.
+This cross-origin protection is a security mechanism
+that ensures malicious websites cannot simply read
+your profile or banking details from other websites.
+However, this reasonable default poses a problem
+even for benevolent Solid apps,
+which might have good reasons to access data from different places.
+For instance,
+a Solid app at `https://app.example/`
+would be prevented from accessing data on
+`https://alice-data-pod.example/` or `https://bob-data-pod.example/`,
+even when Alice and Bob have given the user of the app
+their permission to see some of their data.
+
+For cases where the other origins
+have their own access protection mechanism—
+[like within Solid](#wac)—
+the browser's built-in cross-origin protection
+is actually an obstacle rather than a feature.
+After all,
+[=data pods=] already ensure through access control
+that certain documents can only be accessed by specific people.
+Preventively blocking apps from different origins
+thus introduces an unnecessary barrier.
+
+Fortunately,
+Web servers can indicate to the browser
+that certain documents do not require cross-origin protection.
+This mechanism to selectively disable that protection
+is called *Cross-Origin Resource Sharing* or *CORS* [[FETCH]].
+By responding to browser requests
+with a specific combination of HTTP headers,
+servers can indicate which actions are allowed for a given resource.
+For a Solid data pod,
+the goal is to allow *all* actions on the CORS level,
+such that the deeper [access control layer](#wac)
+can exert full control over the app's allowed permissions.
+The next section describes how to achieve this
+through the right HTTP header configuration.
+
+### Required server-side implementation ### {#cors-server}
+
+A [=data pod=] MUST implement the CORS protocol [[!FETCH]]
+such that, to the extent possible,
+no request to it or response from it is blocked by the browser.
+If the data pod wishes to block access to a resource,
+this MUST NOT happen via CORS
+but MUST instead be communicated to the Solid app in the browser
+through HTTP status codes such as `401`, `403`, or `404` [[!RFC7231]].
+Furthermore,
+all response headers MUST be exposed to the Solid app.
+
+Note: Since the CORS protocol is part of a Living Standard,
+it should still be considered in evolution.
+Changes to the CORS protocol might thus happen at any point,
+which might necessitate changes to server implementations
+for continued prevention of undesired blocking.
+A [proposal](https://github.com/whatwg/fetch/issues/878) to mitigate this
+has been suggested.
+
+Concretely,
+whenever a data pod receives an HTTP request
+containing an `Origin` header [[!RFC6454]],
+the server MUST respond with the appropriate `Access-Control-*` headers
+as specified in the CORS protocol [[!FETCH]].
+A data pod MUST also support the HTTP `OPTIONS` method [[!RFC7231]]
+such that it can respond appropriately to CORS preflight requests.
+
+Careful attention is warranted,
+especially because of the many edge cases.
+For instance,
+data pods SHOULD enumerate all response headers under `Access-Control-Expose-Headers`
+because there are cases (credentials mode set to `include`)
+where using `*` as a value does not work.
+As another example,
+data pods SHOULD always explicitly list `Accept` under `Access-Control-Allow-Headers`.
+This is recommended because,
+despite `Accept` being safelisted,
+values longer than 128 characters are blocked by default,
+and the number of available RDF formats that Solid apps might use
+could easily lead to longer value lengths.
+
+Note: Under the current CORS protocol,
+the correct HTTP response headers depend on the specifics of the request
+and thus cannot be pre-generated.

main/security.bs

@@ -3,6 +3,33 @@ Security Considerations {#security}
 
 Issue: Write Security Considerations section.
 
+Solid data pods [disable all cross-origin protections](#cors-server) in browsers
+because resource access is governed explicitly by [Web Access Control](#wac).
+As such,
+data pods MUST NOT rely on cross-origin protection
+for shielding access to resources.
+While this ensures that unauthorized resource access will not occur,
+additional security measures MAY be needed
+to prevent metadata in error responses from leaking.
+For instance,
+a malicious app could probe multiple servers
+to check whether the response status code is `401` or `403`,
+or could try to access an error page
+from an intranet server within the user agent's private network
+to extract company names or other data.
+To mitigate this,
+when a request from an untrusted the `Origin` arrives,
+the data pod MAY set the status code of error responses to `404`
+and/or anonymize or censor their contents.
+
+A data pod MUST NOT assume that the user agent is a regular Web browser,
+even when requests contain familiar values
+in headers such as `User-Agent` or `Origin`.
+
+
 ## Privacy Considerations ## {#privacy}
 
 Issue: Write Privacy Considerations section.
+
+In order to prevent leakage of non-resource data,
+error responses SHOULD NOT contain identifiable information.