aspera-cli 4.15.0 → 4.17.0

data/lib/aspera/keychain/macos_security.rb

@@ -2,6 +2,9 @@
 
 # https://github.com/fastlane-community/security
 require 'aspera/cli/info'
+require 'aspera/log'
+require 'aspera/assert'
+require 'open3'
 
 # enhance the gem to support other key chains
 module Aspera
@@ -9,6 +12,8 @@ module Aspera
     module MacosSecurity
       # keychain based on macOS keychain, using `security` command line
       class Keychain
+        # https://www.unix.com/man-page/osx/1/security/
+        SECURITY_UTILITY = 'security'
         DOMAINS = %i[user system common dynamic].freeze
         LIST_OPTIONS = {
           domain: :c
@@ -36,25 +41,27 @@ module Aspera
             url = options&.delete(:url)
             if !url.nil?
               uri = URI.parse(url)
-              raise 'only https' unless uri.scheme.eql?('https')
+              Aspera.assert(uri.scheme.eql?('https')){'only https'}
               options[:protocol] = 'htps' # cspell: disable-line
               raise 'host required in URL' if uri.host.nil?
               options[:server] = uri.host
               options[:path] = uri.path unless ['', '/'].include?(uri.path)
               options[:port] = uri.port unless uri.port.eql?(443) && !url.include?(':443/')
             end
-            cmd = ['security', command]
+            command_line = [SECURITY_UTILITY, command]
             options&.each do |k, v|
-              raise "unknown option: #{k}" unless supported.key?(k)
+              Aspera.assert(supported.key?(k)){"unknown option: #{k}"}
               next if v.nil?
-              cmd.push("-#{supported[k]}")
-              cmd.push(v.shellescape) unless v.empty?
+              command_line.push("-#{supported[k]}")
+              command_line.push(v.shellescape) unless v.empty?
             end
-            cmd.push(last_opt) unless last_opt.nil?
-            Log.log.debug{"executing>>#{cmd.join(' ')}"}
-            result = %x(#{cmd.join(' ')} 2>&1)
-            Log.log.debug{"result>>[#{result}]"}
-            return result
+            command_line.push(last_opt) unless last_opt.nil?
+            Log.log.debug{"executing>>#{command_line.join(' ')}"}
+            stdout, stderr, status = Open3.capture3(*command_line)
+            Log.log.debug{"status=#{status}, stderr=#{stderr}"}
+            Log.log.trace1{"stdout=#{stdout}"}
+            raise "#{SECURITY_UTILITY} failed: #{status.exitstatus} : #{stderr}" unless status.success?
+            return stdout
           end
 
           def key_chains(output)
@@ -70,7 +77,7 @@ module Aspera
           end
 
           def list(options={})
-            raise ArgumentError, "Invalid domain #{options[:domain]}, expected one of: #{DOMAINS}" unless options[:domain].nil? || DOMAINS.include?(options[:domain])
+            Aspera.assert_values(options[:domain], DOMAINS, exception_class: ArgumentError){'domain'} unless options[:domain].nil?
             key_chains(execute('list-key_chains', options, LIST_OPTIONS))
           end
 
@@ -89,15 +96,15 @@ module Aspera
         end
 
         def password(operation, pass_type, options)
-          raise "wrong operation: #{operation}" unless %i[add find delete].include?(operation)
-          raise "wrong pass_type: #{pass_type}" unless %i[generic internet].include?(pass_type)
-          raise 'options shall be Hash' unless options.is_a?(Hash)
+          Aspera.assert_values(operation, %i[add find delete]){'operation'}
+          Aspera.assert_values(pass_type, %i[generic internet]){'pass_type'}
+          Aspera.assert_type(options, Hash)
           missing = (operation.eql?(:add) ? %i[account service password] : %i[label]) - options.keys
-          raise "missing options: #{missing}" unless missing.empty?
+          Aspera.assert(missing.empty?){"missing options: #{missing}"}
           options[:getpass] = '' if operation.eql?(:find)
           output = self.class.execute("#{operation}-#{pass_type}-password", options, ADD_PASS_OPTIONS, @path)
           raise output.gsub(/^.*: /, '') if output.start_with?('security: ')
-          return nil unless operation.eql?(:find)
+          return unless operation.eql?(:find)
           attributes = {}
           output.split("\n").each do |line|
             case line
@@ -127,18 +134,18 @@ module Aspera
       end
 
       def set(options)
-        raise 'options shall be Hash' unless options.is_a?(Hash)
+        Aspera.assert_type(options, Hash){'options'}
         unsupported = options.keys - %i[label username password url description]
-        raise "unsupported options: #{unsupported}" unless unsupported.empty?
+        Aspera.assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         @keychain.password(
           :add, :generic, service: options[:label],
           account: options[:username] || 'none', password: options[:password], comment: options[:description])
       end
 
       def get(options)
-        raise 'options shall be Hash' unless options.is_a?(Hash)
+        Aspera.assert_type(options, Hash){'options'}
         unsupported = options.keys - %i[label]
-        raise "unsupported options: #{unsupported}" unless unsupported.empty?
+        Aspera.assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         info = @keychain.password(:find, :generic, label: options[:label])
         raise 'not found' if info.nil?
         result = options.clone
@@ -153,9 +160,9 @@ module Aspera
       end
 
       def delete(options)
-        raise 'options shall be Hash' unless options.is_a?(Hash)
+        Aspera.assert_type(options, Hash){'options'}
         unsupported = options.keys - %i[label]
-        raise "unsupported options: #{unsupported}" unless unsupported.empty?
+        Aspera.assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         raise 'delete not implemented, use macos keychain app'
       end
     end

data/lib/aspera/log.rb

@@ -3,6 +3,7 @@
 require 'aspera/colors'
 require 'aspera/secret_hider'
 require 'aspera/environment'
+require 'aspera/assert'
 require 'logger'
 require 'pp'
 require 'json'
@@ -13,7 +14,7 @@ class Logger
   TRACE_MAX = 2
   # add custom level to logger severity
   module Severity
-    1.upto(TRACE_MAX).each { |level| const_set("TRACE#{level}", - level)}
+    1.upto(TRACE_MAX).each { |level| const_set(:"TRACE#{level}", - level)}
   end
   # quick access to label
   SEVERITY_LABEL = Severity.constants.each_with_object({}) { |name, hash| hash[Severity.const_get(name)] = name}
@@ -39,6 +40,7 @@ class Logger
       end
     EOM
   end
+  # declare methods for all levels
   Logger::Severity.constants.each { |severity| make_methods(severity) }
 end
 
@@ -97,8 +99,7 @@ module Aspera
       Logger::Severity.constants.each do |name|
         return name.downcase.to_sym if @logger.level.eql?(Logger::Severity.const_get(name))
       end
-      # should not happen
-      raise "INTERNAL ERROR: unexpected level #{@logger.level}"
+      Aspera.error_unexpected_value(@logger.level){'log level'}
     end
 
     # change underlying logger, but keep log level
@@ -123,7 +124,7 @@ module Aspera
         end
         @logger = Syslog::Logger.new(@program_name, Syslog::LOG_LOCAL2)
       else
-        raise "unknown log type: #{new_log_type.class} #{new_log_type}"
+        raise "unknown log type: #{new_log_type}, use one of: #{LOG_TYPES.join(', ')}"
       end
       @logger.level = current_severity_integer
       @logger_type = new_log_type

data/lib/aspera/nagios.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'aspera/log'
+require 'aspera/assert'
 require 'date'
 
 module Aspera
@@ -21,8 +23,11 @@ module Aspera
     class << self
       # process results of a analysis and display status and exit with code
       def process(data)
-        raise 'INTERNAL ERROR, result must be list and not empty' unless data.is_a?(Array) && !data.empty?
-        %w[status component message].each{|c|raise "INTERNAL ERROR, result must have #{c}" unless data.first.key?(c)}
+        Aspera.assert_type(data, Array)
+        Aspera.assert(!data.empty?){'data is empty'}
+        %w[status component message].each do |c|
+          Aspera.assert(data.first.key?(c)){"result must have #{c}"}
+        end
         res_errors = data.reject{|s|s['status'].eql?('ok')}
         # keep only errors in case of problem, other ok are assumed so
         data = res_errors unless res_errors.empty?

data/lib/aspera/node_simulator.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'aspera/ascp/installation'
+require 'aspera/agent/direct'
+require 'aspera/log'
+require 'webrick'
+require 'json'
+
+module Aspera
+  # this class answers the Faspex /send API and creates a package on Aspera on Cloud
+  class NodeSimulatorServlet < WEBrick::HTTPServlet::AbstractServlet
+    PATH_TRANSFERS = '/ops/transfers'
+    PATH_ONE_TRANSFER = %r{/ops/transfers/(.+)$}
+    # @param app_api [Api::AoC]
+    # @param app_context [String]
+    def initialize(server, credentials, transfer)
+      super(server)
+      @credentials = credentials
+      @xfer_manager = Agent::Direct.new
+    end
+
+    def do_POST(request, response)
+      case request.path
+      when PATH_TRANSFERS
+        job_id = @xfer_manager.start_transfer(JSON.parse(request.body))
+        session = @xfer_manager.sessions_by_job(job_id).first
+        result = session[:ts].clone
+        result['id'] = job_id
+        set_json_response(response, result)
+      else
+        set_json_response(response, [{error: 'Bad request'}], code: 400)
+      end
+    end
+
+    def do_GET(request, response)
+      case request.path
+      when '/info'
+        info = Ascp::Installation.instance.ascp_info
+        set_json_response(response, {
+          application:                           'node',
+          current_time:                          Time.now.utc.iso8601(0),
+          version:                               info['ascp_version'].gsub(/ .*$/, ''),
+          license_expiration_date:               info['expiration_date'],
+          license_max_rate:                      info['maximum_bandwidth'],
+          os:                                    %x(uname -srv).chomp,
+          aej_status:                            'disconnected',
+          async_reporting:                       'yes',
+          transfer_activity_reporting:           'yes',
+          transfer_user:                         'xfer',
+          docroot:                               'file:////data/aoc/eudemo-sedemo',
+          node_id:                               '2bbdcc39-f789-4d47-8163-6767fc14f421',
+          cluster_id:                            '6dae2844-d1a9-47a5-916d-9b3eac3ea466',
+          acls:                                  [],
+          access_key_configuration_capabilities: {
+            transfer: %w[
+              cipher
+              policy
+              target_rate_cap_kbps
+              target_rate_kbps
+              preserve_timestamps
+              content_protection_secret
+              aggressiveness
+              token_encryption_key
+              byok_enabled
+              bandwidth_flow_network_rc_module
+              file_checksum_type],
+            server:   %w[
+              activity_event_logging
+              activity_file_event_logging
+              recursive_counts
+              aej_logging
+              wss_enabled
+              activity_transfer_ignore_skipped_files
+              activity_files_max
+              access_key_credentials_encryption_type
+              discovery
+              auto_delete
+              allow
+              deny]
+          },
+          capabilities:                          [
+            {name:  'sync', value: true},
+            {name:  'watchfolder', value: true},
+            {name:  'symbolic_links', value: true},
+            {name:  'move_file', value: true},
+            {name:  'move_directory', value: true},
+            {name:  'filelock', value: false},
+            {name:  'ssh_fingerprint', value: false},
+            {name:  'aej_version', value: '1.0'},
+            {name:  'page', value: true},
+            {name:  'file_id_version', value: '2.0'},
+            {name:  'auto_delete', value: false}],
+          settings:                              [
+            {name:  'content_protection_required', value: false},
+            {name:  'content_protection_strong_pass_required', value: false},
+            {name:  'filelock_restriction', value: 'none'},
+            {name:  'ssh_fingerprint', value: nil},
+            {name:  'wss_enabled', value: false},
+            {name:  'wss_port', value: 443}
+          ]})
+      when PATH_TRANSFERS
+        result = @xfer_manager.sessions.map { |session| job_to_transfer(session) }
+        set_json_response(response, result)
+      when PATH_ONE_TRANSFER
+        job_id = request.path.match(PATH_ONE_TRANSFER)[1]
+        set_json_response(response, job_to_transfer(@xfer_manager.sessions_by_job(job_id).first))
+      else
+        set_json_response(response, [{error: 'Unknown request'}], code: 400)
+      end
+    end
+
+    def set_json_response(response, json, code: 200)
+      response.status = code
+      response['Content-Type'] = 'application/json'
+      response.body = json.to_json
+      Log.log.trace1{Log.dump('response', json)}
+    end
+
+    def job_to_transfer(job)
+      session = {
+        id:                    'bafc72b8-366c-4501-8095-47208183d6b8',
+        client_node_id:        '',
+        server_node_id:        '2bbdcc39-f789-4d47-8163-6767fc14f421',
+        client_ip_address:     '192.168.0.100',
+        server_ip_address:     '5.10.114.4',
+        status:                'running',
+        retry_timeout:         3600,
+        retry_count:           0,
+        start_time_usec:       1701094040000000,
+        end_time_usec:         nil,
+        elapsed_usec:          405312,
+        bytes_transferred:     26,
+        bytes_written:         26,
+        bytes_lost:            0,
+        files_completed:       1,
+        directories_completed: 0,
+        target_rate_kbps:      500000,
+        min_rate_kbps:         0,
+        calc_rate_kbps:        9900,
+        network_delay_usec:    40000,
+        avg_rate_kbps:         0.51,
+        error_code:            0,
+        error_desc:            '',
+        source_statistics:     {
+          args_scan_attempted:  1,
+          args_scan_completed:  1,
+          paths_scan_attempted: 1,
+          paths_scan_failed:    0,
+          paths_scan_skipped:   0,
+          paths_scan_excluded:  0,
+          dirs_scan_completed:  0,
+          files_scan_completed: 1,
+          dirs_xfer_attempted:  0,
+          dirs_xfer_fail:       0,
+          files_xfer_attempted: 1,
+          files_xfer_fail:      0,
+          files_xfer_noxfer:    0
+        },
+        precalc:               {
+          enabled:              true,
+          status:               'ready',
+          bytes_expected:       0,
+          directories_expected: 0,
+          files_expected:       0,
+          files_excluded:       0,
+          files_special:        0,
+          files_failed:         1
+        }}
+      return {
+        id:                    '609a667d-642e-4290-9312-b4d20d3c0159',
+        status:                'running',
+        start_spec:            job[:ts],
+        sessions:              [session],
+        bytes_transferred:     26,
+        bytes_written:         26,
+        bytes_lost:            0,
+        avg_rate_kbps:         0.51,
+        files_completed:       1,
+        files_skipped:         0,
+        directories_completed: 0,
+        start_time_usec:       1701094040000000,
+        end_time_usec:         1701094040405312,
+        elapsed_usec:          405312,
+        error_code:            0,
+        error_desc:            '',
+        precalc:               {
+          status:               'ready',
+          bytes_expected:       0,
+          files_expected:       0,
+          directories_expected: 0,
+          files_special:        0,
+          files_failed:         1
+        },
+        files:                 [{
+          id:              'd1b5c112-82b75425-860745fc-93851671-64541bdd',
+          path:            '/workspaces/45071/packages/bYA_ilq73g.asp-package/contents/data_file.bin',
+          start_time_usec: 1701094040000000,
+          elapsed_usec:    105616,
+          end_time_usec:   1701094040001355,
+          status:          'completed',
+          error_code:      0,
+          error_desc:      '',
+          size:            26,
+          type:            'file',
+          checksum_type:   'none',
+          checksum:        nil,
+          start_byte:      0,
+          bytes_written:   26,
+          session_id:      'bafc72b8-366c-4501-8095-47208183d6b8'}]
+      }
+    end
+  end # NodeSimulatorServlet
+end # Aspera

data/lib/aspera/oauth/base.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'aspera/oauth/factory'
+require 'aspera/log'
+require 'aspera/assert'
+require 'aspera/id_generator'
+require 'date'
+
+module Aspera
+  module OAuth
+    # Implement OAuth 2 for the REST client and generate a bearer token
+    # call get_authorization() to get a token.
+    # bearer tokens are kept in memory and also in a file cache for later re-use
+    # if a token is expired (api returns 4xx), call again get_authorization(refresh: true)
+    # https://tools.ietf.org/html/rfc6749
+    class Base
+      # scope can be modified after creation
+      attr_writer :scope
+
+      # [M]=mandatory [D]=has default value [O]=Optional/nil
+      # @param base_url            [M] URL of authentication API
+      # @param auth                [O] basic auth parameters
+      # @param client_id           [O]
+      # @param client_secret       [O]
+      # @param scope               [O]
+      # @param path_token          [D] API end point to create a token
+      # @param token_field         [D] field in result that contains the token
+      def initialize(
+        base_url:,
+        auth: nil,
+        client_id: nil,
+        client_secret: nil,
+        scope: nil,
+        path_token:  'token',       # default endpoint for /token to generate token
+        token_field: 'access_token' # field with token in result of call to path_token
+      )
+        Aspera.assert_type(base_url, String)
+        Aspera.assert(respond_to?(:create_token), 'create_token method must be defined', exception_class: InternalError)
+        @base_url = base_url
+        @path_token = path_token
+        @token_field = token_field
+        @client_id = client_id
+        @client_secret = client_secret
+        @scope = scope
+        @identifiers = []
+        @identifiers.push(auth[:username]) if auth.is_a?(Hash) && auth.key?(:username)
+        # this is the OAuth API
+        @api = Rest.new(
+          base_url:     @base_url,
+          redirect_max: 2,
+          auth:         auth)
+      end
+
+      # helper method to create token as per RFC
+      def create_token_call(www_params)
+        Log.log.debug{'Generating a new token'.bg_green}
+        return @api.call(
+          operation:       'POST',
+          subpath:         @path_token,
+          headers:         {'Accept' => 'application/json'},
+          www_body_params: www_params)
+      end
+
+      # @return Hash with optional general parameters
+      def optional_scope_client_id(add_secret: false)
+        call_params = {}
+        call_params[:scope] = @scope unless @scope.nil?
+        call_params[:client_id] = @client_id unless @client_id.nil?
+        call_params[:client_secret] = @client_secret if add_secret && !@client_id.nil?
+        return call_params
+      end
+
+      # OAuth v2 token generation
+      # @param use_refresh_token set to true to force refresh or re-generation (if previous failed)
+      def get_authorization(use_refresh_token: false, use_cache: true)
+        # generate token unique identifier for persistency (memory/disk cache)
+        token_id = IdGenerator.from_list(Factory.id(
+          @base_url,
+          @grant_method,
+          @identifiers,
+          @scope
+        ))
+
+        # get token_data from cache (or nil), token_data is what is returned by /token
+        token_data = Factory.instance.persist_mgr.get(token_id) if use_cache
+        token_data = JSON.parse(token_data) unless token_data.nil?
+        # Optional optimization: check if node token is expired based on decoded content then force refresh if close enough
+        # might help in case the transfer agent cannot refresh himself
+        # `direct` agent is equipped with refresh code
+        if !use_refresh_token && !token_data.nil?
+          decoded_token = OAuth::Factory.instance.decode_token(token_data[@token_field])
+          Log.log.debug{Log.dump('decoded_token', decoded_token)} unless decoded_token.nil?
+          if decoded_token.is_a?(Hash)
+            expires_at_sec =
+              if    decoded_token['expires_at'].is_a?(String) then DateTime.parse(decoded_token['expires_at']).to_time
+              elsif decoded_token['exp'].is_a?(Integer)       then Time.at(decoded_token['exp'])
+              end
+            # force refresh if we see a token too close from expiration
+            use_refresh_token = true if expires_at_sec.is_a?(Time) && (expires_at_sec - Time.now) < OAuth::Factory.instance.globals[:token_expiration_guard_sec]
+            Log.log.debug{"Expiration: #{expires_at_sec} / #{use_refresh_token}"}
+          end
+        end
+
+        # an API was already called, but failed, we need to regenerate or refresh
+        if use_refresh_token
+          if token_data.is_a?(Hash) && token_data.key?('refresh_token') && !token_data['refresh_token'].eql?('not_supported')
+            # save possible refresh token, before deleting the cache
+            refresh_token = token_data['refresh_token']
+          end
+          # delete cache
+          Factory.instance.persist_mgr.delete(token_id)
+          token_data = nil
+          # lets try the existing refresh token
+          if !refresh_token.nil?
+            Log.log.info{"refresh=[#{refresh_token}]".bg_green}
+            # try to refresh
+            # note: AoC admin token has no refresh, and lives by default 1800secs
+            resp = create_token_call(optional_scope_client_id.merge(grant_type: 'refresh_token', refresh_token: refresh_token))
+            if resp[:http].code.start_with?('2')
+              # save only if success
+              json_data = resp[:http].body
+              token_data = JSON.parse(json_data)
+              Factory.instance.persist_mgr.put(token_id, json_data)
+            else
+              Log.log.debug{"refresh failed: #{resp[:http].body}".bg_red}
+            end
+          end
+        end
+
+        # no cache, nor refresh: generate a token
+        if token_data.nil?
+          resp = create_token
+          json_data = resp[:http].body
+          token_data = JSON.parse(json_data)
+          Factory.instance.persist_mgr.put(token_id, json_data)
+        end # if ! in_cache
+        Aspera.assert(token_data.key?(@token_field)){"API error: No such field in answer: #{@token_field}"}
+        # ok we shall have a token here
+        return OAuth::Factory.bearer_build(token_data[@token_field])
+      end
+    end # OAuth
+  end
+end

data/lib/aspera/oauth/factory.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'aspera/assert'
+require 'base64'
+module Aspera
+  module OAuth
+    class Factory
+      include Singleton
+      # a prefix for persistency of tokens (simplify garbage collect)
+      PERSIST_CATEGORY_TOKEN = 'token'
+      # prefix for bearer token when in header
+      BEARER_PREFIX = 'Bearer '
+
+      private_constant :PERSIST_CATEGORY_TOKEN, :BEARER_PREFIX
+
+      class << self
+        def bearer_build(token)
+          return BEARER_PREFIX + token
+        end
+
+        def bearer_extract(token)
+          Aspera.assert(bearer?(token)){'not a bearer token, wrong prefix'}
+          return token[BEARER_PREFIX.length..-1]
+        end
+
+        def bearer?(token)
+          return token.start_with?(BEARER_PREFIX)
+        end
+
+        def id(*params)
+          return [PERSIST_CATEGORY_TOKEN, *params].flatten
+        end
+
+        def class_to_id(creator_class)
+          return creator_class.name.split('::').last.capital_to_snake.to_sym
+        end
+      end
+
+      private
+
+      def initialize
+        # persistency manager
+        @persist = nil
+        # token creation methods
+        @token_type_classes = {}
+        @decoders = []
+        @globals = {
+          # remove 5 minutes to account for time offset between client and server (TODO: configurable?)
+          jwt_accepted_offset_sec:    300,
+          # one hour validity (TODO: configurable?)
+          jwt_expiry_offset_sec:      3600,
+          # tokens older than 30 minutes will be discarded from cache
+          token_cache_expiry_sec:     1800,
+          # tokens valid for less than this duration will be regenerated
+          token_expiration_guard_sec: 120
+        }
+      end
+
+      public
+
+      attr_reader :globals
+
+      def persist_mgr=(manager)
+        @persist = manager
+        # cleanup expired tokens
+        @persist.garbage_collect(PERSIST_CATEGORY_TOKEN, @globals[:token_cache_expiry_sec])
+      end
+
+      def persist_mgr
+        if @persist.nil?
+          # use OAuth::Factory.instance.persist_mgr=PersistencyFolder.new)
+          Log.log.debug('Not using persistency')
+          # create NULL persistency class
+          @persist = Class.new do
+            def get(_x); nil; end; def delete(_x); nil; end; def put(_x, _y); nil; end; def garbage_collect(_x, _y); nil; end # rubocop:disable Layout/EmptyLineBetweenDefs, Style/Semicolon, Layout/LineLength
+          end.new
+        end
+        return @persist
+      end
+
+      # delete all existing tokens
+      def flush_tokens
+        persist_mgr.garbage_collect(PERSIST_CATEGORY_TOKEN, nil)
+      end
+
+      # register a bearer token decoder, mainly to inspect expiry date
+      def register_decoder(method)
+        @decoders.push(method)
+      end
+
+      # decode token using all registered decoders
+      def decode_token(token)
+        @decoders.each do |decoder|
+          result = decoder.call(token) rescue nil
+          return result unless result.nil?
+        end
+        return nil
+      end
+
+      # register a token creation method
+      # @param id creation type from field :grant_method in constructor
+      # @param lambda_create called to create token
+      # @param id_create called to generate unique id for token, for cache
+      def register_token_creator(creator_class)
+        Aspera.assert_type(creator_class, Class)
+        id = self.class.class_to_id(creator_class)
+        Log.log.debug{"registering token creator #{id}"}
+        @token_type_classes[id] = creator_class
+      end
+
+      # @return one of the registered creators for the given create type
+      def create(**parameters)
+        Aspera.assert_type(parameters, Hash)
+        id = parameters[:grant_method]
+        Aspera.assert(@token_type_classes.key?(id)){"token grant method unknown: '#{id}'"}
+        create_parameters = parameters.reject { |k, _v| k.eql?(:grant_method) }
+        @token_type_classes[id].new(**create_parameters)
+      end
+    end
+    # JSON Web Signature (JWS) compact serialization: https://datatracker.ietf.org/doc/html/rfc7515
+    Factory.instance.register_decoder(lambda { |token| parts = token.split('.'); Aspera.assert(parts.length.eql?(3)){'not aoc token'}; JSON.parse(Base64.decode64(parts[1]))}) # rubocop:disable Style/Semicolon, Layout/LineLength
+  end
+end