otto 2.0.0.pre1 → 2.0.0.pre3

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

@@ -7,11 +7,11 @@
 
 require_relative 'authentication/auth_strategy'
 require_relative 'authentication/strategy_result'
-require_relative 'authentication/failure_result'
-require_relative 'authentication/authentication_middleware'
+require_relative 'authentication/auth_failure'
+require_relative 'authentication/route_auth_wrapper'
 
 # 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,15 +21,14 @@ 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
     PermissionStrategy = Authentication::Strategies::PermissionStrategy
-    AuthenticationMiddleware = Authentication::AuthenticationMiddleware
   end
 
   # Top-level backward compatibility aliases
   StrategyResult = Security::Authentication::StrategyResult
-  FailureResult = Security::Authentication::FailureResult
+  AuthFailure = Security::Authentication::AuthFailure
 end

data/lib/otto/security/config.rb

@@ -4,6 +4,7 @@
 
 require 'securerandom'
 require 'digest'
+require_relative '../core/freezable'
 
 class Otto
   module Security
@@ -23,12 +24,15 @@ class Otto
     #   config.max_request_size = 5 * 1024 * 1024  # 5MB
     #   config.max_param_depth = 16
     class Config
-      attr_accessor :csrf_protection, :csrf_token_key, :csrf_header_key, :csrf_session_key,
-                    :max_request_size, :max_param_depth, :max_param_keys,
-                    :trusted_proxies, :require_secure_cookies,
-                    :security_headers, :input_validation,
-                    :csp_nonce_enabled, :debug_csp, :mcp_auth,
-                    :rate_limiting_config
+      include Otto::Core::Freezable
+
+      attr_accessor :input_validation, :max_param_depth, :csrf_token_key, :rate_limiting_config, :csrf_session_key, :max_request_size, :max_param_keys
+
+      attr_reader :csrf_protection,  :csrf_header_key,
+                  :trusted_proxies, :require_secure_cookies,
+                  :security_headers,
+                  :csp_nonce_enabled, :debug_csp, :mcp_auth,
+                  :ip_privacy_config
 
       # Initialize security configuration with safe defaults
       #
@@ -48,7 +52,8 @@ class Otto
         @input_validation       = true
         @csp_nonce_enabled      = false
         @debug_csp              = false
-        @rate_limiting_config   = {}
+        @rate_limiting_config   = { custom_rules: {} }
+        @ip_privacy_config      = Otto::Privacy::Config.new
       end
 
       # Enable CSRF (Cross-Site Request Forgery) protection
@@ -60,14 +65,20 @@ class Otto
       # - Provide helper methods for forms and AJAX requests
       #
       # @return [void]
+      # @raise [FrozenError] if configuration is frozen
       def enable_csrf_protection!
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+
         @csrf_protection = true
       end
 
       # Disable CSRF protection
       #
       # @return [void]
+      # @raise [FrozenError] if configuration is frozen
       def disable_csrf_protection!
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+
         @csrf_protection = false
       end
 
@@ -86,6 +97,7 @@ class Otto
       #
       # @param proxy [String, Array] IP address, CIDR range, or array of addresses
       # @raise [ArgumentError] if proxy is not a String or Array
+      # @raise [FrozenError] if configuration is frozen
       # @return [void]
       #
       # @example Add single proxy
@@ -97,6 +109,8 @@ class Otto
       # @example Add multiple proxies
       #   config.add_trusted_proxy(['10.0.0.1', '172.16.0.0/12'])
       def add_trusted_proxy(proxy)
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+
         case proxy
         when String, Regexp
           @trusted_proxies << proxy
@@ -149,11 +163,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 +177,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
 
@@ -186,7 +189,10 @@ class Otto
       # @param max_age [Integer] Maximum age in seconds (default: 1 year)
       # @param include_subdomains [Boolean] Apply to all subdomains (default: true)
       # @return [void]
+      # @raise [FrozenError] if configuration is frozen
       def enable_hsts!(max_age: 31_536_000, include_subdomains: true)
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+
         hsts_value                                     = "max-age=#{max_age}"
         hsts_value                                    += '; includeSubDomains' if include_subdomains
         @security_headers['strict-transport-security'] = hsts_value
@@ -199,10 +205,13 @@ class Otto
       #
       # @param policy [String] CSP policy string (default: "default-src 'self'")
       # @return [void]
+      # @raise [FrozenError] if configuration is frozen
       #
       # @example Custom policy
       #   config.enable_csp!("default-src 'self'; script-src 'self' 'unsafe-inline'")
       def enable_csp!(policy = "default-src 'self'")
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+
         @security_headers['content-security-policy'] = policy
       end
 
@@ -214,10 +223,13 @@ class Otto
       #
       # @param debug [Boolean] Enable debug logging for CSP headers (default: false)
       # @return [void]
+      # @raise [FrozenError] if configuration is frozen
       #
       # @example
       #   config.enable_csp_with_nonce!(debug: true)
       def enable_csp_with_nonce!(debug: false)
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+
         @csp_nonce_enabled = true
         @debug_csp         = debug
       end
@@ -225,7 +237,10 @@ class Otto
       # Disable CSP nonce support
       #
       # @return [void]
+      # @raise [FrozenError] if configuration is frozen
       def disable_csp_nonce!
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+
         @csp_nonce_enabled = false
       end
 
@@ -257,7 +272,10 @@ class Otto
       #
       # @param option [String] Frame options: 'DENY', 'SAMEORIGIN', or 'ALLOW-FROM uri'
       # @return [void]
+      # @raise [FrozenError] if configuration is frozen
       def enable_frame_protection!(option = 'SAMEORIGIN')
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+
         @security_headers['x-frame-options'] = option
       end
 
@@ -265,6 +283,7 @@ class Otto
       #
       # @param headers [Hash] Hash of header name => value pairs
       # @return [void]
+      # @raise [FrozenError] if configuration is frozen
       #
       # @example
       #   config.set_custom_headers({
@@ -272,9 +291,23 @@ class Otto
       #     'cross-origin-opener-policy' => 'same-origin'
       #   })
       def set_custom_headers(headers)
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen?
+
         @security_headers.merge!(headers)
       end
 
+      # Override deep_freeze! to ensure rate_limiting_config has custom_rules initialized
+      #
+      # This pre-initializes any lazy values before freezing to prevent FrozenError
+      # when accessing configuration after it's frozen.
+      #
+      # @return [self] The frozen configuration
+      def deep_freeze!
+        # Ensure custom_rules is initialized (should already be done in constructor)
+        @rate_limiting_config[:custom_rules] ||= {}
+        super
+      end
+
       def get_or_create_session_id(request)
         # Try existing sources first
         session_id = extract_existing_session_id(request)

data/lib/otto/security/configurator.rb

@@ -4,7 +4,6 @@
 
 require_relative 'middleware/csrf_middleware'
 require_relative 'middleware/validation_middleware'
-require_relative 'authentication/authentication_middleware'
 require_relative 'middleware/rate_limit_middleware'
 
 # Security configuration facade for Otto framework
@@ -21,7 +20,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
@@ -75,7 +74,6 @@ class Otto
         enable_hsts! if hsts
         enable_csp! if csp
         enable_frame_protection! if frame_protection
-        enable_authentication! if authentication
       end
 
       # Enable CSRF protection for POST, PUT, DELETE, and PATCH requests.
@@ -118,7 +116,6 @@ class Otto
       # @option options [Integer] :period Time period in seconds (default: 60)
       # @option options [Proc] :condition Optional condition proc that receives request
       def add_rate_limit_rule(name, options)
-        @security_config.rate_limiting_config[:custom_rules] ||= {}
         @security_config.rate_limiting_config[:custom_rules][name.to_s] = options
       end
 
@@ -171,32 +168,22 @@ class Otto
         @security_config.enable_csp_with_nonce!(debug: debug)
       end
 
-      # Enable authentication middleware for route-level access control.
-      # This will automatically check route auth parameters and enforce authentication.
-      def enable_authentication!
-        return if middleware_enabled?(Otto::Security::Authentication::AuthenticationMiddleware)
-
-        @middleware_stack.add(Otto::Security::Authentication::AuthenticationMiddleware, @auth_config)
-      end
-
       # Add a single authentication strategy
       #
       # @param name [String] Strategy name
       # @param strategy [Otto::Security::Authentication::AuthStrategy] Strategy instance
       def add_auth_strategy(name, strategy)
         @auth_config[:auth_strategies][name] = strategy
-        enable_authentication!
       end
 
       # Configure authentication strategies for route-level access control.
       #
       # @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
-        enable_authentication! unless strategies.empty?
       end
 
       # Configure rate limiting settings.