otto 2.2.0 → 2.3.1

data/lib/otto/security/config.rb

@@ -4,6 +4,8 @@
 
 require 'securerandom'
 require 'digest'
+require 'openssl'
+require 'ipaddr'
 require_relative '../core/freezable'
 
 class Otto
@@ -26,13 +28,42 @@ class Otto
     class Config
       include Otto::Core::Freezable
 
-      attr_accessor :input_validation, :max_param_depth, :csrf_token_key, :rate_limiting_config, :csrf_session_key, :max_request_size, :max_param_keys
+      # Error raised when the two mutually-exclusive trusted-proxy resolution
+      # modes are configured together: CIDR-walk (enumerated #trusted_proxies)
+      # and count-based depth (#trusted_proxy_depth >= 1).
+      PROXY_MODE_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        Cannot configure both trusted_proxies (CIDR filter mode) and
+        trusted_proxy_depth >= 1 (count mode). Enumerate proxy CIDRs OR set a
+        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
+
+      # 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
+      # refuse it in production rather than serve intermittently-failing tokens.
+      CSRF_SECRET_REQUIRED_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        CSRF protection is enabled in production without a configured secret.
+        Set OTTO_CSRF_SECRET (or config.csrf_secret=) to a stable random value
+        (e.g. SecureRandom.hex(32)); a per-process random secret is not valid
+        across workers or restarts.
+      MSG
+
+      attr_accessor :input_validation, :max_param_depth, :csrf_token_key,
+                    :rate_limiting_config, :csrf_session_key, :max_request_size,
+                    :max_param_keys
 
       attr_reader :csrf_protection,  :csrf_header_key,
                   :trusted_proxies, :require_secure_cookies,
                   :security_headers,
                   :csp_nonce_enabled, :debug_csp, :mcp_auth,
-                  :ip_privacy_config
+                  :ip_privacy_config, :trusted_proxy_depth, :trusted_proxy_header
 
       # Initialize security configuration with safe defaults
       #
@@ -47,6 +78,9 @@ class Otto
         @max_param_depth        = 32
         @max_param_keys         = 64
         @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
@@ -54,6 +88,10 @@ class Otto
         @debug_csp              = false
         @rate_limiting_config   = { custom_rules: {} }
         @ip_privacy_config      = Otto::Privacy::Config.new
+
+        configured_secret      = ENV.fetch('OTTO_CSRF_SECRET', nil)
+        @csrf_secret_generated = configured_secret.nil? || configured_secret.empty?
+        @csrf_secret           = @csrf_secret_generated ? SecureRandom.hex(32) : configured_secret
       end
 
       # Enable CSRF (Cross-Site Request Forgery) protection
@@ -67,7 +105,7 @@ class Otto
       # @return [void]
       # @raise [FrozenError] if configuration is frozen
       def enable_csrf_protection!
-        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+        ensure_not_frozen!
 
         @csrf_protection = true
       end
@@ -77,7 +115,7 @@ class Otto
       # @return [void]
       # @raise [FrozenError] if configuration is frozen
       def disable_csrf_protection!
-        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+        ensure_not_frozen!
 
         @csrf_protection = false
       end
@@ -109,12 +147,18 @@ class Otto
       # @example Add multiple proxies
       #   config.add_trusted_proxy(['10.0.0.1', '172.16.0.0/12'])
       def add_trusted_proxy(proxy)
-        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+        ensure_not_frozen!
+        # CIDR-walk and count-based depth are mutually exclusive. Catch the
+        # conflict eagerly here (and in #trusted_proxy_depth=) so it surfaces at
+        # configuration time, not only at freeze (which the test harness skips).
+        raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if trusted_proxy_depth_mode?
 
         case proxy
         when String, Regexp
           @trusted_proxies << proxy
+          @trusted_proxy_matchers << register_proxy_matcher(proxy)
         when Array
+          proxy.each { |entry| @trusted_proxy_matchers << register_proxy_matcher(entry) }
           @trusted_proxies.concat(proxy)
         else
           raise ArgumentError, 'Proxy must be a String, Regexp, or Array'
@@ -123,23 +167,93 @@ class Otto
 
       # Check if an IP address is from a trusted proxy
       #
+      # String entries that parse as an IP or CIDR range are matched with
+      # proper IPAddr containment (IPv4 and IPv6). Entries that are not valid
+      # IPs (e.g. a bare prefix like '172.16.') fall back to the legacy
+      # exact/prefix string match for backward compatibility. Regexp entries
+      # are matched against the raw IP string.
+      #
+      # Proxy entries are parsed once at registration (see #add_trusted_proxy)
+      # into @trusted_proxy_matchers, so this never re-parses per request.
+      #
       # @param ip [String] IP address to check
       # @return [Boolean] true if the IP is from a trusted proxy
       def trusted_proxy?(ip)
-        return false if @trusted_proxies.empty?
-
-        @trusted_proxies.any? do |proxy|
-          case proxy
-          when String
-            ip == proxy || ip.start_with?(proxy)
-          when Regexp
-            proxy.match?(ip)
+        return false if @trusted_proxy_matchers.empty? || ip.nil? || ip.empty?
+
+        # Fold IPv4-mapped IPv6 (::ffff:a.b.c.d) to plain IPv4 so a dual-stack
+        # peer presented in mapped form still matches an IPv4 proxy entry.
+        client = parse_ipaddr(ip)&.native
+
+        @trusted_proxy_matchers.any? do |entry, range|
+          if range
+            # Pre-parsed IP/CIDR entry -> proper containment
+            client && ip_in_range?(range, client)
+          elsif entry.is_a?(Regexp)
+            entry.match?(ip)
+          elsif entry.is_a?(String)
+            # Legacy non-IP entry (e.g. '172.16.') -> exact/prefix match
+            ip == entry || ip.start_with?(entry)
           else
             false
           end
         end
       end
 
+      # Whether count-based ("trust the last N hops") proxy resolution is active.
+      #
+      # When true, Otto::Utils.resolve_client_ip ignores trusted-proxy CIDRs and
+      # instead trusts a fixed number of hops from the right of the forwarded
+      # chain (Express `trust proxy = N`). This is the only sound model for
+      # non-enumerable proxy tiers (Fly, cloud load balancers, dynamic reverse
+      # proxies) whose addresses cannot be listed as CIDRs.
+      #
+      # @return [Boolean] true when trusted_proxy_depth is an Integer >= 1
+      def trusted_proxy_depth_mode?
+        @trusted_proxy_depth.is_a?(Integer) && @trusted_proxy_depth >= 1
+      end
+
+      # Set the count-based trusted-proxy depth ("trust the last N hops").
+      #
+      # Validates eagerly so a misconfiguration fails at assignment rather than
+      # only at freeze (which the test harness skips): the value must be a
+      # non-negative Integer or nil, and the mode is mutually exclusive with
+      # CIDR-walk (trusted_proxies). nil/0 disable depth mode.
+      #
+      # @param depth [Integer, nil] number of trusted hops (nil/0 disables depth mode)
+      # @raise [FrozenError] if configuration is frozen
+      # @raise [ArgumentError] if depth is non-integer/negative, or if
+      #   trusted_proxies are already configured and depth >= 1
+      def trusted_proxy_depth=(depth)
+        ensure_not_frozen!
+
+        validate_trusted_proxy_depth!(depth)
+        raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if depth.to_i >= 1 && @trusted_proxies.any?
+
+        @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
@@ -156,28 +270,45 @@ class Otto
         true
       end
 
+      # Set the server-side secret used to sign (HMAC) CSRF tokens. Set this to
+      # a stable value (e.g. ENV['OTTO_CSRF_SECRET']) in multi-process or
+      # multi-host deployments so tokens stay valid across workers and restarts.
+      #
+      # Write-only by design: the signing key has no public reader, so it is not
+      # exposed to inspection/logging/serialization via the config object.
+      def csrf_secret=(secret)
+        ensure_not_frozen!
+
+        @csrf_secret           = secret
+        @csrf_secret_generated = false
+      end
+
+      # Generate a CSRF token bound to the given session id and signed (HMAC-SHA256)
+      # with the server-side secret, so tokens cannot be self-minted and are not
+      # valid across sessions. A session binding is REQUIRED.
       def generate_csrf_token(session_id = nil)
-        base       = session_id || 'no-session'
-        token      = SecureRandom.hex(32)
-        hash_input = base + ':' + token
-        signature  = Digest::SHA256.hexdigest(hash_input)
-        csrf_token = "#{token}:#{signature}"
+        binding_id = session_id.to_s
+        raise ArgumentError, 'CSRF token generation requires a session binding' if binding_id.empty?
 
-        csrf_token
+        reject_generated_secret_in_production!
+        warn_generated_csrf_secret
+        token = SecureRandom.hex(32)
+        "#{token}:#{sign_csrf_token(binding_id, token)}"
       end
 
+      # Verify a CSRF token against its session binding using a constant-time
+      # comparison. Returns false (never raises) for blank/malformed input.
       def verify_csrf_token(token, session_id = nil)
         return false if token.nil? || token.empty?
 
-        token_part, signature = token.split(':')
-        return false if token_part.nil? || signature.nil?
+        binding_id = session_id.to_s
+        return false if binding_id.empty?
 
-        base               = session_id || 'no-session'
-        hash_input         = "#{base}:#{token_part}"
-        expected_signature = Digest::SHA256.hexdigest(hash_input)
-        comparison_result  = secure_compare(signature, expected_signature)
+        token_part, signature = token.split(':', 2)
+        return false if token_part.nil? || signature.nil?
 
-        comparison_result
+        expected_signature = sign_csrf_token(binding_id, token_part)
+        secure_compare(signature, expected_signature)
       end
 
       # Enable HTTP Strict Transport Security (HSTS) header
@@ -191,7 +322,7 @@ class Otto
       # @return [void]
       # @raise [FrozenError] if configuration is frozen
       def enable_hsts!(max_age: 31_536_000, include_subdomains: true)
-        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+        ensure_not_frozen!
 
         hsts_value                                     = "max-age=#{max_age}"
         hsts_value                                    += '; includeSubDomains' if include_subdomains
@@ -210,7 +341,7 @@ class Otto
       # @example Custom policy
       #   config.enable_csp!("default-src 'self'; script-src 'self' 'unsafe-inline'")
       def enable_csp!(policy = "default-src 'self'")
-        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+        ensure_not_frozen!
 
         @security_headers['content-security-policy'] = policy
       end
@@ -228,7 +359,7 @@ class Otto
       # @example
       #   config.enable_csp_with_nonce!(debug: true)
       def enable_csp_with_nonce!(debug: false)
-        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+        ensure_not_frozen!
 
         @csp_nonce_enabled = true
         @debug_csp         = debug
@@ -239,7 +370,7 @@ class Otto
       # @return [void]
       # @raise [FrozenError] if configuration is frozen
       def disable_csp_nonce!
-        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+        ensure_not_frozen!
 
         @csp_nonce_enabled = false
       end
@@ -274,7 +405,7 @@ class Otto
       # @return [void]
       # @raise [FrozenError] if configuration is frozen
       def enable_frame_protection!(option = 'SAMEORIGIN')
-        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+        ensure_not_frozen!
 
         @security_headers['x-frame-options'] = option
       end
@@ -291,7 +422,7 @@ class Otto
       #     'cross-origin-opener-policy' => 'same-origin'
       #   })
       def set_custom_headers(headers)
-        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+        ensure_not_frozen!
 
         @security_headers.merge!(headers)
       end
@@ -305,6 +436,8 @@ class Otto
       def deep_freeze!
         # Ensure custom_rules is initialized (should already be done in constructor)
         @rate_limiting_config[:custom_rules] ||= {}
+        validate_trusted_proxy_config!
+        validate_csrf_secret_config!
         super
       end
 
@@ -323,6 +456,139 @@ class Otto
 
       private
 
+      # Guard for mutators: refuse changes once the configuration is frozen.
+      # Centralizes the repeated frozen-check so every setter shares one message.
+      def ensure_not_frozen!
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+      end
+
+      # Validate a candidate trusted_proxy_depth value (type and range).
+      #
+      # Shared by the eager #trusted_proxy_depth= setter and the freeze-time
+      # backstop so an invalid value raises a clear ArgumentError instead of a
+      # downstream NoMethodError from #to_i coercion. nil disables depth mode.
+      #
+      # @param depth [Object] candidate value
+      # @raise [ArgumentError] if depth is non-nil and not a non-negative Integer
+      # @return [void]
+      def validate_trusted_proxy_depth!(depth)
+        return if depth.nil?
+
+        unless depth.is_a?(Integer)
+          raise ArgumentError,
+                "trusted_proxy_depth must be an Integer or nil, got #{depth.class}"
+        end
+
+        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
+      # reject invalid types and the mutually-exclusive CIDR-walk vs depth
+      # combination at assignment. This re-checks at finalization as a backstop
+      # for a direct/ivar configuration path that bypassed the setters.
+      #
+      # @raise [ArgumentError] if depth is non-integer/negative, or if both
+      #   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?
+
+        raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if @trusted_proxy_depth >= 1 && @trusted_proxies.any?
+      end
+
+      # Parse a value into an IPAddr, returning nil for invalid / non-IP input.
+      #
+      # @param value [String] candidate IP or CIDR string
+      # @return [IPAddr, nil]
+      def parse_ipaddr(value)
+        IPAddr.new(value)
+      rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+        nil
+      end
+
+      # Build a cached matcher tuple for a proxy entry at registration time.
+      #
+      # String entries are parsed to an IPAddr exactly once here; the result is
+      # reused for both the legacy-entry warning and per-request matching, so
+      # trusted_proxy? never re-parses. Non-IP strings and Regexp/other entries
+      # store a nil range and fall back to prefix/regexp matching.
+      #
+      # @param entry [String, Regexp, Object] trusted proxy entry being added
+      # @return [Array(Object, IPAddr)] [raw_entry, parsed_range_or_nil]
+      def register_proxy_matcher(entry)
+        return [entry, nil] unless entry.is_a?(String)
+
+        range = parse_ipaddr(entry)
+        warn_legacy_proxy_entry(entry) unless range
+        [entry, range]
+      end
+
+      # Warn that a string proxy entry is not a valid IP/CIDR and will use
+      # legacy string-prefix matching.
+      #
+      # @param entry [String] trusted proxy entry
+      # @return [void]
+      def warn_legacy_proxy_entry(entry)
+        Otto.logger.warn(
+          "[Otto::Security::Config] trusted proxy #{entry.inspect} is not a " \
+          'valid IP or CIDR; using legacy string-prefix matching. Prefer a ' \
+          "CIDR range (e.g. '172.16.0.0/12')."
+        )
+      end
+
+      # CIDR/host containment that is safe across address families.
+      #
+      # @param range [IPAddr] trusted proxy range or host
+      # @param client [IPAddr] client address
+      # @return [Boolean]
+      def ip_in_range?(range, client)
+        return false unless range.family == client.family
+
+        range.include?(client)
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+
       def extract_existing_session_id(request)
         # Try session first
         begin
@@ -386,6 +652,59 @@ class Otto
         result == 0
       end
 
+      # HMAC-SHA256 signature binding a token's random component to a session id
+      # and the server-side secret. Keyed HMAC (not a bare digest) is what prevents
+      # token self-minting.
+      def sign_csrf_token(session_id, token)
+        OpenSSL::HMAC.hexdigest('SHA256', @csrf_secret, "#{session_id}:#{token}")
+      end
+
+      # Warn once per config instance when CSRF tokens are being signed with a
+      # randomly-generated per-process secret. Such tokens do not survive process
+      # restarts and are not shared across workers; set OTTO_CSRF_SECRET (or
+      # config.csrf_secret=) for stable multi-process behavior.
+      def warn_generated_csrf_secret
+        return unless @csrf_secret_generated
+        return if @csrf_secret_warning_emitted
+
+        @csrf_secret_warning_emitted = true
+        Otto.logger.warn(<<~MSG.gsub(/\s+/, ' ').strip)
+          [Otto::Security::Config] CSRF tokens are signed with a randomly
+          generated per-process secret; they will not survive restarts or be
+          valid across workers. Set OTTO_CSRF_SECRET (or config.csrf_secret=)
+          for stable CSRF tokens in multi-process deployments.
+        MSG
+      end
+
+      # Freeze-time backstop: refuse to finalize a production configuration that
+      # enables CSRF with a generated (non-configured) secret. Mirrors
+      # #validate_trusted_proxy_config! so the failure surfaces at boot, before
+      # serving traffic, for apps that deep-freeze their config.
+      def validate_csrf_secret_config!
+        raise ArgumentError, CSRF_SECRET_REQUIRED_MESSAGE if csrf_secret_unsafe_for_production?
+      end
+
+      # Generation-time guard for apps that never freeze their config: never
+      # mint a CSRF token signed with a generated per-process secret in
+      # production (fail loud instead of serving tokens that won't verify).
+      def reject_generated_secret_in_production!
+        raise ArgumentError, CSRF_SECRET_REQUIRED_MESSAGE if csrf_secret_unsafe_for_production?
+      end
+
+      # True when CSRF is enabled, the secret was randomly generated (not
+      # configured via OTTO_CSRF_SECRET / #csrf_secret=), and we are running in
+      # a production environment.
+      def csrf_secret_unsafe_for_production?
+        @csrf_protection && @csrf_secret_generated && production_environment?
+      end
+
+      # Whether RACK_ENV indicates a production deployment. Gated to an explicit
+      # allowlist (not "anything but dev") so test/unknown environments keep the
+      # zero-config generated-secret fallback.
+      def production_environment?
+        defined?(Otto) && Otto.respond_to?(:env?) && Otto.env?(:production, :prod)
+      end
+
       # Generate CSP directives for development environment
       #
       # Development mode allows inline scripts/styles and hot reloading connections

data/lib/otto/security/configurator.rb

@@ -36,6 +36,12 @@ class Otto
       #   - `true`: Enable with default settings
       #   - `Hash`: Provide custom rate limiting rules
       # @param trusted_proxies [String, Array<String>] IP addresses or CIDR ranges to trust
+      # @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
@@ -58,6 +64,8 @@ class Otto
         request_validation: false,
         rate_limiting: false,
         trusted_proxies: [],
+        trusted_proxy_depth: nil,
+        trusted_proxy_header: nil,
         security_headers: {},
         hsts: false,
         csp: false,
@@ -69,6 +77,8 @@ class Otto
         enable_rate_limiting!(rate_limiting.is_a?(Hash) ? rate_limiting : {}) if rate_limiting
 
         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
@@ -127,6 +137,26 @@ class Otto
         @security_config.add_trusted_proxy(proxy)
       end
 
+      # Set count-based trusted-proxy depth ("trust the last N hops") for
+      # non-enumerable proxy tiers (Fly, cloud load balancers, dynamic reverse
+      # proxies). Mutually exclusive with trusted_proxies; the conflict is
+      # validated when the configuration is frozen.
+      #
+      # @param depth [Integer, nil] number of trusted hops (nil/0 disables depth mode)
+      def trusted_proxy_depth=(depth)
+        @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.
       #

data/lib/otto/security/constant_resolver.rb

@@ -0,0 +1,73 @@
+# lib/otto/security/constant_resolver.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    # Shared, validated resolution of a class from its String name.
+    #
+    # Centralizes the class-name format check and the forbidden-class blocklist
+    # so every dispatch path that turns a route/handler string into a constant
+    # (Otto::Route, RouteHandlers::BaseHandler, and the MCP registry/server)
+    # enforces the SAME guards against code-injection via crafted class names.
+    module ConstantResolver
+      # A class name is a sequence of ::-separated, capitalized Ruby constant
+      # tokens. This also rejects leading "::" (a name must start with [A-Z]).
+      CLASS_NAME_PATTERN = /\A[A-Z][a-zA-Z0-9_]*(?:::[A-Z][a-zA-Z0-9_]*)*\z/
+
+      # Constants that must never be resolvable from untrusted route/handler
+      # strings, since dispatching to them enables arbitrary/dangerous behavior.
+      FORBIDDEN_CLASSES = %w[
+        Kernel Module Class Object BasicObject
+        File Dir IO Process System
+        Binding Proc Method UnboundMethod
+        Thread ThreadGroup Fiber
+        ObjectSpace GC
+      ].freeze
+
+      # The actual constant objects behind FORBIDDEN_CLASSES that exist in this
+      # runtime. The resolved constant is checked against these by identity so a
+      # forbidden class reached through a namespace prefix (e.g. "Object::Kernel")
+      # or via Ruby's trailing-segment constant inheritance (e.g. "App::File"
+      # falling back to top-level ::File) is rejected even though its literal
+      # string is not listed in FORBIDDEN_CLASSES. An app's OWN class that merely
+      # shares a name (a distinct object) is unaffected.
+      FORBIDDEN_CONSTANTS = FORBIDDEN_CLASSES.filter_map do |const_name|
+        Object.const_get(const_name) if Object.const_defined?(const_name, false)
+      end.freeze
+
+      module_function
+
+      # Resolve a validated class name to its Class object.
+      #
+      # @param class_name [String] fully-qualified class name (e.g. "App::Users")
+      # @return [Class, Module] the resolved constant
+      # @raise [ArgumentError] if the name is malformed, forbidden, or not found
+      def safe_const_get(class_name)
+        name = class_name.to_s
+
+        raise ArgumentError, "Invalid class name format: #{class_name}" unless name.match?(CLASS_NAME_PATTERN)
+
+        raise ArgumentError, "Forbidden class name: #{class_name}" if FORBIDDEN_CLASSES.include?(name)
+
+        fq_class_name = "::#{name.sub(/^::+/, '')}"
+
+        resolved =
+          begin
+            Object.const_get(fq_class_name)
+          rescue NameError => e
+            raise ArgumentError, "Class not found: #{fq_class_name} - #{e.message}"
+          end
+
+        # Reject forbidden constants reached via a namespace prefix or Ruby's
+        # trailing-segment constant inheritance, which the literal-name check
+        # above cannot see (e.g. "Object::Kernel", or "App::File" -> ::File).
+        if FORBIDDEN_CONSTANTS.any? { |forbidden| resolved.equal?(forbidden) }
+          raise ArgumentError, "Forbidden class name: #{class_name}"
+        end
+
+        resolved
+      end
+    end
+  end
+end

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

@@ -93,9 +93,10 @@ class Otto
           # Inject meta tag into HTML head
           body_content = body.respond_to?(:join) ? body.join : body.to_s
 
-          if body_content.match?(/<head>/i)
+          head_open_tag = /<head(?:\s[^>]*)?>/i
+          if body_content.match?(head_open_tag)
             meta_tag     = %(<meta name="csrf-token" content="#{csrf_token}">)
-            body_content = body_content.sub(/<head>/i, "<head>\n#{meta_tag}")
+            body_content = body_content.sub(head_open_tag) { |tag| "#{tag}\n#{meta_tag}" }
 
             # Update content length if present
             content_length_key          = headers.keys.find { |k| k.downcase == 'content-length' }