prauga-flexdoc 0.4.4 → 0.4.5

data/lib/prauga/flexdoc/config.rb

@@ -23,7 +23,7 @@ module Prauga
     # @!attribute [r] try_it_api_client_persistence_key
     #   Optional persistence key, or `false` to disable.
     # @!attribute [r] try_it_host_execution
-    #   Emits host-execution protocol metadata; execution is not implemented by this adapter.
+    #   Enables host-execution protocol metadata when a real native executor is attached to the host.
     Config = Data.define(
       :path,
       :spec_url,
@@ -47,7 +47,7 @@ module Prauga
       # @param try_it_default_server [String, nil] optional default server URL for Try It
       # @param try_it_credentials [String, nil] optional fetch credentials mode
       # @param try_it_api_client_persistence_key [String, false, nil] optional persistence key
-      # @param try_it_host_execution [Boolean] emit host-execution protocol metadata; execution is not implemented by this adapter
+      # @param try_it_host_execution [Boolean] expose host execution when the host has a native executor
       def initialize(
         path: "/docs",
         spec_url: "/openapi.json",

data/lib/prauga/flexdoc/host.rb

@@ -14,20 +14,32 @@ module Prauga
       #   @return [Config] validated renderer and route configuration for this host
       # @!attribute [r] fingerprint
       #   @return [String] stable renderer-asset fingerprint used for cache-busting URLs
-      attr_reader :config, :fingerprint
+      # @!attribute [r] host_execution
+      #   @return [HostExecution, nil] optional native API-host executor
+      attr_reader :config, :fingerprint, :host_execution
 
       # Create a host and load its canonical renderer assets.
       #
       # @param config [Config] renderer and route settings
       # @param assets_dir [String, nil] optional directory overriding bundled renderer assets
-      def initialize(config = Config.new, assets_dir: nil)
+      # @param host_execution [HostExecution, nil] optional native API-host executor
+      def initialize(config = Config.new, assets_dir: nil, host_execution: nil)
         @config = config
+        @host_execution = host_execution
         root = assets_dir || File.expand_path("../../../assets", __dir__)
         @javascript = File.binread(File.join(root, "flexdoc.standalone.js"))
         @css = File.binread(File.join(root, "flexdoc.standalone.css"))
         @fingerprint = Digest::SHA256.hexdigest(@javascript + "\0" + @css)[0, 16]
       end
 
+      def execute_path
+        "#{config.path}/__flexdoc/execute"
+      end
+
+      def execution_available?
+        config.try_it_host_execution && !host_execution.nil?
+      end
+
       # Match a request path and return the docs shell, renderer asset, or 404 response.
       #
       # @param path [String] request path
@@ -50,9 +62,9 @@ module Prauga
         try_it[:apiClientPersistenceKey] = config.try_it_api_client_persistence_key unless config.try_it_api_client_persistence_key.nil?
         if config.try_it_host_execution
           try_it[:hostExecution] = {
-            available: false,
-            endpoint: "#{config.path}/__flexdoc/execute",
-            capabilities: []
+            available: execution_available?,
+            endpoint: execute_path,
+            capabilities: host_execution&.capabilities || []
           }
         end
 

data/lib/prauga/flexdoc/host_execution.rb

@@ -0,0 +1,462 @@
+# frozen_string_literal: true
+
+require "base64"
+require "ipaddr"
+require "json"
+require "net/http"
+require "securerandom"
+require "socket"
+require "timeout"
+require "uri"
+
+module Prauga
+  module FlexDoc
+    HostExecutionFile = Data.define(:filename, :content_type, :data)
+    HostExecutionResult = Data.define(:status, :body)
+
+    # Framework-neutral implementation of FlexDoc's existing API-host execution envelope.
+    class HostExecution
+      MAX_EXECUTION_REQUEST_BYTES = 32 * 1024 * 1024
+      MAX_EXECUTION_RESPONSE_BYTES = 10 * 1024 * 1024
+      DEFAULT_TIMEOUT_MS = 30_000
+      MIN_TIMEOUT_MS = 100
+      MAX_TIMEOUT_MS = 120_000
+      MAX_REDIRECTS = 5
+      UNSAFE_HEADERS = %w[
+        connection keep-alive proxy-authenticate proxy-authorization te trailer
+        transfer-encoding upgrade host content-length set-cookie origin referer
+      ].freeze
+      METADATA_HOSTS = %w[169.254.169.254 metadata.google.internal metadata.google].freeze
+      LINK_LOCAL_V4 = IPAddr.new("169.254.0.0/16")
+      LINK_LOCAL_V6 = IPAddr.new("fe80::/10")
+      SUPPORTED_METHODS = %w[GET HEAD POST PUT PATCH DELETE OPTIONS].freeze
+
+      attr_reader :allowed_origins
+
+      def initialize(allowed_origins:)
+        normalized = Array(allowed_origins).filter_map do |raw|
+          value = raw.to_s.strip
+          next if value.empty?
+
+          uri = parse_http_uri(value)
+          unless uri.userinfo.nil? && [nil, "", "/"].include?(uri.path) && uri.query.nil? && uri.fragment.nil?
+            raise ArgumentError,
+                  "host execution allowed origins cannot contain credentials, paths, queries, or fragments: #{value}"
+          end
+          origin_of(uri)
+        rescue URI::InvalidURIError
+          raise ArgumentError, "host execution allowed origin #{value.inspect} must be an absolute HTTP(S) origin"
+        end
+        raise ArgumentError, "FlexDoc host execution requires at least one exact allowed origin" if normalized.empty?
+
+        @allowed_origins = normalized.uniq.freeze
+      end
+
+      def capabilities
+        []
+      end
+
+      def handle(marker:, envelope:, files: {})
+        return HostExecutionResult.new(status: 403, body: { "error" => "Missing X-FlexDoc-Execute header." }) unless marker == "1"
+
+        HostExecutionResult.new(status: 200, body: execute(envelope, files))
+      rescue ExecutionError => error
+        HostExecutionResult.new(status: error.status, body: { "error" => error.message })
+      end
+
+      private
+
+      class ExecutionError < StandardError
+        attr_reader :status
+
+        def initialize(status, message)
+          @status = status
+          super(message)
+        end
+      end
+
+      def bad_request(message) = raise(ExecutionError.new(400, message))
+      def forbidden(message) = raise(ExecutionError.new(403, message))
+      def upstream(message) = raise(ExecutionError.new(502, message))
+
+      def execute(envelope, files)
+        root = envelope.is_a?(Hash) ? envelope : bad_request("Host execution body must be a JSON object.")
+        bad_request("Session cookie jars are not implemented by the Ruby host executor.") if root["cookieJar"] == "session"
+        certificate_id = root["certificateId"].to_s
+        bad_request("Client certificates are not implemented by the Ruby host executor.") unless certificate_id.strip.empty?
+
+        draft = root["request"]
+        bad_request("Host execution body requires a canonical request draft.") unless draft.is_a?(Hash)
+
+        raw_url = string_value(draft["url"])
+        bad_request("Host execution requires an absolute request URL.") if raw_url.strip.empty?
+        target = parse_http_uri(raw_url)
+        forbidden("Host execution URLs cannot contain embedded credentials.") unless target.userinfo.nil?
+        append_query!(target, entries(draft["query"]))
+
+        method = string_value(draft["method"]).strip.upcase
+        method = "GET" if method.empty?
+        bad_request("Unsupported host execution HTTP method: #{method}") unless SUPPORTED_METHODS.include?(method)
+
+        headers = sanitize_headers(entries(draft["headers"]))
+        apply_header_auth!(draft["auth"], headers)
+        mode = infer_body_mode(draft)
+        body, content_type = prepare_body(draft, root, files, mode)
+        headers.delete("content-type") if mode == "formdata"
+        headers["content-type"] ||= [content_type] if content_type
+
+        timeout_ms = integer_value(root["timeoutMs"], DEFAULT_TIMEOUT_MS).clamp(MIN_TIMEOUT_MS, MAX_TIMEOUT_MS)
+        execute_with_redirects(method, target, headers, body, timeout_ms, draft["auth"])
+      rescue URI::InvalidURIError
+        bad_request("Host execution requires an absolute HTTP(S) request URL.")
+      end
+
+      def execute_with_redirects(method, current, headers, body, timeout_ms, auth)
+        Timeout.timeout(timeout_ms / 1000.0) do
+          (0..MAX_REDIRECTS).each do |redirect_count|
+            request_uri = current.dup
+            apply_query_auth!(auth, request_uri)
+            validated_ip = assert_allowed!(request_uri)
+
+            started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            response = perform_request(method, request_uri, headers, body, timeout_ms, validated_ip)
+            status = response[:status]
+
+            if status.between?(300, 399) && response[:location]
+              forbidden("Host execution exceeded the redirect safety limit.") if redirect_count == MAX_REDIRECTS
+              next_uri = request_uri.merge(response[:location])
+              forbidden("Host execution does not follow cross-origin redirects.") unless origin_of(next_uri) == origin_of(request_uri)
+              assert_allowed!(next_uri)
+              if status == 303
+                method = "GET"
+                body = "".b
+                headers = headers.reject { |name, _| name == "content-type" }
+              end
+              current = next_uri
+              next
+            end
+
+            elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+            return {
+              "status" => status,
+              "statusText" => response[:message],
+              "headers" => response[:headers],
+              "body" => response[:body].dup.force_encoding(Encoding::UTF_8).scrub,
+              "responseTime" => elapsed
+            }
+          end
+        end
+        forbidden("Host execution exceeded the redirect safety limit.")
+      rescue Timeout::Error
+        upstream("Host execution request timed out after #{timeout_ms} ms.")
+      rescue ExecutionError
+        raise
+      rescue StandardError => error
+        upstream("Host execution request failed: #{error.message}")
+      end
+
+      def perform_request(method, uri, headers, body, timeout_ms, validated_ip)
+        request = Net::HTTPGenericRequest.new(method, true, method != "HEAD", uri.request_uri, {})
+        headers.each do |name, values|
+          Array(values).each { |value| request.add_field(name, value) }
+        end
+        request.body = body unless body.empty? && %w[GET HEAD].include?(method)
+
+        response_body = "".b
+        response_headers = nil
+        status = nil
+        message = nil
+        location = nil
+        seconds = timeout_ms / 1000.0
+
+        # Disable environment proxies and pin the connection to the address validated above.
+        # Net::HTTP keeps +uri.host+ as the HTTP/TLS identity while +ipaddr+ controls the
+        # actual TCP destination, closing the DNS-preflight/connection-time lookup gap.
+        http = Net::HTTP.new(uri.host, uri.port, nil)
+        http.ipaddr = validated_ip
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = seconds
+        http.read_timeout = seconds
+        http.write_timeout = seconds if http.respond_to?(:write_timeout=)
+        http.start do |session|
+          session.request(request) do |response|
+            status = response.code.to_i
+            message = response.message.to_s
+            location = response["location"]
+            response_headers = response.to_hash.flat_map do |name, values|
+              Array(values).map { |value| [name, value] }
+            end
+            response.read_body do |chunk|
+              if response_body.bytesize + chunk.bytesize > MAX_EXECUTION_RESPONSE_BYTES
+                upstream("Host execution response exceeded the 10 MiB safety limit.")
+              end
+              response_body << chunk.b
+            end
+          end
+        end
+
+        { status:, message:, headers: response_headers || [], body: response_body, location: }
+      end
+
+      def assert_allowed!(uri)
+        forbidden("Host execution only allows HTTP(S) URLs.") unless uri.is_a?(URI::HTTP) && uri.host
+        forbidden("Host execution URLs cannot contain embedded credentials.") unless uri.userinfo.nil?
+        origin = origin_of(uri)
+        forbidden("Origin #{origin} is not allowed for host execution.") unless allowed_origins.include?(origin)
+
+        host = uri.host.to_s.downcase.delete_prefix("[").delete_suffix("]")
+        forbidden("Host execution blocks link-local and cloud metadata endpoints.") if METADATA_HOSTS.include?(host)
+        if ip_literal?(host)
+          forbidden("Host execution blocks link-local and cloud metadata endpoints.") if metadata_ip?(host)
+          return host
+        end
+
+        addresses = Addrinfo.getaddrinfo(host, uri.port, nil, :STREAM)
+        upstream("Host execution could not resolve target hostname.") if addresses.empty?
+        if addresses.any? { |address| metadata_ip?(address.ip_address) }
+          forbidden("Host execution blocks DNS resolutions to link-local and cloud metadata endpoints.")
+        end
+
+        addresses.first.ip_address
+      rescue SocketError
+        upstream("Host execution could not resolve target hostname.")
+      end
+
+      def parse_http_uri(raw)
+        uri = URI.parse(raw)
+        raise URI::InvalidURIError unless uri.is_a?(URI::HTTP) && uri.host
+
+        uri
+      end
+
+      def origin_of(uri)
+        default_port = uri.scheme == "https" ? 443 : 80
+        host = uri.host.to_s
+        host = "[#{host}]" if host.include?(":") && !host.start_with?("[")
+        port = uri.port == default_port ? "" : ":#{uri.port}"
+        "#{uri.scheme.downcase}://#{host.downcase}#{port}"
+      end
+
+      def append_query!(uri, values)
+        encoded = values.filter_map do |entry|
+          next unless entry_enabled?(entry)
+          key = string_value(entry["key"])
+          next if key.strip.empty?
+
+          URI.encode_www_form([[key, string_value(entry["value"])]])
+        end
+        return if encoded.empty?
+
+        uri.query = [uri.query, *encoded].compact.reject(&:empty?).join("&")
+      end
+
+      def sanitize_headers(values)
+        values.each_with_object({}) do |entry, result|
+          next unless entry_enabled?(entry)
+          name = string_value(entry["key"]).strip
+          next if name.empty?
+          normalized = name.downcase
+          next if UNSAFE_HEADERS.include?(normalized) || normalized.start_with?("proxy-", "sec-")
+          bad_request("Invalid host execution request header: #{name}") unless name.match?(/\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/)
+          value = string_value(entry["value"])
+          bad_request("Invalid host execution request header: #{name}") if value.include?("\r") || value.include?("\n")
+          (result[normalized] ||= []) << value
+        end
+      end
+
+      def set_header!(headers, raw_name, raw_value)
+        name = raw_name.to_s.strip
+        bad_request("Invalid host execution request header: #{raw_name}") if name.empty? || !name.match?(/\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/)
+        normalized = name.downcase
+        if UNSAFE_HEADERS.include?(normalized) || normalized.start_with?("proxy-", "sec-")
+          bad_request("Unsafe host execution request header: #{name}")
+        end
+        value = raw_value.to_s
+        bad_request("Invalid host execution request header: #{name}") if value.include?("\r") || value.include?("\n")
+        headers[normalized] = [value]
+      end
+
+      def apply_header_auth!(raw, headers)
+        auth = raw.is_a?(Hash) ? raw : {}
+        case string_value(auth["type"])
+        when "", "none", "inherit"
+          nil
+        when "bearer"
+          token = string_value(auth["token"])
+          set_header!(headers, "authorization", "Bearer #{token}") unless token.empty?
+        when "oauth2"
+          token = string_value(auth["accessToken"])
+          set_header!(headers, "authorization", "Bearer #{token}") unless token.empty?
+        when "basic"
+          credential = "#{string_value(auth["username"])}:#{string_value(auth["password"])}"
+          set_header!(headers, "authorization", "Basic #{Base64.strict_encode64(credential)}")
+        when "apiKey"
+          key = string_value(auth["key"]).strip
+          bad_request("API key authentication requires a key name.") if key.empty?
+          location = string_value(auth["in"])
+          location = "header" if location.empty?
+          case location
+          when "header"
+            set_header!(headers, key, string_value(auth["value"]))
+          when "query"
+            nil
+          when "cookie"
+            bad_request("Cookie authentication is not implemented by the Ruby host executor.")
+          else
+            bad_request("Unsupported API key location: #{location}")
+          end
+        else
+          bad_request("Authentication type #{string_value(auth["type"])} is not implemented by the Ruby host executor.")
+        end
+      end
+
+      def apply_query_auth!(raw, uri)
+        auth = raw.is_a?(Hash) ? raw : {}
+        return unless string_value(auth["type"]) == "apiKey" && string_value(auth["in"]) == "query"
+
+        key = string_value(auth["key"])
+        bad_request("API key authentication requires a key name.") if key.strip.empty?
+        encoded = URI.encode_www_form([[key, string_value(auth["value"])]])
+        uri.query = [uri.query, encoded].compact.reject(&:empty?).join("&")
+      end
+
+      def prepare_body(draft, envelope, files, mode)
+        explicit_type = string_value(draft["contentType"])
+        case mode
+        when "none"
+          ["".b, nil]
+        when "raw"
+          [string_value(draft["body"]).b, non_empty(explicit_type)]
+        when "json"
+          [string_value(draft["body"]).b, explicit_type.empty? ? "application/json" : explicit_type]
+        when "binary"
+          encoded = string_value(envelope["bodyBase64"])
+          bad_request("Binary host execution requires bodyBase64.") if encoded.empty?
+          data = Base64.strict_decode64(encoded)
+          nested = draft["binary"].is_a?(Hash) ? string_value(draft["binary"]["contentType"]) : ""
+          content_type = explicit_type.empty? ? (nested.empty? ? "application/octet-stream" : nested) : explicit_type
+          [data.b, content_type]
+        when "urlencoded"
+          pairs = entries(draft["urlencoded"]).filter_map do |entry|
+            next unless entry_enabled?(entry)
+            key = string_value(entry["key"])
+            next if key.strip.empty?
+            [key, string_value(entry["value"])]
+          end
+          [URI.encode_www_form(pairs).b, explicit_type.empty? ? "application/x-www-form-urlencoded" : explicit_type]
+        when "graphql"
+          graph = draft["graphql"]
+          bad_request("GraphQL body must be an object.") unless graph.is_a?(Hash)
+          variables_text = string_value(graph["variables"])
+          variables = variables_text.strip.empty? ? {} : JSON.parse(variables_text)
+          [JSON.generate({ "query" => string_value(graph["query"]), "variables" => variables }).b,
+           explicit_type.empty? ? "application/json" : explicit_type]
+        when "formdata"
+          build_multipart(draft, files)
+        else
+          bad_request("Body mode #{mode} is not implemented by the Ruby host executor.")
+        end
+      rescue ArgumentError
+        bad_request("Binary host execution bodyBase64 is invalid.") if mode == "binary"
+        raise
+      rescue JSON::ParserError
+        bad_request("GraphQL variables must be valid JSON.")
+      end
+
+      def build_multipart(draft, files)
+        boundary = "----flexdoc-ruby-#{SecureRandom.hex(12)}"
+        output = "".b
+        entries(draft["formData"]).each_with_index do |entry, index|
+          next unless entry_enabled?(entry)
+          key = string_value(entry["key"])
+          next if key.strip.empty?
+
+          if string_value(entry["type"]) == "file"
+            file = files[index]
+            bad_request("Host execution multipart file formData[#{index}] is missing.") unless file
+            filename = non_empty(file.filename.to_s) || non_empty(string_value(entry["fileName"])) || "upload.bin"
+            content_type = non_empty(file.content_type.to_s) || non_empty(string_value(entry["contentType"])) || "application/octet-stream"
+            bad_request("Host execution multipart Content-Type is invalid.") if content_type.include?("\r") || content_type.include?("\n")
+            output << "--#{boundary}\r\n"
+            output << "Content-Disposition: form-data; name=\"#{quote_multipart(key)}\"; filename=\"#{quote_multipart(filename)}\"\r\n"
+            output << "Content-Type: #{content_type}\r\n\r\n"
+            output << file.data.b << "\r\n"
+          else
+            output << "--#{boundary}\r\n"
+            output << "Content-Disposition: form-data; name=\"#{quote_multipart(key)}\"\r\n\r\n"
+            output << string_value(entry["value"]).b << "\r\n"
+          end
+        end
+        output << "--#{boundary}--\r\n"
+        [output, "multipart/form-data; boundary=#{boundary}"]
+      end
+
+      def infer_body_mode(draft)
+        explicit = string_value(draft["bodyMode"])
+        return explicit unless explicit.strip.empty?
+        binary = draft["binary"]
+        return "binary" if binary.is_a?(Hash) && !string_value(binary["fileName"]).empty?
+        return "formdata" unless entries(draft["formData"]).empty?
+        return "urlencoded" unless entries(draft["urlencoded"]).empty?
+        graph = draft["graphql"]
+        if graph.is_a?(Hash) && (!string_value(graph["query"]).empty? || !string_value(graph["variables"]).empty?)
+          return "graphql"
+        end
+        body = string_value(draft["body"])
+        return "none" if body.empty?
+
+        string_value(draft["contentType"]).downcase.include?("json") ? "json" : "raw"
+      end
+
+      def entries(raw)
+        raw.is_a?(Array) ? raw.select { |entry| entry.is_a?(Hash) } : []
+      end
+
+      def entry_enabled?(entry)
+        entry["enabled"] != false
+      end
+
+      def string_value(raw)
+        case raw
+        when nil then ""
+        when String then raw
+        when true, false, Numeric then raw.to_s
+        else JSON.generate(raw)
+        end
+      end
+
+      def integer_value(raw, fallback)
+        Integer(raw || fallback)
+      rescue ArgumentError, TypeError, RangeError
+        fallback
+      end
+
+      def non_empty(value)
+        value.nil? || value.empty? ? nil : value
+      end
+
+      def quote_multipart(value)
+        value.to_s.delete("\r\n").gsub("\\") { "\\\\" }.gsub('"') { '\\"' }
+      end
+
+      def ip_literal?(host)
+        IPAddr.new(host)
+        true
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+
+      def metadata_ip?(value)
+        ip = IPAddr.new(value)
+        return true if LINK_LOCAL_V4.include?(ip) || LINK_LOCAL_V6.include?(ip)
+        if ip.ipv6? && (ip.to_i >> 32) == 0xFFFF
+          mapped = IPAddr.new(ip.to_i & 0xFFFF_FFFF, Socket::AF_INET)
+          return true if LINK_LOCAL_V4.include?(mapped)
+        end
+        false
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+    end
+  end
+end

data/lib/prauga/flexdoc/rack_app.rb

@@ -1,11 +1,19 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Prauga
   module FlexDoc
     # Rack application that serves FlexDoc routes from a {Host}.
     class RackApp
       # @param host [Host] host backing the Rack application
-      def initialize(host = Host.new)
+      # @param host_execution_protected [Boolean] explicit acknowledgement that the docs/execute surface is protected by application auth/middleware
+      def initialize(host = Host.new, host_execution_protected: false)
+        if host.execution_available? && !host_execution_protected
+          raise ArgumentError,
+                "FlexDoc Rack host execution requires host_execution_protected: true after configuring application auth/middleware; the origin allowlist is not authentication."
+        end
+
         @host = host
       end
 
@@ -15,8 +23,136 @@ module Prauga
       # @return [Array]
       def call(env)
         path = "#{env.fetch("SCRIPT_NAME", "")}#{env.fetch("PATH_INFO", "")}"
+        if path == @host.execute_path
+          return not_found unless env.fetch("REQUEST_METHOD", "GET") == "POST" && @host.execution_available?
+
+          return execute(env)
+        end
+
         @host.response_for_path(path).rack
       end
+
+      private
+
+      def execute(env)
+        marker = env["HTTP_X_FLEXDOC_EXECUTE"]
+        return execution_error(403, "Missing X-FlexDoc-Execute header.") unless marker == "1"
+
+        raw = read_bounded(env)
+        content_type = env.fetch("CONTENT_TYPE", "")
+        envelope, files = if content_type.split(";", 2).first.to_s.strip.casecmp("application/json").zero?
+                            [parse_json_object(raw, "Host execution body must be valid UTF-8 JSON object."), {}]
+                          elsif content_type.split(";", 2).first.to_s.strip.casecmp("multipart/form-data").zero?
+                            parse_multipart(content_type, raw)
+                          else
+                            return execution_error(400, "Host execution requires application/json or multipart/form-data.")
+                          end
+        result = @host.host_execution.handle(
+          marker: marker,
+          envelope:,
+          files:
+        )
+        execution_json(result.status, result.body)
+      rescue EnvelopeError => error
+        execution_error(400, error.message)
+      end
+
+      def read_bounded(env)
+        declared = env["CONTENT_LENGTH"].to_i
+        if declared > HostExecution::MAX_EXECUTION_REQUEST_BYTES
+          raise EnvelopeError, "Host execution request exceeded the 32 MiB safety limit."
+        end
+        input = env.fetch("rack.input")
+        raw = input.read(HostExecution::MAX_EXECUTION_REQUEST_BYTES + 1).to_s.b
+        if raw.bytesize > HostExecution::MAX_EXECUTION_REQUEST_BYTES
+          raise EnvelopeError, "Host execution request exceeded the 32 MiB safety limit."
+        end
+        raw
+      end
+
+      def parse_json_object(raw, message)
+        text = raw.dup.force_encoding(Encoding::UTF_8)
+        raise EnvelopeError, message unless text.valid_encoding?
+
+        value = JSON.parse(text)
+        raise EnvelopeError, message unless value.is_a?(Hash)
+
+        value
+      rescue JSON::ParserError
+        raise EnvelopeError, message
+      end
+
+      def parse_multipart(content_type, raw)
+        boundary = content_type[/boundary=(?:"([^"]+)"|([^;]+))/, 1] || content_type[/boundary=(?:"([^"]+)"|([^;]+))/, 2]
+        raise EnvelopeError, "Host execution multipart body is invalid." if boundary.to_s.strip.empty?
+
+        descriptor = nil
+        files = {}
+        delimiter = "--#{boundary}".b
+        raw.split(delimiter).each do |segment|
+          next if segment.empty?
+          segment = segment.sub(/\A\r\n/n, "")
+          break if segment.start_with?("--")
+          segment = segment.sub(/\r\n\z/n, "")
+          header_blob, data = segment.split("\r\n\r\n".b, 2)
+          raise EnvelopeError, "Host execution multipart body is invalid." unless data
+
+          headers = header_blob.split("\r\n".b).each_with_object({}) do |line, result|
+            name, value = line.split(":", 2)
+            next unless value
+            result[name.to_s.downcase] = value.to_s.strip
+          end
+          disposition = headers.fetch("content-disposition", "")
+          name = disposition[/\bname="([^"]*)"/, 1].to_s
+          filename = disposition[/\bfilename="([^"]*)"/, 1].to_s
+
+          if name == "descriptor"
+            raise EnvelopeError, "Host execution multipart request contains multiple descriptors." if descriptor
+            descriptor = data
+            next
+          end
+
+          match = name.match(/\AformData\[(\d+)\]\z/)
+          next unless match
+          index = match[1].to_i
+          if files.key?(index)
+            raise EnvelopeError, "Host execution multipart request contains duplicate formData[#{index}] parts."
+          end
+          files[index] = HostExecutionFile.new(
+            filename:,
+            content_type: headers.fetch("content-type", ""),
+            data: data.b
+          )
+        end
+
+        raise EnvelopeError, "Host execution multipart request requires a descriptor." unless descriptor
+        [parse_json_object(descriptor, "Host execution multipart descriptor must be valid UTF-8 JSON object."), files]
+      rescue ArgumentError
+        raise EnvelopeError, "Host execution multipart body is invalid."
+      end
+
+      def execution_error(status, message)
+        execution_json(status, { "error" => message })
+      end
+
+      def execution_json(status, payload)
+        body = JSON.generate(payload)
+        [
+          status,
+          {
+            "content-type" => "application/json; charset=utf-8",
+            "content-length" => body.bytesize.to_s,
+            "cache-control" => "no-store"
+          },
+          [body]
+        ]
+      end
+
+      def not_found
+        Response.new(status: 404, content_type: "text/plain; charset=utf-8", body: "Not Found", cache_control: nil).rack
+      end
+
+      class EnvelopeError < StandardError; end
     end
   end
 end