otto 2.5.0 → 2.7.0

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

@@ -12,9 +12,26 @@ class Otto
       # This is the main orchestrator that:
       # - Sets anonymous StrategyResult for unauthenticated routes
       # - Enforces authentication for protected routes
-      # - Supports multi-strategy with OR logic (first success wins)
+      # - Supports multi-strategy with OR logic (first authenticated success wins)
       # - Performs Layer 1 (route-level) role authorization
       #
+      # Multi-strategy chain semantics (in precedence order):
+      # - AUTHENTICATED success wins immediately; later strategies never run.
+      # - TERMINAL failure (AuthFailure with terminal: true — explicit
+      #   credentials examined and rejected) halts the chain and fails closed,
+      #   regardless of strategy order. An anonymous success from an
+      #   anonymous-capable strategy elsewhere in the chain does not rescue the
+      #   request. See AuthFailure.
+      # - ANONYMOUS success (StrategyResult with no user, e.g. from noauth) is
+      #   held as a fallback while the rest of the chain runs. It wins once the
+      #   chain completes without an authenticated success or terminal failure,
+      #   so credential-less requests still fall through to noauth. When more
+      #   than one strategy produces an anonymous success, the first declared
+      #   is the fallback; later ones are deliberately ignored.
+      # - Plain failures are recorded and the next strategy is consulted
+      #   (OR logic). If everything fails, an AuthorizationFailure (valid
+      #   credential, denied) yields 403; otherwise 401.
+      #
       # @example Basic usage
       #   wrapper = RouteAuthWrapper.new(handler, route_def, auth_config)
       #   response = wrapper.call(env)
@@ -53,7 +70,8 @@ class Otto
           validation_error = validate_strategies(auth_requirements, env)
           return validation_error if validation_error
 
-          # Try each strategy in order (first success wins)
+          # Try each strategy in order (first authenticated success wins;
+          # anonymous success is a fallback; terminal failure halts the chain)
           authenticate_and_authorize(env, extra_params, auth_requirements)
         end
 
@@ -83,8 +101,15 @@ class Otto
         end
 
         # Main authentication and authorization flow
+        #
+        # chain tracks two views of the run: :executed is every strategy that
+        # ran (including one whose anonymous success is merely held as the
+        # fallback), :failed only those that returned a failure result. Failure
+        # metadata reports :executed as attempted_strategies so a terminal halt
+        # after a deferred anonymous success doesn't under-report what ran.
         def authenticate_and_authorize(env, extra_params, auth_requirements)
-          failed_strategies = []
+          chain = { failed: [], executed: [] }
+          anonymous_fallback = nil
           total_start_time = Otto::Utils.now_in_μs
 
           auth_requirements.each do |requirement|
@@ -96,39 +121,90 @@ class Otto
             start_time = Otto::Utils.now_in_μs
             result = strategy.authenticate(env, requirement)
             duration = Otto::Utils.now_in_μs - start_time
+            chain[:executed] << strategy_name
 
             # Inject strategy_name into result
             result = result.with(strategy_name: strategy_name) if result.is_a?(StrategyResult)
 
-            # Handle authentication success
-            if result.is_a?(StrategyResult) && (result.authenticated? || result.anonymous?)
+            # Handle authenticated success - wins immediately
+            if authenticated_result?(result)
               return handle_auth_success(env, extra_params, result, strategy_name,
-                                        duration, total_start_time, failed_strategies)
+                                        duration, total_start_time, chain)
+            end
+
+            # An anonymous success (e.g. noauth) is held as a fallback rather
+            # than winning outright, so a credentialed strategy elsewhere in
+            # the chain still gets to examine explicitly presented credentials
+            # and reject them terminally, regardless of declaration order.
+            # When the chain completes without a terminal failure, the
+            # fallback wins (see below), preserving OR fallthrough for
+            # credential-less requests.
+            if anonymous_result?(result)
+              anonymous_fallback ||= { result: result, strategy_name: strategy_name, duration: duration }
+              next
             end
 
             # Handle a failure (authentication OR authorization) - record it and
             # continue to the next strategy (OR logic; a later success still wins).
             # AuthorizationFailure (valid credential, denied) is tagged so the
             # final response is 403 instead of 401. See handle_all_strategies_failed.
-            next unless result.is_a?(AuthFailure) || result.is_a?(AuthorizationFailure)
+            # Anything else is a strategy-author bug (wrong return type): the
+            # chain skips it as if it failed without a reason, but leaves a
+            # trace — a silent drop makes those bugs hard to debug.
+            unless result.is_a?(AuthFailure) || result.is_a?(AuthorizationFailure)
+              log_unexpected_result(env, strategy_name, result)
+              next
+            end
 
             log_strategy_failure(env, strategy_name, result, duration, auth_requirements, requirement)
-            failed_strategies << {
-              strategy: strategy_name,
-              reason: result.failure_reason,
-              authorization: result.is_a?(AuthorizationFailure),
-            }
+
+            # A terminal failure means explicit credentials were examined and
+            # rejected: fail the whole chain closed (401) instead of letting an
+            # anonymous-capable strategy accept the request as anonymous.
+            if record_failure(chain[:failed], strategy_name, result)
+              return handle_all_strategies_failed(env, auth_requirements, chain,
+                                                  total_start_time, terminal: true)
+            end
+          end
+
+          # Chain completed without authenticated success or terminal failure:
+          # a held anonymous success wins (OR fallthrough to noauth et al.)
+          if anonymous_fallback
+            return handle_auth_success(env, extra_params, anonymous_fallback[:result],
+                                       anonymous_fallback[:strategy_name],
+                                       anonymous_fallback[:duration],
+                                       total_start_time, chain)
           end
 
           # All strategies failed
-          handle_all_strategies_failed(env, auth_requirements, failed_strategies, total_start_time)
+          handle_all_strategies_failed(env, auth_requirements, chain, total_start_time)
+        end
+
+        def authenticated_result?(result)
+          result.is_a?(StrategyResult) && result.authenticated?
+        end
+
+        def anonymous_result?(result)
+          result.is_a?(StrategyResult) && result.anonymous?
+        end
+
+        # Append the failure to the running list; returns true when it was terminal
+        def record_failure(failed_strategies, strategy_name, result)
+          terminal = result.is_a?(AuthFailure) && result.terminal?
+          failed_strategies << {
+            strategy: strategy_name,
+            reason: result.failure_reason,
+            authorization: result.is_a?(AuthorizationFailure),
+            terminal: terminal,
+          }
+          terminal
         end
 
         # Handle successful authentication
-        def handle_auth_success(env, extra_params, result, strategy_name, duration, total_start_time, failed_strategies)
+        def handle_auth_success(env, extra_params, result, strategy_name, duration, total_start_time, chain)
           total_duration = Otto::Utils.now_in_μs - total_start_time
 
-          log_auth_success(env, strategy_name, result, duration, total_duration, failed_strategies)
+          log_auth_success(env, strategy_name, result, duration, total_duration, chain)
 
           # Set environment variables for controllers/logic
           env['otto.strategy_result'] = result
@@ -148,14 +224,19 @@ class Otto
           wrapped_handler.call(env, extra_params)
         end
 
-        # Handle case when all authentication strategies fail
-        def handle_all_strategies_failed(env, auth_requirements, failed_strategies, total_start_time)
+        # Handle case when authentication fails for the whole chain — either
+        # every strategy failed, or a terminal failure halted the chain early
+        # (terminal: true; remaining strategies were deliberately not consulted).
+        # chain is the { failed:, executed: } state built by
+        # authenticate_and_authorize.
+        def handle_all_strategies_failed(env, auth_requirements, chain, total_start_time, terminal: false)
+          failed_strategies = chain[:failed]
           total_duration = Otto::Utils.now_in_μs - total_start_time
 
-          log_all_failed(env, failed_strategies, total_duration)
+          log_all_failed(env, chain, total_duration, terminal: terminal)
 
           # Create anonymous result with failure info
-          metadata = build_failure_metadata(env, failed_strategies)
+          metadata = build_failure_metadata(env, chain, terminal: terminal)
           failure_strategy_name = determine_failure_strategy_name(auth_requirements, failed_strategies)
 
           env['otto.strategy_result'] = StrategyResult.anonymous(
@@ -167,14 +248,18 @@ class Otto
           # authenticated the subject but denied authorization (wrong role/missing
           # permission), respond 403 Forbidden rather than 401 — the subject IS
           # authenticated, they simply lack access. A bare 401 would (incorrectly)
-          # tell a logged-in client to re-authenticate.
+          # tell a logged-in client to re-authenticate. This precedence also holds
+          # on a terminal halt: the denial's 403 is the more specific outcome.
           authz_denial = failed_strategies.find { |f| f[:authorization] }
           return @response_builder.forbidden(env, authz_denial[:reason]) if authz_denial
 
+          # On a terminal halt the terminal failure is necessarily the last one
+          # recorded, so its reason is what gets rendered.
           last_failure = if failed_strategies.any?
                            AuthFailure.new(
                              failure_reason: failed_strategies.last[:reason],
-                             auth_method: failed_strategies.last[:strategy]
+                             auth_method: failed_strategies.last[:strategy],
+                             terminal: failed_strategies.last[:terminal] || false
                            )
                          else
                            AuthFailure.new(
@@ -194,13 +279,21 @@ class Otto
         end
 
         # Build metadata for failed authentication
-        def build_failure_metadata(env, failed_strategies)
+        #
+        # attempted_strategies lists every strategy that EXECUTED (including
+        # one whose anonymous success was held as the fallback and then
+        # overruled by a terminal failure); failure_reasons lists only the
+        # reasons of strategies that FAILED, in failure order. The two arrays
+        # are therefore not index-aligned.
+        def build_failure_metadata(env, chain, terminal: false)
+          summary = terminal ? 'Authentication halted by terminal failure' : 'All authentication strategies failed'
           metadata = {
                           ip: env['otto.client_ip'] || env['REMOTE_ADDR'],
-                auth_failure: 'All authentication strategies failed',
-            attempted_strategies: failed_strategies.map { |f| f[:strategy] },
-                 failure_reasons: failed_strategies.map { |f| f[:reason] },
+                auth_failure: summary,
+            attempted_strategies: chain[:executed],
+                 failure_reasons: chain[:failed].map { |f| f[:reason] },
           }
+          metadata[:terminal_failure] = true if terminal
           metadata[:country] = env['otto.privacy.geo_country'] if env['otto.privacy.geo_country']
           metadata
         end
@@ -228,7 +321,7 @@ class Otto
             ))
         end
 
-        def log_auth_success(env, strategy_name, result, duration, total_duration, failed_strategies)
+        def log_auth_success(env, strategy_name, result, duration, total_duration, chain)
           Otto.structured_log(:info, 'Auth strategy result',
             Otto::LoggingHelpers.request_context(env).merge(
               strategy: strategy_name,
@@ -236,7 +329,11 @@ class Otto
               user_id: result.user_id,
               duration: duration,
               total_duration: total_duration,
-              strategies_attempted: failed_strategies.size + 1
+              # Every strategy that ran, including the winner (already in
+              # chain[:executed] by the time a success is handled) and any
+              # held anonymous fallback — not just the failures. Same array
+              # shape as the failure log so consumers see one type.
+              strategies_attempted: chain[:executed]
             ))
         end
 
@@ -251,12 +348,22 @@ class Otto
             ))
         end
 
-        def log_all_failed(env, failed_strategies, total_duration)
-          Otto.structured_log(:warn, 'All auth strategies failed',
+        def log_unexpected_result(env, strategy_name, result)
+          Otto.structured_log(:warn, 'Auth strategy returned unexpected type',
+            Otto::LoggingHelpers.request_context(env).merge(
+              strategy: strategy_name,
+              result_class: result.class.name
+            ))
+        end
+
+        def log_all_failed(env, chain, total_duration, terminal: false)
+          message = terminal ? 'Auth chain halted by terminal failure' : 'All auth strategies failed'
+          Otto.structured_log(:warn, message,
             Otto::LoggingHelpers.request_context(env).merge(
-              strategies_attempted: failed_strategies.map { |f| f[:strategy] },
+              strategies_attempted: chain[:executed],
               total_duration: total_duration,
-              failure_count: failed_strategies.size
+              failure_count: chain[:failed].size,
+              terminal: terminal
             ))
         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
 
@@ -214,6 +217,20 @@ class Otto
         end
       end
 
+      # Whether any trusted-proxy IP/CIDR/Regexp matchers are configured.
+      #
+      # This mirrors {#trusted_proxy?}, which consults the same matcher list, so
+      # the two answers stay consistent: a request can only be "via a trusted
+      # proxy" when matchers exist. It deliberately EXCLUDES count-based depth
+      # mode — depth resolves the client IP but never confers proxy identity
+      # trust (the same decoupling {Otto::Request#forwarded_by_trusted_proxy?}
+      # applies to X-Forwarded-Proto). Used to gate geo-header trust.
+      #
+      # @return [Boolean] true when at least one trusted-proxy matcher exists
+      def trusted_proxies_configured?
+        @trusted_proxy_matchers.any?
+      end
+
       # Whether count-based ("trust the last N hops") proxy resolution is active.
       #
       # When true, Otto::Utils.resolve_client_ip ignores trusted-proxy CIDRs and
@@ -367,19 +384,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 +610,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 +623,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
 
@@ -696,12 +782,20 @@ class Otto
       # trusted_proxy? never re-parses. Non-IP strings and Regexp/other entries
       # store a nil range and fall back to prefix/regexp matching.
       #
+      # The parsed range is folded through IPAddr#native at registration, to
+      # match the fold trusted_proxy? applies to the client address. Without
+      # it a mapped-IPv6 proxy entry (::ffff:10.0.0.0/104) could never match,
+      # because ip_in_range?'s family check would reject the folded IPv4
+      # client — a proxy silently untrusted, which is what gates
+      # otto.via_trusted_proxy, secure?, and geo-header trust. #native returns
+      # self for entries that are not IPv4-mapped/compatible.
+      #
       # @param entry [String, Regexp, Object] trusted proxy entry being added
       # @return [Array(Object, IPAddr)] [raw_entry, parsed_range_or_nil]
       def register_proxy_matcher(entry)
         return [entry, nil] unless entry.is_a?(String)
 
-        range = parse_ipaddr(entry)
+        range = parse_ipaddr(entry)&.native
         warn_legacy_proxy_entry(entry) unless range
         [entry, range]
       end
@@ -819,6 +913,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

data/lib/otto/security/core.rb

@@ -181,7 +181,10 @@ class Otto
       # The middleware is pinned to run OUTERMOST (ahead of CSRF and every other
       # middleware), so it short-circuits report POSTs before CSRF validation —
       # browsers can post reports without a CSRF token. This holds regardless of
-      # the order in which you enable security features.
+      # the order in which you enable security features. The one thing that runs
+      # ahead of it is IPPrivacyMiddleware, pinned to the outer :entrypoint tier
+      # so nothing observes a raw client IP; being a pass-through, it cannot
+      # affect the short-circuit.
       #
       # SECURITY / DoS: running outermost also means the receiver sits ahead of
       # rate limiting (rate limiting is inner middleware). This is intentional —

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/csp/report_middleware.rb

@@ -27,7 +27,9 @@ class Otto
       #   with no CSRF token: the report never reaches the CSRF middleware.
       #   {Otto::Security::Core#enable_csp_reporting!} pins this middleware
       #   OUTERMOST (via the :outermost stack position), so the guarantee holds
-      #   regardless of the order security features are enabled in. The flip side
+      #   regardless of the order security features are enabled in. Only
+      #   IPPrivacyMiddleware (pinned to the outer :entrypoint tier) runs ahead
+      #   of it, and it is a pass-through. The flip side
       #   is that reports also bypass rate limiting — see the DoS note on
       #   {Otto::Security::Core#enable_csp_reporting!}; keep callbacks cheap.
       # - Enforces a hard {MAX_BODY_BYTES} body cap. Oversized bodies are