otto 2.3.1 → 2.4.0

data/examples/caddy_tls_demo/standalone.ru

@@ -0,0 +1,38 @@
+# examples/caddy_tls_demo/standalone.ru
+#
+# STRONGEST isolation for the Caddy on-demand TLS permission endpoint: run it as
+# its own tiny Otto app, bound to a dedicated loopback-only port, physically
+# separate from your public-facing application. This is the topology used in
+# production (cf. the OneTimeSecret "Internal ACME" app the pilot absorbs).
+#
+# This is ALSO how you support Caddy and the app running on DIFFERENT hosts: run
+# this tiny app on the Caddy host (Caddy -> endpoint stays loopback), and let the
+# permission block below reach your real domain data over your own authenticated
+# channel (internal API, shared DB, cache). The loopback guard never has to trust
+# a cross-host source IP.
+#
+# Because this process listens only on 127.0.0.1 and serves *nothing else*, the
+# endpoint is unreachable from outside the host by construction; the localhost
+# guard is then a second layer, not the only one.
+#
+# Run it on a dedicated loopback port:
+#
+#   rackup examples/caddy_tls_demo/standalone.ru -o 127.0.0.1 -p 12020
+#
+# Point Caddy at that port (config-only; `ask` and `permission http` are equivalent):
+#
+#   on_demand_tls {
+#     permission http { endpoint http://127.0.0.1:12020/_caddy/tls-permission }
+#   }
+
+require_relative '../../lib/otto'
+require_relative 'app'
+
+# No routes file: this app serves ONLY the permission endpoint.
+acme = Otto.new
+
+acme.enable_caddy_tls! do |domain|
+  DomainDirectory.allowed?(domain)
+end
+
+run acme

data/lib/otto/caddy_tls/core.rb

@@ -0,0 +1,74 @@
+# lib/otto/caddy_tls/core.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  # Otto::CaddyTLS is a modular, opt-in integration for Caddy's on-demand TLS
+  # permission endpoint — the HTTP question Caddy asks a backend before it
+  # obtains or loads a certificate on demand: "may I serve TLS for this host?".
+  # The contract is a single GET endpoint with +?domain=<host>+ appended; HTTP
+  # 200 means allow, any non-2xx means deny. One endpoint serves BOTH the
+  # deprecated +ask+ directive and its replacement, the +permission http+ module
+  # (their HTTP contracts are identical, so migrating is config-only on Caddy's
+  # side):
+  #
+  #   on_demand_tls {
+  #     permission http { endpoint http://127.0.0.1:PORT/_caddy/tls-permission }
+  #   }
+  #   # legacy / deprecated, same endpoint:
+  #   on_demand_tls { ask http://127.0.0.1:PORT/_caddy/tls-permission }
+  #
+  # Otto owns all the HTTP ceremony (routing, localhost-only guard, blank-domain
+  # handling, fail-closed decision, response semantics). The app owns exactly one
+  # thing — the domain decision — supplied as a block to +enable_caddy_tls!+.
+  #
+  # It is structured like Otto::MCP: a self-contained, top-level namespace loaded
+  # eagerly but inert until +enable_caddy_tls!+ is called, rather than an
+  # always-on concern like Otto::Security / Otto::Privacy. Each such integration
+  # gets its own feature-named home (cf. Otto::MCP, Otto::Security::CSP) — Otto
+  # deliberately has no generic "services" bucket; genuinely shared mechanism
+  # (e.g. the +:outermost+ middleware position) lives in Otto::Core instead.
+  module CaddyTLS
+    # Public API mixin included into the Otto class. Mirrors Otto::MCP::Core.
+    module Core
+      # Enable the Caddy on-demand TLS permission endpoint.
+      #
+      # Registers a GET endpoint that answers Caddy's on-demand certificate
+      # question. The block you pass is the ONLY application coupling point: it
+      # receives the requested domain and returns truthy to allow a certificate
+      # (HTTP 200) or falsy to deny (HTTP 403). Any exception raised inside the
+      # block is caught and treated as a denial (fail-closed).
+      #
+      # @param endpoint [String] path to serve (default '/_caddy/tls-permission')
+      # @param localhost_only [Boolean] install the loopback-only guard (default true).
+      #   Passing false removes the only built-in access control — do so only when the
+      #   endpoint is isolated at the network layer; a warning is logged when disabled.
+      # @yieldparam domain [String] the domain Caddy is asking about
+      # @yieldreturn [Boolean] truthy to allow (200), falsy to deny (403)
+      # @return [self]
+      # @raise [ArgumentError] if no permission block is given (no allow-all default)
+      # @raise [FrozenError] if called after configuration is frozen
+      #
+      # @example
+      #   otto = Otto.new('routes.txt')
+      #   otto.enable_caddy_tls! do |domain|
+      #     MyApp::CustomDomain.verified?(domain)
+      #   end
+      def enable_caddy_tls!(endpoint: '/_caddy/tls-permission', localhost_only: true, &permission)
+        ensure_not_frozen!
+        raise ArgumentError, 'enable_caddy_tls! requires a permission block' unless block_given?
+
+        @caddy_tls_server ||= Otto::CaddyTLS::Server.new(self)
+        @caddy_tls_server.enable!(endpoint: endpoint, localhost_only: localhost_only, permission: permission)
+        Otto.logger.info '[CaddyTLS] Enabled Caddy on-demand TLS permission endpoint' if Otto.debug
+
+        self
+      end
+
+      # @return [Boolean] whether the Caddy on-demand TLS endpoint is enabled
+      def caddy_tls_enabled?
+        @caddy_tls_server&.enabled? || false
+      end
+    end
+  end
+end

data/lib/otto/caddy_tls/localhost_guard.rb

@@ -0,0 +1,158 @@
+# lib/otto/caddy_tls/localhost_guard.rb
+#
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+require_relative '../utils'
+
+class Otto
+  module CaddyTLS
+    # Path-scoped Rack middleware that only allows requests to a single
+    # endpoint when they originate from the loopback interface.
+    #
+    # Introduced for the Caddy on-demand TLS endpoint but written to be generic:
+    # it protects any single endpoint whose only legitimate caller is a
+    # co-located process (a reverse proxy's control-plane callback). Pass it the
+    # endpoint path to protect, and it 401s any request to that path whose
+    # connecting peer is not loopback. Every other path passes straight through,
+    # so installing it never affects the rest of the application. (It lives under
+    # Otto::CaddyTLS while it has a single consumer; promote it to a shared home
+    # if a second internal-only integration ever needs it.)
+    #
+    # == Security: authenticate the RAW peer, not the resolved client IP
+    #
+    # The guard reads the ORIGINAL +env['REMOTE_ADDR']+ — the TCP socket peer —
+    # and MUST run before +IPPrivacyMiddleware+ rewrites +REMOTE_ADDR+ from
+    # forwarded headers. Installed via +Otto#use+ (appended, hence outermost in
+    # the reduce-built stack) it always executes ahead of +IPPrivacyMiddleware+
+    # (which is pinned innermost), so it inspects the true socket peer.
+    #
+    # Reading Otto's resolved +otto.client_ip+ (or the rewritten +REMOTE_ADDR+)
+    # would be exploitable: a co-located reverse proxy on loopback is itself a
+    # natural trusted proxy, so an attacker who could reach the endpoint through
+    # it and send +X-Forwarded-For: 127.0.0.1+ would be promoted to "localhost".
+    # Authenticating the raw peer removes forwarded headers from the trust
+    # decision entirely.
+    #
+    # == What "a direct local call" means
+    #
+    # The endpoint's only legitimate caller is the co-located service making a
+    # *direct* request over the loopback interface. Two things must both hold:
+    #
+    # 1. The socket peer (+REMOTE_ADDR+) is loopback.
+    # 2. The request carries NO forwarding headers. Caddy's on-demand permission
+    #    request is a direct backend call and sends none; a request that was
+    #    *relayed through a reverse proxy* carries +X-Forwarded-For+ (or a
+    #    sibling). Rejecting those is what makes the guard safe even when the
+    #    endpoint is accidentally mounted inside a public app behind a proxy that
+    #    connects to the backend over loopback — there, every proxied request has
+    #    a loopback peer, but it also carries a forwarding header, so it is
+    #    denied.
+    #
+    # == Deployment assumption
+    #
+    # The guard trusts that +REMOTE_ADDR+ is the real socket peer and that a
+    # trusted layer has not stripped forwarding headers before Otto sees them.
+    # The strongest isolation is still network-level: bind the endpoint on a
+    # dedicated loopback-only port that the proxy reaches directly (see
+    # examples/caddy_tls_demo/standalone.ru). Blocking the endpoint path at the
+    # proxy is a sound additional layer. See docs/reverse-proxy-network-services.md.
+    class LocalhostGuard
+      # Forwarding headers whose presence means the request was relayed by a
+      # proxy rather than issued directly. Any one present => not a direct local
+      # call. Mirrors Otto::Utils::FORWARDED_FOR_HEADERS plus RFC 7239 Forwarded.
+      FORWARDED_HEADERS = %w[
+        HTTP_X_FORWARDED_FOR
+        HTTP_X_REAL_IP
+        HTTP_X_CLIENT_IP
+        HTTP_FORWARDED
+      ].freeze
+
+      # @param app [#call] the downstream Rack app
+      # @param endpoint [String] the path to protect (e.g. '/_caddy/tls-permission')
+      def initialize(app, endpoint)
+        @app      = app
+        @endpoint = normalize_path(endpoint)
+      end
+
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response tuple
+      def call(env)
+        return @app.call(env) unless targets_endpoint?(env)
+        return deny unless direct_local_call?(env)
+
+        @app.call(env)
+      end
+
+      private
+
+      # A direct local call: loopback socket peer AND no forwarding headers.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Boolean]
+      def direct_local_call?(env)
+        loopback_peer?(env['REMOTE_ADDR']) && !relayed?(env)
+      end
+
+      # Whether any forwarding header is present (request came via a proxy).
+      #
+      # @param env [Hash] Rack environment
+      # @return [Boolean]
+      def relayed?(env)
+        FORWARDED_HEADERS.any? { |header| !env[header].to_s.strip.empty? }
+      end
+
+      # Whether this request is for the protected endpoint. Normalizes
+      # +PATH_INFO+ through the same +Otto::Utils.normalize_path+ the router
+      # uses for literal matching, so a percent-encoded, invalid-byte, or
+      # trailing-slash variant the router would still route cannot slip past the
+      # guard by normalizing differently here than at dispatch.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Boolean]
+      def targets_endpoint?(env)
+        normalize_path(env['PATH_INFO']) == @endpoint
+      end
+
+      # Router-equivalent path normalization. Delegates to the single shared
+      # implementation so the guard and the router cannot drift (see
+      # Otto::Utils.normalize_path).
+      #
+      # @param path [String, nil]
+      # @return [String] normalized path
+      def normalize_path(path)
+        Otto::Utils.normalize_path(path)
+      end
+
+      # Whether the connecting peer is a loopback address. Fails closed: a
+      # blank or otherwise unparseable value is treated as non-loopback
+      # (denied) rather than raising on the hot path.
+      #
+      # +.native+ folds IPv4-mapped IPv6 (+::ffff:127.0.0.1+, which dual-stack
+      # servers commonly present) so it is correctly recognized as loopback;
+      # plain +IPAddr#loopback?+ returns false for the mapped form.
+      #
+      # A conforming Rack server sets +REMOTE_ADDR+ to a bare IP (the peer's
+      # port lives in +REMOTE_PORT+). We deliberately do NOT strip a +:port+
+      # suffix here: an unexpected format is a signal something upstream is
+      # non-standard, so denying (fail-closed) is safer than coercing it.
+      #
+      # @param remote_addr [String, nil] the raw socket peer address
+      # @return [Boolean]
+      def loopback_peer?(remote_addr)
+        addr = remote_addr.to_s.strip
+        return false if addr.empty?
+
+        IPAddr.new(addr).native.loopback?
+      rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+        false
+      end
+
+      # @return [Array] 401 Rack response tuple
+      def deny
+        [401, { 'content-type' => 'text/plain' }, ['Unauthorized']]
+      end
+    end
+  end
+end

data/lib/otto/caddy_tls/server.rb

@@ -0,0 +1,149 @@
+# lib/otto/caddy_tls/server.rb
+#
+# frozen_string_literal: true
+
+require_relative '../route'
+require_relative '../utils'
+require_relative 'localhost_guard'
+
+class Otto
+  module CaddyTLS
+    # Registers the permission route and (by default) the localhost guard,
+    # and wraps the app-supplied decision block with fail-closed semantics.
+    #
+    # Mirrors +Otto::MCP::Server+: a small per-integration object that owns
+    # its route and middleware registration and is referenced by its handler.
+    class Server
+      # @return [Otto] the owning Otto instance
+      attr_reader :otto
+
+      # @return [String, nil] the registered endpoint path
+      attr_reader :endpoint
+
+      # @param otto [Otto] the owning Otto instance
+      def initialize(otto)
+        @otto    = otto
+        @enabled = false
+      end
+
+      # @return [Boolean]
+      def enabled?
+        @enabled
+      end
+
+      # Enable the integration. Idempotent: a second call is ignored so the
+      # route and guard are never duplicated.
+      #
+      # @param endpoint [String] path to serve (registered programmatically)
+      # @param localhost_only [Boolean] install the loopback guard (default true)
+      # @param permission [#call] block receiving the domain, returning truthy to allow
+      # @return [void]
+      def enable!(endpoint:, localhost_only:, permission:)
+        return if @enabled
+
+        # Normalize once so the guard's endpoint, the router's literal-route
+        # key, and @endpoint all agree. Without this, a configured trailing
+        # slash (or percent-encoding) registers a literal route the router can
+        # never match — requests are normalized before lookup — while the guard
+        # still targets it, so Caddy would get a denial instead of a decision.
+        endpoint = Otto::Utils.normalize_path(endpoint)
+
+        @endpoint       = endpoint
+        @permission     = permission
+        @localhost_only = localhost_only
+        @enabled        = true
+
+        register_route(endpoint)
+
+        if localhost_only
+          # SECURITY: appended (via #use) so it is OUTERMOST in the stack and
+          # runs BEFORE IPPrivacyMiddleware — the guard must see the raw socket
+          # peer, not the forwarded-header-resolved client IP. See LocalhostGuard.
+          @otto.use(Otto::CaddyTLS::LocalhostGuard, endpoint)
+        else
+          # Explicit opt-out: the endpoint then has no built-in access control,
+          # so it must be isolated at the network layer. Surface that at setup.
+          Otto.structured_log(:warn,
+            '[CaddyTLS] localhost guard disabled (localhost_only: false); endpoint is ' \
+            'reachable by any client that can reach this app — ensure network-level isolation',
+            endpoint: endpoint)
+        end
+
+        # structured_log self-skips :debug unless Otto.debug is set.
+        Otto.structured_log(:debug, '[CaddyTLS] enabled',
+          endpoint: endpoint, localhost_only: localhost_only)
+      end
+
+      # Fail-closed decision wrapper. Any exception, +nil+, or +false+ from the
+      # app block denies — a broken decision must never authorize a cert.
+      #
+      # @param domain [String] the domain Caddy is asking about
+      # @return [Boolean] true to allow (200), false to deny (403)
+      def permit?(domain)
+        !!@permission.call(domain)
+      rescue StandardError => e
+        Otto.structured_log(:error, '[CaddyTLS] permission callback raised; denying',
+          domain: domain, error: e.message, error_class: e.class.name)
+        false
+      end
+
+      private
+
+      # Register the GET route programmatically (like MCP's /_mcp endpoint),
+      # so enabling is purely code-side with no routes.txt entry required.
+      #
+      # @param endpoint [String]
+      # @return [void]
+      def register_route(endpoint)
+        route      = Otto::Route.new('GET', endpoint, 'Otto::CaddyTLS::PermissionHandler.handle')
+        route.otto = @otto
+
+        (@otto.routes[:GET] ||= []) << route
+        (@otto.routes_literal[:GET] ||= {})[endpoint] = route
+      end
+    end
+
+    # Class-method route handler for the permission endpoint.
+    #
+    # The owning Server is resolved per-request from the Otto instance the
+    # dispatcher binds to this class (+Otto::Route::ClassMethods#otto+), NOT a
+    # class-level global. That keeps multiple Otto instances in one process
+    # isolated: each endpoint consults its own permission block. (This shares
+    # the same per-request class-accessor mechanism the rest of Otto uses for
+    # class-method handlers.)
+    class PermissionHandler
+      # Handle a permission request. Only +?domain=+ is consulted — no other
+      # query parameter reaches the decision. A non-string +domain+ (e.g.
+      # +?domain[]=a+) is treated as missing rather than coerced.
+      #
+      # @param req [Otto::Request]
+      # @param res [Otto::Response]
+      # @return [Otto::Response]
+      def self.handle(req, res)
+        raw    = req.params['domain']
+        domain = raw.is_a?(String) ? raw.strip : ''
+
+        return respond(req, res, 400, 'Bad Request - domain parameter required') if domain.empty?
+
+        server  = respond_to?(:otto) ? otto&.caddy_tls_server : nil
+        allowed = server ? server.permit?(domain) : false
+        Otto.structured_log(:info, '[CaddyTLS] permission decision', domain: domain, allowed: allowed)
+
+        respond(req, res, allowed ? 200 : 403, allowed ? 'OK' : 'Forbidden')
+      end
+
+      # @param req [Otto::Request]
+      # @param res [Otto::Response]
+      # @param status [Integer]
+      # @param body [String]
+      # @return [Otto::Response]
+      def self.respond(req, res, status, body)
+        res.status          = status
+        res['content-type'] = 'text/plain'
+        # HEAD must carry no body (Rack SPEC / Rack::Lint); headers still apply.
+        res.body            = req.head? ? [] : [body]
+        res
+      end
+    end
+  end
+end

data/lib/otto/caddy_tls.rb

@@ -0,0 +1,7 @@
+# lib/otto/caddy_tls.rb
+#
+# frozen_string_literal: true
+
+require_relative 'caddy_tls/core'
+require_relative 'caddy_tls/localhost_guard'
+require_relative 'caddy_tls/server'

data/lib/otto/core/middleware_management.rb

@@ -35,13 +35,12 @@ class Otto
       # @param args Additional arguments passed to middleware constructor
       def use(middleware, ...)
         ensure_not_frozen!
+        # @middleware.add fires the stack's on_change callback, which rebuilds
+        # @app when it already exists (wired in Otto#initialize_core_state). A
+        # rebuild triggered during a live request could swap @app mid-flight
+        # under multi-threaded serving; configure middleware before the first
+        # request (the lazy configuration freeze enforces this in production).
         @middleware.add(middleware, ...)
-
-        # NOTE: If build_app! is triggered during a request (via use() or
-        # middleware_stack=), the @app instance variable could be swapped
-        # mid-request in a multi-threaded environment.
-
-        build_app! if @app # Rebuild app if already initialized
       end
 
       # Compatibility method for existing tests
@@ -53,9 +52,10 @@ class Otto
       # Compatibility method for existing tests
       # @param stack [Array] Array of middleware classes
       def middleware_stack=(stack)
+        # clear! and each add fire the stack's on_change callback, which keeps
+        # @app in sync (wired in Otto#initialize_core_state).
         @middleware.clear!
         Array(stack).each { |middleware| @middleware.add(middleware) }
-        build_app! if @app # Rebuild app if already initialized
       end
 
       # Check if a specific middleware is enabled

data/lib/otto/core/middleware_stack.rb

@@ -16,6 +16,9 @@ class Otto
       def initialize
         @stack = []
         @middleware_set = Set.new
+        # Classes pinned to run OUTERMOST regardless of insertion order (see
+        # the :outermost position in #add_with_position and #ordered_stack).
+        @outermost = Set.new
         @on_change_callback = nil
       end
 
@@ -49,10 +52,20 @@ class Otto
 
       # Add middleware with position hint for optimal ordering
       #
+      # Positions:
+      # - :first     — innermost (runs last, closest to the app)
+      # - :last/nil  — append (outermost among currently-registered middleware,
+      #                but a later append displaces it)
+      # - :outermost — pin to run OUTERMOST (first to see the request) and STAY
+      #                there even if more middleware is appended afterward. Unlike
+      #                :last, this is order-independent: honored in #ordered_stack
+      #                at build time. Use for middleware that must short-circuit
+      #                ahead of everything else (e.g. the CSP report receiver,
+      #                which must intercept before CSRF).
+      #
       # @param middleware_class [Class] Middleware class
       # @param args [Array] Middleware arguments
-      # @param position [Symbol, nil] Position hint (:first, :last, or nil for append)
-      # @option options [Symbol] :position Position hint (:first or :last)
+      # @param position [Symbol, nil] Position hint (:first, :last, :outermost, or nil)
       def add_with_position(middleware_class, *args, position: nil, **options)
         raise FrozenError, 'Cannot modify frozen middleware stack' if frozen?
 
@@ -70,10 +83,11 @@ class Otto
         case position
         when :first
           @stack.unshift(entry)
-        when :last
+        when :outermost
           @stack << entry
+          @outermost.add(middleware_class)
         else
-          @stack << entry # Default append
+          @stack << entry # :last / nil — default append
         end
 
         @middleware_set.add(middleware_class)
@@ -148,6 +162,7 @@ class Otto
 
         # Rebuild the set of unique middleware classes
         @middleware_set = Set.new(@stack.map { |entry| entry[:middleware] })
+        @outermost.delete(middleware_class)
         # Notify of change
         @on_change_callback&.call
       end
@@ -164,6 +179,7 @@ class Otto
 
         @stack.clear
         @middleware_set.clear
+        @outermost.clear
         # Notify of change
         @on_change_callback&.call
       end
@@ -174,8 +190,13 @@ class Otto
       end
 
       # Build Rack application with middleware chain
+      #
+      # The stack folds via reduce, so the LAST entry becomes the OUTERMOST
+      # wrapper (first to see the request). #ordered_stack moves any :outermost-
+      # pinned middleware to the end so it stays outermost regardless of the
+      # order middleware was registered in.
       def wrap(base_app, security_config = nil)
-        @stack.reduce(base_app) do |app, entry|
+        ordered_stack.reduce(base_app) do |app, entry|
           middleware = entry[:middleware]
           args = entry[:args]
           options = entry[:options]
@@ -233,6 +254,18 @@ class Otto
 
       private
 
+      # The stack ordered for #wrap: identical to @stack unless some middleware
+      # is pinned :outermost, in which case pinned entries are moved to the end
+      # (outermost) while preserving the relative order of both groups. Returns
+      # @stack itself (no copy) in the common no-pin case, so ordinary apps are
+      # completely unaffected.
+      def ordered_stack
+        return @stack if @outermost.empty?
+
+        pinned, rest = @stack.partition { |entry| @outermost.include?(entry[:middleware]) }
+        rest + pinned
+      end
+
       def middleware_needs_config?(middleware_class)
         # Include all Otto security middleware that can accept security_config
         # Support both new namespaced classes and backward compatibility aliases
@@ -241,6 +274,7 @@ class Otto
           Otto::Security::Middleware::ValidationMiddleware,
           Otto::Security::Middleware::RateLimitMiddleware,
           Otto::Security::Middleware::IPPrivacyMiddleware,
+          Otto::Security::CSP::ReportMiddleware,
         ].include?(middleware_class)
       end
     end

data/lib/otto/core/router.rb

@@ -72,14 +72,10 @@ class Otto
         path_info          = '/' if path_info.to_s.empty?
 
         begin
-          path_info_clean = path_info
-                            .encode(
-                              'UTF-8', # Target encoding
-                              invalid: :replace, # Replace invalid byte sequences
-                              undef: :replace,   # Replace characters undefined in UTF-8
-                              replace: '' # Use empty string for replacement
-                            )
-                            .gsub(%r{/$}, '') # Remove trailing slash, if present
+          # Shared with Otto::CaddyTLS::LocalhostGuard so the guard and the
+          # router cannot normalize a path differently (which would be a guard
+          # bypass). See Otto::Utils.normalize_path.
+          path_info_clean = Otto::Utils.normalize_path(env['PATH_INFO'])
         rescue ArgumentError => e
           # Log the error but don't expose details
           Otto.logger.error '[Otto.handle_request] Path encoding error'