otto 2.4.0 → 2.6.0

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

@@ -0,0 +1,273 @@
+# 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)
+        # @param directive_overrides [Hash, nil] per-directive overrides merged
+        #   into the base set before reporting directives are appended. See
+        #   {.merge_directives} for the accepted shape (replace a directive's
+        #   sources, add a new directive, or remove one with a nil/false value).
+        # @return [String] complete CSP policy string
+        def nonce_policy(nonce, development_mode: false, report_uri: nil, report_to_url: nil, directive_overrides: nil)
+          directives = development_mode ? development_directives(nonce) : production_directives(nonce)
+          directives = merge_directives(directives, directive_overrides)
+          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
+
+        # Merge per-directive overrides into a base directive set.
+        #
+        # This is the customization seam the hardcoded directive sets previously
+        # lacked: a consuming app can adjust ANY directive (e.g. re-allow
+        # `data:` workers via `worker-src 'self' data: blob:`) without
+        # vendoring the gem. Order is
+        # preserved — an override that matches an existing directive replaces it
+        # in place; an override for a directive not in the base set is appended
+        # after the base directives (before any reporting directives).
+        #
+        # Override values:
+        # - a String  → the directive's source list verbatim, e.g.
+        #   `'worker-src' => "'self' blob:"` yields `worker-src 'self' blob:;`
+        # - an Array   → sources joined with a single space, e.g.
+        #   `%w['self' blob:]`
+        # - `nil`/`false` → REMOVE the directive from the emitted policy
+        #
+        # Directive names are matched case-insensitively (CSP directive names are
+        # case-insensitive) and may be given as Strings or Symbols.
+        #
+        # @note The per-request nonce is embedded in `script-src` (production)
+        #   and cannot be reproduced in a static override, so replacing (or
+        #   removing) `script-src` strips the nonce from the emitted header and
+        #   DEFEATS nonce protection: the browser then accepts any inline script
+        #   the page carries the nonce attribute on. Overriding `script-src`
+        #   while nonce mode is enabled therefore disables nonce enforcement;
+        #   {Otto::Security::Config} logs a warning when such an override is
+        #   configured. Override other directives freely.
+        #
+        # @param directives [Array<String>] base directive strings, each `;`-terminated
+        # @param overrides [Hash, nil] directive name => source list / nil
+        # @return [Array<String>] merged directive strings, each `;`-terminated
+        # @raise [ArgumentError] if an override name or source token contains a
+        #   `;`, newline, or carriage return (see {.build_directive})
+        def merge_directives(directives, overrides)
+          return directives if overrides.nil? || overrides.empty?
+
+          normalized = normalize_overrides(overrides)
+          consumed   = {}
+
+          merged = directives.filter_map do |directive|
+            name = directive_name(directive)
+            next directive unless normalized.key?(name)
+
+            consumed[name] = true
+            build_directive(name, normalized[name])
+          end
+
+          normalized.each do |name, value|
+            next if consumed[name]
+
+            appended = build_directive(name, value)
+            merged << appended if appended
+          end
+
+          merged
+        end
+
+        # Normalize an overrides hash to lowercased, hyphenated String keys so
+        # lookups are case-insensitive and Symbol/String keys are
+        # interchangeable. Underscores map to hyphens (no CSP directive contains
+        # an underscore) so a Symbol key like `:worker_src` addresses the
+        # `worker-src` directive. Blank keys are dropped.
+        #
+        # @param overrides [Hash]
+        # @return [Hash{String=>Object}]
+        def normalize_overrides(overrides)
+          overrides.each_with_object({}) do |(key, value), acc|
+            name = key.to_s.strip.downcase.tr('_', '-')
+            acc[name] = value unless name.empty?
+          end
+        end
+
+        # The directive name (first token) of a `;`-terminated directive string,
+        # lowercased for case-insensitive matching.
+        #
+        # @param directive [String]
+        # @return [String]
+        def directive_name(directive)
+          directive.to_s.strip.delete_suffix(';').split(/\s+/, 2).first.to_s.downcase
+        end
+
+        # Build a single `;`-terminated directive string from a name and an
+        # override value, or nil when the value signals removal (nil/false).
+        #
+        # The directive name and each source token are validated against CSP's
+        # separator characters: a name or token containing `;` (which separates
+        # directives), a newline, or a carriage return raises {ArgumentError}
+        # rather than silently injecting extra directives — a real footgun when
+        # overrides come from env/config files. (The `false` removal sentinel is
+        # checked before {Array} so a bare `false` never becomes a `[false]`
+        # source list.)
+        #
+        # @param name [String] directive name
+        # @param value [String, Array, nil, false] source list, or nil/false to remove
+        # @return [String, nil]
+        # @raise [ArgumentError] if the name or a source token contains a `;`,
+        #   newline, or carriage return
+        def build_directive(name, value)
+          return nil if value.nil? || value == false
+
+          reject_injection!('directive name', name)
+          sources = Array(value).filter_map do |token|
+            str = token.to_s.strip
+            next if str.empty?
+
+            reject_injection!("source for #{name}", str)
+            str
+          end.join(' ')
+          sources.empty? ? "#{name};" : "#{name} #{sources};"
+        end
+
+        # Raise {ArgumentError} when +text+ carries a CSP directive/token
+        # separator (`;`, newline, or carriage return) that would let an
+        # override break out of its directive and inject another.
+        #
+        # @param label [String] what is being validated (for the error message)
+        # @param text [String]
+        # @return [void]
+        # @raise [ArgumentError] if +text+ contains `;`, `\n`, or `\r`
+        def reject_injection!(label, text)
+          return unless text.match?(/[;\r\n]/)
+
+          raise ArgumentError,
+                "invalid CSP #{label}: #{text.inspect} contains a ';', newline, or carriage return"
+        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' blob:;",
+          ]
+        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' blob:;",                # Allow Workers from same origin and blob: URLs
+          ]
+        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/security/csrf_enforcement_wrapper.rb

@@ -0,0 +1,68 @@
+# lib/otto/security/csrf_enforcement_wrapper.rb
+#
+# frozen_string_literal: true
+
+require_relative 'csrf_validation'
+
+class Otto
+  module Security
+    # Per-route CSRF enforcement, applied at the handler layer.
+    #
+    # CSRF enforcement lives here rather than in the global +CSRFMiddleware+
+    # because +csrf=exempt+ is a per-route option: it is only known once a
+    # route has been matched (the middleware runs *ahead* of route matching and
+    # never sees route options, so a global block could not honor exemption —
+    # issue #186). This wrapper runs after matching, alongside +RouteAuthWrapper+,
+    # where +route_definition.csrf_exempt?+ is directly available. It is composed
+    # by +HandlerFactory+ only when CSRF protection is enabled, and wraps outside
+    # +RouteAuthWrapper+ so a forged unsafe request is rejected before any
+    # authentication work runs.
+    #
+    # The global +CSRFMiddleware+ retains only token *injection* into HTML
+    # responses (a response-shaping concern that is method/content-type based,
+    # not route based, so it stays global).
+    class CSRFEnforcementWrapper
+      include CSRFValidation
+
+      attr_reader :wrapped_handler, :route_definition, :config
+
+      # @param wrapped_handler [#call] the handler to guard
+      # @param route_definition [Otto::RouteDefinition] the matched route
+      # @param config [Otto::Security::Config] security config exposing CSRF settings
+      def initialize(wrapped_handler, route_definition, config)
+        @wrapped_handler  = wrapped_handler
+        @route_definition = route_definition
+        @config           = config
+      end
+
+      # @param env [Hash] Rack environment
+      # @param extra_params [Hash] Additional parameters passed through to the handler
+      # @return [Array] Rack response tuple
+      def call(env, extra_params = {})
+        return wrapped_handler.call(env, extra_params) unless enforce?(env)
+
+        request = Otto::Request.new(env)
+        return wrapped_handler.call(env, extra_params) if valid_csrf_token?(request)
+
+        Otto.structured_log(:warn, 'CSRF validation failed',
+          Otto::LoggingHelpers.request_context(env).merge(
+            handler: route_definition.definition,
+            referrer: request.referrer
+          ))
+        csrf_error_response
+      end
+
+      private
+
+      # Whether this request must present a valid CSRF token. Only unsafe
+      # methods on a non-exempt route are enforced when protection is enabled.
+      def enforce?(env)
+        return false unless config&.csrf_enabled?
+        return false if safe_method?(env['REQUEST_METHOD'])
+        return false if route_definition.csrf_exempt?
+
+        true
+      end
+    end
+  end
+end

data/lib/otto/security/csrf_validation.rb

@@ -0,0 +1,75 @@
+# lib/otto/security/csrf_validation.rb
+#
+# frozen_string_literal: true
+
+require 'json'
+
+class Otto
+  module Security
+    # Shared CSRF token mechanics.
+    #
+    # Both the global +CSRFMiddleware+ (which injects tokens into HTML
+    # responses) and the per-route +CSRFEnforcementWrapper+ (which enforces
+    # tokens on unsafe requests, honoring +csrf=exempt+) mix this in so the
+    # two cannot drift on what counts as a safe method, where a token may be
+    # carried, or how a rejection is shaped. The including object must expose a
+    # +@config+ (an +Otto::Security::Config+).
+    module CSRFValidation
+      # HTTP methods that never mutate state and so are exempt from token
+      # validation (RFC 7231 safe methods plus TRACE).
+      SAFE_METHODS = %w[GET HEAD OPTIONS TRACE].freeze
+
+      # Static 403 body. Frozen once so a rejected request does not re-serialize
+      # the same JSON on every call.
+      CSRF_ERROR_BODY = {
+          error: 'CSRF token validation failed',
+        message: 'The request could not be authenticated. Please refresh the page and try again.',
+      }.to_json.freeze
+
+      private
+
+      def safe_method?(method)
+        SAFE_METHODS.include?(method.to_s.upcase)
+      end
+
+      def valid_csrf_token?(request)
+        token = extract_csrf_token(request)
+        # Reject nil / blank / whitespace-only tokens up front, before creating
+        # a session or running HMAC verification — obviously-malformed input
+        # should not cause session churn (#186 review).
+        return false if token.nil? || token.strip.empty?
+
+        session_id = extract_session_id(request)
+        @config.verify_csrf_token(token, session_id)
+      end
+
+      def extract_csrf_token(request)
+        # Try form parameter first
+        token = request.params[@config.csrf_token_key]
+
+        # Try header if not in params
+        token ||= request.env[@config.csrf_header_key]
+
+        # Try alternative header format
+        token ||= request.env['HTTP_X_CSRF_TOKEN'] if request.env['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest'
+
+        token
+      end
+
+      def extract_session_id(request)
+        @config.get_or_create_session_id(request)
+      end
+
+      def csrf_error_response
+        [
+          403,
+          {
+            'content-type' => 'application/json',
+            'content-length' => CSRF_ERROR_BODY.bytesize.to_s,
+          },
+          [CSRF_ERROR_BODY],
+        ]
+      end
+    end
+  end
+end