roda 3.79.0 → 3.80.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e77e7eba739ca8bf0afe44555c8af8c9188f4ce8668310aad110a2afc638701
-  data.tar.gz: 19db55450dfe15e7aa4f678d7556ec427e52bcad421a096791d47a5a3fe128b4
+  metadata.gz: 0cebe935d536e1f903b212075108ba9cbcade4aa2e8d2abf1c5e0d6e6f539ce8
+  data.tar.gz: 9b0c576aaa36c5a05596c1bc1bec23d3ab0f37c56dc72342bfa962b10442928f
 SHA512:
-  metadata.gz: f504398b08e35ca42b765afca4357d750836ce5d7e3e7ec9ba73b061dde57fd2bbd3fa5d7752b9e6995739fac8a8718b0a8a71d70432ec14b65c95e13dadeb29
-  data.tar.gz: ceb20219c23d4e44d006c5fe177fff3ef2cacb77ec75e109b92c03d12f0e9cf434459759d007df96becfa0e426c89f4f8f9517c00c579135cfbb0e613852a0a1
+  metadata.gz: 0e83d0fe8e1f70bb196ea5f285f7a00590ab1669e4b1d686f859d1e5c65a8e760d1320b345306740d00c7d063f0f6bada1af88433b3b04c6b429f439bb7e2521
+  data.tar.gz: e9b0ffd5b5fb7e976a971f11fbed4f0beb35868dcb7aa70c41c005046a9053cb6c62caf29f669c02cd53e67cd5db51a28076f058824c90a1c1b917a9b7f0f4fb

data/CHANGELOG

@@ -1,3 +1,7 @@
+= 3.80.0 (2024-05-10)
+
+* Support :namespace option in hmac_paths plugin, allowing for easy per-user/per-group HMAC paths (jeremyevans)
+
 = 3.79.0 (2024-04-12)
 
 * Do not update template mtime when there is an error reloading templates in the render plugin (jeremyevans)

data/doc/release_notes/3.80.0.txt

@@ -0,0 +1,31 @@
+= New Features
+
+* The hmac_paths plugin now supports a :namespace option for both hmac_path and
+  r.hmac_path.  The :namespace option makes the generated HMAC values unique
+  per namespace, allowing easy use of per user/group HMAC paths. This can
+  be useful if the same path will show different information to different
+  users/groups, and you want to prevent path enumeration for each user/group
+  (not allow paths enumerated by one user/group to be valid for a different
+  user/group). Example:
+
+    hmac_path('/widget/1', namespace: '1')
+    # => "/3793ac2a72ea399c40cbd63f154d19f0fe34cdf8d347772134c506a0b756d590/n/widget/1"
+
+    hmac_path('/widget/1', namespace: '2')
+    # => "/0e1e748860d4fd17fe9b7c8259b1e26996502c38e465f802c2c9a0a13000087c/n/widget/1"
+  
+  The HMAC path created with namespace: '1' will only be valid when calling
+  r.hmac_path with namespace: '1' (similar for namespace: '2').
+
+  It is expected that the most common use of the :namespace option is to
+  reference session values, so the value of each path depends on the logged in
+  user.  You can use the :namespace_session_key plugin option to set the
+  default namespace for both hmac_path and r.hmac_path:
+
+    plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes',
+           namespace_session_key: 'account_id'
+
+  This will use <tt>session['account_id']</tt> (converted to a string) as the namespace
+  for both hmac_path and r.hmac_path, unless a specific :namespace option is
+  given, making it simple to implement per user/group HMAC paths across an
+  application.

data/lib/roda/plugins/hmac_paths.rb

@@ -112,13 +112,43 @@ class Roda
     # this for POST requests (or other HTTP verbs that can have request bodies), use +r.GET+
     # instead of +r.params+ to specifically check query string parameters.
     #
-    # You can use +:root+, +:method+, and +:params+ at the same time:
+    # The :namespace option, if provided, should be a string, and it modifies the generated HMACs
+    # to only match those in the same namespace.  This can be used to provide different paths to
+    # different users or groups of users.
     #
-    #   hmac_path('/1', root: '/widget', method: :get, params: {foo: 'bar'})
-    #   # => "/widget/9169af1b8f40c62a1c2bb15b1b377c65bda681b8efded0e613a4176387468c15/mp/1?foo=bar"
+    #   hmac_path('/widget/1', namespace: '1')
+    #   # => "/3793ac2a72ea399c40cbd63f154d19f0fe34cdf8d347772134c506a0b756d590/n/widget/1"
+    #
+    #   hmac_path('/widget/1', namespace: '2')
+    #   # => "/0e1e748860d4fd17fe9b7c8259b1e26996502c38e465f802c2c9a0a13000087c/n/widget/1"
+    #
+    # The +r.hmac_path+ method accepts a :namespace option, and if a :namespace option is
+    # provided, it will only match an hmac path if the namespace given matches the one used
+    # when the hmac path was created.
+    #
+    #   r.hmac_path(namespace: '1'){}
+    #   # will match "/3793ac2a72ea399c40cbd63f154d19f0fe34cdf8d347772134c506a0b756d590/n/widget/1"
+    #   # will not match "/0e1e748860d4fd17fe9b7c8259b1e26996502c38e465f802c2c9a0a13000087c/n/widget/1"
+    #
+    # The most common use of the :namespace option is to reference session values, so the value of
+    # each path depends on the logged in user.  You can use the +:namespace_session_key+ plugin
+    # option to set the default namespace for both +hmac_path+ and +r.hmac_path+:
+    #
+    #   plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes',
+    #                       namespace_session_key: 'account_id'
+    #
+    # This will use <tt>session['account_id']</tt> as the default namespace for both +hmac_path+
+    # and +r.hmac_path+ (if the session value is not nil, it is converted to a string using +to_s+).
+    # You can override the default namespace by passing a +:namespace+ option when calling +hmac_path+
+    # and +r.hmac_path+.
+    #
+    # You can use +:root+, +:method+, +:params+, and +:namespace+ at the same time:
+    #
+    #   hmac_path('/1', root: '/widget', method: :get, params: {foo: 'bar'}, namespace: '1')
+    #   # => "/widget/c14c78a81d34d766cf334a3ddbb7a6b231bc2092ef50a77ded0028586027b14e/mpn/1?foo=bar"
     #
     # This gives you a path only valid for a GET request with a root of <tt>/widget</tt> and
-    # a query string of <tt>foo=bar</tt>.
+    # a query string of <tt>foo=bar</tt>, using namespace +1+.
     #
     # To handle secret rotation, you can provide an +:old_secret+ option when loading the
     # plugin.
@@ -128,6 +158,43 @@ class Roda
     #
     # This will use +:secret+ for constructing new paths, but will respect paths generated by
     # +:old_secret+.
+    #
+    # = HMAC Construction
+    #
+    # This describes the internals for how HMACs are constructed based on the options provided
+    # to +hmac_path+.  In the examples below:
+    #
+    # * +HMAC+ is the raw HMAC-SHA256 output (first argument is secret, second is data)
+    # * +HMAC_hex+ is the hexidecimal version of +HMAC+
+    # * +secret+ is the plugin :secret option
+    #
+    # The +:secret+ plugin option is never used directly as the HMAC secret.  All HMACs are
+    # generated with a root-specific secret.  The root will be the empty if no +:root+ option
+    # is given.  The hmac path flags are always included in the hmac calculation, prepended to the
+    # path:
+    #
+    #  r.hmac_path('/1')
+    #  HMAC_hex(HMAC_hex(secret, ''), '/0/1')
+    # 
+    #  r.hmac_path('/1', root: '/2')
+    #  HMAC_hex(HMAC_hex(secret, '/2'), '/0/1')
+    #
+    # The +:method+ option uses an uppercase version of the method prepended to the path. This
+    # cannot conflict with the path itself, since paths must start with a slash.
+    #
+    #  r.hmac_path('/1', method: :get)
+    #  HMAC_hex(HMAC_hex(secret, ''), 'GET:/m/1')
+    # 
+    # The +:params+ option includes the query string for the params in the HMAC:
+    #
+    #  r.hmac_path('/1', params: {k: 2})
+    #  HMAC_hex(HMAC_hex(secret, ''), '/p/1?k=2')
+    #
+    # If a +:namespace+ option is provided, the original secret used before the +:root+ option is
+    # an HMAC of the +:secret+ plugin option and the given namespace.
+    # 
+    #  r.hmac_path('/1', namespace: '2')
+    #  HMAC_hex(HMAC_hex(HMAC(secret, '2'), ''), '/n/1')
     module HmacPaths
       def self.configure(app, opts=OPTS)
         hmac_secret = opts[:secret]
@@ -143,6 +210,10 @@ class Roda
 
         app.opts[:hmac_paths_secret] = hmac_secret
         app.opts[:hmac_paths_old_secret] = hmac_old_secret
+
+        if opts[:namespace_session_key]
+          app.opts[:hmac_paths_namespace_session_key] = opts[:namespace_session_key]
+        end
       end
 
       module InstanceMethods
@@ -152,6 +223,9 @@ class Roda
         # valid paths.  The given path should be a string starting with +/+.  Options:
         #
         # :method :: Limits the returned path to only be valid for the given request method.
+        # :namespace :: Make the HMAC value depend on the given namespace. If this is not
+        #               provided, the default namespace is used.  To explicitly not use a
+        #               namespace when there is a default namespace, pass a nil value.
         # :params :: Includes parameters in the query string of the returned path, and
         #            limits the returned path to only be valid for that exact query string.
         # :root :: Should be an empty string or string starting with +/+. This will be
@@ -180,6 +254,10 @@ class Roda
             path << '?' << Rack::Utils.build_query(params)
           end
 
+          if hmac_path_namespace(opts)
+            flags << 'n'
+          end
+
           flags << '0' if flags.empty?
           
           hmac_path = if method
@@ -188,7 +266,7 @@ class Roda
             "/#{flags}#{path}"
           end
 
-          "#{root}/#{hmac_path_hmac(root, hmac_path)}/#{flags}#{path}"
+          "#{root}/#{hmac_path_hmac(root, hmac_path, opts)}/#{flags}#{path}"
         end
 
         # The HMAC to use in hmac_path, for the given root, path, and options.
@@ -196,14 +274,34 @@ class Roda
           OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, hmac_path_hmac_secret(root, opts), path)
         end
 
+        # The namespace to use for the hmac path.  If a :namespace option is not
+        # provided, and a :namespace_session_key option was provided, this will
+        # use the value of the related session key, if present.
+        def hmac_path_namespace(opts=OPTS)
+          opts.fetch(:namespace){hmac_path_default_namespace}
+        end
+
         private
 
         # The secret used to calculate the HMAC in hmac_path. This is itself an HMAC, created
-        # using the secret given in the plugin, for the given root and options. If the 
+        # using the secret given in the plugin, for the given root and options.
+        # This always returns a hexidecimal string.
         def hmac_path_hmac_secret(root, opts=OPTS)
           secret = opts[:secret] || self.opts[:hmac_paths_secret]
+
+          if namespace = hmac_path_namespace(opts)
+            secret = OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secret, namespace)
+          end
+
           OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, secret, root)
         end
+
+        # The default namespace to use for hmac_path, if a :namespace option is not provided.
+        def hmac_path_default_namespace
+          if (key = opts[:hmac_paths_namespace_session_key]) && (value = session[key])
+            value.to_s
+          end
+        end
       end
 
       module RequestMethods
@@ -221,6 +319,13 @@ class Roda
             if submitted_hmac.bytesize == 64
               on String do |flags|
                 if flags.bytesize >= 1
+                  if flags.include?('n') ^ !scope.hmac_path_namespace(opts).nil?
+                    # Namespace required and not provided, or provided and not required.
+                    # Bail early to avoid unnecessary HMAC calculation.
+                    @remaining_path = orig_path
+                    return
+                  end
+
                   if flags.include?('m')
                     rpath = "#{env['REQUEST_METHOD'].to_s.upcase}:#{rpath}"
                   end
@@ -229,7 +334,7 @@ class Roda
                     rpath = "#{rpath}?#{env["QUERY_STRING"]}"
                   end
 
-                  if hmac_path_valid?(mpath, rpath, submitted_hmac)
+                  if hmac_path_valid?(mpath, rpath, submitted_hmac, opts)
                     always(&block)
                   end
                 end
@@ -249,11 +354,13 @@ class Roda
         private
 
         # Determine whether the provided hmac matches.
-        def hmac_path_valid?(root, path, hmac)
-          if Rack::Utils.secure_compare(scope.hmac_path_hmac(root, path), hmac)
+        def hmac_path_valid?(root, path, hmac, opts=OPTS)
+          if Rack::Utils.secure_compare(scope.hmac_path_hmac(root, path, opts), hmac)
             true
           elsif old_secret = roda_class.opts[:hmac_paths_old_secret]
-            Rack::Utils.secure_compare(scope.hmac_path_hmac(root, path, secret: old_secret), hmac)
+            opts = opts.dup
+            opts[:secret] = old_secret
+            Rack::Utils.secure_compare(scope.hmac_path_hmac(root, path, opts), hmac)
           else
             false
           end

data/lib/roda/version.rb

@@ -4,7 +4,7 @@ class Roda
   RodaMajorVersion = 3
 
   # The minor version of Roda, updated for new feature releases of Roda.
-  RodaMinorVersion = 79
+  RodaMinorVersion = 80
 
   # The patch version of Roda, updated only for bug fixes from the last
   # feature release.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roda
 version: !ruby/object:Gem::Version
-  version: 3.79.0
+  version: 3.80.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-12 00:00:00.000000000 Z
+date: 2024-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -254,6 +254,7 @@ extra_rdoc_files:
 - doc/release_notes/3.78.0.txt
 - doc/release_notes/3.79.0.txt
 - doc/release_notes/3.8.0.txt
+- doc/release_notes/3.80.0.txt
 - doc/release_notes/3.9.0.txt
 files:
 - CHANGELOG
@@ -340,6 +341,7 @@ files:
 - doc/release_notes/3.78.0.txt
 - doc/release_notes/3.79.0.txt
 - doc/release_notes/3.8.0.txt
+- doc/release_notes/3.80.0.txt
 - doc/release_notes/3.9.0.txt
 - lib/roda.rb
 - lib/roda/cache.rb
@@ -505,7 +507,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: Routing tree web toolkit