otto 2.0.0.pre7 → 2.0.0.pre9

data/lib/otto/route_handlers/instance_method.rb

@@ -1,71 +1,31 @@
 # lib/otto/route_handlers/instance_method.rb
 #
 # frozen_string_literal: true
-require 'securerandom'
 
 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
-        req = Rack::Request.new(env)
-        res = Rack::Response.new
-
-        begin
-          # Apply the same extensions and processing as original Route#call
-          setup_request_response(req, res, env, extra_params)
-
-          # Create instance and call method (existing Otto behavior)
-          instance = target_class.new(req, res)
-          result   = instance.send(route_definition.method_name)
-
-          # Only handle response if response_type is not default
-          if route_definition.response_type != 'default'
-            handle_response(result, res, {
-                              instance: instance,
-                              request: req,
-                            })
-          end
-        rescue StandardError => e
-          # Check if we're being called through Otto's integrated context (vs direct handler testing)
-          # In integrated context, let Otto's centralized error handler manage the response
-          # In direct testing context, handle errors locally for unit testing
-          if otto_instance
-            # Store handler context in env for centralized error handler
-            handler_name = "#{target_class}##{route_definition.method_name}"
-            env['otto.handler'] = handler_name
-            env['otto.handler_duration'] = Otto::Utils.now_in_μs - start_time
-
-            raise e # Re-raise to let Otto's centralized error handler manage the response
-          else
-            # Direct handler testing context - handle errors locally with security improvements
-            error_id = SecureRandom.hex(8)
-            Otto.logger.error "[#{error_id}] #{e.class}: #{e.message}"
-            Otto.logger.debug "[#{error_id}] Backtrace: #{e.backtrace.join("\n")}" if Otto.debug
-
-            res.status                  = 500
-            res.headers['content-type'] = 'text/plain'
-
-            if Otto.env?(:dev, :development)
-              res.write "Server error (ID: #{error_id}). Check logs for details."
-            else
-              res.write 'An error occurred. Please try again later.'
-            end
-
-            # Add security headers if available
-            if otto_instance.respond_to?(:security_config) && otto_instance.security_config
-              otto_instance.security_config.security_headers.each do |header, value|
-                res.headers[header] = value
-              end
-            end
-          end
-        end
-
-        finalize_response(res)
+      protected
+
+      # Invoke the instance method on the target class
+      # @param req [Rack::Request] Request object
+      # @param res [Rack::Response] Response object
+      # @return [Array] [result, context] for handle_response
+      def invoke_target(req, res)
+        instance = target_class.new(req, res)
+        result = instance.send(route_definition.method_name)
+        [result, { instance: instance, request: req }]
       end
     end
   end

data/lib/otto/route_handlers/logic_class.rb

@@ -1,109 +1,112 @@
 # lib/otto/route_handlers/logic_class.rb
 #
 # frozen_string_literal: true
-require 'json'
-require 'securerandom'
 
 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
-        req = Rack::Request.new(env)
-        res = Rack::Response.new
+      protected
 
+      # Invoke Logic class with constrained signature
+      # @param req [Rack::Request] Request object
+      # @param res [Rack::Response] Response object
+      # @return [Array] [result, context] for handle_response
+      def invoke_target(req, _res)
+        env = req.env
+
+        # Get strategy result (guaranteed to exist from RouteAuthWrapper)
+        strategy_result = env['otto.strategy_result']
+
+        # Extract params including JSON body parsing
+        logic_params = extract_logic_params(req, env)
+
+        # Get locale
+        locale = env['otto.locale'] || 'en'
+
+        # Instantiate Logic class
+        logic = target_class.new(strategy_result, logic_params, locale)
+
+        # Execute standard Logic class lifecycle
+        logic.raise_concerns if logic.respond_to?(:raise_concerns)
+
+        result = if logic.respond_to?(:process)
+                   logic.process
+                 else
+                   logic.call || logic
+                 end
+
+        context = {
+          logic_instance: logic,
+                 request: req,
+             status_code: logic.respond_to?(:status_code) ? logic.status_code : nil,
+        }
+
+        [result, context]
+      end
+
+      # Extract logic parameters including JSON body parsing
+      # @param req [Rack::Request] Request object
+      # @param env [Hash] Rack environment
+      # @return [Hash] Parameters for Logic class
+      def extract_logic_params(req, env)
+        # req.params already has extra_params merged and indifferent_params applied
+        # by setup_request_response in BaseHandler
+        logic_params = req.params.dup
+
+        # Handle JSON request bodies
+        if req.content_type&.include?('application/json') && req.body.size.positive?
+          logic_params = parse_json_body(req, env, logic_params)
+        end
+
+        logic_params
+      end
+
+      # Parse JSON request body with error handling
+      # @param req [Rack::Request] Request object
+      # @param env [Hash] Rack environment
+      # @param logic_params [Hash] Current parameters
+      # @return [Hash] Parameters with JSON merged (or original if parsing fails)
+      def parse_json_body(req, env, logic_params)
         begin
-          # Get strategy result (guaranteed to exist from RouteAuthWrapper)
-          strategy_result = env['otto.strategy_result']
-
-          # Initialize Logic class with new signature: context, params, locale
-          logic_params = req.params.merge(extra_params)
-
-          # Handle JSON request bodies
-          if req.content_type&.include?('application/json') && req.body.size.positive?
-            begin
-              req.body.rewind
-              json_data = JSON.parse(req.body.read)
-              logic_params = logic_params.merge(json_data) if json_data.is_a?(Hash)
-            rescue JSON::ParserError => e
-              # Base context pattern: create once, reuse for correlation
-              base_context = Otto::LoggingHelpers.request_context(env)
-
-              Otto.structured_log(:error, "JSON parsing error",
-                base_context.merge(
-                  handler: "#{target_class}#call",
-                  error: e.message,
-                  error_class: e.class.name,
-                  duration: Otto::Utils.now_in_μs - start_time
-                )
-              )
-
-              Otto::LoggingHelpers.log_backtrace(e,
-                base_context.merge(handler: "#{target_class}#call")
-              )
-            end
-          end
-
-          locale = env['otto.locale'] || 'en'
-
-          logic = target_class.new(strategy_result, logic_params, locale)
-
-          # Execute standard Logic class lifecycle
-          logic.raise_concerns if logic.respond_to?(:raise_concerns)
-
-          result = if logic.respond_to?(:process)
-                     logic.process
-                   else
-                     logic.call || logic
-                   end
-
-          # Handle response with Logic instance context
-          handle_response(result, res, {
-                            logic_instance: logic,
-            request: req,
-            status_code: logic.respond_to?(:status_code) ? logic.status_code : nil,
-                          })
-        rescue StandardError => e
-          # Check if we're being called through Otto's integrated context (vs direct handler testing)
-          # In integrated context, let Otto's centralized error handler manage the response
-          # In direct testing context, handle errors locally for unit testing
-          if otto_instance
-            # Store handler context in env for centralized error handler
-            handler_name = "#{target_class}#call"
-            env['otto.handler'] = handler_name
-            env['otto.handler_duration'] = Otto::Utils.now_in_μs - start_time
-
-            raise e # Re-raise to let Otto's centralized error handler manage the response
-          else
-            # Direct handler testing context - handle errors locally with security improvements
-            error_id = SecureRandom.hex(8)
-            Otto.logger.error "[#{error_id}] #{e.class}: #{e.message}"
-            Otto.logger.debug "[#{error_id}] Backtrace: #{e.backtrace.join("\n")}" if Otto.debug
-
-            res.status                  = 500
-            res.headers['content-type'] = 'text/plain'
-
-            if Otto.env?(:dev, :development)
-              res.write "Server error (ID: #{error_id}). Check logs for details."
-            else
-              res.write 'An error occurred. Please try again later.'
-            end
-
-            # Add security headers if available
-            if otto_instance.respond_to?(:security_config) && otto_instance.security_config
-              otto_instance.security_config.security_headers.each do |header, value|
-                res.headers[header] = value
-              end
-            end
-          end
+          req.body.rewind
+          json_data = JSON.parse(req.body.read)
+          logic_params = logic_params.merge(json_data) if json_data.is_a?(Hash)
+        rescue JSON::ParserError => e
+          # Base context pattern: create once, reuse for correlation
+          log_context = Otto::LoggingHelpers.request_context(env)
+
+          Otto.structured_log(:error, 'JSON parsing error',
+            log_context.merge(
+              handler: handler_name,
+              error: e.message,
+              error_class: e.class.name,
+              duration: Otto::Utils.now_in_μs - @start_time
+            ))
+
+          Otto::LoggingHelpers.log_backtrace(e,
+            log_context.merge(handler: handler_name))
         end
 
-        res.finish
+        logic_params
+      end
+
+      # Format handler name for Logic routes
+      # @return [String] Handler name in format "ClassName#call"
+      def handler_name
+        "#{target_class.name}#call"
       end
     end
   end

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

@@ -1,7 +1,7 @@
 # lib/otto/security/authentication/auth_strategy.rb
 #
 # frozen_string_literal: true
-#
+
 # Base class for all authentication strategies in Otto framework
 # Provides pluggable authentication patterns that can be customized per application
 
@@ -33,7 +33,7 @@ class Otto
             user: user,
             auth_method: auth_method || self.class.name.split('::').last,
             metadata: metadata,
-            strategy_name: nil  # Will be set by RouteAuthWrapper
+            strategy_name: nil # Will be set by RouteAuthWrapper
           )
         end
 

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