otto 2.10.0 → 2.12.0

data/docs/guides/testing-guide.md

@@ -41,6 +41,7 @@ require 'rack/mock'
 require 'rspec'
 require 'tempfile'
 require 'otto'
+require 'otto/testing'
 
 module OttoAppSpecHelpers
   def rack_env(path = '/', method: 'GET', headers: {}, params: {})
@@ -69,6 +70,10 @@ end
 RSpec.configure do |config|
   config.include OttoAppSpecHelpers
 
+  config.before do
+    Otto::Testing.reset!
+  end
+
   config.after do
     Array(@route_files).each(&:unlink)
   end
@@ -79,6 +84,46 @@ Within Otto itself, use the existing helpers in
 [`spec/support/test_helpers.rb`](../../spec/support/test_helpers.rb) instead of
 copying this application-level helper.
 
+## Reset Otto's process-global state between tests
+
+`require 'otto'` does not load `otto/testing`. Require it from the test helper;
+it does not depend on RSpec.
+
+`Otto.new` pins `Rack::Request.forwarded_priority` from `trusted_proxy_header`
+whenever an application configures proxy trust or names a header. Rack keeps one
+priority per process, so Otto records the family and raises `ArgumentError`
+when a later application in the same process chooses a different one. A suite
+that builds one application with `trusted_proxy_header: 'Forwarded'` and
+another with `trusted_proxies:` fails or passes depending on test order unless
+the record is cleared between tests. `Otto::Testing.reset!` clears it and
+restores Rack's priority to the value Otto saw at load time.
+
+Call it before every test:
+
+```ruby
+# RSpec
+RSpec.configure { |config| config.before { Otto::Testing.reset! } }
+
+# Minitest
+class Minitest::Test
+  def before_setup
+    super
+    Otto::Testing.reset!
+  end
+end
+
+# Tryouts: at the start of each test case that builds an Otto app
+## a depth-mode app reading Forwarded
+Otto::Testing.reset!
+Otto.new(nil, trusted_proxy_depth: 1, trusted_proxy_header: 'Forwarded')
+```
+
+Tryouts runs a file's setup section once, before all of its test cases, so a
+reset placed there does not separate the cases from each other.
+
+`Otto::Security::Config.reset_rack_forwarding_family_for_testing!` does the
+same but raises unless RSpec is loaded. It remains for existing callers.
+
 ## Test Logic classes as plain Ruby objects
 
 Logic classes receive an authentication result, merged parameters, and a locale.
@@ -260,7 +305,9 @@ Otto's parser. Send an `application/json` body through a real Otto instance or
 
 Current behavior to cover explicitly:
 
-- a JSON object is merged into the Logic parameters;
+- a JSON object is merged into the Logic parameters below path captures, the
+  query string and any form body, which all win over it;
+- a JSON body on `GET` or `HEAD` is ignored;
 - a valid non-object JSON value is ignored;
 - malformed JSON is logged and the Logic class continues with other parameters;
 - non-JSON bodies are not parsed by the Logic handler.
@@ -343,6 +390,52 @@ octets, or set `mask_private_ips = true` to include private and localhost
 addresses. For application-facing tests, prefer a real Otto instance configured
 through `configure_ip_privacy`.
 
+### Hand a harness a resolved client IP
+
+Code that runs behind `IPPrivacyMiddleware` reads `env['otto.client_ip']` and,
+for access decisions, `env['otto.ip_match']`. Do not write `otto.client_ip` by
+hand. The middleware treats its presence as a sign that it already ran, so it
+never builds `otto.ip_match` from the full address. Instead it installs a check
+that returns `false` for every range and logs a warning. Allowlist tests then
+deny, and when the application uses CIDR proxy trust it also treats the peer as
+untrusted.
+
+`Otto::Testing.env_for` runs the middleware over a Rack env for a request
+arriving directly from `client_ip`, so both keys come from one resolution:
+
+```ruby
+env = Otto::Testing.env_for('/admin', client_ip: '203.0.113.9',
+                                      security_config: otto.security_config)
+
+env['otto.client_ip']                          # => "203.0.113.0" (masked)
+env['otto.ip_match'].call(['203.0.113.9/32'])  # => true
+```
+
+`security_config:` is required. The application's own middleware keeps what
+this resolution produced, so pass `otto.security_config` to get the masking and
+proxy trust of the application under test; `nil` means an unconfigured
+middleware (public addresses masked, no proxy trust). `client_ip: nil` builds a
+request with no resolvable client IP: `env['otto.client_ip']` is `nil` and
+`otto.ip_match` denies every range. Other keywords and String env keys go to
+`Rack::MockRequest.env_for`.
+
+`env_for` models a direct request, so it raises `ArgumentError` when given
+`X-Forwarded-For`, `X-Real-IP`, `X-Client-IP` or `Forwarded`: under a
+configuration that trusts the peer, those would resolve an address other than
+`client_ip`. For a request relayed by a proxy, build the env with `REMOTE_ADDR`
+and the forwarded headers, then resolve it under the application's
+configuration:
+
+```ruby
+env = Rack::MockRequest.env_for('/admin', 'REMOTE_ADDR' => '10.0.0.5',
+                                          'HTTP_X_FORWARDED_FOR' => '203.0.113.9')
+Otto::Testing.resolve_client_ip!(env, otto.security_config)
+```
+
+Resolved under a different configuration, the proxy can become the client and
+the application keeps that answer. `resolve_client_ip!` raises on an env that
+already carries `otto.client_ip` or `otto.ip_match` for the same reason.
+
 See the [privacy guide](privacy.md) and the maintained privacy specs:
 
 - [`spec/otto/ip_privacy_spec.rb`](../../spec/otto/ip_privacy_spec.rb)
@@ -369,13 +462,33 @@ Otto's default route responses include:
 - `x-xss-protection: 1; mode=block`
 - `referrer-policy: strict-origin-when-cross-origin`
 
+Configure exactly one W3C policy token when constructing the application; Otto
+applies it to routed responses, static files, and authentication failures:
+
+```ruby
+otto = Otto.new('routes.txt', referrer_policy: 'no-referrer')
+```
+
+The same setting is available as
+`otto.security_config.referrer_policy = 'no-referrer'` and
+`otto.security.referrer_policy = 'no-referrer'` during boot, before the first
+request freezes configuration. An unknown policy token raises `ArgumentError`
+at configuration time. Comma-separated policy fallback lists are not accepted.
+Existing applications that pass `referrer-policy`
+through `security_headers` remain supported and receive the same validation.
+A route handler that explicitly sets `res['referrer-policy']` keeps its
+response-specific value.
+
 `x-frame-options` is not a default header. Call
 `otto.enable_frame_protection!` before the first request if a test should expect
 `x-frame-options: SAMEORIGIN`.
 
 Test security behavior at the narrowest useful level, but do not require every
 unrelated unit test to repeat header and privacy assertions. Keep those checks in
-focused middleware or request specs.
+focused middleware or request specs. When testing a custom referrer policy,
+exercise a complete response from each response family the application uses
+(for example, routed HTML, `Rack::Files`, and an authentication failure), rather
+than asserting only against `security_config.security_headers`.
 
 ## Maintained examples by task
 

data/lib/otto/caddy_tls/localhost_guard.rb

@@ -120,16 +120,16 @@ class Otto
         Otto::Utils.relayed_request?(env)
       end
 
-      # Whether this request is for the protected endpoint. Normalizes
-      # +PATH_INFO+ through the same +Otto::Utils.normalize_path+ the router
-      # uses for literal matching, so a percent-encoded, invalid-byte, or
-      # trailing-slash variant the router would still route cannot slip past the
-      # guard by normalizing differently here than at dispatch.
+      # Whether this request is for the protected endpoint. Compares the path
+      # the router itself dispatches on (+Otto::Utils.routing_path+), so a
+      # percent-encoded, invalid-byte, or trailing-slash variant the router
+      # would still route cannot slip past the guard by normalizing differently
+      # here than at dispatch.
       #
       # @param env [Hash] Rack environment
       # @return [Boolean]
       def targets_endpoint?(env)
-        normalize_path(env['PATH_INFO']) == @endpoint
+        Otto::Utils.routing_path(env) == @endpoint
       end
 
       # Router-equivalent path normalization. Delegates to the single shared

data/lib/otto/core/configuration.rb

@@ -85,10 +85,12 @@ class Otto
           @security_config.trusted_proxy_header = opts[:trusted_proxy_header]
         end
 
-        # Set custom security headers
-        return unless opts[:security_headers]
+        # Keep the generic security_headers option compatible while routing a
+        # Referrer-Policy entry through the same validated collection as the
+        # dedicated setting. When both are present, the dedicated option wins.
+        set_security_headers(opts[:security_headers]) if opts[:security_headers]
 
-        set_security_headers(opts[:security_headers])
+        @security_config.referrer_policy = opts[:referrer_policy] if opts.key?(:referrer_policy)
       end
 
       def configure_authentication(opts)
@@ -308,11 +310,14 @@ class Otto
         deep_freeze_value(@routes_literal) if @routes_literal
         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

@@ -36,16 +36,32 @@ class Otto
       # callers never have to re-run realpath (one resolution per request).
       StaticFile = Struct.new(:root, :path, :relative)
 
-      # Resolve a request path to a canonical, contained, servable file.
+      # 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?
-        return nil if path.nil? || path.empty?
 
-        public_dir = canonical_public_dir
-        return nil if public_dir.nil?
+        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
@@ -57,18 +73,18 @@ class Otto
 
         # 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)
+        # 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?
 
-        return nil unless contained?(real_path, public_dir)
+        return nil unless contained?(real_path, root)
 
         # 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(public_dir, real_path, real_path.delete_prefix(public_dir + File::SEPARATOR))
+        StaticFile.new(root, real_path, real_path.delete_prefix(root + File::SEPARATOR))
       end
 
       def safe_file?(path)

data/lib/otto/core/router.rb

@@ -105,22 +105,16 @@ class Otto
         # 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?
-
-        begin
-          # Shared with Otto::CaddyTLS::LocalhostGuard so the guard and the
-          # router cannot normalize a path differently (which would be a guard
-          # bypass). See Otto::Utils.normalize_path.
-          path_info_clean = Otto::Utils.normalize_path(env['PATH_INFO'])
-        rescue ArgumentError => e
-          # Log the error but don't expose details
-          Otto.logger.error '[Otto.handle_request] Path encoding error'
-          Otto.logger.debug "[Otto.handle_request] Error details: #{e.message}" if Otto.debug
-          # Set a default value or use the original path_info
-          path_info_clean = path_info
-        end
+        @static_route ||= build_static_route
+
+        # The one path every dispatch stage matches. It comes from the public
+        # Otto::Utils.routing_path so that guards running before the router
+        # (Otto::CaddyTLS::LocalhostGuard, an application's own middleware)
+        # judge exactly this value rather than re-deriving it; a guard that
+        # normalized differently would be a bypass. It never raises: a
+        # malformed escape (%zz) is kept as written and routed like any other
+        # path.
+        path_info_clean = Otto::Utils.routing_path(env)
 
         http_verb      = env['REQUEST_METHOD'].upcase.to_sym
         literal_routes = routes_literal[http_verb] || {}
@@ -142,9 +136,12 @@ class Otto
 
         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).
+        # 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',
@@ -158,6 +155,13 @@ class Otto
             @route_matched_callbacks.each { |cb| cb.call(env, route.route_definition) }
           end
           route.call(env)
+        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_mount', prefix: mount.display_prefix
+            ))
+          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'))
@@ -201,12 +205,18 @@ class Otto
       # 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)
+      #
+      # +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)}"
-        static_route_for(static_file.root).call(static_env)
+        status, headers, body = files.call(static_env)
+        headers['referrer-policy'] ||= @security_config.referrer_policy
+        [status, headers, body]
       end
 
       # Rack::Files rooted at the root +static_file+ was validated against.
@@ -235,9 +245,9 @@ class Otto
       end
 
       # +dispatch_path+ is the normalized path from #handle_request (see the
-      # +dispatch_path+ comment there): +Otto::Utils.normalize_path+ output with
+      # +dispatch_path+ comment there): +Otto::Utils.routing_path+ output with
       # root's empty string mapped back to '/' so the anchored route regexes can
-      # match. It is deliberately NOT the raw +normalize_path+ value.
+      # match. It is deliberately NOT the raw +routing_path+ value.
       def match_dynamic_route(env, dispatch_path, http_verb, literal_routes)
         extra_params  = {}
         found_route   = nil
@@ -287,10 +297,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(@security_config) 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|

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

@@ -217,7 +217,8 @@ class Otto
     # Note: setting CLIENT_IP yourself is out of contract — it trips the
     #       middleware's idempotency guard, so the unmasked address is never
     #       captured and this capability degrades to a logged fail-closed
-    #       check that denies every range.
+    #       check that denies every range. Test harnesses build both keys
+    #       with Otto::Testing.env_for (require 'otto/testing').
     IP_MATCH = 'otto.ip_match'
 
     # Privacy-safe masked IP address