otto 2.4.0 → 2.6.0

data/lib/otto/request.rb

@@ -24,6 +24,20 @@ class Otto
       env['HTTP_USER_AGENT']
     end
 
+    # Framework-owned, request-scoped CSP nonce, generated lazily on first
+    # access and memoized into the request env. Views call this to stamp
+    # `nonce="…"` onto their inline `<script>`/`<link>` tags; the same value is
+    # what {Otto::Security::CSP::EmitMiddleware} writes into the `script-src
+    # 'nonce-…'` header — so the header and the views agree structurally, not by
+    # convention. An untouched request generates nothing.
+    #
+    # The env key is configurable via {Otto::Security::Config#csp_nonce_key}.
+    #
+    # @return [String] this request's nonce (base64)
+    def csp_nonce
+      Otto::Security::CSP.nonce(env)
+    end
+
     # Canonical client IP for the request.
     #
     # Prefers env['otto.client_ip'] — the value resolved once, early, by
@@ -119,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

data/lib/otto/response.rb

@@ -14,12 +14,18 @@ class Otto
   # @example Using Otto's response in route handlers
   #   def show(req, res)
   #     res.send_secure_cookie('session_id', token, 3600)
-  #     res.send_csp_headers('text/html', nonce)
+  #     res.apply_csp(req.csp_nonce)
   #     res.no_cache!
   #   end
   #
   # @see Otto#register_response_helpers
   class Response < Rack::Response
+    # One-time-per-process guard for the #send_csp_headers deprecation warning.
+    @send_csp_headers_deprecation_warned = false
+    class << self
+      attr_accessor :send_csp_headers_deprecation_warned # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+    end
+
     # Reference to the request object (needed by some response helpers)
     # @return [Otto::Request]
     attr_accessor :request
@@ -97,56 +103,65 @@ class Otto
       headers
     end
 
-    # Set Content Security Policy (CSP) headers with nonce support
+    # Apply a nonce-based Content-Security-Policy to this response.
+    #
+    # This is THE emission helper: it routes through the single apply core
+    # ({Otto::Security::CSP::Writer}), so all the invariants — enabled-only,
+    # nonce-present, HTML-only, lowercase key, no duplicate — hold here exactly as
+    # they do in the middleware, with no guard logic duplicated. The response's
+    # Content-Type must already be set (it decides HTML-only); this helper does
+    # NOT set it.
+    #
+    # `mode: :override` (the default) is the deliberate per-request call: it
+    # REPLACES any existing CSP. Pass `mode: :backstop` to defer to an existing
+    # policy instead.
     #
-    # This method generates and sets CSP headers with the provided nonce value,
-    # following the same usage pattern as send_cookie methods. The CSP policy
-    # is generated dynamically based on the security configuration and environment.
+    # @param nonce [String] the per-request nonce (typically {Otto::Request#csp_nonce})
+    # @param mode [Symbol] `:override` or `:backstop` (see {Otto::Security::CSP::Writer::MODES})
+    # @param development_mode [Boolean] use development-friendly CSP directives
+    # @param security_config [Otto::Security::Config, nil] config to use; resolved
+    #   from the request env when omitted
+    # @return [Otto::Security::CSP::Writer::Result] the outcome (applied?, policy,
+    #   skip_reason) for uniform observability
     #
-    # @param content_type [String] Content-Type header value to set
+    # @example
+    #   res['content-type'] = 'text/html; charset=utf-8'
+    #   res.apply_csp(req.csp_nonce)
+    def apply_csp(nonce, mode: :override, development_mode: false, security_config: nil)
+      config = security_config || (request&.env && request.env['otto.security_config'])
+      Otto::Security::CSP::Writer.apply(
+        headers, nonce,
+        config: config, mode: mode, development_mode: development_mode
+      )
+    end
+
+    # @deprecated Use {#apply_csp} instead. Retained as a thin shim over the apply
+    #   core so existing callers keep working while its historical quirks are
+    #   fixed: a nil/empty nonce no longer emits a broken `script-src 'nonce-'`
+    #   (it skips), a CSP is no longer emitted for non-HTML responses, and the
+    #   override notice goes through {Otto.logger} instead of a bare `warn` to
+    #   stderr. Unlike {#apply_csp}, it still sets the Content-Type for you and
+    #   emits in `:override` mode.
+    #
+    # @param content_type [String] Content-Type to set if not already set
     # @param nonce [String] Nonce value to include in CSP directives
-    # @param opts [Hash] Options for CSP generation
+    # @param opts [Hash] Options
     # @option opts [Otto::Security::Config] :security_config Security config to use
     # @option opts [Boolean] :development_mode Use development-friendly CSP directives
-    # @option opts [Boolean] :debug Enable debug logging for this request
-    # @return [void]
-    #
-    # @example Basic usage
-    #   nonce = SecureRandom.base64(16)
-    #   res.send_csp_headers('text/html; charset=utf-8', nonce)
-    #
-    # @example With options
-    #   res.send_csp_headers('text/html; charset=utf-8', nonce, {
-    #     development_mode: Rails.env.development?,
-    #     debug: true
-    #   })
+    # @return [Otto::Security::CSP::Writer::Result]
     def send_csp_headers(content_type, nonce, opts = {})
-      # Set content type if not already set
-      headers['content-type'] ||= content_type
+      warn_send_csp_headers_deprecated
 
-      # Warn if CSP header already exists but don't skip
-      warn 'CSP header already set, overriding with nonce-based policy' if headers['content-security-policy']
-
-      # Get security configuration
-      security_config = opts[:security_config] ||
-                        (request&.env && request.env['otto.security_config']) ||
-                        nil
-
-      # Skip if CSP nonce support is not enabled
-      return unless security_config&.csp_nonce_enabled?
-
-      # Generate CSP policy with nonce
-      development_mode = opts[:development_mode] || false
-      csp_policy       = security_config.generate_nonce_csp(nonce, development_mode: development_mode)
-
-      # Debug logging if enabled
-      debug_enabled = opts[:debug] || security_config.debug_csp?
-      if debug_enabled && defined?(Otto.logger)
-        Otto.logger.debug "[CSP] #{csp_policy}"
-      end
+      # Historical behavior the shim keeps (apply_csp does not): default the
+      # Content-Type so an HTML response is recognized as HTML.
+      headers['content-type'] ||= content_type
 
-      # Set the CSP header
-      headers['content-security-policy'] = csp_policy
+      apply_csp(
+        nonce,
+        mode: :override,
+        development_mode: opts[:development_mode] || false,
+        security_config: opts[:security_config]
+      )
     end
 
     # Set cache control headers to prevent caching
@@ -187,5 +202,27 @@ class Otto
       paths.unshift(request.env['SCRIPT_NAME']) if request&.env&.[]('SCRIPT_NAME')
       paths.join('/').gsub('//', '/')
     end
+
+    private
+
+    # Emit the #send_csp_headers deprecation notice at most once per process
+    # (Response is per-request, so the guard lives on the class).
+    #
+    # The check-then-set on the class flag is deliberately unsynchronized: the
+    # race is benign — worst case, two threads racing on the very first call each
+    # log the notice once. The flag gates only a log line, never any behavior, so
+    # a mutex would add contention on a hot path to save at most a couple of
+    # duplicate deprecation lines at startup.
+    def warn_send_csp_headers_deprecated
+      return if self.class.send_csp_headers_deprecation_warned
+      return unless defined?(Otto.logger) && Otto.logger
+
+      self.class.send_csp_headers_deprecation_warned = true
+      Otto.logger.warn(
+        '[Otto::Response] #send_csp_headers is deprecated and will be removed in a ' \
+        'future release; use #apply_csp(nonce, mode: :override) (set Content-Type first), ' \
+        'or mount Otto::Security::CSP::EmitMiddleware via #enable_csp_emission!.'
+      )
+    end
   end
 end

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