aspera-cli 4.27.5 → 4.28.0

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'aspera/secret_hider'
+require 'aspera/cli/error'
+require 'aspera/cli/info'
+require 'aspera/cli/web_secret'
+require 'json'
+
+module Aspera
+  module Cli
+    module Mcp
+      # Secrets of extended value `@secret:` in MCP server mode, entered by the user on a web page (see WebSecret).
+      # The MCP client opens the page following a URL mode elicitation, so that the secret never passes through
+      # the MCP client or the AI model.
+      # See: https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation
+      module Secrets
+        # Tag thrown, with the prompt, when a tool call needs a secret not requested yet
+        THROW_TAG = :mcp_secret_required
+        # Fiber-local variable holding the secrets of the tool call in progress
+        CALL_KEY = :aspera_mcp_secret_call
+        private_constant :CALL_KEY
+
+        class << self
+          # @param base_url    [String, nil] URL of the MCP server, `nil` to start a local web server on first request
+          # @param access_code [String, nil] If set, the user must also enter it on the page (`auth_token` of the server)
+          # @return [WebSecret] Secret pages of the MCP server
+          def web_secret(base_url: nil, access_code: nil)
+            WebSecret.new(base_url: base_url, access_code: access_code, name: "#{Info::CMD_NAME} MCP server", requester: 'AI assistant')
+          end
+
+          # Value of extended value `@secret:` for the tool call in progress
+          # @param prompt [String] Name of the secret
+          # @return [String] The secret
+          def value(prompt)
+            call = Thread.current[CALL_KEY]
+            raise BadArgument, '@secret: is available only in MCP tool calls' if call.nil?
+            call.value(prompt.empty? ? 'secret' : prompt)
+          end
+
+          # Execute the block with the secrets of the given tool call available to `@secret:`
+          # @param call [Call] Secrets of the tool call
+          def with_call(call)
+            previous = Thread.current[CALL_KEY]
+            Thread.current[CALL_KEY] = call
+            yield
+          ensure
+            Thread.current[CALL_KEY] = previous
+          end
+        end
+
+        # Secrets of one tool call.
+        # Following MCP multi round-trip requests, the tool call is executed again from the start on each round:
+        # `@secret:` values are taken in order from the requests of previous rounds, listed in the request state.
+        class Call
+          # @param web_secret     [WebSecret, nil]          Secret pages, `nil` if `@secret:` is not available
+          # @param server_context [MCP::ServerContext, nil] Context of the tool call
+          def initialize(web_secret, server_context)
+            @web_secret     = web_secret
+            @server_context = server_context
+            @ids            = request_ids(server_context&.request_state)
+            @next           = 0
+          end
+
+          # @param prompt [String] Name of the secret
+          # @return [String] The secret entered by the user, waiting for it if needed
+          # @throw THROW_TAG with the prompt if the secret was not requested yet
+          def value(prompt)
+            raise BadArgument, '@secret: is not available' if @web_secret.nil?
+            throw(THROW_TAG, prompt) if @next >= @ids.size
+            id = @ids[@next]
+            @next += 1
+            # The command is the same on each round, so prompts come in the same order
+            raise BadArgument, 'Secret request expired or command changed: execute the command again' unless @web_secret.prompt(id).eql?(prompt)
+            action = input_action(id)
+            raise Error, "Secret request refused in MCP client: #{action}" unless action.nil? || action.eql?('accept')
+            value = @web_secret.wait_value(id) do |elapsed|
+              @server_context&.report_progress(elapsed.to_i, message: "Waiting for secret #{prompt} entered in browser")
+            end
+            # Clients of protocol 2025-11-25: completion of the out-of-band interaction
+            @server_context.notify_elicitation_complete(elicitation_id: id) unless action.nil? || @server_context.modern?
+            # Never reaches the client, even if displayed by the command
+            SecretHider.instance.add_secret_values(value)
+            value
+          end
+
+          # @return [Boolean] `true` if the MCP client supports URL mode elicitation
+          def url_elicitation?
+            !@web_secret.nil? && !read_key(read_key(@server_context&.client_capabilities, :elicitation), :url).nil?
+          end
+
+          # Request a new secret: the client asks the user to open the page, then executes the tool call again
+          # @param prompt [String] Name of the secret
+          # @return [MCP::Server::InputRequiredResult]
+          def input_required(prompt)
+            id = @web_secret.create(prompt)
+            @ids.push(id)
+            params = {
+              mode:    'url',
+              url:     @web_secret.url(id),
+              message: "#{Info::CMD_NAME} needs secret \"#{prompt}\" to execute the command. " \
+                'Enter it on the web page: it is sent to the MCP server only, not to the AI assistant.'
+            }
+            # Clients of protocol 2025-11-25: identifier of the out-of-band interaction
+            params[:elicitationId] = id unless @server_context.modern?
+            MCP::Server::InputRequiredResult.new(
+              input_requests: {id => {method: 'elicitation/create', params: params}},
+              request_state:  JSON.generate(@ids)
+            )
+          end
+
+          # Forget the secrets of this call
+          def finish
+            @web_secret&.delete(@ids)
+          end
+
+          private
+
+          # @param state [String, nil] Request state echoed by the client (unsealed by the MCP server)
+          # @return [Array<String>] Identifiers of the requests of previous rounds
+          def request_ids(state)
+            return [] if state.nil?
+            ids = JSON.parse(state) rescue nil
+            raise BadArgument, 'Invalid request state' unless ids.is_a?(Array) && ids.all?(String)
+            ids
+          end
+
+          # @param id [String] Identifier of the request
+          # @return [String, nil] Action of the user in the MCP client (`accept`, `decline`, `cancel`), `nil` if not in this round
+          def input_action(id)
+            response = @server_context&.input_response(id)
+            read_key(response, :action)&.to_s
+          end
+
+          # Read a key of a JSON object, parsed with or without symbolized keys
+          def read_key(hash, key)
+            return unless hash.is_a?(Hash)
+            hash.key?(key) ? hash[key] : hash[key.to_s]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+# cspell:ignore ascli
+
+require 'json'
+require 'aspera/log'
+require 'aspera/secret_hider'
+require 'aspera/cli/runner'
+require 'aspera/cli/error'
+require 'aspera/cli/mcp/secrets'
+require 'aspera/schema/reader'
+require 'aspera/schema/registry'
+require 'aspera/cli/plugins/mcp'
+unless defined?(MCP::Tool)
+  begin
+    require 'mcp'
+  rescue LoadError
+    raise Cli::Error, "The 'mcp' and 'rack' gems are required. Install them with: gem install mcp rack"
+  end
+end
+
+module Aspera
+  module Cli
+    module Mcp
+      # MCP Tool: executes an ascli command in-process.
+      class Tool < MCP::Tool
+        # Default maximum byte size of the JSON text content returned for list results.
+        # Items are appended whole until the limit is reached; the full list is always
+        # available in structuredContent.
+        DEFAULT_MAX_TEXT_BYTES = 100_000
+        # Default extra arguments automatically prepended to every ascli call.
+        # Keeps the AI from having to remember mandatory flags on every invocation.
+        DEFAULT_EXTRA_ARGS = ['--interactive=no', '--transfer.asynchronous=true'].freeze
+
+        tool_name 'execute_ascli_command'
+
+        description <<~DESC.strip
+          Execute any ascli (Aspera CLI) command in-process and return its result.
+
+          #{Plugins::Mcp::COMMAND_DISPLAY_INSTRUCTIONS}
+
+          SYNTAX
+            args is a JSON array of strings mirroring the CLI command line.
+            Element 0 : plugin name (aoc, faspex5, node, server, config, …).
+            Elements 1+: sub-commands, positional arguments, and --option=value flags in any order.
+            Structured values use an extended-value prefix on the relevant element:
+              "@json:{...}"   — inline JSON object or array (preferred: no shell quoting)
+              "@preset:name"  — expand a saved preset
+              "@base64:..."   — base64-encoded value
+              "@val:..."      — literal string (no further decoding)
+              "@secret:name"  — secret entered by the user on a web page, never visible to you:
+                                use it for a secret the user did not give, e.g. "--password=@secret:password"
+            Note: @stdin: is disabled; @ruby:, @file:, @uri:, @env: depend on the security level of the server.
+            A secret (from @secret:, @vault:, @preset:) must be the whole value: no other prefix before it, not in @extend:.
+
+          AUTOMATIC FLAGS
+            The server prepends extra_args to every call (default: #{DEFAULT_EXTRA_ARGS.join(' ')}).
+            Do NOT repeat them. To override one, include it in args: later values take precedence.
+            Commands never prompt: if credentials are missing, an error is returned; report it and stop.
+
+          DISCOVERY — never guess command or field names from training data
+            Step 1 — commands of a plugin, with syntax:
+              ["config", "commands", "<plugin>"]
+              Returns { syntax, description } for every command of that plugin.
+              Notation: <arg> mandatory, [<arg>] optional, <a|b> enum, <arg...> variadic, <arg:Hash> typed.
+              A line ending with <command...> and "(see: <plugin> <path>)" provides the commands of that path:
+              list them with ["config", "commands", "<plugin>", "<command>", ...] (command words only).
+              Omit <plugin> to list the commands of all plugins (large).
+            Step 2 — schema of a Hash argument (shown <name:Hash>), MANDATORY before calling such a command:
+              ["<plugin>", "<cmd>", ..., "help"]
+              Put the literal "help" in place of the Hash argument. Returns field names, types,
+              required flags and descriptions. Never infer fields from server error messages.
+            Step 2b — filter parameters of a list command:
+              ["<plugin>", "<cmd>", ..., "--query=help"]
+            Step 3 — all --flags of a plugin, with allowed values:
+              ["config", "options", "<plugin>"]
+            Documentation:
+              ["config", "documentation", "toc"]              → { level, title, anchor } per heading
+              ["config", "documentation", "local", "<anchor>"] → one README section
+            Presets (saved credentials):
+              ["config", "preset", "overview"]
+
+          RESULT FORMAT
+            Structured data is always in structuredContent (a JSON object; lists are under "items").
+            For lists, text content is limited to #{DEFAULT_MAX_TEXT_BYTES} bytes (whole items only);
+            when truncated, a WARNING line gives the real total. Read structuredContent.items for
+            the full dataset — never report counts or search results from a truncated text block.
+
+          FILE LIST FOR TRANSFERS
+            For all transfers (upload, download, package send, …), append source paths at the
+            end of args — no --sources flag needed.
+
+          EXAMPLES
+            ["config", "commands", "aoc"]
+            ["aoc", "admin", "user", "create", "help"]
+            ["config", "options", "aoc"]
+            ["config", "documentation", "local", "leveraging-ai-assistance"]
+            ["aoc", "--preset=myaoc", "packages", "list"]
+            ["aoc", "--preset=myaoc", "admin", "user", "create", '@json:{"email":"a@b.com","name":"Alice"}']
+            ["aoc", "--preset=myaoc", "packages", "send",
+             '@json:{"name":"pkg","recipients":["user@example.com"]}', "/local/a.txt", "/local/b.txt"]
+            ["server", "--preset=myserver", "upload", "--to-folder=/uploads", "/local/a.txt"]
+            ["server", "browse", "/", "--url=ssh://host:33001", "--username=user", "--password=secret"]
+        DESC
+
+        input_schema(
+          properties: {
+            args: {
+              type:        'array',
+              items:       {type: 'string'},
+              minItems:    1,
+              description: 'ascli arguments: first element is the plugin name, followed by action and --option=value flags'
+            }
+          },
+          required: ['args']
+        )
+
+        class << self
+          attr_accessor :max_text_bytes, :extra_args
+          # @return [WebSecret, nil] Secret pages for extended value `@secret:`
+          attr_accessor :web_secret
+
+          # Executes the command.
+          # If it needs a secret (`@secret:`), returns an `input_required` result: the client opens the page where the user
+          # enters the secret, then calls the tool again, and the command is executed again with the secret.
+          def call(args:, server_context: nil)
+            secret_call = Secrets::Call.new(web_secret, server_context)
+            prompt = catch(Secrets::THROW_TAG) do
+              response = Secrets.with_call(secret_call) { execute(args) }
+              secret_call.finish
+              # Secret values (e.g. entered by the user, tokens) never reach the client, even if displayed by the command,
+              # also short ones in a text (e.g. a short password in an error message)
+              hider = SecretHider.instance
+              return MCP::Tool::Response.new(
+                hider.hidden_copy(response.content, short_in_text: true),
+                structured_content: hider.hidden_copy(response.structured_content, short_in_text: true),
+                error:              response.error?
+              )
+            end
+            return secret_call.input_required(prompt) if secret_call.url_elicitation?
+            secret_call.finish
+            MCP::Tool::Response.new([{type: 'text', text: "Extended value @secret:#{prompt} requires an MCP client supporting URL mode elicitation"}], error: true)
+          end
+
+          # Executes the command in-process
+          # Unsafe extended values are restricted when evaluated, see Security
+          # @param args [Array<String>] Arguments of the command
+          # @return [MCP::Tool::Response]
+          def execute(args)
+            effective_args = Array(extra_args || DEFAULT_EXTRA_ARGS) + args
+            Log.dump(:mcp_execute, effective_args)
+            runner = Runner.new(effective_args)
+            result = runner.run_with_result
+            # Secrets never reach the AI client, whatever the output format requested in args.
+            # As on the command line, `--out.query` applies to the data of an object or list, after secrets are removed
+            if result.is_a?(Result::SingleObject) || result.is_a?(Result::ObjectList) || result.is_a?(Result::ValueList)
+              result = result.with_data(SecretHider.instance.hidden_copy(result.data))
+              result = runner.context.formatter.query_result(result)
+            end
+            case result
+            when Result::Nothing, Result::Empty, NilClass
+              MCP::Tool::Response.new([{type: 'text', text: ''}])
+            when Result::SingleObject, Result::ObjectList, Result::ValueList
+              # Apply --select filter (affects both text and structuredContent).
+              result = result.with_data(runner.context.formatter.filter_columns_on_select(result.data)) if result.data.is_a?(Array)
+              # MCP spec requires structuredContent to be a JSON object (not an array).
+              structured = result.data.is_a?(Array) ? {items: result.data} : result.data
+              content = if result.data.is_a?(Array)
+                text_limit = max_text_bytes || DEFAULT_MAX_TEXT_BYTES
+                truncated_items = truncate_items_by_bytes(result.data, text_limit)
+                total = result.data.size
+                if truncated_items.size < total
+                  [
+                    {type: 'text', text: JSON.generate(truncated_items)},
+                    {type: 'text', text: "WARNING: result truncated to #{truncated_items.size} of #{total} items. Full dataset available in structuredContent."}
+                  ]
+                else
+                  [{type: 'text', text: JSON.generate(result.data)}]
+                end
+              else
+                [{type: 'text', text: JSON.generate(result.data)}]
+              end
+              MCP::Tool::Response.new(content, structured_content: structured)
+            else
+              MCP::Tool::Response.new([{type: 'text', text: SecretHider.instance.hide_secrets_in_string(result.data.to_s, all: true)}])
+            end
+          rescue Cli::SchemaRequest => e
+            schema_path = e.path
+            if schema_path.nil?
+              MCP::Tool::Response.new([{type: 'text', text: "#{e.class}: #{e.message} (no schema available)"}], error: true)
+            else
+              rows = schema_to_rows(Schema::Registry.instance.reader(schema_path))
+              structured = {items: rows}
+              MCP::Tool::Response.new([{type: 'text', text: JSON.generate(rows)}], structured_content: structured)
+            end
+          rescue SystemExit => e
+            MCP::Tool::Response.new([{type: 'text', text: "exited with status #{e.status}"}], error: !e.status.zero?)
+          rescue => e
+            MCP::Tool::Response.new([{type: 'text', text: SecretHider.instance.hide_secrets_in_string("#{e.class}: #{dedupe_lines(e.message)}", all: true)}], error: true)
+          end
+
+          # Delegate to Schema::Reader#to_rows — semantic fields, no ANSI, MCP/JSON-ready.
+          def schema_to_rows(reader)
+            reader.to_rows
+          end
+
+          # Collapse consecutive duplicate lines in a multi-line message.
+          # Each run of identical lines is replaced by one line + "(×N)" suffix when N > 1.
+          def dedupe_lines(msg)
+            return msg unless msg.include?("\n")
+            msg.split("\n").chunk_while { |a, b| a == b }.map do |group|
+              group.size > 1 ? "#{group.first} (x#{group.size})" : group.first
+            end.join("\n")
+          end
+
+          # Returns the largest prefix of `items` whose JSON serialization fits within `max_bytes`.
+          # Items are appended whole — no item is ever split mid-JSON.
+          def truncate_items_by_bytes(items, max_bytes)
+            buf = +''
+            items.each_with_index do |item, i|
+              fragment = (i.zero? ? '[' : ',') + JSON.generate(item)
+              break if buf.bytesize + fragment.bytesize + 1 > max_bytes # +1 for closing ']'
+              buf << fragment
+            end
+            buf.empty? ? [] : JSON.parse("#{buf}]")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aspera/cli/option_value.rb

@@ -134,7 +134,9 @@ module Aspera
         Aspera.assert_type(new_value, *@types, type: BadArgument) { "Option #{@option}" } if @types
         if merge && (new_value.is_a?(Hash) || new_value.is_a?(Array))
           current_value = @value
-          mergeable = current_value.is_a?(new_value.is_a?(Hash) ? Hash : Array) && !current_value.empty?
+          # An `Array` default value is replaced, not appended to
+          mergeable = current_value.is_a?(new_value.is_a?(Hash) ? Hash : Array) && !current_value.empty? &&
+            !(new_value.is_a?(Array) && [source, @source].include?(:default))
           if lower
             # Current value has priority: merge new value under it, unless explicitly emptied
             return unless mergeable
@@ -269,6 +271,12 @@ module Aspera
       # @param new_value [Object] value to store
       # @param source [Symbol, nil] `OptionSource` of value
       def store(new_value, source)
+        # Secret values are hidden wherever they appear: logs, results
+        if @sensitive
+          SecretHider.instance.add_secret_values(new_value)
+        else
+          SecretHider.instance.add_secrets_in(new_value)
+        end
         @value = new_value
         @source = source
         @on_set&.call(new_value)