otto 2.2.0 → 2.3.0

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

@@ -15,7 +15,7 @@ class Otto
       #
       # @example Default behavior (privacy enabled)
       #   # env['REMOTE_ADDR'] is masked to 192.168.1.0
-      #   # env['otto.redacted_fingerprint'] contains full anonymized data
+      #   # env['otto.privacy.fingerprint'] contains full anonymized data
       #   # env['otto.original_ip'] is NOT set
       #
       # @example Privacy disabled
@@ -42,6 +42,22 @@ class Otto
         # @param env [Hash] Rack environment
         # @return [Array] Rack response tuple [status, headers, body]
         def call(env)
+          # Idempotency: if a prior IPPrivacyMiddleware pass already resolved the
+          # canonical client IP for this request, do not re-resolve or re-mask.
+          # This makes stacking two instances (e.g. an app-level mount plus
+          # Otto's built-in router mount) order-safe instead of double-masking.
+          return @app.call(env) if env.key?('otto.client_ip')
+
+          # Record the connecting peer's trust decision BEFORE any masking, so
+          # secure? can authorize X-Forwarded-Proto canonically even after
+          # REMOTE_ADDR is rewritten to the masked client IP. Leak-free boolean.
+          #
+          # This is the trusted-proxy *identity* check only — it is deliberately
+          # independent of count-based depth mode. Depth resolves the client IP;
+          # it never grants proxy trust for X-Forwarded-Proto (matching the
+          # downstream OneTimeSecret behavior).
+          env['otto.via_trusted_proxy'] = trusted_proxy?(env['REMOTE_ADDR'])
+
           if @privacy_enabled
             apply_privacy(env)
           else
@@ -63,7 +79,8 @@ class Otto
         #
         # @param env [Hash] Rack environment
         def apply_privacy(env)
-          # Resolve the actual client IP (handling proxies)
+          # Resolve the actual client IP once (handling proxies). This is the
+          # canonical resolution step; masking below operates on this value.
           client_ip = resolve_client_ip(env)
 
           Otto.logger.debug "[IPPrivacyMiddleware] Resolved client IP: #{client_ip}" if Otto.debug
@@ -75,6 +92,8 @@ class Otto
               # Update REMOTE_ADDR to the resolved client IP (even though it's not masked)
               env['REMOTE_ADDR'] = client_ip
               env['otto.original_ip'] = client_ip
+              # Canonical client IP downstream reads (exempt: not masked)
+              env['otto.client_ip'] = client_ip
               # Don't mask forwarded headers for private IPs
               Otto.logger.debug "[IPPrivacyMiddleware] Private/localhost IP exempted: #{client_ip}" if Otto.debug
               return
@@ -99,6 +118,10 @@ class Otto
           # automatically uses the masked values without modification
           env['REMOTE_ADDR'] = fingerprint.masked_ip
 
+          # Canonical client IP downstream reads ("resolve once, read everywhere").
+          # 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
@@ -118,41 +141,17 @@ class Otto
         end
 
 
-        # Resolve the actual client IP address from the request
+        # Resolve the actual client IP address from the request.
         #
-        # This method handles proxy scenarios by checking X-Forwarded-For and
-        # other proxy headers from trusted proxies, similar to Rack's logic
-        # and Otto's client_ipaddress method.
+        # Delegates to the shared Otto::Utils.resolve_client_ip so the
+        # middleware ("resolve once") and Otto::Request#client_ipaddress (its
+        # no-middleware fallback) use one canonical proxy-chain resolver and
+        # cannot drift on which headers are trusted.
         #
         # @param env [Hash] Rack environment
         # @return [String] Resolved client IP address
         def resolve_client_ip(env)
-          remote_addr = env['REMOTE_ADDR']
-
-          # If we don't have a security config, use direct connection
-          return remote_addr unless @security_config
-
-          # If REMOTE_ADDR is not from a trusted proxy, it's the client IP
-          return remote_addr unless trusted_proxy?(remote_addr)
-
-          # REMOTE_ADDR is from a trusted proxy, check forwarded headers
-          forwarded_ips = [
-            env['HTTP_X_FORWARDED_FOR'],
-            env['HTTP_X_REAL_IP'],
-            env['HTTP_X_CLIENT_IP'],
-          ].compact.map { |header| header.split(/,\s*/) }.flatten
-
-          # Return the first valid public IP from forwarded headers
-          forwarded_ips.each do |ip|
-            clean_ip = validate_ip_address(ip.strip)
-            next unless clean_ip
-
-            # Return first IP that's not from a trusted proxy
-            return clean_ip unless trusted_proxy?(clean_ip)
-          end
-
-          # Fallback to remote address if no valid forwarded IPs
-          remote_addr
+          Otto::Utils.resolve_client_ip(env, @security_config)
         end
 
         # Mask X-Forwarded-For and related proxy headers
@@ -182,26 +181,6 @@ class Otto
           @security_config.trusted_proxy?(ip)
         end
 
-        # Validate and clean IP address
-        #
-        # @param ip [String, nil] IP address to validate
-        # @return [String, nil] Cleaned IP or nil if invalid
-        def validate_ip_address(ip)
-          return nil if ip.nil? || ip.empty?
-
-          # Remove any port number
-          clean_ip = ip.split(':').first
-
-          # Basic IPv4 format validation
-          return nil unless clean_ip.match?(/\A\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\z/)
-
-          # Validate each octet
-          octets = clean_ip.split('.')
-          return nil unless octets.all? { |octet| (0..255).cover?(octet.to_i) }
-
-          clean_ip
-        end
-
         # Apply no-privacy settings (privacy explicitly disabled)
         #
         # When privacy is disabled, original IP is available for
@@ -209,6 +188,11 @@ class Otto
         #
         # @param env [Hash] Rack environment
         def apply_no_privacy(env)
+          # Resolve the canonical client IP once, even with privacy disabled, so
+          # downstream code can read env['otto.client_ip'] instead of re-deriving
+          # it from REMOTE_ADDR / forwarded headers.
+          env['otto.client_ip'] = resolve_client_ip(env)
+
           # Store original values for explicit access when privacy is disabled
           if env['REMOTE_ADDR']
             env['otto.original_ip'] = env['REMOTE_ADDR'].dup.force_encoding('UTF-8')

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

@@ -16,13 +16,11 @@ class Otto
         NULL_BYTE          = /\0/
 
         # HTML/XSS sanitization is handled by Loofah library for better security coverage
-
-        SQL_INJECTION_PATTERNS = [
-          /('|(\\')|(;)|(\\)|(--)|(%27)|(%3B)|(%3D))/i,
-          /(union|select|insert|update|delete|drop|create|alter|exec|execute)/i,
-          /(or|and)\s+\w+\s*=\s*\w+/i,
-          /\d+\s*(=|>|<|>=|<=|<>|!=)\s*\d+/i,
-        ].freeze
+        #
+        # NOTE: There is deliberately no SQL-injection pattern matching here.
+        # Input-validation blocklists for SQL are bypassable theater and produce
+        # false positives on legitimate input; the correct defense is
+        # parameterized queries / prepared statements at the data-access layer.
 
         def initialize(app, config = nil)
           @app    = app
@@ -181,14 +179,7 @@ class Otto
           sanitized = Loofah.fragment(original).scrub!(:whitewash).to_s
 
           # Remove control characters (sanitize, don't block)
-          sanitized = sanitized.gsub(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/, '')
-
-          # Check for SQL injection patterns
-          SQL_INJECTION_PATTERNS.each do |pattern|
-            raise Otto::Security::ValidationError, 'Potential SQL injection detected' if sanitized.match?(pattern)
-          end
-
-          sanitized
+          sanitized.gsub(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/, '')
         end
 
         include Otto::Security::ValidationHelpers

data/lib/otto/security.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require_relative 'security/core'
+require_relative 'security/constant_resolver'
 require_relative 'security/authentication/strategy_result'
 require_relative 'security/authorization_error'
 require_relative 'security/config'

data/lib/otto/utils.rb

@@ -2,11 +2,32 @@
 #
 # frozen_string_literal: true
 
+require 'ipaddr'
+
 class Otto
   # Utility methods for common operations and helpers
   module Utils
     extend self
 
+    # Forwarded-for style headers consulted (in order) when resolving the real
+    # client IP from behind a trusted proxy. Shared by IPPrivacyMiddleware and
+    # Otto::Request so the two resolvers cannot drift.
+    FORWARDED_FOR_HEADERS = %w[
+      HTTP_X_FORWARDED_FOR
+      HTTP_X_REAL_IP
+      HTTP_X_CLIENT_IP
+    ].freeze
+
+    # Special-use IPv4/IPv6 ranges that IPAddr's #private?/#loopback?/#link_local?
+    # predicates do not cover but that should still be treated as non-public
+    # (e.g. when picking the real client out of a forwarded chain).
+    SPECIAL_USE_RANGES = [
+      IPAddr.new('0.0.0.0/8'),   # "this" network / unspecified (IPv4)
+      IPAddr.new('224.0.0.0/4'), # IPv4 multicast
+      IPAddr.new('::/128'),      # IPv6 unspecified
+      IPAddr.new('ff00::/8'),    # IPv6 multicast
+    ].freeze
+
     # @return [Time] Current time in UTC
     def now
       Time.now.utc
@@ -35,5 +56,154 @@ class Otto
     def yes?(value)
       !value.to_s.empty? && %w[true yes 1].include?(value.to_s.downcase)
     end
+
+    # Validate and normalize an IP address (IPv4 and IPv6).
+    #
+    # Strips an optional port (IPv6-safe), validates with IPAddr, and returns
+    # the cleaned address string, or nil if the input is blank or malformed.
+    #
+    # @param ip [String, nil] candidate address, optionally with a port
+    # @return [String, nil] cleaned IP string, or nil if invalid
+    def normalize_ip(ip)
+      return nil if ip.nil? || ip.empty?
+
+      candidate = strip_ip_port(ip.strip)
+      return nil if candidate.nil? || candidate.empty?
+
+      # IPAddr validates both IPv4 and IPv6; raises for malformed input
+      IPAddr.new(candidate)
+      candidate
+    rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+      nil
+    end
+
+    # Strip an optional port without corrupting IPv6 addresses.
+    #
+    # Handles bracketed IPv6 with a port (`[2001:db8::1]:443`) and IPv4
+    # host:port (`203.0.113.5:443`). A bare IPv6 address (multiple colons,
+    # no brackets) is returned unchanged.
+    #
+    # @param ip [String] candidate address, possibly including a port
+    # @return [String] address with any port removed
+    def strip_ip_port(ip)
+      if ip.start_with?('[')
+        inner = ip[/\A\[([^\]]+)\]/, 1]
+        return inner if inner
+      end
+
+      return ip.split(':', 2).first if ip.count(':') == 1
+
+      ip
+    end
+
+    # Resolve the real client IP from a Rack env, honoring forwarded headers
+    # only when the connecting peer (REMOTE_ADDR) is a trusted proxy.
+    #
+    # This is the single canonical resolver shared by IPPrivacyMiddleware
+    # ("resolve once") and Otto::Request#client_ipaddress (its no-middleware
+    # fallback), so both paths agree on which headers to trust and how to walk
+    # a proxy chain. It walks the forwarded chain left-to-right and returns the
+    # first address that is not itself a trusted proxy; if the peer is not a
+    # trusted proxy (or there is no config) it returns REMOTE_ADDR unchanged.
+    #
+    # @param env [Hash] Rack environment
+    # @param security_config [Otto::Security::Config, nil] config exposing #trusted_proxy?
+    # @return [String, nil] resolved client IP (the raw REMOTE_ADDR when no proxy applies)
+    def resolve_client_ip(env, security_config)
+      remote_addr = env['REMOTE_ADDR']
+
+      # Count-based ("trust the last N hops") mode for non-enumerable proxy
+      # tiers (Fly, cloud load balancers, dynamic reverse proxies) where the
+      # CIDR-walk below has no enumerable proxy IPs to match. Mirrors Express
+      # `trust proxy = N`. Takes precedence over CIDR-walk; the two modes are
+      # mutually exclusive (enforced at config freeze).
+      return resolve_client_ip_by_depth(env, security_config) if security_config&.trusted_proxy_depth_mode?
+
+      # No config, or the peer is a direct (untrusted) connection: REMOTE_ADDR
+      # is the client. Don't honor forwarded headers from untrusted sources.
+      return remote_addr unless security_config&.trusted_proxy?(remote_addr)
+
+      forwarded_ips = FORWARDED_FOR_HEADERS
+                      .filter_map { |header| env[header] }
+                      .flat_map { |value| value.split(/,\s*/) }
+
+      forwarded_ips.each do |candidate|
+        clean_ip = normalize_ip(candidate.strip)
+        next unless clean_ip
+
+        # First address in the chain that isn't a known proxy is the client.
+        return clean_ip unless security_config.trusted_proxy?(clean_ip)
+      end
+
+      # Whole chain was trusted proxies (or empty): fall back to the peer.
+      remote_addr
+    end
+
+    # Resolve the client IP by trusting a fixed number of proxy hops, counted
+    # 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.
+    #
+    # 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.
+    # 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.
+    #
+    # @param env [Hash] Rack environment
+    # @param security_config [Otto::Security::Config] config exposing #trusted_proxy_depth
+    # @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)
+      chain     = forwarded + [remote_addr]
+
+      index = chain.length - (depth + 1)
+      return remote_addr if index.negative? # chain shorter than depth + 1
+
+      normalize_ip(chain[index].to_s.strip) || remote_addr
+    end
+
+    # Whether an address is non-public: RFC1918 private, loopback, link-local,
+    # multicast, or unspecified — for both IPv4 and IPv6.
+    #
+    # Uses IPAddr's family-aware predicates (which also fold IPv4-mapped IPv6
+    # via #native) plus an explicit set of special-use ranges that the
+    # predicates don't cover (IPv4 0.0.0.0/8 and 224.0.0.0/4, IPv6 ::/128 and
+    # ff00::/8). Returns false for malformed input rather than raising.
+    #
+    # @param ip [String, IPAddr, nil] address to classify
+    # @return [Boolean]
+    def private_ip?(ip)
+      return false if ip.nil?
+      return false if ip.respond_to?(:empty?) && ip.empty?
+
+      addr = ip.is_a?(IPAddr) ? ip : IPAddr.new(strip_ip_port(ip.to_s.strip))
+      addr = addr.native # fold IPv4-mapped IPv6 (::ffff:a.b.c.d) to IPv4
+
+      return true if addr.private? || addr.loopback? || addr.link_local?
+
+      SPECIAL_USE_RANGES.any? { |range| range.family == addr.family && range.include?(addr) }
+    rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+      false
+    end
   end
 end

data/lib/otto/version.rb

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

data/lib/otto.rb

@@ -214,7 +214,15 @@ class Otto
   end
 
   class << self
-    attr_accessor :debug, :logger # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+    attr_accessor :debug # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+    attr_writer :logger # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+
+    # Otto's logger. Never nil: falls back to a default $stdout logger so call
+    # sites can log unconditionally without defensive `&.` guards. Assign your
+    # own logger (or a null logger to silence) via `Otto.logger = ...`.
+    def logger
+      @logger ||= Logger.new($stdout, Logger::INFO)
+    end
 
     # Helper method for structured logging that works with both standard Logger and structured loggers
     def structured_log(level, message, data = {})

data/otto.gemspec

@@ -21,7 +21,14 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ['>= 3.2', '< 4.1']
 
   spec.add_dependency 'concurrent-ruby', '~> 1.3', '< 2.0'
-  spec.add_dependency 'ipaddr', '~> 1', '< 2.0'
+
+  # ipaddr is a default gem on every supported Ruby (3.2+), so `require
+  # 'ipaddr'` works without a gemspec dependency. Declaring one collides
+  # with bundler 2.7.x's default-gem handling: the lockfile pins a version
+  # newer than the activated default and bundler refuses to swap, breaking
+  # `bundle exec` (including `rake release`). Drop the declaration and
+  # rely on the runtime default gem until bundler ships default-gem
+  # override support for ipaddr.
 
   # Logger is not part of the default gems as of Ruby 3.5.0
   spec.add_dependency 'logger', '~> 1', '< 2.0'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -29,26 +29,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: ipaddr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -162,6 +142,7 @@ files:
 - docs/ipaddr-encoding-quirk.md
 - docs/migrating/v2.0.0-pre1.md
 - docs/migrating/v2.0.0-pre2.md
+- docs/migrating/v2.3.0.md
 - docs/modern-authentication-authorization-landscape.md
 - docs/multi-strategy-authentication-design.md
 - examples/.gitignore
@@ -295,6 +276,7 @@ files:
 - lib/otto/security/authorization_error.rb
 - lib/otto/security/config.rb
 - lib/otto/security/configurator.rb
+- lib/otto/security/constant_resolver.rb
 - lib/otto/security/core.rb
 - lib/otto/security/csrf.rb
 - lib/otto/security/middleware/csrf_middleware.rb