otto 2.9.0 → 2.11.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,23 +306,16 @@ 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
+        # Explicit static mounts are already immutable snapshots; freezing the
+        # array here records that fact and makes any in-place mutation raise.
+        deep_freeze_value(@static_mounts) if @static_mounts
 
         @configuration_frozen = true
 
         duration = Otto::Utils.now_in_μs - start_time
-        frozen_objects = %w[security_config locale_config middleware auth_config option routes]
+        frozen_objects = %w[security_config locale_config middleware auth_config option routes static_mounts]
         Otto.structured_log(:info, 'Freezing completed',
           {
                   duration: duration,

data/lib/otto/core/error_handler.rb

@@ -71,8 +71,8 @@ class Otto
         # Content negotiation for built-in error response
         return json_error_response(error_id) if wants_json_response?(env)
 
-        # Fallback to built-in error response
-        @server_error || secure_error_response(error_id)
+        # Fallback to the configured server_error response, else the built-in one
+        server_error_response(env, error, error_id)
       end
 
       # Register an error handler for expected business logic errors
@@ -268,6 +268,44 @@ class Otto
         end
       end
 
+      # Build the fallback 500 response for an unhandled error.
+      #
+      # A configured +server_error+ callable is invoked per request with
+      # +env+ and the original +error+, trimmed to the positional parameters
+      # it declares; +env+ carries +otto.error_id+ so the response can
+      # reference the logged error. A configured static triple is copied per
+      # request (see {Otto::Static.copy_response}) so header writes by cookie
+      # middleware cannot accumulate on the shared object. A callable that
+      # raises is logged and replaced by the built-in secure response,
+      # mirroring how a failing custom +/500+ route is handled.
+      #
+      # @param env [Hash] Rack environment
+      # @param error [Exception] the unhandled error
+      # @param error_id [String] correlation id already logged for +error+
+      # @return [Array] a fresh Rack triple
+      def server_error_response(env, error, error_id)
+        fallback = @server_error
+        return secure_error_response(error_id) if fallback.nil?
+
+        env['otto.error_id'] = error_id
+        resolve_fallback_response(:server_error, fallback, env, error)
+      rescue StandardError => e
+        fallback_error_id = SecureRandom.hex(8)
+        base_context = Otto::LoggingHelpers.request_context(env)
+
+        Otto.structured_log(:error, 'Error in server_error fallback',
+          base_context.merge(
+            error: e.message,
+            error_class: e.class.name,
+            error_id: fallback_error_id,
+            original_error_id: error_id
+          ))
+        Otto::LoggingHelpers.log_backtrace(e,
+          base_context.merge(error_id: fallback_error_id, original_error_id: error_id))
+
+        secure_error_response(error_id)
+      end
+
       def secure_error_response(error_id)
         body = if Otto.env?(:dev, :development)
                  "Server error (ID: #{error_id}). Check logs for details."

data/lib/otto/core/file_safety.rb

@@ -4,31 +4,91 @@
 
 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 under
+      # the implicit +public:+ directory.
+      #
+      # @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?
+
+        resolve_file_under(canonical_public_dir, path)
+      end
+
+      # Resolve +path+ against an already-canonical +root+ and return it only
+      # when it is a contained, readable, owned regular file.
+      #
+      # Shared by the implicit public directory and explicit static mounts
+      # (Otto::Core::StaticMounts) so both apply one containment policy.
+      # +root+ must be a File.realpath result: containment compares canonical
+      # strings on a separator boundary, so a non-canonical root would never
+      # match the canonicalized candidate.
+      #
+      # @param root [String, nil] canonical directory
+      # @param path [String, nil] root-relative path (may start with '/')
+      # @return [StaticFile, nil] the validated file, or nil when unsafe
+      def resolve_file_under(root, path)
+        return nil if root.nil? || root.empty?
+        return nil if path.nil? || path.empty?
+
+        # 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 and expand to get the full resolved path
-        requested_path = File.expand_path(File.join(public_dir, clean_path))
+        # Join, then canonicalize: realpath resolves '..', '.' AND every
+        # symlink component, so the containment check below cannot be fooled
+        # by a link that points outside the root.
+        candidate = File.join(root, clean_path)
+        real_path = safe_realpath(candidate)
+        return nil if real_path.nil?
 
-        # Ensure the resolved path is within the public directory (prevents path traversal)
-        return false unless requested_path.start_with?(public_dir + File::SEPARATOR)
+        return nil unless contained?(real_path, root)
 
-        # 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))
+        # 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)
+
+        StaticFile.new(root, real_path, real_path.delete_prefix(root + File::SEPARATOR))
+      end
+
+      def safe_file?(path)
+        !resolve_static_file(path).nil?
       end
 
       def safe_dir?(path)
@@ -38,23 +98,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
 
-      def add_static_path(path)
-        return unless safe_file?(path)
+      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 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,15 @@ 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 explicit static
+        # mounts (longest prefix first), then the implicit public directory,
+        # then dynamic routes. Every static-file request passes through
+        # containment validation before it is served (issues #257, #260 and
+        # #267). A mount or the public directory claims files, not paths: when
+        # the file is absent the request falls through to the next stage.
+        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 +161,17 @@ 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 http_verb == :GET && (mounted = resolve_mounted_file(dispatch_path))
+          mount, static_file = mounted
           Otto.structured_log(:debug, 'Route matched',
             Otto::LoggingHelpers.request_context(env).merge(
-              type: 'static_new',
-              base_path: base_path
+              type: 'static_mount', prefix: mount.display_prefix
             ))
-          routes_static[:GET][base_path] = base_path
-          static_route.call(env)
+          serve_static_file(env, static_file, mount.files)
+        elsif static_candidate && (static_file = resolve_static_file(dispatch_path))
+          Otto.structured_log(:debug, 'Route matched',
+            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 +197,57 @@ 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.
+      #
+      # +files+ is the Rack::Files instance rooted at +static_file.root+: a
+      # mount's own frozen instance, or (by default) the public-directory one
+      # that #static_route_for keeps in step with the current root.
+      def serve_static_file(env, static_file, files = static_route_for(static_file.root))
+        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)}"
+        files.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
@@ -244,10 +301,29 @@ class Otto
             Otto::LoggingHelpers.request_context(env).merge(
               fallback_to: 'default_not_found'
             ))
-          @not_found || Otto::Static.not_found
+          not_found_response(env)
         end
       end
 
+      # Build the response for a request that matched no route and has no
+      # +/404+ route configured.
+      #
+      # A configured +not_found+ callable is invoked with +env+ on every miss.
+      # A configured static triple is copied per request (see
+      # {Otto::Static.copy_response}) so header writes by cookie middleware
+      # cannot accumulate on, or leak between requests through, the shared
+      # object. With nothing configured the built-in {Otto::Static.not_found}
+      # response is used.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Array] a fresh Rack triple
+      def not_found_response(env)
+        fallback = @not_found
+        return Otto::Static.not_found if fallback.nil?
+
+        resolve_fallback_response(:not_found, fallback, env)
+      end
+
       def build_route_params(route, values)
         if route.keys.any?
           route.keys.zip(values).each_with_object({}) do |(k, v), hash|