aspera-cli 4.28.0 → 4.29.1

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 (242) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +217 -2
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +135 -56
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +122 -26
  10. data/SECURITY.md +84 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1895 -632
  14. data/docs/test-mcp-with-ai.md +8 -8
  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 +20 -19
  19. data/lib/aspera/agent/factory.rb +6 -3
  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 +7 -4
  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 +29 -22
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +95 -67
  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 +370 -0
  41. data/lib/aspera/ascp/log_locations.rb +163 -0
  42. data/lib/aspera/ascp/management.rb +16 -8
  43. data/lib/aspera/ascp/session_errors.rb +217 -0
  44. data/lib/aspera/assert.rb +4 -0
  45. data/lib/aspera/cli/ascp_actions.rb +12 -19
  46. data/lib/aspera/cli/ascp_logs_actions.rb +188 -0
  47. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  48. data/lib/aspera/cli/bootstrapper.rb +38 -33
  49. data/lib/aspera/cli/command_line.rb +63 -8
  50. data/lib/aspera/cli/command_registry.rb +9 -1
  51. data/lib/aspera/cli/command_spec.rb +47 -7
  52. data/lib/aspera/cli/completion/ascli.bash +19 -5
  53. data/lib/aspera/cli/completion/ascli.fish +13 -2
  54. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  55. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  56. data/lib/aspera/cli/completion_actions.rb +303 -69
  57. data/lib/aspera/cli/context.rb +9 -4
  58. data/lib/aspera/cli/deprecation.rb +5 -2
  59. data/lib/aspera/cli/error.rb +6 -0
  60. data/lib/aspera/cli/extended_value.rb +66 -31
  61. data/lib/aspera/cli/formatter.rb +43 -30
  62. data/lib/aspera/cli/gem_checker.rb +9 -6
  63. data/lib/aspera/cli/hints.rb +22 -10
  64. data/lib/aspera/cli/http.rb +38 -10
  65. data/lib/aspera/cli/info.rb +12 -7
  66. data/lib/aspera/cli/mailer.rb +6 -3
  67. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  68. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  69. data/lib/aspera/cli/mcp/tool.rb +20 -17
  70. data/lib/aspera/cli/option_declarator.rb +10 -4
  71. data/lib/aspera/cli/option_registry.rb +6 -3
  72. data/lib/aspera/cli/option_types.rb +17 -2
  73. data/lib/aspera/cli/option_value.rb +77 -18
  74. data/lib/aspera/cli/options.schema.yaml +641 -80
  75. data/lib/aspera/cli/parser.rb +71 -35
  76. data/lib/aspera/cli/plugins/alee.rb +7 -4
  77. data/lib/aspera/cli/plugins/aoc.rb +248 -37
  78. data/lib/aspera/cli/plugins/ats.rb +10 -9
  79. data/lib/aspera/cli/plugins/base.rb +50 -18
  80. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  81. data/lib/aspera/cli/plugins/config.rb +210 -104
  82. data/lib/aspera/cli/plugins/console.rb +6 -3
  83. data/lib/aspera/cli/plugins/cos.rb +8 -4
  84. data/lib/aspera/cli/plugins/factory.rb +21 -7
  85. data/lib/aspera/cli/plugins/faspex5.rb +31 -26
  86. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  87. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  88. data/lib/aspera/cli/plugins/mcp.rb +42 -22
  89. data/lib/aspera/cli/plugins/node.rb +39 -38
  90. data/lib/aspera/cli/plugins/oauth.rb +23 -6
  91. data/lib/aspera/cli/plugins/orchestrator.rb +287 -83
  92. data/lib/aspera/cli/plugins/preview.rb +72 -45
  93. data/lib/aspera/cli/plugins/server.rb +66 -14
  94. data/lib/aspera/cli/plugins/shares.rb +87 -18
  95. data/lib/aspera/cli/plugins/transferd.rb +228 -0
  96. data/lib/aspera/cli/poll.rb +236 -0
  97. data/lib/aspera/cli/preset_actions.rb +144 -30
  98. data/lib/aspera/cli/preset_manager.rb +113 -35
  99. data/lib/aspera/cli/prompt.rb +157 -9
  100. data/lib/aspera/cli/result.rb +12 -8
  101. data/lib/aspera/cli/runner.rb +89 -48
  102. data/lib/aspera/cli/secret_finder.rb +4 -1
  103. data/lib/aspera/cli/security.rb +89 -9
  104. data/lib/aspera/cli/special_values.rb +4 -1
  105. data/lib/aspera/cli/sync_actions.rb +15 -10
  106. data/lib/aspera/cli/table_fitter.rb +3 -0
  107. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  108. data/lib/aspera/cli/transfer_actions.rb +11 -8
  109. data/lib/aspera/cli/transfer_agent.rb +43 -20
  110. data/lib/aspera/cli/transfer_progress.rb +14 -45
  111. data/lib/aspera/cli/vault_actions.rb +45 -0
  112. data/lib/aspera/cli/vault_manager.rb +188 -42
  113. data/lib/aspera/cli/version.rb +4 -1
  114. data/lib/aspera/cli/web_secret.rb +12 -10
  115. data/lib/aspera/cli/wizard.rb +42 -39
  116. data/lib/aspera/command_line_builder.rb +9 -5
  117. data/lib/aspera/command_line_converter.rb +4 -1
  118. data/lib/aspera/coverage.rb +103 -33
  119. data/lib/aspera/data_repository.rb +4 -1
  120. data/lib/aspera/dot_container.rb +4 -1
  121. data/lib/aspera/environment.rb +23 -12
  122. data/lib/aspera/exec_spec.rb +3 -0
  123. data/lib/aspera/faspex_gw.rb +13 -9
  124. data/lib/aspera/faspex_postproc.rb +15 -12
  125. data/lib/aspera/formatter_interface.rb +4 -1
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +20 -5
  129. data/lib/aspera/inflate.rb +43 -0
  130. data/lib/aspera/json_rpc/client.rb +6 -5
  131. data/lib/aspera/json_rpc/version.rb +3 -0
  132. data/lib/aspera/line_logger.rb +4 -1
  133. data/lib/aspera/link_header.rb +4 -1
  134. data/lib/aspera/log.rb +18 -5
  135. data/lib/aspera/markdown.rb +5 -2
  136. data/lib/aspera/mime.rb +3 -0
  137. data/lib/aspera/nagios.rb +6 -4
  138. data/lib/aspera/node_emulator.rb +15 -13
  139. data/lib/aspera/oauth/client/base.rb +124 -73
  140. data/lib/aspera/oauth/client/boot.rb +7 -4
  141. data/lib/aspera/oauth/client/factory.rb +41 -18
  142. data/lib/aspera/oauth/client/generic.rb +5 -1
  143. data/lib/aspera/oauth/client/json_credentials.rb +7 -3
  144. data/lib/aspera/oauth/client/jwt.rb +6 -3
  145. data/lib/aspera/oauth/client/shares_web.rb +94 -0
  146. data/lib/aspera/oauth/client/url_json.rb +7 -3
  147. data/lib/aspera/oauth/client/web.rb +40 -13
  148. data/lib/aspera/oauth/server/pkce.rb +6 -5
  149. data/lib/aspera/orchestrator_workflow_checker.rb +129 -2
  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 +16 -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 +17 -2
  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 +3 -0
  165. data/lib/aspera/rest/aspera_errors.rb +4 -1
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +45 -34
  168. data/lib/aspera/rest/error_analyzer.rb +5 -2
  169. data/lib/aspera/rest/list.rb +8 -4
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +8 -5
  172. data/lib/aspera/rest.rb +9 -6
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  175. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  176. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  177. data/lib/aspera/schema/async_tables.yaml +11 -10
  178. data/lib/aspera/schema/documentation.rb +8 -2
  179. data/lib/aspera/schema/reader.rb +7 -0
  180. data/lib/aspera/schema/registry.rb +44 -28
  181. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  182. data/lib/aspera/schema/validator.rb +4 -1
  183. data/lib/aspera/sealed_hash.rb +150 -0
  184. data/lib/aspera/secret/hider.rb +213 -0
  185. data/lib/aspera/secret/reference.rb +150 -0
  186. data/lib/aspera/secret/resolver.rb +212 -0
  187. data/lib/aspera/secret/store/base.rb +153 -0
  188. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  189. data/lib/aspera/secret/store/factory.rb +103 -0
  190. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  191. data/lib/aspera/secret/store/keeper.rb +141 -0
  192. data/lib/aspera/secret/store/macos_security.rb +284 -0
  193. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  194. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  195. data/lib/aspera/secret/store/one_password_cli.rb +112 -0
  196. data/lib/aspera/secret/store/secret_service.rb +125 -0
  197. data/lib/aspera/secret/strength.rb +119 -0
  198. data/lib/aspera/servlet_helpers.rb +5 -2
  199. data/lib/aspera/ssh.rb +10 -7
  200. data/lib/aspera/ssl.rb +5 -2
  201. data/lib/aspera/string_ext.rb +3 -0
  202. data/lib/aspera/sync/args.schema.yaml +3 -0
  203. data/lib/aspera/sync/conf.schema.yaml +9 -4
  204. data/lib/aspera/sync/database.rb +3 -0
  205. data/lib/aspera/sync/operations.rb +17 -15
  206. data/lib/aspera/temp_file_manager.rb +8 -4
  207. data/lib/aspera/timer_limiter.rb +3 -0
  208. data/lib/aspera/transfer/error.rb +4 -1
  209. data/lib/aspera/transfer/faux_file.rb +4 -1
  210. data/lib/aspera/transfer/parameters.rb +17 -14
  211. data/lib/aspera/transfer/result.rb +23 -0
  212. data/lib/aspera/transfer/resumer.rb +6 -4
  213. data/lib/aspera/transfer/spec.rb +9 -22
  214. data/lib/aspera/units/decimal.rb +67 -0
  215. data/lib/aspera/units/duration.rb +109 -0
  216. data/lib/aspera/uri_reader.rb +64 -9
  217. data/lib/aspera/web_auth/index.html.erb +6 -2
  218. data/lib/aspera/web_auth/paste.rb +109 -0
  219. data/lib/aspera/web_auth/receiver.rb +50 -0
  220. data/lib/aspera/web_auth/relay.rb +76 -0
  221. data/lib/aspera/web_auth/reply.html.erb +150 -0
  222. data/lib/aspera/web_auth/server.rb +47 -10
  223. data/lib/aspera/web_page.rb +7 -2
  224. data/lib/aspera/web_server_simple.rb +6 -3
  225. data/lib/aspera/yaml.rb +5 -1
  226. data/llms-install.md +88 -0
  227. data/llms.txt +87 -0
  228. data/skills/ascli/SKILL.md +94 -0
  229. data.tar.gz.sig +0 -0
  230. metadata +77 -20
  231. metadata.gz.sig +0 -0
  232. data/lib/aspera/duration.rb +0 -42
  233. data/lib/aspera/keychain/base.rb +0 -30
  234. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  235. data/lib/aspera/keychain/factory.rb +0 -58
  236. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  237. data/lib/aspera/keychain/macos_security.rb +0 -277
  238. data/lib/aspera/keychain/one_password_api.rb +0 -91
  239. data/lib/aspera/keychain/one_password_base.rb +0 -39
  240. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  241. data/lib/aspera/secret_hider.rb +0 -196
  242. data/lib/aspera/secret_strength.rb +0 -114
@@ -1,21 +1,22 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- # cspell:ignore ascli
4
-
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../../log'
7
+ require_relative '../../secret/hider'
8
+ require_relative '../runner'
9
+ require_relative '../error'
10
+ require_relative 'secrets'
11
+ require_relative '../../schema/reader'
12
+ require_relative '../../schema/registry'
13
+ require_relative '../plugins/mcp'
5
14
  require 'json'
6
- require 'aspera/log'
7
- require 'aspera/secret_hider'
8
- require 'aspera/cli/runner'
9
- require 'aspera/cli/error'
10
- require 'aspera/cli/mcp/secrets'
11
- require 'aspera/schema/reader'
12
- require 'aspera/schema/registry'
13
- require 'aspera/cli/plugins/mcp'
14
15
  unless defined?(MCP::Tool)
15
16
  begin
16
17
  require 'mcp'
17
- rescue LoadError
18
- raise Cli::Error, "The 'mcp' and 'rack' gems are required. Install them with: gem install mcp rack"
18
+ rescue LoadError => e
19
+ raise Aspera::Cli::Error, "The 'mcp' gem is required (and 'rack' for transport http). Install with: gem install mcp rack (#{e.message})"
19
20
  end
20
21
  end
21
22
 
@@ -50,7 +51,7 @@ module Aspera
50
51
  "@val:..." — literal string (no further decoding)
51
52
  "@secret:name" — secret entered by the user on a web page, never visible to you:
52
53
  use it for a secret the user did not give, e.g. "--password=@secret:password"
53
- Note: @stdin: is disabled; @ruby:, @file:, @uri:, @env: depend on the security level of the server.
54
+ Note: @stdin: is disabled; @ruby:, @file:, @uri:, @env:, @zlib: depend on the security level of the server.
54
55
  A secret (from @secret:, @vault:, @preset:) must be the whole value: no other prefix before it, not in @extend:.
55
56
 
56
57
  AUTOMATIC FLAGS
@@ -130,7 +131,7 @@ module Aspera
130
131
  secret_call.finish
131
132
  # Secret values (e.g. entered by the user, tokens) never reach the client, even if displayed by the command,
132
133
  # also short ones in a text (e.g. a short password in an error message)
133
- hider = SecretHider.instance
134
+ hider = Secret::Hider.instance
134
135
  return MCP::Tool::Response.new(
135
136
  hider.hidden_copy(response.content, short_in_text: true),
136
137
  structured_content: hider.hidden_copy(response.structured_content, short_in_text: true),
@@ -151,10 +152,12 @@ module Aspera
151
152
  Log.dump(:mcp_execute, effective_args)
152
153
  runner = Runner.new(effective_args)
153
154
  result = runner.run_with_result
155
+ # The command of a poll is executed when the result is displayed, on the command line only
156
+ raise Cli::BadArgument, 'Option poll: not available in MCP server mode, call the tool again instead' if result.is_a?(Result::Poll)
154
157
  # Secrets never reach the AI client, whatever the output format requested in args.
155
158
  # As on the command line, `--out.query` applies to the data of an object or list, after secrets are removed
156
159
  if result.is_a?(Result::SingleObject) || result.is_a?(Result::ObjectList) || result.is_a?(Result::ValueList)
157
- result = result.with_data(SecretHider.instance.hidden_copy(result.data))
160
+ result = result.with_data(Secret::Hider.instance.hidden_copy(result.data))
158
161
  result = runner.context.formatter.query_result(result)
159
162
  end
160
163
  case result
@@ -182,7 +185,7 @@ module Aspera
182
185
  end
183
186
  MCP::Tool::Response.new(content, structured_content: structured)
184
187
  else
185
- MCP::Tool::Response.new([{type: 'text', text: SecretHider.instance.hide_secrets_in_string(result.data.to_s, all: true)}])
188
+ MCP::Tool::Response.new([{type: 'text', text: Secret::Hider.instance.hide_secrets_in_string(result.data.to_s, all: true)}])
186
189
  end
187
190
  rescue Cli::SchemaRequest => e
188
191
  schema_path = e.path
@@ -196,7 +199,7 @@ module Aspera
196
199
  rescue SystemExit => e
197
200
  MCP::Tool::Response.new([{type: 'text', text: "exited with status #{e.status}"}], error: !e.status.zero?)
198
201
  rescue => e
199
- MCP::Tool::Response.new([{type: 'text', text: SecretHider.instance.hide_secrets_in_string("#{e.class}: #{dedupe_lines(e.message)}", all: true)}], error: true)
202
+ MCP::Tool::Response.new([{type: 'text', text: Secret::Hider.instance.hide_secrets_in_string("#{e.class}: #{dedupe_lines(e.message)}", all: true)}], error: true)
200
203
  end
201
204
 
202
205
  # Delegate to Schema::Reader#to_rows — semantic fields, no ANSI, MCP/JSON-ready.
@@ -1,7 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/parser'
4
- require 'aspera/cli/command_spec'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'command_spec'
5
7
 
6
8
  module Aspera
7
9
  module Cli
@@ -26,9 +28,11 @@ module Aspera
26
28
  # @param deprecation [Hash, nil] Deprecation `{last:, message:}` forwarded to options.declare (see `Deprecation`)
27
29
  # @param schema [String, nil] Schema reference (e.g. "opts:components.schemas.Foo");
28
30
  # when description: is nil, the schema title or first description line is used
31
+ # @param complete [Symbol, nil] Values proposed by shell completion, one of `Complete::KINDS`
32
+ # @param security [Symbol, nil] Most restrictive security level at which the option is available (see `Security`)
29
33
  def option(name, description: nil,
30
34
  short: nil, allowed: nil, default: nil,
31
- on_set: nil, shorthand: nil, deprecation: nil, schema: nil)
35
+ on_set: nil, shorthand: nil, deprecation: nil, schema: nil, complete: nil, security: nil)
32
36
  register_option_spec(
33
37
  OptionSpec.new(
34
38
  name: name,
@@ -39,7 +43,9 @@ module Aspera
39
43
  on_set: on_set,
40
44
  shorthand: shorthand,
41
45
  deprecation: deprecation,
42
- schema: schema
46
+ schema: schema,
47
+ complete: complete,
48
+ security: security
43
49
  )
44
50
  )
45
51
  end
@@ -1,8 +1,11 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/option_value'
4
- require 'aspera/cli/error'
5
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'option_value'
7
+ require_relative 'error'
8
+ require_relative '../assert'
6
9
 
7
10
  module Aspera
8
11
  module Cli
@@ -1,7 +1,10 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/error'
4
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'error'
7
+ require_relative '../assert'
5
8
 
6
9
  module Aspera
7
10
  module Cli
@@ -77,6 +80,18 @@ module Aspera
77
80
  STRING = [String].freeze
78
81
  end
79
82
 
83
+ # Values proposed by shell completion for an option, an argument or a schema key (`complete:`, `x-cli-complete`),
84
+ # when they are not a list of allowed values:
85
+ # - `file`: local file or folder
86
+ # - `folder`: local folder
87
+ # - `destination_folder`: local folder, unless the command sends files (the destination is then remote)
88
+ # - `preset`: name of option preset
89
+ # - `preset_parameter`: parameter of the option preset given as first argument of the command
90
+ # - `transfer_job`: identifier of an asynchronous transfer job
91
+ module Complete
92
+ KINDS = %i[file folder destination_folder preset preset_parameter transfer_job].freeze
93
+ end
94
+
80
95
  # Sources of option values.
81
96
  # A value is ignored if the option was already set from a source with higher priority.
82
97
  module OptionSource
@@ -1,13 +1,17 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/option_types'
4
- require 'aspera/cli/extended_value'
5
- require 'aspera/cli/deprecation'
6
- require 'aspera/secret_hider'
7
- require 'aspera/schema/registry'
8
- require 'aspera/schema/validator'
9
- require 'aspera/log'
10
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'option_types'
7
+ require_relative 'extended_value'
8
+ require_relative 'security'
9
+ require_relative 'deprecation'
10
+ require_relative '../secret/hider'
11
+ require_relative '../schema/registry'
12
+ require_relative '../schema/validator'
13
+ require_relative '../log'
14
+ require_relative '../assert'
11
15
 
12
16
  module Aspera
13
17
  module Cli
@@ -22,6 +26,12 @@ module Aspera
22
26
  # [Symbol, nil] `OptionSource` of current value, `nil` if never set
23
27
  attr_reader :source
24
28
  attr_reader :sensitive, :schema, :deprecation
29
+ # [Symbol, nil] Most restrictive security level at which the option is available, `nil`: all levels, see `Security`
30
+ attr_reader :security
31
+ # [String, nil] For a `Hash` option: key of a `String` value
32
+ attr_reader :shorthand
33
+ # [Symbol, nil] Values proposed by shell completion, one of `Complete::KINDS`
34
+ attr_reader :complete
25
35
  # [Array] List of allowed values (Symbols and specific values)
26
36
  attr_accessor :values
27
37
  # [String] Help section group name (set by OptionRegistry)
@@ -36,14 +46,17 @@ module Aspera
36
46
  # @param allowed [nil,Class,Array<Class>,Array<Symbol>] Allowed values
37
47
  # @param on_set [#call, nil] Called with the new value each time the value is set
38
48
  # @param shorthand [String, nil] For a `Hash` option: a `String` value is stored as `{shorthand => value}`
49
+ # @param convert [#call, nil] For a `Hash` option: called with a new `Hash` value, returns the value to store, before merge (e.g. conversion of a deprecated form)
39
50
  # @param deprecation [Hash, Deprecation, nil] Deprecation: `{last:, message:}`, see `Deprecation`
40
51
  # @param schema [String] Declaration of schema
52
+ # @param complete [Symbol, nil] Values proposed by shell completion, one of `Complete::KINDS`
53
+ # @param security [Symbol, nil] Most restrictive security level at which the option is available (e.g. `:low`: executes code), see `Security`
41
54
  # `allowed`:
42
55
  # - `nil` No validation, so just a string
43
56
  # - `Class` The single allowed Class
44
57
  # - `Array<Class>` Multiple allowed classes
45
58
  # - `Array<Symbol>` List of allowed values
46
- def initialize(option:, description: nil, allowed: Type::STRING, on_set: nil, shorthand: nil, deprecation: nil, schema: nil)
59
+ def initialize(option:, description: nil, allowed: Type::STRING, on_set: nil, shorthand: nil, convert: nil, deprecation: nil, schema: nil, complete: nil, security: nil)
47
60
  Log.log.trace1 { "option: #{option}, allowed: #{allowed}" }
48
61
  @option = option
49
62
  @description = description
@@ -51,10 +64,16 @@ module Aspera
51
64
  @short = nil
52
65
  @block = nil
53
66
  # by default passwords and secrets are sensitive, else specify when declaring the option
54
- @sensitive = SecretHider.instance.secret?(@option, '')
67
+ @sensitive = Secret::Hider.instance.secret?(@option, '')
55
68
  @deprecation = Deprecation.create(deprecation)
56
69
  @schema = schema
57
70
  @shorthand = shorthand
71
+ Aspera.assert(convert.nil? || convert.respond_to?(:call)) { "#{@option}: convert must respond to call" }
72
+ @convert = convert
73
+ Aspera.assert_values(complete, Complete::KINDS + [nil]) { "#{@option}: complete" }
74
+ @complete = complete
75
+ Aspera.assert_values(security, Security::LEVELS + [nil]) { "#{@option}: security" }
76
+ @security = security
58
77
  @source = nil
59
78
  @value = nil
60
79
  Aspera.assert(on_set.nil? || on_set.respond_to?(:call)) { "#{@option}: on_set callback must respond to call" }
@@ -100,7 +119,7 @@ module Aspera
100
119
  # @param log [Boolean] whether to log the value retrieval
101
120
  # @return [Object] current value
102
121
  def value(log: true)
103
- Log.log.trace1 { "#{@option} -> (#{@value.class})#{@value}" } if log
122
+ Log.log.trace1 { "#{@option} -> (#{@value.class})#{Secret::Hider.instance.hidden_copy(@value)}" } if log
104
123
  @value
105
124
  end
106
125
 
@@ -121,6 +140,8 @@ module Aspera
121
140
  return
122
141
  end
123
142
  Aspera.assert(!@deprecation, type: :warn) { "Option #{@option} is #{@deprecation}" } if warn_deprecation
143
+ # Values set by the program itself are not restricted: those from command line, preset, environment are
144
+ Security.instance.check_level(@security, "option #{@option}") if restricted_source?(source)
124
145
  if schema_request?(value)
125
146
  return if lower
126
147
  raise SchemaRequest.new(:option, @option, @schema) unless @schema.nil?
@@ -129,9 +150,12 @@ module Aspera
129
150
  return
130
151
  end
131
152
  new_value = coerce(ExtendedValue.instance.evaluate(value, context: "option: #{@option}", allowed: @types))
153
+ check_sub_options_security(new_value) if restricted_source?(source)
132
154
  new_value = {@shorthand => new_value} if @shorthand && new_value.is_a?(String)
133
- Log.log.trace1 { "#{source}: #{@option} <- (#{new_value.class})#{new_value}" }
155
+ declare_secrets(new_value)
156
+ Log.log.trace1 { "#{source}: #{@option} <- (#{new_value.class})#{Secret::Hider.instance.hidden_copy(new_value)}" }
134
157
  Aspera.assert_type(new_value, *@types, type: BadArgument) { "Option #{@option}" } if @types
158
+ new_value = @convert.call(new_value) if @convert && new_value.is_a?(Hash)
135
159
  if merge && (new_value.is_a?(Hash) || new_value.is_a?(Array))
136
160
  current_value = @value
137
161
  # An `Array` default value is replaced, not appended to
@@ -150,8 +174,38 @@ module Aspera
150
174
  nil
151
175
  end
152
176
 
177
+ # Check that the option, and the sub-options present in a `Hash` value (`x-security` in schema), are available at current security level.
178
+ # Used for a value that is not assigned yet, e.g. to store in a preset.
179
+ # @param value [Object] Value of the option
180
+ # @raise [BadArgument] If refused at current level
181
+ def check_security(value)
182
+ Security.instance.check_level(@security, "option #{@option}")
183
+ check_sub_options_security(value)
184
+ end
185
+
153
186
  private
154
187
 
188
+ # Values set by the program, or by the environment of the process (under control of the one who starts it), are not restricted:
189
+ # those from command line, presets (that a client can modify) and interactive input are.
190
+ # @param source [Symbol] `OptionSource`
191
+ # @return [Boolean] `true` if a value from this source is checked against security level
192
+ def restricted_source?(source)
193
+ !%i[default code env].include?(source)
194
+ end
195
+
196
+ # @param value [Object] Value of the option
197
+ # @raise [BadArgument] If a sub-option with `x-security` in the schema is present and refused at current level
198
+ def check_sub_options_security(value)
199
+ return unless @schema && value.is_a?(Hash)
200
+ Schema::Registry.instance.reader(@schema).each_property do |property, _name, full_name, _required|
201
+ level = property['x-security']
202
+ next if level.nil?
203
+ # Value of the sub-option, if given (a `nil` value clears it)
204
+ given = full_name.split('.').reduce(value) { |node, key| node.is_a?(Hash) ? node.find { |k, _| k.to_s.eql?(key) }&.last : nil }
205
+ Security.instance.check_level(level.to_sym, "option #{@option}.#{full_name}") unless given.nil?
206
+ end
207
+ end
208
+
155
209
  # Validate a structured value against the schema of the option.
156
210
  # Value may be partial: completed by other sources or defaults, so `required` is not enforced.
157
211
  # @param value [Object] value to validate
@@ -268,15 +322,20 @@ module Aspera
268
322
  end
269
323
  end
270
324
 
271
- # @param new_value [Object] value to store
272
- # @param source [Symbol, nil] `OptionSource` of value
273
- def store(new_value, source)
274
- # Secret values are hidden wherever they appear: logs, results
325
+ # Secret values are hidden wherever they appear: logs, results
326
+ # @param value [Object] value of option
327
+ def declare_secrets(value)
275
328
  if @sensitive
276
- SecretHider.instance.add_secret_values(new_value)
329
+ Secret::Hider.instance.add_secret_values(value)
277
330
  else
278
- SecretHider.instance.add_secrets_in(new_value)
331
+ Secret::Hider.instance.add_secrets_in(value)
279
332
  end
333
+ end
334
+
335
+ # @param new_value [Object] value to store
336
+ # @param source [Symbol, nil] `OptionSource` of value
337
+ def store(new_value, source)
338
+ declare_secrets(new_value)
280
339
  @value = new_value
281
340
  @source = source
282
341
  @on_set&.call(new_value)