otto 2.9.0 → 2.10.0

data/lib/otto/caddy_tls/localhost_guard.rb

@@ -59,17 +59,14 @@ class Otto
     # The strongest isolation is still network-level: bind the endpoint on a
     # dedicated loopback-only port that the proxy reaches directly (see
     # examples/caddy_tls_demo/standalone.ru). Blocking the endpoint path at the
-    # proxy is a sound additional layer. See docs/reverse-proxy-network-services.md.
+    # proxy is a sound additional layer. See
+    # docs/adr/adr-003-caddy-tls-route-based-integration.md.
     class LocalhostGuard
       # Forwarding headers whose presence means the request was relayed by a
       # proxy rather than issued directly. Any one present => not a direct local
-      # call. Mirrors Otto::Utils::FORWARDED_FOR_HEADERS plus RFC 7239 Forwarded.
-      FORWARDED_HEADERS = %w[
-        HTTP_X_FORWARDED_FOR
-        HTTP_X_REAL_IP
-        HTTP_X_CLIENT_IP
-        HTTP_FORWARDED
-      ].freeze
+      # call. The forwarded-for family plus RFC 7239 Forwarded, shared with
+      # IPPrivacyMiddleware's pre-scrub record so the two cannot drift.
+      FORWARDED_HEADERS = Otto::Utils::RELAY_MARKER_HEADERS
 
       # @param app [#call] the downstream Rack app
       # @param endpoint [String] the path to protect (e.g. '/_caddy/tls-permission')
@@ -99,27 +96,28 @@ class Otto
 
       # Whether any forwarding header is present (request came via a proxy).
       #
-      # Unlike the peer check, this reads header STATE, which IPPrivacyMiddleware
-      # has already touched by the time the guard runs. That is safe in both of
-      # its paths, but only for a reason worth writing down:
+      # Unlike the peer check, a header scan reads STATE that IPPrivacyMiddleware
+      # has already touched by the time the guard runs, and one of its paths
+      # DELETES relay markers while REMOTE_ADDR stays loopback: the
+      # untrusted-peer scrub, which removes HTTP_FORWARDED and the
+      # X-Forwarded-Host/Proto/Scheme/SSL/Port authority carriers for every
+      # peer under `trusted_proxies: :none` and for any unlisted peer in CIDR
+      # mode. A request relayed over loopback by a proxy emitting only RFC 7239
+      # `Forwarded`, or only `X-Forwarded-Host`, would then look direct,
+      # turning a deny into an allow. Otto::Utils::RELAY_MARKER_HEADERS
+      # therefore covers every carrier the scrub can delete.
       #
-      # - Masking REWRITES a forwarded header to the masked IP rather than
-      #   removing it, so a relayed request still looks relayed. Correct — it was.
-      # - The no-resolvable-client-IP path DELETES them, which would make a
-      #   relayed request look direct. That path is reached only when REMOTE_ADDR
-      #   is absent or blank, which forces otto.peer_loopback to false, so
-      #   #direct_local_call? denies on the peer check before this one matters.
-      #
-      # So header deletion upstream cannot turn a deny into an allow — but that
-      # rests on the peer check failing closed for a blank address. Anything that
-      # makes an unresolvable-IP request keep a loopback peer verdict would need
-      # to record the relay state pre-scrub too (an otto.peer_relayed sibling to
-      # otto.peer_loopback).
+      # So prefer +env['otto.peer_relayed']+ — IPPrivacyMiddleware's verdict on
+      # the ORIGINAL headers, recorded before any scrub — and fall back to the
+      # live scan only when the guard runs without that middleware.
       #
       # @param env [Hash] Rack environment
       # @return [Boolean]
       def relayed?(env)
-        FORWARDED_HEADERS.any? { |header| !env[header].to_s.strip.empty? }
+        recorded = env['otto.peer_relayed']
+        return recorded if [true, false].include?(recorded)
+
+        Otto::Utils.relayed_request?(env)
       end
 
       # Whether this request is for the protected endpoint. Normalizes

data/lib/otto/core/configuration.rb

@@ -55,7 +55,17 @@ class Otto
         end
 
         # Add trusted proxies if provided
-        Array(opts[:trusted_proxies]).each { |proxy| add_trusted_proxy(proxy) } if opts[:trusted_proxies]
+        # `trusted_proxies: :none` is an explicit operator assertion that no
+        # proxy is trusted (as opposed to omitting the option, which asserts
+        # nothing); see Otto::Security::Config#trust_no_proxies!.
+        if Otto::Security::Config.trust_no_proxies_option?(opts[:trusted_proxies])
+          @security_config.trust_no_proxies!
+        elsif opts[:trusted_proxies]
+          # Pass the list whole so add_trusted_proxy validates every entry
+          # before registering any (a mixed list containing 'none' is rejected
+          # without installing the rest).
+          add_trusted_proxy(Array(opts[:trusted_proxies])) unless Array(opts[:trusted_proxies]).empty?
+        end
 
         # Set count-based trusted-proxy depth if provided (mutually exclusive
         # with trusted_proxies; conflict validated at configuration freeze).
@@ -64,10 +74,16 @@ class Otto
         # and fails loud instead of being silently dropped.
         @security_config.trusted_proxy_depth = opts[:trusted_proxy_depth] unless opts[:trusted_proxy_depth].nil?
 
-        # Select the forwarded header depth mode reads from ('X-Forwarded-For',
-        # 'Forwarded', or 'Both'). Only consulted in depth mode. Same presence
-        # guard: a provided-but-invalid value is validated, not ignored.
-        @security_config.trusted_proxy_header = opts[:trusted_proxy_header] unless opts[:trusted_proxy_header].nil?
+        # Select the forwarded family Otto and Rack read from. An explicit
+        # option is an operator choice that every Otto app in the process must
+        # share; with no option, align Rack with Otto's default family without
+        # staking that claim, so a no-options sub-mount never blocks a later
+        # explicit choice. A provided-but-invalid value is still validated.
+        if opts[:trusted_proxy_header].nil?
+          @security_config.apply_default_rack_forwarding_family!
+        else
+          @security_config.trusted_proxy_header = opts[:trusted_proxy_header]
+        end
 
         # Set custom security headers
         return unless opts[:security_headers]
@@ -87,17 +103,25 @@ class Otto
       def configure_mcp(opts)
         @mcp_server = nil
 
-        # Enable MCP if requested in options
-        return unless opts[:mcp_enabled] || opts[:mcp_http] || opts[:mcp_stdio]
+        # Enable MCP if requested in options. The gating keys are read through
+        # the MCP option normalizer so that "mcp_enabled" => true enables MCP
+        # exactly like mcp_enabled: true, matching the String-or-Symbol
+        # contract every other MCP option already honours (#258). The
+        # normalizer also raises unless each value is exactly true or false:
+        # the `== false` check below would otherwise mount the endpoint for a
+        # String "false" from ENV.fetch or YAML, or for nil from an unset ENV.
+        gating = Otto::MCP::Options.gating_options(opts)
+        return unless gating[:mcp_enabled] || gating[:mcp_http] || gating[:mcp_stdio]
 
         @mcp_server = Otto::MCP::Server.new(self)
 
-        mcp_options = {}
-        mcp_options[:http_endpoint] = opts[:mcp_endpoint] if opts[:mcp_endpoint]
-
-        return unless opts[:mcp_http] != false # Default to true unless explicitly disabled
+        return if gating[:mcp_http] == false # Default to true unless explicitly disabled
 
-        @mcp_server.enable!(mcp_options)
+        # Forward the whole options hash under the :constructor scope, which
+        # picks out the MCP vocabulary (auth_tokens, rate limits, ...) and
+        # ignores the rest of Otto's options. Previously only the endpoint
+        # survived, silently starting an unauthenticated MCP endpoint (#258).
+        @mcp_server.enable!(Otto::MCP::Server.normalize_options(opts, :constructor))
       end
 
       # Validate and freeze the lambda handler registry supplied at construction
@@ -282,16 +306,6 @@ class Otto
         # Deep freeze route structures (prevent modification of nested hashes/arrays)
         deep_freeze_value(@routes) if @routes
         deep_freeze_value(@routes_literal) if @routes_literal
-        # @routes_static is intentionally NOT deep-frozen: its :GET entry is a
-        # Concurrent::Map that lazy static-file discovery writes into at
-        # request time (Core::Router#handle_request, Core::FileSafety#add_static_path),
-        # after this method has already run. Deep-freezing it would turn the
-        # first request for any as-yet-uncached static file into a
-        # FrozenError / 500 in production (issue #185). The outer hash is
-        # still shallow-frozen so its verb-key structure (currently just
-        # :GET) can't be altered post-freeze, while the Concurrent::Map value
-        # stays writable.
-        @routes_static.freeze if @routes_static && !@routes_static.frozen?
         deep_freeze_value(@route_definitions) if @route_definitions
         deep_freeze_value(@routes_by_definition) if @routes_by_definition
 

data/lib/otto/core/file_safety.rb

@@ -4,31 +4,75 @@
 
 class Otto
   module Core
-    # File safety module providing secure file access validation and path traversal protection
+    # File safety module providing secure file access validation and path traversal protection.
+    #
+    # Symlink policy (issue #257)
+    # ---------------------------
+    # Every candidate path is canonicalized with File.realpath before it is
+    # compared against the canonicalized public root. A symlink inside the
+    # public directory is therefore served ONLY when its fully resolved target
+    # (including every intermediate directory component) is still inside that
+    # root. Links that escape the root are rejected even when the target is
+    # owned by the same user or group -- the ownership check is a second gate,
+    # not a containment gate.
+    #
+    # The root itself is canonicalized too, so a symlinked public directory
+    # (the usual `public -> releases/<n>/public` deploy layout) keeps working.
+    #
+    # Missing, unreadable, looping and non-directory-component paths all fail
+    # closed: realpath raises and the raise is treated as "unsafe".
     module FileSafety
-      def safe_file?(path)
-        return false if option[:public].nil? || option[:public].empty?
-        return false if path.nil? || path.empty?
+      # Errors raised by File.realpath for paths that must never be served.
+      REALPATH_ERRORS = [
+        Errno::ENOENT,       # missing target (dangling symlink)
+        Errno::EACCES,       # unreadable component
+        Errno::ELOOP,        # symlink loop
+        Errno::ENOTDIR,      # a path component is not a directory
+        Errno::ENAMETOOLONG, # oversized path
+      ].freeze
 
-        # Normalize and resolve the public directory path
-        public_dir = File.expand_path(option[:public])
-        return false unless File.directory?(public_dir)
+      # A validated static file: the canonical root, the canonical absolute
+      # path under it, and their relative difference. Returned as one value so
+      # callers never have to re-run realpath (one resolution per request).
+      StaticFile = Struct.new(:root, :path, :relative)
 
-        # Clean the requested path - remove null bytes and normalize
-        clean_path = path.delete("\0").strip
-        return false if clean_path.empty?
+      # Resolve a request path to a canonical, contained, servable file.
+      #
+      # @param path [String, nil] request-relative path (may start with '/')
+      # @return [StaticFile, nil] the validated file, or nil when unsafe
+      def resolve_static_file(path)
+        return nil if option[:public].nil? || option[:public].empty?
+        return nil if path.nil? || path.empty?
+
+        public_dir = canonical_public_dir
+        return nil if public_dir.nil?
+
+        # A NUL byte in a request path is never legitimate; it is a truncation
+        # attack on downstream C string handling. Reject it rather than
+        # repairing the path into something servable.
+        return nil if path.include?("\0")
+
+        clean_path = path.strip
+        return nil if clean_path.empty?
+
+        # Join, then canonicalize: realpath resolves '..', '.' AND every
+        # symlink component, so the containment check below cannot be fooled
+        # by a link that points outside the public directory.
+        candidate = File.join(public_dir, clean_path)
+        real_path = safe_realpath(candidate)
+        return nil if real_path.nil?
 
-        # Join and expand to get the full resolved path
-        requested_path = File.expand_path(File.join(public_dir, clean_path))
+        return nil unless contained?(real_path, public_dir)
 
-        # Ensure the resolved path is within the public directory (prevents path traversal)
-        return false unless requested_path.start_with?(public_dir + File::SEPARATOR)
+        # Second gate: it must be a readable regular file we (or our group) own.
+        return nil unless File.file?(real_path) && File.readable?(real_path)
+        return nil unless File.owned?(real_path) || File.grpowned?(real_path)
 
-        # Check file exists, is readable, and is not a directory
-        File.exist?(requested_path) &&
-          File.readable?(requested_path) &&
-          !File.directory?(requested_path) &&
-          (File.owned?(requested_path) || File.grpowned?(requested_path))
+        StaticFile.new(public_dir, real_path, real_path.delete_prefix(public_dir + File::SEPARATOR))
+      end
+
+      def safe_file?(path)
+        !resolve_static_file(path).nil?
       end
 
       def safe_dir?(path)
@@ -38,23 +82,37 @@ class Otto
         clean_path = path.delete("\0").strip
         return false if clean_path.empty?
 
-        expanded_path = File.expand_path(clean_path)
+        real_path = safe_realpath(clean_path)
+        return false if real_path.nil?
 
         # Check directory exists, is readable, and has proper ownership
-        File.directory?(expanded_path) &&
-          File.readable?(expanded_path) &&
-          (File.owned?(expanded_path) || File.grpowned?(expanded_path))
+        File.directory?(real_path) &&
+          File.readable?(real_path) &&
+          (File.owned?(real_path) || File.grpowned?(real_path))
+      end
+
+      private
+
+      # Canonical public root, or nil when it is missing/not a directory.
+      # Not memoized: the root can be replaced (deploy symlink flip) between
+      # requests and each request must see the current target.
+      def canonical_public_dir
+        real = safe_realpath(option[:public])
+        return nil if real.nil? || !File.directory?(real)
+
+        real
       end
 
-      def add_static_path(path)
-        return unless safe_file?(path)
+      def safe_realpath(path)
+        File.realpath(path)
+      rescue *REALPATH_ERRORS, SystemCallError, ArgumentError
+        nil
+      end
 
-        base_path                      = File.split(path).first
-        # Files in the root directory can refer to themselves
-        base_path                      = path if base_path == '/'
-        File.join(option[:public], base_path)
-        Otto.logger.debug "new static route: #{base_path} (#{path})" if Otto.debug
-        routes_static[:GET][base_path] = base_path
+      # Component-aware containment: '/srv/public2' must not pass for the
+      # root '/srv/public', so compare on a separator boundary.
+      def contained?(real_path, root)
+        real_path == root || real_path.start_with?(root + File::SEPARATOR)
       end
     end
   end

data/lib/otto/core/middleware_stack.rb

@@ -121,54 +121,54 @@ class Otto
         @on_change_callback&.call
       end
 
-      # Validate MCP middleware ordering
+      # MCP middleware in security-optimal EXECUTION order, outermost first.
+      # @api private
+      MCP_MIDDLEWARE_EXECUTION_ORDER = [
+        'Otto::MCP::RateLimitMiddleware',
+        'Otto::MCP::Auth::TokenMiddleware',
+        'Otto::MCP::SchemaValidationMiddleware',
+      ].freeze
+
+      # Validate MCP middleware ordering.
       #
-      # MCP middleware must be in security-optimal order:
-      # 1. RateLimitMiddleware (reject excessive requests early)
+      # MCP middleware must run in this order, where "before" means "sees the
+      # request first" — i.e. is the further-out wrapper:
+      # 1. RateLimitMiddleware (shed excessive load early)
       # 2. Auth middleware (validate credentials before parsing)
       # 3. SchemaValidationMiddleware (expensive JSON schema validation last)
       #
+      # This reasons over #execution_order, NOT over raw array indices. Array
+      # order is the reverse of execution order (see #add_with_position), so the
+      # earlier index-based implementation reported exactly the wrong stacks as
+      # correct.
+      #
       # @return [Array<String>] Warning messages if order is suboptimal
       def validate_mcp_middleware_order
         warnings = []
 
-        # PERFORMANCE NOTE: This implementation intentionally uses select + find_index
-        # rather than a single-pass approach. The filtered mcp_middlewares array is
-        # typically 0-3 items, making the performance difference unmeasurable.
-        # The current approach prioritizes readability over micro-optimization.
-        # Single-pass alternatives were considered but rejected as premature optimization.
-        mcp_middlewares = @stack.select do |entry|
-          [
-            Otto::MCP::RateLimitMiddleware,
-            Otto::MCP::Auth::TokenMiddleware,
-            Otto::MCP::SchemaValidationMiddleware,
-          ].include?(entry[:middleware])
+        # 0-3 items in practice; clarity beats a single-pass micro-optimization.
+        mcp_middlewares = execution_order.select do |middleware|
+          MCP_MIDDLEWARE_EXECUTION_ORDER.include?(middleware.to_s)
         end
 
         return warnings if mcp_middlewares.size < 2
 
-        # Find positions
-        rate_limit_pos = mcp_middlewares.find_index { |e| e[:middleware] == Otto::MCP::RateLimitMiddleware }
-        auth_pos = mcp_middlewares.find_index { |e| e[:middleware] == Otto::MCP::Auth::TokenMiddleware }
-        validation_pos = mcp_middlewares.find_index { |e| e[:middleware] == Otto::MCP::SchemaValidationMiddleware }
-
-        # Check optimal order: rate_limit < auth < validation
-        if rate_limit_pos && auth_pos && rate_limit_pos > auth_pos
-          warnings << <<~MSG.chomp
-            [MCP Middleware] RateLimitMiddleware should come before TokenMiddleware
-          MSG
-        end
-
-        if auth_pos && validation_pos && auth_pos > validation_pos
-          warnings << <<~MSG.chomp
-            [MCP Middleware] TokenMiddleware should come before SchemaValidationMiddleware
-          MSG
-        end
-
-        if rate_limit_pos && validation_pos && rate_limit_pos > validation_pos
-          warnings << <<~MSG.chomp
-            [MCP Middleware] RateLimitMiddleware should come before SchemaValidationMiddleware
-          MSG
+        # Positions in EXECUTION order: smaller means it sees the request
+        # sooner. The same class can be registered more than once (entries are
+        # keyed on class + args + options), so compare the LAST occurrence of
+        # the outer middleware against the FIRST occurrence of the inner one:
+        # the order is only right when every outer occurrence precedes every
+        # inner occurrence. Checking first-vs-first would pass a stack shaped
+        # rate-limit, auth, rate-limit.
+        first_position = ->(name) { mcp_middlewares.find_index { |m| m.to_s == name } }
+        last_position  = ->(name) { mcp_middlewares.rindex { |m| m.to_s == name } }
+
+        MCP_MIDDLEWARE_EXECUTION_ORDER.combination(2) do |outer, inner|
+          outer_pos = last_position.call(outer)
+          inner_pos = first_position.call(inner)
+          next unless outer_pos && inner_pos && outer_pos > inner_pos
+
+          warnings << "[MCP Middleware] #{outer.split('::').last} should run before #{inner.split('::').last}"
         end
 
         warnings

data/lib/otto/core/router.rb

@@ -100,7 +100,12 @@ class Otto
         locale             = determine_locale env
         env['rack.locale'] = locale
         env['otto.locale_config'] = @locale_config.to_h if @locale_config
-        @static_route    ||= Rack::Files.new(option[:public]) if option[:public] && safe_dir?(option[:public])
+        # Rack::Files is rooted at the CANONICAL public directory, so the
+        # symlink-free relative path #serve_static_file hands it is joined to a
+        # symlink-free root (issue #257). A missing root leaves @static_route
+        # nil and the request falls through to normal routing (404), rather
+        # than raising at construction.
+        @static_route    ||= build_static_route
         path_info          = Rack::Utils.unescape(env['PATH_INFO'])
         path_info          = '/' if path_info.to_s.empty?
 
@@ -117,9 +122,6 @@ class Otto
           path_info_clean = path_info
         end
 
-        base_path      = File.split(path_info).first
-        # Files in the root directory can refer to themselves
-        base_path      = path_info if base_path == '/'
         http_verb      = env['REQUEST_METHOD'].upcase.to_sym
         literal_routes = routes_literal[http_verb] || {}
         literal_routes.merge! routes_literal[:GET] if http_verb == :HEAD
@@ -138,14 +140,12 @@ class Otto
         # 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',
-              base_path: base_path
-            ))
-          static_route.call(env)
-        elsif literal_routes.has_key?(path_info_clean)
+        static_candidate = !static_route.nil? && http_verb == :GET
+
+        # Dispatch precedence is fixed: literal routes, then static files, then
+        # dynamic routes. Static-file requests always pass through containment
+        # validation before they are served (issues #257 and #260).
+        if literal_routes.has_key?(path_info_clean)
           route = literal_routes[path_info_clean]
           Otto.structured_log(:debug, 'Route matched',
             Otto::LoggingHelpers.request_context(env).merge(
@@ -158,14 +158,10 @@ 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?(dispatch_path)
+        elsif static_candidate && (static_file = resolve_static_file(dispatch_path))
           Otto.structured_log(:debug, 'Route matched',
-            Otto::LoggingHelpers.request_context(env).merge(
-              type: 'static_new',
-              base_path: base_path
-            ))
-          routes_static[:GET][base_path] = base_path
-          static_route.call(env)
+            Otto::LoggingHelpers.request_context(env).merge(type: 'static'))
+          serve_static_file(env, static_file)
         else
           match_dynamic_route(env, dispatch_path, http_verb, literal_routes)
         end
@@ -191,6 +187,53 @@ class Otto
 
       private
 
+      # Serve the path that was actually validated, not the request path.
+      #
+      # Rack::Files re-derives its target by joining its root with PATH_INFO,
+      # so handing it the raw request path reopened the check/open gap that
+      # #resolve_static_file just closed: an approved request path could be
+      # re-resolved through a symlink at open time. Rewriting PATH_INFO to the
+      # canonical (fully symlink-resolved) relative path means the path
+      # Rack::Files opens contains no symlink components at all.
+      #
+      # Residual TOCTOU: a real (non-symlink) component renamed between the
+      # File.realpath in #resolve_static_file and the File.open inside
+      # Rack::Files could still redirect the open. Closing that requires an
+      # O_NOFOLLOW-per-component or fd-based serve, i.e. replacing
+      # Rack::Files. Accepted for now; see issue #257.
+      def serve_static_file(env, static_file)
+        static_env = env.dup
+        # Rack::Files unescapes PATH_INFO, so escape the canonical path to
+        # survive the round trip (escape_path preserves '/').
+        static_env['PATH_INFO'] = "/#{Rack::Utils.escape_path(static_file.relative)}"
+        static_route_for(static_file.root).call(static_env)
+      end
+
+      # Rack::Files rooted at the root +static_file+ was validated against.
+      #
+      # @static_route is memoised once, but the public directory can be
+      # repointed without a restart (a release symlink flip). Containment
+      # re-resolves the root on every request and would validate against the
+      # new tree while the memoised Rack::Files kept opening files under the
+      # old one, so a validated relative path could be joined to a root it was
+      # never checked against. Rebuild whenever the two diverge. The race
+      # between two threads rebuilding at once is benign: both produce an
+      # equivalent instance for the same root.
+      def static_route_for(root)
+        current = static_route
+        return current if current && current.root == root
+
+        @static_route = Rack::Files.new(root)
+      end
+
+      def build_static_route
+        return nil if option[:public].nil? || option[:public].empty?
+        return nil unless safe_dir?(option[:public])
+
+        root = canonical_public_dir
+        root && Rack::Files.new(root)
+      end
+
       # +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

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