add report-to directive, supported by reporting-endpoints header, account for backwards compatibility with report-uri

Author: KyFaSt

lib/secure_headers.rb

@@ -11,6 +11,7 @@
 require "secure_headers/headers/referrer_policy"
 require "secure_headers/headers/clear_site_data"
 require "secure_headers/headers/expect_certificate_transparency"
+require "secure_headers/headers/reporting_endpoints"
 require "secure_headers/middleware"
 require "secure_headers/railtie"
 require "secure_headers/view_helper"

lib/secure_headers/configuration.rb

@@ -131,6 +131,7 @@ def deep_copy_if_hash(value)
       csp: ContentSecurityPolicy,
       csp_report_only: ContentSecurityPolicy,
       cookies: Cookie,
+      reporting_endpoints: ReportingEndpoints,
     }.freeze
 
     CONFIG_ATTRIBUTES = CONFIG_ATTRIBUTES_TO_HEADER_CLASSES.keys.freeze
@@ -167,6 +168,7 @@ def initialize(&block)
       @x_permitted_cross_domain_policies = nil
       @x_xss_protection = nil
       @expect_certificate_transparency = nil
+      @reporting_endpoints = nil
 
       self.referrer_policy = OPT_OUT
       self.csp = ContentSecurityPolicyConfig.new(ContentSecurityPolicyConfig::DEFAULT)
@@ -192,6 +194,7 @@ def dup
       copy.clear_site_data = @clear_site_data
       copy.expect_certificate_transparency = @expect_certificate_transparency
       copy.referrer_policy = @referrer_policy
+      copy.reporting_endpoints = self.class.send(:deep_copy_if_hash, @reporting_endpoints)
       copy
     end
 

lib/secure_headers/headers/content_security_policy.rb

@@ -63,6 +63,8 @@ def build_value
           build_sandbox_list_directive(directive_name)
         when :media_type_list
           build_media_type_list_directive(directive_name)
+        when :report_to_endpoint
+          build_report_to_directive(directive_name)
         end
       end.compact.join("; ")
     end
@@ -100,6 +102,13 @@ def build_media_type_list_directive(directive)
       end
     end
 
+    def build_report_to_directive(directive)
+      return unless endpoint_name = @config.directive_value(directive)
+      if endpoint_name && endpoint_name.is_a?(String) && !endpoint_name.empty?
+        [symbol_to_hyphen_case(directive), endpoint_name].join(" ")
+      end
+    end
+
     # Private: builds a string that represents one directive in a minified form.
     #
     # directive_name - a symbol representing the various ALL_DIRECTIVES
@@ -179,11 +188,12 @@ def append_nonce(source_list, nonce)
     end
 
     # Private: return the list of directives,
-    # starting with default-src and ending with report-uri.
+    # starting with default-src and ending with reporting directives (alphabetically ordered).
     def directives
       [
         DEFAULT_SRC,
         BODY_DIRECTIVES,
+        REPORT_TO,
         REPORT_URI,
       ].flatten
     end

lib/secure_headers/headers/policy_management.rb

@@ -39,6 +39,7 @@ def self.included(base)
     SCRIPT_SRC = :script_src
     STYLE_SRC = :style_src
     REPORT_URI = :report_uri
+    REPORT_TO = :report_to
 
     DIRECTIVES_1_0 = [
       DEFAULT_SRC,
@@ -51,7 +52,8 @@ def self.included(base)
       SANDBOX,
       SCRIPT_SRC,
       STYLE_SRC,
-      REPORT_URI
+      REPORT_URI,
+      REPORT_TO
     ].freeze
 
     BASE_URI = :base_uri
@@ -110,9 +112,9 @@ def self.included(base)
 
     ALL_DIRECTIVES = (DIRECTIVES_1_0 + DIRECTIVES_2_0 + DIRECTIVES_3_0 + DIRECTIVES_EXPERIMENTAL).uniq.sort
 
-    # Think of default-src and report-uri as the beginning and end respectively,
+    # Think of default-src and report-uri/report-to as the beginning and end respectively,
     # everything else is in between.
-    BODY_DIRECTIVES = ALL_DIRECTIVES - [DEFAULT_SRC, REPORT_URI]
+    BODY_DIRECTIVES = ALL_DIRECTIVES - [DEFAULT_SRC, REPORT_URI, REPORT_TO]
 
     DIRECTIVE_VALUE_TYPES = {
       BASE_URI                  => :source_list,
@@ -132,6 +134,7 @@ def self.included(base)
       REQUIRE_SRI_FOR           => :require_sri_for_list,
       REQUIRE_TRUSTED_TYPES_FOR => :require_trusted_types_for_list,
       REPORT_URI                => :source_list,
+      REPORT_TO                 => :report_to_endpoint,
       PREFETCH_SRC              => :source_list,
       SANDBOX                   => :sandbox_list,
       SCRIPT_SRC                => :source_list,
@@ -159,6 +162,7 @@ def self.included(base)
       FRAME_ANCESTORS,
       NAVIGATE_TO,
       REPORT_URI,
+      REPORT_TO,
     ]
 
     FETCH_SOURCES = ALL_DIRECTIVES - NON_FETCH_SOURCES - NON_SOURCE_LIST_SOURCES
@@ -344,6 +348,8 @@ def validate_directive!(directive, value)
           validate_require_sri_source_expression!(directive, value)
         when :require_trusted_types_for_list
           validate_require_trusted_types_for_source_expression!(directive, value)
+        when :report_to_endpoint
+          validate_report_to_endpoint_expression!(directive, value)
         else
           raise ContentSecurityPolicyConfigError.new("Unknown directive #{directive}")
         end
@@ -398,6 +404,18 @@ def validate_require_trusted_types_for_source_expression!(directive, require_tru
         end
       end
 
+      # Private: validates that a report-to endpoint expression:
+      # 1. is a string
+      # 2. is not empty
+      def validate_report_to_endpoint_expression!(directive, endpoint_name)
+        unless endpoint_name.is_a?(String)
+          raise ContentSecurityPolicyConfigError.new("#{directive} must be a string. Found #{endpoint_name.class} value")
+        end
+        if endpoint_name.empty?
+          raise ContentSecurityPolicyConfigError.new("#{directive} must not be empty")
+        end
+      end
+
       # Private: validates that a source expression:
       # 1. is an array of strings
       # 2. does not contain any deprecated, now invalid values (inline, eval, self, none)

lib/secure_headers/headers/reporting_endpoints.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+module SecureHeaders
+  class ReportingEndpointsConfigError < StandardError; end
+  class ReportingEndpoints
+    HEADER_NAME = "reporting-endpoints".freeze
+
+    class << self
+      # Public: generate a Reporting-Endpoints header.
+      #
+      # The config should be a Hash of endpoint names to URLs.
+      # Example: { "csp-endpoint" => "https://example.com/reports" }
+      #
+      # Returns nil if config is OPT_OUT or nil, or a header name and
+      # formatted header value based on the config.
+      def make_header(config = nil)
+        return if config.nil? || config == OPT_OUT
+        validate_config!(config)
+        [HEADER_NAME, format_endpoints(config)]
+      end
+
+      def validate_config!(config)
+        case config
+        when nil, OPT_OUT
+          # valid
+        when Hash
+          config.each_pair do |name, url|
+            unless name.is_a?(String) && !name.empty?
+              raise ReportingEndpointsConfigError.new("Endpoint name must be a non-empty string, got: #{name.inspect}")
+            end
+            unless url.is_a?(String) && !url.empty?
+              raise ReportingEndpointsConfigError.new("Endpoint URL must be a non-empty string, got: #{url.inspect}")
+            end
+            unless url.start_with?("https://")
+              raise ReportingEndpointsConfigError.new("Endpoint URLs must use https, got: #{url.inspect}")
+            end
+          end
+        else
+          raise TypeError.new("Must be a Hash of endpoint names to URLs. Found #{config.class}: #{config}")
+        end
+      end
+
+      private
+
+      def format_endpoints(config)
+        config.map do |name, url|
+          %{#{name}="#{url}"}
+        end.join(", ")
+      end
+    end
+  end
+end

spec/lib/secure_headers/headers/content_security_policy_spec.rb

@@ -210,6 +210,32 @@ module SecureHeaders
         csp = ContentSecurityPolicy.new({trusted_types: %w(blahblahpolicy 'allow-duplicates')})
         expect(csp.value).to eq("trusted-types blahblahpolicy 'allow-duplicates'")
       end
+
+      it "supports report-to directive with endpoint name" do
+        csp = ContentSecurityPolicy.new({default_src: %w('self'), report_to: "csp-endpoint"})
+        expect(csp.value).to eq("default-src 'self'; report-to csp-endpoint")
+      end
+
+      it "includes report-to before report-uri in alphabetical order" do
+        csp = ContentSecurityPolicy.new({default_src: %w('self'), report_uri: %w(/csp_report), report_to: "csp-endpoint"})
+        expect(csp.value).to eq("default-src 'self'; report-to csp-endpoint; report-uri /csp_report")
+      end
+
+      it "does not add report-to if the endpoint name is empty" do
+        csp = ContentSecurityPolicy.new({default_src: %w('self'), report_to: ""})
+        expect(csp.value).to eq("default-src 'self'")
+      end
+
+      it "does not add report-to if not provided" do
+        csp = ContentSecurityPolicy.new({default_src: %w('self')})
+        expect(csp.value).not_to include("report-to")
+      end
+
+      it "supports report-to without report-uri" do
+        csp = ContentSecurityPolicy.new({default_src: %w('self'), report_to: "reporting-endpoint-name"})
+        expect(csp.value).to eq("default-src 'self'; report-to reporting-endpoint-name")
+      end
     end
   end
 end
+

spec/lib/secure_headers/headers/policy_management_spec.rb

@@ -169,6 +169,30 @@ module SecureHeaders
           ContentSecurityPolicy.validate_config!(ContentSecurityPolicyReportOnlyConfig.new(default_opts.merge(report_only: true)))
         end.to_not raise_error
       end
+
+      it "requires report_to to be a string" do
+        expect do
+          ContentSecurityPolicy.validate_config!(ContentSecurityPolicyConfig.new(default_opts.merge(report_to: ["endpoint"])))
+        end.to raise_error(ContentSecurityPolicyConfigError)
+      end
+
+      it "rejects empty report_to endpoint names" do
+        expect do
+          ContentSecurityPolicy.validate_config!(ContentSecurityPolicyConfig.new(default_opts.merge(report_to: "")))
+        end.to raise_error(ContentSecurityPolicyConfigError)
+      end
+
+      it "accepts valid report_to endpoint names" do
+        expect do
+          ContentSecurityPolicy.validate_config!(ContentSecurityPolicyConfig.new(default_opts.merge(report_to: "csp-endpoint")))
+        end.to_not raise_error
+      end
+
+      it "accepts report_to with hyphens and underscores" do
+        expect do
+          ContentSecurityPolicy.validate_config!(ContentSecurityPolicyConfig.new(default_opts.merge(report_to: "csp-endpoint_name-123")))
+        end.to_not raise_error
+      end
     end
 
     describe "#combine_policies" do

spec/lib/secure_headers/headers/reporting_endpoints_spec.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+require "spec_helper"
+
+module SecureHeaders
+  describe ReportingEndpoints do
+    describe "#make_header" do
+      it "returns nil when config is nil" do
+        expect(ReportingEndpoints.make_header(nil)).to be_nil
+      end
+
+      it "returns nil when config is OPT_OUT" do
+        expect(ReportingEndpoints.make_header(OPT_OUT)).to be_nil
+      end
+
+      it "formats a single endpoint" do
+        config = { "csp-endpoint" => "https://example.com/csp-reports" }
+        header_name, value = ReportingEndpoints.make_header(config)
+        expect(header_name).to eq("reporting-endpoints")
+        expect(value).to eq('csp-endpoint="https://example.com/csp-reports"')
+      end
+
+      it "formats multiple endpoints" do
+        config = {
+          "csp-endpoint" => "https://example.com/csp-reports",
+          "permissions-endpoint" => "https://example.com/permissions-reports"
+        }
+        header_name, value = ReportingEndpoints.make_header(config)
+        expect(header_name).to eq("reporting-endpoints")
+        # Order may vary, so check both endpoints are present
+        expect(value).to include('csp-endpoint="https://example.com/csp-reports"')
+        expect(value).to include('permissions-endpoint="https://example.com/permissions-reports"')
+        expect(value).to include(",")
+      end
+
+      it "validates that endpoints are present" do
+        expect do
+          ReportingEndpoints.validate_config!({})
+        end.to_not raise_error
+      end
+    end
+
+    describe "#validate_config!" do
+      it "accepts nil" do
+        expect do
+          ReportingEndpoints.validate_config!(nil)
+        end.to_not raise_error
+      end
+
+      it "accepts OPT_OUT" do
+        expect do
+          ReportingEndpoints.validate_config!(OPT_OUT)
+        end.to_not raise_error
+      end
+
+      it "accepts valid endpoint configuration" do
+        expect do
+          ReportingEndpoints.validate_config!({
+            "csp-violations" => "https://example.com/reports"
+          })
+        end.to_not raise_error
+      end
+
+      it "rejects non-hash config" do
+        expect do
+          ReportingEndpoints.validate_config!("not a hash")
+        end.to raise_error(TypeError)
+      end
+
+      it "rejects empty endpoint name" do
+        expect do
+          ReportingEndpoints.validate_config!({
+            "" => "https://example.com/reports"
+          })
+        end.to raise_error(ReportingEndpointsConfigError)
+      end
+
+      it "rejects non-string endpoint name" do
+        expect do
+          ReportingEndpoints.validate_config!({
+            123 => "https://example.com/reports"
+          })
+        end.to raise_error(ReportingEndpointsConfigError)
+      end
+
+      it "rejects empty endpoint URL" do
+        expect do
+          ReportingEndpoints.validate_config!({
+            "csp-endpoint" => ""
+          })
+        end.to raise_error(ReportingEndpointsConfigError)
+      end
+
+      it "rejects non-string endpoint URL" do
+        expect do
+          ReportingEndpoints.validate_config!({
+            "csp-endpoint" => 123
+          })
+        end.to raise_error(ReportingEndpointsConfigError)
+      end
+
+      it "rejects non-https URLs" do
+        expect do
+          ReportingEndpoints.validate_config!({
+            "csp-endpoint" => "http://example.com/reports"
+          })
+        end.to raise_error(ReportingEndpointsConfigError, /must use https/)
+      end
+    end
+  end
+end