aspera-cli 4.26.1 → 4.27.0

data/lib/aspera/graphql.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'aspera/rest_call_error'
+
+module Aspera
+  # Helper to execute GraphQL queries via a Rest object.
+  # Follows the GraphQL-over-HTTP convention: POST {query, variables} to endpoint,
+  # parse top-level `data` key, raise on top-level `errors` array.
+  module GraphQL
+    QUERIES_FOLDER = File.join(__dir__, 'api', 'queries')
+    private_constant :QUERIES_FOLDER
+
+    class << self
+      # Execute a GraphQL query loaded from a .graphql file in lib/aspera/api/queries/
+      # @param rest      [Rest]   API object pointing at the GraphQL endpoint
+      # @param name      [String] Base filename without extension (e.g. 'my_query')
+      # @param variables [Hash]   GraphQL variables
+      # @return [Hash]   The `data` object from the response
+      # @raise [RestCallError] if the response contains GraphQL errors
+      def execute(rest, name, variables = {})
+        query = load_query(name)
+        response = rest.create(nil, {query: query, variables: variables})
+        errors = response['errors']
+        raise RestCallError, errors.map{ |e| e['message']}.join("\n") if errors.is_a?(Array) && !errors.empty?
+        response['data']
+      end
+
+      private
+
+      def load_query(name)
+        File.read(File.join(QUERIES_FOLDER, "#{name}.graphql"))
+      end
+    end
+  end
+end

data/lib/aspera/hash_ext.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
 class ::Hash
+  # Recursively merge another hash, with nested hashes merged deeply
+  # @param second [Hash] Hash to merge into self
+  # @return [Hash] New merged hash
   def deep_merge(second)
     merge(second){ |_key, v1, v2| v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge(v2) : v2}
   end
 
+  # Recursively merge another hash in-place, with nested hashes merged deeply
+  # @param second [Hash] Hash to merge into self
+  # @return [Hash] self
   def deep_merge!(second)
     merge!(second){ |_key, v1, v2| v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge!(v2) : v2}
   end

data/lib/aspera/json_rpc/client.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# cspell:ignore blankslate jsonrpc
+
+require 'aspera/rest_error_analyzer'
+require 'aspera/assert'
+require 'aspera/json_rpc/version'
+require 'blankslate'
+
+Aspera::RestErrorAnalyzer.instance.add_simple_handler(name: 'JSON RPC', path: %w[error message], always: true)
+
+module Aspera
+  module JsonRpc
+    # JSON-RPC 2.0 client over an Aspera::Rest HTTP endpoint.
+    # Methods are dispatched dynamically via method_missing.
+    # Example:
+    #   client = JsonRpc::Client.new(Rest.new(base_url: 'http://127.0.0.1:33024'))
+    #   client.get_info
+    #   client.start_transfer(app_id: '...', transfer_spec: {...})
+    class Client < BlankSlate
+      reveal :instance_variable_get
+      reveal :inspect
+      reveal :to_s
+
+      # @param api       [Rest]   Aspera REST object pointing at the JSON-RPC endpoint
+      # @param namespace [String, nil] optional method prefix, e.g. "myns."
+      def initialize(api, namespace = nil)
+        super()
+        @api        = api
+        @namespace  = namespace
+        @request_id = 0
+      end
+
+      def respond_to_missing?(_sym, _include_private = false)
+        true
+      end
+
+      # Dispatch any Ruby method call as a JSON-RPC request
+      def method_missing(method, *args, &block)
+        args = args.first if args.size == 1 && args.first.is_a?(Hash)
+        data = @api.create('', {
+          jsonrpc: VERSION,
+          method:  "#{@namespace}#{method}",
+          params:  args,
+          id:      @request_id += 1
+        })
+        Aspera.assert_type(data, Hash){'response'}
+        Aspera.assert(data['jsonrpc'] == VERSION, 'bad version in response')
+        Aspera.assert(data.key?('id'), 'missing id in response')
+        Aspera.assert(!(data.key?('error') && data.key?('result')), 'both error and response')
+        Aspera.assert(
+          !data.key?('error') ||
+          data['error'].is_a?(Hash) &&
+          data['error']['code'].is_a?(Integer) &&
+          data['error']['message'].is_a?(String),
+          'bad error response'
+        )
+        return data['result']
+      end
+    end
+  end
+end

data/lib/aspera/json_rpc/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Aspera
+  module JsonRpc
+    VERSION = '2.0'
+  end
+end

data/lib/aspera/keychain/base.rb

@@ -11,7 +11,7 @@ module Aspera
         options.each_pair do |k, v|
           Aspera.assert_type(v, String){k.to_s}
         end
-        Aspera.assert(options.key?(:label)){'label is required'}
+        Aspera.assert(options.key?(:label), 'label is required')
       end
     end
   end

data/lib/aspera/keychain/encrypted_hash.rb

@@ -28,7 +28,7 @@ module Aspera
           vault_file = File.read(@path)
           if vault_file.start_with?('---')
             vault_info = YAML.parse(vault_file).to_ruby
-            Aspera.assert(vault_info.keys.sort == FILE_KEYS){'Invalid vault file'}
+            Aspera.assert(vault_info.keys.sort == FILE_KEYS, 'Invalid vault file')
             @cipher_name = vault_info['cipher']
             vault_encrypted_data = vault_info['data']
           else
@@ -64,7 +64,7 @@ module Aspera
       def set(options)
         validate_set(options)
         label = options.delete(:label)
-        raise "secret #{label} already exist, delete first" if @all_secrets.key?(label)
+        Aspera.assert(!@all_secrets.key?(label)){"secret #{label} already exist, delete first"}
         @all_secrets[label] = options.symbolize_keys
         save
       end

data/lib/aspera/keychain/factory.rb

@@ -20,23 +20,23 @@ module Aspera
           when 'file'
             info[:file] = name || 'vault.bin'
             info[:file] = File.join(folder, info[:file]) unless File.absolute_path?(info[:file])
-            Aspera.assert(!password.nil?){'please provide password'}
+            Aspera.assert(!password.nil?, 'please provide password')
             info[:password] = password
             # this module requires compilation, so it is optional
             require 'aspera/keychain/encrypted_hash'
-            @vault = Keychain::EncryptedHash.new(**info)
+            Keychain::EncryptedHash.new(**info)
           when 'system'
             case Environment.instance.os
             when Environment::OS_MACOS
               info[:name] ||= name
-              @vault = Keychain::MacosSystem.new(**info)
+              Keychain::MacosSystem.new(**info)
             else
               raise Error, 'not implemented for this OS'
             end
           when 'vault'
             require 'aspera/keychain/hashicorp_vault'
             info[:token] ||= password
-            @vault = Keychain::HashicorpVault.new(**info)
+            Keychain::HashicorpVault.new(**info)
           else Aspera.error_unexpected_value(vault_type)
           end
         end

data/lib/aspera/keychain/macos_security.rb

@@ -42,9 +42,9 @@ 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?
+              Aspera.assert(!uri.host.nil?, type: Error){'host required in URL'}
               options[:server] = uri.host
               options[:path] = uri.path unless ['', '/'].include?(uri.path)
               options[:port] = uri.port unless uri.port.eql?(443) && !url.include?(':443/')
@@ -128,7 +128,7 @@ module Aspera
         super()
         @keychain_name = name.nil? ? 'default keychain' : name
         @keychain = name.nil? ? MacosSecurity::Keychain.default : MacosSecurity::Keychain.by_name(name)
-        raise "no such keychain #{name}" if @keychain.nil?
+        Aspera.assert(!@keychain.nil?){"no such keychain #{name}"}
       end
 
       def info
@@ -155,7 +155,7 @@ module Aspera
         unsupported = options.keys - %i[label]
         Aspera.assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         info = @keychain.password(:find, :generic, label: options[:label])
-        raise Error, 'not found' if info.nil?
+        Aspera.assert(!info.nil?, type: Error){'not found'}
         result = options.clone
         result[:secret] = info['password']
         result[:description] = info['icmt'] # cspell: disable-line

data/lib/aspera/link_header.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Aspera
+  # Parse and represent an HTTP Link header as per RFC 8288.
+  # Inspired by the link_header gem, with the following fixes:
+  #   - rel lookup is case-insensitive (RFC 7230: parameter names are case-insensitive)
+  #   - uses StringScanner so commas inside <URI> are never mistaken for entry separators
+  #   - no external dependency
+  class LinkHeader
+    # A single link entry: one URI and its attribute pairs.
+    class Link
+      attr_reader :href, :attr_pairs
+
+      def initialize(href, attr_pairs)
+        @href = href
+        @attr_pairs = attr_pairs
+      end
+
+      # Retrieve an attribute value by name, case-insensitively.
+      def [](key)
+        pair = @attr_pairs.detect{ |k, _v| k.casecmp?(key)}
+        pair&.last
+      end
+    end
+
+    attr_reader :links
+
+    def initialize(links = [])
+      @links = links
+    end
+
+    # Return the href of the first link whose +rel+ attribute matches +rel+.
+    # Comparison is case-insensitive per RFC 7230 s.3.2 and RFC 8288 s.3.
+    # Returns nil if no link with that relation exists.
+    # @param rel [String]
+    # @return [String, nil]
+    def find_href(rel: 'next')
+      @links.detect{ |link| link['rel']&.casecmp?(rel)}&.href
+    end
+
+    class << self
+      # Parse a raw Link header value into a +LinkHeader+ instance.
+      # Uses StringScanner so that commas inside <URI> are not treated as separators.
+      # @param raw [String, nil]
+      # @return [LinkHeader]
+      def parse(raw)
+        return new unless raw && !raw.empty?
+
+        links = []
+        scanner = StringScanner.new(raw)
+
+        while scanner.scan(HREF_RE)
+          href  = scanner[1].strip
+          attrs = []
+          while scanner.scan(ATTR_RE)
+            key   = scanner[1]
+            # scanner[2] = full match (token or "quoted"), scanner[3] = content inside double-quotes
+            value = scanner[3] || scanner[2]
+            attrs << [key, value]
+            break unless scanner.scan(SEMI_RE)
+          end
+          links << Link.new(href, attrs)
+          break unless scanner.scan(COMMA_RE)
+        end
+
+        new(links)
+      end
+
+      private :new
+    end
+
+    # RFC 2616 token: any char except separators
+    TOKEN_RE  = /[^()<>@,;:\"\[\]?={}\s]+/  # RFC 2616 token
+    QUOTED_RE = /"((?:[^"\\]|\\.)*)"/       # double-quoted string with backslash escapes
+    HREF_RE   = /\s*<([^>]*)>\s*;?\s*/      # <URI> possibly followed by ;
+    ATTR_RE   = /(#{TOKEN_RE})\s*=\s*(#{TOKEN_RE}|#{QUOTED_RE})\s*/ # key=value or key="value"
+    SEMI_RE   = /;\s*/                       # parameter separator
+    COMMA_RE  = /,\s*/                       # link entry separator
+  end
+end

data/lib/aspera/log.rb

@@ -36,13 +36,16 @@ class Logger
   end
 
   class << self
-    # Define methods for a given log level
+    # Define logger methods for a given log level (e.g. `debug`, `debug?`, `debug!`)
+    # @param str_level [String] Log level name (e.g. "DEBUG", "TRACE1")
+    # @return [nil]
     def make_methods(str_level)
       int_level = ::Logger.const_get(str_level.upcase)
       method_base = str_level.downcase
       define_method(method_base, ->(message = nil, &block){add(int_level, message, &block)})
       define_method("#{method_base}?", ->{level <= int_level})
       define_method("#{method_base}!", ->{self.level = int_level})
+      nil
     end
   end
   # Declare methods for all levels
@@ -54,6 +57,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 +87,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
@@ -138,9 +145,13 @@ module Aspera
     attr_reader :logger_type, :logger
     attr_accessor :dump_format
 
+    # Set the program name used in log output
+    # @param value [String] Program name
+    # @return [nil]
     def program_name=(value)
       @program_name = value
       self.logger_type = @logger_type
+      nil
     end
 
     # Set log level of underlying logger given symbol level
@@ -150,15 +161,19 @@ module Aspera
       @logger.level = Logger::Severity.const_get(new_level.to_sym.upcase)
     end
 
+    # Set log formatter; accepts a symbol name, a Proc, or a Logger::Formatter instance
+    # @param formatter [String, Proc, Logger::Formatter] Formatter to use; one of: standard, default, caller
+    # @return [nil]
     def formatter=(formatter)
       if formatter.is_a?(String)
-        raise Error, "Unknown formatter #{formatter}, use one of: #{FORMATTERS.join(', ')}" unless FORMATTER_LAMBDAS.key?(formatter.to_sym)
+        Aspera.assert(FORMATTER_LAMBDAS.key?(formatter.to_sym), type: Error){"Unknown formatter #{formatter}, use one of: #{FORMATTERS.join(', ')}"}
         formatter = FORMATTER_LAMBDAS[formatter.to_sym]
       elsif !formatter.respond_to?(:call) && !formatter.is_a?(Logger::Formatter)
         raise Error, 'Formatter must be a String, a Logger::Formatter or a Proc'
       end
       # Update formatter with password hiding
       @logger.formatter = SecretHider.instance.log_formatter(formatter)
+      nil
     end
 
     def formatter
@@ -168,11 +183,13 @@ 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
 
-    # Change underlying logger, but keep log level (default: INFO)
+    # Change underlying logger output destination, keeping current log level
+    # @param new_log_type [Symbol] Log destination; one of LOG_TYPES (:stderr, :stdout, :syslog)
+    # @return [nil]
     def logger_type=(new_log_type)
       # [Integer]
       current_severity_integer = @logger&.level || ENV['AS_LOG_LEVEL']&.to_i || Logger::Severity::INFO
@@ -199,6 +216,7 @@ module Aspera
       @logger_type = new_log_type
       # add secret hider to default logger
       self.formatter = @logger.formatter
+      nil
     end
 
     private

data/lib/aspera/markdown.rb

@@ -9,6 +9,71 @@ module Aspera
 
     class << self
       COL_WIDTH = 80
+
+      # Convert a Markdown heading text to a GitHub-flavoured anchor.
+      # Rules: downcase, keep letters/digits/spaces/hyphens, replace spaces with hyphens.
+      # Duplicate anchors are disambiguated by appending -1, -2, … (pass a seen Hash to track).
+      # @param text  [String]           raw heading text (without leading # and spaces)
+      # @param seen  [Hash{String=>Integer}, nil]  mutable counter; pass the same Hash across a document
+      # @return [String] anchor slug (without leading #)
+      def heading_to_anchor(text, seen: nil)
+        slug = text
+          .downcase
+          .gsub(/[`*_]/, '')           # strip inline code/bold/italic markers
+          .gsub(/&[a-z]+;/, '')        # strip HTML entities
+          .gsub(/[^\w\s-]/, '')        # keep word chars, spaces, hyphens
+          .gsub(/\s+/, '-')            # spaces → hyphens
+          .squeeze('-')                # collapse consecutive hyphens
+          .strip
+        if seen
+          count = seen[slug].to_i
+          seen[slug] = count + 1
+          slug = "#{slug}-#{count}" if count > 0
+        end
+        slug
+      end
+
+      # Extract the table of contents from a Markdown document.
+      # @param content [String]  full Markdown source
+      # @return [Array<Hash>]   array of { level, title, anchor }
+      HEADING_RE = /^(\#{1,6})\s+(.+)$/
+
+      def toc(content)
+        seen = {}
+        content.each_line.filter_map do |line|
+          m = line.match(HEADING_RE)
+          next unless m
+          title = m[2].strip
+          {level: m[1].length, title: title, anchor: heading_to_anchor(title, seen: seen)}
+        end
+      end
+
+      # Extract the content of a single section (heading + body until next heading of same/higher level).
+      # @param content   [String]  full Markdown source
+      # @param anchor    [String]  GitHub anchor slug (without #)
+      # @return [String, nil]  the section content, or nil if not found
+      def extract_section(content, anchor)
+        seen = {}
+        section_level = nil
+        result = []
+        content.each_line do |line|
+          m = line.match(HEADING_RE)
+          if m
+            slug = heading_to_anchor(m[2].strip, seen: seen)
+            if section_level.nil?
+              # not yet found: check if this heading matches
+              next unless slug == anchor
+              section_level = m[1].length
+            elsif m[1].length <= section_level
+              # already in section: stop at same/higher level heading
+              break
+            end
+          end
+          result << line if section_level
+        end
+        result.empty? ? nil : result.join
+      end
+
       # Generate markdown from the provided 2D table
       # @param table [Array<Array<String>>] 2D array of strings
       # @return [String] markdown table
@@ -26,28 +91,46 @@ module Aspera
       end
 
       # Generate markdown list from the provided list
+      # @param items [Array<String>] list of items
+      # @return [String] markdown unordered list
       def list(items)
         items.map{ |i| "- #{i}"}.join("\n")
       end
 
+      # Generate a markdown heading
+      # @param title [String] heading text
+      # @param level [Integer] heading level (1–6)
+      # @return [String] markdown heading
       def heading(title, level: 1)
         "#{'#' * level} #{title}\n\n"
       end
 
-      # type: NOTE CAUTION WARNING IMPORTANT TIP INFO
+      # Generate a GitHub-flavoured admonition block
+      # @param lines [Array<String>] lines of the admonition body
+      # @param type [String] admonition type: NOTE, CAUTION, WARNING, IMPORTANT, TIP, INFO
+      # @return [String] markdown admonition block
       def admonition(lines, type: 'INFO')
         "> [!#{type}]\n#{lines.map{ |l| "> #{l}"}.join("\n")}\n\n"
       end
 
+      # Generate a fenced code block
+      # @param lines [Array<String>] lines of code
+      # @param type [String] language identifier for syntax highlighting
+      # @return [String] markdown fenced code block
       def code(lines, type: 'shell')
         "```#{type}\n#{lines.join("\n")}\n```\n\n"
       end
 
-      # inline code
+      # Wrap text in inline code backticks
+      # @param text [String] text to wrap
+      # @return [String] inline code span
       def icode(text)
         "`#{text}`"
       end
 
+      # Wrap text in a markdown paragraph (trailing blank line)
+      # @param text [String] paragraph content
+      # @return [String] paragraph with trailing newlines
       def paragraph(text)
         "#{text}\n\n"
       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/node_simulator.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'aspera/assert'
 require 'aspera/ascp/installation'
 require 'aspera/agent/direct'
 require 'aspera/log'
@@ -128,6 +129,7 @@ module Aspera
 
     # Process event from management port
     def process_event(event)
+      # Code duplicated on purpose, as implementation goes, blocks will be replaced
       case event['Type']
       when 'NOP' then Aspera.Log.debug{"event not managed: #{event['Type']}"}
       # rubocop:disable Lint/DuplicateBranch
@@ -174,7 +176,7 @@ module Aspera
     require 'time'
 
     def folder_to_structure(folder_path)
-      raise "Path does not exist or is not a directory: #{folder_path}" unless Dir.exist?(folder_path)
+      Aspera.assert(Dir.exist?(folder_path)){"Path does not exist or is not a directory: #{folder_path}"}
 
       # Build self structure
       folder_stat = File.stat(folder_path)

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,14 +42,14 @@ 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]
-      # @raise RestError if not 2XX code
+      # @return [Net::HTTPResponse] raw HTTP response with token
+      # @raise [RestCallError] if not 2XX code
       def create_token_call(creation_params)
         Log.log.debug{'Generating a new token'.bg_green}
         return @api.create(@path_token, nil, query: creation_params, ret: :resp) if @use_query
@@ -73,8 +73,8 @@ module Aspera
       # get an OAuth v2 token (generated, cached, refreshed)
       # call token() to get a token.
       # if a token is expired (api returns 4xx), call again token(refresh: true)
-      # @param cache set to false to disable cache
-      # @param refresh set to true to force refresh or re-generation (if previous failed)
+      # @param cache   [Boolean] set to false to disable cache
+      # @param refresh [Boolean] set to true to force refresh or re-generation (if previous failed)
       def token(cache: true, refresh: false)
         # get token info from cache (or nil), decoded with date and expiration status
         token_info = Factory.instance.get_token_info(@token_cache_id) if cache
@@ -106,7 +106,7 @@ module Aspera
                 json_data = http.body
                 token_data = JSON.parse(json_data)
                 Factory.instance.persist_mgr.put(@token_cache_id, json_data)
-              rescue => e
+              rescue StandardError => e
                 # Refresh token can fail.
                 Log.log.warn{"Refresh failed: #{e}"}
               end
@@ -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 [Hash] 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