otto 2.9.0 → 2.11.0

data/lib/otto/core/static_mounts.rb

@@ -0,0 +1,172 @@
+# lib/otto/core/static_mounts.rb
+#
+# frozen_string_literal: true
+
+require 'rack/files'
+
+class Otto
+  module Core
+    # Explicit static-file registration (issue #267).
+    #
+    # A static mount binds a URL prefix to one directory on disk:
+    #
+    #   otto.mount_static('/assets', root: 'public/assets')
+    #
+    # Requests for GET /assets/<rest> are then resolved against
+    # public/assets/<rest> using the same containment policy as the implicit
+    # +public:+ directory (Otto::Core::FileSafety): the candidate is
+    # canonicalized with File.realpath and must land inside the mount's
+    # canonical root, be a regular readable file, and be owned by the process
+    # user or group. A mount never authorizes anything outside its own root,
+    # so several mounts can point into unrelated directories without exposing
+    # their parents or siblings.
+    #
+    # Registration is a boot-time operation. The root is canonicalized once,
+    # when the mount is registered, and every failure mode (missing,
+    # unreadable, not a directory, escaping symlink, malformed prefix,
+    # duplicate prefix) raises ArgumentError immediately so a misconfigured
+    # application does not start. Mounts participate in configuration
+    # freezing: mount_static raises FrozenError after freeze_configuration!,
+    # and the mount table is an immutable, sorted snapshot that dispatch reads
+    # without any per-request mutation.
+    #
+    # Dispatch precedence is fixed: literal routes, then static mounts (longest
+    # prefix first), then the implicit +public:+ directory, then dynamic
+    # routes. A mount claims files, not the prefix: when no mount root
+    # contains the requested file the request falls through to the next
+    # stage exactly as an unregistered path would. See Otto::Core::Router.
+    module StaticMounts
+      # One registered mount. +prefix+ is the normalized URL prefix ('' for a
+      # root mount), +root+ the canonical directory, +files+ the Rack::Files
+      # instance rooted there. Instances are frozen at construction.
+      StaticMount = Struct.new(:prefix, :root, :files) do
+        # Request-relative path under this mount, or nil when +path+ is not
+        # beneath the prefix. The prefix itself (the directory) never matches:
+        # a mount serves files, not directory listings.
+        #
+        # @param path [String] normalized dispatch path (leading '/')
+        # @return [String, nil]
+        def relative_path_for(path)
+          if prefix.empty?
+            path
+          elsif path.start_with?("#{prefix}/")
+            path[(prefix.length + 1)..]
+          end
+        end
+
+        # Prefix as an operator would write it ('/' for a root mount).
+        def display_prefix
+          prefix.empty? ? '/' : prefix
+        end
+      end
+
+      # Registered mounts, longest prefix first. Frozen snapshot; a new array
+      # replaces it on every registration so readers never observe a partial
+      # update.
+      #
+      # @return [Array<StaticMount>]
+      def static_mounts
+        @static_mounts
+      end
+
+      # Serve the files under +root+ at URLs beneath +prefix+.
+      #
+      # @param prefix [String] URL prefix starting with '/'. A trailing slash
+      #   is ignored; '/' mounts the root at the top level.
+      # @param root [String] directory path; relative paths resolve against
+      #   the process working directory and are canonicalized immediately.
+      # @return [StaticMount] the registered mount
+      # @raise [ArgumentError] on a malformed prefix, a duplicate prefix, or a
+      #   root that is missing, unreadable, not a directory, not owned by the
+      #   process user or group, or that cannot be canonicalized.
+      # @raise [FrozenError] after configuration freezing
+      def mount_static(prefix, root:)
+        ensure_not_frozen!
+
+        clean_prefix = normalize_mount_prefix(prefix)
+        if @static_mounts.any? { |mount| mount.prefix == clean_prefix }
+          raise ArgumentError,
+                "Static mount prefix #{display_mount_prefix(clean_prefix).inspect} is already registered"
+        end
+
+        canonical_root = canonicalize_mount_root(clean_prefix, root)
+        mount = StaticMount.new(clean_prefix, canonical_root, Rack::Files.new(canonical_root).freeze).freeze
+
+        # Longest prefix first so an overlay ('/assets/vendor') is consulted
+        # before the mount that contains it ('/assets'). Ties cannot happen:
+        # prefixes are unique. Rebuild rather than mutate so in-flight readers
+        # keep their snapshot.
+        @static_mounts = (@static_mounts + [mount]).sort_by { |m| -m.prefix.length }.freeze
+
+        Otto.structured_log(:debug, 'Static mount registered',
+          { prefix: mount.display_prefix, root: mount.root })
+        mount
+      end
+
+      private
+
+      # Resolve +path+ through the registered mounts, longest prefix first.
+      # Read-only: safe to call from concurrent request threads.
+      #
+      # @param path [String] normalized dispatch path (leading '/')
+      # @return [Array(StaticMount, Otto::Core::FileSafety::StaticFile), nil]
+      def resolve_mounted_file(path)
+        @static_mounts.each do |mount|
+          relative = mount.relative_path_for(path)
+          next if relative.nil?
+
+          static_file = resolve_file_under(mount.root, relative)
+          return [mount, static_file] if static_file
+        end
+        nil
+      end
+
+      # Validate and normalize a mount prefix. Returns '' for the root mount
+      # and a leading-slash, no-trailing-slash prefix otherwise, matching the
+      # normalized request path the router compares against.
+      def normalize_mount_prefix(prefix)
+        raise ArgumentError, "Static mount prefix must be a String, got #{prefix.class}" unless prefix.is_a?(String)
+        raise ArgumentError, "Static mount prefix #{prefix.inspect} contains a NUL byte" if prefix.include?("\0")
+        raise ArgumentError, "Static mount prefix #{prefix.inspect} must start with '/'" unless prefix.start_with?('/')
+
+        clean = prefix.sub(%r{/+\z}, '')
+        return '' if clean.empty?
+
+        segments = clean.split('/', -1).drop(1)
+        if segments.any? { |segment| segment.empty? || segment == '.' || segment == '..' }
+          raise ArgumentError,
+                "Static mount prefix #{prefix.inspect} must not contain empty, '.', or '..' segments"
+        end
+
+        clean.freeze
+      end
+
+      # Canonicalize a mount root under Otto's static-file safety policy and
+      # fail loudly on anything that could not be served safely.
+      def canonicalize_mount_root(prefix, root)
+        label = "Static mount #{display_mount_prefix(prefix).inspect}"
+        raise ArgumentError, "#{label} root must be a String, got #{root.class}" unless root.is_a?(String)
+        raise ArgumentError, "#{label} root must not be empty" if root.strip.empty?
+        raise ArgumentError, "#{label} root #{root.inspect} contains a NUL byte" if root.include?("\0")
+
+        real = safe_realpath(File.expand_path(root))
+        if real.nil?
+          raise ArgumentError,
+                "#{label} root #{root.inspect} cannot be resolved " \
+                '(missing, unreadable component, or symlink loop)'
+        end
+        raise ArgumentError, "#{label} root #{root.inspect} is not a directory" unless File.directory?(real)
+        raise ArgumentError, "#{label} root #{root.inspect} is not readable" unless File.readable?(real)
+
+        owned = File.owned?(real) || File.grpowned?(real)
+        raise ArgumentError, "#{label} root #{root.inspect} is not owned by the process user or group" unless owned
+
+        real.freeze
+      end
+
+      def display_mount_prefix(prefix)
+        prefix.empty? ? '/' : prefix
+      end
+    end
+  end
+end

data/lib/otto/core.rb

@@ -4,6 +4,7 @@
 
 require_relative 'core/router'
 require_relative 'core/file_safety'
+require_relative 'core/static_mounts'
 require_relative 'core/configuration'
 require_relative 'core/error_handler'
 require_relative 'core/uri_generator'

data/lib/otto/env_keys.rb

@@ -100,13 +100,16 @@ class Otto
     # Type: Boolean when present; the key may be ABSENT.
     # Set by: IPPrivacyMiddleware, evaluated on the original peer BEFORE
     #   REMOTE_ADDR is masked — but ONLY when proxy trust is configured
-    #   (Security::Config#proxy_trust_configured?: CIDR matchers or a depth).
+    #   (Security::Config#proxy_trust_configured?: CIDR matchers, a depth, or
+    #   the explicit trust-nobody assertion `trusted_proxies: :none`).
     #   True when the peer matches a configured trusted_proxies CIDR (filter
     #   mode), or unconditionally when count-based depth mode is active
     #   (trusted_proxy_depth >= 1) — the modes are mutually exclusive, and
     #   configuring a depth is the operator's assertion that the connecting
     #   peer is their proxy tier (#226). False means trust IS configured and
-    #   this peer failed it — an authoritative deny. When no proxy trust is
+    #   this peer failed it — an authoritative deny; it is also false for
+    #   EVERY peer (loopback included) when the operator asserted
+    #   `trusted_proxies: :none` (#259). When no proxy trust is
     #   configured the key is NOT written, so consumers can distinguish
     #   "denied" from "unconfigured" and apply legacy heuristics only in the
     #   latter case.
@@ -129,6 +132,21 @@ class Otto
     #   in a localhost trust decision.
     PEER_LOOPBACK = 'otto.peer_loopback'
 
+    # Whether the request arrived relayed by a proxy (any relay marker header
+    # present).
+    # Type: Boolean
+    # Set by: IPPrivacyMiddleware (every request), evaluated on the ORIGINAL
+    #   headers BEFORE the untrusted-peer scrub may DELETE those carriers
+    #   (Otto::Utils::RELAY_MARKER_HEADERS cover the forwarded-for family, RFC
+    #   7239 Forwarded, and the X-Forwarded-Host/Proto/Scheme/SSL/Port
+    #   authority carriers — everything the scrub removes). A boolean, so it
+    #   carries no identifying data.
+    # Used by: Otto::CaddyTLS::LocalhostGuard#relayed? — without this record a
+    #   request relayed over loopback by a proxy emitting only RFC 7239
+    #   `Forwarded` or only `X-Forwarded-Host` would look like a direct local
+    #   call after the scrub, and a deny would become an allow.
+    PEER_RELAYED = 'otto.peer_relayed'
+
     # =========================================================================
     # LOCALIZATION (I18N)
     # =========================================================================

data/lib/otto/mcp/auth/token.rb

@@ -5,6 +5,8 @@
 require 'json'
 require 'rack/utils'
 
+require_relative '../endpoint'
+
 class Otto
   module MCP
     module Auth
@@ -54,19 +56,23 @@ class Otto
           # Only apply to MCP endpoints
           return @app.call(env) unless mcp_endpoint?(env)
 
-          # Get auth instance from security config
+          # Fail closed: this middleware is only mounted when MCP auth was
+          # requested, so a missing authenticator is a misconfiguration, not a
+          # licence to serve the endpoint unauthenticated (issue #258).
           auth = @security_config&.mcp_auth
-          return unauthorized_response if auth && !auth.authenticate(env)
+          return unauthorized_response if auth.nil? || !auth.authenticate(env)
 
           @app.call(env)
         end
 
         private
 
+        # Exact endpoint only, normalized as the router normalizes it. A prefix
+        # match would answer 401 for sibling paths (/admin beside /a) that the
+        # MCP handler never receives.
         def mcp_endpoint?(env)
           endpoint = env['otto.mcp_http_endpoint'] || '/_mcp'
-          path     = env['PATH_INFO'].to_s
-          path.start_with?(endpoint)
+          Otto::MCP.endpoint_path?(env['PATH_INFO'], endpoint)
         end
 
         def unauthorized_response

data/lib/otto/mcp/core.rb

@@ -9,17 +9,35 @@ class Otto
     module Core
       # Enable MCP (Model Context Protocol) server support
       #
+      # Options are normalized by Otto::MCP::Server.normalize_options under the
+      # :explicit scope. That scope accepts the canonical keys below and their
+      # mcp_-prefixed spellings (:mcp_endpoint, :mcp_auth_tokens, ...), as
+      # String or Symbol keys, so one hash can feed both Otto.new and this
+      # method.
+      #
+      # It is STRICT: any other key raises ArgumentError rather than being
+      # ignored, so a typo such as `enable_mcp!(auth_token: 'x')` fails at boot
+      # instead of quietly leaving the endpoint unauthenticated. That includes
+      # the constructor-only gating keys (:mcp_enabled, :mcp_http, :mcp_stdio):
+      # this method always enables the HTTP endpoint, so it cannot honour them.
+      #
       # @param options [Hash] MCP configuration options
-      # @option options [Boolean] :http Enable HTTP endpoint (default: true)
-      # @option options [Boolean] :stdio Enable STDIO communication (default: false)
-      # @option options [String] :endpoint HTTP endpoint path (default: '/_mcp')
+      # @option options [String] :http_endpoint HTTP endpoint path (default: '/_mcp')
+      # @option options [Array<String>, String] :auth_tokens Bearer tokens required
+      #   on the MCP endpoint (default: none, which logs a warning)
+      # @option options [Boolean] :allow_unauthenticated Acknowledge an
+      #   intentionally unauthenticated endpoint, silencing that warning (default: false)
+      # @option options [Boolean] :enable_validation Enable JSON schema validation (default: true)
+      # @option options [Boolean] :enable_rate_limiting Enable rate limiting (default: true)
+      # @option options [Integer] :requests_per_minute MCP endpoint limit (default: 60)
+      # @option options [Integer] :tools_per_minute tools/call limit (default: 20)
       # @example
-      #   otto.enable_mcp!(http: true, endpoint: '/api/mcp')
+      #   otto.enable_mcp!(http_endpoint: '/api/mcp', auth_tokens: ['secret'])
       def enable_mcp!(options = {})
         ensure_not_frozen!
         @mcp_server ||= Otto::MCP::Server.new(self)
 
-        @mcp_server.enable!(options)
+        @mcp_server.enable!(Otto::MCP::Server.normalize_options(options))
         Otto.logger.info '[MCP] Enabled MCP server' if Otto.debug
       end
 

data/lib/otto/mcp/endpoint.rb

@@ -0,0 +1,41 @@
+# lib/otto/mcp/endpoint.rb
+#
+# frozen_string_literal: true
+
+require_relative '../utils'
+
+class Otto
+  # Model Context Protocol support.
+  module MCP
+    # Whether +path+ is the MCP endpoint +endpoint+: the one request the router
+    # dispatches to the MCP handler, and nothing else.
+    #
+    # The MCP route is a literal route. The router normalizes PATH_INFO with
+    # Otto::Utils.normalize_path and looks it up by exact equality, so it never
+    # dispatches a sibling path to the MCP handler. The throttles, the throttled
+    # responder, the log subscriber, the token middleware and the schema
+    # validator all used to classify by prefix (start_with?) instead: with MCP
+    # mounted at /a, every /admin request was counted by 'mcp_requests:/a' and
+    # could be answered with an MCP JSON-RPC 429, or a 401, for a path the MCP
+    # handler can never receive; with MCP at / that was every route in the app.
+    #
+    # Both sides go through the router's normalize_path, as LocalhostGuard does
+    # for the Caddy endpoint, so a trailing slash or percent-encoding on either
+    # side cannot make these guards and the router disagree about a request.
+    #
+    # Callers must pass PATH_INFO (Rack::Request#path_info), never
+    # Rack::Request#path, which prepends SCRIPT_NAME. The router matches on
+    # PATH_INFO alone, so when the host app mounts Otto under a prefix
+    # (`map '/api' { run otto }`) the endpoint /_mcp is dispatched for
+    # PATH_INFO=/_mcp while #path reads /api/_mcp and never matches.
+    #
+    # @param path [String, nil] raw PATH_INFO of the request
+    # @param endpoint [String, nil] configured MCP endpoint
+    # @return [Boolean]
+    def self.endpoint_path?(path, endpoint)
+      return false if endpoint.nil?
+
+      Otto::Utils.normalize_path(path) == Otto::Utils.normalize_path(endpoint)
+    end
+  end
+end

data/lib/otto/mcp/errors.rb

@@ -0,0 +1,15 @@
+# lib/otto/mcp/errors.rb
+#
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+class Otto
+  module MCP
+    # Raised by {Otto::MCP::Registry#call_tool} when the requested tool name is
+    # not registered. Distinct from a tool that exists but fails during
+    # execution: the former is a named-entity lookup failure (JSON-RPC -32002,
+    # HTTP 404), the latter an execution fault (-32603, HTTP 500).
+    class ToolNotFoundError < Otto::NotFoundError; end
+  end
+end

data/lib/otto/mcp/options.rb

@@ -0,0 +1,292 @@
+# lib/otto/mcp/options.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module MCP
+    # Normalization of MCP configuration options.
+    #
+    # Otto.new and Otto#enable_mcp! historically accepted different spellings
+    # of the same settings and the constructor dropped all but the endpoint
+    # (issue #258). Every path now funnels through {.normalize}.
+    #
+    # One vocabulary: the canonical keys, their +mcp_+-prefixed variants (the
+    # constructor needs a namespace inside an options hash that also
+    # configures the rest of Otto), and +tool_calls_per_minute+, which is the
+    # name the rate-limiting middleware itself uses. Bare generic names such
+    # as +endpoint+, +validation+ and +rate_limiting+ are NOT accepted:
+    # +rate_limiting:+ is Otto's own general rate-limiting option (a Hash),
+    # and the others were documented before #258 but never read.
+    #
+    # Two strictness rules, selected with the +scope+ argument:
+    #
+    # +:constructor+ (used by Otto.new / #configure_mcp)
+    #   The constructor forwards its ENTIRE options hash here, most of which
+    #   configures things other than MCP, so unrecognized keys are ignored.
+    #   Unknown +mcp_+-prefixed keys still fail loud, since such a key can
+    #   only have been meant for MCP.
+    #
+    # +:explicit+ (used by Otto#enable_mcp!)
+    #   The caller is configuring MCP and nothing else, so any unrecognized
+    #   key raises. That turns +enable_mcp!(auth_token: 'x')+ — a
+    #   singular-vs-plural typo that silently left the endpoint open — into a
+    #   boot failure.
+    #
+    # The +mcp_+-prefixed gating keys (+mcp_enabled+, +mcp_http+, +mcp_stdio+)
+    # decide *whether* MCP is enabled and are read by the constructor itself
+    # (Otto::Core::Configuration#configure_mcp) through {.gating_options}. The
+    # +:constructor+ scope tolerates them; the +:explicit+ scope rejects them,
+    # because +enable_mcp!(mcp_http: false)+ would otherwise be accepted and
+    # still mount the endpoint. Their values must be exactly +true+ or
+    # +false+: the constructor disables the endpoint on +mcp_http == false+,
+    # so a String +"false"+ (from +ENV.fetch+ or YAML) or +nil+ (from an
+    # unset +ENV[...]+) would otherwise mount it.
+    #
+    # Keys may be Strings or Symbols; they are symbolized before anything is
+    # read, so +"auth_tokens" => [...]+ configures authentication exactly like
+    # +auth_tokens:+. A String key and its Symbol twin are two spellings of one
+    # option and conflict when their values differ.
+    #
+    # Both scopes accept the canonical output of {.normalize}, so normalization
+    # is idempotent under either.
+    module Options
+      # Canonical MCP option keys and every accepted alias.
+      # @api private
+      OPTION_ALIASES = {
+                http_endpoint: %i[http_endpoint mcp_endpoint],
+                  auth_tokens: %i[auth_tokens mcp_auth_tokens],
+            enable_validation: %i[enable_validation mcp_validation],
+         enable_rate_limiting: %i[enable_rate_limiting mcp_rate_limiting],
+          requests_per_minute: %i[requests_per_minute mcp_requests_per_minute],
+             tools_per_minute: %i[tools_per_minute tool_calls_per_minute mcp_tool_calls_per_minute],
+        allow_unauthenticated: %i[allow_unauthenticated mcp_allow_unauthenticated],
+      }.freeze
+
+      # @api private
+      SCOPES = %i[constructor explicit].freeze
+
+      # Canonical defaults applied when no alias supplies a value.
+      # @api private
+      OPTION_DEFAULTS = {
+                http_endpoint: '/_mcp',
+                  auth_tokens: [].freeze,
+            enable_validation: true,
+         enable_rate_limiting: true,
+          requests_per_minute: 60,
+             tools_per_minute: 20,
+        allow_unauthenticated: false,
+      }.freeze
+
+      # +mcp_+-prefixed constructor keys that gate *whether* MCP is enabled
+      # rather than configure the server. Otto.new reads them itself, so the
+      # :constructor scope tolerates them (and never emits them). #enable_mcp!
+      # cannot honour them, so the :explicit scope rejects them.
+      # @api private
+      GATING_KEYS = %i[mcp_enabled mcp_http mcp_stdio].freeze
+
+      # Every key {.normalize} recognizes, per scope.
+      # @api private
+      RECOGNIZED_KEYS = {
+        constructor: (OPTION_ALIASES.values.flatten + GATING_KEYS).freeze,
+           explicit: OPTION_ALIASES.values.flatten.freeze,
+      }.freeze
+
+      # Normalize a constructor- or #enable_mcp!-style option hash into the
+      # single canonical shape consumed by {Otto::MCP::Server#enable!}.
+      #
+      # +scope+ is positional, not a keyword, so a brace-less hash at the call
+      # site (+normalize(auth_tokens: ['t'])+) binds to +opts+ as intended.
+      #
+      # @param opts [Hash] raw options; String and Symbol keys are equivalent
+      # @param scope [Symbol] :explicit (strict; the default) or :constructor
+      #   (permissive about non-MCP keys)
+      # @return [Hash] canonical hash with keys :http_endpoint, :auth_tokens,
+      #   :enable_validation, :enable_rate_limiting, :requests_per_minute,
+      #   :tools_per_minute, :allow_unauthenticated
+      # @raise [ArgumentError] on an unrecognized key, conflicting aliases or
+      #   String/Symbol spellings, values of the wrong type, or auth tokens
+      #   supplied but empty/blank
+      def self.normalize(opts = {}, scope = :explicit)
+        raise ArgumentError, "Unknown MCP option scope #{scope.inspect}; expected one of #{SCOPES.inspect}" unless SCOPES.include?(scope)
+
+        opts = symbolize_keys(opts.to_h)
+        reject_unrecognized_keys!(opts, scope)
+
+        canonical = OPTION_DEFAULTS.dup
+        OPTION_ALIASES.each do |key, key_aliases|
+          supplied = key_aliases.select { |a| opts.key?(a) }
+          next if supplied.empty?
+
+          values = supplied.map { |a| opts[a] }
+          raise_conflict!(key, supplied.map { |a| [a, opts[a]] }) if values.uniq.size > 1
+
+          canonical[key] = coerce_option(key, values.first)
+        end
+
+        canonical
+      end
+
+      # Read the constructor-only gating keys (+mcp_enabled+, +mcp_http+,
+      # +mcp_stdio+) with the same String/Symbol tolerance as {.normalize}.
+      #
+      # Otto.new decides *whether* to enable MCP from these before it
+      # normalizes the rest, and it used to read them as raw Symbol keys, so
+      # +Otto.new(nil, "mcp_enabled" => true)+ silently did nothing while the
+      # String-keyed +"auth_tokens"+ beside it was documented as accepted.
+      #
+      # Every gating value present must be exactly +true+ or +false+.
+      # #configure_mcp disables the HTTP endpoint only on +mcp_http == false+,
+      # so +mcp_http: ENV.fetch('MCP_HTTP', 'false')+ (a String, truthy) or
+      # +mcp_http: ENV['MCP_HTTP']+ with the variable unset (+nil+, not
+      # +false+) would each mount the endpoint the caller meant to disable.
+      # An explicit +nil+ is rejected rather than treated as absent for that
+      # reason, matching the other boolean options and +auth_tokens: nil+.
+      #
+      # @param opts [Hash, nil] raw constructor options
+      # @return [Hash{Symbol=>Boolean}] the gating keys present in +opts+
+      # @raise [ArgumentError] when a String key and its Symbol twin disagree,
+      #   or when a gating value is anything but +true+ or +false+ (including
+      #   the Strings +"true"+ / +"false"+, Integers and +nil+)
+      def self.gating_options(opts)
+        gating = symbolize_keys(opts.to_h).slice(*GATING_KEYS)
+        gating.each { |key, value| coerce_boolean!(key, value) }
+        gating
+      end
+
+      # Symbolize option keys once, so String-keyed options configure the
+      # server instead of passing the unrecognized-key guard (which already
+      # symbolized) and then being ignored by normalization — which is how
+      # +enable_mcp!("auth_tokens" => [...])+ served the endpoint without
+      # authentication.
+      #
+      # A String key and its Symbol twin are two spellings of one option: equal
+      # values collapse, differing values conflict. Keys that cannot be
+      # symbolized are kept as-is for the unrecognized-key guard.
+      # @api private
+      def self.symbolize_keys(opts)
+        seen = {} # symbolized key => [original spelling, value]
+        opts.each do |key, value|
+          sym = key.respond_to?(:to_sym) ? key.to_sym : key
+          raise_conflict!(sym, [seen[sym], [key, value]]) if seen.key?(sym) && seen[sym].last != value
+
+          seen[sym] = [key, value]
+        end
+
+        seen.transform_values(&:last)
+      end
+      private_class_method :symbolize_keys
+
+      # @api private
+      def self.raise_conflict!(key, spellings)
+        raise ArgumentError,
+              "Conflicting MCP options for #{key}: " \
+              "#{spellings.map { |spelling, value| "#{spelling.inspect}=#{value.inspect}" }.join(', ')}"
+      end
+      private_class_method :raise_conflict!
+
+      # Reject keys the given scope cannot accept.
+      #
+      # :explicit rejects anything unrecognized, including the constructor-only
+      # gating keys, which it explains by name. :constructor rejects only
+      # unrecognized +mcp_+-prefixed keys, because it is handed Otto's whole
+      # options hash and most keys legitimately belong to other subsystems.
+      # @api private
+      def self.reject_unrecognized_keys!(opts, scope)
+        recognized = RECOGNIZED_KEYS.fetch(scope)
+        unknown    = opts.keys.reject { |k| recognized.include?(k) }
+        unknown.select! { |k| k.to_s.start_with?('mcp_') } if scope == :constructor
+        return if unknown.empty?
+
+        message = "Unknown MCP option(s): #{unknown.map(&:inspect).join(', ')}. "
+        gating  = unknown & GATING_KEYS
+        unless gating.empty?
+          message += "#{gating.map(&:inspect).join(', ')} gate whether MCP is enabled and are " \
+                     'constructor-only: pass them to Otto.new. #enable_mcp! always enables the ' \
+                     'HTTP endpoint, so it cannot honour them. '
+        end
+
+        raise ArgumentError,
+              message + "Recognized MCP options (#{scope}): #{recognized.map(&:inspect).join(', ')}"
+      end
+      private_class_method :reject_unrecognized_keys!
+
+      # @api private
+      def self.coerce_option(key, value)
+        case key
+        when :auth_tokens
+          coerce_auth_tokens!(value)
+        when :enable_validation, :enable_rate_limiting, :allow_unauthenticated
+          coerce_boolean!(key, value)
+        when :requests_per_minute, :tools_per_minute
+          unless value.is_a?(Integer) && value.positive?
+            raise ArgumentError,
+                  "MCP #{key} must be a positive Integer, got #{value.inspect}"
+          end
+
+          value
+        when :http_endpoint
+          unless value.is_a?(String) && value.start_with?('/')
+            raise ArgumentError,
+                  "MCP http_endpoint must be a String path starting with '/', got #{value.inspect}"
+          end
+
+          value
+        else
+          value
+        end
+      end
+      private_class_method :coerce_option
+
+      # Coerce and validate the configured bearer tokens.
+      #
+      # A literal empty Array is the one accepted "no tokens" spelling: it is
+      # unambiguous, and it is what {.normalize} itself emits when the key is
+      # omitted, which keeps normalization idempotent. Every other empty shape
+      # (+nil+, +''+, +[nil]+, +['']+) raises, because those are what
+      # +auth_tokens: ENV['MCP_TOKEN']+ produces when the variable is unset —
+      # silently serving the endpoint to anyone.
+      # @api private
+      def self.coerce_auth_tokens!(value)
+        return [] if value.is_a?(Array) && value.empty?
+
+        tokens  = value.is_a?(String) ? [value] : Array(value)
+        invalid = tokens.grep_v(String)
+        unless invalid.empty?
+          raise ArgumentError,
+                "MCP auth_tokens must be Strings, got #{invalid.map(&:class).uniq.join(', ')}"
+        end
+
+        raise_empty_auth_tokens!(value) if tokens.empty?
+
+        blank = tokens.select { |token| token.strip.empty? }
+        unless blank.empty?
+          raise ArgumentError,
+                "MCP auth_tokens must not be blank, got #{blank.map(&:inspect).join(', ')}. " \
+                'A blank token cannot be presented by a client and would not protect the endpoint.'
+        end
+
+        tokens
+      end
+      private_class_method :coerce_auth_tokens!
+
+      # @api private
+      def self.raise_empty_auth_tokens!(value)
+        raise ArgumentError,
+              "MCP auth_tokens was supplied as #{value.inspect} but resolves to no tokens. " \
+              "This is what auth_tokens: ENV['MCP_TOKEN'] does when the variable is unset, " \
+              'and it would expose the MCP endpoint to any caller. Supply at least one token, ' \
+              'or omit auth_tokens entirely and pass allow_unauthenticated: true to serve the ' \
+              'endpoint without authentication on purpose.'
+      end
+      private_class_method :raise_empty_auth_tokens!
+
+      # @api private
+      def self.coerce_boolean!(key, value)
+        return value if [true, false].include?(value)
+
+        raise ArgumentError, "MCP #{key} must be true or false, got #{value.inspect}"
+      end
+      private_class_method :coerce_boolean!
+    end
+  end
+end