otto 2.0.0.pre1 → 2.0.0.pre3

data/docs/migrating/v2.0.0-pre2.md

@@ -0,0 +1,338 @@
+# Otto v2.0.0-pre2 Migration Guide
+
+## Overview
+
+This release resolves critical architectural issues with `StrategyResult` semantics and removes deprecated methods. The changes clarify the distinction between "request state" (user in session) and "authentication outcomes" (auth attempt just succeeded).
+
+## Breaking Changes
+
+### 1. StrategyResult Methods Removed
+
+**Removed Methods:**
+- `StrategyResult#success?` - Always returned `true`, meaningless
+- `StrategyResult#failure?` - Always returned `false`, meaningless
+- `FailureResult#success?` - Always returned `false`
+- `FailureResult#failure?` - Always returned `true`
+
+**Migration:**
+
+```ruby
+# Before - checking success/failure
+if strategy_result&.success?
+  # handle success
+end
+
+# After - type checking
+if strategy_result.is_a?(Otto::Security::Authentication::StrategyResult)
+  # handle success
+end
+
+```
+
+### 2. New Semantic Distinction
+
+**New Method:**
+- `StrategyResult#auth_attempt_succeeded?` - Returns `true` only when auth strategy just executed successfully
+
+**Key Semantic Difference:**
+
+| Method | Meaning | Use Case |
+|--------|---------|----------|
+| `authenticated?` | User in session (request state) | Check if session has user |
+| `auth_attempt_succeeded?` | Auth strategy just succeeded (auth outcome) | Post-login redirects, analytics |
+
+**Migration Examples:**
+
+#### Registration Flow (IMPORTANT)
+
+```ruby
+# Before - BROKEN - blocks legitimate registration
+class CreateAccount < Logic::Base
+  def raise_concerns
+    # This was always true if user in session, blocking registration
+    raise OT::FormError, "Already signed up" if @strategy_result.success?
+  end
+end
+
+# After - CORRECT
+class CreateAccount < Logic::Base
+  def raise_concerns
+    # Check if user already in session
+    raise OT::FormError, "Already signed up" if @strategy_result.authenticated?
+  end
+end
+```
+
+#### Post-Login Redirect
+
+```ruby
+# Before - unreliable
+class AuthController
+  def authenticate
+    if @strategy_result.success?  # Always true, not helpful
+      redirect_to dashboard_path
+    end
+  end
+end
+
+# After - correct semantic
+class AuthController
+  def authenticate
+    if @strategy_result.auth_attempt_succeeded?
+      # Only redirect when auth route just succeeded
+      redirect_to dashboard_path
+    end
+  end
+end
+```
+
+## Non-Breaking Enhancements
+
+### 1. Comprehensive Documentation
+
+`StrategyResult` now includes extensive inline documentation:
+- Usage patterns and creation guidelines
+- Session contract for multi-app architectures
+- Examples for common scenarios
+- Clear distinction between request state and auth outcomes
+
+### 2. Session Contract (Multi-App Architectures)
+
+For shared session architectures (Auth app + Core app):
+
+**Required session keys for authenticated state:**
+```ruby
+session['authenticated']     # Boolean flag
+session['identity_id']       # User/customer ID
+session['authenticated_at']  # Timestamp
+```
+
+**Optional session keys:**
+```ruby
+session['email']            # User email
+session['ip_address']       # Client IP (masked by default via IPPrivacyMiddleware)
+session['user_agent']       # Client UA
+session['locale']           # User locale
+```
+
+**Advanced mode adds:**
+```ruby
+session['account_external_id']  # Rodauth external_id
+session['advanced_account_id']  # Rodauth account ID
+```
+
+## Application Code Updates Required
+
+### 1. Remove Manual StrategyResult Creation
+
+**Anti-pattern identified:**
+```ruby
+# BAD - Bypasses Otto's auth_method tracking
+class Controller::Base
+  def _strategy_result
+    Otto::Security::Authentication::StrategyResult.new(
+      session: session,
+      user: cust,
+      auth_method: 'session',  # Hardcoded - loses semantic meaning
+      metadata: { ip: req.masked_ip }  # Uses masked IP (privacy by default)
+    )
+  end
+end
+```
+
+**Correct approach:**
+```ruby
+# GOOD - Use RouteAuthWrapper-provided result
+class Controller::Base
+  def strategy_result
+    req.env['otto.strategy_result']  # Created by RouteAuthWrapper
+  end
+end
+
+# Or for non-auth checks, use session directly
+class Controller::Base
+  def current_user
+    return nil unless session['authenticated']
+    Customer.find(session['identity_id'])
+  end
+end
+```
+
+### 2. Update Logic Classes
+
+**Pattern to check for:**
+```ruby
+# Search your codebase for these patterns:
+grep -r "@strategy_result.success?" apps/
+grep -r "@context.success?" apps/
+grep -r "strategy_result&.success?" apps/
+```
+
+**Update to:**
+- Use `authenticated?` for "user in session" checks (registration, profile access, etc.)
+- Use `auth_attempt_succeeded?` for "just logged in" checks (redirects, welcome messages, etc.)
+
+### 3. Test Updates
+
+**RSpec matchers:**
+```ruby
+# Before
+expect(result).to be_success
+expect(result).to be_failure
+
+# After
+expect(result).to be_a(Otto::Security::Authentication::StrategyResult)
+```
+
+## Architecture Clarifications
+
+### When StrategyResult is Created
+
+1. **Routes WITH `auth=...` requirement:**
+   - RouteAuthWrapper executes strategy
+   - Always returns `StrategyResult` (success or failure)
+   - RouteAuthWrapper returns 401/302 response on `AuthFailure`
+
+2. **Routes WITHOUT `auth=...` requirement:**
+   - No RouteAuthWrapper wrapping
+   - No `StrategyResult` created (routes without auth don't need it)
+
+3. **Auth app (Roda) routes:**
+   - Manually creates `StrategyResult` for Logic class compatibility
+   - Same interface as Otto controllers
+
+### Integration Boundaries
+
+**Multi-app setup (Auth + Core + API):**
+- **Shared:** Session middleware, Redis session, Logic classes, Customer model
+- **Auth app:** Creates StrategyResult manually, uses Roda routing
+- **Core/API apps:** StrategyResult from RouteAuthWrapper
+- **Integration:** Pure session-based, no direct code calls between apps
+
+## Testing Your Migration
+
+### 1. Registration Flow Test
+
+```ruby
+describe "CreateAccount" do
+  it "blocks registration when user already authenticated" do
+    strategy_result = Otto::Security::Authentication::StrategyResult.new(
+      session: { user_id: 123 },
+      user: { id: 123 },
+      auth_method: 'anonymous',  # No auth route, but user in session
+      metadata: {}
+    )
+
+    logic = CreateAccount.new(strategy_result, params, 'en')
+
+    expect { logic.raise_concerns }.to raise_error(OT::FormError, /Already signed up/)
+  end
+end
+```
+
+### 2. Auth Attempt Test
+
+```ruby
+describe "LoginHandler" do
+  it "redirects after successful authentication" do
+    strategy_result = Otto::Security::Authentication::StrategyResult.new(
+      session: { user_id: 123 },
+      user: { id: 123 },
+      auth_method: 'session',  # Auth route succeeded
+      metadata: {}
+    )
+
+    expect(strategy_result.authenticated?).to be true
+    expect(strategy_result.auth_attempt_succeeded?).to be true
+  end
+end
+```
+
+## Checklist
+
+- [ ] Remove all usage of `success?` and `failure?` methods
+- [ ] Update registration flows to use `authenticated?`
+- [ ] Update post-login flows to use `auth_attempt_succeeded?` if needed
+- [ ] Remove manual `StrategyResult` creation in controllers
+- [ ] Update test matchers from `be_success`/`be_failure` to type checks
+- [ ] Verify session contract keys match across apps
+- [ ] Run full test suite: `bundle exec rspec`
+- [ ] Test registration while logged in (should be blocked)
+- [ ] Test login redirect flow (should work correctly)
+
+## Configuration Updates
+
+### Authentication Login Path Configuration
+
+When authentication fails for HTML requests, Otto redirects to a login page. You can configure this path:
+
+```ruby
+# Initialize with login_path configuration
+otto = Otto.new do
+  auth_config[:login_path] = '/auth/login'  # Default: '/signin'
+end
+
+# Or configure after initialization
+otto.auth_config[:login_path] = '/custom/login'
+```
+
+**Note:** If not configured, the default fallback is `/signin`. Ensure this route exists or configure your actual login path to avoid 404 errors on authentication failures.
+
+## Additional Improvements in v2.0.0-pre2
+
+### Middleware Architecture Enhancements
+
+**1. Renamed MCP ValidationMiddleware → SchemaValidationMiddleware**
+- Resolves naming collision with `Otto::Security::ValidationMiddleware`
+- `Otto::MCP::SchemaValidationMiddleware` now clearly indicates JSON schema validation
+- `Otto::Security::ValidationMiddleware` remains for input sanitization
+
+**Migration:**
+```ruby
+# File renamed: lib/otto/mcp/validation.rb → lib/otto/mcp/schema_validation.rb
+# Class renamed automatically if using Otto's MCP server
+# No action needed for most users
+```
+
+**2. Centralized Env Keys Documentation**
+- New file: `lib/otto/env_keys.rb`
+- Documents all `env['otto.*']` keys with types, setters, and users
+- Includes usage examples and multi-app integration patterns
+- Essential reference for custom middleware development
+
+**3. RateLimitMiddleware Clarity**
+- Added documentation clarifying it's a CONFIGURATOR, not enforcer
+- Actual rate limiting happens in Rack::Attack middleware
+- `call` method is explicitly a pass-through
+
+**4. Middleware Order Enforcement**
+- New method: `MiddlewareStack#validate_mcp_middleware_order`
+- New method: `MiddlewareStack#add_with_position` for explicit ordering
+- MCP Server uses explicit positioning: `position: :first` and `position: :last`
+- Validates middleware order and warns if suboptimal
+- Optimal: RateLimitMiddleware → TokenMiddleware → SchemaValidationMiddleware
+- Validation runs automatically when MCP is enabled
+
+**Usage Example:**
+```ruby
+# Explicit positioning for clarity
+middleware.add_with_position(
+  Otto::MCP::RateLimitMiddleware,
+  security_config,
+  position: :first  # Ensures rate limiting runs first
+)
+
+middleware.add_with_position(
+  Otto::MCP::SchemaValidationMiddleware,
+  position: :last  # Ensures validation runs last
+)
+```
+
+## Questions?
+
+Review the comprehensive inline documentation in:
+- `lib/otto/security/authentication/strategy_result.rb` (lines 1-90) - Auth semantics
+- `lib/otto/security/authentication/route_auth_wrapper.rb` - Auth handler wrapper
+- `lib/otto/env_keys.rb` - Complete env key registry
+
+The documentation includes detailed usage patterns, session contracts, and examples for common scenarios.

data/examples/authentication_strategies/config.ru

@@ -12,7 +12,6 @@ otto = Otto.new('routes')
 # Enable security features to demonstrate advanced route parameters
 otto.enable_csrf_protection!
 otto.enable_request_validation!
-otto.enable_authentication!
 
 # Load and configure authentication strategies
 AuthenticationSetup.configure(otto)

data/lib/otto/core/configuration.rb

@@ -7,52 +7,37 @@ require_relative '../security/validator'
 require_relative '../security/authentication'
 require_relative '../security/rate_limiting'
 require_relative '../mcp/server'
+require_relative 'freezable'
 
 class Otto
   module Core
     # Configuration module providing locale and application configuration methods
     module Configuration
+      include Otto::Core::Freezable
       def configure_locale(opts)
-        # Start with global configuration
-        global_config = self.class.global_config
-        @locale_config = nil
-
-        # Check if we have any locale configuration from any source
-        has_global_locale = global_config && (global_config[:available_locales] || global_config[:default_locale])
+        # Check if we have any locale configuration
         has_direct_options = opts[:available_locales] || opts[:default_locale]
         has_legacy_config = opts[:locale_config]
 
-        # Only create locale_config if we have configuration from somewhere
-        return unless has_global_locale || has_direct_options || has_legacy_config
+        # Only create locale_config if we have configuration
+        return unless has_direct_options || has_legacy_config
 
-        @locale_config = {}
+        # Initialize with direct options
+        available_locales = opts[:available_locales]
+        default_locale = opts[:default_locale]
 
-        # Apply global configuration first
-        if global_config && global_config[:available_locales]
-          @locale_config[:available_locales] =
-            global_config[:available_locales]
-        end
-        if global_config && global_config[:default_locale]
-          @locale_config[:default_locale] =
-            global_config[:default_locale]
+        # Legacy support: Configure locale if provided via locale_config hash
+        if opts[:locale_config]
+          locale_opts = opts[:locale_config]
+          available_locales ||= locale_opts[:available_locales] || locale_opts[:available]
+          default_locale ||= locale_opts[:default_locale] || locale_opts[:default]
         end
 
-        # Apply direct instance options (these override global config)
-        @locale_config[:available_locales] = opts[:available_locales] if opts[:available_locales]
-        @locale_config[:default_locale] = opts[:default_locale] if opts[:default_locale]
-
-        # Legacy support: Configure locale if provided in initialization options via locale_config hash
-        return unless opts[:locale_config]
-
-        locale_opts = opts[:locale_config]
-        if locale_opts[:available_locales] || locale_opts[:available]
-          @locale_config[:available_locales] =
-            locale_opts[:available_locales] || locale_opts[:available]
-        end
-        return unless locale_opts[:default_locale] || locale_opts[:default]
-
-        @locale_config[:default_locale] =
-          locale_opts[:default_locale] || locale_opts[:default]
+        # Create Otto::Locale::Config instance
+        @locale_config = Otto::Locale::Config.new(
+          available_locales: available_locales,
+          default_locale: default_locale
+        )
       end
 
       def configure_security(opts)
@@ -86,7 +71,6 @@ class Otto
         # Enable authentication middleware if strategies are configured
         return unless opts[:auth_strategies] && !opts[:auth_strategies].empty?
 
-        enable_authentication!
       end
 
       def configure_mcp(opts)
@@ -115,9 +99,14 @@ class Otto
       #     default_locale: 'en'
       #   )
       def configure(available_locales: nil, default_locale: nil)
-        @locale_config ||= {}
-        @locale_config[:available_locales] = available_locales if available_locales
-        @locale_config[:default_locale] = default_locale if default_locale
+        ensure_not_frozen!
+
+        # Initialize locale_config if not already set
+        @locale_config ||= Otto::Locale::Config.new
+
+        # Update configuration
+        @locale_config.available_locales = available_locales if available_locales
+        @locale_config.default_locale = default_locale if default_locale
       end
 
       # Configure rate limiting settings.
@@ -134,6 +123,7 @@ class Otto
       #     }
       #   })
       def configure_rate_limiting(config)
+        ensure_not_frozen!
         @security_config.rate_limiting_config.merge!(config)
       end
 
@@ -143,20 +133,80 @@ class Otto
       # @param default_strategy [String] Default strategy to use when none specified
       # @example
       #   otto.configure_auth_strategies({
-      #     'publicly' => Otto::Security::Authentication::Strategies::PublicStrategy.new,
+      #     'noauth' => Otto::Security::Authentication::Strategies::NoAuthStrategy.new,
       #     'authenticated' => Otto::Security::Authentication::Strategies::SessionStrategy.new(session_key: 'user_id'),
       #     'role:admin' => Otto::Security::Authentication::Strategies::RoleStrategy.new(['admin']),
       #     'api_key' => Otto::Security::Authentication::Strategies::APIKeyStrategy.new(api_keys: ['secret123'])
       #   })
-      def configure_auth_strategies(strategies, default_strategy: 'publicly')
+      def configure_auth_strategies(strategies, default_strategy: 'noauth')
+        ensure_not_frozen!
         # Update existing @auth_config rather than creating a new one
         @auth_config[:auth_strategies] = strategies
         @auth_config[:default_auth_strategy] = default_strategy
 
-        enable_authentication! unless strategies.empty?
       end
 
-      private
+      # Freeze the application configuration to prevent runtime modifications.
+      # Called automatically at the end of initialization to ensure immutability.
+      #
+      # This prevents security-critical configuration from being modified after
+      # the application begins handling requests. Uses deep freezing to prevent
+      # both direct modification and modification through nested structures.
+      #
+      # @raise [RuntimeError] if configuration is already frozen
+      # @return [self]
+      def freeze_configuration!
+        if frozen_configuration?
+          Otto.logger.debug '[Otto::Configuration] Configuration already frozen, skipping' if Otto.debug
+          return self
+        end
+
+        Otto.logger.debug '[Otto::Configuration] Starting configuration freeze process' if Otto.debug
+
+        # Deep freeze configuration objects with memoization support
+        Otto.logger.debug '[Otto::Configuration] Freezing security_config' if Otto.debug
+        @security_config.deep_freeze! if @security_config.respond_to?(:deep_freeze!)
+
+        Otto.logger.debug '[Otto::Configuration] Freezing locale_config' if Otto.debug
+        @locale_config.deep_freeze! if @locale_config.respond_to?(:deep_freeze!)
+
+        Otto.logger.debug '[Otto::Configuration] Freezing middleware stack' if Otto.debug
+        @middleware.deep_freeze! if @middleware.respond_to?(:deep_freeze!)
+
+        # Deep freeze configuration hashes (recursively freezes nested structures)
+        Otto.logger.debug '[Otto::Configuration] Freezing auth_config hash' if Otto.debug
+        deep_freeze_value(@auth_config) if @auth_config
+
+        Otto.logger.debug '[Otto::Configuration] Freezing option hash' if Otto.debug
+        deep_freeze_value(@option) if @option
+
+        # Deep freeze route structures (prevent modification of nested hashes/arrays)
+        Otto.logger.debug '[Otto::Configuration] Freezing route structures' if Otto.debug
+        deep_freeze_value(@routes) if @routes
+        deep_freeze_value(@routes_literal) if @routes_literal
+        deep_freeze_value(@routes_static) if @routes_static
+        deep_freeze_value(@route_definitions) if @route_definitions
+
+        @configuration_frozen = true
+        Otto.logger.info '[Otto::Configuration] Configuration freeze completed successfully'
+
+        self
+      end
+
+      # Check if configuration is frozen
+      #
+      # @return [Boolean] true if configuration is frozen
+      def frozen_configuration?
+        @configuration_frozen == true
+      end
+
+      # Ensure configuration is not frozen before allowing mutations
+      #
+      # @raise [FrozenError] if configuration is frozen
+      def ensure_not_frozen!
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen_configuration?
+      end
+
 
       def middleware_enabled?(middleware_class)
         # Only check the new middleware stack as the single source of truth

data/lib/otto/core/freezable.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# lib/otto/core/freezable.rb
+
+require 'set'
+
+class Otto
+  module Core
+    # Provides deep freezing capability for configuration objects
+    #
+    # This module enables objects to be deeply frozen, preventing any
+    # modifications to the object itself and all its nested structures.
+    # This is critical for security as it prevents runtime tampering with
+    # security configurations.
+    #
+    # @example
+    #   class MyConfig
+    #     include Otto::Core::Freezable
+    #
+    #     def initialize
+    #       @settings = { security: { enabled: true } }
+    #     end
+    #   end
+    #
+    #   config = MyConfig.new
+    #   config.deep_freeze!
+    #   # Now config and all nested hashes/arrays are frozen
+    #
+    module Freezable
+      # Deeply freeze this object and all its instance variables
+      #
+      # This method recursively freezes all nested structures including:
+      # - Hashes (both keys and values)
+      # - Arrays (and all elements)
+      # - Sets
+      # - Other freezable objects
+      #
+      # NOTE: This method is idempotent and safe to call multiple times.
+      #
+      # @return [self] The frozen object
+      def deep_freeze!
+        return self if frozen?
+
+        freeze_instance_variables!
+        freeze
+        self
+      end
+
+      private
+
+      # Freeze all instance variables recursively
+      def freeze_instance_variables!
+        instance_variables.each do |var|
+          value = instance_variable_get(var)
+          deep_freeze_value(value)
+        end
+      end
+
+      # Recursively freeze a value based on its type
+      #
+      # @param value [Object] Value to freeze
+      # @return [void]
+      def deep_freeze_value(value)
+        case value
+        when Hash
+          # Freeze hash keys and values, then freeze the hash itself
+          value.each do |k, v|
+            k.freeze unless k.frozen?
+            deep_freeze_value(v)
+          end
+          value.freeze
+        when Array
+          # Freeze all array elements, then freeze the array
+          value.each { |item| deep_freeze_value(item) }
+          value.freeze
+        when Set
+          # Sets are immutable once frozen
+          value.freeze
+        when String, Symbol, Numeric, TrueClass, FalseClass, NilClass
+          # These types are either immutable or already frozen
+          value.freeze if value.respond_to?(:freeze) && !value.frozen?
+        else
+          # For other objects, recursively freeze if they support it, otherwise shallow freeze.
+          if value.respond_to?(:deep_freeze!)
+            value.deep_freeze!
+          elsif value.respond_to?(:freeze) && !value.frozen?
+            value.freeze
+          end
+        end
+      end
+    end
+  end
+end