otto 2.5.0 → 2.6.0

data/lib/otto/core/router.rb

@@ -17,7 +17,13 @@ class Otto
           # Enhanced parsing: split only on first two whitespace boundaries
           # This preserves parameters in the definition part
           parts = entry.split(/\s+/, 3)
-          next if parts.size < 3 # Skip malformed entries
+          if parts.size < 3
+            # A missing/blank handler must not make the route vanish silently
+            # (issue #191): warn unconditionally, not gated behind Otto.debug.
+            Otto.structured_log(:warn, 'Malformed route line skipped',
+              { line: entry, expected: 'VERB /path Handler [options]' })
+            next
+          end
 
           verb = parts[0]
           path = parts[1]
@@ -32,10 +38,32 @@ class Otto
             next
           end
 
-          route                                   = Otto::Route.new verb, path, definition
-          route.otto                              = self
-          path_clean                              = path.gsub(%r{/$}, '')
-          @route_definitions[route.definition]    = route
+          route      = Otto::Route.new verb, path, definition
+          route.otto = self
+          path_clean = path.gsub(%r{/$}, '')
+
+          # A definition string is not unique (the same handler can be mounted
+          # at several verb/path pairs), so @route_definitions keeps the
+          # first-loaded route per definition — deterministic, instead of the
+          # last-loaded route silently winning — and @routes_by_definition
+          # keeps them all for uri() disambiguation (issue #190).
+          if (existing = @route_definitions[route.definition])
+            # Mounting one handler at several paths is a fully supported
+            # pattern (issue #190) — uri() disambiguates by params, so this
+            # is informational, not a problem. Debug-gated like other
+            # routing diagnostics rather than warning on every boot for
+            # valid configs (e.g. `/users/:id` and `/me` aliases).
+            Otto.structured_log(:debug, 'Duplicate route definition',
+              {
+                definition: route.definition,
+                kept: "#{existing.verb} #{existing.path}",
+                also: "#{route.verb} #{route.path}",
+                hint: 'uri() picks the route whose path params match the given params',
+              })
+          else
+            @route_definitions[route.definition] = route
+          end
+          (@routes_by_definition[route.definition] ||= []) << route
           if Otto.debug
             Otto.structured_log(:debug, 'Route loaded',
               {
@@ -49,6 +77,11 @@ class Otto
           @routes[route.verb] << route
           @routes_literal[route.verb]           ||= {}
           @routes_literal[route.verb][path_clean] = route
+        rescue Otto::RouteDefinitionError
+          # A malformed security-gating option (auth/role/csrf) fails fast at
+          # boot rather than serving the route without its intended protection
+          # (issue #191). Deliberately not swallowed like other per-line errors.
+          raise
         rescue StandardError => e
           Otto.structured_log(:error, 'Route load failed',
             {
@@ -91,7 +124,21 @@ class Otto
         literal_routes = routes_literal[http_verb] || {}
         literal_routes.merge! routes_literal[:GET] if http_verb == :HEAD
 
-        if static_route && http_verb == :GET && routes_static[:GET].member?(base_path)
+        # Dynamic-route and static-file dispatch match against the SAME
+        # normalized path the literal table and the LocalhostGuard use, so all
+        # dispatch paths share one normalization (issue #187). Without this,
+        # dynamic routes matched the raw (unescape-only) path: they were
+        # stricter about trailing slashes than literal routes (equivalent URLs
+        # matched or missed depending on route kind), and invalid-UTF-8 bytes
+        # scrubbed for the guard and literal matching survived into the dynamic
+        # matcher and safe_file? — the guard-bypass class normalize_path exists
+        # to close. normalize_path collapses root to '' after stripping the
+        # trailing slash; the regex matcher and safe_file? need a leading slash
+        # to be structural (a catch-all `/*` still matches `/`), so restore '/'
+        # for them. Literal lookup keeps '' — it already keys root that way.
+        dispatch_path = path_info_clean.empty? ? '/' : path_info_clean
+
+        if static_route && http_verb == :GET && routes_static[:GET].key?(base_path)
           Otto.structured_log(:debug, 'Route matched',
             Otto::LoggingHelpers.request_context(env).merge(
               type: 'static_cached',
@@ -111,7 +158,7 @@ class Otto
             @route_matched_callbacks.each { |cb| cb.call(env, route.route_definition) }
           end
           route.call(env)
-        elsif static_route && http_verb == :GET && safe_file?(path_info)
+        elsif static_route && http_verb == :GET && safe_file?(dispatch_path)
           Otto.structured_log(:debug, 'Route matched',
             Otto::LoggingHelpers.request_context(env).merge(
               type: 'static_new',
@@ -120,7 +167,7 @@ class Otto
           routes_static[:GET][base_path] = base_path
           static_route.call(env)
         else
-          match_dynamic_route(env, path_info, http_verb, literal_routes)
+          match_dynamic_route(env, dispatch_path, http_verb, literal_routes)
         end
       end
 
@@ -144,14 +191,18 @@ class Otto
 
       private
 
-      def match_dynamic_route(env, path_info, http_verb, literal_routes)
+      # +dispatch_path+ is the normalized path from #handle_request (see the
+      # +dispatch_path+ comment there): +Otto::Utils.normalize_path+ output with
+      # root's empty string mapped back to '/' so the anchored route regexes can
+      # match. It is deliberately NOT the raw +normalize_path+ value.
+      def match_dynamic_route(env, dispatch_path, http_verb, literal_routes)
         extra_params  = {}
         found_route   = nil
         valid_routes  = routes[http_verb] || []
         valid_routes.push(*routes[:GET]) if http_verb == :HEAD
 
         valid_routes.each do |route|
-          next unless (match = route.pattern.match(path_info))
+          next unless (match = route.pattern.match(dispatch_path))
 
           values = match.captures.to_a
           # The first capture returned is the entire matched string b/c
@@ -219,6 +270,10 @@ class Otto
         route_info = Otto::MCP::RouteParser.parse_mcp_route(verb, path, definition)
         @mcp_server.register_mcp_route(route_info)
         Otto.logger.debug "[MCP] Registered resource route: #{definition}" if Otto.debug
+      rescue Otto::RouteDefinitionError
+        # Same fail-fast contract as the normal route loader: a malformed
+        # security-gating option must abort boot, not just log-and-drop.
+        raise
       rescue StandardError => e
         Otto.logger.error "[MCP] Failed to parse MCP route: #{definition} - #{e.message}"
       end
@@ -229,6 +284,8 @@ class Otto
         route_info = Otto::MCP::RouteParser.parse_tool_route(verb, path, definition)
         @mcp_server.register_mcp_route(route_info)
         Otto.logger.debug "[MCP] Registered tool route: #{definition}" if Otto.debug
+      rescue Otto::RouteDefinitionError
+        raise
       rescue StandardError => e
         Otto.logger.error "[MCP] Failed to parse TOOL route: #{definition} - #{e.message}"
       end

data/lib/otto/core/uri_generator.rb

@@ -14,8 +14,7 @@ class Otto
       #     Otto.default.path 'YourClass.somemethod'  #=> /some/path
       #
       def uri(route_definition, params = {})
-        # raise RuntimeError, "Not working"
-        route = @route_definitions[route_definition]
+        route = select_uri_route(route_definition, params)
         return if route.nil?
 
         local_params = params.clone
@@ -39,6 +38,41 @@ class Otto
         end
         uri.to_s
       end
+
+      private
+
+      # Pick which route a reverse lookup means when one definition string is
+      # mounted at several verb/path pairs (issue #190). Routes whose path
+      # placeholders are all present in +params+ are preferred; among those,
+      # the route consuming the most params wins. Ties keep load order, so a
+      # single-route definition behaves exactly as before.
+      #
+      # e.g. with `GET /users/:id Account#show` and `GET /me Account#show`:
+      #   uri('Account#show', id: 5) #=> /users/5
+      #   uri('Account#show')        #=> /me
+      def select_uri_route(route_definition, params)
+        candidates = routes_for_definition(route_definition)
+        # @route_definitions fallback covers hand-assembled instances whose
+        # routes never went through Otto#load.
+        return candidates.first || @route_definitions[route_definition] if candidates.size <= 1
+
+        param_keys = params.keys.map(&:to_s)
+        satisfied  = candidates.select { |route| (required_keys(route) - param_keys).empty? }
+        pool       = satisfied.empty? ? candidates : satisfied
+        pool.max_by { |route| (route.keys & param_keys).size }
+      end
+
+      def routes_for_definition(route_definition)
+        (@routes_by_definition && @routes_by_definition[route_definition]) || []
+      end
+
+      # `splat` is a positional catch-all captured from a `*` in the path,
+      # not a named parameter a caller would ever pass to uri(). Requiring
+      # it before a wildcard route counts as "satisfied" would exclude that
+      # route from selection unconditionally (issue #190 review follow-up).
+      def required_keys(route)
+        route.keys - ['splat']
+      end
     end
   end
 end

data/lib/otto/env_keys.rb

@@ -153,6 +153,17 @@ class Otto
       # Used by: Session correlation without storing IPs
       HASHED_IP = 'otto.privacy.hashed_ip'
 
+      # Stable IP correlation hash: identifies the same visitor across days/months
+      # Type: String (hexadecimal), or nil when no correlation secret configured
+      # Set by: IPPrivacyMiddleware (computed over the FULL client IP,
+      #   pre-masking, keyed with the caller-configured stable
+      #   correlation_secret — NOT the daily rotation_key behind HASHED_IP)
+      # Used by: Correlating the same visitor across days/months (e.g. audit
+      #   trails) without ever storing or exposing the real IP
+      # Read via: Otto::Request#ip_correlation_hash
+      # Contrast: HASHED_IP rotates daily (session-scoped); this is stable.
+      CORRELATION_HASH = 'otto.privacy.correlation_hash'
+
       # Privacy fingerprint object
       # Type: Otto::Privacy::RedactedFingerprint
       # Set by: IPPrivacyMiddleware

data/lib/otto/errors.rb

@@ -11,6 +11,13 @@
 #   otto.register_error_handler(MyApp::ResourceNotFound, status: 404, log_level: :info)
 #
 class Otto
+  # Raised at route-load time when a route definition is malformed in a way
+  # that must not be silently ignored — e.g. a security-gating option
+  # (auth/role/csrf) without a value. Unlike generic per-line load errors,
+  # this error propagates out of Otto#load so the app fails at boot instead
+  # of serving the route with default (less safe) behavior.
+  class RouteDefinitionError < StandardError; end
+
   # Base class for all Otto HTTP errors
   #
   # Provides default_status and default_log_level class methods that

data/lib/otto/mcp/route_parser.rb

@@ -2,6 +2,8 @@
 #
 # frozen_string_literal: true
 
+require_relative '../route_definition'
+
 class Otto
   module MCP
     # Parser for MCP route definitions and resource URIs
@@ -64,10 +66,19 @@ class Otto
         parts   = handler_definition.split(/\s+/)
         options = {}
 
-        # First part is the handler class.method
-        parts[1..-1]&.each do |part|
-          key, value = part.split('=', 2)
-          options[key.to_sym] = value if key && value
+        # First part is the handler class.method. Delegate token parsing to
+        # Otto::RouteDefinition so a bare/empty auth|role|csrf token here
+        # fails fast exactly like it does for normal routes (issue #191
+        # MCP/TOOL follow-up), instead of silently registering the route
+        # without its intended protection.
+        parts[1..]&.each do |part|
+          pair = Otto::RouteDefinition.parse_option_token(part, "handler #{handler_definition.inspect}")
+          if pair
+            options[pair[0]] = pair[1]
+          else
+            Otto.structured_log(:warn, 'Malformed MCP/tool route option ignored',
+              { option: part, handler: handler_definition })
+          end
         end
 
         options

data/lib/otto/privacy/config.rb

@@ -28,7 +28,7 @@ class Otto
       include Otto::Core::Freezable
 
       attr_accessor :octet_precision, :hash_rotation_period, :geo_enabled, :mask_private_ips
-      attr_reader :disabled
+      attr_reader :disabled, :correlation_secret
 
       # Class-level rotation key storage (mutable, not frozen with instances)
       # This is stored at the class level so it persists across frozen config instances
@@ -51,6 +51,22 @@ class Otto
       # @option options [Boolean] :geo_enabled Enable geo-location resolution (default: true)
       # @option options [Boolean] :disabled Disable privacy entirely (default: false)
       # @option options [Boolean] :mask_private_ips Mask private/localhost IPs (default: false)
+      # @option options [String] :correlation_secret A secret string that turns
+      #   on IP correlation. Default nil, meaning off.
+      #
+      #   It answers one question: "are these two requests, maybe months apart,
+      #   from the same visitor?" — without your app ever seeing the real IP.
+      #
+      #   Otto masks each IP before your app runs (203.0.113.42 becomes
+      #   203.0.113.0), which is too coarse to tell visitors apart. When a secret
+      #   is set, Otto also fingerprints the full IP, before masking, and hands
+      #   your app just the fingerprint as req.ip_correlation_hash. The same IP
+      #   always produces the same fingerprint, and it can't be turned back into
+      #   an IP without the secret.
+      #
+      #   Keep the secret stable — changing it changes every fingerprint. An empty
+      #   string is rejected, because an empty secret would let anyone reverse the
+      #   fingerprint back to an IP.
       # @option options [Redis] :redis Optional Redis connection for multi-server environments
       def initialize(options = {})
         @octet_precision = options.fetch(:octet_precision, 1)
@@ -58,9 +74,29 @@ class Otto
         @geo_enabled = options.fetch(:geo_enabled, true)
         @disabled = options.fetch(:disabled, false) # Enabled by default (privacy-by-default)
         @mask_private_ips = options.fetch(:mask_private_ips, false) # Don't mask private/localhost by default
+        self.correlation_secret = options.fetch(:correlation_secret, nil) # Opt-in stable IP-correlation secret
         @redis = options[:redis] # Optional Redis connection for multi-server environments
       end
 
+      # Set the stable correlation secret, validating its type up front.
+      #
+      # nil or an empty string mean "correlation hash disabled" (see
+      # IPPrivacyMiddleware#correlation_hash — an empty key is never used to
+      # hash). Any other non-String is a configuration error: without this
+      # guard it would surface far from its cause, as a NoMethodError on
+      # `#empty?` deep inside per-request middleware. Fail fast here instead,
+      # at the point of misconfiguration, with a message that names the type.
+      #
+      # @param value [String, nil] stable secret, or nil/"" to disable
+      # @raise [ArgumentError] if value is neither a String nor nil
+      def correlation_secret=(value)
+        unless value.nil? || value.is_a?(String)
+          raise ArgumentError, "correlation_secret must be a String or nil, got: #{value.class}"
+        end
+
+        @correlation_secret = value
+      end
+
       # Check if privacy is enabled
       #
       # @return [Boolean] true if privacy is enabled (default)

data/lib/otto/privacy/core.rb

@@ -52,6 +52,13 @@ class Otto
       # @param hash_rotation [Integer] Seconds between key rotation (default: 86400)
       # @param geo [Boolean] Enable geo-location resolution (default: true)
       # @param redis [Redis] Redis connection for multi-server atomic key generation
+      # @param correlation_secret [String] A secret string that turns on IP
+      #   correlation: it lets you tell whether two requests, even months apart,
+      #   came from the same visitor — without your app ever seeing the real IP.
+      #   (Otto masks the IP before your app runs; with a secret set it also
+      #   fingerprints the full IP into req.ip_correlation_hash, which can't be
+      #   reversed to an IP without the secret.) Omit it to leave any existing
+      #   secret unchanged; pass an empty string to turn the feature back off.
       #
       # @example Mask 2 octets instead of 1
       #   otto.configure_ip_privacy(octet_precision: 2)
@@ -62,16 +69,26 @@ class Otto
       # @example Custom hash rotation
       #   otto.configure_ip_privacy(hash_rotation: 24.hours)
       #
+      # @example Enable stable IP correlation (same visitor across days)
+      #   otto.configure_ip_privacy(correlation_secret: ENV['IP_CORRELATION_SECRET'])
+      #
       # @example Multi-server with Redis
       #   redis = Redis.new(url: ENV['REDIS_URL'])
       #   otto.configure_ip_privacy(redis: redis)
-      def configure_ip_privacy(octet_precision: nil, hash_rotation: nil, geo: nil, redis: nil)
+      def configure_ip_privacy(octet_precision: nil, hash_rotation: nil, geo: nil, redis: nil,
+                               correlation_secret: nil)
         ensure_not_frozen!
         config = @security_config.ip_privacy_config
 
         config.octet_precision = octet_precision if octet_precision
         config.hash_rotation_period = hash_rotation if hash_rotation
         config.geo_enabled = geo unless geo.nil?
+        # Mirror geo's `unless nil?` guard: nil means "leave unchanged", while an
+        # explicit "" is a real value that disables the correlation hash. (A
+        # plain `if correlation_secret` would also assign "" since "" is truthy
+        # in Ruby, but stating the nil intent explicitly keeps this consistent
+        # with the other nilable kwargs.)
+        config.correlation_secret = correlation_secret unless correlation_secret.nil?
         config.instance_variable_set(:@redis, redis) if redis
 
         # Validate configuration

data/lib/otto/privacy/redacted_fingerprint.rb

@@ -92,30 +92,14 @@ class Otto
 
       # Anonymize user agent string by removing version numbers and build identifiers
       #
-      # Removes specific version numbers (*.*.* pattern) and build identifiers
-      # (e.g., Build/MRA58N) to reduce fingerprinting granularity while maintaining
-      # browser/OS info.
+      # Delegates to the public {UserAgentPrivacy.anonymize} so there is a single
+      # source of truth for the reduction (removes version numbers and build
+      # identifiers, preserving browser/OS info) shared with downstream consumers.
       #
       # @param ua [String, nil] User agent string
       # @return [String, nil] Anonymized user agent or nil
       def anonymize_user_agent(ua)
-        return nil if ua.nil? || ua.empty?
-
-        # Remove build identifiers (e.g., Build/MRA58N, Build/MPJ24.139-64)
-        # This must run BEFORE version stripping to avoid partial matches.
-        # If we strip versions first, Build/MPJ24.139-64 becomes Build/MPJ*.*-64,
-        # and the regex won't match properly (asterisks not in [\w.-] class).
-        anonymized = ua.gsub(/Build\/[\w.-]+/, 'Build/*')
-
-        # Remove version patterns (*.*.*.*, *.*.*, *.*)
-        # Support both dot and underscore separators (e.g., 10.15.7 and 10_15_7)
-        anonymized = anonymized
-                     .gsub(/\d+[._]\d+[._]\d+[._]\d+/, '*.*.*.*')
-                     .gsub(/\d+[._]\d+[._]\d+/, '*.*.*')
-                     .gsub(/\d+[._]\d+/, '*.*')
-
-        # Truncate if too long (prevent DoS via huge UA strings)
-        anonymized.length > 500 ? anonymized[0..499] : anonymized
+        UserAgentPrivacy.anonymize(ua)
       end
 
       # Anonymize referer URL

data/lib/otto/privacy/user_agent_privacy.rb

@@ -0,0 +1,64 @@
+# lib/otto/privacy/user_agent_privacy.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Privacy
+    # User-Agent anonymization utilities.
+    #
+    # Reduces a User-Agent string to a lower-entropy form by stripping build
+    # identifiers and version numbers and truncating, so it can be logged or
+    # stored for analytics without a high-entropy fingerprint while preserving
+    # browser/OS family information. This is the User-Agent analogue of
+    # {IPPrivacy} for IP addresses, exposed as a public surface so downstream
+    # consumers can reduce a UA outside of the full RedactedFingerprint /
+    # middleware flow without re-implementing (and drifting from) these regexes.
+    #
+    # @example
+    #   UserAgentPrivacy.anonymize(
+    #     'Mozilla/5.0 (Windows NT 10.0) Chrome/119.0.0.0 Safari/537.36'
+    #   )
+    #   # => 'Mozilla/*.* (Windows NT *.*) Chrome/*.*.*.* Safari/*.*'
+    #
+    # @note Idempotent: re-anonymizing already-anonymized output is a no-op, so
+    #   a UA reduced at the edge and one reduced again downstream agree.
+    class UserAgentPrivacy
+      # Default cap on the returned string, guarding against a DoS via a huge
+      # User-Agent header. Matches the length RedactedFingerprint has always
+      # applied.
+      DEFAULT_MAX_LENGTH = 500
+
+      # Anonymize a User-Agent string.
+      #
+      # Removes build identifiers (e.g. +Build/MRA58N+) and version numbers
+      # (+*.*.*.*+, +*.*.*+, +*.*+; dot- or underscore-separated), then
+      # truncates to +max_length+. Browser/OS family text is preserved -- the
+      # point is a partial, not a full redaction.
+      #
+      # Build identifiers are stripped BEFORE versions: if versions went first,
+      # a token like +Build/MPJ24.139-64+ would become +Build/MPJ*.*-64+ and the
+      # build regex (which matches only +[\w.-]+) would no longer catch it.
+      #
+      # @param ua [String, nil] the raw User-Agent string.
+      # @param max_length [Integer] maximum length of the returned string.
+      # @return [String, nil] the anonymized UA, or nil for nil/empty input.
+      def self.anonymize(ua, max_length: DEFAULT_MAX_LENGTH)
+        return nil if ua.nil? || ua.empty?
+
+        # Remove build identifiers (e.g., Build/MRA58N, Build/MPJ24.139-64).
+        # Must run BEFORE version stripping (see method note).
+        anonymized = ua.gsub(%r{Build/[\w.-]+}, 'Build/*')
+
+        # Remove version patterns (*.*.*.*, *.*.*, *.*), longest first.
+        # Support both dot and underscore separators (e.g. 10.15.7 and 10_15_7).
+        anonymized = anonymized
+                     .gsub(/\d+[._]\d+[._]\d+[._]\d+/, '*.*.*.*')
+                     .gsub(/\d+[._]\d+[._]\d+/, '*.*.*')
+                     .gsub(/\d+[._]\d+/, '*.*')
+
+        # Truncate if too long (prevent DoS via huge UA strings).
+        anonymized.length > max_length ? anonymized[0...max_length] : anonymized
+      end
+    end
+  end
+end

data/lib/otto/privacy.rb

@@ -5,6 +5,7 @@
 require_relative 'privacy/core'
 require_relative 'privacy/config'
 require_relative 'privacy/ip_privacy'
+require_relative 'privacy/user_agent_privacy'
 require_relative 'privacy/geo_resolver'
 require_relative 'privacy/redacted_fingerprint'
 

data/lib/otto/request.rb

@@ -133,6 +133,33 @@ class Otto
       redacted_fingerprint&.hashed_ip || env['otto.privacy.hashed_ip']
     end
 
+    # Get the stable-keyed correlation hash of the client IP.
+    #
+    # Contrast with #hashed_ip: that value is keyed with a daily-rotating
+    # secret (great for correlating requests within a session, useless across
+    # days). This value is HMAC-SHA256 over the SAME full, pre-masking client
+    # IP but keyed with a caller-configured STABLE secret, so the same IP
+    # produces the same hash indefinitely — the granularity long-lived audit
+    # records need without ever handling the raw IP.
+    #
+    # Both are computed before masking, so both reflect the per-host address
+    # (not the /24 the app is otherwise left with); the raw IP itself never
+    # reaches the application — only the hash does.
+    #
+    # Returns nil when IP privacy is disabled, no correlation secret is
+    # configured (see Otto#configure_ip_privacy(correlation_secret:)), or the
+    # client IP is exempt from masking. By default private/localhost IPs are
+    # exempt (mask_private_ips is false), so this is nil for RFC-1918 and
+    # loopback addresses — including the common local dev path — just like
+    # #masked_ip and #hashed_ip. It targets public audit-trail traffic.
+    #
+    # @return [String, nil] Hexadecimal HMAC-SHA256 hash string or nil
+    # @example
+    #   req.ip_correlation_hash  # => 'b7e2...'  (stable across days)
+    def ip_correlation_hash
+      env['otto.privacy.correlation_hash']
+    end
+
     def client_ipaddress
       # Prefer the canonical client IP resolved once by IPPrivacyMiddleware
       # ("resolve once, read everywhere"). Falls back to the shared resolver