otto 2.3.1 → 2.5.0

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/parser.rb

@@ -0,0 +1,120 @@
+# lib/otto/security/csp/parser.rb
+#
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'report'
+
+class Otto
+  module Security
+    module CSP
+      # Parses inbound Content-Security-Policy violation report bodies into a
+      # list of normalized {Otto::Security::CSP::Report} objects.
+      #
+      # Handles BOTH standardized wire formats:
+      #
+      # - Legacy `application/csp-report` — a single JSON object
+      #   `{"csp-report": { ... }}`.
+      # - Reporting API `application/reports+json` — a JSON ARRAY of
+      #   `{"type": "csp-violation", "body": { ... }}` entries (a single
+      #   un-wrapped object is tolerated too).
+      #
+      # The parser keys off the JSON SHAPE rather than trusting the declared
+      # `Content-Type`, because browsers and intermediaries are inconsistent
+      # about the header. The `content_type` argument is accepted for future use
+      # and symmetry with the middleware but is not currently required to
+      # disambiguate.
+      #
+      # It is intentionally TOTAL: malformed JSON, an unexpected top-level type,
+      # or entries that are not CSP violations yield an empty array rather than
+      # raising. A violation-report receiver must never fail on hostile input.
+      module Parser
+        module_function
+
+        # Parse a raw report body into normalized reports.
+        #
+        # @param body [String, nil] the raw request body (JSON).
+        # @param content_type [String, nil] the request Content-Type (hint only).
+        # @return [Array<Otto::Security::CSP::Report>] zero or more normalized
+        #   reports. Empty when the body is nil/blank/malformed or contains no
+        #   recognizable CSP violations.
+        def parse(body, content_type = nil)
+          return [] if body.nil? || body.empty?
+
+          data = safe_json_parse(body)
+          return [] if data.nil?
+
+          extract_raw_reports(data, content_type).filter_map do |raw|
+            Report.from_raw(raw)
+          end
+        end
+
+        # Parse JSON, swallowing the errors a hostile/garbled body can throw.
+        #
+        # @param body [String]
+        # @return [Object, nil] the parsed structure, or nil on any parse error.
+        def safe_json_parse(body)
+          JSON.parse(body)
+        rescue JSON::ParserError, EncodingError
+          nil
+        end
+
+        # Pull the per-violation field hashes out of either wire format.
+        #
+        # @param data [Object] the parsed JSON structure.
+        # @param _content_type [String, nil] unused (shape drives extraction).
+        # @return [Array<Hash>] raw, un-normalized per-violation field hashes.
+        def extract_raw_reports(data, _content_type = nil)
+          case data
+          when Array
+            extract_from_reporting_api(data)
+          when Hash
+            extract_from_object(data)
+          else
+            []
+          end
+        end
+
+        # Reporting API batch: an array of report envelopes. Keep entries that
+        # are (or are untyped but shaped like) CSP violations and carry a body.
+        #
+        # @param entries [Array]
+        # @return [Array<Hash>]
+        def extract_from_reporting_api(entries)
+          entries.filter_map do |entry|
+            next unless entry.is_a?(Hash)
+
+            body = entry['body']
+            next unless body.is_a?(Hash)
+
+            type = entry['type']
+            # Accept entries explicitly typed csp-violation, or untyped bodies.
+            # Skip other report types (deprecation, intervention, ...).
+            next unless type.nil? || type == 'csp-violation'
+
+            body
+          end
+        end
+
+        # A single top-level object in either the legacy `{"csp-report": {...}}`
+        # envelope or a lone Reporting API `{"type":..., "body": {...}}` object.
+        #
+        # @param data [Hash]
+        # @return [Array<Hash>]
+        def extract_from_object(data)
+          if data['csp-report'].is_a?(Hash)
+            [data['csp-report']]
+          elsif data['body'].is_a?(Hash) && (data['type'].nil? || data['type'] == 'csp-violation')
+            # Mirror extract_from_reporting_api: accept a lone csp-violation (or
+            # untyped) envelope, but skip other single-object report types
+            # (deprecation, intervention, ...).
+            [data['body']]
+          else
+            []
+          end
+        end
+      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/report.rb

@@ -0,0 +1,147 @@
+# lib/otto/security/csp/report.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module CSP
+      # A single, normalized Content-Security-Policy violation report.
+      #
+      # Browsers emit violation reports in two different wire formats with two
+      # different field-naming conventions:
+      #
+      # - Legacy `application/csp-report` (CSP Level 2/3): a JSON object under a
+      #   `"csp-report"` key using kebab-case fields (`blocked-uri`,
+      #   `violated-directive`, `line-number`, ...).
+      # - Reporting API `application/reports+json` (Reporting API v1): a JSON
+      #   ARRAY of `{"type": "csp-violation", "body": {...}}` entries whose body
+      #   uses camelCase fields (`blockedURL`, `effectiveDirective`,
+      #   `lineNumber`, ...).
+      #
+      # This Struct is the single normalized shape both formats collapse into, so
+      # application callbacks registered via
+      # {Otto::Security::Config#on_csp_violation} never have to care which format
+      # the browser used. Build instances with {.from_raw}; use {#to_h} to
+      # serialize.
+      #
+      # SECURITY NOTE: the URL-ish fields (`document_uri`, `blocked_uri`,
+      # `referrer`, `source_file`) reflect the page the browser was on and the
+      # resource it tried to load. In some applications these can carry sensitive
+      # path/query data (tokens, secret links). Otto does NOT redact these — it
+      # normalizes and hands them to your callback verbatim. If your application
+      # logs or forwards reports, redact these fields in your callback per your
+      # own privacy policy before they reach a log sink.
+      #
+      # @example Reading fields in a callback
+      #   config.on_csp_violation do |report|
+      #     logger.warn("CSP violation: #{report.violated_directive} " \
+      #                 "blocked #{report.blocked_uri}")
+      #   end
+      Report = Struct.new(
+        :document_uri,
+        :referrer,
+        :blocked_uri,
+        :violated_directive,
+        :effective_directive,
+        :original_policy,
+        :disposition,
+        :source_file,
+        :status_code,
+        :script_sample,
+        :line_number,
+        :column_number,
+        keyword_init: true
+      )
+
+      # Normalization behavior for {Report}. Reopened (rather than defined inside
+      # the Struct.new block) so the constants below are plain class constants,
+      # not constants-defined-in-a-block.
+      class Report
+        # Map from a normalized field to the list of raw keys (in priority order)
+        # that may hold its value across both wire formats. Legacy kebab-case
+        # keys are listed alongside their Reporting API camelCase equivalents.
+        FIELD_ALIASES = {
+                 document_uri:        %w[document-uri documentURL],
+                     referrer:        %w[referrer referer],
+                  blocked_uri:        %w[blocked-uri blockedURL],
+           violated_directive:        %w[violated-directive violatedDirective],
+          effective_directive:        %w[effective-directive effectiveDirective],
+              original_policy:        %w[original-policy originalPolicy],
+                  disposition:        %w[disposition],
+                  source_file:        %w[source-file sourceFile],
+                  status_code:        %w[status-code statusCode],
+                script_sample:        %w[script-sample sample],
+                  line_number:        %w[line-number lineNumber],
+                column_number:        %w[column-number columnNumber],
+        }.freeze
+
+        # Fields coerced to an Integer (or nil) rather than kept as whatever
+        # scalar the browser sent.
+        NUMERIC_FIELDS = %i[status_code line_number column_number].freeze
+
+        # Build a normalized Report from a single raw per-violation field hash.
+        #
+        # Accepts either wire format's field naming. `violated_directive` and
+        # `effective_directive` are cross-filled from each other when only one is
+        # present, because the two formats disagree on which they send (legacy
+        # favors `violated-directive`; the Reporting API favors
+        # `effectiveDirective`).
+        #
+        # @param raw [Hash] a single violation's field hash (already unwrapped
+        #   from any `csp-report`/`body` envelope by the parser).
+        # @return [Report, nil] the normalized report, or nil when `raw` is not a
+        #   usable Hash.
+        def self.from_raw(raw)
+          return nil unless raw.is_a?(Hash)
+
+          attrs = FIELD_ALIASES.each_with_object({}) do |(field, keys), acc|
+            value      = first_present(raw, keys)
+            acc[field] = NUMERIC_FIELDS.include?(field) ? coerce_int(value) : value
+          end
+
+          cross_fill_directives!(attrs)
+          new(**attrs)
+        end
+
+        # First non-nil value among the given keys, in priority order.
+        #
+        # @param raw [Hash]
+        # @param keys [Array<String>]
+        # @return [Object, nil]
+        def self.first_present(raw, keys)
+          keys.each do |key|
+            value = raw[key]
+            return value unless value.nil?
+          end
+          nil
+        end
+
+        # Coerce a raw value to an Integer, or nil when it is not a clean
+        # integer. Guards against a browser sending a huge or non-numeric value.
+        #
+        # @param value [Object]
+        # @return [Integer, nil]
+        def self.coerce_int(value)
+          return nil if value.nil?
+          return value if value.is_a?(Integer)
+
+          str = value.to_s
+          str.match?(/\A-?\d{1,18}\z/) ? str.to_i : nil
+        end
+
+        # Populate a missing directive from its sibling so callbacks can rely on
+        # both `violated_directive` and `effective_directive` being present when
+        # the browser sent at least one.
+        #
+        # @param attrs [Hash]
+        # @return [void]
+        def self.cross_fill_directives!(attrs)
+          attrs[:violated_directive]  ||= attrs[:effective_directive]
+          attrs[:effective_directive] ||= attrs[:violated_directive]
+        end
+
+        private_class_method :first_present, :coerce_int, :cross_fill_directives!
+      end
+    end
+  end
+end