aspera-cli 4.27.5 → 4.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (249) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +301 -4
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +139 -58
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +10 -7
  13. data/docs/README.md +2551 -772
  14. data/docs/test-mcp-with-ai.md +13 -11
  15. data/lib/aspera/agent/base.rb +23 -2
  16. data/lib/aspera/agent/connect.rb +16 -12
  17. data/lib/aspera/agent/desktop.rb +10 -7
  18. data/lib/aspera/agent/direct.rb +34 -22
  19. data/lib/aspera/agent/factory.rb +8 -4
  20. data/lib/aspera/agent/httpgw.rb +7 -5
  21. data/lib/aspera/agent/node.rb +15 -7
  22. data/lib/aspera/agent/transferd.rb +167 -43
  23. data/lib/aspera/api/alee.rb +4 -1
  24. data/lib/aspera/api/aoc.rb +14 -11
  25. data/lib/aspera/api/ats.rb +4 -2
  26. data/lib/aspera/api/cos_node.rb +8 -5
  27. data/lib/aspera/api/faspex.rb +16 -9
  28. data/lib/aspera/api/httpgw.rb +9 -6
  29. data/lib/aspera/api/node.rb +23 -19
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +84 -42
  32. data/lib/aspera/ascp/log.schema.yaml +1084 -0
  33. data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
  34. data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
  35. data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
  36. data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
  37. data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
  38. data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
  39. data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
  40. data/lib/aspera/ascp/log_analyzer.rb +354 -0
  41. data/lib/aspera/ascp/management.rb +102 -48
  42. data/lib/aspera/ascp/session_errors.rb +217 -0
  43. data/lib/aspera/assert.rb +4 -0
  44. data/lib/aspera/cli/ascp_actions.rb +16 -37
  45. data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
  46. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  47. data/lib/aspera/cli/bootstrapper.rb +37 -34
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +49 -4
  50. data/lib/aspera/cli/command_spec.rb +34 -4
  51. data/lib/aspera/cli/completion/ascli.bash +53 -5
  52. data/lib/aspera/cli/completion/ascli.fish +27 -8
  53. data/lib/aspera/cli/completion/ascli.ps1 +63 -0
  54. data/lib/aspera/cli/completion/ascli.zsh +36 -4
  55. data/lib/aspera/cli/completion_actions.rb +594 -0
  56. data/lib/aspera/cli/context.rb +9 -4
  57. data/lib/aspera/cli/deprecation.rb +5 -2
  58. data/lib/aspera/cli/error.rb +45 -0
  59. data/lib/aspera/cli/extended_value.rb +83 -24
  60. data/lib/aspera/cli/formatter.rb +142 -73
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -11
  63. data/lib/aspera/cli/http.rb +17 -13
  64. data/lib/aspera/cli/info.rb +17 -6
  65. data/lib/aspera/cli/mailer.rb +7 -4
  66. data/lib/aspera/cli/mcp/http_servlet.rb +155 -0
  67. data/lib/aspera/cli/mcp/secrets.rb +146 -0
  68. data/lib/aspera/cli/mcp/tool.rb +232 -0
  69. data/lib/aspera/cli/option_declarator.rb +10 -4
  70. data/lib/aspera/cli/option_registry.rb +6 -3
  71. data/lib/aspera/cli/option_types.rb +17 -2
  72. data/lib/aspera/cli/option_value.rb +72 -11
  73. data/lib/aspera/cli/options.schema.yaml +856 -81
  74. data/lib/aspera/cli/parser.rb +64 -31
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +250 -44
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +51 -25
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +207 -141
  81. data/lib/aspera/cli/plugins/console.rb +9 -4
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +22 -8
  84. data/lib/aspera/cli/plugins/faspex5.rb +37 -44
  85. data/lib/aspera/cli/plugins/faspio.rb +41 -8
  86. data/lib/aspera/cli/plugins/httpgw.rb +8 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +186 -121
  88. data/lib/aspera/cli/plugins/node.rb +41 -34
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +572 -59
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +66 -12
  93. data/lib/aspera/cli/plugins/shares.rb +288 -48
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +155 -33
  96. data/lib/aspera/cli/preset_manager.rb +72 -16
  97. data/lib/aspera/cli/prompt.rb +7 -2
  98. data/lib/aspera/cli/result.rb +28 -11
  99. data/lib/aspera/cli/runner.rb +193 -80
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +204 -0
  102. data/lib/aspera/cli/special_values.rb +4 -1
  103. data/lib/aspera/cli/sync_actions.rb +13 -10
  104. data/lib/aspera/cli/table_fitter.rb +119 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +32 -40
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +31 -19
  108. data/lib/aspera/cli/transfer_progress.rb +13 -45
  109. data/lib/aspera/cli/vault_actions.rb +45 -0
  110. data/lib/aspera/cli/vault_manager.rb +197 -50
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.html.erb +61 -0
  113. data/lib/aspera/cli/web_secret.rb +222 -0
  114. data/lib/aspera/cli/wizard.rb +58 -45
  115. data/lib/aspera/command_line_builder.rb +35 -5
  116. data/lib/aspera/command_line_converter.rb +4 -1
  117. data/lib/aspera/coverage.rb +103 -33
  118. data/lib/aspera/data_repository.rb +42 -25
  119. data/lib/aspera/dot_container.rb +4 -1
  120. data/lib/aspera/duration.rb +45 -0
  121. data/lib/aspera/environment.rb +106 -33
  122. data/lib/aspera/exec_spec.rb +9 -5
  123. data/lib/aspera/faspex_gw.rb +105 -35
  124. data/lib/aspera/faspex_postproc.rb +193 -47
  125. data/lib/aspera/formatter_interface.rb +4 -2
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +6 -3
  129. data/lib/aspera/json_rpc/client.rb +55 -35
  130. data/lib/aspera/json_rpc/version.rb +4 -0
  131. data/lib/aspera/line_logger.rb +4 -1
  132. data/lib/aspera/link_header.rb +4 -1
  133. data/lib/aspera/log.rb +20 -10
  134. data/lib/aspera/markdown.rb +155 -115
  135. data/lib/aspera/mime.rb +9 -0
  136. data/lib/aspera/nagios.rb +9 -5
  137. data/lib/aspera/node_emulator.rb +111 -112
  138. data/lib/aspera/oauth/client/base.rb +163 -0
  139. data/lib/aspera/oauth/{boot.rb → client/boot.rb} +8 -4
  140. data/lib/aspera/oauth/{factory.rb → client/factory.rb} +13 -3
  141. data/lib/aspera/oauth/{generic.rb → client/generic.rb} +5 -1
  142. data/lib/aspera/oauth/{json_credentials.rb → client/json_credentials.rb} +4 -1
  143. data/lib/aspera/oauth/{jwt.rb → client/jwt.rb} +6 -3
  144. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  145. data/lib/aspera/oauth/{url_json.rb → client/url_json.rb} +4 -1
  146. data/lib/aspera/oauth/client/web.rb +84 -0
  147. data/lib/aspera/oauth/server/authorize.html.erb +34 -0
  148. data/lib/aspera/oauth/server/pkce.rb +427 -0
  149. data/lib/aspera/orchestrator_workflow_checker.rb +679 -0
  150. data/lib/aspera/persistency_action_once.rb +5 -3
  151. data/lib/aspera/persistency_folder.rb +6 -3
  152. data/lib/aspera/preview/file_types.rb +6 -3
  153. data/lib/aspera/preview/generator.rb +9 -5
  154. data/lib/aspera/preview/options.schema.yaml +3 -3
  155. data/lib/aspera/preview/terminal.rb +11 -6
  156. data/lib/aspera/preview/utils.rb +6 -4
  157. data/lib/aspera/products/connect.rb +5 -2
  158. data/lib/aspera/products/desktop.rb +4 -1
  159. data/lib/aspera/products/other.rb +4 -2
  160. data/lib/aspera/products/transferd.rb +6 -2
  161. data/lib/aspera/products/transferd_service.rb +610 -0
  162. data/lib/aspera/proxy_auto_config.js +2 -2
  163. data/lib/aspera/proxy_auto_config.rb +5 -2
  164. data/lib/aspera/rainbow.rb +30 -1
  165. data/lib/aspera/rest/aspera_errors.rb +55 -60
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +42 -42
  168. data/lib/aspera/rest/error_analyzer.rb +14 -2
  169. data/lib/aspera/rest/list.rb +14 -10
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +13 -4
  172. data/lib/aspera/rest.rb +9 -7
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -11
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +4089 -0
  175. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml +1097 -0
  176. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  177. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  178. data/lib/aspera/schema/IBM_Aspera_Shares.yaml +819 -7
  179. data/lib/aspera/schema/async_tables.yaml +11 -10
  180. data/lib/aspera/schema/documentation.rb +56 -78
  181. data/lib/aspera/schema/reader.rb +46 -11
  182. data/lib/aspera/schema/registry.rb +45 -24
  183. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  184. data/lib/aspera/schema/validator.rb +4 -1
  185. data/lib/aspera/sealed_hash.rb +166 -0
  186. data/lib/aspera/secret/hider.rb +201 -0
  187. data/lib/aspera/secret/reference.rb +150 -0
  188. data/lib/aspera/secret/resolver.rb +212 -0
  189. data/lib/aspera/secret/store/base.rb +153 -0
  190. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  191. data/lib/aspera/secret/store/factory.rb +103 -0
  192. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  193. data/lib/aspera/secret/store/keeper.rb +141 -0
  194. data/lib/aspera/secret/store/macos_security.rb +284 -0
  195. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  196. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  197. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  198. data/lib/aspera/secret/store/secret_service.rb +125 -0
  199. data/lib/aspera/secret/strength.rb +119 -0
  200. data/lib/aspera/servlet_helpers.rb +114 -0
  201. data/lib/aspera/ssh.rb +10 -7
  202. data/lib/aspera/ssl.rb +5 -2
  203. data/lib/aspera/string_ext.rb +3 -0
  204. data/lib/aspera/sync/args.schema.yaml +6 -1
  205. data/lib/aspera/sync/conf.schema.yaml +25 -10
  206. data/lib/aspera/sync/database.rb +3 -0
  207. data/lib/aspera/sync/operations.rb +34 -12
  208. data/lib/aspera/temp_file_manager.rb +85 -22
  209. data/lib/aspera/timer_limiter.rb +3 -0
  210. data/lib/aspera/transfer/error.rb +4 -1
  211. data/lib/aspera/transfer/faux_file.rb +4 -1
  212. data/lib/aspera/transfer/parameters.rb +22 -14
  213. data/lib/aspera/transfer/result.rb +3 -0
  214. data/lib/aspera/transfer/resumer.rb +6 -4
  215. data/lib/aspera/transfer/spec.rb +45 -18
  216. data/lib/aspera/transfer/spec.schema.yaml +8 -5
  217. data/lib/aspera/transfer/units.rb +75 -0
  218. data/lib/aspera/uri_reader.rb +57 -7
  219. data/lib/aspera/web_auth/index.html.erb +20 -0
  220. data/lib/aspera/web_auth/paste.rb +109 -0
  221. data/lib/aspera/web_auth/receiver.rb +50 -0
  222. data/lib/aspera/web_auth/relay.rb +76 -0
  223. data/lib/aspera/web_auth/reply.html.erb +150 -0
  224. data/lib/aspera/web_auth/server.rb +59 -14
  225. data/lib/aspera/web_page.html.erb +262 -0
  226. data/lib/aspera/web_page.rb +66 -0
  227. data/lib/aspera/web_server_simple.rb +82 -13
  228. data/lib/aspera/yaml.rb +5 -1
  229. data/llms.txt +81 -0
  230. data/skills/ascli/SKILL.md +88 -0
  231. data.tar.gz.sig +0 -0
  232. metadata +116 -48
  233. metadata.gz.sig +0 -0
  234. data/lib/aspera/cli/mcp_tool.rb +0 -189
  235. data/lib/aspera/keychain/base.rb +0 -25
  236. data/lib/aspera/keychain/encrypted_hash.rb +0 -188
  237. data/lib/aspera/keychain/factory.rb +0 -59
  238. data/lib/aspera/keychain/hashicorp_vault.rb +0 -74
  239. data/lib/aspera/keychain/macos_security.rb +0 -171
  240. data/lib/aspera/keychain/one_password_api.rb +0 -86
  241. data/lib/aspera/keychain/one_password_base.rb +0 -34
  242. data/lib/aspera/keychain/one_password_cli.rb +0 -98
  243. data/lib/aspera/oauth/base.rb +0 -141
  244. data/lib/aspera/oauth/web.rb +0 -57
  245. data/lib/aspera/oauth.rb +0 -9
  246. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1.yaml +0 -1784
  247. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0.yaml +0 -249
  248. data/lib/aspera/secret_hider.rb +0 -117
  249. data/lib/aspera/web_auth/index.html +0 -147
@@ -0,0 +1,284 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ # https://github.com/fastlane-community/security
7
+ require_relative '../../cli/info'
8
+ require_relative '../../log'
9
+ require_relative '../../assert'
10
+ require_relative '../../environment'
11
+ require_relative 'base'
12
+
13
+ # enhance the gem to support other key chains
14
+ module Aspera
15
+ module Secret
16
+ module Store
17
+ module MacosSecurity
18
+ # keychain based on macOS keychain, using `security` command line
19
+ class Keychain
20
+ # https://www.unix.com/man-page/osx/1/security/
21
+ SECURITY_UTILITY = 'security'
22
+ DOMAINS = %i[user system common dynamic].freeze
23
+ LIST_OPTIONS = {
24
+ domain: :c
25
+ }.freeze
26
+ KEYCHAIN_OPTIONS = {
27
+ password: :p
28
+ }.freeze
29
+ ADD_PASS_OPTIONS = {
30
+ account: :a,
31
+ creator: :c,
32
+ type: :C,
33
+ domain: :d,
34
+ kind: :D,
35
+ value: :G,
36
+ comment: :j,
37
+ label: :l,
38
+ path: :p,
39
+ port: :P,
40
+ protocol: :r,
41
+ server: :s,
42
+ service: :s,
43
+ auth: :t,
44
+ password: :w,
45
+ getpass: :g
46
+ }.freeze
47
+ # Exit code of `security` when the item is not found
48
+ EXIT_ITEM_NOT_FOUND = 44
49
+ class << self
50
+ # Execute a `security` CLI command with given options
51
+ # @param command [String] The security sub-command
52
+ # @param options [Hash, nil] Command options
53
+ # @param supported [Hash, nil] Mapping of option keys to CLI flags
54
+ # @param last_opt [String, nil] Trailing argument (e.g. keychain path)
55
+ # @param exception [Boolean] Whether to raise on non-zero exit
56
+ # @return [Array(String, String, Process::Status)] stdout, stderr, status
57
+ def execute(command, options = nil, supported = nil, last_opt = nil, exception: true)
58
+ url = options&.delete(:url)
59
+ if !url.nil?
60
+ uri = URI.parse(url)
61
+ Aspera.assert(uri.scheme.eql?('https'), 'only https')
62
+ options[:protocol] = 'htps'
63
+ Aspera.assert(!uri.host.nil?, type: Error) { 'host required in URL' }
64
+ options[:server] = uri.host
65
+ options[:path] = uri.path unless ['', '/'].include?(uri.path)
66
+ options[:port] = uri.port unless uri.port.eql?(443) && !url.include?(':443/')
67
+ end
68
+ command_args = [SECURITY_UTILITY, command]
69
+ options&.each do |k, v|
70
+ Aspera.assert(supported.key?(k)) { "unknown option: #{k}" }
71
+ next if v.nil?
72
+ command_args.push("-#{supported[k]}")
73
+ # No shell is involved: value is passed as is
74
+ command_args.push(v.to_s) unless v.to_s.empty?
75
+ end
76
+ command_args.push(last_opt) unless last_opt.nil?
77
+ Environment.secure_execute(*command_args, mode: :capture, exception: exception)
78
+ end
79
+
80
+ # Parse output of list command into Keychain objects
81
+ # @param output [String] Raw CLI output
82
+ # @return [Array<Keychain>] List of keychain instances
83
+ def key_chains(output)
84
+ output.split("\n").collect { |line| new(line.strip.gsub(/^"|"$/, '')) }
85
+ end
86
+
87
+ # Get the macOS default keychain
88
+ # @return [Keychain] Default keychain instance
89
+ def default
90
+ key_chains(execute('default-keychain').first).first
91
+ end
92
+
93
+ # Get the macOS login keychain
94
+ # @return [Keychain] Login keychain instance
95
+ def login
96
+ key_chains(execute('login-keychain').first).first
97
+ end
98
+
99
+ # List keychains in the search list or domain
100
+ # @param options [Hash] Domain options
101
+ # @return [Array<Keychain>] List of keychains
102
+ def list(options = {})
103
+ Aspera.assert_values(options[:domain], DOMAINS, type: ParameterError) { 'domain' } unless options[:domain].nil?
104
+ key_chains(execute('list-keychains', options, LIST_OPTIONS).first)
105
+ end
106
+
107
+ # Find a keychain by its short name (without `.keychain-db` extension)
108
+ # @param name [String] Keychain name
109
+ # @return [Keychain, nil] Matching keychain or nil
110
+ def by_name(name)
111
+ list.find { |kc| kc.path.end_with?("/#{name}.keychain-db") }
112
+ end
113
+
114
+ # Create a new macOS keychain file
115
+ # @param path [String] File path for the new keychain
116
+ # @param password [String] Password for the new keychain
117
+ # @return [Keychain] Created keychain instance
118
+ def create(path, password:)
119
+ execute('create-keychain', {password: password}, KEYCHAIN_OPTIONS, path)
120
+ new(path)
121
+ end
122
+
123
+ # Set the keychain search list
124
+ # @param keychain_list [Array<Keychain>] Ordered list of keychains
125
+ # @return [Array(String, String, Process::Status)] Execution result
126
+ def search_list=(keychain_list)
127
+ Environment.secure_execute(SECURITY_UTILITY, 'list-keychains', '-s', *keychain_list.map(&:path), mode: :capture)
128
+ end
129
+ end
130
+ attr_reader :path
131
+
132
+ # @param path [String] File path of the keychain
133
+ def initialize(path)
134
+ @path = path
135
+ end
136
+
137
+ # Decode a hexadecimal encoded string into UTF-8
138
+ # @param string [String] Hex string
139
+ # @return [String] Decoded string
140
+ def decode_hex_blob(string)
141
+ [string].pack('H*').force_encoding('UTF-8')
142
+ end
143
+
144
+ # Perform generic or internet password operation (add, find, delete)
145
+ # @param operation [Symbol] :add, :find, or :delete
146
+ # @param pass_type [Symbol] :generic or :internet
147
+ # @param options [Hash] Operation options (account, service, password, label, etc.)
148
+ # @return [Hash, nil] Parsed attributes for :find, or nil
149
+ def password(operation, pass_type, options)
150
+ Aspera.assert_values(operation, %i[add find delete]) { 'operation' }
151
+ Aspera.assert_values(pass_type, %i[generic internet]) { 'pass_type' }
152
+ Aspera.assert_type(options, Hash)
153
+ missing = (operation.eql?(:add) ? %i[account service password] : %i[label]) - options.keys
154
+ Aspera.assert(missing.empty?) { "missing options: #{missing}" }
155
+ options[:getpass] = '' if operation.eql?(:find)
156
+ stdout, stderr, status = self.class.execute("#{operation}-#{pass_type}-password", options, ADD_PASS_OPTIONS, @path, exception: false)
157
+ unless status.success?
158
+ return if operation.eql?(:find) && status.exitstatus.eql?(EXIT_ITEM_NOT_FOUND)
159
+ raise Error, stderr.strip.gsub(/^.*: /, '')
160
+ end
161
+ return unless operation.eql?(:find)
162
+ attributes = {}
163
+ # Attributes are on stdout, password (option -g) is on stderr
164
+ "#{stdout}\n#{stderr}".split("\n").each do |line|
165
+ case line
166
+ when /^keychain: "(.+)"/
167
+ # ignore
168
+ when /0x00000007 .+="(.+)"/
169
+ attributes['label'] = Regexp.last_match(1)
170
+ when /"(\w{4})".+="(.+)"/
171
+ attributes[Regexp.last_match(1)] = Regexp.last_match(2)
172
+ when /"(\w{4})"<blob>=0x([[:xdigit:]]+)/
173
+ attributes[Regexp.last_match(1)] = decode_hex_blob(Regexp.last_match(2))
174
+ when /^password: "(.+)"/
175
+ attributes['password'] = Regexp.last_match(1)
176
+ when /^password: 0x([[:xdigit:]]+)/
177
+ attributes['password'] = decode_hex_blob(Regexp.last_match(1))
178
+ end
179
+ end
180
+ return attributes
181
+ end
182
+
183
+ # Unlock this keychain with its password
184
+ # @param password [String] Password of the keychain
185
+ # @return [Array(String, String, Process::Status)] Execution result
186
+ def unlock(password:)
187
+ self.class.execute('unlock-keychain', {password: password}, KEYCHAIN_OPTIONS, @path)
188
+ end
189
+
190
+ # Lock this keychain
191
+ # @return [Array(String, String, Process::Status)] Execution result
192
+ def lock
193
+ self.class.execute('lock-keychain', nil, nil, @path)
194
+ end
195
+
196
+ # Delete this keychain file from disk
197
+ # @return [Array(String, String, Process::Status)] Execution result
198
+ def delete
199
+ self.class.execute('delete-keychain', nil, nil, @path)
200
+ end
201
+
202
+ # Configure settings for this keychain (lock timeout, lock on sleep)
203
+ # @param timeout [Integer, nil] Inactivity timeout in seconds
204
+ # @param lock_on_sleep [Boolean] Whether to lock when system sleeps
205
+ # @return [Array(String, String, Process::Status)] Execution result
206
+ def set_settings(timeout: nil, lock_on_sleep: false)
207
+ args = [SECURITY_UTILITY, 'set-keychain-settings']
208
+ args.push('-l') if lock_on_sleep
209
+ args.push('-u', '-t', timeout.to_s) if timeout
210
+ args.push(@path)
211
+ Environment.secure_execute(*args, mode: :capture)
212
+ end
213
+ end
214
+ end
215
+
216
+ # Vault backend implementation wrapping macOS system keychain
217
+ class MacosSystem < Base
218
+ # Account is mandatory in keychain: used when no username is provided
219
+ NO_ACCOUNT = 'none'
220
+ private_constant :NO_ACCOUNT
221
+ PARAMETERS = %i[name].freeze
222
+
223
+ # @param name [String, nil] Specific keychain name, or nil for default
224
+ def initialize(name: nil)
225
+ super()
226
+ raise Error, 'type system: only on macOS' unless Environment.instance.os.eql?(Environment::OS_MACOS)
227
+ @keychain_name = name.nil? ? 'default keychain' : name
228
+ @keychain = name.nil? ? MacosSecurity::Keychain.default : MacosSecurity::Keychain.by_name(name)
229
+ Aspera.assert(!@keychain.nil?) { "no such keychain #{name}" }
230
+ end
231
+
232
+ # @return [Hash] Vault information metadata
233
+ def info
234
+ return {
235
+ keychain: @keychain_name
236
+ }
237
+ end
238
+
239
+ # Overview of all secrets (not supported on macOS due to OS restrictions)
240
+ # @raise [Error] Always raised
241
+ def all
242
+ # the only way to list is `dump-keychain` which triggers security alert
243
+ raise Error, 'overview not implemented, use macos keychain app'
244
+ end
245
+
246
+ # Store a secret in the keychain
247
+ # @param options [Hash] Secret attributes (label, password, username, description)
248
+ # @return [Hash, nil] Result
249
+ def set(options)
250
+ validate_set(options)
251
+ @keychain.password(
252
+ :add, :generic, service: options[:label],
253
+ account: options[:username] || NO_ACCOUNT, password: options[:password], comment: options[:description]
254
+ )
255
+ end
256
+
257
+ # Retrieve a secret by label
258
+ # @param label [String] Secret label identifier
259
+ # @param exception [Boolean] Whether to raise if not found
260
+ # @return [Hash, nil] Secret attributes or nil
261
+ def get(label:, exception: true)
262
+ info = @keychain.password(:find, :generic, label: label)
263
+ if info.nil?
264
+ raise "Secret '#{label}' not found" if exception
265
+ return
266
+ end
267
+ return {
268
+ label: label,
269
+ username: (info['acct'] unless info['acct'].eql?(NO_ACCOUNT)),
270
+ password: info['password'],
271
+ description: info['icmt']
272
+ }.compact
273
+ end
274
+
275
+ # Delete a secret by label
276
+ # @param label [String] Secret label identifier
277
+ # @return [Hash, nil] Result
278
+ def delete(label:)
279
+ @keychain.password(:delete, :generic, label: label)
280
+ end
281
+ end
282
+ end
283
+ end
284
+ end
@@ -0,0 +1,99 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../../rest'
7
+ require_relative 'base'
8
+ require_relative 'one_password_base'
9
+
10
+ module Aspera
11
+ module Secret
12
+ module Store
13
+ # Manage secrets using the 1Password Connect REST API
14
+ # https://developer.1password.com/docs/connect/connect-api-reference/
15
+ class OnePasswordApi < Base
16
+ include OnePasswordBase
17
+
18
+ PARAMETERS = %i[url token vault_id].freeze
19
+
20
+ # @param url [String] Base URL of the 1Password Connect server (e.g. http://localhost:8080)
21
+ # @param token [String] Bearer token (Connect token or service-account token)
22
+ # @param vault_id [String] ID of the 1Password vault to operate on
23
+ def initialize(url:, token:, vault_id:)
24
+ super()
25
+ @vault_id = vault_id
26
+ @api = Rest::Client.new(
27
+ base_url: url,
28
+ headers: {'Authorization' => "Bearer #{token}"}
29
+ )
30
+ end
31
+
32
+ def info
33
+ {
34
+ url: @api.base_url,
35
+ vault_id: @vault_id
36
+ }
37
+ end
38
+
39
+ def all
40
+ items = @api.read("v1/vaults/#{@vault_id}/items")
41
+ return items.map do |item|
42
+ item_to_secret(@api.read("v1/vaults/#{@vault_id}/items/#{item['id']}")).merge(id: item['id'])
43
+ end
44
+ end
45
+
46
+ def ids
47
+ @api.read("v1/vaults/#{@vault_id}/items").map { |item| {id: item['id'], label: item['title']} }
48
+ end
49
+
50
+ def set(options)
51
+ validate_set(options)
52
+ Aspera.assert(resolve_id(options[:label], exception: false).nil?) { "secret #{options[:label]} already exist, delete first" }
53
+ @api.create("v1/vaults/#{@vault_id}/items", build_item(options))
54
+ nil
55
+ end
56
+
57
+ def get(label:, id: nil, exception: true)
58
+ iid = id || resolve_id(label, exception: exception)
59
+ return if iid.nil?
60
+ return item_to_secret(@api.read("v1/vaults/#{@vault_id}/items/#{iid}")).merge(id: iid)
61
+ end
62
+
63
+ def delete(label:, id: nil)
64
+ iid = id || resolve_id(label, exception: true)
65
+ @api.delete("v1/vaults/#{@vault_id}/items/#{iid}")
66
+ nil
67
+ end
68
+
69
+ private
70
+
71
+ # Resolve an item id from its title, or else from its id; raises if ambiguous or missing
72
+ def resolve_id(label, exception: true)
73
+ items = @api.read("v1/vaults/#{@vault_id}/items", {filter: "title eq \"#{label}\""})
74
+ raise "Multiple secrets found with label '#{label}': use id to disambiguate" if items.length > 1
75
+ # No title matches: the identifier may be an item id
76
+ items = @api.read("v1/vaults/#{@vault_id}/items").select { |item| item['id'] == label } if items.empty?
77
+ raise "Secret '#{label}' not found" if items.empty? && exception
78
+ items.first&.fetch('id')
79
+ end
80
+
81
+ def build_item(options)
82
+ fields = []
83
+ fields << {'id' => FIELD_USERNAME, 'type' => 'STRING', 'value' => options[:username]} if options[:username]
84
+ fields << {'id' => FIELD_PASSWORD, 'type' => 'CONCEALED', 'value' => options[:password]} if options[:password]
85
+ fields << {'id' => FIELD_NOTES_ID, 'type' => 'STRING', 'value' => options[:description]} if options[:description]
86
+ item = {
87
+ 'title' => options[:label],
88
+ 'category' => ITEM_CATEGORY.upcase,
89
+ 'vault' => {'id' => @vault_id},
90
+ 'fields' => fields
91
+ }
92
+ # Website of the item
93
+ item['urls'] = [{'href' => options[:url], 'primary' => true}] if options[:url]
94
+ item
95
+ end
96
+ end
97
+ end
98
+ end
99
+ end
@@ -0,0 +1,42 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ module Aspera
7
+ module Secret
8
+ module Store
9
+ # Shared field constants and item_to_secret conversion for 1Password backends.
10
+ # Both the REST (Connect) and CLI (`op`) backends use the same JSON item schema.
11
+ module OnePasswordBase
12
+ FIELD_USERNAME = 'username'
13
+ FIELD_PASSWORD = 'password'
14
+ FIELD_URL = 'url'
15
+ FIELD_NOTES_ID = 'notesPlain'
16
+ ITEM_CATEGORY = 'Login'
17
+
18
+ private_constant :FIELD_USERNAME, :FIELD_PASSWORD, :FIELD_URL, :FIELD_NOTES_ID, :ITEM_CATEGORY
19
+
20
+ private
21
+
22
+ # Convert a 1Password item JSON object to a vault secret Hash.
23
+ # Same JSON schema for API Connect and CLI items.
24
+ # Built-in fields are found by `id`, custom fields (generated `id`) by `label`.
25
+ # URL is the website of the item, or a custom field `url` (created by previous versions).
26
+ def item_to_secret(item)
27
+ fields = Array(item['fields'])
28
+ by_id = fields.to_h { |f| [f['id'], f['value']] }
29
+ by_label = fields.to_h { |f| [f['label'], f['value']] }
30
+ urls = Array(item['urls'])
31
+ values = {
32
+ username: by_id[FIELD_USERNAME] || by_label[FIELD_USERNAME],
33
+ password: by_id[FIELD_PASSWORD] || by_label[FIELD_PASSWORD],
34
+ url: (urls.find { |u| u['primary'] } || urls.first)&.[]('href') || by_id[FIELD_URL] || by_label[FIELD_URL],
35
+ description: by_id[FIELD_NOTES_ID] || by_label[FIELD_NOTES_ID]
36
+ }
37
+ return {label: item['title']}.merge(values.compact)
38
+ end
39
+ end
40
+ end
41
+ end
42
+ end
@@ -0,0 +1,110 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../../environment'
7
+ require_relative 'base'
8
+ require_relative 'one_password_base'
9
+ require 'json'
10
+
11
+ module Aspera
12
+ module Secret
13
+ module Store
14
+ # Manage secrets using the 1Password CLI (`op`)
15
+ # https://developer.1password.com/docs/cli/
16
+ class OnePasswordCli < Base
17
+ include OnePasswordBase
18
+
19
+ OP_EXECUTABLE = 'op'
20
+ private_constant :OP_EXECUTABLE
21
+ PARAMETERS = %i[vault account].freeze
22
+
23
+ # @param vault [String, nil] Name or ID of the 1Password vault (optional, uses default vault if omitted)
24
+ # @param account [String, nil] Account shorthand for `op` (optional, uses default account if omitted)
25
+ def initialize(vault: nil, account: nil)
26
+ super()
27
+ @vault = vault
28
+ @account = account
29
+ end
30
+
31
+ def info
32
+ h = {}
33
+ h[:vault] = @vault unless @vault.nil?
34
+ h[:account] = @account unless @account.nil?
35
+ h
36
+ end
37
+
38
+ def all
39
+ items = op_json('item', 'list', '--categories', ITEM_CATEGORY)
40
+ return items.map do |item|
41
+ item_to_secret(op_json('item', 'get', item['id'])).merge(id: item['id'])
42
+ end
43
+ end
44
+
45
+ def ids
46
+ op_json('item', 'list', '--categories', ITEM_CATEGORY).map { |item| {id: item['id'], label: item['title']} }
47
+ end
48
+
49
+ def set(options)
50
+ validate_set(options)
51
+ assert_new_label(options[:label])
52
+ args = ['item', 'create', '--category', ITEM_CATEGORY, "--title=#{options[:label]}"]
53
+ args << "--url=#{options[:url]}" if options[:url]
54
+ args << "#{FIELD_USERNAME}=#{options[:username]}" if options[:username]
55
+ args << "#{FIELD_PASSWORD}[password]=#{options[:password]}" if options[:password]
56
+ args << "#{FIELD_NOTES_ID}=#{options[:description]}" if options[:description]
57
+ op_run(*args)
58
+ nil
59
+ end
60
+
61
+ def get(label:, id: nil, exception: true)
62
+ identifier = id || label
63
+ stdout, stderr, status = op_capture('item', 'get', identifier, '--format=json', exception: false)
64
+ if !status.success?
65
+ raise "Multiple secrets found with label '#{label}': use id to disambiguate, or option vault to restrict" if stderr.to_s.match?(/more than one item/i)
66
+ # Other failures (e.g. not signed in) must not be reported as a missing secret
67
+ # `op` prefixes its messages with `[ERROR] <date> <time>`
68
+ raise "1Password CLI failed for '#{label}': #{stderr.to_s.sub(%r{\A\[ERROR\]\s+\d{4}/\d\d/\d\d\s+[\d:]+\s+}, '').strip}" unless stderr.to_s.match?(/isn't an item|not found/i)
69
+ raise "Secret '#{label}' not found" if exception
70
+ return
71
+ end
72
+ full = JSON.parse(stdout)
73
+ return item_to_secret(full).merge(id: full['id'])
74
+ end
75
+
76
+ def delete(label:, id: nil)
77
+ op_run('item', 'delete', id || label)
78
+ nil
79
+ end
80
+
81
+ private
82
+
83
+ def common_flags
84
+ flags = []
85
+ flags.push('--vault', @vault) unless @vault.nil?
86
+ flags.push('--account', @account) unless @account.nil?
87
+ flags
88
+ end
89
+
90
+ def op_json(*args)
91
+ stdout, = op_capture(*args, '--format=json', exception: true)
92
+ JSON.parse(stdout)
93
+ end
94
+
95
+ def op_run(*args)
96
+ op_capture(*args, exception: true)
97
+ nil
98
+ end
99
+
100
+ def op_capture(*args, exception: true)
101
+ Environment.instance.class.secure_execute(
102
+ OP_EXECUTABLE, *args, *common_flags,
103
+ mode: :capture,
104
+ exception: exception
105
+ )
106
+ end
107
+ end
108
+ end
109
+ end
110
+ end
@@ -0,0 +1,125 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../../environment'
7
+ require_relative 'base'
8
+
9
+ module Aspera
10
+ module Secret
11
+ module Store
12
+ # Manage secrets using the Linux Secret Service (GNOME Keyring, KWallet, KeePassXC...), with the `secret-tool` CLI of `libsecret`.
13
+ # https://specifications.freedesktop.org/secret-service/latest/
14
+ # Items have attributes: `service` (parameter `name`), `label`, and optionally `username`, `url`, `description`.
15
+ class SecretService < Base
16
+ SECRET_TOOL = 'secret-tool'
17
+ # Attribute that groups the secrets of one store
18
+ ATTR_SERVICE = 'service'
19
+ # Attributes of a secret, other than the password
20
+ ATTRIBUTES = %i[label username url description].freeze
21
+ # `secret-tool search` writes the label of each item on stdout, and its attributes on stderr
22
+ LABEL_REGEX = /^label = (.*)$/
23
+ ATTRIBUTE_REGEX = /^attribute\.(\w+) = (.*)$/
24
+ private_constant :SECRET_TOOL, :ATTR_SERVICE, :ATTRIBUTES, :LABEL_REGEX, :ATTRIBUTE_REGEX
25
+ PARAMETERS = %i[name].freeze
26
+
27
+ # @param name [String] Name of the group of secrets in the Secret Service (attribute `service`)
28
+ def initialize(name: 'ascli')
29
+ super()
30
+ raise Error, 'type secret_service: only on Linux' unless Environment.instance.os.eql?(Environment::OS_LINUX)
31
+ @name = name
32
+ end
33
+
34
+ def info
35
+ {service: @name}
36
+ end
37
+
38
+ def all
39
+ labels.map { |label| get(label: label) }
40
+ end
41
+
42
+ def ids
43
+ labels.map { |label| {label: label} }
44
+ end
45
+
46
+ # Store a new secret
47
+ # @param options [Hash] `label`, `password`, `username`, `url`, `description`
48
+ def set(options)
49
+ validate_set(options)
50
+ Aspera.assert(options.key?(:password), 'password is required')
51
+ assert_new_label(options[:label])
52
+ attributes = [ATTR_SERVICE, @name]
53
+ ATTRIBUTES.each do |key|
54
+ attributes.push(key.to_s, options[key]) if options.key?(key)
55
+ end
56
+ # the password is read from stdin: not visible in process list
57
+ _, stderr, status = secret_tool('store', "--label=#{options[:label]}", *attributes, stdin_data: options[:password])
58
+ raise Error, stderr.strip unless status.success?
59
+ nil
60
+ end
61
+
62
+ # @param label [String] Label of the secret
63
+ # @param exception [Boolean] Raise if not found
64
+ # @return [Hash, nil] Secret, `nil` if not found and `exception` is `false`
65
+ def get(label:, exception: true)
66
+ stdout, stderr, status = secret_tool('lookup', ATTR_SERVICE, @name, 'label', label)
67
+ if !status.success?
68
+ # no error message when the item does not exist
69
+ raise Error, stderr.strip unless stderr.strip.empty?
70
+ raise "Secret '#{label}' not found" if exception
71
+ return
72
+ end
73
+ attributes = search(label).last
74
+ return {
75
+ label: label,
76
+ username: attributes['username'],
77
+ password: stdout.dup.force_encoding('UTF-8'),
78
+ url: attributes['url'],
79
+ description: attributes['description']
80
+ }.compact
81
+ end
82
+
83
+ # @param label [String] Label of the secret
84
+ def delete(label:)
85
+ raise "Secret '#{label}' not found" if get(label: label, exception: false).nil?
86
+ _, stderr, status = secret_tool('clear', ATTR_SERVICE, @name, 'label', label)
87
+ raise Error, stderr.strip unless status.success?
88
+ nil
89
+ end
90
+
91
+ private
92
+
93
+ # @param args [Array<String>] Arguments of `secret-tool`
94
+ # @param stdin_data [String, nil] Data sent to stdin
95
+ # @return [Array(String, String, Process::Status)] stdout, stderr, status
96
+ def secret_tool(*args, stdin_data: nil)
97
+ kwargs = {mode: :capture, exception: false}
98
+ kwargs[:stdin_data] = stdin_data unless stdin_data.nil?
99
+ Environment.secure_execute(SECRET_TOOL, *args, **kwargs)
100
+ rescue Errno::ENOENT
101
+ raise Error, "#{SECRET_TOOL} not found: install libsecret tools (e.g. libsecret-tools)"
102
+ end
103
+
104
+ # @return [Array<String>] Labels of all secrets of the store
105
+ def labels
106
+ search.first
107
+ end
108
+
109
+ # @param label [String, nil] Label of the secret, `nil` for all secrets of the store
110
+ # @return [Array(Array<String>, Hash<String,String>)] Labels of found secrets, and attributes
111
+ # (those of all found secrets, so they belong to the secret only when `label` is given)
112
+ def search(label = nil)
113
+ filter = [ATTR_SERVICE, @name]
114
+ filter.push('label', label) unless label.nil?
115
+ stdout, stderr, status = secret_tool('search', '--all', '--unlock', *filter)
116
+ # no output and no error message when there is no item
117
+ raise Error, stderr.strip if !status.success? && !stderr.strip.empty?
118
+ labels = stdout.dup.force_encoding('UTF-8').scan(LABEL_REGEX).flatten
119
+ attributes = stderr.dup.force_encoding('UTF-8').scan(ATTRIBUTE_REGEX).to_h
120
+ [labels, attributes]
121
+ end
122
+ end
123
+ end
124
+ end
125
+ end