otto 2.4.0 → 2.6.0

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,9 +70,10 @@ 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
+                  :csp_report_uri, :csp_report_to_url, :csp_violation_callback,
+                  :csp_directive_overrides
 
       # Initialize security configuration with safe defaults
       #
@@ -92,10 +96,13 @@ 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
+        @csp_directive_overrides = {}
+        @csp_script_src_override_warned = false
         @rate_limiting_config   = { custom_rules: {} }
         @ip_privacy_config      = Otto::Privacy::Config.new
 
@@ -363,19 +370,85 @@ class Otto
       # Unlike enable_csp!, this doesn't set a static policy but enables the response
       # helper to generate CSP headers with nonces on a per-request basis.
       #
+      # Per-directive overrides may be supplied to customize the emitted nonce
+      # policy without vendoring the gem. They merge into Otto's base directive
+      # sets ({Otto::Security::CSP::Policy.development_directives} /
+      # {Otto::Security::CSP::Policy.production_directives}): a matching directive
+      # is replaced in place, a new directive is appended, and a nil/false value
+      # removes a directive. See {#csp_directive_overrides=} for the accepted
+      # shape.
+      #
       # @param debug [Boolean] Enable debug logging for CSP headers (default: false)
+      # @param directives [Hash] per-directive overrides merged into the base set
       # @return [void]
       # @raise [FrozenError] if configuration is frozen
       #
       # @example
       #   config.enable_csp_with_nonce!(debug: true)
-      def enable_csp_with_nonce!(debug: false)
+      #
+      # @example Restore data: workers (blob: is the default worker-src token)
+      #   config.enable_csp_with_nonce!(directives: { 'worker-src' => "'self' data: blob:" })
+      def enable_csp_with_nonce!(debug: false, directives: {})
         ensure_not_frozen!
 
+        # Apply overrides before toggling state so a bad +directives+ argument
+        # raises without leaving the config half-updated (nonce enabled but
+        # overrides not merged).
+        merge_csp_directives(directives) unless directives.nil? || directives.empty?
         @csp_nonce_enabled = true
         @debug_csp         = debug
       end
 
+      # Replace the per-directive overrides applied to the nonce CSP policy.
+      #
+      # Overrides merge into Otto's base directive sets when
+      # {#generate_nonce_csp} builds the policy, so a consuming app can adjust
+      # ANY directive rather than only `report-uri`/`report-to`. Keys are
+      # directive names (String or Symbol, matched case-insensitively); values
+      # are the source list as a String (`"'self' blob:"`) or Array
+      # (`%w['self' blob:]`), or nil/false to REMOVE the directive.
+      #
+      # Keys are normalized on store (lowercased, hyphenated) via
+      # {Otto::Security::CSP::Policy.normalize_overrides}, so the stored hash
+      # never accumulates logically-identical entries under different key styles
+      # (`'WORKER-SRC'` and `:worker_src` both read back as `'worker-src'`).
+      #
+      # @note Overriding `script-src` while nonce mode is enabled disables
+      #   nonce-based script protection: the per-request nonce cannot be
+      #   included in a static override, so it is stripped from the emitted
+      #   header. A warning is logged when a `script-src` override is stored.
+      #   See {Otto::Security::CSP::Policy.merge_directives}.
+      #
+      # @param overrides [Hash] directive name => source list / nil
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      #
+      # @example
+      #   config.csp_directive_overrides = { 'worker-src' => "'self' data: blob:" }
+      def csp_directive_overrides=(overrides)
+        ensure_not_frozen!
+
+        normalized = Otto::Security::CSP::Policy.normalize_overrides(overrides || {})
+        warn_if_script_src_overridden(normalized)
+        @csp_directive_overrides = normalized
+      end
+
+      # Merge additional per-directive overrides into the existing set, leaving
+      # untouched any directive not named in +overrides+ (last write wins for a
+      # repeated directive). Use this to accumulate overrides incrementally;
+      # use {#csp_directive_overrides=} to replace them wholesale.
+      #
+      # @param overrides [Hash] directive name => source list / nil
+      # @return [void]
+      # @raise [FrozenError] if configuration is frozen
+      def merge_csp_directives(overrides)
+        ensure_not_frozen!
+
+        normalized = Otto::Security::CSP::Policy.normalize_overrides(overrides || {})
+        warn_if_script_src_overridden(normalized)
+        @csp_directive_overrides = @csp_directive_overrides.merge(normalized)
+      end
+
       # Disable CSP nonce support
       #
       # @return [void]
@@ -393,6 +466,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 +595,23 @@ 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. Any configured
+      # {#csp_directive_overrides} are merged into the base directive set. Output
+      # is byte-identical to Otto's historical policy when no overrides or
+      # reporting are configured.
+      #
       # @param nonce [String] The nonce value to include in the CSP
       # @param development_mode [Boolean] Whether to use development-friendly directives
       # @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,
+          directive_overrides: @csp_directive_overrides
+        )
       end
 
       # Enable X-Frame-Options header to prevent clickjacking
@@ -795,6 +891,29 @@ class Otto
         MSG
       end
 
+      # Warn once per config instance when a `script-src` override is stored for
+      # the nonce CSP policy. The per-request nonce is generated at response time
+      # and therefore cannot be present in a static override, so replacing (or
+      # removing) `script-src` necessarily strips the nonce from the emitted
+      # header — the browser then accepts any inline script the page carries the
+      # nonce attribute on, voiding nonce-based protection. Overriding any other
+      # directive (e.g. `worker-src`) is unaffected and stays silent.
+      #
+      # @param normalized [Hash] normalized (lowercased/hyphenated) overrides
+      # @return [void]
+      def warn_if_script_src_overridden(normalized)
+        return unless normalized.key?('script-src')
+        return if @csp_script_src_override_warned
+
+        @csp_script_src_override_warned = true
+        Otto.structured_log(:warn, <<~MSG.gsub(/\s+/, ' ').strip, directive: 'script-src')
+          [Otto::CSP] A script-src override was configured while nonce mode is in
+          use. The per-request nonce cannot be included in a static override, so
+          nonce-based script protection is disabled for this policy. Remove the
+          script-src override to keep nonce enforcement.
+        MSG
+      end
+
       # Freeze-time backstop: refuse to finalize a production configuration that
       # enables CSRF with a generated (non-configured) secret. Mirrors
       # #validate_trusted_proxy_config! so the failure surfaces at boot, before
@@ -888,28 +1007,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 +1017,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