otto 1.6.0 → 2.0.0.pre2

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# lib/otto/security/authentication/route_auth_wrapper.rb
+
+class Otto
+  module Security
+    module Authentication
+      # Wraps route handlers to enforce authentication requirements
+      #
+      # 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).
+      #
+      # 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
+      #   handler = InstanceMethodHandler.new(route_def, otto)
+      #   wrapped = RouteAuthWrapper.new(handler, route_def, auth_config)
+      #   wrapped.call(env, extra_params)
+      #
+      class RouteAuthWrapper
+        attr_reader :wrapped_handler, :route_definition, :auth_config
+
+        def initialize(wrapped_handler, route_definition, auth_config)
+          @wrapped_handler  = wrapped_handler
+          @route_definition = route_definition
+          @auth_config      = auth_config  # Hash: { auth_strategies: {}, default_auth_strategy: 'publicly' }
+        end
+
+        # Execute authentication then call wrapped handler
+        #
+        # @param env [Hash] Rack environment
+        # @param extra_params [Hash] Additional parameters
+        # @return [Array] Rack response array
+        def call(env, extra_params = {})
+          # Execute authentication strategy for this route
+          auth_requirement = route_definition.auth_requirement
+          strategy = get_strategy(auth_requirement)
+
+          unless strategy
+            Otto.logger.error "[RouteAuthWrapper] No strategy found for requirement: #{auth_requirement}"
+            return unauthorized_response(env, "Authentication strategy not configured")
+          end
+
+          # Execute the strategy
+          result = strategy.authenticate(env, auth_requirement)
+
+          # Set environment variables for controllers/logic
+          env['otto.strategy_result'] = result
+          env['otto.user'] = result.user if result.is_a?(StrategyResult)
+          env['otto.user_context'] = result.user_context if result.is_a?(StrategyResult)
+
+          # Handle authentication failure
+          if result.is_a?(FailureResult)
+            return auth_failure_response(env, result)
+          end
+
+          # Authentication succeeded - call wrapped handler
+          wrapped_handler.call(env, extra_params)
+        end
+
+        private
+
+        # Get strategy from auth_config hash
+        #
+        # @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]
+
+          auth_config[:auth_strategies][requirement]
+        end
+
+        # Generate 401 response for authentication failure
+        #
+        # @param env [Hash] Rack environment
+        # @param result [FailureResult] 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')
+
+          if wants_json
+            json_auth_error(result)
+          else
+            html_auth_error(result)
+          end
+        end
+
+        # Generate JSON 401 response
+        #
+        # @param result [FailureResult] 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
+
+          [
+            401,
+            { 'content-type' => 'application/json' },
+            [body]
+          ]
+        end
+
+        # Generate HTML 401 response or redirect
+        #
+        # @param result [FailureResult] 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'
+
+          [
+            302,
+            { 'location' => login_path },
+            ["Redirecting to #{login_path}"]
+          ]
+        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
+            [401, { 'content-type' => 'application/json' }, [body]]
+          else
+            [401, { 'content-type' => 'text/plain' }, [message]]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../auth_strategy'
+
+class Otto
+  module Security
+    module Authentication
+      module Strategies
+        # API key authentication strategy
+        class APIKeyStrategy < AuthStrategy
+          def initialize(api_keys: [], header_name: 'X-API-Key', param_name: 'api_key')
+            @api_keys = Array(api_keys)
+            @header_name = header_name
+            @param_name = param_name
+          end
+
+          def authenticate(env, _requirement)
+            # Try header first, then query parameter
+            api_key = env["HTTP_#{@header_name.upcase.tr('-', '_')}"]
+
+            if api_key.nil?
+              request = Rack::Request.new(env)
+              api_key = request.params[@param_name]
+            end
+
+            return failure('No API key provided') unless api_key
+
+            if @api_keys.empty? || @api_keys.include?(api_key)
+              # Create a simple user hash for API key authentication
+              user_data = { api_key: api_key }
+              success(user: user_data, api_key: api_key)
+            else
+              failure('Invalid API key')
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../auth_strategy'
+require_relative '../strategy_result'
+
+class Otto
+  module Security
+    module Authentication
+      module Strategies
+        # Public access strategy - always allows access
+        class NoAuthStrategy < AuthStrategy
+          def authenticate(env, _requirement)
+            Otto::Security::Authentication::StrategyResult.anonymous(metadata: { ip: env['REMOTE_ADDR'] })
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative '../auth_strategy'
+
+class Otto
+  module Security
+    module Authentication
+      module Strategies
+        # Permission-based authentication strategy
+        class PermissionStrategy < AuthStrategy
+          def initialize(required_permissions, session_key: 'user_permissions')
+            @required_permissions = Array(required_permissions)
+            @session_key = session_key
+          end
+
+          def authenticate(env, requirement)
+            session = env['rack.session']
+            return failure('No session available') unless session
+
+            user_permissions = session[@session_key] || []
+            user_permissions = Array(user_permissions)
+
+            # Create user data from session
+            user_data = { user_permissions: user_permissions, session: session }
+
+            # Extract permission from requirement (e.g., "permission:write" -> "write")
+            required_permission = requirement.split(':', 2).last
+
+            if user_permissions.include?(required_permission)
+              success(user: user_data, user_permissions: user_permissions, required_permission: required_permission)
+            else
+              failure("Insufficient privileges - requires permission: #{required_permission}")
+            end
+          end
+
+          def user_context(env)
+            session = env['rack.session']
+            return {} unless session
+
+            user_permissions = session[@session_key] || []
+            { user_permissions: Array(user_permissions) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../auth_strategy'
+
+class Otto
+  module Security
+    module Authentication
+      module Strategies
+        # Role-based authentication strategy
+        class RoleStrategy < AuthStrategy
+          def initialize(allowed_roles, session_key: 'user_roles')
+            @allowed_roles = Array(allowed_roles)
+            @session_key = session_key
+          end
+
+          def authenticate(env, requirement)
+            session = env['rack.session']
+            return failure('No session available') unless session
+
+            user_roles = session[@session_key] || []
+            user_roles = Array(user_roles)
+
+            # Create user data from session
+            user_data = { user_roles: user_roles, session: session }
+
+            # For requirements like "role:admin", extract the role part
+            if requirement.include?(':')
+              required_role = requirement.split(':', 2).last
+              if user_roles.include?(required_role)
+                success(user: user_data, user_roles: user_roles, required_role: required_role)
+              else
+                failure("Insufficient privileges - requires role: #{required_role}")
+              end
+            else
+              # For direct strategy matches, check if user has any of the allowed roles
+              matching_roles = user_roles & @allowed_roles
+              if matching_roles.any?
+                success(user: user_data, user_roles: user_roles, allowed_roles: @allowed_roles,
+                        matching_roles: matching_roles)
+              else
+                failure("Insufficient privileges - requires one of roles: #{@allowed_roles.join(', ')}")
+              end
+            end
+          end
+
+          def user_context(env)
+            session = env['rack.session']
+            return {} unless session
+
+            user_roles = session[@session_key] || []
+            { user_roles: Array(user_roles) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative '../auth_strategy'
+
+class Otto
+  module Security
+    module Authentication
+      module Strategies
+        # Session-based authentication strategy
+        class SessionStrategy < AuthStrategy
+          def initialize(session_key: 'user_id', session_store: nil)
+            @session_key = session_key
+            @session_store = session_store
+          end
+
+          def authenticate(env, _requirement)
+            session = env['rack.session']
+            return failure('No session available') unless session
+
+            user_id = session[@session_key]
+            return failure('Not authenticated') unless user_id
+
+            # Create a simple user hash for the generic strategy
+            user_data = { id: user_id, user_id: user_id }
+            success(session: session, user: user_data, auth_method: 'session')
+          end
+
+          def user_context(env)
+            session = env['rack.session']
+            return {} unless session
+
+            user_id = session[@session_key]
+            return {} unless user_id
+
+            { user_id: user_id }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+# lib/otto/security/authentication/strategy_result.rb
+
+# StrategyResult is an immutable data structure that holds the result of an
+# authentication strategy. It contains session, user, and metadata needed by
+# Otto Logic classes.
+#
+# @example Basic usage
+#   result = StrategyResult.new(
+#     session: { id: 'abc123', user_id: 1 },
+#     user: user_model_instance,  # Actual user model, not a hash
+#     auth_method: 'token',
+#     metadata: { ip: '127.0.0.1' }
+#   )
+#
+#   result.authenticated?  #=> true
+#   result.has_role?('admin')  #=> true
+#   result.user.name  #=> 'John' (assuming user model has name method)
+#
+class Otto
+  module Security
+    module Authentication
+      StrategyResult = Data.define(:session, :user, :auth_method, :metadata) do
+        # =====================================================================
+        # USAGE PATTERNS - READ THIS FIRST
+        # =====================================================================
+        #
+        # StrategyResult represents authentication state for a request.
+        # It serves TWO distinct purposes that must not be confused:
+        #
+        # 1. REQUEST STATE: Current session/user information
+        #    - Use `authenticated?` to check if session has a user
+        #    - Available on ALL requests (anonymous or authenticated)
+        #
+        # 2. AUTH ATTEMPT OUTCOME: Whether authentication just succeeded
+        #    - Use `auth_attempt_succeeded?` to check if auth strategy ran
+        #    - Only true when route had auth=... requirement AND succeeded
+        #
+        # CREATION PATTERNS
+        # -----------------
+        #
+        # StrategyResult should ONLY be created by:
+        #
+        # 1. Otto's AuthenticationMiddleware (automatic, route-based)
+        #    - Routes WITH auth=...: Creates result from strategy execution
+        #    - Routes WITHOUT auth=...: Creates anonymous result
+        #
+        # 2. Auth app router (manual, for Logic class compatibility)
+        #    - Manually builds StrategyResult for Roda routes
+        #    - Maintains same interface as Otto controllers
+        #
+        # APPLICATION CODE SHOULD NOT manually create StrategyResult!
+        # Instead, access session directly or rely on middleware.
+        #
+        # SESSION CONTRACT
+        # ----------------
+        #
+        # For multi-app architectures with shared session:
+        #
+        # Required session keys for authenticated state:
+        #   session['authenticated']     # Boolean flag
+        #   session['identity_id']       # User/customer ID
+        #   session['authenticated_at']  # Timestamp
+        #
+        # Optional session keys:
+        #   session['email']            # User email
+        #   session['ip_address']       # Client IP
+        #   session['user_agent']       # Client UA
+        #   session['locale']           # User locale
+        #
+        # Advanced mode adds:
+        #   session['account_external_id']  # Rodauth external_id
+        #   session['advanced_account_id']  # Rodauth account ID
+        #
+        # EXAMPLES
+        # --------
+        #
+        # Check if user in session (registration flow):
+        #   class CreateAccount
+        #     def raise_concerns
+        #       # Block registration if already logged in
+        #       raise FormError, "Already signed up" if @context.authenticated?
+        #     end
+        #   end
+        #
+        # Check if auth just succeeded (post-login redirect):
+        #   class LoginHandler
+        #     def process
+        #       if @context.auth_attempt_succeeded?
+        #         redirect_to dashboard_path
+        #       end
+        #     end
+        #   end
+        #
+        # Distinguish between the two:
+        #   @context.authenticated?           #=> true (user in session)
+        #   @context.auth_attempt_succeeded?  #=> false (no auth route)
+        #
+        #   # vs route with auth=session:
+        #   @context.authenticated?           #=> true (user in session)
+        #   @context.auth_attempt_succeeded?  #=> true (strategy just ran)
+        #
+        # =====================================================================
+
+        # Create an anonymous (unauthenticated) result
+        #
+        # Used by middleware for routes without auth requirements
+        # and by PublicStrategy for publicly accessible routes.
+        #
+        # @param metadata [Hash] Optional metadata (IP, user agent, etc.)
+        # @return [StrategyResult] Anonymous result with nil user
+        def self.anonymous(metadata: {})
+          new(
+            session: {},
+            user: nil,
+            auth_method: 'anonymous',
+            metadata: metadata
+          )
+        end
+
+        # Check if the request has an authenticated user in session
+        #
+        # This checks REQUEST STATE, not auth attempt outcome.
+        # Returns true if session contains a user, regardless of
+        # whether authentication just occurred or was from a previous request.
+        #
+        # @return [Boolean] True if user is present in session
+        # @example
+        #   # Block registration if user already logged in
+        #   raise FormError if @context.authenticated?
+        def authenticated?
+          !user.nil?
+        end
+
+        # Check if authentication strategy just executed and succeeded
+        #
+        # This checks AUTH ATTEMPT OUTCOME, not just session state.
+        # Returns true only when:
+        # 1. Route had an auth=... requirement (not anonymous/public)
+        # 2. Auth strategy executed
+        # 3. Authentication succeeded (user authenticated)
+        #
+        # @return [Boolean] True if auth strategy just succeeded
+        # @example
+        #   # Redirect after successful login
+        #   redirect_to dashboard if @context.auth_attempt_succeeded?
+        def auth_attempt_succeeded?
+          authenticated? && auth_method.to_s != 'anonymous'
+        end
+
+        # Check if the request is anonymous (no user in session)
+        #
+        # @return [Boolean] True if not authenticated
+        def anonymous?
+          user.nil?
+        end
+
+        # Check if the user has a specific role
+        #
+        # @param role [String, Symbol] Role to check
+        # @return [Boolean] True if user has the role
+        def has_role?(role)
+          return false unless authenticated?
+
+          # Try user model methods first, fall back to hash access for backward compatibility
+          if user.respond_to?(:role)
+            user.role.to_s == role.to_s
+          elsif user.respond_to?(:has_role?)
+            user.has_role?(role)
+          elsif user.is_a?(Hash)
+            user_role = user[:role] || user['role']
+            user_role.to_s == role.to_s
+          else
+            false
+          end
+        end
+
+        # Check if the user has a specific permission
+        #
+        # @param permission [String, Symbol] Permission to check
+        # @return [Boolean] True if user has the permission
+        def has_permission?(permission)
+          return false unless authenticated?
+
+          # Try user model methods first, fall back to hash access for backward compatibility
+          if user.respond_to?(:has_permission?)
+            user.has_permission?(permission)
+          elsif user.respond_to?(:permissions)
+            permissions = user.permissions || []
+            permissions = [permissions] unless permissions.is_a?(Array)
+            permissions.map(&:to_s).include?(permission.to_s)
+          elsif user.is_a?(Hash)
+            permissions = user[:permissions] || user['permissions'] || []
+            permissions = [permissions] unless permissions.is_a?(Array)
+            permissions.map(&:to_s).include?(permission.to_s)
+          else
+            false
+          end
+        end
+
+        # Check if the user has any of the specified roles
+        #
+        # @param roles [Array<String, Symbol>] Roles to check
+        # @return [Boolean] True if user has any of the roles
+        def has_any_role?(*roles)
+          roles.flatten.any? { |role| has_role?(role) }
+        end
+
+        # Check if the user has any of the specified permissions
+        #
+        # @param permissions [Array<String, Symbol>] Permissions to check
+        # @return [Boolean] True if user has any of the permissions
+        def has_any_permission?(*permissions)
+          permissions.flatten.any? { |permission| has_permission?(permission) }
+        end
+
+        # Get user ID from various possible locations
+        #
+        # @return [String, Integer, nil] User ID or nil
+        def user_id
+          return nil unless authenticated?
+
+          # Try user model methods first, fall back to hash access and session
+          if user.respond_to?(:id)
+            user.id
+          elsif user.respond_to?(:user_id)
+            user.user_id
+          elsif user.is_a?(Hash)
+            user[:id] || user['id'] || user[:user_id] || user['user_id']
+          end || session[:user_id] || session['user_id']
+        end
+
+        # Get user name from various possible locations
+        #
+        # @return [String, nil] User name or nil
+        def user_name
+          return nil unless authenticated?
+
+          # Try user model methods first, fall back to hash access
+          if user.respond_to?(:name)
+            user.name
+          elsif user.respond_to?(:username)
+            user.username
+          elsif user.is_a?(Hash)
+            user[:name] || user['name'] || user[:username] || user['username']
+          end
+        end
+
+        # Get session ID from various possible locations
+        #
+        # @return [String, nil] Session ID or nil
+        def session_id
+          session[:id] || session['id'] || session[:session_id] || session['session_id']
+        end
+
+        # Get all user roles as an array
+        #
+        # @return [Array<String>] Array of roles (empty if none)
+        def roles
+          return [] unless authenticated?
+
+          roles_data = user[:roles] || user['roles']
+          if roles_data.is_a?(Array)
+            roles_data.map(&:to_s)
+          elsif roles_data
+            [roles_data.to_s]
+          else
+            role = user[:role] || user['role']
+            role ? [role.to_s] : []
+          end
+        end
+
+        # Get all user permissions as an array
+        #
+        # @return [Array<String>] Array of permissions (empty if none)
+        def permissions
+          return [] unless authenticated?
+
+          perms = user[:permissions] || user['permissions'] || []
+          perms = [perms] unless perms.is_a?(Array)
+          perms.map(&:to_s)
+        end
+
+        # Create a string representation for debugging
+        #
+        # @return [String] Debug representation
+        def inspect
+          if authenticated?
+            "#<StrategyResult authenticated user=#{user_name || user_id} roles=#{roles} method=#{auth_method}>"
+          else
+            "#<StrategyResult anonymous method=#{auth_method}>"
+          end
+        end
+
+        # Get user context - a hash containing user-specific information and metadata
+        #
+        # @return [Hash] User context hash
+        def user_context
+          if authenticated?
+            case auth_method
+            when 'session'
+              { user_id: user_id, session: session }
+            else
+              metadata
+            end
+          else
+            case auth_method
+            when 'anonymous'
+              {}
+            else
+              metadata
+            end
+          end
+        end
+
+        # Create a hash representation
+        #
+        # @return [Hash] Hash representation of the context
+        def to_h
+          {
+            session: session,
+            user: user,
+            auth_method: auth_method,
+            metadata: metadata,
+            authenticated: authenticated?,
+            auth_attempt_succeeded: auth_attempt_succeeded?,
+            user_id: user_id,
+            user_name: user_name,
+            roles: roles,
+            permissions: permissions
+          }
+        end
+      end
+    end
+  end
+end