roda 3.77.0 → 3.78.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8afa46b8055c19e63e1efeebf444b422cd810701c759936d476797515630245d
-  data.tar.gz: 4e857447435707de1d586857126795e2a1191f685ca8893e99cd1c78aeb50c02
+  metadata.gz: 44eb48fa9dd507c495e32f90e5ef3b9b197d47f1c148f5d91714272afdca74f8
+  data.tar.gz: 276ceaf7256b816b4a5c59e7c2508cb9066e1d1693d398e7be43ac17be7a9115
 SHA512:
-  metadata.gz: 2ecfeb211d574d46bdc31995c3551afb97af50acf8567cce83b46808e87ff797a5ef7c769e42c0477ed6a6d9271040b818da72e77c91e4f91f9760201d2cd5ca
-  data.tar.gz: 45e67fbd1da64839c6dc5a8dc0975a0dca5f67a77c83ae79a62ab22e7d9cf0002cb8b8f6a22661bdaf97ad973b6bc6ff928af2e416a96c35b12150e9fe0eaf4d
+  metadata.gz: b99672a570f6c119375435546104627d27437cb66372f61df0b7e08a9eb4ae66709b33162d2cf0354b2a22c3ed7c456b60423218cd734a9fe644c9b278c5c44f
+  data.tar.gz: 6bd6f328f173bfe2dd28b1b4ea9452158f127ac2c93dcf4de6783af5513d38803e9642c3c24b899e16d05dbdb35569464dc9ca2f00111a8814193e48870afe45

data/CHANGELOG

@@ -1,3 +1,7 @@
+= 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/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/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 = 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.77.0
+  version: 3.78.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-12 00:00:00.000000000 Z
+date: 2024-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -251,6 +251,7 @@ 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.8.0.txt
 - doc/release_notes/3.9.0.txt
 files:
@@ -335,6 +336,7 @@ 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.8.0.txt
 - doc/release_notes/3.9.0.txt
 - lib/roda.rb
@@ -432,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