otto 2.11.0 → 2.12.0

data/lib/otto/security/configurator.rb

@@ -23,34 +23,60 @@ class Otto
         @auth_config = auth_config || { auth_strategies: {}, default_auth_strategy: 'noauth' }
       end
 
+      # Options accepted by #configure, with their defaults. A new security
+      # knob is a new entry here, not another keyword parameter.
+      CONFIGURE_DEFAULTS = {
+             csrf_protection: false,
+          request_validation: false,
+               rate_limiting: false,
+             trusted_proxies: [].freeze,
+         trusted_proxy_depth: nil,
+        trusted_proxy_header: nil,
+            security_headers: {}.freeze,
+                        hsts: false,
+                         csp: false,
+            frame_protection: false,
+              authentication: false,
+      }.freeze
+
+      # The options #configure resolved: CONFIGURE_DEFAULTS overlaid with the
+      # caller's, read through accessors so a misspelled read in #configure
+      # raises instead of returning nil.
+      ConfigureOptions = Data.define(*CONFIGURE_DEFAULTS.keys)
+
       # Unified security configuration method with sensible defaults
       #
       # Provides a comprehensive, one-stop configuration method for Otto's security features.
       # This method allows configuring multiple security aspects in a single call, with flexible options.
+      # Every option is optional; see CONFIGURE_DEFAULTS.
       #
-      # @param csrf_protection [Boolean, Hash] Enable CSRF protection
+      # @param options [Hash] security options
+      # @option options [Boolean, Hash] :csrf_protection Enable CSRF protection
       #   - `true`: Enable with default settings
       #   - `Hash`: Provide custom CSRF configuration
-      # @param request_validation [Boolean] Enable input validation and sanitization
-      # @param rate_limiting [Boolean, Hash] Enable rate limiting
+      # @option options [Boolean] :request_validation Enable input validation and sanitization
+      # @option options [Boolean, Hash] :rate_limiting Enable rate limiting
       #   - `true`: Enable with default settings
       #   - `Hash`: Provide custom rate limiting rules
-      # @param trusted_proxies [String, Array<String>, Symbol] IP addresses or
-      #   CIDR ranges to trust, or :none to assert that no proxy is trusted
-      # @param trusted_proxy_depth [Integer, nil] Count-based proxy depth ("trust
-      #   the last N hops") for non-enumerable proxy tiers; mutually exclusive
-      #   with trusted_proxies (validated at configuration freeze)
-      # @param trusted_proxy_header [String, nil] Forwarded header depth mode
-      #   counts hops from: 'X-Forwarded-For' (default), 'Forwarded' (RFC 7239),
-      #   or 'Both'. Otto reads it only in depth mode, but setting it always
-      #   pins Rack::Request.forwarded_priority (process-global) to that family
-      #   and claims the family for this process; see
+      # @option options [String, Array<String>, Symbol] :trusted_proxies IP
+      #   addresses or CIDR ranges to trust, or :none to assert that no proxy
+      #   is trusted
+      # @option options [Integer, nil] :trusted_proxy_depth Count-based proxy
+      #   depth ("trust the last N hops") for non-enumerable proxy tiers;
+      #   mutually exclusive with trusted_proxies
+      # @option options [String, nil] :trusted_proxy_header Forwarded header
+      #   depth mode counts hops from: 'X-Forwarded-For' (default), 'Forwarded'
+      #   (RFC 7239), or 'Both'. Otto reads it only in depth mode, but setting
+      #   it always pins Rack::Request.forwarded_priority (process-global) to
+      #   that family and claims the family for this process; see
       #   Otto::Security::Config.apply_rack_forwarding_family!.
-      # @param security_headers [Hash] Custom security headers to merge with defaults
-      # @param hsts [Boolean] Enable HTTP Strict Transport Security
-      # @param csp [Boolean, String] Enable Content Security Policy
-      # @param frame_protection [Boolean, String] Enable frame protection
-      # @param authentication [Boolean] Enable authentication
+      # @option options [Hash] :security_headers Custom security headers to merge with defaults
+      # @option options [Boolean] :hsts Enable HTTP Strict Transport Security
+      # @option options [Boolean, String] :csp Enable Content Security Policy
+      # @option options [Boolean, String] :frame_protection Enable frame protection
+      # @option options [Boolean] :authentication Accepted for compatibility;
+      #   authentication is configured through strategies (#add_auth_strategy)
+      # @raise [ArgumentError] for an unrecognized option
       #
       # @example Configure multiple security features in one call
       #   otto.security.configure(
@@ -63,41 +89,31 @@ class Otto
       #     csp: "default-src 'self'",
       #     frame_protection: 'SAMEORIGIN'
       #   )
-      def configure(
-        csrf_protection: false,
-        request_validation: false,
-        rate_limiting: false,
-        trusted_proxies: [],
-        trusted_proxy_depth: nil,
-        trusted_proxy_header: nil,
-        security_headers: {},
-        hsts: false,
-        csp: false,
-        frame_protection: false,
-        authentication: false
-      )
-        enable_csrf_protection! if csrf_protection
-        enable_request_validation! if request_validation
-        enable_rate_limiting!(rate_limiting.is_a?(Hash) ? rate_limiting : {}) if rate_limiting
-
-        if Otto::Security::Config.trust_no_proxies_option?(trusted_proxies)
+      def configure(**options)
+        opts = resolve_configure_options(options)
+
+        enable_csrf_protection! if opts.csrf_protection
+        enable_request_validation! if opts.request_validation
+        enable_rate_limiting!(opts.rate_limiting.is_a?(Hash) ? opts.rate_limiting : {}) if opts.rate_limiting
+
+        if Otto::Security::Config.trust_no_proxies_option?(opts.trusted_proxies)
           trust_no_proxies!
         else
           # Pass the list whole so add_trusted_proxy validates every entry
           # before registering any; a mixed list like ['10.0.0.0/8', 'none']
           # must not leave the first half installed.
-          add_trusted_proxy(Array(trusted_proxies)) unless Array(trusted_proxies).empty?
+          add_trusted_proxy(Array(opts.trusted_proxies)) unless Array(opts.trusted_proxies).empty?
         end
-        self.trusted_proxy_depth = trusted_proxy_depth unless trusted_proxy_depth.nil?
-        self.trusted_proxy_header = trusted_proxy_header unless trusted_proxy_header.nil?
+        self.trusted_proxy_depth = opts.trusted_proxy_depth unless opts.trusted_proxy_depth.nil?
+        self.trusted_proxy_header = opts.trusted_proxy_header unless opts.trusted_proxy_header.nil?
         # Proxy trust configured here (after Otto.new) commits the app to its
         # forwarding family now rather than at freeze.
         @security_config.commit_rack_forwarding_family!
-        self.security_headers = security_headers unless security_headers.empty?
+        self.security_headers = opts.security_headers unless opts.security_headers.empty?
 
-        enable_hsts! if hsts
-        enable_csp! if csp
-        enable_frame_protection! if frame_protection
+        enable_hsts! if opts.hsts
+        enable_csp! if opts.csp
+        enable_frame_protection! if opts.frame_protection
       end
 
       # Enable CSRF protection for POST, PUT, DELETE, and PATCH requests.
@@ -195,6 +211,13 @@ class Otto
         @security_config.security_headers.merge!(headers)
       end
 
+      # Set the Referrer-Policy value added to Otto responses.
+      #
+      # @param policy [String] one W3C Referrer Policy HTTP token
+      def referrer_policy=(policy)
+        @security_config.referrer_policy = policy
+      end
+
       # Enable HTTP Strict Transport Security (HSTS) header.
       # WARNING: This can make your domain inaccessible if HTTPS is not properly
       # configured. Only enable this when you're certain HTTPS is working correctly.
@@ -249,7 +272,8 @@ class Otto
       # inject {Otto::Security::CSP::ReportMiddleware} pinned OUTERMOST so it
       # intercepts report POSTs ahead of CSRF regardless of enable order.
       #
-      # @param report_uri [String] path browsers POST reports to (matched against PATH_INFO)
+      # @param report_uri [String] site-absolute path browsers POST reports to,
+      #   including any mount prefix (see {Otto::Security::Config#csp_report_uri=})
       # @param endpoint_url [String, nil] absolute URL for the modern Reporting
       #   API endpoint (emits `report-to` + `Reporting-Endpoints`); nil emits
       #   only the legacy `report-uri`
@@ -267,7 +291,8 @@ class Otto
       # Configure the CSP violation report path without injecting middleware.
       # Prefer {#enable_csp_reporting!} for the full turnkey setup.
       #
-      # @param uri [String, nil] report path (matched against PATH_INFO), or nil to disable
+      # @param uri [String, nil] site-absolute report path, including any mount
+      #   prefix (see {Otto::Security::Config#csp_report_uri=}), or nil to disable
       def csp_report_uri=(uri)
         @security_config.csp_report_uri = uri
       end
@@ -327,6 +352,18 @@ class Otto
 
       private
 
+      # Overlay the caller's options on CONFIGURE_DEFAULTS. An unrecognized
+      # key raises the ArgumentError a keyword parameter list raises, checked
+      # here because Data.new would also accept a String spelling of a member.
+      def resolve_configure_options(options)
+        unknown = options.keys - CONFIGURE_DEFAULTS.keys
+        unless unknown.empty?
+          raise ArgumentError, "unknown keyword#{'s' if unknown.size > 1}: #{unknown.map(&:inspect).join(', ')}"
+        end
+
+        ConfigureOptions.new(**CONFIGURE_DEFAULTS, **options)
+      end
+
       def middleware_enabled?(middleware_class)
         @middleware_stack.includes?(middleware_class)
       end

data/lib/otto/security/core.rb

@@ -221,8 +221,10 @@ class Otto
       # emits a `report-to` directive plus a `Reporting-Endpoints` header so those
       # browsers deliver `application/reports+json` to the same receiver.
       #
-      # @param report_uri [String] path browsers POST reports to (matched against
-      #   `PATH_INFO`, e.g. `/_/csp-report`).
+      # @param report_uri [String] site-absolute path browsers POST reports to,
+      #   including any mount prefix (e.g. `/_/csp-report`, or
+      #   `/api/_/csp-report` when mounted at `/api`). See
+      #   {Otto::Security::Config#csp_report_uri=}.
       # @param endpoint_url [String, nil] absolute URL for the modern Reporting
       #   API endpoint (e.g. `https://example.com/_/csp-report`); nil emits only
       #   the legacy `report-uri`.

data/lib/otto/security/csp/report_middleware.rb

@@ -22,6 +22,8 @@ class Otto
       #   not configured the middleware is a transparent pass-through.
       # - Only intercepts a POST whose path matches the configured report URI.
       #   Everything else (other paths, other methods) passes through untouched.
+      #   The match is on the full request path (mount prefix included), since
+      #   the report URI is the site-absolute path the browser POSTs to.
       # - Short-circuits BEFORE inner middleware, so CSRF, auth, and rate
       #   limiting never see the request. This is why browsers can POST reports
       #   with no CSRF token: the report never reaches the CSRF middleware.
@@ -76,6 +78,19 @@ class Otto
         # True only when reporting is configured AND this is a POST to the
         # configured report path.
         #
+        # The configured path is site-absolute: it is emitted verbatim as the
+        # `report-uri` directive, and the browser resolves it against the site
+        # root. So it is compared against the request's full path, SCRIPT_NAME
+        # plus PATH_INFO, not the mount-relative PATH_INFO the router matches.
+        # Under `map '/api' { run otto }` a report to `/api/csp-report` arrives
+        # as SCRIPT_NAME=/api, PATH_INFO=/csp-report and still matches a
+        # configured `/api/csp-report`. Unmounted, SCRIPT_NAME is empty and the
+        # two forms coincide.
+        #
+        # Both sides go through Otto::Utils.normalize_path, so a trailing slash
+        # or percent-encoded spelling of the report path is intercepted the way
+        # the router would normalize it.
+        #
         # @param env [Hash]
         # @return [Boolean]
         def report_request?(env)
@@ -83,7 +98,8 @@ class Otto
           return false if report_uri.nil? || report_uri.empty?
           return false unless env['REQUEST_METHOD'] == 'POST'
 
-          env['PATH_INFO'] == report_uri
+          request_path = Otto::Utils.normalize_path("#{env['SCRIPT_NAME']}#{env['PATH_INFO']}")
+          request_path == Otto::Utils.normalize_path(report_uri)
         end
 
         # Read (capped), parse, and dispatch. Never raises; parse/dispatch

data/lib/otto/security/middleware/ip_privacy_middleware.rb

@@ -232,7 +232,8 @@ class Otto
             '[IPPrivacyMiddleware] otto.client_ip was set outside this ' \
             'middleware, so otto.ip_match could not be built from the ' \
             'unmasked address; installing a fail-closed check (every CIDR ' \
-            'test returns false). Let IPPrivacyMiddleware resolve the client IP.'
+            'test returns false). Let IPPrivacyMiddleware resolve the client IP; ' \
+            'test harnesses can build the env with Otto::Testing.env_for.'
           )
           env['otto.ip_match'] = ->(_cidrs) { false }
         end
@@ -499,10 +500,7 @@ class Otto
         #
         # @param env [Hash] Rack environment
         def scrub_forwarded_headers(env)
-          env.delete('HTTP_X_FORWARDED_FOR')
-          env.delete('HTTP_X_REAL_IP')
-          env.delete('HTTP_X_CLIENT_IP')
-          env.delete('HTTP_FORWARDED')
+          Otto::Utils::CLIENT_ADDRESS_HEADERS.each { |key| env.delete(key) }
         end
 
         # Mask X-Forwarded-For and related proxy headers

data/lib/otto/security/rate_limiter.rb

@@ -5,6 +5,7 @@
 require 'json'
 
 require_relative '../optional_dependency'
+require_relative '../utils'
 
 class Otto
   module Security
@@ -31,12 +32,14 @@ class Otto
         default_requests_per_minute = config.fetch(:requests_per_minute, 100)
 
         # General request throttling. Internal paths (/_mcp, /_status, ...)
-        # are skipped by default. PATH_INFO, not Rack::Request#path: #path
-        # prepends SCRIPT_NAME, so with Otto mounted under `map '/api'` the
-        # internal /_mcp request read as /api/_mcp and was counted here while
-        # the MCP throttle, comparing the same way, never saw it at all.
+        # are skipped by default. The mount-relative routing path, not
+        # Rack::Request#path: #path prepends SCRIPT_NAME, so with Otto mounted
+        # under `map '/api'` the internal /_mcp request read as /api/_mcp and
+        # was counted here while the MCP throttle never saw it at all. And the
+        # routing path, not raw PATH_INFO, which counted /%5Fmcp while the
+        # router dispatched it as /_mcp.
         Rack::Attack.throttle('requests', limit: default_requests_per_minute, period: 60) do |request|
-          request.ip unless request.path_info.start_with?('/_')
+          request.ip unless Otto::Utils.routing_path(request.env).start_with?('/_')
         end
 
         # Apply custom rules if provided