otto 2.0.0.pre3 → 2.0.0.pre8

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

@@ -1,28 +1,27 @@
 # frozen_string_literal: true
 
-# lib/otto/security/authentication/route_auth_wrapper.rb
+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'], env['otto.user']
-      #   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,229 +29,220 @@ 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
-        #
         # @param env [Hash] Rack environment
         # @param extra_params [Hash] Additional parameters
         # @return [Array] Rack response array
         def call(env, extra_params = {})
-          auth_requirement = route_definition.auth_requirement
+          auth_requirements = route_definition.auth_requirements
 
           # Routes without auth requirement get anonymous StrategyResult
-          unless auth_requirement
-            # Note: env['REMOTE_ADDR'] is masked by IPPrivacyMiddleware by default
-            metadata = { ip: env['REMOTE_ADDR'] }
-            metadata[:country] = env['otto.geo_country'] if env['otto.geo_country']
-
-            result = StrategyResult.anonymous(metadata: metadata)
-            env['otto.strategy_result'] = result
-            env['otto.user'] = nil
-            env['otto.user_context'] = result.user_context
-            return wrapped_handler.call(env, extra_params)
-          end
+          return handle_anonymous_route(env, extra_params) if auth_requirements.empty?
 
-          # Routes WITH auth requirement: Execute authentication strategy
-          strategy = get_strategy(auth_requirement)
+          # Validate all strategies exist before executing any (fail-fast)
+          validation_error = validate_strategies(auth_requirements, env)
+          return validation_error if validation_error
 
-          unless strategy
-            Otto.logger.error "[RouteAuthWrapper] No strategy found for requirement: #{auth_requirement}"
-            return unauthorized_response(env, "Authentication strategy not configured")
-          end
+          # Try each strategy in order (first success wins)
+          authenticate_and_authorize(env, extra_params, auth_requirements)
+        end
 
-          # Execute the strategy
-          result = strategy.authenticate(env, auth_requirement)
-
-          # Handle authentication failure
-          if result.is_a?(AuthFailure)
-            # Create anonymous result with failure info for logging/auditing
-            # Note: env['REMOTE_ADDR'] is masked by IPPrivacyMiddleware by default
-            metadata = {
-              ip: env['REMOTE_ADDR'],
-              auth_failure: result.failure_reason,
-              attempted_strategy: auth_requirement
-            }
-            metadata[:country] = env['otto.geo_country'] if env['otto.geo_country']
-
-            env['otto.strategy_result'] = StrategyResult.anonymous(metadata: metadata)
-            env['otto.user'] = nil
-            env['otto.user_context'] = {}
-            return auth_failure_response(env, result)
-          end
+        private
 
-          # Set environment variables for controllers/logic on success
+        # 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
-          env['otto.user'] = result.user
-          env['otto.user_context'] = result.user_context
-
-          # 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
-
-          # Authentication succeeded - call wrapped handler
           wrapped_handler.call(env, extra_params)
         end
 
-        private
-
-        # Get strategy from auth_config hash with sophisticated pattern matching
-        #
-        # Supports:
-        # - Exact match: 'authenticated' → looks up auth_config[:auth_strategies]['authenticated']
-        # - Prefix match: 'role:admin' → looks up 'role' strategy
-        # - Fallback: 'role:*' → creates default RoleStrategy
-        # - Fallback: 'permission:*' → creates default PermissionStrategy
-        #
-        # Results are cached to avoid repeated lookups for the same requirement.
+        # Validate all strategies exist before executing
         #
-        # @param requirement [String] Auth requirement from route
-        # @return [AuthStrategy, nil] Strategy instance or nil
-        def get_strategy(requirement)
-          return nil unless auth_config && auth_config[:auth_strategies]
-
-          # Check cache first
-          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
-            @strategy_cache[requirement] = strategy
-            return strategy
+        # @return [Array, nil] Error response if validation fails, nil otherwise
+        def validate_strategies(auth_requirements, env)
+          auth_requirements.each do |requirement|
+            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
 
-          # For colon-separated requirements like "role:admin", try prefix match
-          if requirement.include?(':')
-            prefix = requirement.split(':', 2).first
+        # Main authentication and authorization flow
+        def authenticate_and_authorize(env, extra_params, auth_requirements)
+          failed_strategies = []
+          total_start_time = Otto::Utils.now_in_μs
 
-            # Check if we have a strategy registered for the prefix
-            prefix_strategy = auth_config[:auth_strategies][prefix]
-            if prefix_strategy
-              @strategy_cache[requirement] = prefix_strategy
-              return prefix_strategy
-            end
+          auth_requirements.each do |requirement|
+            strategy, strategy_name = @strategy_resolver.resolve(requirement)
+
+            log_strategy_start(env, strategy_name, requirement, auth_requirements)
 
-            # Try fallback patterns for role: and permission: requirements
-            if requirement.start_with?('role:')
-              # Cache the fallback strategy under 'role:' key to create it only once
-              strategy = @strategy_cache['role:'] ||= begin
-                auth_config[:auth_strategies]['role'] || Strategies::RoleStrategy.new([])
-              end
-              @strategy_cache[requirement] = strategy
-              return strategy
-            elsif requirement.start_with?('permission:')
-              # Cache the fallback strategy under 'permission:' key
-              strategy = @strategy_cache['permission:'] ||= begin
-                auth_config[:auth_strategies]['permission'] || Strategies::PermissionStrategy.new([])
-              end
-              @strategy_cache[requirement] = strategy
-              return strategy
+            # 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
+            result = result.with(strategy_name: strategy_name) if result.is_a?(StrategyResult)
+
+            # Handle authentication success
+            if result.is_a?(StrategyResult) && (result.authenticated? || result.anonymous?)
+              return handle_auth_success(env, extra_params, result, strategy_name,
+                                        duration, total_start_time, failed_strategies)
             end
+
+            # Handle authentication failure - continue to next strategy
+            next unless result.is_a?(AuthFailure)
+
+            log_strategy_failure(env, strategy_name, result, duration, auth_requirements, requirement)
+            failed_strategies << { strategy: strategy_name, reason: result.failure_reason }
           end
 
-          # Cache nil results too to avoid repeated failed lookups
-          @strategy_cache[requirement] = nil
-          nil
+          # All strategies failed
+          handle_all_strategies_failed(env, auth_requirements, failed_strategies, total_start_time)
         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 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
 
-          if wants_json
-            json_auth_error(result)
-          else
-            html_auth_error(result)
-          end
-        end
+          log_auth_success(env, strategy_name, result, duration, total_duration, failed_strategies)
 
-        # 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
-          }
+          # Set environment variables for controllers/logic
+          env['otto.strategy_result'] = result
 
-          # Add security headers if available
-          merge_security_headers!(headers)
+          # 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
 
-          [401, headers, [body]]
-        end
+          # 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
 
-        # 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'
+          # Authentication and authorization succeeded
+          wrapped_handler.call(env, extra_params)
+        end
 
-          headers = { 'location' => login_path }
+        # 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
+
+          log_all_failed(env, failed_strategies, total_duration)
+
+          # Create anonymous result with failure info
+          metadata = build_failure_metadata(env, failed_strategies)
+          failure_strategy_name = determine_failure_strategy_name(auth_requirements, failed_strategies)
+
+          env['otto.strategy_result'] = StrategyResult.anonymous(
+            metadata: metadata,
+            strategy_name: failure_strategy_name
+          )
+
+          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
 
-          # Add security headers if available
-          merge_security_headers!(headers)
+        # 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
 
-          [302, headers, ["Redirecting to #{login_path}"]]
+        # 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 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]]
+        # 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)
-            [401, headers, [message]]
+            auth_requirements.first
           end
         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
+        # Logging helpers
+
+        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
+
+        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
+
+        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/security/authentication/strategies/api_key_strategy.rb

@@ -1,3 +1,5 @@
+# lib/otto/security/authentication/strategies/api_key_strategy.rb
+#
 # frozen_string_literal: true
 
 require_relative '../auth_strategy'

data/lib/otto/security/authentication/strategies/noauth_strategy.rb

@@ -1,3 +1,5 @@
+# lib/otto/security/authentication/strategies/noauth_strategy.rb
+#
 # frozen_string_literal: true
 
 require_relative '../auth_strategy'

data/lib/otto/security/authentication/strategies/permission_strategy.rb

@@ -1,3 +1,5 @@
+# lib/otto/security/authentication/strategies/permission_strategy.rb
+#
 # frozen_string_literal: true
 
 require_relative '../auth_strategy'

data/lib/otto/security/authentication/strategies/role_strategy.rb

@@ -1,3 +1,5 @@
+# lib/otto/security/authentication/strategies/role_strategy.rb
+#
 # frozen_string_literal: true
 
 require_relative '../auth_strategy'

data/lib/otto/security/authentication/strategies/session_strategy.rb

@@ -1,3 +1,5 @@
+# lib/otto/security/authentication/strategies/session_strategy.rb
+#
 # frozen_string_literal: true
 
 require_relative '../auth_strategy'

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

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/security/authentication/strategy_result.rb
+#
+# frozen_string_literal: true
 
 # StrategyResult is an immutable data structure that holds the result of an
 # authentication strategy. It contains session, user, and metadata needed by
@@ -21,7 +21,7 @@
 class Otto
   module Security
     module Authentication
-      StrategyResult = Data.define(:session, :user, :auth_method, :metadata) do
+      StrategyResult = Data.define(:session, :user, :auth_method, :metadata, :strategy_name) do
         # =====================================================================
         # USAGE PATTERNS - READ THIS FIRST
         # =====================================================================
@@ -110,12 +110,13 @@ class Otto
         #
         # @param metadata [Hash] Optional metadata (IP, user agent, etc.)
         # @return [StrategyResult] Anonymous result with nil user
-        def self.anonymous(metadata: {})
+        def self.anonymous(metadata: {}, strategy_name: 'anonymous')
           new(
             session: {},
             user: nil,
             auth_method: 'anonymous',
-            metadata: metadata
+            metadata: metadata,
+            strategy_name: strategy_name
           )
         end
 

data/lib/otto/security/authentication.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 # lib/otto/security/authentication.rb
 #
+# frozen_string_literal: true
+#
 # Index file for Otto authentication module
 # Requires all authentication-related components for backward compatibility
 

data/lib/otto/security/authorization_error.rb

@@ -0,0 +1,73 @@
+# lib/otto/security/authorization_error.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    # Authorization error for resource-level access control failures
+    #
+    # This exception is designed to be raised from Logic classes when a user
+    # attempts to access a resource they don't have permission to access.
+    #
+    # Otto automatically registers this as a 403 Forbidden error during
+    # initialization, so raising this exception will return a 403 response
+    # instead of a 500 error.
+    #
+    # Two-Layer Authorization Pattern:
+    # - Layer 1 (Route-level): RouteAuthWrapper checks authentication/basic roles
+    # - Layer 2 (Resource-level): Logic classes raise AuthorizationError for ownership/permissions
+    #
+    # @example Ownership check in Logic class
+    #   class PostEditLogic
+    #     def raise_concerns
+    #       @post = Post.find(params[:id])
+    #
+    #       unless @post.user_id == @context.user_id
+    #         raise Otto::Security::AuthorizationError, "Cannot edit another user's post"
+    #       end
+    #     end
+    #   end
+    #
+    # @example Multi-condition authorization
+    #   class OrganizationDeleteLogic
+    #     def raise_concerns
+    #       @org = Organization.find(params[:id])
+    #
+    #       unless @context.user_roles.include?('admin') || @org.owner_id == @context.user_id
+    #         raise Otto::Security::AuthorizationError,
+    #           "Requires admin role or organization ownership"
+    #       end
+    #     end
+    #   end
+    #
+    class AuthorizationError < StandardError
+      # Optional additional context for logging/debugging
+      attr_reader :resource, :action, :user_id
+
+      # Initialize authorization error with optional context
+      #
+      # @param message [String] Human-readable error message
+      # @param resource [String, nil] Resource type being accessed (e.g., 'Post', 'Organization')
+      # @param action [String, nil] Action being attempted (e.g., 'edit', 'delete')
+      # @param user_id [String, Integer, nil] ID of user attempting access
+      def initialize(message = 'Access denied', resource: nil, action: nil, user_id: nil)
+        super(message)
+        @resource = resource
+        @action = action
+        @user_id = user_id
+      end
+
+      # Generate structured log data for authorization failures
+      #
+      # @return [Hash] Hash suitable for structured logging
+      def to_log_data
+        {
+          error: message,
+          resource: resource,
+          action: action,
+          user_id: user_id,
+        }.compact
+      end
+    end
+  end
+end

data/lib/otto/security/config.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/security/config.rb
+#
+# frozen_string_literal: true
 
 require 'securerandom'
 require 'digest'

data/lib/otto/security/configurator.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/security/configurator.rb
+#
+# frozen_string_literal: true
 
 require_relative 'middleware/csrf_middleware'
 require_relative 'middleware/validation_middleware'
@@ -170,9 +170,24 @@ class Otto
 
       # Add a single authentication strategy
       #
+      # Part of the Security::Configurator facade for consolidated configuration.
+      # This delegates to the same storage as Otto#add_auth_strategy, allowing
+      # authentication to be configured alongside other security features.
+      #
+      # Prefer using Otto#add_auth_strategy directly for simpler cases, or use this
+      # when configuring multiple security features together via the security facade.
+      #
       # @param name [String] Strategy name
       # @param strategy [Otto::Security::Authentication::AuthStrategy] Strategy instance
+      # @example
+      #   otto.security.add_auth_strategy('session', SessionStrategy.new)
+      # @raise [ArgumentError] if strategy name already registered
       def add_auth_strategy(name, strategy)
+        # Strict mode: Detect strategy name collisions
+        if @auth_config[:auth_strategies].key?(name)
+          raise ArgumentError, "Authentication strategy '#{name}' is already registered"
+        end
+
         @auth_config[:auth_strategies][name] = strategy
       end
 

data/lib/otto/security/csrf.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 # lib/otto/security/csrf.rb
 #
+# frozen_string_literal: true
+#
 # Index file for CSRF protection components
 # Provides backward compatibility for existing CSRF usage