otto 2.5.0 → 2.7.0

data/lib/otto/core/middleware_stack.rb

@@ -13,12 +13,24 @@ class Otto
       include Enumerable
       include Otto::Core::Freezable
 
+      # Pin tiers honored by #ordered_stack, outward-ascending. #wrap folds the
+      # stack with reduce, so a LATER array position is a FURTHER OUT wrapper;
+      # sorting by tier therefore sorts by how early the middleware sees the
+      # request. Unpinned entries are tier 0 and keep their insertion order.
+      #
+      # A tier is recorded on the ENTRY (as entry[:pin_tier]), not on the
+      # middleware class. Entries are identified by (class, args, options), so
+      # the same class can legitimately be registered more than once with
+      # different configuration; a class-wide pin would drag those other
+      # registrations into the pinned tier along with it.
+      PIN_TIERS = {
+         outermost: 1,
+        entrypoint: 2,
+      }.freeze
+
       def initialize
         @stack = []
         @middleware_set = Set.new
-        # Classes pinned to run OUTERMOST regardless of insertion order (see
-        # the :outermost position in #add_with_position and #ordered_stack).
-        @outermost = Set.new
         @on_change_callback = nil
       end
 
@@ -52,8 +64,15 @@ class Otto
 
       # Add middleware with position hint for optimal ordering
       #
-      # Positions:
-      # - :first     — innermost (runs last, closest to the app)
+      # Positions name a place in the ARRAY; #wrap folds the array with reduce,
+      # so array order is the REVERSE of execution order — the last entry is the
+      # outermost wrapper and therefore the first to see a request.
+      #
+      # - :first/:innermost — innermost: the LAST middleware to see the request,
+      #                closest to the app. Note the trap in the older `:first`
+      #                spelling: it is first-in-array, hence last-to-execute.
+      #                `:innermost` says the same thing in execution terms and is
+      #                the preferred spelling.
       # - :last/nil  — append (outermost among currently-registered middleware,
       #                but a later append displaces it)
       # - :outermost — pin to run OUTERMOST (first to see the request) and STAY
@@ -62,10 +81,18 @@ class Otto
       #                at build time. Use for middleware that must short-circuit
       #                ahead of everything else (e.g. the CSP report receiver,
       #                which must intercept before CSRF).
+      # - :entrypoint — pin OUTSIDE even the :outermost tier: the very first
+      #                middleware to touch a request. Reserved for middleware
+      #                that must normalize the request before anything else can
+      #                observe it. Otto pins IPPrivacyMiddleware here so every
+      #                other middleware — its own, an :outermost pin, and
+      #                anything the app adds via Otto#use — reads a masked
+      #                REMOTE_ADDR and the canonical env['otto.client_ip'].
       #
       # @param middleware_class [Class] Middleware class
       # @param args [Array] Middleware arguments
-      # @param position [Symbol, nil] Position hint (:first, :last, :outermost, or nil)
+      # @param position [Symbol, nil] Position hint (:first, :innermost, :last,
+      #   :outermost, :entrypoint, or nil)
       def add_with_position(middleware_class, *args, position: nil, **options)
         raise FrozenError, 'Cannot modify frozen middleware stack' if frozen?
 
@@ -81,11 +108,10 @@ class Otto
         entry = { middleware: middleware_class, args: args, options: options }
 
         case position
-        when :first
+        when :first, :innermost
           @stack.unshift(entry)
-        when :outermost
-          @stack << entry
-          @outermost.add(middleware_class)
+        when *PIN_TIERS.keys
+          @stack << entry.merge(pin_tier: PIN_TIERS.fetch(position))
         else
           @stack << entry # :last / nil — default append
         end
@@ -160,9 +186,9 @@ class Otto
         # Update middleware set if any matching entries were found
         return unless matches
 
-        # Rebuild the set of unique middleware classes
+        # Rebuild the set of unique middleware classes. Pins need no cleanup:
+        # each removed entry took its own tier with it.
         @middleware_set = Set.new(@stack.map { |entry| entry[:middleware] })
-        @outermost.delete(middleware_class)
         # Notify of change
         @on_change_callback&.call
       end
@@ -179,7 +205,6 @@ class Otto
 
         @stack.clear
         @middleware_set.clear
-        @outermost.clear
         # Notify of change
         @on_change_callback&.call
       end
@@ -192,9 +217,15 @@ class Otto
       # Build Rack application with middleware chain
       #
       # The stack folds via reduce, so the LAST entry becomes the OUTERMOST
-      # wrapper (first to see the request). #ordered_stack moves any :outermost-
-      # pinned middleware to the end so it stays outermost regardless of the
-      # order middleware was registered in.
+      # wrapper (first to see the request). #ordered_stack moves any pinned
+      # middleware (:outermost, :entrypoint) to the end so it stays outermost
+      # regardless of the order middleware was registered in.
+      #
+      # NOT a request-path method. Its only caller is Otto's build_app!, which
+      # runs at construction and again whenever the stack changes; requests are
+      # served by the chain it returns. So the ordering work here (and in
+      # #ordered_stack) is per-BUILD, not per-request — don't add caching
+      # machinery on the assumption that it is hot.
       def wrap(base_app, security_config = nil)
         ordered_stack.reduce(base_app) do |app, entry|
           middleware = entry[:middleware]
@@ -215,11 +246,23 @@ class Otto
         end
       end
 
-      # Returns list of middleware classes in order
+      # Returns list of middleware classes in REGISTRATION order — the order
+      # they were added, which is the reverse of execution order and ignores pin
+      # tiers. Use #execution_order to see what actually runs first.
       def middleware_list
         @stack.map { |entry| entry[:middleware] }
       end
 
+      # Returns middleware classes in EXECUTION order: the first entry is the
+      # outermost wrapper #wrap builds, i.e. the first to see a request. This is
+      # #middleware_list resolved through the pin tiers and reversed, so it
+      # answers "what does this stack actually do?" without building the app.
+      #
+      # @return [Array<Class>] outermost (first to execute) first
+      def execution_order
+        ordered_stack.reverse.map { |entry| entry[:middleware] }
+      end
+
       # Detailed introspection
       def middleware_details
         @stack.map do |entry|
@@ -254,16 +297,20 @@ class Otto
 
       private
 
-      # The stack ordered for #wrap: identical to @stack unless some middleware
-      # is pinned :outermost, in which case pinned entries are moved to the end
-      # (outermost) while preserving the relative order of both groups. Returns
-      # @stack itself (no copy) in the common no-pin case, so ordinary apps are
-      # completely unaffected.
+      # The stack ordered for #wrap: identical to @stack unless some entry is
+      # pinned, in which case entries are sorted by pin tier (PIN_TIERS,
+      # outward-ascending) so pinned entries move to the end (outermost) while
+      # the relative order within every tier is preserved. Ruby's sort_by is not
+      # stable, hence the explicit index tiebreak. Returns @stack itself (no
+      # copy) in the common no-pin case, so ordinary apps are unaffected.
+      #
+      # Runs per build, not per request — see #wrap.
       def ordered_stack
-        return @stack if @outermost.empty?
+        return @stack if @stack.none? { |entry| entry[:pin_tier] }
 
-        pinned, rest = @stack.partition { |entry| @outermost.include?(entry[:middleware]) }
-        rest + pinned
+        @stack.each_with_index
+              .sort_by { |entry, index| [entry[:pin_tier] || 0, index] }
+              .map(&:first)
       end
 
       def middleware_needs_config?(middleware_class)

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

@@ -82,6 +82,17 @@ class Otto
     #   without depending on the (masked) REMOTE_ADDR
     VIA_TRUSTED_PROXY = 'otto.via_trusted_proxy'
 
+    # Whether the connecting peer was the loopback interface.
+    # Type: Boolean
+    # Set by: IPPrivacyMiddleware (every request, evaluated on the ORIGINAL
+    #   socket peer BEFORE REMOTE_ADDR is masked/rewritten). A boolean, never
+    #   an address, so it carries no identifying data.
+    # Used by: Otto::CaddyTLS::LocalhostGuard to authenticate a direct local
+    #   call now that IPPrivacyMiddleware runs outermost. Deliberately the raw
+    #   peer, not the resolved client IP: forwarded headers must play no part
+    #   in a localhost trust decision.
+    PEER_LOOPBACK = 'otto.peer_loopback'
+
     # =========================================================================
     # LOCALIZATION (I18N)
     # =========================================================================
@@ -134,6 +145,27 @@ class Otto
     # Note: presence also acts as the idempotency guard for the middleware
     CLIENT_IP = 'otto.client_ip'
 
+    # Verdict-only CIDR membership check over the resolved, UNMASKED client IP
+    # Type: Proc — call with an Enumerable of CIDR strings or IPAddr objects,
+    #       returns true/false
+    # Set by: IPPrivacyMiddleware (every path that resolves an IP, all
+    #         privacy profiles)
+    # Used by: Downstream IP policy code (allowlists, denylists, network
+    #          zones) that needs full /32-/128 precision without changing the
+    #          observability posture — CLIENT_IP is masked under the default
+    #          profile, so it cannot express a single host
+    # Note: the unmasked IP never lands in env; only this closure does, and a
+    #       Proc serializes to nothing useful, so env dumps and loggers cannot
+    #       leak the address accidentally. Returns false when the request had
+    #       no resolvable client IP (fail-closed for allowlist callers);
+    #       raises IPAddr::InvalidAddressError for invalid CIDR entries
+    #       (configuration error). See Otto::Utils.ip_in_cidrs?.
+    # Note: setting CLIENT_IP yourself is out of contract — it trips the
+    #       middleware's idempotency guard, so the unmasked address is never
+    #       captured and this capability degrades to a logged fail-closed
+    #       check that denies every range.
+    IP_MATCH = 'otto.ip_match'
+
     # Privacy-safe masked IP address
     # Type: String (e.g., '192.168.1.0')
     # Set by: IPPrivacyMiddleware
@@ -153,6 +185,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/logging_helpers.rb

@@ -76,12 +76,61 @@ class Otto
       {
             method: env['REQUEST_METHOD'],
               path: env['PATH_INFO'],
-                ip: env['otto.client_ip'] || env['REMOTE_ADDR'], # Canonical client IP (masked when privacy on)
+                ip: privacy_safe_ip(env), # Canonical client IP (masked when privacy on)
            country: env['otto.privacy.geo_country'],
         user_agent: env['HTTP_USER_AGENT']&.slice(0, 100), # Already anonymized by IPPrivacyMiddleware
       }.compact
     end
 
+    # A client IP that is safe to write to a log.
+    #
+    # Prefers the canonical env['otto.client_ip'] that IPPrivacyMiddleware
+    # resolves once per request: masked when privacy is on, and deliberately
+    # the real address when the app has disabled privacy. That key is present
+    # for anything running inside Otto, since the middleware is pinned
+    # outermost.
+    #
+    # It is ABSENT for code that runs outside Otto's stack — notably
+    # Rack::Attack, which the hosting app mounts ahead of Otto (see
+    # Otto::Security::Middleware::RateLimitMiddleware), so its 'rack.attack'
+    # subscriber observes the raw peer no matter how Otto orders its own
+    # middleware. There we mask the address ourselves rather than log it whole:
+    # a public IP is reduced with the default precision (privacy config is not
+    # reachable from a global subscriber), and private/localhost addresses pass
+    # through unmasked, matching the middleware's own exemption so development
+    # logs stay readable.
+    #
+    # Never raises and never returns a raw public address: an unparseable value
+    # (a ported REMOTE_ADDR, a malformed forwarded entry) becomes '[redacted]'.
+    #
+    # @param env [Hash] Rack environment hash
+    # @param fallback_ip [String, nil] address to fall back to when the env
+    #   carries no canonical client IP — e.g. Rack::Request#ip, which factors in
+    #   forwarded headers. Defaults to REMOTE_ADDR.
+    # @return [String, nil] log-safe address, or nil when there is none
+    def self.privacy_safe_ip(env, fallback_ip = nil)
+      canonical = env['otto.client_ip']
+      return canonical unless canonical.to_s.empty?
+
+      candidate = fallback_ip.to_s.empty? ? env['REMOTE_ADDR'] : fallback_ip
+      redact_ip(candidate)
+    end
+
+    # Reduce a raw address to a log-safe form. See .privacy_safe_ip.
+    #
+    # @param ip [String, nil] raw address
+    # @return [String, nil] masked address, the address itself when
+    #   private/localhost, '[redacted]' when unparseable, nil when blank
+    def self.redact_ip(ip)
+      address = ip.to_s.strip
+      return nil if address.empty?
+      return address if Otto::Privacy::IPPrivacy.private_or_localhost?(address)
+
+      Otto::Privacy::IPPrivacy.mask_ip(address) || '[redacted]'
+    rescue ArgumentError
+      '[redacted]'
+    end
+
     # Log a timed operation with consistent timing and error handling
     #
     # @param level [Symbol] The log level (:debug, :info, :warn, :error)

data/lib/otto/mcp/rate_limiting.rb

@@ -113,14 +113,17 @@ class Otto
       def self.configure_mcp_logging
         return unless defined?(ActiveSupport::Notifications)
 
+        # Masked address only — see the note on the sibling subscriber in
+        # Otto::Security::RateLimiting.configure_rack_attack! (issue #219).
         ActiveSupport::Notifications.subscribe('rack.attack') do |_name, _start, _finish, _request_id, payload|
           req      = payload[:request]
           endpoint = req.env['otto.mcp_http_endpoint'] || '/_mcp'
+          ip       = Otto::LoggingHelpers.privacy_safe_ip(req.env, req.ip)
 
           if req.path.start_with?(endpoint)
-            Otto.logger.warn "[MCP] Rate limit #{payload[:match_type]} for #{req.ip}: #{payload[:matched]}"
+            Otto.logger.warn "[MCP] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
           else
-            Otto.logger.warn "[Otto] Rate limit #{payload[:match_type]} for #{req.ip}: #{payload[:matched]}"
+            Otto.logger.warn "[Otto] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
           end
         end
       end

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