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,333 @@
1
+ # DO NOT EDIT THIS FILE MANUALLY
2
+ # This file is automatically downloaded from:
3
+ # https://raw.githubusercontent.com/laurent-martin/aspera-api-examples/refs/heads/main/openapi/transferd-config.schema.json
4
+ # Use 'rake tools:openapi' to update this file
5
+
6
+ {
7
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
8
+ "$comment": "Matches transferd 1.1.10 (source of truth: internal/config/config.go in the transferd repository). Durations are in seconds.",
9
+ "title": "IBM Aspera Transfer SDK daemon (transferd) configuration",
10
+ "description": "Configuration file of transferd, in JSON or YAML. Without option --config (-c), transferd reads ../etc/transferd.json relative to the directory of the transferd executable, then /etc/transferd/transferd.json, and if neither exists uses built-in defaults. transferd ignores unknown keys, so a misspelled key silently has no effect: validate the file against this schema to catch it.",
11
+ "type": "object",
12
+ "additionalProperties": false,
13
+ "properties": {
14
+ "$schema": {
15
+ "type": "string",
16
+ "description": "Optional URI or path of this schema, used by editors for completion and validation. Ignored by transferd."
17
+ },
18
+ "log_directory": {
19
+ "type": "string",
20
+ "description": "Directory of the transferd log file transferd.log (rotated at 10 MiB, 10 files kept). A relative path is resolved from the directory of the transferd executable. The directory is created if missing. Empty or omitted: logs are written to standard output.",
21
+ "examples": ["/var/log/aspera", "../var/log"]
22
+ },
23
+ "log_level": {
24
+ "type": "string",
25
+ "description": "Level of detail of the transferd log, from most (trace) to least (panic) verbose. Omitted or unrecognized value: info.",
26
+ "enum": ["trace", "debug", "info", "warning", "error", "fatal", "panic"],
27
+ "default": "info"
28
+ },
29
+ "log_format": {
30
+ "type": "string",
31
+ "description": "Format of the transferd log: text for human-readable lines, json for one JSON object per line. Any value other than text gives json.",
32
+ "enum": ["text", "json"],
33
+ "default": "text"
34
+ },
35
+ "address": {
36
+ "type": "string",
37
+ "description": "IP address or host name on which the gRPC API listens. Use 0.0.0.0 to listen on all IPv4 interfaces (for example in a container); when not listening on a loopback address, consider enabling tls and authentication. Overridden by environment variable TRANSFERD_ADDRESS, and by option --address (-a), which takes precedence.",
38
+ "default": "127.0.0.1",
39
+ "examples": ["127.0.0.1", "0.0.0.0"]
40
+ },
41
+ "port": {
42
+ "type": "integer",
43
+ "description": "TCP port on which the gRPC API listens. 0 or omitted: a free port is selected at startup; it is written in the log and in file transferd.<port>.optport of runtime_dir. The configuration file shipped with the SDK sets 55002. Overridden by environment variable TRANSFERD_PORT, and by option --port (-p), which takes precedence.",
44
+ "minimum": 0,
45
+ "maximum": 65535,
46
+ "default": 0,
47
+ "examples": [55002]
48
+ },
49
+ "runtime_dir": {
50
+ "type": "string",
51
+ "description": "Directory for runtime files. When port is 0, transferd writes the selected port in file transferd.<port>.optport there. Created with owner-only permissions if missing. Omitted: ../var/run/aspera relative to the directory of the transferd executable.",
52
+ "examples": ["/var/run/aspera"]
53
+ },
54
+ "reflection": {
55
+ "type": "boolean",
56
+ "description": "Enables the gRPC server reflection service, so that tools such as `grpcurl` or `grpcui` can list and call the API without the transferd.proto file. Useful for debugging; leave disabled otherwise.",
57
+ "default": false
58
+ },
59
+ "workers": {
60
+ "type": "object",
61
+ "description": "Transfer execution and retention.",
62
+ "additionalProperties": false,
63
+ "properties": {
64
+ "max_concurrent": {
65
+ "type": "integer",
66
+ "description": "Maximum number of transfers running at the same time. Additional transfers wait in a queue until a running one ends. 0 or omitted: 100.",
67
+ "minimum": 0,
68
+ "default": 100,
69
+ "examples": [10]
70
+ },
71
+ "transfer_cleaning_period": {
72
+ "type": "integer",
73
+ "description": "Interval, in seconds, at which transferd removes ended transfers older than transfer_max_age. 0 or omitted: 3600 (1 hour).",
74
+ "minimum": 0,
75
+ "default": 3600
76
+ },
77
+ "transfer_max_age": {
78
+ "type": "integer",
79
+ "description": "Time, in seconds, during which an ended transfer remains known to transferd (status queries, events) before it can be removed. Removal happens at the next cleaning, so a transfer may remain up to transfer_max_age + transfer_cleaning_period. 0 or omitted: 7200 (2 hours).",
80
+ "minimum": 0,
81
+ "default": 7200,
82
+ "examples": [86400]
83
+ }
84
+ }
85
+ },
86
+ "fasp_management": {
87
+ "type": "object",
88
+ "description": "Management port on which the ascp processes started by transferd report transfer progress.",
89
+ "additionalProperties": false,
90
+ "properties": {
91
+ "promiscuous_mode_enabled": {
92
+ "type": "boolean",
93
+ "description": "When true, transferd also reports transfers of ascp processes that it did not start. So that those processes find the management port, transferd writes it in file transferd.<port>.optport of directory ../var/run/aspera, relative to the FASP runtime bin directory. Those ascp processes must use the same FASP runtime as transferd (see fasp_runtime).",
94
+ "default": false
95
+ },
96
+ "port": {
97
+ "type": "integer",
98
+ "description": "TCP port of the management server. 0 or omitted: a free port is selected at startup. Overridden by environment variable TRANSFERD_MGMT_PORT, and by option --mgmtport (-P), which takes precedence.",
99
+ "minimum": 0,
100
+ "maximum": 65535,
101
+ "default": 0,
102
+ "examples": [23456]
103
+ },
104
+ "address": {
105
+ "type": "string",
106
+ "description": "IP address on which the management server listens. Change it only when ascp must reach transferd through an interface other than loopback. Overridden by environment variable TRANSFERD_MGMT_ADDRESS, and by option --mgmtaddress (-A), which takes precedence.",
107
+ "default": "127.0.0.1",
108
+ "examples": ["127.0.0.1"]
109
+ }
110
+ }
111
+ },
112
+ "fasp_runtime": {
113
+ "type": "object",
114
+ "description": "FASP runtime (ascp, async, license, aspera.conf) used for transfers. Omitted: the runtime embedded in the SDK is used. When this section is present, set use_embedded explicitly: if it is not true, user_defined is required.",
115
+ "additionalProperties": false,
116
+ "properties": {
117
+ "use_embedded": {
118
+ "type": "boolean",
119
+ "description": "true: use the FASP runtime embedded in the SDK, and ignore user_defined. false: use the runtime located by user_defined. Omitted while the fasp_runtime section is present: false.",
120
+ "examples": [true]
121
+ },
122
+ "force_version": {
123
+ "type": "string",
124
+ "description": "Accepted for backward compatibility. Has no effect.",
125
+ "deprecated": true
126
+ },
127
+ "user_defined": {
128
+ "type": "object",
129
+ "description": "Location of a separately installed FASP runtime. Required when use_embedded is not true, ignored otherwise. Both directories must exist at startup.",
130
+ "additionalProperties": false,
131
+ "required": ["bin", "etc"],
132
+ "properties": {
133
+ "bin": {
134
+ "type": "string",
135
+ "description": "Directory containing the ascp and async executables. A relative path is resolved from the working directory of transferd.",
136
+ "minLength": 1,
137
+ "examples": ["/opt/aspera/bin"]
138
+ },
139
+ "etc": {
140
+ "type": "string",
141
+ "description": "Directory containing the license file aspera-license and the configuration file aspera.conf. A relative path is resolved from the working directory of transferd.",
142
+ "minLength": 1,
143
+ "examples": ["/opt/aspera/etc"]
144
+ }
145
+ }
146
+ },
147
+ "log": {
148
+ "type": "object",
149
+ "description": "Default logging of ascp, for transfers whose request configuration does not set localLog or logLevel. Does not apply to async.",
150
+ "additionalProperties": false,
151
+ "properties": {
152
+ "dir": {
153
+ "type": "string",
154
+ "description": "Directory where ascp writes its log (ascp option -L). Empty or omitted: default location of ascp.",
155
+ "examples": ["/var/log/aspera"]
156
+ },
157
+ "level": {
158
+ "type": "integer",
159
+ "description": "Level of detail of the ascp log: 0 for basic information (files transferred, transfer rate), 1 to 4 for increasingly detailed debug messages (ascp options -D to -DDDD).",
160
+ "minimum": 0,
161
+ "maximum": 4,
162
+ "default": 0
163
+ }
164
+ }
165
+ },
166
+ "extra_config": {
167
+ "type": "array",
168
+ "description": "Extra command line options added to the executables started for transfers. Does not apply to async.",
169
+ "items": {
170
+ "type": "object",
171
+ "additionalProperties": false,
172
+ "required": ["command"],
173
+ "properties": {
174
+ "command": {
175
+ "type": "string",
176
+ "description": "End of the path of the executable to which options are added, for example ascp (ascp.exe on Windows). Only the first matching entry is used.",
177
+ "minLength": 1,
178
+ "examples": ["ascp", "ascp.exe"]
179
+ },
180
+ "options": {
181
+ "type": "array",
182
+ "description": "Options added to the command line, one argument per item, before the transfer arguments.",
183
+ "items": {
184
+ "type": "string"
185
+ },
186
+ "examples": [["--save-before-overwrite"]]
187
+ }
188
+ }
189
+ }
190
+ }
191
+ },
192
+ "if": {
193
+ "required": ["use_embedded"],
194
+ "properties": {
195
+ "use_embedded": {
196
+ "const": true
197
+ }
198
+ }
199
+ },
200
+ "else": {
201
+ "required": ["user_defined"]
202
+ }
203
+ },
204
+ "tls": {
205
+ "type": "object",
206
+ "description": "TLS for the gRPC API. When enabled, clients must connect using TLS.",
207
+ "additionalProperties": false,
208
+ "properties": {
209
+ "enabled": {
210
+ "type": "boolean",
211
+ "description": "Enables TLS. certificate and key are then required.",
212
+ "default": false
213
+ },
214
+ "certificate": {
215
+ "type": "string",
216
+ "description": "Path of the PEM server certificate file, which may include intermediate certificates. A relative path is resolved from the working directory of transferd.",
217
+ "minLength": 1,
218
+ "examples": ["/etc/transferd/server.crt"]
219
+ },
220
+ "key": {
221
+ "type": "string",
222
+ "description": "Path of the PEM private key file matching certificate. A relative path is resolved from the working directory of transferd.",
223
+ "minLength": 1,
224
+ "examples": ["/etc/transferd/server.key"]
225
+ },
226
+ "min_tls_version": {
227
+ "type": "string",
228
+ "description": "Minimum TLS version accepted from clients. Omitted or other value: TLSv12.",
229
+ "enum": ["TLSv12", "TLSv13"],
230
+ "default": "TLSv12"
231
+ }
232
+ },
233
+ "if": {
234
+ "required": ["enabled"],
235
+ "properties": {
236
+ "enabled": {
237
+ "const": true
238
+ }
239
+ }
240
+ },
241
+ "then": {
242
+ "required": ["certificate", "key"]
243
+ }
244
+ },
245
+ "authentication": {
246
+ "type": "object",
247
+ "description": "API key authentication of clients of the gRPC API.",
248
+ "additionalProperties": false,
249
+ "properties": {
250
+ "enabled": {
251
+ "type": "boolean",
252
+ "description": "Requires every call to carry the API key; other calls are rejected with status UNAUTHENTICATED. api_key is then required.",
253
+ "default": false
254
+ },
255
+ "api_key": {
256
+ "type": "string",
257
+ "description": "Value that clients must send in gRPC request metadata entry api_key. It is stored in clear text: restrict read access to this file.",
258
+ "minLength": 1,
259
+ "examples": ["change-me-to-a-long-random-value"]
260
+ }
261
+ },
262
+ "if": {
263
+ "required": ["enabled"],
264
+ "properties": {
265
+ "enabled": {
266
+ "const": true
267
+ }
268
+ }
269
+ },
270
+ "then": {
271
+ "required": ["api_key"]
272
+ }
273
+ },
274
+ "api_time_settings": {
275
+ "type": "object",
276
+ "description": "Keepalive and connection lifetime settings of the gRPC API server, in seconds.",
277
+ "additionalProperties": false,
278
+ "properties": {
279
+ "max_conn_idle": {
280
+ "type": "integer",
281
+ "description": "Time after which a client connection with no ongoing call is closed. 0 or omitted: 86400 (24 hours).",
282
+ "minimum": 0,
283
+ "default": 86400,
284
+ "examples": [120]
285
+ },
286
+ "max_conn_age": {
287
+ "type": "integer",
288
+ "description": "Maximum lifetime of a client connection, with a random variation of +/-10%; the client must then reconnect. 0 or omitted: no limit.",
289
+ "minimum": 0,
290
+ "default": 0,
291
+ "examples": [3600]
292
+ },
293
+ "max_conn_age_grace": {
294
+ "type": "integer",
295
+ "description": "Additional time given to ongoing calls once max_conn_age is reached, before the connection is forcibly closed. 0 or omitted: no limit.",
296
+ "minimum": 0,
297
+ "default": 0,
298
+ "examples": [10]
299
+ },
300
+ "time": {
301
+ "type": "integer",
302
+ "description": "Time without activity from a client after which the server pings it to check that the connection is still alive. 0 or omitted: 7200 (2 hours).",
303
+ "minimum": 0,
304
+ "default": 7200,
305
+ "examples": [60]
306
+ },
307
+ "timeout": {
308
+ "type": "integer",
309
+ "description": "Time the server waits for activity after a keepalive ping before closing the connection. 0 or omitted: 20.",
310
+ "minimum": 0,
311
+ "default": 20,
312
+ "examples": [3]
313
+ }
314
+ }
315
+ }
316
+ },
317
+ "examples": [
318
+ {
319
+ "address": "127.0.0.1",
320
+ "port": 55002,
321
+ "workers": {
322
+ "max_concurrent": 10
323
+ },
324
+ "fasp_management": {
325
+ "promiscuous_mode_enabled": false,
326
+ "port": 23456
327
+ },
328
+ "fasp_runtime": {
329
+ "use_embedded": true
330
+ }
331
+ }
332
+ ]
333
+ }
@@ -1,8 +1,11 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'registry'
3
7
  require 'singleton'
4
8
  require 'json'
5
- require 'aspera/schema/registry'
6
9
 
7
10
  module Aspera
8
11
  module Schema
@@ -0,0 +1,166 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'assert'
7
+ require 'json'
8
+ require 'zlib'
9
+ require 'openssl'
10
+
11
+ module Aspera
12
+ # Converts a Hash to a compact text, typed or pasted by a user, and back. Only Ruby standard libraries are used.
13
+ # Used for the codes exchanged by the user between `ascli` and the browser, or Shares (option `ui.web_auth=paste`).
14
+ #
15
+ # Steps: Hash -> JSON -> deflate -> AES-256-GCM -> Base64 URL-safe, without padding (characters: `A-Z a-z 0-9 - _`).
16
+ #
17
+ # Text layout, once decoded from Base64: `IV (12 bytes) + authentication tag (16 bytes) + encrypted data`.
18
+ # The key is `SHA256(<base key> + <secret> + <slot>)`, where slot is the Unix time divided by the period (15 minutes by default), rounded down.
19
+ # Base key and secret are optional.
20
+ # The authentication tag detects an incomplete, mistyped or modified text, or a wrong key.
21
+ # There is no prefix nor type in the text: the receiver checks the keys of the Hash.
22
+ #
23
+ # The protection depends on the key: if the base key is a constant (e.g. in the source code) and there is no secret, the key is not secret, and the slot is easy to guess:
24
+ # the text is then not readable at first sight and is not valid for long, but it is not confidential.
25
+ # To make it confidential, give a `secret` known only by both sides (e.g. a random `state`).
26
+ #
27
+ # The slot changes every period, and the clocks of both sides can differ: `unseal` also tries the previous slot and the next one.
28
+ # So a text is valid from 1 to 2 periods after its creation (15 to 30 minutes by default), and is also accepted if the clock of the receiver is up to 1 period behind.
29
+ # When unsealing, spaces and line breaks are ignored (a text split on several lines is valid), as well as quotes and punctuation around the text.
30
+ # Letter case matters.
31
+ #
32
+ # With `encrypt: false`, there is no encryption and no validity period: the text is only Hash -> JSON -> deflate -> Base64 URL-safe, readable by anyone, without detection of errors.
33
+ # It is used for links that must stay valid and are decoded by other programs (e.g. JavaScript in a browser).
34
+ # `sealed?` does not know this mode.
35
+ # With `reverse: true`, the final text is reversed (it must be the same on both sides), in any mode.
36
+ module SealedHash
37
+ CIPHER = 'aes-256-gcm'
38
+ IV_SIZE = 12
39
+ TAG_SIZE = 16
40
+ # Duration of a slot, in seconds
41
+ PERIOD = 900
42
+ # Shortest text: IV, tag and one byte of data, in Base64
43
+ MIN_TEXT_LENGTH = ((IV_SIZE + TAG_SIZE + 1) * 4 / 3.0).ceil
44
+ # Limits on what is accepted: protection against an abusive input
45
+ MAX_TEXT_LENGTH = 65_536
46
+ MAX_INFLATED_SIZE = 262_144
47
+ # Slots tried to decrypt, relative to the current slot
48
+ SLOT_OFFSETS = [0, -1, 1].freeze
49
+ TEXT_CHARS = /\A[A-Za-z0-9_-]*\z/
50
+ private_constant :CIPHER, :IV_SIZE, :TAG_SIZE, :MIN_TEXT_LENGTH, :MAX_TEXT_LENGTH, :MAX_INFLATED_SIZE, :SLOT_OFFSETS, :TEXT_CHARS
51
+
52
+ class << self
53
+ # @param data [Hash] Data to transform
54
+ # @param secret [String, nil] Value known by both sides, added to the key
55
+ # @param base_key [String, nil] Base of the key, e.g. the name of the application (optional)
56
+ # @param time [Time] Time used for the key
57
+ # @param period [Integer] Duration of a slot, in seconds (must be the same on both sides)
58
+ # @param encrypt [Boolean] `false`: no encryption, no validity period (secret, base_key, time and period are ignored)
59
+ # @param reverse [Boolean] `true`: the text is reversed
60
+ # @return [String] Base64 URL-safe text, without padding
61
+ def seal(data, secret: nil, base_key: nil, time: Time.now, period: PERIOD, encrypt: true, reverse: false)
62
+ Aspera.assert_type(data, Hash)
63
+ deflated = Zlib::Deflate.deflate(JSON.generate(data), Zlib::BEST_COMPRESSION)
64
+ raw =
65
+ if encrypt
66
+ cipher = OpenSSL::Cipher.new(CIPHER).encrypt
67
+ cipher.key = derive_key(base_key, secret, time.to_i / period)
68
+ iv = cipher.random_iv
69
+ body = cipher.update(deflated) + cipher.final
70
+ iv + cipher.auth_tag(TAG_SIZE) + body
71
+ else
72
+ deflated
73
+ end
74
+ text = [raw].pack('m0').tr('+/', '-_').delete('=')
75
+ reverse ? text.reverse : text
76
+ end
77
+
78
+ # @param text [String] Text typed or pasted by the user
79
+ # @return [Boolean] `true` if text looks like a sealed hash (characters and length), to be decoded with `unseal`.
80
+ # A URL or a query always has other characters (`:`, `/`, `?`, `=`, `&`).
81
+ def sealed?(text)
82
+ clean = normalize(text)
83
+ clean.length >= MIN_TEXT_LENGTH && clean.match?(TEXT_CHARS)
84
+ end
85
+
86
+ # @param text [String] Text produced by `seal`
87
+ # @param secret [String, nil] Value known by both sides, added to the key
88
+ # @param base_key [String, nil] Base of the key, e.g. the name of the application (optional)
89
+ # @param time [Time] Time used for the key
90
+ # @param period [Integer] Duration of a slot, in seconds (must be the same on both sides)
91
+ # @param encrypt [Boolean] Same value as for `seal`
92
+ # @param reverse [Boolean] Same value as for `seal`
93
+ # @return [Hash] The data
94
+ # @raise [ParameterError] if text is not valid: incomplete, mistyped, modified, or made with another key or too long ago
95
+ def unseal(text, secret: nil, base_key: nil, time: Time.now, period: PERIOD, encrypt: true, reverse: false)
96
+ clean = normalize(text)
97
+ clean = clean.reverse if reverse
98
+ raise ParameterError, 'Code is too long' if clean.length > MAX_TEXT_LENGTH
99
+ raise ParameterError, 'Code has invalid characters: only letters, digits, - and _ are expected' unless clean.match?(TEXT_CHARS)
100
+ raise ParameterError, 'Code is incomplete' if clean.length < (encrypt ? MIN_TEXT_LENGTH : 1)
101
+ raw = begin
102
+ "#{clean.tr('-_', '+/')}#{'=' * ((4 - (clean.length % 4)) % 4)}".unpack1('m0')
103
+ rescue ArgumentError
104
+ raise ParameterError, 'Code is incomplete or has typing errors'
105
+ end
106
+ if encrypt
107
+ deflated = nil
108
+ SLOT_OFFSETS.each do |offset|
109
+ deflated = decrypt(raw, derive_key(base_key, secret, (time.to_i / period) + offset))
110
+ break unless deflated.nil?
111
+ end
112
+ raise ParameterError, 'Invalid code: incomplete, mistyped, expired, or the clock is wrong (check the time of both computers)' if deflated.nil?
113
+ else
114
+ deflated = raw
115
+ end
116
+ data = JSON.parse(inflate(deflated))
117
+ raise ParameterError, 'Invalid code: unexpected content' unless data.is_a?(Hash)
118
+ data
119
+ rescue JSON::ParserError, Zlib::Error
120
+ raise ParameterError, 'Invalid code: unexpected content'
121
+ end
122
+
123
+ private
124
+
125
+ # @return [String] Text without spaces and surrounding punctuation (quotes, ...)
126
+ def normalize(text)
127
+ # Only patterns anchored at the start (the end is handled on the reversed text): linear time on any input
128
+ clean = text.to_s.gsub(/\s/, '').sub(/\A[^A-Za-z0-9_-]+/, '')
129
+ clean.reverse.sub(/\A[^A-Za-z0-9_-]+/, '').reverse
130
+ end
131
+
132
+ # @return [String] 32 bytes
133
+ def derive_key(base_key, secret, slot)
134
+ OpenSSL::Digest.digest('SHA256', "#{base_key}#{secret}#{slot}")
135
+ end
136
+
137
+ # @return [String, nil] Deflated data, or `nil` if the key or the tag is not the expected one
138
+ def decrypt(raw, key)
139
+ cipher = OpenSSL::Cipher.new(CIPHER).decrypt
140
+ cipher.key = key
141
+ cipher.iv = raw.byteslice(0, IV_SIZE)
142
+ cipher.auth_tag = raw.byteslice(IV_SIZE, TAG_SIZE)
143
+ cipher.update(raw.byteslice((IV_SIZE + TAG_SIZE)..)) + cipher.final
144
+ rescue OpenSSL::Cipher::CipherError
145
+ nil
146
+ end
147
+
148
+ # @param body [String] Deflated data
149
+ # @return [String] Inflated data, limited in size
150
+ def inflate(body)
151
+ output = +''
152
+ inflater = Zlib::Inflate.new
153
+ begin
154
+ inflater.inflate(body) do |chunk|
155
+ output << chunk
156
+ raise ParameterError, 'Invalid code: content is too large' if output.bytesize > MAX_INFLATED_SIZE
157
+ end
158
+ raise ParameterError, 'Code is incomplete' unless inflater.finished?
159
+ ensure
160
+ inflater.close
161
+ end
162
+ output
163
+ end
164
+ end
165
+ end
166
+ end