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
@@ -1,9 +1,12 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/plugins/basic_auth'
4
- require 'aspera/cli/plugins/node'
5
- require 'aspera/assert'
6
- require 'aspera/rest/list'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'basic_auth'
7
+ require_relative 'node'
8
+ require_relative '../../assert'
9
+ require_relative '../../rest/list'
7
10
 
8
11
  module Aspera
9
12
  module Cli
@@ -14,6 +17,13 @@ module Aspera
14
17
  NODE_API_PATH = 'node_api'
15
18
  # path for node admin after base url
16
19
  ADMIN_API_PATH = 'api/v1'
20
+ # path for authentication (SAML login page, OAuth token) after base url
21
+ AUTH_API_PATH = 'auth'
22
+ # default URL that receives the tokens, with auth `web` and `ui.web_auth=port`
23
+ REDIRECT_LOCALHOST = 'http://localhost:12345'
24
+ AUTH_TYPES = %i[basic web].freeze
25
+ option :auth, description: 'Type of authentication: user and password, or Web browser (SAML)', allowed: AUTH_TYPES, default: :basic
26
+ option :redirect_uri, description: "Web authentication with ui.web_auth=port: loopback URL that receives the tokens (default: #{REDIRECT_LOCALHOST})"
17
27
  class << self
18
28
  # Check various endpoints on Shares
19
29
  # @return [Hash] with version, ping, api
@@ -27,12 +37,13 @@ module Aspera
27
37
  .new(base_url: url, redirect_max: 2)
28
38
  .read('', headers: {'Accept'=>'text/html'})
29
39
  Aspera.assert(login_page.include?('aspera-Shares')) { 'not Shares' }
30
- if (m = login_page.match(/\(v([0-9a-f\.]+)\)/))
40
+ if (m = login_page.match(/\(v([0-9a-f.]+)\)/))
31
41
  version = m[1]
32
42
  if (m = login_page.match(/Patch level ([0-9]+)/))
33
43
  version = "#{version} #{m[0]}"
34
44
  end
35
45
  end
46
+ result[:saml] = login_page.include?('/auth/saml')
36
47
  version.nil? ? 'no version' : version
37
48
  rescue => e
38
49
  e
@@ -60,6 +71,15 @@ module Aspera
60
71
  rescue => e
61
72
  e
62
73
  end
74
+ # Native JSON health check endpoint (no auth required)
75
+ result[:system] =
76
+ begin
77
+ Rest::Client
78
+ .new(base_url: url)
79
+ .read('health_check')
80
+ rescue => e
81
+ e
82
+ end
63
83
  result
64
84
  end
65
85
 
@@ -70,7 +90,8 @@ module Aspera
70
90
  return unless health[:api].is_a?(String)
71
91
  return {
72
92
  version: health[:version].is_a?(String) ? health[:version] : 'unknown',
73
- url: address_or_url
93
+ url: address_or_url,
94
+ saml: health[:saml] || false
74
95
  }
75
96
  end
76
97
  end
@@ -79,14 +100,53 @@ module Aspera
79
100
  # @param app_url [String] Tested URL
80
101
  # @return [Hash] :preset_value, :test_args
81
102
  def wizard(wizard, app_url)
82
- return {
83
- preset_value: {
84
- url: app_url,
85
- username: options.get_option(:username, mandatory: true),
86
- password: options.get_option(:password, mandatory: true)
87
- },
88
- test_args: 'files browse /'
89
- }
103
+ auth_type = if !options.option_def(:auth).source.eql?(:default)
104
+ options.get_option(:auth)
105
+ elsif options.get_option(:password)
106
+ :basic
107
+ else
108
+ saml_detected = begin
109
+ self.class.health_check(app_url)[:saml] || false
110
+ rescue StandardError
111
+ false
112
+ end
113
+ formatter.display_status('SAML authentication is available.') if saml_detected
114
+ if wizard.required
115
+ formatter.display_status('Select authentication method:')
116
+ options.prompt_user_input_in_list('auth', AUTH_TYPES)
117
+ else
118
+ saml_detected ? :web : :basic
119
+ end
120
+ end
121
+
122
+ case auth_type
123
+ when :web
124
+ username = options.get_option(:username)
125
+ preset_ids = username && !username.empty? ? [username] : ['web']
126
+ preset_value = {
127
+ url: app_url,
128
+ auth: :web.to_s
129
+ }
130
+ preset_value[:username] = username if username && !username.empty?
131
+ redirect_uri = options.get_option(:redirect_uri)
132
+ preset_value[:redirect_uri] = redirect_uri if redirect_uri
133
+ {
134
+ preset_ids: preset_ids,
135
+ preset_value: preset_value,
136
+ test_args: 'files browse /'
137
+ }
138
+ when :basic
139
+ username = options.get_option(:username, mandatory: true)
140
+ {
141
+ preset_ids: [username],
142
+ preset_value: {
143
+ url: app_url,
144
+ username: username,
145
+ password: options.get_option(:password, mandatory: true)
146
+ },
147
+ test_args: 'files browse /'
148
+ }
149
+ end
90
150
  end
91
151
 
92
152
  def initialize(**_)
@@ -94,15 +154,40 @@ module Aspera
94
154
  @api_shares_admin = nil
95
155
  end
96
156
 
157
+ # With `auth` `web`, the user authenticates with a browser (SAML), and the REST API uses the OAuth token.
158
+ # Otherwise: user and password.
159
+ # @param subpath [String, nil] Path of API after base URL
160
+ # @return [Hash] Parameters of `Rest::Client`
161
+ def basic_auth_params(subpath = nil)
162
+ return super unless options.get_option(:auth).eql?(:web)
163
+ url = options.get_option(:url, mandatory: true)
164
+ username = options.get_option(:username)
165
+ return {
166
+ base_url: subpath.nil? ? url : "#{url}/#{subpath}",
167
+ auth: {
168
+ type: :oauth2,
169
+ base_url: "#{url}/#{AUTH_API_PATH}",
170
+ grant_method: :shares_web,
171
+ redirect_uri: options.get_option(:redirect_uri) || REDIRECT_LOCALHOST,
172
+ # a token is cached for each user, if known
173
+ cache_ids: [username].compact
174
+ }
175
+ }
176
+ end
177
+
97
178
  SAML_IMPORT_MANDATORY = %w[id name_id].freeze
98
179
  SAML_IMPORT_ALLOWED = (%w[email given_name surname] + SAML_IMPORT_MANDATORY).freeze
99
180
 
100
181
  # common to users and groups
101
182
  USR_GRP_SETTINGS = %i[transfer_settings app_authorizations share_permissions].freeze
183
+ # transfer_settings supports delete (resets to global inheritance); app_authorizations and share_permissions do not
184
+ TRANSFER_SETTINGS_OPS = %i[show modify delete].freeze
102
185
  # share_permissions is read-only (Rails only exposes index+show)
103
186
  SHARE_PERMISSIONS_OPS = %i[list show].freeze
104
- # group users: Rails only exposes index+show+update+destroy (no create)
187
+ # group users (all): Rails only exposes index+show+update+destroy (no create)
105
188
  GROUP_USERS_OPS = (Operations::ALL - %i[create]).freeze
189
+ # local group users: same operations (no create), via data/local_groups/{id}/local_users
190
+ LOCAL_GROUP_USERS_OPS = GROUP_USERS_OPS
106
191
  # Arguments of group users commands, by operation
107
192
  GROUP_USERS_ARGS = {
108
193
  show: [{name: :user_id, type: :identifier}],
@@ -117,10 +202,25 @@ module Aspera
117
202
  command :files, description: 'Browse and transfer files on Shares', aliases: [:repository],
118
203
  mount: {plugin: Node, instance: :shares_node_plugin, only: Node::COMMANDS_SHARES}
119
204
  command :admin, description: 'Administer Shares', setup: :setup_admin
205
+ command :share, description: 'Shares accessible to current user'
206
+
207
+ commands_under :share do
208
+ command :list, description: 'List shares accessible to the current user',
209
+ action: ->(**) { entity_list(api: basic_auth_api(ADMIN_API_PATH), entity: 'shares', items_key: 'shares') }
210
+ command :event, description: 'Transfer notification events on a share'
211
+ commands_under :event do
212
+ command :create,
213
+ description: 'Notify Shares of a completed transfer (triggers email alerts)',
214
+ arguments: [
215
+ {name: :share_id, type: :identifier, lookup: :lookup_share_id_user},
216
+ {name: :event, type: Hash}
217
+ ]
218
+ end
219
+ end
120
220
 
121
221
  commands_under :admin do
122
222
  commands_under :node do
123
- crud_commands entity: 'data/nodes', api: :@api_shares_admin
223
+ crud_commands entity: 'data/nodes', api: :@api_shares_admin, lookup: %w[name]
124
224
  end
125
225
  commands_under :ldap_config, description: 'LDAP configuration' do
126
226
  crud_commands entity: 'data/ldap_configs', api: :@api_shares_admin
@@ -136,13 +236,30 @@ module Aspera
136
236
  body_component: Schema::Registry::SHARES,
137
237
  operations: %i[show create modify]
138
238
  end
239
+ commands_under :directory do
240
+ command :list, description: 'List configured authentication directories',
241
+ action: ->(**) { entity_list(api: @api_shares_admin, entity: 'directories') }
242
+ command :show,
243
+ description: 'Get details of an authentication directory',
244
+ arguments: [{name: :directory_id, type: :identifier}]
245
+ command :users,
246
+ description: 'Search users in a directory',
247
+ arguments: [{name: :directory_id, type: :identifier}]
248
+ command :groups,
249
+ description: 'Search groups in a directory',
250
+ arguments: [{name: :directory_id, type: :identifier}]
251
+ end
252
+ command :authenticate,
253
+ description: 'Validate credentials and optionally check a permission',
254
+ arguments: [{name: :credentials, type: Hash}]
139
255
  # user / group: sub-commands per location, generated for both entity types
140
256
  %i[user group].each do |entity_type|
141
257
  commands_under entity_type do
142
- command :all, description: "#{entity_type.capitalize}s from all sources"
143
- command :local, description: "Local #{entity_type}s"
144
- command :ldap, description: "LDAP #{entity_type}s"
145
- command :saml, description: "SAML #{entity_type}s"
258
+ command :all, description: "#{entity_type.capitalize}s from all sources"
259
+ command :local, description: "Local #{entity_type}s"
260
+ command :ldap, description: "LDAP #{entity_type}s"
261
+ command :saml, description: "SAML #{entity_type}s"
262
+ command :search, description: "Search #{entity_type}s across all directories"
146
263
 
147
264
  user_fields = %w[id user_id username first_name last_name email] if entity_type.eql?(:user)
148
265
  # all: list/show/delete only (no create, no modify — users/groups/:all has no update route)
@@ -154,23 +271,34 @@ module Aspera
154
271
  operations: Operations::ALL - %i[create modify],
155
272
  lookup: lookup_method_all,
156
273
  display_fields: user_fields && (user_fields + %w[directory_user])
274
+ # share_permissions are read-only: tell where they are granted
275
+ grant_hint = "read-only, grant with: admin share #{entity_type}_permissions"
157
276
  USR_GRP_SETTINGS.each do |setting|
158
- # share_permissions: Rails only exposes index+show (read-only)
159
- setting_ops = setting.eql?(:share_permissions) ? SHARE_PERMISSIONS_OPS : %i[show modify]
277
+ # choose the operations set for this setting
278
+ setting_ops =
279
+ case setting
280
+ when :share_permissions then SHARE_PERMISSIONS_OPS
281
+ when :transfer_settings then TRANSFER_SETTINGS_OPS
282
+ else %i[show modify]
283
+ end
160
284
  command setting,
161
- description: "Manage #{entity_noun(setting, singular: false)} for a #{entity_type}",
285
+ description: setting.eql?(:share_permissions) ? "Permissions of a #{entity_type} on shares (#{grant_hint})" : "Manage #{entity_noun(setting, singular: false)} for a #{entity_type}",
162
286
  arguments: [{name: :"#{entity_type}_id", type: :identifier, lookup: lookup_method_all}]
163
287
  commands_under setting do
164
288
  setting_ops.each do |op|
165
- # share_permissions > show needs a permission identifier (list does not), modify needs data
289
+ # share_permissions > show needs a share identifier (list does not), modify needs data
166
290
  op_args =
167
291
  case op
168
- when :show then setting.eql?(:share_permissions) ? [{name: :permission_id, type: :identifier, lookup: :lookup_share_id}] : nil
292
+ when :show then setting.eql?(:share_permissions) ? [{name: :share_id, type: :identifier, lookup: :lookup_share_id}] : nil
169
293
  when :modify then [{name: setting, type: Hash}]
170
294
  end
171
- command op,
172
- description: "#{op.capitalize} #{entity_noun(setting, singular: false)} for a #{entity_type}",
173
- arguments: op_args
295
+ op_description =
296
+ case [setting, op]
297
+ when %i[share_permissions list] then "List permissions of a #{entity_type} on shares (#{grant_hint})"
298
+ when %i[share_permissions show] then "Show permission of a #{entity_type} on a share (#{grant_hint})"
299
+ else "#{op.capitalize} #{entity_noun(setting, singular: false)} for a #{entity_type}"
300
+ end
301
+ command op, description: op_description, arguments: op_args
174
302
  end
175
303
  end
176
304
  end
@@ -197,11 +325,16 @@ module Aspera
197
325
  body_component: Schema::Registry::SHARES
198
326
  if entity_type.eql?(:group)
199
327
  command :users,
200
- description: 'Manage users of a group',
328
+ description: 'Manage users of a local group',
201
329
  arguments: [{name: :group_id, type: :identifier, lookup: :lookup_shares_group_local_id}]
202
330
  commands_under :users do
203
- GROUP_USERS_OPS.each do |op|
204
- command op, description: "#{op.capitalize} users of a group", arguments: GROUP_USERS_ARGS[op]
331
+ LOCAL_GROUP_USERS_OPS.each do |op|
332
+ local_op_args =
333
+ case op
334
+ when :show, :delete then [{name: :user_id, type: :identifier}]
335
+ when :modify then [{name: :user_id, type: :identifier}, {name: :user, type: Hash}]
336
+ end
337
+ command op, description: "#{op.capitalize} users of a local group", arguments: local_op_args
205
338
  end
206
339
  end
207
340
  end
@@ -218,6 +351,24 @@ module Aspera
218
351
  command :import, description: "Import a SAML #{entity_type}",
219
352
  arguments: [{name: entity_type, type: Hash, bulk: true}]
220
353
  end
354
+
355
+ # search: list + show by URN + (groups only) members
356
+ # The cross-directory search endpoints return a collection object {"resource_type":"collection","members":[...]}
357
+ # entity_plural captured at class-load time in the closure
358
+ entity_plural_search = entity_type.eql?(:user) ? 'users' : 'groups'
359
+ commands_under :search do
360
+ command :list,
361
+ description: "Search #{entity_type}s across all directories (use --query={q: '...'} to filter)",
362
+ action: ->(**) { entity_list(api: @api_shares_admin, entity: entity_plural_search, items_key: 'members') }
363
+ command :show,
364
+ description: "Get directory #{entity_type} details by URN",
365
+ arguments: [{name: :"#{entity_type}_urn", type: :identifier}]
366
+ if entity_type.eql?(:group)
367
+ command :members,
368
+ description: 'Search members in a directory group',
369
+ arguments: [{name: :group_urn, type: :identifier}]
370
+ end
371
+ end
221
372
  end
222
373
  end
223
374
  end
@@ -233,7 +384,7 @@ module Aspera
233
384
  lookup_method = :"lookup_shares_#{entity_type}_#{location}_id"
234
385
  define_method(lookup_method) do |field, value, **|
235
386
  path = admin_entity_path(entity_type, location)
236
- Rest::List.lookup_entity_generic(entity: entity_type, field: field, value: value) { @api_shares_admin.read(path) }['id']
387
+ Rest::List.lookup_entity_generic(field: field, value: value, entity: entity_type) { @api_shares_admin.read(path) }['id']
237
388
  end
238
389
  private lookup_method
239
390
  end
@@ -259,10 +410,12 @@ module Aspera
259
410
  {user_permissions: :user, group_permissions: :group}.each do |perm_type, entity_type|
260
411
  commands_under [:admin, :share, perm_type] do
261
412
  crud_commands entity: :"share_#{perm_type}",
262
- api: :@api_shares_admin,
263
- name: entity_noun(perm_type),
264
- id_name: :"#{entity_type}_id",
265
- lookup: :"lookup_shares_#{entity_type}_all_id"
413
+ api: :@api_shares_admin,
414
+ name: entity_noun(perm_type),
415
+ id_name: :"#{entity_type}_id",
416
+ lookup: :"lookup_shares_#{entity_type}_all_id",
417
+ body_component: Schema::Registry::SHARES,
418
+ schema_entity: "data/shares/{share_id}/#{perm_type}"
266
419
  end
267
420
  end
268
421
 
@@ -297,7 +450,14 @@ module Aspera
297
450
 
298
451
  # Lookup a share id by field/value using the admin API.
299
452
  def lookup_share_id(field, value, **)
300
- Rest::List.lookup_entity_generic(entity: 'share', field: field, value: value) { @api_shares_admin.read('data/shares') }['id']
453
+ Rest::List.lookup_entity_generic(field: field, value: value, entity: 'share') { @api_shares_admin.read('data/shares') }['id']
454
+ end
455
+
456
+ # Lookup a share id by field/value using the user-level API (for share event create).
457
+ def lookup_share_id_user(field, value, **)
458
+ data = basic_auth_api(ADMIN_API_PATH).read('shares')
459
+ data = data['shares'] if data.is_a?(Hash)
460
+ Rest::List.lookup_entity_generic(field: field, value: value, entity: 'share') { data }['id']
301
461
  end
302
462
 
303
463
  # --- health ---
@@ -317,6 +477,25 @@ module Aspera
317
477
  else
318
478
  nagios.add_critical('API', health[:api].to_s)
319
479
  end
480
+ if health[:system].is_a?(Hash)
481
+ sys = health[:system]
482
+ # one status item for the license (standard or entitlement)
483
+ if sys['valid_license'] || sys['entitled']
484
+ nagios.add_ok('license', sys['entitled'] ? 'entitled' : 'valid')
485
+ else
486
+ nagios.add_critical('license', 'invalid')
487
+ end
488
+ # one status item per configured node
489
+ (sys['nodes'] || []).each do |node|
490
+ if node['status'].to_s.casecmp('active').zero?
491
+ nagios.add_ok("node #{node['id']}", node['status'])
492
+ else
493
+ nagios.add_critical("node #{node['id']}", node['status'])
494
+ end
495
+ end
496
+ else
497
+ nagios.add_critical('system', health[:system].to_s)
498
+ end
320
499
  Result::ObjectList.new(nagios.status_list)
321
500
  end
322
501
 
@@ -336,10 +515,10 @@ module Aspera
336
515
  # @param setting [Symbol] one of USR_GRP_SETTINGS
337
516
  # @param op [Symbol] CRUD operation
338
517
  # entity_id: resolved via arguments:(:identifier) on the setting node
339
- # permission_id: (share_permissions show) and data: (modify) resolved via arguments: on the leaf
340
- def admin_entity_setting(entity_type, location, setting, op, entity_id:, permission_id: nil, data: nil)
518
+ # share_id: (share_permissions show) and data: (modify) resolved via arguments: on the leaf
519
+ def admin_entity_setting(entity_type, location, setting, op, entity_id:, share_id: nil, data: nil)
341
520
  entity_path = "#{admin_entity_path(entity_type, location)}/#{entity_id}/#{setting}"
342
- send(:"entity_#{op}", api: @api_shares_admin, entity: entity_path, id: permission_id, is_singleton: !setting.eql?(:share_permissions), data: data)
521
+ send(:"entity_#{op}", api: @api_shares_admin, entity: entity_path, id: share_id, is_singleton: !setting.eql?(:share_permissions), data: data)
343
522
  end
344
523
 
345
524
  # Shared handler for :users (group only)
@@ -353,25 +532,45 @@ module Aspera
353
532
 
354
533
  # Generate action_admin_<user|group>_<location>_<verb> for all combinations
355
534
  %i[user group].each do |entity_type|
356
- # all: list/show/delete only (no create, no modify — no update route on /users and /groups)
535
+ # all: list/show/delete only — nested settings (transfer_settings, app_authorizations, share_permissions) only under :all
357
536
  # local: full CRUD only — no nested settings under local_users/local_groups
358
537
  ENTITY_LOCATIONS.each do |location|
359
538
  unless location.eql?(:local)
360
539
  USR_GRP_SETTINGS.each do |setting|
361
- # share_permissions: Rails only exposes index+show (read-only)
362
- setting_ops = setting.eql?(:share_permissions) ? SHARE_PERMISSIONS_OPS : %i[show modify]
540
+ # choose the operations set for this setting
541
+ setting_ops =
542
+ case setting
543
+ when :share_permissions then SHARE_PERMISSIONS_OPS
544
+ when :transfer_settings then TRANSFER_SETTINGS_OPS
545
+ else %i[show modify]
546
+ end
363
547
  setting_ops.each do |op|
364
548
  define_action_method([:admin, entity_type, location, setting, op]) do |**kwargs|
365
- admin_entity_setting(entity_type, location, setting, op, entity_id: kwargs[:"#{entity_type}_id"], permission_id: kwargs[:permission_id], data: kwargs[setting])
549
+ admin_entity_setting(entity_type, location, setting, op, entity_id: kwargs[:"#{entity_type}_id"], share_id: kwargs[:share_id], data: kwargs[setting])
366
550
  end
367
551
  end
368
552
  end
369
553
  end
370
554
  next unless entity_type.eql?(:group)
371
- # group users: no create route (Rails only exposes index+show+update+destroy)
372
- GROUP_USERS_OPS.each do |op|
373
- define_action_method([:admin, entity_type, location, :users, op]) do |group_id:, user_id: nil, user: nil, **|
374
- admin_entity_users(entity_type, location, op, group_id: group_id, user_id: user_id, data: user)
555
+ if location.eql?(:all)
556
+ # all group users: no create route (Rails only exposes index+show+update+destroy)
557
+ GROUP_USERS_OPS.each do |op|
558
+ define_action_method([:admin, entity_type, :all, :users, op]) do |group_id:, user_id: nil, user: nil, **|
559
+ admin_entity_users(entity_type, :all, op, group_id: group_id, user_id: user_id, data: user)
560
+ end
561
+ end
562
+ else
563
+ # local group local_users: list/show/modify/delete (via data/local_groups/{id}/local_users)
564
+ LOCAL_GROUP_USERS_OPS.each do |op|
565
+ define_action_method([:admin, entity_type, :local, :users, op]) do |group_id:, user_id: nil, user: nil, **|
566
+ send(
567
+ :"entity_#{op}",
568
+ api: @api_shares_admin,
569
+ entity: "data/local_groups/#{group_id}/local_users",
570
+ id: user_id,
571
+ data: user
572
+ )
573
+ end
375
574
  end
376
575
  end
377
576
  end
@@ -397,6 +596,47 @@ module Aspera
397
596
  @api_shares_admin.create("#{path}/import", entity_parameters)
398
597
  end
399
598
  end
599
+
600
+ # search: list + show + (groups) members — cross-directory endpoints under /api/v1/users|groups
601
+ # URNs contain ':' and '=' and must be percent-encoded in the URL path segment.
602
+ entity_plural = entity_type.eql?(:user) ? 'users' : 'groups'
603
+ define_action_method(%i[admin].push(entity_type, :search, :show)) do |**kwargs|
604
+ urn = URI.encode_www_form_component(kwargs[:"#{entity_type}_urn"])
605
+ Result::SingleObject.new(@api_shares_admin.read("#{entity_plural}/#{urn}"))
606
+ end
607
+ next unless entity_type.eql?(:group)
608
+ define_action_method(%i[admin group search members]) do |group_urn:, **|
609
+ encoded = URI.encode_www_form_component(group_urn)
610
+ entity_list(api: @api_shares_admin, entity: "groups/#{encoded}/members", items_key: 'members')
611
+ end
612
+ end
613
+
614
+ # admin > directory > show / users / groups
615
+ # directory_id is a URN — must be percent-encoded in the URL path segment.
616
+ define_action_method(%i[admin directory show]) do |directory_id:, **|
617
+ enc = URI.encode_www_form_component(directory_id)
618
+ Result::SingleObject.new(@api_shares_admin.read("directories/#{enc}"))
619
+ end
620
+
621
+ define_action_method(%i[admin directory users]) do |directory_id:, **|
622
+ enc = URI.encode_www_form_component(directory_id)
623
+ entity_list(api: @api_shares_admin, entity: "directories/#{enc}/users", items_key: 'members')
624
+ end
625
+
626
+ define_action_method(%i[admin directory groups]) do |directory_id:, **|
627
+ enc = URI.encode_www_form_component(directory_id)
628
+ entity_list(api: @api_shares_admin, entity: "directories/#{enc}/groups", items_key: 'members')
629
+ end
630
+
631
+ # admin > authenticate
632
+ define_action_method(%i[admin authenticate]) do |credentials:, **|
633
+ Result::SingleObject.new(@api_shares_admin.create('authenticate', credentials))
634
+ end
635
+
636
+ # share > event > create
637
+ define_action_method(%i[share event create]) do |share_id:, event:, **|
638
+ basic_auth_api(ADMIN_API_PATH).create("shares/#{share_id}/events", event)
639
+ Result::Status.new('event created')
400
640
  end
401
641
  end
402
642
  end