otto 2.1.0 → 2.3.0

data/lib/otto/mcp/registry.rb

@@ -2,6 +2,8 @@
 #
 # frozen_string_literal: true
 
+require_relative '../security/constant_resolver'
+
 class Otto
   module MCP
     # Registry for managing MCP resources and tools
@@ -82,7 +84,7 @@ class Otto
           klass_name   = klass_method[0..-2].join('::')
           method_name  = klass_method.last
 
-          klass  = Object.const_get(klass_name)
+          klass  = Otto::Security::ConstantResolver.safe_const_get(klass_name)
           result = klass.public_send(method_name, arguments, env)
         else
           raise "Invalid tool handler: #{handler}"

data/lib/otto/mcp/server.rb

@@ -8,6 +8,7 @@ require_relative 'route_parser'
 require_relative 'auth/token'
 require_relative 'schema_validation'
 require_relative 'rate_limiting'
+require_relative '../security/constant_resolver'
 
 class Otto
   module MCP
@@ -124,7 +125,7 @@ class Otto
 
         # Create resource handler
         handler = lambda do
-          klass = Object.const_get(klass_name)
+          klass = Otto::Security::ConstantResolver.safe_const_get(klass_name)
           method = klass.method(method_name)
           if method.arity != 0
             raise ArgumentError, "Handler #{klass_name}.#{method_name} must be a zero-arity method for resource #{uri}"

data/lib/otto/request.rb

@@ -24,13 +24,25 @@ class Otto
       env['HTTP_USER_AGENT']
     end
 
-    # NOTE: We do NOT override Rack::Request#ip
+    # Canonical client IP for the request.
     #
-    # IPPrivacyMiddleware masks both REMOTE_ADDR and X-Forwarded-For headers,
-    # so Rack's native ip resolution logic works correctly with masked values.
-    # This allows Rack to handle proxy scenarios (trusted proxies, header parsing)
-    # while still returning privacy-safe masked IPs.
+    # Prefers env['otto.client_ip'] — the value resolved once, early, by
+    # IPPrivacyMiddleware ("resolve once, read everywhere"): the masked IP
+    # when privacy is enabled, or the resolved real IP when privacy is
+    # disabled or the address is exempt. This means downstream code no longer
+    # depends on REMOTE_ADDR / X-Forwarded-For rewriting being load-bearing.
     #
+    # Falls back to Rack's native resolution when the middleware has not run
+    # (e.g. standalone request use without the Otto middleware stack).
+    #
+    # @return [String, nil] Canonical (privacy-applied) client IP
+    def ip
+      canonical = env['otto.client_ip']
+      return canonical if canonical && !canonical.empty?
+
+      super
+    end
+
     # If you need the masked IP explicitly, use:
     #   req.masked_ip  # => '192.168.1.0' or nil if privacy disabled
     #
@@ -51,7 +63,7 @@ class Otto
     #   fingerprint.masked_ip    # => '192.168.1.0'
     #   fingerprint.country      # => 'US'
     def redacted_fingerprint
-      env['otto.redacted_fingerprint']
+      env['otto.privacy.fingerprint']
     end
 
     # Get the geo-location country code for the request
@@ -63,7 +75,7 @@ class Otto
     # @example
     #   req.geo_country  # => 'US'
     def geo_country
-      redacted_fingerprint&.country || env['otto.geo_country']
+      redacted_fingerprint&.country || env['otto.privacy.geo_country']
     end
 
     # Get anonymized user agent string
@@ -91,7 +103,7 @@ class Otto
     # @example
     #   req.masked_ip  # => '192.168.1.0'
     def masked_ip
-      env['otto.masked_ip'] || env['REMOTE_ADDR']
+      env['otto.privacy.masked_ip'] || env['REMOTE_ADDR']
     end
 
     # Get hashed IP for session correlation
@@ -104,30 +116,19 @@ class Otto
     # @example
     #   req.hashed_ip  # => 'a3f8b2c4d5e6f7...'
     def hashed_ip
-      redacted_fingerprint&.hashed_ip || env['otto.hashed_ip']
+      redacted_fingerprint&.hashed_ip || env['otto.privacy.hashed_ip']
     end
 
     def client_ipaddress
-      remote_addr = env['REMOTE_ADDR']
-
-      # If we don't have a security config or trusted proxies, use direct connection
-      return validate_ip_address(remote_addr) if !otto_security_config || !trusted_proxy?(remote_addr)
-
-      # Check forwarded headers from trusted proxies
-      forwarded_ips = [
-        env['HTTP_X_FORWARDED_FOR'],
-        env['HTTP_X_REAL_IP'],
-        env['HTTP_CLIENT_IP'],
-      ].compact.map { |header| header.split(/,\s*/) }.flatten
-
-      # Return the first valid IP that's not a private/loopback address
-      forwarded_ips.each do |ip|
-        clean_ip = validate_ip_address(ip.strip)
-        return clean_ip if clean_ip && !private_ip?(clean_ip)
-      end
-
-      # Fallback to remote address
-      validate_ip_address(remote_addr)
+      # Prefer the canonical client IP resolved once by IPPrivacyMiddleware
+      # ("resolve once, read everywhere"). Falls back to the shared resolver
+      # (Otto::Utils.resolve_client_ip) for standalone use without the
+      # middleware, so the with- and without-middleware paths agree on which
+      # forwarded headers to trust and how to walk a proxy chain.
+      canonical = env['otto.client_ip']
+      return canonical if canonical && !canonical.empty?
+
+      Otto::Utils.resolve_client_ip(env, otto_security_config)
     end
 
     def request_method
@@ -180,16 +181,31 @@ class Otto
       # Check direct HTTPS connection
       return true if env['HTTPS'] == 'on' || env['SERVER_PORT'] == '443'
 
-      remote_addr = env['REMOTE_ADDR']
+      # Only trust forwarded proto headers when the request actually arrived via
+      # a trusted proxy.
+      return false unless forwarded_by_trusted_proxy?
 
-      # Only trust forwarded proto headers from trusted proxies
-      if otto_security_config && trusted_proxy?(remote_addr)
-        # X-Scheme is set by nginx
-        # X-FORWARDED-PROTO is set by elastic load balancer
-        return env['HTTP_X_FORWARDED_PROTO'] == 'https' || env['HTTP_X_SCHEME'] == 'https'
-      end
+      # X-Scheme is set by nginx; X-Forwarded-Proto by elastic load balancer
+      env['HTTP_X_FORWARDED_PROTO'] == 'https' || env['HTTP_X_SCHEME'] == 'https'
+    end
 
-      false
+    # Whether the request arrived through a trusted proxy.
+    #
+    # Prefers the canonical decision recorded once by IPPrivacyMiddleware in
+    # env['otto.via_trusted_proxy'] — evaluated against the original peer before
+    # REMOTE_ADDR is masked, so it stays correct even after masking. Falls back
+    # to evaluating the current REMOTE_ADDR when the middleware has not run
+    # (standalone request use).
+    #
+    # This is the trusted-proxy *identity* check only and is independent of
+    # count-based depth mode: depth resolves the client IP but never grants
+    # proxy trust for X-Forwarded-Proto.
+    #
+    # @return [Boolean]
+    def forwarded_by_trusted_proxy?
+      return env['otto.via_trusted_proxy'] if env.key?('otto.via_trusted_proxy')
+
+      otto_security_config ? trusted_proxy?(env['REMOTE_ADDR']) : false
     end
 
     # See: http://stackoverflow.com/questions/10013812/how-to-prevent-jquery-ajax-from-following-a-redirect-after-a-post
@@ -227,41 +243,25 @@ class Otto
     end
 
     def validate_ip_address(ip)
-      return nil if ip.nil? || ip.empty?
-
-      # Remove any port number
-      clean_ip = ip.split(':').first
-
-      # Basic IP 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
+      Otto::Utils.normalize_ip(ip)
     end
 
+    # Whether the given address is non-public (private, loopback, link-local,
+    # multicast or unspecified). IPv4 and IPv6 aware via Otto::Utils.private_ip?
+    # — the previous implementation was an IPv4-only regex that silently
+    # treated every IPv6 address (including ::1 and ULA fc00::/7) as public.
+    #
+    # @param ip [String, IPAddr, nil] address to classify
+    # @return [Boolean]
     def private_ip?(ip)
-      return false unless ip
-
-      # RFC 1918 private ranges and loopback
-      private_ranges = [
-        /\A10\./, # 10.0.0.0/8
-        /\A172\.(1[6-9]|2[0-9]|3[01])\./, # 172.16.0.0/12
-        /\A192\.168\./,              # 192.168.0.0/16
-        /\A169\.254\./,              # 169.254.0.0/16 (link-local)
-        /\A224\./,                   # 224.0.0.0/4 (multicast)
-        /\A0\./, # 0.0.0.0/8
-      ]
-
-      private_ranges.any? { |range| ip.match?(range) }
+      Otto::Utils.private_ip?(ip)
     end
 
     def local_or_private_ip?(ip)
       return false unless ip
 
-      # Check for localhost
+      # Fast path for the common localhost cases (avoids IPAddr allocation);
+      # private_ip? would also catch these via IPAddr#loopback?.
       return true if ['127.0.0.1', '::1'].include?(ip)
 
       # Check for private IP ranges

data/lib/otto/route.rb

@@ -2,6 +2,8 @@
 #
 # frozen_string_literal: true
 
+require_relative 'security/constant_resolver'
+
 class Otto
   # Otto::Route
   #
@@ -51,7 +53,7 @@ class Otto
       @route_definition = Otto::RouteDefinition.new(verb, path, definition, pattern: pattern, keys: keys)
 
       # Resolve the class
-      @klass = safe_const_get(@route_definition.klass_name)
+      @klass = Otto::Security::ConstantResolver.safe_const_get(@route_definition.klass_name)
     end
 
     # Delegate common methods to route_definition for backward compatibility
@@ -170,48 +172,6 @@ class Otto
 
     private
 
-    # Safely resolve a class name using Object.const_get with security validations
-    # This replaces the previous eval() usage to prevent code injection attacks.
-    #
-    # Security features:
-    # - Validates class name format (must start with capital letter)
-    # - Prevents access to dangerous system classes
-    # - Blocks relative class references (starting with ::)
-    # - Provides clear error messages for debugging
-    #
-    # @param class_name [String] The class name to resolve
-    # @return [Class] The resolved class
-    # @raise [ArgumentError] if class name is invalid, forbidden, or not found
-    def safe_const_get(class_name)
-      # Validate class name format
-      unless class_name.match?(/\A[A-Z][a-zA-Z0-9_]*(?:::[A-Z][a-zA-Z0-9_]*)*\z/)
-        raise ArgumentError, "Invalid class name format: #{class_name}"
-      end
-
-      # Remove any leading :: then add exactly one
-      fq_class_name = "::#{class_name.sub(/^::+/, '')}"
-
-      # Prevent dangerous class names
-      forbidden_classes = %w[
-        Kernel Module Class Object BasicObject
-        File Dir IO Process System
-        Binding Proc Method UnboundMethod
-        Thread ThreadGroup Fiber
-        ObjectSpace GC
-      ]
-
-      if forbidden_classes.include?(class_name) || class_name.start_with?('::')
-        raise ArgumentError, "Forbidden class name: #{class_name}"
-      end
-
-      begin
-        # Always guarantee exactly two leading colons
-        Object.const_get(fq_class_name)
-      rescue NameError => e
-        raise ArgumentError, "Class not found: #{fq_class_name} - #{e.message}"
-      end
-    end
-
     def compile(path)
       keys = []
 

data/lib/otto/route_handlers/base.rb

@@ -5,6 +5,8 @@
 require 'json'
 require 'securerandom'
 
+require_relative '../security/constant_resolver'
+
 class Otto
   module RouteHandlers
     # Base class for all route handlers
@@ -43,7 +45,7 @@ class Otto
       # Get the target class, loading it safely
       # @return [Class] The target class
       def target_class
-        @target_class ||= safe_const_get(route_definition.klass_name)
+        @target_class ||= Otto::Security::ConstantResolver.safe_const_get(route_definition.klass_name)
       end
 
       # Template method for subclasses to implement their invocation logic
@@ -187,19 +189,6 @@ class Otto
 
         handler_class.handle(result, response, context)
       end
-
-      private
-
-      # Safely get a constant from a string name
-      # @param name [String] Class name
-      # @return [Class] The class
-      def safe_const_get(name)
-        name.split('::').inject(Object) do |scope, const_name|
-          scope.const_get(const_name)
-        end
-      rescue NameError => e
-        raise NameError, "Unknown class: #{name} (#{e})"
-      end
     end
   end
 end

data/lib/otto/security/authentication/auth_strategy.rb

@@ -31,20 +31,47 @@ class Otto
           Otto::Security::Authentication::StrategyResult.new(
             session: session,
             user: user,
-            auth_method: auth_method || self.class.name.split('::').last,
+            auth_method: auth_method || strategy_auth_method,
             metadata: metadata,
             strategy_name: nil # Will be set by RouteAuthWrapper
           )
         end
 
         # Helper for authentication failure - return AuthFailure
+        #
+        # Use for a missing, invalid, or expired credential. RouteAuthWrapper maps
+        # this to 401 Unauthorized. For a VALID credential that is not permitted,
+        # use #authorization_failure instead (403 Forbidden).
         def failure(reason = nil)
           Otto.logger.debug "[#{self.class}] Authentication failed: #{reason}" if reason
           Otto::Security::Authentication::AuthFailure.new(
             failure_reason: reason || 'Authentication failed',
-            auth_method: self.class.name.split('::').last
+            auth_method: strategy_auth_method
+          )
+        end
+
+        # Helper for authorization failure - return AuthorizationFailure
+        #
+        # Use when the credential is valid but the authenticated subject is not
+        # permitted (wrong role, missing permission). RouteAuthWrapper maps this to
+        # 403 Forbidden, letting clients distinguish "authenticate again" (401) from
+        # "you lack this permission" (403). See AuthorizationFailure.
+        def authorization_failure(reason = nil)
+          Otto.logger.debug "[#{self.class}] Authorization denied: #{reason}" if reason
+          Otto::Security::Authentication::AuthorizationFailure.new(
+            failure_reason: reason || 'Authorization denied',
+            auth_method: strategy_auth_method
           )
         end
+
+        private
+
+        # Short auth_method label from the strategy class name. Anonymous strategy
+        # classes (Class.new(...), common in tests) have a nil #name, so fall back
+        # to a generic label rather than raising on nil#split.
+        def strategy_auth_method
+          (self.class.name || 'AuthStrategy').split('::').last
+        end
       end
     end
   end

data/lib/otto/security/authentication/authorization_failure.rb

@@ -0,0 +1,56 @@
+# lib/otto/security/authentication/authorization_failure.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module Authentication
+      # Result for AUTHORIZATION failures (authenticated, but not permitted).
+      #
+      # This is distinct from AuthFailure, which represents an AUTHENTICATION
+      # failure (no/invalid/expired credential). A strategy that performs both
+      # authentication and authorization in one pass (e.g. a token strategy that
+      # also enforces a role/permission encoded in the route requirement) returns:
+      #
+      #   * AuthFailure          -> credential missing/invalid  -> 401 Unauthorized
+      #   * AuthorizationFailure -> credential valid, but denied -> 403 Forbidden
+      #
+      # Without this type a combined strategy could only return AuthFailure, and
+      # RouteAuthWrapper would collapse an authorization denial to 401 — leaving a
+      # client unable to distinguish "authenticate again" from "you lack this
+      # permission." The wrapper maps this type to ResponseBuilder#forbidden (403);
+      # see RouteAuthWrapper#handle_all_strategies_failed.
+      #
+      # NOTE: Otto's built-in Layer-1 role check (RoleAuthorization, driven by the
+      # `role=` route token) already yields 403 for role mismatches on a successful
+      # StrategyResult. This type covers the complementary case: a strategy that
+      # owns authorization itself (including permission tiers, which Layer-1 does
+      # not model) and needs to signal a 403 directly.
+      AuthorizationFailure = Data.define(:failure_reason, :auth_method) do
+        # Authorization failures are not an authenticated request state. The
+        # request never reaches the handler, so handler-facing predicates report
+        # the same "no user context" shape AuthFailure does.
+        #
+        # @return [Boolean] False
+        def authenticated?
+          false
+        end
+
+        # @return [Boolean] True (no user context attached to a denial)
+        def anonymous?
+          true
+        end
+
+        # @return [Hash] Empty hash
+        def user_context
+          {}
+        end
+
+        # @return [String] Debug representation
+        def inspect
+          "#<AuthorizationFailure reason=#{failure_reason.inspect} method=#{auth_method}>"
+        end
+      end
+    end
+  end
+end

data/lib/otto/security/authentication/route_auth_wrapper.rb

@@ -106,11 +106,18 @@ class Otto
                                         duration, total_start_time, failed_strategies)
             end
 
-            # Handle authentication failure - continue to next strategy
-            next unless result.is_a?(AuthFailure)
+            # Handle a failure (authentication OR authorization) - record it and
+            # continue to the next strategy (OR logic; a later success still wins).
+            # AuthorizationFailure (valid credential, denied) is tagged so the
+            # final response is 403 instead of 401. See handle_all_strategies_failed.
+            next unless result.is_a?(AuthFailure) || result.is_a?(AuthorizationFailure)
 
             log_strategy_failure(env, strategy_name, result, duration, auth_requirements, requirement)
-            failed_strategies << { strategy: strategy_name, reason: result.failure_reason }
+            failed_strategies << {
+              strategy: strategy_name,
+              reason: result.failure_reason,
+              authorization: result.is_a?(AuthorizationFailure),
+            }
           end
 
           # All strategies failed
@@ -156,6 +163,14 @@ class Otto
             strategy_name: failure_strategy_name
           )
 
+          # Authorization denial wins over authentication failure: if any strategy
+          # authenticated the subject but denied authorization (wrong role/missing
+          # permission), respond 403 Forbidden rather than 401 — the subject IS
+          # authenticated, they simply lack access. A bare 401 would (incorrectly)
+          # tell a logged-in client to re-authenticate.
+          authz_denial = failed_strategies.find { |f| f[:authorization] }
+          return @response_builder.forbidden(env, authz_denial[:reason]) if authz_denial
+
           last_failure = if failed_strategies.any?
                            AuthFailure.new(
                              failure_reason: failed_strategies.last[:reason],
@@ -173,7 +188,7 @@ class Otto
 
         # Build metadata for anonymous routes
         def build_anonymous_metadata(env)
-          metadata = { ip: env['REMOTE_ADDR'] }
+          metadata = { ip: env['otto.client_ip'] || env['REMOTE_ADDR'] }
           metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
           metadata
         end
@@ -181,7 +196,7 @@ class Otto
         # Build metadata for failed authentication
         def build_failure_metadata(env, failed_strategies)
           metadata = {
-                          ip: env['REMOTE_ADDR'],
+                          ip: env['otto.client_ip'] || env['REMOTE_ADDR'],
                 auth_failure: 'All authentication strategies failed',
             attempted_strategies: failed_strategies.map { |f| f[:strategy] },
                  failure_reasons: failed_strategies.map { |f| f[:reason] },

data/lib/otto/security/authentication/strategies/api_key_strategy.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require_relative '../auth_strategy'
+require 'rack/utils'
 
 class Otto
   module Security
@@ -27,7 +28,7 @@ class Otto
 
             return failure('No API key provided') unless api_key
 
-            if @api_keys.empty? || @api_keys.include?(api_key)
+            if @api_keys.empty? || valid_api_key?(api_key)
               # Create a simple user hash for API key authentication
               user_data = { api_key: api_key }
               success(user: user_data, api_key: api_key)
@@ -35,6 +36,17 @@ class Otto
               failure('Invalid API key')
             end
           end
+
+          private
+
+          # Constant-time membership check over the configured API keys. Compares
+          # against every key without short-circuiting so match position/membership is
+          # not leaked via timing.
+          def valid_api_key?(api_key)
+            @api_keys.reduce(false) do |matched, key|
+              Rack::Utils.secure_compare(key, api_key) || matched
+            end
+          end
         end
       end
     end

data/lib/otto/security/authentication/strategies/noauth_strategy.rb

@@ -12,9 +12,11 @@ class Otto
         # Public access strategy - always allows access
         class NoAuthStrategy < AuthStrategy
           def authenticate(env, _requirement)
-            # Note: env['REMOTE_ADDR'] is masked by IPPrivacyMiddleware by default
-            metadata = { ip: env['REMOTE_ADDR'] }
-            metadata[:country] = env['otto.geo_country'] if env['otto.geo_country']
+            # Canonical client IP ("resolve once, read everywhere"): masked by
+            # IPPrivacyMiddleware when privacy is on; REMOTE_ADDR fallback when
+            # the middleware has not run.
+            metadata = { ip: env['otto.client_ip'] || env['REMOTE_ADDR'] }
+            metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
 
             Otto::Security::Authentication::StrategyResult.anonymous(metadata: metadata)
           end

data/lib/otto/security/authentication.rb

@@ -8,6 +8,7 @@
 require_relative 'authentication/auth_strategy'
 require_relative 'authentication/strategy_result'
 require_relative 'authentication/auth_failure'
+require_relative 'authentication/authorization_failure'
 require_relative 'authentication/route_auth_wrapper'
 
 # Load all strategies
@@ -31,4 +32,5 @@ class Otto
   # Top-level backward compatibility aliases
   StrategyResult = Security::Authentication::StrategyResult
   AuthFailure = Security::Authentication::AuthFailure
+  AuthorizationFailure = Security::Authentication::AuthorizationFailure
 end