NAME
    Plack::Middleware::CrossOrigin - Adds headers to allow Cross-Origin
    Resource Sharing

SYNOPSIS
        # Allow any WebDAV or standard HTTP request from any location.
        builder {
            enable 'CrossOrigin', origins => '*';
            $app;
        };

        # Allow GET and POST requests from any location, cache results for 30 days.
        builder {
            enable 'CrossOrigin',
                origins => '*', methods => ['GET', 'POST'], max_age => 60*60*24*30;
            $app;
        };

DESCRIPTION
    Adds Cross Origin Request Sharing headers used by modern browsers to
    allow "XMLHttpRequest" to work across domains. This module will also
    help protect against CSRF attacks in some browsers.

    This module attempts to fully conform to the CORS spec, while allowing
    additional flexibility in the values specified for the of the headers.

    The module also ensures that the response contains a "Vary: Origin"
    header to avoid potential issues with caches.

CORS REQUESTS IN BRIEF
    There are two types of CORS requests. Simple requests, and preflighted
    requests.

  Simple Requests
    A simple request is one that could be generated by a standard HTML form.
    Either a "GET" or "POST" request, with no additional headers. For these
    requests, the server processes the request as normal, and attaches the
    correct CORS headers in the response. The browser then decides based on
    those headers whether to allow the client script access to the response.

  Preflighted Requests
    If additional headers are specified, or a method other than "GET" or
    "POST" is used, the request must be preflighted. This means that the
    browser will first send a special request to the server to check if
    access is allowed. If the server allows it by responding with the
    correct headers, the actual request is then performed.

CSRF Protection
    Some browsers will also provide same headers with cross domain "POST"
    requests from HTML forms. These requests will also be checked against
    the allowed origins and rejected before they reach the rest of your
    Plack application.

CONFIGURATION
    origins A list of allowed origins. Origins should be formatted as a URL
            scheme and host, with no path information.
            ("http://www.example.com") '"*"' can be specified to allow
            access from any location. Wildcards ("*") can also be included
            in in the host to match any part of a host name (e.g.
            "https://*.example.com"). At least one origin must bust be
            specified for this middleware to have any effect. This will be
            matched against the "Origin" request header, and will control
            the "Access-Control-Allow-Origin" response header. If the origin
            does not match, the request is aborted.

    headers A list of allowed request headers. '"*"' can be specified to
            allow any headers. Controls the "Access-Control-Allow-Headers"
            response header. Includes a set of headers by default to
            simplify working with WebDAV and AJAX frameworks:

            *   "Cache-Control"

            *   "Depth"

            *   "If-Modified-Since"

            *   "User-Agent"

            *   "X-File-Name"

            *   "X-File-Size"

            *   "X-Prototype-Version"

            *   "X-Requested-With"

    methods A list of allowed methods. '"*"' can be specified to allow any
            methods. Controls the "Access-Control-Allow-Methods" response
            header. Defaults to all of the standard HTTP and WebDAV methods.

    max_age The max length in seconds to cache the response data for.
            Controls the "Access-Control-Max-Age" response header. If not
            specified, the web browser will decide how long to use.

    expose_headers
            A list of allowed headers to expose to the client. '"*"' can be
            specified to allow the browser to see all of the response
            headers. Controls the "Access-Control-Expose-Headers" response
            header.

    credentials
            Whether the resource will be allowed with user credentials
            (cookies, HTTP authentication, and client-side SSL certificates)
            supplied. Controls the "Access-Control-Allow-Credentials"
            response header.

    continue_on_failure
            Normally, simple requests with an Origin that hasn't been
            allowed will be stopped before they continue to the main app. If
            this option is set, the request will be allowed to continue, but
            no CORS headers will be added to the response. This matches how
            non-allowed requests would be handled if this module was not
            used at all.

            This disables the CSRF protection and is not recommended. It
            could be needed for applications that need to allow cross-origin
            HTML form "POST"s without whitelisting domains.

BROWSER SUPPORT
    Different browsers have different levels of support for CORS headers.

    Gecko (Firefox, Seamonkey)
            Initially supported in Gecko 1.9.1 (Firefox 3.5). Supports the
            complete CORS spec for "XMLHttpRequest"s.

            Does not yet provide the "Origin" header for CSRF protection
            (Bugzilla #446344
            <https://bugzilla.mozilla.org/show_bug.cgi?id=446344>).

    WebKit (Safari, Google Chrome)
            Initially supported in Safari 4 and Chrome 3. Supports the
            complete CORS spec.

            The "expose_headers" feature has been supported since WebKit
            v535.18 (Safari 6, Chrome 18). Preflighted requests were buggy
            prior to WebKit v534.19 (Safari 5.1, Chrome 11), but this module
            uses a workaround where possible (using the "Referer" header).

            Also provides the "Origin" header for CSRF protection starting
            with WebKit v528.5 (Chrome 2, Safari 4).

    Internet Explorer
            Initially supported in IE8. Not supported with the standard
            "XMLHttpRequest" object. A separate object, "XDomainRequest",
            must be used. Only "GET" and "POST" methods are allowed. No
            extra headers can be added to the request. Neither the status
            code or any headers aside from "Content-Type" can be retrieved
            from the response.

            IE10 supports CORS via the standard "XMLHttpRequest" object.

    Opera   Opera and Opera Mobile support CORS since version 12.

SEE ALSO
  CORS Resources
    *   W3C Spec for Cross-Origin Resource Sharing
        <http://www.w3.org/TR/cors/>

    *   W3C Spec for Cross-Origin Resource Sharing - Implementation
        Considerations <http://www.w3.org/TR/cors/#resource-implementation>

    *   Mozilla Developer Center - HTTP Access Control
        <https://developer.mozilla.org/En/HTTP_access_control>

    *   Mozilla Developer Center - Server-Side Access Control
        <https://developer.mozilla.org/En/Server-Side_Access_Control>

    *   Cross browser examples of using CORS requests
        <http://www.nczonline.net/blog/2010/05/25/cross-domain-ajax-with-cro
        ss-origin-resource-sharing/>

    *   MSDN - XDomainRequest Object
        <http://msdn.microsoft.com/en-us/library/cc288060%28v=vs.85%29.aspx>

    *   XDomainRequest - Restrictions, Limitations and Workarounds
        <http://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainreque
        st-restrictions-limitations-and-workarounds.aspx>

    *   Wikipedia - Cross-Origin Resource Sharing
        <http://en.wikipedia.org/wiki/Cross-Origin_Resource_Sharing>

    *   CORS advocacy <http://enable-cors.org/>

  CSRF Resources
    *   Wikipedia - Cross-site request forgery
        <http://en.wikipedia.org/wiki/Cross-site_request_forgery>

    *   Stanford Web Security Research - Cross-Site Request Forgery
        <http://seclab.stanford.edu/websec/csrf/>

    *   WebKit Bugzilla - Add origin header to POST requests
        <https://bugs.webkit.org/show_bug.cgi?id=20792>

    *   Mozilla Bugzilla - Implement Origin header CSRF mitigation
        <https://bugzilla.mozilla.org/show_bug.cgi?id=446344>

  Related Technologies
    *   Cross-domain policy file for Flash
        <http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.h
        tml>

    *   Wikipedia - JSONP <http://en.wikipedia.org/wiki/JSONP>

AUTHOR
    Graham Knop <haarg@haarg.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Graham Knop.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

AUTHOR
    haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>

  CONTRIBUTORS
    None so far.

COPYRIGHT
    Copyright (c) 2011 the Plack::Middleware::CrossOrigin "AUTHOR" and
    "CONTRIBUTORS" as listed above.

LICENSE
    This library is free software and may be distributed under the same
    terms as perl itself.

