otto 2.3.1 → 2.4.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.rb

@@ -0,0 +1,19 @@
+# lib/otto/security/csp.rb
+#
+# frozen_string_literal: true
+
+#
+# Index file for Content-Security-Policy violation reporting components.
+#
+# 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.
+#
+# See Otto::Security::Core#enable_csp_reporting! for the primary entry point and
+# delano/otto#174 for the design.
+
+require_relative 'csp/report'
+require_relative 'csp/parser'
+require_relative 'csp/report_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.4.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.4.0
 platform: ruby
 authors:
 - Delano Mandelbaum
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-01 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,10 @@ 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/parser.rb
+- lib/otto/security/csp/report.rb
+- lib/otto/security/csp/report_middleware.rb
 - lib/otto/security/csrf.rb
 - lib/otto/security/middleware/csrf_middleware.rb
 - lib/otto/security/middleware/ip_privacy_middleware.rb
@@ -298,6 +316,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -315,7 +334,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: []