otto 2.3.1 → 2.5.0

data/lib/otto/response.rb

@@ -14,12 +14,18 @@ class Otto
   # @example Using Otto's response in route handlers
   #   def show(req, res)
   #     res.send_secure_cookie('session_id', token, 3600)
-  #     res.send_csp_headers('text/html', nonce)
+  #     res.apply_csp(req.csp_nonce)
   #     res.no_cache!
   #   end
   #
   # @see Otto#register_response_helpers
   class Response < Rack::Response
+    # One-time-per-process guard for the #send_csp_headers deprecation warning.
+    @send_csp_headers_deprecation_warned = false
+    class << self
+      attr_accessor :send_csp_headers_deprecation_warned # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+    end
+
     # Reference to the request object (needed by some response helpers)
     # @return [Otto::Request]
     attr_accessor :request
@@ -97,56 +103,65 @@ class Otto
       headers
     end
 
-    # Set Content Security Policy (CSP) headers with nonce support
+    # Apply a nonce-based Content-Security-Policy to this response.
+    #
+    # This is THE emission helper: it routes through the single apply core
+    # ({Otto::Security::CSP::Writer}), so all the invariants — enabled-only,
+    # nonce-present, HTML-only, lowercase key, no duplicate — hold here exactly as
+    # they do in the middleware, with no guard logic duplicated. The response's
+    # Content-Type must already be set (it decides HTML-only); this helper does
+    # NOT set it.
+    #
+    # `mode: :override` (the default) is the deliberate per-request call: it
+    # REPLACES any existing CSP. Pass `mode: :backstop` to defer to an existing
+    # policy instead.
     #
-    # This method generates and sets CSP headers with the provided nonce value,
-    # following the same usage pattern as send_cookie methods. The CSP policy
-    # is generated dynamically based on the security configuration and environment.
+    # @param nonce [String] the per-request nonce (typically {Otto::Request#csp_nonce})
+    # @param mode [Symbol] `:override` or `:backstop` (see {Otto::Security::CSP::Writer::MODES})
+    # @param development_mode [Boolean] use development-friendly CSP directives
+    # @param security_config [Otto::Security::Config, nil] config to use; resolved
+    #   from the request env when omitted
+    # @return [Otto::Security::CSP::Writer::Result] the outcome (applied?, policy,
+    #   skip_reason) for uniform observability
     #
-    # @param content_type [String] Content-Type header value to set
+    # @example
+    #   res['content-type'] = 'text/html; charset=utf-8'
+    #   res.apply_csp(req.csp_nonce)
+    def apply_csp(nonce, mode: :override, development_mode: false, security_config: nil)
+      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
+      )
+    end
+
+    # @deprecated Use {#apply_csp} instead. Retained as a thin shim over the apply
+    #   core so existing callers keep working while its historical quirks are
+    #   fixed: a nil/empty nonce no longer emits a broken `script-src 'nonce-'`
+    #   (it skips), a CSP is no longer emitted for non-HTML responses, and the
+    #   override notice goes through {Otto.logger} instead of a bare `warn` to
+    #   stderr. Unlike {#apply_csp}, it still sets the Content-Type for you and
+    #   emits in `:override` mode.
+    #
+    # @param content_type [String] Content-Type to set if not already set
     # @param nonce [String] Nonce value to include in CSP directives
-    # @param opts [Hash] Options for CSP generation
+    # @param opts [Hash] Options
     # @option opts [Otto::Security::Config] :security_config Security config to use
     # @option opts [Boolean] :development_mode Use development-friendly CSP directives
-    # @option opts [Boolean] :debug Enable debug logging for this request
-    # @return [void]
-    #
-    # @example Basic usage
-    #   nonce = SecureRandom.base64(16)
-    #   res.send_csp_headers('text/html; charset=utf-8', nonce)
-    #
-    # @example With options
-    #   res.send_csp_headers('text/html; charset=utf-8', nonce, {
-    #     development_mode: Rails.env.development?,
-    #     debug: true
-    #   })
+    # @return [Otto::Security::CSP::Writer::Result]
     def send_csp_headers(content_type, nonce, opts = {})
-      # Set content type if not already set
-      headers['content-type'] ||= content_type
+      warn_send_csp_headers_deprecated
 
-      # Warn if CSP header already exists but don't skip
-      warn 'CSP header already set, overriding with nonce-based policy' if headers['content-security-policy']
-
-      # Get security configuration
-      security_config = opts[:security_config] ||
-                        (request&.env && request.env['otto.security_config']) ||
-                        nil
-
-      # Skip if CSP nonce support is not enabled
-      return unless security_config&.csp_nonce_enabled?
-
-      # Generate CSP policy with nonce
-      development_mode = opts[:development_mode] || false
-      csp_policy       = security_config.generate_nonce_csp(nonce, development_mode: development_mode)
-
-      # Debug logging if enabled
-      debug_enabled = opts[:debug] || security_config.debug_csp?
-      if debug_enabled && defined?(Otto.logger)
-        Otto.logger.debug "[CSP] #{csp_policy}"
-      end
+      # Historical behavior the shim keeps (apply_csp does not): default the
+      # Content-Type so an HTML response is recognized as HTML.
+      headers['content-type'] ||= content_type
 
-      # Set the CSP header
-      headers['content-security-policy'] = csp_policy
+      apply_csp(
+        nonce,
+        mode: :override,
+        development_mode: opts[:development_mode] || false,
+        security_config: opts[:security_config]
+      )
     end
 
     # Set cache control headers to prevent caching
@@ -187,5 +202,27 @@ class Otto
       paths.unshift(request.env['SCRIPT_NAME']) if request&.env&.[]('SCRIPT_NAME')
       paths.join('/').gsub('//', '/')
     end
+
+    private
+
+    # Emit the #send_csp_headers deprecation notice at most once per process
+    # (Response is per-request, so the guard lives on the class).
+    #
+    # The check-then-set on the class flag is deliberately unsynchronized: the
+    # race is benign — worst case, two threads racing on the very first call each
+    # log the notice once. The flag gates only a log line, never any behavior, so
+    # a mutex would add contention on a hot path to save at most a couple of
+    # duplicate deprecation lines at startup.
+    def warn_send_csp_headers_deprecated
+      return if self.class.send_csp_headers_deprecation_warned
+      return unless defined?(Otto.logger) && Otto.logger
+
+      self.class.send_csp_headers_deprecation_warned = true
+      Otto.logger.warn(
+        '[Otto::Response] #send_csp_headers is deprecated and will be removed in a ' \
+        'future release; use #apply_csp(nonce, mode: :override) (set Content-Type first), ' \
+        'or mount Otto::Security::CSP::EmitMiddleware via #enable_csp_emission!.'
+      )
+    end
   end
 end

data/lib/otto/security/config.rb

@@ -7,6 +7,7 @@ require 'digest'
 require 'openssl'
 require 'ipaddr'
 require_relative '../core/freezable'
+require_relative 'csp/policy'
 
 class Otto
   module Security
@@ -44,6 +45,13 @@ class Otto
       # depth mode; CIDR-walk is unaffected.
       TRUSTED_PROXY_HEADERS = %w[X-Forwarded-For Forwarded Both].freeze
 
+      # Endpoint group name shared by the CSP `report-to` directive and the
+      # `Reporting-Endpoints` response header (modern Reporting API). Browsers
+      # match the directive's group to the header's key, so both must agree.
+      # Aliases {Otto::Security::CSP::Policy::REPORTING_GROUP} — the one source
+      # the policy builder uses — so the header and the directive cannot drift.
+      CSP_REPORTING_GROUP = Otto::Security::CSP::Policy::REPORTING_GROUP
+
       # Error raised when CSRF protection is enabled in production without an
       # explicitly configured secret. A randomly-generated per-process secret
       # silently breaks token verification across workers and restarts, so we
@@ -62,8 +70,9 @@ class Otto
       attr_reader :csrf_protection,  :csrf_header_key,
                   :trusted_proxies, :require_secure_cookies,
                   :security_headers,
-                  :csp_nonce_enabled, :debug_csp, :mcp_auth,
-                  :ip_privacy_config, :trusted_proxy_depth, :trusted_proxy_header
+                  :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
 
       # Initialize security configuration with safe defaults
       #
@@ -86,6 +95,11 @@ class Otto
         @input_validation       = true
         @csp_nonce_enabled      = false
         @debug_csp              = false
+        @csp_nonce_key          = 'otto.nonce'
+        @csp_policy             = nil
+        @csp_report_uri         = nil
+        @csp_report_to_url      = nil
+        @csp_violation_callback = nil
         @rate_limiting_config   = { custom_rules: {} }
         @ip_privacy_config      = Otto::Privacy::Config.new
 
@@ -343,7 +357,8 @@ class Otto
       def enable_csp!(policy = "default-src 'self'")
         ensure_not_frozen!
 
-        @security_headers['content-security-policy'] = policy
+        @csp_policy = policy
+        @security_headers['content-security-policy'] = build_static_csp(policy)
       end
 
       # Enable Content Security Policy (CSP) with nonce support
@@ -382,6 +397,22 @@ class Otto
         @csp_nonce_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.
+      # `'onetime.nonce'`) so the accessor adopts that app's env key without a
+      # rename. A blank value resets to the default.
+      #
+      # @param key [String] the env key
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      def csp_nonce_key=(key)
+        ensure_not_frozen!
+
+        normalized     = key.to_s.strip
+        @csp_nonce_key = normalized.empty? ? 'otto.nonce' : normalized
+      end
+
       # Check if CSP debug logging is enabled
       #
       # @return [Boolean] true if CSP debug logging is enabled
@@ -389,14 +420,126 @@ class Otto
         @debug_csp
       end
 
+      # Configure the path browsers should POST CSP violation reports to.
+      #
+      # Setting this does two things:
+      # 1. A `report-uri <path>` directive is appended to every emitted CSP
+      #    policy — both the static policy from {#enable_csp!} and the per-request
+      #    nonce policy from {#generate_nonce_csp} — so browsers know where to
+      #    send violations.
+      # 2. {Otto::Security::CSP::ReportMiddleware} activates for that path (it is
+      #    inert until a report URI is set).
+      #
+      # When nil/empty (the default), NO reporting directive is emitted and the
+      # policy output is byte-identical to Otto's historical output.
+      #
+      # For the turnkey setup that also injects the receiving middleware, prefer
+      # {Otto::Security::Core#enable_csp_reporting!} on the Otto instance.
+      #
+      # @param uri [String, nil] path browsers POST reports to (matched against
+      #   `PATH_INFO`, e.g. `/_/csp-report`), or nil to disable reporting. A
+      #   value without a leading slash is coerced to an absolute path so it
+      #   matches the slash-prefixed `PATH_INFO` the middleware compares against.
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      def csp_report_uri=(uri)
+        ensure_not_frozen!
+
+        @csp_report_uri = normalize_report_path(uri)
+        rebuild_static_csp_with_reporting!
+      end
+
+      # Configure the absolute URL browsers should POST CSP violation reports to
+      # via the modern Reporting API (Reporting-Endpoints header + `report-to`
+      # directive), complementing the legacy path-based {#csp_report_uri=}.
+      #
+      # Setting this does two things:
+      # 1. A `report-to #{CSP_REPORTING_GROUP}` directive is appended to every
+      #    emitted CSP policy (static and per-request nonce alike), and a
+      #    `Reporting-Endpoints` response header maps that group to this URL.
+      # 2. Modern browsers (which have deprecated `report-uri`) deliver reports
+      #    as `application/reports+json` to this endpoint — already parsed by
+      #    {Otto::Security::CSP::Parser}.
+      #
+      # The value MUST be an ABSOLUTE URL (Reporting-Endpoints does not accept a
+      # bare path). Point it at the same receiver as {#csp_report_uri=}: its path
+      # component should equal the report URI so {Otto::Security::CSP::ReportMiddleware}
+      # (which matches on PATH_INFO) intercepts modern reports too.
+      #
+      # When nil/empty (the default), NO `report-to` directive or
+      # `Reporting-Endpoints` header is emitted and policy output is
+      # byte-identical to Otto's historical output.
+      #
+      # @param url [String, nil] absolute URL for the Reporting API endpoint, or
+      #   nil to disable modern reporting.
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      def csp_report_to_url=(url)
+        ensure_not_frozen!
+
+        @csp_report_to_url = normalize_report_uri(url)
+        if @csp_report_to_url
+          @security_headers['reporting-endpoints'] = reporting_endpoints_header
+        else
+          @security_headers.delete('reporting-endpoints')
+        end
+        rebuild_static_csp_with_reporting!
+      end
+
+      # Register the callback invoked once per parsed CSP violation report.
+      #
+      # The block receives an {Otto::Security::CSP::Report}. Your application
+      # decides what to do — log, emit a metric, store, forward, or ignore. Otto
+      # adds no storage or database coupling.
+      #
+      # Registering a second callback REPLACES the first (last registration
+      # wins), matching the singular `on_csp_violation` semantics. Calling this
+      # with NO block clears (unregisters) any previously-set callback.
+      #
+      # SECURITY NOTE: report URL fields may carry sensitive path/query data in
+      # some applications. Redact them in your callback before logging if needed;
+      # Otto passes them through un-redacted (see {Otto::Security::CSP::Report}).
+      #
+      # @yieldparam report [Otto::Security::CSP::Report] a normalized report
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      def on_csp_violation(&block)
+        ensure_not_frozen!
+
+        @csp_violation_callback = block
+      end
+
+      # Invoke the registered violation callback for a report, isolating any
+      # error it raises. A misbehaving application callback must never break the
+      # report receiver (which always answers 204).
+      #
+      # @param report [Otto::Security::CSP::Report]
+      # @return [void]
+      def dispatch_csp_violation(report)
+        callback = @csp_violation_callback
+        return if callback.nil?
+
+        callback.call(report)
+      rescue StandardError => e
+        Otto.logger.error("[Otto::CSP] violation callback raised #{e.class}: #{e.message}")
+      end
+
       # 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.
+      #
       # @param nonce [String] The nonce value to include in the CSP
       # @param development_mode [Boolean] Whether to use development-friendly directives
       # @return [String] Complete CSP policy string
       def generate_nonce_csp(nonce, development_mode: false)
-        directives = development_mode ? development_csp_directives(nonce) : production_csp_directives(nonce)
-        directives.join(' ')
+        Otto::Security::CSP::Policy.nonce_policy(
+          nonce,
+          development_mode: development_mode,
+          report_uri: @csp_report_uri,
+          report_to_url: @csp_report_to_url
+        )
       end
 
       # Enable X-Frame-Options header to prevent clickjacking
@@ -705,52 +848,92 @@ class Otto
         defined?(Otto) && Otto.respond_to?(:env?) && Otto.env?(:production, :prod)
       end
 
-      # Generate CSP directives for development environment
-      #
-      # Development mode allows inline scripts/styles and hot reloading connections
-      # for better developer experience with build tools like Vite.
-      #
-      # @param nonce [String] The nonce value to include in script-src
-      # @return [Array<String>] Array of CSP directive strings
-      def development_csp_directives(nonce)
-        [
-          "default-src 'none';",
-          "script-src 'nonce-#{nonce}' 'unsafe-inline';", # Allow inline scripts for development tools
-          "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:;",
-          "font-src 'self';",
-          "object-src 'none';",
-          "base-uri 'self';",
-          "form-action 'self';",
-          "frame-ancestors 'none';",
-          "manifest-src 'self';",
-          "worker-src 'self' data:;",
-        ]
-      end
-
-      # Generate CSP directives for production environment
-      #
-      # Production mode is more restrictive, only allowing HTTPS connections
-      # and nonce-only scripts for enhanced XSS protection.
-      #
-      # @param nonce [String] The nonce value to include in script-src
-      # @return [Array<String>] Array of CSP directive strings
-      def production_csp_directives(nonce)
-        [
-          "default-src 'none';",                     # Restrict to same origin by default
-          "script-src 'nonce-#{nonce}';",            # Only allow scripts with valid nonce
-          "style-src 'self' 'unsafe-inline';",       # Allow inline styles and same-origin stylesheets
-          "connect-src 'self' wss: https:;",         # Only HTTPS and secure WebSockets
-          "img-src 'self' data:;",                   # Allow images from same origin and data URIs
-          "font-src 'self';",                        # Allow fonts from same origin only
-          "object-src 'none';",                      # Block <object>, <embed>, and <applet> elements
-          "base-uri 'self';",                        # Restrict <base> tag targets to same origin
-          "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
-        ]
+      # Normalize a configured report URI: strip surrounding whitespace and
+      # treat a blank string as "not configured" (nil).
+      #
+      # @param uri [String, nil]
+      # @return [String, nil]
+      def normalize_report_uri(uri)
+        return nil if uri.nil?
+
+        stripped = uri.to_s.strip
+        stripped.empty? ? nil : stripped
+      end
+
+      # Normalize a configured report PATH: the local endpoint the receiver
+      # matches on `PATH_INFO`. Same strip/blank-to-nil handling as
+      # {#normalize_report_uri}, but a bare relative value is coerced to an
+      # absolute path — a value like `"csp-report"` would otherwise (a) never
+      # equal the slash-prefixed `PATH_INFO` the middleware compares against, and
+      # (b) be resolved by browsers relative to the document URL. An absolute URL
+      # (contains a scheme) is left untouched.
+      #
+      # @param uri [String, nil]
+      # @return [String, nil]
+      def normalize_report_path(uri)
+        normalized = normalize_report_uri(uri)
+        return nil if normalized.nil?
+        return normalized if normalized.start_with?('/') || normalized.include?('://')
+
+        "/#{normalized}"
+      end
+
+      # Recompute the stored static CSP header so the report-uri / report-to
+      # directives track the current settings, independent of the order in which
+      # {#enable_csp!} and the report setters were called.
+      #
+      # The base is normally @csp_policy (set by {#enable_csp!}). When a static
+      # CSP was instead injected directly through {#set_security_headers} (so
+      # @csp_policy is nil), adopt that header as the base the first time a report
+      # directive is configured — so reporting augments it too. Capturing it as
+      # the pristine base keeps later rebuilds idempotent. A static header set
+      # directly AFTER reporting is configured bypasses this and remains the
+      # application's to manage.
+      #
+      # @return [void]
+      def rebuild_static_csp_with_reporting!
+        @csp_policy ||= adoptable_static_csp_base
+        return if @csp_policy.nil?
+
+        @security_headers['content-security-policy'] = build_static_csp(@csp_policy)
+      end
+
+      # The current static CSP header when it can serve as a pristine base policy
+      # for reporting augmentation: present and not already carrying a report
+      # directive (adopting one that does would double-append). Otherwise nil —
+      # notably, the nonce path sets no static header, so nothing is adopted.
+      #
+      # @return [String, nil]
+      def adoptable_static_csp_base
+        existing = @security_headers['content-security-policy']
+        return nil if existing.nil? || existing.empty?
+        return nil if existing.include?('report-uri') || existing.include?('report-to')
+
+        existing
+      end
+
+      # The `Reporting-Endpoints` response header value mapping the CSP reporting
+      # group to the configured absolute endpoint URL, e.g.
+      # `otto-csp="https://example.com/_/csp-report"`.
+      #
+      # @return [String]
+      def reporting_endpoints_header
+        %(#{CSP_REPORTING_GROUP}="#{@csp_report_to_url}")
+      end
+
+      # Build the stored static-CSP header value: the base policy plus the
+      # optional report-uri and report-to directives. Thin facade over
+      # {Otto::Security::CSP::Policy.static_policy}; byte-identical to the bare
+      # policy when no reporting is configured.
+      #
+      # @param policy [String] the base policy passed to {#enable_csp!}
+      # @return [String]
+      def build_static_csp(policy)
+        Otto::Security::CSP::Policy.static_policy(
+          policy,
+          report_uri: @csp_report_uri,
+          report_to_url: @csp_report_to_url
+        )
       end
     end
 

data/lib/otto/security/configurator.rb

@@ -198,6 +198,60 @@ class Otto
         @security_config.enable_csp_with_nonce!(debug: debug)
       end
 
+      # Mount {Otto::Security::CSP::EmitMiddleware} (passive backstop that emits a
+      # nonce CSP for responses lacking one, never clobbering). Enable nonce-CSP
+      # ({#enable_csp_with_nonce!}) for it to emit anything; until then it is
+      # INERT (a transparent pass-through), not an error, and the two may be
+      # enabled in either order. Emit-if-consumed by default — see
+      # {Otto::Security::Core#enable_csp_emission!}.
+      #
+      # @param eager [Boolean] mint-and-emit for every eligible HTML response
+      # @param development_mode [Boolean, #call, nil] development-directive toggle;
+      #   a callable is evaluated per request with the env
+      def enable_csp_emission!(eager: false, development_mode: nil)
+        return if middleware_enabled?(Otto::Security::CSP::EmitMiddleware)
+
+        @middleware_stack.add(Otto::Security::CSP::EmitMiddleware, eager: eager, development_mode: development_mode)
+      end
+
+      # Enable turnkey CSP violation reporting: set the report URI (appends a
+      # `report-uri` directive to emitted policies), register the callback, and
+      # inject {Otto::Security::CSP::ReportMiddleware} pinned OUTERMOST so it
+      # intercepts report POSTs ahead of CSRF regardless of enable order.
+      #
+      # @param report_uri [String] path browsers POST reports to (matched against PATH_INFO)
+      # @param endpoint_url [String, nil] absolute URL for the modern Reporting
+      #   API endpoint (emits `report-to` + `Reporting-Endpoints`); nil emits
+      #   only the legacy `report-uri`
+      # @yieldparam report [Otto::Security::CSP::Report] a normalized violation report
+      def enable_csp_reporting!(report_uri, endpoint_url: nil, &block)
+        @security_config.csp_report_uri = report_uri
+        @security_config.csp_report_to_url = endpoint_url unless endpoint_url.nil?
+        @security_config.on_csp_violation(&block) if block
+
+        return if middleware_enabled?(Otto::Security::CSP::ReportMiddleware)
+
+        @middleware_stack.add_with_position(Otto::Security::CSP::ReportMiddleware, position: :outermost)
+      end
+
+      # Configure the CSP violation report path without injecting middleware.
+      # Prefer {#enable_csp_reporting!} for the full turnkey setup.
+      #
+      # @param uri [String, nil] report path (matched against PATH_INFO), or nil to disable
+      def csp_report_uri=(uri)
+        @security_config.csp_report_uri = uri
+      end
+
+      # Configure the absolute URL for the modern Reporting API endpoint
+      # (`report-to` directive + `Reporting-Endpoints` header) without injecting
+      # middleware. Prefer {#enable_csp_reporting!} with `endpoint_url:` for the
+      # full turnkey setup.
+      #
+      # @param url [String, nil] absolute endpoint URL, or nil to disable modern reporting
+      def csp_report_to_url=(url)
+        @security_config.csp_report_to_url = url
+      end
+
       # Add a single authentication strategy
       #
       # Part of the Security::Configurator facade for consolidated configuration.

data/lib/otto/security/core.rb

@@ -135,6 +135,100 @@ class Otto
         @security_config.enable_csp_with_nonce!(debug: debug)
       end
 
+      # Mount {Otto::Security::CSP::EmitMiddleware} so nonce-based CSP headers are
+      # applied to responses by the framework instead of hand-rolled in each app.
+      #
+      # It is a passive backstop: it emits a nonce CSP only for responses that
+      # would otherwise ship without one, and never clobbers a policy a route
+      # already set. Enable nonce-CSP via {#enable_csp_with_nonce!} for it to
+      # emit anything — until then the middleware is INERT (a transparent
+      # pass-through), NOT an error. The two may be enabled in either order:
+      # both read the same security config, so mounting the backstop first and
+      # enabling nonce-CSP later works. Enable-order independence is why this
+      # does not raise when nonce-CSP is off.
+      #
+      # By DEFAULT it is emit-if-consumed — it emits only when the request
+      # actually consumed a nonce (a view called {Otto::Request#csp_nonce}). This
+      # is the only safe blanket default: a nonce-only policy on a page that never
+      # stamped the nonce blocks every script.
+      #
+      # @param eager [Boolean] mint-and-emit for every eligible HTML response
+      #   rather than only emit-if-consumed (see the middleware's caveats)
+      # @param development_mode [Boolean, #call, nil] whether to emit development
+      #   directives; a callable is evaluated per request with the env
+      # @return [void]
+      # @example
+      #   otto.enable_csp_with_nonce!
+      #   otto.enable_csp_emission!(development_mode: -> (env) { ENV['RACK_ENV'] == 'development' })
+      def enable_csp_emission!(eager: false, development_mode: nil)
+        ensure_not_frozen!
+        return if @middleware.includes?(Otto::Security::CSP::EmitMiddleware)
+
+        @middleware.add(Otto::Security::CSP::EmitMiddleware, eager: eager, development_mode: development_mode)
+      end
+
+      # Enable turnkey Content Security Policy violation reporting.
+      #
+      # This is the receiving half of Otto's CSP support. It:
+      # 1. Configures the report path (`config.csp_report_uri = report_uri`), so a
+      #    `report-uri` directive is appended to every emitted CSP policy (static
+      #    {#enable_csp!} and nonce {#enable_csp_with_nonce!} alike).
+      # 2. Registers your violation callback (if a block is given).
+      # 3. Injects {Otto::Security::CSP::ReportMiddleware} so browser POSTs to the
+      #    report path are received, parsed, and dispatched to the callback —
+      #    always answered with 204 and never touching your routes.
+      #
+      # 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.
+      #
+      # SECURITY / DoS: running outermost also means the receiver sits ahead of
+      # rate limiting (rate limiting is inner middleware). This is intentional —
+      # a public, unauthenticated report endpoint cannot depend on CSRF, session,
+      # or per-client throttling state — but it means a client can POST reports
+      # up to the 64 KiB body cap and invoke your callback on each one. Keep the
+      # callback cheap and bounded (sample or aggregate; avoid unbounded
+      # synchronous I/O), and put request-rate control for this path at the edge
+      # (reverse proxy / CDN / WAF) rather than expecting Otto to throttle it.
+      #
+      # To (re)assign the callback later without touching the wiring, use the
+      # config primitive directly: `otto.security_config.on_csp_violation { ... }`.
+      #
+      # For modern browsers (which have deprecated `report-uri`), also pass
+      # `endpoint_url:` — an ABSOLUTE URL whose path is `report_uri`. Otto then
+      # emits a `report-to` directive plus a `Reporting-Endpoints` header so those
+      # browsers deliver `application/reports+json` to the same receiver.
+      #
+      # @param report_uri [String] path browsers POST reports to (matched against
+      #   `PATH_INFO`, e.g. `/_/csp-report`).
+      # @param endpoint_url [String, nil] absolute URL for the modern Reporting
+      #   API endpoint (e.g. `https://example.com/_/csp-report`); nil emits only
+      #   the legacy `report-uri`.
+      # @yieldparam report [Otto::Security::CSP::Report] a normalized violation report
+      # @return [void]
+      # @example
+      #   otto.enable_csp_with_nonce!
+      #   otto.enable_csp_reporting!('/_/csp-report',
+      #     endpoint_url: 'https://example.com/_/csp-report') do |report|
+      #     Otto.logger.warn("CSP violation: #{report.to_h}")
+      #   end
+      def enable_csp_reporting!(report_uri, endpoint_url: nil, &block)
+        ensure_not_frozen!
+
+        @security_config.csp_report_uri = report_uri
+        @security_config.csp_report_to_url = endpoint_url unless endpoint_url.nil?
+        @security_config.on_csp_violation(&block) if block
+
+        return if @middleware.includes?(Otto::Security::CSP::ReportMiddleware)
+
+        # Pin OUTERMOST so it intercepts report POSTs ahead of CSRF regardless of
+        # the order security features are enabled in. add_with_position fires the
+        # stack's on_change callback, which rebuilds @app (wired in
+        # Otto#initialize_core_state) — no explicit build_app! needed.
+        @middleware.add_with_position(Otto::Security::CSP::ReportMiddleware, position: :outermost)
+      end
+
       # Add an authentication strategy with a registered name
       #
       # This is the primary public API for registering authentication strategies.