roda 3.77.0 → 3.79.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8afa46b8055c19e63e1efeebf444b422cd810701c759936d476797515630245d
-  data.tar.gz: 4e857447435707de1d586857126795e2a1191f685ca8893e99cd1c78aeb50c02
+  metadata.gz: 8e77e7eba739ca8bf0afe44555c8af8c9188f4ce8668310aad110a2afc638701
+  data.tar.gz: 19db55450dfe15e7aa4f678d7556ec427e52bcad421a096791d47a5a3fe128b4
 SHA512:
-  metadata.gz: 2ecfeb211d574d46bdc31995c3551afb97af50acf8567cce83b46808e87ff797a5ef7c769e42c0477ed6a6d9271040b818da72e77c91e4f91f9760201d2cd5ca
-  data.tar.gz: 45e67fbd1da64839c6dc5a8dc0975a0dca5f67a77c83ae79a62ab22e7d9cf0002cb8b8f6a22661bdaf97ad973b6bc6ff928af2e416a96c35b12150e9fe0eaf4d
+  metadata.gz: f504398b08e35ca42b765afca4357d750836ce5d7e3e7ec9ba73b061dde57fd2bbd3fa5d7752b9e6995739fac8a8718b0a8a71d70432ec14b65c95e13dadeb29
+  data.tar.gz: ceb20219c23d4e44d006c5fe177fff3ef2cacb77ec75e109b92c03d12f0e9cf434459759d007df96becfa0e426c89f4f8f9517c00c579135cfbb0e613852a0a1

data/CHANGELOG

@@ -1,3 +1,13 @@
+= 3.79.0 (2024-04-12)
+
+* Do not update template mtime when there is an error reloading templates in the render plugin (jeremyevans)
+
+* Add hmac_paths plugin for preventing path enumeration and supporting access control (jeremyevans)
+
+= 3.78.0 (2024-03-13)
+
+* Add permissions_policy plugin for setting Permissions-Policy header (jeremyevans)
+
 = 3.77.0 (2024-02-12)
 
 * Support formaction/formmethod attributes in forms in route_csrf plugin (jeremyevans)

data/doc/release_notes/3.78.0.txt

@@ -0,0 +1,99 @@
+= New Features
+
+* A permissions_policy plugin has been added that allows you to easily set a
+  Permissions-Policy header for the application, which browsers can use to
+  determine whether to allow specific functionality on the returned page
+  (mainly related to which JavaScript APIs the page is allowed to use).
+
+  You would generally call the plugin with a block to set the default policy:
+
+    plugin :permissions_policy do |pp|
+      pp.camera :none
+      pp.fullscreen :self
+      pp.clipboard_read :self, 'https://example.com'
+    end
+
+  Then, anywhere in the routing tree, you can customize the policy for just that
+  branch or action using the same block syntax:
+
+    r.get 'foo' do
+      permissions_policy do |pp|
+        pp.camera :self
+      end
+      # ...
+    end
+
+  In addition to using a block, you can also call methods on the object returned
+  by the method:
+
+    r.get 'foo' do
+      permissions_policy.camera :self
+      # ...
+    end
+
+  You can use the :default plugin option to set the default for all settings.
+  For example, to disallow all access for each setting by default:
+
+    plugin :permissions_policy, default: :none
+
+  The following methods are available for configuring the permissions policy,
+  which specify the setting (substituting _ with -): 
+
+  * accelerometer
+  * ambient_light_sensor
+  * autoplay
+  * bluetooth
+  * camera
+  * clipboard_read
+  * clipboard_write
+  * display_capture
+  * encrypted_media
+  * fullscreen
+  * geolocation
+  * gyroscope
+  * hid
+  * idle_detection
+  * keyboard_map
+  * magnetometer
+  * microphone
+  * midi
+  * payment
+  * picture_in_picture
+  * publickey_credentials_get
+  * screen_wake_lock
+  * serial
+  * sync_xhr
+  * usb
+  * web_share
+  * window_management
+
+  All of these methods support any number of arguments, and each argument should
+  be one of the following values:
+
+  :all :: Grants permission to all domains (must be only argument)
+  :none :: Does not allow permission at all (must be only argument)
+  :self :: Allows feature in current document and any nested browsing contexts
+           that use the same domain as the current document.
+  :src :: Allows feature in current document and any nested browsing contexts
+          that use the same domain as the src of the iframe.
+  String :: Specifies origin domain where access is allowed
+
+  When calling a method with no arguments, the setting is removed from the policy instead
+  of being left empty, since all of these setting require at least one value.  Likewise,
+  if the policy does not have any settings, the header will not be added.
+
+  Calling the method overrides any previous setting.  Each of the methods has +add_*+ and
+  +get_*+ methods defined. The +add_*+ method appends to any existing setting, and the +get_*+ method
+  returns the current value for the setting (this will be +:all+ if all domains are allowed, or
+  any array of strings/:self/:src).
+
+    permissions_policy.fullscreen :self, 'https://example.com'
+    # fullscreen (self "https://example.com")
+
+    permissions_policy.add_fullscreen 'https://*.example.com'
+    # fullscreen (self "https://example.com" "https://*.example.com")
+
+    permissions_policy.get_fullscreen
+    # => [:self, "https://example.com", "https://*.example.com"]
+
+  The clear method can be used to remove all settings from the policy.

data/doc/release_notes/3.79.0.txt

@@ -0,0 +1,148 @@
+= New Features
+
+* The hmac_paths plugin allows protection of paths using an HMAC.  This can be used
+  to prevent users enumerating paths, since only paths with valid HMACs will be
+  respected.
+  
+  To use the plugin, you must provide a :secret option.  This sets the secret for
+  the HMACs.  Make sure to keep this value secret, as this plugin does not provide
+  protection against users who know the secret value.  The secret must be at least
+  32 bytes.
+  
+    plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes'
+  
+  To generate a valid HMAC path, you call the hmac_path method:
+  
+    hmac_path('/widget/1')
+    # => "/0c2feaefdfc80cc73da19b060c713d4193c57022815238c6657ce2d99b5925eb/0/widget/1"
+  
+  The first segment in the returned path is the HMAC.  The second segment is flags for
+  the type of paths (see below), and the rest of the path is as given.
+  
+  To protect a path or any subsection in the routing tree, you wrap the related code
+  in an +r.hmac_path+ block.
+  
+    route do |r|
+      r.hmac_path do
+        r.get 'widget', Integer do |widget_id|
+          # ...
+        end
+      end
+    end
+  
+  If first segment of the remaining path contains a valid HMAC for the rest of the path (considering
+  the flags), then r.hmac_path will match and yield to the block, and routing continues inside
+  the block with the HMAC and flags segments removed.
+  
+  In the above example, if you provide a user a link for widget with ID 1, there is no way
+  for them to guess the valid path for the widget with ID 2, preventing a user from
+  enumerating widgets, without relying on custom access control.  Users can only access
+  paths that have been generated by the application and provided to them, either directly
+  or indirectly.
+  
+  In the above example, r.hmac_path is used at the root of the routing tree. If you
+  would like to call it below the root of the routing tree, it works correctly, but you
+  must pass hmac_path the :root option specifying where r.hmac_paths will be called from.
+  Consider this example:
+  
+    route do |r|
+      r.on 'widget' do
+        r.hmac_path do
+          r.get Integer do |widget_id|
+            # ...
+          end
+        end
+      end
+  
+      r.on 'foobar' do
+        r.hmac_path do
+          r.get Integer do |foobar_id|
+            # ...
+          end
+        end
+      end
+    end
+  
+  For security reasons, the hmac_path plugin does not allow an HMAC path designed for
+  widgets to be a valid match in the r.hmac_path call inside the "r.on 'foobar'"
+  block, preventing users who have a valid HMAC for a widget from looking at the page for
+  a foobar with the same ID.  When generating HMAC paths where the matching r.hmac_path
+  call is not at the root of the routing tree, you must pass the :root option:
+  
+    hmac_path('/1', root: '/widget')
+    # => "/widget/daccafce3ce0df52e5ce774626779eaa7286085fcbde1e4681c74175ff0bbacd/0/1"
+  
+    hmac_path('/1', root: '/foobar')
+    # => "/foobar/c5fdaf482771d4f9f38cc13a1b2832929026a4ceb05e98ed6a0cd5a00bf180b7/0/1"
+  
+  Note how the HMAC changes even though the path is the same.
+  
+  In addition to the +:root+ option, there are additional options that further constrain
+  use of the generated paths.
+  
+  The :method option creates a path that can only be called with a certain request
+  method:
+  
+    hmac_path('/widget/1', method: :get)
+    # => "/d38c1e634ecf9a3c0ab9d0832555b035d91b35069efcbf2670b0dfefd4b62fdd/m/widget/1"
+  
+  Note how this results in a different HMAC than the original hmac_path('/widget/1')
+  call.  This sets the flags segment to "m", which means r.hmac_path will consider the
+  request mehod when checking the HMAC, and will only match if the provided request method
+  is GET.  This allows you to provide a user the ability to submit a GET request for the
+  underlying path, without providing them the ability to submit a POST request for the
+  underlying path, with no other access control.
+  
+  The :params option accepts a hash of params, converts it into a query string, and
+  includes the query string in the returned path.  It sets the flags segment to +p+, which
+  means r.hmac_path will check for that exact query string.  Requests with an empty query
+  string or a different string will not match.
+  
+   hmac_path('/widget/1', params: {foo: 'bar'})
+   # => "/fe8d03f9572d5af6c2866295bd3c12c2ea11d290b1cbd016c3b68ee36a678139/p/widget/1?foo=bar"
+  
+  For GET requests, which cannot have request bodies, that is sufficient to ensure that the
+  submitted params are exactly as specified. However, POST requests can have request bodies,
+  and request body params override query string params in r.params.  So if you are using
+  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:
+  
+    hmac_path('/1', root: '/widget', method: :get, params: {foo: 'bar'})
+    # => "/widget/9169af1b8f40c62a1c2bb15b1b377c65bda681b8efded0e613a4176387468c15/mp/1?foo=bar"
+  
+  This gives you a path only valid for a GET request with a root of "/widget" and
+  a query string of "foo=bar".
+  
+  To handle secret rotation, you can provide an :old_secret option when loading the
+  plugin.
+  
+    plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes',
+                        old_secret: 'previous-secret-value-with-at-least-32-bytes'
+  
+  This will use :secret for constructing new paths, but will respect paths generated by
+  :old_secret.
+
+= Other Improvements
+
+* When not using cached templates in the render plugin, the render plugin
+  now has better handling when a template is modified and results in an
+  error.  Previously, the error would be raised on the first request after
+  the template modification, but subsequent requests would use the
+  previous template value.  The render plugin will no longer update the
+  last modified time in this case, so if a template is modified and
+  introduces an error (e.g. SyntaxError in an erb template), all future
+  requests that use the template will result in the error being raised,
+  until the template is fixed.
+
+= Backwards Compatibility
+
+* The internal TemplateMtimeWrapper API has been modified.  As documented,
+  this is an internal class and the API can change in any Roda version.
+  However, if any code was relying on the previous implementation of
+  TemplateMtimeWrapper#modified?, it will need to be modified, as that
+  method has been replaced with TemplateMtimeWrapper#if_modified.
+
+  Additionally, the TemplateMtimeWrapper#compiled_method_lambda API has
+  also changed.

data/lib/roda/plugins/content_security_policy.rb

@@ -89,7 +89,7 @@ class Roda
     #   content_security_policy.add_script_src 'example.com', [:nonce, 'foobarbaz']
     #   # script-src 'self' 'unsafe-eval' example.com 'nonce-foobarbaz'; 
     #
-    #   content_security_policy.get_script_src 'example.com', [:nonce, 'foobarbaz']
+    #   content_security_policy.get_script_src
     #   # => [:self, :unsafe_eval, 'example.com', [:nonce, 'foobarbaz']]
     #
     # The clear method can be used to remove all settings from the policy.

data/lib/roda/plugins/hmac_paths.rb

@@ -0,0 +1,266 @@
+# frozen-string-literal: true
+
+require 'openssl'
+
+#
+class Roda
+  module RodaPlugins
+    # The hmac_paths plugin allows protection of paths using an HMAC.  This can be used
+    # to prevent users enumerating paths, since only paths with valid HMACs will be
+    # respected.
+    #
+    # To use the plugin, you must provide a +secret+ option.  This sets the secret for
+    # the HMACs.  Make sure to keep this value secret, as this plugin does not provide
+    # protection against users who know the secret value.  The secret must be at least
+    # 32 bytes.
+    #
+    #   plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes'
+    #
+    # To generate a valid HMAC path, you call the +hmac_path+ method:
+    #
+    #   hmac_path('/widget/1')
+    #   # => "/0c2feaefdfc80cc73da19b060c713d4193c57022815238c6657ce2d99b5925eb/0/widget/1"
+    #
+    # The first segment in the returned path is the HMAC.  The second segment is flags for
+    # the type of paths (see below), and the rest of the path is as given.
+    #
+    # To protect a path or any subsection in the routing tree, you wrap the related code
+    # in an +r.hmac_path+ block.
+    #
+    #   route do |r|
+    #     r.hmac_path do
+    #       r.get 'widget', Integer do |widget_id|
+    #         # ...
+    #       end
+    #     end
+    #   end
+    #
+    # If first segment of the remaining path contains a valid HMAC for the rest of the path (considering
+    # the flags), then +r.hmac_path+ will match and yield to the block, and routing continues inside
+    # the block with the HMAC and flags segments removed.
+    #
+    # In the above example, if you provide a user a link for widget with ID 1, there is no way
+    # for them to guess the valid path for the widget with ID 2, preventing a user from
+    # enumerating widgets, without relying on custom access control.  Users can only access
+    # paths that have been generated by the application and provided to them, either directly
+    # or indirectly.
+    #
+    # In the above example, +r.hmac_path+ is used at the root of the routing tree. If you
+    # would like to call it below the root of the routing tree, it works correctly, but you
+    # must pass +hmac_path+ the +:root+ option specifying where +r.hmac_paths+ will be called from.
+    # Consider this example:
+    #
+    #   route do |r|
+    #     r.on 'widget' do
+    #       r.hmac_path do
+    #         r.get Integer do |widget_id|
+    #           # ...
+    #         end
+    #       end
+    #     end
+    #
+    #     r.on 'foobar' do
+    #       r.hmac_path do
+    #         r.get Integer do |foobar_id|
+    #           # ...
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # For security reasons, the hmac_path plugin does not allow an HMAC path designed for
+    # widgets to be a valid match in the +r.hmac_path+ call inside the <tt>r.on 'foobar'</tt>
+    # block, preventing users who have a valid HMAC for a widget from looking at the page for
+    # a foobar with the same ID.  When generating HMAC paths where the matching +r.hmac_path+
+    # call is not at the root of the routing tree, you must pass the +:root+ option:
+    #
+    #   hmac_path('/1', root: '/widget')
+    #   # => "/widget/daccafce3ce0df52e5ce774626779eaa7286085fcbde1e4681c74175ff0bbacd/0/1"
+    #
+    #   hmac_path('/1', root: '/foobar')
+    #   # => "/foobar/c5fdaf482771d4f9f38cc13a1b2832929026a4ceb05e98ed6a0cd5a00bf180b7/0/1"
+    #
+    # Note how the HMAC changes even though the path is the same.
+    #
+    # In addition to the +:root+ option, there are additional options that further constrain
+    # use of the generated paths.
+    #
+    # The +:method+ option creates a path that can only be called with a certain request
+    # method:
+    #
+    #   hmac_path('/widget/1', method: :get)
+    #   # => "/d38c1e634ecf9a3c0ab9d0832555b035d91b35069efcbf2670b0dfefd4b62fdd/m/widget/1"
+    #
+    # Note how this results in a different HMAC than the original <tt>hmac_path('/widget/1')</tt>
+    # call.  This sets the flags segment to +m+, which means +r.hmac_path+ will consider the
+    # request mehod when checking the HMAC, and will only match if the provided request method
+    # is GET.  This allows you to provide a user the ability to submit a GET request for the
+    # underlying path, without providing them the ability to submit a POST request for the
+    # underlying path, with no other access control.
+    #
+    # The +:params+ option accepts a hash of params, converts it into a query string, and
+    # includes the query string in the returned path.  It sets the flags segment to +p+, which
+    # means +r.hmac_path+ will check for that exact query string.  Requests with an empty query
+    # string or a different string will not match.
+    #
+    #   hmac_path('/widget/1', params: {foo: 'bar'})
+    #   # => "/fe8d03f9572d5af6c2866295bd3c12c2ea11d290b1cbd016c3b68ee36a678139/p/widget/1?foo=bar"
+    #
+    # For GET requests, which cannot have request bodies, that is sufficient to ensure that the
+    # submitted params are exactly as specified. However, POST requests can have request bodies,
+    # and request body params override query string params in +r.params+.  So if you are using
+    # 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:
+    #
+    #   hmac_path('/1', root: '/widget', method: :get, params: {foo: 'bar'})
+    #   # => "/widget/9169af1b8f40c62a1c2bb15b1b377c65bda681b8efded0e613a4176387468c15/mp/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>.
+    #
+    # To handle secret rotation, you can provide an +:old_secret+ option when loading the
+    # plugin.
+    #
+    #   plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes',
+    #                       old_secret: 'previous-secret-value-with-at-least-32-bytes'
+    #
+    # This will use +:secret+ for constructing new paths, but will respect paths generated by
+    # +:old_secret+.
+    module HmacPaths
+      def self.configure(app, opts=OPTS)
+        hmac_secret = opts[:secret]
+        unless hmac_secret.is_a?(String) && hmac_secret.bytesize >= 32
+          raise RodaError, "hmac_paths plugin :secret option must be a string containing at least 32 bytes"
+        end
+
+        if hmac_old_secret = opts[:old_secret]
+          unless hmac_old_secret.is_a?(String) && hmac_old_secret.bytesize >= 32
+            raise RodaError, "hmac_paths plugin :old_secret option must be a string containing at least 32 bytes if present"
+          end
+        end
+
+        app.opts[:hmac_paths_secret] = hmac_secret
+        app.opts[:hmac_paths_old_secret] = hmac_old_secret
+      end
+
+      module InstanceMethods
+        # Return a path with an HMAC.  Designed to be used with r.hmac_path, to make sure
+        # users can only request paths that they have been provided by the application
+        # (directly or indirectly).  This can prevent users of a site from enumerating
+        # 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.
+        # :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
+        #          the already matched path of the routing tree using r.hmac_path. Defaults
+        #          to the empty string, which will returns paths valid for r.hmac_path at
+        #          the top level of the routing tree.
+        def hmac_path(path, opts=OPTS)
+          unless path.is_a?(String) && path.getbyte(0) == 47
+            raise RodaError, "path must be a string starting with /"
+          end
+
+          root = opts[:root] || ''
+          unless root.is_a?(String) && ((root_byte = root.getbyte(0)) == 47 || root_byte == nil)
+            raise RodaError, "root must be empty string or string starting with /"
+          end
+
+          flags = String.new
+          path = path.dup
+
+          if method = opts[:method]
+            flags << 'm'
+          end
+
+          if params = opts[:params]
+            flags << 'p'
+            path << '?' << Rack::Utils.build_query(params)
+          end
+
+          flags << '0' if flags.empty?
+          
+          hmac_path = if method
+            "#{method.to_s.upcase}:/#{flags}#{path}"
+          else
+            "/#{flags}#{path}"
+          end
+
+          "#{root}/#{hmac_path_hmac(root, hmac_path)}/#{flags}#{path}"
+        end
+
+        # The HMAC to use in hmac_path, for the given root, path, and options.
+        def hmac_path_hmac(root, path, opts=OPTS)
+          OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, hmac_path_hmac_secret(root, opts), path)
+        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 
+        def hmac_path_hmac_secret(root, opts=OPTS)
+          secret = opts[:secret] || self.opts[:hmac_paths_secret]
+          OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, secret, root)
+        end
+      end
+
+      module RequestMethods
+        # Looks at the first segment of the remaining path, and if it contains a valid HMAC for the
+        # rest of the path considering the flags in the second segment and the given options, the
+        # block matches and is yielded to, and the result of the block is returned. Otherwise, the
+        # block does not matches and routing continues after the call.
+        def hmac_path(opts=OPTS, &block)
+          orig_path = remaining_path
+          mpath = matched_path
+
+          on String do |submitted_hmac|
+            rpath = remaining_path
+
+            if submitted_hmac.bytesize == 64
+              on String do |flags|
+                if flags.bytesize >= 1
+                  if flags.include?('m')
+                    rpath = "#{env['REQUEST_METHOD'].to_s.upcase}:#{rpath}"
+                  end
+
+                  if flags.include?('p')
+                    rpath = "#{rpath}?#{env["QUERY_STRING"]}"
+                  end
+
+                  if hmac_path_valid?(mpath, rpath, submitted_hmac)
+                    always(&block)
+                  end
+                end
+
+                # Return from method without matching
+                @remaining_path = orig_path
+                return
+              end
+            end
+
+            # Return from method without matching
+            @remaining_path = orig_path
+            return
+          end
+        end
+
+        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)
+            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)
+          else
+            false
+          end
+        end
+      end
+    end
+
+    register_plugin(:hmac_paths, HmacPaths)
+  end
+end

data/lib/roda/plugins/permissions_policy.rb

@@ -0,0 +1,326 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # A permissions_policy plugin has been added that allows you to easily set a
+    # Permissions-Policy header for the application, which browsers can use to
+    # determine whether to allow specific functionality on the returned page
+    # (mainly related to which JavaScript APIs the page is allowed to use).
+    #
+    # You would generally call the plugin with a block to set the default policy:
+    #
+    #   plugin :permissions_policy do |pp|
+    #     pp.camera :none
+    #     pp.fullscreen :self
+    #     pp.clipboard_read :self, 'https://example.com'
+    #   end
+    #
+    # Then, anywhere in the routing tree, you can customize the policy for just that
+    # branch or action using the same block syntax:
+    #
+    #   r.get 'foo' do
+    #     permissions_policy do |pp|
+    #       pp.camera :self
+    #     end
+    #     # ...
+    #   end
+    #
+    # In addition to using a block, you can also call methods on the object returned
+    # by the method:
+    #
+    #   r.get 'foo' do
+    #     permissions_policy.camera :self
+    #     # ...
+    #   end
+    #
+    # You can use the :default plugin option to set the default for all settings.
+    # For example, to disallow all access for each setting by default:
+    #
+    #   plugin :permissions_policy, default: :none
+    #
+    # The following methods are available for configuring the permissions policy,
+    # which specify the setting (substituting _ with -): 
+    #
+    # * accelerometer
+    # * ambient_light_sensor
+    # * autoplay
+    # * bluetooth
+    # * camera
+    # * clipboard_read
+    # * clipboard_write
+    # * display_capture
+    # * encrypted_media
+    # * fullscreen
+    # * geolocation
+    # * gyroscope
+    # * hid
+    # * idle_detection
+    # * keyboard_map
+    # * magnetometer
+    # * microphone
+    # * midi
+    # * payment
+    # * picture_in_picture
+    # * publickey_credentials_get
+    # * screen_wake_lock
+    # * serial
+    # * sync_xhr
+    # * usb
+    # * web_share
+    # * window_management
+    #
+    # All of these methods support any number of arguments, and each argument should
+    # be one of the following values:
+    #
+    # :all :: Grants permission to all domains (must be only argument)
+    # :none :: Does not allow permission at all (must be only argument)
+    # :self :: Allows feature in current document and any nested browsing contexts
+    #          that use the same domain as the current document.
+    # :src :: Allows feature in current document and any nested browsing contexts
+    #         that use the same domain as the src of the iframe.
+    # String :: Specifies origin domain where access is allowed
+    #
+    # When calling a method with no arguments, the setting is removed from the policy instead
+    # of being left empty, since all of these setting require at least one value.  Likewise,
+    # if the policy does not have any settings, the header will not be added.
+    #
+    # Calling the method overrides any previous setting.  Each of the methods has +add_*+ and
+    # +get_*+ methods defined. The +add_*+ method appends to any existing setting, and the +get_*+ method
+    # returns the current value for the setting (this will be +:all+ if all domains are allowed, or
+    # any array of strings/:self/:src).
+    #
+    #   permissions_policy.fullscreen :self, 'https://example.com'
+    #   # fullscreen (self "https://example.com")
+    #
+    #   permissions_policy.add_fullscreen 'https://*.example.com'
+    #   # fullscreen (self "https://example.com" "https://*.example.com")
+    #
+    #   permissions_policy.get_fullscreen
+    #   # => [:self, "https://example.com", "https://*.example.com"]
+    #
+    # The clear method can be used to remove all settings from the policy.
+    module PermissionsPolicy
+      SUPPORTED_SETTINGS = %w'
+      accelerometer
+      ambient-light-sensor
+      autoplay
+      bluetooth
+      camera
+      clipboard-read
+      clipboard-write
+      display-capture
+      encrypted-media
+      fullscreen
+      geolocation
+      gyroscope
+      hid
+      idle-detection
+      keyboard-map
+      magnetometer
+      microphone
+      midi
+      payment
+      picture-in-picture
+      publickey-credentials-get
+      screen-wake-lock
+      serial
+      sync-xhr
+      usb
+      web-share
+      window-management
+      '.each(&:freeze).freeze
+      private_constant :SUPPORTED_SETTINGS
+
+      # Represents a permissions policy.
+      class Policy
+        SUPPORTED_SETTINGS.each do |setting|
+          meth = setting.gsub('-', '_').freeze
+
+          # Setting method name sets the setting value, or removes it if no args are given.
+          define_method(meth) do |*args|
+            if args.empty?
+              @opts.delete(setting)
+            else
+              @opts[setting] = option_value(args)
+            end
+            nil
+          end
+
+          # add_* method name adds to the setting value, or clears setting if no values
+          # are given.
+          define_method(:"add_#{meth}") do |*args|
+            unless args.empty?
+              case v = @opts[setting]
+              when :all
+                # If all domains are already allowed, there is no reason to add more.
+                return
+              when Array
+                @opts[setting] = option_value(v + args)
+              else
+                @opts[setting] = option_value(args)
+              end
+            end
+            nil
+          end
+
+          # get_* method always returns current setting value.
+          define_method(:"get_#{meth}") do
+            @opts[setting]
+          end
+        end
+
+        def initialize
+          clear
+        end
+
+        # Clear all settings, useful to remove any inherited settings.
+        def clear
+          @opts = {}
+        end
+
+        # Do not allow future modifications to any settings.
+        def freeze
+          @opts.freeze
+          header_value.freeze
+          super
+        end
+
+        # The header name to use, depends on whether report only mode has been enabled.
+        def header_key
+          @report_only ? RodaResponseHeaders::PERMISSIONS_POLICY_REPORT_ONLY : RodaResponseHeaders::PERMISSIONS_POLICY
+        end
+
+        # The header value to use.
+        def header_value
+          return @header_value if @header_value
+
+          s = String.new
+          @opts.each do |k, vs|
+            s << k << "="
+
+            if vs == :all
+              s << '*, '
+            else
+              s << '('
+              vs.each{|v| append_formatted_value(s, v)}
+              s.chop! unless vs.empty?
+              s << '), '
+            end
+          end
+          s.chop!
+          s.chop!
+          @header_value = s
+        end
+
+        # Set whether the Permissions-Policy-Report-Only header instead of the
+        # default Permissions-Policy header.
+        def report_only(report=true)
+          @report_only = report
+        end
+
+        # Whether this policy uses report only mode.
+        def report_only?
+          !!@report_only
+        end
+
+        # Set the current policy in the headers hash.  If no settings have been made
+        # in the policy, does not set a header.
+        def set_header(headers)
+          return if @opts.empty?
+          headers[header_key] ||= header_value
+        end
+
+        private
+
+        # Formats nested values, quoting strings and using :self and :src verbatim.
+        def append_formatted_value(s, v)
+          case v
+          when String
+            s << v.inspect << ' '
+          when :self
+            s << 'self '
+          when :src
+            s << 'src '
+          else
+            raise RodaError, "unsupported Permissions-Policy item value used: #{v.inspect}"
+          end
+        end
+
+        # Make object copy use copy of settings, and remove cached header value.
+        def initialize_copy(_)
+          super
+          @opts = @opts.dup
+          @header_value = nil
+        end
+
+        # The option value to store for the given args.
+        def option_value(args)
+          if args.length == 1
+            case args[0]
+            when :all
+              :all
+            when :none
+              EMPTY_ARRAY
+            else
+              args.freeze
+            end
+          else
+            args.freeze
+          end
+        end
+      end
+
+      # Yield the current Permissions Policy to the block.
+      def self.configure(app, opts=OPTS)
+        policy = app.opts[:permissions_policy] = if policy = app.opts[:permissions_policy]
+          policy.dup
+        else
+          Policy.new
+        end
+
+        if default = opts[:default]
+          SUPPORTED_SETTINGS.each do |setting|
+            policy.send(setting.gsub('-', '_'), *default)
+          end
+        end
+
+        yield policy if defined?(yield)
+        policy.freeze
+      end
+
+      module InstanceMethods
+        # If a block is given, yield the current permission policy.  Returns the
+        # current permissions policy.
+        def permissions_policy
+          policy = @_response.permissions_policy
+          yield policy if defined?(yield)
+          policy
+        end
+      end
+
+      module ResponseMethods
+        # Unset any permissions policy when reinitializing
+        def initialize
+          super
+          @permissions_policy &&= nil
+        end
+
+        # The current permissions policy to be used for this response.
+        def permissions_policy
+          @permissions_policy ||= roda_class.opts[:permissions_policy].dup
+        end
+
+        private
+
+        # Set the appropriate permissions policy header.
+        def set_default_headers
+          super
+          (@permissions_policy || roda_class.opts[:permissions_policy]).set_header(headers)
+        end
+      end
+    end
+
+    register_plugin(:permissions_policy, PermissionsPolicy)
+  end
+end

data/lib/roda/plugins/render.rb

@@ -335,8 +335,13 @@ class Roda
         # If the template file exists and the modification time has
         # changed, rebuild the template file, then call render on it.
         def render(*args, &block)
-          modified?
-          @template.render(*args, &block)
+          res = nil
+          modified = false
+          if_modified do
+            res = @template.render(*args, &block)
+            modified = true
+          end
+          modified ? res : @template.render(*args, &block)
         end
 
         # Return when the template was last modified.  If the template depends on any
@@ -352,20 +357,18 @@ class Roda
 
         # If the template file has been updated, return true and update
         # the template object and the modification time. Other return false.
-        def modified?
+        def if_modified
           begin
             mtime = template_last_modified
           rescue
             # ignore errors
           else
             if mtime != @mtime
-              @mtime = mtime
               reset_template
-              return true
+              yield
+              @mtime = mtime
             end
           end
-
-          false
         end
 
         if COMPILED_METHOD_SUPPORT
@@ -375,13 +378,13 @@ class Roda
             mod = roda_class::RodaCompiledTemplates
             internal_method_name = :"_#{method_name}"
             begin
-              mod.send(:define_method, internal_method_name, send(:compiled_method, locals_keys, roda_class))
+              mod.send(:define_method, internal_method_name, compiled_method(locals_keys, roda_class))
             rescue ::NotImplementedError
               return false
             end
 
             mod.send(:private, internal_method_name)
-            mod.send(:define_method, method_name, &compiled_method_lambda(self, roda_class, internal_method_name, locals_keys))
+            mod.send(:define_method, method_name, &compiled_method_lambda(roda_class, internal_method_name, locals_keys))
             mod.send(:private, method_name)
 
             method_name
@@ -397,10 +400,11 @@ class Roda
           # Return the lambda used to define the compiled template method.  This
           # is separated into its own method so the lambda does not capture any
           # unnecessary local variables
-          def compiled_method_lambda(template, roda_class, method_name, locals_keys=EMPTY_ARRAY)
+          def compiled_method_lambda(roda_class, method_name, locals_keys=EMPTY_ARRAY)
             mod = roda_class::RodaCompiledTemplates
+            template = self
             lambda do |locals, &block|
-              if template.modified?
+              template.if_modified do
                 mod.send(:define_method, method_name, Render.tilt_template_compiled_method(template, locals_keys, roda_class))
                 mod.send(:private, method_name)
               end

data/lib/roda/response.rb

@@ -14,7 +14,8 @@ class Roda
 
     %w'Allow Cache-Control Content-Disposition Content-Encoding Content-Length
        Content-Security-Policy Content-Security-Policy-Report-Only Content-Type
-       ETag Expires Last-Modified Link Location Set-Cookie Transfer-Encoding Vary'.
+       ETag Expires Last-Modified Link Location Set-Cookie Transfer-Encoding Vary
+       Permissions-Policy Permissions-Policy-Report-Only'.
       each do |value|
         value = value.downcase if downcase
         const_set(value.gsub('-', '_').upcase!.to_sym, value.freeze)

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 = 77
+  RodaMinorVersion = 79
 
   # 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.77.0
+  version: 3.79.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-12 00:00:00.000000000 Z
+date: 2024-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -251,6 +251,8 @@ extra_rdoc_files:
 - doc/release_notes/3.75.0.txt
 - doc/release_notes/3.76.0.txt
 - doc/release_notes/3.77.0.txt
+- 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.9.0.txt
 files:
@@ -335,6 +337,8 @@ files:
 - doc/release_notes/3.75.0.txt
 - doc/release_notes/3.76.0.txt
 - doc/release_notes/3.77.0.txt
+- 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.9.0.txt
 - lib/roda.rb
@@ -397,6 +401,7 @@ files:
 - lib/roda/plugins/head.rb
 - lib/roda/plugins/header_matchers.rb
 - lib/roda/plugins/heartbeat.rb
+- lib/roda/plugins/hmac_paths.rb
 - lib/roda/plugins/hooks.rb
 - lib/roda/plugins/host_authorization.rb
 - lib/roda/plugins/indifferent_params.rb
@@ -432,6 +437,7 @@ files:
 - lib/roda/plugins/path.rb
 - lib/roda/plugins/path_matchers.rb
 - lib/roda/plugins/path_rewriter.rb
+- lib/roda/plugins/permissions_policy.rb
 - lib/roda/plugins/placeholder_string_matchers.rb
 - lib/roda/plugins/plain_hash_response_headers.rb
 - lib/roda/plugins/precompile_templates.rb