aspera-cli 4.13.0 → 4.15.0

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

@@ -17,15 +17,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 {product: :aoc, version: 'SaaS' }
+            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 {
+                preset_value: preset_value,
+                test_args:    'organization'
+              }
+            end
+            # 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
+              raise Cli::Error, 'Public key is already set in profile (use --override=yes)' unless myself['public_key'].empty? || 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 nil
+            return {
+              preset_value: preset_result,
+              test_args:    'user profile show'
+            }
           end
         end
         # special value for package id
@@ -50,7 +165,6 @@ module Aspera
           client_registration_token
           client_access_key
           kms_profile].freeze
-        ENTITY_NAME_SPECIFIER = 'name'
         PACKAGE_QUERY_DEFAULT = {'archived' => false, 'exclude_dropbox_packages' => true, 'has_content' => true, 'received' => true}.freeze
 
         def initialize(env)
@@ -58,130 +172,52 @@ module Aspera
           @cache_workspace_info = nil
           @cache_home_node_file = nil
           @cache_api_aoc = nil
-          options.add_opt_list(:auth, Oauth::STD_AUTH_TYPES, 'OAuth type of authentication')
-          options.add_opt_list(:operation, %i[push pull], 'client operation for transfers')
-          options.add_opt_simple(:client_id, 'OAuth API client identifier')
-          options.add_opt_simple(:client_secret, 'OAuth API client secret')
-          options.add_opt_simple(:redirect_uri, 'OAuth API client redirect URI')
-          options.add_opt_simple(:private_key, 'OAuth JWT RSA private key PEM value (prefix file path with @file:)')
-          options.add_opt_simple(:scope, 'OAuth scope for AoC API calls')
-          options.add_opt_simple(:passphrase, 'RSA private key passphrase')
-          options.add_opt_simple(:workspace, 'Name of workspace')
-          options.add_opt_simple(:name, "Resource name (prefer to use keyword #{ENTITY_NAME_SPECIFIER})")
-          options.add_opt_simple(:link, 'Public link to shared resource')
-          options.add_opt_simple(:new_user_option, 'New user creation option for unknown package recipients')
-          options.add_opt_simple(:from_folder, 'Source folder for Folder-to-Folder transfer')
-          options.add_opt_boolean(:validate_metadata, 'Validate shared inbox metadata')
-          options.set_option(:validate_metadata, :yes)
-          options.set_option(:operation, :push)
-          options.set_option(:auth, :jwt)
-          options.set_option(:scope, AoC::SCOPE_FILES_USER)
-          options.set_option(:private_key, '@file:' + env[:private_key_path]) if env[:private_key_path].is_a?(String)
-          options.set_option(:workspace, :default)
+          options.declare(:auth, 'OAuth type of authentication', values: Oauth::STD_AUTH_TYPES, default: :jwt)
+          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(:passphrase, 'RSA private key passphrase')
+          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(:validate_metadata, 'Validate shared inbox metadata', values: :bool, default: true)
           options.parse_options!
-          # add node plugin options
-          Node.new(env.merge({man_only: true, skip_basic_auth_options: true}))
-        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)}
+          # add node plugin options (for manual)
+          Node.declare_options(options)
         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_entity_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_entity_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_entity_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|
+            raise Cli::BadArgument, 'only selection by name is supported' unless field.eql?('name')
+            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: }
@@ -189,10 +225,8 @@ module Aspera
           raise 'Query must be Hash' unless base_query.is_a?(Hash)
           # 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']
@@ -209,9 +243,10 @@ 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
+          item_list = item_list[0..max_items - 1] if !max_items.nil? && item_list.count > max_items
           return {list: item_list, total: total_count}
         end
 
@@ -222,33 +257,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, is_type: :mandatory)
+            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, is_type: :mandatory)
+              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, is_type: :mandatory)
+              server_folder = source_folder
+            else raise 'internal error'
             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)
@@ -290,7 +324,8 @@ module Aspera
             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) {
@@ -339,17 +374,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])
@@ -360,24 +396,23 @@ 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 raise 'Internal error'
                 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, is_type: :mandatory)
+              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, is_type: :mandatory), current_workspace_info['name']].push(
-                    filter_resource,
+                  ids: IdGenerator.from_list(['aoc_ana_date', options.get_option(:url, mandatory: true), aoc_api.context[:workspace_name]].push(
+                    filter_resource.to_s,
                     filter_id)))
                 start_date_time = saved_date.first
                 stop_date_time = Time.now.utc.strftime('%FT%T.%LZ')
@@ -387,9 +422,9 @@ module Aspera
                 filter['start_time'] = start_date_time unless start_date_time.nil?
                 filter['stop_time'] = stop_date_time
               end
-              events = analytics_api.read("#{filter_resource}/#{filter_id}/#{event_type}", option_url_query(filter))[:data][event_type]
+              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
@@ -405,7 +440,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
@@ -429,9 +464,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
@@ -451,35 +484,39 @@ 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, option_url_query(default_query))
+              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}
             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)
+              aoc_api.context(:none)
               return execute_nodegen4_command(command_repo, res_id)
             else raise 'unknown command'
             end
           when :usage_reports
-            return {type: :object_list, data: aoc_api.read('usage_reports', {workspace_id: current_workspace_info['id']})[:data]}
+            return {type: :object_list, data: aoc_api.read('usage_reports', {workspace_id: aoc_api.context(:none)[:workspace_id]})[:data]}
           end
         end
 
@@ -488,10 +525,19 @@ 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
-            user_email = options.get_option(:username, is_type: :mandatory)
+            user_email = options.get_option(:username, mandatory: true)
             Rest.new(base_url: "#{AoC.api_base_url}/#{AoC::API_V1}").create('organization_reminders', {email: user_email})[:data]
             return Main.result_status("List of organizations user is member of, has been sent by e-mail to #{user_email}")
           when :servers
@@ -511,14 +557,14 @@ module Aspera
               when :list
                 return {type: :object_list, data: aoc_api.read('workspaces')[:data], 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(:none)[: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
             end
@@ -528,29 +574,28 @@ module Aspera
             when :shared_inboxes
               case options.get_next_command(%i[list show])
               when :list
-                query = option_url_query(nil)
+                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)
+                  query['workspace_id'] = aoc_api.context[:workspace_id] unless aoc_api.context[:workspace_id].eql?(:undefined)
                 end
                 return {type: :object_list, data: aoc_api.read('dropbox_memberships', query)[:data], fields: ['dropbox_id', 'dropbox.name']}
               when :show
                 return {type: :single_object, data: aoc_api.read(get_resource_path_from_args('dropboxes'), query)[:data]}
               end
             when :send
-              package_data = options.get_option(:value, is_type: :mandatory)
-              raise CliBadArgument, 'value must be hash, refer to doc' unless package_data.is_a?(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
@@ -559,38 +604,43 @@ module Aspera
               # 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'])
+              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, is_type: :mandatory)
+              if options.get_option(:once_only, mandatory: true)
                 skip_ids_persistency = PersistencyActionOnce.new(
                   manager: @agents[:persistency],
                   data: skip_ids_data,
-                  id: IdGenerator.from_list(['aoc_recv', options.get_option(:url, is_type: :mandatory),
-                                             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 = option_url_query(PACKAGE_QUERY_DEFAULT)
+              if ExtendedValue::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_entity_by_name('dropboxes', query['dropbox_name'])['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)
+                query['workspace_id'] ||= aoc_api.context[:workspace_id] unless aoc_api.context[:workspace_id].eql?(:undefined)
                 # get list of packages in inbox
                 package_info = aoc_api.read('packages', query)[:data]
                 # remove from list the ones already downloaded
                 ids_to_download = package_info.map{|e|e['id']}
                 # array here
                 ids_to_download.reject!{|id|skip_ids_data.include?(id)}
-              end # VAL_ALL
+              end # ExtendedValue::ALL
               # list here
               ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
               result_transfer = []
@@ -600,8 +650,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(
@@ -618,112 +668,145 @@ 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 = option_url_query(PACKAGE_QUERY_DEFAULT)
+              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_entity_by_name('dropboxes', query['dropbox_name'])['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)
+              if aoc_api.context[:workspace_id].eql?(:undefined)
                 display_fields.push('workspace_id')
               else
-                query['workspace_id'] ||= current_workspace_info['id']
+                query['workspace_id'] ||= aoc_api.context[:workspace_id]
               end
               packages = aoc_api.read('packages', query)[:data]
               return {type: :object_list, data: packages, fields: display_fields}
             when :delete
-              list_or_one = instance_identifier
-              return do_bulk_operation(list_or_one, 'deleted') do |id|
+              return do_bulk_operation(command: package_command, descr: 'identifier', values: identifier) do |id|
                 raise 'expecting String identifier' unless id.is_a?(String) || id.is_a?(Integer)
                 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
-              # TODO: move to permissions ?
-              folder_dest = options.get_option(:to_folder)
-              value_option = options.get_option(:value)
-              case value_option
-              when 'public'  then value_option = {'purpose' => 'token_auth_redirection'}
-              when 'private' then value_option = {'purpose' => 'shared_folder_auth_link'}
-              when NilClass, Hash then nil # keep value
-              else raise 'value must be either: public, private, Hash or nil'
+              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:        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: 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'
               end
-              create_params = nil
-              shared_apfid = nil
-              if !folder_dest.nil?
-                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)
-                create_params = {
-                  file_id:      shared_apfid[:file_id],
-                  node_id:      shared_apfid[:api].app_info[:node_info]['id'],
-                  workspace_id: current_workspace_info['id']
+              case short_link_command
+              when :delete
+                one_id = instance_identifier
+                folder_info.delete(:workspace_id)
+                delete_params = {
+                  edit_access: true,
+                  json_query:  folder_info.to_json
                 }
-              end
-              if !value_option.nil? && !create_params.nil?
-                case value_option['purpose']
-                when 'shared_folder_auth_link'
-                  value_option['data'] = create_params
-                  value_option['user_selected_name'] = nil
-                when 'token_auth_redirection'
-                  create_params['name'] = ''
-                  value_option['data'] = {
+                aoc_api.delete("short_links/#{one_id}", delete_params)
+                if link_type.eql?(:public)
+                  # TODO: get permission id..
+                  # shared_apfid[:api].delete('permissions', {ids: })[:data]
+                end
+                return Main.result_status('deleted')
+              when :list
+                query = if link_type.eql?(:private)
+                  folder_info
+                else
+                  {
+                    url_token_data: {
+                      data:    folder_info,
+                      purpose: 'view_shared_file'
+                    }
+                  }
+                end
+                list_params = {
+                  json_query:  query.to_json,
+                  purpose:     purpose,
+                  edit_access: true,
+                  # embed: 'updated_by_user',
+                  sort:        '-created_at'
+                }
+                result = aoc_api.read('short_links', list_params)[:data]
+                return {type: :object_list, data: result, fields: Formatter.all_but('data')}
+              when :create
+                creation_params = {
+                  purpose:            purpose,
+                  user_selected_name: nil
+                }
+                case link_type
+                when :private
+                  creation_params[:data] = folder_info
+                when :public
+                  creation_params[:expires_at]       = nil
+                  creation_params[:password_enabled] = false
+                  folder_info[:name] = ''
+                  creation_params[:data] = {
                     aoc:            true,
                     url_token_data: {
-                      data:    create_params,
+                      data:    folder_info,
                       purpose: 'view_shared_file'
                     }
                   }
-                  value_option['user_selected_name'] = nil
-                else
-                  raise 'purpose must be one of: token_auth_redirection or shared_folder_auth_link'
                 end
-                options.set_option(:value, value_option)
-              end
-              result = entity_action(aoc_api, 'short_links', id_default: 'self')
-              if result[:data].is_a?(Hash) && result[:data].key?('created_at') && result[:data]['resource_type'].eql?('UrlToken')
-                # TODO: access level as arg
-                access_levels = Aspera::Node::ACCESS_LEVELS # ['delete','list','mkdir','preview','read','rename','write']
-                perm_data = {
-                  'file_id'       => shared_apfid[:file_id],
-                  'access_type'   => 'user',
-                  'access_id'     => result[:data]['resource_id'],
-                  'access_levels' => access_levels,
-                  'tags'          => {
-                    'url_token'        => true,
-                    'workspace_id'     => current_workspace_info['id'],
-                    'workspace_name'   => current_workspace_info['name'],
-                    'folder_name'      => 'my folder',
-                    'created_by_name'  => aoc_api.current_user_info['name'],
-                    'created_by_email' => aoc_api.current_user_info['email'],
-                    'access_key'       => shared_apfid[:api].app_info[:node_info]['access_key'],
-                    'node'             => shared_apfid[:api].app_info[:node_info]['host']
+                result_create_short_link = aoc_api.create('short_links', creation_params)[:data]
+                # public: Creation: permission on node
+                if link_type.eql?(:public)
+                  # TODO: merge with node permissions ?
+                  # TODO: access level as arg
+                  access_levels = Aspera::Node::ACCESS_LEVELS # ['delete','list','mkdir','preview','read','rename','write']
+                  folder_name = File.basename(folder_dest)
+                  perm_data = {
+                    'file_id'       => shared_apfid[:file_id],
+                    'access_id'     => result_create_short_link['resource_id'],
+                    'access_type'   => 'user',
+                    'access_levels' => access_levels,
+                    'tags'          => {
+                      'url_token'        => true,
+                      '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'],
+                      'access_key'       => shared_apfid[:api].app_info[:node_info]['access_key'],
+                      'node'             => shared_apfid[:api].app_info[:node_info]['host']
+                    }
                   }
-                }
-                shared_apfid[:api].create("permissions?file_id=#{shared_apfid[:file_id]}", perm_data)
-                # TODO: event ?
-              end
-              return result
+                  created_data = shared_apfid[:api].create('permissions', perm_data)[:data]
+                  aoc_api.permissions_send_event(created_data: created_data, app_info: shared_apfid[:api].app_info)
+                  # TODO: event ?
+                end
+                return {type: :single_object, data: result_create_short_link}
+              end # short_link command
             end # files command
-            throw('Error: shall not reach this line')
+            raise 'Error: shall not reach this line'
           when :automation
             Log.log.warn('BETA: work under progress')
             # automation api is not in the same place
@@ -738,7 +821,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]
@@ -760,10 +843,10 @@ module Aspera
             return execute_admin_action
           when :gateway
             require 'aspera/faspex_gw'
-            url = options.get_option(:value, is_type: :mandatory)
+            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(:none)[:workspace_id])
             trap('INT') { server.shutdown }
             formatter.display_status("Faspex 4 gateway listening on #{url}")
             Log.log.info("Listening on #{url}")
@@ -776,10 +859,7 @@ module Aspera
           raise 'internal error: command shall return'
         end
 
-        private :aoc_params,
-          :home_info,
-          :assert_public_link_types,
-          :execute_admin_action
+        private :execute_admin_action
       end # AoC
     end # Plugins
   end # Cli