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,12 +1,16 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/oauth/client/factory'
4
- require 'aspera/log'
5
- require 'aspera/assert'
6
- require 'aspera/secret_hider'
7
- require 'aspera/mime'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'factory'
7
+ require_relative '../../log'
8
+ require_relative '../../assert'
9
+ require_relative '../../secret/hider'
10
+ require_relative '../../mime'
11
+ require_relative '../../rainbow'
8
12
  require 'date'
9
- require 'aspera/rainbow'
13
+ require 'time'
10
14
  using Rainbow
11
15
 
12
16
  module Aspera
@@ -18,12 +22,17 @@ module Aspera
18
22
  # Bearer Token Usage: https://tools.ietf.org/html/rfc6750
19
23
  class Base
20
24
  Aspera.require_method!(:create_token)
25
+ class << self
26
+ # @param path [String] Path of an end point
27
+ # @return [Boolean] `true` if `path` is an absolute URL (`http` or `https`)
28
+ def absolute_url?(path) = path.match?(%r{\Ahttps?://}i)
29
+ end
21
30
  # @param params [Hash] Parameters for token creation (client_id, client_secret, scope, etc...)
22
- # @param path_token [String] API end point to create a token from base URL
31
+ # @param path_token [String] API end point to create a token: path from base URL, or absolute URL (`http` or `https`), e.g. on another host
23
32
  # @param use_query [Boolean] Provide parameters in query instead of body
24
- # @param token_field [String] Field in result that contains the token
33
+ # @param token_field [String] Field in result that contains the token, or dot-separated path of a nested field (e.g. `authed_user.access_token`)
25
34
  # @param cache_ids [Array] List of unique identifiers for cache id generation
26
- # @param **rest_params [Hash] Parameters for REST
35
+ # @param rest_params [Hash] Parameters for REST
27
36
  def initialize(
28
37
  params: {},
29
38
  path_token: 'token',
@@ -50,92 +59,134 @@ module Aspera
50
59
  # Sub path to generate token
51
60
  attr_reader :path_token
52
61
 
62
+ # URL of an end point of the OAuth server
63
+ # @param path [String] Path from the base URL, or absolute URL (`http` or `https`), used as is
64
+ # @return [String] URL of the end point
65
+ def endpoint_url(path)
66
+ Base.absolute_url?(path) ? path : "#{@api.base_url}/#{path}"
67
+ end
68
+
69
+ # API and subpath to call an end point of the OAuth server
70
+ # An absolute URL (e.g. token on another host than authorization) gets its own API, same parameters.
71
+ # The token cache id does not depend on it: it uses the base URL.
72
+ # @param path [String] Path from the base URL, or absolute URL (`http` or `https`)
73
+ # @return [Array(Rest::Client, String)] API and subpath
74
+ def endpoint_api(path)
75
+ return [@api, path] unless Base.absolute_url?(path)
76
+ [Rest::Client.new(**@api.params.merge(base_url: path)), '']
77
+ end
78
+
53
79
  # Parameters for token creation call
54
80
  # @param include_secret [Boolean] Add secret in default call parameters
55
81
  # @param other_params [Hash] Other parameters to merge
56
82
  # @return [Hash] Token creation parameters
57
83
  def base_parameters(include_secret: false, **other_params)
58
- call_params = @params.dup
59
- call_params.delete(:client_secret) unless include_secret
60
- call_params.merge(other_params)
84
+ (include_secret ? @params : @params.except(:client_secret)).merge(other_params)
61
85
  end
62
86
 
63
87
  # Helper method to create token as per RFC
88
+ # @param include_secret [Boolean] Add secret in call parameters
64
89
  # @param other_params [Hash] Additional parameter to base parameters
65
90
  # @return [Net::HTTPResponse] Raw HTTP response with token
66
91
  # @raise [Rest::CallError] If not 2XX code
67
92
  def create_token_base(include_secret: false, **other_params)
68
93
  Log.log.debug { 'Generating a new token'.bg(:green) }
69
94
  creation_params = base_parameters(include_secret: include_secret, **other_params)
70
- return @api.create(@path_token, nil, query: creation_params, ret: :resp) if @use_query
71
- return @api.create(@path_token, creation_params, content_type: Mime::WWW, ret: :resp)
95
+ token_api, subpath = endpoint_api(@path_token)
96
+ return token_api.create(subpath, nil, query: creation_params, ret: :resp) if @use_query
97
+ token_api.create(subpath, creation_params, content_type: Mime::WWW, ret: :resp)
72
98
  end
73
99
 
74
- # @return [String] Value suitable for Authorization header: adds `Bearer `
75
- def authorization(**kwargs)
76
- return OAuth::Factory.bearer_authorization(token(**kwargs))
100
+ # Get the value of the HTTP `Authorization` header for this OAuth client, i.e. `Bearer <token>`.
101
+ # The bearer token is obtained through {#token} (cached, refreshed or generated).
102
+ # @return [String] Value suitable for Authorization header
103
+ def authorization
104
+ OAuth::Factory.bearer_authorization(token)
77
105
  end
78
106
 
79
- # Get a OAuth v2 token (generated, cached, refreshed)
80
- # If a token is expired (api returns 4xx), call again token(refresh: true)
81
- # @param cache [Boolean] set to false to disable cache
82
- # @param refresh [Boolean] set to true to force refresh or re-generation (if previous failed)
107
+ # Get the value of the HTTP `Authorization` header with a renewed token, i.e. `Bearer <token>`.
108
+ # To be used when the server rejected the current token.
109
+ # The bearer token is obtained through {#renew_token}.
110
+ # @return [String] Value suitable for Authorization header
111
+ def renewed_authorization
112
+ OAuth::Factory.bearer_authorization(renew_token)
113
+ end
114
+
115
+ # Get a OAuth v2 token: the cached one, unless it expires soon, else a renewed one.
116
+ # Checking expiration in advance helps a transfer agent which cannot renew the token itself
117
+ # (`direct` agent is equipped with renewal code).
118
+ # If the server rejects the token (API returns 4xx), call {#renew_token}.
83
119
  # @return [String] The bearer token
84
- def token(cache: true, refresh: false)
85
- # Get token info from cache (or nil), decoded with date and expiration status
86
- token_info = Factory.instance.get_token_info(@token_cache_id, token_field: @token_field) if cache
87
- token_data = nil
120
+ def token
121
+ token_info = cached_token_info
88
122
  unless token_info.nil?
89
- token_data = token_info[:data]
90
- # Optional optimization:
91
- # Check if token is expired based on decoded content then force refresh if close enough
92
- # might help in case the transfer agent cannot refresh himself
93
- # `direct` agent is equipped with refresh code
94
- # an API was already called, but failed, we need to regenerate or refresh
95
- if refresh || token_info[:expired]
96
- Log.log.trace1 { "refresh: #{refresh} expired: #{token_info[:expired]}" }
97
- refresh_token = nil
98
- if token_data.key?('refresh_token') && !token_data['refresh_token'].eql?('not_supported')
99
- # Save possible refresh token, before deleting the cache
100
- refresh_token = token_data['refresh_token']
101
- end
102
- # Delete cache
103
- Factory.instance.persist_mgr.delete(@token_cache_id)
104
- token_data = nil
105
- # Lets try the existing refresh token
106
- # NOTE: AoC admin token has no refresh, and lives by default 1800secs
107
- if !refresh_token.nil?
108
- begin
109
- http = create_token_base(
110
- include_secret: true,
111
- grant_type: 'refresh_token',
112
- refresh_token: refresh_token
113
- )
114
- # Save only if success
115
- json_data = http.body
116
- token_data = JSON.parse(json_data)
117
- Factory.instance.persist_mgr.put(@token_cache_id, json_data)
118
- rescue StandardError => e
119
- # Refresh token can fail.
120
- Log.log.warn { "Refresh failed: #{e}" }
121
- end
122
- end
123
- end
123
+ return bearer_token(token_info[:data]) unless token_info[:expired]
124
+ Log.log.trace1 { 'Cached token expires soon' }
124
125
  end
126
+ renew_token
127
+ end
125
128
 
126
- # no cache, nor refresh: generate a token
127
- if token_data.nil?
128
- # Call the method-specific token creation
129
- # which returns the result of create_token_base
130
- json_data = create_token.body
131
- token_data = JSON.parse(json_data)
132
- Factory.instance.persist_mgr.put(@token_cache_id, json_data)
133
- Factory.instance.get_token_info(@token_cache_id, token_field: @token_field)
134
- end
135
- Aspera.assert(token_data.key?(@token_field)) { "API error: No such field in answer: #{@token_field}" } unless token_data.nil?
136
- # Ok we shall have a token here: hidden wherever it appears (logs, results)
137
- SecretHider.instance.add_secret_values(token_data[@token_field], token_data['refresh_token'])
138
- return token_data[@token_field]
129
+ # Get a new OAuth v2 token, discarding the cached one.
130
+ # Use the refresh token of the cached token, if any, else generate a new token.
131
+ # @return [String] The bearer token
132
+ # @raise [StandardError] Error of the generation of a new token
133
+ def renew_token
134
+ bearer_token(refreshed_token_data(discard_cached_token) || save_token_data(create_token))
135
+ end
136
+
137
+ private
138
+
139
+ # @return [Hash, nil] Token information from cache (see {Factory#get_token_info}), or `nil` if none
140
+ def cached_token_info
141
+ Factory.instance.get_token_info(@token_cache_id, token_field: @token_field)
142
+ end
143
+
144
+ # Delete the cached token
145
+ # @return [String, nil] Its refresh token, or `nil` if none
146
+ def discard_cached_token
147
+ token_info = cached_token_info
148
+ return if token_info.nil?
149
+ Factory.instance.persist_mgr.delete(@token_cache_id)
150
+ refresh_token = token_info[:data]['refresh_token']
151
+ refresh_token unless refresh_token.eql?('not_supported')
152
+ end
153
+
154
+ # Get a new token using a refresh token.
155
+ # NOTE: AoC admin token has no refresh token, and lives by default 1800 secs
156
+ # @param refresh_token [String, nil] Refresh token, or `nil` if none
157
+ # @return [Hash{String => Object}, nil] Token creation response, or `nil` if no refresh token or if refresh failed
158
+ def refreshed_token_data(refresh_token)
159
+ return if refresh_token.nil?
160
+ save_token_data(create_token_base(include_secret: true, grant_type: 'refresh_token', refresh_token: refresh_token))
161
+ rescue StandardError => e
162
+ # Refresh token can fail: a new token will be generated
163
+ Log.log.warn { "Refresh failed: #{e}" }
164
+ nil
165
+ end
166
+
167
+ # Cache the token creation response
168
+ # Adds `obtained_at` and, if the server gives `expires_in`, `expires_at` (expiration of an opaque token)
169
+ # @param http [Net::HTTPResponse] Response of the token creation (see {#create_token_base})
170
+ # @return [Hash{String => Object}] Token creation response: `@token_field`, optional `refresh_token`, `expires_in`, ...
171
+ def save_token_data(http)
172
+ token_data = JSON.parse(http.body)
173
+ now = Time.now
174
+ token_data[Factory::OBTAINED_AT_FIELD] = now.utc.iso8601
175
+ lifetime = Integer(token_data['expires_in'], exception: false)
176
+ token_data[Factory::EXPIRES_AT_FIELD] = (now + lifetime).utc.iso8601 if lifetime && !token_data.key?(Factory::EXPIRES_AT_FIELD)
177
+ Factory.instance.persist_mgr.put(@token_cache_id, JSON.generate(token_data))
178
+ # Logs decoded token information
179
+ cached_token_info
180
+ token_data
181
+ end
182
+
183
+ # @param token_data [Hash{String => Object}] Token creation response
184
+ # @return [String] The bearer token, registered as secret: hidden wherever it appears (logs, results)
185
+ def bearer_token(token_data)
186
+ token_value = Factory.token_value(token_data, @token_field)
187
+ Aspera.assert(!token_value.nil?) { "API error: No such field in answer: #{@token_field}" }
188
+ Secret::Hider.instance.add_secret_values(token_value, token_data['refresh_token'])
189
+ token_value
139
190
  end
140
191
  end
141
192
  end
@@ -1,8 +1,11 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/oauth/client/base'
4
- require 'aspera/assert'
5
- require 'aspera/environment'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'base'
7
+ require_relative '../../assert'
8
+ require_relative '../../environment'
6
9
  require 'json'
7
10
 
8
11
  module Aspera
@@ -13,7 +16,7 @@ module Aspera
13
16
  class Boot < Base
14
17
  # @param cookie [String, nil] Raw cookie string (--password), nil to rely on existing cache
15
18
  # @param username [String, nil] Expected subject; if provided, must match token's `sub` claim
16
- # @param **base_params [Hash] Forwarded to Base (base_url:, params: {client_id:, scope:}, etc.)
19
+ # @param base_params [Hash] Forwarded to Base (base_url:, params: {client_id:, scope:}, etc.)
17
20
  def initialize(cookie: nil, username: nil, **base_params)
18
21
  if cookie.nil?
19
22
  # No cookie: rely on existing cache, identified by username if provided
@@ -1,10 +1,15 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/id_generator'
4
- require 'aspera/assert'
5
- require 'aspera/string_ext'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../../id_generator'
7
+ require_relative '../../assert'
8
+ require_relative '../../string_ext'
6
9
  require 'singleton'
7
10
  require 'base64'
11
+ require 'json'
12
+ require 'time'
8
13
  module Aspera
9
14
  module OAuth
10
15
  # Factory to create tokens and manage their cache
@@ -20,8 +25,13 @@ module Aspera
20
25
  # prefix for bearer authorization when in header
21
26
  SPACE_BEARER_AUTH_SCHEME = 'Bearer '
22
27
  TOKEN_FIELD = 'access_token'
28
+ # Separator of the path of a nested token field, e.g. `authed_user.access_token`
29
+ FIELD_PATH_SEPARATOR = '.'
30
+ # fields added to the cached token creation response
31
+ OBTAINED_AT_FIELD = 'obtained_at'
32
+ EXPIRES_AT_FIELD = 'expires_at'
23
33
 
24
- private_constant :PERSIST_CATEGORY_TOKEN, :SPACE_BEARER_AUTH_SCHEME
34
+ private_constant :PERSIST_CATEGORY_TOKEN, :SPACE_BEARER_AUTH_SCHEME, :FIELD_PATH_SEPARATOR
25
35
 
26
36
  class << self
27
37
  # Format a token for use in Authorization header
@@ -55,6 +65,14 @@ module Aspera
55
65
  return IdGenerator.from_list(PERSIST_CATEGORY_TOKEN, url, Factory.class_to_id(creator_class), params)
56
66
  end
57
67
 
68
+ # Value of the token in a token creation response
69
+ # @param token_data [Hash{String => Object}] Token creation response
70
+ # @param token_field [String] Field that contains the token, or dot-separated path of a nested field, e.g. `authed_user.access_token`
71
+ # @return [Object, nil] Value of the field, `nil` if absent (or an intermediate value is not a Hash)
72
+ def token_value(token_data, token_field)
73
+ token_field.split(FIELD_PATH_SEPARATOR).reduce(token_data) { |data, key| data.is_a?(Hash) ? data[key] : nil }
74
+ end
75
+
58
76
  # Convert a class name to snake_case symbol
59
77
  # @param creator_class [Class] The class to convert
60
78
  # @return [Symbol] snake_case version of class name
@@ -78,7 +96,9 @@ module Aspera
78
96
  # tokens older than this duration in sec. will be discarded from cache
79
97
  token_cache_max_age: 1800,
80
98
  # tokens valid for less than this duration in sec. will be regenerated
81
- token_refresh_threshold: 120
99
+ token_refresh_threshold: 120,
100
+ # tokens obtained since more than this duration in sec. will be regenerated (0: no limit)
101
+ token_refresh_max_age: 0
82
102
  }
83
103
  end
84
104
 
@@ -130,29 +150,32 @@ module Aspera
130
150
 
131
151
  # Get token information from cache
132
152
  # @param id [String] identifier of token
133
- # @param token_field [String, nil] Field containing the token, or nil to auto-detect
153
+ # @param token_field [String, nil] Field containing the token (or dot-separated path), or nil to auto-detect
134
154
  # @return [Hash] token internal information , including Date object for `expiration_date`
135
155
  def get_token_info(id, token_field: nil)
136
156
  token_raw_string = persist_mgr.get(id)
137
157
  return if token_raw_string.nil?
138
158
  token_data = JSON.parse(token_raw_string)
139
159
  Aspera.assert_type(token_data, Hash)
140
- token_value = token_data[token_field] || token_data[TOKEN_FIELD] || token_data['token']
160
+ token_value = (self.class.token_value(token_data, token_field) unless token_field.nil?) || token_data[TOKEN_FIELD] || token_data['token']
141
161
  decoded_token = decode_token(token_value)
142
162
  info = {data: token_data}
143
- if decoded_token.is_a?(Hash)
144
- info[:decoded] = decoded_token
145
- # TODO: move date decoding to token decoder ?
146
- expiration_date =
147
- if decoded_token['expires_at'].is_a?(String) then Time.parse(decoded_token['expires_at']).to_time
148
- elsif decoded_token['exp'].is_a?(Integer) then Time.at(decoded_token['exp'])
149
- end
150
- unless expiration_date.nil?
151
- info[:expiration] = expiration_date
152
- info[:ttl_sec] = expiration_date - Time.now
153
- info[:expired] = info[:ttl_sec] < @parameters[:token_refresh_threshold]
163
+ info[:decoded] = decoded_token if decoded_token.is_a?(Hash)
164
+ # TODO: move date decoding to token decoder ?
165
+ expiration_date =
166
+ if decoded_token.is_a?(Hash) && decoded_token['expires_at'].is_a?(String) then Time.parse(decoded_token['expires_at'])
167
+ elsif decoded_token.is_a?(Hash) && decoded_token['exp'].is_a?(Integer) then Time.at(decoded_token['exp'])
168
+ elsif token_data[EXPIRES_AT_FIELD].is_a?(String) then Time.parse(token_data[EXPIRES_AT_FIELD])
154
169
  end
170
+ unless expiration_date.nil?
171
+ info[:expiration] = expiration_date
172
+ info[:ttl_sec] = expiration_date - Time.now
173
+ info[:expired] = info[:ttl_sec] < @parameters[:token_refresh_threshold]
155
174
  end
175
+ # Force refresh of an old token, e.g. before its refresh token expires
176
+ max_age = @parameters[:token_refresh_max_age].to_i
177
+ obtained_at = token_data[OBTAINED_AT_FIELD]
178
+ info[:expired] = true if max_age.positive? && obtained_at.is_a?(String) && Time.now - Time.parse(obtained_at) > max_age
156
179
  Log.dump(:token_info, info)
157
180
  return info
158
181
  end
@@ -1,6 +1,10 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/oauth/client/base'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'base'
7
+ require_relative 'factory'
4
8
 
5
9
  module Aspera
6
10
  module OAuth
@@ -1,6 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/oauth/client/base'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'base'
4
7
  require 'digest'
5
8
 
6
9
  module Aspera
@@ -19,9 +22,10 @@ module Aspera
19
22
  end
20
23
 
21
24
  def create_token
22
- api.call(
25
+ token_api, subpath = endpoint_api(path_token)
26
+ token_api.call(
23
27
  operation: 'POST',
24
- subpath: path_token,
28
+ subpath: subpath,
25
29
  content_type: Mime::JSON,
26
30
  body: @body,
27
31
  headers: {'Accept' => Mime::JSON},
@@ -1,8 +1,11 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/oauth/client/base'
4
- require 'aspera/environment'
5
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'base'
7
+ require_relative '../../environment'
8
+ require_relative '../../assert'
6
9
  require 'securerandom'
7
10
  require 'openssl'
8
11
  module Aspera
@@ -0,0 +1,94 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'web'
7
+ require_relative '../../sealed_hash'
8
+ require_relative '../../cli/info'
9
+ require_relative '../../cli/prompt'
10
+ require 'securerandom'
11
+
12
+ module Aspera
13
+ module OAuth
14
+ # Authentication of a SAML user of Aspera Shares using a Web browser.
15
+ #
16
+ # Shares has no OAuth authorization endpoint: the OAuth tokens of the user (same as those of `<url>/auth/oauth2/token`) are given by the SAML login page
17
+ # (`<url>/auth/saml`), once the user is authenticated. The way depends on option `ui.web_auth`:
18
+ # - `port` (default): `RelayState` is the loopback URL, Shares redirects the browser to it with the tokens in the query. It is automatic.
19
+ # - `paste`: `RelayState` is `aspera://device-code?state=<state>`, Shares shows a code that the user pastes in the terminal.
20
+ # No local port is used, the browser can be on any system.
21
+ # The refresh token received (in the URL, or in the code) is immediately exchanged for a new token: the tokens that went through the browser are not valid any more.
22
+ class SharesWeb < Web
23
+ # `RelayState` that tells Shares to show the code (`paste`)
24
+ DEVICE_CODE_RELAY_STATE = 'aspera://device-code?state='
25
+
26
+ # @param redirect_uri [String] Loopback URL that receives the tokens (`port`)
27
+ # @param path_authorize [String] Path to the SAML login page, from the base URL
28
+ # @param base_params [Hash] Parameters for base class: `base_url` is `<url>/auth`, `path_token` is `oauth2/token`
29
+ def initialize(redirect_uri:, path_authorize: 'saml', **base_params)
30
+ # Shares needs a path in the loopback URL, and the local server expects it
31
+ uri = URI.parse(redirect_uri)
32
+ uri.path = '/' if uri.path.empty?
33
+ super(redirect_uri: uri.to_s, path_authorize: path_authorize, path_token: 'oauth2/token', **base_params)
34
+ end
35
+
36
+ def create_token
37
+ # state is returned unchanged by Shares: it ties the answer to this login
38
+ random_state = SecureRandom.uuid
39
+ received_params =
40
+ case Environment.instance.web_auth
41
+ when :paste then receive_code(random_state)
42
+ when :port then receive_on_loopback(random_state)
43
+ else Aspera.error_unexpected_value(Environment.instance.web_auth) { 'ui.web_auth' }
44
+ end
45
+ Aspera.assert(random_state.eql?(received_params['state'])) { 'wrong received state' }
46
+ refresh_token = received_params['refresh_token'].to_s
47
+ Aspera.assert(!refresh_token.empty?) { 'No token received: does this Shares have the login patch for ascli?' }
48
+ Secret::Hider.instance.add_secret_values(refresh_token, received_params['access_token'].to_s)
49
+ create_token_base(grant_type: 'refresh_token', refresh_token: refresh_token)
50
+ end
51
+
52
+ private
53
+
54
+ # `port`: the browser is redirected to the loopback URL, which has the state in its query
55
+ # @return [Hash{String=>String}] Query received
56
+ def receive_on_loopback(state)
57
+ login_page_url = login_page(Rest.build_uri(@redirect_uri, state: state).to_s)
58
+ # the page shows where the user is logged in
59
+ login_receiver = WebAuth.receiver(@redirect_uri, [Web.additional_info, URI.parse(api.base_url).host].compact.join(' - '))
60
+ Environment.instance.open_uri(login_page_url)
61
+ login_receiver.received_request
62
+ end
63
+
64
+ # `paste`: Shares shows a code, to paste in the terminal
65
+ # The prompt shows if the code is valid, and asks again if not.
66
+ # @return [Hash{String=>String}] Content of the code
67
+ def receive_code(state)
68
+ Environment.instance.open_uri(login_page("#{DEVICE_CODE_RELAY_STATE}#{state}"))
69
+ Log.log.warn { 'USER ACTION: Log in with the web browser, then copy the code displayed by Shares and paste it in the prompt below.' }
70
+ code = Cli::Prompt.prompt_user_input('Code', sensitive: true, validate: ->(text) { unseal_code(text, state) })
71
+ unseal_code(code, state)
72
+ end
73
+
74
+ # The state is part of the key of the code: the code is not readable without it
75
+ # @param text [String] Pasted by the user
76
+ # @param state [String] State of this login
77
+ # @return [Hash{String=>String}] Content of the code
78
+ # @raise [ParameterError] if the text is not a valid code of this login (or it is expired)
79
+ def unseal_code(text, state)
80
+ Aspera.assert(SealedHash.sealed?(text), type: ParameterError) { 'Not a code: copy the code displayed by Shares after login' }
81
+ SealedHash.unseal(text, secret: state, base_key: Cli::Info::CMD_NAME)
82
+ end
83
+
84
+ # @param relay_state [String] Where Shares sends the result
85
+ # @return [String] URL of the SAML login page
86
+ def login_page(relay_state)
87
+ url = Rest.build_uri("#{api.base_url}/#{@path_authorize}", RelayState: relay_state)
88
+ Log.log.debug { "login_page_url=#{url}" }
89
+ url
90
+ end
91
+ end
92
+ Factory.instance.register_token_creator(SharesWeb)
93
+ end
94
+ end
@@ -1,6 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/oauth/client/base'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'base'
4
7
 
5
8
  module Aspera
6
9
  module OAuth
@@ -20,9 +23,10 @@ module Aspera
20
23
  end
21
24
 
22
25
  def create_token
23
- api.call(
26
+ token_api, subpath = endpoint_api(path_token)
27
+ token_api.call(
24
28
  operation: 'POST',
25
- subpath: path_token,
29
+ subpath: subpath,
26
30
  query: @query.merge(scope: params[:scope]), # scope is here because it may change over time (node)
27
31
  content_type: Mime::JSON,
28
32
  body: @body,
@@ -1,26 +1,43 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/oauth/client/base'
4
- require 'aspera/environment'
5
- require 'aspera/web_auth/server'
6
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'base'
7
+ require_relative '../../environment'
8
+ require_relative '../../web_auth/receiver'
9
+ require_relative '../../assert'
10
+ require 'base64'
11
+ require 'digest'
12
+ require 'securerandom'
7
13
  module Aspera
8
14
  module OAuth
9
15
  # Authentication using Web browser
10
16
  class Web < Base
17
+ # PKCE code challenge method (RFC 7636 §4.2)
18
+ PKCE_METHOD = 'S256'
11
19
  class << self
12
20
  attr_accessor :additional_info
21
+
22
+ # @param verifier [String] PKCE code verifier
23
+ # @return [String] PKCE S256 code challenge: BASE64URL(SHA256(verifier)), without padding (RFC 7636 §4.2)
24
+ def pkce_challenge(verifier)
25
+ Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
26
+ end
13
27
  end
14
- # @param redirect_uri [String] url to receive the code after auth (to be exchanged for token)
15
- # @param path_authorize [String] path to login page on web app
28
+ # @param redirect_uri [String] url to receive the code after auth (to be exchanged for token)
29
+ # @param path_authorize [String] path to login page on web app, or absolute URL (`http` or `https`), e.g. on another host than the token
30
+ # @param pkce [Boolean] use PKCE (RFC 7636): the code can be exchanged only by this process
16
31
  def initialize(
17
32
  redirect_uri:,
18
33
  path_authorize: 'authorize',
34
+ pkce: false,
19
35
  **base_params
20
36
  )
21
37
  super(**base_params)
22
38
  @redirect_uri = redirect_uri
23
39
  @path_authorize = path_authorize
40
+ @pkce = pkce
24
41
  uri = URI.parse(@redirect_uri)
25
42
  Aspera.assert_values(uri.scheme, %w[http https]) { 'redirect_uri scheme must be http or https' }
26
43
  Aspera.assert(!uri.port.nil?, 'redirect_uri must have a port')
@@ -30,25 +47,35 @@ module Aspera
30
47
  def create_token
31
48
  # generate secure state to check later
32
49
  random_state = SecureRandom.uuid
50
+ authorize_params = {response_type: 'code', redirect_uri: @redirect_uri, state: random_state}
51
+ token_params = {}
52
+ if @pkce
53
+ # 32 random bytes: 43 characters of base64url, within the 43..128 allowed (RFC 7636 §4.1)
54
+ code_verifier = SecureRandom.urlsafe_base64(32)
55
+ authorize_params[:code_challenge] = self.class.pkce_challenge(code_verifier)
56
+ authorize_params[:code_challenge_method] = PKCE_METHOD
57
+ token_params[:code_verifier] = code_verifier
58
+ end
33
59
  login_page_url = Rest.build_uri(
34
- "#{api.base_url}/#{@path_authorize}",
35
- base_parameters(response_type: 'code', redirect_uri: @redirect_uri, state: random_state)
60
+ endpoint_url(@path_authorize),
61
+ base_parameters(**authorize_params)
36
62
  )
37
63
  # here, we need a human to authorize on a web page
38
64
  Log.log.debug { "login_page_url=#{login_page_url}" }
39
- # start a web server to receive request code
40
- web_server = WebAuth::Server.new(@redirect_uri, self.class.additional_info)
65
+ # receive the code: local web server, or redirect URL pasted by the user (see option ui.web_auth)
66
+ login_receiver = WebAuth.receiver(@redirect_uri, self.class.additional_info, login_url: login_page_url, reply_keys: %w[code state])
41
67
  # start browser on login page
42
- Environment.instance.open_uri(login_page_url)
68
+ WebAuth.open_login_page(login_receiver, login_page_url)
43
69
  # wait for code in request
44
- received_params = web_server.received_request
70
+ received_params = login_receiver.received_request
45
71
  Aspera.assert(random_state.eql?(received_params['state'])) { 'wrong received state' }
46
72
  # exchange code for token
47
73
  create_token_base(
48
74
  include_secret: true,
49
75
  grant_type: 'authorization_code',
50
76
  code: received_params['code'],
51
- redirect_uri: @redirect_uri
77
+ redirect_uri: @redirect_uri,
78
+ **token_params
52
79
  )
53
80
  end
54
81
  end
@@ -1,11 +1,12 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- # cspell:ignore pkce urlsafe
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
4
5
 
5
- require 'aspera/log'
6
- require 'aspera/assert'
7
- require 'aspera/web_page'
8
- require 'aspera/servlet_helpers'
6
+ require_relative '../../log'
7
+ require_relative '../../assert'
8
+ require_relative '../../web_page'
9
+ require_relative '../../servlet_helpers'
9
10
  require 'json'
10
11
  require 'securerandom'
11
12
  require 'uri'