otto 2.5.0 → 2.6.0

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/config.rb

@@ -72,7 +72,8 @@ class Otto
                   :security_headers,
                   :csp_nonce_enabled, :debug_csp, :mcp_auth, :csp_nonce_key,
                   :ip_privacy_config, :trusted_proxy_depth, :trusted_proxy_header,
-                  :csp_report_uri, :csp_report_to_url, :csp_violation_callback
+                  :csp_report_uri, :csp_report_to_url, :csp_violation_callback,
+                  :csp_directive_overrides
 
       # Initialize security configuration with safe defaults
       #
@@ -100,6 +101,8 @@ class Otto
         @csp_report_uri         = nil
         @csp_report_to_url      = nil
         @csp_violation_callback = nil
+        @csp_directive_overrides = {}
+        @csp_script_src_override_warned = false
         @rate_limiting_config   = { custom_rules: {} }
         @ip_privacy_config      = Otto::Privacy::Config.new
 
@@ -367,19 +370,85 @@ class Otto
       # Unlike enable_csp!, this doesn't set a static policy but enables the response
       # helper to generate CSP headers with nonces on a per-request basis.
       #
+      # Per-directive overrides may be supplied to customize the emitted nonce
+      # policy without vendoring the gem. They merge into Otto's base directive
+      # sets ({Otto::Security::CSP::Policy.development_directives} /
+      # {Otto::Security::CSP::Policy.production_directives}): a matching directive
+      # is replaced in place, a new directive is appended, and a nil/false value
+      # removes a directive. See {#csp_directive_overrides=} for the accepted
+      # shape.
+      #
       # @param debug [Boolean] Enable debug logging for CSP headers (default: false)
+      # @param directives [Hash] per-directive overrides merged into the base set
       # @return [void]
       # @raise [FrozenError] if configuration is frozen
       #
       # @example
       #   config.enable_csp_with_nonce!(debug: true)
-      def enable_csp_with_nonce!(debug: false)
+      #
+      # @example Restore data: workers (blob: is the default worker-src token)
+      #   config.enable_csp_with_nonce!(directives: { 'worker-src' => "'self' data: blob:" })
+      def enable_csp_with_nonce!(debug: false, directives: {})
         ensure_not_frozen!
 
+        # Apply overrides before toggling state so a bad +directives+ argument
+        # raises without leaving the config half-updated (nonce enabled but
+        # overrides not merged).
+        merge_csp_directives(directives) unless directives.nil? || directives.empty?
         @csp_nonce_enabled = true
         @debug_csp         = debug
       end
 
+      # Replace the per-directive overrides applied to the nonce CSP policy.
+      #
+      # Overrides merge into Otto's base directive sets when
+      # {#generate_nonce_csp} builds the policy, so a consuming app can adjust
+      # ANY directive rather than only `report-uri`/`report-to`. Keys are
+      # directive names (String or Symbol, matched case-insensitively); values
+      # are the source list as a String (`"'self' blob:"`) or Array
+      # (`%w['self' blob:]`), or nil/false to REMOVE the directive.
+      #
+      # Keys are normalized on store (lowercased, hyphenated) via
+      # {Otto::Security::CSP::Policy.normalize_overrides}, so the stored hash
+      # never accumulates logically-identical entries under different key styles
+      # (`'WORKER-SRC'` and `:worker_src` both read back as `'worker-src'`).
+      #
+      # @note Overriding `script-src` while nonce mode is enabled disables
+      #   nonce-based script protection: the per-request nonce cannot be
+      #   included in a static override, so it is stripped from the emitted
+      #   header. A warning is logged when a `script-src` override is stored.
+      #   See {Otto::Security::CSP::Policy.merge_directives}.
+      #
+      # @param overrides [Hash] directive name => source list / nil
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      #
+      # @example
+      #   config.csp_directive_overrides = { 'worker-src' => "'self' data: blob:" }
+      def csp_directive_overrides=(overrides)
+        ensure_not_frozen!
+
+        normalized = Otto::Security::CSP::Policy.normalize_overrides(overrides || {})
+        warn_if_script_src_overridden(normalized)
+        @csp_directive_overrides = normalized
+      end
+
+      # Merge additional per-directive overrides into the existing set, leaving
+      # untouched any directive not named in +overrides+ (last write wins for a
+      # repeated directive). Use this to accumulate overrides incrementally;
+      # use {#csp_directive_overrides=} to replace them wholesale.
+      #
+      # @param overrides [Hash] directive name => source list / nil
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      def merge_csp_directives(overrides)
+        ensure_not_frozen!
+
+        normalized = Otto::Security::CSP::Policy.normalize_overrides(overrides || {})
+        warn_if_script_src_overridden(normalized)
+        @csp_directive_overrides = @csp_directive_overrides.merge(normalized)
+      end
+
       # Disable CSP nonce support
       #
       # @return [void]
@@ -527,8 +596,10 @@ class Otto
       # Generate a CSP policy string with the provided nonce
       #
       # Thin facade over {Otto::Security::CSP::Policy.nonce_policy}; the directive
-      # sets and report-uri/report-to assembly live there now. Output is
-      # byte-identical to Otto's historical policy.
+      # sets and report-uri/report-to assembly live there now. Any configured
+      # {#csp_directive_overrides} are merged into the base directive set. Output
+      # is byte-identical to Otto's historical policy when no overrides or
+      # reporting are configured.
       #
       # @param nonce [String] The nonce value to include in the CSP
       # @param development_mode [Boolean] Whether to use development-friendly directives
@@ -538,7 +609,8 @@ class Otto
           nonce,
           development_mode: development_mode,
           report_uri: @csp_report_uri,
-          report_to_url: @csp_report_to_url
+          report_to_url: @csp_report_to_url,
+          directive_overrides: @csp_directive_overrides
         )
       end
 
@@ -819,6 +891,29 @@ class Otto
         MSG
       end
 
+      # Warn once per config instance when a `script-src` override is stored for
+      # the nonce CSP policy. The per-request nonce is generated at response time
+      # and therefore cannot be present in a static override, so replacing (or
+      # removing) `script-src` necessarily strips the nonce from the emitted
+      # header — the browser then accepts any inline script the page carries the
+      # nonce attribute on, voiding nonce-based protection. Overriding any other
+      # directive (e.g. `worker-src`) is unaffected and stays silent.
+      #
+      # @param normalized [Hash] normalized (lowercased/hyphenated) overrides
+      # @return [void]
+      def warn_if_script_src_overridden(normalized)
+        return unless normalized.key?('script-src')
+        return if @csp_script_src_override_warned
+
+        @csp_script_src_override_warned = true
+        Otto.structured_log(:warn, <<~MSG.gsub(/\s+/, ' ').strip, directive: 'script-src')
+          [Otto::CSP] A script-src override was configured while nonce mode is in
+          use. The per-request nonce cannot be included in a static override, so
+          nonce-based script protection is disabled for this policy. Remove the
+          script-src override to keep nonce enforcement.
+        MSG
+      end
+
       # Freeze-time backstop: refuse to finalize a production configuration that
       # enables CSRF with a generated (non-configured) secret. Mirrors
       # #validate_trusted_proxy_config! so the failure surfaces at boot, before