otto 2.3.1 → 2.5.0

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

@@ -0,0 +1,120 @@
+# lib/otto/security/csp/report_middleware.rb
+#
+# frozen_string_literal: true
+
+require_relative 'parser'
+
+class Otto
+  module Security
+    module CSP
+      # Rack middleware that receives browser-posted Content-Security-Policy
+      # violation reports and dispatches them to an application callback.
+      #
+      # This is the receiving half of Otto's CSP support; the emitting half is
+      # {Otto::Security::Config#generate_nonce_csp} / {Otto::Response#send_csp_headers}
+      # (and the static {Otto::Security::Config#enable_csp!}). When a report URI
+      # is configured, the emitted policy carries a `report-uri` directive
+      # pointing here.
+      #
+      # Behavior (all mandatory for a public, unauthenticated receiver):
+      #
+      # - INERT unless {Otto::Security::Config#csp_report_uri} is set. When it is
+      #   not configured the middleware is a transparent pass-through.
+      # - Only intercepts a POST whose path matches the configured report URI.
+      #   Everything else (other paths, other methods) passes through untouched.
+      # - Short-circuits BEFORE inner middleware, so CSRF, auth, and rate
+      #   limiting never see the request. This is why browsers can POST reports
+      #   with no CSRF token: the report never reaches the CSRF middleware.
+      #   {Otto::Security::Core#enable_csp_reporting!} pins this middleware
+      #   OUTERMOST (via the :outermost stack position), so the guarantee holds
+      #   regardless of the order security features are enabled in. The flip side
+      #   is that reports also bypass rate limiting — see the DoS note on
+      #   {Otto::Security::Core#enable_csp_reporting!}; keep callbacks cheap.
+      # - Enforces a hard {MAX_BODY_BYTES} body cap. Oversized bodies are
+      #   detected with a `cap + 1` read and skipped WITHOUT parsing, so a
+      #   hostile client cannot force large allocations against a public endpoint.
+      # - Parses both wire formats via {Otto::Security::CSP::Parser} and invokes
+      #   the registered callback once per normalized report.
+      # - NEVER raises to the client and always responds `204 No Content`
+      #   (browsers ignore the body). A throwing callback is isolated by
+      #   {Otto::Security::Config#dispatch_csp_violation}.
+      class ReportMiddleware
+        # Hard cap on the request body we are willing to read/parse. Browsers
+        # send small JSON documents; anything larger is abuse and is dropped.
+        MAX_BODY_BYTES = 64 * 1024 # 64 KiB
+
+        def initialize(app, config = nil)
+          @app    = app
+          @config = config || Otto::Security::Config.new
+        end
+
+        def call(env)
+          return @app.call(env) unless report_request?(env)
+
+          receive_report(env)
+        end
+
+        private
+
+        # Handle a report POST and always answer 204. A report receiver must
+        # never surface an error to the browser, so parse/dispatch failures are
+        # contained HERE — deliberately NOT around the #call pass-through, which
+        # would swallow unrelated downstream errors (turning every failing
+        # request into a silent 204, since this middleware runs outermost).
+        def receive_report(env)
+          handle_report(env)
+          # A fresh header hash + body per call (never a shared/frozen literal)
+          # so a downstream server that mutates the response tuple is safe.
+          [204, {}, []]
+        rescue StandardError => e
+          Otto.logger.error("[Otto::CSP] report handling failed: #{e.class}: #{e.message}")
+          [204, {}, []]
+        end
+
+        # True only when reporting is configured AND this is a POST to the
+        # configured report path.
+        #
+        # @param env [Hash]
+        # @return [Boolean]
+        def report_request?(env)
+          report_uri = @config.csp_report_uri
+          return false if report_uri.nil? || report_uri.empty?
+          return false unless env['REQUEST_METHOD'] == 'POST'
+
+          env['PATH_INFO'] == report_uri
+        end
+
+        # Read (capped), parse, and dispatch. Never raises; parse/dispatch
+        # failures are contained so the caller can still return 204.
+        #
+        # @param env [Hash]
+        # @return [void]
+        def handle_report(env)
+          body = read_capped_body(env)
+          return if body.nil?
+
+          reports = Otto::Security::CSP::Parser.parse(body, env['CONTENT_TYPE'])
+          reports.each { |report| @config.dispatch_csp_violation(report) }
+        end
+
+        # Read at most MAX_BODY_BYTES + 1 bytes so an oversized body is detected
+        # without ever materializing more than the cap. Returns nil when there is
+        # no readable body or the body exceeds the cap (skip without parsing).
+        #
+        # @param env [Hash]
+        # @return [String, nil]
+        def read_capped_body(env)
+          input = env['rack.input']
+          return nil if input.nil?
+
+          chunk = input.read(MAX_BODY_BYTES + 1)
+          input.rewind if input.respond_to?(:rewind)
+          return nil if chunk.nil? || chunk.empty?
+          return nil if chunk.bytesize > MAX_BODY_BYTES # oversized: drop unparsed
+
+          chunk
+        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

@@ -0,0 +1,31 @@
+# lib/otto/security/csp.rb
+#
+# frozen_string_literal: true
+
+#
+# Index file for Content-Security-Policy components — both halves of Otto's CSP
+# support live under Otto::Security::CSP.
+#
+# 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!.
+#
+# 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/middleware/ip_privacy_middleware.rb

@@ -85,6 +85,27 @@ class Otto
 
           Otto.logger.debug "[IPPrivacyMiddleware] Resolved client IP: #{client_ip}" if Otto.debug
 
+          # No resolvable client IP (REMOTE_ADDR absent or blank, and no trusted
+          # forwarded value). There is nothing to mask, and masking would derive
+          # a nil masked IP (IPPrivacy.mask_ip returns nil for nil/empty input).
+          # Writing that nil back to REMOTE_ADDR / forwarded headers would leave
+          # present-but-nil CGI keys, which violate the Rack SPEC and trip
+          # Rack::Lint — the same class of bug as the User-Agent/Referer case
+          # below (issue #167). Skip the IP-masking work, leaving REMOTE_ADDR
+          # untouched (an absent key stays absent; an empty string stays an
+          # empty string).
+          #
+          # The User-Agent/Referer redaction, however, is independent of the
+          # client IP, and this middleware's contract is to ALWAYS clear the
+          # original sensitive data. So still scrub those headers before
+          # bailing — a request with no resolvable IP must not leak an
+          # un-anonymized User-Agent or Referer.
+          if client_ip.to_s.empty?
+            Otto.logger.debug '[IPPrivacyMiddleware] No resolvable client IP; skipping IP masking' if Otto.debug
+            scrub_sensitive_headers(env, Otto::Privacy::RedactedFingerprint.new(env, @config))
+            return
+          end
+
           # Skip masking for private/localhost IPs unless explicitly configured to mask them
           # This provides better DX for development while still protecting public IPs
           unless @config.mask_private_ips
@@ -122,13 +143,10 @@ class Otto
           # Privacy-safe: holds the masked value, never the original public IP.
           env['otto.client_ip'] = fingerprint.masked_ip
 
-          # Replace User-Agent with anonymized version (consistent with IP masking)
-          # CRITICAL: Always replace, even if nil, to clear original sensitive data
-          env['HTTP_USER_AGENT'] = fingerprint.anonymized_ua
-
-          # Replace Referer with anonymized version (query params stripped)
-          # CRITICAL: Always replace, even if nil, to clear original sensitive data
-          env['HTTP_REFERER'] = fingerprint.referer
+          # Replace User-Agent / Referer with anonymized versions (consistent
+          # with IP masking). See scrub_sensitive_headers — also reached by the
+          # no-resolvable-IP path so these headers are always cleared.
+          scrub_sensitive_headers(env, fingerprint)
 
           # Mask X-Forwarded-For headers to prevent leakage
           # Replace with masked IP so proxy resolution logic finds the masked IP
@@ -141,6 +159,45 @@ class Otto
         end
 
 
+        # Set or clear a Rack env header in a SPEC-compliant way.
+        #
+        # CGI-style keys (those without a period) must hold String values per
+        # the Rack SPEC; a present-but-nil value trips Rack::Lint. So when the
+        # anonymized replacement is nil, delete the key entirely instead of
+        # assigning nil — semantically identical to "cleared" for downstream
+        # readers, and SPEC-compliant.
+        #
+        # @param env [Hash] Rack environment
+        # @param key [String] Env key to set or delete
+        # @param value [String, nil] Replacement value, or nil to clear the key
+        def replace_or_delete(env, key, value)
+          if value.nil?
+            env.delete(key)
+          else
+            env[key] = value
+          end
+        end
+
+        # Redact the request's sensitive non-IP headers in place.
+        #
+        # User-Agent and Referer carry identifying information independent of
+        # the client IP, so they are scrubbed on every privacy-enabled request
+        # — including ones with no resolvable IP, where IP masking is skipped.
+        # Each header is replaced with the fingerprint's anonymized value, or
+        # DELETED when that value is nil (no/empty header): CGI-style keys must
+        # hold String values per the Rack SPEC, so a present-but-nil
+        # HTTP_USER_AGENT/HTTP_REFERER would trip Rack::Lint (issue #167).
+        # Deleting is also marginally more private — an absent header is
+        # indistinguishable from one that was never sent.
+        #
+        # @param env [Hash] Rack environment
+        # @param fingerprint [Otto::Privacy::RedactedFingerprint] source of the
+        #   anonymized header values
+        def scrub_sensitive_headers(env, fingerprint)
+          replace_or_delete(env, 'HTTP_USER_AGENT', fingerprint.anonymized_ua)
+          replace_or_delete(env, 'HTTP_REFERER', fingerprint.referer)
+        end
+
         # Resolve the actual client IP address from the request.
         #
         # Delegates to the shared Otto::Utils.resolve_client_ip so the
@@ -162,6 +219,14 @@ class Otto
         # @param env [Hash] Rack environment
         # @param masked_ip [String] The masked IP to use as replacement
         def mask_forwarded_headers(env, masked_ip)
+          # Defensive: never write a nil replacement into these CGI-style headers
+          # (the Rack SPEC requires String values; a nil trips Rack::Lint — see
+          # issue #167). apply_privacy's early "no client IP" guard already
+          # guarantees a non-nil masked_ip here, but keep this method
+          # self-contained so a future caller change can't reintroduce a
+          # present-but-nil HTTP_X_FORWARDED_FOR.
+          return if masked_ip.nil?
+
           # Replace X-Forwarded-For with masked IP
           # This prevents Rack::Request#ip from finding the real IP
           env['HTTP_X_FORWARDED_FOR'] = masked_ip if env['HTTP_X_FORWARDED_FOR']

data/lib/otto/security.rb

@@ -12,3 +12,4 @@ require_relative 'security/middleware/csrf_middleware'
 require_relative 'security/middleware/validation_middleware'
 require_relative 'security/middleware/rate_limit_middleware'
 require_relative 'security/middleware/ip_privacy_middleware'
+require_relative 'security/csp'

data/lib/otto/utils.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require 'ipaddr'
+require 'rack/utils'
 
 class Otto
   # Utility methods for common operations and helpers
@@ -57,6 +58,41 @@ class Otto
       !value.to_s.empty? && %w[true yes 1].include?(value.to_s.downcase)
     end
 
+    # Canonical path normalization for literal route matching: URL-unescape,
+    # scrub invalid/undefined bytes, and strip a single trailing slash.
+    #
+    # This is the SINGLE SOURCE OF TRUTH shared by the router
+    # (Otto::Core::Router#handle_request, which compares the result against its
+    # literal-route table) and Otto::CaddyTLS::LocalhostGuard (which compares it
+    # against the guarded endpoint). The two MUST normalize identically: if a
+    # crafted path — a trailing slash, a percent-encoded byte, an invalid UTF-8
+    # byte — normalized differently in the guard than in the router, the router
+    # could dispatch a request the guard let through, bypassing the loopback
+    # check. One implementation makes that drift impossible.
+    #
+    # Mirrors the empty-path handling and :replace scrubbing the router applies.
+    # Robust to invalid input: Rack::Utils.unescape raises ArgumentError on an
+    # already-invalid byte sequence (a raw \xFF in the path), so that is caught
+    # and the raw string is scrubbed instead — a percent-encoded invalid byte
+    # (%FF) decodes to the same invalid byte and is scrubbed identically, so the
+    # two crafted forms normalize alike. The method itself does not raise.
+    #
+    # @param raw_path [String, nil] a raw PATH_INFO or a configured endpoint
+    # @return [String] normalized path suitable for exact literal comparison
+    def normalize_path(raw_path)
+      raw = raw_path.to_s
+      decoded =
+        begin
+          Rack::Utils.unescape(raw)
+        rescue ArgumentError
+          raw
+        end
+      decoded = '/' if decoded.empty?
+      decoded
+        .encode('UTF-8', invalid: :replace, undef: :replace, replace: '')
+        .gsub(%r{/$}, '')
+    end
+
     # Validate and normalize an IP address (IPv4 and IPv6).
     #
     # Strips an optional port (IPv6-safe), validates with IPAddr, and returns

data/lib/otto/version.rb

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

data/lib/otto.rb

@@ -22,6 +22,7 @@ require_relative 'otto/route_handlers'
 require_relative 'otto/errors'
 require_relative 'otto/locale'
 require_relative 'otto/mcp'
+require_relative 'otto/caddy_tls'
 require_relative 'otto/core'
 require_relative 'otto/privacy'
 require_relative 'otto/security'
@@ -62,6 +63,7 @@ class Otto
   include Otto::Security::Core
   include Otto::Privacy::Core
   include Otto::MCP::Core
+  include Otto::CaddyTLS::Core
 
   LIB_HOME = __dir__ unless defined?(Otto::LIB_HOME)
 
@@ -75,7 +77,7 @@ class Otto
 
   attr_reader :routes, :routes_literal, :routes_static, :route_definitions, :option,
               :static_route, :security_config, :locale_config, :auth_config,
-              :route_handler_factory, :mcp_server, :security, :middleware,
+              :route_handler_factory, :mcp_server, :caddy_tls_server, :security, :middleware,
               :error_handlers, :request_class, :response_class
   attr_accessor :not_found, :server_error
 
@@ -107,8 +109,13 @@ class Otto
 
   # Main Rack application interface
   def call(env)
-    # Freeze configuration on first request (thread-safe)
-    # Skip in test environment to allow test flexibility
+    # Freeze configuration on first request (thread-safe).
+    # Skipped under RSpec so specs can mutate configuration after construction.
+    # Because of this skip, behavior that depends on a genuinely frozen config
+    # (e.g. CSP violation dispatch through a frozen Config) is NOT exercised by
+    # the normal request path in tests — cover it with specs that freeze
+    # explicitly (see spec/otto/security/csp_reporting_frozen_spec.rb and
+    # spec/otto/configuration_freezing_spec.rb).
     unless defined?(RSpec) || @configuration_frozen
       Otto.logger.debug '[Otto] Lazy freezing check: configuration not yet frozen' if Otto.debug
 
@@ -169,6 +176,22 @@ class Otto
     @auth_config       = { auth_strategies: {}, default_auth_strategy: 'noauth' }
     @security          = Otto::Security::Configurator.new(@security_config, @middleware, @auth_config)
     @app               = nil # Pre-built middleware app (built after initialization)
+
+    # Keep the running Rack app in sync with the middleware stack. This is the
+    # SINGLE rebuild trigger: any add/remove/clear — whether via Otto#use,
+    # otto.enable_*!, or the otto.security.* Configurator surface — rebuilds @app
+    # once it exists. Without it, middleware added through the Configurator after
+    # Otto.new would register in the stack but never enter the running request
+    # chain, silently disabling CSRF, request validation, rate limiting, and CSP
+    # reporting configured that way.
+    #
+    # The `if @app` guard makes stack mutations during initialization (e.g. the
+    # IP-privacy add below) no-ops until the first build_app! runs. A rebuild
+    # during a live request could swap @app mid-flight under multi-threaded
+    # serving; Otto's contract is to configure before the first request, which
+    # the lazy configuration freeze enforces in production.
+    @middleware.on_change { build_app! if @app }
+
     @request_complete_callbacks = [] # Instance-level request completion callbacks
     @route_matched_callbacks    = [] # Instance-level route matched callbacks
     @handler_wrappers           = [] # Instance-level handler wrapper factories

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.5.0
 platform: ruby
 authors:
 - Delano Mandelbaum
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -123,12 +124,15 @@ files:
 - ".github/workflows/claude.yml"
 - ".github/workflows/code-smells.yml"
 - ".github/workflows/release-gem.yml"
+- ".github/workflows/ruby-lint.yml"
+- ".github/workflows/yardoc.yml"
 - ".gitignore"
 - ".pre-commit-config.yaml"
 - ".pre-push-config.yaml"
 - ".reek.yml"
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - AGENTS.md
 - CHANGELOG.rst
 - Gemfile
@@ -146,6 +150,7 @@ files:
 - docs/migrating/v2.3.0.md
 - docs/modern-authentication-authorization-landscape.md
 - docs/multi-strategy-authentication-design.md
+- docs/reverse-proxy-network-services.md
 - examples/.gitignore
 - examples/advanced_routes/README.md
 - examples/advanced_routes/app.rb
@@ -192,6 +197,11 @@ files:
 - examples/basic/app.rb
 - examples/basic/config.ru
 - examples/basic/routes
+- examples/caddy_tls_demo/README.md
+- examples/caddy_tls_demo/app.rb
+- examples/caddy_tls_demo/config.ru
+- examples/caddy_tls_demo/routes
+- examples/caddy_tls_demo/standalone.ru
 - examples/error_handler_registration.rb
 - examples/logging_improvements.rb
 - examples/mcp_demo/README.md
@@ -204,6 +214,10 @@ files:
 - examples/security_features/routes
 - examples/simple_geo_resolver.rb
 - lib/otto.rb
+- lib/otto/caddy_tls.rb
+- lib/otto/caddy_tls/core.rb
+- lib/otto/caddy_tls/localhost_guard.rb
+- lib/otto/caddy_tls/server.rb
 - lib/otto/core.rb
 - lib/otto/core/configuration.rb
 - lib/otto/core/error_handler.rb
@@ -279,6 +293,14 @@ files:
 - lib/otto/security/configurator.rb
 - 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
@@ -298,6 +320,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -315,7 +338,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Define your rack-apps in plaintext.
 test_files: []