otto 2.5.0 → 2.6.0

data/lib/otto/security/csp/policy.rb

@@ -43,9 +43,14 @@ class Otto
         # @param report_to_url [String, nil] absolute URL configured for the
         #   modern Reporting API; its presence (not its value) toggles the
         #   `report-to <group>` directive (omitted when nil/empty)
+        # @param directive_overrides [Hash, nil] per-directive overrides merged
+        #   into the base set before reporting directives are appended. See
+        #   {.merge_directives} for the accepted shape (replace a directive's
+        #   sources, add a new directive, or remove one with a nil/false value).
         # @return [String] complete CSP policy string
-        def nonce_policy(nonce, development_mode: false, report_uri: nil, report_to_url: nil)
+        def nonce_policy(nonce, development_mode: false, report_uri: nil, report_to_url: nil, directive_overrides: nil)
           directives = development_mode ? development_directives(nonce) : production_directives(nonce)
+          directives = merge_directives(directives, directive_overrides)
           uri_directive = report_uri_directive(report_uri)
           to_directive  = report_to_directive(report_to_url)
           directives += ["#{uri_directive};"] if uri_directive
@@ -88,6 +93,133 @@ class Otto
           "report-to #{REPORTING_GROUP}"
         end
 
+        # Merge per-directive overrides into a base directive set.
+        #
+        # This is the customization seam the hardcoded directive sets previously
+        # lacked: a consuming app can adjust ANY directive (e.g. re-allow
+        # `data:` workers via `worker-src 'self' data: blob:`) without
+        # vendoring the gem. Order is
+        # preserved — an override that matches an existing directive replaces it
+        # in place; an override for a directive not in the base set is appended
+        # after the base directives (before any reporting directives).
+        #
+        # Override values:
+        # - a String  → the directive's source list verbatim, e.g.
+        #   `'worker-src' => "'self' blob:"` yields `worker-src 'self' blob:;`
+        # - an Array   → sources joined with a single space, e.g.
+        #   `%w['self' blob:]`
+        # - `nil`/`false` → REMOVE the directive from the emitted policy
+        #
+        # Directive names are matched case-insensitively (CSP directive names are
+        # case-insensitive) and may be given as Strings or Symbols.
+        #
+        # @note The per-request nonce is embedded in `script-src` (production)
+        #   and cannot be reproduced in a static override, so replacing (or
+        #   removing) `script-src` strips the nonce from the emitted header and
+        #   DEFEATS nonce protection: the browser then accepts any inline script
+        #   the page carries the nonce attribute on. Overriding `script-src`
+        #   while nonce mode is enabled therefore disables nonce enforcement;
+        #   {Otto::Security::Config} logs a warning when such an override is
+        #   configured. Override other directives freely.
+        #
+        # @param directives [Array<String>] base directive strings, each `;`-terminated
+        # @param overrides [Hash, nil] directive name => source list / nil
+        # @return [Array<String>] merged directive strings, each `;`-terminated
+        # @raise [ArgumentError] if an override name or source token contains a
+        #   `;`, newline, or carriage return (see {.build_directive})
+        def merge_directives(directives, overrides)
+          return directives if overrides.nil? || overrides.empty?
+
+          normalized = normalize_overrides(overrides)
+          consumed   = {}
+
+          merged = directives.filter_map do |directive|
+            name = directive_name(directive)
+            next directive unless normalized.key?(name)
+
+            consumed[name] = true
+            build_directive(name, normalized[name])
+          end
+
+          normalized.each do |name, value|
+            next if consumed[name]
+
+            appended = build_directive(name, value)
+            merged << appended if appended
+          end
+
+          merged
+        end
+
+        # Normalize an overrides hash to lowercased, hyphenated String keys so
+        # lookups are case-insensitive and Symbol/String keys are
+        # interchangeable. Underscores map to hyphens (no CSP directive contains
+        # an underscore) so a Symbol key like `:worker_src` addresses the
+        # `worker-src` directive. Blank keys are dropped.
+        #
+        # @param overrides [Hash]
+        # @return [Hash{String=>Object}]
+        def normalize_overrides(overrides)
+          overrides.each_with_object({}) do |(key, value), acc|
+            name = key.to_s.strip.downcase.tr('_', '-')
+            acc[name] = value unless name.empty?
+          end
+        end
+
+        # The directive name (first token) of a `;`-terminated directive string,
+        # lowercased for case-insensitive matching.
+        #
+        # @param directive [String]
+        # @return [String]
+        def directive_name(directive)
+          directive.to_s.strip.delete_suffix(';').split(/\s+/, 2).first.to_s.downcase
+        end
+
+        # Build a single `;`-terminated directive string from a name and an
+        # override value, or nil when the value signals removal (nil/false).
+        #
+        # The directive name and each source token are validated against CSP's
+        # separator characters: a name or token containing `;` (which separates
+        # directives), a newline, or a carriage return raises {ArgumentError}
+        # rather than silently injecting extra directives — a real footgun when
+        # overrides come from env/config files. (The `false` removal sentinel is
+        # checked before {Array} so a bare `false` never becomes a `[false]`
+        # source list.)
+        #
+        # @param name [String] directive name
+        # @param value [String, Array, nil, false] source list, or nil/false to remove
+        # @return [String, nil]
+        # @raise [ArgumentError] if the name or a source token contains a `;`,
+        #   newline, or carriage return
+        def build_directive(name, value)
+          return nil if value.nil? || value == false
+
+          reject_injection!('directive name', name)
+          sources = Array(value).filter_map do |token|
+            str = token.to_s.strip
+            next if str.empty?
+
+            reject_injection!("source for #{name}", str)
+            str
+          end.join(' ')
+          sources.empty? ? "#{name};" : "#{name} #{sources};"
+        end
+
+        # Raise {ArgumentError} when +text+ carries a CSP directive/token
+        # separator (`;`, newline, or carriage return) that would let an
+        # override break out of its directive and inject another.
+        #
+        # @param label [String] what is being validated (for the error message)
+        # @param text [String]
+        # @return [void]
+        # @raise [ArgumentError] if +text+ contains `;`, `\n`, or `\r`
+        def reject_injection!(label, text)
+          return unless text.match?(/[;\r\n]/)
+
+          raise ArgumentError,
+                "invalid CSP #{label}: #{text.inspect} contains a ';', newline, or carriage return"
+        end
+
         # CSP directives for the development environment.
         #
         # Development mode allows inline scripts/styles and hot reloading
@@ -108,7 +240,7 @@ class Otto
             "form-action 'self';",
             "frame-ancestors 'none';",
             "manifest-src 'self';",
-            "worker-src 'self' data:;",
+            "worker-src 'self' blob:;",
           ]
         end
 
@@ -132,7 +264,7 @@ class Otto
             "form-action 'self';",                     # Restrict form submissions to same origin
             "frame-ancestors 'none';",                 # Prevent site from being embedded in frames
             "manifest-src 'self';",                    # Allow web app manifests from same origin
-            "worker-src 'self' data:;",                # Allow Workers from same origin and data blobs
+            "worker-src 'self' blob:;",                # Allow Workers from same origin and blob: URLs
           ]
         end
       end

data/lib/otto/security/csrf_enforcement_wrapper.rb

@@ -0,0 +1,68 @@
+# lib/otto/security/csrf_enforcement_wrapper.rb
+#
+# frozen_string_literal: true
+
+require_relative 'csrf_validation'
+
+class Otto
+  module Security
+    # Per-route CSRF enforcement, applied at the handler layer.
+    #
+    # CSRF enforcement lives here rather than in the global +CSRFMiddleware+
+    # because +csrf=exempt+ is a per-route option: it is only known once a
+    # route has been matched (the middleware runs *ahead* of route matching and
+    # never sees route options, so a global block could not honor exemption —
+    # issue #186). This wrapper runs after matching, alongside +RouteAuthWrapper+,
+    # where +route_definition.csrf_exempt?+ is directly available. It is composed
+    # by +HandlerFactory+ only when CSRF protection is enabled, and wraps outside
+    # +RouteAuthWrapper+ so a forged unsafe request is rejected before any
+    # authentication work runs.
+    #
+    # The global +CSRFMiddleware+ retains only token *injection* into HTML
+    # responses (a response-shaping concern that is method/content-type based,
+    # not route based, so it stays global).
+    class CSRFEnforcementWrapper
+      include CSRFValidation
+
+      attr_reader :wrapped_handler, :route_definition, :config
+
+      # @param wrapped_handler [#call] the handler to guard
+      # @param route_definition [Otto::RouteDefinition] the matched route
+      # @param config [Otto::Security::Config] security config exposing CSRF settings
+      def initialize(wrapped_handler, route_definition, config)
+        @wrapped_handler  = wrapped_handler
+        @route_definition = route_definition
+        @config           = config
+      end
+
+      # @param env [Hash] Rack environment
+      # @param extra_params [Hash] Additional parameters passed through to the handler
+      # @return [Array] Rack response tuple
+      def call(env, extra_params = {})
+        return wrapped_handler.call(env, extra_params) unless enforce?(env)
+
+        request = Otto::Request.new(env)
+        return wrapped_handler.call(env, extra_params) if valid_csrf_token?(request)
+
+        Otto.structured_log(:warn, 'CSRF validation failed',
+          Otto::LoggingHelpers.request_context(env).merge(
+            handler: route_definition.definition,
+            referrer: request.referrer
+          ))
+        csrf_error_response
+      end
+
+      private
+
+      # Whether this request must present a valid CSRF token. Only unsafe
+      # methods on a non-exempt route are enforced when protection is enabled.
+      def enforce?(env)
+        return false unless config&.csrf_enabled?
+        return false if safe_method?(env['REQUEST_METHOD'])
+        return false if route_definition.csrf_exempt?
+
+        true
+      end
+    end
+  end
+end

data/lib/otto/security/csrf_validation.rb

@@ -0,0 +1,75 @@
+# lib/otto/security/csrf_validation.rb
+#
+# frozen_string_literal: true
+
+require 'json'
+
+class Otto
+  module Security
+    # Shared CSRF token mechanics.
+    #
+    # Both the global +CSRFMiddleware+ (which injects tokens into HTML
+    # responses) and the per-route +CSRFEnforcementWrapper+ (which enforces
+    # tokens on unsafe requests, honoring +csrf=exempt+) mix this in so the
+    # two cannot drift on what counts as a safe method, where a token may be
+    # carried, or how a rejection is shaped. The including object must expose a
+    # +@config+ (an +Otto::Security::Config+).
+    module CSRFValidation
+      # HTTP methods that never mutate state and so are exempt from token
+      # validation (RFC 7231 safe methods plus TRACE).
+      SAFE_METHODS = %w[GET HEAD OPTIONS TRACE].freeze
+
+      # Static 403 body. Frozen once so a rejected request does not re-serialize
+      # the same JSON on every call.
+      CSRF_ERROR_BODY = {
+          error: 'CSRF token validation failed',
+        message: 'The request could not be authenticated. Please refresh the page and try again.',
+      }.to_json.freeze
+
+      private
+
+      def safe_method?(method)
+        SAFE_METHODS.include?(method.to_s.upcase)
+      end
+
+      def valid_csrf_token?(request)
+        token = extract_csrf_token(request)
+        # Reject nil / blank / whitespace-only tokens up front, before creating
+        # a session or running HMAC verification — obviously-malformed input
+        # should not cause session churn (#186 review).
+        return false if token.nil? || token.strip.empty?
+
+        session_id = extract_session_id(request)
+        @config.verify_csrf_token(token, session_id)
+      end
+
+      def extract_csrf_token(request)
+        # Try form parameter first
+        token = request.params[@config.csrf_token_key]
+
+        # Try header if not in params
+        token ||= request.env[@config.csrf_header_key]
+
+        # Try alternative header format
+        token ||= request.env['HTTP_X_CSRF_TOKEN'] if request.env['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest'
+
+        token
+      end
+
+      def extract_session_id(request)
+        @config.get_or_create_session_id(request)
+      end
+
+      def csrf_error_response
+        [
+          403,
+          {
+            'content-type' => 'application/json',
+            'content-length' => CSRF_ERROR_BODY.bytesize.to_s,
+          },
+          [CSRF_ERROR_BODY],
+        ]
+      end
+    end
+  end
+end

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

@@ -7,10 +7,18 @@ require_relative '../config'
 class Otto
   module Security
     module Middleware
-      # Middleware that provides Cross-Site Request Forgery (CSRF) protection
+      # Global middleware that injects CSRF tokens into HTML responses.
+      #
+      # Token *enforcement* deliberately does NOT live here. This middleware
+      # runs ahead of route matching, so it cannot see per-route options like
+      # +csrf=exempt+ (issue #186); enforcing globally would block routes an
+      # operator explicitly exempted. Enforcement is applied after matching by
+      # +Otto::Security::CSRFEnforcementWrapper+ at the handler layer, where the
+      # route definition is available. This middleware keeps only the
+      # response-shaping half — injecting a fresh token into HTML responses so
+      # forms and meta tags can carry it — which is method/content-type based
+      # and correctly stays global.
       class CSRFMiddleware
-        SAFE_METHODS = %w[GET HEAD OPTIONS TRACE].freeze
-
         def initialize(app, config = nil)
           @app    = app
           @config = config || Otto::Security::Config.new
@@ -19,60 +27,14 @@ class Otto
         def call(env)
           return @app.call(env) unless @config.csrf_enabled?
 
-          request = Otto::Request.new(env)
-
-          # Skip CSRF protection for safe methods
-          if safe_method?(request.request_method)
-            response = @app.call(env)
-            response = inject_csrf_token(request, response) if html_response?(response)
-            return response
-          end
-
-          # Validate CSRF token for unsafe methods
-          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)
+          request  = Otto::Request.new(env)
+          response = @app.call(env)
+          response = inject_csrf_token(request, response) if html_response?(response)
+          response
         end
 
         private
 
-        def safe_method?(method)
-          SAFE_METHODS.include?(method.upcase)
-        end
-
-        def valid_csrf_token?(request)
-          token = extract_csrf_token(request)
-          return false if token.nil? || token.empty?
-
-          session_id = @config.get_or_create_session_id(request)
-          @config.verify_csrf_token(token, session_id)
-        end
-
-        def extract_csrf_token(request)
-          # Try form parameter first
-          token = request.params[@config.csrf_token_key]
-
-          # Try header if not in params
-          token ||= request.env[@config.csrf_header_key]
-
-          # Try alternative header format
-          token ||= request.env['HTTP_X_CSRF_TOKEN'] if request.env['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest'
-
-          token
-        end
-
-        def extract_session_id(request)
-          @config.get_or_create_session_id(request)
-        end
-
         def inject_csrf_token(request, response)
           return response unless response.is_a?(Array) && response.length >= 3
 
@@ -138,24 +100,6 @@ class Otto
           content_type = headers.find { |k, _v| k.downcase == 'content-type' }&.last
           content_type&.include?('text/html')
         end
-
-        def csrf_error_response
-          [
-            403,
-            {
-              'content-type' => 'application/json',
-              'content-length' => csrf_error_body.bytesize.to_s,
-            },
-            [csrf_error_body],
-          ]
-        end
-
-        def csrf_error_body
-          {
-            error: 'CSRF token validation failed',
-            message: 'The request could not be authenticated. Please refresh the page and try again.',
-          }.to_json
-        end
       end
     end
   end

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

@@ -69,12 +69,6 @@ class Otto
 
         private
 
-        # Apply privacy settings to environment
-        #
-        # @param env [Hash] Rack environment
-        # Apply privacy settings to environment
-        #
-        # @param env [Hash] Rack environment
         # Apply privacy settings to environment
         #
         # @param env [Hash] Rack environment
@@ -116,6 +110,15 @@ class Otto
               # Canonical client IP downstream reads (exempt: not masked)
               env['otto.client_ip'] = client_ip
               # Don't mask forwarded headers for private IPs
+              #
+              # This early return also means NONE of the privacy fingerprint
+              # values are produced for exempt IPs — no otto.privacy.fingerprint,
+              # masked_ip, hashed_ip, geo_country, or correlation_hash. That is
+              # intentional and consistent: the correlation hash targets public
+              # audit-trail traffic, so req.ip_correlation_hash is nil for
+              # localhost / RFC-1918 addresses (the default dev path) even when a
+              # correlation_secret is configured. Set mask_private_ips to treat
+              # private IPs as public and run them through the full path below.
               Otto.logger.debug "[IPPrivacyMiddleware] Private/localhost IP exempted: #{client_ip}" if Otto.debug
               return
             end
@@ -134,6 +137,14 @@ class Otto
           env['otto.privacy.hashed_ip'] = fingerprint.hashed_ip
           env['otto.privacy.geo_country'] = fingerprint.country
 
+          # Fingerprint the FULL client IP here — while client_ip is still the
+          # real address, before REMOTE_ADDR is masked below — so it identifies
+          # the visitor, not just their /24. Uses the caller's stable secret
+          # (unlike hashed_ip's daily key), so the same IP matches across days.
+          # nil when no secret is set. The real IP is never written to env; only
+          # this hash leaves the middleware.
+          env['otto.privacy.correlation_hash'] = correlation_hash(client_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 values without modification
@@ -158,6 +169,23 @@ class Otto
           # or env['otto.original_referer']. This prevents accidental leakage of the real values.
         end
 
+        # Fingerprint of the full client IP, keyed with the caller's stable
+        # correlation secret (not hashed_ip's daily-rotating key). The same IP
+        # and secret always produce the same value, so it can match a visitor
+        # across days — which the daily hash can't.
+        #
+        # Returns nil when no secret is configured. An empty key is never used
+        # to hash (that would let anyone reverse it); we return nil rather than
+        # raise, since "no secret" just means the feature is off.
+        #
+        # @param client_ip [String] Resolved full client IP (pre-masking)
+        # @return [String, nil] Hex HMAC-SHA256 digest, or nil when unconfigured
+        def correlation_hash(client_ip)
+          secret = @config.correlation_secret
+          return nil if secret.nil? || secret.empty?
+
+          Otto::Privacy::IPPrivacy.hash_ip(client_ip, secret)
+        end
 
         # Set or clear a Rack env header in a SPEC-compliant way.
         #

data/lib/otto/security.rb

@@ -9,6 +9,7 @@ require_relative 'security/authorization_error'
 require_relative 'security/config'
 require_relative 'security/configurator'
 require_relative 'security/middleware/csrf_middleware'
+require_relative 'security/csrf_enforcement_wrapper'
 require_relative 'security/middleware/validation_middleware'
 require_relative 'security/middleware/rate_limit_middleware'
 require_relative 'security/middleware/ip_privacy_middleware'

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 class Otto
-  VERSION = '2.5.0'
+  VERSION = '2.6.0'
 end

data/lib/otto.rb

@@ -2,6 +2,7 @@
 #
 # frozen_string_literal: true
 
+require 'concurrent'
 require 'json'
 require 'logger'
 require 'securerandom'
@@ -75,7 +76,8 @@ class Otto
            end
   @logger = Logger.new($stdout, Logger::INFO)
 
-  attr_reader :routes, :routes_literal, :routes_static, :route_definitions, :option,
+  attr_reader :routes, :routes_literal, :routes_static, :route_definitions,
+              :routes_by_definition, :option,
               :static_route, :security_config, :locale_config, :auth_config,
               :route_handler_factory, :mcp_server, :caddy_tls_server, :security, :middleware,
               :error_handlers, :request_class, :response_class
@@ -107,6 +109,10 @@ class Otto
   end
   alias options option
 
+  # Read-only view of assembled instance options. LambdaHandler resolves its
+  # registry via otto_instance.config[:lambda_handlers].
+  alias config option
+
   # Main Rack application interface
   def call(env)
     # Freeze configuration on first request (thread-safe).
@@ -166,10 +172,24 @@ class Otto
   private
 
   def initialize_core_state
-    @routes_static     = { GET: {} }
+    # The GET cache is a Concurrent::Map, not a plain Hash: lazy static-file
+    # discovery (Core::Router#handle_request, Core::FileSafety#add_static_path)
+    # writes into it at request time, after freeze_configuration! has already
+    # deep-frozen the rest of the routing state. Deep-freezing this cache too
+    # would turn every as-yet-uncached static file request into a 500
+    # (FrozenError) in production (issue #185), so it is intentionally excluded
+    # from deep_freeze_value in Configuration#freeze_configuration! and kept as
+    # a structure that is both mutable post-freeze and safe under concurrent
+    # request threads.
+    @routes_static     = { GET: Concurrent::Map.new }
     @routes            = { GET: [] }
     @routes_literal    = { GET: {} }
     @route_definitions = {}
+    # All routes per definition string, in load order. A definition string is
+    # not unique — the same handler can be mounted at several verb/path pairs —
+    # so reverse lookups (Otto#uri) consult this index instead of the
+    # single-route @route_definitions entry (issue #190).
+    @routes_by_definition = {}
     @security_config   = Otto::Security::Config.new
     @middleware        = Otto::Core::MiddlewareStack.new
     # Initialize @auth_config first so it can be shared with the configurator
@@ -234,6 +254,10 @@ class Otto
 
     # Initialize MCP server
     configure_mcp(opts)
+
+    # Validate and freeze the lambda handler registry (issue #41).
+    # Runs last so misconfiguration fails fast at construction.
+    configure_lambda_handlers(opts)
   end
 
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -203,6 +203,10 @@ files:
 - examples/caddy_tls_demo/routes
 - examples/caddy_tls_demo/standalone.ru
 - examples/error_handler_registration.rb
+- examples/lambda_handlers/README.md
+- examples/lambda_handlers/config.ru
+- examples/lambda_handlers/handlers.rb
+- examples/lambda_handlers/routes
 - examples/logging_improvements.rb
 - examples/mcp_demo/README.md
 - examples/mcp_demo/app.rb
@@ -254,6 +258,7 @@ files:
 - lib/otto/privacy/geo_resolver.rb
 - lib/otto/privacy/ip_privacy.rb
 - lib/otto/privacy/redacted_fingerprint.rb
+- lib/otto/privacy/user_agent_privacy.rb
 - lib/otto/request.rb
 - lib/otto/response.rb
 - lib/otto/response_handlers.rb
@@ -302,6 +307,8 @@ files:
 - lib/otto/security/csp/report_middleware.rb
 - lib/otto/security/csp/writer.rb
 - lib/otto/security/csrf.rb
+- lib/otto/security/csrf_enforcement_wrapper.rb
+- lib/otto/security/csrf_validation.rb
 - lib/otto/security/middleware/csrf_middleware.rb
 - lib/otto/security/middleware/ip_privacy_middleware.rb
 - lib/otto/security/middleware/rate_limit_middleware.rb