otto 2.0.0.pre3 → 2.0.0.pre7

data/lib/otto/route_handlers/lambda.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/route_handlers/lambda.rb
+#
+# frozen_string_literal: true
 require 'securerandom'
 
 require_relative 'base'
@@ -10,6 +10,7 @@ class Otto
     # Custom handler for lambda/proc definitions (future extension)
     class LambdaHandler < BaseHandler
       def call(env, extra_params = {})
+        start_time = Otto::Utils.now_in_μs
         req = Rack::Request.new(env)
         res = Rack::Response.new
 
@@ -31,25 +32,12 @@ class Otto
             request: req,
                           })
         rescue StandardError => e
-          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'
+          # Store handler context in env for centralized error handler
+          handler_name = "Lambda[#{route_definition.klass_name}]"
+          env['otto.handler'] = handler_name
+          env['otto.handler_duration'] = Otto::Utils.now_in_μs - start_time
 
-          if Otto.env?(:dev, :development)
-            res.write "Lambda handler 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
+          raise e # Re-raise to let Otto's centralized error handler manage the response
         end
 
         res.finish

data/lib/otto/route_handlers/logic_class.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/route_handlers/logic_class.rb
+#
+# frozen_string_literal: true
 require 'json'
 require 'securerandom'
 
@@ -13,6 +13,7 @@ class Otto
     # Logic classes use signature: initialize(context, params, locale)
     class LogicClassHandler < BaseHandler
       def call(env, extra_params = {})
+        start_time = Otto::Utils.now_in_μs
         req = Rack::Request.new(env)
         res = Rack::Response.new
 
@@ -30,7 +31,21 @@ class Otto
               json_data = JSON.parse(req.body.read)
               logic_params = logic_params.merge(json_data) if json_data.is_a?(Hash)
             rescue JSON::ParserError => e
-              Otto.logger.error "[LogicClassHandler] JSON parsing error: #{e.message}"
+              # 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
 
@@ -58,9 +73,11 @@ class Otto
           # 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
-            # Log error for handler-specific context but let Otto's centralized error handler manage the response
-            Otto.logger.error "[LogicClassHandler] #{e.class}: #{e.message}"
-            Otto.logger.debug "[LogicClassHandler] Backtrace: #{e.backtrace.join("\n")}" if Otto.debug
+            # 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

data/lib/otto/route_handlers.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/route_handlers.rb
+#
+# frozen_string_literal: true
 
 class Otto
   # Pluggable Route Handler Factory

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

@@ -1,7 +1,7 @@
+# lib/otto/security/authentication/auth_failure.rb
+#
 # frozen_string_literal: true
 
-# lib/otto/security/authentication/failure_result.rb
-
 class Otto
   module Security
     module Authentication

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

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 # 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
 
@@ -13,7 +13,9 @@ class Otto
         # Check if the request meets the authentication requirements
         # @param env [Hash] Rack environment
         # @param requirement [String] Authentication requirement string
-        # @return [Otto::Security::Authentication::StrategyResult, Otto::Security::Authentication::AuthFailure] StrategyResult for success, AuthFailure for failure
+        # @return [Otto::Security::Authentication::StrategyResult,
+        #          Otto::Security::Authentication::AuthFailure]
+        #          StrategyResult for success, AuthFailure for failure
         def authenticate(env, requirement)
           raise NotImplementedError, 'Subclasses must implement #authenticate'
         end
@@ -21,12 +23,17 @@ class Otto
         protected
 
         # Helper to create successful strategy result
+        #
+        # NOTE: strategy_name will be injected by RouteAuthWrapper after strategy execution.
+        # Strategies don't know their registered name, so we pass nil here and let the wrapper
+        # set it based on how the strategy was registered via add_auth_strategy(name, strategy).
         def success(user:, session: {}, auth_method: nil, **metadata)
           Otto::Security::Authentication::StrategyResult.new(
             session: session,
             user: user,
             auth_method: auth_method || self.class.name.split('::').last,
-            metadata: metadata
+            metadata: metadata,
+            strategy_name: nil  # Will be set by RouteAuthWrapper
           )
         end
 

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

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/security/authentication/route_auth_wrapper.rb
+#
+# frozen_string_literal: true
 
 class Otto
   module Security
@@ -15,7 +15,7 @@ class Otto
       #   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']
+      #   4. Set env['otto.strategy_result']
       #   5. If auth fails, return 401 or redirect
       #   6. If auth succeeds, call wrapped handler
       #
@@ -39,132 +39,231 @@ class Otto
         #
         # 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
         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
+          if auth_requirements.empty?
             # 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']
+            metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
 
-            result = StrategyResult.anonymous(metadata: metadata)
+            result = StrategyResult.anonymous(metadata: metadata, strategy_name: 'anonymous')
             env['otto.strategy_result'] = result
-            env['otto.user'] = nil
-            env['otto.user_context'] = result.user_context
             return wrapped_handler.call(env, extra_params)
           end
 
-          # Routes WITH auth requirement: Execute authentication strategy
-          strategy = get_strategy(auth_requirement)
+          # Routes WITH auth requirements: Try each strategy in order (first success wins)
 
-          unless strategy
-            Otto.logger.error "[RouteAuthWrapper] No strategy found for requirement: #{auth_requirement}"
-            return unauthorized_response(env, "Authentication strategy not configured")
+          # Validate all strategies exist before executing any (fail-fast)
+          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
           end
 
-          # Execute the strategy
-          result = strategy.authenticate(env, auth_requirement)
+          last_failure = nil
+          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
+              )
+            )
+
+            # 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
 
-          # 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']
+            # Handle authentication success (both authenticated and anonymous results) - return immediately
+            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)
+            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
 
-            env['otto.strategy_result'] = StrategyResult.anonymous(metadata: metadata)
-            env['otto.user'] = nil
-            env['otto.user_context'] = {}
-            return auth_failure_response(env, result)
+          # 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']
+
+          # 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
           end
 
-          # Set environment variables for controllers/logic on success
-          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)
+          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
+          ))
         end
 
         private
 
-        # Get strategy from auth_config hash with sophisticated pattern matching
+        # Get strategy from auth_config hash with 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
+        # - 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 [AuthStrategy, nil] Strategy instance or nil
+        # @return [Array<AuthStrategy, String>, Array<nil, nil>] Tuple of [strategy, name] or [nil, nil]
         def get_strategy(requirement)
-          return nil unless auth_config && auth_config[:auth_strategies]
+          return [nil, nil] unless auth_config && auth_config[:auth_strategies]
 
-          # Check cache first
+          # 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
-            @strategy_cache[requirement] = strategy
-            return strategy
+            result = [strategy, requirement]
+            @strategy_cache[requirement] = result
+            return result
           end
 
-          # For colon-separated requirements like "role:admin", try prefix match
+          # For colon-separated requirements like "custom:value", try prefix match
           if requirement.include?(':')
             prefix = requirement.split(':', 2).first
 
             # 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
-
-            # 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
+              result = [prefix_strategy, prefix]
+              @strategy_cache[requirement] = result
+              return result
             end
           end
 
           # Cache nil results too to avoid repeated failed lookups
-          @strategy_cache[requirement] = nil
-          nil
+          @strategy_cache[requirement] = [nil, nil]
+          [nil, nil]
         end
 
         # Generate 401 response for authentication failure
@@ -246,6 +345,59 @@ class Otto
           end
         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]]
+          else
+            headers = { 'content-type' => 'text/plain' }
+            merge_security_headers!(headers)
+            [403, headers, [message]]
+          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
+
+          # Try metadata
+          if result.metadata && result.metadata[:user_roles]
+            return Array(result.metadata[:user_roles])
+          end
+
+          # No roles found
+          []
+        end
+
         # Merge security headers into response headers
         #
         # @param headers [Hash] Response headers hash to merge into

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