Network.Wai.Middleware.Cors

An implemenation of Cross-Origin resource sharing (CORS) for WAI that aims to be compliant with http://www.w3.org/TR/cors.

Documentation

data CorsResourcePolicy

Constructors

CorsResourcePolicy

Fields

corsOrigins :: !(Maybe ([Origin], Bool))

HTTP origins that are allowed in CORS requests.

A value of Nothing indicates unrestricted cross-origin sharing and results in * as value for the Access-Control-Allow-Origin HTTP response header.

A value other than Nothing is a tuple that consists of a list of origins each with a Boolean flag that indicates if credentials are used to access the resource via CORS.

Origins must be formated as described in RFC6454 (section 6.2). In particular the string * is not a valid origin (but the string null is).

corsMethods :: ![Method]

HTTP methods that are allowed in CORS requests.

corsRequestHeaders :: ![HeaderName]

Field names of HTTP request headers that are allowed in CORS requests. Header names that are included in simpleHeaders, except for content-type, are implicitely included an thus optional in this list.

corsExposedHeaders :: !(Maybe [HeaderName])

Field names of HTTP headers that are exposed on the client.

corsMaxAge :: !(Maybe Int)

Number of seconds that the response may be cached by the client.

corsVaryOrigin :: !Bool

If the resource is shared by multiple origins but Access-Control-Allow-Origin is not set to * this may be set to True.

corsVerboseResponse :: !Bool

If this is True verbose responses with HTTP status 400 (bad request) are returned in case of a failure. Otherwise status 200 is used along with an empty body.

Instances

Eq CorsResourcePolicy

Ord CorsResourcePolicy

Read CorsResourcePolicy

Show CorsResourcePolicy

cors

Arguments

:: (Request -> Maybe CorsResourcePolicy)

A value of Nothing indicates that the resource is not available for CORS

-> Middleware

A Cross-Origin resource sharing (CORS) middleware.

The middleware is given a function that serves as a pattern to decide whether a requested resource is available for CORS. If the match fails with Nothing the request is passed unmodified to the inner application.

The current version of this module does only aim at compliance with the CORS protocol as specified in http://www.w3.org/TR/cors/. It does not implement any enforcement of authorization policies that are possibly implied by the CorsResourcePolicy. It is up to the inner WAI application to enforce such policy and make sure that it is in accordance with the configuration of the cors middleware.

Matches are done as follows: * matches every origin. For all other cases a match succeeds if and only if the ASCII serializations (as described in RCF6454 section 6.2) are equal.

The OPTIONS method may return options for resources that are not actually available. In particular for preflight requests the implementation returns for the HTTP response headers Access-Control-Allow-Headers and Access-Control-Allow-Methods all values specified in the CorsResourcePolicy together with the respective values for simple requests (except content-type). This does not imply that the respective values are actually supported for the Resource by the application. Thus, depending on the application, an actual request may still fail with 404 even if the preflight request supported the usage of the HTTP method with CORS.

The implementation does not distinguish between simple requests and requests that require preflight. The client is free to omit a preflight request or do a preflight request in cases when it wouldn't be required.

For application authors it is strongly recommended to take into account the security considerations in section 6.3 of http://wwww.w3.org/TR/cors.

TODO

• We may consider adding enforcment aspects to this module: we may check if a request respects our origin restrictions and we may check that a CORS request respects the restrictions that we publish in the preflight responses.
• Even though slightly out of scope we may (optionally) check if host header matches the actual host of the resource, since clients using CORS may expect this, since this check is recommended in http://www.w3.org/TR/cors.
• We may consider integrating CORS policy handling more closely with the handling of the source, for instance by integrating with ActionM from scotty.

Utils

isSimple :: Method -> RequestHeaders -> Bool

simpleResponseHeaders :: [HeaderName]

Simple HTTP response headers as defined in http://www.w3.org/TR/cors/

simpleHeaders :: [HeaderName]

simpleContentTypes :: [CI ByteString]

simpleMethods :: [Method]

Simple HTTP methods as defined in http://www.w3.org/TR/cors/