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
@@ -0,0 +1,150 @@
1
+ <%# Content of the page displayed after login when the reply is given to the user, to paste in the terminal of ascli, in layout of Aspera::WebPage. Variables: additional_info, code, nonce %>
2
+ <style>
3
+ .code-box {
4
+ display: flex;
5
+ align-items: stretch;
6
+ gap: 0.5rem;
7
+ margin-top: 1.25rem;
8
+ }
9
+
10
+ .code {
11
+ flex: 1;
12
+ min-width: 0;
13
+ padding: 0.6rem 0.75rem;
14
+ text-align: left;
15
+ font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
16
+ font-size: 0.8rem;
17
+ line-height: 1.4;
18
+ letter-spacing: 0.05em;
19
+ word-break: break-all;
20
+ max-height: 9rem;
21
+ overflow-y: auto;
22
+ background: var(--surface);
23
+ color: var(--text);
24
+ border: 1px solid var(--border);
25
+ border-radius: 6px;
26
+ user-select: none;
27
+ }
28
+
29
+ .code.revealed {
30
+ user-select: all;
31
+ }
32
+
33
+ .code-box button.icon {
34
+ flex: none;
35
+ width: 2.75rem;
36
+ padding: 0;
37
+ display: flex;
38
+ align-items: center;
39
+ justify-content: center;
40
+ background: var(--card-bg);
41
+ color: var(--text-secondary);
42
+ border: 1px solid var(--input-border);
43
+ }
44
+
45
+ .code-box button.icon:hover {
46
+ color: var(--accent);
47
+ border-color: var(--accent);
48
+ }
49
+
50
+ .code-box button.icon svg.hide,
51
+ .code-box button.icon.on svg.show {
52
+ display: none;
53
+ }
54
+
55
+ .code-box button.icon.on svg.hide {
56
+ display: block;
57
+ }
58
+
59
+ .status {
60
+ min-height: 1.4rem;
61
+ font-size: 0.85rem;
62
+ color: var(--success);
63
+ }
64
+ </style>
65
+
66
+ <div class="icon-circle ok">
67
+ <svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
68
+ <polyline points="6 16 13 23 26 9"/>
69
+ </svg>
70
+ </div>
71
+
72
+ <h1>Login Complete</h1>
73
+ <p>Copy this code, and paste it in the terminal where <b>ascli</b> waits for it. This code is valid for <%= Aspera::SealedHash::PERIOD / 60 %> minutes. You can then close this window.</p>
74
+
75
+ <% unless additional_info.to_s.empty? %>
76
+ <div class="info-box">
77
+ <%= h additional_info %>
78
+ </div>
79
+ <% end %>
80
+
81
+ <div class="code-box">
82
+ <div id="code" class="code" aria-live="polite">&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;</div>
83
+ <button type="button" id="reveal" class="icon" title="Show the code" aria-label="Show the code" aria-pressed="false">
84
+ <svg class="show" xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
85
+ <path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/>
86
+ <circle cx="12" cy="12" r="3"/>
87
+ </svg>
88
+ <svg class="hide" xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
89
+ <path d="M17.94 17.94A10.07 10.07 0 0 1 12 20c-7 0-11-8-11-8a18.45 18.45 0 0 1 5.06-5.94M9.9 4.24A9.12 9.12 0 0 1 12 4c7 0 11 8 11 8a18.5 18.5 0 0 1-2.16 3.19m-6.72-1.07a3 3 0 1 1-4.24-4.24"/>
90
+ <line x1="1" y1="1" x2="23" y2="23"/>
91
+ </svg>
92
+ </button>
93
+ </div>
94
+ <div class="actions">
95
+ <button type="button" id="copy" class="allow">Copy</button>
96
+ </div>
97
+ <p id="status" class="status" role="status"></p>
98
+
99
+ <%# The code is in this script only, not in the page: it is inserted in the page when the user shows it %>
100
+ <script nonce="<%= h nonce %>">
101
+ (function () {
102
+ var code = <%= JSON.generate(code.to_s).gsub('<', '\u003c') %>;
103
+ var box = document.getElementById('code');
104
+ var mask = box.textContent;
105
+ var reveal = document.getElementById('reveal');
106
+ var status = document.getElementById('status');
107
+ var shown = false;
108
+
109
+ reveal.addEventListener('click', function () {
110
+ shown = !shown;
111
+ box.textContent = shown ? code : mask;
112
+ box.classList.toggle('revealed', shown);
113
+ reveal.classList.toggle('on', shown);
114
+ reveal.setAttribute('aria-pressed', shown ? 'true' : 'false');
115
+ var label = shown ? 'Hide the code' : 'Show the code';
116
+ reveal.title = label;
117
+ reveal.setAttribute('aria-label', label);
118
+ });
119
+
120
+ function legacyCopy() {
121
+ var area = document.createElement('textarea');
122
+ area.value = code;
123
+ area.setAttribute('readonly', '');
124
+ area.style.position = 'fixed';
125
+ area.style.opacity = '0';
126
+ document.body.appendChild(area);
127
+ area.select();
128
+ var ok = false;
129
+ try { ok = document.execCommand('copy'); } catch (e) { ok = false; }
130
+ document.body.removeChild(area);
131
+ return ok;
132
+ }
133
+
134
+ function done(ok) {
135
+ status.style.color = ok ? '' : 'var(--danger)';
136
+ status.textContent = ok ? 'Copied. Paste it in the terminal.' : 'Copy failed: show the code, select it and copy it.';
137
+ }
138
+
139
+ document.getElementById('copy').addEventListener('click', function () {
140
+ if (navigator.clipboard && window.isSecureContext) {
141
+ navigator.clipboard.writeText(code).then(function () { done(true); }, function () { done(legacyCopy()); });
142
+ } else {
143
+ done(legacyCopy());
144
+ }
145
+ });
146
+
147
+ // The callback URL contains a code or tokens: remove the query from the address bar and from the entry of the session history
148
+ if (window.history && history.replaceState) history.replaceState(null, '', location.pathname);
149
+ })();
150
+ </script>
@@ -1,9 +1,16 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/web_server_simple'
4
- require 'aspera/servlet_helpers'
5
- require 'aspera/web_page'
6
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../web_server_simple'
7
+ require_relative '../servlet_helpers'
8
+ require_relative '../web_page'
9
+ require_relative '../sealed_hash'
10
+ require_relative '../cli/info'
11
+ require_relative '../assert'
12
+ require 'json'
13
+ require 'securerandom'
7
14
 
8
15
  module Aspera
9
16
  module WebAuth
@@ -13,7 +20,11 @@ module Aspera
13
20
 
14
21
  # ERB template of page displayed in browser after authentication
15
22
  HTML_TEMPLATE_PATH = File.join(__dir__, 'index.html.erb')
16
- private_constant :HTML_TEMPLATE_PATH
23
+ # ERB template of page displayed in browser after authentication, when the reply is given to the user to paste in a terminal
24
+ REPLY_TEMPLATE_PATH = File.join(__dir__, 'reply.html.erb')
25
+ # Policy of the reply page: it has a secret. Only its own script (with nonce) and style, nothing external
26
+ REPLY_CSP = "default-src 'none'; img-src data:; style-src 'unsafe-inline'; script-src 'nonce-%<nonce>s'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
27
+ private_constant :HTML_TEMPLATE_PATH, :REPLY_TEMPLATE_PATH, :REPLY_CSP
17
28
 
18
29
  # @param server [WEBrick::HTTPServer] the HTTP server instance
19
30
  # @param web_auth [Server] the Server instance to record the callback
@@ -33,25 +44,42 @@ module Aspera
33
44
  Aspera.assert_values(request.path, [@web_auth.expected_path], type: WEBrick::HTTPStatus::NotFound) { "Unsupported path: #{request.path}" }
34
45
  # response to browser
35
46
  response.status = 200
36
- WebPage.secure_headers(response)
37
- response.body = WebPage.render(HTML_TEMPLATE_PATH, title: 'Authentication Complete', additional_info: @web_auth.additional_info)
47
+ if @web_auth.reply_keys.nil?
48
+ WebPage.secure_headers(response)
49
+ response.body = WebPage.render(HTML_TEMPLATE_PATH, title: 'Authentication Complete', additional_info: @web_auth.additional_info)
50
+ else
51
+ render_reply(request, response)
52
+ end
38
53
  # continue internal processing
39
54
  @web_auth.signal_request(request)
40
55
  nil
41
56
  end
57
+
58
+ private
59
+
60
+ # Page that gives the reply to the user: the code to paste in the terminal of the remote ascli
61
+ def render_reply(request, response)
62
+ nonce = SecureRandom.base64(16)
63
+ WebPage.secure_headers(response, content_security_policy: format(REPLY_CSP, nonce: nonce))
64
+ code = SealedHash.seal(request.query.slice(*@web_auth.reply_keys).transform_values(&:to_s), base_key: Cli::Info::CMD_NAME)
65
+ response.body = WebPage.render(REPLY_TEMPLATE_PATH, title: 'Login Complete', additional_info: @web_auth.additional_info, code: code, nonce: nonce)
66
+ end
42
67
  end
43
68
 
44
69
  # start a local web server
45
70
  # then start a browser that will callback the local server upon authentication
46
71
  # store the final query
47
72
  class Server < WebServerSimple
48
- attr_reader :additional_info, :expected_path
73
+ # @return [Array<String>, nil] Keys of the query that the page gives to the user as a code to paste in a terminal, `nil` for the standard page
74
+ attr_reader :additional_info, :expected_path, :reply_keys
49
75
 
50
76
  # @param endpoint_url [String] e.g. 'https://127.0.0.1:12345'
51
77
  # @param additional_info [String] Information in web page
52
- def initialize(endpoint_url, additional_info = nil)
78
+ # @param reply_keys [Array<String>, nil] If set, the page shows to the user a code with these keys of the query, to paste in the terminal of `ascli` that waits for it
79
+ def initialize(endpoint_url, additional_info = nil, reply_keys: nil)
53
80
  uri = URI.parse(endpoint_url)
54
81
  super(uri)
82
+ @reply_keys = reply_keys
55
83
  @mutex = Mutex.new
56
84
  @cond = ConditionVariable.new
57
85
  @expected_path = uri.path.empty? ? '/' : uri.path
@@ -60,7 +88,16 @@ module Aspera
60
88
  # last argument (self) is provided to constructor of servlet
61
89
  mount(@expected_path, Servlet, self)
62
90
  # server runs in thread
63
- Thread.new { start }
91
+ @thread = Thread.new { start }
92
+ end
93
+
94
+ # Wait until the server thread has ended: the response of the last request (page shown to the user) is sent.
95
+ # To call after `received_request`, when the process does not continue with a long operation.
96
+ # @param timeout [Integer] Maximum time to wait, in seconds
97
+ # @return [nil]
98
+ def wait_stopped(timeout = 10)
99
+ @thread.join(timeout)
100
+ nil
64
101
  end
65
102
 
66
103
  # Called by web server thread on received request
@@ -1,5 +1,8 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
3
6
  require 'erb'
4
7
 
5
8
  module Aspera
@@ -41,10 +44,12 @@ module Aspera
41
44
 
42
45
  class << self
43
46
  # Set the headers of an HTML page: type and security headers
44
- # @param response [WEBrick::HTTPResponse]
47
+ # @param response [WEBrick::HTTPResponse]
48
+ # @param content_security_policy [String, nil] Policy that replaces the default one, e.g. to allow a script of the page
45
49
  # @return [nil]
46
- def secure_headers(response)
50
+ def secure_headers(response, content_security_policy: nil)
47
51
  HEADERS.each { |name, value| response[name] = value }
52
+ response['Content-Security-Policy'] = content_security_policy unless content_security_policy.nil?
48
53
  nil
49
54
  end
50
55
 
@@ -1,11 +1,14 @@
1
1
  # frozen_string_literal: true
2
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 'hash_ext'
3
9
  require 'delegate'
4
10
  require 'ipaddr'
5
11
  require 'webrick'
6
- require 'aspera/log'
7
- require 'aspera/assert'
8
- require 'aspera/hash_ext'
9
12
 
10
13
  module Aspera
11
14
  # Simple WEBrick server with HTTPS support
data/lib/aspera/yaml.rb CHANGED
@@ -1,6 +1,10 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'assert'
7
+ require 'date'
4
8
  require 'yaml'
5
9
 
6
10
  module Aspera
data/llms-install.md ADDED
@@ -0,0 +1,88 @@
1
+ # Install the IBM Aspera CLI MCP server
2
+
3
+ Instructions for an AI agent that installs and configures the MCP server of `ascli` (IBM Aspera CLI) for an MCP client.
4
+ Details: [MCP client configuration](https://github.com/IBM/aspera-cli/blob/main/docs/README.md#mcp-client-configuration) in the manual.
5
+
6
+ ## 1. Check Ruby
7
+
8
+ ```shell
9
+ ruby -v
10
+ ```
11
+
12
+ Ruby 3.3 or later is required.
13
+ If Ruby is missing or older, install it first (macOS: `brew install ruby`, Linux: the distribution package or `rbenv`, Windows: RubyInstaller).
14
+
15
+ ## 2. Install the gems
16
+
17
+ Install the published gem from RubyGems, with the optional gem `mcp` (required for `ascli mcp server`).
18
+ Do not build the gem from the source repository, even if it is cloned locally.
19
+
20
+ ```shell
21
+ gem install aspera-cli mcp
22
+ ```
23
+
24
+ Check:
25
+
26
+ ```shell
27
+ ascli -v
28
+ ```
29
+
30
+ `ascli mcp server` starts the server on standard input and output (`stdio`): it waits for an MCP client and does not return.
31
+ To check it outside a client, stop it after the line `Starting MCP server`.
32
+
33
+ ## 3. Add the server to the MCP client
34
+
35
+ Add the server to the configuration file of the MCP client itself (not to VS Code `settings.json`).
36
+ Server name: `ascli`, command: `ascli`, arguments: `mcp server`.
37
+
38
+ Cline: add to `cline_mcp_settings.json` (Cline: MCP Servers > Configure, or Edit Configuration):
39
+
40
+ ```json
41
+ {
42
+ "mcpServers": {
43
+ "ascli": {
44
+ "command": "ascli",
45
+ "args": ["mcp", "server"]
46
+ }
47
+ }
48
+ }
49
+ ```
50
+
51
+ The same `mcpServers` entry applies to Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`) and IBM Bob (`.bob/mcp.json`).
52
+
53
+ VS Code (GitHub Copilot agent mode): add to `.vscode/mcp.json`:
54
+
55
+ ```json
56
+ {
57
+ "servers": {
58
+ "ascli": {
59
+ "type": "stdio",
60
+ "command": "ascli",
61
+ "args": ["mcp", "server"]
62
+ }
63
+ }
64
+ }
65
+ ```
66
+
67
+ Claude Code:
68
+
69
+ ```shell
70
+ claude mcp add ascli -- ascli mcp server
71
+ ```
72
+
73
+ If `ascli` is not found by the client, use the absolute path given by `which ascli` (Windows: `where ascli`) as `command`.
74
+
75
+ ## 4. Verify
76
+
77
+ The client lists the server `ascli`, connected, with the tool `execute_ascli_command`.
78
+
79
+ ## 5. Optional: try it
80
+
81
+ No account needed, the public Aspera demo server:
82
+
83
+ ```shell
84
+ ascli config initdemo
85
+ ```
86
+
87
+ Then ask the AI: "List the files on the Aspera demo server."
88
+ For your own systems, create presets (`ascli config wizard`) and keep secrets in a vault: the AI never sees them.
data/llms.txt ADDED
@@ -0,0 +1,87 @@
1
+ # ascli: command line interface for IBM Aspera
2
+
3
+ > `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
4
+ > An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
5
+ > transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
6
+
7
+ If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
8
+
9
+ ## Products and plugins
10
+
11
+ The first word after `ascli` is a plugin: one per product.
12
+
13
+ - `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
14
+ - `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
15
+ - `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
16
+ - `node`: Node API of a transfer server (files, access keys, transfers, sync)
17
+ - `shares`: IBM Aspera Shares
18
+ - `console`: IBM Aspera Console
19
+ - `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
20
+ - `ats`: IBM Aspera Transfer Service
21
+ - `cos`: IBM Cloud Object Storage
22
+ - `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
23
+ - `preview`: generation of previews of files
24
+ - `transferd`: Transfer Daemon of the Transfer SDK (install, service)
25
+ - `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
26
+ - `mcp`: Model Context Protocol server
27
+
28
+ ## Two ways to use it
29
+
30
+ - Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
31
+ Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
32
+ - MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
33
+ The description of the tool repeats the rules below.
34
+
35
+ ## Discover, do not guess
36
+
37
+ Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
38
+
39
+ 1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
40
+ 2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
41
+ 3. Filter parameters of a list command: `--query=help`.
42
+ 4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
43
+ 5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
44
+
45
+ ## Workflow development
46
+
47
+ Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
48
+
49
+ - IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
50
+ Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
51
+ Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
52
+ Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
53
+ - IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
54
+ Start with the section of each trigger and action used (for example, "Send a package" is action type `package_transfer`, section `package-transfer`),
55
+ then `payload-rules-enforced-by-the-api` and `finding-the-identifiers`.
56
+
57
+ ## Rules
58
+
59
+ - Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
60
+ - Extended values inside JSON (e.g. a vault secret in a parameter file): write `"@vault:<label>.<field>@"` (closing `@`) in the file, and give `@json:@extend:@file:<path>`. Without `@extend:`, or without the closing `@`, the value stays a literal string. Check with `ascli config echo`.
61
+ - Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
62
+ - Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
63
+ - Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
64
+ - Wait for a state (a work order complete, a task created, a package received): repeat a read-only command (`list`, `show`, `status`) with `--poll`, not with `sleep` or a shell loop, e.g. ``--poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'``.
65
+ `until` is a JMESPath expression on the result (`@`: result not empty), the command fails if it is not met after `max` runs (or `timeout`). `"show":"last"` displays only the last result, `"errors":"retry"` runs again after an error. With `--format=json`, each result displayed is one line: usable in a background watcher. See section `polling-option-poll` of the manual.
66
+ - Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
67
+ - Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
68
+ - Show the user the command line that was executed.
69
+
70
+ ## Examples
71
+
72
+ ```shell
73
+ ascli config commands faspex5
74
+ ascli faspex5 packages send help
75
+ ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
76
+ ascli aoc files browse / --format=json
77
+ ascli orchestrator workorders status 1234 --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}' --format=json
78
+ ascli server upload /path/to/file --to-folder=/Upload
79
+ ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
80
+ ```
81
+
82
+ ## Documentation
83
+
84
+ - [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
85
+ - [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
86
+ - [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
87
+ - [Source](https://github.com/IBM/aspera-cli)
@@ -0,0 +1,94 @@
1
+ ---
2
+ name: ascli
3
+ description: 'Operate IBM Aspera products with the ascli command line: Aspera on Cloud, Faspex 5, High-Speed Transfer Server, Node API, Shares, Console, Orchestrator, Cloud Object Storage. Use when the user wants to transfer files with FASP (ascp), send or receive packages, browse or manage remote files, administer users, workspaces, nodes or access keys, analyze ascp logs, or develop Orchestrator or Aspera on Cloud Automation workflows.'
4
+ license: Apache-2.0
5
+ compatibility: Requires the ascli command (Ruby gem aspera-cli) in the shell, or the ascli MCP server.
6
+ ---
7
+
8
+ # ascli: command line interface for IBM Aspera
9
+
10
+ > `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
11
+ > An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
12
+ > transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
13
+
14
+ If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
15
+
16
+ ## Products and plugins
17
+
18
+ The first word after `ascli` is a plugin: one per product.
19
+
20
+ - `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
21
+ - `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
22
+ - `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
23
+ - `node`: Node API of a transfer server (files, access keys, transfers, sync)
24
+ - `shares`: IBM Aspera Shares
25
+ - `console`: IBM Aspera Console
26
+ - `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
27
+ - `ats`: IBM Aspera Transfer Service
28
+ - `cos`: IBM Cloud Object Storage
29
+ - `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
30
+ - `preview`: generation of previews of files
31
+ - `transferd`: Transfer Daemon of the Transfer SDK (install, service)
32
+ - `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
33
+ - `mcp`: Model Context Protocol server
34
+
35
+ ## Two ways to use it
36
+
37
+ - Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
38
+ Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
39
+ - MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
40
+ The description of the tool repeats the rules below.
41
+
42
+ ## Discover, do not guess
43
+
44
+ Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
45
+
46
+ 1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
47
+ 2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
48
+ 3. Filter parameters of a list command: `--query=help`.
49
+ 4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
50
+ 5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
51
+
52
+ ## Workflow development
53
+
54
+ Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
55
+
56
+ - IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
57
+ Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
58
+ Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
59
+ Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
60
+ - IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
61
+ Start with the section of each trigger and action used (for example, "Send a package" is action type `package_transfer`, section `package-transfer`),
62
+ then `payload-rules-enforced-by-the-api` and `finding-the-identifiers`.
63
+
64
+ ## Rules
65
+
66
+ - Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
67
+ - Extended values inside JSON (e.g. a vault secret in a parameter file): write `"@vault:<label>.<field>@"` (closing `@`) in the file, and give `@json:@extend:@file:<path>`. Without `@extend:`, or without the closing `@`, the value stays a literal string. Check with `ascli config echo`.
68
+ - Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
69
+ - Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
70
+ - Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
71
+ - Wait for a state (a work order complete, a task created, a package received): repeat a read-only command (`list`, `show`, `status`) with `--poll`, not with `sleep` or a shell loop, e.g. ``--poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'``.
72
+ `until` is a JMESPath expression on the result (`@`: result not empty), the command fails if it is not met after `max` runs (or `timeout`). `"show":"last"` displays only the last result, `"errors":"retry"` runs again after an error. With `--format=json`, each result displayed is one line: usable in a background watcher. See section `polling-option-poll` of the manual.
73
+ - Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
74
+ - Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
75
+ - Show the user the command line that was executed.
76
+
77
+ ## Examples
78
+
79
+ ```shell
80
+ ascli config commands faspex5
81
+ ascli faspex5 packages send help
82
+ ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
83
+ ascli aoc files browse / --format=json
84
+ ascli orchestrator workorders status 1234 --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}' --format=json
85
+ ascli server upload /path/to/file --to-folder=/Upload
86
+ ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
87
+ ```
88
+
89
+ ## Documentation
90
+
91
+ - [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
92
+ - [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
93
+ - [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
94
+ - [Source](https://github.com/IBM/aspera-cli)
data.tar.gz.sig CHANGED
Binary file