aspera-cli 4.24.2 → 4.25.0.pre2

data/lib/aspera/cli/sync_actions.rb

@@ -7,7 +7,7 @@ require 'pathname'
 
 module Aspera
   module Cli
-    # Manage command line arguments to provide to Sync::Run, Sync::Database and Sync::Operations
+    # Manage command line arguments to provide to Sync::Operations and Sync::Database
     module SyncActions
       # Translate state id (int) to string
       STATE_STR = (['Nil'] +
@@ -19,15 +19,19 @@ module Aspera
         end
       end
 
-      # Read command line arguments (1 to 3) and converts to sync_info format
-      # @param sync [Bool] Set to `true` for non-admin
+      # Read 1 or 2 command line arguments and converts to `sync_info` format
+      # The resulting sync_info has `args` format only if it contains one of the `sessions` or `instance` keys.
+      # It has the `conf` format (default) otherwise.
+      # If the `conf` format is detected, then both `local` and `remote` keys are set.
+      # @param direction [Symbol,NilClass] One of directions, or `nil` if only for admin command
       # @return [Hash] sync info
       def async_info_from_args(direction: nil)
         path = options.get_next_argument('path')
         sync_info = options.get_next_argument('sync info', mandatory: false, validation: Hash, default: {})
+        # is the positional path a remote path ?
         path_is_remote = direction.eql?(:pull)
         if sync_info.key?('sessions') || sync_info.key?('instance')
-          # "args"
+          # `args`
           sync_info['sessions'] ||= [{}]
           Aspera.assert(sync_info['sessions'].length == 1){'Only one session is supported'}
           session = sync_info['sessions'].first
@@ -41,7 +45,7 @@ module Aspera
             local_remote = %w[local remote].map{ |i| session["#{i}_dir"]}
           end
         else
-          # "conf"
+          # `conf`
           session = sync_info
           dir_key = path_is_remote ? 'remote' : 'local'
           session[dir_key] ||= {}
@@ -54,7 +58,7 @@ module Aspera
             session[dir_key]['path'] = transfer.destination_folder(path_is_remote ? Transfer::Spec::DIRECTION_RECEIVE : Transfer::Spec::DIRECTION_SEND)
             local_remote = %w[local remote].map{ |i| session[i]['path']}
           end
-          # "conf" is quiet by default
+          # `conf` is quiet by default
           session['quiet'] = false if !session.key?('quiet') && Environment.terminal?
         end
         if direction
@@ -62,17 +66,20 @@ module Aspera
           session['direction'] = direction.to_s
           # generate name if not provided by user
           if !session.key?('name')
+            safe_char = Environment.instance.safe_filename_character
+            # from async man page:
+            # -N : can contain only ASCII alphanumeric, hyphen, and underscore characters
             session['name'] = Environment.instance.sanitized_filename(
               ([direction.to_s] + local_remote).map do |value|
-                Pathname(value).each_filename.to_a.last(2).join(Environment.instance.safe_filename_character)
-              end.join(Environment.instance.safe_filename_character)
+                Pathname(value).each_filename.to_a.last(2).join(safe_char)
+              end.join(safe_char).gsub(/[^A-Za-z0-9_-]/, safe_char)
             )
           end
         end
         sync_info
       end
 
-      # provide database object from command line arguments for admin ops
+      # Provide database object from command line arguments for admin ops
       def db_from_args
         sync_info = async_info_from_args
         session = sync_info.key?('sessions') ? sync_info['sessions'].first : sync_info
@@ -86,43 +93,47 @@ module Aspera
         Sync::Database.new(Sync::Operations.session_db_file(sync_info))
       end
 
+      def execute_sync_admin
+        command2 = options.get_next_command(%i[status find meta counters file_info overview])
+        require 'aspera/sync/database' unless command2.eql?(:status)
+        case command2
+        when :status
+          return Main.result_single_object(Sync::Operations.admin_status(async_info_from_args))
+        when :find
+          folder = options.get_next_argument('path')
+          dbs = Sync::Operations.list_db_files(folder)
+          return Main.result_object_list(dbs.keys.map{ |n| {name: n, path: dbs[n]}})
+        when :meta, :counters
+          return Main.result_single_object(db_from_args.send(command2))
+        when :file_info
+          result = db_from_args.send(command2)
+          result.each do |r|
+            r['sstate'] = SyncActions::STATE_STR[r['state']] if r['state']
+          end
+          return Main.result_object_list(
+            result,
+            fields: %w[sstate record_id f_meta_path message]
+          )
+        when :overview
+          return Main.result_object_list(
+            db_from_args.overview,
+            fields: %w[table name type]
+          )
+        else Aspera.error_unexpected_value(command2)
+        end
+      end
+
       # Execute sync action
-      # @param &block [nil, Proc] block to generate transfer spec, takes: direction (one of DIRECTIONS), local_dir, remote_dir
+      # @param &block [nil, Proc] block to generate transfer spec, takes: `direction` (one of DIRECTIONS), `local_dir`, `remote_dir`
       def execute_sync_action(&block)
         command = options.get_next_command(%i[admin] + Sync::Operations::DIRECTIONS)
         # try to get 3 arguments as simple arguments
         case command
         when *Sync::Operations::DIRECTIONS
-          Sync::Operations.start(async_info_from_args(direction: command), transfer.option_transfer_spec, &block)
+          Sync::Operations.start(async_info_from_args(direction: command), transfer.user_transfer_spec, &block)
           return Main.result_success
         when :admin
-          command2 = options.get_next_command(%i[status find meta counters file_info overview])
-          require 'aspera/sync/database' unless command2.eql?(:status)
-          case command2
-          when :status
-            return Main.result_single_object(Sync::Operations.admin_status(async_info_from_args))
-          when :find
-            folder = options.get_next_argument('path')
-            dbs = Sync::Operations.list_db_files(folder)
-            return Main.result_object_list(dbs.keys.map{ |n| {name: n, path: dbs[n]}})
-          when :meta, :counters
-            return Main.result_single_object(db_from_args.send(command2))
-          when :file_info
-            result = db_from_args.send(command2)
-            result.each do |r|
-              r['sstate'] = SyncActions::STATE_STR[r['state']] if r['state']
-            end
-            return Main.result_object_list(
-              result,
-              fields: %w[sstate record_id f_meta_path message]
-            )
-          when :overview
-            return Main.result_object_list(
-              db_from_args.overview,
-              fields: %w[table name type]
-            )
-          else Aspera.error_unexpected_value(command2)
-          end
+          return execute_sync_admin
         else Aspera.error_unexpected_value(command)
         end
       end

data/lib/aspera/cli/transfer_agent.rb

@@ -48,8 +48,8 @@ module Aspera
       def initialize(opt_mgr, config_plugin)
         @opt_mgr = opt_mgr
         @config = config_plugin
-        # command line can override transfer spec
-        @transfer_spec_command_line = {
+        # Command line can override transfer spec
+        @user_transfer_spec = {
           'create_dir'    => true,
           'resume_policy' => 'sparse_csum'
         }
@@ -61,12 +61,12 @@ module Aspera
         @transfer_paths = nil
         # HTTPGW URL provided by webapp
         @httpgw_url_lambda = nil
-        @opt_mgr.declare(:ts, 'Override transfer spec values', types: Hash, handler: {o: self, m: :option_transfer_spec})
+        @opt_mgr.declare(:ts, 'Override transfer spec values', allowed: Hash, handler: {o: self, m: :user_transfer_spec})
         @opt_mgr.declare(:to_folder, 'Destination folder for transferred files')
         @opt_mgr.declare(:sources, "How list of transferred files is provided (#{FILE_LIST_OPTIONS.join(',')})", default: FILE_LIST_FROM_ARGS)
-        @opt_mgr.declare(:src_type, 'Type of file list', values: %i[list pair], default: :list)
-        @opt_mgr.declare(:transfer, 'Type of transfer agent', values: TRANSFER_AGENTS, default: :direct)
-        @opt_mgr.declare(:transfer_info, 'Parameters for transfer agent', types: Hash, handler: {o: self, m: :transfer_info})
+        @opt_mgr.declare(:src_type, 'Type of file list', allowed: %i[list pair], default: :list)
+        @opt_mgr.declare(:transfer, 'Type of transfer agent', allowed: TRANSFER_AGENTS, default: :direct)
+        @opt_mgr.declare(:transfer_info, 'Parameters for transfer agent', allowed: Hash, handler: {o: self, m: :transfer_info})
         @opt_mgr.parse_options!
         @notification_cb = nil
         if !@opt_mgr.get_option(:notify_to).nil?
@@ -80,25 +80,7 @@ module Aspera
         end
       end
 
-      def option_transfer_spec; @transfer_spec_command_line; end
-
-      # Multiple option are merged
-      # @param value [Hash] Transfer spec
-      def option_transfer_spec=(value)
-        Aspera.assert_type(value, Hash){'ts'}
-        @transfer_spec_command_line.deep_merge!(value)
-      end
-
-      # Add other transfer spec parameters
-      def option_transfer_spec_deep_merge(value); @transfer_spec_command_line.deep_merge!(value); end
-
-      attr_reader :transfer_info
-
-      # Multiple option are merged
-      # @param value [Hash]
-      def transfer_info=(value)
-        @transfer_info.deep_merge!(value)
-      end
+      attr_accessor :user_transfer_spec, :transfer_info
 
       def agent_instance=(instance)
         @agent = instance
@@ -145,7 +127,7 @@ module Aspera
         dest_folder = @opt_mgr.get_option(:to_folder)
         # do not expand path, if user wants to expand path: user @path:
         return dest_folder unless dest_folder.nil?
-        dest_folder = @transfer_spec_command_line['destination_root']
+        dest_folder = @user_transfer_spec['destination_root']
         return dest_folder unless dest_folder.nil?
         # default: / on remote, . on local
         case direction.to_s
@@ -193,7 +175,7 @@ module Aspera
         # return cache if set
         return @transfer_paths unless @transfer_paths.nil?
         # start with lower priority : get paths from transfer spec on command line
-        @transfer_paths = @transfer_spec_command_line['paths'] if @transfer_spec_command_line.key?('paths')
+        @transfer_paths = @user_transfer_spec['paths'] if @user_transfer_spec.key?('paths')
         # is there a source list option ?
         sources = @opt_mgr.get_option(:sources)
         @transfer_paths =
@@ -216,7 +198,7 @@ module Aspera
             @transfer_paths
           when Array
             Log.log.debug('getting file list as extended value')
-            Aspera.assert(sources.all?(String), type: Cli::BadArgument){'sources must be a Array of String'}
+            Aspera.assert_array_all(sources, String, type: Cli::BadArgument){'sources must be a Array of String'}
             list_to_paths(sources)
           else Aspera.error_unexpected_value(sources){'sources'}
           end
@@ -235,25 +217,25 @@ module Aspera
         case transfer_spec['direction']
         when Transfer::Spec::DIRECTION_RECEIVE
           # init default if required in any case
-          @transfer_spec_command_line['destination_root'] ||= destination_folder(transfer_spec['direction'])
+          @user_transfer_spec['destination_root'] ||= destination_folder(transfer_spec['direction'])
         when Transfer::Spec::DIRECTION_SEND
           if transfer_spec.dig('tags', Transfer::Spec::TAG_RESERVED, 'node', 'access_key')
             # gen4
-            @transfer_spec_command_line.delete('destination_root') if @transfer_spec_command_line.key?('destination_root_id')
+            @user_transfer_spec.delete('destination_root') if @user_transfer_spec.key?('destination_root_id')
           elsif transfer_spec.key?('token')
             # gen3
             # in that case, destination is set in return by application (API/upload_setup)
             # but to_folder was used in initial API call
-            @transfer_spec_command_line.delete('destination_root')
+            @user_transfer_spec.delete('destination_root')
           else
             # init default if required
-            @transfer_spec_command_line['destination_root'] ||= destination_folder(transfer_spec['direction'])
+            @user_transfer_spec['destination_root'] ||= destination_folder(transfer_spec['direction'])
           end
         end
         # update command line paths, unless destination already has one
-        @transfer_spec_command_line['paths'] = transfer_spec['paths'] || ts_source_paths
+        @user_transfer_spec['paths'] = transfer_spec['paths'] || ts_source_paths
         # updated transfer spec with command line
-        transfer_spec.deep_merge!(@transfer_spec_command_line)
+        transfer_spec.deep_merge!(@user_transfer_spec)
         # recursively remove values that are nil (user wants to delete)
         transfer_spec.deep_do{ |hash, key, value, _unused| hash.delete(key) if value.nil?}
         # if TS from app has content_protection (e.g. F5), that means content is protected: ask password if not provided

data/lib/aspera/cli/version.rb

@@ -4,6 +4,6 @@ module Aspera
   module Cli
     # For beta add extension : .beta1
     # For dev version add extension : .pre
-    VERSION = '4.24.2'
+    VERSION = '4.25.0.pre2'
   end
 end

data/lib/aspera/cli/wizard.rb

@@ -17,8 +17,8 @@ module Aspera
         @parent = parent
         @main_folder = main_folder
         # Wizard options
-        options.declare(:override, 'Wizard: override existing value', values: :bool, default: :no)
-        options.declare(:default, 'Wizard: set as default configuration for specified plugin (also: update)', values: :bool, default: true)
+        options.declare(:override, 'Wizard: override existing value', allowed: Allowed::TYPES_BOOLEAN, default: false)
+        options.declare(:default, 'Wizard: set as default configuration for specified plugin (also: update)', allowed: Allowed::TYPES_BOOLEAN, default: true)
         options.declare(:key_path, 'Wizard: path to private key for JWT')
       end
 
@@ -84,7 +84,10 @@ module Aspera
       end
 
       # To be called in public wizard method to get private key
-      # @return [Array] Private key path, pub key PEM
+      # @param user [String] User's email
+      # @param url  [String] Instance URL
+      # @param page [String] URL of page to enter pub key
+      # @return [String] Private key path (can contain ~ for home)
       def ask_private_key(user:, url:, page:)
         # Lets see if path to priv key is provided
         private_key_path = options.get_option(:key_path)
@@ -95,7 +98,7 @@ module Aspera
         end
         # Else generate path
         private_key_path = File.join(@main_folder, DEFAULT_PRIV_KEY_FILENAME) if private_key_path.empty?
-        if File.exist?(private_key_path)
+        if File.exist?(File.expand_path(private_key_path))
           formatter.display_status('Using existing key:')
         else
           formatter.display_status("Generating #{OAuth::Jwt::DEFAULT_PRIV_KEY_LENGTH} bit RSA key...")
@@ -103,7 +106,7 @@ module Aspera
           formatter.display_status('Created key:')
         end
         formatter.display_status(private_key_path)
-        private_key_pem = File.read(private_key_path)
+        private_key_pem = File.read(File.expand_path(private_key_path))
         pub_key_pem = OpenSSL::PKey::RSA.new(private_key_pem).public_key.to_s
         options.set_option(:private_key, private_key_pem)
         formatter.display_status("Please Log in as user #{user.red} at: #{url.red}")

data/lib/aspera/command_line_builder.rb

@@ -31,39 +31,42 @@ module Aspera
       'x-deprecation'   # [String]       Deprecation message for doc
     ].freeze
 
-    CLI_AGENT = 'direct'
-
-    private_constant :PROPERTY_KEYS, :CLI_AGENT
+    private_constant :PROPERTY_KEYS
 
     class << self
-      # @return true if given agent supports that field
+      # Called by provider of definition before constructor of this class so that schema has all mandatory fields
+      def read_schema(folder, name, ascp: false)
+        schema = YAML.load_file(File.join(folder, "#{name}.schema.yaml"))
+        validate_schema(schema, ascp: ascp)
+      end
+
+      # @param agent      [Symbol] Transfer agent name
+      # @param properties [Hash]   Transfer spec parameter information
+      # @return [Boolean] `true` if given agent supports that field
       def supported_by_agent(agent, properties)
-        !properties.key?('x-agents') || properties['x-agents'].include?(agent)
+        !properties.key?('x-agents') || properties['x-agents'].include?(agent.to_s)
       end
 
+      private
+
       # Fill default values for some fields in the schema
       # @param schema [Hash] The JSON schema
+      # @param ascp [Bool] `true` if ascp
       def validate_schema(schema, ascp: false)
+        direct_props = %w[x-cli-option x-cli-envvar x-cli-special].freeze
         schema['properties'].each do |name, info|
           Aspera.assert_type(info, Hash){"#{info.class} for #{name}"}
           unsupported_keys = info.keys - PROPERTY_KEYS
           Aspera.assert(unsupported_keys.empty?){"Unsupported definition keys: #{unsupported_keys}"}
-          # By default : string, unless it's without arg (switch)
-          # info['type'] ||= info['x-cli-switch'] ? 'boolean' : 'string'
           Aspera.assert(info.key?('type') || info.key?('enum')){"Missing type for #{name} in #{schema['description']}"}
-          Aspera.assert(info['type'].eql?('boolean')){"switch must be bool: #{name}"} if info['x-cli-switch']
-          # Add default cli option name if not present, and if supported in "direct".
+          Aspera.assert(info['type'].eql?('boolean')){"switch must be bool: #{name}"} if info['x-cli-switch'] && !info['x-cli-special']
           info['x-cli-option'] = "--#{name.to_s.tr('_', '-')}" if info['x-cli-option'].eql?(true) || (info['x-cli-switch'].eql?(true) && !info.key?('x-cli-option'))
-          Aspera.assert(%w[x-cli-option x-cli-envvar x-cli-special].any?{ |i| info.key?(i)}, type: :warn){name} if ascp && supported_by_agent(CLI_AGENT, info)
-          # info['x-cli-option'] = "--#{name.to_s.tr('_', '-')}" if ascp && !info.key?('x-cli-option') && !info['x-cli-envvar'] && (info.key?('x-cli-switch') || supported_by_agent(CLI_AGENT, info))
+          Aspera.assert(direct_props.any?{ |i| info.key?(i)}, type: :warn){name} if ascp && supported_by_agent(:direct, info)
           info.freeze
           validate_schema(info, ascp: ascp) if info['type'].eql?('object') && info['properties']
+          validate_schema(info['items'], ascp: ascp) if info['type'].eql?('array') && info['items'] && info['items']['properties']
         end
-      end
-
-      # Called by provider of definition before constructor of this class so that schema has all mandatory fields
-      def read_schema(source_path, name)
-        YAML.load_file(File.join(File.dirname(source_path), "#{name}.schema.yaml"))
+        schema
       end
     end
 
@@ -173,7 +176,7 @@ module Aspera
         parameter_value = converted_value
       end
 
-      return unless self.class.supported_by_agent(CLI_AGENT, properties)
+      return unless self.class.supported_by_agent(:direct, properties)
 
       if read
         # just get value (deferred)

data/lib/aspera/coverage.rb

@@ -6,14 +6,18 @@ if ENV.key?('ENABLE_COVERAGE')
   require 'securerandom'
   # compute development top folder based on this source location
   development_root = File.dirname(File.realpath(__FILE__), 3)
+  coverage_dir = 'tmp/coverage'
+  coverage_root = File.join(development_root, coverage_dir)
+  FileUtils.mkdir_p(coverage_root)
   SimpleCov.root(development_root)
+  SimpleCov.coverage_dir(coverage_dir)
   SimpleCov.enable_for_subprocesses if SimpleCov.respond_to?(:enable_for_subprocesses)
-  # keep cache data for 1 day (must be longer that time to run the whole test suite)
+  # keep cache data for 1 day (must be longer than time to run the whole test suite)
   SimpleCov.merge_timeout(86400)
   SimpleCov.command_name(SecureRandom.uuid)
   SimpleCov.at_exit do
     original_file_descriptor = $stdout
-    $stdout.reopen(File.join(development_root, 'simplecov.log'))
+    $stdout.reopen(File.open(File.join(coverage_root, 'simplecov.log'), 'a'))
     SimpleCov.result.format!
     $stdout.reopen(original_file_descriptor)
   end

data/lib/aspera/environment.rb

@@ -5,7 +5,9 @@ require 'aspera/log'
 require 'aspera/assert'
 require 'rbconfig'
 require 'singleton'
+require 'open3'
 require 'English'
+require 'shellwords'
 
 # cspell:words MEBI mswin bccwin
 
@@ -40,100 +42,85 @@ module Aspera
 
     RB_EXT = '.rb'
 
+    PROCESS_MODES = %i[execute background capture].freeze
+
     class << self
       def ruby_version
         return RbConfig::CONFIG['RUBY_PROGRAM_VERSION']
       end
 
-      # empty variable binding for secure eval
+      # Empty variable binding for secure eval
       def empty_binding
         return Kernel.binding
       end
 
-      # secure execution of Ruby code
+      # Secure execution of Ruby code
+      # @param code [String] Ruby code to execute
+      # @param file [String] File name for error reporting
+      # @param line [Integer] Line number for error reporting
       def secure_eval(code, file, line)
         Kernel.send('lave'.reverse, code, empty_binding, file, line)
       end
 
-      # Generate log line for external program with arguments
-      # @param env [Hash, nil]   environment variables
-      # @param exec [String]     path to executable
-      # @param args [Array, nil] arguments
-      # @return [String] log line with environment, program and arguments
-      def log_spawn(exec:, args: nil, env: nil)
-        [
-          'execute:'.red,
-          env&.map{ |k, v| "#{k}=#{Shellwords.shellescape(v)}"},
-          Shellwords.shellescape(exec),
-          args&.map{ |a| Shellwords.shellescape(a)}
-        ].compact.flatten.join(' ')
-      end
-
-      # Start process in background
-      # caller can call Process.wait on returned value
-      # @param exec    [String]     path to executable
-      # @param args    [Array, nil] arguments for executable
-      # @param env     [Hash, nil]  environment variables
-      # @param options [Hash, nil]  spawn options
-      # @return [String]            PID of process
-      # @raise  [Exception]         if problem
-      def secure_spawn(exec:, args: nil, env: nil, **options)
-        Aspera.assert_type(exec, String)
-        Aspera.assert_type(args, Array, NilClass)
-        Aspera.assert_type(env, Hash, NilClass)
-        Aspera.assert_type(options, Hash, NilClass)
-        Log.log.debug{log_spawn(exec: exec, args: args, env: env)}
-        # start ascp in separate process
-        spawn_args = []
-        spawn_args.push(env) unless env.nil?
-        spawn_args.push([exec, exec])
-        spawn_args.concat(args) unless args.nil?
-        opts = {close_others: true}
-        opts.merge!(options) unless options.nil?
-        ascp_pid = Process.spawn(*spawn_args, **opts)
-        Log.log.debug{"pid: #{ascp_pid}"}
-        return ascp_pid
+      # Build argv for Process.spawn / Kernel.system (no shell)
+      # @param cmd    [Array]  Command and arguments
+      # @param kwargs [Hash]   Additional arguments to `secure_execute`
+      def build_spawn_argv(cmd, kwargs)
+        env = kwargs.delete(:env)
+        argv = []
+        argv << env if env
+        argv << [cmd.first, cmd.first] # no shell, preserve argv[0]
+        argv.concat(cmd.drop(1))
+        argv
       end
 
-      # start process and wait for completion
-      # @param env [Hash, nil]   environment variables
-      # @param exec [String]     path to executable
-      # @param args [Array, nil] arguments
-      # @return [String] PID of process
-      def secure_execute(exec:, args: nil, env: nil, **system_args)
-        Aspera.assert_type(exec, String)
-        Aspera.assert_type(args, Array, NilClass)
-        Aspera.assert_type(env, Hash, NilClass)
-        Log.log.debug{log_spawn(exec: exec, args: args, env: env)}
-        # start in separate process
-        spawn_args = []
-        spawn_args.push(env) unless env.nil?
-        # ensure no shell expansion
-        spawn_args.push([exec, exec])
-        spawn_args.concat(args) unless args.nil?
-        kwargs = {exception: true}
-        kwargs.merge!(system_args)
-        Kernel.system(*spawn_args, **kwargs)
-        nil
-      end
-
-      # Execute process and capture stdout
-      # @param exec [String] path to executable
-      # @param args [Array] arguments to executable
-      # @param opts [Hash] options to capture3
-      # @return stdout of executable or raise exception
-      def secure_capture(exec:, args: [], exception: true, **opts)
-        Aspera.assert_type(exec, String)
-        Aspera.assert_type(args, Array)
-        Aspera.assert_type(opts, Hash)
-        Log.log.debug{log_spawn(exec: exec, args: args)}
-        Log.dump(:opts, opts, level: :trace2)
-        Log.dump(:ENV, ENV.to_h, level: :trace1)
-        stdout, stderr, status = Open3.capture3(exec, *args, **opts)
-        Log.log.debug{"status=#{status}, stderr=#{stderr}"}
-        Log.log.trace1{"stdout=#{stdout}"}
-        raise "process failed: #{status.exitstatus} (#{stderr})" if !status.success? && exception
-        return stdout
+      # Execute a process securely (no shell)
+      # mode:
+      #   :execute    -> Kernel.system, return nil
+      #   :background -> Process.spawn, return pid
+      #   :capture    -> Open3.capture3, return stdout
+      # @param cmd       [Array]     Command and arguments
+      # @param env       [Hash, nil] Environment variables
+      # @param mode      [Symbol]    Execution mode (see above)
+      # @param kwargs    [Hash]      Additional arguments to underlying method, includes:
+      #                              :exception [Boolean] for :capture mode, raise error if process fails
+      #                              :close_others [Boolean] for :background mode
+      #                              :env [Hash] for :execute mode
+      def secure_execute(*cmd, mode: :execute, **kwargs)
+        cmd = cmd.map(&:to_s)
+        Aspera.assert(cmd.size.positive?, type: ArgumentError){'executable must be present'}
+        Aspera.assert_values(mode, PROCESS_MODES, type: ArgumentError){'mode'}
+        Log.log.debug do
+          parts = [mode.to_s, 'command:']
+          kwargs[:env]&.each{ |k, v| parts << "#{k}=#{Shellwords.shellescape(v.to_s)}"}
+          cmd.each{ |a| parts << Shellwords.shellescape(a)}
+          parts.join(' ')
+        end
+        case mode
+        when :execute
+          # https://docs.ruby-lang.org/en/master/Kernel.html#method-i-system
+          # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
+          kwargs[:exception] = true unless kwargs.key?(:exception)
+          Kernel.system(*build_spawn_argv(cmd, kwargs), **kwargs)
+        when :background
+          # https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn
+          # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
+          kwargs[:close_others] = true unless kwargs.key?(:close_others)
+          pid = Process.spawn(*build_spawn_argv(cmd, kwargs), **kwargs)
+          Log.dump(:pid, pid)
+          pid
+        when :capture
+          # https://docs.ruby-lang.org/en/master/Open3.html#method-c-capture3
+          # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
+          argv = [kwargs.delete(:env)].compact + cmd
+          exception = kwargs.delete(:exception){true}
+          stdout, stderr, status = Open3.capture3(*argv, **kwargs)
+          Log.log.debug{"status=#{status}, stderr=#{stderr}"}
+          Log.log.trace1{"stdout=#{stdout}"}
+          raise "Process failed: #{status.exitstatus} (#{stderr})" if exception && !status.success?
+          stdout
+        else Aspera.error_unreachable_line
+        end
       end
 
       # Write content to a file, with restricted access
@@ -266,9 +253,9 @@ module Aspera
     # @param uri [String] the URI to open
     def open_uri_graphical(uri)
       case @os
-      when Environment::OS_MACOS then return self.class.secure_execute(exec: 'open', args: [uri.to_s])
-      when Environment::OS_WINDOWS then return self.class.secure_execute(exec: 'start', args: ['explorer', %Q{"#{uri}"}])
-      when Environment::OS_LINUX   then return self.class.secure_execute(exec: 'xdg-open', args: [uri.to_s])
+      when Environment::OS_MACOS then return self.class.secure_execute('open', uri.to_s)
+      when Environment::OS_WINDOWS then return self.class.secure_execute('start', 'explorer', %Q{"#{uri}"})
+      when Environment::OS_LINUX   then return self.class.secure_execute('xdg-open', uri.to_s)
       else Assert.error_unexpected_value(os){'no graphical open method'}
       end
     end
@@ -276,9 +263,9 @@ module Aspera
     # open a file in an editor
     def open_editor(file_path)
       if ENV.key?('EDITOR')
-        self.class.secure_execute(exec: ENV['EDITOR'], args: [file_path.to_s])
+        self.class.secure_execute(ENV['EDITOR'], file_path.to_s)
       elsif @os.eql?(Environment::OS_WINDOWS)
-        self.class.secure_execute(exec: 'notepad.exe', args: [%Q{"#{file_path}"}])
+        self.class.secure_execute('notepad.exe', %Q{"#{file_path}"})
       else
         open_uri_graphical(file_path.to_s)
       end

data/lib/aspera/faspex_gw.rb

@@ -55,7 +55,7 @@ module Aspera
         content_type: Rest::MIME_JSON,
         body:         {paths: [{'destination'=>'/'}]},
         headers:      {'Accept' => Rest::MIME_JSON}
-      )[:data]
+      )
       transfer_spec.delete('authentication')
       # but we place it in a Faspex package creation response
       return {

data/lib/aspera/faspex_postproc.rb

@@ -50,7 +50,7 @@ module Aspera
         Log.dump(:webhook_parameters, webhook_parameters)
         # env expects only strings
         environment = webhook_parameters.each_with_object({}){ |(k, v), h| h[k] = v.to_s}
-        post_proc_pid = Environment.secure_spawn(env: environment, exec: script_path)
+        post_proc_pid = Environment.secure_execute(script_path, mode: :background, env: environment)
         Timeout.timeout(@parameters[:timeout_seconds]) do
           # "wait" for process to avoid zombie
           Process.wait(post_proc_pid)

data/lib/aspera/keychain/factory.rb

@@ -12,8 +12,7 @@ module Aspera
         # @param folder   [String] folder to store the vault (if needed)
         # @param password [String] password to open the vault
         def create(info, name, folder, password)
-          Aspera.assert_type(info, Hash)
-          Aspera.assert(info.values.all?(String)){'vault info shall have only string values'}
+          Aspera.assert_hash_all(info, Symbol, String){'vault info shall have only string values'}
           info = info.symbolize_keys
           vault_type = info.delete(:type)
           Aspera.assert_values(vault_type, LIST.map(&:to_s)){'vault.type'}