otto 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e50cca678689db3e2447e76a8a1b12f3b709305d4f73908cb06dfe6883adc596
-  data.tar.gz: a6093388b74ffbd098c222a026c1f1cf439c8039c75a0d55b663a0874669c6ee
+  metadata.gz: 343eb2f324f142437e65c4d5659201363a13eb68d599891146a2aad426da817e
+  data.tar.gz: 542f896395a10158c89025cc3a6685d837ad63fa4aeb93deca81744f3a7d7e92
 SHA512:
-  metadata.gz: ea5a8acda9a29c09d3a16a050050c2e9b9a1517c7f63e24bb7bc910801a7a07874fff1215550a740cef2c9c3698bc77378083b33f47794a7668b77feff9e6e67
-  data.tar.gz: 62cfbe824d5d0d9e159424a6d930217f05b8b01de7142108a6a80953207cca9037a3e63d6ae5c16585dda3ff7b8a9b2d070b593f748563c0a5a20ed852add37f
+  metadata.gz: 59073e6907b3f183b7bf81b376ec07ff6d30ddbadb1436bbc8b1711265c325026486d44645b8f1a39e2cc181d9fcba4e8661259321ce40eab006e1e837fb82de
+  data.tar.gz: 4b2a0c746eb41f05971740593d04a45670869f35ce4b58d1aa74cc1a25052cbb32d0dec961ba60dfd31bc7fe0c6e990dbaad5e12396869240065bd461b7e8229

data/CHANGELOG.rst

@@ -7,6 +7,76 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.5.0:
+
+2.5.0 — 2026-07-02
+==================
+
+Added
+-----
+
+- ``Otto::Security::CSP::Writer.apply(headers, nonce, config:, mode:,
+  development_mode:)`` — the single structural apply core for nonce-based CSP
+  emission. Writes are in-place and key-scoped (case-variant keys are corrected
+  to Rack 3's lowercase in the caller's hash; a frozen headers hash fails loud).
+  Returns a ``Result`` (``applied?``, ``policy``, ``skip_reason`` of
+  ``:disabled`` / ``:blank_nonce`` / ``:non_html`` / ``:existing_csp``). Named
+  modes ``:override`` (deliberate, replaces) and ``:backstop`` (passive,
+  defers). (delano/otto#180)
+
+- Framework-owned lazy nonce: ``Otto::Request#csp_nonce`` /
+  ``Otto::Security::CSP.nonce(env)`` generate on first access and memoize into
+  ``env['otto.nonce']`` (registered as ``Otto::EnvKeys::NONCE``), so views and
+  the header read one value. Configurable env key via
+  ``Otto::Security::Config#csp_nonce_key`` for apps with an existing convention.
+
+- ``Otto::Security::CSP::EmitMiddleware`` and ``Otto#enable_csp_emission!`` — a
+  passive backstop that emits a nonce CSP for HTML responses whose request
+  consumed a nonce (emit-if-consumed default), never clobbering an existing
+  policy. Optional ``eager:`` mode and a per-request ``development_mode:``
+  callable.
+
+- ``Otto::Response#apply_csp(nonce, mode: :override)`` — the one emission helper,
+  routed through the apply core.
+
+- ``Otto::Security::CSP::Policy`` — CSP policy building (directive sets,
+  report-uri/report-to assembly) extracted from ``Otto::Security::Config`` into
+  its own home beside the parser and middlewares; ``Config`` delegates with
+  byte-identical output.
+
+Deprecated
+----------
+
+- ``Otto::Response#send_csp_headers`` — use ``#apply_csp`` or
+  ``#enable_csp_emission!``. Retained as a thin shim over the apply core (logs a
+  one-time ``Otto.logger`` deprecation notice).
+
+Fixed
+-----
+
+- ``#send_csp_headers`` no longer emits a broken ``script-src 'nonce-'`` for a
+  blank/nil nonce (it skips) and no longer emits a CSP for non-HTML responses —
+  both via the shared apply core. Its bare ``warn`` to stderr when overwriting an
+  existing CSP is also gone: replacement is deliberate in ``:override`` mode, and
+  the shim instead logs a one-time deprecation notice through ``Otto.logger``.
+
+Security
+--------
+
+- Nonce-CSP emission now detects and normalizes CSP / Content-Type headers
+  case-insensitively, so a canonical-/mixed-cased header from a downstream layer
+  is recognized (and the CSP key rewritten to lowercase) rather than silently
+  duplicated — de-duplicating the hand-rolled, case-sensitive guards adopters
+  previously re-implemented at each raw-tuple boundary. (delano/otto#180)
+
+AI Assistance
+-------------
+
+- The nonce-CSP emission redesign — the ``Writer`` apply core, the
+  framework-owned lazy nonce, the ``EmitMiddleware`` backstop, and the
+  ``Policy`` extraction — was designed and implemented with AI assistance.
+  (delano/otto#180)
+
 .. _changelog-2.4.0:
 
 2.4.0 — 2026-07-01

data/Gemfile.lock

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

data/README.md

@@ -84,6 +84,60 @@ app = Otto.new("./routes", {
 
 Security features include CSRF protection, input validation, security headers, and trusted proxy configuration.
 
+### Content Security Policy (nonce-based emission)
+
+Otto owns the nonce lifecycle so the header and your views can never drift. A
+request-scoped nonce is minted lazily on first access and memoized in the env;
+your views read it to stamp `<script>`/`<link>` tags, and the framework reads
+the *same* value to emit the `script-src 'nonce-…'` header.
+
+```ruby
+app = Otto.new("./routes")
+app.enable_csp_with_nonce!    # turn on nonce-based CSP
+app.enable_csp_emission!      # mount the backstop that writes the header
+
+# In a view/handler:
+def show(req, res)
+  res['content-type'] = 'text/html; charset=utf-8'
+  res.write(%(<script nonce="#{req.csp_nonce}">/* inline */</script>))
+end
+```
+
+`enable_csp_emission!` mounts `Otto::Security::CSP::EmitMiddleware`, a passive
+**backstop**:
+
+- **Emit-if-consumed** (default): it emits a policy only for a response whose
+  request actually consumed a nonce (a view called `req.csp_nonce`). A nonce-only
+  `script-src` on an HTML page that never stamped the nonce would block every
+  script, so "CSP responses whose request consumed a nonce" is the only safe
+  blanket default. Pass `eager: true` to mint-and-emit for every eligible HTML
+  response (see the caveat in the middleware docs).
+- **Never clobbers**: it defers to any CSP a route already set.
+- **HTML only**, and inert unless `enable_csp_with_nonce!` is on.
+- `development_mode:` accepts a per-request callable, e.g.
+  `->(env) { ENV['RACK_ENV'] == 'development' }`, to switch directive sets.
+
+To set a policy explicitly from a handler instead, use the one emission helper —
+it routes through the same apply core:
+
+```ruby
+res['content-type'] = 'text/html; charset=utf-8'
+result = res.apply_csp(req.csp_nonce)          # mode: :override by default
+result.applied?        # => true
+result.skip_reason     # => nil (or :disabled / :blank_nonce / :non_html / :existing_csp)
+```
+
+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.
+
+> [!NOTE]
+> `res.send_csp_headers(content_type, nonce)` is **deprecated** in favour of
+> `res.apply_csp` / `enable_csp_emission!`. It remains as a thin shim over the
+> same apply core (so its old quirks — a broken `'nonce-'` on a blank nonce, a
+> CSP on non-HTML responses, a `warn` to stderr — are now fixed) and logs a
+> one-time deprecation notice.
+
 ### CSP Violation Reporting
 
 Otto can both emit Content-Security-Policy headers and receive the violation

data/lib/otto/core/middleware_stack.rb

@@ -275,6 +275,7 @@ class Otto
           Otto::Security::Middleware::RateLimitMiddleware,
           Otto::Security::Middleware::IPPrivacyMiddleware,
           Otto::Security::CSP::ReportMiddleware,
+          Otto::Security::CSP::EmitMiddleware,
         ].include?(middleware_class)
       end
     end

data/lib/otto/env_keys.rb

@@ -61,6 +61,16 @@ class Otto
     # Used by: All security middleware (CSRF, Headers, Validation)
     SECURITY_CONFIG = 'otto.security_config'
 
+    # Per-request CSP nonce, minted lazily on first access and memoized here.
+    # Type: String (base64)
+    # Set by: Otto::Security::CSP.nonce / Otto::Request#csp_nonce (first touch)
+    # Used by: views (stamping script/style nonces) and
+    #   Otto::Security::CSP::EmitMiddleware (emit-if-consumed)
+    # Note: this is the DEFAULT key. Apps with an existing convention can point
+    #   the accessor at their own key via Otto::Security::Config#csp_nonce_key
+    #   (e.g. 'onetime.nonce'), so the header and views still share one value.
+    NONCE = 'otto.nonce'
+
     # Whether the request arrived via a trusted proxy.
     # Type: Boolean
     # Set by: IPPrivacyMiddleware (every request, evaluated on the original

data/lib/otto/request.rb

@@ -24,6 +24,20 @@ class Otto
       env['HTTP_USER_AGENT']
     end
 
+    # Framework-owned, request-scoped CSP nonce, generated lazily on first
+    # access and memoized into the request env. Views call this to stamp
+    # `nonce="…"` onto their inline `<script>`/`<link>` tags; the same value is
+    # what {Otto::Security::CSP::EmitMiddleware} writes into the `script-src
+    # 'nonce-…'` header — so the header and the views agree structurally, not by
+    # convention. An untouched request generates nothing.
+    #
+    # The env key is configurable via {Otto::Security::Config#csp_nonce_key}.
+    #
+    # @return [String] this request's nonce (base64)
+    def csp_nonce
+      Otto::Security::CSP.nonce(env)
+    end
+
     # Canonical client IP for the request.
     #
     # Prefers env['otto.client_ip'] — the value resolved once, early, by

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
@@ -47,7 +48,9 @@ class Otto
       # 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.
-      CSP_REPORTING_GROUP = 'otto-csp'
+      # 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
@@ -67,7 +70,7 @@ class Otto
       attr_reader :csrf_protection,  :csrf_header_key,
                   :trusted_proxies, :require_secure_cookies,
                   :security_headers,
-                  :csp_nonce_enabled, :debug_csp, :mcp_auth,
+                  :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
 
@@ -92,6 +95,7 @@ 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
@@ -393,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
@@ -506,16 +526,20 @@ class Otto
 
       # Generate a CSP policy string with the provided nonce
       #
+      # Thin facade over {Otto::Security::CSP::Policy.nonce_policy}; the directive
+      # sets and report-uri/report-to assembly live there now. Output is
+      # byte-identical to Otto's historical policy.
+      #
       # @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)
-        report_uri_directive = csp_report_directive
-        report_to_directive  = csp_report_to_directive
-        directives += ["#{report_uri_directive};"] if report_uri_directive
-        directives += ["#{report_to_directive};"] if report_to_directive
-        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
@@ -888,28 +912,6 @@ class Otto
         existing
       end
 
-      # The `report-uri` directive to append to emitted policies, or nil when no
-      # report URI is configured. No trailing semicolon (callers add their own
-      # separator to match each policy style).
-      #
-      # @return [String, nil]
-      def csp_report_directive
-        return nil if @csp_report_uri.nil? || @csp_report_uri.empty?
-
-        "report-uri #{@csp_report_uri}"
-      end
-
-      # The `report-to` directive (modern Reporting API) to append to emitted
-      # policies, or nil when no reporting endpoint URL is configured. Its group
-      # name matches the Reporting-Endpoints header. No trailing semicolon.
-      #
-      # @return [String, nil]
-      def csp_report_to_directive
-        return nil if @csp_report_to_url.nil? || @csp_report_to_url.empty?
-
-        "report-to #{CSP_REPORTING_GROUP}"
-      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"`.
@@ -920,62 +922,18 @@ class Otto
       end
 
       # Build the stored static-CSP header value: the base policy plus the
-      # optional report-uri and report-to directives. Byte-identical to the bare
-      # policy when no reporting is configured, so existing static-CSP output is
-      # unchanged.
+      # 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)
-        [policy, csp_report_directive, csp_report_to_directive].compact.join('; ')
-      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
-        ]
+        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,22 @@ 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

data/lib/otto/security/core.rb

@@ -135,6 +135,38 @@ 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:

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

@@ -0,0 +1,91 @@
+# lib/otto/security/csp/emit_middleware.rb
+#
+# frozen_string_literal: true
+
+require_relative 'writer'
+require_relative 'nonce'
+
+class Otto
+  module Security
+    module CSP
+      # Rack middleware that emits a nonce-based Content-Security-Policy on the
+      # way out — the EMITTING sibling of {Otto::Security::CSP::ReportMiddleware}.
+      #
+      # It is a passive BACKSTOP: it runs the CSP through {Otto::Security::CSP::Writer}
+      # in `:backstop` mode, so it fills the gap for responses that would
+      # otherwise ship without a CSP but NEVER clobbers one a route or another
+      # layer already set. All the emission invariants (enabled / HTML-only /
+      # nonce-present / don't-clobber / lowercase key) are the Writer's, so this
+      # middleware carries none of that guard logic itself.
+      #
+      # DEFAULT: emit-if-consumed. It emits only when the request actually
+      # consumed a nonce (a view called {Otto::Request#csp_nonce}, memoizing it
+      # into the env). This is the safe default: a nonce-only `script-src` on an
+      # HTML page whose templates never stamped that nonce would block EVERY
+      # script on the page. "CSP responses whose request consumed a nonce" is
+      # sound; "CSP all HTML responses" is not.
+      #
+      # EAGER (opt-in): with `eager: true` it MINTS a nonce for every otherwise
+      # eligible response, even one that never touched it. Only safe when the app
+      # either uses no nonce-gated inline scripts or stamps the nonce another way;
+      # otherwise it reintroduces the blocked-script hazard above.
+      #
+      # INERT unless {Otto::Security::Config#csp_nonce_enabled?}. When nonce-CSP
+      # is off it is a transparent pass-through (and never mints a nonce).
+      class EmitMiddleware
+        # @param app [#call] the inner Rack app
+        # @param config [Otto::Security::Config, nil] security config (the
+        #   middleware stack injects this); a nil config yields an inert instance
+        # @param eager [Boolean] mint-and-emit for every eligible response rather
+        #   than only emit-if-consumed
+        # @param development_mode [Boolean, #call, nil] whether to emit the
+        #   development directive set. A callable is invoked per request with the
+        #   env (e.g. `->(env) { OT.conf.dig('development', 'enabled') }`); a plain
+        #   value is used as-is; nil means production.
+        def initialize(app, config = nil, eager: false, development_mode: nil)
+          @app              = app
+          @config           = config || Otto::Security::Config.new
+          @eager            = eager
+          @development_mode = development_mode
+        end
+
+        def call(env)
+          status, headers, body = @app.call(env)
+          apply_backstop(env, headers) if @config.csp_nonce_enabled?
+          [status, headers, body]
+        end
+
+        private
+
+        # Resolve the nonce per the eager/consumed policy and, when present, let
+        # the Writer apply the backstop CSP. The Writer re-checks every guard, so
+        # a non-HTML or already-CSP'd response is left untouched.
+        def apply_backstop(env, headers)
+          nonce = resolve_nonce(env)
+          return if nonce.nil? || nonce.empty?
+
+          Otto::Security::CSP::Writer.apply(
+            headers, nonce,
+            config: @config, mode: :backstop, development_mode: development_mode?(env)
+          )
+        end
+
+        # Eager mode mints a nonce for this request; the default emits only a
+        # nonce the request already consumed (memoized in env by a view).
+        def resolve_nonce(env)
+          return Otto::Security::CSP.nonce(env) if @eager
+          return Otto::Security::CSP.nonce(env) if Otto::Security::CSP.nonce?(env)
+
+          nil
+        end
+
+        def development_mode?(env)
+          mode = @development_mode
+          return mode.call(env) if mode.respond_to?(:call)
+
+          !!mode
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# lib/otto/security/csp/nonce.rb
+#
+# frozen_string_literal: true
+
+require 'securerandom'
+
+class Otto
+  module Security
+    # Content-Security-Policy support. The framework-owned lazy nonce accessor
+    # lives directly on this module ({.nonce} / {.nonce?}), beside the {Policy}
+    # builder, the {Writer} apply core, the {Parser}, and the report/emit
+    # middlewares.
+    module CSP
+      # Default Rack env key the per-request nonce is memoized under. Registered
+      # as documentation in {Otto::EnvKeys::NONCE}; per that module's convention
+      # the string literal (not the constant) is what the codebase passes around,
+      # so this DEFAULT_NONCE_KEY exists for the CSP code's own use and the two
+      # are kept identical.
+      DEFAULT_NONCE_KEY = 'otto.nonce'
+
+      module_function
+
+      # Framework-owned, request-scoped, LAZY CSP nonce.
+      #
+      # Generates a fresh base64 nonce on first access and memoizes it into the
+      # request env under the resolved key, so every later reader observes ONE
+      # value: the views that stamp `nonce="…"` onto `<script>`/`<link>` tags and
+      # the {Otto::Security::CSP::EmitMiddleware} that writes the `script-src
+      # 'nonce-…'` header both read it here. The header's nonce matching the
+      # views' nonce is therefore a STRUCTURAL property, not a convention each app
+      # re-implements (Rails' `request.content_security_policy_nonce` model).
+      #
+      # An untouched request never generates a nonce and pays nothing — which is
+      # also why the emit-if-consumed middleware is safe: it only emits a
+      # nonce-only policy for a request whose views actually consumed the nonce.
+      #
+      # A value already present under the key (e.g. an app that still mints its
+      # own under the same convention) is honored, not overwritten.
+      #
+      # @param env [Hash] the Rack request env (mutated: the nonce is memoized in)
+      # @param key [String, nil] override the env key; nil resolves it from the
+      #   security config's {Otto::Security::Config#csp_nonce_key} (or the default)
+      # @return [String] the request's nonce
+      def nonce(env, key: nil)
+        resolved = key || nonce_key(env)
+        existing = env[resolved]
+        return existing if existing && !existing.empty?
+
+        env[resolved] = SecureRandom.base64(16)
+      end
+
+      # Whether a nonce was already minted for this request, WITHOUT minting one.
+      # This is the emit-if-consumed predicate.
+      #
+      # @param env [Hash]
+      # @param key [String, nil] see {.nonce}
+      # @return [Boolean]
+      def nonce?(env, key: nil)
+        value = env[key || nonce_key(env)]
+        !value.nil? && !value.empty?
+      end
+
+      # The env key the nonce lives under: the app's configured convention
+      # ({Otto::Security::Config#csp_nonce_key}) when a security config is present
+      # on the env, else the framework default. Lets an app with an existing
+      # convention (e.g. `onetime.nonce`) adopt the accessor without renaming its
+      # env key.
+      #
+      # @param env [Hash]
+      # @return [String]
+      def nonce_key(env)
+        config = env['otto.security_config']
+        configured = config.csp_nonce_key if config.respond_to?(:csp_nonce_key)
+        configured && !configured.empty? ? configured : DEFAULT_NONCE_KEY
+      end
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+# lib/otto/security/csp/policy.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module CSP
+      # Assembles Content-Security-Policy strings from Otto's directive sets and
+      # the optional reporting directives.
+      #
+      # This is the policy-BUILDING half of Otto's CSP support, extracted from
+      # {Otto::Security::Config} so the domain (directive sets, report-uri /
+      # report-to assembly) lives beside the parser and the middlewares under
+      # {Otto::Security::CSP}. {Otto::Security::Config} keeps thin delegating
+      # facades ({Otto::Security::Config#generate_nonce_csp} and its static
+      # counterpart), so callers and output are unchanged — the assembly logic
+      # simply has a home of its own now.
+      #
+      # All methods are pure functions of their arguments (the report URI/URL are
+      # passed in, not read from global state), so the same policy string can be
+      # produced from any surface without a Config in hand.
+      module Policy
+        module_function
+
+        # 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.
+        # {Otto::Security::Config::CSP_REPORTING_GROUP} aliases this so the two
+        # can never drift.
+        REPORTING_GROUP = 'otto-csp'
+
+        # Build the per-request nonce CSP policy string.
+        #
+        # Byte-identical to Otto's historical {Otto::Security::Config#generate_nonce_csp}
+        # output: the base directive set (development or production) followed by
+        # the optional `report-uri` and `report-to` directives, each terminated
+        # with `;` and joined by a single space.
+        #
+        # @param nonce [String] nonce value injected into `script-src`
+        # @param development_mode [Boolean] use the development directive set
+        # @param report_uri [String, nil] path for the `report-uri` directive
+        #   (omitted when nil/empty)
+        # @param report_to_url [String, nil] absolute URL configured for the
+        #   modern Reporting API; its presence (not its value) toggles the
+        #   `report-to <group>` directive (omitted when nil/empty)
+        # @return [String] complete CSP policy string
+        def nonce_policy(nonce, development_mode: false, report_uri: nil, report_to_url: nil)
+          directives = development_mode ? development_directives(nonce) : production_directives(nonce)
+          uri_directive = report_uri_directive(report_uri)
+          to_directive  = report_to_directive(report_to_url)
+          directives += ["#{uri_directive};"] if uri_directive
+          directives += ["#{to_directive};"] if to_directive
+          directives.join(' ')
+        end
+
+        # Build a static CSP header value: a base policy plus the optional
+        # reporting directives, joined `'; '`. Byte-identical to the bare policy
+        # when no reporting is configured.
+        #
+        # @param base [String] the base policy (e.g. from {Otto::Security::Config#enable_csp!})
+        # @param report_uri [String, nil] path for the `report-uri` directive
+        # @param report_to_url [String, nil] absolute URL toggling `report-to`
+        # @return [String]
+        def static_policy(base, report_uri: nil, report_to_url: nil)
+          [base, report_uri_directive(report_uri), report_to_directive(report_to_url)].compact.join('; ')
+        end
+
+        # The `report-uri` directive, or nil when no report URI is configured.
+        # No trailing semicolon (callers add their own separator).
+        #
+        # @param uri [String, nil]
+        # @return [String, nil]
+        def report_uri_directive(uri)
+          return nil if uri.nil? || uri.empty?
+
+          "report-uri #{uri}"
+        end
+
+        # The `report-to` directive (modern Reporting API), or nil when no
+        # reporting endpoint URL is configured. Its group name matches the
+        # Reporting-Endpoints header. No trailing semicolon.
+        #
+        # @param url [String, nil]
+        # @return [String, nil]
+        def report_to_directive(url)
+          return nil if url.nil? || url.empty?
+
+          "report-to #{REPORTING_GROUP}"
+        end
+
+        # 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.
+        #
+        # @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
+            "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
+
+        # CSP directives for the production environment.
+        #
+        # Production mode is more restrictive, only allowing HTTPS connections
+        # and nonce-only scripts for enhanced XSS protection.
+        #
+        # @param nonce [String] nonce value injected into `script-src`
+        # @return [Array<String>] directive strings, each terminated with `;`
+        def production_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
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+# lib/otto/security/csp/writer.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module CSP
+      # The single structural apply core for nonce-based Content-Security-Policy
+      # emission. Every in-framework surface that writes a nonce CSP onto a
+      # response — {Otto::Response#apply_csp}, {Otto::Security::CSP::EmitMiddleware},
+      # and the deprecated {Otto::Response#send_csp_headers} shim — routes through
+      # {.apply}, so the emission invariants are properties of ONE method rather
+      # than guard logic re-implemented (and re-reviewed) at each surface:
+      #
+      # - **Enabled only.** No header unless the security config has nonce-CSP on.
+      # - **Nonce present.** A nil/empty nonce never produces a broken
+      #   `script-src 'nonce-'` policy; it skips.
+      # - **HTML only.** Non-HTML responses (JSON, redirects, static assets) are
+      #   left untouched.
+      # - **Passive layers never clobber.** In `:backstop` mode an existing CSP is
+      #   deferred to; only an explicit `:override` replaces one.
+      #
+      # Writes are **in-place and key-scoped**: {.apply} finds any case-variant of
+      # the CSP key (Rack 3 mandates lowercase response-header keys, but a
+      # canonical-/mixed-cased key from a downstream layer is a spec violation this
+      # corrects in place), deletes it, and writes the lowercase key into the
+      # CALLER'S headers hash. There is no wrapping, no copy, and no
+      # "callers-must-use-the-return-value" contract — the `[status, headers,
+      # body]` tuple never needs reassignment. A frozen headers hash therefore
+      # fails loud (FrozenError) on write, surfacing the downstream SPEC violation
+      # rather than silently dropping the policy.
+      #
+      # The return is a {Result}, not the headers: `result.applied?`,
+      # `result.policy`, `result.skip_reason` give uniform observability across
+      # every surface (and drive the optional debug log) without any cleverness to
+      # detect "did anything happen".
+      class Writer
+        # Canonical (lowercase, per Rack 3 SPEC) response-header keys.
+        CSP_HEADER = 'content-security-policy'
+        CONTENT_TYPE_HEADER = 'content-type'
+
+        # 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
+        # fills the gap, never clobbers).
+        MODES = %i[override backstop].freeze
+
+        # Outcome of an {Writer.apply} call.
+        #
+        # `applied?` is the single source of truth for "did a header get
+        # 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.
+        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
+
+          def initialize(applied:, mode:, policy: nil, skip_reason: nil)
+            @applied = applied
+            @mode = mode
+            @policy = policy
+            @skip_reason = skip_reason
+          end
+
+          # Build an "applied" result for a written policy.
+          def self.applied(policy, mode:)
+            new(applied: true, mode: mode, policy: policy)
+          end
+
+          # Build a "skipped" result. `policy` carries the pre-existing policy for
+          # the `:existing_csp` case (observability), nil otherwise.
+          def self.skipped(reason, mode:, policy: nil)
+            new(applied: false, mode: mode, skip_reason: reason, policy: policy)
+          end
+
+          # @return [Boolean] true when a CSP header was written
+          def applied?
+            @applied
+          end
+
+          # @return [Boolean] true when no header was written
+          def skipped?
+            !@applied
+          end
+        end
+
+        # Apply a nonce-based CSP to the caller's response headers, in place.
+        #
+        # @param headers [Hash] the Rack response headers hash, mutated in place.
+        #   MUST be mutable (Rack 3 SPEC); a frozen hash raises FrozenError.
+        # @param nonce [String, nil] the per-request nonce.
+        # @param config [Otto::Security::Config, nil] source of the enabled gate
+        #   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.
+        # @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)
+          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)
+          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)
+          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)
+
+          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)
+          write_csp(headers, policy)
+          Result.applied(policy, mode: mode)
+        end
+        private_class_method :evaluate
+
+        # 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
+        # deleting so we never mutate the hash while iterating it.
+        def self.write_csp(headers, policy)
+          variant_keys = headers.keys.select { |key| key != CSP_HEADER && key.to_s.casecmp?(CSP_HEADER) }
+          variant_keys.each { |key| headers.delete(key) }
+          headers[CSP_HEADER] = policy
+        end
+        private_class_method :write_csp
+
+        # Whether the config has nonce-CSP enabled (nil/foreign configs are "off").
+        def self.enabled?(config)
+          config.respond_to?(:csp_nonce_enabled?) && config.csp_nonce_enabled?
+        end
+        private_class_method :enabled?
+
+        # Whether the response is HTML, by the leading media type of its
+        # Content-Type (case-insensitive; charset and other parameters ignored).
+        # The media type must be exactly `text/html` — matched on the token
+        # before any `;`, so `text/html; charset=utf-8` is HTML but `text/html5`
+        # or `text/html-foo` is not. Absent Content-Type is treated as non-HTML:
+        # a nonce-only CSP on a response the templates never stamped would block
+        # every script.
+        def self.html_response?(headers)
+          content_type = lookup(headers, CONTENT_TYPE_HEADER)
+          return false if content_type.nil?
+
+          media_type = content_type.to_s.split(';', 2).first.to_s.strip.downcase
+          media_type == 'text/html'
+        end
+        private_class_method :html_response?
+
+        # The existing CSP value (any case-variant key), or nil.
+        def self.existing_csp(headers)
+          lookup(headers, CSP_HEADER)
+        end
+        private_class_method :existing_csp
+
+        # Case-insensitive header read: fast path for the canonical lowercase key,
+        # else a scan for a case-variant.
+        def self.lookup(headers, name)
+          return headers[name] if headers.key?(name)
+
+          headers.each { |key, value| return value if key.to_s.casecmp?(name) }
+          nil
+        end
+        private_class_method :lookup
+
+        def self.blank?(value)
+          value.nil? || value.to_s.empty?
+        end
+        private_class_method :blank?
+
+        # 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.
+        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})"
+          Otto.logger.debug("[CSP] #{detail}")
+        end
+        private_class_method :log_debug
+      end
+    end
+  end
+end

data/lib/otto/security/csp.rb

@@ -3,17 +3,29 @@
 # frozen_string_literal: true
 
 #
-# Index file for Content-Security-Policy violation reporting components.
+# Index file for Content-Security-Policy components — both halves of Otto's CSP
+# support live under Otto::Security::CSP.
 #
-# Otto emits CSP headers via Otto::Security::Config (static #enable_csp! and
-# nonce-based #generate_nonce_csp / Otto::Response#send_csp_headers). This
-# module adds the receiving half: a turnkey violation-report endpoint plus a
-# callback API, so an application can collect CSP reports with a few lines of
-# config instead of hand-rolling a parser, size cap, and CSRF exemption.
+# EMISSION (delano/otto#180):
+# - Policy       — builds the policy string (directive sets, report-uri/report-to).
+# - Nonce        — the framework-owned lazy nonce (Otto::Security::CSP.nonce /
+#                  Otto::Request#csp_nonce), memoized in env['otto.nonce'].
+# - Writer       — the single structural apply core (in-place, key-scoped writes,
+#                  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.
+# - 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!.
 #
-# See Otto::Security::Core#enable_csp_reporting! for the primary entry point and
-# delano/otto#174 for the design.
+# RECEPTION (delano/otto#174):
+# - Report, Parser, ReportMiddleware — a turnkey violation-report endpoint plus a
+#   callback API. See Otto::Security::Core#enable_csp_reporting!.
 
+require_relative 'csp/policy'
+require_relative 'csp/nonce'
+require_relative 'csp/writer'
 require_relative 'csp/report'
 require_relative 'csp/parser'
 require_relative 'csp/report_middleware'
+require_relative 'csp/emit_middleware'

data/lib/otto/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -294,9 +294,13 @@ files:
 - lib/otto/security/constant_resolver.rb
 - lib/otto/security/core.rb
 - lib/otto/security/csp.rb
+- lib/otto/security/csp/emit_middleware.rb
+- lib/otto/security/csp/nonce.rb
 - lib/otto/security/csp/parser.rb
+- lib/otto/security/csp/policy.rb
 - lib/otto/security/csp/report.rb
 - lib/otto/security/csp/report_middleware.rb
+- lib/otto/security/csp/writer.rb
 - lib/otto/security/csrf.rb
 - lib/otto/security/middleware/csrf_middleware.rb
 - lib/otto/security/middleware/ip_privacy_middleware.rb