otto 2.0.0.pre2 → 2.0.0.pre7

data/lib/otto/security/config.rb

@@ -1,9 +1,10 @@
-# frozen_string_literal: true
-
 # lib/otto/security/config.rb
+#
+# frozen_string_literal: true
 
 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
@@ -175,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
@@ -188,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
 
@@ -203,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
@@ -214,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
 
@@ -246,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
 
@@ -254,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({
@@ -261,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

@@ -1,10 +1,9 @@
-# frozen_string_literal: true
-
 # lib/otto/security/configurator.rb
+#
+# frozen_string_literal: true
 
 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
@@ -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,21 +168,27 @@ 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
       #
+      # Part of the Security::Configurator facade for consolidated configuration.
+      # This delegates to the same storage as Otto#add_auth_strategy, allowing
+      # authentication to be configured alongside other security features.
+      #
+      # Prefer using Otto#add_auth_strategy directly for simpler cases, or use this
+      # when configuring multiple security features together via the security facade.
+      #
       # @param name [String] Strategy name
       # @param strategy [Otto::Security::Authentication::AuthStrategy] Strategy instance
+      # @example
+      #   otto.security.add_auth_strategy('session', SessionStrategy.new)
+      # @raise [ArgumentError] if strategy name already registered
       def add_auth_strategy(name, strategy)
+        # Strict mode: Detect strategy name collisions
+        if @auth_config[:auth_strategies].key?(name)
+          raise ArgumentError, "Authentication strategy '#{name}' is already registered"
+        end
+
         @auth_config[:auth_strategies][name] = strategy
-        enable_authentication!
       end
 
       # Configure authentication strategies for route-level access control.
@@ -196,7 +199,6 @@ class Otto
         # 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.

data/lib/otto/security/csrf.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 # lib/otto/security/csrf.rb
 #
+# frozen_string_literal: true
+#
 # Index file for CSRF protection components
 # Provides backward compatibility for existing CSRF usage
 

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

@@ -1,3 +1,5 @@
+# lib/otto/security/middleware/csrf_middleware.rb
+#
 # frozen_string_literal: true
 
 require_relative '../config'
@@ -27,7 +29,15 @@ class Otto
           end
 
           # Validate CSRF token for unsafe methods
-          return csrf_error_response unless valid_csrf_token?(request)
+          unless valid_csrf_token?(request)
+            # Log CSRF validation failure
+            Otto.structured_log(:warn, "CSRF validation failed",
+              Otto::LoggingHelpers.request_context(env).merge(
+                referrer: request.referrer
+              )
+            )
+            return csrf_error_response
+          end
 
           @app.call(env)
         end

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

@@ -0,0 +1,231 @@
+# lib/otto/security/middleware/ip_privacy_middleware.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module Middleware
+      # IP Privacy Middleware
+      #
+      # Automatically masks IP addresses for privacy by default. Original IPs
+      # are never stored unless privacy is explicitly disabled.
+      #
+      # This middleware runs FIRST in the stack to ensure all downstream
+      # middleware and application code receives masked IPs by default.
+      #
+      # @example Default behavior (privacy enabled)
+      #   # env['REMOTE_ADDR'] is masked to 192.168.1.0
+      #   # env['otto.redacted_fingerprint'] contains full anonymized data
+      #   # env['otto.original_ip'] is NOT set
+      #
+      # @example Privacy disabled
+      #   otto.disable_ip_privacy!
+      #   # env['REMOTE_ADDR'] contains real IP
+      #   # env['otto.original_ip'] also contains real IP
+      #
+      class IPPrivacyMiddleware
+        # Initialize IP Privacy middleware
+        #
+        # @param app [#call] Rack application
+        # @param security_config [Otto::Security::Config] Security configuration
+        def initialize(app, security_config = nil)
+          @app = app
+          @security_config = security_config
+          @config = security_config&.ip_privacy_config || Otto::Privacy::Config.new
+
+          # Privacy is enabled by default unless explicitly disabled
+          @privacy_enabled = @config.enabled?
+        end
+
+        # Process request with IP privacy
+        #
+        # @param env [Hash] Rack environment
+        # @return [Array] Rack response tuple [status, headers, body]
+        def call(env)
+          if @privacy_enabled
+            apply_privacy(env)
+          else
+            apply_no_privacy(env)
+          end
+
+          @app.call(env)
+        end
+
+        private
+
+        # Apply privacy settings to environment
+        #
+        # @param env [Hash] Rack environment
+        # Apply privacy settings to environment
+        #
+        # @param env [Hash] Rack environment
+        # Apply privacy settings to environment
+        #
+        # @param env [Hash] Rack environment
+        def apply_privacy(env)
+          # Resolve the actual client IP (handling proxies)
+          client_ip = resolve_client_ip(env)
+
+          Otto.logger.debug "[IPPrivacyMiddleware] Resolved client IP: #{client_ip}" if Otto.debug
+
+          # Skip masking for private/localhost IPs unless explicitly configured to mask them
+          # This provides better DX for development while still protecting public IPs
+          unless @config.mask_private_ips
+            if Otto::Privacy::IPPrivacy.private_or_localhost?(client_ip)
+              # Update REMOTE_ADDR to the resolved client IP (even though it's not masked)
+              env['REMOTE_ADDR'] = client_ip
+              env['otto.original_ip'] = client_ip
+              # Don't mask forwarded headers for private IPs
+              Otto.logger.debug "[IPPrivacyMiddleware] Private/localhost IP exempted: #{client_ip}" if Otto.debug
+              return
+            end
+          end
+
+          # Create privacy-safe fingerprint using the resolved client IP
+          # We temporarily set REMOTE_ADDR to the client IP for fingerprint creation
+          original_remote_addr = env['REMOTE_ADDR']
+          env['REMOTE_ADDR'] = client_ip
+          fingerprint = Otto::Privacy::RedactedFingerprint.new(env, @config)
+          env['REMOTE_ADDR'] = original_remote_addr
+
+          # Set privacy-safe values in environment
+          env['otto.privacy.fingerprint'] = fingerprint
+          env['otto.privacy.masked_ip'] = fingerprint.masked_ip
+          env['otto.privacy.hashed_ip'] = fingerprint.hashed_ip
+          env['otto.privacy.geo_country'] = fingerprint.country
+
+          # CRITICAL: Replace REMOTE_ADDR and forwarded headers with masked values
+          # This ensures downstream code (rate limiting, auth, logging, Rack's request.ip)
+          # automatically uses the masked values without modification
+          env['REMOTE_ADDR'] = fingerprint.masked_ip
+
+          # Replace User-Agent with anonymized version (consistent with IP masking)
+          # CRITICAL: Always replace, even if nil, to clear original sensitive data
+          env['HTTP_USER_AGENT'] = fingerprint.anonymized_ua
+
+          # Replace Referer with anonymized version (query params stripped)
+          # CRITICAL: Always replace, even if nil, to clear original sensitive data
+          env['HTTP_REFERER'] = fingerprint.referer
+
+          # Mask X-Forwarded-For headers to prevent leakage
+          # Replace with masked IP so proxy resolution logic finds the masked IP
+          mask_forwarded_headers(env, fingerprint.masked_ip)
+
+          Otto.logger.debug "[IPPrivacyMiddleware] Masked IP: #{fingerprint.masked_ip}" if Otto.debug
+
+          # NOTE: We deliberately DO NOT set env['otto.original_ip'], env['otto.original_user_agent'],
+          # or env['otto.original_referer']. This prevents accidental leakage of the real values.
+        end
+
+
+        # Resolve the actual client IP address from the request
+        #
+        # This method handles proxy scenarios by checking X-Forwarded-For and
+        # other proxy headers from trusted proxies, similar to Rack's logic
+        # and Otto's client_ipaddress method.
+        #
+        # @param env [Hash] Rack environment
+        # @return [String] Resolved client IP address
+        def resolve_client_ip(env)
+          remote_addr = env['REMOTE_ADDR']
+
+          # If we don't have a security config, use direct connection
+          return remote_addr unless @security_config
+
+          # If REMOTE_ADDR is not from a trusted proxy, it's the client IP
+          return remote_addr unless trusted_proxy?(remote_addr)
+
+          # REMOTE_ADDR is from a trusted proxy, check forwarded headers
+          forwarded_ips = [
+            env['HTTP_X_FORWARDED_FOR'],
+            env['HTTP_X_REAL_IP'],
+            env['HTTP_X_CLIENT_IP'],
+          ].compact.map { |header| header.split(/,\s*/) }.flatten
+
+          # Return the first valid public IP from forwarded headers
+          forwarded_ips.each do |ip|
+            clean_ip = validate_ip_address(ip.strip)
+            next unless clean_ip
+
+            # Return first IP that's not from a trusted proxy
+            return clean_ip unless trusted_proxy?(clean_ip)
+          end
+
+          # Fallback to remote address if no valid forwarded IPs
+          remote_addr
+        end
+
+        # Mask X-Forwarded-For and related proxy headers
+        #
+        # Replaces forwarded IP headers with the masked IP to prevent leakage
+        # when downstream code (including Rack's request.ip) parses these headers.
+        #
+        # @param env [Hash] Rack environment
+        # @param masked_ip [String] The masked IP to use as replacement
+        def mask_forwarded_headers(env, masked_ip)
+          # Replace X-Forwarded-For with masked IP
+          # This prevents Rack::Request#ip from finding the real IP
+          env['HTTP_X_FORWARDED_FOR'] = masked_ip if env['HTTP_X_FORWARDED_FOR']
+          env['HTTP_X_REAL_IP'] = masked_ip if env['HTTP_X_REAL_IP']
+          env['HTTP_X_CLIENT_IP'] = masked_ip if env['HTTP_X_CLIENT_IP']
+
+          Otto.logger.debug "[IPPrivacyMiddleware] Masked forwarded headers" if Otto.debug
+        end
+
+        # Check if an IP is from a trusted proxy
+        #
+        # @param ip [String] IP address to check
+        # @return [Boolean] true if IP is from a trusted proxy
+        def trusted_proxy?(ip)
+          return false unless @security_config
+
+          @security_config.trusted_proxy?(ip)
+        end
+
+        # Validate and clean IP address
+        #
+        # @param ip [String, nil] IP address to validate
+        # @return [String, nil] Cleaned IP or nil if invalid
+        def validate_ip_address(ip)
+          return nil if ip.nil? || ip.empty?
+
+          # Remove any port number
+          clean_ip = ip.split(':').first
+
+          # Basic IPv4 format validation
+          return nil unless clean_ip.match?(/\A\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\z/)
+
+          # Validate each octet
+          octets = clean_ip.split('.')
+          return nil unless octets.all? { |octet| (0..255).cover?(octet.to_i) }
+
+          clean_ip
+        end
+
+        # Apply no-privacy settings (privacy explicitly disabled)
+        #
+        # When privacy is disabled, original IP is available for
+        # backward compatibility with code that requires it.
+        #
+        # @param env [Hash] Rack environment
+        def apply_no_privacy(env)
+          # Store original values for explicit access when privacy is disabled
+          if env['REMOTE_ADDR']
+            env['otto.original_ip'] = env['REMOTE_ADDR'].dup.force_encoding('UTF-8')
+          end
+
+          if env['HTTP_USER_AGENT']
+            env['otto.original_user_agent'] = env['HTTP_USER_AGENT'].dup.force_encoding('UTF-8')
+          end
+
+          if env['HTTP_REFERER']
+            env['otto.original_referer'] = env['HTTP_REFERER'].dup.force_encoding('UTF-8')
+          end
+
+          # env['REMOTE_ADDR'], env['HTTP_USER_AGENT'], env['HTTP_REFERER'] remain unchanged (real values)
+          # No fingerprint is created when privacy is disabled
+        end
+      end
+    end
+  end
+end

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

@@ -1,3 +1,5 @@
+# lib/otto/security/middleware/rate_limit_middleware.rb
+#
 # frozen_string_literal: true
 
 require_relative '../rate_limiter'

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

@@ -1,3 +1,5 @@
+# lib/otto/security/middleware/validation_middleware.rb
+#
 # frozen_string_literal: true
 
 require_relative '../config'
@@ -52,8 +54,21 @@ class Otto
 
             @app.call(env)
           rescue Otto::Security::ValidationError => e
+            # Log validation failure
+            Otto.structured_log(:warn, "Input validation failed",
+              Otto::LoggingHelpers.request_context(env).merge(
+                error: e.message
+              )
+            )
             validation_error_response(e.message)
           rescue Otto::Security::RequestTooLargeError => e
+            # Log request size violation
+            Otto.structured_log(:warn, "Request too large",
+              Otto::LoggingHelpers.request_context(env).merge(
+                error: e.message,
+                content_length: request.env['CONTENT_LENGTH']
+              )
+            )
             request_too_large_response(e.message)
           end
         end

data/lib/otto/security/rate_limiter.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/security/rate_limiter.rb
+#
+# frozen_string_literal: true
 
 require 'json'
 

data/lib/otto/security/rate_limiting.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 # lib/otto/security/rate_limiting.rb
 #
+# frozen_string_literal: true
+#
 # Index file for rate limiting components
 # Provides backward compatibility for existing rate limiting usage
 

data/lib/otto/security/validator.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 # lib/otto/security/validator.rb
 #
+# frozen_string_literal: true
+#
 # Index file for validation middleware
 # Provides backward compatibility for existing validation usage
 

data/lib/otto/security.rb

@@ -0,0 +1,12 @@
+# lib/otto/security.rb
+#
+# frozen_string_literal: true
+
+require_relative 'security/authentication/strategy_result'
+require_relative 'security/authorization_error'
+require_relative 'security/config'
+require_relative 'security/configurator'
+require_relative 'security/middleware/csrf_middleware'
+require_relative 'security/middleware/validation_middleware'
+require_relative 'security/middleware/rate_limit_middleware'
+require_relative 'security/middleware/ip_privacy_middleware'

data/lib/otto/static.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/static.rb
+#
+# frozen_string_literal: true
 
 class Otto
   # Static response utilities for common HTTP responses

data/lib/otto/utils.rb

@@ -1,12 +1,37 @@
-# frozen_string_literal: true
-
 # lib/otto/utils.rb
+#
+# frozen_string_literal: true
 
 class Otto
   # Utility methods for common operations and helpers
   module Utils
     extend self
 
+    # @return [Time] Current time in UTC
+    def now
+      Time.now.utc
+    end
+
+    # Returns the current time in microseconds.
+    # This is used to measure the duration of Database commands.
+    #
+    # Alias: now_in_microseconds
+    #
+    # @return [Integer] The current time in microseconds.
+    def now_in_μs
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
+    end
+    alias now_in_microseconds now_in_μs
+
+    # Determine if a value represents a "yes" or true value
+    #
+    # @param value [Object] The value to evaluate
+    # @return [Boolean] True if the value represents "yes", false otherwise
+    #
+    # Examples:
+    # yes?('true')  # => true
+    # yes?('yes')   # => true
+    # yes?('1')     # => true
     def yes?(value)
       !value.to_s.empty? && %w[true yes 1].include?(value.to_s.downcase)
     end

data/lib/otto/version.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 # lib/otto/version.rb
+#
+# frozen_string_literal: true
 
 class Otto
-  VERSION = '2.0.0.pre2'
+  VERSION = '2.0.0.pre7'
 end