aspera-cli 4.27.5 → 4.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (249) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +301 -4
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +139 -58
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +10 -7
  13. data/docs/README.md +2551 -772
  14. data/docs/test-mcp-with-ai.md +13 -11
  15. data/lib/aspera/agent/base.rb +23 -2
  16. data/lib/aspera/agent/connect.rb +16 -12
  17. data/lib/aspera/agent/desktop.rb +10 -7
  18. data/lib/aspera/agent/direct.rb +34 -22
  19. data/lib/aspera/agent/factory.rb +8 -4
  20. data/lib/aspera/agent/httpgw.rb +7 -5
  21. data/lib/aspera/agent/node.rb +15 -7
  22. data/lib/aspera/agent/transferd.rb +167 -43
  23. data/lib/aspera/api/alee.rb +4 -1
  24. data/lib/aspera/api/aoc.rb +14 -11
  25. data/lib/aspera/api/ats.rb +4 -2
  26. data/lib/aspera/api/cos_node.rb +8 -5
  27. data/lib/aspera/api/faspex.rb +16 -9
  28. data/lib/aspera/api/httpgw.rb +9 -6
  29. data/lib/aspera/api/node.rb +23 -19
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +84 -42
  32. data/lib/aspera/ascp/log.schema.yaml +1084 -0
  33. data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
  34. data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
  35. data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
  36. data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
  37. data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
  38. data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
  39. data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
  40. data/lib/aspera/ascp/log_analyzer.rb +354 -0
  41. data/lib/aspera/ascp/management.rb +102 -48
  42. data/lib/aspera/ascp/session_errors.rb +217 -0
  43. data/lib/aspera/assert.rb +4 -0
  44. data/lib/aspera/cli/ascp_actions.rb +16 -37
  45. data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
  46. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  47. data/lib/aspera/cli/bootstrapper.rb +37 -34
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +49 -4
  50. data/lib/aspera/cli/command_spec.rb +34 -4
  51. data/lib/aspera/cli/completion/ascli.bash +53 -5
  52. data/lib/aspera/cli/completion/ascli.fish +27 -8
  53. data/lib/aspera/cli/completion/ascli.ps1 +63 -0
  54. data/lib/aspera/cli/completion/ascli.zsh +36 -4
  55. data/lib/aspera/cli/completion_actions.rb +594 -0
  56. data/lib/aspera/cli/context.rb +9 -4
  57. data/lib/aspera/cli/deprecation.rb +5 -2
  58. data/lib/aspera/cli/error.rb +45 -0
  59. data/lib/aspera/cli/extended_value.rb +83 -24
  60. data/lib/aspera/cli/formatter.rb +142 -73
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -11
  63. data/lib/aspera/cli/http.rb +17 -13
  64. data/lib/aspera/cli/info.rb +17 -6
  65. data/lib/aspera/cli/mailer.rb +7 -4
  66. data/lib/aspera/cli/mcp/http_servlet.rb +155 -0
  67. data/lib/aspera/cli/mcp/secrets.rb +146 -0
  68. data/lib/aspera/cli/mcp/tool.rb +232 -0
  69. data/lib/aspera/cli/option_declarator.rb +10 -4
  70. data/lib/aspera/cli/option_registry.rb +6 -3
  71. data/lib/aspera/cli/option_types.rb +17 -2
  72. data/lib/aspera/cli/option_value.rb +72 -11
  73. data/lib/aspera/cli/options.schema.yaml +856 -81
  74. data/lib/aspera/cli/parser.rb +64 -31
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +250 -44
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +51 -25
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +207 -141
  81. data/lib/aspera/cli/plugins/console.rb +9 -4
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +22 -8
  84. data/lib/aspera/cli/plugins/faspex5.rb +37 -44
  85. data/lib/aspera/cli/plugins/faspio.rb +41 -8
  86. data/lib/aspera/cli/plugins/httpgw.rb +8 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +186 -121
  88. data/lib/aspera/cli/plugins/node.rb +41 -34
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +572 -59
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +66 -12
  93. data/lib/aspera/cli/plugins/shares.rb +288 -48
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +155 -33
  96. data/lib/aspera/cli/preset_manager.rb +72 -16
  97. data/lib/aspera/cli/prompt.rb +7 -2
  98. data/lib/aspera/cli/result.rb +28 -11
  99. data/lib/aspera/cli/runner.rb +193 -80
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +204 -0
  102. data/lib/aspera/cli/special_values.rb +4 -1
  103. data/lib/aspera/cli/sync_actions.rb +13 -10
  104. data/lib/aspera/cli/table_fitter.rb +119 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +32 -40
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +31 -19
  108. data/lib/aspera/cli/transfer_progress.rb +13 -45
  109. data/lib/aspera/cli/vault_actions.rb +45 -0
  110. data/lib/aspera/cli/vault_manager.rb +197 -50
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.html.erb +61 -0
  113. data/lib/aspera/cli/web_secret.rb +222 -0
  114. data/lib/aspera/cli/wizard.rb +58 -45
  115. data/lib/aspera/command_line_builder.rb +35 -5
  116. data/lib/aspera/command_line_converter.rb +4 -1
  117. data/lib/aspera/coverage.rb +103 -33
  118. data/lib/aspera/data_repository.rb +42 -25
  119. data/lib/aspera/dot_container.rb +4 -1
  120. data/lib/aspera/duration.rb +45 -0
  121. data/lib/aspera/environment.rb +106 -33
  122. data/lib/aspera/exec_spec.rb +9 -5
  123. data/lib/aspera/faspex_gw.rb +105 -35
  124. data/lib/aspera/faspex_postproc.rb +193 -47
  125. data/lib/aspera/formatter_interface.rb +4 -2
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +6 -3
  129. data/lib/aspera/json_rpc/client.rb +55 -35
  130. data/lib/aspera/json_rpc/version.rb +4 -0
  131. data/lib/aspera/line_logger.rb +4 -1
  132. data/lib/aspera/link_header.rb +4 -1
  133. data/lib/aspera/log.rb +20 -10
  134. data/lib/aspera/markdown.rb +155 -115
  135. data/lib/aspera/mime.rb +9 -0
  136. data/lib/aspera/nagios.rb +9 -5
  137. data/lib/aspera/node_emulator.rb +111 -112
  138. data/lib/aspera/oauth/client/base.rb +163 -0
  139. data/lib/aspera/oauth/{boot.rb → client/boot.rb} +8 -4
  140. data/lib/aspera/oauth/{factory.rb → client/factory.rb} +13 -3
  141. data/lib/aspera/oauth/{generic.rb → client/generic.rb} +5 -1
  142. data/lib/aspera/oauth/{json_credentials.rb → client/json_credentials.rb} +4 -1
  143. data/lib/aspera/oauth/{jwt.rb → client/jwt.rb} +6 -3
  144. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  145. data/lib/aspera/oauth/{url_json.rb → client/url_json.rb} +4 -1
  146. data/lib/aspera/oauth/client/web.rb +84 -0
  147. data/lib/aspera/oauth/server/authorize.html.erb +34 -0
  148. data/lib/aspera/oauth/server/pkce.rb +427 -0
  149. data/lib/aspera/orchestrator_workflow_checker.rb +679 -0
  150. data/lib/aspera/persistency_action_once.rb +5 -3
  151. data/lib/aspera/persistency_folder.rb +6 -3
  152. data/lib/aspera/preview/file_types.rb +6 -3
  153. data/lib/aspera/preview/generator.rb +9 -5
  154. data/lib/aspera/preview/options.schema.yaml +3 -3
  155. data/lib/aspera/preview/terminal.rb +11 -6
  156. data/lib/aspera/preview/utils.rb +6 -4
  157. data/lib/aspera/products/connect.rb +5 -2
  158. data/lib/aspera/products/desktop.rb +4 -1
  159. data/lib/aspera/products/other.rb +4 -2
  160. data/lib/aspera/products/transferd.rb +6 -2
  161. data/lib/aspera/products/transferd_service.rb +610 -0
  162. data/lib/aspera/proxy_auto_config.js +2 -2
  163. data/lib/aspera/proxy_auto_config.rb +5 -2
  164. data/lib/aspera/rainbow.rb +30 -1
  165. data/lib/aspera/rest/aspera_errors.rb +55 -60
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +42 -42
  168. data/lib/aspera/rest/error_analyzer.rb +14 -2
  169. data/lib/aspera/rest/list.rb +14 -10
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +13 -4
  172. data/lib/aspera/rest.rb +9 -7
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -11
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +4089 -0
  175. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml +1097 -0
  176. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  177. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  178. data/lib/aspera/schema/IBM_Aspera_Shares.yaml +819 -7
  179. data/lib/aspera/schema/async_tables.yaml +11 -10
  180. data/lib/aspera/schema/documentation.rb +56 -78
  181. data/lib/aspera/schema/reader.rb +46 -11
  182. data/lib/aspera/schema/registry.rb +45 -24
  183. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  184. data/lib/aspera/schema/validator.rb +4 -1
  185. data/lib/aspera/sealed_hash.rb +166 -0
  186. data/lib/aspera/secret/hider.rb +201 -0
  187. data/lib/aspera/secret/reference.rb +150 -0
  188. data/lib/aspera/secret/resolver.rb +212 -0
  189. data/lib/aspera/secret/store/base.rb +153 -0
  190. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  191. data/lib/aspera/secret/store/factory.rb +103 -0
  192. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  193. data/lib/aspera/secret/store/keeper.rb +141 -0
  194. data/lib/aspera/secret/store/macos_security.rb +284 -0
  195. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  196. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  197. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  198. data/lib/aspera/secret/store/secret_service.rb +125 -0
  199. data/lib/aspera/secret/strength.rb +119 -0
  200. data/lib/aspera/servlet_helpers.rb +114 -0
  201. data/lib/aspera/ssh.rb +10 -7
  202. data/lib/aspera/ssl.rb +5 -2
  203. data/lib/aspera/string_ext.rb +3 -0
  204. data/lib/aspera/sync/args.schema.yaml +6 -1
  205. data/lib/aspera/sync/conf.schema.yaml +25 -10
  206. data/lib/aspera/sync/database.rb +3 -0
  207. data/lib/aspera/sync/operations.rb +34 -12
  208. data/lib/aspera/temp_file_manager.rb +85 -22
  209. data/lib/aspera/timer_limiter.rb +3 -0
  210. data/lib/aspera/transfer/error.rb +4 -1
  211. data/lib/aspera/transfer/faux_file.rb +4 -1
  212. data/lib/aspera/transfer/parameters.rb +22 -14
  213. data/lib/aspera/transfer/result.rb +3 -0
  214. data/lib/aspera/transfer/resumer.rb +6 -4
  215. data/lib/aspera/transfer/spec.rb +45 -18
  216. data/lib/aspera/transfer/spec.schema.yaml +8 -5
  217. data/lib/aspera/transfer/units.rb +75 -0
  218. data/lib/aspera/uri_reader.rb +57 -7
  219. data/lib/aspera/web_auth/index.html.erb +20 -0
  220. data/lib/aspera/web_auth/paste.rb +109 -0
  221. data/lib/aspera/web_auth/receiver.rb +50 -0
  222. data/lib/aspera/web_auth/relay.rb +76 -0
  223. data/lib/aspera/web_auth/reply.html.erb +150 -0
  224. data/lib/aspera/web_auth/server.rb +59 -14
  225. data/lib/aspera/web_page.html.erb +262 -0
  226. data/lib/aspera/web_page.rb +66 -0
  227. data/lib/aspera/web_server_simple.rb +82 -13
  228. data/lib/aspera/yaml.rb +5 -1
  229. data/llms.txt +81 -0
  230. data/skills/ascli/SKILL.md +88 -0
  231. data.tar.gz.sig +0 -0
  232. metadata +116 -48
  233. metadata.gz.sig +0 -0
  234. data/lib/aspera/cli/mcp_tool.rb +0 -189
  235. data/lib/aspera/keychain/base.rb +0 -25
  236. data/lib/aspera/keychain/encrypted_hash.rb +0 -188
  237. data/lib/aspera/keychain/factory.rb +0 -59
  238. data/lib/aspera/keychain/hashicorp_vault.rb +0 -74
  239. data/lib/aspera/keychain/macos_security.rb +0 -171
  240. data/lib/aspera/keychain/one_password_api.rb +0 -86
  241. data/lib/aspera/keychain/one_password_base.rb +0 -34
  242. data/lib/aspera/keychain/one_password_cli.rb +0 -98
  243. data/lib/aspera/oauth/base.rb +0 -141
  244. data/lib/aspera/oauth/web.rb +0 -57
  245. data/lib/aspera/oauth.rb +0 -9
  246. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1.yaml +0 -1784
  247. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0.yaml +0 -249
  248. data/lib/aspera/secret_hider.rb +0 -117
  249. data/lib/aspera/web_auth/index.html +0 -147
@@ -0,0 +1,85 @@
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 state is part of the key of the code: the code is not readable without it
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
+ input = Cli::Prompt.prompt_user_input('Code', sensitive: true)
71
+ Aspera.assert(SealedHash.sealed?(input), type: ParameterError) { 'Not a code: copy the code displayed by Shares after login' }
72
+ SealedHash.unseal(input, secret: state, base_key: Cli::Info::CMD_NAME)
73
+ end
74
+
75
+ # @param relay_state [String] Where Shares sends the result
76
+ # @return [String] URL of the SAML login page
77
+ def login_page(relay_state)
78
+ url = Rest.build_uri("#{api.base_url}/#{@path_authorize}", RelayState: relay_state)
79
+ Log.log.debug { "login_page_url=#{url}" }
80
+ url
81
+ end
82
+ end
83
+ Factory.instance.register_token_creator(SharesWeb)
84
+ end
85
+ end
@@ -1,6 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/oauth/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
@@ -0,0 +1,84 @@
1
+ # frozen_string_literal: true
2
+
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'
13
+ module Aspera
14
+ module OAuth
15
+ # Authentication using Web browser
16
+ class Web < Base
17
+ # PKCE code challenge method (RFC 7636 §4.2)
18
+ PKCE_METHOD = 'S256'
19
+ class << self
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
27
+ end
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
30
+ # @param pkce [Boolean] use PKCE (RFC 7636): the code can be exchanged only by this process
31
+ def initialize(
32
+ redirect_uri:,
33
+ path_authorize: 'authorize',
34
+ pkce: false,
35
+ **base_params
36
+ )
37
+ super(**base_params)
38
+ @redirect_uri = redirect_uri
39
+ @path_authorize = path_authorize
40
+ @pkce = pkce
41
+ uri = URI.parse(@redirect_uri)
42
+ Aspera.assert_values(uri.scheme, %w[http https]) { 'redirect_uri scheme must be http or https' }
43
+ Aspera.assert(!uri.port.nil?, 'redirect_uri must have a port')
44
+ Aspera.assert(WebServerSimple.loopback?(uri.hostname)) { "redirect_uri host must be loopback (localhost, 127.0.0.0/8, ::1): #{uri.host}" }
45
+ end
46
+
47
+ def create_token
48
+ # generate secure state to check later
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
59
+ login_page_url = Rest.build_uri(
60
+ "#{api.base_url}/#{@path_authorize}",
61
+ base_parameters(**authorize_params)
62
+ )
63
+ # here, we need a human to authorize on a web page
64
+ Log.log.debug { "login_page_url=#{login_page_url}" }
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])
67
+ # start browser on login page
68
+ WebAuth.open_login_page(login_receiver, login_page_url)
69
+ # wait for code in request
70
+ received_params = login_receiver.received_request
71
+ Aspera.assert(random_state.eql?(received_params['state'])) { 'wrong received state' }
72
+ # exchange code for token
73
+ create_token_base(
74
+ include_secret: true,
75
+ grant_type: 'authorization_code',
76
+ code: received_params['code'],
77
+ redirect_uri: @redirect_uri,
78
+ **token_params
79
+ )
80
+ end
81
+ end
82
+ Factory.instance.register_token_creator(Web)
83
+ end
84
+ end
@@ -0,0 +1,34 @@
1
+ <%# Content of the consent page, in layout of Aspera::WebPage %>
2
+ <div class="icon-circle">
3
+ <svg xmlns="http://www.w3.org/2000/svg" width="28" height="28" viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
4
+ <rect x="6" y="13" width="20" height="15" rx="3"/>
5
+ <path d="M10 13V9a6 6 0 0 1 12 0v4"/>
6
+ <circle cx="16" cy="20.5" r="2" fill="currentColor"/>
7
+ </svg>
8
+ </div>
9
+
10
+ <h1>Authorization request</h1>
11
+ <p>The client <span class="client"><%= h client_id %></span> is requesting access to <%= description %>.</p>
12
+ <p>The authorization is sent to <span class="client"><%= h redirect_origin %></span>.</p>
13
+ <p>Do you want to allow it?</p>
14
+ <% if error %>
15
+ <p class="error"><%= h error %></p>
16
+ <% end %>
17
+
18
+ <form method="POST" action="<%= h action_url %>">
19
+ <input type="hidden" name="client_id" value="<%= h client_id %>">
20
+ <input type="hidden" name="redirect_uri" value="<%= h redirect_uri %>">
21
+ <input type="hidden" name="state" value="<%= h state %>">
22
+ <input type="hidden" name="code_challenge" value="<%= h code_challenge %>">
23
+ <input type="hidden" name="code_challenge_method" value="<%= h code_challenge_method %>">
24
+ <% if secret_required %>
25
+ <label class="secret">Server access code
26
+ <input type="password" name="consent_secret" autocomplete="current-password" required autofocus>
27
+ </label>
28
+ <% end %>
29
+ <div class="actions">
30
+ <button class="allow" type="submit" name="decision" value="allow">Allow</button>
31
+ <button class="deny" type="submit" name="decision" value="deny" formnovalidate>Deny</button>
32
+ </div>
33
+ </form>
34
+
@@ -0,0 +1,427 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../../log'
7
+ require_relative '../../assert'
8
+ require_relative '../../web_page'
9
+ require_relative '../../servlet_helpers'
10
+ require 'json'
11
+ require 'securerandom'
12
+ require 'uri'
13
+
14
+ module Aspera
15
+ module OAuth
16
+ module Server
17
+ # Minimal OAuth 2.0 authorization server supporting:
18
+ # - Dynamic Client Registration (RFC 7591)
19
+ # - Authorization Code + PKCE (S256) flow (RFC 7636)
20
+ # - Refresh Token rotation
21
+ # - RFC 8414 authorization server metadata discovery
22
+ #
23
+ # Designed to be embedded inside a WEBrick servlet. The caller is
24
+ # responsible for:
25
+ # 1. Creating an instance (once, before the server starts).
26
+ # 2. Routing the five OAuth paths to the handle_* methods.
27
+ # 3. Calling access_token_valid?(bearer_token) to gate every other request.
28
+ #
29
+ # All in-memory stores are protected by an internal Mutex.
30
+ #
31
+ # @example Minimal integration inside a WEBrick servlet
32
+ # @oauth = OAuth::Server::Pkce.new(base_url: 'http://localhost:3000')
33
+ # # inside do_GET / do_POST:
34
+ # case req.path
35
+ # when '/.well-known/oauth-authorization-server' then @oauth.handle_discovery(req, res)
36
+ # when '/oauth/register' then @oauth.handle_register(req, res)
37
+ # when '/oauth/authorize' then @oauth.handle_authorize(req, res)
38
+ # when '/oauth/token' then @oauth.handle_token(req, res)
39
+ # else
40
+ # unless @oauth.access_token_valid?(authorization(req, 'Bearer'))
41
+ # # respond 401 …
42
+ # end
43
+ # end
44
+ class Pkce
45
+ include ServletHelpers
46
+
47
+ ACCESS_TOKEN_TTL = 3600 # 1 hour
48
+ REFRESH_TOKEN_TTL = 2_592_000 # 30 days
49
+ CODE_TTL = 120 # 2 minutes
50
+ # Limits of dynamic client registration, which needs no authentication
51
+ MAX_CLIENTS = 100 # beyond, the least recently used client is removed
52
+ MAX_REDIRECT_URIS = 10
53
+ MAX_REDIRECT_URI_SIZE = 2048
54
+ # Path to the ERB consent page template (relative to this file).
55
+ HTML_TEMPLATE_PATH = File.join(__dir__, 'authorize.html.erb')
56
+
57
+ private_constant :ACCESS_TOKEN_TTL, :REFRESH_TOKEN_TTL, :CODE_TTL, :MAX_CLIENTS, :MAX_REDIRECT_URIS, :MAX_REDIRECT_URI_SIZE, :HTML_TEMPLATE_PATH
58
+
59
+ # Default TTL values, exposed for callers that want to display or override them.
60
+ class << self
61
+ def default_access_token_ttl = ACCESS_TOKEN_TTL
62
+ def default_refresh_token_ttl = REFRESH_TOKEN_TTL
63
+ end
64
+
65
+ # @param base_url [String] Full base URL, e.g. "http://localhost:3000"
66
+ # @param access_token_ttl [Integer] Lifetime (seconds) of issued access tokens
67
+ # @param refresh_token_ttl [Integer] Lifetime (seconds) of issued refresh tokens
68
+ # @param title [String] Page <title> and branding (default: "Authorization request")
69
+ # @param description [String] Description shown in the consent text (default: "this server"), trusted HTML (not escaped)
70
+ # @param consent_secret [String, nil] If set, the user must enter this secret on the consent page to allow access.
71
+ # Without it, anyone who can reach the server can approve its own request.
72
+ # @param authorize_html_cb [#call] Optional callable(params, base_url) → HTML String
73
+ # for the consent page. If nil the built-in HTML template is used.
74
+ # With `consent_secret`, the form must post it in field `consent_secret`.
75
+ def initialize(base_url:, access_token_ttl: ACCESS_TOKEN_TTL, refresh_token_ttl: REFRESH_TOKEN_TTL,
76
+ title: 'Authorization request', description: 'this server',
77
+ consent_secret: nil, authorize_html_cb: nil)
78
+ require 'openssl'
79
+ Aspera.assert(consent_secret.nil? || !consent_secret.to_s.empty?) { 'consent_secret must not be empty' }
80
+ @base_url = base_url
81
+ @access_token_ttl = access_token_ttl
82
+ @refresh_token_ttl = refresh_token_ttl
83
+ @title = title
84
+ @description = description
85
+ @consent_secret = consent_secret&.to_s
86
+ @authorize_html_cb = authorize_html_cb
87
+ @store_mutex = Mutex.new
88
+ # dynamically registered clients: client_id => redirect_uris, least recently used first
89
+ @clients = {}
90
+ # pending authorization codes: code => {client_id:, redirect_uri:, code_challenge:, expires_at:}
91
+ @pending_codes = {}
92
+ # valid access tokens: token => expires_at (Time)
93
+ @access_tokens = {}
94
+ # refresh tokens: token => {access_token:, expires_at:}
95
+ @refresh_tokens = {}
96
+ end
97
+
98
+ # -------------------------------------------------------------------------
99
+ # Authorization check
100
+ # -------------------------------------------------------------------------
101
+
102
+ # @param access_token [String, nil] Bearer token of the request, see ServletHelpers#authorization
103
+ # @return [Boolean] true if it is an access token issued by this server, not expired
104
+ def access_token_valid?(access_token)
105
+ return false if access_token.nil?
106
+ @store_mutex.synchronize do
107
+ expire_at = @access_tokens[access_token]
108
+ !expire_at.nil? && expire_at > Time.now
109
+ end
110
+ end
111
+
112
+ # -------------------------------------------------------------------------
113
+ # RFC 8414 — authorization server metadata
114
+ # -------------------------------------------------------------------------
115
+
116
+ # Metadata hash (RFC 8414).
117
+ # @return [Hash]
118
+ def metadata
119
+ {
120
+ issuer: @base_url,
121
+ authorization_endpoint: "#{@base_url}/oauth/authorize",
122
+ token_endpoint: "#{@base_url}/oauth/token",
123
+ registration_endpoint: "#{@base_url}/oauth/register",
124
+ response_types_supported: ['code'],
125
+ grant_types_supported: %w[authorization_code refresh_token],
126
+ code_challenge_methods_supported: ['S256'],
127
+ token_endpoint_auth_methods_supported: ['none']
128
+ }
129
+ end
130
+
131
+ # GET /.well-known/oauth-authorization-server
132
+ def handle_discovery(_req, res)
133
+ json_response(res, 200, metadata)
134
+ end
135
+
136
+ # -------------------------------------------------------------------------
137
+ # Dynamic Client Registration — RFC 7591
138
+ # -------------------------------------------------------------------------
139
+
140
+ # POST /oauth/register
141
+ def handle_register(req, res)
142
+ body = req.body.to_s.empty? ? {} : (JSON.parse(req.body.to_s) rescue {})
143
+ body = {} unless body.is_a?(Hash)
144
+ redirect_uris = body['redirect_uris']
145
+ error = redirect_uris_error(redirect_uris)
146
+ unless error.nil?
147
+ json_error(res, 400, 'invalid_redirect_uri', error)
148
+ return
149
+ end
150
+ client_id = SecureRandom.urlsafe_base64(16)
151
+ @store_mutex.synchronize do
152
+ while @clients.size >= MAX_CLIENTS
153
+ removed_id, = @clients.shift
154
+ Log.log.info { "OAuth client removed, limit of #{MAX_CLIENTS} clients reached: client_id=#{removed_id}" }
155
+ end
156
+ @clients[client_id] = redirect_uris
157
+ end
158
+ Log.log.info { "OAuth dynamic registration: client_id=#{client_id} name=#{body['client_name'].to_s[0, 64].inspect}" }
159
+ registration = {
160
+ client_id: client_id,
161
+ client_id_issued_at: Time.now.to_i,
162
+ grant_types: %w[authorization_code refresh_token],
163
+ response_types: ['code'],
164
+ token_endpoint_auth_method: 'none',
165
+ redirect_uris: redirect_uris
166
+ }
167
+ json_response(res, 201, registration, headers: {'Cache-Control' => 'no-store'})
168
+ end
169
+
170
+ # -------------------------------------------------------------------------
171
+ # Authorization endpoint — RFC 6749 §4.1
172
+ # -------------------------------------------------------------------------
173
+
174
+ # GET or POST /oauth/authorize — dispatch based on request method.
175
+ def handle_authorize(req, res)
176
+ if req.request_method == 'GET'
177
+ handle_authorize_get(req, res)
178
+ elsif req.request_method == 'POST'
179
+ handle_authorize_post(req, res)
180
+ else
181
+ json_error(res, 405, 'method_not_allowed')
182
+ end
183
+ end
184
+
185
+ # -------------------------------------------------------------------------
186
+ # Token endpoint — RFC 6749 §4.1 / §6
187
+ # -------------------------------------------------------------------------
188
+
189
+ # POST /oauth/token
190
+ def handle_token(req, res)
191
+ require 'webrick'
192
+ params = WEBrick::HTTPUtils.parse_query(req.body.to_s)
193
+ grant_type = params['grant_type']
194
+ case grant_type
195
+ when 'authorization_code'
196
+ code = params['code']
197
+ code_verifier = params['code_verifier']
198
+ stored = @store_mutex.synchronize { @pending_codes.delete(code) }
199
+ if stored.nil? || stored[:expires_at] < Time.now
200
+ json_error(res, 400, 'invalid_grant', 'Authorization code expired or unknown')
201
+ return
202
+ end
203
+ # RFC 6749 §4.1.3: the code must have been issued to this client (client_id is optional with PKCE)
204
+ unless params['client_id'].nil? || params['client_id'] == stored[:client_id]
205
+ json_error(res, 400, 'invalid_grant', 'client_id mismatch')
206
+ return
207
+ end
208
+ # RFC 6749 §4.1.3: redirect_uri must match the one used in the authorization request
209
+ unless params['redirect_uri'] == stored[:redirect_uri]
210
+ json_error(res, 400, 'invalid_grant', 'redirect_uri mismatch')
211
+ return
212
+ end
213
+ unless pkce_valid?(code_verifier.to_s, stored[:code_challenge])
214
+ json_error(res, 400, 'invalid_grant', 'PKCE verification failed')
215
+ return
216
+ end
217
+ token_response(res)
218
+ when 'refresh_token'
219
+ rt_value = params['refresh_token']
220
+ stored = @store_mutex.synchronize do
221
+ # Single use: removed even if expired
222
+ entry = @refresh_tokens.delete(rt_value)
223
+ next nil if entry.nil? || entry[:expires_at] < Time.now
224
+ # Rotate: revoke old access token and issue fresh pair
225
+ @access_tokens.delete(entry[:access_token])
226
+ entry
227
+ end
228
+ if stored.nil?
229
+ json_error(res, 400, 'invalid_grant', 'Refresh token expired or unknown')
230
+ return
231
+ end
232
+ token_response(res)
233
+ else
234
+ json_error(res, 400, 'unsupported_grant_type', "Unsupported grant_type: #{grant_type}")
235
+ end
236
+ end
237
+
238
+ # -------------------------------------------------------------------------
239
+ # WWW-Authenticate header value for 401 responses
240
+ # -------------------------------------------------------------------------
241
+
242
+ # @return [String] value for the WWW-Authenticate header
243
+ def www_authenticate_header
244
+ "Bearer realm=\"#{@base_url}\", " \
245
+ "resource_metadata=\"#{@base_url}/.well-known/oauth-authorization-server\""
246
+ end
247
+
248
+ private
249
+
250
+ # -------------------------------------------------------------------------
251
+ # Internal helpers
252
+ # -------------------------------------------------------------------------
253
+
254
+ # @param redirect_uris [Object] Value of `redirect_uris` in the registration request
255
+ # @return [String, nil] Reason why `redirect_uris` is refused, `nil` if valid
256
+ def redirect_uris_error(redirect_uris)
257
+ return 'redirect_uris must be a non-empty array of strings' unless redirect_uris.is_a?(Array) && !redirect_uris.empty? && redirect_uris.all?(String)
258
+ return "redirect_uris must have at most #{MAX_REDIRECT_URIS} values" if redirect_uris.length > MAX_REDIRECT_URIS
259
+ redirect_uris.each do |redirect_uri|
260
+ return "redirect_uri must have at most #{MAX_REDIRECT_URI_SIZE} characters" if redirect_uri.length > MAX_REDIRECT_URI_SIZE
261
+ # RFC 6749 §3.1.2: absolute URI, without fragment
262
+ uri = URI.parse(redirect_uri) rescue nil
263
+ return "redirect_uri must be an absolute URI without fragment: #{redirect_uri}" if uri.nil? || !uri.absolute? || !uri.fragment.nil?
264
+ end
265
+ nil
266
+ end
267
+
268
+ # The client is also marked as the most recently used one
269
+ # @return [Boolean] true if client is registered and redirect_uri is one of its registered URIs (exact match)
270
+ def client_redirect_valid?(client_id, redirect_uri)
271
+ @store_mutex.synchronize do
272
+ redirect_uris = @clients.delete(client_id)
273
+ next false if redirect_uris.nil?
274
+ @clients[client_id] = redirect_uris
275
+ redirect_uris.include?(redirect_uri)
276
+ end
277
+ end
278
+
279
+ # @param redirect_uri [String] Redirect URI of the authorization request
280
+ # @return [String] Where the code is sent: origin of `redirect_uri`, or `redirect_uri` if it has no host
281
+ def redirect_origin(redirect_uri)
282
+ URI.parse(redirect_uri).host.to_s.empty? ? redirect_uri : ServletHelpers.origin(redirect_uri)
283
+ rescue URI::InvalidURIError
284
+ redirect_uri
285
+ end
286
+
287
+ # Build redirect URL to client, preserving any query already present in redirect_uri.
288
+ def client_redirect_url(redirect_uri, **params)
289
+ query = params.reject { |_, v| v.to_s.empty? }.map { |k, v| "#{k}=#{WEBrick::HTTPUtils.escape_form(v.to_s)}" }.join('&')
290
+ "#{redirect_uri}#{redirect_uri.include?('?') ? '&' : '?'}#{query}"
291
+ end
292
+
293
+ def purge_expired
294
+ now = Time.now
295
+ @pending_codes.delete_if { |_, v| v[:expires_at] < now }
296
+ @access_tokens.delete_if { |_, exp| exp < now }
297
+ @refresh_tokens.delete_if { |_, v| v[:expires_at] < now }
298
+ end
299
+
300
+ def issue_tokens
301
+ access = SecureRandom.urlsafe_base64(32)
302
+ refresh = SecureRandom.urlsafe_base64(48)
303
+ now = Time.now
304
+ @store_mutex.synchronize do
305
+ purge_expired
306
+ @access_tokens[access] = now + @access_token_ttl
307
+ @refresh_tokens[refresh] = {access_token: access, expires_at: now + @refresh_token_ttl}
308
+ end
309
+ {
310
+ access_token: access,
311
+ token_type: 'Bearer',
312
+ expires_in: @access_token_ttl,
313
+ refresh_token: refresh
314
+ }
315
+ end
316
+
317
+ def token_response(res)
318
+ json_response(res, 200, issue_tokens, headers: {'Cache-Control' => 'no-store'})
319
+ end
320
+
321
+ # Verify PKCE: SHA-256(code_verifier) == code_challenge (base64url, no padding).
322
+ def pkce_valid?(verifier, challenge)
323
+ return false unless challenge.is_a?(String) && !challenge.empty?
324
+ require 'base64'
325
+ digest = OpenSSL::Digest::SHA256.digest(verifier)
326
+ computed = Base64.urlsafe_encode64(digest, padding: false)
327
+ OpenSSL.secure_compare(computed, challenge)
328
+ end
329
+
330
+ def handle_authorize_get(req, res)
331
+ require 'webrick'
332
+ params = req.query
333
+ client_id = params['client_id']
334
+ unless client_redirect_valid?(client_id, params['redirect_uri'])
335
+ json_error(res, 400, 'unauthorized_client', "Unknown client_id or unregistered redirect_uri: #{client_id}")
336
+ return
337
+ end
338
+ unless pkce_requested?(params)
339
+ json_error(res, 400, 'invalid_request', 'PKCE with S256 is required')
340
+ return
341
+ end
342
+ consent_page(res, params)
343
+ end
344
+
345
+ # @return [Boolean] true if the request carries a S256 PKCE challenge
346
+ def pkce_requested?(params)
347
+ !params['code_challenge'].to_s.empty? && params['code_challenge_method'] == 'S256'
348
+ end
349
+
350
+ # Respond with the consent page
351
+ # @param params [Hash] Parameters of the authorization request
352
+ # @param status [Integer] HTTP status
353
+ # @param error [String, nil] Error message displayed on the page
354
+ def consent_page(res, params, status: 200, error: nil)
355
+ res.status = status
356
+ WebPage.secure_headers(res)
357
+ res.body = if @authorize_html_cb
358
+ @authorize_html_cb.call(params, @base_url)
359
+ else
360
+ authorize_html_from_template(params, error: error)
361
+ end
362
+ end
363
+
364
+ def handle_authorize_post(req, res)
365
+ require 'webrick'
366
+ params = WEBrick::HTTPUtils.parse_query(req.body.to_s)
367
+ client_id = params['client_id']
368
+ redirect_uri = params['redirect_uri']
369
+ state = params['state']
370
+ decision = params['decision']
371
+ # Validate client and redirect_uri before any redirect (prevents open redirect)
372
+ unless client_redirect_valid?(client_id, redirect_uri)
373
+ json_error(res, 400, 'unauthorized_client', "Unknown client_id or unregistered redirect_uri: #{client_id}")
374
+ return
375
+ end
376
+ if decision != 'allow'
377
+ res.status = 302
378
+ res['Location'] = client_redirect_url(redirect_uri, error: 'access_denied', state: state)
379
+ return
380
+ end
381
+ unless pkce_requested?(params)
382
+ res.status = 302
383
+ res['Location'] = client_redirect_url(redirect_uri, error: 'invalid_request', error_description: 'PKCE with S256 is required', state: state)
384
+ return
385
+ end
386
+ # The consent secret proves that the user approving the request is allowed to grant access
387
+ if @consent_secret && !OpenSSL.secure_compare(params['consent_secret'].to_s, @consent_secret)
388
+ Log.log.warn { "OAuth consent refused: wrong access code for client_id=#{client_id}" }
389
+ consent_page(res, params, status: 401, error: 'Invalid access code')
390
+ return
391
+ end
392
+ code = SecureRandom.urlsafe_base64(24)
393
+ @store_mutex.synchronize do
394
+ purge_expired
395
+ @pending_codes[code] = {
396
+ client_id: client_id,
397
+ redirect_uri: redirect_uri,
398
+ code_challenge: params['code_challenge'],
399
+ expires_at: Time.now + CODE_TTL
400
+ }
401
+ end
402
+ res.status = 302
403
+ res['Location'] = client_redirect_url(redirect_uri, code: code, state: state)
404
+ end
405
+
406
+ # Render the consent page from the ERB template.
407
+ # @param error [String, nil] Error message displayed on the page
408
+ def authorize_html_from_template(params, error: nil)
409
+ WebPage.render(
410
+ HTML_TEMPLATE_PATH,
411
+ title: @title,
412
+ description: @description,
413
+ action_url: "#{@base_url}/oauth/authorize",
414
+ client_id: params['client_id'].to_s,
415
+ redirect_uri: params['redirect_uri'].to_s,
416
+ redirect_origin: redirect_origin(params['redirect_uri'].to_s),
417
+ state: params['state'].to_s,
418
+ code_challenge: params['code_challenge'].to_s,
419
+ code_challenge_method: params['code_challenge_method'].to_s,
420
+ secret_required: !@consent_secret.nil?,
421
+ error: error
422
+ )
423
+ end
424
+ end
425
+ end
426
+ end
427
+ end