aspera-cli 4.14.0 → 4.16.0

data/lib/aspera/cli/plugins/aoc.rb

@@ -10,6 +10,7 @@ require 'aspera/aoc'
 require 'aspera/node'
 require 'aspera/persistency_action_once'
 require 'aspera/id_generator'
+require 'aspera/assert'
 require 'securerandom'
 require 'date'
 
@@ -17,18 +18,130 @@ module Aspera
   module Cli
     module Plugins
       class Aoc < Aspera::Cli::BasicAuthPlugin
+        AOC_PATH_API_CLIENTS = 'admin/api-clients'
+        # default redirect for AoC web auth
+        DEFAULT_REDIRECT = 'http://localhost:12345'
+        private_constant :AOC_PATH_API_CLIENTS, :DEFAULT_REDIRECT
         class << self
+          def application_name
+            'Aspera on Cloud'
+          end
+
           def detect(base_url)
-            api = Rest.new({base_url: base_url})
+            # no protocol ?
+            base_url = "https://#{base_url}" unless base_url.match?(%r{^[a-z]{1,6}://})
+            # only org provided ?
+            base_url = "#{base_url}.#{Aspera::AoC::PROD_DOMAIN}" unless base_url.include?('.')
+            # AoC is only https
+            return nil unless base_url.start_with?('https://')
+            result = Rest.new({base_url: base_url, redirect_max: 10}).read('')
+            # Any AoC is on this domain
+            return nil unless result[:http].uri.host.end_with?(Aspera::AoC::PROD_DOMAIN)
+            Log.log.debug{'AoC Main page: #{result[:http].body.include?(Aspera::AoC::PRODUCT_NAME)}'}
+            base_url = result[:http].uri.to_s if result[:http].uri.path.include?('/public')
             # either in standard domain, or product name in page
-            if URI.parse(base_url).host.end_with?(Aspera::AoC::PROD_DOMAIN) ||
-                api.call({operation: 'GET', redirect_max: 1, headers: {'Accept' => 'text/html'}})[:http].body.include?(Aspera::AoC::PRODUCT_NAME)
+            return {
+              version: 'SaaS',
+              url:     base_url
+            }
+          end
+
+          def private_key_required?(url)
+            # pub link do not need private key
+            return AoC.link_info(url)[:token].nil?
+          end
+
+          # @param [Hash] env : options, formatter
+          # @param [Hash] params : plugin_sym, instance_url
+          # @return [Hash] :preset_value, :test_args
+          def wizard(object:, private_key_path: nil, pub_key_pem: nil)
+            # set vars to look like object
+            options = object.options
+            formatter = object.formatter
+            options.declare(:use_generic_client, 'Wizard: AoC: use global or org specific jwt client id', values: :bool, default: true)
+            options.parse_options!
+            instance_url = options.get_option(:url, mandatory: true)
+            pub_link_info = AoC.link_info(instance_url)
+            if !pub_link_info[:token].nil?
+              pub_api = Rest.new({base_url: "https://#{URI.parse(pub_link_info[:url]).host}/api/v1"})
+              pub_info = pub_api.read('env/url_token_check', {token: pub_link_info[:token]})[:data]
+              preset_value = {
+                link: instance_url
+              }
+              preset_value[:password] = options.get_option(:password, mandatory: true) if pub_info['password_protected']
               return {
-                version: 'SaaS',
-                name:    'Aspera on Cloud'
+                preset_value: preset_value,
+                test_args:    'organization'
               }
             end
-            return nil
+            # make username mandatory for jwt, this triggers interactive input
+            wiz_username = options.get_option(:username, mandatory: true)
+            raise "Username shall be an email in AoC: #{wiz_username}" if !(wiz_username =~ /\A[\w+\-.]+@[a-z\d\-.]+\.[a-z]+\z/i)
+            # Set the pub key and jwt tag in the user's profile automatically
+            auto_set_pub_key = false
+            auto_set_jwt = false
+            # use browser authentication to bootstrap
+            use_browser_authentication = false
+            if options.get_option(:use_generic_client)
+              formatter.display_status('Using global client_id.')
+              formatter.display_status('Please Login to your Aspera on Cloud instance.')
+              formatter.display_status('Navigate to: 👤 → Account Settings → Profile → Public Key')
+              formatter.display_status('Check or update the value to:'.red.blink)
+              formatter.display_status(pub_key_pem)
+              if !options.get_option(:test_mode)
+                formatter.display_status('Once updated or validated, press enter.')
+                OpenApplication.instance.uri(instance_url)
+                $stdin.gets
+              end
+            else
+              formatter.display_status('Using organization specific client_id.')
+              if options.get_option(:client_id).nil? || options.get_option(:client_secret).nil?
+                formatter.display_status('Please login to your Aspera on Cloud instance.'.red)
+                formatter.display_status('Navigate to: 𓃑  → Admin → Integrations → API Clients')
+                formatter.display_status('Check or create in integration:')
+                formatter.display_status("- name: #{@info[:name]}")
+                formatter.display_status("- redirect uri: #{DEFAULT_REDIRECT}")
+                formatter.display_status('- origin: localhost')
+                formatter.display_status('Use the generated client id and secret in the following prompts.'.red)
+              end
+              OpenApplication.instance.uri("#{instance_url}/#{AOC_PATH_API_CLIENTS}")
+              options.get_option(:client_id, mandatory: true)
+              options.get_option(:client_secret, mandatory: true)
+              use_browser_authentication = true
+            end
+            if use_browser_authentication
+              formatter.display_status('We will use web authentication to bootstrap.')
+              auto_set_pub_key = true
+              auto_set_jwt = true
+              aoc_api.oauth.generic_parameters[:grant_method] = :web
+              aoc_api.oauth.generic_parameters[:scope] = AoC::SCOPE_FILES_ADMIN
+              aoc_api.oauth.specific_parameters[:redirect_uri] = DEFAULT_REDIRECT
+            end
+            myself = object.aoc_api.read('self')[:data]
+            if auto_set_pub_key
+              assert(myself['public_key'].empty?, exception_class: Cli::Error){'Public key is already set in profile (use --override=yes)'} unless option_override
+              formatter.display_status('Updating profile with the public key.')
+              aoc_api.update("users/#{myself['id']}", {'public_key' => pub_key_pem})
+            end
+            if auto_set_jwt
+              formatter.display_status('Enabling JWT for client')
+              aoc_api.update("clients/#{options.get_option(:client_id)}", {'jwt_grant_enabled' => true, 'explicit_authorization_required' => false})
+            end
+            preset_result = {
+              url:         instance_url,
+              username:    myself['email'],
+              auth:        :jwt.to_s,
+              private_key: "@file:#{private_key_path}"
+            }
+            # set only if non nil
+            %i[client_id client_secret].each do |s|
+              o = options.get_option(s)
+              preset_result[s.to_s] = o unless o.nil?
+            end
+            return {
+              preset_value: preset_result,
+              test_args:    'user profile show'
+            }
           end
         end
         # special value for package id
@@ -53,9 +166,11 @@ module Aspera
           client_registration_token
           client_access_key
           kms_profile].freeze
-        # TODO: remove this and use %name: instead
-        ENTITY_NAME_SPECIFIER = 'name'
-        PACKAGE_QUERY_DEFAULT = {'archived' => false, 'exclude_dropbox_packages' => true, 'has_content' => true, 'received' => true}.freeze
+        PACKAGE_RECEIVED_BASE_QUERY = {
+          'archived'    => false,
+          'has_content' => true,
+          'received'    => true,
+          'completed'   => true}.freeze
 
         def initialize(env)
           super(env)
@@ -63,135 +178,60 @@ module Aspera
           @cache_home_node_file = nil
           @cache_api_aoc = nil
           options.declare(:auth, 'OAuth type of authentication', values: Oauth::STD_AUTH_TYPES, default: :jwt)
-          options.declare(:operation, 'Client operation for transfers', values: %i[push pull], default: :push)
           options.declare(:client_id, 'OAuth API client identifier')
           options.declare(:client_secret, 'OAuth API client secret')
+          options.declare(:scope, 'OAuth scope for AoC API calls', default: AoC::SCOPE_FILES_USER)
           options.declare(:redirect_uri, 'OAuth API client redirect URI')
           options.declare(:private_key, 'OAuth JWT RSA private key PEM value (prefix file path with @file:)')
-          options.declare(:scope, 'OAuth scope for AoC API calls', default: AoC::SCOPE_FILES_USER)
           options.declare(:passphrase, 'RSA private key passphrase')
-          options.declare(:workspace, 'Name of workspace', default: :default)
-          # TODO: remove this and use %name: instead
-          options.declare(:name, "Resource name (prefer to use keyword #{ENTITY_NAME_SPECIFIER})")
-          options.declare(:link, 'Public link to shared resource')
+          options.declare(:workspace, 'Name of workspace', types: [String, NilClass], default: Aspera::AoC::DEFAULT_WORKSPACE)
           options.declare(:new_user_option, 'New user creation option for unknown package recipients')
-          options.declare(:from_folder, 'Source folder for Folder-to-Folder transfer')
           options.declare(:validate_metadata, 'Validate shared inbox metadata', values: :bool, default: true)
           options.parse_options!
-          # add node plugin options (TODO: check needed ? if yes, tell why)
-          Node.new(env.merge({man_only: true, skip_basic_auth_options: true}))
+          # add node plugin options (for manual)
+          Node.declare_options(options)
         end
 
-        # build list of options for AoC API, based on options of CLI
-        def aoc_params(subpath)
-          # copy command line options to args
-          return Aspera::AoC::OPTIONS_NEW.each_with_object({subpath: subpath}){|i, m|m[i] = options.get_option(i)}
-        end
-
-        def aoc_api
-          if @cache_api_aoc.nil?
-            @cache_api_aoc = AoC.new(aoc_params(AoC::API_V1))
-            # add keychain for access key secrets
-            @cache_api_aoc.secret_finder = @agents[:config]
-          end
-          return @cache_api_aoc
-        end
+        OPTIONS_NEW = %i[url auth client_id client_secret scope redirect_uri private_key passphrase username password workspace].freeze
 
-        # @return [Hash] current workspace information,
-        def current_workspace_info
-          return @cache_workspace_info unless @cache_workspace_info.nil?
-          default_workspace_id = if aoc_api.url_token_data.nil?
-            aoc_api.current_user_info['default_workspace_id']
-          else
-            aoc_api.url_token_data['data']['workspace_id']
+        def api_from_options(new_base_path)
+          create_values = {subpath: new_base_path, secret_finder: @agents[:config]}
+          # create an API object with the same options, but with a different subpath
+          return Aspera::AoC.new(**OPTIONS_NEW.each_with_object(create_values) { |i, m|m[i] = options.get_option(i) unless options.get_option(i).nil?})
+        rescue ArgumentError => e
+          if (m = e.message.match(/missing keyword: :(.*)$/))
+            raise Cli::Error, "Missing option: #{m[1]}"
           end
-
-          ws_name = options.get_option(:workspace)
-          ws_id =
-            case ws_name
-            when :default
-              Log.log.debug('Using default workspace'.green)
-              raise CliError, 'No default workspace defined for user, please specify workspace' if default_workspace_id.nil?
-              default_workspace_id
-            when String then aoc_api.lookup_by_name('workspaces', ws_name)['id']
-            when NilClass then nil
-            else raise CliError, 'unexpected value type for workspace'
-            end
-          @cache_workspace_info =
-            begin
-              aoc_api.read("workspaces/#{ws_id}")[:data]
-            rescue Aspera::RestCallError => e
-              Log.log.debug(e.message)
-              { 'id' => :undefined, 'name' => :undefined }
-            end
-          Log.dump(:current_workspace_info, @cache_workspace_info)
-          # display workspace
-          default_flag = @cache_workspace_info['id'] == default_workspace_id ? ' (default)' : ''
-          formatter.display_status("Current Workspace: #{@cache_workspace_info['name'].to_s.red}#{default_flag}")
-          return @cache_workspace_info
+          raise
         end
 
-        # @return [Hash] with :node_id and :file_id
-        def home_info
-          return @cache_home_node_file unless @cache_home_node_file.nil?
-          if !aoc_api.url_token_data.nil?
-            assert_public_link_types(['view_shared_file'])
-            home_node_id = aoc_api.url_token_data['data']['node_id']
-            home_file_id = aoc_api.url_token_data['data']['file_id']
-          end
-          home_node_id ||= current_workspace_info['home_node_id'] || current_workspace_info['node_id']
-          home_file_id ||= current_workspace_info['home_file_id']
-          if home_node_id.to_s.empty?
-            # not part of any workspace, but has some folder shared
-            user_info = aoc_api.current_user_info(exception: true)
-            home_node_id = user_info['read_only_home_node_id']
-            home_file_id = user_info['read_only_home_file_id']
-          end
-
-          raise "Cannot get user's home node id, check your default workspace or specify one" if home_node_id.to_s.empty?
-          @cache_home_node_file = {
-            node_id: home_node_id,
-            file_id: home_file_id
-          }
-          return @cache_home_node_file
+        def aoc_api
+          @cache_api_aoc = api_from_options(AoC::API_V1) if @cache_api_aoc.nil?
+          return @cache_api_aoc
         end
 
         # get identifier or name from command line
         # @return identifier
         def get_resource_id_from_args(resource_class_path)
-          l_res_id = options.get_option(:id)
-          l_res_name = options.get_option(:name)
-          raise 'Provide either option id or name, not both' unless l_res_id.nil? || l_res_name.nil?
-          # try to find item by name (single partial match or exact match)
-          l_res_id = aoc_api.lookup_by_name(resource_class_path, l_res_name)['id'] unless l_res_name.nil?
-          # if no name or id option, taken on command line (after command)
-          if l_res_id.nil?
-            l_res_id = options.get_next_argument('identifier')
-            l_res_id = aoc_api.lookup_by_name(resource_class_path, options.get_next_argument('identifier'))['id'] if l_res_id.eql?(ENTITY_NAME_SPECIFIER)
+          return instance_identifier do |field, value|
+            assert(field.eql?('name'), exception_class: Cli::BadArgument){'only selection by name is supported'}
+            aoc_api.lookup_by_name(resource_class_path, value)['id']
           end
-          return l_res_id
         end
 
         def get_resource_path_from_args(resource_class_path)
           return "#{resource_class_path}/#{get_resource_id_from_args(resource_class_path)}"
         end
 
-        def assert_public_link_types(expected)
-          raise CliBadArgument, "public link type is #{aoc_api.url_token_data['purpose']} but action requires one of #{expected.join(',')}" \
-          unless expected.include?(aoc_api.url_token_data['purpose'])
-        end
-
-        # Call aoc_api.read with same parameters.
-        # Use paging if necessary to get all results
-        # @return [Hash] {list: , total: }
-        def read_with_paging(resource_class_path, base_query)
-          raise 'Query must be Hash' unless base_query.is_a?(Hash)
+        # Call block with same query using paging and response information
+        # @return [Hash] {data: , total: }
+        def api_call_paging(base_query={})
+          assert_type(base_query, Hash){'query'}
+          assert(block_given?)
           # set default large page if user does not specify own parameters. AoC Caps to 1000 anyway
           base_query['per_page'] = 1000 unless base_query.key?('per_page')
-          max_items = base_query[MAX_ITEMS]
-          base_query.delete(MAX_ITEMS)
-          max_pages = base_query[MAX_PAGES]
-          base_query.delete(MAX_PAGES)
+          max_items = base_query.delete(MAX_ITEMS)
+          max_pages = base_query.delete(MAX_PAGES)
           item_list = []
           total_count = nil
           current_page = base_query['page']
@@ -200,7 +240,7 @@ module Aspera
           loop do
             query = base_query.clone
             query['page'] = current_page
-            result = aoc_api.read(resource_class_path, query)
+            result = yield(query)
             total_count = result[:http]['X-Total-Count']
             page_count += 1
             current_page += 1
@@ -208,10 +248,40 @@ module Aspera
             break if add_items.empty?
             # append new items to full list
             item_list += add_items
-            break if !max_pages.nil? && page_count > max_pages
-            break if !max_items.nil? && item_list.count > max_items
+            break if !max_items.nil? && item_list.count >= max_items
+            break if !max_pages.nil? && page_count >= max_pages
           end
-          return {list: item_list, total: total_count}
+          item_list = item_list[0..max_items - 1] if !max_items.nil? && item_list.count > max_items
+          return {data: item_list, total: total_count}
+        end
+
+        # read using the query and paging
+        # @return [Hash] {data: , total: }
+        def api_read_all(resource_class_path, base_query={})
+          return api_call_paging(base_query) do |query|
+            aoc_api.read(resource_class_path, query)
+          end
+        end
+
+        # list all entities, given additional, default and user's queries
+        def result_list(resource_class_path, fields: nil, base_query: {}, default_query: {})
+          assert_type(base_query, Hash)
+          assert_type(default_query, Hash)
+          user_query = query_read_delete(default: default_query)
+          # caller may add specific modifications or checks
+          yield(user_query) if block_given?
+          return {type: :object_list, fields: fields}.merge(api_read_all(resource_class_path, base_query.merge(user_query)))
+        end
+
+        def resolve_dropbox_name_default_ws_id(query)
+          if query.key?('dropbox_name')
+            # convenience: specify name instead of id
+            raise 'not both dropbox_name and dropbox_id' if query.key?('dropbox_id')
+            query['dropbox_id'] = aoc_api.lookup_by_name('dropboxes', query['dropbox_name'])['id']
+            query.delete('dropbox_name')
+          end
+          query['workspace_id'] ||= aoc_api.context[:workspace_id] unless aoc_api.context[:workspace_id].eql?(:undefined)
+          query['exclude_dropbox_packages'] = true unless query.key?('dropbox_id')
         end
 
         NODE4_EXT_COMMANDS = %i[transfer].concat(Node::COMMANDS_GEN4).freeze
@@ -221,33 +291,32 @@ module Aspera
         # @param scope [String] node scope, or nil (admin)
         def execute_nodegen4_command(command_repo, node_id, file_id: nil, scope: nil)
           top_node_api = aoc_api.node_api_from(
-            node_id: node_id,
-            workspace_id: current_workspace_info['id'],
-            workspace_name: current_workspace_info['name'],
-            scope: scope
+            node_id:        node_id,
+            workspace_id:   aoc_api.context[:workspace_id],
+            workspace_name: aoc_api.context[:workspace_name],
+            scope:          scope
           )
           file_id = top_node_api.read("access_keys/#{top_node_api.app_info[:node_info]['access_key']}")[:data]['root_file_id'] if file_id.nil?
-          node_plugin = Node.new(@agents.merge(
-            skip_basic_auth_options: true,
-            skip_node_options:       true,
-            node_api:                top_node_api))
+          node_plugin = Node.new(@agents, api: top_node_api)
           case command_repo
           when *Node::COMMANDS_GEN4
             return node_plugin.execute_command_gen4(command_repo, file_id)
           when :transfer
             # client side is agent
-            # server side is protocol server
+            # server side is transfer server
             # in same workspace
-            # default is push
-            case options.get_option(:operation, mandatory: true)
+            push_pull = options.get_next_argument('direction', expected: %i[push pull])
+            source_folder = options.get_next_argument('folder of source files', type: String)
+            case push_pull
             when :push
               client_direction = Fasp::TransferSpec::DIRECTION_SEND
-              client_folder = options.get_option(:from_folder, mandatory: true)
+              client_folder = source_folder
               server_folder = transfer.destination_folder(client_direction)
             when :pull
               client_direction = Fasp::TransferSpec::DIRECTION_RECEIVE
               client_folder = transfer.destination_folder(client_direction)
-              server_folder = options.get_option(:from_folder, mandatory: true)
+              server_folder = source_folder
+            else error_unreachable_line
             end
             client_apfid = top_node_api.resolve_api_fid(file_id, client_folder)
             server_apfid = top_node_api.resolve_api_fid(file_id, server_folder)
@@ -268,9 +337,9 @@ module Aspera
               server_apfid[:file_id],
               client_direction,
               add_ts)))
-          else raise "INTERNAL ERROR: Missing case: #{command_repo}"
+          else error_unreachable_line
           end # command_repo
-          # raise 'internal error:shall not reach here'
+          error_unreachable_line
         end # execute_nodegen4_command
 
         def execute_admin_action
@@ -282,14 +351,14 @@ module Aspera
             command_auth_prov = options.get_next_command(%i[list update])
             case command_auth_prov
             when :list
-              providers = aoc_api.read('admin/auth_providers')[:data]
-              return {type: :object_list, data: providers}
+              return result_list('admin/auth_providers')
             when :update
               raise 'not implemented'
             end
           when :subscription
             org = aoc_api.read('organization')[:data]
-            bss_api = AoC.new(aoc_params('bss/platform'))
+            bss_api = api_from_options('bss/platform')
+            # cspell:disable
             graphql_query = "
     query ($organization_id: ID!) {
       aoc (organization_id: $organization_id) {
@@ -338,17 +407,18 @@ module Aspera
       }
     }
   "
+            # cspell:enable
             result = bss_api.create('graphql', {'variables' => {'organization_id' => org['id']}, 'query' => graphql_query})[:data]['data']
             return {type: :single_object, data: result['aoc']['bssSubscription']}
           when :ats
             ats_api = Rest.new(aoc_api.params.deep_merge({
-              base_url: aoc_api.params[:base_url] + '/admin/ats/pub/v1',
+              base_url: "#{aoc_api.params[:base_url]}/admin/ats/pub/v1",
               auth:     {scope: AoC::SCOPE_FILES_ADMIN_USER}
             }))
-            return Ats.new(@agents.merge(skip_node_options: true)).execute_action_gen(ats_api)
+            return Ats.new(@agents).execute_action_gen(ats_api)
           when :analytics
             analytics_api = Rest.new(aoc_api.params.deep_merge({
-              base_url: aoc_api.params[:base_url].gsub('/api/v1', '') + '/analytics/v2',
+              base_url: "#{aoc_api.params[:base_url].gsub('/api/v1', '')}/analytics/v2",
               auth:     {scope: AoC::SCOPE_FILES_ADMIN_USER}
             }))
             command_analytics = options.get_next_command(%i[application_events transfers])
@@ -359,25 +429,28 @@ module Aspera
               return {type: :object_list, data: events}
             when :transfers
               event_type = command_analytics.to_s
-              filter_resource = options.get_option(:name) || 'organizations'
-              filter_id = options.get_option(:id) ||
+              filter_resource = options.get_next_argument('resource', expected: %i[organizations users nodes])
+              filter_id = options.get_next_argument('identifier', mandatory: false) ||
                 case filter_resource
-                when 'organizations' then aoc_api.current_user_info['organization_id']
-                when 'users' then aoc_api.current_user_info['id']
-                when 'nodes' then aoc_api.current_user_info['id'] # TODO: consistent ? # rubocop:disable Lint/DuplicateBranch
-                else raise 'organizations or users for option --name'
+                when :organizations then aoc_api.current_user_info['organization_id']
+                when :users then aoc_api.current_user_info['id']
+                when :nodes then aoc_api.current_user_info['id'] # TODO: consistent ? # rubocop:disable Lint/DuplicateBranch
+                else error_unreachable_line
                 end
               filter = options.get_option(:query) || {}
-              raise 'query must be Hash' unless filter.is_a?(Hash)
               filter['limit'] ||= 100
               if options.get_option(:once_only, mandatory: true)
                 saved_date = []
                 start_date_persistency = PersistencyActionOnce.new(
                   manager: @agents[:persistency],
                   data: saved_date,
-                  ids: IdGenerator.from_list(['aoc_ana_date', options.get_option(:url, mandatory: true), current_workspace_info['name']].push(
-                    filter_resource,
-                    filter_id)))
+                  id: IdGenerator.from_list([
+                    'aoc_ana_date',
+                    options.get_option(:url, mandatory: true),
+                    aoc_api.context(:files)[:workspace_name],
+                    filter_resource.to_s,
+                    filter_id
+                  ]))
                 start_date_time = saved_date.first
                 stop_date_time = Time.now.utc.strftime('%FT%T.%LZ')
                 # Log.log().error("start: #{start_date_time}")
@@ -388,7 +461,7 @@ module Aspera
               end
               events = analytics_api.read("#{filter_resource}/#{filter_id}/#{event_type}", query_read_delete(default: filter))[:data][event_type]
               start_date_persistency&.save
-              if !options.get_option(:notif_to).nil?
+              if !options.get_option(:notify_to).nil?
                 events.each do |tr_event|
                   config.send_email_template(values: {ev: tr_event})
                 end
@@ -404,7 +477,7 @@ module Aspera
               when :self, :organization then resource_type
               when :client_registration_token, :client_access_key then "admin/#{resource_type}s"
               when :application then 'admin/apps_new'
-              when :dropbox then resource_type.to_s + 'es'
+              when :dropbox then "#{resource_type}es"
               when :kms_profile then "integrations/#{resource_type}s"
               else "#{resource_type}s"
               end
@@ -428,9 +501,7 @@ module Aspera
               id_result = 'token' if resource_class_path.eql?('admin/client_registration_tokens')
               # TODO: report inconsistency: creation url is !=, and does not return id.
               resource_class_path = 'admin/client_registration/token' if resource_class_path.eql?('admin/client_registration_tokens')
-              list_or_one = options.get_next_argument('creation data', type: Hash)
-              return do_bulk_operation(list_or_one, 'created', id_result: id_result) do |params|
-                raise 'expecting Hash' unless params.is_a?(Hash)
+              return do_bulk_operation(command: command, descr: 'creation data', id_result: id_result) do |params|
                 aoc_api.create(resource_class_path, params)[:data]
               end
             when :list
@@ -450,35 +521,38 @@ module Aspera
               when :group_membership then default_fields.push(*%w[group_id member_type member_id])
               when :workspace_membership then default_fields.push(*%w[workspace_id member_type member_id])
               end
-              items = read_with_paging(resource_class_path, query_read_delete(default: default_query))
-              formatter.display_item_count(items[:list].length, items[:total])
-              return {type: :object_list, data: items[:list], fields: default_fields}
+              return result_list(resource_class_path, fields: default_fields, default_query: default_query)
             when :show
               object = aoc_api.read(resource_instance_path)[:data]
+              # default: show all, but certificate
               fields = object.keys.reject{|k|k.eql?('certificate')}
               return { type: :single_object, data: object, fields: fields }
             when :modify
-              changes = options.get_next_argument('modified parameters (hash)')
-              aoc_api.update(resource_instance_path, changes)
-              return Main.result_status('modified')
+              changes = options.get_next_argument('properties', type: Hash)
+              return do_bulk_operation(command: command, descr: 'identifier', values: res_id) do |one_id|
+                aoc_api.update("#{resource_class_path}/#{one_id}", changes)
+                {'id' => one_id}
+              end
             when :delete
-              return do_bulk_operation(res_id, 'deleted') do |one_id|
+              return do_bulk_operation(command: command, descr: 'identifier', values: res_id) do |one_id|
                 aoc_api.delete("#{resource_class_path}/#{one_id}")
                 {'id' => one_id}
               end
             when :set_pub_key
               # special : reads private and generate public
-              the_private_key = options.get_next_argument('private_key')
+              the_private_key = options.get_next_argument('private_key PEM value', type: String)
               the_public_key = OpenSSL::PKey::RSA.new(the_private_key).public_key.to_s
               aoc_api.update(resource_instance_path, {jwt_grant_enabled: true, public_key: the_public_key})
               return Main.result_success
             when :do
               command_repo = options.get_next_command(NODE4_EXT_COMMANDS)
+              # init context
+              aoc_api.context(:files)
               return execute_nodegen4_command(command_repo, res_id)
-            else raise 'unknown command'
+            else error_unexpected_value(command)
             end
           when :usage_reports
-            return {type: :object_list, data: aoc_api.read('usage_reports', {workspace_id: current_workspace_info['id']})[:data]}
+            return result_list('usage_reports', base_query: {workspace_id: aoc_api.context(:files)[:workspace_id]})
           end
         end
 
@@ -487,6 +561,15 @@ module Aspera
 
         def execute_action
           command = options.get_next_command(ACTIONS)
+          if %i[files packages].include?(command)
+            default_flag = ' (default)' if options.get_option(:workspace).eql?(:default)
+            app_context = aoc_api.context(command)
+            formatter.display_status("Workspace: #{app_context[:workspace_name].to_s.red}#{default_flag}")
+            if !aoc_api.private_link.nil?
+              folder_name = aoc_api.node_api_from(node_id: app_context[:home_node_id]).read("files/#{app_context[:home_file_id]}")[:data]['name']
+              formatter.display_status("Private Folder: #{folder_name}")
+            end
+          end
           case command
           when :reminder
             # send an email reminder with list of orgs
@@ -502,53 +585,59 @@ module Aspera
           when :tier_restrictions
             return { type: :single_object, data: aoc_api.read('tier_restrictions')[:data] }
           when :user
-            case options.get_next_command(%i[workspaces profile])
+            case options.get_next_command(%i[workspaces profile preferences])
             # when :settings
             # return {type: :object_list,data: aoc_api.read('client_settings/')[:data]}
             when :workspaces
               case options.get_next_command(%i[list current])
               when :list
-                return {type: :object_list, data: aoc_api.read('workspaces')[:data], fields: %w[id name]}
+                return result_list('workspaces', fields: %w[id name])
               when :current
-                return { type: :single_object, data: current_workspace_info }
+                return { type: :single_object, data: aoc_api.read("workspaces/#{aoc_api.context(:files)[:workspace_id]}")[:data] }
               end
             when :profile
               case options.get_next_command(%i[show modify])
               when :show
                 return { type: :single_object, data: aoc_api.current_user_info(exception: true) }
               when :modify
-                aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", options.get_next_argument('modified parameters (hash)'))
+                aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", options.get_next_argument('properties', type: Hash))
+                return Main.result_status('modified')
+              end
+            when :preferences
+              user_preferences_res = "users/#{aoc_api.current_user_info(exception: true)['id']}/user_interaction_preferences"
+              case options.get_next_command(%i[show modify])
+              when :show
+                return { type: :single_object, data: aoc_api.read(user_preferences_res)[:data] }
+              when :modify
+                aoc_api.update(user_preferences_res, options.get_next_argument('properties', type: Hash))
                 return Main.result_status('modified')
               end
             end
           when :packages
-            package_command = options.get_next_command(%i[shared_inboxes send recv list show delete].concat(Node::NODE4_READ_ACTIONS))
+            package_command = options.get_next_command(%i[shared_inboxes send receive list show delete].concat(Node::NODE4_READ_ACTIONS), aliases: {recv: :receive})
             case package_command
             when :shared_inboxes
               case options.get_next_command(%i[list show])
               when :list
-                query = query_read_delete
-                if query.nil?
-                  query = {'embed[]' => 'dropbox', 'aggregate_permissions_by_dropbox' => true, 'sort' => 'dropbox_name'}
-                  query['workspace_id'] = current_workspace_info['id'] unless current_workspace_info['id'].eql?(:undefined)
-                end
-                return {type: :object_list, data: aoc_api.read('dropbox_memberships', query)[:data], fields: ['dropbox_id', 'dropbox.name']}
+                default_query = {'embed[]' => 'dropbox', 'aggregate_permissions_by_dropbox' => true, 'sort' => 'dropbox_name'}
+                default_query['workspace_id'] = aoc_api.context[:workspace_id] unless aoc_api.context[:workspace_id].eql?(:undefined)
+                return result_list('dropbox_memberships', fields: %w[dropbox_id dropbox.name], default_query: default_query)
               when :show
                 return {type: :single_object, data: aoc_api.read(get_resource_path_from_args('dropboxes'), query)[:data]}
               end
             when :send
-              package_data = value_create_modify(command: package_command, type: Hash)
+              package_data = value_create_modify(command: package_command)
               new_user_option = options.get_option(:new_user_option)
               option_validate = options.get_option(:validate_metadata)
               # works for both normal usr auth and link auth
-              package_data['workspace_id'] ||= current_workspace_info['id']
+              package_data['workspace_id'] ||= aoc_api.context[:workspace_id]
 
-              if !aoc_api.url_token_data.nil?
-                assert_public_link_types(%w[send_package_to_user send_package_to_dropbox])
-                box_type = aoc_api.url_token_data['purpose'].split('_').last
-                package_data['recipients'] = [{'id' => aoc_api.url_token_data['data']["#{box_type}_id"], 'type' => box_type}]
+              if !aoc_api.public_link.nil?
+                aoc_api.assert_public_link_types(%w[send_package_to_user send_package_to_dropbox])
+                box_type = aoc_api.public_link['purpose'].split('_').last
+                package_data['recipients'] = [{'id' => aoc_api.public_link['data']["#{box_type}_id"], 'type' => box_type}]
                 # enforce workspace id from link (should be already ok, but in case user wanted to override)
-                package_data['workspace_id'] = aoc_api.url_token_data['data']['workspace_id']
+                package_data['workspace_id'] = aoc_api.public_link['data']['workspace_id']
               end
 
               # transfer may raise an error
@@ -556,41 +645,47 @@ module Aspera
               Main.result_transfer(transfer.start(created_package[:spec], rest_token: created_package[:node]))
               # return all info on package (especially package id)
               return { type: :single_object, data: created_package[:info]}
-            when :recv
-              if !aoc_api.url_token_data.nil?
-                assert_public_link_types(['view_received_package'])
-                options.set_option(:id, aoc_api.url_token_data['data']['package_id'])
+            when :receive
+              ids_to_download = nil
+              if !aoc_api.public_link.nil?
+                aoc_api.assert_public_link_types(['view_received_package'])
+                # set the package id, it will
+                ids_to_download = aoc_api.public_link['data']['package_id']
               end
-              # scalar here
-              ids_to_download = instance_identifier
+              # get from command line unless it was a public link
+              ids_to_download ||= instance_identifier
               skip_ids_data = []
               skip_ids_persistency = nil
               if options.get_option(:once_only, mandatory: true)
+                # TODO: add query info to id
                 skip_ids_persistency = PersistencyActionOnce.new(
                   manager: @agents[:persistency],
                   data: skip_ids_data,
-                  id: IdGenerator.from_list(['aoc_recv', options.get_option(:url, mandatory: true),
-                                             current_workspace_info['id']].concat(aoc_api.additional_persistence_ids)))
+                  id: IdGenerator.from_list(
+                    ['aoc_recv',
+                     options.get_option(:url, mandatory: true),
+                     aoc_api.context[:workspace_id]
+                    ].concat(aoc_api.additional_persistence_ids)))
               end
-              if VAL_ALL.eql?(ids_to_download)
-                query = query_read_delete(default: PACKAGE_QUERY_DEFAULT)
-                raise 'option query must be Hash' unless query.is_a?(Hash)
-                if query.key?('dropbox_name')
-                  # convenience: specify name instead of id
-                  raise 'not both dropbox_name and dropbox_id' if query.key?('dropbox_id')
-                  query['dropbox_id'] = aoc_api.lookup_by_name('dropboxes', query['dropbox_name'])['id']
-                  query.delete('dropbox_name')
-                end
-                query['workspace_id'] ||= current_workspace_info['id'] unless current_workspace_info['id'].eql?(:undefined)
-                # get list of packages in inbox
-                package_info = aoc_api.read('packages', query)[:data]
+              case ids_to_download
+              when ExtendedValue::ALL, ExtendedValue::INIT
+                query = query_read_delete(default: PACKAGE_RECEIVED_BASE_QUERY)
+                assert_type(query, Hash){'query'}
+                resolve_dropbox_name_default_ws_id(query)
                 # remove from list the ones already downloaded
-                ids_to_download = package_info.map{|e|e['id']}
+                all_ids = api_read_all('packages', query)[:data].map{|e|e['id']}
+                if ids_to_download.eql?(ExtendedValue::INIT)
+                  assert(skip_ids_persistency){'Only with option once_only'}
+                  skip_ids_persistency.data.clear.concat(all_ids)
+                  skip_ids_persistency.save
+                  return Main.result_status("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
+                end
                 # array here
-                ids_to_download.reject!{|id|skip_ids_data.include?(id)}
-              end # VAL_ALL
+                ids_to_download = all_ids.reject{|id|skip_ids_data.include?(id)}
+              else
+                ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
+              end # ExtendedValue::ALL
               # list here
-              ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
               result_transfer = []
               formatter.display_status("found #{ids_to_download.length} package(s).")
               ids_to_download.each do |package_id|
@@ -598,8 +693,8 @@ module Aspera
                 formatter.display_status("downloading package: #{package_info['name']}")
                 package_node_api = aoc_api.node_api_from(
                   node_id: package_info['node_id'],
-                  workspace_id: current_workspace_info['id'],
-                  workspace_name: current_workspace_info['name'],
+                  workspace_id: aoc_api.context[:workspace_id],
+                  workspace_name: aoc_api.context[:workspace_name],
                   package_info: package_info)
                 statuses = transfer.start(
                   package_node_api.transfer_spec_gen4(
@@ -616,61 +711,48 @@ module Aspera
               end
               return Main.result_transfer_multiple(result_transfer)
             when :show
-              package_id = options.get_next_argument('package ID')
+              package_id = instance_identifier
               package_info = aoc_api.read("packages/#{package_id}")[:data]
               return { type: :single_object, data: package_info }
             when :list
               display_fields = %w[id name bytes_transferred]
-              query = query_read_delete(default: PACKAGE_QUERY_DEFAULT)
-              raise 'option query must be Hash' unless query.is_a?(Hash)
-              if query.key?('dropbox_name')
-                # convenience: specify name instead of id
-                raise 'not both dropbox_name and dropbox_id' if query.key?('dropbox_id')
-                query['dropbox_id'] = aoc_api.lookup_by_name('dropboxes', query['dropbox_name'])['id']
-                query.delete('dropbox_name')
-              end
-              if current_workspace_info['id'].eql?(:undefined)
-                display_fields.push('workspace_id')
-              else
-                query['workspace_id'] ||= current_workspace_info['id']
-              end
-              packages = aoc_api.read('packages', query)[:data]
-              return {type: :object_list, data: packages, fields: display_fields}
+              display_fields.push('workspace_id') if aoc_api.context[:workspace_id].eql?(:undefined)
+              return result_list('packages', fields: display_fields, base_query: PACKAGE_RECEIVED_BASE_QUERY) do |query|
+                       resolve_dropbox_name_default_ws_id(query)
+                     end
             when :delete
-              list_or_one = instance_identifier
-              return do_bulk_operation(list_or_one, 'deleted') do |id|
-                raise 'expecting String identifier' unless id.is_a?(String) || id.is_a?(Integer)
+              return do_bulk_operation(command: package_command, descr: 'identifier', values: identifier) do |id|
+                assert_values(id.class, [String, Integer]){'identifier'}
                 aoc_api.delete("packages/#{id}")[:data]
               end
             when *Node::NODE4_READ_ACTIONS
-              package_id = options.get_next_argument('package ID')
+              package_id = instance_identifier
               package_info = aoc_api.read("packages/#{package_id}")[:data]
-              return execute_nodegen4_command(package_command, package_info['node_id'], file_id: package_info['file_id'], scope: AoC::SCOPE_NODE_USER)
+              return execute_nodegen4_command(package_command, package_info['node_id'], file_id: package_info['file_id'], scope: Aspera::Node::SCOPE_USER)
             end
           when :files
             command_repo = options.get_next_command([:short_link].concat(NODE4_EXT_COMMANDS))
             case command_repo
             when *NODE4_EXT_COMMANDS
-              return execute_nodegen4_command(command_repo, home_info[:node_id], file_id: home_info[:file_id], scope: AoC::SCOPE_NODE_USER)
+              return execute_nodegen4_command(command_repo, aoc_api.context[:home_node_id], file_id: aoc_api.context[:home_file_id], scope: Aspera::Node::SCOPE_USER)
             when :short_link
-              # execute action on AoC API
-              short_link_command = options.get_next_command(%i[create delete list])
-              folder_dest = options.get_next_argument('path')
               link_type = options.get_next_argument('link type', expected: %i[public private])
+              short_link_command = options.get_next_command(%i[create delete list])
+              folder_dest = options.get_next_argument('path', type: String)
               home_node_api = aoc_api.node_api_from(
-                node_id: home_info[:node_id],
-                workspace_id: current_workspace_info['id'],
-                workspace_name: current_workspace_info['name'])
-              shared_apfid = home_node_api.resolve_api_fid(home_info[:file_id], folder_dest)
+                node_id:        aoc_api.context[:home_node_id],
+                workspace_id:   aoc_api.context[:workspace_id],
+                workspace_name: aoc_api.context[:workspace_name])
+              shared_apfid = home_node_api.resolve_api_fid(aoc_api.context[:home_file_id], folder_dest)
               folder_info = {
                 node_id:      shared_apfid[:api].app_info[:node_info]['id'],
                 file_id:      shared_apfid[:file_id],
-                workspace_id: current_workspace_info['id']
+                workspace_id: aoc_api.context[:workspace_id]
               }
               purpose = case link_type
               when :public  then 'token_auth_redirection'
               when :private then 'shared_folder_auth_link'
-              else raise 'internal error'
+              else error_unreachable_line
               end
               case short_link_command
               when :delete
@@ -699,14 +781,12 @@ module Aspera
                 end
                 list_params = {
                   json_query:  query.to_json,
-                  edit_access: true,
                   purpose:     purpose,
+                  edit_access: true,
                   # embed: 'updated_by_user',
                   sort:        '-created_at'
                 }
-                result = aoc_api.read('short_links', list_params)[:data]
-                result.each{|i|i.delete('data')}
-                return {type: :object_list, data: result}
+                return result_list('short_links', fields: Formatter.all_but('data'), base_query: list_params)
               when :create
                 creation_params = {
                   purpose:            purpose,
@@ -741,8 +821,8 @@ module Aspera
                     'access_levels' => access_levels,
                     'tags'          => {
                       'url_token'        => true,
-                      'workspace_id'     => current_workspace_info['id'],
-                      'workspace_name'   => current_workspace_info['name'],
+                      'workspace_id'     => aoc_api.context[:workspace_id],
+                      'workspace_name'   => aoc_api.context[:workspace_name],
                       'folder_name'      => folder_name,
                       'created_by_name'  => aoc_api.current_user_info['name'],
                       'created_by_email' => aoc_api.current_user_info['email'],
@@ -772,7 +852,7 @@ module Aspera
               wf_command = options.get_next_command(%i[action launch].concat(Plugin::ALL_OPS))
               case wf_command
               when *Plugin::ALL_OPS
-                return entity_command(wf_command, automation_api, 'workflows', id_default: :id)
+                return entity_command(wf_command, automation_api, 'workflows')
               when :launch
                 wf_id = instance_identifier
                 data = automation_api.create("workflows/#{wf_id}/launch", {})[:data]
@@ -794,106 +874,22 @@ module Aspera
             return execute_admin_action
           when :gateway
             require 'aspera/faspex_gw'
-            url = value_create_modify(type: String)
+            url = value_create_modify(command: command, type: String)
             uri = URI.parse(url)
             server = WebServerSimple.new(uri)
-            server.mount(uri.path, Faspex4GWServlet, aoc_api, current_workspace_info['id'])
+            server.mount(uri.path, Faspex4GWServlet, aoc_api, aoc_api.context(:files)[:workspace_id])
             trap('INT') { server.shutdown }
             formatter.display_status("Faspex 4 gateway listening on #{url}")
             Log.log.info("Listening on #{url}")
             # this is blocking until server exits
             server.start
             return Main.result_status('Gateway terminated')
-          else
-            raise "internal error: #{command}"
+          else error_unreachable_line
           end # action
-          raise 'internal error: command shall return'
-        end
-
-        # @param [Hash] params : plugin_sym, instance_url
-        # @return [Hash] :preset_value, :test_args
-        def wizard(params)
-          if params[:prepare]
-            organization = AoC.parse_url(params[:instance_url]).first
-            # if not defined by user, generate name
-            params[:preset_name] ||= [params[:plugin_sym], organization].join('_')
-            params[:need_private_key] = true
-            return
-          end
-          options.set_option(:private_key, '@file:' + params[:private_key_path])
-          # make username mandatory for jwt, this triggers interactive input
-          options.get_option(:username, mandatory: true)
-          auto_set_pub_key = false
-          auto_set_jwt = false
-          use_browser_authentication = false
-          if options.get_option(:use_generic_client)
-            formatter.display_status('Using global client_id.')
-            formatter.display_status('Please Login to your Aspera on Cloud instance.'.red)
-            formatter.display_status('Navigate to your "Account Settings"'.red)
-            formatter.display_status('Check or update the value of "Public Key" to be:'.red.blink)
-            formatter.display_status(params[:pub_key_pem])
-            if !options.get_option(:test_mode)
-              formatter.display_status('Once updated or validated, press enter.')
-              OpenApplication.instance.uri(params[:instance_url])
-              $stdin.gets
-            end
-          else
-            formatter.display_status('Using organization specific client_id.')
-            if options.get_option(:client_id).nil? || options.get_option(:client_secret).nil?
-              formatter.display_status('Please login to your Aspera on Cloud instance.'.red)
-              formatter.display_status('Go to: Apps->Admin->Organization->Integrations')
-              formatter.display_status('Create or check if there is an existing integration named:')
-              formatter.display_status("- name: #{@info[:name]}")
-              formatter.display_status("- redirect uri: #{DEFAULT_REDIRECT}")
-              formatter.display_status('- origin: localhost')
-              formatter.display_status('Once created or identified,')
-              formatter.display_status('Please enter:'.red)
-            end
-            OpenApplication.instance.uri("#{params[:instance_url]}/#{AOC_PATH_API_CLIENTS}")
-            options.get_option(:client_id, mandatory: true)
-            options.get_option(:client_secret, mandatory: true)
-            use_browser_authentication = true
-          end
-          if use_browser_authentication
-            formatter.display_status('We will use web authentication to bootstrap.')
-            auto_set_pub_key = true
-            auto_set_jwt = true
-            aoc_api.oauth.generic_parameters[:grant_method] = :web
-            aoc_api.oauth.generic_parameters[:scope] = AoC::SCOPE_FILES_ADMIN
-            aoc_api.oauth.specific_parameters[:redirect_uri] = DEFAULT_REDIRECT
-          end
-          myself = aoc_api.read('self')[:data]
-          if auto_set_pub_key
-            raise CliError, 'Public key is already set in profile (use --override=yes)' unless myself['public_key'].empty? || option_override
-            formatter.display_status('Updating profile with new key')
-            aoc_api.update("users/#{myself['id']}", {'public_key' => params[:pub_key_pem]})
-          end
-          if auto_set_jwt
-            formatter.display_status('Enabling JWT for client')
-            aoc_api.update("clients/#{options.get_option(:client_id)}", {'jwt_grant_enabled' => true, 'explicit_authorization_required' => false})
-          end
-          formatter.display_status("Creating new config preset: #{params[:preset_name]}")
-          preset_result = {
-            url:         params[:instance_url],
-            username:    myself['email'],
-            auth:        :jwt.to_s,
-            private_key: '@file:' + params[:private_key_path]
-          }.stringify_keys
-          # set only if non nil
-          %i[client_id client_secret].each do |s|
-            o = options.get_option(s)
-            preset_result[s.to_s] = o unless o.nil?
-          end
-          return {
-            preset_value: preset_result,
-            test_args:    "#{params[:plugin_sym]} user profile show"
-          }
+          error_unreachable_line
         end
 
-        private :aoc_params,
-          :home_info,
-          :assert_public_link_types,
-          :execute_admin_action
+        private :execute_admin_action
       end # AoC
     end # Plugins
   end # Cli