aspera-cli 4.26.1 → 4.26.2

data/lib/aspera/keychain/macos_security.rb

@@ -42,7 +42,7 @@ module Aspera
             url = options&.delete(:url)
             if !url.nil?
               uri = URI.parse(url)
-              Aspera.assert(uri.scheme.eql?('https')){'only https'}
+              Aspera.assert(uri.scheme.eql?('https'), 'only https')
               options[:protocol] = 'htps' # cspell: disable-line
               raise Error, 'host required in URL' if uri.host.nil?
               options[:server] = uri.host

data/lib/aspera/log.rb

@@ -54,6 +54,10 @@ $VERBOSE = old_verbose
 
 module Aspera
   # Singleton object for logging
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of Log
+  #   @return [Log] the singleton instance
   class Log
     include Singleton
 
@@ -80,7 +84,7 @@ module Aspera
       # @yieldreturn [Object] Computed object to dump (alternative to object parameter)
       def dump(name, object = nil, level: :debug, &block)
         return unless instance.logger.send(:"#{level}?")
-        Aspera.assert(object.nil? || block.nil?){'Use either object, or block, not both'}
+        Aspera.assert(object.nil? || block.nil?, 'Use either object, or block, not both')
         object = yield if block_given?
         instance.logger.send(level, obj_dump(name, object))
       end
@@ -168,7 +172,7 @@ module Aspera
     # Get symbol of debug level of underlying logger
     # @return [Symbol] One of LEVELS
     def level
-      Aspera.assert(Logger::SEVERITY_LABEL.key?(@logger.level))
+      Aspera.assert(Logger::SEVERITY_LABEL.key?(@logger.level), 'unexpected logger level value')
       Logger::SEVERITY_LABEL[@logger.level].downcase
     end
 

data/lib/aspera/nagios.rb

@@ -24,7 +24,7 @@ module Aspera
       # Process results of a analysis and display status and exit with code
       def process(data)
         Aspera.assert_type(data, Array)
-        Aspera.assert(!data.empty?){'data is empty'}
+        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
@@ -79,7 +79,7 @@ module Aspera
     # Readable status list
     # @return [Array] of Hash
     def status_list
-      Aspera.assert(!@data.empty?){'missing result'}
+      Aspera.assert(!@data.empty?, 'missing result')
       @data.map{ |i| {'status' => LEVELS[i[:code]].to_s, 'component' => i[:comp], 'message' => i[:msg]}}
     end
   end

data/lib/aspera/oauth/base.rb

@@ -15,15 +15,15 @@ module Aspera
     class Base
       Aspera.require_method!(:create_token)
       # @param params         [Hash]    Parameters for token creation (client_id, client_secret, scope, etc...)
-      # @param use_query      [Boolean] Provide parameters in query instead of body
       # @param path_token     [String]  API end point to create a token from base URL
+      # @param use_query      [Boolean] Provide parameters in query instead of body
       # @param token_field    [String]  Field in result that contains the token
       # @param cache_ids      [Array]   List of unique identifiers for cache id generation
       # @param **rest_params  [Hash]    Parameters for REST
       def initialize(
         params: {},
+        path_token: 'token',
         use_query: false,
-        path_token:  'token',
         token_field: Factory::TOKEN_FIELD,
         cache_ids: [],
         **rest_params
@@ -42,10 +42,10 @@ module Aspera
 
       # The OAuth API Object
       attr_reader :api
-      # Sub path to generate token
-      attr_reader :path_token
       # Parameters to generate token
       attr_reader :params
+      # Sub path to generate token
+      attr_reader :path_token
 
       # Helper method to create token as per RFC
       # @return [HTTPResponse]
@@ -122,7 +122,7 @@ module Aspera
           token_data = JSON.parse(json_data)
           Factory.instance.persist_mgr.put(@token_cache_id, json_data)
         end
-        Aspera.assert(token_data.key?(@token_field)){"API error: No such field in answer: #{@token_field}"}
+        Aspera.assert(token_data.key?(@token_field)){"API error: No such field in answer: #{@token_field}"} unless token_data.nil?
         # ok we shall have a token here
         return token_data[@token_field]
       end

data/lib/aspera/oauth/boot.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'aspera/oauth/base'
+require 'aspera/assert'
+require 'json'
+
+module Aspera
+  module OAuth
+    # Token provider bootstrapped from an existing cookie (e.g. AoC browser cookie).
+    # Injects the bearer token and optional refresh token directly into the cache.
+    # Never generates a new token from scratch — raises if cache+refresh are both exhausted.
+    class Boot < Base
+      # @param cookie   [String, nil] Raw cookie string (--password), nil to rely on existing cache
+      # @param username [String, nil] Expected subject; if provided, must match token's `sub` claim
+      # @param **base_params          Forwarded to Base (base_url:, params: {client_id:, scope:}, etc.)
+      def initialize(cookie: nil, username: nil, **base_params)
+        if cookie.nil?
+          # No cookie: rely on existing cache, identified by username if provided
+          Aspera.assert(username, 'Provide --password (cookie) on first use, or --username for cache lookup', type: ParameterError)
+          super(**base_params, cache_ids: [username])
+        else
+          cookies = cookie.split('; ').map{ |p| p.split('=', 2)}.to_h
+          Aspera.assert(cookies.key?('aoc.token'), '--password cookie does not contain aoc.token', type: ParameterError)
+          token = cookies['aoc.token']
+          decoded = Factory.instance.decode_token(token)
+          Aspera.assert_type(decoded, Hash){'Boot: token is not a decodable JWT'}
+          sub = decoded['sub']
+          Aspera.assert(username.nil? || username.eql?(sub)){"Boot: --username #{username} does not match token subject #{sub}"}
+          super(**base_params, cache_ids: [sub])
+          token_data = {Factory::TOKEN_FIELD => token}
+          token_data['refresh_token'] = cookies['aoc.refresh'] if cookies.key?('aoc.refresh')
+          Factory.instance.persist_mgr.put(@token_cache_id, JSON.generate(token_data))
+        end
+      end
+
+      # Should never be reached: if cache and refresh are both exhausted, re-authenticate via browser
+      def create_token
+        Aspera.report_error(AssertError, 'Boot: token expired and no refresh available — re-authenticate in browser')
+      end
+    end
+    Factory.instance.register_token_creator(Boot)
+  end
+end

data/lib/aspera/oauth/factory.rb

@@ -7,10 +7,14 @@ require 'base64'
 module Aspera
   module OAuth
     # Factory to create tokens and manage their cache
+    #
+    # @!method self.instance
+    #   Returns the singleton instance of Factory
+    #   @return [Factory] the singleton instance
     class Factory
       include Singleton
 
-      # a prefix for persistency of tokens (simplify garbage collect)
+      # prefix for persistency of tokens (simplify garbage collect)
       PERSIST_CATEGORY_TOKEN = 'token'
       # prefix for bearer authorization when in header
       SPACE_BEARER_AUTH_SCHEME = 'Bearer '
@@ -19,18 +23,23 @@ module Aspera
       private_constant :PERSIST_CATEGORY_TOKEN, :SPACE_BEARER_AUTH_SCHEME
 
       class << self
+        # Format a token for use in Authorization header
         # @param token [String] The token alone
         # @return [String] Value suitable for Authorization header
         def bearer_authorization(token)
           return "#{SPACE_BEARER_AUTH_SCHEME}#{token}"
         end
 
-        # @return true if the authorization contains a bearer token , i.e. auth scheme is bearer
+        # Check if the authorization contains a bearer token
+        # @param authorization [String] The authorization header value
+        # @return [Boolean] true if the authorization contains a bearer token, i.e. auth scheme is bearer
         def bearer_auth?(authorization)
           return authorization.start_with?(SPACE_BEARER_AUTH_SCHEME)
         end
 
         # Extract only token from Authorization (remove scheme)
+        # @param authorization [String] The authorization header value
+        # @return [String] The bearer token without the scheme prefix
         def bearer_token(authorization)
           Aspera.assert(bearer_auth?(authorization)){'not a bearer token, wrong prefix scheme'}
           return authorization.delete_prefix(SPACE_BEARER_AUTH_SCHEME)
@@ -40,12 +49,14 @@ module Aspera
         # @param url           [String] Base URL of the OAuth server
         # @param creator_class [Class]  Class of the token creator
         # @param params        [Array]  List of parameters (can be nested) to uniquely identify the token
-        # @return a unique cache identifier
+        # @return [String] a unique cache identifier
         def cache_id(url, creator_class, *params)
           return IdGenerator.from_list(PERSIST_CATEGORY_TOKEN, url, Factory.class_to_id(creator_class), params)
         end
 
-        # @return snake version of class name
+        # Convert a class name to snake_case symbol
+        # @param creator_class [Class] The class to convert
+        # @return [Symbol] snake_case version of class name
         def class_to_id(creator_class)
           return creator_class.name.split('::').last.capital_to_snake.to_sym
         end
@@ -53,6 +64,7 @@ module Aspera
 
       private
 
+      # Initialize the factory with default parameters and empty collections
       def initialize
         # persistency manager
         @persist = nil
@@ -73,12 +85,16 @@ module Aspera
 
       attr_reader :parameters
 
+      # Set the persistence manager for token caching
+      # @param manager [Object] The persistence manager instance
       def persist_mgr=(manager)
         @persist = manager
         # cleanup expired tokens
         @persist.garbage_collect(PERSIST_CATEGORY_TOKEN, @parameters[:token_cache_max_age])
       end
 
+      # Get or initialize the persistence manager
+      # @return [Object] The persistence manager instance
       def persist_mgr
         if @persist.nil?
           # use OAuth::Factory.instance.persist_mgr=PersistencyFolder.new)
@@ -91,11 +107,14 @@ module Aspera
         return @persist
       end
 
-      # delete all existing tokens
+      # Delete all existing tokens in cache
+      # @return [void]
       def flush_tokens
         persist_mgr.garbage_collect(PERSIST_CATEGORY_TOKEN)
       end
 
+      # Retrieve all persisted tokens with their decoded information
+      # @return [Array<Hash>] Array of token information hashes
       def persisted_tokens
         data = persist_mgr.current_items(PERSIST_CATEGORY_TOKEN)
         data.each.map do |k, v|
@@ -134,12 +153,16 @@ module Aspera
         return info
       end
 
-      # register a bearer token decoder, mainly to inspect expiry date
+      # Register a bearer token decoder for inspecting token properties
+      # @param method [Proc] The decoder lambda/proc to register
+      # @return [void]
       def register_decoder(method)
         @decoders.push(method)
       end
 
-      # decode token using all registered decoders
+      # Decode a token using all registered decoders
+      # @param token [String] The token to decode
+      # @return [Hash, nil] Decoded token data or nil if no decoder succeeded
       def decode_token(token)
         @decoders.each do |decoder|
           result = decoder.call(token) rescue nil
@@ -148,10 +171,9 @@ module Aspera
         return
       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
+      # Register a token creation method
+      # @param creator_class [Class] The token creator class to register
+      # @return [void]
       def register_token_creator(creator_class)
         Aspera.assert_type(creator_class, Class)
         id = Factory.class_to_id(creator_class)
@@ -159,7 +181,9 @@ module Aspera
         @token_type_classes[id] = creator_class
       end
 
-      # @return one of the registered creators for the given create type
+      # Create a token creator instance for the specified grant method
+      # @param parameters [Hash] Parameters including :grant_method and creator-specific options
+      # @return [Object] An instance of the registered token creator class
       def create(**parameters)
         Aspera.assert_type(parameters, Hash)
         id = parameters[:grant_method]
@@ -169,6 +193,6 @@ module Aspera
       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 JWS token'}; JSON.parse(Base64.decode64(parts[1]))}) # rubocop:disable Style/Semicolon
+    Factory.instance.register_decoder(lambda{ |token| parts = token.split('.'); Aspera.assert_values(parts.length, [3]){'JWS token parts'}; JSON.parse(Base64.decode64(parts[1]))}) # rubocop:disable Style/Semicolon
   end
 end

data/lib/aspera/oauth/web.rb

@@ -22,8 +22,8 @@ module Aspera
         @redirect_uri = redirect_uri
         @path_authorize = path_authorize
         uri = URI.parse(@redirect_uri)
-        Aspera.assert(%w[http https].include?(uri.scheme)){'redirect_uri scheme must be http or https'}
-        Aspera.assert(!uri.port.nil?){'redirect_uri must have a port'}
+        Aspera.assert_values(uri.scheme, %w[http https]){'redirect_uri scheme must be http or https'}
+        Aspera.assert(!uri.port.nil?, 'redirect_uri must have a port')
         # TODO: we could check that host is localhost or local address, as we are going to listen locally
       end
 

data/lib/aspera/oauth.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'aspera/oauth/factory'
+require 'aspera/oauth/boot'
 require 'aspera/oauth/generic'
 require 'aspera/oauth/jwt'
 require 'aspera/oauth/web'

data/lib/aspera/persistency_action_once.rb

@@ -23,9 +23,9 @@ module Aspera
     # @param :merge    Optional  merge data from file to current data
     def initialize(manager:, data:, id:, delete: DELETE_DEFAULT, parse: PARSE_DEFAULT, format: FORMAT_DEFAULT, merge: MERGE_DEFAULT)
       Aspera.assert(MANAGER_METHODS.all?{ |i| manager.respond_to?(i)}){"Manager must answer to #{MANAGER_METHODS}"}
-      Aspera.assert(!data.nil?)
+      Aspera.assert(!data.nil?, 'data must not be nil')
       Aspera.assert_type(id, String)
-      Aspera.assert(!id.empty?)
+      Aspera.assert(!id.empty?, 'id must not be empty')
       Aspera.assert_type(delete, Proc)
       Aspera.assert_type(parse, Proc)
       Aspera.assert_type(format, Proc)

data/lib/aspera/preview/file_types.rb

@@ -8,6 +8,10 @@ require 'marcel'
 module Aspera
   module Preview
     # function conversion_type returns one of the types: CONVERSION_TYPES
+    #
+    # @!method self.instance
+    #   Returns the singleton instance of FileTypes
+    #   @return [FileTypes] the singleton instance
     class FileTypes
       include Singleton
 

data/lib/aspera/products/connect.rb

@@ -5,6 +5,9 @@ require 'singleton'
 
 module Aspera
   module Products
+    # @!method self.instance
+    #   Returns the singleton instance of Connect
+    #   @return [Connect] the singleton instance
     class Connect
       include Singleton
 

data/lib/aspera/products/transferd.rb

@@ -29,7 +29,7 @@ module Aspera
 
         # @return the path to folder where SDK is or should be installed
         def sdk_directory
-          Aspera.assert(!@sdk_dir.nil?){'SDK path was not initialized'}
+          Aspera.assert(!@sdk_dir.nil?, 'SDK path was not initialized')
           @sdk_dir
         end
 
@@ -52,7 +52,7 @@ module Aspera
               end
             end
           end
-          Aspera.assert(!result.nil?){'Port not found in daemon logs'}
+          Aspera.assert(!result.nil?, 'Port not found in daemon logs')
           Log.log.debug{"Got port #{result} from log"}
           return result
         end

data/lib/aspera/proxy_auto_config.rb

@@ -14,7 +14,7 @@ module URI
       # @yieldparam url [String] The URL to find proxy for
       # @yieldreturn [String, nil] Proxy URL or nil to fallback to original method
       def register_proxy_finder
-        Aspera.assert(block_given?)
+        Aspera.assert(block_given?, 'block required for register_proxy_finder')
         # overload the method in URI : call user's provided block and fallback to original method
         define_method(:find_proxy){ |env_vars = ENV| yield(to_s) || find_proxy_orig(env_vars)}
       end
@@ -116,12 +116,12 @@ END_OF_JAVASCRIPT
         parts = item.strip.split
         case parts.shift
         when 'DIRECT'
-          Aspera.assert(parts.empty?){'DIRECT has no param'}
+          Aspera.assert(parts.empty?, 'DIRECT has no param')
           Log.log.debug('ignoring proxy DIRECT')
         when 'PROXY'
           addr_port = parts.shift
           Aspera.assert_type(addr_port, String)
-          Aspera.assert(parts.empty?){'PROXY shall have one param'}
+          Aspera.assert(parts.empty?, 'PROXY shall have one param')
           begin
             # PAC proxy addresses are <host>:<port>
             if /:[0-9]+$/.match?(addr_port)

data/lib/aspera/rest.rb

@@ -30,6 +30,10 @@ module Aspera
   # @param download_partial_suffix [String] suffix for partial download
   # @param session_cb [lambda] lambda called on new HTTP session. Takes the Net::HTTP as arg. Used to change parameters on creation.
   # @param progress_bar [Object] progress bar object called for file transfer
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of RestParameters
+  #   @return [RestParameters] the singleton instance
   class RestParameters
     include Singleton
 
@@ -102,7 +106,7 @@ module Aspera
           when Hash
             URI.encode_www_form(h_to_query_array(query))
           when Array
-            Aspera.assert(query.all?{ |i| i.is_a?(Array) && i.length.eql?(2)}){'Query must be array of arrays of 2 elements'}
+            Aspera.assert(query.all?{ |i| i.is_a?(Array) && i.length.eql?(2)}, 'Query must be array of arrays of 2 elements')
             URI.encode_www_form(query) # remove nil values
           else Aspera.error_unexpected_value(query.class){'query type'}
           end.gsub('%5B%5D=', '[]=')
@@ -316,7 +320,7 @@ module Aspera
       # default is no auth
       @auth_params = auth
       Aspera.assert_type(@auth_params, Hash)
-      Aspera.assert(@auth_params.key?(:type)){'no auth type defined'}
+      Aspera.assert(@auth_params.key?(:type), 'no auth type defined')
       @not_auth_codes = not_auth_codes
       Aspera.assert_type(@not_auth_codes, Array)
       # persistent session
@@ -333,7 +337,7 @@ module Aspera
     # @return the OAuth object (create, or cached if already created)
     def oauth
       if @oauth.nil?
-        Aspera.assert(@auth_params[:type].eql?(:oauth2)){'no OAuth defined'}
+        Aspera.assert(@auth_params[:type].eql?(:oauth2), 'no OAuth defined')
         oauth_parameters = @auth_params.reject{ |k, _v| k.eql?(:type)}
         Log.dump(:oauth_parameters, oauth_parameters)
         @oauth = OAuth::Factory.instance.create(**oauth_parameters)
@@ -374,7 +378,7 @@ module Aspera
       Log.dump(:headers, headers, level: :trace1)
       Aspera.assert_type(subpath, String)
       # We must have a way to check return code
-      Aspera.assert(exception || !ret.eql?(:data))
+      Aspera.assert(exception || !ret.eql?(:data), 'ret: :data requires exception handler')
       if headers.nil?
         headers = @headers.clone
       else

data/lib/aspera/rest_error_analyzer.rb

@@ -7,6 +7,10 @@ require 'net/http'
 
 module Aspera
   # analyze error codes returned by REST calls and raise ruby exception
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of RestErrorAnalyzer
+  #   @return [RestErrorAnalyzer] the singleton instance
   class RestErrorAnalyzer
     include Singleton
 

data/lib/aspera/rest_list.rb

@@ -50,6 +50,7 @@ module Aspera
     # @return [Array<(Array<Hash>, Integer)>] items, total_count
     def list_entities_limit_offset_total_count(
       entity:,
+      operation: 'GET',
       items_key: nil,
       query: nil
     )
@@ -67,9 +68,15 @@ module Aspera
       # Merge default parameters, by default 100 per page
       query = {'limit'=> PER_PAGE_DEFAULT}.merge(query)
       total_count = nil
+      call_args = {
+        operation: operation,
+        subpath:   entity,
+        query:     query,
+        headers:   {'Accept' => Mime::JSON}
+      }
       loop do
         query['offset'] = offset
-        page_result = read(entity, query)
+        page_result = call(**call_args)
         Aspera.assert_type(page_result[items_key], Array)
         result.concat(page_result[items_key])
         # Reach the limit set by user ?
@@ -97,7 +104,7 @@ module Aspera
     # @param query     [Hash]   Additional query parameters (Default: `:default`)
     def lookup_entity_by_field(entity:, value:, field: 'name', items_key: nil, query: :default)
       if query.eql?(:default)
-        Aspera.assert(field.eql?('name')){'Default query is on name only'}
+        Aspera.assert_values(field, ['name']){'Default query field'}
         query = {'q'=> value}
       end
       lookup_entity_generic(entity: entity, field: field, value: value){list_entities_limit_offset_total_count(entity: entity, items_key: items_key, query: query).first}
@@ -113,7 +120,7 @@ module Aspera
     # @return [Hash] The unique matching object.
     # @raise  [Cli::BadIdentifier] If 0 or >1 matches are found.
     def lookup_entity_generic(entity:, value:, field: 'name')
-      Aspera.assert(block_given?)
+      Aspera.assert(block_given?, 'block required for lookup_entity_generic')
       found = yield
       Aspera.assert_array_all(found, Hash)
       found = found.select{ |i| i[field].eql?(value)}

data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml

@@ -1,3 +1,8 @@
+# DO NOT EDIT THIS FILE MANUALLY
+# This file is automatically downloaded from:
+# https://raw.githubusercontent.com/laurent-martin/aspera-api-examples/refs/heads/main/openapi/IBM%20Aspera%20Faspex%20API-5.0-enhanced.yaml
+# Use 'rake tools:openapi' to update this file
+
 openapi: 3.1.0
 info:
   title: IBM Aspera Faspex API
@@ -32646,7 +32651,12 @@ components:
                       maxLength: 255
                       minLength: 1
               expiration_policy:
-                description: The expiration policy for the package. Default is "none" for no expiration policy (a package will not be marked for deletion based on recipient downloads), "delete_after_all_download" for deleting a package after ALL users do a full download of the package (download of all files/folders in the package), "delete_after_any_download" for deleting a package after ANY user fully downloads and "delete_after_expiration_date" for deleting a package after the date set in expiration_date parameter.
+                description: |-
+                  The expiration policy for the package.
+                  * `none`: Default, for no expiration policy (a package will not be marked for deletion based on recipient downloads).
+                  * `delete_after_all_download` for deleting a package after ALL users do a full download of the package (download of all files/folders in the package).
+                  * `delete_after_any_download` for deleting a package after ANY user fully downloads.
+                  * `delete_after_expiration_date` for deleting a package after the date set in expiration_date parameter.
                 type: string
                 default: none
                 enum:
@@ -40721,9 +40731,9 @@ components:
           type: boolean
         can_have_public_url:
           description: |-
-            Specifies whether the user can share public submission submission links.\
-                                                        A user can share public submission links to invite external users to \
-                                                        send packages to the user.
+            Specifies whether the user can share public submission submission links.
+            A user can share public submission links to invite external users to
+            send packages to the user.
           type: string
           default: default
           enum: