otto 2.0.0.pre3 → 2.0.0.pre7

data/lib/otto/security/authorization_error.rb

@@ -0,0 +1,73 @@
+# lib/otto/security/authorization_error.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    # Authorization error for resource-level access control failures
+    #
+    # This exception is designed to be raised from Logic classes when a user
+    # attempts to access a resource they don't have permission to access.
+    #
+    # Otto automatically registers this as a 403 Forbidden error during
+    # initialization, so raising this exception will return a 403 response
+    # instead of a 500 error.
+    #
+    # Two-Layer Authorization Pattern:
+    # - Layer 1 (Route-level): RouteAuthWrapper checks authentication/basic roles
+    # - Layer 2 (Resource-level): Logic classes raise AuthorizationError for ownership/permissions
+    #
+    # @example Ownership check in Logic class
+    #   class PostEditLogic
+    #     def raise_concerns
+    #       @post = Post.find(params[:id])
+    #
+    #       unless @post.user_id == @context.user_id
+    #         raise Otto::Security::AuthorizationError, "Cannot edit another user's post"
+    #       end
+    #     end
+    #   end
+    #
+    # @example Multi-condition authorization
+    #   class OrganizationDeleteLogic
+    #     def raise_concerns
+    #       @org = Organization.find(params[:id])
+    #
+    #       unless @context.user_roles.include?('admin') || @org.owner_id == @context.user_id
+    #         raise Otto::Security::AuthorizationError,
+    #           "Requires admin role or organization ownership"
+    #       end
+    #     end
+    #   end
+    #
+    class AuthorizationError < StandardError
+      # Optional additional context for logging/debugging
+      attr_reader :resource, :action, :user_id
+
+      # Initialize authorization error with optional context
+      #
+      # @param message [String] Human-readable error message
+      # @param resource [String, nil] Resource type being accessed (e.g., 'Post', 'Organization')
+      # @param action [String, nil] Action being attempted (e.g., 'edit', 'delete')
+      # @param user_id [String, Integer, nil] ID of user attempting access
+      def initialize(message = 'Access denied', resource: nil, action: nil, user_id: nil)
+        super(message)
+        @resource = resource
+        @action = action
+        @user_id = user_id
+      end
+
+      # Generate structured log data for authorization failures
+      #
+      # @return [Hash] Hash suitable for structured logging
+      def to_log_data
+        {
+          error: message,
+          resource: resource,
+          action: action,
+          user_id: user_id,
+        }.compact
+      end
+    end
+  end
+end

data/lib/otto/security/config.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/security/config.rb
+#
+# frozen_string_literal: true
 
 require 'securerandom'
 require 'digest'

data/lib/otto/security/configurator.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/security/configurator.rb
+#
+# frozen_string_literal: true
 
 require_relative 'middleware/csrf_middleware'
 require_relative 'middleware/validation_middleware'
@@ -170,9 +170,24 @@ class Otto
 
       # 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
       end
 

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

@@ -1,3 +1,5 @@
+# lib/otto/security/middleware/ip_privacy_middleware.rb
+#
 # frozen_string_literal: true
 
 class Otto
@@ -87,24 +89,32 @@ class Otto
           env['REMOTE_ADDR'] = original_remote_addr
 
           # Set privacy-safe values in environment
-          env['otto.redacted_fingerprint'] = fingerprint
-          env['otto.masked_ip'] = fingerprint.masked_ip
-          env['otto.hashed_ip'] = fingerprint.hashed_ip
-          env['otto.geo_country'] = fingerprint.country
+          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 IP
+          # 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 IP without modification
+          # 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']
-          # This prevents accidental leakage of the real IP address
+          # 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
 
 
@@ -199,10 +209,20 @@ class Otto
         #
         # @param env [Hash] Rack environment
         def apply_no_privacy(env)
-          # Store original IP for explicit access
-          env['otto.original_ip'] = env['REMOTE_ADDR'].dup.force_encoding('UTF-8')
+          # 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'] remains unchanged (real IP)
+          # env['REMOTE_ADDR'], env['HTTP_USER_AGENT'], env['HTTP_REFERER'] remain unchanged (real values)
           # No fingerprint is created when privacy is disabled
         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

@@ -1,6 +1,9 @@
 # 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'

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.pre3'
+  VERSION = '2.0.0.pre7'
 end

data/lib/otto.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto.rb
+#
+# frozen_string_literal: true
 
 require 'json'
 require 'logger'
@@ -17,13 +17,14 @@ require_relative 'otto/static'
 require_relative 'otto/helpers'
 require_relative 'otto/response_handlers'
 require_relative 'otto/route_handlers'
-require_relative 'otto/locale/config'
+require_relative 'otto/locale'
 require_relative 'otto/mcp'
 require_relative 'otto/core'
 require_relative 'otto/privacy'
 require_relative 'otto/security'
 require_relative 'otto/utils'
 require_relative 'otto/version'
+require_relative 'otto/logging_helpers'
 
 # Otto is a simple Rack router that allows you to define routes in a file
 # with built-in security features including CSRF protection, input validation,
@@ -65,7 +66,8 @@ class Otto
 
   attr_reader :routes, :routes_literal, :routes_static, :route_definitions, :option,
               :static_route, :security_config, :locale_config, :auth_config,
-              :route_handler_factory, :mcp_server, :security, :middleware
+              :route_handler_factory, :mcp_server, :security, :middleware,
+              :error_handlers
   attr_accessor :not_found, :server_error
 
   def initialize(path = nil, opts = {})
@@ -77,6 +79,10 @@ class Otto
     load(path) unless path.nil?
     super()
 
+    # Auto-register AuthorizationError for 403 Forbidden responses
+    # This allows Logic classes to raise AuthorizationError for resource-level access control
+    register_error_handler(Otto::Security::AuthorizationError, status: 403, log_level: :warn)
+
     # Build the middleware app once after all initialization is complete
     build_app!
 
@@ -106,12 +112,35 @@ class Otto
       end
     end
 
+    # Track request timing for lifecycle hooks
+    start_time = Otto::Utils.now_in_μs
+    request = Rack::Request.new(env)
+    response_raw = nil
+
     begin
       # Use pre-built middleware app (built once at initialization)
-      @app.call(env)
+      response_raw = @app.call(env)
     rescue StandardError => e
-      handle_error(e, env)
+      response_raw = handle_error(e, env)
+    ensure
+      # Execute request completion hooks if any are registered
+      unless @request_complete_callbacks.empty?
+        begin
+          duration = Otto::Utils.now_in_μs - start_time
+          # Wrap response tuple in Rack::Response for developer-friendly API
+          # Otto's hook API should provide nice abstractions like Rack::Request/Response
+          response = Rack::Response.new(response_raw[2], response_raw[0], response_raw[1])
+          @request_complete_callbacks.each do |callback|
+            callback.call(request, response, duration)
+          end
+        rescue StandardError => e
+          Otto.logger.error "[Otto] Request completion hook error: #{e.message}"
+          Otto.logger.debug "[Otto] Hook error backtrace: #{e.backtrace.join("\n")}" if Otto.debug
+        end
+      end
     end
+
+    response_raw
   end
 
   # Builds the middleware application chain
@@ -145,7 +174,7 @@ class Otto
     # middleware_stack=), the @app instance variable could be swapped
     # mid-request in a multi-threaded environment.
 
-    build_app! if @app  # Rebuild app if already initialized
+    build_app! if @app # Rebuild app if already initialized
   end
 
   # Compatibility method for existing tests
@@ -157,7 +186,7 @@ class Otto
   def middleware_stack=(stack)
     @middleware.clear!
     Array(stack).each { |middleware| @middleware.add(middleware) }
-    build_app! if @app  # Rebuild app if already initialized
+    build_app! if @app # Rebuild app if already initialized
   end
 
   # Compatibility method for middleware detection
@@ -301,14 +330,73 @@ class Otto
   # @param strategy [Otto::Security::Authentication::AuthStrategy] Strategy instance
   # @example
   #   otto.add_auth_strategy('custom', MyCustomStrategy.new)
+  # Add an authentication strategy with a registered name
+  #
+  # This is the primary public API for registering authentication strategies.
+  # The name you provide here will be available as `strategy_result.strategy_name`
+  # in your application code, making it easy to identify which strategy authenticated
+  # the current request.
+  #
+  # Also available via Otto::Security::Configurator for consolidated security config.
+  #
+  # @param name [String, Symbol] Strategy name (e.g., 'session', 'api_key', 'jwt')
+  # @param strategy [AuthStrategy] Strategy instance
+  # @example
+  #   otto.add_auth_strategy('session', SessionStrategy.new(session_key: 'user_id'))
+  #   otto.add_auth_strategy('api_key', APIKeyStrategy.new)
+  # @raise [ArgumentError] if strategy name already registered
   def add_auth_strategy(name, strategy)
     ensure_not_frozen!
     # Ensure auth_config is initialized (handles edge case where it might be nil)
     @auth_config = { auth_strategies: {}, default_auth_strategy: 'noauth' } if @auth_config.nil?
 
+    # 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
   end
 
+  # Register an error handler for expected business logic errors
+  #
+  # This allows you to handle known error conditions (like missing resources,
+  # expired data, rate limits) without logging them as unhandled 500 errors.
+  #
+  # @param error_class [Class, String] The exception class or class name to handle
+  # @param status [Integer] HTTP status code to return (default: 500)
+  # @param log_level [Symbol] Log level for expected errors (:info, :warn, :error)
+  # @param handler [Proc] Optional block to customize error response
+  #
+  # @example Basic usage with status code
+  #   otto.register_error_handler(Onetime::MissingSecret, status: 404, log_level: :info)
+  #   otto.register_error_handler(Onetime::SecretExpired, status: 410, log_level: :info)
+  #
+  # @example With custom response handler
+  #   otto.register_error_handler(Onetime::RateLimited, status: 429, log_level: :warn) do |error, req|
+  #     {
+  #       error: 'Rate limit exceeded',
+  #       retry_after: error.retry_after,
+  #       message: error.message
+  #     }
+  #   end
+  #
+  # @example Using string class names (for lazy loading)
+  #   otto.register_error_handler('Onetime::MissingSecret', status: 404, log_level: :info)
+  #
+  def register_error_handler(error_class, status: 500, log_level: :info, &handler)
+    ensure_not_frozen!
+
+    # Normalize error class to string for consistent lookup
+    error_class_name = error_class.is_a?(String) ? error_class : error_class.name
+
+    @error_handlers[error_class_name] = {
+      status: status,
+      log_level: log_level,
+      handler: handler
+    }
+  end
+
   # Disable IP privacy to access original IP addresses
   #
   # IMPORTANT: By default, Otto masks public IP addresses for privacy.
@@ -327,7 +415,6 @@ class Otto
     @security_config.ip_privacy_config.disable!
   end
 
-
   # Enable full IP privacy (mask ALL IPs including private/localhost)
   #
   # By default, Otto exempts private and localhost IPs from masking for
@@ -346,6 +433,56 @@ class Otto
     @security_config.ip_privacy_config.mask_private_ips = true
   end
 
+  # Register a callback to be executed after each request completes
+  #
+  # Instance-level request completion callbacks allow each Otto instance
+  # to have its own isolated set of callbacks, preventing duplicate
+  # invocations in multi-app architectures (e.g., Rack::URLMap).
+  #
+  # The callback receives three arguments:
+  # - request: Rack::Request object
+  # - response: Rack::Response object (wrapping the response tuple)
+  # - duration: Request processing duration in microseconds
+  #
+  # @example Basic usage
+  #   otto = Otto.new(routes_file)
+  #   otto.on_request_complete do |req, res, duration|
+  #     logger.info "Request completed", path: req.path, duration: duration
+  #   end
+  #
+  # @example Multi-app architecture
+  #   # App 1: Core Web Application
+  #   core_router = Otto.new
+  #   core_router.on_request_complete do |req, res, duration|
+  #     logger.info "Core app request", path: req.path
+  #   end
+  #
+  #   # App 2: API Application
+  #   api_router = Otto.new
+  #   api_router.on_request_complete do |req, res, duration|
+  #     logger.info "API request", path: req.path
+  #   end
+  #
+  #   # Each callback only fires for its respective Otto instance
+  #
+  # @yield [request, response, duration] Block to execute after each request
+  # @yieldparam request [Rack::Request] The request object
+  # @yieldparam response [Rack::Response] The response object
+  # @yieldparam duration [Integer] Duration in microseconds
+  # @return [self] Returns self for method chaining
+  # @raise [FrozenError] if called after configuration is frozen
+  def on_request_complete(&block)
+    ensure_not_frozen!
+    @request_complete_callbacks << block if block_given?
+    self
+  end
+
+  # Get registered request completion callbacks (for internal use)
+  #
+  # @api private
+  # @return [Array<Proc>] Array of registered callback blocks
+  attr_reader :request_complete_callbacks
+
   # Configure IP privacy settings
   #
   # Privacy is enabled by default. Use this method to customize privacy
@@ -415,7 +552,9 @@ class Otto
     # Initialize @auth_config first so it can be shared with the configurator
     @auth_config       = { auth_strategies: {}, default_auth_strategy: 'noauth' }
     @security          = Otto::Security::Configurator.new(@security_config, @middleware, @auth_config)
-    @app               = nil  # Pre-built middleware app (built after initialization)
+    @app               = nil # Pre-built middleware app (built after initialization)
+    @request_complete_callbacks = [] # Instance-level request completion callbacks
+    @error_handlers    = {} # Registered error handlers for expected errors
 
     # Add IP Privacy middleware first in stack (privacy by default for public IPs)
     # Private/localhost IPs are automatically exempted from masking
@@ -449,6 +588,29 @@ class Otto
 
   class << self
     attr_accessor :debug, :logger # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+
+    # Helper method for structured logging that works with both standard Logger and structured loggers
+    def structured_log(level, message, data = {})
+      return unless logger
+
+      # Skip debug logging when Otto.debug is false
+      return if level == :debug && !debug
+
+      # Sanitize backtrace if present
+      if data.is_a?(Hash) && data[:backtrace].is_a?(Array)
+        data = data.dup
+        data[:backtrace] = Otto::LoggingHelpers.sanitize_backtrace(data[:backtrace])
+      end
+
+      # Try structured logging first (SemanticLogger, etc.)
+      if logger.respond_to?(level) && logger.method(level).arity > 1
+        logger.send(level, message, data)
+      else
+        # Fallback to standard logger with formatted string
+        formatted_data = data.empty? ? '' : " -- #{data.inspect}"
+        logger.send(level, "[Otto] #{message}#{formatted_data}")
+      end
+    end
   end
 
   # Class methods for Otto framework providing singleton access and configuration
@@ -471,7 +633,7 @@ class Otto
     end
 
     def env? *guesses
-      !guesses.flatten.select { |n| ENV['RACK_ENV'].to_s == n.to_s }.empty?
+      guesses.flatten.any? { |n| ENV['RACK_ENV'].to_s == n.to_s }
     end
 
     # Test-only method to unfreeze Otto configuration
@@ -488,9 +650,7 @@ class Otto
     # @raise [RuntimeError] if RSpec is not defined (not in test environment)
     # @api private
     def unfreeze_for_testing(otto)
-      unless defined?(RSpec)
-        raise 'Otto.unfreeze_for_testing is only available in RSpec test environment'
-      end
+      raise 'Otto.unfreeze_for_testing is only available in RSpec test environment' unless defined?(RSpec)
 
       otto.instance_variable_set(:@configuration_frozen, false)
       otto