aspera-cli 4.13.0 → 4.15.0

data/lib/aspera/aoc.rb

@@ -5,6 +5,7 @@ require 'aspera/rest'
 require 'aspera/hash_ext'
 require 'aspera/data_repository'
 require 'aspera/fasp/transfer_spec'
+require 'aspera/node'
 require 'base64'
 require 'cgi'
 
@@ -27,9 +28,9 @@ module Aspera
   class AoC < Aspera::Rest
     PRODUCT_NAME = 'Aspera on Cloud'
     # Production domain of AoC
-    PROD_DOMAIN = 'ibmaspera.com'
+    PROD_DOMAIN = 'ibmaspera.com' # cspell:disable-line
     # to avoid infinite loop in pub link redirection
-    MAX_REDIRECT = 10
+    MAX_AOC_URL_REDIRECT = 10
     # Well-known AoC globals client apps
     GLOBAL_CLIENT_APPS = %w[aspera.global-cli-client aspera.drive].freeze
     # index offset in data repository of client app
@@ -37,20 +38,25 @@ module Aspera
     # cookie prefix so that console can decode identity
     COOKIE_PREFIX_CONSOLE_AOC = 'aspera.aoc'
     # path in URL of public links
-    PUBLIC_LINK_PATHS = %w[/packages/public/receive /packages/public/send /files/public].freeze
+    PUBLIC_LINK_PATHS = %w[/packages/public/receive /packages/public/send /files/public /public/files /public/send].freeze
     JWT_AUDIENCE = 'https://api.asperafiles.com/api/v1/oauth2/token'
     OAUTH_API_SUBPATH = 'api/v1/oauth2'
     # minimum fields for user info if retrieval fails
     USER_INFO_FIELDS_MIN = %w[name email id default_workspace_id organization_id].freeze
+    # types of events for shared folder creation
+    # Node events: permission.created permission.modified permission.deleted
+    PERMISSIONS_CREATED = ['permission.created'].freeze
+    DEFAULT_WORKSPACE = ''
 
-    private_constant :MAX_REDIRECT,
+    private_constant :MAX_AOC_URL_REDIRECT,
       :GLOBAL_CLIENT_APPS,
       :DATA_REPO_INDEX_START,
       :COOKIE_PREFIX_CONSOLE_AOC,
       :PUBLIC_LINK_PATHS,
       :JWT_AUDIENCE,
       :OAUTH_API_SUBPATH,
-      :USER_INFO_FIELDS_MIN
+      :USER_INFO_FIELDS_MIN,
+      :PERMISSIONS_CREATED
 
     # various API scopes supported
     SCOPE_FILES_SELF = 'self'
@@ -58,13 +64,9 @@ module Aspera
     SCOPE_FILES_ADMIN = 'admin:all'
     SCOPE_FILES_ADMIN_USER = 'admin-user:all'
     SCOPE_FILES_ADMIN_USER_USER = "#{SCOPE_FILES_ADMIN_USER}+#{SCOPE_FILES_USER}"
-    SCOPE_NODE_USER = 'user:all'
-    SCOPE_NODE_ADMIN = 'admin:all'
     FILES_APP = 'files'
     PACKAGES_APP = 'packages'
     API_V1 = 'api/v1'
-    # error message when entity not found
-    ENTITY_NOT_FOUND = 'No such'
 
     # class static methods
     class << self
@@ -75,20 +77,6 @@ module Aspera
         return client_name, Base64.urlsafe_encode64(DataRepository.instance.data(DATA_REPO_INDEX_START + client_index))
       end
 
-      # @param url of AoC instance
-      # @return organization id in url and AoC domain: ibmaspera.com, asperafiles.com or qa.asperafiles.com, etc...
-      def parse_url(aoc_org_url)
-        uri = URI.parse(aoc_org_url.gsub(%r{/+$}, ''))
-        instance_fqdn = uri.host
-        Log.log.debug{"instance_fqdn=#{instance_fqdn}"}
-        raise "No host found in URL.Please check URL format: https://myorg.#{PROD_DOMAIN}" if instance_fqdn.nil?
-        organization, instance_domain = instance_fqdn.split('.', 2)
-        Log.log.debug{"instance_domain=#{instance_domain}"}
-        Log.log.debug{"organization=#{organization}"}
-        raise "expecting a public FQDN for #{PRODUCT_NAME}" if instance_domain.nil?
-        return organization, instance_domain
-      end
-
       # base API url depends on domain, which could be "qa.xxx"
       def api_base_url(organization: 'api', api_domain: PROD_DOMAIN)
         return "https://#{organization}.#{api_domain}"
@@ -97,118 +85,131 @@ module Aspera
       def metering_api(entitlement_id, customer_id, api_domain=PROD_DOMAIN)
         return Rest.new({
           base_url: "#{api_base_url(api_domain: api_domain)}/metering/v1",
-          headers:  {'X-Aspera-Entitlement-Authorization' => Rest.basic_creds(entitlement_id, customer_id)}
+          headers:  {'X-Aspera-Entitlement-Authorization' => Rest.basic_token(entitlement_id, customer_id)}
         })
       end
 
-      # node API scopes
-      def node_scope(access_key, scope)
-        return "node.#{access_key}:#{scope}"
+      # split host of http://myorg.asperafiles.com in org and domain
+      def url_parts(uri)
+        raise "No host found in URL.Please check URL format: https://myorg.#{PROD_DOMAIN}" if uri.host.nil?
+        parts = uri.host.split('.', 2)
+        raise "expecting a public FQDN for #{PRODUCT_NAME}" unless parts.length == 2
+        return parts
       end
 
-      # check option "link"
-      # if present try to get token value (resolve redirection if short links used)
-      # then set options url/token/auth
-      def resolve_pub_link(a_auth, a_opt)
-        public_link_url = a_opt[:link]
-        return if public_link_url.nil?
-        raise 'do not use both link and url options' unless a_opt[:url].nil?
-        redirect_count = 0
-        while redirect_count <= MAX_REDIRECT
-          uri = URI.parse(public_link_url)
-          # detect if it's an expected format
-          if PUBLIC_LINK_PATHS.include?(uri.path)
-            url_param_token_pair = URI.decode_www_form(uri.query).find{|e|e.first.eql?('token')}
-            raise ArgumentError, 'link option must be URL with "token" parameter' if url_param_token_pair.nil?
-            # ok we get it !
-            a_opt[:url] = 'https://' + uri.host
-            a_auth[:grant_method] = :aoc_pub_link
-            a_auth[:aoc_pub_link] = {
-              url:  {grant_type: 'url_token'}, # URL args
-              json: {url_token: url_param_token_pair.last} # JSON body
-            }
-            # password protection of link
-            a_auth[:aoc_pub_link][:json][:password] = a_opt[:password] unless a_opt[:password].nil?
-            return # SUCCESS
+      # @param url [String] URL of AoC public link
+      # @return [Hash] information about public link, or nil if not a public link
+      def link_info(url)
+        final_uri = Rest.new({base_url: url, redirect_max: MAX_AOC_URL_REDIRECT}).read('')[:http].uri
+        raise 'AoC shall redirect to login page' if final_uri.query.nil?
+        decoded_query = Rest.decode_query(final_uri.query)
+        # is that a public link ?
+        if decoded_query.key?('token')
+          Log.log.warn{"Unknown pub link path: #{final_uri.path}"} unless PUBLIC_LINK_PATHS.include?(final_uri.path)
+          # ok we get it !
+          return {
+            instance_domain: url_parts(final_uri)[1],
+            url:             'https://' + final_uri.host,
+            token:           decoded_query['token']
+          }
+        end
+        Log.log.debug{"path=#{final_uri.path} does not end with /login"} unless final_uri.path.end_with?('/login')
+        if decoded_query['state']
+          # can be a private link
+          state_uri = URI.parse(decoded_query['state'])
+          if state_uri.query && decoded_query['redirect_uri']
+            decoded_state = Rest.decode_query(state_uri.query)
+            if decoded_state.key?('short_link_url')
+              if (m = state_uri.path.match(%r{/files/workspaces/([0-9]+)/all/([0-9]+):([0-9]+)}))
+                redirect_uri = URI.parse(decoded_query['redirect_uri'])
+                parts = url_parts(redirect_uri)
+                return {
+                  instance_domain: parts[1],
+                  organization:    parts[0],
+                  url:             'https://' + redirect_uri.host,
+                  private_link:    {
+                    workspace_id: m[1],
+                    node_id:      m[2],
+                    file_id:      m[3]
+                  }
+                }
+              end
+            end
           end
-          Log.log.debug{"no expected format: #{public_link_url}"}
-          r = Net::HTTP.get_response(uri)
-          # not a redirection
-          raise ArgumentError, 'link option must be redirect or have token parameter' unless r.code.start_with?('3')
-          public_link_url = r['location']
-          raise 'no location in redirection' if public_link_url.nil?
-          Log.log.debug{"redirect to: #{public_link_url}"}
-        end # loop
-        raise "exceeded max redirection: #{MAX_REDIRECT}"
+        end
+        parts = url_parts(URI.parse(url))
+        return {
+          instance_domain: parts[1],
+          organization:    parts[0]
+        }
       end
     end # static methods
 
-    # CLI options that are also options to initialize
-    OPTIONS_NEW = %i[link url auth client_id client_secret scope redirect_uri private_key passphrase username password].freeze
-
-    # @param any of OPTIONS_NEW + subpath
-    def initialize(opt)
-      raise ArgumentError, 'Missing mandatory option: scope' if opt[:scope].nil?
+    attr_reader :private_link
 
+    def initialize(subpath: API_V1, url:, auth:, client_id: nil, client_secret: nil, scope: nil, redirect_uri: nil, private_key: nil, passphrase: nil, username: nil,
+      password: nil, workspace: nil, secret_finder: nil)
+      # test here because link may set url
+      raise ArgumentError, 'Missing mandatory option: url' if url.nil?
+      raise ArgumentError, 'Missing mandatory option: scope' if scope.nil?
+      # default values for client id
+      client_id, client_secret = self.class.get_client_info if client_id.nil?
       # access key secrets are provided out of band to get node api access
       # key: access key
       # value: associated secret
-      @secret_finder = nil
+      @secret_finder = secret_finder
+      @workspace_name = workspace
       @cache_user_info = nil
       @cache_url_token_info = nil
-
       # init rest params
       aoc_rest_p = {auth: {type: :oauth2}}
       # shortcut to auth section
       aoc_auth_p = aoc_rest_p[:auth]
-
-      # sets opt[:url], aoc_rest_p[:auth][:grant_method], [:auth][:aoc_pub_link] if there is a link
-      self.class.resolve_pub_link(aoc_auth_p, opt)
-
-      # test here because link may set url
-      raise ArgumentError, 'Missing mandatory option: url' if opt[:url].nil?
-
-      # get org name and domain from url
-      organization, instance_domain = self.class.parse_url(opt[:url])
+      # analyze type of url
+      url_info = AoC.link_info(url)
+      Log.log.debug{Log.dump(:url_info, url_info)}
+      @private_link = url_info[:private_link]
+      aoc_auth_p[:grant_method] = if url_info.key?(:token)
+        :aoc_pub_link
+      else
+        raise ArgumentError, 'Missing mandatory option: auth' if auth.nil?
+        auth
+      end
       # this is the base API url
-      api_url_base = self.class.api_base_url(api_domain: instance_domain)
+      api_url_base = self.class.api_base_url(api_domain: url_info[:instance_domain])
       # API URL, including subpath (version ...)
-      aoc_rest_p[:base_url] = "#{api_url_base}/#{opt[:subpath]}"
-      # base auth URL
-      aoc_auth_p[:base_url] = "#{api_url_base}/#{OAUTH_API_SUBPATH}/#{organization}"
-      aoc_auth_p[:client_id] = opt[:client_id]
-      aoc_auth_p[:client_secret] = opt[:client_secret]
-      aoc_auth_p[:scope] = opt[:scope]
-
-      # filled if pub link
-      if !aoc_auth_p.key?(:grant_method)
-        raise ArgumentError, 'Missing mandatory option: auth' if opt[:auth].nil?
-        aoc_auth_p[:grant_method] = opt[:auth]
-      end
-
-      if aoc_auth_p[:client_id].nil?
-        aoc_auth_p[:client_id], aoc_auth_p[:client_secret] = self.class.get_client_info
-      end
+      aoc_rest_p[:base_url] = "#{api_url_base}/#{subpath}"
+      # auth URL
+      aoc_auth_p[:base_url] = "#{api_url_base}/#{OAUTH_API_SUBPATH}/#{url_info[:organization]}"
+      aoc_auth_p[:client_id] = client_id
+      aoc_auth_p[:client_secret] = client_secret
+      aoc_auth_p[:scope] = scope
 
       # fill other auth parameters based on Oauth method
       case aoc_auth_p[:grant_method]
       when :web
-        raise ArgumentError, 'Missing mandatory option: redirect_uri' if opt[:redirect_uri].nil?
-        aoc_auth_p[:web] = {redirect_uri: opt[:redirect_uri]}
+        raise ArgumentError, 'Missing mandatory option: redirect_uri' if redirect_uri.nil?
+        aoc_auth_p[:web] = {redirect_uri: redirect_uri}
       when :jwt
-        raise ArgumentError, 'Missing mandatory option: private_key' if opt[:private_key].nil?
-        raise ArgumentError, 'Missing mandatory option: username' if opt[:username].nil?
+        raise ArgumentError, 'Missing mandatory option: private_key' if private_key.nil?
+        raise ArgumentError, 'Missing mandatory option: username' if username.nil?
         aoc_auth_p[:jwt] = {
-          private_key_obj: OpenSSL::PKey::RSA.new(opt[:private_key], opt[:passphrase]),
+          private_key_obj: OpenSSL::PKey::RSA.new(private_key, passphrase),
           payload:         {
-            iss: aoc_auth_p[:client_id],  # issuer
-            sub: opt[:username],          # subject
+            iss: aoc_auth_p[:client_id], # issuer
+            sub: username, # subject
             aud: JWT_AUDIENCE
           }
         }
         # add jwt payload for global ids
-        aoc_auth_p[:jwt][:payload][:org] = organization if GLOBAL_CLIENT_APPS.include?(aoc_auth_p[:client_id])
+        aoc_auth_p[:jwt][:payload][:org] = url_info[:organization] if GLOBAL_CLIENT_APPS.include?(aoc_auth_p[:client_id])
       when :aoc_pub_link
+        aoc_auth_p[:aoc_pub_link] = {
+          url:  {grant_type: 'url_token'}, # URL arguments
+          json: {url_token: url_info[:token]} # JSON body
+        }
+        # password protection of link
+        aoc_auth_p[:aoc_pub_link][:json][:password] = password unless password.nil?
         # basic auth required for /token
         aoc_auth_p[:auth] = {type: :basic, username: aoc_auth_p[:client_id], password: aoc_auth_p[:client_secret]}
       else raise "ERROR: unsupported auth method: #{aoc_auth_p[:grant_method]}"
@@ -216,7 +217,7 @@ module Aspera
       super(aoc_rest_p)
     end
 
-    def url_token_data
+    def public_link
       return nil unless params[:auth][:grant_method].eql?(:aoc_pub_link)
       return @cache_url_token_info unless @cache_url_token_info.nil?
       # TODO: can there be several in list ?
@@ -224,41 +225,104 @@ module Aspera
       return @cache_url_token_info
     end
 
-    def additional_persistence_ids
-      return [current_user_info['id']] if url_token_data.nil?
-      return [] # TODO : url_token_data['id'] ?
+    def assert_public_link_types(expected)
+      raise "public link type is #{public_link['purpose']} but action requires one of #{expected.join(',')}" unless expected.include?(public_link['purpose'])
     end
 
-    def secret_finder=(secret_finder)
-      raise 'secret finder already set' unless @secret_finder.nil?
-      raise 'secret finder must have lookup_secret' unless secret_finder.respond_to?(:lookup_secret)
-      @secret_finder = secret_finder
+    def additional_persistence_ids
+      return [current_user_info['id']] if public_link.nil?
+      return [] # TODO : public_link['id'] ?
     end
 
+    # def secret_finder=(secret_finder)
+    #  raise 'secret finder already set' unless @secret_finder.nil?
+    #  raise 'secret finder must have lookup_secret' unless secret_finder.respond_to?(:lookup_secret)
+    #  @secret_finder = secret_finder
+    # end
+
     # cached user information
     def current_user_info(exception: false)
-      if @cache_user_info.nil?
-        # get our user's default information
-        @cache_user_info =
-          begin
-            read('self')[:data]
-          rescue StandardError => e
-            raise e if exception
-            Log.log.debug{"ignoring error: #{e}"}
-            {}
-          end
-        USER_INFO_FIELDS_MIN.each{|f|@cache_user_info[f] = 'unknown' if @cache_user_info[f].nil?}
-      end
+      return @cache_user_info unless @cache_user_info.nil?
+      # get our user's default information
+      @cache_user_info =
+        begin
+          read('self')[:data]
+        rescue StandardError => e
+          raise e if exception
+          Log.log.debug{"ignoring error: #{e}"}
+          {}
+        end
+      USER_INFO_FIELDS_MIN.each{|f|@cache_user_info[f] = 'unknown' if @cache_user_info[f].nil?}
       return @cache_user_info
     end
 
+    # @param application [Symbol] :files or :packages
+    # @return [Hash] current context information: workspace, and home node/file if app is "Files"
+    def context(application = nil)
+      return @context_cache unless @context_cache.nil?
+      raise 'context must be initialized with application' if application.nil?
+      ws_id =
+        if !public_link.nil?
+          Log.log.debug('Using workspace of public link')
+          public_link['data']['workspace_id']
+        elsif !private_link.nil?
+          Log.log.debug('Using workspace of private link')
+          private_link[:workspace_id]
+        elsif @workspace_name.eql?(DEFAULT_WORKSPACE)
+          Log.log.debug('Using default workspace'.green)
+          raise 'User does not have default workspace, please specify workspace' if current_user_info['default_workspace_id'].nil?
+          current_user_info['default_workspace_id']
+        elsif @workspace_name.nil?
+          nil
+        else
+          lookup_by_name('workspaces', @workspace_name)['id']
+        end
+      ws_info =
+        if ws_id.nil?
+          nil
+        else
+          read("workspaces/#{ws_id}")[:data]
+        end
+      @context_cache = if ws_info.nil?
+        {
+          workspace_id:   nil,
+          workspace_name: 'Shared folders'
+        }
+      else
+        {
+          workspace_id:   ws_info['id'],
+          workspace_name: ws_info['name']
+        }
+      end
+      return @context_cache unless application.eql?(:files)
+      if !public_link.nil?
+        assert_public_link_types(['view_shared_file'])
+        @context_cache[:home_node_id] = public_link['data']['node_id']
+        @context_cache[:home_file_id] = public_link['data']['file_id']
+      elsif !private_link.nil?
+        @context_cache[:home_node_id] = private_link[:node_id]
+        @context_cache[:home_file_id] = private_link[:file_id]
+      elsif ws_info
+        @context_cache[:home_node_id] = ws_info['home_node_id']
+        @context_cache[:home_file_id] = ws_info['home_file_id']
+      else
+        # not part of any workspace, but has some folder shared
+        user_info = current_user_info(exception: true) rescue {'read_only_home_node_id' => nil, 'read_only_home_file_id' => nil}
+        @context_cache[:home_node_id] = user_info['read_only_home_node_id']
+        @context_cache[: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 @context_cache[:home_node_id].to_s.empty?
+      Log.log.debug{Log.dump(:context, @context_cache)}
+      return @context_cache
+    end
+
     # @param node_id [String] identifier of node in AoC
     # @param workspace_id [String] workspace identifier
     # @param workspace_name [String] workspace name
-    # @param scope e.g. SCOPE_NODE_USER, or nil (requires secret)
+    # @param scope e.g. Aspera::Node::SCOPE_USER, or nil (requires secret)
     # @param package_info [Hash] created package information
     # @returns [Aspera::Node] a node API for access key
-    def node_api_from(node_id:, workspace_id: nil, workspace_name: nil, scope: SCOPE_NODE_USER, package_info: nil)
+    def node_api_from(node_id:, workspace_id: nil, workspace_name: nil, scope: Aspera::Node::SCOPE_USER, package_info: nil)
       raise 'invalid type for node_id' unless node_id.is_a?(String)
       node_info = read("nodes/#{node_id}")[:data]
       if workspace_name.nil? && !workspace_id.nil?
@@ -287,35 +351,13 @@ module Aspera
       else
         # OAuth bearer token
         node_rest_params[:auth] = params[:auth].clone
-        node_rest_params[:auth][:scope] = self.class.node_scope(node_info['access_key'], scope)
+        node_rest_params[:auth][:scope] = Aspera::Node.token_scope(node_info['access_key'], scope)
         # special header required for bearer token only
         node_rest_params[:headers] = {Aspera::Node::HEADER_X_ASPERA_ACCESS_KEY => node_info['access_key']}
       end
       return Node.new(params: node_rest_params, app_info: app_info)
     end
 
-    # Query entity type by name and returns the id if a single entry only
-    # @param entity_type path of entity in API
-    # @param entity_name name of searched entity
-    # @param options additional search options
-    def lookup_entity_by_name(entity_type, entity_name, options={})
-      # returns entities whose name contains value (case insensitive)
-      matching_items = read(entity_type, options.merge({'q' => CGI.escape(entity_name)}))[:data]
-      case matching_items.length
-      when 1 then return matching_items.first
-      when 0 then raise %Q{#{ENTITY_NOT_FOUND} #{entity_type}: "#{entity_name}"}
-      else
-        # multiple case insensitive partial matches, try case insensitive full match
-        # (anyway AoC does not allow creation of 2 entities with same case insensitive name)
-        name_matches = matching_items.select{|i|i['name'].casecmp?(entity_name)}
-        case name_matches.length
-        when 1 then return name_matches.first
-        when 0 then raise %Q(#{entity_type}: multiple case insensitive partial match for: "#{entity_name}": #{matching_items.map{|i|i['name']}} but no case insensitive full match. Please be more specific or give exact name.) # rubocop:disable Layout/LineLength
-        else raise "Two entities cannot have the same case insensitive name: #{name_matches.map{|i|i['name']}}"
-        end
-      end
-    end
-
     # Check metadata: remove when validation is done server side
     def validate_metadata(pkg_data)
       # validate only for shared inboxes
@@ -331,7 +373,7 @@ module Aspera
       pkg_meta = pkg_data['metadata']
       raise "package requires metadata: #{meta_schema}" unless pkg_data.key?('metadata')
       raise 'metadata must be an Array' unless pkg_meta.is_a?(Array)
-      Log.dump(:metadata, pkg_meta)
+      Log.log.debug{Log.dump(:metadata, pkg_meta)}
       pkg_meta.each do |field|
         raise 'metadata field must be Hash' unless field.is_a?(Hash)
         raise 'metadata field must have name' unless field.key?('name')
@@ -367,7 +409,7 @@ module Aspera
           # email: user, else dropbox
           entity_type = short_recipient_info.include?('@') ? 'contacts' : 'dropboxes'
           begin
-            full_recipient_info = lookup_entity_by_name(entity_type, short_recipient_info, {'current_workspace_id' => ws_id})
+            full_recipient_info = lookup_by_name(entity_type, short_recipient_info, {'current_workspace_id' => ws_id})
           rescue RuntimeError => e
             raise e unless e.message.start_with?(ENTITY_NOT_FOUND)
             # dropboxes cannot be created on the fly
@@ -375,7 +417,8 @@ module Aspera
             # unknown user: create it as external user
             full_recipient_info = create('contacts', {
               'current_workspace_id' => ws_id,
-              'email'                => short_recipient_info}.merge(new_user_option))[:data]
+              'email'                => short_recipient_info
+            }.merge(new_user_option))[:data]
           end
           short_recipient_info = if entity_type.eql?('dropboxes')
             {'id' => full_recipient_info['id'], 'type' => 'dropbox'}
@@ -448,7 +491,7 @@ module Aspera
       }
     end
 
-    # Add transferspec
+    # Add transfer spec
     # callback in Aspera::Node (transfer_spec_gen4)
     def add_ts_tags(transfer_spec:, app_info:)
       # translate transfer direction to upload/download
@@ -488,7 +531,10 @@ module Aspera
                 'package_id'        => app_info[:package_id],
                 'package_name'      => app_info[:package_name],
                 'package_operation' => transfer_type
-              }}}})
+              }
+            }
+          }
+        })
       end
       transfer_spec['tags'][Fasp::TransferSpec::TAG_RESERVED]['files']['node_id'] = app_info[:node_info]['id']
       transfer_spec['tags'][Fasp::TransferSpec::TAG_RESERVED]['app'] = app_info[:app]
@@ -496,7 +542,10 @@ module Aspera
 
     ID_AK_ADMIN = 'ASPERA_ACCESS_KEY_ADMIN'
     # Callback from Plugins::Node
-    def permissions_create_params(create_param:, app_info:)
+    # add application specific tags to permissions creation
+    # @param create_param [Hash] parameters for creating permissions
+    # @param app_info [Hash] application information
+    def permissions_set_create_params(create_param:, app_info:)
       # workspace shared folder:
       # access_id = "#{ID_AK_ADMIN}_WS_#{app_info[:workspace_id]}"
       default_params = {
@@ -514,10 +563,15 @@ module Aspera
                 'shared_by_email'   => current_user_info['email'],
                 # 'shared_with_name'  => access_id,
                 'access_key'        => app_info[:node_info]['access_key'],
-                'node'              => app_info[:node_info]['name']}}}}}
+                'node'              => app_info[:node_info]['name']
+              }
+            }
+          }
+        }
+      }
       create_param.deep_merge!(default_params)
       if create_param.key?('with')
-        contact_info = lookup_entity_by_name(
+        contact_info = lookup_by_name(
           'contacts',
           create_param['with'],
           {'current_workspace_id' => app_info[:workspace_id], 'context' => 'share_folder'})
@@ -531,14 +585,20 @@ module Aspera
     end
 
     # Callback from Plugins::Node
-    def permissions_create_event(created_data:, app_info:)
+    # send shared folder event to AoC
+    # @param created_data [Hash] response from permission creation
+    # @param app_info [Hash] hash with app info
+    # @param types [Array] event types
+    def permissions_send_event(created_data:, app_info:, types: PERMISSIONS_CREATED)
+      raise "INTERNAL: (assert) Invalid event types: #{types}" unless types.is_a?(Array) && !types.empty?
       event_creation = {
-        'types'        => ['permission.created'],
+        'types'        => types,
         'node_id'      => app_info[:node_info]['id'],
         'workspace_id' => app_info[:workspace_id],
-        'data'         => created_data # Response from previous step
+        'data'         => created_data
       }
-      # (optional). The name of the folder to be displayed to the destination user. Use it if its value is different from the "share_as" field.
+      # (optional). The name of the folder to be displayed to the destination user.
+      # Use it if its value is different from the "share_as" field.
       event_creation['link_name'] = app_info[:opt_link_name] unless app_info[:opt_link_name].nil?
       create('events', event_creation)
     end