otto 2.0.0.pre2 → 2.0.0.pre7

data/lib/otto/core/configuration.rb

@@ -1,58 +1,44 @@
-# frozen_string_literal: true
-
 # lib/otto/core/configuration.rb
+#
+# frozen_string_literal: true
 
 require_relative '../security/csrf'
 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
-      def configure_locale(opts)
-        # Start with global configuration
-        global_config = self.class.global_config
-        @locale_config = nil
+      include Otto::Core::Freezable
 
-        # Check if we have any locale configuration from any source
-        has_global_locale = global_config && (global_config[:available_locales] || global_config[:default_locale])
+      def configure_locale(opts)
+        # 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)
@@ -83,10 +69,7 @@ class Otto
         @auth_config[:auth_strategies] = opts[:auth_strategies] if opts[:auth_strategies]
         @auth_config[:default_auth_strategy] = opts[:default_auth_strategy] if opts[:default_auth_strategy]
 
-        # Enable authentication middleware if strategies are configured
-        return unless opts[:auth_strategies] && !opts[:auth_strategies].empty?
-
-        enable_authentication!
+        # No-op: authentication strategies are configured via @auth_config above
       end
 
       def configure_mcp(opts)
@@ -115,9 +98,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 +122,7 @@ class Otto
       #     }
       #   })
       def configure_rate_limiting(config)
+        ensure_not_frozen!
         @security_config.rate_limiting_config.merge!(config)
       end
 
@@ -149,18 +138,74 @@ class Otto
       #     'api_key' => Otto::Security::Authentication::Strategies::APIKeyStrategy.new(api_keys: ['secret123'])
       #   })
       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
+      end
 
-        enable_authentication! unless strategies.empty?
+      # 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.structured_log(:debug, 'Configuration already frozen', { status: 'skipped' }) if Otto.debug
+          return self
+        end
+
+        start_time = Otto::Utils.now_in_μs
+
+        # Deep freeze configuration objects with memoization support
+        @security_config.deep_freeze! if @security_config.respond_to?(:deep_freeze!)
+        @locale_config.deep_freeze! if @locale_config.respond_to?(:deep_freeze!)
+        @middleware.deep_freeze! if @middleware.respond_to?(:deep_freeze!)
+
+        # Deep freeze configuration hashes (recursively freezes nested structures)
+        deep_freeze_value(@auth_config) if @auth_config
+        deep_freeze_value(@option) if @option
+
+        # Deep freeze route structures (prevent modification of nested hashes/arrays)
+        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
+
+        duration = Otto::Utils.now_in_μs - start_time
+        frozen_objects = %w[security_config locale_config middleware auth_config option routes]
+        Otto.structured_log(:info, 'Freezing completed',
+          {
+                  duration: duration,
+            frozen_objects: frozen_objects.join(','),
+          })
+
+        self
       end
 
-      private
+      # 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
-        @middleware && @middleware.includes?(middleware_class)
+        @middleware&.includes?(middleware_class)
       end
     end
   end

data/lib/otto/core/error_handler.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/core/error_handler.rb
+#
+# frozen_string_literal: true
 
 require 'securerandom'
 require 'json'
@@ -11,10 +11,30 @@ class Otto
     # Error handling module providing secure error reporting and logging functionality
     module ErrorHandler
       def handle_error(error, env)
+        # Check if this is a registered expected error
+        if handler_config = @error_handlers[error.class.name]
+          return handle_expected_error(error, env, handler_config)
+        end
+
         # Log error details internally but don't expose them
         error_id = SecureRandom.hex(8)
-        Otto.logger.error "[#{error_id}] #{error.class}: #{error.message}"
-        Otto.logger.debug "[#{error_id}] Backtrace: #{error.backtrace.join("\n")}" if Otto.debug
+
+        # Base context pattern: create once, reuse for correlation
+        base_context = Otto::LoggingHelpers.request_context(env)
+
+        # Include handler context if available (set by route handlers)
+        log_context = base_context.merge(
+          error: error.message,
+          error_class: error.class.name,
+          error_id: error_id
+        )
+        log_context[:handler] = env['otto.handler'] if env['otto.handler']
+        log_context[:duration] = env['otto.handler_duration'] if env['otto.handler_duration']
+
+        Otto.structured_log(:error, 'Unhandled error in request', log_context)
+
+        Otto::LoggingHelpers.log_backtrace(error,
+          base_context.merge(error_id: error_id))
 
         # Parse request for content negotiation
         begin
@@ -30,7 +50,21 @@ class Otto
             env['otto.error_id'] = error_id
             return found_route.call(env)
           rescue StandardError => e
-            Otto.logger.error "[#{error_id}] Error in custom error handler: #{e.message}"
+            # When the custom error handler itself fails, generate a new error ID
+            # to distinguish it from the original error, but link them.
+            custom_handler_error_id = SecureRandom.hex(8)
+            base_context = Otto::LoggingHelpers.request_context(env)
+
+            Otto.structured_log(:error, 'Error in custom error handler',
+              base_context.merge(
+                error: e.message,
+                error_class: e.class.name,
+                error_id: custom_handler_error_id,
+                original_error_id: error_id # Link to original error
+              ))
+
+            Otto::LoggingHelpers.log_backtrace(e,
+              base_context.merge(error_id: custom_handler_error_id, original_error_id: error_id))
           end
         end
 
@@ -44,6 +78,102 @@ class Otto
 
       private
 
+      # Handle expected business logic errors with custom status codes and logging
+      #
+      # @param error [Exception] The expected error to handle
+      # @param env [Hash] Rack environment hash
+      # @param handler_config [Hash] Configuration from error_handlers registry
+      # @return [Array] Rack response tuple [status, headers, body]
+      def handle_expected_error(error, env, handler_config)
+        # Generate error ID for correlation (even for expected errors)
+        error_id = SecureRandom.hex(8)
+
+        # Base context pattern: create once, reuse for correlation
+        base_context = Otto::LoggingHelpers.request_context(env)
+
+        # Include handler context if available
+        log_context = base_context.merge(
+          error: error.message,
+          error_class: error.class.name,
+          error_id: error_id,
+          expected: true  # Mark as expected error
+        )
+        log_context[:handler] = env['otto.handler'] if env['otto.handler']
+        log_context[:duration] = env['otto.handler_duration'] if env['otto.handler_duration']
+
+        # Log at configured level (info/warn instead of error)
+        log_level = handler_config[:log_level] || :info
+        Otto.structured_log(log_level, 'Expected error in request', log_context)
+
+        # Build response body
+        response_body = if handler_config[:handler]
+                          # Use custom handler block if provided
+                          begin
+                            req = Rack::Request.new(env)
+                            result = handler_config[:handler].call(error, req)
+
+                            # Validate that custom handler returned a Hash
+                            unless result.is_a?(Hash)
+                              base_context = Otto::LoggingHelpers.request_context(env)
+                              Otto.structured_log(:warn, 'Custom error handler returned non-hash value',
+                                base_context.merge(
+                                  error_class: error.class.name,
+                                  handler_result_class: result.class.name,
+                                  error_id: error_id
+                                ))
+                              result = { error: error.class.name.split('::').last, message: error.message }
+                            end
+
+                            result
+                          rescue StandardError => e
+                            # If custom handler fails, fall back to default
+                            base_context = Otto::LoggingHelpers.request_context(env)
+                            Otto.structured_log(:warn, 'Error in custom error handler',
+                              base_context.merge(
+                                error: e.message,
+                                error_class: e.class.name,
+                                original_error_class: error.class.name,
+                                error_id: error_id
+                              ))
+                            { error: error.class.name.split('::').last, message: error.message }
+                          end
+                        else
+                          # Default response body
+                          { error: error.class.name.split('::').last, message: error.message }
+                        end
+
+        # Add error_id in development mode
+        response_body[:error_id] = error_id if Otto.env?(:dev, :development)
+
+        # Content negotiation
+        accept_header = env['HTTP_ACCEPT'].to_s
+        status = handler_config[:status] || 500
+
+        if accept_header.include?('application/json')
+          body = JSON.generate(response_body)
+          headers = {
+            'content-type' => 'application/json',
+            'content-length' => body.bytesize.to_s
+          }.merge(@security_config.security_headers)
+
+          [status, headers, [body]]
+        else
+          # Plain text response
+          body = if Otto.env?(:dev, :development)
+                   "#{response_body[:error]}: #{response_body[:message]} (ID: #{error_id})"
+                 else
+                   "#{response_body[:error]}: #{response_body[:message]}"
+                 end
+
+          headers = {
+            'content-type' => 'text/plain',
+            'content-length' => body.bytesize.to_s
+          }.merge(@security_config.security_headers)
+
+          [status, headers, [body]]
+        end
+      end
+
       def secure_error_response(error_id)
         body = if Otto.env?(:dev, :development)
                  "Server error (ID: #{error_id}). Check logs for details."
@@ -62,13 +192,13 @@ class Otto
       def json_error_response(error_id)
         error_data = if Otto.env?(:dev, :development)
                        {
-                         error: 'Internal Server Error',
-                         message: 'Server error occurred. Check logs for details.',
+                            error: 'Internal Server Error',
+                          message: 'Server error occurred. Check logs for details.',
                          error_id: error_id,
                        }
                      else
                        {
-                         error: 'Internal Server Error',
+                           error: 'Internal Server Error',
                          message: 'An error occurred. Please try again later.',
                        }
                      end

data/lib/otto/core/file_safety.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/core/file_safety.rb
+#
+# frozen_string_literal: true
 
 class Otto
   module Core

data/lib/otto/core/freezable.rb

@@ -0,0 +1,93 @@
+# lib/otto/core/freezable.rb
+#
+# frozen_string_literal: true
+
+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

data/lib/otto/core/middleware_stack.rb

@@ -1,6 +1,8 @@
+# lib/otto/core/middleware_stack.rb
+#
 # frozen_string_literal: true
 
-# lib/otto/core/middleware_stack.rb
+require_relative 'freezable'
 
 class Otto
   module Core
@@ -9,10 +11,18 @@ class Otto
     # and improved execution chain management.
     class MiddlewareStack
       include Enumerable
+      include Otto::Core::Freezable
 
       def initialize
         @stack = []
         @middleware_set = Set.new
+        @on_change_callback = nil
+      end
+
+      # Set a callback to be invoked when the middleware stack changes
+      # @param callback [Proc] A callable object (e.g., method or lambda)
+      def on_change(&callback)
+        @on_change_callback = callback
       end
 
       # Enhanced middleware registration with argument uniqueness and immutability check
@@ -33,8 +43,8 @@ class Otto
         entry = { middleware: middleware_class, args: args, options: options }
         @stack << entry
         @middleware_set.add(middleware_class)
-        # Invalidate memoized middleware list
-        @memoized_middleware_list = nil
+        # Notify of change
+        @on_change_callback&.call
       end
 
       # Add middleware with position hint for optimal ordering
@@ -67,7 +77,8 @@ class Otto
         end
 
         @middleware_set.add(middleware_class)
-        @memoized_middleware_list = nil
+        # Notify of change
+        @on_change_callback&.call
       end
 
       # Validate MCP middleware ordering
@@ -131,8 +142,8 @@ class Otto
 
         # Rebuild the set of unique middleware classes
         @middleware_set = Set.new(@stack.map { |entry| entry[:middleware] })
-        # Invalidate memoized middleware list
-        @memoized_middleware_list = nil
+        # Notify of change
+        @on_change_callback&.call
       end
 
       # Check if middleware is registered - now O(1) using Set
@@ -147,8 +158,8 @@ class Otto
 
         @stack.clear
         @middleware_set.clear
-        # Invalidate memoized middleware list
-        @memoized_middleware_list = nil
+        # Notify of change
+        @on_change_callback&.call
       end
 
       # Enumerable support
@@ -157,7 +168,7 @@ class Otto
       end
 
       # Build Rack application with middleware chain
-      def build_app(base_app, security_config = nil)
+      def wrap(base_app, security_config = nil)
         @stack.reduce(base_app) do |app, entry|
           middleware = entry[:middleware]
           args = entry[:args]
@@ -177,10 +188,9 @@ class Otto
         end
       end
 
-      # Cached middleware list to reduce array creation
+      # Returns list of middleware classes in order
       def middleware_list
-        # Memoize the result to avoid repeated array creation
-        @memoized_middleware_list ||= @stack.map { |entry| entry[:middleware] }
+        @stack.map { |entry| entry[:middleware] }
       end
 
       # Detailed introspection
@@ -215,6 +225,8 @@ class Otto
         @stack.reverse_each(&)
       end
 
+
+
       private
 
       def middleware_needs_config?(middleware_class)
@@ -224,12 +236,7 @@ class Otto
           Otto::Security::Middleware::CSRFMiddleware,
           Otto::Security::Middleware::ValidationMiddleware,
           Otto::Security::Middleware::RateLimitMiddleware,
-          Otto::Security::Authentication::AuthenticationMiddleware,
-          # Backward compatibility aliases
-          Otto::Security::CSRFMiddleware,
-          Otto::Security::ValidationMiddleware,
-          Otto::Security::RateLimitMiddleware,
-          Otto::Security::AuthenticationMiddleware,
+          Otto::Security::Middleware::IPPrivacyMiddleware,
         ].include?(middleware_class)
       end
     end