otto 2.5.0 → 2.7.0

data/lib/otto/request.rb

@@ -133,6 +133,33 @@ class Otto
       redacted_fingerprint&.hashed_ip || env['otto.privacy.hashed_ip']
     end
 
+    # Get the stable-keyed correlation hash of the client IP.
+    #
+    # Contrast with #hashed_ip: that value is keyed with a daily-rotating
+    # secret (great for correlating requests within a session, useless across
+    # days). This value is HMAC-SHA256 over the SAME full, pre-masking client
+    # IP but keyed with a caller-configured STABLE secret, so the same IP
+    # produces the same hash indefinitely — the granularity long-lived audit
+    # records need without ever handling the raw IP.
+    #
+    # Both are computed before masking, so both reflect the per-host address
+    # (not the /24 the app is otherwise left with); the raw IP itself never
+    # reaches the application — only the hash does.
+    #
+    # Returns nil when IP privacy is disabled, no correlation secret is
+    # configured (see Otto#configure_ip_privacy(correlation_secret:)), or the
+    # client IP is exempt from masking. By default private/localhost IPs are
+    # exempt (mask_private_ips is false), so this is nil for RFC-1918 and
+    # loopback addresses — including the common local dev path — just like
+    # #masked_ip and #hashed_ip. It targets public audit-trail traffic.
+    #
+    # @return [String, nil] Hexadecimal HMAC-SHA256 hash string or nil
+    # @example
+    #   req.ip_correlation_hash  # => 'b7e2...'  (stable across days)
+    def ip_correlation_hash
+      env['otto.privacy.correlation_hash']
+    end
+
     def client_ipaddress
       # Prefer the canonical client IP resolved once by IPPrivacyMiddleware
       # ("resolve once, read everywhere"). Falls back to the shared resolver
@@ -195,8 +222,15 @@ class Otto
       # Check direct HTTPS connection
       return true if env['HTTPS'] == 'on' || env['SERVER_PORT'] == '443'
 
+      # rack.url_scheme is server-/middleware-set (never a client header), so a
+      # scheme normalized upstream the canonical Rack way counts as authoritative
+      # — keeping this answer aligned with Rack::Request#scheme, which the
+      # session Secure-cookie gate and CSRF middleware read.
+      return true if env['rack.url_scheme'] == 'https'
+
       # Only trust forwarded proto headers when the request actually arrived via
-      # a trusted proxy.
+      # a trusted proxy. Stricter than Rack::Request#scheme, which honors
+      # X-Forwarded-Proto unconditionally.
       return false unless forwarded_by_trusted_proxy?
 
       # X-Scheme is set by nginx; X-Forwarded-Proto by elastic load balancer

data/lib/otto/route.rb

@@ -2,6 +2,8 @@
 #
 # frozen_string_literal: true
 
+require 'concurrent'
+
 require_relative 'security/constant_resolver'
 
 class Otto
@@ -24,9 +26,44 @@ class Otto
   #
   #
   class Route
-    # Class methods for Route providing Otto instance access
+    # Class methods for Route providing Otto instance access.
+    #
+    # `route.rb` and `route_handlers/base.rb` `extend` this onto the target
+    # class on every request and set `.otto = otto_instance` so app code can
+    # read `self.class.otto` from within a handler method. A plain class
+    # ivar here would be shared, mutable state: two `Otto` instances sharing
+    # a controller/logic class, or concurrent threads/fibers serving
+    # requests under different `Otto` instances, would race and clobber
+    # `klass.otto`, leaking one request's security_config/auth_config into
+    # another's handler (issue #188). Backing the accessor with a
+    # `Concurrent::FiberLocalVar` scopes each assignment to the fiber/thread
+    # actually serving that request instead.
+    #
+    # NOTE (Otto v3): this whole class-level accessor is ambient per-request
+    # state and exists only as a convenience so handler code can reach otto via
+    # `self.class.otto`. The clean design carries no ambient state at all —
+    # the handler instance already receives its `Otto` explicitly
+    # (`BaseHandler.new(route_definition, otto_instance)`), so app code should
+    # read it from an instance-level `#otto` reader instead. Recommended for
+    # Otto v3: expose `otto` on the handler instance, deprecate
+    # `self.class.otto`, and drop `ClassMethods` — then there is no shared slot
+    # to race, reset, or leak, and this fiber-local workaround goes away.
     module ClassMethods
-      attr_accessor :otto
+      # Per-fiber storage keyed by target class. Deliberately
+      # `FiberLocalVar`, not `ThreadLocalVar`: fiber-per-request schedulers
+      # (Falcon/Async) run many requests as fibers in one thread, so
+      # thread-scoped storage would let those fibers clobber each other's
+      # `klass.otto` — the same race, one level down. The default block gives
+      # each fiber its own class => otto hash on first access.
+      OTTO_INSTANCES = Concurrent::FiberLocalVar.new { {} }
+
+      def otto=(instance)
+        OTTO_INSTANCES.value[self] = instance
+      end
+
+      def otto
+        OTTO_INSTANCES.value[self]
+      end
     end
     # @return [Otto::RouteDefinition] The immutable route definition
     attr_reader :route_definition
@@ -52,8 +89,15 @@ class Otto
       # Create immutable route definition
       @route_definition = Otto::RouteDefinition.new(verb, path, definition, pattern: pattern, keys: keys)
 
-      # Resolve the class
-      @klass = Otto::Security::ConstantResolver.safe_const_get(@route_definition.klass_name)
+      # Resolve the class.
+      # Lambda routes carry a registry KEY in klass_name, not a Ruby constant.
+      # Skip constant resolution (it would raise on a lowercase/unregistered key
+      # and the loader would silently drop the route).
+      @klass = if @route_definition.kind == :lambda
+                 nil
+               else
+                 Otto::Security::ConstantResolver.safe_const_get(@route_definition.klass_name)
+               end
     end
 
     # Delegate common methods to route_definition for backward compatibility
@@ -102,14 +146,37 @@ class Otto
     # @return [Array] Rack response array [status, headers, body]
     def call(env, extra_params = {})
       extra_params ||= {}
-      req            = otto.request_class.new(env)
-      res            = otto.response_class.new
+
+      # Pluggable route handler factory (Phase 4). The handler owns
+      # request/response construction and decoration — param merging,
+      # indifferent access, security headers, CSRF/validation helpers all
+      # happen once in BaseHandler#setup_request_response. Building them here
+      # too would duplicate that work on objects that get discarded (issue #189).
+      if otto&.route_handler_factory
+        # Make security config, route definition, and options available to
+        # middleware and handlers before delegating, so wrappers that run
+        # ahead of the handler's own setup (RouteAuthWrapper, the centralized
+        # error handler) can see them.
+        env['otto.security_config'] = otto.security_config if otto.respond_to?(:security_config) && otto.security_config
+        env['otto.route_definition'] = @route_definition
+        env['otto.route_options'] = @route_definition.options
+
+        handler = otto.route_handler_factory.create_handler(@route_definition, otto)
+        return handler.call(env, extra_params)
+      end
+
+      # Fallback to legacy behavior for backward compatibility. Build req/res
+      # before touching env, preserving the exact ordering this path always
+      # had — a custom request_class/response_class#initialize that reads env
+      # must keep seeing it unpopulated, same as before #189 (review follow-up).
+      req         = otto.request_class.new(env)
+      res         = otto.response_class.new
       res.request = req
 
       # Make security config available to response helpers
       env['otto.security_config'] = otto.security_config if otto.respond_to?(:security_config) && otto.security_config
 
-      # NEW: Make route definition and options available to middleware and handlers
+      # Make route definition and options available to middleware and handlers
       env['otto.route_definition'] = @route_definition
       env['otto.route_options'] = @route_definition.options
 
@@ -124,8 +191,11 @@ class Otto
         end
       end
 
-      klass.extend Otto::Route::ClassMethods
-      klass.otto = otto
+      # No target class for lambda routes (klass is nil); skip class extension.
+      if klass
+        klass.extend Otto::Route::ClassMethods
+        klass.otto = otto
+      end
 
       # Add security helpers if CSRF is enabled
       if otto.respond_to?(:security_config) && otto.security_config&.csrf_enabled?
@@ -135,39 +205,31 @@ class Otto
       # Add validation helpers
       res.extend Otto::Security::ValidationHelpers
 
-      # NEW: Use the pluggable route handler factory (Phase 4)
-      # This replaces the hardcoded execution pattern with a factory approach
-      if otto&.route_handler_factory
-        handler = otto.route_handler_factory.create_handler(@route_definition, otto)
-        handler.call(env, extra_params)
-      else
-        # Fallback to legacy behavior for backward compatibility
-        inst = nil
-        result = case kind
-                 when :instance
-                   inst = klass.new req, res
-                   inst.send(name)
-                 when :class
-                   klass.send(name, req, res)
-                 else
-                   raise "Unsupported kind for #{definition}: #{kind}"
-                 end
-
-        # Handle response based on route options
-        response_type = @route_definition.response_type
-        if response_type != 'default'
-          context = {
-            logic_instance: (kind == :instance ? inst : nil),
-               status_code: nil,
-             redirect_path: nil,
-          }
-
-          Otto::ResponseHandlers::HandlerFactory.handle_response(result, res, response_type, context)
-        end
-
-        res.body = [res.body] unless res.body.respond_to?(:each)
-        res.finish
+      inst = nil
+      result = case kind
+               when :instance
+                 inst = klass.new req, res
+                 inst.send(name)
+               when :class
+                 klass.send(name, req, res)
+               else
+                 raise "Unsupported kind for #{definition}: #{kind}"
+               end
+
+      # Handle response based on route options
+      response_type = @route_definition.response_type
+      if response_type != 'default'
+        context = {
+          logic_instance: (kind == :instance ? inst : nil),
+             status_code: nil,
+           redirect_path: nil,
+        }
+
+        Otto::ResponseHandlers::HandlerFactory.handle_response(result, res, response_type, context)
       end
+
+      res.body = [res.body] unless res.body.respond_to?(:each)
+      res.finish
     end
 
     private

data/lib/otto/route_definition.rb

@@ -2,10 +2,18 @@
 #
 # frozen_string_literal: true
 
+require_relative 'errors'
+
 class Otto
   # Immutable data class representing a complete route definition
   # This encapsulates all aspects of a route: path, target, and options
   class RouteDefinition
+    # Options that gate access to a route. A malformed token for one of these
+    # (e.g. `csrf` instead of `csrf=exempt`, or a bare `auth`) must not fall
+    # back to the default behavior silently — the route would serve without
+    # its intended protection (issue #191).
+    SECURITY_GATING_OPTIONS = %w[auth role csrf].freeze
+
     # @return [String] The HTTP verb (GET, POST, etc.)
     attr_reader :verb
 
@@ -112,6 +120,32 @@ class Otto
       option(:response, 'default')
     end
 
+    # Parse a single whitespace-delimited `key=value` option token, applying
+    # the security-gating fail-fast rule shared by normal routes and the MCP
+    # RouteParser (issue #191 and its MCP/TOOL follow-up).
+    # @param part [String] a single option token, e.g. "auth=session"
+    # @param context [String] human-readable source description for the
+    #   raised error message, e.g. "route definition \"GET /admin ...\""
+    # @return [Array(Symbol, String), nil] the [key, value] pair to store,
+    #   or nil if the token is malformed and should only be warned about
+    # @raise [Otto::RouteDefinitionError] if a security-gating option
+    #   (auth/role/csrf) is malformed
+    def self.parse_option_token(part, context)
+      key, value = part.split('=', 2)
+      normalized_key = key&.downcase
+
+      if SECURITY_GATING_OPTIONS.include?(normalized_key)
+        if key != normalized_key || value.nil? || value.empty?
+          raise Otto::RouteDefinitionError,
+                "Malformed security option #{part.inspect} in #{context}: " \
+                "expected #{normalized_key}=value"
+        end
+        [key.to_sym, value]
+      elsif key && !key.empty? && value
+        [key.to_sym, value]
+      end
+    end
+
     # Check if CSRF is exempt for this route
     # @return [Boolean]
     def csrf_exempt?
@@ -168,18 +202,21 @@ class Otto
     # Parse route definition into target and options
     # @param definition [String] The route definition
     # @return [Hash] Hash with :target and :options keys
+    # @raise [Otto::RouteDefinitionError] if a security-gating option token
+    #   (auth/role/csrf) has no value — failing fast instead of serving the
+    #   route with default (less safe) behavior
     def parse_definition(definition)
       parts   = definition.split(/\s+/)
       target  = parts.shift
       options = {}
 
       parts.each do |part|
-        key, value = part.split('=', 2)
-        if key && value
-          options[key.to_sym] = value
-        elsif Otto.debug
-          # Malformed parameter, log warning if debug enabled
-          Otto.logger.warn "Ignoring malformed route parameter: #{part}"
+        pair = self.class.parse_option_token(part, "route definition #{definition.inspect}")
+        if pair
+          options[pair[0]] = pair[1]
+        else
+          Otto.structured_log(:warn, 'Malformed route option ignored',
+            { option: part, definition: definition })
         end
       end
 
@@ -191,6 +228,19 @@ class Otto
     # @return [Hash] Hash with :klass_name, :method_name, and :kind
     def parse_target(target)
       case target
+      when /^&/
+        # Lambda handler: '&name' references a proc pre-registered in the
+        # lambda_handlers registry. The entire remainder after '&' is the exact
+        # O(1) Hash lookup key (may contain '.', '#', '::' — all inert here;
+        # resolution is string equality, never eval/const_get). Issue #41 security.
+        name = target[1..].to_s
+        if name.strip.empty?
+          raise ArgumentError,
+                "Invalid lambda handler target #{target.inspect}: handler name " \
+                "after '&' cannot be empty (expected '&handler_name')"
+        end
+        { klass_name: name, method_name: nil, kind: :lambda }
+
       when /^(.+)\.(.+)$/
         # Class.method - call class method directly
         { klass_name: ::Regexp.last_match(1), method_name: ::Regexp.last_match(2), kind: :class }

data/lib/otto/route_handlers/base.rb

@@ -125,6 +125,10 @@ class Otto
       # @param env [Hash] Rack environment
       # @param extra_params [Hash] Additional parameters
       def setup_request_response(req, res, env, extra_params)
+        # Expose the raw path-capture hash to invoke_target (LambdaHandler
+        # passes it as the proc's 3rd arg). Inert for other subclasses.
+        @extra_params = extra_params
+
         # Set request reference (helpers are already included in class)
         res.request = req
 

data/lib/otto/route_handlers/factory.rb

@@ -4,6 +4,7 @@
 
 require_relative 'base'
 require_relative '../security/authentication/route_auth_wrapper'
+require_relative '../security/csrf_enforcement_wrapper'
 
 class Otto
   module RouteHandlers
@@ -19,6 +20,7 @@ class Otto
                         when :logic then LogicClassHandler
                         when :instance then InstanceMethodHandler
                         when :class then ClassMethodHandler
+                        when :lambda then LambdaHandler
                         else
                           raise ArgumentError, "Unknown handler kind: #{route_definition.kind}"
                         end
@@ -37,6 +39,19 @@ class Otto
           )
         end
 
+        # Enforce CSRF at the handler layer, where `csrf=exempt` is visible
+        # (the global CSRFMiddleware runs ahead of route matching and cannot
+        # honor per-route exemption — issue #186). Wrapped OUTSIDE
+        # RouteAuthWrapper so a forged unsafe request is rejected before any
+        # authentication work runs. Only added when protection is enabled.
+        if otto_instance&.security_config&.csrf_enabled?
+          handler = Otto::Security::CSRFEnforcementWrapper.new(
+            handler,
+            route_definition,
+            otto_instance.security_config
+          )
+        end
+
         apply_handler_wrappers(handler, route_definition, otto_instance)
       end
 

data/lib/otto/route_handlers/lambda.rb

@@ -1,46 +1,61 @@
 # lib/otto/route_handlers/lambda.rb
 #
 # frozen_string_literal: true
-require 'securerandom'
 
 require_relative 'base'
 
 class Otto
   module RouteHandlers
-    # Custom handler for lambda/proc definitions (future extension)
+    # Handler for pre-registered lambda/proc route targets (issue #41).
+    #
+    # Route syntax `GET /ping &health_check` parses to kind :lambda with
+    # klass_name = "health_check" (the registry KEY, not a Ruby constant) and
+    # method_name = nil. The proc is looked up O(1) by name from the Otto
+    # instance's pre-registered lambda_handlers — no eval, no dynamic constants.
+    #
+    # Reuses BaseHandler#call: implements #invoke_target and guards the base's
+    # constant-resolution steps (#target_class / #handler_name).
     class LambdaHandler < BaseHandler
-      def call(env, extra_params = {})
-        start_time = Otto::Utils.now_in_μs
-        req = otto_instance ? otto_instance.request_class.new(env) : Otto::Request.new(env)
-        res = otto_instance ? otto_instance.response_class.new : Otto::Response.new
-
-        begin
-          # Security: Lambda handlers require pre-configured procs from Otto instance
-          # This prevents code injection via eval and maintains security
-          handler_name    = route_definition.klass_name
-          lambda_registry = otto_instance&.config&.dig(:lambda_handlers) || {}
-
-          lambda_proc = lambda_registry[handler_name]
-          unless lambda_proc.respond_to?(:call)
-            raise ArgumentError, "Lambda handler '#{handler_name}' not found in registry or not callable"
-          end
-
-          result = lambda_proc.call(req, res, extra_params)
-
-          handle_response(result, res, {
-                            lambda: lambda_proc,
-            request: req,
-                          })
-        rescue StandardError => e
-          # Store handler context in env for centralized error handler
-          handler_name = "Lambda[#{route_definition.klass_name}]"
-          env['otto.handler'] = handler_name
-          env['otto.handler_duration'] = Otto::Utils.now_in_μs - start_time
-
-          raise e # Re-raise to let Otto's centralized error handler manage the response
+      protected
+
+      # No Ruby constant backs a lambda route. Returning nil (a) prevents
+      # ConstantResolver.safe_const_get from raising on a registry key and
+      # (b) makes BaseHandler#setup_request_response skip its target_class
+      # extension block.
+      def target_class
+        nil
+      end
+
+      # Derive the log/handler name from the route, not target_class.name
+      # (which would be nil.name -> NoMethodError inside handle_execution_error).
+      def handler_name
+        "Lambda[#{route_definition.klass_name}]"
+      end
+
+      # Look up the pre-registered proc and invoke it with (req, res, extra_params).
+      # @return [Array] [result, context] consumed by BaseHandler#handle_response
+      def invoke_target(req, res)
+        handler_key = route_definition.klass_name
+        lambda_proc = lambda_registry[handler_key]
+
+        unless lambda_proc.respond_to?(:call)
+          raise ArgumentError,
+                "Lambda handler '#{handler_key}' is not registered or not callable"
         end
 
-        res.finish
+        result = lambda_proc.call(req, res, @extra_params || {})
+        [result, { request: req }]
+      end
+
+      private
+
+      # O(1) read of the frozen registry from Otto config. Tolerates the
+      # direct-testing context (no otto_instance / no :config) by returning {},
+      # so invoke_target raises the clear "not registered" ArgumentError.
+      def lambda_registry
+        return {} unless otto_instance.respond_to?(:config)
+
+        (otto_instance.config && otto_instance.config[:lambda_handlers]) || {}
       end
     end
   end

data/lib/otto/security/authentication/auth_failure.rb

@@ -6,10 +6,44 @@ class Otto
   module Security
     module Authentication
       # Failure result for authentication failures
-      AuthFailure = Data.define(:failure_reason, :auth_method) do
+      AuthFailure = Data.define(:failure_reason, :auth_method, :terminal) do
         # AuthFailure represents authentication failure
         # Returned by strategies when authentication fails
         # Contains failure reason for error messages
+        #
+        # TERMINAL FAILURES
+        # -----------------
+        # By default a failure is non-terminal: RouteAuthWrapper records it and
+        # consults the next strategy in the route's chain (OR logic), so a
+        # request without credentials can still fall through to an
+        # anonymous-capable strategy like noauth.
+        #
+        # A failure constructed with `terminal: true` means "this request
+        # explicitly presented credentials and they were examined and
+        # rejected — do not consult further strategies." RouteAuthWrapper
+        # halts the chain and renders the 401 with this failure's reason,
+        # regardless of where the strategy sits in the chain. This lets mixed
+        # credentialed/anonymous chains (e.g. auth=basicauth,noauth) fail
+        # closed on invalid credentials instead of silently degrading to
+        # anonymous.
+        #
+        # Only reject terminally when credentials were EXPLICITLY presented
+        # (e.g. an Authorization header). Ambient credentials such as session
+        # cookies should fail non-terminally so a logged-out browser can still
+        # degrade to anonymous on noauth-capable routes.
+
+        # terminal defaults to false so existing keyword construction
+        # (failure_reason:, auth_method:) is unaffected.
+        def initialize(failure_reason:, auth_method:, terminal: false)
+          super
+        end
+
+        # Check if this failure halts the strategy chain
+        #
+        # @return [Boolean] True when the chain must fail closed
+        def terminal?
+          terminal
+        end
 
         # Check if authenticated - always false for failures
         #
@@ -36,7 +70,7 @@ class Otto
         #
         # @return [String] Debug representation
         def inspect
-          "#<AuthFailure reason=#{failure_reason.inspect} method=#{auth_method}>"
+          "#<AuthFailure reason=#{failure_reason.inspect} method=#{auth_method}#{' terminal' if terminal}>"
         end
       end
     end

data/lib/otto/security/authentication/auth_strategy.rb

@@ -42,11 +42,21 @@ class Otto
         # Use for a missing, invalid, or expired credential. RouteAuthWrapper maps
         # this to 401 Unauthorized. For a VALID credential that is not permitted,
         # use #authorization_failure instead (403 Forbidden).
-        def failure(reason = nil)
+        #
+        # Pass terminal: true when the request EXPLICITLY presented credentials
+        # (e.g. an Authorization header) that were examined and rejected.
+        # RouteAuthWrapper then halts the strategy chain and fails closed with
+        # 401 instead of consulting further strategies — so an anonymous-capable
+        # strategy later (or earlier) in the chain cannot silently accept the
+        # request as anonymous. Leave it false for missing credentials and for
+        # ambient credentials (session cookies), which should keep today's OR
+        # fallthrough. See AuthFailure.
+        def failure(reason = nil, terminal: false)
           Otto.logger.debug "[#{self.class}] Authentication failed: #{reason}" if reason
           Otto::Security::Authentication::AuthFailure.new(
             failure_reason: reason || 'Authentication failed',
-            auth_method: strategy_auth_method
+            auth_method: strategy_auth_method,
+            terminal: terminal
           )
         end
 

data/lib/otto/security/authentication/authorization_failure.rb

@@ -26,6 +26,13 @@ class Otto
       # StrategyResult. This type covers the complementary case: a strategy that
       # owns authorization itself (including permission tiers, which Layer-1 does
       # not model) and needs to signal a 403 directly.
+      #
+      # DELIBERATELY has no `terminal` member (unlike AuthFailure): an
+      # authorization denial must not halt the strategy chain — a later
+      # strategy's success still wins (a different credential may well be
+      # permitted). When the chain DOES end in failure, a recorded denial
+      # already takes response precedence (403 over 401, even over a terminal
+      # halt), so there is nothing a terminal flag here would add.
       AuthorizationFailure = Data.define(:failure_reason, :auth_method) do
         # Authorization failures are not an authenticated request state. The
         # request never reaches the handler, so handler-facing predicates report