otto 2.8.1 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f94ca7311ea4fde801ec716a32f0136bd3802332ad654e368e69b7d6638c4d0f
-  data.tar.gz: 319fcb9bf53b73dada223539de15cbc8eb7e700f6aa6e53046306fd8abe391a1
+  metadata.gz: 0bbfc031ec4ff48d3d0ce373a4a8cbbfac62571f80a07ef54427e71a3fc34444
+  data.tar.gz: 4cf1c8c6171a8af0f18dcc61c8c00b86c9bc829b573e8e3b727b1047ad2ce230
 SHA512:
-  metadata.gz: f8097fc6d3b184a0e6775f728ecb3195301a36512ad270b22db1f6137d79b5a0f8a5173235f96b1d42408fd381248b2f669326e08b48c02505884e779a97c6d2
-  data.tar.gz: 0c035928bf9bd52096567cdea4e725c44b6fc8055999564c606db8eff50c302ae863bc018a4366022ed8c5899965929edb06837eff8405bbbef76a8c0ced1320
+  metadata.gz: c4405b81202ecf23a1f09629ccc8392a70a1fa6d0287c46ba4590517f884e527ecca5d909475b6ff772ad857def5686991c99b9b93dde9489c040d3502662f73
+  data.tar.gz: 155b0b637c48466d3ad68f91f28647c6f7a7a6cf4c60aac343af270c09a0be98f6fa5c1764d94e4886a148ee8d9f226c1567118e865404b3add638dbe50ee2a5

data/CHANGELOG.rst

@@ -7,6 +7,42 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.9.0:
+
+2.9.0 — 2026-08-18
+==================
+
+Added
+-----
+
+- Add opt-in request-scoped CSP directive extras for sources that are known
+  only while handling a request. Enable the feature at boot with
+  ``security_config.enable_csp_request_extras!``, then add approved source
+  origins by directive through ``env['otto.csp.extra_directives']``. This
+  supports cases such as adding a tenant's SSO provider to ``form-action``.
+  Disabled by default. (#243)
+
+Fixed
+-----
+
+- Prevent request-scoped CSP extras from invalidating valueless directives,
+  including ``upgrade-insecure-requests`` and ``block-all-mixed-content``.
+  Unsupported extras are ignored and logged; valid extras for other
+  directives continue to apply. (#243)
+
+Security
+--------
+
+- Validate request-scoped CSP extras before adding them to a response policy.
+  Extras can only add valid HTTP(S) origins to compatible directives already
+  present in the configured policy; script and default source directives are
+  excluded. Invalid or unsupported entries are ignored and logged without
+  affecting the remaining policy. (#243)
+
+- Reject request-scoped CSP extras for valueless directives during input
+  validation, with equivalent protection for direct CSP policy generation.
+  (#243)
+
 .. _changelog-2.8.1:
 
 2.8.1 — 2026-08-16

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.8.1)
+    otto (2.9.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)

data/README.md

@@ -129,7 +129,70 @@ result.skip_reason     # => nil (or :disabled / :blank_nonce / :non_html / :exis
 
 Apps with an existing nonce env-key convention can point the accessor at it with
 `app.security_config.csp_nonce_key = 'onetime.nonce'` — the views and the header
-still share one value.
+still share one value. Boot-time policy shaping goes through
+`security_config.csp_directive_overrides = { 'worker-src' => "'self' data: blob:" }`,
+which replaces (or with `nil`, removes) a directive's sources wholesale.
+
+#### Request-scoped directive extras
+
+Some directive values only exist at request time — the canonical case is a
+multi-tenant app that must allow the resolved tenant's SSO IdP origin in
+`form-action`. The channel is **boot-time opt-in** (the env key is a write
+surface any middleware in the Rack stack can reach, so it does not exist until
+boot code says so):
+
+```ruby
+app.security_config.enable_csp_request_extras!  # default: off
+```
+
+With the channel enabled, a handler (or middleware) writes a hash of directive
+name => additional source tokens to the env before the response is finalized:
+
+```ruby
+def signin(req, res)
+  idp_origin = resolve_tenant(req).idp_origin  # e.g. "https://login.example-idp.com"
+  req.env['otto.csp.extra_directives'] = { 'form-action' => [idp_origin] }
+  # ... render as usual; the emitted CSP now carries the origin
+end
+```
+
+Without the opt-in, the env key is ignored entirely — no sanitization, no
+logs. The `Writer::Result` returned by the emission surfaces reports what
+actually happened: `result.extra_directives` carries only the extras that
+landed in the policy; rejected or dropped entries are excluded and logged with
+request context instead.
+
+The extras channel is **additive-only** and deliberately narrow:
+
+- Tokens are appended to directives already present in the built policy,
+  deduplicated. A directive that is *absent* (not in the base set, or removed
+  by a boot override) is dropped — creating one at request time would tighten
+  the policy (`form-action` does not fall back to `default-src`), and
+  re-adding one would resurrect a deliberate removal.
+- Directives that take **no value** (`upgrade-insecure-requests`,
+  `block-all-mixed-content`) are refused during sanitization: a source appended
+  there would emit `upgrade-insecure-requests https://…`, which browsers treat
+  as malformed and discard — an extras key would silently switch the directive
+  *off*. The policy assembler independently leaves such directives
+  byte-identical for direct callers that bypass the sanitizer.
+- Only **origins** are accepted: `scheme://host[:port]` with an http(s) scheme
+  — no keywords (`'self'`, `'unsafe-inline'`), no scheme sources (`data:`,
+  `https:`), no wildcards, no paths, nothing that could smuggle a separator.
+- `script-src` (and `-elem`/`-attr`) and `default-src` are refused outright.
+  For the script family that is defence-in-depth policy, not nonce protection
+  (extras append, so the nonce would survive); `default-src` is refused
+  because widening it widens every unlisted directive at once.
+- Everything that fails validation is **dropped and logged** (`warn`, with the
+  directive, token, and reason) — a hostile value never raises, and the
+  response ships with the rest of the policy intact.
+
+Otto validates defensively, but it is not the policy authority: the app
+decides *which* origins to admit (resolve them from trusted per-request data,
+never echo attacker-controlled input). Extras live only in the request env —
+nothing is memoized on the (frozen-in-production) security config, so
+concurrent requests can never bleed into each other. The constant
+`Otto::EnvKeys::CSP::EXTRA_DIRECTIVES` (via `require 'otto/env_keys'`) names
+the key for downstream apps.
 
 > [!NOTE]
 > `res.send_csp_headers(content_type, nonce)` is **deprecated** in favour of

data/lib/otto/env_keys.rb

@@ -74,6 +74,28 @@ class Otto
     #   (e.g. 'onetime.nonce'), so the header and views still share one value.
     NONCE = 'otto.nonce'
 
+    # Content-Security-Policy request-scoped keys
+    module CSP
+      # Request-scoped CSP directive extras (delano/otto#243).
+      # Type: Hash{String|Symbol directive-name => String|Array<String> tokens}
+      # Set by: the consuming application (a handler, logic class, or
+      #   middleware) any time before the response is finalized
+      # Used by: Otto::Security::CSP::RequestExtras (read + sanitized) and
+      #   folded ADDITIVELY into the nonce policy by
+      #   Otto::Security::CSP::Policy.append_extra_sources at build time
+      # Note: BOOT-TIME OPT-IN — the channel does not exist until the app
+      #   calls Otto::Security::Config#enable_csp_request_extras! (default
+      #   off); without it the key is ignored entirely, no sanitize work and
+      #   no logs. The env key is a write surface any middleware in the Rack
+      #   stack can reach, a lower-trust position than boot code.
+      # Note: additive-only — extras can only APPEND origin tokens
+      #   (scheme://host[:port], http/https) to directives already present in
+      #   the built policy. The script-src family and default-src are refused
+      #   outright, keyword/scheme sources and wildcards are dropped, and every
+      #   drop is logged. See Otto::Security::CSP::RequestExtras.
+      EXTRA_DIRECTIVES = 'otto.csp.extra_directives'
+    end
+
     # Whether the request arrived via a trusted proxy. TRI-STATE.
     # Type: Boolean when present; the key may be ABSENT.
     # Set by: IPPrivacyMiddleware, evaluated on the original peer BEFORE

data/lib/otto/response.rb

@@ -124,6 +124,11 @@ class Otto
     # @return [Otto::Security::CSP::Writer::Result] the outcome (applied?, policy,
     #   skip_reason) for uniform observability
     #
+    # @note request-scoped directive extras (`env['otto.csp.extra_directives']`,
+    #   delano/otto#243) are seen only when this response has its {#request}
+    #   wired — the env is resolved via `request&.env`, so a bare Response
+    #   degrades gracefully to the base policy.
+    #
     # @example
     #   res['content-type'] = 'text/html; charset=utf-8'
     #   res.apply_csp(req.csp_nonce)
@@ -131,7 +136,8 @@ class Otto
       config = security_config || (request&.env && request.env['otto.security_config'])
       Otto::Security::CSP::Writer.apply(
         headers, nonce,
-        config: config, mode: mode, development_mode: development_mode
+        config: config, mode: mode, development_mode: development_mode,
+        env: request&.env # nil-safe: specs and bare responses have no request
       )
     end
 

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

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

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

@@ -2,6 +2,8 @@
 #
 # frozen_string_literal: true
 
+require_relative 'request_extras'
+
 class Otto
   module Security
     module CSP
@@ -39,6 +41,10 @@ class Otto
         CSP_HEADER = 'content-security-policy'
         CONTENT_TYPE_HEADER = 'content-type'
 
+        # Method#parameters types that declare a keyword parameter (used by
+        # {.supports_extra_directives?}).
+        KEYWORD_PARAM_TYPES = %i[key keyreq].freeze
+
         # Emission modes. `:override` is a deliberate per-request call that
         # REPLACES any existing CSP (the caller owns this response's policy).
         # `:backstop` is a passive layer that DEFERS to an existing CSP (it only
@@ -51,23 +57,26 @@ class Otto
         # written". `policy` is the emitted policy on success, or the pre-existing
         # policy when a `:backstop` deferred to one. `skip_reason` is one of
         # `:disabled`, `:blank_nonce`, `:non_html`, `:existing_csp` when skipped,
-        # else nil.
+        # else nil. `extra_directives` carries the request-scoped extras that
+        # were ACTUALLY folded into the policy — entries dropped during the
+        # append (absent directive) are excluded — or nil when none landed.
         class Result
           # Recognized skip reasons, in the order {Writer.apply} evaluates them.
           SKIP_REASONS = %i[disabled blank_nonce non_html existing_csp].freeze
 
-          attr_reader :policy, :skip_reason, :mode
+          attr_reader :policy, :skip_reason, :mode, :extra_directives
 
-          def initialize(applied:, mode:, policy: nil, skip_reason: nil)
+          def initialize(applied:, mode:, policy: nil, skip_reason: nil, extra_directives: nil)
             @applied = applied
             @mode = mode
             @policy = policy
             @skip_reason = skip_reason
+            @extra_directives = extra_directives
           end
 
           # Build an "applied" result for a written policy.
-          def self.applied(policy, mode:)
-            new(applied: true, mode: mode, policy: policy)
+          def self.applied(policy, mode:, extra_directives: nil)
+            new(applied: true, mode: mode, policy: policy, extra_directives: extra_directives)
           end
 
           # Build a "skipped" result. `policy` carries the pre-existing policy for
@@ -96,23 +105,35 @@ class Otto
         #   and the policy string ({Otto::Security::Config#generate_nonce_csp}).
         # @param mode [Symbol] one of {MODES}.
         # @param development_mode [Boolean] use the development directive set.
+        # @param env [Hash, nil] the Rack environment. When given AND the
+        #   config has opted the channel in
+        #   ({Otto::Security::Config#enable_csp_request_extras!}), any
+        #   request-scoped directive extras the app wrote to
+        #   `env['otto.csp.extra_directives']` are sanitized
+        #   ({Otto::Security::CSP::RequestExtras.from_env}) and folded
+        #   ADDITIVELY into the policy. Nil (surfaces with no env in hand)
+        #   simply builds the policy without extras; without the opt-in the
+        #   env key is ignored entirely.
         # @return [Result]
         # @raise [ArgumentError] if mode is not one of {MODES}
         # @raise [FrozenError] if a write is attempted against a frozen headers hash
-        def self.apply(headers, nonce, config:, mode: :override, development_mode: false)
+        def self.apply(headers, nonce, config:, mode: :override, development_mode: false, env: nil)
           unless MODES.include?(mode)
             raise ArgumentError, "mode must be one of #{MODES.join(', ')}, got #{mode.inspect}"
           end
 
-          result = evaluate(headers, nonce, config, mode, development_mode)
+          result = evaluate(headers, nonce, config, mode, development_mode, env)
           log_debug(config, result)
           result
         end
 
         # Guarded core: returns a Result and performs the in-place write when it
         # applies. Guards are evaluated most-fundamental first so the reported
-        # skip_reason is stable and meaningful.
-        def self.evaluate(headers, nonce, config, mode, development_mode)
+        # skip_reason is stable and meaningful. Request-scoped extras are
+        # resolved only once every guard has passed — so a skipped response
+        # never logs extras drops for a policy that was never built — and only
+        # when the config opted the channel in (see {.resolve_extras}).
+        def self.evaluate(headers, nonce, config, mode, development_mode, env)
           return Result.skipped(:disabled, mode: mode) unless enabled?(config)
           return Result.skipped(:blank_nonce, mode: mode) if blank?(nonce)
           return Result.skipped(:non_html, mode: mode) unless html_response?(headers)
@@ -120,12 +141,126 @@ class Otto
           existing = existing_csp(headers)
           return Result.skipped(:existing_csp, mode: mode, policy: existing) if existing && mode == :backstop
 
-          policy = config.generate_nonce_csp(nonce, development_mode: development_mode)
+          extras = resolve_extras(config, env)
+          policy, applied_extras = build_policy(config, nonce, development_mode, extras, env)
           write_csp(headers, policy)
-          Result.applied(policy, mode: mode)
+          Result.applied(policy, mode: mode, extra_directives: applied_extras)
         end
         private_class_method :evaluate
 
+        # Build the policy string, folding in the request-scoped extras when
+        # the config supports them. Returns `[policy, applied_extras]` where
+        # applied_extras is the hash of extras entries that ACTUALLY landed in
+        # the policy (nil when none did), as reported back by
+        # {Policy.append_extra_sources} through the outcome block — never the
+        # pre-append input, so {Result#extra_directives} and the debug log can
+        # only claim what happened. Entries the append dropped (absent
+        # directive) are logged HERE, the one place with the env in hand, with
+        # full request context; Policy stays a pure function of its arguments.
+        #
+        # Configs are duck-typed (see {.enabled?}): one with the pre-#243
+        # `generate_nonce_csp` signature would raise ArgumentError on the
+        # `extra_directives:` kwarg at request time — violating the extras
+        # channel's never-raises invariant — so the kwarg is passed only when
+        # the signature declares it. Otherwise the historical call shape is
+        # used and the extras are dropped with a single structured warn
+        # (`reason: :config_without_extras_support`).
+        #
+        # Declaring the kwarg is only half the duck-config protocol: opting
+        # in means BOTH accepting `extra_directives:` AND invoking the
+        # outcome block. A config that takes the kwarg but never yields
+        # leaves the outcome unknown — its policy string is still used as
+        # returned, but no applied extras are reported
+        # ({Result#extra_directives} stays nil; never fabricated from the
+        # pre-append input) and a single structured warn
+        # (`reason: :config_outcome_not_reported`) flags the gap.
+        def self.build_policy(config, nonce, development_mode, extras, env)
+          return [config.generate_nonce_csp(nonce, development_mode: development_mode), nil] if extras.nil?
+
+          unless supports_extra_directives?(config)
+            Otto.structured_log(
+              :warn, 'CSP request extras dropped',
+              Otto::LoggingHelpers.request_context(env).merge(
+                directives: extras.keys.join(' '),
+                reason: :config_without_extras_support
+              )
+            )
+            return [config.generate_nonce_csp(nonce, development_mode: development_mode), nil]
+          end
+
+          applied = nil
+          reported = false
+          policy = config.generate_nonce_csp(
+            nonce, development_mode: development_mode, extra_directives: extras
+          ) do |applied_extras, dropped_extras|
+            reported = true
+            applied = applied_extras unless applied_extras.empty?
+            log_dropped_extras(env, dropped_extras)
+          end
+          unless reported
+            Otto.structured_log(
+              :warn, 'CSP request extras outcome unreported',
+              Otto::LoggingHelpers.request_context(env).merge(
+                directives: extras.keys.join(' '),
+                reason: :config_outcome_not_reported
+              )
+            )
+          end
+          [policy, applied]
+        end
+        private_class_method :build_policy
+
+        # Whether the config's generate_nonce_csp declares the
+        # `extra_directives:` keyword (or accepts arbitrary keywords).
+        def self.supports_extra_directives?(config)
+          parameters = config.method(:generate_nonce_csp).parameters
+          parameters.any? { |type, name| KEYWORD_PARAM_TYPES.include?(type) && name == :extra_directives } ||
+            parameters.any? { |type, _name| type == :keyrest }
+        rescue NameError
+          false
+        end
+        private_class_method :supports_extra_directives?
+
+        # Log each extras entry the policy build dropped, once per entry, with
+        # full request context. The reason distinguishes the two ways an entry
+        # fails to land: its directive was absent from the built policy
+        # (:absent_directive) or the directive takes no value at all, so a
+        # source could never be appended to it (:valueless_directive) — the
+        # latter is an app bug worth naming precisely, since the entry is a
+        # no-op rather than a policy gap.
+        def self.log_dropped_extras(env, dropped)
+          return if dropped.nil? || dropped.empty?
+
+          context = Otto::LoggingHelpers.request_context(env)
+          dropped.each do |name, tokens|
+            reason = Policy.valueless_directive?(name) ? :valueless_directive : :absent_directive
+            Otto.structured_log(
+              :warn, 'CSP request extra dropped',
+              context.merge(
+                directive: name,
+                token: Array(tokens).join(' ').inspect.slice(0, 128),
+                reason: reason
+              )
+            )
+          end
+        end
+        private_class_method :log_dropped_extras
+
+        # Resolve the request-scoped extras, gated on the boot-time opt-in.
+        # The env key is a write surface ANY middleware in the Rack stack can
+        # reach — a lower-trust position than boot code — so the channel does
+        # not exist until {Otto::Security::Config#enable_csp_request_extras!}
+        # was called: when disabled (including duck-typed configs without the
+        # predicate) the env key is ignored entirely, with no sanitize work
+        # and no logs.
+        def self.resolve_extras(config, env)
+          return nil unless env
+          return nil unless config.respond_to?(:csp_request_extras_enabled?) && config.csp_request_extras_enabled?
+
+          RequestExtras.from_env(env)
+        end
+        private_class_method :resolve_extras
+
         # In-place, key-scoped write. Delete any case-variant of the CSP key
         # (correcting a downstream SPEC violation), then write the canonical
         # lowercase key into the caller's hash. Variant keys are collected before
@@ -182,12 +317,18 @@ class Otto
 
         # Uniform debug observability: when the config opts into CSP debugging,
         # log the outcome — applied policy OR skip reason — so "why didn't my page
-        # get a CSP?" no longer needs a debugger.
+        # get a CSP?" no longer needs a debugger. When request-scoped extras
+        # were folded in, note which directives and how many tokens: the
+        # EmitMiddleware backstop is otherwise silent about them, so this is
+        # the observable trace that a request's extras actually landed.
         def self.log_debug(config, result)
           return unless config.respond_to?(:debug_csp?) && config.debug_csp?
           return unless defined?(Otto.logger) && Otto.logger
 
           detail = result.applied? ? "applied (#{result.mode}) #{result.policy}" : "skipped (#{result.skip_reason})"
+          if (extras = result.extra_directives)
+            detail += " extras[#{extras.keys.join(' ')}](#{extras.each_value.sum(&:length)} tokens)"
+          end
           Otto.logger.debug("[CSP] #{detail}")
         end
         private_class_method :log_debug

data/lib/otto/security/csp.rb

@@ -14,6 +14,10 @@
 #                  Result object, :override / :backstop modes) that every surface
 #                  routes through: Otto::Response#apply_csp, the EmitMiddleware,
 #                  and the deprecated Otto::Response#send_csp_headers shim.
+# - RequestExtras — reads + sanitizes the opt-in request-scoped directive
+#                  extras from env['otto.csp.extra_directives'] (delano/otto#243);
+#                  the Writer folds the survivors in additively via
+#                  Policy.append_extra_sources.
 # - EmitMiddleware — passive backstop that emits a nonce CSP for responses whose
 #                  request consumed a nonce (emit-if-consumed). See
 #                  Otto::Security::Core#enable_csp_emission!.
@@ -23,6 +27,7 @@
 #   callback API. See Otto::Security::Core#enable_csp_reporting!.
 
 require_relative 'csp/policy'
+require_relative 'csp/request_extras'
 require_relative 'csp/nonce'
 require_relative 'csp/writer'
 require_relative 'csp/report'

data/lib/otto/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.8.1
+  version: 2.9.0
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -312,6 +312,7 @@ files:
 - lib/otto/security/csp/policy.rb
 - lib/otto/security/csp/report.rb
 - lib/otto/security/csp/report_middleware.rb
+- lib/otto/security/csp/request_extras.rb
 - lib/otto/security/csp/writer.rb
 - lib/otto/security/csrf.rb
 - lib/otto/security/csrf_enforcement_wrapper.rb