otto 2.0.0.pre2 → 2.0.0.pre3

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

data/lib/otto/core/middleware_stack.rb

@@ -2,6 +2,8 @@
 
 # lib/otto/core/middleware_stack.rb
 
+require_relative 'freezable'
+
 class Otto
   module Core
     # Enhanced middleware stack management for Otto framework.
@@ -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

data/lib/otto/core/router.rb

@@ -51,7 +51,7 @@ class Otto
       def handle_request(env)
         locale             = determine_locale env
         env['rack.locale'] = locale
-        env['otto.locale_config'] = @locale_config if @locale_config
+        env['otto.locale_config'] = @locale_config.to_h if @locale_config
         @static_route    ||= Rack::Files.new(option[:public]) if option[:public] && safe_dir?(option[:public])
         path_info          = Rack::Utils.unescape(env['PATH_INFO'])
         path_info          = '/' if path_info.to_s.empty?

data/lib/otto/core.rb

@@ -0,0 +1,8 @@
+# lib/otto/core.rb
+
+require_relative 'core/router'
+require_relative 'core/file_safety'
+require_relative 'core/configuration'
+require_relative 'core/error_handler'
+require_relative 'core/uri_generator'
+require_relative 'core/middleware_stack'

data/lib/otto/env_keys.rb

@@ -36,21 +36,25 @@ class Otto
 
     # Authentication strategy result containing session/user state
     # Type: Otto::Security::Authentication::StrategyResult
-    # Set by: AuthenticationMiddleware
+    # Set by: RouteAuthWrapper (wraps all route handlers)
     # Used by: RouteHandlers, LogicClasses, Controllers
-    # Note: Always present (anonymous or authenticated)
+    # Guarantee: ALWAYS present - either authenticated or anonymous
+    # - Routes WITH auth requirement: Authenticated StrategyResult or 401/302
+    # - Routes WITHOUT auth requirement: Anonymous StrategyResult
     STRATEGY_RESULT = 'otto.strategy_result'
 
     # Authenticated user object (convenience accessor)
     # Type: Hash, Custom User Object, or nil
-    # Set by: AuthenticationMiddleware (from strategy_result.user)
+    # Set by: RouteAuthWrapper (from strategy_result.user)
     # Used by: Controllers, RouteHandlers
+    # Note: nil for anonymous/unauthenticated requests
     USER = 'otto.user'
 
     # User-specific context (session, roles, permissions, etc.)
     # Type: Hash
-    # Set by: AuthenticationMiddleware (from strategy_result.user_context)
+    # Set by: RouteAuthWrapper (from strategy_result.user_context)
     # Used by: Controllers, Analytics
+    # Note: Empty hash {} for anonymous requests
     USER_CONTEXT = 'otto.user_context'
 
     # =========================================================================

data/lib/otto/helpers/request.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 # lib/otto/helpers/request.rb
 
 require_relative 'base'
@@ -13,6 +11,86 @@ class Otto
       env['HTTP_USER_AGENT']
     end
 
+    # NOTE: We do NOT override Rack::Request#ip
+    #
+    # IPPrivacyMiddleware masks both REMOTE_ADDR and X-Forwarded-For headers,
+    # so Rack's native ip resolution logic works correctly with masked values.
+    # This allows Rack to handle proxy scenarios (trusted proxies, header parsing)
+    # while still returning privacy-safe masked IPs.
+    #
+    # If you need the masked IP explicitly, use:
+    #   req.masked_ip  # => '192.168.1.0' or nil if privacy disabled
+    #
+    # If you need the geo country:
+    #   req.geo_country  # => 'US' or nil
+    #
+    # If you need the full privacy fingerprint:
+    #   req.redacted_fingerprint  # => RedactedFingerprint object or nil
+
+    # Get the privacy-safe fingerprint for this request
+    #
+    # Returns nil if IP privacy is disabled. The fingerprint contains
+    # anonymized request information suitable for logging and analytics.
+    #
+    # @return [Otto::Privacy::RedactedFingerprint, nil] Privacy-safe fingerprint
+    # @example
+    #   fingerprint = req.redacted_fingerprint
+    #   fingerprint.masked_ip    # => '192.168.1.0'
+    #   fingerprint.country      # => 'US'
+    def redacted_fingerprint
+      env['otto.redacted_fingerprint']
+    end
+
+    # Get the geo-location country code for the request
+    #
+    # Returns ISO 3166-1 alpha-2 country code or 'XX' for unknown.
+    # Only available when IP privacy is enabled (default).
+    #
+    # @return [String, nil] Country code or nil if privacy disabled
+    # @example
+    #   req.geo_country  # => 'US'
+    def geo_country
+      redacted_fingerprint&.country || env['otto.geo_country']
+    end
+
+    # Get anonymized user agent string
+    #
+    # Returns user agent with version numbers stripped for privacy.
+    # Only available when IP privacy is enabled (default).
+    #
+    # @return [String, nil] Anonymized user agent or nil
+    # @example
+    #   req.anonymized_user_agent
+    #   # => 'Mozilla/X.X (Windows NT X.X; Win64; x64) AppleWebKit/X.X'
+    def anonymized_user_agent
+      redacted_fingerprint&.anonymized_ua
+    end
+
+    # Get masked IP address
+    #
+    # Returns privacy-safe masked IP. When privacy is enabled (default),
+    # this returns the masked version. When disabled, returns original IP.
+    #
+    # @return [String, nil] Masked or original IP address
+    # @example
+    #   req.masked_ip  # => '192.168.1.0'
+    def masked_ip
+      env['otto.masked_ip'] || env['REMOTE_ADDR']
+    end
+
+    # Get hashed IP for session correlation
+    #
+    # Returns daily-rotating hash of the IP address, allowing session
+    # tracking without storing the original IP. Only available when
+    # IP privacy is enabled (default).
+    #
+    # @return [String, nil] Hexadecimal hash string or nil
+    # @example
+    #   req.hashed_ip  # => 'a3f8b2c4d5e6f7...'
+    def hashed_ip
+      redacted_fingerprint&.hashed_ip || env['otto.hashed_ip']
+    end
+
     def client_ipaddress
       remote_addr = env['REMOTE_ADDR']
 

data/lib/otto/helpers/response.rb

@@ -14,10 +14,10 @@ class Otto
     def send_secure_cookie(name, value, ttl, opts = {})
       # Default security options
       defaults = {
-        secure: true,
-        httponly: true,
+           secure: true,
+         httponly: true,
         same_site: :strict,
-        path: '/',
+             path: '/',
       }
 
       # Merge with provided options

data/lib/otto/helpers.rb

@@ -0,0 +1,4 @@
+# lib/otto/helpers.rb
+
+require_relative 'helpers/request'
+require_relative 'helpers/response'

data/lib/otto/locale/config.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# lib/otto/locale/config.rb
+
+require_relative '../core/freezable'
+
+class Otto
+  module Locale
+    # Locale configuration for Otto applications
+    #
+    # This class manages locale-related settings including available locales
+    # and default locale selection.
+    #
+    # @example Basic usage
+    #   config = Otto::Locale::Config.new
+    #   config.available_locales = { 'en' => 'English', 'es' => 'Spanish' }
+    #   config.default_locale = 'en'
+    #
+    # @example With initialization
+    #   config = Otto::Locale::Config.new(
+    #     available_locales: { 'en' => 'English', 'fr' => 'French' },
+    #     default_locale: 'en'
+    #   )
+    class Config
+      include Otto::Core::Freezable
+
+      attr_accessor :available_locales, :default_locale
+
+      # Initialize locale configuration
+      #
+      # @param available_locales [Hash, nil] Hash of locale codes to names
+      # @param default_locale [String, nil] Default locale code
+      def initialize(available_locales: nil, default_locale: nil)
+        @available_locales = available_locales
+        @default_locale = default_locale
+      end
+
+      # Convert to hash for compatibility with existing code
+      #
+      # @return [Hash] Hash representation of configuration
+      def to_h
+        {
+          available_locales: @available_locales,
+          default_locale: @default_locale,
+        }.compact
+      end
+
+      # Check if locale configuration is present
+      #
+      # @return [Boolean] true if either available_locales or default_locale is set
+      def configured?
+        !@available_locales.nil? || !@default_locale.nil?
+      end
+    end
+  end
+end

data/lib/otto/mcp.rb

@@ -0,0 +1,3 @@
+# lib/otto/mcp.rb
+
+require_relative 'mcp/server'

data/lib/otto/privacy/config.rb

@@ -0,0 +1,199 @@
+# lib/otto/privacy/config.rb
+
+require 'ipaddr'
+require 'securerandom'
+require 'digest'
+
+require 'concurrent'
+
+require_relative '../core/freezable'
+
+class Otto
+  module Privacy
+    # Configuration for IP privacy features
+    #
+    # Privacy is ENABLED by default for public IPs. Private/localhost IPs are not masked.
+    #
+    # @example Default configuration (privacy enabled)
+    #   config = Otto::Privacy::Config.new
+    #   config.enabled? # => true
+    #
+    # @example Configure masking level
+    #   config = Otto::Privacy::Config.new
+    #   config.octet_precision = 2  # Mask 2 octets instead of 1
+    #
+    class Config
+      include Otto::Core::Freezable
+
+      attr_accessor :octet_precision, :hash_rotation_period, :geo_enabled, :mask_private_ips
+      attr_reader :disabled
+
+      # Class-level rotation key storage (mutable, not frozen with instances)
+      # This is stored at the class level so it persists across frozen config instances
+      @rotation_keys_store = nil
+
+      class << self
+        # Get the class-level rotation keys store
+        # @return [Concurrent::Map] Thread-safe map for rotation keys
+        def rotation_keys_store
+          @rotation_keys_store = Concurrent::Map.new unless defined?(@rotation_keys_store) && @rotation_keys_store
+          @rotation_keys_store
+        end
+      end
+
+      # Initialize privacy configuration
+      #
+      # @param options [Hash] Configuration options
+      # @option options [Integer] :octet_precision Number of trailing octets to mask (1 or 2, default: 1)
+      # @option options [Integer] :hash_rotation_period Seconds between key rotation (default: 86400)
+      # @option options [Boolean] :geo_enabled Enable geo-location resolution (default: true)
+      # @option options [Boolean] :disabled Disable privacy entirely (default: false)
+      # @option options [Boolean] :mask_private_ips Mask private/localhost IPs (default: false)
+      # @option options [Redis] :redis Optional Redis connection for multi-server environments
+      def initialize(options = {})
+        @octet_precision = options.fetch(:octet_precision, 1)
+        @hash_rotation_period = options.fetch(:hash_rotation_period, 86_400) # 24 hours
+        @geo_enabled = options.fetch(:geo_enabled, true)
+        @disabled = options.fetch(:disabled, false) # Enabled by default (privacy-by-default)
+        @mask_private_ips = options.fetch(:mask_private_ips, false) # Don't mask private/localhost by default
+        @redis = options[:redis] # Optional Redis connection for multi-server environments
+      end
+
+      # Check if privacy is enabled
+      #
+      # @return [Boolean] true if privacy is enabled (default)
+      def enabled?
+        !@disabled
+      end
+
+      # Check if privacy is disabled
+      #
+      # @return [Boolean] true if privacy was explicitly disabled
+      def disabled?
+        @disabled
+      end
+
+      # Disable privacy (allows access to original IPs)
+      #
+      # IMPORTANT: This should only be used when you have a specific
+      # requirement to access original IP addresses. By default, Otto
+      # provides privacy-safe masked IPs.
+      #
+      # @return [self]
+      def disable!
+        @disabled = true
+        self
+      end
+
+      # Enable privacy (default state)
+      #
+      # @return [self]
+      def enable!
+        @disabled = false
+        self
+      end
+
+      # Get the current rotation key for IP hashing
+      #
+      # Keys rotate at fixed intervals based on hash_rotation_period (default: 24 hours).
+      # Each rotation period gets a unique key, ensuring IP addresses hash differently
+      # across periods while remaining consistent within.
+      #
+      # Multi-server support:
+      # - With Redis: Uses SET NX GET EX for atomic key generation across all servers
+      # - Without Redis: Falls back to in-memory Concurrent::Hash (single-server only)
+      #
+      # Redis keys:
+      #   - rotation_key:{timestamp} - Stores the rotation key with TTL
+      #
+      # @return [String] Current rotation key for hashing
+      def rotation_key
+        if @redis
+          rotation_key_redis
+        else
+          rotation_key_memory
+        end
+      end
+
+      # Validate configuration settings
+      #
+      # @raise [ArgumentError] if configuration is invalid
+      def validate!
+        raise ArgumentError, "octet_precision must be 1 or 2, got: #{@octet_precision}" unless [1,
+                                                                                                2].include?(@octet_precision)
+
+        return unless @hash_rotation_period < 60
+
+        raise ArgumentError, 'hash_rotation_period must be at least 60 seconds'
+      end
+
+      private
+
+      # Redis-based rotation key (atomic across multiple servers)
+      #
+      # Uses SET NX GET EX to atomically:
+      # 1. Check if key exists
+      # 2. Set new key only if missing
+      # 3. Return existing or newly set key
+      # 4. Auto-expire with TTL
+      #
+      # @return [String] Current rotation key
+      # @api private
+      def rotation_key_redis
+        now_seconds = Time.now.utc.to_i
+
+        # Quantize to rotation period boundary
+        rotation_timestamp = (now_seconds / @hash_rotation_period) * @hash_rotation_period
+
+        redis_key = "rotation_key:#{rotation_timestamp}"
+        ttl = (@hash_rotation_period * 1.2).to_i # Auto-cleanup with 20% buffer
+
+        key = SecureRandom.hex(32)
+
+        # SET NX GET returns old value if key exists, nil if we set it
+        # @see https://valkey.io/commands/set/
+        existing_key = @redis.set(redis_key, key, nx: true, get: true, ex: ttl)
+
+        existing_key || key
+      end
+
+      # In-memory rotation key (single-server fallback)
+      #
+      # Uses class-level Concurrent::Hash for thread-safety within a single process.
+      # NOT atomic across multiple servers.
+      #
+      # The rotation keys are stored at the class level so they remain mutable
+      # even when config instances are frozen.
+      #
+      # @return [String] Current rotation key
+      # @api private
+      def rotation_key_memory
+        rotation_keys = self.class.rotation_keys_store
+
+        now_seconds = Time.now.utc.to_i
+
+        # Quantize to rotation period boundary (e.g., midnight UTC for 24-hour period)
+        seconds_since_epoch = now_seconds % @hash_rotation_period
+        rotation_timestamp = now_seconds - seconds_since_epoch
+
+        # Atomically get or create key for this rotation period
+        # Use compute_if_absent for thread-safe atomic operation
+        key = rotation_keys.compute_if_absent(rotation_timestamp) do
+          # Generate new key atomically
+          # IMPORTANT: Don't modify the map inside this block to avoid deadlock
+          SecureRandom.hex(32)
+        end
+
+        # Clean up old keys after atomic operation completes
+        # This runs outside compute_if_absent to avoid deadlock
+        if rotation_keys.size > 1
+          rotation_keys.each_key do |ts|
+            rotation_keys.delete(ts) if ts != rotation_timestamp
+          end
+        end
+
+        key
+      end
+    end
+  end
+end