otto 2.3.0 → 2.4.0

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

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

@@ -0,0 +1,120 @@
+# lib/otto/security/csp/report_middleware.rb
+#
+# frozen_string_literal: true
+
+require_relative 'parser'
+
+class Otto
+  module Security
+    module CSP
+      # Rack middleware that receives browser-posted Content-Security-Policy
+      # violation reports and dispatches them to an application callback.
+      #
+      # This is the receiving half of Otto's CSP support; the emitting half is
+      # {Otto::Security::Config#generate_nonce_csp} / {Otto::Response#send_csp_headers}
+      # (and the static {Otto::Security::Config#enable_csp!}). When a report URI
+      # is configured, the emitted policy carries a `report-uri` directive
+      # pointing here.
+      #
+      # Behavior (all mandatory for a public, unauthenticated receiver):
+      #
+      # - INERT unless {Otto::Security::Config#csp_report_uri} is set. When it is
+      #   not configured the middleware is a transparent pass-through.
+      # - Only intercepts a POST whose path matches the configured report URI.
+      #   Everything else (other paths, other methods) passes through untouched.
+      # - Short-circuits BEFORE inner middleware, so CSRF, auth, and rate
+      #   limiting never see the request. This is why browsers can POST reports
+      #   with no CSRF token: the report never reaches the CSRF middleware.
+      #   {Otto::Security::Core#enable_csp_reporting!} pins this middleware
+      #   OUTERMOST (via the :outermost stack position), so the guarantee holds
+      #   regardless of the order security features are enabled in. The flip side
+      #   is that reports also bypass rate limiting — see the DoS note on
+      #   {Otto::Security::Core#enable_csp_reporting!}; keep callbacks cheap.
+      # - Enforces a hard {MAX_BODY_BYTES} body cap. Oversized bodies are
+      #   detected with a `cap + 1` read and skipped WITHOUT parsing, so a
+      #   hostile client cannot force large allocations against a public endpoint.
+      # - Parses both wire formats via {Otto::Security::CSP::Parser} and invokes
+      #   the registered callback once per normalized report.
+      # - NEVER raises to the client and always responds `204 No Content`
+      #   (browsers ignore the body). A throwing callback is isolated by
+      #   {Otto::Security::Config#dispatch_csp_violation}.
+      class ReportMiddleware
+        # Hard cap on the request body we are willing to read/parse. Browsers
+        # send small JSON documents; anything larger is abuse and is dropped.
+        MAX_BODY_BYTES = 64 * 1024 # 64 KiB
+
+        def initialize(app, config = nil)
+          @app    = app
+          @config = config || Otto::Security::Config.new
+        end
+
+        def call(env)
+          return @app.call(env) unless report_request?(env)
+
+          receive_report(env)
+        end
+
+        private
+
+        # Handle a report POST and always answer 204. A report receiver must
+        # never surface an error to the browser, so parse/dispatch failures are
+        # contained HERE — deliberately NOT around the #call pass-through, which
+        # would swallow unrelated downstream errors (turning every failing
+        # request into a silent 204, since this middleware runs outermost).
+        def receive_report(env)
+          handle_report(env)
+          # A fresh header hash + body per call (never a shared/frozen literal)
+          # so a downstream server that mutates the response tuple is safe.
+          [204, {}, []]
+        rescue StandardError => e
+          Otto.logger.error("[Otto::CSP] report handling failed: #{e.class}: #{e.message}")
+          [204, {}, []]
+        end
+
+        # True only when reporting is configured AND this is a POST to the
+        # configured report path.
+        #
+        # @param env [Hash]
+        # @return [Boolean]
+        def report_request?(env)
+          report_uri = @config.csp_report_uri
+          return false if report_uri.nil? || report_uri.empty?
+          return false unless env['REQUEST_METHOD'] == 'POST'
+
+          env['PATH_INFO'] == report_uri
+        end
+
+        # Read (capped), parse, and dispatch. Never raises; parse/dispatch
+        # failures are contained so the caller can still return 204.
+        #
+        # @param env [Hash]
+        # @return [void]
+        def handle_report(env)
+          body = read_capped_body(env)
+          return if body.nil?
+
+          reports = Otto::Security::CSP::Parser.parse(body, env['CONTENT_TYPE'])
+          reports.each { |report| @config.dispatch_csp_violation(report) }
+        end
+
+        # Read at most MAX_BODY_BYTES + 1 bytes so an oversized body is detected
+        # without ever materializing more than the cap. Returns nil when there is
+        # no readable body or the body exceeds the cap (skip without parsing).
+        #
+        # @param env [Hash]
+        # @return [String, nil]
+        def read_capped_body(env)
+          input = env['rack.input']
+          return nil if input.nil?
+
+          chunk = input.read(MAX_BODY_BYTES + 1)
+          input.rewind if input.respond_to?(:rewind)
+          return nil if chunk.nil? || chunk.empty?
+          return nil if chunk.bytesize > MAX_BODY_BYTES # oversized: drop unparsed
+
+          chunk
+        end
+      end
+    end
+  end
+end

data/lib/otto/security/csp.rb

@@ -0,0 +1,19 @@
+# lib/otto/security/csp.rb
+#
+# frozen_string_literal: true
+
+#
+# Index file for Content-Security-Policy violation reporting components.
+#
+# Otto emits CSP headers via Otto::Security::Config (static #enable_csp! and
+# nonce-based #generate_nonce_csp / Otto::Response#send_csp_headers). This
+# module adds the receiving half: a turnkey violation-report endpoint plus a
+# callback API, so an application can collect CSP reports with a few lines of
+# config instead of hand-rolling a parser, size cap, and CSRF exemption.
+#
+# See Otto::Security::Core#enable_csp_reporting! for the primary entry point and
+# delano/otto#174 for the design.
+
+require_relative 'csp/report'
+require_relative 'csp/parser'
+require_relative 'csp/report_middleware'

data/lib/otto/security/middleware/ip_privacy_middleware.rb

@@ -85,6 +85,27 @@ class Otto
 
           Otto.logger.debug "[IPPrivacyMiddleware] Resolved client IP: #{client_ip}" if Otto.debug
 
+          # No resolvable client IP (REMOTE_ADDR absent or blank, and no trusted
+          # forwarded value). There is nothing to mask, and masking would derive
+          # a nil masked IP (IPPrivacy.mask_ip returns nil for nil/empty input).
+          # Writing that nil back to REMOTE_ADDR / forwarded headers would leave
+          # present-but-nil CGI keys, which violate the Rack SPEC and trip
+          # Rack::Lint — the same class of bug as the User-Agent/Referer case
+          # below (issue #167). Skip the IP-masking work, leaving REMOTE_ADDR
+          # untouched (an absent key stays absent; an empty string stays an
+          # empty string).
+          #
+          # The User-Agent/Referer redaction, however, is independent of the
+          # client IP, and this middleware's contract is to ALWAYS clear the
+          # original sensitive data. So still scrub those headers before
+          # bailing — a request with no resolvable IP must not leak an
+          # un-anonymized User-Agent or Referer.
+          if client_ip.to_s.empty?
+            Otto.logger.debug '[IPPrivacyMiddleware] No resolvable client IP; skipping IP masking' if Otto.debug
+            scrub_sensitive_headers(env, Otto::Privacy::RedactedFingerprint.new(env, @config))
+            return
+          end
+
           # Skip masking for private/localhost IPs unless explicitly configured to mask them
           # This provides better DX for development while still protecting public IPs
           unless @config.mask_private_ips
@@ -122,13 +143,10 @@ class Otto
           # Privacy-safe: holds the masked value, never the original public IP.
           env['otto.client_ip'] = fingerprint.masked_ip
 
-          # Replace User-Agent with anonymized version (consistent with IP masking)
-          # CRITICAL: Always replace, even if nil, to clear original sensitive data
-          env['HTTP_USER_AGENT'] = fingerprint.anonymized_ua
-
-          # Replace Referer with anonymized version (query params stripped)
-          # CRITICAL: Always replace, even if nil, to clear original sensitive data
-          env['HTTP_REFERER'] = fingerprint.referer
+          # Replace User-Agent / Referer with anonymized versions (consistent
+          # with IP masking). See scrub_sensitive_headers — also reached by the
+          # no-resolvable-IP path so these headers are always cleared.
+          scrub_sensitive_headers(env, fingerprint)
 
           # Mask X-Forwarded-For headers to prevent leakage
           # Replace with masked IP so proxy resolution logic finds the masked IP
@@ -141,6 +159,45 @@ class Otto
         end
 
 
+        # Set or clear a Rack env header in a SPEC-compliant way.
+        #
+        # CGI-style keys (those without a period) must hold String values per
+        # the Rack SPEC; a present-but-nil value trips Rack::Lint. So when the
+        # anonymized replacement is nil, delete the key entirely instead of
+        # assigning nil — semantically identical to "cleared" for downstream
+        # readers, and SPEC-compliant.
+        #
+        # @param env [Hash] Rack environment
+        # @param key [String] Env key to set or delete
+        # @param value [String, nil] Replacement value, or nil to clear the key
+        def replace_or_delete(env, key, value)
+          if value.nil?
+            env.delete(key)
+          else
+            env[key] = value
+          end
+        end
+
+        # Redact the request's sensitive non-IP headers in place.
+        #
+        # User-Agent and Referer carry identifying information independent of
+        # the client IP, so they are scrubbed on every privacy-enabled request
+        # — including ones with no resolvable IP, where IP masking is skipped.
+        # Each header is replaced with the fingerprint's anonymized value, or
+        # DELETED when that value is nil (no/empty header): CGI-style keys must
+        # hold String values per the Rack SPEC, so a present-but-nil
+        # HTTP_USER_AGENT/HTTP_REFERER would trip Rack::Lint (issue #167).
+        # Deleting is also marginally more private — an absent header is
+        # indistinguishable from one that was never sent.
+        #
+        # @param env [Hash] Rack environment
+        # @param fingerprint [Otto::Privacy::RedactedFingerprint] source of the
+        #   anonymized header values
+        def scrub_sensitive_headers(env, fingerprint)
+          replace_or_delete(env, 'HTTP_USER_AGENT', fingerprint.anonymized_ua)
+          replace_or_delete(env, 'HTTP_REFERER', fingerprint.referer)
+        end
+
         # Resolve the actual client IP address from the request.
         #
         # Delegates to the shared Otto::Utils.resolve_client_ip so the
@@ -162,6 +219,14 @@ class Otto
         # @param env [Hash] Rack environment
         # @param masked_ip [String] The masked IP to use as replacement
         def mask_forwarded_headers(env, masked_ip)
+          # Defensive: never write a nil replacement into these CGI-style headers
+          # (the Rack SPEC requires String values; a nil trips Rack::Lint — see
+          # issue #167). apply_privacy's early "no client IP" guard already
+          # guarantees a non-nil masked_ip here, but keep this method
+          # self-contained so a future caller change can't reintroduce a
+          # present-but-nil HTTP_X_FORWARDED_FOR.
+          return if masked_ip.nil?
+
           # Replace X-Forwarded-For with masked IP
           # This prevents Rack::Request#ip from finding the real IP
           env['HTTP_X_FORWARDED_FOR'] = masked_ip if env['HTTP_X_FORWARDED_FOR']

data/lib/otto/security.rb

@@ -12,3 +12,4 @@ require_relative 'security/middleware/csrf_middleware'
 require_relative 'security/middleware/validation_middleware'
 require_relative 'security/middleware/rate_limit_middleware'
 require_relative 'security/middleware/ip_privacy_middleware'
+require_relative 'security/csp'

data/lib/otto/utils.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require 'ipaddr'
+require 'rack/utils'
 
 class Otto
   # Utility methods for common operations and helpers
@@ -57,6 +58,41 @@ class Otto
       !value.to_s.empty? && %w[true yes 1].include?(value.to_s.downcase)
     end
 
+    # Canonical path normalization for literal route matching: URL-unescape,
+    # scrub invalid/undefined bytes, and strip a single trailing slash.
+    #
+    # This is the SINGLE SOURCE OF TRUTH shared by the router
+    # (Otto::Core::Router#handle_request, which compares the result against its
+    # literal-route table) and Otto::CaddyTLS::LocalhostGuard (which compares it
+    # against the guarded endpoint). The two MUST normalize identically: if a
+    # crafted path — a trailing slash, a percent-encoded byte, an invalid UTF-8
+    # byte — normalized differently in the guard than in the router, the router
+    # could dispatch a request the guard let through, bypassing the loopback
+    # check. One implementation makes that drift impossible.
+    #
+    # Mirrors the empty-path handling and :replace scrubbing the router applies.
+    # Robust to invalid input: Rack::Utils.unescape raises ArgumentError on an
+    # already-invalid byte sequence (a raw \xFF in the path), so that is caught
+    # and the raw string is scrubbed instead — a percent-encoded invalid byte
+    # (%FF) decodes to the same invalid byte and is scrubbed identically, so the
+    # two crafted forms normalize alike. The method itself does not raise.
+    #
+    # @param raw_path [String, nil] a raw PATH_INFO or a configured endpoint
+    # @return [String] normalized path suitable for exact literal comparison
+    def normalize_path(raw_path)
+      raw = raw_path.to_s
+      decoded =
+        begin
+          Rack::Utils.unescape(raw)
+        rescue ArgumentError
+          raw
+        end
+      decoded = '/' if decoded.empty?
+      decoded
+        .encode('UTF-8', invalid: :replace, undef: :replace, replace: '')
+        .gsub(%r{/$}, '')
+    end
+
     # Validate and normalize an IP address (IPv4 and IPv6).
     #
     # Strips an optional port (IPv6-safe), validates with IPAddr, and returns
@@ -143,37 +179,41 @@ class Otto
     # from the right of the forwarded chain (Express `trust proxy = N`). Used
     # when the proxy tier's addresses cannot be enumerated as CIDRs.
     #
-    # The chain is X-Forwarded-For (leftmost = client .. rightmost = nearest
-    # proxy) plus REMOTE_ADDR (the direct peer). With depth N the client is
-    # chain[-(N+1)] — exactly N trusted hops from the right, equivalent to
-    # Express's addrs[N]. This is robust to X-Forwarded-For padding: a forged
-    # leftmost entry is never reached.
+    # The chain is the configured forwarded header (leftmost = client ..
+    # rightmost = nearest proxy) plus REMOTE_ADDR (the direct peer). With depth
+    # N the client is chain[-(N+1)] — exactly N trusted hops from the right,
+    # equivalent to Express's addrs[N]. This is robust to forwarded-header
+    # padding: a forged leftmost entry is never reached.
     #
     # SECURITY: depth trust ASSUMES ORIGIN LOCKDOWN — the app must be
     # unreachable except through the proxy tier. Without it, a direct client
-    # could pad X-Forwarded-For to land a forged value at the target index.
+    # could pad the forwarded header to land a forged value at the target index.
     # This is the inherent trade vs CIDR-walk (a fixed hop count instead of
     # enumerable proxy addresses).
     #
-    # Only X-Forwarded-For is consulted; X-Real-IP / X-Client-IP are
-    # single-value and cannot express a hop chain. Positions are counted raw
-    # (never dropped), so junk padding cannot shift the index; only the
-    # selected entry is validated. If the chain is shorter than N+1 (a request
-    # that may have bypassed the proxy tier) or the selected entry is invalid,
-    # REMOTE_ADDR is returned rather than a spoofable forwarded value.
+    # The forwarded chain is selected by security_config.trusted_proxy_header:
+    # 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239), or 'Both' (RFC 7239
+    # when it carries a `for=`, otherwise X-Forwarded-For — mirrors
+    # OneTimeSecret's site.network.trusted_proxy.header). X-Real-IP / X-Client-IP
+    # are single-value and cannot express a hop chain, so they are never
+    # consulted in depth mode. Positions are counted raw (never dropped), so junk
+    # padding cannot shift the index; only the selected entry is validated. If
+    # the chain is shorter than N+1 (a request that may have bypassed the proxy
+    # tier) or the selected entry is invalid, REMOTE_ADDR is returned rather than
+    # a spoofable forwarded value.
     #
     # @param env [Hash] Rack environment
-    # @param security_config [Otto::Security::Config] config exposing #trusted_proxy_depth
+    # @param security_config [Otto::Security::Config] config exposing #trusted_proxy_depth and #trusted_proxy_header
     # @return [String, nil] resolved client IP (REMOTE_ADDR on short chain / invalid target)
     def resolve_client_ip_by_depth(env, security_config)
       remote_addr = env['REMOTE_ADDR']
       depth       = security_config.trusted_proxy_depth.to_i
 
-      # Split on commas keeping every position (-1 preserves trailing empty
-      # fields) so a malformed hop still counts as a position. The client must
-      # be located by counting from the right; dropping entries here would let
-      # padding shift the index.
-      forwarded = env['HTTP_X_FORWARDED_FOR'].to_s.split(',', -1)
+      # Build the positional hop chain from the configured header, keeping every
+      # position (junk/empty entries included) so the client can be located by
+      # counting from the right; dropping entries would let padding shift the
+      # index. REMOTE_ADDR (the direct peer) is the rightmost hop.
+      forwarded = forwarded_chain_for_depth(env, security_config.trusted_proxy_header)
       chain     = forwarded + [remote_addr]
 
       index = chain.length - (depth + 1)
@@ -182,6 +222,81 @@ class Otto
       normalize_ip(chain[index].to_s.strip) || remote_addr
     end
 
+    # Positional forwarded-hop chain for depth resolution, selected by header
+    # mode. Each element is one hop (preserving count); values are raw — only the
+    # finally-selected entry is normalized. Mirrors OneTimeSecret's
+    # site.network.trusted_proxy.header semantics.
+    #
+    # @param env [Hash] Rack environment
+    # @param header_mode [String] 'X-Forwarded-For', 'Forwarded', or 'Both'
+    # @return [Array<String>] one entry per hop (may include blank/invalid entries)
+    def forwarded_chain_for_depth(env, header_mode)
+      case header_mode
+      when 'Forwarded'
+        rfc7239_for_chain(env['HTTP_FORWARDED'])
+      when 'Both'
+        # RFC 7239 wins when it carries at least one `for=`; otherwise fall back
+        # to X-Forwarded-For. The chains are NOT merged (matches OTS's
+        # `extract_rfc7239_forwarded(env) || extract_x_forwarded_for(env)`).
+        forwarded = rfc7239_for_chain(env['HTTP_FORWARDED'])
+        forwarded.any? { |entry| !entry.empty? } ? forwarded : xff_chain(env['HTTP_X_FORWARDED_FOR'])
+      else
+        xff_chain(env['HTTP_X_FORWARDED_FOR'])
+      end
+    end
+
+    # Split X-Forwarded-For into raw positional entries. `-1` keeps trailing
+    # empty fields so a malformed/empty hop still counts as a position.
+    #
+    # @param value [String, nil] raw X-Forwarded-For header value
+    # @return [Array<String>]
+    def xff_chain(value)
+      value.to_s.split(',', -1)
+    end
+
+    # Extract the per-hop `for=` chain from an RFC 7239 Forwarded header,
+    # preserving one position per forwarded-element. Elements without a `for=`
+    # parameter yield a blank placeholder so they still occupy a hop position
+    # (raw position counting). The extracted token is only unquoted here; port
+    # and IPv6 brackets are left for normalize_ip when the entry is selected.
+    # Obfuscated (`for=_hidden`) and `for=unknown` identifiers are preserved as
+    # positions but normalize to nil (→ REMOTE_ADDR fallback if selected).
+    # Commas separate forwarded-elements (and join multiple Forwarded headers).
+    # A nil/blank header splits to [] (not ['']), so an absent Forwarded header
+    # yields an empty chain and depth's explicit short-chain guard returns
+    # REMOTE_ADDR — symmetric with xff_chain.
+    #
+    # @param value [String, nil] raw Forwarded header value
+    # @return [Array<String>] one `for=` token per forwarded-element
+    def rfc7239_for_chain(value)
+      value.to_s.split(',', -1).map { |element| rfc7239_for_value(element) }
+    end
+
+    # Pull the `for=` token out of a single RFC 7239 forwarded-element. The value
+    # is a quoted-string (which may itself legally contain ';') or an unquoted
+    # token ending at the next ';'. The quoted form is matched first so a ';'
+    # inside DQUOTEs is NOT treated as a parameter separator — otherwise a value
+    # like for="1.2.3.4;junk" would be truncated to a valid-looking IP instead of
+    # being rejected. Only DQUOTE wrappers are stripped: RFC 7239 quoted-strings
+    # use DQUOTE exclusively, so a value like for='1.2.3.4' keeps its quotes,
+    # fails normalize_ip, and safely falls back to REMOTE_ADDR rather than being
+    # permissively accepted. This is deliberately stricter than OTS (which strips
+    # both ['"]), consistent with depth's other intentionally-not-reconciled-down
+    # safety properties. The raw value (port / IPv6 brackets intact) is left for
+    # normalize_ip when the entry is selected. Returns '' when the element carries
+    # no `for=` parameter, preserving the hop position. The `for=` pair may be the
+    # element's first pair or follow a ';'; leading whitespace (e.g. after a comma
+    # split) is tolerated.
+    #
+    # @param element [String] one forwarded-element (e.g. 'for=1.2.3.4;proto=https')
+    # @return [String]
+    def rfc7239_for_value(element)
+      match = element.match(/(?:\A|;)\s*for=(?:"([^"]*)"|([^;]+))/i)
+      return '' unless match
+
+      (match[1] || match[2]).strip
+    end
+
     # Whether an address is non-public: RFC1918 private, loopback, link-local,
     # multicast, or unspecified — for both IPv4 and IPv6.
     #

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 class Otto
-  VERSION = '2.3.0'
+  VERSION = '2.4.0'
 end

data/lib/otto.rb

@@ -22,6 +22,7 @@ require_relative 'otto/route_handlers'
 require_relative 'otto/errors'
 require_relative 'otto/locale'
 require_relative 'otto/mcp'
+require_relative 'otto/caddy_tls'
 require_relative 'otto/core'
 require_relative 'otto/privacy'
 require_relative 'otto/security'
@@ -62,6 +63,7 @@ class Otto
   include Otto::Security::Core
   include Otto::Privacy::Core
   include Otto::MCP::Core
+  include Otto::CaddyTLS::Core
 
   LIB_HOME = __dir__ unless defined?(Otto::LIB_HOME)
 
@@ -75,7 +77,7 @@ class Otto
 
   attr_reader :routes, :routes_literal, :routes_static, :route_definitions, :option,
               :static_route, :security_config, :locale_config, :auth_config,
-              :route_handler_factory, :mcp_server, :security, :middleware,
+              :route_handler_factory, :mcp_server, :caddy_tls_server, :security, :middleware,
               :error_handlers, :request_class, :response_class
   attr_accessor :not_found, :server_error
 
@@ -107,8 +109,13 @@ class Otto
 
   # Main Rack application interface
   def call(env)
-    # Freeze configuration on first request (thread-safe)
-    # Skip in test environment to allow test flexibility
+    # Freeze configuration on first request (thread-safe).
+    # Skipped under RSpec so specs can mutate configuration after construction.
+    # Because of this skip, behavior that depends on a genuinely frozen config
+    # (e.g. CSP violation dispatch through a frozen Config) is NOT exercised by
+    # the normal request path in tests — cover it with specs that freeze
+    # explicitly (see spec/otto/security/csp_reporting_frozen_spec.rb and
+    # spec/otto/configuration_freezing_spec.rb).
     unless defined?(RSpec) || @configuration_frozen
       Otto.logger.debug '[Otto] Lazy freezing check: configuration not yet frozen' if Otto.debug
 
@@ -169,6 +176,22 @@ class Otto
     @auth_config       = { auth_strategies: {}, default_auth_strategy: 'noauth' }
     @security          = Otto::Security::Configurator.new(@security_config, @middleware, @auth_config)
     @app               = nil # Pre-built middleware app (built after initialization)
+
+    # Keep the running Rack app in sync with the middleware stack. This is the
+    # SINGLE rebuild trigger: any add/remove/clear — whether via Otto#use,
+    # otto.enable_*!, or the otto.security.* Configurator surface — rebuilds @app
+    # once it exists. Without it, middleware added through the Configurator after
+    # Otto.new would register in the stack but never enter the running request
+    # chain, silently disabling CSRF, request validation, rate limiting, and CSP
+    # reporting configured that way.
+    #
+    # The `if @app` guard makes stack mutations during initialization (e.g. the
+    # IP-privacy add below) no-ops until the first build_app! runs. A rebuild
+    # during a live request could swap @app mid-flight under multi-threaded
+    # serving; Otto's contract is to configure before the first request, which
+    # the lazy configuration freeze enforces in production.
+    @middleware.on_change { build_app! if @app }
+
     @request_complete_callbacks = [] # Instance-level request completion callbacks
     @route_matched_callbacks    = [] # Instance-level route matched callbacks
     @handler_wrappers           = [] # Instance-level handler wrapper factories