= New Features

* A route_csrf plugin has been added.  This plugin allows for more
  control over CSRF protection, since the user can choose where in
  the routing tree to enforce the protection.  Additionally, the
  route_csrf plugin offers better security than the CSRF protection
  used by the csrf plugin (which uses the rack_csrf library).

  The route_csrf plugin defaults to allowing only CSRF tokens
  specific to a given request method and request path, and not
  allowing generic CSRF tokens (though it does offer optional support
  for such tokens).  Both request-specific and generic CSRF tokens
  are designed to never leak the CSRF secret key, making it more
  difficult to forge valid CSRF tokens.  Additionally, the plugin
  offers optional support for accepting rack_csrf tokens, which
  should only be enabled during a short transition period.

  Some differences between the route_csrf plugin and the older
  csrf plugin:

  * route_csrf supports and by default only allows CSRF tokens
    specific to request method and request path, as mentioned
    above.  You can use the require_request_specific_tokens: false
    option to allow generic CSRF tokens.

  * route_csrf does not check the HTTP header by default, it
    only checks the header if the :check_header option is set.
    The :check_header option can be set to true to check both
    the parameter and the header, or set to :only to only check
    the header.

  * route_csrf raises by default for invalid CSRF tokens.  rack_csrf
    returns an empty 403 response in that case.  You can use the
    error_handler plugin to handle the
    Roda::RodaPlugins::RouteCsrf::InvalidToken exceptions, or you
    can use the csrf_failure: :empty_403 option if you would like
    the csrf plugin default behavior.  The plugin also accepts a
    block for configurable failure behavior.

  * route_csrf does not use a middleware, as it is designed to give
    more control. In order to enforce the CSRF protection, you need
    to call check_csrf! in your routing tree at the appropriate
    place.  If you are not sure where to add it, add it to the top
    of the routing tree, after the public or assets routes if you
    are using those plugins:

      route do
        r.public
        r.assets
        check_csrf!

        # ...
      end

    The check_csrf! method accepts an options hash, which can be used
    to override the plugin options on a per-call basis.

  * The csrf_token/csrf_tag methods take an optional path and method
    arguments.  If a path is given, the method defaults to POST, and
    the resulting CSRF token can only be used to submit forms for the
    path and method.  If a path is not given, the resulting CSRF token
    will be generic, but it will only work if the plugin has been
    configured to allow generic CSRF tokens.

  * A csrf_path method is available for easily taking a form action
    string and returning an appropriate path to pass to the csrf_token
    or csrf_tag methods.
