otto 2.3.1 → 2.4.0

data/lib/otto/security/config.rb

@@ -44,6 +44,11 @@ class Otto
       # depth mode; CIDR-walk is unaffected.
       TRUSTED_PROXY_HEADERS = %w[X-Forwarded-For Forwarded Both].freeze
 
+      # Endpoint group name shared by the CSP `report-to` directive and the
+      # `Reporting-Endpoints` response header (modern Reporting API). Browsers
+      # match the directive's group to the header's key, so both must agree.
+      CSP_REPORTING_GROUP = 'otto-csp'
+
       # Error raised when CSRF protection is enabled in production without an
       # explicitly configured secret. A randomly-generated per-process secret
       # silently breaks token verification across workers and restarts, so we
@@ -63,7 +68,8 @@ class Otto
                   :trusted_proxies, :require_secure_cookies,
                   :security_headers,
                   :csp_nonce_enabled, :debug_csp, :mcp_auth,
-                  :ip_privacy_config, :trusted_proxy_depth, :trusted_proxy_header
+                  :ip_privacy_config, :trusted_proxy_depth, :trusted_proxy_header,
+                  :csp_report_uri, :csp_report_to_url, :csp_violation_callback
 
       # Initialize security configuration with safe defaults
       #
@@ -86,6 +92,10 @@ class Otto
         @input_validation       = true
         @csp_nonce_enabled      = false
         @debug_csp              = false
+        @csp_policy             = nil
+        @csp_report_uri         = nil
+        @csp_report_to_url      = nil
+        @csp_violation_callback = nil
         @rate_limiting_config   = { custom_rules: {} }
         @ip_privacy_config      = Otto::Privacy::Config.new
 
@@ -343,7 +353,8 @@ class Otto
       def enable_csp!(policy = "default-src 'self'")
         ensure_not_frozen!
 
-        @security_headers['content-security-policy'] = policy
+        @csp_policy = policy
+        @security_headers['content-security-policy'] = build_static_csp(policy)
       end
 
       # Enable Content Security Policy (CSP) with nonce support
@@ -389,6 +400,110 @@ class Otto
         @debug_csp
       end
 
+      # Configure the path browsers should POST CSP violation reports to.
+      #
+      # Setting this does two things:
+      # 1. A `report-uri <path>` directive is appended to every emitted CSP
+      #    policy — both the static policy from {#enable_csp!} and the per-request
+      #    nonce policy from {#generate_nonce_csp} — so browsers know where to
+      #    send violations.
+      # 2. {Otto::Security::CSP::ReportMiddleware} activates for that path (it is
+      #    inert until a report URI is set).
+      #
+      # When nil/empty (the default), NO reporting directive is emitted and the
+      # policy output is byte-identical to Otto's historical output.
+      #
+      # For the turnkey setup that also injects the receiving middleware, prefer
+      # {Otto::Security::Core#enable_csp_reporting!} on the Otto instance.
+      #
+      # @param uri [String, nil] path browsers POST reports to (matched against
+      #   `PATH_INFO`, e.g. `/_/csp-report`), or nil to disable reporting. A
+      #   value without a leading slash is coerced to an absolute path so it
+      #   matches the slash-prefixed `PATH_INFO` the middleware compares against.
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      def csp_report_uri=(uri)
+        ensure_not_frozen!
+
+        @csp_report_uri = normalize_report_path(uri)
+        rebuild_static_csp_with_reporting!
+      end
+
+      # Configure the absolute URL browsers should POST CSP violation reports to
+      # via the modern Reporting API (Reporting-Endpoints header + `report-to`
+      # directive), complementing the legacy path-based {#csp_report_uri=}.
+      #
+      # Setting this does two things:
+      # 1. A `report-to #{CSP_REPORTING_GROUP}` directive is appended to every
+      #    emitted CSP policy (static and per-request nonce alike), and a
+      #    `Reporting-Endpoints` response header maps that group to this URL.
+      # 2. Modern browsers (which have deprecated `report-uri`) deliver reports
+      #    as `application/reports+json` to this endpoint — already parsed by
+      #    {Otto::Security::CSP::Parser}.
+      #
+      # The value MUST be an ABSOLUTE URL (Reporting-Endpoints does not accept a
+      # bare path). Point it at the same receiver as {#csp_report_uri=}: its path
+      # component should equal the report URI so {Otto::Security::CSP::ReportMiddleware}
+      # (which matches on PATH_INFO) intercepts modern reports too.
+      #
+      # When nil/empty (the default), NO `report-to` directive or
+      # `Reporting-Endpoints` header is emitted and policy output is
+      # byte-identical to Otto's historical output.
+      #
+      # @param url [String, nil] absolute URL for the Reporting API endpoint, or
+      #   nil to disable modern reporting.
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      def csp_report_to_url=(url)
+        ensure_not_frozen!
+
+        @csp_report_to_url = normalize_report_uri(url)
+        if @csp_report_to_url
+          @security_headers['reporting-endpoints'] = reporting_endpoints_header
+        else
+          @security_headers.delete('reporting-endpoints')
+        end
+        rebuild_static_csp_with_reporting!
+      end
+
+      # Register the callback invoked once per parsed CSP violation report.
+      #
+      # The block receives an {Otto::Security::CSP::Report}. Your application
+      # decides what to do — log, emit a metric, store, forward, or ignore. Otto
+      # adds no storage or database coupling.
+      #
+      # Registering a second callback REPLACES the first (last registration
+      # wins), matching the singular `on_csp_violation` semantics. Calling this
+      # with NO block clears (unregisters) any previously-set callback.
+      #
+      # SECURITY NOTE: report URL fields may carry sensitive path/query data in
+      # some applications. Redact them in your callback before logging if needed;
+      # Otto passes them through un-redacted (see {Otto::Security::CSP::Report}).
+      #
+      # @yieldparam report [Otto::Security::CSP::Report] a normalized report
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      def on_csp_violation(&block)
+        ensure_not_frozen!
+
+        @csp_violation_callback = block
+      end
+
+      # Invoke the registered violation callback for a report, isolating any
+      # error it raises. A misbehaving application callback must never break the
+      # report receiver (which always answers 204).
+      #
+      # @param report [Otto::Security::CSP::Report]
+      # @return [void]
+      def dispatch_csp_violation(report)
+        callback = @csp_violation_callback
+        return if callback.nil?
+
+        callback.call(report)
+      rescue StandardError => e
+        Otto.logger.error("[Otto::CSP] violation callback raised #{e.class}: #{e.message}")
+      end
+
       # Generate a CSP policy string with the provided nonce
       #
       # @param nonce [String] The nonce value to include in the CSP
@@ -396,6 +511,10 @@ class Otto
       # @return [String] Complete CSP policy string
       def generate_nonce_csp(nonce, development_mode: false)
         directives = development_mode ? development_csp_directives(nonce) : production_csp_directives(nonce)
+        report_uri_directive = csp_report_directive
+        report_to_directive  = csp_report_to_directive
+        directives += ["#{report_uri_directive};"] if report_uri_directive
+        directives += ["#{report_to_directive};"] if report_to_directive
         directives.join(' ')
       end
 
@@ -705,6 +824,112 @@ class Otto
         defined?(Otto) && Otto.respond_to?(:env?) && Otto.env?(:production, :prod)
       end
 
+      # Normalize a configured report URI: strip surrounding whitespace and
+      # treat a blank string as "not configured" (nil).
+      #
+      # @param uri [String, nil]
+      # @return [String, nil]
+      def normalize_report_uri(uri)
+        return nil if uri.nil?
+
+        stripped = uri.to_s.strip
+        stripped.empty? ? nil : stripped
+      end
+
+      # Normalize a configured report PATH: the local endpoint the receiver
+      # matches on `PATH_INFO`. Same strip/blank-to-nil handling as
+      # {#normalize_report_uri}, but a bare relative value is coerced to an
+      # absolute path — a value like `"csp-report"` would otherwise (a) never
+      # equal the slash-prefixed `PATH_INFO` the middleware compares against, and
+      # (b) be resolved by browsers relative to the document URL. An absolute URL
+      # (contains a scheme) is left untouched.
+      #
+      # @param uri [String, nil]
+      # @return [String, nil]
+      def normalize_report_path(uri)
+        normalized = normalize_report_uri(uri)
+        return nil if normalized.nil?
+        return normalized if normalized.start_with?('/') || normalized.include?('://')
+
+        "/#{normalized}"
+      end
+
+      # Recompute the stored static CSP header so the report-uri / report-to
+      # directives track the current settings, independent of the order in which
+      # {#enable_csp!} and the report setters were called.
+      #
+      # The base is normally @csp_policy (set by {#enable_csp!}). When a static
+      # CSP was instead injected directly through {#set_security_headers} (so
+      # @csp_policy is nil), adopt that header as the base the first time a report
+      # directive is configured — so reporting augments it too. Capturing it as
+      # the pristine base keeps later rebuilds idempotent. A static header set
+      # directly AFTER reporting is configured bypasses this and remains the
+      # application's to manage.
+      #
+      # @return [void]
+      def rebuild_static_csp_with_reporting!
+        @csp_policy ||= adoptable_static_csp_base
+        return if @csp_policy.nil?
+
+        @security_headers['content-security-policy'] = build_static_csp(@csp_policy)
+      end
+
+      # The current static CSP header when it can serve as a pristine base policy
+      # for reporting augmentation: present and not already carrying a report
+      # directive (adopting one that does would double-append). Otherwise nil —
+      # notably, the nonce path sets no static header, so nothing is adopted.
+      #
+      # @return [String, nil]
+      def adoptable_static_csp_base
+        existing = @security_headers['content-security-policy']
+        return nil if existing.nil? || existing.empty?
+        return nil if existing.include?('report-uri') || existing.include?('report-to')
+
+        existing
+      end
+
+      # The `report-uri` directive to append to emitted policies, or nil when no
+      # report URI is configured. No trailing semicolon (callers add their own
+      # separator to match each policy style).
+      #
+      # @return [String, nil]
+      def csp_report_directive
+        return nil if @csp_report_uri.nil? || @csp_report_uri.empty?
+
+        "report-uri #{@csp_report_uri}"
+      end
+
+      # The `report-to` directive (modern Reporting API) to append to emitted
+      # policies, or nil when no reporting endpoint URL is configured. Its group
+      # name matches the Reporting-Endpoints header. No trailing semicolon.
+      #
+      # @return [String, nil]
+      def csp_report_to_directive
+        return nil if @csp_report_to_url.nil? || @csp_report_to_url.empty?
+
+        "report-to #{CSP_REPORTING_GROUP}"
+      end
+
+      # The `Reporting-Endpoints` response header value mapping the CSP reporting
+      # group to the configured absolute endpoint URL, e.g.
+      # `otto-csp="https://example.com/_/csp-report"`.
+      #
+      # @return [String]
+      def reporting_endpoints_header
+        %(#{CSP_REPORTING_GROUP}="#{@csp_report_to_url}")
+      end
+
+      # Build the stored static-CSP header value: the base policy plus the
+      # optional report-uri and report-to directives. Byte-identical to the bare
+      # policy when no reporting is configured, so existing static-CSP output is
+      # unchanged.
+      #
+      # @param policy [String] the base policy passed to {#enable_csp!}
+      # @return [String]
+      def build_static_csp(policy)
+        [policy, csp_report_directive, csp_report_to_directive].compact.join('; ')
+      end
+
       # Generate CSP directives for development environment
       #
       # Development mode allows inline scripts/styles and hot reloading connections

data/lib/otto/security/configurator.rb

@@ -198,6 +198,44 @@ class Otto
         @security_config.enable_csp_with_nonce!(debug: debug)
       end
 
+      # Enable turnkey CSP violation reporting: set the report URI (appends a
+      # `report-uri` directive to emitted policies), register the callback, and
+      # inject {Otto::Security::CSP::ReportMiddleware} pinned OUTERMOST so it
+      # intercepts report POSTs ahead of CSRF regardless of enable order.
+      #
+      # @param report_uri [String] path browsers POST reports to (matched against PATH_INFO)
+      # @param endpoint_url [String, nil] absolute URL for the modern Reporting
+      #   API endpoint (emits `report-to` + `Reporting-Endpoints`); nil emits
+      #   only the legacy `report-uri`
+      # @yieldparam report [Otto::Security::CSP::Report] a normalized violation report
+      def enable_csp_reporting!(report_uri, endpoint_url: nil, &block)
+        @security_config.csp_report_uri = report_uri
+        @security_config.csp_report_to_url = endpoint_url unless endpoint_url.nil?
+        @security_config.on_csp_violation(&block) if block
+
+        return if middleware_enabled?(Otto::Security::CSP::ReportMiddleware)
+
+        @middleware_stack.add_with_position(Otto::Security::CSP::ReportMiddleware, position: :outermost)
+      end
+
+      # Configure the CSP violation report path without injecting middleware.
+      # Prefer {#enable_csp_reporting!} for the full turnkey setup.
+      #
+      # @param uri [String, nil] report path (matched against PATH_INFO), or nil to disable
+      def csp_report_uri=(uri)
+        @security_config.csp_report_uri = uri
+      end
+
+      # Configure the absolute URL for the modern Reporting API endpoint
+      # (`report-to` directive + `Reporting-Endpoints` header) without injecting
+      # middleware. Prefer {#enable_csp_reporting!} with `endpoint_url:` for the
+      # full turnkey setup.
+      #
+      # @param url [String, nil] absolute endpoint URL, or nil to disable modern reporting
+      def csp_report_to_url=(url)
+        @security_config.csp_report_to_url = url
+      end
+
       # Add a single authentication strategy
       #
       # Part of the Security::Configurator facade for consolidated configuration.

data/lib/otto/security/core.rb

@@ -135,6 +135,68 @@ class Otto
         @security_config.enable_csp_with_nonce!(debug: debug)
       end
 
+      # Enable turnkey Content Security Policy violation reporting.
+      #
+      # This is the receiving half of Otto's CSP support. It:
+      # 1. Configures the report path (`config.csp_report_uri = report_uri`), so a
+      #    `report-uri` directive is appended to every emitted CSP policy (static
+      #    {#enable_csp!} and nonce {#enable_csp_with_nonce!} alike).
+      # 2. Registers your violation callback (if a block is given).
+      # 3. Injects {Otto::Security::CSP::ReportMiddleware} so browser POSTs to the
+      #    report path are received, parsed, and dispatched to the callback —
+      #    always answered with 204 and never touching your routes.
+      #
+      # The middleware is pinned to run OUTERMOST (ahead of CSRF and every other
+      # middleware), so it short-circuits report POSTs before CSRF validation —
+      # browsers can post reports without a CSRF token. This holds regardless of
+      # the order in which you enable security features.
+      #
+      # SECURITY / DoS: running outermost also means the receiver sits ahead of
+      # rate limiting (rate limiting is inner middleware). This is intentional —
+      # a public, unauthenticated report endpoint cannot depend on CSRF, session,
+      # or per-client throttling state — but it means a client can POST reports
+      # up to the 64 KiB body cap and invoke your callback on each one. Keep the
+      # callback cheap and bounded (sample or aggregate; avoid unbounded
+      # synchronous I/O), and put request-rate control for this path at the edge
+      # (reverse proxy / CDN / WAF) rather than expecting Otto to throttle it.
+      #
+      # To (re)assign the callback later without touching the wiring, use the
+      # config primitive directly: `otto.security_config.on_csp_violation { ... }`.
+      #
+      # For modern browsers (which have deprecated `report-uri`), also pass
+      # `endpoint_url:` — an ABSOLUTE URL whose path is `report_uri`. Otto then
+      # emits a `report-to` directive plus a `Reporting-Endpoints` header so those
+      # browsers deliver `application/reports+json` to the same receiver.
+      #
+      # @param report_uri [String] path browsers POST reports to (matched against
+      #   `PATH_INFO`, e.g. `/_/csp-report`).
+      # @param endpoint_url [String, nil] absolute URL for the modern Reporting
+      #   API endpoint (e.g. `https://example.com/_/csp-report`); nil emits only
+      #   the legacy `report-uri`.
+      # @yieldparam report [Otto::Security::CSP::Report] a normalized violation report
+      # @return [void]
+      # @example
+      #   otto.enable_csp_with_nonce!
+      #   otto.enable_csp_reporting!('/_/csp-report',
+      #     endpoint_url: 'https://example.com/_/csp-report') do |report|
+      #     Otto.logger.warn("CSP violation: #{report.to_h}")
+      #   end
+      def enable_csp_reporting!(report_uri, endpoint_url: nil, &block)
+        ensure_not_frozen!
+
+        @security_config.csp_report_uri = report_uri
+        @security_config.csp_report_to_url = endpoint_url unless endpoint_url.nil?
+        @security_config.on_csp_violation(&block) if block
+
+        return if @middleware.includes?(Otto::Security::CSP::ReportMiddleware)
+
+        # Pin OUTERMOST so it intercepts report POSTs ahead of CSRF regardless of
+        # the order security features are enabled in. add_with_position fires the
+        # stack's on_change callback, which rebuilds @app (wired in
+        # Otto#initialize_core_state) — no explicit build_app! needed.
+        @middleware.add_with_position(Otto::Security::CSP::ReportMiddleware, position: :outermost)
+      end
+
       # Add an authentication strategy with a registered name
       #
       # This is the primary public API for registering authentication strategies.

data/lib/otto/security/csp/parser.rb

@@ -0,0 +1,120 @@
+# lib/otto/security/csp/parser.rb
+#
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'report'
+
+class Otto
+  module Security
+    module CSP
+      # Parses inbound Content-Security-Policy violation report bodies into a
+      # list of normalized {Otto::Security::CSP::Report} objects.
+      #
+      # Handles BOTH standardized wire formats:
+      #
+      # - Legacy `application/csp-report` — a single JSON object
+      #   `{"csp-report": { ... }}`.
+      # - Reporting API `application/reports+json` — a JSON ARRAY of
+      #   `{"type": "csp-violation", "body": { ... }}` entries (a single
+      #   un-wrapped object is tolerated too).
+      #
+      # The parser keys off the JSON SHAPE rather than trusting the declared
+      # `Content-Type`, because browsers and intermediaries are inconsistent
+      # about the header. The `content_type` argument is accepted for future use
+      # and symmetry with the middleware but is not currently required to
+      # disambiguate.
+      #
+      # It is intentionally TOTAL: malformed JSON, an unexpected top-level type,
+      # or entries that are not CSP violations yield an empty array rather than
+      # raising. A violation-report receiver must never fail on hostile input.
+      module Parser
+        module_function
+
+        # Parse a raw report body into normalized reports.
+        #
+        # @param body [String, nil] the raw request body (JSON).
+        # @param content_type [String, nil] the request Content-Type (hint only).
+        # @return [Array<Otto::Security::CSP::Report>] zero or more normalized
+        #   reports. Empty when the body is nil/blank/malformed or contains no
+        #   recognizable CSP violations.
+        def parse(body, content_type = nil)
+          return [] if body.nil? || body.empty?
+
+          data = safe_json_parse(body)
+          return [] if data.nil?
+
+          extract_raw_reports(data, content_type).filter_map do |raw|
+            Report.from_raw(raw)
+          end
+        end
+
+        # Parse JSON, swallowing the errors a hostile/garbled body can throw.
+        #
+        # @param body [String]
+        # @return [Object, nil] the parsed structure, or nil on any parse error.
+        def safe_json_parse(body)
+          JSON.parse(body)
+        rescue JSON::ParserError, EncodingError
+          nil
+        end
+
+        # Pull the per-violation field hashes out of either wire format.
+        #
+        # @param data [Object] the parsed JSON structure.
+        # @param _content_type [String, nil] unused (shape drives extraction).
+        # @return [Array<Hash>] raw, un-normalized per-violation field hashes.
+        def extract_raw_reports(data, _content_type = nil)
+          case data
+          when Array
+            extract_from_reporting_api(data)
+          when Hash
+            extract_from_object(data)
+          else
+            []
+          end
+        end
+
+        # Reporting API batch: an array of report envelopes. Keep entries that
+        # are (or are untyped but shaped like) CSP violations and carry a body.
+        #
+        # @param entries [Array]
+        # @return [Array<Hash>]
+        def extract_from_reporting_api(entries)
+          entries.filter_map do |entry|
+            next unless entry.is_a?(Hash)
+
+            body = entry['body']
+            next unless body.is_a?(Hash)
+
+            type = entry['type']
+            # Accept entries explicitly typed csp-violation, or untyped bodies.
+            # Skip other report types (deprecation, intervention, ...).
+            next unless type.nil? || type == 'csp-violation'
+
+            body
+          end
+        end
+
+        # A single top-level object in either the legacy `{"csp-report": {...}}`
+        # envelope or a lone Reporting API `{"type":..., "body": {...}}` object.
+        #
+        # @param data [Hash]
+        # @return [Array<Hash>]
+        def extract_from_object(data)
+          if data['csp-report'].is_a?(Hash)
+            [data['csp-report']]
+          elsif data['body'].is_a?(Hash) && (data['type'].nil? || data['type'] == 'csp-violation')
+            # Mirror extract_from_reporting_api: accept a lone csp-violation (or
+            # untyped) envelope, but skip other single-object report types
+            # (deprecation, intervention, ...).
+            [data['body']]
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/otto/security/csp/report.rb

@@ -0,0 +1,147 @@
+# lib/otto/security/csp/report.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module CSP
+      # A single, normalized Content-Security-Policy violation report.
+      #
+      # Browsers emit violation reports in two different wire formats with two
+      # different field-naming conventions:
+      #
+      # - Legacy `application/csp-report` (CSP Level 2/3): a JSON object under a
+      #   `"csp-report"` key using kebab-case fields (`blocked-uri`,
+      #   `violated-directive`, `line-number`, ...).
+      # - Reporting API `application/reports+json` (Reporting API v1): a JSON
+      #   ARRAY of `{"type": "csp-violation", "body": {...}}` entries whose body
+      #   uses camelCase fields (`blockedURL`, `effectiveDirective`,
+      #   `lineNumber`, ...).
+      #
+      # This Struct is the single normalized shape both formats collapse into, so
+      # application callbacks registered via
+      # {Otto::Security::Config#on_csp_violation} never have to care which format
+      # the browser used. Build instances with {.from_raw}; use {#to_h} to
+      # serialize.
+      #
+      # SECURITY NOTE: the URL-ish fields (`document_uri`, `blocked_uri`,
+      # `referrer`, `source_file`) reflect the page the browser was on and the
+      # resource it tried to load. In some applications these can carry sensitive
+      # path/query data (tokens, secret links). Otto does NOT redact these — it
+      # normalizes and hands them to your callback verbatim. If your application
+      # logs or forwards reports, redact these fields in your callback per your
+      # own privacy policy before they reach a log sink.
+      #
+      # @example Reading fields in a callback
+      #   config.on_csp_violation do |report|
+      #     logger.warn("CSP violation: #{report.violated_directive} " \
+      #                 "blocked #{report.blocked_uri}")
+      #   end
+      Report = Struct.new(
+        :document_uri,
+        :referrer,
+        :blocked_uri,
+        :violated_directive,
+        :effective_directive,
+        :original_policy,
+        :disposition,
+        :source_file,
+        :status_code,
+        :script_sample,
+        :line_number,
+        :column_number,
+        keyword_init: true
+      )
+
+      # Normalization behavior for {Report}. Reopened (rather than defined inside
+      # the Struct.new block) so the constants below are plain class constants,
+      # not constants-defined-in-a-block.
+      class Report
+        # Map from a normalized field to the list of raw keys (in priority order)
+        # that may hold its value across both wire formats. Legacy kebab-case
+        # keys are listed alongside their Reporting API camelCase equivalents.
+        FIELD_ALIASES = {
+                 document_uri:        %w[document-uri documentURL],
+                     referrer:        %w[referrer referer],
+                  blocked_uri:        %w[blocked-uri blockedURL],
+           violated_directive:        %w[violated-directive violatedDirective],
+          effective_directive:        %w[effective-directive effectiveDirective],
+              original_policy:        %w[original-policy originalPolicy],
+                  disposition:        %w[disposition],
+                  source_file:        %w[source-file sourceFile],
+                  status_code:        %w[status-code statusCode],
+                script_sample:        %w[script-sample sample],
+                  line_number:        %w[line-number lineNumber],
+                column_number:        %w[column-number columnNumber],
+        }.freeze
+
+        # Fields coerced to an Integer (or nil) rather than kept as whatever
+        # scalar the browser sent.
+        NUMERIC_FIELDS = %i[status_code line_number column_number].freeze
+
+        # Build a normalized Report from a single raw per-violation field hash.
+        #
+        # Accepts either wire format's field naming. `violated_directive` and
+        # `effective_directive` are cross-filled from each other when only one is
+        # present, because the two formats disagree on which they send (legacy
+        # favors `violated-directive`; the Reporting API favors
+        # `effectiveDirective`).
+        #
+        # @param raw [Hash] a single violation's field hash (already unwrapped
+        #   from any `csp-report`/`body` envelope by the parser).
+        # @return [Report, nil] the normalized report, or nil when `raw` is not a
+        #   usable Hash.
+        def self.from_raw(raw)
+          return nil unless raw.is_a?(Hash)
+
+          attrs = FIELD_ALIASES.each_with_object({}) do |(field, keys), acc|
+            value      = first_present(raw, keys)
+            acc[field] = NUMERIC_FIELDS.include?(field) ? coerce_int(value) : value
+          end
+
+          cross_fill_directives!(attrs)
+          new(**attrs)
+        end
+
+        # First non-nil value among the given keys, in priority order.
+        #
+        # @param raw [Hash]
+        # @param keys [Array<String>]
+        # @return [Object, nil]
+        def self.first_present(raw, keys)
+          keys.each do |key|
+            value = raw[key]
+            return value unless value.nil?
+          end
+          nil
+        end
+
+        # Coerce a raw value to an Integer, or nil when it is not a clean
+        # integer. Guards against a browser sending a huge or non-numeric value.
+        #
+        # @param value [Object]
+        # @return [Integer, nil]
+        def self.coerce_int(value)
+          return nil if value.nil?
+          return value if value.is_a?(Integer)
+
+          str = value.to_s
+          str.match?(/\A-?\d{1,18}\z/) ? str.to_i : nil
+        end
+
+        # Populate a missing directive from its sibling so callbacks can rely on
+        # both `violated_directive` and `effective_directive` being present when
+        # the browser sent at least one.
+        #
+        # @param attrs [Hash]
+        # @return [void]
+        def self.cross_fill_directives!(attrs)
+          attrs[:violated_directive]  ||= attrs[:effective_directive]
+          attrs[:effective_directive] ||= attrs[:violated_directive]
+        end
+
+        private_class_method :first_present, :coerce_int, :cross_fill_directives!
+      end
+    end
+  end
+end