aspera-cli 4.27.5 → 4.28.0

data/lib/aspera/cli/extended_value.rb

@@ -6,7 +6,10 @@ require 'aspera/environment'
 require 'aspera/yaml'
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/secret_hider'
 require 'aspera/cli/error'
+require 'aspera/cli/prompt'
+require 'aspera/cli/security'
 require 'json'
 require 'base64'
 require 'zlib'
@@ -73,6 +76,16 @@ module Aspera
           Aspera.assert(value.empty?, type: BadArgument) { "no value allowed for extended value type: #{ext_type}" }
         end
 
+        # Ask the user for a secret: on a web page if the user interface is graphical (option `ui`), else on terminal
+        # @param prompt [String] Name of the secret, empty for default
+        # @return [String] The secret
+        def read_secret(prompt)
+          prompt = 'secret' if prompt.empty?
+          return Prompt.prompt_user_input(prompt, sensitive: true) unless Environment.instance.url_method.eql?(:graphical)
+          require 'aspera/cli/web_secret'
+          WebSecret.ask(prompt)
+        end
+
         def read_stdin(mode)
           case mode
           when '' then $stdin.read
@@ -95,7 +108,7 @@ module Aspera
           base64: lambda { |i| Base64.decode64(i) },
           csvt:   lambda { |i| ExtendedValue.decode_csvt(i) },
           env:    lambda { |i| ENV.fetch(i, nil) },
-          file:   lambda { |i| File.read(File.expand_path(i)) },
+          file:   lambda { |i| File.read(Security.instance.readable_path(i)) },
           uri:    lambda { |i| UriReader.read(i) },
           json:   lambda { |i| ExtendedValue.JSON_parse(i) },
           lines:  lambda { |i| i.split("\n") },
@@ -105,7 +118,7 @@ module Aspera
           re:     lambda { |i| Regexp.new(i, Regexp::MULTILINE) },
           ruby:   lambda { |i| Environment.secure_eval(i, __FILE__, __LINE__) },
           s:      lambda(&:to_s),
-          secret: lambda { |i| prompt = i.empty? ? 'secret' : i; $stdin.getpass("#{prompt}> ") }, # rubocop:disable Style/Semicolon
+          secret: lambda { |i| ExtendedValue.read_secret(i) },
           stdin:  lambda { |i| ExtendedValue.read_stdin(i) },
           yaml:   lambda { |i| YAML.safe_load(i) },
           zlib:   lambda { |i| Zlib::Inflate.inflate(i) },
@@ -170,8 +183,15 @@ module Aspera
           break if SPECIAL_HANDLERS.include?(handler)
         end
         Log.log.trace1 { "evaluating: #{handlers_reversed}, value: #{value.class}:#{value}" }
-        handlers_reversed.each do |handler|
+        handlers_reversed.each_with_index do |handler, index|
+          Security.instance.check_extended_value(handler)
+          # The value read by the previous handler may be a secret
+          Security.instance.check_secret_processing("@#{handler}") { SecretHider.instance.contains_secret?(value) } if index.positive?
           value = @handlers[handler].call(value)
+          # Values read from a secret source are hidden wherever they appear: logs, results
+          if SECRET_HANDLERS.include?(handler)
+            value.is_a?(String) ? SecretHider.instance.add_secret_values(value) : SecretHider.instance.add_secrets_in(value)
+          end
         rescue => e
           raise BadArgument, "Evaluation of #{handler} for #{context}: #{e.message}"
         end
@@ -184,7 +204,10 @@ module Aspera
         while (m = value.match(@regex_extend))
           sub_value = "@#{m[2]}:#{m[3]}"
           Log.log.debug { "evaluating #{sub_value}" }
-          value = "#{m[1]}#{evaluate(sub_value, context: 'composite extended value')}#{m[4]}"
+          sub_value = evaluate(sub_value, context: 'composite extended value')
+          # In a text, a secret is not the whole value
+          Security.instance.check_secret_processing('@extend') { SecretHider.instance.contains_secret?(sub_value) }
+          value = "#{m[1]}#{sub_value}#{m[4]}"
         end
         return value
       end
@@ -199,10 +222,12 @@ module Aspera
       # :extend includes processing of other handlers in itself
       # :val keeps the value intact
       SPECIAL_HANDLERS = %i[extend val].freeze
+      # Handlers that read a secret
+      SECRET_HANDLERS = %i[secret vault].freeze
 
       # Array and Hash types:
       DEFAULT_PARSER_TYPES = [Array, Hash].freeze
-      private_constant :MARKER_START, :MARKER_END, :MARKER_IN_END, :SPECIAL_HANDLERS, :DEFAULT_PARSER_TYPES
+      private_constant :MARKER_START, :MARKER_END, :MARKER_IN_END, :SPECIAL_HANDLERS, :SECRET_HANDLERS, :DEFAULT_PARSER_TYPES
     end
   end
 end

data/lib/aspera/cli/formatter.rb

@@ -5,6 +5,7 @@ require 'aspera/schema/registry'
 require 'aspera/cli/option_declarator'
 require 'aspera/cli/special_values'
 require 'aspera/cli/terminal_formatter'
+require 'aspera/cli/table_fitter'
 require 'aspera/preview/terminal'
 require 'aspera/secret_hider'
 require 'aspera/environment'
@@ -12,12 +13,11 @@ require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/markdown'
 require 'aspera/dot_container'
-require 'terminal-table'
 require 'tty-spinner'
+require 'json'
 require 'yaml'
 require 'pp'
 require 'csv'
-require 'word_wrap'
 require 'aspera/rainbow'
 using Rainbow
 
@@ -37,10 +37,12 @@ module Aspera
       SINGLE_OBJECT_COLUMN_NAMES = %i[field value].freeze
       # Terminal: vertical separator for list of strings.
       STR_LST_SEP_VERT = "\n"
+      # Sub-options of option `out`, for help and errors
+      OUT_SUB_OPTIONS = 'format, level, file, fields, select, query, table[.pivot], flat, secrets, colors, utf8, img'
 
-      private_constant :FIELDS_LESS, :DISPLAY_FORMATS, :DISPLAY_LEVELS, :SINGLE_OBJECT_COLUMN_NAMES, :STR_LST_SEP_VERT
+      private_constant :FIELDS_LESS, :DISPLAY_FORMATS, :DISPLAY_LEVELS, :SINGLE_OBJECT_COLUMN_NAMES, :STR_LST_SEP_VERT, :OUT_SUB_OPTIONS
 
-      option :out,          description: 'Output rendering options (dot-notation: format, level, file, fields, select, table[.pivot], flat, secrets, colors, utf8, img)', schema: Schema::Registry::OUT_OPTIONS
+      option :out,          description: "Output rendering options (dot-notation: #{OUT_SUB_OPTIONS})", schema: Schema::Registry::OUT_OPTIONS
       option :display,      description: 'Output only some information', allowed: DISPLAY_LEVELS, default: :data, deprecation: {last: '4.27.0', message: 'use --out.level'}
       option :format,       description: 'Output format (also: --out.format)', allowed: DISPLAY_FORMATS, default: :table
       option :output,       description: 'Destination for results', deprecation: {last: '4.27.0', message: 'use --out.file'}
@@ -56,35 +58,23 @@ module Aspera
 
       class << self
         # Replace special values with a readable version on terminal
+        # @param input_hash            [Hash]   Object to display (not modified)
+        # @param string_list_separator [String] Separator of the items of a list of strings
+        # @return [Hash] Copy of input_hash with special values replaced, also in nested objects
         def replace_specific_for_terminal(input_hash, string_list_separator)
-          hash_to_process = [input_hash]
-          until hash_to_process.empty?
-            current = hash_to_process.pop
-            current.each do |key, value|
-              case value
-              when NilClass
-                current[key] = TerminalFormatter.special_format('null')
-              when String
-                current[key] = TerminalFormatter.special_format('empty string') if value.empty?
-              when Proc
-                current[key] = TerminalFormatter.special_format('lambda')
-              when Array
-                if value.empty?
-                  current[key] = TerminalFormatter.special_format('empty list')
-                elsif value.all?(String)
-                  current[key] = value.join(string_list_separator)
-                else
-                  value.each do |item|
-                    hash_to_process.push(item) if item.is_a?(Hash)
-                  end
-                end
-              when Hash
-                if value.empty?
-                  current[key] = TerminalFormatter.special_format('empty dict')
-                else
-                  hash_to_process.push(value)
-                end
+          input_hash.transform_values do |value|
+            case value
+            when NilClass then TerminalFormatter.special_format('null')
+            when String then value.empty? ? TerminalFormatter.special_format('empty string') : value
+            when Proc then TerminalFormatter.special_format('lambda')
+            when Array
+              if value.empty? then TerminalFormatter.special_format('empty list')
+              elsif value.all?(String) then value.join(string_list_separator)
+              else value.map { |item| item.is_a?(Hash) ? replace_specific_for_terminal(item, string_list_separator) : item }
               end
+            when Hash
+              value.empty? ? TerminalFormatter.special_format('empty dict') : replace_specific_for_terminal(value, string_list_separator)
+            else value
             end
           end
         end
@@ -102,8 +92,12 @@ module Aspera
         @options = {}
         # Last value of option `out`
         @out_dispatched = {}
-        # Colors auto-detected by Rainbow at load time, restored when `--out.colors` is reset
+        # Colors auto-detected at load time (aspera/rainbow), restored when `--out.colors` is reset
         @colors_detected = Rainbow.enabled
+        # Value of `--out.colors`: `true`, `false`, or `nil` for detection
+        @colors = nil
+        # `true` if results are written to a file (`--out.file`)
+        @output_to_file = false
         @spinner = nil
       end
 
@@ -185,9 +179,12 @@ module Aspera
             when :flat     then @parser.set_option(:flat_hash,    v, warn_deprecation: false)
             when :secrets  then @parser.set_option(:show_secrets, v, warn_deprecation: false)
             when :img      then @parser.set_option(:image,        v, warn_deprecation: false)
-            when :colors   then Rainbow.enabled = v.nil? ? @colors_detected : v
+            when :query    then self.query = v
             when :utf8     then Environment.unicode = v
-            else Aspera.error_unexpected_value(k) { 'out sub-option (format, level, file, fields, select, table[.pivot], flat, secrets, colors, utf8, img)' }
+            when :colors
+              @colors = v
+              apply_colors
+            else Aspera.error_unexpected_value(k) { "out sub-option (#{OUT_SUB_OPTIONS})" }
             end
           end
           return
@@ -199,11 +196,13 @@ module Aspera
           # The default output level depends on the format, unless the level is set explicitly (e.g. `--out.level`)
           @options[:display] = value.eql?(:table) ? :info : :data if @parser.nil? || @parser.option_def(:display).source.eql?(:default)
         when :output
-          $stdout = if value.eql?('-')
-            STDOUT # rubocop:disable Style/GlobalStdStream
-          else
+          @output_to_file = !value.eql?('-')
+          $stdout = if @output_to_file
             File.open(value, 'w')
+          else
+            STDOUT # rubocop:disable Style/GlobalStdStream
           end
+          apply_colors
         when :image
           # get list if key arguments of method
           allowed_options = Preview::Terminal.method(:build).parameters.select { |i| i[0].eql?(:key) }.map { |i| i[1] }
@@ -214,6 +213,28 @@ module Aspera
         nil
       end
 
+      # Enable colors as set by `--out.colors`, else as detected, but not when results go to a file
+      # @return [nil]
+      def apply_colors
+        Rainbow.enabled = @colors.nil? ? @colors_detected && !@output_to_file : @colors
+        nil
+      end
+
+      # Set the query of `--out.query`, syntax of a JMESPath expression is checked before the command is executed
+      # @param expression [String, Proc, nil] JMESPath expression, or Ruby lambda, or `nil` for none
+      def query=(expression)
+        Aspera.assert_type(expression, String, Proc, NilClass, type: Cli::BadArgument) { 'out.query' }
+        if expression.is_a?(String)
+          require 'jmespath'
+          begin
+            JMESPath::Parser.new.parse(expression)
+          rescue JMESPath::Errors::SyntaxError => e
+            raise Cli::BadArgument, "JMESPath: #{e.message}"
+          end
+        end
+        @options[:query] = expression
+      end
+
       # Main output method for displaying messages to the user
       # This method is used by Result classes to output formatted data
       # @param message_level [Symbol] The level of the message - must be one of: :data, :info, :error
@@ -238,14 +259,15 @@ module Aspera
         display_message(:info, status, **kwargs)
       end
 
-      # Check if secrets should be hidden
+      # Check if secrets should be hidden: always, unless explicitly requested (`--out.secrets=yes`)
       def hide_secrets?
-        !@options[:show_secrets] && !@options[:display].eql?(:data)
+        !@options[:show_secrets]
       end
 
-      # Hides secrets in Hash or Array
+      # @param data [Object] Data of a result
+      # @return [Object] Copy of data with secrets hidden (by key name, and declared values), or data itself if secrets are shown
       def hide_secrets(data)
-        SecretHider.instance.deep_remove_secret(data) if hide_secrets?
+        hide_secrets? ? SecretHider.instance.hidden_copy(data) : data
       end
 
       # Display results using the Visitor pattern
@@ -260,8 +282,10 @@ module Aspera
         Log.dump(:data, result.data, level: :trace1)
         Log.dump(:fields, result.fields, level: :trace1)
 
-        # Hide secrets in data
-        hide_secrets(result.data)
+        # Hide secrets in a copy of data: it may be shared (e.g. a preset of the configuration)
+        result = result.with_data(hide_secrets(result.data)) if hide_secrets?
+        # Secrets are hidden before the expression may rename their keys
+        result = query_result(result) unless @options[:query].nil?
 
         # Use the Visitor pattern: delegate formatting to the result object
         result.format(self)
@@ -357,9 +381,9 @@ module Aspera
         # no filter for single element
         return data unless data.is_a?(Array)
         # by default, keep all data intact
-        return data if @options[:fields].eql?(SpecialValues::DEF) && @options[:select].nil?
+        return data if @options[:fields].eql?(SpecialValues::DEF) && [nil, {}].include?(@options[:select])
         Aspera.assert_array_all(data, Hash) { 'filter or select' }
-        filter_columns_on_select(data)
+        data = filter_columns_on_select(data)
         return data if @options[:fields].eql?(SpecialValues::DEF)
         selected_fields = compute_fields(data, @options[:fields])
         return data.map { |i| i[selected_fields.first] } if selected_fields.length == 1
@@ -367,20 +391,54 @@ module Aspera
       end
 
       # Filter the list of items on the select option
-      # @param data [Array<Hash>] List of items
-      # @return [nil]
+      # @param data [Array<Hash>] List of items (not modified)
+      # @return [Array<Hash>] Selected items
       def filter_columns_on_select(data)
         case @options[:select]
         when Proc
           begin
-            data.select! { |i| @options[:select].call(i) }
+            data.select { |i| @options[:select].call(i) }
           rescue StandardError => e
             raise Cli::BadArgument, "Error in user-provided ruby lambda code during select: #{e.message}"
           end
         when Hash
-          @options[:select].each { |k, v| data.select! { |i| i[k].eql?(v) } }
+          @options[:select].reduce(data) { |items, (k, v)| items.select { |i| i[k].eql?(v) } }
+        else data
         end
-        nil
+      end
+
+      # Apply the query of `--out.query` to the data of an object or list result
+      # @param result [Result] Result of command
+      # @return [Result] Result with the value of the expression, or `result` if no query, or not an object or list
+      def query_result(result)
+        return result if @options[:query].nil?
+        data =
+          case result
+          when Result::SingleObject, Result::ObjectList, Result::ValueList then result.data
+          when Result::Empty then []
+          else return result
+          end
+        value =
+          if @options[:query].is_a?(Proc)
+            begin
+              # JSON view of the value, as with JMESPath: keys, and objects like `Time`, become strings
+              JSON.parse(JSON.generate(@options[:query].call(data)))
+            rescue StandardError => e
+              raise Cli::BadArgument, "Error in user-provided ruby lambda code during query: #{e.message}"
+            end
+          else
+            begin
+              JMESPath.search(@options[:query], data)
+            rescue JMESPath::Errors::Error => e
+              raise Cli::BadArgument, "JMESPath: #{e.message}"
+            end
+          end
+        # Lists of objects, and lists of scalar values are displayed as tables
+        return Result.auto(value) unless value.is_a?(Array) && !value.all?(Hash) && !value.all? { |i| Result::SCALAR_TYPES.include?(i.class) }
+        Aspera.assert(Result::STRUCTURED_FORMATS.include?(@options[:format]), type: Cli::BadArgument) do
+          "Result of query is a list of lists or of mixed values: use a JMESPath multi-select hash (e.g. `[].{a: x, b: y}`), or a format among: #{Result::STRUCTURED_FORMATS.join(', ')}"
+        end
+        Result.new(data: value)
       end
 
       # Displays a list of objects
@@ -396,11 +454,11 @@ module Aspera
           display_message(:info, TerminalFormatter.special_format('empty')) if @options[:format].eql?(:table)
           return
         end
-        filter_columns_on_select(object_array)
+        object_array = filter_columns_on_select(object_array)
         format_style = @options[:table_style].symbolize_keys
         string_list_separator = format_style.delete(:str_lst_sep) || STR_LST_SEP_VERT
         # convert data to string, and keep only display fields
-        object_array.each { |i| self.class.replace_specific_for_terminal(i, string_list_separator) }
+        object_array = object_array.map { |i| self.class.replace_specific_for_terminal(i, string_list_separator) }
         # if table has only one element, and only one field, display the value
         if object_array.length == 1 && fields.length == 1
           Log.log.debug("single element, field: #{fields.first}")
@@ -423,22 +481,26 @@ module Aspera
         case @options[:format]
         when :table
           format_style[:border] = :unicode_round if Environment.terminal_supports_unicode?
+          # fit in the requested maximum width, or in the terminal
+          width = format_style.delete(:width) || Environment.terminal_columns
           if single || @options[:multi_single].eql?(:yes) ||
               (@options[:multi_single].eql?(:single) && final_table_rows.length.eql?(1))
             # display multiple objects as multiple transposed tables
             final_table_rows.each do |row|
-              display_message(:data, Terminal::Table.new(
+              display_message(:data, TableFitter.table(
                 headings:  SINGLE_OBJECT_COLUMN_NAMES,
                 rows:      fields.zip(row),
-                style:     format_style
+                style:     format_style,
+                width:     width
               ))
             end
           else
             # display the table as single table
-            display_message(:data, Terminal::Table.new(
+            display_message(:data, TableFitter.table(
               headings:  fields,
               rows:      final_table_rows,
-              style:     format_style
+              style:     format_style,
+              width:     width
             ))
           end
         when :csv

data/lib/aspera/cli/hints.rb

@@ -137,7 +137,6 @@ module Aspera
             matches = hint[:match]
             matches = [matches] unless matches.is_a?(Array)
             matches.each do |m|
-              Aspera.assert_values(m.class, [String, Regexp])
               case m
               when String
                 next unless message.eql?(m)

data/lib/aspera/cli/http.rb

@@ -7,7 +7,7 @@ require 'aspera/line_logger'
 require 'aspera/schema/registry'
 require 'aspera/cli/option_declarator'
 require 'aspera/rest'
-require 'aspera/oauth'
+require 'aspera/oauth/client/factory'
 require 'aspera/ssl'
 require 'openssl'
 
@@ -28,7 +28,7 @@ module Aspera
 
       # `on_set` callbacks are methods of the instance given as `target:` to `declare_options`
       option :insecure,           description: 'HTTP/S: Do not validate any certificate',                   allowed: Type::BOOLEAN, default: false, on_set: :insecure=
-      option :ignore_certificate, description: 'HTTP/S: Do not validate certificate for these URLs',        allowed: [Array, NilClass],             on_set: :ignore_cert_host_port=
+      option :ignore_certificate, description: 'HTTP/S: Do not validate certificate for these URLs',        allowed: Type::STRING_ARRAY,            on_set: :ignore_cert_host_port=
       option :warn_insecure,      description: 'HTTP/S: Issue a warning if certificate is ignored',         allowed: Type::BOOLEAN, default: true,  on_set: :warn_insecure=
       option :cert_stores,        description: 'HTTP/S: List of folder with trusted certificates',          allowed: Type::STRING_ARRAY,            on_set: :trusted_cert_locations=
       option :http_options,       schema: Schema::Registry::HTTP_OPTIONS,                                                                           on_set: :http_options=
@@ -87,9 +87,10 @@ module Aspera
       # Per-URL certificate ignore list
       # ------------------------------------------------------------------
 
-      # @param url_list [Array<String>, nil] URLs for which certificate is not validated
+      # @param url_list [Array<String>] URLs for which certificate is not validated
       def ignore_cert_host_port=(url_list)
-        @ignore_cert_host_port = (url_list || []).map do |url|
+        Aspera.assert_type(url_list, Array) { 'ignore certificate URLs' }
+        @ignore_cert_host_port = url_list.map do |url|
           uri = URI.parse(url)
           Aspera.assert(uri.scheme.eql?('https')) { "Expecting https scheme: #{url}" }
           [uri.host, uri.port].freeze
@@ -148,7 +149,7 @@ module Aspera
           paths_to_add.each do |p|
             pp = [File.realpath(p)]
             if File.directory?(p)
-              pp = Dir.entries(p)
+              pp = Dir.children(p)
                 .map { |e| File.realpath(File.join(p, e)) }
                 .select { |entry| File.file?(entry) }
                 .select { |entry| CERT_EXT.any? { |ext| entry.end_with?(ext) } }

data/lib/aspera/cli/info.rb

@@ -12,14 +12,20 @@ module Aspera
       GEM_URL  = "https://rubygems.org/gems/#{GEM_NAME}"
       SRC_URL  = 'https://github.com/IBM/aspera-cli'
       CONTAINER = 'docker.io/martinlaurent/ascli'
+      # Minimum required Ruby version: single reference, used by `required_ruby_version` in gemspec file and by the documentation
+      # Policy: a Ruby version is supported until 18 months after its end of official support
+      # Consistency with other files: `rake tools:check_ruby`
+      RUBY_MINIMUM_VERSION = '3.2'
       # Set this to warn in advance when minimum required ruby version will increase
-      # See also required_ruby_version in gemspec file
-      RUBY_FUTURE_MINIMUM_VERSION = '3.2'
+      RUBY_FUTURE_MINIMUM_VERSION = '3.3'
       # Version with which this version of CLI was tested
       SDK_VERSION = '1.1.9'
-      # RubyInstaller version packaged in the Windows installer zip (release tag without `RubyInstaller-` prefix)
+      # Ruby version with which this version of CLI was tested, packaged in container image and portable packages
+      RUBY_TESTED_VERSION = '4.0.7'
+      # Suffix of the RubyInstaller release of `RUBY_TESTED_VERSION`, packaged in the Windows zip
+      # (release tag: `RubyInstaller-<Ruby version><suffix>`)
       # https://github.com/oneclick/rubyinstaller2/releases
-      WINDOWS_RUBY_INSTALLER_VERSION = '4.0.7-1'
+      WINDOWS_RUBY_INSTALLER_EXT = '-2'
     end
   end
 end

data/lib/aspera/cli/mailer.rb

@@ -58,7 +58,7 @@ module Aspera
         %i[server port domain].each do |n|
           Aspera.assert(smtp.key?(n)) { "Missing mandatory smtp parameter: #{n}" }
         end
-        Log.dump(:smtp, smtp.reject { |k, _| k == :password })
+        Log.dump(:smtp, smtp)
         return smtp
       end
 

data/lib/aspera/cli/mcp/http_servlet.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+# cspell:ignore webrick
+
+require 'aspera/log'
+require 'aspera/servlet_helpers'
+require 'aspera/cli/web_secret'
+require 'json'
+require 'openssl'
+require 'stringio'
+require 'webrick'
+
+module Aspera
+  module Cli
+    module Mcp
+      # Servlet of the HTTP transport of the MCP server, on WEBrick (already a project dependency), mounted on `/` of a WebServerSimple.
+      # Rack 3 removed Rack::Handler: the servlet calls the Rack app of the MCP transport directly.
+      #
+      # Routes:
+      #   /                     Discovery: server metadata, no authentication
+      #   /.well-known/oauth-authorization-server, /oauth/*: OAuth 2.0 PKCE server, if enabled
+      #   /secret/<id>          Secret pages (see WebSecret), protected by their access code
+      #   other paths           MCP endpoints: static Bearer token or OAuth access token, if configured
+      # Requests that a web page could send are refused on all paths (see ServletHelpers#check_request),
+      # as the MCP transport does for its own endpoints, with the same `allowed_hosts` and `allowed_origins`.
+      class HttpServlet < WEBrick::HTTPServlet::AbstractServlet
+        include ServletHelpers
+
+        # Paths with a JSON body, not handled by the MCP transport
+        JSON_PATHS = %w[/oauth/register].freeze
+        private_constant :JSON_PATHS
+
+        # @param server  [WEBrick::HTTPServer]
+        # @param options [Hash] With keys:
+        #   app:          [#call]                    Rack app of the MCP transport
+        #   server_info:  [Hash]                     Name, version and description of the server, for discovery
+        #   web_secret:   [WebSecret]                Secret pages
+        #   auth_token:   [String, nil]              Static Bearer token, if any
+        #   oauth_server: [OAuth::Server::Pkce, nil] OAuth server, if enabled
+        #   allowed_hosts:   [Array<String>, nil]    Other values accepted in header `Host`
+        #   allowed_origins: [Array<String>, nil]    Other values accepted in header `Origin`
+        def initialize(server, options)
+          super(server)
+          @app          = options.fetch(:app)
+          @server_info  = options.fetch(:server_info)
+          @web_secret   = options.fetch(:web_secret)
+          @auth_token   = options[:auth_token]
+          @oauth_server = options[:oauth_server]
+          @allowed      = {allowed_hosts: Array(options[:allowed_hosts]), allowed_origins: Array(options[:allowed_origins])}
+        end
+
+        def do_GET(req, res) = dispatch(req, res)
+        def do_POST(req, res) = dispatch(req, res)
+        def do_DELETE(req, res) = dispatch(req, res)
+
+        private
+
+        def dispatch(req, res)
+          check_request(req, json: JSON_PATHS.include?(req.path), **@allowed)
+          case req.path
+          when '/'
+            # Discovery endpoint (server metadata, no auth required)
+            json_response(res, 200, @server_info)
+          when '/.well-known/oauth-authorization-server' then oauth(req, res, :handle_discovery)
+          when '/oauth/register'                          then oauth(req, res, :handle_register, post_only: true)
+          when '/oauth/authorize'                         then oauth(req, res, :handle_authorize)
+          when '/oauth/token'                             then oauth(req, res, :handle_token, post_only: true)
+          when ->(path) { path.start_with?(WebSecret::PATH_PREFIX) }
+            # Page opened by the user in a browser (no bearer token), protected by the access code
+            @web_secret.handle(req, res)
+          else
+            # All other paths are MCP endpoints: require authorization
+            return unauthorized(res) unless authorized?(req)
+            call_app(req, res)
+          end
+        rescue WEBrick::HTTPStatus::Error => e
+          Log.log.warn { "Rejected request: #{e.message}" }
+          json_error(res, e.code, 'invalid_request', e.message)
+        end
+
+        # Route to the OAuth server, if enabled
+        # @param handler   [Symbol]  Method of the OAuth server
+        # @param post_only [Boolean] Accept only method POST
+        def oauth(req, res, handler, post_only: false)
+          return json_error(res, 405, 'method_not_allowed') if post_only && !req.request_method.eql?('POST')
+          return json_error(res, 404, 'not_found') if @oauth_server.nil?
+          @oauth_server.public_send(handler, req, res)
+        end
+
+        # @return [Boolean] true if no auth is configured, or the request carries a valid token
+        def authorized?(req)
+          return true if @auth_token.nil? && @oauth_server.nil?
+          token = authorization(req, 'Bearer')
+          return false if token.nil?
+          # Static token, or OAuth access token
+          (!@auth_token.nil? && OpenSSL.secure_compare(token, @auth_token.to_s)) ||
+            (!@oauth_server.nil? && @oauth_server.access_token_valid?(token))
+        end
+
+        def unauthorized(res)
+          json_error(res, 401, 'Unauthorized', headers: {'WWW-Authenticate' => @oauth_server.nil? ? 'Bearer' : @oauth_server.www_authenticate_header})
+        end
+
+        # Call the Rack app, with streaming of the response body if it is a callable (SSE)
+        def call_app(req, res)
+          status, headers, rack_body = @app.call(rack_env(req))
+          res.status = status
+          headers.each { |k, v| res[k] = v }
+          if rack_body.respond_to?(:call)
+            res.chunked = true
+            res.body = proc do |socket|
+              stream = Object.new
+              stream.define_singleton_method(:write) { |data| socket.write(data) }
+              stream.define_singleton_method(:flush) { socket.flush rescue nil }
+              stream.define_singleton_method(:close) { socket.close rescue nil }
+              rack_body.call(stream)
+            end
+          else
+            buf = +''
+            rack_body.each { |chunk| buf << chunk }
+            rack_body.close if rack_body.respond_to?(:close)
+            res.body = buf
+          end
+        end
+
+        # @return [Hash] Rack environment of the WEBrick request
+        def rack_env(req)
+          {
+            'REQUEST_METHOD'    => req.request_method,
+            'SCRIPT_NAME'       => '',
+            'PATH_INFO'         => req.path,
+            'QUERY_STRING'      => req.query_string || '',
+            'SERVER_NAME'       => req.host,
+            'SERVER_PORT'       => req.port.to_s,
+            'HTTP_VERSION'      => req.http_version,
+            'rack.input'        => StringIO.new(req.body.to_s),
+            'rack.errors'       => $stderr,
+            'rack.url_scheme'   => req.ssl? ? 'https' : 'http',
+            'rack.multithread'  => true,
+            'rack.multiprocess' => false,
+            'rack.run_once'     => false
+          }.tap do |env|
+            req.header.each do |key, values|
+              http_key = "HTTP_#{key.upcase.tr('-', '_')}"
+              case key.downcase
+              when 'content-type'   then env['CONTENT_TYPE']   = values.first
+              when 'content-length' then env['CONTENT_LENGTH'] = values.first
+              else                       env[http_key] = values.join(', ')
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end