aspera-cli 4.15.0 → 4.16.0

data/lib/aspera/fasp/sync.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+# cspell:words logdir bidi watchd cooloff asyncadmin
+
+require 'aspera/command_line_builder'
+require 'aspera/fasp/installation'
+require 'aspera/log'
+require 'aspera/assert'
+require 'json'
+require 'base64'
+require 'open3'
+require 'English'
+
+module Aspera
+  module Fasp
+    # builds command line arg for async
+    module Sync
+      # sync direction, default is push
+      DIRECTIONS = %i[push pull bidi].freeze
+      # custom JSON for async instance command line options
+      PARAMS_VX_INSTANCE =
+        {
+          'alt_logdir'          => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'watchd'              => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'apply_local_docroot' => { cli: { type: :opt_without_arg}},
+          'quiet'               => { cli: { type: :opt_without_arg}},
+          'ws_connect'          => { cli: { type: :opt_without_arg}}
+        }.freeze
+
+      # map sync session parameters to transfer spec: sync -> ts, true if same
+      PARAMS_VX_SESSION =
+        {
+          'name'                       => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'local_dir'                  => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'remote_dir'                 => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'local_db_dir'               => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'remote_db_dir'              => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'host'                       => { cli: { type: :opt_with_arg}, accepted_types: :string, ts: :remote_host},
+          'user'                       => { cli: { type: :opt_with_arg}, accepted_types: :string, ts: :remote_user},
+          'private_key_paths'          => { cli: { type: :opt_with_arg, switch: '--private-key-path'}, accepted_types: :array},
+          'direction'                  => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'checksum'                   => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'tags'                       => { cli: { type: :opt_with_arg, switch: '--tags64', convert: 'Aspera::Fasp::Parameters.convert_json64'},
+                                            accepted_types: :hash, ts: true},
+          'tcp_port'                   => { cli: { type: :opt_with_arg}, accepted_types: :int, ts: :ssh_port},
+          'rate_policy'                => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'target_rate'                => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'cooloff'                    => { cli: { type: :opt_with_arg}, accepted_types: :int},
+          'pending_max'                => { cli: { type: :opt_with_arg}, accepted_types: :int},
+          'scan_intensity'             => { cli: { type: :opt_with_arg}, accepted_types: :string},
+          'cipher'                     => { cli: { type: :opt_with_arg, convert: 'Aspera::Fasp::Parameters.convert_remove_hyphen'}, accepted_types: :string, ts: true},
+          'transfer_threads'           => { cli: { type: :opt_with_arg}, accepted_types: :int},
+          'preserve_time'              => { cli: { type: :opt_without_arg}, ts: :preserve_times},
+          'preserve_access_time'       => { cli: { type: :opt_without_arg}, ts: nil},
+          'preserve_modification_time' => { cli: { type: :opt_without_arg}, ts: nil},
+          'preserve_uid'               => { cli: { type: :opt_without_arg}, ts: :preserve_file_owner_uid},
+          'preserve_gid'               => { cli: { type: :opt_without_arg}, ts: :preserve_file_owner_gid},
+          'create_dir'                 => { cli: { type: :opt_without_arg}, ts: true},
+          'reset'                      => { cli: { type: :opt_without_arg}},
+          # NOTE: only one env var, but multiple sessions... could be a problem
+          'remote_password'            => { cli: { type: :envvar, variable: 'ASPERA_SCP_PASS'}, ts: true},
+          'cookie'                     => { cli: { type: :envvar, variable: 'ASPERA_SCP_COOKIE'}, ts: true},
+          'token'                      => { cli: { type: :envvar, variable: 'ASPERA_SCP_TOKEN'}, ts: true},
+          'license'                    => { cli: { type: :envvar, variable: 'ASPERA_SCP_LICENSE'}}
+        }.freeze
+
+      Aspera::CommandLineBuilder.normalize_description(PARAMS_VX_INSTANCE)
+      Aspera::CommandLineBuilder.normalize_description(PARAMS_VX_SESSION)
+
+      PARAMS_VX_KEYS = %w[instance sessions].freeze
+
+      # Translation of transfer spec parameters to async v2 API (asyncs)
+      TS_TO_PARAMS_V2 = {
+        'remote_host'     => 'remote.host',
+        'remote_user'     => 'remote.user',
+        'remote_password' => 'remote.pass',
+        'sshfp'           => 'remote.fingerprint',
+        'ssh_port'        => 'remote.port',
+        'wss_port'        => 'remote.ws_port',
+        'proxy'           => 'remote.proxy',
+        'token'           => 'remote.token',
+        'tags'            => 'tags'
+      }.freeze
+
+      ASYNC_EXECUTABLE = 'async'
+      ASYNC_ADMIN_EXECUTABLE = 'asyncadmin'
+
+      private_constant :PARAMS_VX_INSTANCE, :PARAMS_VX_SESSION, :PARAMS_VX_KEYS, :TS_TO_PARAMS_V2, :ASYNC_EXECUTABLE, :ASYNC_ADMIN_EXECUTABLE
+
+      class << self
+        # Set remote_dir in sync parameters based on transfer spec
+        # @param params [Hash] sync parameters, old or new format
+        # @param remote_dir_key [String] key to update in above hash
+        # @param transfer_spec [Hash] transfer spec
+        def update_remote_dir(sync_params, remote_dir_key, transfer_spec)
+          if transfer_spec.dig(*%w[tags aspera node file_id])
+            # in AoC, use gen4
+            sync_params[remote_dir_key] = '/'
+          elsif transfer_spec['cookie']&.start_with?('aspera.shares2')
+            # TODO : something more generic, independent of Shares
+            # in Shares, the actual folder on remote end is not always the same as the name of the share
+            actual_remote = transfer_spec['paths']&.first&.[]('source')
+            sync_params[remote_dir_key] = actual_remote if actual_remote
+          end
+          nil
+        end
+
+        def remote_certificates(remote)
+          certificates_to_use = []
+          # use web socket secure for session ?
+          if remote['connect_mode']&.eql?('ws')
+            remote.delete('port')
+            remote.delete('fingerprint')
+            # ignore cert for wss ?
+            if false # @options[:check_ignore]&.call(remote['host'], remote['ws_port'])
+              wss_cert_file = TempFileManager.instance.new_file_path_global('wss_cert')
+              wss_url = "https://#{remote['host']}:#{remote['ws_port']}"
+              File.write(wss_cert_file, Rest.remote_certificates(wss_url))
+              certificates_to_use.push(wss_cert_file)
+            end
+            # set location for CA bundle to be the one of Ruby, see env var SSL_CERT_FILE / SSL_CERT_DIR
+            # certificates_to_use.concat(@options[:trusted_certs]) if @options[:trusted_certs]
+          else
+            # remove unused parameter (avoid warning)
+            remote.delete('ws_port')
+            # add SSH bypass keys when authentication is token and no auth is provided
+            if remote.key?('token') && !remote.key?('pass')
+              certificates_to_use.concat(Installation.instance.aspera_token_ssh_key_paths)
+            end
+          end
+          return certificates_to_use
+        end
+
+        # @param sync_params [Hash] sync parameters, old or new format
+        # @param block [nil, Proc] block to generate transfer spec, takes: direction (one of DIRECTIONS), local_dir, remote_dir
+        def start(sync_params, &block)
+          assert_type(sync_params, Hash)
+          env_args = {
+            args: [],
+            env:  {}
+          }
+          if sync_params.key?('local')
+            remote = sync_params['remote']
+            # async native JSON format (v2)
+            assert_type(remote, Hash)
+            # get transfer spec if possible, and feed back to new structure
+            if block
+              transfer_spec = yield((sync_params['direction'] || 'push').to_sym, sync_params['local']['path'], remote['path'])
+              # async native JSON format
+              assert_type(sync_params['local'], Hash)
+              # translate transfer spec to async parameters
+              TS_TO_PARAMS_V2.each do |ts_param, sy_path|
+                next unless transfer_spec.key?(ts_param)
+                sy_dig = sy_path.split('.')
+                param = sy_dig.pop
+                hash = sy_dig.empty? ? sync_params : sync_params[sy_dig.first]
+                hash = sync_params[sy_dig.first] = {} if hash.nil?
+                hash[param] = transfer_spec[ts_param]
+              end
+              update_remote_dir(remote, 'path', transfer_spec)
+            end
+            remote['connect_mode'] ||= remote.key?('ws_port') ? 'ws' : 'ssh'
+            add_certificates = remote_certificates(remote)
+            if !add_certificates.empty?
+              remote['private_key_paths'] ||= []
+              remote['private_key_paths'].concat(add_certificates)
+            end
+            assert_type(sync_params, Hash)
+            env_args[:args] = ["--conf64=#{Base64.strict_encode64(JSON.generate(sync_params))}"]
+          elsif sync_params.key?('sessions')
+            # ascli JSON format (v1)
+            if block
+              sync_params['sessions'].each do |session|
+                transfer_spec = yield((session['direction'] || 'push').to_sym, session['local_dir'], session['remote_dir'])
+                PARAMS_VX_SESSION.each do |async_param, behavior|
+                  if behavior.key?(:ts)
+                    tspec_param = behavior[:ts].is_a?(TrueClass) ? async_param : behavior[:ts].to_s
+                    session[async_param] ||= transfer_spec[tspec_param] if transfer_spec.key?(tspec_param)
+                  end
+                end
+                session['private_key_paths'] = Fasp::Installation.instance.aspera_token_ssh_key_paths if transfer_spec.key?('token')
+                update_remote_dir(session, 'remote_dir', transfer_spec)
+              end
+            end
+            raise StandardError, "Only 'sessions', and optionally 'instance' keys are allowed" unless
+              sync_params.keys.push('instance').uniq.sort.eql?(PARAMS_VX_KEYS)
+            assert_type(sync_params['sessions'], Array)
+            assert_type(sync_params['sessions'].first, Hash)
+            if sync_params.key?('instance')
+              assert_type(sync_params['instance'], Hash)
+              instance_builder = Aspera::CommandLineBuilder.new(sync_params['instance'], PARAMS_VX_INSTANCE)
+              instance_builder.process_params
+              instance_builder.add_env_args(env_args)
+            end
+
+            sync_params['sessions'].each do |session_params|
+              assert_type(session_params, Hash)
+              assert(session_params.key?('name')){'session must contain at least name'}
+              session_builder = Aspera::CommandLineBuilder.new(session_params, PARAMS_VX_SESSION)
+              session_builder.process_params
+              session_builder.add_env_args(env_args)
+            end
+          else
+            raise 'At least one of `local` or `sessions` must be present in async parameters'
+          end
+          Log.log.debug{Log.dump(:sync_params, sync_params)}
+          Log.log.debug{"execute: #{env_args[:env].map{|k, v| "#{k}=\"#{v}\""}.join(' ')} \"#{ASYNC_EXECUTABLE}\" \"#{env_args[:args].join('" "')}\""}
+          res = system(env_args[:env], [ASYNC_EXECUTABLE, ASYNC_EXECUTABLE], *env_args[:args])
+          Log.log.debug{"result=#{res}"}
+          case res
+          when true then return nil
+          when false then raise "failed: #{$CHILD_STATUS}"
+          when nil then raise "not started: #{$CHILD_STATUS}"
+          else error_unexpected_value(res)
+          end
+        end
+
+        def parse_status(stdout)
+          Log.log.trace1{"stdout=#{stdout}"}
+          result = {}
+          ids = nil
+          stdout.split("\n").each do |line|
+            info = line.split(':', 2).map(&:lstrip)
+            if info[1].eql?('')
+              info[1] = ids = []
+            elsif info[1].nil?
+              ids.push(info[0])
+              next
+            end
+            result[info[0]] = info[1]
+          end
+          return result
+        end
+
+        def admin_status(sync_params, session_name)
+          command_line = [ASYNC_ADMIN_EXECUTABLE, '--quiet']
+          if sync_params.key?('local')
+            assert(!sync_params['name'].nil?){'Missing session name'}
+            assert(session_name.nil? || session_name.eql?(sync_params['name'])){'Session not found'}
+            command_line.push("--name=#{sync_params['name']}")
+            if sync_params.key?('local_db_dir')
+              command_line.push("--local-db-dir=#{sync_params['local_db_dir']}")
+            elsif sync_params.dig('local', 'path')
+              command_line.push("--local-dir=#{sync_params.dig('local', 'path')}")
+            else
+              raise 'Missing either local_db_dir or local.path'
+            end
+          elsif sync_params.key?('sessions')
+            session = session_name.nil? ? sync_params['sessions'].first : sync_params['sessions'].find{|s|s['name'].eql?(session_name)}
+            raise "Session #{session_name} not found in #{sync_params['sessions'].map{|s|s['name']}.join(',')}" if session.nil?
+            raise 'Missing session name' if session['name'].nil?
+            command_line.push("--name=#{session['name']}")
+            if session.key?('local_db_dir')
+              command_line.push("--local-db-dir=#{session['local_db_dir']}")
+            elsif session.key?('local_dir')
+              command_line.push("--local-dir=#{session['local_dir']}")
+            else
+              raise 'Missing either local_db_dir or local_dir'
+            end
+          else
+            raise 'At least one of `local` or `sessions` must be present in async parameters'
+          end
+          Log.log.debug{"execute: #{command_line.join(' ')}"}
+          stdout, stderr, status = Open3.capture3(*command_line)
+          Log.log.debug{"status=#{status}, stderr=#{stderr}"}
+          Log.log.trace1{"stdout=#{stdout}"}
+          raise "Sync failed: #{status.exitstatus} : #{stderr}" unless status.success?
+          return parse_status(stdout)
+        end
+      end # end self
+    end # end Sync
+  end # end Fasp
+end # end Aspera

data/lib/aspera/fasp/transfer_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'aspera/fasp/parameters'
+require 'aspera/assert'
 
 module Aspera
   module Fasp
@@ -27,22 +28,23 @@ module Aspera
       end
       class << self
         def action_to_direction(tspec, command)
-          raise 'transfer spec must be a Hash' unless tspec.is_a?(Hash)
+          assert_type(tspec, Hash){'transfer spec'}
           tspec['direction'] = case command.to_sym
           when :upload then DIRECTION_SEND
           when :download then DIRECTION_RECEIVE
-          else raise 'Error: upload or download only'
+          else error_unexpected_value(command.to_sym)
           end
           return tspec
         end
 
         def action(tspec)
-          raise 'transfer spec must be a Hash' unless tspec.is_a?(Hash)
-          return case tspec['direction']
-                 when DIRECTION_SEND then :upload
-                 when DIRECTION_RECEIVE then :download
-                 else raise "Error: upload or download only, not #{tspec['direction']} (#{tspec['direction'].class})"
-                 end
+          assert_type(tspec, Hash){'transfer spec'}
+          assert_values(tspec['direction'], [DIRECTION_SEND, DIRECTION_RECEIVE]){'direction'}
+          case tspec['direction']
+          when DIRECTION_SEND then :upload
+          when DIRECTION_RECEIVE then :download
+          else error_unexpected_value(tspec['direction'])
+          end
         end
       end
     end

data/lib/aspera/fasp/uri.rb

@@ -8,12 +8,12 @@ require 'aspera/command_line_builder'
 
 module Aspera
   module Fasp
-    # translates a "faspe:" URI (used in Faspex 4) into transfer spec hash
+    # translates a "faspe:" URI (used in Faspex 4) into transfer spec (Hash)
     class Uri
       SCHEME = 'faspe'
       def initialize(fasp_link)
         @fasp_uri = URI.parse(fasp_link.gsub(' ', '%20'))
-        # TODO: check scheme is faspe
+        # TODO: check scheme is 'faspe'
       end
 
       def transfer_spec

data/lib/aspera/faspex_gw.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
-require 'aspera/web_server_simple'
 require 'aspera/log'
+require 'aspera/assert'
+require 'webrick'
 require 'json'
 
 module Aspera
-  # this class answers the Faspex /send API and creates a package on Aspera on Cloud
+  # Simulate the Faspex 4 /send API and creates a package on Aspera on Cloud or Faspex 5
   class Faspex4GWServlet < WEBrick::HTTPServlet::AbstractServlet
     # @param app_api [Aspera::AoC]
     # @param app_context [String]
     def initialize(server, app_api, app_context)
+      assert_values(app_api.class.name, ['Aspera::AoC', 'Aspera::Rest'])
       super(server)
       # typed: Aspera::AoC
       @app_api = app_api
@@ -67,13 +69,14 @@ module Aspera
           raise 'no payload' if request.body.nil?
           faspex_pkg_parameters = JSON.parse(request.body)
           Log.log.debug{"faspex pkg create parameters=#{faspex_pkg_parameters}"}
+          # compare string, as class is not yet known here
           faspex_package_create_result =
-            if @app_api.class.name.eql?('Aspera::AoC')
+            case @app_api.class.name
+            when 'Aspera::AoC'
               faspex4_send_to_aoc(faspex_pkg_parameters)
-            elsif @app_api.class.name.eql?('Aspera::Rest')
+            when 'Aspera::Rest'
               faspex4_send_to_faspex5(faspex_pkg_parameters)
-            else
-              raise "No such adapter: #{@app_api.class}"
+            else error_unexpected_value(@app_api.class.name)
             end
           Log.log.info{"faspex_package_create_result=#{faspex_package_create_result}"}
           response.status = 200
@@ -89,8 +92,8 @@ module Aspera
       else
         response.status = 400
         response['Content-Type'] = 'application/json'
-        response.body = {error: 'Bad request'}.to_json
+        response.body = {error: 'Unsupported endpoint'}.to_json
       end
     end
   end # Faspex4GWServlet
-end # AsperaLm
+end # Aspera

data/lib/aspera/faspex_postproc.rb

@@ -1,17 +1,18 @@
 # frozen_string_literal: true
 
-require 'English'
-require 'aspera/web_server_simple'
-require 'aspera/log'
 require 'json'
 require 'timeout'
+require 'English'
+require 'webrick'
+require 'aspera/log'
+require 'aspera/assert'
 
 module Aspera
   # this class answers the Faspex /send API and creates a package on Aspera on Cloud
   class Faspex4PostProcServlet < WEBrick::HTTPServlet::AbstractServlet
     ALLOWED_PARAMETERS = %i[root script_folder fail_on_error timeout_seconds].freeze
     def initialize(server, parameters)
-      raise 'parameters must be Hash' unless parameters.is_a?(Hash)
+      assert_type(parameters, Hash)
       @parameters = parameters.symbolize_keys
       Log.log.debug{Log.dump(:post_proc_parameters, @parameters)}
       raise "unexpected key in parameters config: only: #{ALLOWED_PARAMETERS.join(', ')}" if @parameters.keys.any?{|k|!ALLOWED_PARAMETERS.include?(k)}
@@ -74,4 +75,4 @@ module Aspera
       end
     end
   end # Faspex4PostProcServlet
-end # AsperaLm
+end # Aspera

data/lib/aspera/id_generator.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'aspera/assert'
 require 'uri'
 
 module Aspera
@@ -11,11 +12,12 @@ module Aspera
     class << self
       def from_list(object_id)
         if object_id.is_a?(Array)
+          # compact: remove nils
           object_id = object_id.compact.map do |i|
             i.is_a?(String) && i.start_with?('https://') ? URI.parse(i).host : i.to_s
           end.join(ID_SEPARATOR)
         end
-        raise 'id must be a String' unless object_id.is_a?(String)
+        assert_type(object_id, String)
         return object_id
             .gsub(WINDOWS_PROTECTED_CHAR, PROTECTED_CHAR_REPLACE) # remove windows forbidden chars
             .gsub('.', PROTECTED_CHAR_REPLACE)  # keep dot for extension only (nicer)

data/lib/aspera/json_rpc.rb

@@ -3,6 +3,7 @@
 # cspell:ignore blankslate
 
 require 'aspera/rest_error_analyzer'
+require 'aspera/assert'
 require 'blankslate'
 
 Aspera::RestErrorAnalyzer.instance.add_simple_handler(name: 'JSON RPC', path: %w[error message], always: true)
@@ -34,15 +35,16 @@ module Aspera
         params:  args,
         id:      @request_id += 1
       })[:data]
-      raise 'response shall be Hash' unless data.is_a?(Hash)
-      raise 'bad version in response' unless data['jsonrpc'] == JSON_RPC_VERSION
-      raise 'missing id in response' unless data.key?('id')
-      raise 'both error and response' if data.key?('error') && data.key?('result')
-      raise 'bad error response' unless
+      assert_type(data, Hash){'response'}
+      assert(data['jsonrpc'] == JSON_RPC_VERSION){'bad version in response'}
+      assert(data.key?('id')){'missing id in response'}
+      assert(!(data.key?('error') && data.key?('result'))){'both error and response'}
+      assert(
         !data.key?('error') ||
-          data['error'].is_a?(Hash) &&
-            data['error']['code'].is_a?(Integer) &&
-            data['error']['message'].is_a?(String)
+        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

data/lib/aspera/keychain/encrypted_hash.rb

@@ -2,6 +2,8 @@
 
 require 'aspera/hash_ext'
 require 'aspera/environment'
+require 'aspera/log'
+require 'aspera/assert'
 require 'symmetric_encryption/core'
 require 'yaml'
 
@@ -9,33 +11,66 @@ module Aspera
   module Keychain
     # Manage secrets in a simple Hash
     class EncryptedHash
-      CIPHER_NAME = 'aes-256-cbc'
+      LEGACY_CIPHER_NAME = 'aes-256-cbc'
+      DEFAULT_CIPHER_NAME = 'aes-256-cbc'
+      FILE_TYPE = 'encrypted_hash_vault'
       CONTENT_KEYS = %i[label username password url description].freeze
+      FILE_KEYS = %w[version type cipher data].sort.freeze
       def initialize(path, current_password)
+        assert_type(path, String){'path to vault file'}
         @path = path
+        @all_secrets = {}
+        vault_encrypted_data = nil
+        if File.exist?(@path)
+          vault_file = File.read(@path)
+          if vault_file.start_with?('---')
+            vault_info = YAML.parse(vault_file).to_ruby
+            assert(vault_info.keys.sort == FILE_KEYS){'Invalid vault file'}
+            @cipher_name = vault_info['cipher']
+            vault_encrypted_data = vault_info['data']
+          else
+            # legacy vault file
+            @cipher_name = LEGACY_CIPHER_NAME
+            vault_encrypted_data = File.read(@path, mode: 'rb')
+          end
+        end
+        # setting password also creates the cipher
         self.password = current_password
-        raise 'path to vault file shall be String' unless @path.is_a?(String)
-        @all_secrets = File.exist?(@path) ? YAML.load_stream(@cipher.decrypt(File.read(@path))).first : {}
+        if !vault_encrypted_data.nil?
+          @all_secrets = YAML.load_stream(@cipher.decrypt(vault_encrypted_data)).first
+        end
       end
 
+      # set the password and cipher
       def password=(new_password)
         # number of bits in second position
-        key_bytes = CIPHER_NAME.split('-')[1].to_i / Environment::BITS_PER_BYTE
+        key_bytes = DEFAULT_CIPHER_NAME.split('-')[1].to_i / Environment::BITS_PER_BYTE
         # derive key from passphrase, add trailing zeros
         key = "#{new_password}#{"\x0" * key_bytes}"[0..(key_bytes - 1)]
-        Log.log.debug{"key=[#{key}],#{key.length}"}
-        SymmetricEncryption.cipher = @cipher = SymmetricEncryption::Cipher.new(cipher_name: CIPHER_NAME, key: key, encoding: :none)
+        Log.log.trace1{"secret=[#{key}],#{key.length}"}
+        @cipher = SymmetricEncryption.cipher = SymmetricEncryption::Cipher.new(cipher_name: DEFAULT_CIPHER_NAME, key: key, encoding: :none)
       end
 
+      # save current data to file with format
       def save
-        File.write(@path, @cipher.encrypt(YAML.dump(@all_secrets)), encoding: 'BINARY')
+        vault_info = {
+          'version' => '1.0.0',
+          'type'    => FILE_TYPE,
+          'cipher'  => @cipher_name,
+          'data'    => @cipher.encrypt(YAML.dump(@all_secrets))
+        }
+        File.write(@path, YAML.dump(vault_info))
       end
 
+      # set a secret
+      # @param options [Hash] with keys :label, :username, :password, :url, :description
       def set(options)
-        raise 'options shall be Hash' unless options.is_a?(Hash)
+        assert_type(options, Hash){'options'}
         unsupported = options.keys - CONTENT_KEYS
-        options.each_value {|v| raise 'value must be String' unless v.is_a?(String)}
-        raise "unsupported options: #{unsupported}" unless unsupported.empty?
+        assert(unsupported.empty?){"unsupported options: #{unsupported}"}
+        options.each_pair do |k, v|
+          assert_type(v, String){k.to_s}
+        end
         label = options.delete(:label)
         raise "secret #{label} already exist, delete first" if @all_secrets.key?(label)
         @all_secrets[label] = options.symbolize_keys
@@ -59,7 +94,7 @@ module Aspera
       end
 
       def get(label:, exception: true)
-        raise "Label not found: #{label}" unless @all_secrets.key?(label) || !exception
+        assert(@all_secrets.key?(label)){"Label not found: #{label}"} if exception
         result = @all_secrets[label].clone
         result[:label] = label if result.is_a?(Hash)
         return result

data/lib/aspera/keychain/macos_security.rb

@@ -2,6 +2,8 @@
 
 # https://github.com/fastlane-community/security
 require 'aspera/cli/info'
+require 'aspera/log'
+require 'aspera/assert'
 
 # enhance the gem to support other key chains
 module Aspera
@@ -36,7 +38,7 @@ module Aspera
             url = options&.delete(:url)
             if !url.nil?
               uri = URI.parse(url)
-              raise 'only https' unless uri.scheme.eql?('https')
+              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
@@ -45,7 +47,7 @@ module Aspera
             end
             cmd = ['security', command]
             options&.each do |k, v|
-              raise "unknown option: #{k}" unless supported.key?(k)
+              assert(supported.key?(k)){"unknown option: #{k}"}
               next if v.nil?
               cmd.push("-#{supported[k]}")
               cmd.push(v.shellescape) unless v.empty?
@@ -70,7 +72,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])
+            assert_values(options[:domain], DOMAINS, exception_class: ArgumentError){'domain'} unless options[:domain].nil?
             key_chains(execute('list-key_chains', options, LIST_OPTIONS))
           end
 
@@ -89,11 +91,11 @@ 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)
+          assert_values(operation, %i[add find delete]){'operation'}
+          assert_values(pass_type, %i[generic internet]){'pass_type'}
+          assert_type(options, Hash)
           missing = (operation.eql?(:add) ? %i[account service password] : %i[label]) - options.keys
-          raise "missing options: #{missing}" unless missing.empty?
+          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: ')
@@ -127,18 +129,18 @@ module Aspera
       end
 
       def set(options)
-        raise 'options shall be Hash' unless options.is_a?(Hash)
+        assert_type(options, Hash){'options'}
         unsupported = options.keys - %i[label username password url description]
-        raise "unsupported options: #{unsupported}" unless unsupported.empty?
+        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)
+        assert_type(options, Hash){'options'}
         unsupported = options.keys - %i[label]
-        raise "unsupported options: #{unsupported}" unless unsupported.empty?
+        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 +155,9 @@ module Aspera
       end
 
       def delete(options)
-        raise 'options shall be Hash' unless options.is_a?(Hash)
+        assert_type(options, Hash){'options'}
         unsupported = options.keys - %i[label]
-        raise "unsupported options: #{unsupported}" unless unsupported.empty?
+        assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         raise 'delete not implemented, use macos keychain app'
       end
     end