roda 3.9.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39ce926351959abb8a72a7b1c9db596dff7e0e84c26c296db4d2b3c124486356
-  data.tar.gz: 904ab94da8c67bfd2d4acb5246fa0a3049c89778e2fbc9e1701f6f342f39329a
+  metadata.gz: 0fa178463d549cd2a8826a8601eccc793e2a3b5a6bb34293ce8511fb8d357128
+  data.tar.gz: 5b099180432b7efc3bc4839883367a454c876d9a2e6809f533f970e83bd32d0d
 SHA512:
-  metadata.gz: 590cc6b72c9fbb3fc01e389a6c12a5d09cd0db1cf56fe0d821b79e0e3aaf1d91ca7598d25fbdbdc50b25171f79501087599bd334ce079ad435ee51be31988588
-  data.tar.gz: 8bcde66bd4ab812a963ace04db8b026df5d5b5c9d79432de4b5780da80f9548f1dc92681e2fe0bdd1330d20f526cab4cea27b4bd0d54dddedbc8b5a9ec864c77
+  metadata.gz: e7ec971ff829c784c21c9660b7964f79755841501449c6372260510a367482a9dde5131bf6b488eadefdd24403f7a19576c8d1176d8d8306fecc861388fb9f7f
+  data.tar.gz: 7fe25ba12cceccf1b59d9993d4972c0ffb2df2b78b68716f7708ecc58d131bc0858d9b7a1b87ac34bb88a05b57aeb6f0fb68beac648bbdfe2f7c0c3c6933def9

data/CHANGELOG

@@ -1,3 +1,21 @@
+= 3.10.0 (2018-07-18)
+
+* Remove flash key from session if new flash is empty when rotating flash (jeremyevans)
+
+* Speed up RodaRequest initialization by avoiding 1-2 method calls (jeremyevans)
+
+* Add roda/session_middleware (RodaSessionMiddleware), usable as a middleware by any Rack app to use Roda's session support (jeremyevans)
+
+* Add sessions plugin for more secure (encrypted+signed) sessions (jeremyevans)
+
+* Support :json_parser and :json_serializer application options as default implementations for parsing/serializing JSON (jeremyevans)
+
+* Add :handle_result option to middleware plugin for modifying rack result before returning it (jeremyevans)
+
+* Make the flash plugin work correctly when sessions are serialized with JSON (jeremyevans)
+
+* Make Integer in typecast_params handle Numeric input, and require that Numeric input not have fractional parts (jeremyevans) (#146)
+
 = 3.9.0 (2018-06-11)
 
 * Add route_csrf plugin for CSRF protection, offering more control, better security, and request-specific tokens compared to rack_csrf (jeremyevans)

data/README.rdoc

@@ -699,8 +699,15 @@ The following options are respected by the default library or multiple plugins:
 :add_script_name :: Prepend the SCRIPT_NAME for the request to paths.  This is
                     useful if you mount the app as a path under another app.
 :freeze_middleware :: Whether to freeze all middleware when building the rack app.
+:json_parser :: A callable for parsing JSON (+JSON.parse+ in general used by
+                default).
+:json_serializer :: A callable for serializing JSON (+to_json+ in general used
+                    by default).
 :root :: Set the root path for the app.  This defaults to the current working
          directory of the process.
+:sessions_convert_symbols :: This should be set to +true+ if the sessions in use
+                             do not support roundtripping of symbols (for
+                             example, when sessions are serialized via JSON).
 
 There may be other options supported by individual plugins, if so it will be
 mentioned in the documentation for the plugin.
@@ -753,38 +760,51 @@ You can override the default rendering options by passing a hash to the plugin:
       template_opts: {default_encoding: 'UTF-8'} # Default template options
   end
 
-== Sessions
+== Security
+
+Web application security is a very large topic,
+but here are some things you can do with Roda
+to prevent some common web application vulnerabilities.
+
+=== Session Security
 
-By default, Roda doesn't turn on sessions,
-but most users are going to want to turn on session support.
-The simplest way to do this is to use the <tt>Rack::Session::Cookie</tt> middleware
-that comes with Rack:
+By default, Roda doesn't turn on sessions, and if you don't need sessions, you can
+skip this section.  If you do need sessions, Roda offers two recommended ways to
+implement cookie-based sessions.
 
-  require "roda"
+If you do not need any session support in middleware, and only need session support
+in the Roda application, then use the sessions plugin:
 
+  require 'roda'
   class App < Roda
-    use Rack::Session::Cookie, secret: ENV['SECRET']
+    plugin :sessions, secret: ENV['SESSION_SECRET']
   end
 
-== Security
+The +:secret+ option should be a randomly generated string of at least 64 bytes.
 
-Web application security is a very large topic,
-but here are some things you can do with Roda
-to prevent some common web application vulnerabilities.
+If you have middleware that need access to sessions, then use the +RodaSessionMiddleware+
+that ships with Roda:
 
-=== Session Security
+  require 'roda'
+  require 'roda/session_middleware'
+  class App < Roda
+    use RodaSessionMiddleware, secret: ENV['SESSION_SECRET']
+  end
 
-If you are using sessions, you should also always set a session secret,
-using the +:secret+ option as shown above.
-Make sure that this secret is not disclosed,
-because if an attacker knows the +:secret+ value,
-they can inject arbitrary session values.
-In the worst case scenario, this can lead to remote code execution.
-
-Keep in mind that with <tt>Rack::Session::Cookie</tt>,
-the content in the session cookie is not encrypted,
-just signed to prevent tampering.
-This means you should not store any secret data in the session.
+If you need non-cookie based sessions (such as sessions stored in a database), you
+should use an appropriate external middleware.
+  
+It is possible to use other session cookie middleware such as
+<tt>Rack::Session::Cookie</tt>, but other middleware may not have the same security
+features that Roda's session support does.  For example, the session cookies used by
+the <tt>Rack::Session::Cookie</tt> middleware are not encrypted, just signed to
+prevent tampering.  This means you should not store any secret data in the session
+when using <tt>Rack::Session::Cookie</tt>.
+
+For any cookie-based sessions, make sure that the necessary secrets (+:secret+ option)
+are not disclosed to an attacker.  Knowledge of the
+secret(s) can allow an attacker to inject arbitrary session values.  In the case of
+<tt>Rack::Session::Cookie</tt>, that can also lead remote code execution.
 
 === Cross Site Request Forgery (CSRF)
 

data/doc/release_notes/3.10.0.txt

@@ -0,0 +1,132 @@
+= New Features
+
+* A sessions plugin has been added that supports encrypted and
+  signed sessions. This plugin is now the recommended way to
+  implement sessions, replacing the previously recommended
+  Rack::Session::Cookie middleware.
+
+  The sessions plugin encrypts session data using the AES-256-CTR
+  cipher, and then signs the encrypted data with HMAC-SHA-256. By
+  doing this, attackers must be able to forge a valid HMAC before
+  they can try to exploit possible weaknesses in the encryption,
+  such as timing attacks during decryption that are dependent on
+  attacker chosen initialization vectors or ciphertext.
+
+  In addition to encryption and a stronger default signature
+  algorithm compared to Rack::Session::Cookie, the sessions
+  plugin has the following benefits:
+
+  * Built in session expiration enabeld by default, to mitigate
+    possible session replay issues (default: 30 days since session
+    creation, 7 days since last update).
+
+  * Padding by default to minimize information leakage due to
+    differing session data sizes (session data padded to
+    a multiple of 32 bytes by default before encryption).
+
+  * Automatic deflate compression of large sessions before
+    encryption (by default if session data is over 128 bytes).
+
+  * JSON is used for serialization instead of Marshal, preventing
+    remote code execution vulnerabilities if the session secret
+    is disclosed. Note that this means that many ruby types do not
+    round trip in the session, such as Symbol and Time instances.
+    This will probably be the largest barrier to adoption, as you
+    need to make sure your application only uses types that
+    round-trip through JSON before you start using the sessions
+    plugin.
+
+  * A plain hash is used for the session, instead of a hash-like
+    object. One consequence of this is that keys in the session
+    are not automatically converted to strings.
+    Rack::Session::Cookie converts session keys to strings for
+    keys at the top level, but not for keys in subhashes.
+
+  * In general sessions are smaller even if deflate compression is not
+    used, despite requiring 16 bytes for the cipher initialization
+    vector. The main reason for this is that the sessions plugin does
+    not set a session id, since one is not needed for cookie sessions.
+
+  * The sessions plugin requires a :secret option be set that is
+    at least 64 bytes, so that users have to make a determined
+    effort to use weak secrets.
+
+  * The HMAC calculation considers the cookie key, so that if the
+    same session secret is used for multiple applications with
+    different cookie keys, an attacker cannot use the session from
+    one application in a different application.
+
+  The sessions plugin ties into the Roda#session method instead
+  of being a rack middleware.  This makes it about twice as
+  fast as Rack::Session::Cookie if the session is not accessed.
+  If the session is accessed, the sessions plugin is roughly
+  as fast as Rack::Session::Cookie, even though it uses a
+  stronger HMAC and has to encrypt and decrypt the session.
+
+  Because the sessions plugin is not a middleware, it does not
+  offer session support to other middleware, only to the app
+  itself.  If you would like to use the same approach as the
+  sessions plugin uses but would like support for middleware to
+  access the sessions, a roda/session_middleware file has been
+  added. This file contains RodaSessionMiddleware, which is a
+  middleware that can be used by any other Rack app for session
+  support, and which uses a SessionHash class similar to the one used
+  by Rack::Session::Cookie.
+
+  To integrate with other plugins that can optionally use symbols
+  or strings in sessions, the sessions plugin sets the
+  :sessions_convert_symbols application option to true.  Other plugins
+  can check for this application option, and if set, should use
+  strings instead of symbols in the session.
+
+  The sessions plugin should be loaded after the flash plugin if both
+  are used in the same application, so that the flash is rotated
+  correctly in the session.
+
+* The middleware plugin now supports a :handle_result option, which
+  can be any callable object.  If set, this object is called with the
+  environment of the request and the rack response after either the
+  Roda app or next middleware returns the rack response.  The rack
+  response can be modified by the callable object, and the response
+  (after possible modification) will be returned to the previous
+  middleware.  Example:
+
+    plugin :middleware, :handle_result=>(proc do |env, res|
+      res[1]['MyHeader'] = 'HeaderValue'
+    end)
+
+* The :json_parser and :json_serializer application options are now
+  supported.  If set, these options are used for parsing and
+  serializing JSON instead of the default of JSON.parse and .to_json.
+
+= Other Improvements
+
+* RodaRequest initialization is now faster by avoiding 1-2 method
+  calls.
+
+* typecast_params.Integer in the typecast_params plugin now handles
+  numeric input as long the numeric input does not have fractional
+  parts.  This makes it more usable when handling JSON input.
+
+* If the flash is empty after the request is processed, the flash
+  session key is removed from the session instead of being left as
+  an empty hash.  If addition to making the session smaller, this
+  makes the session appear empty if there are no other keys in the
+  session, which works better with the sessions plugin as empty
+  sessions will remove the session cookie completely.
+
+= Backwards Compatibility
+
+* The flash plugin now uses '_flash' instead of :_flash as the session
+  key.  When using session middleware that uses
+  Rack::Session::Abstract::SessionHash to store the session (e.g.
+  Rack::Session::Cookie), session keys are converted internally to
+  strings, so this change will not affect you unless you are using
+  alternative session support.  Even if your session does treat
+  :_flash different than '_flash' in keys, the plugin will still work
+  because it will try :_flash if there is no value for '_flash'.  This
+  change was made to support the sessions plugin, which doesn't
+  convert keys to strings.
+
+* This DEFAULT_PARSER and DEFAULT_SERIALIZER constants from the
+  the json_parser and json plugins have been removed.

data/lib/roda.rb

@@ -228,7 +228,7 @@ class Roda
         # Add a middleware to use for the rack application.  Must be
         # called before calling #route to have an effect. Example:
         #
-        #   Roda.use Rack::Session::Cookie, secret: ENV['secret']
+        #   Roda.use Rack::ShowExceptions
         def use(*args, &block)
           @middleware << [args, block].freeze
           build_rack_app
@@ -372,7 +372,7 @@ class Roda
           @scope = scope
           @captures = []
           @remaining_path = _remaining_path(env)
-          super(env)
+          @env = env
         end
 
         # Handle match block return values.  By default, if a string is given
@@ -670,7 +670,7 @@ class Roda
         # The session for the current request.  Raises a RodaError if
         # a session handler has not been loaded.
         def session
-          @env['rack.session'] || raise(RodaError, "You're missing a session handler. You can get started by adding use Rack::Session::Cookie")
+          @env['rack.session'] || raise(RodaError, "You're missing a session handler, try using the sessions plugin.")
         end
 
         private

data/lib/roda/plugins/assets.rb

@@ -368,7 +368,7 @@ class Roda
 
         if opts[:precompiled] && !opts[:compiled] && ::File.exist?(opts[:precompiled])
           require 'json'
-          opts[:compiled] = ::JSON.parse(::File.read(opts[:precompiled]))
+          opts[:compiled] = (app.opts[:json_parser] || ::JSON.method(:parse)).call(::File.read(opts[:precompiled]))
         end
 
         if opts[:early_hints]
@@ -451,7 +451,7 @@ class Roda
           if assets_opts[:precompiled]
             require 'json'
             ::FileUtils.mkdir_p(File.dirname(assets_opts[:precompiled]))
-            ::File.open(assets_opts[:precompiled], 'wb'){|f| f.write(assets_opts[:compiled].to_json)}
+            ::File.open(assets_opts[:precompiled], 'wb'){|f| f.write((opts[:json_serializer] || :to_json.to_proc).call(assets_opts[:compiled]))}
           end
 
           assets_opts[:compiled]

data/lib/roda/plugins/flash.rb

@@ -91,7 +91,8 @@ class Roda
         # Access the flash hash for the current request, loading
         # it from the session if it is not already loaded.
         def flash
-          @_flash ||= FlashHash.new(session[:_flash])
+          # :_flash to support transparent upgrades from previous key
+          @_flash ||= FlashHash.new(session['_flash'] || (session['_flash'] = session.delete(:_flash)))
         end
 
         # If the routing doesn't raise an error, rotate the flash
@@ -100,7 +101,12 @@ class Roda
           res = super
 
           if f = @_flash
-            session[:_flash] = f.next
+            f = f.next
+            if f.empty?
+              session.delete('_flash')
+            else
+              session['_flash'] = f
+            end
           end
 
           res

data/lib/roda/plugins/json.rb

@@ -53,8 +53,6 @@ class Roda
     #
     #   plugin :json, content_type: 'application/xml'
     module Json
-      DEFAULT_SERIALIZER = :to_json.to_proc
-
       # Set the classes to automatically convert to JSON, and the serializer to use.
       def self.configure(app, opts=OPTS)
         classes = opts[:classes] || [Array, Hash]
@@ -63,7 +61,7 @@ class Roda
         app.opts[:json_result_classes].uniq!
         app.opts[:json_result_classes].freeze
 
-        app.opts[:json_result_serializer] = opts[:serializer] || app.opts[:json_result_serializer] || DEFAULT_SERIALIZER
+        app.opts[:json_result_serializer] = opts[:serializer] || app.opts[:json_result_serializer] || app.opts[:json_serializer] || :to_json.to_proc
 
         app.opts[:json_result_include_request] = opts[:include_request] if opts.has_key?(:include_request)
 

data/lib/roda/plugins/json_parser.rb

@@ -12,7 +12,6 @@ class Roda
     # header for the request includes "json".
     module JsonParser
       DEFAULT_ERROR_HANDLER = proc{|r| r.halt [400, {}, []]}
-      DEFAULT_PARSER = JSON.method(:parse)
 
       # Handle options for the json_parser plugin:
       # :error_handler :: A proc to call if an exception is raised when
@@ -32,7 +31,7 @@ class Roda
       #          only wrap values that are not already hashes.
       def self.configure(app, opts=OPTS)
         app.opts[:json_parser_error_handler] = opts[:error_handler] || app.opts[:json_parser_error_handler] || DEFAULT_ERROR_HANDLER
-        app.opts[:json_parser_parser] = opts[:parser] || app.opts[:json_parser_parser] || DEFAULT_PARSER
+        app.opts[:json_parser_parser] = opts[:parser] || app.opts[:json_parser_parser] || app.opts[:json_parser] || JSON.method(:parse)
         app.opts[:json_parser_include_request] = opts[:include_request] if opts.has_key?(:include_request)
 
         case opts[:wrap]

data/lib/roda/plugins/middleware.rb

@@ -69,10 +69,15 @@ class Roda
       #             application that the current request is a middleware request.
       #             You should only need to override this if you are using multiple
       #             roda middleware in the same application.
+      # :handle_result :: Callable object that will be called with request environment
+      #                   and rack response for all requests passing through the middleware,
+      #                   after either the middleware or next app handles the request
+      #                   and returns a response.
       def self.configure(app, opts={}, &block)
         app.opts[:middleware_env_var] = opts[:env_var] if opts.has_key?(:env_var)
         app.opts[:middleware_env_var] ||= 'roda.forward_next'
         app.opts[:middleware_configure] = block if block
+        app.opts[:middleware_handle_result] = opts[:handle_result]
       end
 
       # Forwarder instances are what is actually used as middleware.
@@ -102,10 +107,14 @@ class Roda
           end
 
           if call_next
-            @app.call(env)
-          else
-            res
+            res = @app.call(env)
           end
+
+          if handle_result = @mid.opts[:middleware_handle_result]
+            handle_result.call(env, res)
+          end
+
+          res
         end
       end
 

data/lib/roda/plugins/route_csrf.rb

@@ -26,9 +26,11 @@ class Roda
     # sessions, so if the attacker has the ability to read cookie data
     # and you are using Rack::Session::Cookie, it will still be possible
     # for an attacker to generate valid CSRF tokens specific to arbitrary
-    # request method and request path.
+    # request method and request path.  Roda's session plugin uses
+    # encrypted sessions and therefore is safe even if the attacker can
+    # read cookie data.
     #
-    # # Usage
+    # == Usage
     #
     # It is recommended to use the plugin defaults, loading the
     # plugin with no options:
@@ -37,39 +39,39 @@ class Roda
     #
     # This plugin supports the following options:
     #
-    #   :field :: Form input parameter name for CSRF token (default: '_csrf')
-    #   :header :: HTTP header name for CSRF token (default: 'X-CSRF-Token')
-    #   :key :: Session key for CSRF secret (default: '_roda_csrf_secret')
-    #   :require_request_specific_tokens :: Whether request-specific tokens are required (default: true).
-    #                                       A false value will allow tokens that are not request-specific
-    #                                       to also work.  You should only set this to false if it is
-    #                                       impossible to use request-specific tokens.  If you must
-    #                                       use non-request-specific tokens in certain cases, it is best
-    #                                       to leave this option true by default, and override it on a
-    #                                       per call basis in those specific cases.
-    #   :csrf_failure :: The action to taken if a request fails the CSRF check (default: :raise).  Options:
-    #                    :raise :: raise a Roda::RodaPlugins::RouteCsrf::InvalidToken exception
-    #                    :empty_403 :: return a blank 403 page (rack_csrf's default behavior)
-    #                    :clear_session :: Clear the current session
-    #                    Proc :: Treated as a routing block, called with request object
-    #   :check_header :: Whether the HTTP header should be checked for the token value (default: false).
-    #                    If true, checks the HTTP header after checking for the form input parameter.
-    #                    If :only, only checks the HTTP header and doesn't check the form input parameter.
-    #   :check_request_methods :: Which request methods require CSRF protection
-    #                             (default: <tt>['POST', 'DELETE', 'PATCH', 'PUT']</tt>)
-    #   :upgrade_from_rack_csrf_key :: If provided, the session key that should be checked for the
-    #                                  rack_csrf raw token.  If the session key is present, the value
-    #                                  will be checked against the submitted token, and if it matches,
-    #                                  the CSRF check will be passed.  Should only be set temporarily
-    #                                  if upgrading from using rack_csrf to the route_csrf plugin, and
-    #                                  should be removed as soon as you are OK with CSRF forms generated
-    #                                  before the upgrade not longer being usable. The default rack_csrf
-    #                                  key is <tt>'csrf.token'</tt>.
+    # :field :: Form input parameter name for CSRF token (default: '_csrf')
+    # :header :: HTTP header name for CSRF token (default: 'X-CSRF-Token')
+    # :key :: Session key for CSRF secret (default: '_roda_csrf_secret')
+    # :require_request_specific_tokens :: Whether request-specific tokens are required (default: true).
+    #                                     A false value will allow tokens that are not request-specific
+    #                                     to also work.  You should only set this to false if it is
+    #                                     impossible to use request-specific tokens.  If you must
+    #                                     use non-request-specific tokens in certain cases, it is best
+    #                                     to leave this option true by default, and override it on a
+    #                                     per call basis in those specific cases.
+    # :csrf_failure :: The action to taken if a request fails the CSRF check (default: :raise).  Options:
+    #                  :raise :: raise a Roda::RodaPlugins::RouteCsrf::InvalidToken exception
+    #                  :empty_403 :: return a blank 403 page (rack_csrf's default behavior)
+    #                  :clear_session :: Clear the current session
+    #                  Proc :: Treated as a routing block, called with request object
+    # :check_header :: Whether the HTTP header should be checked for the token value (default: false).
+    #                  If true, checks the HTTP header after checking for the form input parameter.
+    #                  If :only, only checks the HTTP header and doesn't check the form input parameter.
+    # :check_request_methods :: Which request methods require CSRF protection
+    #                           (default: <tt>['POST', 'DELETE', 'PATCH', 'PUT']</tt>)
+    # :upgrade_from_rack_csrf_key :: If provided, the session key that should be checked for the
+    #                                rack_csrf raw token.  If the session key is present, the value
+    #                                will be checked against the submitted token, and if it matches,
+    #                                the CSRF check will be passed.  Should only be set temporarily
+    #                                if upgrading from using rack_csrf to the route_csrf plugin, and
+    #                                should be removed as soon as you are OK with CSRF forms generated
+    #                                before the upgrade not longer being usable. The default rack_csrf
+    #                                key is <tt>'csrf.token'</tt>.
     #
     # The plugin also supports a block, in which case the block will be used
     # as the value of the :csrf_failure option.
     #
-    # # Methods
+    # == Methods
     #
     # This adds the following instance methods:
     #
@@ -116,7 +118,7 @@ class Roda
     #                 will not work unless you set the :require_request_specific_tokens option to
     #                 false, which is a bad idea from a security standpoint.
     #
-    # # Token Cryptography
+    # == Token Cryptography
     #
     # route_csrf uses HMAC-SHA-256 to generate all CSRF tokens.  It generates a random 32-byte secret,
     # which is stored base64 encoded in the session.  For each CSRF token, it generates 31 bytes