roda 3.76.0 → 3.78.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f4eee948a9994645560f635fd228d2f46f3f466da782a476d7046b2b0b9f026
-  data.tar.gz: 4abb6bed043b264c59e17b1120771822a26292f24037a283c08003168c72e602
+  metadata.gz: 44eb48fa9dd507c495e32f90e5ef3b9b197d47f1c148f5d91714272afdca74f8
+  data.tar.gz: 276ceaf7256b816b4a5c59e7c2508cb9066e1d1693d398e7be43ac17be7a9115
 SHA512:
-  metadata.gz: 112d90a74ed25ae0bb608a2e89d2f6fa757912287feb3a68d312ef4b8fd317bdb8f04eb76f529090d14a92c322d869ededa831f8db5d20bce8a66cd973a71584
-  data.tar.gz: 22ddb0a055b5849c6dcd3ec93426e495198434cf1e9cf9adbae1c22ece9b788c0ea7332122b9ad525954e2b946b0eef873de3b0466fe5b844407dec6c9844c84
+  metadata.gz: b99672a570f6c119375435546104627d27437cb66372f61df0b7e08a9eb4ae66709b33162d2cf0354b2a22c3ed7c456b60423218cd734a9fe644c9b278c5c44f
+  data.tar.gz: 6bd6f328f173bfe2dd28b1b4ea9452158f127ac2c93dcf4de6783af5513d38803e9642c3c24b899e16d05dbdb35569464dc9ca2f00111a8814193e48870afe45

data/CHANGELOG

@@ -1,3 +1,11 @@
+= 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)
+
 = 3.76.0 (2024-01-12)
 
 * Support :filter plugin option in error_mail and error_email for filtering parameters, environment variables, and session values (jeremyevans) (#346)

data/doc/release_notes/3.77.0.txt

@@ -0,0 +1,8 @@
+= New Features
+
+* The route_csrf plugin now supports formaction/formmethod attributes
+  in forms. A csrf_formaction_tag method has been added for creating
+  a hidden input for a particular path and method.  When a form is
+  submitted, the check_csrf! method will fix check for a path-specific
+  csrf token (set by the hidden tag added by the csrf_formaction_tag
+  method), before checking for the default csrf token.

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/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/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/route_csrf.rb

@@ -42,6 +42,9 @@ class Roda
     # This plugin supports the following options:
     #
     # :field :: Form input parameter name for CSRF token (default: '_csrf')
+    # :formaction_field :: Form input parameter name for path-specific CSRF tokens (used by the
+    #                      +csrf_formaction_tag+ method).  If present, this parameter should be
+    #                      submitted as a hash, keyed by path, with CSRF token values.
     # :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).
@@ -86,6 +89,10 @@ class Roda
     #                         override any of the plugin options for this specific call.
     #                         The :token option can be used to specify the provided CSRF token
     #                         (instead of looking for the token in the submitted parameters).
+    # csrf_formaction_tag(path, method='POST') :: An HTML hidden input tag string containing the CSRF token, suitable
+    #                                             for placing in an HTML form that has inputs that use formaction
+    #                                             attributes to change the endpoint to which the form is submitted.
+    #                                             Takes the same arguments as csrf_token.
     # csrf_field :: The field name to use for the hidden tag containing the CSRF token.
     # csrf_path(action) :: This takes an argument that would be the value of the HTML form's
     #                      action attribute, and returns a path you can pass to csrf_token
@@ -152,6 +159,7 @@ class Roda
       # Default CSRF option values
       DEFAULTS = {
         :field => '_csrf'.freeze,
+        :formaction_field => '_csrfs'.freeze,
         :header => 'X-CSRF-Token'.freeze,
         :key => '_roda_csrf_secret'.freeze,
         :require_request_specific_tokens => true,
@@ -252,6 +260,14 @@ class Roda
           end
         end
 
+        # An HTML hidden input tag string containing the CSRF token, used for inputs
+        # with formaction, so the same form can be used to submit to multiple endpoints
+        # depending on which button was clicked.  See csrf_token for arguments, but the
+        # path argument is required.
+        def csrf_formaction_tag(path, *args)
+          "<input type=\"hidden\" name=\"#{csrf_options[:formaction_field]}[#{Rack::Utils.escape_html(path)}]\" value=\"#{csrf_token(path, *args)}\" \/>"
+        end
+
         # An HTML hidden input tag string containing the CSRF token.  See csrf_token for
         # arguments.
         def csrf_tag(*args)
@@ -291,6 +307,8 @@ class Roda
             return
           end
 
+          path = @_request.path
+
           unless encoded_token = opts[:token]
             encoded_token = case opts[:check_header]
             when :only
@@ -298,7 +316,8 @@ class Roda
             when true
               return (csrf_invalid_message(opts.merge(:check_header=>false)) && csrf_invalid_message(opts.merge(:check_header=>:only)))
             else
-              @_request.params[opts[:field]]
+              params = @_request.params
+              ((formactions = params[opts[:formaction_field]]).is_a?(Hash) && (formactions[path])) || params[opts[:field]]
             end
           end
 
@@ -326,7 +345,7 @@ class Roda
 
           random_data = submitted_hmac.slice!(0...31)
 
-          if csrf_compare(csrf_hmac(random_data, method, @_request.path), submitted_hmac)
+          if csrf_compare(csrf_hmac(random_data, method, path), submitted_hmac)
             return
           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 = 76
+  RodaMinorVersion = 78
 
   # 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.76.0
+  version: 3.78.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-12 00:00:00.000000000 Z
+date: 2024-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -250,6 +250,8 @@ extra_rdoc_files:
 - doc/release_notes/3.74.0.txt
 - 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.8.0.txt
 - doc/release_notes/3.9.0.txt
 files:
@@ -333,6 +335,8 @@ files:
 - doc/release_notes/3.74.0.txt
 - 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.8.0.txt
 - doc/release_notes/3.9.0.txt
 - lib/roda.rb
@@ -430,6 +434,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