secure_headers 3.1.2 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3ebe74bc751469bb4305dd36b59fe4881a87ec3d
-  data.tar.gz: 83fed6de7e4cab010cab6010caa0ba005ac43fc7
+  metadata.gz: a02f16867ec55f8c168ace664cc63d760785256f
+  data.tar.gz: db54c113af8919984c8f382b957834f38210cf3e
 SHA512:
-  metadata.gz: bd02880ba737a5a9489dd6e8209420259fec8d78330f5992e7b34f61ebe16677a93ff123dd3b417f6973bfcd85e03524b053bcd1487458492aa4c7b8a7a9bb40
-  data.tar.gz: 550c48cfd47e656e70dd3ab39ed6386b8d148231d55a553395da6076bc88bdaaa7fe1803695b093cf3e4fd49cb30bed0aff15a2455652efd00d7a27d9ce55636
+  metadata.gz: 6d9ddcb98a8c646d4e7a8cdb79bf3d8638cae4cb230ff268660e8eab7000fba99bb65e126ce55b3ff5f2a0346013fcf8b769dab4db697c82ab4461d444d0e2bd
+  data.tar.gz: b63c79ac3e9b37a4cff698f979f1ca6fd7e92567e35b1f9026be2e68a205e5badff302d512938a4d36517e8ec5b752d4833082e1b733ff73916fbf0b326641aa

data/CHANGELOG.md

@@ -1,3 +1,120 @@
+## 3.2.0 Cookie settings and CSP hash sources
+
+### Cookies
+
+SecureHeaders supports `Secure`, `HttpOnly` and [`SameSite`](https://tools.ietf.org/html/draft-west-first-party-cookies-07) cookies. These can be defined in the form of a boolean, or as a Hash for more refined configuration.
+
+__Note__: Regardless of the configuration specified, Secure cookies are only enabled for HTTPS requests.
+
+#### Boolean-based configuration
+
+Boolean-based configuration is intended to globally enable or disable a specific cookie attribute.
+
+```ruby
+config.cookies = {
+  secure: true, # mark all cookies as Secure
+  httponly: false, # do not mark any cookies as HttpOnly
+}
+```
+
+#### Hash-based configuration
+
+Hash-based configuration allows for fine-grained control.
+
+```ruby
+config.cookies = {
+  secure: { except: ['_guest'] }, # mark all but the `_guest` cookie as Secure
+  httponly: { only: ['_rails_session'] }, # only mark the `_rails_session` cookie as HttpOnly
+}
+```
+
+#### SameSite cookie configuration
+
+SameSite cookies permit either `Strict` or `Lax` enforcement mode options.
+
+```ruby
+config.cookies = {
+  samesite: {
+    strict: true # mark all cookies as SameSite=Strict
+  }
+}
+```
+
+`Strict` and `Lax` enforcement modes can also be specified using a Hash.
+
+```ruby
+config.cookies = {
+  samesite: {
+    strict: { only: ['_rails_session'] },
+    lax: { only: ['_guest'] }
+  }
+}
+```
+
+#### Hash
+
+`script`/`style-src` hashes can be used to whitelist inline content that is static. This has the benefit of allowing inline content without opening up the possibility of dynamic javascript like you would with a `nonce`.
+
+You can add hash sources directly to your policy :
+
+```ruby
+::SecureHeaders::Configuration.default do |config|
+   config.csp = {
+     default_src: %w('self')
+
+     # this is a made up value but browsers will show the expected hash in the console.
+     script_src: %w(sha256-123456)
+   }
+ end
+ ```
+
+ You can also use the automated inline script detection/collection/computation of hash source values in your app.
+
+ ```bash
+ rake secure_headers:generate_hashes
+ ```
+
+ This will generate a file (`config/config/secure_headers_generated_hashes.yml` by default, you can override by setting `ENV["secure_headers_generated_hashes_file"]`) containing a mapping of file names with the array of hash values found on that page. When ActionView renders a given file, we check if there are any known hashes for that given file. If so, they are added as values to the header.
+
+```yaml
+---
+scripts:
+  app/views/asdfs/index.html.erb:
+  - "'sha256-yktKiAsZWmc8WpOyhnmhQoDf9G2dAZvuBBC+V0LGQhg='"
+styles:
+  app/views/asdfs/index.html.erb:
+  - "'sha256-SLp6LO3rrKDJwsG9uJUxZapb4Wp2Zhj6Bu3l+d9rnAY='"
+  - "'sha256-HSGHqlRoKmHAGTAJ2Rq0piXX4CnEbOl1ArNd6ejp2TE='"
+```
+
+##### Helpers
+
+**This will not compute dynamic hashes** by design. The output of both helpers will be a plain `script`/`style` tag without modification and the known hashes for a given file will be added to `script-src`/`style-src` when `hashed_javascript_tag` and `hashed_style_tag` are used. You can use `raise_error_on_unrecognized_hash = true` to be extra paranoid that you have precomputed hash values for all of your inline content. By default, this will raise an error in non-production environments.
+
+```erb
+<%= hashed_style_tag do %>
+body {
+  background-color: black;
+}
+<% end %>
+
+<%= hashed_style_tag do %>
+body {
+  font-size: 30px;
+  font-color: green;
+}
+<% end %>
+
+<%= hashed_javascript_tag do %>
+console.log(1)
+<% end %>
+```
+
+```
+Content-Security-Policy: ...
+ script-src 'sha256-yktKiAsZWmc8WpOyhnmhQoDf9G2dAZvuBBC+V0LGQhg=' ... ;
+ style-src 'sha256-SLp6LO3rrKDJwsG9uJUxZapb4Wp2Zhj6Bu3l+d9rnAY=' 'sha256-HSGHqlRoKmHAGTAJ2Rq0piXX4CnEbOl1ArNd6ejp2TE=' ...;
+
 ## 3.1.2 Bug fix for regression
 
 See https://github.com/twitter/secureheaders/pull/239

data/README.md

@@ -15,7 +15,7 @@ The gem will automatically apply several headers that are related to security.
 - X-Permitted-Cross-Domain-Policies - [Restrict Adobe Flash Player's access to data](https://www.adobe.com/devnet/adobe-media-server/articles/cross-domain-xml-for-streaming.html)
 - Public Key Pinning - Pin certificate fingerprints in the browser to prevent man-in-the-middle attacks due to compromised Certificate Authorities. [Public Key Pinning Specification](https://tools.ietf.org/html/rfc7469)
 
-It can also mark all http cookies with the secure attribute (when configured to do so).
+It can also mark all http cookies with the Secure, HttpOnly and SameSite attributes (when configured to do so).
 
 `secure_headers` is a library with a global config, per request overrides, and rack middleware that enables you customize your application settings.
 
@@ -31,7 +31,13 @@ All `nil` values will fallback to their default values. `SecureHeaders::OPT_OUT`
 
 ```ruby
 SecureHeaders::Configuration.default do |config|
-  config.secure_cookies = true # mark all cookies as "secure"
+  config.cookies = {
+    secure: true, # mark all cookies as "Secure"
+    httponly: true, # mark all cookies as "HttpOnly"
+    samesite: {
+      strict: true # mark all cookies as SameSite=Strict
+    }
+  }
   config.hsts = "max-age=#{20.years.to_i}; includeSubdomains; preload"
   config.x_frame_options = "DENY"
   config.x_content_type_options = "nosniff"
@@ -195,24 +201,6 @@ Code  | Result
 
 #### Nonce
 
-script/style-nonce can be used to whitelist inline content. To do this, call the `SecureHeaders.content_security_policy_nonce` then set the nonce attributes on the various tags.
-
-Setting a nonce will also set 'unsafe-inline' for browsers that don't support nonces for backwards compatibility. 'unsafe-inline' is ignored if a nonce is present in a directive in compliant browsers.
-
-```erb
-<script nonce="<%= content_security_policy_nonce %>">
-  console.log("whitelisted, will execute")
-</script>
-
-<script nonce="lol">
-  console.log("won't execute, not whitelisted")
-</script>
-
-<script>
-  console.log("won't execute, not whitelisted")
-</script>
-```
-
 You can use a view helper to automatically add nonces to script tags:
 
 ```erb
@@ -240,9 +228,93 @@ body {
 </style>
 ```
 
+```
+
+Content-Security-Policy: ...
+  script-src 'nonce-/jRAxuLJsDXAxqhNBB7gg7h55KETtDQBXe4ZL+xIXwI=' ...;
+  style-src 'nonce-/jRAxuLJsDXAxqhNBB7gg7h55KETtDQBXe4ZL+xIXwI=' ...;
+```
+
+`script`/`style-nonce` can be used to whitelist inline content. To do this, call the `content_security_policy_script_nonce` or `content_security_policy_style_nonce` then set the nonce attributes on the various tags.
+
+```erb
+<script nonce="<%= content_security_policy_script_nonce %>">
+  console.log("whitelisted, will execute")
+</script>
+
+<script nonce="lol">
+  console.log("won't execute, not whitelisted")
+</script>
+
+<script>
+  console.log("won't execute, not whitelisted")
+</script>
+```
+
 #### Hash
 
-The hash feature has been removed, for now.
+`script`/`style-src` hashes can be used to whitelist inline content that is static. This has the benefit of allowing inline content without opening up the possibility of dynamic javascript like you would with a `nonce`.
+
+You can add hash sources directly to your policy :
+
+```ruby
+::SecureHeaders::Configuration.default do |config|
+   config.csp = {
+     default_src: %w('self')
+
+     # this is a made up value but browsers will show the expected hash in the console.
+     script_src: %w(sha256-123456)
+   }
+ end
+ ```
+
+ You can also use the automated inline script detection/collection/computation of hash source values in your app.
+
+ ```bash
+ rake secure_headers:generate_hashes
+ ```
+
+ This will generate a file (`config/config/secure_headers_generated_hashes.yml` by default, you can override by setting `ENV["secure_headers_generated_hashes_file"]`) containing a mapping of file names with the array of hash values found on that page. When ActionView renders a given file, we check if there are any known hashes for that given file. If so, they are added as values to the header.
+
+```yaml
+---
+scripts:
+  app/views/asdfs/index.html.erb:
+  - "'sha256-yktKiAsZWmc8WpOyhnmhQoDf9G2dAZvuBBC+V0LGQhg='"
+styles:
+  app/views/asdfs/index.html.erb:
+  - "'sha256-SLp6LO3rrKDJwsG9uJUxZapb4Wp2Zhj6Bu3l+d9rnAY='"
+  - "'sha256-HSGHqlRoKmHAGTAJ2Rq0piXX4CnEbOl1ArNd6ejp2TE='"
+```
+
+##### Helpers
+
+**This will not compute dynamic hashes** by design. The output of both helpers will be a plain `script`/`style` tag without modification and the known hashes for a given file will be added to `script-src`/`style-src` when `hashed_javascript_tag` and `hashed_style_tag` are used. You can use `raise_error_on_unrecognized_hash = true` to be extra paranoid that you have precomputed hash values for all of your inline content. By default, this will raise an error in non-production environments.
+
+```erb
+<%= hashed_style_tag do %>
+body {
+  background-color: black;
+}
+<% end %>
+
+<%= hashed_style_tag do %>
+body {
+  font-size: 30px;
+  font-color: green;
+}
+<% end %>
+
+<%= hashed_javascript_tag do %>
+console.log(1)
+<% end %>
+```
+
+```
+Content-Security-Policy: ...
+ script-src 'sha256-yktKiAsZWmc8WpOyhnmhQoDf9G2dAZvuBBC+V0LGQhg=' ... ;
+ style-src 'sha256-SLp6LO3rrKDJwsG9uJUxZapb4Wp2Zhj6Bu3l+d9rnAY=' 'sha256-HSGHqlRoKmHAGTAJ2Rq0piXX4CnEbOl1ArNd6ejp2TE=' ...;
+```
 
 ### Public Key Pins
 
@@ -264,6 +336,57 @@ config.hpkp = {
 }
 ```
 
+### Cookies
+
+SecureHeaders supports `Secure`, `HttpOnly` and [`SameSite`](https://tools.ietf.org/html/draft-west-first-party-cookies-07) cookies. These can be defined in the form of a boolean, or as a Hash for more refined configuration.
+
+__Note__: Regardless of the configuration specified, Secure cookies are only enabled for HTTPS requests.
+
+#### Boolean-based configuration
+
+Boolean-based configuration is intended to globally enable or disable a specific cookie attribute.
+
+```ruby
+config.cookies = {
+  secure: true, # mark all cookies as Secure
+  httponly: false, # do not mark any cookies as HttpOnly
+}
+```
+
+#### Hash-based configuration
+
+Hash-based configuration allows for fine-grained control.
+
+```ruby
+config.cookies = {
+  secure: { except: ['_guest'] }, # mark all but the `_guest` cookie as Secure
+  httponly: { only: ['_rails_session'] }, # only mark the `_rails_session` cookie as HttpOnly
+}
+```
+
+#### SameSite cookie configuration
+
+SameSite cookies permit either `Strict` or `Lax` enforcement mode options.
+
+```ruby
+config.cookies = {
+  samesite: {
+    strict: true # mark all cookies as SameSite=Strict
+  }
+}
+```
+
+`Strict` and `Lax` enforcement modes can also be specified using a Hash.
+
+```ruby
+config.cookies = {
+  samesite: {
+    strict: { only: ['_rails_session'] },
+    lax: { only: ['_guest'] }
+  }
+}
+```
+
 ### Using with Sinatra
 
 Here's an example using SecureHeaders for Sinatra applications:

data/lib/secure_headers/configuration.rb

@@ -1,3 +1,5 @@
+require 'yaml'
+
 module SecureHeaders
   class Configuration
     DEFAULT_CONFIG = :default
@@ -102,9 +104,16 @@ module SecureHeaders
 
     attr_writer :hsts, :x_frame_options, :x_content_type_options,
       :x_xss_protection, :x_download_options, :x_permitted_cross_domain_policies,
-      :hpkp, :dynamic_csp, :secure_cookies
+      :hpkp, :dynamic_csp, :cookies
+
+    attr_reader :cached_headers, :csp, :dynamic_csp, :cookies
 
-    attr_reader :cached_headers, :csp, :dynamic_csp, :secure_cookies
+    HASH_CONFIG_FILE = ENV["secure_headers_generated_hashes_file"] || "config/secure_headers_generated_hashes.yml"
+    if File.exists?(HASH_CONFIG_FILE)
+      config = YAML.safe_load(File.open(HASH_CONFIG_FILE))
+      @script_hashes = config["scripts"]
+      @style_hashes = config["styles"]
+    end
 
     def initialize(&block)
       self.hpkp = OPT_OUT
@@ -117,7 +126,7 @@ module SecureHeaders
     # Returns a deep-dup'd copy of this configuration.
     def dup
       copy = self.class.new
-      copy.secure_cookies = @secure_cookies
+      copy.cookies = @cookies
       copy.csp = self.class.send(:deep_copy_if_hash, @csp)
       copy.dynamic_csp = self.class.send(:deep_copy_if_hash, @dynamic_csp)
       copy.cached_headers = self.class.send(:deep_copy_if_hash, @cached_headers)
@@ -172,13 +181,19 @@ module SecureHeaders
       XDownloadOptions.validate_config!(@x_download_options)
       XPermittedCrossDomainPolicies.validate_config!(@x_permitted_cross_domain_policies)
       PublicKeyPins.validate_config!(@hpkp)
+      Cookie.validate_config!(@cookies)
+    end
+
+    def secure_cookies=(secure_cookies)
+      Kernel.warn "#{Kernel.caller.first}: [DEPRECATION] `#secure_cookies=` is deprecated. Please use `#cookies=` to configure secure cookies instead."
+      @cookies = (@cookies || {}).merge(secure: secure_cookies)
     end
 
     protected
 
     def csp=(new_csp)
       if self.dynamic_csp
-        raise IllegalPolicyModificationError, "You are attempting to modify CSP settings directly. Use dynamic_csp= isntead."
+        raise IllegalPolicyModificationError, "You are attempting to modify CSP settings directly. Use dynamic_csp= instead."
       end
 
       @csp = new_csp

data/lib/secure_headers/hash_helper.rb

@@ -0,0 +1,10 @@
+require 'base64'
+
+module SecureHeaders
+  module HashHelper
+    def hash_source(inline_script, digest = :SHA256)
+      base64_hashed_content = Base64.encode64(Digest.const_get(digest).digest(inline_script)).chomp
+      "'#{digest.to_s.downcase}-#{base64_hashed_content}'"
+    end
+  end
+end

data/lib/secure_headers/headers/cookie.rb

@@ -0,0 +1,126 @@
+require 'cgi'
+require 'secure_headers/utils/cookies_config'
+
+module SecureHeaders
+  class CookiesConfigError < StandardError; end
+  class Cookie
+
+    class << self
+      def validate_config!(config)
+        CookiesConfig.new(config).validate!
+      end
+    end
+
+    attr_reader :raw_cookie, :config
+
+    def initialize(cookie, config)
+      @raw_cookie = cookie
+      @config = config
+      @attributes = {
+        httponly: nil,
+        samesite: nil,
+        secure: nil,
+      }
+
+      parse(cookie)
+    end
+
+    def to_s
+      @raw_cookie.dup.tap do |c|
+        c << "; secure" if secure?
+        c << "; HttpOnly" if httponly?
+        c << "; #{samesite_cookie}" if samesite?
+      end
+    end
+
+    def secure?
+      flag_cookie?(:secure) && !already_flagged?(:secure)
+    end
+
+    def httponly?
+      flag_cookie?(:httponly) && !already_flagged?(:httponly)
+    end
+
+    def samesite?
+      flag_samesite? && !already_flagged?(:samesite)
+    end
+
+    private
+
+    def parsed_cookie
+      @parsed_cookie ||= CGI::Cookie.parse(raw_cookie)
+    end
+
+    def already_flagged?(attribute)
+      @attributes[attribute]
+    end
+
+    def flag_cookie?(attribute)
+      case config[attribute]
+      when TrueClass
+        true
+      when Hash
+        conditionally_flag?(config[attribute])
+      else
+        false
+      end
+    end
+
+    def conditionally_flag?(configuration)
+      if(Array(configuration[:only]).any? && (Array(configuration[:only]) & parsed_cookie.keys).any?)
+        true
+      elsif(Array(configuration[:except]).any? && (Array(configuration[:except]) & parsed_cookie.keys).none?)
+        true
+      else
+        false
+      end
+    end
+
+    def samesite_cookie
+      if flag_samesite_lax?
+        "SameSite=Lax"
+      elsif flag_samesite_strict?
+        "SameSite=Strict"
+      end
+    end
+
+    def flag_samesite?
+      flag_samesite_lax? || flag_samesite_strict?
+    end
+
+    def flag_samesite_lax?
+      flag_samesite_enforcement?(:lax)
+    end
+
+    def flag_samesite_strict?
+      flag_samesite_enforcement?(:strict)
+    end
+
+    def flag_samesite_enforcement?(mode)
+      return unless config[:samesite]
+
+      case config[:samesite][mode]
+      when Hash
+        conditionally_flag?(config[:samesite][mode])
+      when TrueClass
+        true
+      else
+        false
+      end
+    end
+
+    def parse(cookie)
+      return unless cookie
+
+      cookie.split(/[;,]\s?/).each do |pairs|
+        name, values = pairs.split('=',2)
+        name = CGI.unescape(name)
+
+        attribute = name.downcase.to_sym
+        if @attributes.has_key?(attribute)
+          @attributes[attribute] = values || true
+        end
+      end
+    end
+  end
+end

data/lib/secure_headers/middleware.rb

@@ -1,7 +1,5 @@
 module SecureHeaders
   class Middleware
-    SECURE_COOKIE_REGEXP = /;\s*secure\s*(;|$)/i.freeze
-
     def initialize(app)
       @app = app
     end
@@ -12,7 +10,7 @@ module SecureHeaders
       status, headers, response = @app.call(env)
 
       config = SecureHeaders.config_for(req)
-      flag_cookies_as_secure!(headers) if config.secure_cookies
+      flag_cookies!(headers, override_secure(env, config.cookies)) if config.cookies
       headers.merge!(SecureHeaders.header_hash_for(req))
       [status, headers, response]
     end
@@ -20,19 +18,35 @@ module SecureHeaders
     private
 
     # inspired by https://github.com/tobmatth/rack-ssl-enforcer/blob/6c014/lib/rack/ssl-enforcer.rb#L183-L194
-    def flag_cookies_as_secure!(headers)
+    def flag_cookies!(headers, config)
       if cookies = headers['Set-Cookie']
         # Support Rails 2.3 / Rack 1.1 arrays as headers
         cookies = cookies.split("\n") unless cookies.is_a?(Array)
 
         headers['Set-Cookie'] = cookies.map do |cookie|
-          if cookie !~ SECURE_COOKIE_REGEXP
-            "#{cookie}; secure"
-          else
-            cookie
-          end
+          SecureHeaders::Cookie.new(cookie, config).to_s
         end.join("\n")
       end
     end
+
+    # disable Secure cookies for non-https requests
+    def override_secure(env, config = {})
+      if scheme(env) != 'https'
+        config.merge!(secure: false)
+      end
+
+      config
+    end
+
+    # derived from https://github.com/tobmatth/rack-ssl-enforcer/blob/6c014/lib/rack/ssl-enforcer.rb#L119
+    def scheme(env)
+      if env['HTTPS'] == 'on' || env['HTTP_X_SSL_REQUEST'] == 'on'
+        'https'
+      elsif env['HTTP_X_FORWARDED_PROTO']
+        env['HTTP_X_FORWARDED_PROTO'].split(',')[0]
+      else
+        env['rack.url_scheme']
+      end
+    end
   end
 end

data/lib/secure_headers/railtie.rb

@@ -13,6 +13,10 @@ if defined?(Rails::Railtie)
         Rails.application.config.middleware.insert_before 0, SecureHeaders::Middleware
       end
 
+      rake_tasks do
+        load File.expand_path(File.join('..', '..', 'lib', 'tasks', 'tasks.rake'), File.dirname(__FILE__))
+      end
+
       initializer "secure_headers.action_controller" do
         ActiveSupport.on_load(:action_controller) do
           include SecureHeaders

data/lib/secure_headers/utils/cookies_config.rb

@@ -0,0 +1,94 @@
+module SecureHeaders
+  class CookiesConfig
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def validate!
+      return if config.nil? || config == SecureHeaders::OPT_OUT
+
+      validate_config!
+      validate_secure_config! if config[:secure]
+      validate_httponly_config! if config[:httponly]
+      validate_samesite_config! if config[:samesite]
+    end
+
+    private
+
+    def validate_config!
+      raise CookiesConfigError.new("config must be a hash.") unless is_hash?(config)
+    end
+
+    def validate_secure_config!
+      validate_hash_or_boolean!(:secure)
+      validate_exclusive_use_of_hash_constraints!(config[:secure], :secure)
+    end
+
+    def validate_httponly_config!
+      validate_hash_or_boolean!(:httponly)
+      validate_exclusive_use_of_hash_constraints!(config[:httponly], :httponly)
+    end
+
+    def validate_samesite_config!
+      raise CookiesConfigError.new("samesite cookie config must be a hash") unless is_hash?(config[:samesite])
+
+      validate_samesite_boolean_config!
+      validate_samesite_hash_config!
+    end
+
+    # when configuring with booleans, only one enforcement is permitted
+    def validate_samesite_boolean_config!
+      if config[:samesite].key?(:lax) && config[:samesite][:lax].is_a?(TrueClass) && config[:samesite].key?(:strict)
+        raise CookiesConfigError.new("samesite cookie config is invalid, combination use of booleans and Hash to configure lax and strict enforcement is not permitted.")
+      elsif config[:samesite].key?(:strict) && config[:samesite][:strict].is_a?(TrueClass) && config[:samesite].key?(:lax)
+        raise CookiesConfigError.new("samesite cookie config is invalid, combination use of booleans and Hash to configure lax and strict enforcement is not permitted.")
+      end
+    end
+
+    def validate_samesite_hash_config!
+      # validate Hash-based samesite configuration
+      if is_hash?(config[:samesite][:lax])
+        validate_exclusive_use_of_hash_constraints!(config[:samesite][:lax], 'samesite lax')
+
+        if is_hash?(config[:samesite][:strict])
+          validate_exclusive_use_of_hash_constraints!(config[:samesite][:strict], 'samesite strict')
+          validate_exclusive_use_of_samesite_enforcement!(:only)
+          validate_exclusive_use_of_samesite_enforcement!(:except)
+        end
+      end
+    end
+
+    def validate_hash_or_boolean!(attribute)
+      if !(is_hash?(config[attribute]) || is_boolean?(config[attribute]))
+        raise CookiesConfigError.new("#{attribute} cookie config must be a hash or boolean")
+      end
+    end
+
+    # validate exclusive use of only or except but not both at the same time
+    def validate_exclusive_use_of_hash_constraints!(conf, attribute)
+      return unless is_hash?(conf)
+
+      if conf.key?(:only) && conf.key?(:except)
+        raise CookiesConfigError.new("#{attribute} cookie config is invalid, simultaneous use of conditional arguments `only` and `except` is not permitted.")
+      end
+    end
+
+    # validate exclusivity of only and except members within strict and lax
+    def validate_exclusive_use_of_samesite_enforcement!(attribute)
+      if (intersection = (config[:samesite][:lax].fetch(attribute, []) & config[:samesite][:strict].fetch(attribute, []))).any?
+        raise CookiesConfigError.new("samesite cookie config is invalid, cookie(s) #{intersection.join(', ')} cannot be enforced as lax and strict")
+      end
+    end
+
+    def is_hash?(obj)
+      obj && obj.is_a?(Hash)
+    end
+
+    def is_boolean?(obj)
+      obj && (obj.is_a?(TrueClass) || obj.is_a?(FalseClass))
+    end
+  end
+end