otto 2.3.0 → 2.4.0

data/lib/otto/core/router.rb

@@ -72,14 +72,10 @@ class Otto
         path_info          = '/' if path_info.to_s.empty?
 
         begin
-          path_info_clean = path_info
-                            .encode(
-                              'UTF-8', # Target encoding
-                              invalid: :replace, # Replace invalid byte sequences
-                              undef: :replace,   # Replace characters undefined in UTF-8
-                              replace: '' # Use empty string for replacement
-                            )
-                            .gsub(%r{/$}, '') # Remove trailing slash, if present
+          # Shared with Otto::CaddyTLS::LocalhostGuard so the guard and the
+          # router cannot normalize a path differently (which would be a guard
+          # bypass). See Otto::Utils.normalize_path.
+          path_info_clean = Otto::Utils.normalize_path(env['PATH_INFO'])
         rescue ArgumentError => e
           # Log the error but don't expose details
           Otto.logger.error '[Otto.handle_request] Path encoding error'

data/lib/otto/security/config.rb

@@ -37,6 +37,18 @@ class Otto
         hop count, not both.
       MSG
 
+      # Forwarded-header sources depth mode (#trusted_proxy_depth) can count
+      # hops from: X-Forwarded-For (default), the RFC 7239 Forwarded header, or
+      # Both (Forwarded when present, else X-Forwarded-For). Mirrors
+      # OneTimeSecret's site.network.trusted_proxy.header. Only consulted in
+      # 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
@@ -56,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
+                  :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
       #
@@ -73,11 +86,16 @@ class Otto
         @trusted_proxies        = []
         @trusted_proxy_matchers = []
         @trusted_proxy_depth    = nil
+        @trusted_proxy_header   = 'X-Forwarded-For'
         @require_secure_cookies = false
         @security_headers       = default_security_headers
         @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
 
@@ -225,6 +243,27 @@ class Otto
         @trusted_proxy_depth = depth
       end
 
+      # Select which forwarded header depth mode counts hops from:
+      # 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239), or 'Both'. Only
+      # consulted when depth mode is active (#trusted_proxy_depth_mode?);
+      # CIDR-walk always uses X-Forwarded-For / X-Real-IP / X-Client-IP.
+      #
+      # The value is matched case-insensitively (surrounding whitespace ignored)
+      # and stored in its canonical spelling, so a hand-edited config can write
+      # `forwarded` or `both` without surprise. A genuinely unrecognized value
+      # fails loud at assignment (rather than silently resolving from the wrong
+      # header, the way a permissive default would), so a typo surfaces at config
+      # time instead of as subtly-wrong client IPs at request time.
+      #
+      # @param header [String] one of TRUSTED_PROXY_HEADERS (case-insensitive)
+      # @raise [FrozenError] if configuration is frozen
+      # @raise [ArgumentError] if header is not a recognized value
+      def trusted_proxy_header=(header)
+        ensure_not_frozen!
+
+        @trusted_proxy_header = canonicalize_trusted_proxy_header(header)
+      end
+
       # Validate that a request size is within acceptable limits
       #
       # @param content_length [String, Integer, nil] Content-Length header value
@@ -314,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
@@ -360,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
@@ -367,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
 
@@ -453,6 +601,42 @@ class Otto
         raise ArgumentError, "trusted_proxy_depth must be >= 0, got #{depth}" if depth.negative?
       end
 
+      # Canonicalize a candidate trusted_proxy_header value: match it
+      # case-insensitively (ignoring surrounding whitespace) against the
+      # recognized set and return the canonical spelling. Liberal in the spelling
+      # it accepts (e.g. 'forwarded' => 'Forwarded') but fail-loud on a genuinely
+      # unrecognized value, so a typo is caught at config time rather than
+      # silently resolving the client IP from the wrong header.
+      #
+      # @param header [Object] candidate value
+      # @raise [ArgumentError] if header is not one of TRUSTED_PROXY_HEADERS
+      # @return [String] the canonical header value
+      def canonicalize_trusted_proxy_header(header)
+        candidate = header.to_s.strip
+        canonical = TRUSTED_PROXY_HEADERS.find { |allowed| allowed.casecmp?(candidate) }
+        return canonical if canonical
+
+        raise ArgumentError,
+              "trusted_proxy_header must be one of #{TRUSTED_PROXY_HEADERS.join(', ')}, got #{header.inspect}"
+      end
+
+      # Strictly validate a stored trusted_proxy_header value against the allowed
+      # set. The eager #trusted_proxy_header= setter already canonicalizes, so by
+      # freeze time the value is canonical; this freeze-time backstop catches a
+      # value smuggled in through a direct-ivar path that bypassed the setter,
+      # failing loud rather than silently mis-resolving the client IP at request
+      # time.
+      #
+      # @param header [Object] candidate value
+      # @raise [ArgumentError] if header is not one of TRUSTED_PROXY_HEADERS
+      # @return [void]
+      def validate_trusted_proxy_header!(header)
+        return if TRUSTED_PROXY_HEADERS.include?(header)
+
+        raise ArgumentError,
+              "trusted_proxy_header must be one of #{TRUSTED_PROXY_HEADERS.join(', ')}, got #{header.inspect}"
+      end
+
       # Validate trusted-proxy configuration coherence at freeze time.
       #
       # The eager setters (#trusted_proxy_depth=, #add_trusted_proxy) already
@@ -464,6 +648,7 @@ class Otto
       #   trusted_proxies and a depth >= 1 are configured
       # @return [void]
       def validate_trusted_proxy_config!
+        validate_trusted_proxy_header!(@trusted_proxy_header)
         validate_trusted_proxy_depth!(@trusted_proxy_depth)
         return if @trusted_proxy_depth.nil?
 
@@ -639,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

@@ -39,6 +39,9 @@ class Otto
       # @param trusted_proxy_depth [Integer, nil] Count-based proxy depth ("trust
       #   the last N hops") for non-enumerable proxy tiers; mutually exclusive
       #   with trusted_proxies (validated at configuration freeze)
+      # @param trusted_proxy_header [String, nil] Forwarded header depth mode
+      #   counts hops from: 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239),
+      #   or 'Both'. Only consulted in depth mode.
       # @param security_headers [Hash] Custom security headers to merge with defaults
       # @param hsts [Boolean] Enable HTTP Strict Transport Security
       # @param csp [Boolean, String] Enable Content Security Policy
@@ -62,6 +65,7 @@ class Otto
         rate_limiting: false,
         trusted_proxies: [],
         trusted_proxy_depth: nil,
+        trusted_proxy_header: nil,
         security_headers: {},
         hsts: false,
         csp: false,
@@ -74,6 +78,7 @@ class Otto
 
         Array(trusted_proxies).each { |proxy| add_trusted_proxy(proxy) }
         self.trusted_proxy_depth = trusted_proxy_depth unless trusted_proxy_depth.nil?
+        self.trusted_proxy_header = trusted_proxy_header unless trusted_proxy_header.nil?
         self.security_headers = security_headers unless security_headers.empty?
 
         enable_hsts! if hsts
@@ -142,6 +147,16 @@ class Otto
         @security_config.trusted_proxy_depth = depth
       end
 
+      # Select which forwarded header depth mode counts hops from:
+      # 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239), or 'Both'. Only
+      # consulted when depth mode is active. Mirrors OneTimeSecret's
+      # site.network.trusted_proxy.header.
+      #
+      # @param header [String] one of Otto::Security::Config::TRUSTED_PROXY_HEADERS
+      def trusted_proxy_header=(header)
+        @security_config.trusted_proxy_header = header
+      end
+
       # Set custom security headers that will be added to all responses.
       # These merge with the default security headers.
       #
@@ -183,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