otto 2.6.0 → 2.8.0

data/lib/otto/security/authentication/auth_failure.rb

@@ -6,10 +6,44 @@ class Otto
   module Security
     module Authentication
       # Failure result for authentication failures
-      AuthFailure = Data.define(:failure_reason, :auth_method) do
+      AuthFailure = Data.define(:failure_reason, :auth_method, :terminal) do
         # AuthFailure represents authentication failure
         # Returned by strategies when authentication fails
         # Contains failure reason for error messages
+        #
+        # TERMINAL FAILURES
+        # -----------------
+        # By default a failure is non-terminal: RouteAuthWrapper records it and
+        # consults the next strategy in the route's chain (OR logic), so a
+        # request without credentials can still fall through to an
+        # anonymous-capable strategy like noauth.
+        #
+        # A failure constructed with `terminal: true` means "this request
+        # explicitly presented credentials and they were examined and
+        # rejected — do not consult further strategies." RouteAuthWrapper
+        # halts the chain and renders the 401 with this failure's reason,
+        # regardless of where the strategy sits in the chain. This lets mixed
+        # credentialed/anonymous chains (e.g. auth=basicauth,noauth) fail
+        # closed on invalid credentials instead of silently degrading to
+        # anonymous.
+        #
+        # Only reject terminally when credentials were EXPLICITLY presented
+        # (e.g. an Authorization header). Ambient credentials such as session
+        # cookies should fail non-terminally so a logged-out browser can still
+        # degrade to anonymous on noauth-capable routes.
+
+        # terminal defaults to false so existing keyword construction
+        # (failure_reason:, auth_method:) is unaffected.
+        def initialize(failure_reason:, auth_method:, terminal: false)
+          super
+        end
+
+        # Check if this failure halts the strategy chain
+        #
+        # @return [Boolean] True when the chain must fail closed
+        def terminal?
+          terminal
+        end
 
         # Check if authenticated - always false for failures
         #
@@ -36,7 +70,7 @@ class Otto
         #
         # @return [String] Debug representation
         def inspect
-          "#<AuthFailure reason=#{failure_reason.inspect} method=#{auth_method}>"
+          "#<AuthFailure reason=#{failure_reason.inspect} method=#{auth_method}#{' terminal' if terminal}>"
         end
       end
     end

data/lib/otto/security/authentication/auth_strategy.rb

@@ -42,11 +42,21 @@ class Otto
         # Use for a missing, invalid, or expired credential. RouteAuthWrapper maps
         # this to 401 Unauthorized. For a VALID credential that is not permitted,
         # use #authorization_failure instead (403 Forbidden).
-        def failure(reason = nil)
+        #
+        # Pass terminal: true when the request EXPLICITLY presented credentials
+        # (e.g. an Authorization header) that were examined and rejected.
+        # RouteAuthWrapper then halts the strategy chain and fails closed with
+        # 401 instead of consulting further strategies — so an anonymous-capable
+        # strategy later (or earlier) in the chain cannot silently accept the
+        # request as anonymous. Leave it false for missing credentials and for
+        # ambient credentials (session cookies), which should keep today's OR
+        # fallthrough. See AuthFailure.
+        def failure(reason = nil, terminal: false)
           Otto.logger.debug "[#{self.class}] Authentication failed: #{reason}" if reason
           Otto::Security::Authentication::AuthFailure.new(
             failure_reason: reason || 'Authentication failed',
-            auth_method: strategy_auth_method
+            auth_method: strategy_auth_method,
+            terminal: terminal
           )
         end
 

data/lib/otto/security/authentication/authorization_failure.rb

@@ -26,6 +26,13 @@ class Otto
       # StrategyResult. This type covers the complementary case: a strategy that
       # owns authorization itself (including permission tiers, which Layer-1 does
       # not model) and needs to signal a 403 directly.
+      #
+      # DELIBERATELY has no `terminal` member (unlike AuthFailure): an
+      # authorization denial must not halt the strategy chain — a later
+      # strategy's success still wins (a different credential may well be
+      # permitted). When the chain DOES end in failure, a recorded denial
+      # already takes response precedence (403 over 401, even over a terminal
+      # halt), so there is nothing a terminal flag here would add.
       AuthorizationFailure = Data.define(:failure_reason, :auth_method) do
         # Authorization failures are not an authenticated request state. The
         # request never reaches the handler, so handler-facing predicates report

data/lib/otto/security/authentication/route_auth_wrapper.rb

@@ -12,9 +12,26 @@ class Otto
       # This is the main orchestrator that:
       # - Sets anonymous StrategyResult for unauthenticated routes
       # - Enforces authentication for protected routes
-      # - Supports multi-strategy with OR logic (first success wins)
+      # - Supports multi-strategy with OR logic (first authenticated success wins)
       # - Performs Layer 1 (route-level) role authorization
       #
+      # Multi-strategy chain semantics (in precedence order):
+      # - AUTHENTICATED success wins immediately; later strategies never run.
+      # - TERMINAL failure (AuthFailure with terminal: true — explicit
+      #   credentials examined and rejected) halts the chain and fails closed,
+      #   regardless of strategy order. An anonymous success from an
+      #   anonymous-capable strategy elsewhere in the chain does not rescue the
+      #   request. See AuthFailure.
+      # - ANONYMOUS success (StrategyResult with no user, e.g. from noauth) is
+      #   held as a fallback while the rest of the chain runs. It wins once the
+      #   chain completes without an authenticated success or terminal failure,
+      #   so credential-less requests still fall through to noauth. When more
+      #   than one strategy produces an anonymous success, the first declared
+      #   is the fallback; later ones are deliberately ignored.
+      # - Plain failures are recorded and the next strategy is consulted
+      #   (OR logic). If everything fails, an AuthorizationFailure (valid
+      #   credential, denied) yields 403; otherwise 401.
+      #
       # @example Basic usage
       #   wrapper = RouteAuthWrapper.new(handler, route_def, auth_config)
       #   response = wrapper.call(env)
@@ -53,7 +70,8 @@ class Otto
           validation_error = validate_strategies(auth_requirements, env)
           return validation_error if validation_error
 
-          # Try each strategy in order (first success wins)
+          # Try each strategy in order (first authenticated success wins;
+          # anonymous success is a fallback; terminal failure halts the chain)
           authenticate_and_authorize(env, extra_params, auth_requirements)
         end
 
@@ -83,8 +101,15 @@ class Otto
         end
 
         # Main authentication and authorization flow
+        #
+        # chain tracks two views of the run: :executed is every strategy that
+        # ran (including one whose anonymous success is merely held as the
+        # fallback), :failed only those that returned a failure result. Failure
+        # metadata reports :executed as attempted_strategies so a terminal halt
+        # after a deferred anonymous success doesn't under-report what ran.
         def authenticate_and_authorize(env, extra_params, auth_requirements)
-          failed_strategies = []
+          chain = { failed: [], executed: [] }
+          anonymous_fallback = nil
           total_start_time = Otto::Utils.now_in_μs
 
           auth_requirements.each do |requirement|
@@ -96,39 +121,90 @@ class Otto
             start_time = Otto::Utils.now_in_μs
             result = strategy.authenticate(env, requirement)
             duration = Otto::Utils.now_in_μs - start_time
+            chain[:executed] << strategy_name
 
             # Inject strategy_name into result
             result = result.with(strategy_name: strategy_name) if result.is_a?(StrategyResult)
 
-            # Handle authentication success
-            if result.is_a?(StrategyResult) && (result.authenticated? || result.anonymous?)
+            # Handle authenticated success - wins immediately
+            if authenticated_result?(result)
               return handle_auth_success(env, extra_params, result, strategy_name,
-                                        duration, total_start_time, failed_strategies)
+                                        duration, total_start_time, chain)
+            end
+
+            # An anonymous success (e.g. noauth) is held as a fallback rather
+            # than winning outright, so a credentialed strategy elsewhere in
+            # the chain still gets to examine explicitly presented credentials
+            # and reject them terminally, regardless of declaration order.
+            # When the chain completes without a terminal failure, the
+            # fallback wins (see below), preserving OR fallthrough for
+            # credential-less requests.
+            if anonymous_result?(result)
+              anonymous_fallback ||= { result: result, strategy_name: strategy_name, duration: duration }
+              next
             end
 
             # Handle a failure (authentication OR authorization) - record it and
             # continue to the next strategy (OR logic; a later success still wins).
             # AuthorizationFailure (valid credential, denied) is tagged so the
             # final response is 403 instead of 401. See handle_all_strategies_failed.
-            next unless result.is_a?(AuthFailure) || result.is_a?(AuthorizationFailure)
+            # Anything else is a strategy-author bug (wrong return type): the
+            # chain skips it as if it failed without a reason, but leaves a
+            # trace — a silent drop makes those bugs hard to debug.
+            unless result.is_a?(AuthFailure) || result.is_a?(AuthorizationFailure)
+              log_unexpected_result(env, strategy_name, result)
+              next
+            end
 
             log_strategy_failure(env, strategy_name, result, duration, auth_requirements, requirement)
-            failed_strategies << {
-              strategy: strategy_name,
-              reason: result.failure_reason,
-              authorization: result.is_a?(AuthorizationFailure),
-            }
+
+            # A terminal failure means explicit credentials were examined and
+            # rejected: fail the whole chain closed (401) instead of letting an
+            # anonymous-capable strategy accept the request as anonymous.
+            if record_failure(chain[:failed], strategy_name, result)
+              return handle_all_strategies_failed(env, auth_requirements, chain,
+                                                  total_start_time, terminal: true)
+            end
+          end
+
+          # Chain completed without authenticated success or terminal failure:
+          # a held anonymous success wins (OR fallthrough to noauth et al.)
+          if anonymous_fallback
+            return handle_auth_success(env, extra_params, anonymous_fallback[:result],
+                                       anonymous_fallback[:strategy_name],
+                                       anonymous_fallback[:duration],
+                                       total_start_time, chain)
           end
 
           # All strategies failed
-          handle_all_strategies_failed(env, auth_requirements, failed_strategies, total_start_time)
+          handle_all_strategies_failed(env, auth_requirements, chain, total_start_time)
+        end
+
+        def authenticated_result?(result)
+          result.is_a?(StrategyResult) && result.authenticated?
+        end
+
+        def anonymous_result?(result)
+          result.is_a?(StrategyResult) && result.anonymous?
+        end
+
+        # Append the failure to the running list; returns true when it was terminal
+        def record_failure(failed_strategies, strategy_name, result)
+          terminal = result.is_a?(AuthFailure) && result.terminal?
+          failed_strategies << {
+            strategy: strategy_name,
+            reason: result.failure_reason,
+            authorization: result.is_a?(AuthorizationFailure),
+            terminal: terminal,
+          }
+          terminal
         end
 
         # Handle successful authentication
-        def handle_auth_success(env, extra_params, result, strategy_name, duration, total_start_time, failed_strategies)
+        def handle_auth_success(env, extra_params, result, strategy_name, duration, total_start_time, chain)
           total_duration = Otto::Utils.now_in_μs - total_start_time
 
-          log_auth_success(env, strategy_name, result, duration, total_duration, failed_strategies)
+          log_auth_success(env, strategy_name, result, duration, total_duration, chain)
 
           # Set environment variables for controllers/logic
           env['otto.strategy_result'] = result
@@ -148,14 +224,19 @@ class Otto
           wrapped_handler.call(env, extra_params)
         end
 
-        # Handle case when all authentication strategies fail
-        def handle_all_strategies_failed(env, auth_requirements, failed_strategies, total_start_time)
+        # Handle case when authentication fails for the whole chain — either
+        # every strategy failed, or a terminal failure halted the chain early
+        # (terminal: true; remaining strategies were deliberately not consulted).
+        # chain is the { failed:, executed: } state built by
+        # authenticate_and_authorize.
+        def handle_all_strategies_failed(env, auth_requirements, chain, total_start_time, terminal: false)
+          failed_strategies = chain[:failed]
           total_duration = Otto::Utils.now_in_μs - total_start_time
 
-          log_all_failed(env, failed_strategies, total_duration)
+          log_all_failed(env, chain, total_duration, terminal: terminal)
 
           # Create anonymous result with failure info
-          metadata = build_failure_metadata(env, failed_strategies)
+          metadata = build_failure_metadata(env, chain, terminal: terminal)
           failure_strategy_name = determine_failure_strategy_name(auth_requirements, failed_strategies)
 
           env['otto.strategy_result'] = StrategyResult.anonymous(
@@ -167,14 +248,18 @@ class Otto
           # authenticated the subject but denied authorization (wrong role/missing
           # permission), respond 403 Forbidden rather than 401 — the subject IS
           # authenticated, they simply lack access. A bare 401 would (incorrectly)
-          # tell a logged-in client to re-authenticate.
+          # tell a logged-in client to re-authenticate. This precedence also holds
+          # on a terminal halt: the denial's 403 is the more specific outcome.
           authz_denial = failed_strategies.find { |f| f[:authorization] }
           return @response_builder.forbidden(env, authz_denial[:reason]) if authz_denial
 
+          # On a terminal halt the terminal failure is necessarily the last one
+          # recorded, so its reason is what gets rendered.
           last_failure = if failed_strategies.any?
                            AuthFailure.new(
                              failure_reason: failed_strategies.last[:reason],
-                             auth_method: failed_strategies.last[:strategy]
+                             auth_method: failed_strategies.last[:strategy],
+                             terminal: failed_strategies.last[:terminal] || false
                            )
                          else
                            AuthFailure.new(
@@ -194,13 +279,21 @@ class Otto
         end
 
         # Build metadata for failed authentication
-        def build_failure_metadata(env, failed_strategies)
+        #
+        # attempted_strategies lists every strategy that EXECUTED (including
+        # one whose anonymous success was held as the fallback and then
+        # overruled by a terminal failure); failure_reasons lists only the
+        # reasons of strategies that FAILED, in failure order. The two arrays
+        # are therefore not index-aligned.
+        def build_failure_metadata(env, chain, terminal: false)
+          summary = terminal ? 'Authentication halted by terminal failure' : 'All authentication strategies failed'
           metadata = {
                           ip: env['otto.client_ip'] || env['REMOTE_ADDR'],
-                auth_failure: 'All authentication strategies failed',
-            attempted_strategies: failed_strategies.map { |f| f[:strategy] },
-                 failure_reasons: failed_strategies.map { |f| f[:reason] },
+                auth_failure: summary,
+            attempted_strategies: chain[:executed],
+                 failure_reasons: chain[:failed].map { |f| f[:reason] },
           }
+          metadata[:terminal_failure] = true if terminal
           metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
           metadata
         end
@@ -228,7 +321,7 @@ class Otto
             ))
         end
 
-        def log_auth_success(env, strategy_name, result, duration, total_duration, failed_strategies)
+        def log_auth_success(env, strategy_name, result, duration, total_duration, chain)
           Otto.structured_log(:info, 'Auth strategy result',
             Otto::LoggingHelpers.request_context(env).merge(
               strategy: strategy_name,
@@ -236,7 +329,11 @@ class Otto
               user_id: result.user_id,
               duration: duration,
               total_duration: total_duration,
-              strategies_attempted: failed_strategies.size + 1
+              # Every strategy that ran, including the winner (already in
+              # chain[:executed] by the time a success is handled) and any
+              # held anonymous fallback — not just the failures. Same array
+              # shape as the failure log so consumers see one type.
+              strategies_attempted: chain[:executed]
             ))
         end
 
@@ -251,12 +348,22 @@ class Otto
             ))
         end
 
-        def log_all_failed(env, failed_strategies, total_duration)
-          Otto.structured_log(:warn, 'All auth strategies failed',
+        def log_unexpected_result(env, strategy_name, result)
+          Otto.structured_log(:warn, 'Auth strategy returned unexpected type',
+            Otto::LoggingHelpers.request_context(env).merge(
+              strategy: strategy_name,
+              result_class: result.class.name
+            ))
+        end
+
+        def log_all_failed(env, chain, total_duration, terminal: false)
+          message = terminal ? 'Auth chain halted by terminal failure' : 'All auth strategies failed'
+          Otto.structured_log(:warn, message,
             Otto::LoggingHelpers.request_context(env).merge(
-              strategies_attempted: failed_strategies.map { |f| f[:strategy] },
+              strategies_attempted: chain[:executed],
               total_duration: total_duration,
-              failure_count: failed_strategies.size
+              failure_count: chain[:failed].size,
+              terminal: terminal
             ))
         end
       end

data/lib/otto/security/config.rb

@@ -38,6 +38,23 @@ class Otto
         hop count, not both.
       MSG
 
+      # Error raised when an app-configured trusted geo header (ip_privacy
+      # geo_header) is combined with count-based depth mode. Geo headers are
+      # honored only for peers matching enumerated trusted_proxies CIDRs
+      # (geo_headers_trusted? gates on trusted_proxies_configured?) — a hop
+      # trusted by count cannot be verified as the geo-setting CDN — so a
+      # geo_header configured alongside a depth could never be consulted.
+      # Failing loud at config time replaces a silent database/'**' fallback
+      # at request time.
+      GEO_HEADER_DEPTH_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        Cannot configure a trusted geo header (ip_privacy geo_header) together
+        with trusted_proxy_depth (count mode): geo headers are only honored
+        for peers matching enumerated trusted_proxies CIDRs, so the header
+        would be silently ignored. Use filter mode (add_trusted_proxy) for
+        header-based geo, or drop geo_header and use database-backed geo
+        (geo_db_path or geo_db_reader).
+      MSG
+
       # Forwarded-header sources depth mode (#trusted_proxy_depth) can count
       # hops from: X-Forwarded-For (default), the RFC 7239 Forwarded header, or
       # Both (Forwarded when present, else X-Forwarded-For). Mirrors
@@ -217,6 +234,32 @@ class Otto
         end
       end
 
+      # Whether any trusted-proxy IP/CIDR/Regexp matchers are configured.
+      #
+      # This mirrors {#trusted_proxy?}, which consults the same matcher list.
+      # It deliberately EXCLUDES count-based depth mode: depth grants the peer
+      # blanket trust for otto.via_trusted_proxy (#226), but it cannot verify
+      # that the hop is a geo-setting CDN, so header-based geo stays gated on
+      # enumerated matchers only. Used to gate geo-header trust.
+      #
+      # @return [Boolean] true when at least one trusted-proxy matcher exists
+      def trusted_proxies_configured?
+        @trusted_proxy_matchers.any?
+      end
+
+      # Whether ANY proxy-trust mode is configured — CIDR matchers (filter
+      # mode) or count-based depth. This is the gate for writing
+      # env['otto.via_trusted_proxy'] at all: when neither mode is configured
+      # the key is left ABSENT (tri-state contract), so downstream consumers
+      # can distinguish "operator configured trust and this peer failed it"
+      # (false) from "no proxy trust configured" (absent) and apply their own
+      # legacy heuristics only in the latter case.
+      #
+      # @return [Boolean] true when filter or depth mode is configured
+      def proxy_trust_configured?
+        trusted_proxies_configured? || trusted_proxy_depth_mode?
+      end
+
       # Whether count-based ("trust the last N hops") proxy resolution is active.
       #
       # When true, Otto::Utils.resolve_client_ip ignores trusted-proxy CIDRs and
@@ -246,6 +289,9 @@ class Otto
 
         validate_trusted_proxy_depth!(depth)
         raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if depth.to_i >= 1 && @trusted_proxies.any?
+        # Depth-then-geo assignment order is caught by configure_ip_privacy;
+        # this catches geo-then-depth so both orders fail eagerly.
+        raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE if depth.to_i >= 1 && @ip_privacy_config&.geo_header
 
         @trusted_proxy_depth = depth
       end
@@ -749,6 +795,12 @@ class Otto
         return if @trusted_proxy_depth.nil?
 
         raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if @trusted_proxy_depth >= 1 && @trusted_proxies.any?
+
+        # Backstop for the direct path (ip_privacy_config.geo_header=) that
+        # bypasses both eager checks; the setters cover the common orders.
+        return unless @trusted_proxy_depth >= 1 && @ip_privacy_config&.geo_header
+
+        raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE
       end
 
       # Parse a value into an IPAddr, returning nil for invalid / non-IP input.
@@ -768,12 +820,20 @@ class Otto
       # trusted_proxy? never re-parses. Non-IP strings and Regexp/other entries
       # store a nil range and fall back to prefix/regexp matching.
       #
+      # The parsed range is folded through IPAddr#native at registration, to
+      # match the fold trusted_proxy? applies to the client address. Without
+      # it a mapped-IPv6 proxy entry (::ffff:10.0.0.0/104) could never match,
+      # because ip_in_range?'s family check would reject the folded IPv4
+      # client — a proxy silently untrusted, which is what gates
+      # otto.via_trusted_proxy, secure?, and geo-header trust. #native returns
+      # self for entries that are not IPv4-mapped/compatible.
+      #
       # @param entry [String, Regexp, Object] trusted proxy entry being added
       # @return [Array(Object, IPAddr)] [raw_entry, parsed_range_or_nil]
       def register_proxy_matcher(entry)
         return [entry, nil] unless entry.is_a?(String)
 
-        range = parse_ipaddr(entry)
+        range = parse_ipaddr(entry)&.native
         warn_legacy_proxy_entry(entry) unless range
         [entry, range]
       end

data/lib/otto/security/core.rb

@@ -181,7 +181,10 @@ class Otto
       # The middleware is pinned to run OUTERMOST (ahead of CSRF and every other
       # middleware), so it short-circuits report POSTs before CSRF validation —
       # browsers can post reports without a CSRF token. This holds regardless of
-      # the order in which you enable security features.
+      # the order in which you enable security features. The one thing that runs
+      # ahead of it is IPPrivacyMiddleware, pinned to the outer :entrypoint tier
+      # so nothing observes a raw client IP; being a pass-through, it cannot
+      # affect the short-circuit.
       #
       # SECURITY / DoS: running outermost also means the receiver sits ahead of
       # rate limiting (rate limiting is inner middleware). This is intentional —

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

@@ -27,7 +27,9 @@ class Otto
       #   with no CSRF token: the report never reaches the CSRF middleware.
       #   {Otto::Security::Core#enable_csp_reporting!} pins this middleware
       #   OUTERMOST (via the :outermost stack position), so the guarantee holds
-      #   regardless of the order security features are enabled in. The flip side
+      #   regardless of the order security features are enabled in. Only
+      #   IPPrivacyMiddleware (pinned to the outer :entrypoint tier) runs ahead
+      #   of it, and it is a pass-through. The flip side
       #   is that reports also bypass rate limiting — see the DoS note on
       #   {Otto::Security::Core#enable_csp_reporting!}; keep callbacks cheap.
       # - Enforces a hard {MAX_BODY_BYTES} body cap. Oversized bodies are