otto 2.0.0.pre1 → 2.0.0.pre2

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

@@ -7,26 +7,34 @@ class Otto
     module Authentication
       # Failure result for authentication failures
       FailureResult = Data.define(:failure_reason, :auth_method) do
-        def success?
-          false
-        end
-
-        def failure?
-          true
-        end
+        # FailureResult represents authentication failure
+        # Returned by strategies when authentication fails
+        # Contains failure reason for error messages
 
+        # Check if authenticated - always false for failures
+        #
+        # @return [Boolean] False (failures are never authenticated)
         def authenticated?
           false
         end
 
+        # Check if anonymous - always true for failures
+        #
+        # @return [Boolean] True (failures have no user)
         def anonymous?
           true
         end
 
+        # Get empty user context for failures
+        #
+        # @return [Hash] Empty hash
         def user_context
           {}
         end
 
+        # Create a string representation for debugging
+        #
+        # @return [String] Debug representation
         def inspect
           "#<FailureResult reason=#{failure_reason.inspect} method=#{auth_method}>"
         end

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/{public_strategy.rb → noauth_strategy.rb}

@@ -8,7 +8,7 @@ class Otto
     module Authentication
       module Strategies
         # Public access strategy - always allows access
-        class PublicStrategy < AuthStrategy
+        class NoAuthStrategy < AuthStrategy
           def authenticate(env, _requirement)
             Otto::Security::Authentication::StrategyResult.anonymous(metadata: { ip: env['REMOTE_ADDR'] })
           end

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

@@ -22,40 +22,142 @@ 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
-        # @return [StrategyResult] Anonymous result with empty session and nil user
+        #
+        # 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,  # Changed from {} to nil - clearer semantics
+            user: nil,
             auth_method: 'anonymous',
             metadata: metadata
           )
         end
 
-        # Check if the request is authenticated (has a user)
-        # @return [Boolean] True if user is present, false otherwise
+        # 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 the request is anonymous (no user)
+        # 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
 
-        # Success/failure methods for compatibility
-        def success?
-          true  # If we have a StrategyResult, authentication succeeded
-        end
-
-        def failure?
-          false  # Failures return nil, not a StrategyResult
-        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)
@@ -75,6 +177,7 @@ class Otto
         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)
@@ -97,6 +200,7 @@ class Otto
         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)
@@ -104,6 +208,7 @@ class Otto
         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)
@@ -111,6 +216,7 @@ class Otto
         end
 
         # Get user ID from various possible locations
+        #
         # @return [String, Integer, nil] User ID or nil
         def user_id
           return nil unless authenticated?
@@ -126,6 +232,7 @@ class Otto
         end
 
         # Get user name from various possible locations
+        #
         # @return [String, nil] User name or nil
         def user_name
           return nil unless authenticated?
@@ -141,12 +248,14 @@ class Otto
         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?
@@ -163,6 +272,7 @@ class Otto
         end
 
         # Get all user permissions as an array
+        #
         # @return [Array<String>] Array of permissions (empty if none)
         def permissions
           return [] unless authenticated?
@@ -173,6 +283,7 @@ class Otto
         end
 
         # Create a string representation for debugging
+        #
         # @return [String] Debug representation
         def inspect
           if authenticated?
@@ -183,6 +294,7 @@ class Otto
         end
 
         # Get user context - a hash containing user-specific information and metadata
+        #
         # @return [Hash] User context hash
         def user_context
           if authenticated?
@@ -203,6 +315,7 @@ class Otto
         end
 
         # Create a hash representation
+        #
         # @return [Hash] Hash representation of the context
         def to_h
           {
@@ -211,6 +324,7 @@ class Otto
             auth_method: auth_method,
             metadata: metadata,
             authenticated: authenticated?,
+            auth_attempt_succeeded: auth_attempt_succeeded?,
             user_id: user_id,
             user_name: user_name,
             roles: roles,

data/lib/otto/security/authentication.rb

@@ -11,7 +11,7 @@ require_relative 'authentication/failure_result'
 require_relative 'authentication/authentication_middleware'
 
 # Load all strategies
-require_relative 'authentication/strategies/public_strategy'
+require_relative 'authentication/strategies/noauth_strategy'
 require_relative 'authentication/strategies/session_strategy'
 require_relative 'authentication/strategies/role_strategy'
 require_relative 'authentication/strategies/api_key_strategy'
@@ -21,7 +21,7 @@ class Otto
   module Security
     # Backward compatibility aliases for the old namespace
     AuthStrategy = Authentication::AuthStrategy
-    PublicStrategy = Authentication::Strategies::PublicStrategy
+    NoAuthStrategy = Authentication::Strategies::NoAuthStrategy
     SessionStrategy = Authentication::Strategies::SessionStrategy
     RoleStrategy = Authentication::Strategies::RoleStrategy
     APIKeyStrategy = Authentication::Strategies::APIKeyStrategy

data/lib/otto/security/config.rb

@@ -149,11 +149,6 @@ class Otto
         signature  = Digest::SHA256.hexdigest(hash_input)
         csrf_token = "#{token}:#{signature}"
 
-        puts '=== CSRF Generation ==='
-        puts "hash_input: #{hash_input.inspect}"
-        puts "signature: #{signature}"
-        puts "csrf_token: #{csrf_token}"
-
         csrf_token
       end
 
@@ -168,12 +163,6 @@ class Otto
         expected_signature = Digest::SHA256.hexdigest(hash_input)
         comparison_result  = secure_compare(signature, expected_signature)
 
-        puts '=== CSRF Verification ==='
-        puts "hash_input: #{hash_input.inspect}"
-        puts "received_signature: #{signature}"
-        puts "expected_signature: #{expected_signature}"
-        puts "match: #{comparison_result}"
-
         comparison_result
       end
 

data/lib/otto/security/configurator.rb

@@ -21,7 +21,7 @@ class Otto
         @security_config = security_config
         @middleware_stack = middleware_stack
         # Use provided auth_config or initialize a new one
-        @auth_config = auth_config || { auth_strategies: {}, default_auth_strategy: 'publicly' }
+        @auth_config = auth_config || { auth_strategies: {}, default_auth_strategy: 'noauth' }
       end
 
       # Unified security configuration method with sensible defaults
@@ -192,7 +192,7 @@ class Otto
       #
       # @param strategies [Hash] Hash mapping strategy names to strategy instances
       # @param default_strategy [String] Default strategy to use when none specified
-      def configure_auth_strategies(strategies, default_strategy: 'publicly')
+      def configure_auth_strategies(strategies, default_strategy: 'noauth')
         # Merge new strategies with existing ones, preserving shared state
         @auth_config[:auth_strategies].merge!(strategies)
         @auth_config[:default_auth_strategy] = default_strategy

data/lib/otto/security/middleware/rate_limit_middleware.rb

@@ -7,6 +7,21 @@ class Otto
     module Middleware
       # Middleware for applying rate limiting to HTTP requests
       class RateLimitMiddleware
+        # NOTE: This middleware is a CONFIGURATOR, not an enforcer.
+        #
+        # Actual rate limiting is performed by Rack::Attack globally via
+        # configure_rack_attack!. This middleware registers during initialization
+        # and then passes through all requests.
+        #
+        # To enforce rate limits, Rack::Attack must be added to the middleware
+        # stack BEFORE Otto's router (typically done by the hosting application).
+        #
+        # Example (config.ru):
+        #   use Rack::Attack  # Must come before Otto
+        #   run otto
+        #
+        # The call method is a pass-through; rate limiting happens in Rack::Attack.
+
         def initialize(app, security_config = nil)
           @app = app
           @security_config = security_config
@@ -19,10 +34,11 @@ class Otto
           end
         end
 
+        # Pass-through call - actual rate limiting handled by Rack::Attack
+        #
+        # This middleware does not enforce limits itself. It configures
+        # Rack::Attack during initialization, then delegates all requests.
         def call(env)
-          return @app.call(env) unless @rate_limiter_available
-
-          # Let rack-attack handle the rate limiting
           @app.call(env)
         end
 

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # lib/otto/version.rb
 
 class Otto
-  VERSION = '2.0.0.pre1'
+  VERSION = '2.0.0.pre2'
 end

data/lib/otto.rb

@@ -57,7 +57,6 @@ require_relative 'otto/utils'
 #   otto.enable_frame_protection!
 #
 # Configuration Data class to replace OpenStruct
-# Configuration Data class to replace OpenStruct
 # Configuration class to replace OpenStruct
 class ConfigData
   def initialize(**kwargs)
@@ -311,7 +310,7 @@ class Otto
   #   otto.add_auth_strategy('custom', MyCustomStrategy.new)
   def add_auth_strategy(name, strategy)
     # Ensure auth_config is initialized (handles edge case where it might be nil)
-    @auth_config = { auth_strategies: {}, default_auth_strategy: 'publicly' } if @auth_config.nil?
+    @auth_config = { auth_strategies: {}, default_auth_strategy: 'noauth' } if @auth_config.nil?
 
     @auth_config[:auth_strategies][name] = strategy
 
@@ -349,7 +348,7 @@ class Otto
     @security_config   = Otto::Security::Config.new
     @middleware        = Otto::Core::MiddlewareStack.new
     # Initialize @auth_config first so it can be shared with the configurator
-    @auth_config       = { auth_strategies: {}, default_auth_strategy: 'publicly' }
+    @auth_config       = { auth_strategies: {}, default_auth_strategy: 'noauth' }
     @security          = Otto::Security::Configurator.new(@security_config, @middleware, @auth_config)
   end
 

data/otto.gemspec

@@ -16,6 +16,8 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ['>= 3.2', '< 4.0']
 
+  # Logger is not part of the default gems as of Ruby 3.5.0
+  spec.add_dependency 'logger', '~> 1', '< 2.0'
 
   spec.add_dependency 'rack', '~> 3.1', '< 4.0'
   spec.add_dependency 'rack-parser', '~> 0.7'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre1
+  version: 2.0.0.pre2
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -9,6 +9,26 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -107,13 +127,11 @@ files:
 - LICENSE.txt
 - README.md
 - bin/rspec
-- changelog.d/20250911_235619_delano_next.rst
-- changelog.d/20250912_123055_delano_remove_ostruct.rst
-- changelog.d/20250912_175625_claude_delano_remove_ostruct.rst
 - changelog.d/README.md
 - changelog.d/scriv.ini
 - docs/.gitignore
 - docs/migrating/v2.0.0-pre1.md
+- docs/migrating/v2.0.0-pre2.md
 - examples/.gitignore
 - examples/advanced_routes/README.md
 - examples/advanced_routes/app.rb
@@ -175,6 +193,7 @@ files:
 - lib/otto/core/router.rb
 - lib/otto/core/uri_generator.rb
 - lib/otto/design_system.rb
+- lib/otto/env_keys.rb
 - lib/otto/helpers/base.rb
 - lib/otto/helpers/request.rb
 - lib/otto/helpers/response.rb
@@ -184,8 +203,8 @@ files:
 - lib/otto/mcp/rate_limiting.rb
 - lib/otto/mcp/registry.rb
 - lib/otto/mcp/route_parser.rb
+- lib/otto/mcp/schema_validation.rb
 - lib/otto/mcp/server.rb
-- lib/otto/mcp/validation.rb
 - lib/otto/response_handlers.rb
 - lib/otto/response_handlers/auto.rb
 - lib/otto/response_handlers/base.rb
@@ -207,9 +226,10 @@ files:
 - lib/otto/security/authentication/auth_strategy.rb
 - lib/otto/security/authentication/authentication_middleware.rb
 - lib/otto/security/authentication/failure_result.rb
+- lib/otto/security/authentication/route_auth_wrapper.rb
 - lib/otto/security/authentication/strategies/api_key_strategy.rb
+- lib/otto/security/authentication/strategies/noauth_strategy.rb
 - lib/otto/security/authentication/strategies/permission_strategy.rb
-- lib/otto/security/authentication/strategies/public_strategy.rb
 - lib/otto/security/authentication/strategies/role_strategy.rb
 - lib/otto/security/authentication/strategies/session_strategy.rb
 - lib/otto/security/authentication/strategy_result.rb