otto 2.0.0.pre7 → 2.0.0.pre8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69a46d80f1fcc3f2472c44554fd7102645226e264befdd23af9871ad4f5fafaf
-  data.tar.gz: 54d8b433d49b549e17d3406aa011b6f4f80c50eefc5a6fa51dde1772fde8b8f2
+  metadata.gz: b094c2fc179b84631bf53b1e4b7f3cbcd661f83e1f8a88ab6c1f22d3e8b11cbd
+  data.tar.gz: 70a7588c86b8b3f31968b577a298f05c09cad5ef5d9fcf028f0feece2963e8fb
 SHA512:
-  metadata.gz: b518140043ad7ab983fb99e85ac9643ca4527385930d77a4b01e2b241b7212854fbc5e8875bc58b17e3d17c66fcfc6455b85587d023ceec13006876bec79a0d9
-  data.tar.gz: f64b842b58acc746ad39d58eac0fb57c245f1db29755f89d259d64bd127db3043034a9e8ada0ee19c04d969ec1bb34b515f5dfc1fcf36c80ceaeb9123ac2de6e
+  metadata.gz: c9e8f2f46cf51bc0799dd6030e52a48c1665b9978efb8bc686977be722e61b3c553f17db91d9fd795447b5b4882ac95af404a71e14f9b65d3935a992ecb768f1
+  data.tar.gz: d0c6f98edf2f468297dcb19bb9743b1a2858f2497cf40d2fc4332550a883542f2b7e1a1de8ac4b9f9d352b40c53e974d6c99aecee2679abc6b38868c02ae5bd6

data/.github/workflows/code-smells.yml

@@ -27,15 +27,12 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: 3.4
-          bundler-cache: true
 
-      - name: Configure Bundler for secure gem installation
+      - name: Install dependencies with optional groups
         run: |
           bundle config set --local path 'vendor/bundle'
-          bundle config set --local deployment 'false'
-
-      - name: Install dependencies
-        run: bundle install --jobs 4 --retry 3
+          bundle config set --local with 'development test'
+          bundle install --jobs 4 --retry 3
 
       - name: Run Reek analysis
         run: |

data/CHANGELOG.rst

@@ -7,10 +7,76 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre8:
+
+2.0.0.pre8 — 2025-11-27
+=======================
+
+Fixed
+-----
+
+- Routes declaring ``response=json`` now return 401 JSON errors instead of 302 redirects when authentication fails, regardless of Accept header. The route's explicit configuration takes precedence over content negotiation.
+
+.. _changelog-2.0.0.pre7:
+
+2.0.0.pre7 — 2025-11-24
+=======================
+
+Added
+-----
+
+- Error handler registration system for expected business logic errors. Register handlers with ``otto.register_error_handler(ErrorClass, status: 404, log_level: :info)`` to return proper HTTP status codes and avoid logging expected errors as 500s with backtraces. Supports custom response handlers via blocks for complete control over error responses.
+
+Changed
+-------
+
+- Backtrace logging now always logs at ERROR level (was DEBUG) with sanitized file paths for security. Backtraces for unhandled 500 errors are always logged regardless of ``OTTO_DEBUG`` setting, with paths sanitized to prevent exposing system information (project files show relative paths, gems show ``[GEM] name-version/path``, Ruby stdlib shows ``[RUBY] filename``).
+- Increased backtrace limit from 10 to 20 lines for critical errors to provide better debugging context.
+
+AI Assistance
+-------------
+
+- Implemented error handler registration architecture with comprehensive test coverage (17 test cases) using sequential thinking to work through security implications and design decisions. AI assisted with path sanitization strategy, error classification patterns, and ensuring backward compatibility with existing error handling.
+
+Improved backtrace sanitization security and readability
+--------------------------------------------------------
+
+**Security Enhancements:**
+
+- Fixed bundler gem path detection to correctly sanitize git-based gems
+- Now properly handles nested gem paths like ``/gems/3.4.0/bundler/gems/otto-abc123/``
+- Strips git hash suffixes from bundler gems (``otto-abc123def456`` → ``otto``)
+- Removes version numbers from regular gems (``rack-3.2.4`` → ``rack``)
+- Prevents exposure of absolute paths, usernames, and project names in logs
+
+**Improvements:**
+
+- Bundler gems now show as ``[GEM] otto/lib/otto/route.rb:142`` instead of ``[GEM] 3.4.0/bundler/gems/...``
+- Regular gems show cleaner output: ``[GEM] rack/lib/rack.rb:20`` instead of ``[GEM] rack-3.2.4/lib/rack.rb:20``
+- Multi-hyphenated gem names handled correctly (``active-record-import-1.5.0`` → ``active-record-import``)
+- Better handling of version-only directory names in gem paths
+
+**Documentation:**
+
+- Added comprehensive backtrace sanitization section to CLAUDE.md
+- Documented security guarantees and sanitization rules
+- Added examples showing before/after path transformations
+- Created comprehensive test suite for backtrace sanitization
+
+**Rationale:**
+
+Raw backtraces expose sensitive information:
+- Usernames (``/Users/alice/``, ``/home/admin/``)
+- Project structure and internal organization
+- Gem installation paths and Ruby versions
+- System architecture details
+
+This improvement ensures all backtraces are sanitized automatically, preventing accidental leakage of sensitive system information while maintaining readability for debugging.
+
 .. _changelog-2.0.0.pre6:
 
-2.0.0.pre6 — TBD
-================
+2.0.0.pre6
+==========
 
 Changed
 -------

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.0.0.pre7)
+    otto (2.0.0.pre8)
       concurrent-ruby (~> 1.3, < 2.0)
       facets (~> 3.1)
       ipaddr (~> 1, < 2.0)

data/lib/otto/route_handlers/class_method.rb

@@ -10,7 +10,14 @@ require_relative 'base'
 class Otto
   module RouteHandlers
     # Handler for class methods (existing Otto pattern)
-    # Maintains backward compatibility for Controller.action patterns
+    # Route syntax: Controller.action
+    #
+    # Class methods receive full Rack request/response access:
+    # - Method signature: def self.action(request, response)
+    # - Direct access to sessions, cookies, headers, and the raw env
+    #
+    # Use this handler for endpoints requiring request-level control (logout,
+    # session management, cookie manipulation, custom header handling).
     class ClassMethodHandler < BaseHandler
       def call(env, extra_params = {})
         start_time = Otto::Utils.now_in_μs

data/lib/otto/route_handlers/instance_method.rb

@@ -8,7 +8,14 @@ require_relative 'base'
 class Otto
   module RouteHandlers
     # Handler for instance methods (existing Otto pattern)
-    # Maintains backward compatibility for Controller#action patterns
+    # Route syntax: Controller#action
+    #
+    # Controller instances receive full Rack request/response access:
+    # - initialize(request, response) with Rack::Request and Rack::Response
+    # - Direct access to sessions, cookies, headers, and the raw env
+    #
+    # Use this handler for endpoints requiring request-level control (logout,
+    # session management, cookie manipulation, custom header handling).
     class InstanceMethodHandler < BaseHandler
       def call(env, extra_params = {})
         start_time = Otto::Utils.now_in_μs

data/lib/otto/route_handlers/logic_class.rb

@@ -9,8 +9,16 @@ require_relative 'base'
 class Otto
   module RouteHandlers
     # Handler for Logic classes (new in Otto Framework Enhancement)
-    # Handles Logic class routes with the modern RequestContext pattern
-    # Logic classes use signature: initialize(context, params, locale)
+    #
+    # Logic classes use a constrained signature: initialize(context, params, locale)
+    # - context: The authentication strategy result (user info, session data)
+    # - params: Merged request parameters (URL params + body + extra_params)
+    # - locale: The locale string from env['otto.locale']
+    #
+    # IMPORTANT: Logic classes do NOT receive the Rack request or env hash.
+    # This is intentional - Logic classes work with clean, authenticated contexts.
+    # For endpoints requiring direct request access (sessions, cookies, headers,
+    # or logout flows), use controller handlers (Controller#action or Controller.action).
     class LogicClassHandler < BaseHandler
       def call(env, extra_params = {})
         start_time = Otto::Utils.now_in_μs

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module Authentication
+      module RouteAuthWrapperComponents
+        # Builds HTTP error responses for authentication/authorization failures
+        #
+        # Handles content negotiation (JSON vs HTML) and applies security headers.
+        # Route's declared response_type takes precedence over Accept header.
+        #
+        # @example
+        #   builder = ResponseBuilder.new(route_definition, auth_config, security_config)
+        #   response = builder.unauthorized(env, "Invalid token")
+        #   response = builder.forbidden(env, "Admin role required")
+        #   response = builder.auth_failure(env, auth_failure_result)
+        #
+        class ResponseBuilder
+          # @param route_definition [RouteDefinition] Route with response_type info
+          # @param auth_config [Hash] Auth config with :login_path for HTML redirects
+          # @param security_config [SecurityConfig, nil] Optional security config for headers
+          def initialize(route_definition, auth_config, security_config = nil)
+            @route_definition = route_definition
+            @auth_config = auth_config
+            @security_config = security_config
+          end
+
+          # Generate response for authentication failure
+          #
+          # @param env [Hash] Rack environment
+          # @param result [AuthFailure] Failure result from strategy
+          # @return [Array] Rack response array
+          def auth_failure(env, result)
+            wants_json?(env) ? json_auth_error(result) : html_auth_error(result)
+          end
+
+          # Generate 401 Unauthorized response
+          #
+          # @param env [Hash] Rack environment
+          # @param message [String] Error message
+          # @return [Array] Rack response array
+          def unauthorized(env, message)
+            if wants_json?(env)
+              json_response(401, error: message)
+            else
+              text_response(401, message)
+            end
+          end
+
+          # Generate 403 Forbidden response
+          #
+          # @param env [Hash] Rack environment
+          # @param message [String] Error message
+          # @return [Array] Rack response array
+          def forbidden(env, message)
+            if wants_json?(env)
+              json_response(403, error: 'Forbidden', message: message)
+            else
+              text_response(403, message)
+            end
+          end
+
+          private
+
+          # Determine if response should be JSON based on route config and Accept header
+          #
+          # Route's declared response type takes precedence over Accept header.
+          # This ensures API routes (response=json) always get JSON errors.
+          #
+          # @param env [Hash] Rack environment
+          # @return [Boolean] true if response should be JSON
+          def wants_json?(env)
+            return true if @route_definition.response_type == 'json'
+
+            accept_header = env['HTTP_ACCEPT'] || ''
+            accept_header.include?('application/json')
+          end
+
+          # Generate JSON 401 response for auth failure
+          def json_auth_error(result)
+            json_response(401,
+              error: 'Authentication Required',
+              message: result.failure_reason || 'Not authenticated',
+              timestamp: Time.now.to_i)
+          end
+
+          # Generate HTML 401 response (redirect to login)
+          def html_auth_error(_result)
+            login_path = @auth_config[:login_path] || '/signin'
+            headers = { 'location' => login_path }
+            merge_security_headers!(headers)
+            [302, headers, ["Redirecting to #{login_path}"]]
+          end
+
+          # Build a JSON response with security headers
+          def json_response(status, body_hash)
+            body = body_hash.to_json
+            headers = {
+              'content-type' => 'application/json',
+              'content-length' => body.bytesize.to_s,
+            }
+            merge_security_headers!(headers)
+            [status, headers, [body]]
+          end
+
+          # Build a plain text response with security headers
+          def text_response(status, message)
+            headers = { 'content-type' => 'text/plain' }
+            merge_security_headers!(headers)
+            [status, headers, [message]]
+          end
+
+          # Merge security headers into response headers
+          def merge_security_headers!(headers)
+            return unless @security_config
+
+            headers.merge!(@security_config.security_headers)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module Authentication
+      module RouteAuthWrapperComponents
+        # Handles Layer 1 (route-level) role-based authorization
+        #
+        # Extracts user roles from authentication results and checks against
+        # route requirements using OR logic (user needs ANY of the required roles).
+        #
+        # @example
+        #   authorizer = RoleAuthorization.new(route_definition)
+        #   authorizer.check!(strategy_result, env)  # raises or returns true
+        #
+        # @note This is Layer 1 authorization only. Layer 2 (resource-level)
+        #   authorization should be handled in Logic classes via raise_concerns.
+        #
+        class RoleAuthorization
+          # @param route_definition [RouteDefinition] Route with role requirements
+          def initialize(route_definition)
+            @route_definition = route_definition
+          end
+
+          # Check if authentication result satisfies role requirements
+          #
+          # @param result [StrategyResult] Authentication result
+          # @param env [Hash] Rack environment (for logging)
+          # @return [true] if authorized
+          # @return [Hash] failure info if not authorized: { authorized: false, required: [...], actual: [...] }
+          def check(result, env)
+            role_requirements = @route_definition.role_requirements
+            return true if role_requirements.empty?
+
+            user_roles = extract_roles(result)
+
+            # OR logic: user needs ANY of the required roles
+            if (user_roles & role_requirements).any?
+              log_success(env, role_requirements, user_roles)
+              true
+            else
+              log_failure(env, role_requirements, user_roles, result)
+              {
+                authorized: false,
+                required: role_requirements,
+                actual: user_roles,
+              }
+            end
+          end
+
+          # Check authorization, returning boolean
+          #
+          # @param result [StrategyResult] Authentication result
+          # @return [Boolean] true if authorized
+          def authorized?(result)
+            role_requirements = @route_definition.role_requirements
+            return true if role_requirements.empty?
+
+            user_roles = extract_roles(result)
+            (user_roles & role_requirements).any?
+          end
+
+          # Get the role requirements for error messages
+          #
+          # @return [Array<String>] Required roles
+          def requirements
+            @route_definition.role_requirements
+          end
+
+          private
+
+          # Extract user roles from authentication result
+          #
+          # Supports multiple role sources in order of precedence:
+          # 1. result.user_roles (Array)
+          # 2. result.user[:roles] (Array)
+          # 3. result.user['roles'] (Array)
+          # 4. result.metadata[:user_roles] (Array)
+          #
+          # @param result [StrategyResult] Authentication result
+          # @return [Array<String>] Array of role strings
+          def extract_roles(result)
+            # Try direct user_roles accessor (e.g., from RoleStrategy)
+            return Array(result.user_roles) if result.respond_to?(:user_roles) && result.user_roles
+
+            # Try user hash/object with roles
+            if result.user
+              roles = result.user[:roles] || result.user['roles']
+              return Array(roles) if roles
+            end
+
+            # Try metadata
+            return Array(result.metadata[:user_roles]) if result.metadata && result.metadata[:user_roles]
+
+            # No roles found
+            []
+          end
+
+          def log_success(env, required_roles, user_roles)
+            Otto.structured_log(:debug, 'Role authorization succeeded',
+              Otto::LoggingHelpers.request_context(env).merge(
+                required_roles: required_roles,
+                user_roles: user_roles,
+                matched_roles: user_roles & required_roles
+              ))
+          end
+
+          def log_failure(env, required_roles, user_roles, result)
+            Otto.structured_log(:warn, 'Role authorization failed',
+              Otto::LoggingHelpers.request_context(env).merge(
+                required_roles: required_roles,
+                user_roles: user_roles,
+                user_id: result.user_id
+              ))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module Authentication
+      module RouteAuthWrapperComponents
+        # Resolves authentication strategy names to strategy instances
+        #
+        # Handles strategy lookup with caching and pattern matching:
+        # - Exact match: 'authenticated' → looks up auth_config[:auth_strategies]['authenticated']
+        # - Prefix match: 'custom:value' → looks up 'custom' strategy
+        #
+        # Results are cached to avoid repeated lookups for the same requirement.
+        #
+        # @example
+        #   resolver = StrategyResolver.new(auth_config)
+        #   strategy, name = resolver.resolve('session')
+        #   strategy, name = resolver.resolve('oauth:google')  # prefix match
+        #
+        class StrategyResolver
+          # @param auth_config [Hash] Auth configuration with :auth_strategies key
+          def initialize(auth_config)
+            @auth_config = auth_config
+            @cache = {}
+          end
+
+          # Resolve a requirement string to a strategy instance
+          #
+          # @param requirement [String] Auth requirement from route (e.g., 'session', 'oauth:google')
+          # @return [Array<AuthStrategy, String>, Array<nil, nil>] Tuple of [strategy, name] or [nil, nil]
+          def resolve(requirement)
+            return [nil, nil] unless @auth_config && @auth_config[:auth_strategies]
+
+            # Check cache first
+            return @cache[requirement] if @cache.key?(requirement)
+
+            result = find_strategy(requirement)
+            @cache[requirement] = result
+            result
+          end
+
+          # Clear the strategy cache
+          def clear_cache
+            @cache.clear
+          end
+
+          private
+
+          def find_strategy(requirement)
+            strategies = @auth_config[:auth_strategies]
+
+            # Try exact match first - highest priority
+            strategy = strategies[requirement]
+            return [strategy, requirement] if strategy
+
+            # For colon-separated requirements like "custom:value", try prefix match
+            if requirement.include?(':')
+              prefix = requirement.split(':', 2).first
+              prefix_strategy = strategies[prefix]
+              return [prefix_strategy, prefix] if prefix_strategy
+            end
+
+            [nil, nil]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,28 +1,27 @@
-# lib/otto/security/authentication/route_auth_wrapper.rb
-#
 # frozen_string_literal: true
 
+require_relative 'route_auth_wrapper/strategy_resolver'
+require_relative 'route_auth_wrapper/response_builder'
+require_relative 'route_auth_wrapper/role_authorization'
+
 class Otto
   module Security
     module Authentication
-      # Wraps route handlers to enforce authentication requirements
+      # Wraps route handlers with authentication and authorization
       #
-      # This wrapper executes authentication strategies AFTER routing but BEFORE
-      # route handler execution. This solves the architectural issue where
-      # middleware-based authentication runs before routing (so can't access route info).
+      # 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)
+      # - Performs Layer 1 (route-level) role authorization
       #
-      # Flow:
-      #   1. Route matched (route_definition available)
-      #   2. RouteAuthWrapper#call invoked
-      #   3. Execute auth strategy based on route's auth_requirement
-      #   4. Set env['otto.strategy_result']
-      #   5. If auth fails, return 401 or redirect
-      #   6. If auth succeeds, call wrapped handler
+      # @example Basic usage
+      #   wrapper = RouteAuthWrapper.new(handler, route_def, auth_config)
+      #   response = wrapper.call(env)
       #
-      # @example
-      #   handler = InstanceMethodHandler.new(route_def, otto)
-      #   wrapped = RouteAuthWrapper.new(handler, route_def, auth_config)
-      #   wrapped.call(env, extra_params)
+      # @see RouteAuthWrapper::StrategyResolver for strategy lookup
+      # @see RouteAuthWrapper::ResponseBuilder for error responses
+      # @see RouteAuthWrapper::RoleAuthorization for role checking
       #
       class RouteAuthWrapper
         attr_reader :wrapped_handler, :route_definition, :auth_config, :security_config
@@ -30,17 +29,17 @@ class Otto
         def initialize(wrapped_handler, route_definition, auth_config, security_config = nil)
           @wrapped_handler  = wrapped_handler
           @route_definition = route_definition
-          @auth_config      = auth_config  # Hash: { auth_strategies: {}, default_auth_strategy: 'publicly' }
+          @auth_config      = auth_config
           @security_config  = security_config
-          @strategy_cache   = {}  # Cache resolved strategies to avoid repeated lookups
+
+          # Initialize extracted components
+          @strategy_resolver = RouteAuthWrapperComponents::StrategyResolver.new(auth_config)
+          @response_builder  = RouteAuthWrapperComponents::ResponseBuilder.new(route_definition, auth_config, security_config)
+          @role_authorizer   = RouteAuthWrapperComponents::RoleAuthorization.new(route_definition)
         end
 
         # Execute authentication then call wrapped handler
         #
-        # For routes WITHOUT auth requirement: Sets anonymous StrategyResult
-        # For routes WITH auth requirement: Enforces authentication
-        # Supports multi-strategy with OR logic: auth=session,apikey,oauth
-        #
         # @param env [Hash] Rack environment
         # @param extra_params [Hash] Additional parameters
         # @return [Array] Rack response array
@@ -48,363 +47,202 @@ class Otto
           auth_requirements = route_definition.auth_requirements
 
           # Routes without auth requirement get anonymous StrategyResult
-          if auth_requirements.empty?
-            # Note: env['REMOTE_ADDR'] is masked by IPPrivacyMiddleware by default
-            metadata = { ip: env['REMOTE_ADDR'] }
-            metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
-
-            result = StrategyResult.anonymous(metadata: metadata, strategy_name: 'anonymous')
-            env['otto.strategy_result'] = result
-            return wrapped_handler.call(env, extra_params)
-          end
-
-          # Routes WITH auth requirements: Try each strategy in order (first success wins)
+          return handle_anonymous_route(env, extra_params) if auth_requirements.empty?
 
           # Validate all strategies exist before executing any (fail-fast)
+          validation_error = validate_strategies(auth_requirements, env)
+          return validation_error if validation_error
+
+          # Try each strategy in order (first success wins)
+          authenticate_and_authorize(env, extra_params, auth_requirements)
+        end
+
+        private
+
+        # Handle routes without authentication requirements
+        def handle_anonymous_route(env, extra_params)
+          metadata = build_anonymous_metadata(env)
+          result = StrategyResult.anonymous(metadata: metadata, strategy_name: 'anonymous')
+          env['otto.strategy_result'] = result
+          wrapped_handler.call(env, extra_params)
+        end
+
+        # Validate all strategies exist before executing
+        #
+        # @return [Array, nil] Error response if validation fails, nil otherwise
+        def validate_strategies(auth_requirements, env)
           auth_requirements.each do |requirement|
-            strategy, _strategy_name = get_strategy(requirement)
-            unless strategy
-              error_msg = "Authentication strategy not configured: '#{requirement}'"
-              Otto.logger.error "[RouteAuthWrapper] #{error_msg}"
-              return unauthorized_response(env, error_msg)
-            end
+            strategy, _name = @strategy_resolver.resolve(requirement)
+            next if strategy
+
+            error_msg = "Authentication strategy not configured: '#{requirement}'"
+            Otto.logger.error "[RouteAuthWrapper] #{error_msg}"
+            return @response_builder.unauthorized(env, error_msg)
           end
+          nil
+        end
 
-          last_failure = nil
+        # Main authentication and authorization flow
+        def authenticate_and_authorize(env, extra_params, auth_requirements)
           failed_strategies = []
           total_start_time = Otto::Utils.now_in_μs
 
           auth_requirements.each do |requirement|
-            strategy, strategy_name = get_strategy(requirement)
-
-            # Log strategy execution start
-            Otto.structured_log(:debug, "Auth strategy executing",
-              Otto::LoggingHelpers.request_context(env).merge(
-                strategy: strategy_name,
-                requirement: requirement,
-                strategy_position: auth_requirements.index(requirement) + 1,
-                total_strategies: auth_requirements.size
-              )
-            )
+            strategy, strategy_name = @strategy_resolver.resolve(requirement)
+
+            log_strategy_start(env, strategy_name, requirement, auth_requirements)
 
             # Execute the strategy
             start_time = Otto::Utils.now_in_μs
             result = strategy.authenticate(env, requirement)
             duration = Otto::Utils.now_in_μs - start_time
 
-            # Inject strategy_name into result (Data.define objects are immutable, use #with for updates)
-            if result.is_a?(StrategyResult)
-              result = result.with(strategy_name: strategy_name)
-            end
+            # Inject strategy_name into result
+            result = result.with(strategy_name: strategy_name) if result.is_a?(StrategyResult)
 
-            # Handle authentication success (both authenticated and anonymous results) - return immediately
+            # Handle authentication success
             if result.is_a?(StrategyResult) && (result.authenticated? || result.anonymous?)
-              total_duration = Otto::Utils.now_in_μs - total_start_time
-
-              # Log authentication success
-              Otto.structured_log(:info, "Auth strategy result",
-                Otto::LoggingHelpers.request_context(env).merge(
-                  strategy: strategy_name,
-                  success: true,
-                  user_id: result.user_id,
-                  duration: duration,
-                  total_duration: total_duration,
-                  strategies_attempted: failed_strategies.size + 1
-                )
-              )
-
-              # Set environment variables for controllers/logic on success
-              env['otto.strategy_result'] = result
-
-              # SESSION PERSISTENCE: This assignment is INTENTIONAL, not a merge operation.
-              # We must ensure env['rack.session'] and strategy_result.session reference
-              # the SAME object so that:
-              #   1. Logic classes write to strategy_result.session
-              #   2. Rack's session middleware persists env['rack.session']
-              #   3. Changes from (1) are included in (2)
-              #
-              # Using merge! instead would break this - the objects must be identical.
-              env['rack.session'] = result.session if result.is_a?(StrategyResult) && result.session
-
-              # Layer 1 Authorization: Check role requirements (route-level)
-              role_requirements = route_definition.role_requirements
-              unless role_requirements.empty?
-                user_roles = extract_user_roles(result)
-
-                # OR logic: user needs ANY of the required roles
-                unless (user_roles & role_requirements).any?
-                  Otto.structured_log(:warn, "Role authorization failed",
-                    Otto::LoggingHelpers.request_context(env).merge(
-                      required_roles: role_requirements,
-                      user_roles: user_roles,
-                      user_id: result.user_id
-                    )
-                  )
-
-                  return forbidden_response(env,
-                    "Access denied: requires one of roles: #{role_requirements.join(', ')}")
-                end
-
-                Otto.structured_log(:debug, "Role authorization succeeded",
-                  Otto::LoggingHelpers.request_context(env).merge(
-                    required_roles: role_requirements,
-                    user_roles: user_roles,
-                    matched_roles: user_roles & role_requirements
-                  )
-                )
-              end
-
-              # Authentication and authorization succeeded - call wrapped handler
-              return wrapped_handler.call(env, extra_params)
+              return handle_auth_success(env, extra_params, result, strategy_name,
+                                        duration, total_start_time, failed_strategies)
             end
 
             # Handle authentication failure - continue to next strategy
-            if result.is_a?(AuthFailure)
-              # Log authentication failure
-              Otto.structured_log(:info, "Auth strategy result",
-                Otto::LoggingHelpers.request_context(env).merge(
-                  strategy: strategy_name,
-                  success: false,
-                  failure_reason: result.failure_reason,
-                  duration: duration,
-                  remaining_strategies: auth_requirements.size - auth_requirements.index(requirement) - 1
-                )
-              )
-
-              failed_strategies << { strategy: strategy_name, reason: result.failure_reason }
-              last_failure = result
-            end
-          end
-
-          # All strategies failed - return 401
-          total_duration = Otto::Utils.now_in_μs - total_start_time
-
-          # Log comprehensive failure
-          Otto.structured_log(:warn, "All auth strategies failed",
-            Otto::LoggingHelpers.request_context(env).merge(
-              strategies_attempted: failed_strategies.map { |f| f[:strategy] },
-              total_duration: total_duration,
-              failure_count: failed_strategies.size
-            )
-          )
-
-          # Create anonymous result with comprehensive failure info
-          # Note: env['REMOTE_ADDR'] is masked by IPPrivacyMiddleware by default
-          metadata = {
-            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] }
-          }
-          metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
+            next unless result.is_a?(AuthFailure)
 
-          # Use 'multi-strategy-failure' only for actual multi-strategy failures
-          # For single-strategy failures, use the actual strategy name
-          failure_strategy_name = if auth_requirements.size > 1
-            'multi-strategy-failure'
-          elsif failed_strategies.any?
-            failed_strategies.first[:strategy]
-          else
-            auth_requirements.first
+            log_strategy_failure(env, strategy_name, result, duration, auth_requirements, requirement)
+            failed_strategies << { strategy: strategy_name, reason: result.failure_reason }
           end
 
-          env['otto.strategy_result'] = StrategyResult.anonymous(
-            metadata: metadata,
-            strategy_name: failure_strategy_name
-          )
-
-          auth_failure_response(env, last_failure || AuthFailure.new(
-            failure_reason: "Authentication required",
-            auth_method: failure_strategy_name
-          ))
+          # All strategies failed
+          handle_all_strategies_failed(env, auth_requirements, failed_strategies, total_start_time)
         end
 
-        private
+        # Handle successful authentication
+        def handle_auth_success(env, extra_params, result, strategy_name, duration, total_start_time, failed_strategies)
+          total_duration = Otto::Utils.now_in_μs - total_start_time
 
-        # Get strategy from auth_config hash with pattern matching
-        #
-        # Supports:
-        # - Exact match: 'authenticated' → looks up auth_config[:auth_strategies]['authenticated']
-        # - Prefix match: 'custom:value' → looks up 'custom' strategy
-        #
-        # Results are cached to avoid repeated lookups for the same requirement.
-        #
-        # NOTE: Role-based authorization should use route option `role=admin` instead of `auth=role:admin`
-        # to properly separate authentication from authorization concerns.
-        #
-        # @param requirement [String] Auth requirement from route
-        # @return [Array<AuthStrategy, String>, Array<nil, nil>] Tuple of [strategy, name] or [nil, nil]
-        def get_strategy(requirement)
-          return [nil, nil] unless auth_config && auth_config[:auth_strategies]
-
-          # Check cache first (cache stores [strategy, name] tuples)
-          return @strategy_cache[requirement] if @strategy_cache.key?(requirement)
-
-          # Try exact match first - this has highest priority
-          strategy = auth_config[:auth_strategies][requirement]
-          if strategy
-            result = [strategy, requirement]
-            @strategy_cache[requirement] = result
-            return result
-          end
+          log_auth_success(env, strategy_name, result, duration, total_duration, failed_strategies)
 
-          # For colon-separated requirements like "custom:value", try prefix match
-          if requirement.include?(':')
-            prefix = requirement.split(':', 2).first
+          # Set environment variables for controllers/logic
+          env['otto.strategy_result'] = result
 
-            # Check if we have a strategy registered for the prefix
-            prefix_strategy = auth_config[:auth_strategies][prefix]
-            if prefix_strategy
-              result = [prefix_strategy, prefix]
-              @strategy_cache[requirement] = result
-              return result
-            end
+          # SESSION PERSISTENCE: Ensure env['rack.session'] and strategy_result.session
+          # reference the SAME object for proper session persistence
+          env['rack.session'] = result.session if result.is_a?(StrategyResult) && result.session
+
+          # Layer 1 Authorization: Check role requirements
+          auth_check = @role_authorizer.check(result, env)
+          unless auth_check == true
+            return @response_builder.forbidden(env,
+              "Access denied: requires one of roles: #{auth_check[:required].join(', ')}")
           end
 
-          # Cache nil results too to avoid repeated failed lookups
-          @strategy_cache[requirement] = [nil, nil]
-          [nil, nil]
+          # Authentication and authorization succeeded
+          wrapped_handler.call(env, extra_params)
         end
 
-        # Generate 401 response for authentication failure
-        #
-        # @param env [Hash] Rack environment
-        # @param result [AuthFailure] Failure result from strategy
-        # @return [Array] Rack response array
-        def auth_failure_response(env, result)
-          # Check if request wants JSON
-          accept_header = env['HTTP_ACCEPT'] || ''
-          wants_json = accept_header.include?('application/json')
+        # Handle case when all authentication strategies fail
+        def handle_all_strategies_failed(env, auth_requirements, failed_strategies, total_start_time)
+          total_duration = Otto::Utils.now_in_μs - total_start_time
 
-          if wants_json
-            json_auth_error(result)
-          else
-            html_auth_error(result)
-          end
-        end
+          log_all_failed(env, failed_strategies, total_duration)
 
-        # Generate JSON 401 response
-        #
-        # @param result [AuthFailure] Failure result
-        # @return [Array] Rack response array
-        def json_auth_error(result)
-          body = {
-            error: 'Authentication Required',
-            message: result.failure_reason || 'Not authenticated',
-            timestamp: Time.now.to_i
-          }.to_json
-
-          headers = {
-            'content-type' => 'application/json',
-            'content-length' => body.bytesize.to_s
-          }
+          # Create anonymous result with failure info
+          metadata = build_failure_metadata(env, failed_strategies)
+          failure_strategy_name = determine_failure_strategy_name(auth_requirements, failed_strategies)
 
-          # Add security headers if available
-          merge_security_headers!(headers)
+          env['otto.strategy_result'] = StrategyResult.anonymous(
+            metadata: metadata,
+            strategy_name: failure_strategy_name
+          )
 
-          [401, headers, [body]]
+          last_failure = if failed_strategies.any?
+                           AuthFailure.new(
+                             failure_reason: failed_strategies.last[:reason],
+                             auth_method: failed_strategies.last[:strategy]
+                           )
+                         else
+                           AuthFailure.new(
+                             failure_reason: 'Authentication required',
+                             auth_method: auth_requirements.first
+                           )
+                         end
+
+          @response_builder.auth_failure(env, last_failure)
         end
 
-        # Generate HTML 401 response or redirect
-        #
-        # @param result [AuthFailure] Failure result
-        # @return [Array] Rack response array
-        def html_auth_error(result)
-          # For HTML requests, redirect to login
-          login_path = auth_config[:login_path] || '/signin'
-
-          headers = { 'location' => login_path }
-
-          # Add security headers if available
-          merge_security_headers!(headers)
-
-          [302, headers, ["Redirecting to #{login_path}"]]
+        # Build metadata for anonymous routes
+        def build_anonymous_metadata(env)
+          metadata = { ip: env['REMOTE_ADDR'] }
+          metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
+          metadata
         end
 
-        # Generate generic unauthorized response
-        #
-        # @param env [Hash] Rack environment
-        # @param message [String] Error message
-        # @return [Array] Rack response array
-        def unauthorized_response(env, message)
-          accept_header = env['HTTP_ACCEPT'] || ''
-          wants_json = accept_header.include?('application/json')
-
-          if wants_json
-            body = { error: message }.to_json
-            headers = {
-              'content-type' => 'application/json',
-              'content-length' => body.bytesize.to_s
-            }
-            merge_security_headers!(headers)
-            [401, headers, [body]]
-          else
-            headers = { 'content-type' => 'text/plain' }
-            merge_security_headers!(headers)
-            [401, headers, [message]]
-          end
+        # Build metadata for failed authentication
+        def build_failure_metadata(env, failed_strategies)
+          metadata = {
+                          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] },
+          }
+          metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
+          metadata
         end
 
-        # Generate 403 Forbidden response for role authorization failure
-        #
-        # @param env [Hash] Rack environment
-        # @param message [String] Error message
-        # @return [Array] Rack response array
-        def forbidden_response(env, message)
-          accept_header = env['HTTP_ACCEPT'] || ''
-          wants_json = accept_header.include?('application/json')
-
-          if wants_json
-            body = { error: 'Forbidden', message: message }.to_json
-            headers = {
-              'content-type' => 'application/json',
-              'content-length' => body.bytesize.to_s
-            }
-            merge_security_headers!(headers)
-            [403, headers, [body]]
+        # Determine strategy name for failure response
+        def determine_failure_strategy_name(auth_requirements, failed_strategies)
+          if auth_requirements.size > 1
+            'multi-strategy-failure'
+          elsif failed_strategies.any?
+            failed_strategies.first[:strategy]
           else
-            headers = { 'content-type' => 'text/plain' }
-            merge_security_headers!(headers)
-            [403, headers, [message]]
+            auth_requirements.first
           end
         end
 
-        # Extract user roles from authentication result
-        #
-        # Supports multiple role sources in order of precedence:
-        # 1. result.user_roles (Array)
-        # 2. result.user[:roles] (Array)
-        # 3. result.user['roles'] (Array)
-        # 4. result.metadata[:user_roles] (Array)
-        #
-        # @param result [StrategyResult] Authentication result
-        # @return [Array<String>] Array of role strings
-        def extract_user_roles(result)
-          # Try direct user_roles accessor (e.g., from RoleStrategy)
-          return Array(result.user_roles) if result.respond_to?(:user_roles) && result.user_roles
-
-          # Try user hash/object with roles
-          if result.user
-            roles = result.user[:roles] || result.user['roles']
-            return Array(roles) if roles
-          end
+        # Logging helpers
 
-          # Try metadata
-          if result.metadata && result.metadata[:user_roles]
-            return Array(result.metadata[:user_roles])
-          end
+        def log_strategy_start(env, strategy_name, requirement, auth_requirements)
+          Otto.structured_log(:debug, 'Auth strategy executing',
+            Otto::LoggingHelpers.request_context(env).merge(
+              strategy: strategy_name,
+              requirement: requirement,
+              strategy_position: auth_requirements.index(requirement) + 1,
+              total_strategies: auth_requirements.size
+            ))
+        end
 
-          # No roles found
-          []
+        def log_auth_success(env, strategy_name, result, duration, total_duration, failed_strategies)
+          Otto.structured_log(:info, 'Auth strategy result',
+            Otto::LoggingHelpers.request_context(env).merge(
+              strategy: strategy_name,
+              success: true,
+              user_id: result.user_id,
+              duration: duration,
+              total_duration: total_duration,
+              strategies_attempted: failed_strategies.size + 1
+            ))
         end
 
-        # Merge security headers into response headers
-        #
-        # @param headers [Hash] Response headers hash to merge into
-        def merge_security_headers!(headers)
-          return unless security_config
+        def log_strategy_failure(env, strategy_name, result, duration, auth_requirements, requirement)
+          Otto.structured_log(:info, 'Auth strategy result',
+            Otto::LoggingHelpers.request_context(env).merge(
+              strategy: strategy_name,
+              success: false,
+              failure_reason: result.failure_reason,
+              duration: duration,
+              remaining_strategies: auth_requirements.size - auth_requirements.index(requirement) - 1
+            ))
+        end
 
-          headers.merge!(security_config.security_headers)
+        def log_all_failed(env, failed_strategies, total_duration)
+          Otto.structured_log(:warn, 'All auth strategies failed',
+            Otto::LoggingHelpers.request_context(env).merge(
+              strategies_attempted: failed_strategies.map { |f| f[:strategy] },
+              total_duration: total_duration,
+              failure_count: failed_strategies.size
+            ))
         end
       end
     end

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 class Otto
-  VERSION = '2.0.0.pre7'
+  VERSION = '2.0.0.pre8'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre7
+  version: 2.0.0.pre8
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -169,8 +169,6 @@ files:
 - LICENSE.txt
 - README.md
 - bin/rspec
-- changelog.d/20251103_235431_delano_86_improve_error_logging.rst
-- changelog.d/20251109_025012_claude_fix_backtrace_sanitization.rst
 - changelog.d/README.md
 - changelog.d/scriv.ini
 - docs/.gitignore
@@ -289,6 +287,9 @@ files:
 - lib/otto/security/authentication/auth_failure.rb
 - lib/otto/security/authentication/auth_strategy.rb
 - lib/otto/security/authentication/route_auth_wrapper.rb
+- lib/otto/security/authentication/route_auth_wrapper/response_builder.rb
+- lib/otto/security/authentication/route_auth_wrapper/role_authorization.rb
+- lib/otto/security/authentication/route_auth_wrapper/strategy_resolver.rb
 - lib/otto/security/authentication/strategies/api_key_strategy.rb
 - lib/otto/security/authentication/strategies/noauth_strategy.rb
 - lib/otto/security/authentication/strategies/permission_strategy.rb

data/changelog.d/20251103_235431_delano_86_improve_error_logging.rst

@@ -1,15 +0,0 @@
-Added
------
-
-- Error handler registration system for expected business logic errors. Register handlers with ``otto.register_error_handler(ErrorClass, status: 404, log_level: :info)`` to return proper HTTP status codes and avoid logging expected errors as 500s with backtraces. Supports custom response handlers via blocks for complete control over error responses.
-
-Changed
--------
-
-- Backtrace logging now always logs at ERROR level (was DEBUG) with sanitized file paths for security. Backtraces for unhandled 500 errors are always logged regardless of ``OTTO_DEBUG`` setting, with paths sanitized to prevent exposing system information (project files show relative paths, gems show ``[GEM] name-version/path``, Ruby stdlib shows ``[RUBY] filename``).
-- Increased backtrace limit from 10 to 20 lines for critical errors to provide better debugging context.
-
-AI Assistance
--------------
-
-- Implemented error handler registration architecture with comprehensive test coverage (17 test cases) using sequential thinking to work through security implications and design decisions. AI assisted with path sanitization strategy, error classification patterns, and ensuring backward compatibility with existing error handling.

data/changelog.d/20251109_025012_claude_fix_backtrace_sanitization.rst

@@ -1,37 +0,0 @@
-.. Changed in: otto
-.. Fixes issue:
-
-Improved backtrace sanitization security and readability
----------------------------------------------------------
-
-**Security Enhancements:**
-
-- Fixed bundler gem path detection to correctly sanitize git-based gems
-- Now properly handles nested gem paths like ``/gems/3.4.0/bundler/gems/otto-abc123/``
-- Strips git hash suffixes from bundler gems (``otto-abc123def456`` → ``otto``)
-- Removes version numbers from regular gems (``rack-3.2.4`` → ``rack``)
-- Prevents exposure of absolute paths, usernames, and project names in logs
-
-**Improvements:**
-
-- Bundler gems now show as ``[GEM] otto/lib/otto/route.rb:142`` instead of ``[GEM] 3.4.0/bundler/gems/...``
-- Regular gems show cleaner output: ``[GEM] rack/lib/rack.rb:20`` instead of ``[GEM] rack-3.2.4/lib/rack.rb:20``
-- Multi-hyphenated gem names handled correctly (``active-record-import-1.5.0`` → ``active-record-import``)
-- Better handling of version-only directory names in gem paths
-
-**Documentation:**
-
-- Added comprehensive backtrace sanitization section to CLAUDE.md
-- Documented security guarantees and sanitization rules
-- Added examples showing before/after path transformations
-- Created comprehensive test suite for backtrace sanitization
-
-**Rationale:**
-
-Raw backtraces expose sensitive information:
-- Usernames (``/Users/alice/``, ``/home/admin/``)
-- Project structure and internal organization
-- Gem installation paths and Ruby versions
-- System architecture details
-
-This improvement ensures all backtraces are sanitized automatically, preventing accidental leakage of sensitive system information while maintaining readability for debugging.