Provided by: libplack-middleware-crossorigin-perl_0.012-1_all bug

NAME

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

VERSION

       version 0.012

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.

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.  Must 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/>

       •   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-cross-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/xdomainrequest-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.html>

       •   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.