otto 2.8.0 → 2.9.0

data/lib/otto/security/config.rb

@@ -90,7 +90,7 @@ class Otto
                   :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_directive_overrides
+                  :csp_directive_overrides, :csp_request_extras_enabled
 
       # Initialize security configuration with safe defaults
       #
@@ -119,6 +119,7 @@ class Otto
         @csp_report_to_url      = nil
         @csp_violation_callback = nil
         @csp_directive_overrides = {}
+        @csp_request_extras_enabled = false
         @csp_script_src_override_warned = false
         @rate_limiting_config   = { custom_rules: {} }
         @ip_privacy_config      = Otto::Privacy::Config.new
@@ -512,6 +513,39 @@ class Otto
         @csp_nonce_enabled
       end
 
+      # Enable the request-scoped CSP directive extras channel (delano/otto#243)
+      #
+      # Off by default: `env['otto.csp.extra_directives']` is a write surface
+      # that ANY middleware in the Rack stack can reach — a lower-trust
+      # position than boot code — so the channel does not exist until the app
+      # explicitly opts in here. Until then the Writer ignores the env key
+      # entirely (no sanitize work, no logs).
+      #
+      # With the channel enabled, a handler (or middleware) can widen
+      # directives with values only known at request time by writing a hash of
+      # directive name => additional origin tokens to the env before the
+      # response is finalized. Extras are additive-only and sanitized
+      # defensively; see {Otto::Security::CSP::RequestExtras}.
+      #
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      #
+      # @example At boot, alongside nonce CSP
+      #   config.enable_csp_with_nonce!
+      #   config.enable_csp_request_extras!
+      def enable_csp_request_extras!
+        ensure_not_frozen!
+
+        @csp_request_extras_enabled = true
+      end
+
+      # Check if the request-scoped CSP directive extras channel is enabled
+      #
+      # @return [Boolean] true when {#enable_csp_request_extras!} was called
+      def csp_request_extras_enabled?
+        @csp_request_extras_enabled
+      end
+
       # Set the Rack env key the framework-owned lazy nonce is memoized under
       # ({Otto::Security::CSP.nonce} / {Otto::Request#csp_nonce}). Defaults to
       # `'otto.nonce'`; override it for an app with an existing convention (e.g.
@@ -649,14 +683,25 @@ class Otto
       #
       # @param nonce [String] The nonce value to include in the CSP
       # @param development_mode [Boolean] Whether to use development-friendly directives
+      # @param extra_directives [Hash{String=>Array<String>}, nil] request-scoped
+      #   extra source tokens appended additively after the overrides merge
+      #   (see {Otto::Security::CSP::Policy.append_extra_sources}, delano/otto#243).
+      #   Per-request data — passed through, never stored on this (deep-frozen
+      #   in production) config.
+      # @yield [applied, dropped] forwarded to
+      #   {Otto::Security::CSP::Policy.nonce_policy}: the extras entries that
+      #   actually landed in the policy and the entries dropped because their
+      #   directive was absent.
       # @return [String] Complete CSP policy string
-      def generate_nonce_csp(nonce, development_mode: false)
+      def generate_nonce_csp(nonce, development_mode: false, extra_directives: nil, &extras_outcome)
         Otto::Security::CSP::Policy.nonce_policy(
           nonce,
-          development_mode: development_mode,
-          report_uri: @csp_report_uri,
-          report_to_url: @csp_report_to_url,
-          directive_overrides: @csp_directive_overrides
+          development_mode:    development_mode,
+                report_uri:    @csp_report_uri,
+             report_to_url:    @csp_report_to_url,
+       directive_overrides:    @csp_directive_overrides,
+          extra_directives:    extra_directives,
+          &extras_outcome
         )
       end
 

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

@@ -66,7 +66,8 @@ class Otto
 
           Otto::Security::CSP::Writer.apply(
             headers, nonce,
-            config: @config, mode: :backstop, development_mode: development_mode?(env)
+            config: @config, mode: :backstop, development_mode: development_mode?(env),
+            env: env # request-scoped extras (env['otto.csp.extra_directives'], #243)
           )
         end
 

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

@@ -29,6 +29,23 @@ class Otto
         # can never drift.
         REPORTING_GROUP = 'otto-csp'
 
+        # CSP directives that take NO value at all. Appending a source to one
+        # of these does not widen it — it makes the directive SYNTACTICALLY
+        # malformed (`upgrade-insecure-requests https://x;`), and a browser
+        # drops a malformed directive wholesale. So an extras entry keyed to
+        # one of them would silently DISABLE the directive it names, the exact
+        # inverse of the additive contract. {.append_extra_sources} therefore
+        # leaves them byte-identical and reports the entry as dropped.
+        #
+        # Deliberately only these two: `sandbox`, `trusted-types`, and
+        # `require-trusted-types-for` take non-source values, which makes
+        # appending an origin to them useless, but the result is still valid
+        # syntax the browser honours — no silent policy loss.
+        # `upgrade-insecure-requests` remains a CSP extension. Conversely,
+        # `block-all-mixed-content` is obsolete in the Mixed Content standard,
+        # but is retained here to protect legacy policies that still emit it.
+        VALUELESS_DIRECTIVES = %w[upgrade-insecure-requests block-all-mixed-content].freeze
+
         # Build the per-request nonce CSP policy string.
         #
         # Byte-identical to Otto's historical {Otto::Security::Config#generate_nonce_csp}
@@ -47,10 +64,26 @@ class Otto
         #   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).
+        # @param extra_directives [Hash{String=>Array<String>}, nil]
+        #   request-scoped extra source tokens appended additively AFTER the
+        #   overrides merge and BEFORE the reporting directives. Expected
+        #   pre-sanitized (see {Otto::Security::CSP::RequestExtras.from_env});
+        #   see {.append_extra_sources} for the semantics (append to present
+        #   directives only, dedupe, drop absent-directive keys).
+        # @yield [applied, dropped] the extras outcome from
+        #   {.append_extra_sources} (both empty hashes when no extras were
+        #   given): the entries actually folded into the policy and the
+        #   entries dropped because their directive was absent. This is the
+        #   return channel {Otto::Security::CSP::Writer} uses to log drops
+        #   with request context and report only real appends — the policy
+        #   string stays the sole return value.
         # @return [String] complete CSP policy string
-        def nonce_policy(nonce, development_mode: false, report_uri: nil, report_to_url: nil, directive_overrides: nil)
+        def nonce_policy(nonce, development_mode: false, report_uri: nil, report_to_url: nil,
+                         directive_overrides: nil, extra_directives: nil)
           directives = development_mode ? development_directives(nonce) : production_directives(nonce)
           directives = merge_directives(directives, directive_overrides)
+          directives, applied_extras, dropped_extras = append_extra_sources(directives, extra_directives)
+          yield(applied_extras, dropped_extras) if block_given?
           uri_directive = report_uri_directive(report_uri)
           to_directive  = report_to_directive(report_to_url)
           directives += ["#{uri_directive};"] if uri_directive
@@ -151,28 +184,147 @@ class Otto
           merged
         end
 
+        # Fold request-scoped extra source tokens ADDITIVELY into a built
+        # directive set (delano/otto#243). A SIBLING of {.merge_directives},
+        # deliberately not a change to it: boot-time overrides REPLACE a
+        # directive's sources wholesale, request-time extras only ever APPEND.
+        #
+        # Semantics:
+        # - A directive PRESENT in the built list gets the extra tokens
+        #   appended to its source list, deduplicated (a token already present
+        #   is not appended again).
+        # - A directive ABSENT from the built list (base set minus any
+        #   boot-override removals) is DROPPED and reported in the return:
+        #   directives like `form-action` do not fall back to `default-src`,
+        #   so CREATING one here would tighten the policy (suddenly blocking
+        #   unrelated forms), and re-adding a directive a boot override
+        #   deliberately removed (nil/false override) would resurrect it.
+        # - A directive that takes NO value ({VALUELESS_DIRECTIVES}, e.g.
+        #   `upgrade-insecure-requests`) is left BYTE-IDENTICAL and its entry
+        #   is DROPPED: appending a source there would emit
+        #   `upgrade-insecure-requests https://x;`, which browsers treat as
+        #   malformed and discard — an extras key would silently turn the
+        #   directive OFF instead of widening it.
+        # - An entry whose token list is nil/empty leaves the base directive
+        #   BYTE-IDENTICAL — the directive string is returned as-is, never
+        #   rebuilt, so `worker-src 'self' blob:;` can never collapse into a
+        #   bare `worker-src;`.
+        #
+        # Callers pass PRE-SANITIZED extras
+        # ({Otto::Security::CSP::RequestExtras.from_env} guarantees no
+        # `;`/CR/LF and origin-only tokens), so this helper does not
+        # re-validate the grammar; it stays defensive only about shape
+        # (nil/empty values are skipped gracefully, request-time input must
+        # never raise).
+        #
+        # Pure — like everything in this module, a function of its arguments
+        # with no logging and no env access. Dropped entries are RETURNED,
+        # not logged, so the one caller with the request in hand
+        # ({Otto::Security::CSP::Writer}) can log them with full request
+        # context.
+        #
+        # @param directives [Array<String>] built directive strings, each
+        #   `;`-terminated (post {.merge_directives})
+        # @param extras [Hash{String=>Array<String>}, nil] normalized directive
+        #   name => extra source tokens
+        # @return [Array(Array<String>, Hash, Hash)] `[merged, applied, dropped]`:
+        #   the directive strings with extras appended; the extras entries that
+        #   addressed a PRESENT directive (their tokens are in the merged
+        #   policy — a token already present is simply not duplicated); and
+        #   the entries dropped because their directive was absent or takes no
+        #   value ({VALUELESS_DIRECTIVES}). Entries with nil/empty token lists
+        #   appear in neither hash.
+        def append_extra_sources(directives, extras)
+          return [directives, {}, {}] if extras.nil? || extras.empty?
+
+          remaining = extras.dup
+          applied = {}
+          merged = directives.map do |directive|
+            name = directive_name(directive)
+            tokens = remaining.delete(name)
+            next directive if tokens.nil? || Array(tokens).empty?
+
+            if valueless_directive?(name)
+              # Put the entry back so it surfaces in `dropped` rather than
+              # vanishing: the caller with the request in hand must be able to
+              # log that these tokens never landed.
+              remaining[name] = tokens
+              next directive
+            end
+
+            applied[name] = tokens
+            append_sources_to(directive, tokens)
+          end
+
+          dropped = remaining.reject { |_name, tokens| Array(tokens).empty? }
+          [merged, applied, dropped]
+        end
+
+        # Append tokens to one `;`-terminated directive string, deduplicated
+        # against its existing sources. Returns the directive UNCHANGED when
+        # every token is already present (the byte-identical invariant).
+        #
+        # @param directive [String] e.g. `"form-action 'self';"`
+        # @param tokens [Array<String>] pre-sanitized source tokens
+        # @return [String] `;`-terminated directive string
+        def append_sources_to(directive, tokens)
+          body = directive.to_s.strip.delete_suffix(';')
+          name, sources = body.split(/\s+/, 2)
+          existing  = sources.to_s.split(/\s+/)
+          additions = Array(tokens).map(&:to_s).reject { |token| token.empty? || existing.include?(token) }
+          return directive if additions.empty?
+
+          "#{name} #{(existing + additions).join(' ')};"
+        end
+
+        # Normalize one directive name: stripped, lowercased, underscores
+        # mapped to hyphens (no CSP directive contains an underscore), so a
+        # Symbol like `:worker_src` addresses the `worker-src` directive.
+        #
+        # The SINGLE normalization used by both {.normalize_overrides} and
+        # {Otto::Security::CSP::RequestExtras.from_env} — the present/absent
+        # matching in {.append_extra_sources} depends on both sides applying
+        # identical normalization, so it lives in exactly one place.
+        #
+        # @param name [String, Symbol]
+        # @return [String] normalized directive name (may be empty for blank input)
+        def normalize_directive_name(name)
+          name.to_s.strip.downcase.tr('_', '-')
+        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.
+        # interchangeable (see {.normalize_directive_name}). 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('_', '-')
+            name = normalize_directive_name(key)
             acc[name] = value unless name.empty?
           end
         end
 
         # The directive name (first token) of a `;`-terminated directive string,
-        # lowercased for case-insensitive matching.
+        # run through {.normalize_directive_name} so the built policy and the
+        # extras/override hashes are compared on ONE normalization.
         #
         # @param directive [String]
         # @return [String]
         def directive_name(directive)
-          directive.to_s.strip.delete_suffix(';').split(/\s+/, 2).first.to_s.downcase
+          normalize_directive_name(directive.to_s.strip.delete_suffix(';').split(/\s+/, 2).first)
+        end
+
+        # True when +name+ addresses a directive that takes no value at all
+        # (see {VALUELESS_DIRECTIVES}). Normalizes through
+        # {.normalize_directive_name}, so `:upgrade_insecure_requests` and
+        # `'Upgrade-Insecure-Requests'` are recognized like the canonical form.
+        #
+        # @param name [String, Symbol]
+        # @return [Boolean]
+        def valueless_directive?(name)
+          VALUELESS_DIRECTIVES.include?(normalize_directive_name(name))
         end
 
         # Build a single `;`-terminated directive string from a name and an
@@ -222,15 +374,17 @@ class Otto
 
         # CSP directives for the development environment.
         #
-        # Development mode allows inline scripts/styles and hot reloading
-        # connections for better developer experience with build tools like Vite.
+        # Development mode allows nonce-authorized inline scripts, inline styles,
+        # HTTP(S) scripts, and hot-reloading connections for build tools such as
+        # Vite. HTTP(S) script sources support both same-origin reverse proxies
+        # (for example Caddy) and direct local Vite servers on another port.
         #
         # @param nonce [String] nonce value injected into `script-src`
         # @return [Array<String>] directive strings, each terminated with `;`
         def development_directives(nonce)
           [
             "default-src 'none';",
-            "script-src 'nonce-#{nonce}' 'unsafe-inline';", # Allow inline scripts for development tools
+            "script-src 'self' 'nonce-#{nonce}' http: https:;",
             "style-src 'self' 'unsafe-inline';",
             "connect-src 'self' ws: wss: http: https:;", # Allow HTTP and all WebSocket connections for dev tools
             "img-src 'self' data:;",

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

@@ -0,0 +1,256 @@
+# lib/otto/security/csp/request_extras.rb
+#
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative 'policy'
+
+class Otto
+  module Security
+    module CSP
+      # Reads and sanitizes request-scoped CSP directive extras from the Rack
+      # env (delano/otto#243).
+      #
+      # This is the opt-in channel for widening CSP directives with values only
+      # known at request time: the app enables it at boot with
+      # {Otto::Security::Config#enable_csp_request_extras!} (default off — the
+      # env key is a write surface any middleware can reach, so it does not
+      # exist until boot code says so), then a handler writes a hash of
+      # directive name => additional source tokens to
+      # `env['otto.csp.extra_directives']` before the response is finalized,
+      # and the policy build folds the sanitized survivors in ADDITIVELY (see
+      # {Otto::Security::CSP::Policy.append_extra_sources}). The motivating
+      # case is a multi-tenant app that must admit the resolved tenant's SSO
+      # IdP origin into `form-action` — per-request data no boot-time override
+      # can express.
+      #
+      # This module deliberately has the OPPOSITE failure mode of
+      # {Otto::Security::CSP::Policy}: Policy is pure functions that raise on
+      # bad input (boot-time overrides should fail loud), while request-time
+      # extras must NEVER raise — a hostile or malformed value is dropped and
+      # logged, and the response still ships with the base policy intact.
+      #
+      # Sanitization rules:
+      # - Directive names are normalized via
+      #   {Otto::Security::CSP::Policy.normalize_directive_name} (the same
+      #   normalization {Policy.normalize_overrides} applies to boot-time
+      #   overrides); blank keys are dropped. Two raw keys that normalize to
+      #   the same directive (`'form_action'` and `'form-action'`) have their
+      #   token lists merged (union) — nothing is silently overwritten.
+      # - {REFUSED_DIRECTIVES} are dropped wholesale. For the `script-src`
+      #   family this is defence-in-depth policy, NOT nonce protection: extras
+      #   are additive, so the nonce source would survive an append — refusing
+      #   the family simply keeps the request channel away from the one
+      #   directive class that gates script execution. `default-src` is refused
+      #   because widening it widens every unlisted directive at once. Directives
+      #   with no value are refused because an appended origin makes the entire
+      #   directive malformed; {Policy.append_extra_sources} retains the same
+      #   guard for callers that bypass this sanitizer.
+      # - Tokens must be ORIGINS: `scheme://host[:port]` with an http/https
+      #   scheme and a non-empty host — no path/query/fragment/userinfo, no
+      #   whitespace, no `;`/CR/LF, no wildcards, no quotes. Keyword sources
+      #   (`'self'`, `'unsafe-inline'`, ...) and scheme sources (`data:`,
+      #   `https:`) are rejected. Accepted tokens are normalized to
+      #   `scheme://host[:port]` with a downcased host and default ports
+      #   omitted. Hosts follow strip-then-validate: a single trailing dot
+      #   (the FQDN root form browsers do NOT treat as the same origin) is
+      #   stripped before validation, any remaining trailing dot rejects the
+      #   token, and a host containing `%` (percent-encoding that URI's host
+      #   parser passes through literally) is rejected outright. An explicit
+      #   port must fall in 1..65535 — URI accepts arbitrarily large all-digit
+      #   ports that no browser can match.
+      #
+      # Every key/token dropped during sanitization is logged at :warn via
+      # {Otto.structured_log} with a distinct reason (`:invalid_shape`,
+      # `:refused_directive`, `:not_an_origin`) and privacy-safe request
+      # context. Entries dropped later, during the policy append (an absent
+      # directive, a valueless directive supplied by a caller that bypassed this
+      # sanitizer, or a config without extras support), are logged by
+      # {Otto::Security::CSP::Writer} — the same message, `reason:
+      # :absent_directive` / `:valueless_directive` /
+      # `:config_without_extras_support`.
+      module RequestExtras
+        # The env key the consuming app writes. Hardcoded on purpose (not
+        # configurable) — it is a cross-gem contract; see also
+        # Otto::EnvKeys::CSP::EXTRA_DIRECTIVES (require 'otto/env_keys').
+        ENV_KEY = 'otto.csp.extra_directives'
+
+        # Directives the request channel refuses to touch, wholesale. See the
+        # module docs for why (defence-in-depth for the script family — NOT
+        # nonce-stripping, since appends keep the nonce — blast radius for
+        # default-src — and invalid syntax for directives with no value).
+        # Keep the policy-level guard too: Policy.nonce_policy(extra_directives:)
+        # is public and can bypass this sanitizer.
+        REFUSED_DIRECTIVES = (
+          %w[script-src script-src-elem script-src-attr default-src] +
+          Policy::VALUELESS_DIRECTIVES
+        ).freeze
+
+        # The only schemes an extra origin may carry.
+        ALLOWED_SCHEMES = %w[http https].freeze
+
+        # Characters that can never appear in an origin token: whitespace and
+        # `;`/CR/LF (directive separators), quotes (keyword sources), and `*`
+        # (wildcards). Checked before URI parsing so hostile tokens are
+        # rejected even when URI would tolerate them.
+        FORBIDDEN_CHARS = /[\s;'"*\r\n]/
+
+        module_function
+
+        # Read and sanitize the request-scoped extras from the Rack env.
+        #
+        # Never raises. Anything that fails validation is dropped and logged;
+        # whatever survives is returned.
+        #
+        # @param env [Hash] the Rack environment
+        # @return [Hash{String=>Array<String>}, nil] normalized directive name
+        #   => normalized origin tokens; nil when the env key is absent, the
+        #   value is not a Hash, or nothing survived sanitization — callers
+        #   never see an empty hash
+        def from_env(env)
+          raw = env[ENV_KEY]
+          return nil if raw.nil?
+
+          # Compute the request context once per call and thread it through —
+          # a hostile payload can produce many drops, and re-deriving the
+          # context per token would defeat LoggingHelpers' compute-once-then-
+          # merge pattern.
+          context = Otto::LoggingHelpers.request_context(env)
+
+          unless raw.is_a?(Hash)
+            log_drop(context, directive: nil, token: raw, reason: :invalid_shape)
+            return nil
+          end
+
+          extras = raw.each_with_object({}) do |(key, value), acc|
+            name = Policy.normalize_directive_name(key)
+            if name.empty?
+              log_drop(context, directive: key, token: value, reason: :invalid_shape)
+              next
+            end
+            if REFUSED_DIRECTIVES.include?(name)
+              log_drop(context, directive: name, token: value, reason: :refused_directive)
+              next
+            end
+
+            tokens = sanitize_tokens(context, name, value)
+            next if tokens.empty?
+
+            # Two raw keys can normalize to the same directive ('form_action'
+            # and 'form-action'): union the token lists rather than letting
+            # the later key silently clobber the earlier one.
+            acc[name] = (acc[name] || []) | tokens
+          end
+          extras.empty? ? nil : extras
+        end
+
+        # Sanitize one directive's token value into normalized origin strings.
+        # A String value is treated as a whitespace-separated source list (the
+        # same ergonomics as a {Policy.merge_directives} String override); an
+        # Array is taken element-wise. Anything else drops the key.
+        #
+        # @param context [Hash] precomputed request context (for log payloads)
+        # @param name [String] normalized directive name (for log context)
+        # @param value [String, Array<String>, Object]
+        # @return [Array<String>] surviving normalized origins (deduplicated)
+        def sanitize_tokens(context, name, value)
+          candidates =
+            case value
+            when String then value.split
+            when Array then value
+            else
+              log_drop(context, directive: name, token: value, reason: :invalid_shape)
+              return []
+            end
+
+          candidates.filter_map do |token|
+            unless token.is_a?(String)
+              log_drop(context, directive: name, token: token, reason: :invalid_shape)
+              next
+            end
+
+            normalized = normalize_origin(token)
+            if normalized.nil?
+              log_drop(context, directive: name, token: token, reason: :not_an_origin)
+              next
+            end
+            normalized
+          end.uniq
+        end
+
+        # Validate and normalize a single token as an http(s) origin.
+        #
+        # @param token [String]
+        # @return [String, nil] `scheme://host[:port]` (downcased host, default
+        #   port omitted), or nil when the token is not an acceptable origin
+        def normalize_origin(token)
+          return nil if token.empty? || token.match?(FORBIDDEN_CHARS)
+
+          uri = begin
+            URI.parse(token)
+          rescue URI::InvalidURIError
+            nil
+          end
+
+          return nil unless uri.is_a?(URI::HTTP) # URI::HTTPS is a subclass
+
+          scheme = uri.scheme.to_s.downcase
+          return nil unless ALLOWED_SCHEMES.include?(scheme)
+          return nil if uri.userinfo
+          return nil unless uri.path.to_s.empty?
+          return nil if uri.query || uri.fragment
+
+          host = normalize_host(uri.host)
+          return nil if host.nil?
+          # URI accepts arbitrarily large all-digit ports (and port 0); no
+          # browser can match an origin outside the TCP port range, so an
+          # out-of-range port is a silent-failure token — reject it. uri.port
+          # is never nil for URI::HTTP (defaults apply), and the default ports
+          # 80/443 are in range, so one check covers both shapes.
+          return nil unless (1..65_535).cover?(uri.port)
+
+          origin = "#{scheme}://#{host}"
+          origin << ":#{uri.port}" unless uri.port == uri.default_port
+          origin
+        end
+
+        # Validate and normalize an origin host: downcased, strip-then-validate
+        # for trailing dots (a single trailing dot — the FQDN root form — is
+        # stripped, since browsers do not equate `example.com.` with
+        # `example.com`; any dot still trailing after the strip rejects the
+        # host), and any `%` rejects the host outright (URI's host parser
+        # passes percent-encodings through literally, so accepting one would
+        # ship raw `%00`-style bytes in a response header).
+        #
+        # @param raw [String, nil] the parsed URI host
+        # @return [String, nil] normalized host, or nil when unacceptable
+        def normalize_host(raw)
+          host = raw.to_s.downcase
+          return nil if host.empty? || host.include?('%')
+
+          host = host.delete_suffix('.')
+          return nil if host.empty? || host.end_with?('.')
+
+          host
+        end
+
+        # Log one dropped key/token at :warn with privacy-safe request context.
+        # Never :debug — drops are actionable signal, and structured_log skips
+        # :debug unless Otto.debug is on.
+        #
+        # @param context [Hash] precomputed request context ({Otto::LoggingHelpers.request_context})
+        def log_drop(context, directive:, token:, reason:)
+          Otto.structured_log(
+            :warn, 'CSP request extra dropped',
+            context.merge(
+              directive: directive&.to_s,
+              token: token.inspect.slice(0, 128),
+              reason: reason
+            ).compact
+          )
+        end
+      end
+    end
+  end
+end