aspera-cli 4.29.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 (78) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +2 -1
  3. data/CHANGELOG.md +76 -2
  4. data/README.md +20 -1
  5. data/SECURITY.md +14 -0
  6. data/docs/README.md +277 -38
  7. data/lib/aspera/api/node.rb +9 -2
  8. data/lib/aspera/ascp/installation.rb +26 -4
  9. data/lib/aspera/ascp/log_analyzer/lines.rb +2 -2
  10. data/lib/aspera/ascp/log_analyzer.rb +19 -3
  11. data/lib/aspera/ascp/log_locations.rb +163 -0
  12. data/lib/aspera/cli/ascp_logs_actions.rb +12 -0
  13. data/lib/aspera/cli/bootstrapper.rb +1 -0
  14. data/lib/aspera/cli/command_line.rb +39 -2
  15. data/lib/aspera/cli/command_registry.rb +3 -0
  16. data/lib/aspera/cli/command_spec.rb +13 -0
  17. data/lib/aspera/cli/error.rb +3 -0
  18. data/lib/aspera/cli/extended_value.rb +5 -4
  19. data/lib/aspera/cli/formatter.rb +14 -8
  20. data/lib/aspera/cli/http.rb +26 -1
  21. data/lib/aspera/cli/info.rb +1 -1
  22. data/lib/aspera/cli/mcp/tool.rb +5 -3
  23. data/lib/aspera/cli/option_value.rb +14 -8
  24. data/lib/aspera/cli/options.schema.yaml +156 -19
  25. data/lib/aspera/cli/parser.rb +15 -3
  26. data/lib/aspera/cli/plugins/aoc.rb +4 -2
  27. data/lib/aspera/cli/plugins/ats.rb +1 -1
  28. data/lib/aspera/cli/plugins/base.rb +33 -6
  29. data/lib/aspera/cli/plugins/config.rb +12 -1
  30. data/lib/aspera/cli/plugins/faspex5.rb +3 -1
  31. data/lib/aspera/cli/plugins/mcp.rb +14 -0
  32. data/lib/aspera/cli/plugins/node.rb +8 -8
  33. data/lib/aspera/cli/plugins/oauth.rb +18 -5
  34. data/lib/aspera/cli/plugins/orchestrator.rb +28 -24
  35. data/lib/aspera/cli/plugins/preview.rb +3 -1
  36. data/lib/aspera/cli/plugins/server.rb +3 -3
  37. data/lib/aspera/cli/plugins/shares.rb +1 -2
  38. data/lib/aspera/cli/plugins/transferd.rb +7 -2
  39. data/lib/aspera/cli/poll.rb +236 -0
  40. data/lib/aspera/cli/preset_manager.rb +63 -19
  41. data/lib/aspera/cli/prompt.rb +153 -8
  42. data/lib/aspera/cli/runner.rb +25 -7
  43. data/lib/aspera/cli/security.rb +10 -0
  44. data/lib/aspera/cli/sync_actions.rb +2 -0
  45. data/lib/aspera/cli/transfer_agent.rb +14 -0
  46. data/lib/aspera/cli/transfer_progress.rb +6 -5
  47. data/lib/aspera/cli/version.rb +1 -1
  48. data/lib/aspera/environment.rb +3 -1
  49. data/lib/aspera/id_generator.rb +16 -3
  50. data/lib/aspera/inflate.rb +43 -0
  51. data/lib/aspera/oauth/client/base.rb +38 -8
  52. data/lib/aspera/oauth/client/factory.rb +35 -15
  53. data/lib/aspera/oauth/client/json_credentials.rb +3 -2
  54. data/lib/aspera/oauth/client/shares_web.rb +13 -4
  55. data/lib/aspera/oauth/client/url_json.rb +3 -2
  56. data/lib/aspera/oauth/client/web.rb +2 -2
  57. data/lib/aspera/orchestrator_workflow_checker.rb +10 -1
  58. data/lib/aspera/preview/terminal.rb +8 -2
  59. data/lib/aspera/products/desktop.rb +13 -1
  60. data/lib/aspera/rest/client.rb +23 -5
  61. data/lib/aspera/schema/registry.rb +1 -0
  62. data/lib/aspera/sealed_hash.rb +2 -18
  63. data/lib/aspera/secret/hider.rb +13 -1
  64. data/lib/aspera/secret/store/one_password_cli.rb +13 -11
  65. data/lib/aspera/sync/operations.rb +4 -4
  66. data/lib/aspera/transfer/result.rb +20 -0
  67. data/lib/aspera/transfer/spec.rb +2 -2
  68. data/lib/aspera/{transfer/units.rb → units/decimal.rb} +4 -12
  69. data/lib/aspera/units/duration.rb +109 -0
  70. data/lib/aspera/uri_reader.rb +11 -6
  71. data/lib/aspera/web_auth/reply.html.erb +1 -1
  72. data/llms-install.md +88 -0
  73. data/llms.txt +6 -0
  74. data/skills/ascli/SKILL.md +6 -0
  75. data.tar.gz.sig +0 -0
  76. metadata +7 -3
  77. metadata.gz.sig +0 -0
  78. data/lib/aspera/duration.rb +0 -45
data/docs/README.md CHANGED
@@ -16,7 +16,7 @@ DO NOT EDIT: THIS FILE IS GENERATED, edit docs/README.erb.md.
16
16
  <!-- gfm2pdf
17
17
  common:
18
18
  metadata:
19
- subtitle: "ascli 4.29.0"
19
+ subtitle: "ascli 4.29.1"
20
20
  author: "Laurent Martin"
21
21
  -->
22
22
 
@@ -195,7 +195,7 @@ This section walks you through your first interaction with `ascli` on Linux.
195
195
 
196
196
  ```shell
197
197
  mkdir -p $HOME/bin
198
- tar -C $HOME/bin -zxvf ascli-4.29.0-linux-x86_64.tgz
198
+ tar -C $HOME/bin -zxvf ascli-4.29.1-linux-x86_64.tgz
199
199
  export PATH=$PATH:$HOME/bin
200
200
  ```
201
201
 
@@ -209,7 +209,7 @@ ascli -v
209
209
  ```
210
210
 
211
211
  ```text
212
- 4.29.0
212
+ 4.29.1
213
213
  ```
214
214
 
215
215
  - Install the Aspera transfer runtime (tested version), as it is not included in the `ascli` package:
@@ -302,6 +302,7 @@ There are three ways, the first one is the simplest:
302
302
  - **The AI executes commands in a shell** (coding agents): nothing to set up, and no limitation: the AI uses `ascli` as you do, with your configuration.
303
303
  Give it the file [`llms.txt`](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/llms.txt), located at the root of the gem and of the GitHub repository.
304
304
  It tells the AI what `ascli` does with IBM Aspera products, and how to discover commands, arguments and options (`config commands`, `help`, `config options`, `config documentation`).
305
+ The same content is displayed by `ascli config skill`: an AI that can execute `ascli` can read it with no file to find.
305
306
  With an AI client that supports agent skills, install the skill instead: the AI loads it by itself when a request is about IBM Aspera.
306
307
  The skill, in the [Agent Skills](https://agentskills.io) format, is the folder `skills/ascli` of the gem (and of the GitHub repository): copy it to the skills folder of the AI client, for example:
307
308
 
@@ -312,7 +313,8 @@ There are three ways, the first one is the simplest:
312
313
  With Claude Code, install it as a plugin from the GitHub repository, which is also a plugin marketplace: it is updated with the repository.
313
314
 
314
315
  ```text
315
- /plugin install ascli --marketplace IBM/aspera-cli
316
+ /plugin marketplace add IBM/aspera-cli
317
+ /plugin install ascli@aspera-cli
316
318
  ```
317
319
 
318
320
  - **The AI executes commands through MCP**: for an AI client without a shell, start the [MCP server](#plugin-mcp-model-context-protocol-server) and register it in the AI client.
@@ -374,7 +376,7 @@ There are several ways to install `ascli`:
374
376
  - On Windows, as a [portable package](#windows-portable-package)
375
377
 
376
378
  This method is the simplest on Windows: extract and run. It includes Ruby, gems and `ascp`.
377
- - On Windows, with the [Chocolatey package](#windows-chocolatey-package) (installs Ruby and the gem).
379
+ - On Windows, with the [Chocolatey package](#windows-chocolatey-package): it installs the portable package and adds `ascli` to the `PATH`.
378
380
  - As a [container](#container) (`docker`, `podman`, `singularity`).
379
381
 
380
382
  The following sections describe the various installation methods.
@@ -504,7 +506,8 @@ To uninstall, delete the folder, and remove it from the `PATH` if it was added.
504
506
 
505
507
  ### Windows: Chocolatey package
506
508
 
507
- If you use [Chocolatey](https://chocolatey.org/), `ascli` can be installed with the `aspera-cli` package: it installs Ruby (if not already present) and the `aspera-cli` gem.
509
+ If you use [Chocolatey](https://chocolatey.org/), `ascli` can be installed with the `aspera-cli` package.
510
+ It installs the [portable package](#windows-portable-package) (Ruby, gems and `ascp` included, checked with its SHA-256) and adds only the command `ascli` to the `PATH`: no Ruby installation is needed.
508
511
 
509
512
  In a PowerShell as Administrator:
510
513
 
@@ -512,7 +515,7 @@ In a PowerShell as Administrator:
512
515
  choco install aspera-cli -y
513
516
  ```
514
517
 
515
- Then, install the Aspera Transfer Daemon, see [Installing `ascp` through `transferd`](#installing-ascp-through-transferd).
518
+ Upgrade with `choco upgrade aspera-cli`, uninstall with `choco uninstall aspera-cli` (the configuration is kept).
516
519
 
517
520
  ### Ruby
518
521
 
@@ -975,6 +978,8 @@ The installation of the transfer binaries follows those steps:
975
978
  - This YAML file lists supported architectures (OS, CPU) and Aspera Transfer Daemon versions with their associated package URLs.
976
979
  - The SDK version is selected as follows: if an additional **positional parameter** is provided it specifies the version; if the special value `LATEST` is given the latest available version is used; otherwise the version tested with this release of `ascli` is used.
977
980
  - The package URL matching the current system architecture is then used.
981
+ - The request for the YAML file includes the version of `ascli` in the HTTP header `Referer`.
982
+ - The YAML file is not read if the requested version is already installed, or if option `sdk_url` gives the archive.
978
983
  - **Extract the archive**
979
984
  - By default, the archive is extracted to `$HOME/.aspera/sdk`.
980
985
  - The destination folder can be changed by setting the `sdk_folder` option.
@@ -1084,11 +1089,11 @@ Alternatively, the necessary gems can be packaged into a `tar.gz` archive as fol
1084
1089
 
1085
1090
  ```shell
1086
1091
  mkdir temp_folder
1087
- gem install aspera-cli:4.29.0 --no-document --install-dir temp_folder
1092
+ gem install aspera-cli:4.29.1 --no-document --install-dir temp_folder
1088
1093
  find temp_folder
1089
- mv temp_folder/cache aspera-cli-4.29.0-gems
1094
+ mv temp_folder/cache aspera-cli-4.29.1-gems
1090
1095
  rm -fr temp_folder
1091
- tar zcvf aspera-cli-4.29.0-gems.tgz aspera-cli-4.29.0-gems
1096
+ tar zcvf aspera-cli-4.29.1-gems.tgz aspera-cli-4.29.1-gems
1092
1097
  ```
1093
1098
 
1094
1099
  #### Unix-like: Alternative installation using `rvm`
@@ -1224,7 +1229,7 @@ ascli -v
1224
1229
  ```
1225
1230
 
1226
1231
  ```text
1227
- 4.29.0
1232
+ 4.29.1
1228
1233
  ```
1229
1234
 
1230
1235
  To persist the configuration on the host, specify your user's configuration folder as a volume for the container.
@@ -1874,6 +1879,44 @@ The behavior can be controlled with:
1874
1879
  - `--ask-options=<yes|no>` (default=no)
1875
1880
  - `yes`: Optional parameters/arguments are asked to the user.
1876
1881
 
1882
+ #### Hidden Input
1883
+
1884
+ Secrets (passwords, `@secret:`, code or URL pasted after a web login) are read without displaying them.
1885
+ On a terminal, a mark shows the state of the input, without revealing its length:
1886
+
1887
+ | Mark | ASCII | State |
1888
+ |------|-------|-------|
1889
+ | `🔑` | `***` | Waiting for input: nothing typed or pasted yet. |
1890
+ | `…` | `...` | Something was typed or pasted. |
1891
+ | `✓` (green) | `valid` | Checked input: it is valid. |
1892
+ | `✗` (red) | `invalid` | Checked input: it is not valid (yet), e.g. incomplete, mistyped or expired. |
1893
+
1894
+ The ASCII form is used when the locale does not support Unicode.
1895
+
1896
+ Some inputs are checked while they are typed or pasted, e.g. the code displayed by Shares after login (see [Authentication of SAML users](#authentication-of-saml-users)): `✓` or `✗` replaces `…`.
1897
+ If `Enter` is pressed on an input that is not valid, the error is displayed and the input is asked again (`Ctrl-C` to stop).
1898
+ If the standard input is not a terminal, an input that is not valid is an error.
1899
+
1900
+ Keys:
1901
+
1902
+ | Key | Action |
1903
+ |-----|--------|
1904
+ | `Enter` | End the input. |
1905
+ | `Backspace` | Erase the last character. |
1906
+ | `Ctrl-W` | Erase the last word. |
1907
+ | `Ctrl-U` | Erase all (for example, to paste again). |
1908
+ | `Ctrl-D` (Unix), `Ctrl-Z` (Windows) | End the input; if empty: error (end of input). |
1909
+ | `Ctrl-C` | Stop `ascli`. |
1910
+
1911
+ If the standard input is not a terminal (for example, a pipe), the line is read as is, without mark.
1912
+ It is the same if the terminal does not support reading characters one by one (raw mode).
1913
+
1914
+ To read secrets without any mark (no feedback, as `getpass`), set option `ui.hidden_silent` to `yes`:
1915
+
1916
+ ```shell
1917
+ ascli config preset set GLOBAL ui.hidden_silent yes
1918
+ ```
1919
+
1877
1920
  ### Output
1878
1921
 
1879
1922
  Command execution will result in output (terminal, stdout/stderr).
@@ -2365,6 +2408,53 @@ ascli config preset overview --out.colors=no --out.utf8=no
2365
2408
  > [!NOTE]
2366
2409
  > Logs issued before the option is processed (e.g. at startup) use the detected value.
2367
2410
 
2411
+ ### Polling: Option `poll`
2412
+
2413
+ Option `--poll` executes a read-only command several times, and displays its results, for example to wait for a state: a work order complete, a task waiting for a user, a package received.
2414
+ It replaces a shell loop with `sleep`: arguments are read once (identifiers looked up once), the command runs again in the same process.
2415
+
2416
+ Its value is a `Hash` (also with dot-notation, e.g. `--poll.interval=10`):
2417
+
2418
+ | Field | Type | Description |
2419
+ | -------- | -------------- | -------------------------------------------------------------------------------- |
2420
+ | `errors` | `Enum[String]` | What an error of a run does (e.g. an API error, an entity not found yet).<br/>- `fail`: the command ends with this error.<br/>- `retry`: the error is shown on the status line, and the command runs again, as for a result where `until` is false. If the last run fails, the command ends with its error.<br/>Allowed values: `fail`, `retry`.<br/>Default: `fail`. |
2421
+ | `interval` | `Number, String` | Time to wait after a run, before the next one. A duration: a number of seconds, or a `String`, e.g. `30s`, `2m`, `1h 30m`, `1d 02:00:00` (rounded down to seconds).<br/>Default: `5`. |
2422
+ | `max` | `Integer` | Maximum number of runs. No limit by default. |
2423
+ | `show` | `Enum[String]` | Which results are displayed.<br/>- `change`: the first result, then each result whose display differs from the previous one.<br/>- `each`: every result.<br/>- `last`: only the last result, when polling stops (including when the condition is not met).<br/>Allowed values: `change`, `each`, `last`.<br/>Default: `change`. |
2424
+ | `timeout` | `Number, String` | Maximum time since the start of the first run. A duration, as `interval`, e.g. `600`, `10m`, `1h`. A last run occurs at this time. No limit by default. With `max`, polling stops at the first limit reached. |
2425
+ | `until` | `String` | JMESPath expression (https://jmespath.org) evaluated on the JSON view of the result data: after `--select` (for a list of objects), before `--fields` and `--out.query`. Polling stops at the first run where it is true: as in JMESPath, `false`, `null`, empty string, empty list and empty object are false, other values are true. So `@` (the data itself) waits for a non-empty result, e.g. a list with at least one item. The syntax is checked before the first run. If the condition is not met after the last run (`max` or `timeout`), the command fails (exit code 1). |
2426
+
2427
+ `interval` and `timeout` are durations: a number of seconds, or a `String` with units `w`, `d`, `h`, `m`, `s`, e.g. `30s`, `2m`, `1h 30m`, `1d 02:00:00`, as for the [HTTP socket parameters](#http-socket-parameters).
2428
+
2429
+ ```shell
2430
+ # Wait for a work order to complete, check every 10 seconds, at most 30 times
2431
+ ascli orchestrator workorders status <WORKORDER_ID> --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'
2432
+ # Same, with dot-notation, and a timeout of 10 minutes
2433
+ ascli orchestrator workorders status <WORKORDER_ID> --poll.interval=10s --poll.timeout=10m --poll.until='status == `Complete`'
2434
+ # Wait for a task waiting for a user (a non-empty list), display only the last result
2435
+ ascli orchestrator tasks list --poll=@json:'{"interval":5,"max":60,"until":"@","show":"last"}' --format=json
2436
+ # Display the status of the resources of a pool, each time it changes, until interrupted (Ctrl-C)
2437
+ ascli orchestrator pools status <POOL_NAME> --poll.interval=5
2438
+ ```
2439
+
2440
+ Behavior:
2441
+
2442
+ - Polling stops at the first run where `until` is true, or after `max` runs, or at `timeout`.
2443
+ - Without `until`, the command runs `max` times (or until `timeout`, or until interrupted), and the exit status is success.
2444
+ - If `until` is not true after the last run, the command fails with `condition not met after <N> runs` (exit status `1`).
2445
+ - `until` is evaluated on the data of the result (as seen by `--out.query`: JSON values), after `--out.select`, before `--out.fields` and `--out.query`.
2446
+ Expression `@` is true for a non-empty result: e.g. a list with at least one item.
2447
+ - Options `--format`, `--out.fields`, `--out.select` and `--out.query` apply to each result displayed.
2448
+ With `show=change` (default), a result is displayed when its display differs from the previous one.
2449
+ - Before each result displayed, a status line on `stderr` gives the run number and the time, e.g. `poll: run 3/30 2026-01-02 10:20:30`.
2450
+ Output is flushed after each result: it can be read line by line by another program, e.g. with `--format=json` (one line per result).
2451
+ - An error of a run (e.g. an API error) ends the command with this error, unless `errors` is `retry`: then the run counts as one where `until` is false.
2452
+ - `Ctrl-C` ends polling: with `show=last`, the last result is displayed, and the exit status is `130`.
2453
+
2454
+ For safety, option `poll` is refused, before anything is executed, on a command that is not marked read-only: a command that creates, modifies, deletes, sends, starts or cancels something, e.g. `faspex5 packages send`.
2455
+ Commands named `list`, `show`, `status`, `info`, `health`, `ls`, `browse` and `find` are read-only (except `preview show`, which generates a preview file), and some others, e.g. `orchestrator workflows workorders`, `server du`, `node ssync state`.
2456
+ It is also refused with options `once_only` (state saved at each run) and `notify_to` (email sent at each run), with format `nagios`, and in [MCP server](#plugin-mcp-model-context-protocol-server) mode (the client calls the tool again instead).
2457
+
2368
2458
  ### Exit status
2369
2459
 
2370
2460
  The exit code of `ascli` indicates the category of error, so that scripts can react to it:
@@ -2461,7 +2551,21 @@ The following decoders are supported:
2461
2551
  To display the result of an [Extended Value](#extended-value-syntax), use the `config echo` command.
2462
2552
 
2463
2553
  The `extend` decoder is useful to evaluate embedded [Extended Value](#extended-value-syntax) syntax in a string.
2464
- It expects a `@` to close the embedded [Extended Value](#extended-value-syntax) syntax.
2554
+ It expects a `@` to close the embedded [Extended Value](#extended-value-syntax) syntax: `@vault:my_label.password@`.
2555
+ A value inserted by `extend` is not evaluated again: `@extend:@file:<PATH>@` inserts the content of the file as is.
2556
+ If the text on the right of `@extend:` is a single [Extended Value](#extended-value-syntax) without closing `@` (for example `@extend:@file:<PATH>`), it is decoded first, and embedded values in the result are then evaluated.
2557
+
2558
+ Example: a JSON file whose values are read from the [vault](#secret-vault):
2559
+
2560
+ ```json
2561
+ {"title":"Report","recipients":["@vault:my_label.username@"]}
2562
+ ```
2563
+
2564
+ ```shell
2565
+ ascli config echo @json:@extend:@file:<PATH>
2566
+ ```
2567
+
2568
+ In the file, an embedded value without closing `@` (`"@vault:my_label.username"`) is not evaluated: it stays a string, and `@json:@file:<PATH>` does not evaluate values inside the JSON.
2465
2569
 
2466
2570
  Option `parser` allows definition of a default parser when the positional parameter or option expects a `Hash` or `Array`.
2467
2571
  For example, with `--parser=json`, the parameter `{}` will be parsed as an empty JSON Hash, even without prefix `@json:`.
@@ -2780,7 +2884,7 @@ It is a `Hash` with the following keys:
2780
2884
  | `allowed_paths` | `Array<string>` | - | With level `medium`: files and folders that `@file:` can read |
2781
2885
  | `writable_paths` | `Array<string>` | - | With levels `medium` and `high`: folders where files can be written |
2782
2886
 
2783
- | Level | `@file:` | `@ruby:`, `@uri:`, and `@env:` | Secret processed by another extended value | Write files | Features that execute code |
2887
+ | Level | `@file:` | `@ruby:`, `@uri:`, `@env:`, and `@zlib:` | Secret processed by another extended value | Write files | Features that execute code |
2784
2888
  |---|---|---|---|---|---|
2785
2889
  | `low` | Allowed | Allowed | Allowed | Allowed | Allowed |
2786
2890
  | `medium` | Only files in `allowed_paths` | Refused | Refused | Only in `writable_paths` | Refused |
@@ -2788,12 +2892,15 @@ It is a `Hash` with the following keys:
2788
2892
 
2789
2893
  With level `medium`, the real path of the file is checked: a symbolic link leading outside of `allowed_paths` is refused.
2790
2894
 
2895
+ `@zlib:` is refused with levels `medium` and `high`: a small value can decompress to gigabytes and exhaust the memory of the system.
2896
+
2791
2897
  With levels `medium` and `high`, files are written only in `writable_paths` (none by default): downloaded files (`config download`, and transfers that receive files), because a file written where the client chooses could replace a file that is used later, for example a plugin or a shell startup file.
2792
2898
  The real path of the folder is checked: neither `..` nor a symbolic link leading outside of `writable_paths` is accepted.
2793
2899
 
2794
2900
  > [!NOTE]
2795
- > Reading files is not restricted for transfers: a command that sends files (for example `server upload`) reads the files that it is given, whatever the level.
2901
+ > Reading files is not restricted for transfers: a command that sends files (for example `server upload`, or `orchestrator workflows import`) reads the files that it is given, whatever the level.
2796
2902
  > The security level restricts extended values, not the paths of transfers.
2903
+ > A command that reads a local file to display something about its content (for example `orchestrator workflows check_import`) reads it as `@file:`.
2797
2904
 
2798
2905
  The same applies to `@file:<path>` in the parameters of stores of option `vault`, and in option `vault_password` (for example, `token`), although the file is read when used, not when the option is evaluated.
2799
2906
 
@@ -3278,6 +3385,7 @@ pubkey @file:my_key
3278
3385
  remote_certificate chain https://node.example.com/path
3279
3386
  remote_certificate name https://node.example.com/path
3280
3387
  remote_certificate only https://node.example.com/path
3388
+ skill
3281
3389
  smtp_settings
3282
3390
  sync spec
3283
3391
  tokens flush
@@ -3294,15 +3402,15 @@ vault overview
3294
3402
  vault show my_label
3295
3403
  wizard @: url=https://console.example.com/path plugin=console override=yes --username=my_username --password=<PASSWORD>
3296
3404
  wizard @: url=https://f5.example.com/path plugin=faspex5 override=yes --username=my_username --private-key=@file:<PRIVATE_KEY_FILE> --client-id=<CLIENT_ID> --client-secret=<CLIENT_SECRET>
3297
- wizard @: url=https://node.example.com/path plugin=node --username=test --password=<PASSWORD>
3298
- wizard @: url=https://orch.example.com/path plugin=orchestrator --username=test --password=<PASSWORD>
3299
- wizard @: url=https://server1.example.com/path plugin=server --username=my_username --password=<PASSWORD>
3300
- wizard @: url=https://shares.example.com/path plugin=shares --username=test --password=<PASSWORD>
3405
+ wizard @: url=https://node.example.com/path plugin=node override=yes --username=test --password=<PASSWORD>
3406
+ wizard @: url=https://orch.example.com/path plugin=orchestrator override=yes --username=test --password=<PASSWORD>
3407
+ wizard @: url=https://server1.example.com/path plugin=server override=yes --username=my_username --password=<PASSWORD>
3408
+ wizard @: url=https://shares.example.com/path plugin=shares override=yes --username=test --password=<PASSWORD>
3301
3409
  wizard @: url=https://tst.example.com/path plugin=faspio override=yes --username=my_username --password=<PASSWORD>
3302
- wizard @: url=https://tst.example.com/path plugin=httpgw
3303
- wizard @: url=my_org plugin=aoc --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=yes
3410
+ wizard @: url=https://tst.example.com/path plugin=httpgw override=yes
3304
3411
  wizard @: url=my_org plugin=aoc override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=no --interactive=yes
3305
- wizard @: url=my_org plugin=aoc preset=my_preset --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE>
3412
+ wizard @: url=my_org plugin=aoc override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=yes
3413
+ wizard @: url=my_org plugin=aoc preset=my_aoc_preset override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE>
3306
3414
  ```
3307
3415
 
3308
3416
  #### Evaluation order of options
@@ -4141,8 +4249,9 @@ By default, `ascli` assumes that a graphical environment is available on Windows
4141
4249
  The composite option `ui` (use `--ui=help` to display this schema) selects the mode, the way a web login is received, and the browser command:
4142
4250
 
4143
4251
  | Field | Type | Description |
4144
- | -------- | ------------- | -------------------------------------------------------------------------------- |
4252
+ | ------------- | ------------- | -------------------------------------------------------------------------------- |
4145
4253
  | `command` | `Array[String]` | Command that opens a URL, instead of the system default. First item is the executable (full path, or name of an executable found in `PATH`), then its arguments. The URL is added as last argument. When set, it is used to open URLs, whatever the `mode`. |
4254
+ | `hidden_silent` | `Bool` | Secrets typed or pasted on a terminal are read without any feedback (no echo, no mark), as `getpass`. By default, a mark shows whether something was typed or pasted, without revealing the length.<br/>Default: `false`. |
4146
4255
  | `mode` | `Enum[String]` | - `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal`.<br/>- `terminal`: URLs to open are displayed on terminal, and secrets are entered on terminal.<br/>- `browser`: a browser opens URLs, and secrets are entered on a web page.<br/>`text` is an alias for `terminal`, and `graphical` is an alias for `browser`.<br/>Files to edit are always opened with a text editor, whatever the `mode`.<br/>Allowed values: `auto`, `terminal`, `browser`, `text`, `graphical`.<br/>Default: `auto`. |
4147
4256
  | `web_auth` | `Enum[String]` | How the result of a web login (`--auth=web`, SSO) is received.<br/>- `port`: `ascli` listens on the loopback port of `redirect_uri`, the browser is redirected to it.<br/>- `paste`: no port is opened. After login, the browser shows a connection error on `redirect_uri`: copy the full URL from the address bar of the browser and paste it in the terminal. Use it when the browser cannot reach the host that runs `ascli` and a SSH tunnel is not possible. For `shares`, Shares displays a code (a long text of letters, digits, `-` and `_`) instead: paste it in the terminal.<br/>Allowed values: `port`, `paste`.<br/>Default: `port`. |
4148
4257
 
@@ -4199,7 +4308,7 @@ Option `ui.web_auth` (part of the composite option `ui`, see [Graphical Interact
4199
4308
  | `port` (default) | Yes: `ascli` listens on the loopback address of `redirect_uri` | The browser runs on the same system as `ascli`, or an SSH tunnel is possible. |
4200
4309
  | `paste` | No: `redirect_uri` is only used in the login URL | The browser cannot reach the system that runs `ascli`, and no tunnel is possible. |
4201
4310
 
4202
- With `paste`, after login the user gives the result to `ascli` through the terminal (nothing is displayed, as it contains a code or tokens):
4311
+ With `paste`, after login the user gives the result to `ascli` through the terminal (it is hidden, as it contains a code or tokens: see [Hidden Input](#hidden-input)):
4203
4312
 
4204
4313
  - the code displayed by Shares (a long text of letters, digits, `-` and `_`), or the code shown by `ascli config web_login` on the workstation,
4205
4314
  - or the full URL (or only the query) from the address bar of the browser, which shows a connection error on `redirect_uri`: this is expected.
@@ -4280,7 +4389,7 @@ The exchange of the code for a token is done by `ascli` on the server: the secre
4280
4389
  4. Log in. The browser shows a page "Login Complete" with the code to paste, hidden by default:
4281
4390
  - The button **Copy** puts the code in the clipboard.
4282
4391
  - The **eye** button shows or hides the code, to select it manually.
4283
- 5. Paste the code in the terminal of the server (nothing is displayed). `ascli` on the server checks the `state`, and the flow continues as described above, from step 6.
4392
+ 5. Paste the code in the terminal of the server ([hidden](#hidden-input): `🔑` becomes `…`). `ascli` on the server checks the `state`, and the flow continues as described above, from step 6.
4284
4393
 
4285
4394
  The command on the workstation:
4286
4395
 
@@ -4300,7 +4409,7 @@ If `ascli` is not installed on the workstation, the URL of the error page is use
4300
4409
  1. In the SSH session, run the command with `--ui=terminal --ui.web_auth=paste`.
4301
4410
  2. Copy the displayed login URL in the browser of the workstation, and log in.
4302
4411
  3. The browser is redirected to `redirect_uri` (for example `http://localhost:12345/?code=...&state=...`) and shows a connection error: this is expected.
4303
- 4. Copy the full URL from the address bar of the browser, and paste it in the terminal (nothing is displayed, as it contains a code or tokens).
4412
+ 4. Copy the full URL from the address bar of the browser, and paste it in the terminal ([hidden](#hidden-input), as it contains a code or tokens).
4304
4413
  The query alone (`code=...&state=...`) is also accepted.
4305
4414
  The `state` is mandatory: it is checked like in the standard flow, then the flow continues from step 6.
4306
4415
 
@@ -4412,23 +4521,26 @@ To disable this warning, set the option `warn_insecure` to `no`.
4412
4521
  HTTP connection parameters (not `ascp` WSS) can be adjusted using option `http_options`:
4413
4522
 
4414
4523
  | Field | Type | Description |
4415
- | ----------------------- | ------------- | -------------------------------------------------------------------------------- |
4524
+ | ----------------------- | -------------- | -------------------------------------------------------------------------------- |
4416
4525
  | `download_partial_suffix` | `String` | File suffix appended to the target filename while a download is in progress. (Rest)<br/>Default: `.http_partial`. |
4417
- | `keep_alive_timeout` | `Number` | Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)<br/>Default: `2`. |
4418
- | `open_timeout` | `Number` | Maximum time in seconds to wait for a connection to be established. (Net::HTTP)<br/>Default: `60`. |
4419
- | `read_timeout` | `Number` | Maximum time in seconds to wait for data to be read from the server. (Net::HTTP)<br/>Default: `60`. |
4526
+ | `jwt_accepted_offset_sec` | `String, Number` | Tolerance of clock difference with the server: a generated JWT is valid since this duration in the past (`nbf`). (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `300`. |
4527
+ | `jwt_expiry_offset_sec` | `String, Number` | Validity of a generated JWT, used to request a token. (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `3600`. |
4528
+ | `keep_alive_timeout` | `String, Number` | Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `2`. |
4529
+ | `open_timeout` | `String, Number` | Maximum time in seconds to wait for a connection to be established. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `60`. |
4530
+ | `read_timeout` | `String, Number` | Maximum time in seconds to wait for data to be read from the server. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `60`. |
4420
4531
  | `retry_max` | `Integer` | Maximum number of retry attempts. (Rest)<br/>Default: `1`. |
4421
4532
  | `retry_on_error` | `Bool` | Retry the request on any HTTP error response. (Rest)<br/>Default: `false`. |
4422
4533
  | `retry_on_timeout` | `Bool` | Retry the request on connection timeout. (Rest)<br/>Default: `true`. |
4423
4534
  | `retry_on_unavailable` | `Bool` | Retry the request on HTTP 503 Service Unavailable. (Rest)<br/>Default: `true`. |
4424
- | `retry_sleep` | `Integer` | Delay in seconds between retry attempts. (Rest)<br/>Default: `4`. |
4535
+ | `retry_sleep` | `String, Number` | Delay in seconds between retry attempts. (Rest) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `4`. |
4425
4536
  | `ssl_options` | `Array[String]` | List of OpenSSL option flags to set on the HTTP session (e.g. `IGNORE_UNEXPECTED_EOF`). (SSL) |
4426
- | `token_cache_max_age` | `Integer` | Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth)<br/>Default: `1800`. |
4427
- | `token_refresh_threshold` | `Integer` | Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth)<br/>Default: `120`. |
4537
+ | `token_cache_max_age` | `String, Number` | Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `1800`. |
4538
+ | `token_refresh_max_age` | `String, Number` | Age in seconds (since it was obtained) above which the token is proactively refreshed, `0` for no limit. E.g. keeps a session alive when the refresh token expires at the same time as the token (Shares). (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `0`. |
4539
+ | `token_refresh_threshold` | `String, Number` | Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `120`. |
4428
4540
  | `user_agent` | `String` | Value sent in the `User-Agent` HTTP request header. (Rest) |
4429
- | `write_timeout` | `Number` | Maximum time in seconds to wait for data to be written to the server. (Net::HTTP)<br/>Default: `60`. |
4541
+ | `write_timeout` | `String, Number` | Maximum time in seconds to wait for data to be written to the server. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `60`. |
4430
4542
 
4431
- Time values are set in **seconds** and can be of type either `Integer` or `Float`.
4543
+ Time values are durations: a number of **seconds** (`Integer` or `Float`), or a `String`, e.g. `30s`, `12h`, `1d`, `1h 30m`, `1d 02:00:00`.
4432
4544
  Any additional key is forwarded as a setter to the `Net::HTTP` session.
4433
4545
  For a full list, refer to the Ruby library: [`Net::HTTP`](https://github.com/ruby/net-http/blob/master/lib/net/http.rb).
4434
4546
 
@@ -4440,6 +4552,13 @@ Example:
4440
4552
  ascli aoc admin package list --http-options=@json:'{"read_timeout":10.0}'
4441
4553
  ```
4442
4554
 
4555
+ With a server whose token and refresh token expire at the same time (e.g. Shares: 24 hours), `token_refresh_max_age` refreshes the token before its refresh token expires.
4556
+ A command run more often than this duration (e.g. scheduled every 12 hours) keeps the session alive without a new login, provided the token stays in cache (`token_cache_max_age`):
4557
+
4558
+ ```shell
4559
+ ascli shares files browse / --http-options=@json:'{"token_cache_max_age":"1d","token_refresh_max_age":"12h"}'
4560
+ ```
4561
+
4443
4562
  The option `ssl_options` corresponds to a list of options as listed in `man SSL_CTX_set_options`.
4444
4563
  The default initial value is the default of Ruby as specified in `openssl/ssl.rb`.
4445
4564
  Each option can be specified as a `String` with the same name as in the OpenSSL library by removing the prefix: `SSL_OP_`, or an `Integer` (for example, `0` resets to no option).
@@ -4713,6 +4832,17 @@ Parameters in transfer-spec can be modified with option `ts`.
4713
4832
  > [!NOTE]
4714
4833
  > Parameters in `transfer` are specific for each agent type and are described in the agents respective sections.
4715
4834
 
4835
+ #### Dry run of a transfer
4836
+
4837
+ With option `dry_run` (`--dry-run=yes`), a transfer command does not start the transfer: its result is the final transfer spec, as it would be given to the agent (with option `ts` and file list applied), with secrets hidden (unless `--out.secrets=yes`).
4838
+ Nothing is transferred.
4839
+
4840
+ ```shell
4841
+ ascli server download /aspera-test-dir-large/100MB --dry-run=yes
4842
+ ```
4843
+
4844
+ Commands that change something before the transfer are refused with option `dry_run`, before any change: `aoc packages send` and `faspex5 packages send` (the package is created first), `sync` commands, and preview generation of `preview`.
4845
+
4716
4846
  #### Asynchronous Transfer Mode
4717
4847
 
4718
4848
  Adding `asynchronous: true` to the `transfer` option makes `ascli` return immediately after
@@ -4873,6 +5003,37 @@ ascli config ascp logs sessions /path/to/folder/aspera-scp-transfer.log
4873
5003
  | `overdrives` | Sessions with loss due to overdriving of network or storage. |
4874
5004
  | `records` | Log lines parsed into records: `samples`, `sessions` or `transfers` (see below). |
4875
5005
  | `fields` | Description of the fields of records: `samples`, `sessions` or `transfers`. |
5006
+ | `find` | `ascp` log files of this system (no argument): `path`, `size`, `modified`, `source`, most recent first. |
5007
+
5008
+ Command `find` lists the local files that contain `ascp` log lines, in the log folders of the installed products (including `<logging><directory>` of their `aspera.conf`), of `ascp` found in `PATH`, of IBM Aspera for Desktop, and in the default locations of `ascp` (below). Give the paths it lists to the other commands:
5009
+
5010
+ ```shell
5011
+ ascli config ascp logs find --fields=path
5012
+ ascli config ascp logs sessions ~/Library/Logs/Aspera
5013
+ ```
5014
+
5015
+ `ascp` writes its log in the folder of option `-L`, else in `<logging><directory>` of `aspera.conf`, else in a location that depends on the OS:
5016
+
5017
+ | OS | Default location of the `ascp` log |
5018
+ |---------------|------------------------------------|
5019
+ | Linux, Unix | syslog, facility `local2`: `/var/log/messages` or `/var/log/syslog` by default, `/var/log/aspera.log` if syslog is configured to separate the Aspera logs. |
5020
+ | macOS | `~/Library/Logs/Aspera` (`/Library/Logs/Aspera` for `root`). |
5021
+ | Windows | `var\log` of the product if this folder exists, else the folder of `ascp`. |
5022
+
5023
+ For the `ascp` used by `ascli`, `ascli config ascp info --fields=log` gives this location (a folder, or `syslog`).
5024
+
5025
+ In a folder, the file is `aspera-scp-transfer.<n>.log` (rotated, `n` from `0` to `log_count` of `aspera.conf`), and `aspera-scp-transfer.log` is a hard link to the current one. `ascp` 4 (`ascp4`) writes `ascp4.<n>.log`.
5026
+
5027
+ | Application | Location of the `ascp` log |
5028
+ |------------------------|----------------------------|
5029
+ | `ascli`, agent `direct` or `transferd` | No `-L`: default location above (e.g. on Linux in syslog). With agent `direct`, `-L` can be set with `ascp_args` (see above). |
5030
+ | IBM Aspera Connect | `-L` set to its log folder (e.g. `~/Library/Logs/Aspera_Connect`). |
5031
+ | IBM Aspera for Desktop | Log folder of the application, also used for its own logs and those of `transferd`: `~/Library/Logs/com.ibm.software.aspera.desktop` on macOS, `%APPDATA%\com.ibm.software.aspera.desktop\logs` on Windows, `~/.config/com.ibm.software.aspera.desktop/logs` on Linux. |
5032
+ | IBM Aspera Transfer Daemon | `-L` set to `fasp_runtime.log.dir` of its configuration (or `localLog` of the transfer), else the default location above. |
5033
+ | Server side of a transfer | On the server, configured by its `aspera.conf`, or by option `-R` of the client: see [`server logs`](#analyze-ascp-logs-of-the-server). |
5034
+
5035
+ On Linux, the syslog files are often readable only by `root`, and a container may have no syslog daemon (the log of `ascp` is then lost): use `-L`, or read the system journal, e.g. `journalctl -t ascp | ascli config ascp logs summary -`.
5036
+ For the other logs of Aspera products, see the IBM support page [Where are IBM Aspera logs located](https://www.ibm.com/support/pages/where-are-ibm-aspera-desktop-client-or-ibm-aspera-server-logs-located).
4876
5037
 
4877
5038
  Log files compressed with gzip (e.g. rotations `aspera.log-20261101.gz`, `aspera-scp-transfer.1.log.gz`) are read directly, in a folder or given as argument; gzip is detected from the first bytes of the file, not from its name. Argument `-` reads the logs from the standard input, plain or compressed with gzip:
4878
5039
 
@@ -6407,7 +6568,7 @@ If the transfer user has no docroot and the transfer does not use a token, you c
6407
6568
  ```text
6408
6569
  ascli -h
6409
6570
  NAME
6410
- ascli -- a command line tool for Aspera Applications (v4.29.0)
6571
+ ascli -- a command line tool for Aspera Applications (v4.29.1)
6411
6572
 
6412
6573
  SYNOPSIS
6413
6574
  ascli [GLOBAL_OPTIONS] <command> [OPTIONS] [ARGS]
@@ -6464,7 +6625,7 @@ OPTIONS: global
6464
6625
  -h, --help Show this message
6465
6626
  --show-config Display parameters used for the provided action
6466
6627
  -v, --version Display version
6467
- --ui=HASH User interface (dot-notation: mode, web_auth, command)
6628
+ --ui=HASH User interface (dot-notation: mode, web_auth, hidden_silent, command)
6468
6629
  --invalid-characters=VALUE Replacement character and invalid filename characters
6469
6630
  --log-level=ENUM Log level
6470
6631
  --log-format=VALUE Log formatter
@@ -6511,6 +6672,7 @@ OPTIONS: global
6511
6672
  --query=HASH Additional filter for for some commands (list/delete)
6512
6673
  --bulk=yes|no Bulk operation (only some)
6513
6674
  --bfail=yes|no Bulk operation error handling
6675
+ --poll=HASH Repeat a read-only command (dot-notation: interval, max, timeout, until, show, errors)
6514
6676
  --ts=HASH Override transfer spec values
6515
6677
  --to-folder=VALUE Destination folder for transferred files
6516
6678
  --sources=VALUE How list of transferred files is provided (@args,@ts,Array)
@@ -6591,6 +6753,78 @@ Created ./foo.rb
6591
6753
  ascli --plugin-folder=. foo
6592
6754
  ```
6593
6755
 
6756
+ #### Writing a plugin
6757
+
6758
+ A plugin is a Ruby file in a plugin folder (option `plugin_folder`, or folder `plugins` of the configuration folder).
6759
+
6760
+ - **Name**: the file name is the plugin name, which is the first command, e.g. file `my_app.rb` for command `my_app`.
6761
+ The file defines class `Aspera::Cli::Plugins::<Class>`, the name in CamelCase (`MyApp`), subclass of:
6762
+ - `Base`: no common option.
6763
+ - `BasicAuth` (`aspera/cli/plugins/basic_auth`): options `url`, `username`, `password`, method `basic_auth_api` returns a REST client with HTTP Basic authentication.
6764
+ - `Oauth` (`aspera/cli/plugins/oauth`): options of `BasicAuth`, and `auth` (default `jwt`), `client_id`, `client_secret`, `redirect_uri`, `private_key`, `passphrase`.
6765
+ - **Requires**: the plugin requires the files of the gem that it uses, e.g. `require 'aspera/cli/plugins/base'` (the `lib` folder of the gem is in the Ruby load path).
6766
+ Built-in plugins load only what they use: a class of the gem (for example `Plugins::Oauth`, `Rest::Client`) may not be loaded yet when the plugin is read (`NameError: uninitialized constant`).
6767
+ - **Options**: `option :<name>, description: '...'` (optional: `default:`, `allowed:` a type or a list of values), value read with `options.get_option(:<name>)` (`mandatory: true` to require it).
6768
+ `use_options <Module>` adds the options of a module, e.g. `use_options OauthWebOptions` (`client_id`, `client_secret`, `redirect_uri`) for the OAuth web flow only, without the other options of `Oauth`.
6769
+ - **Commands**: `command :<name>, description: '...'`, inside `commands_under :<name> do ... end` for sub-commands.
6770
+ Positional arguments: `arguments: [{name: :<name>, description: '...'}]` (optional: `mandatory: false`, `default:`, `type: Hash`, `multiple: true`).
6771
+ `read_only: true` for a command that changes nothing (allowed with option `poll`).
6772
+ - **Actions**: the method `action_<command path>`, e.g. `action_item_show` for `item show`, receives the arguments as keyword arguments (and `**` for others).
6773
+ It returns a result, displayed according to option `format`: `Result::SingleObject.new(<Hash>)`, `Result::ObjectList.new(<Array of Hash>)`, `Result::Status.new('<text>')`, `Result::Nothing.new`.
6774
+ - **REST**: `Rest::Client.new(base_url:, auth:)` (`aspera/rest`), methods `read`, `create`, `update`, `delete` (JSON), and `call` for other cases:
6775
+ - `auth`: `{type: :basic, username:, password:}`, or `{type: :oauth2, grant_method: :web, client_id:, ...}` (see `lib/aspera/oauth/client`).
6776
+ Parameters `path_authorize` and `path_token` are paths from `base_url`, or absolute URLs, when the token is created on another host than the authorization page.
6777
+ Parameter `token_field` is the field of the token in the answer (default `access_token`), or a dot-separated path of a nested field, e.g. `authed_user.access_token` for a Slack user token.
6778
+ - Raw body, e.g. binary, sent as is: `call(operation: 'PUT', body: <String or IO>, headers: {'Content-Type' => '<MIME_TYPE>'})`.
6779
+ An `IO` (e.g. `File.open(path, 'rb')`) is streamed from its current position, without loading the file in memory.
6780
+ - **Errors**: raise `Cli::BadArgument` (wrong argument or option) or `Cli::Error`.
6781
+ For any other error, the location in the plugin (file and line) is logged at level `info`.
6782
+ - **Security**: a plugin is code: plugins from other folders than the gem are loaded at [Security Level](#security-level) `low` only.
6783
+
6784
+ Example: plugin `my_app` for a REST API with Basic authentication: `my_app info`, `my_app item list`, `my_app item show <ID>`.
6785
+
6786
+ ```ruby
6787
+ # Plugin `my_app`, file `my_app.rb` in a plugin folder, class `MyApp`
6788
+ # Files of the gem used by the plugin (its `lib` folder is in the load path)
6789
+ require 'aspera/cli/plugins/basic_auth'
6790
+
6791
+ module Aspera
6792
+ module Cli
6793
+ module Plugins
6794
+ # Options `url`, `username` and `password` of `BasicAuth`
6795
+ class MyApp < BasicAuth
6796
+ application_name 'My Application'
6797
+ option :page_size, description: 'Number of items per page', allowed: Integer, default: 100
6798
+
6799
+ command :info, description: 'Show application information', read_only: true
6800
+ commands_under :item, description: 'Manage items' do
6801
+ command :list, description: 'List items', read_only: true
6802
+ command :show, description: 'Show an item', arguments: [{name: :id, description: 'Item identifier'}], read_only: true
6803
+ end
6804
+
6805
+ # Command `info`
6806
+ def action_info(**) = Result::SingleObject.new(api.read('info'))
6807
+
6808
+ # Command `item list`
6809
+ def action_item_list(**) = Result::ObjectList.new(api.read('items', {limit: options.get_option(:page_size)}))
6810
+
6811
+ # Command `item show <ID>`, with arguments as keyword arguments
6812
+ def action_item_show(id:, **) = Result::SingleObject.new(api.read("items/#{id}"))
6813
+
6814
+ private
6815
+
6816
+ # REST client of the application, with Basic authentication
6817
+ def api = @api ||= basic_auth_api
6818
+ end
6819
+ end
6820
+ end
6821
+ end
6822
+ ```
6823
+
6824
+ ```shell
6825
+ ascli --plugin-folder=<FOLDER> my_app item list --url=https://app.example.com/api --username=<USERNAME> --password=<PASSWORD> --page-size=10
6826
+ ```
6827
+
6594
6828
  ### Plugins vs Transfer Agents
6595
6829
 
6596
6830
  Plugins typically represent a specific remote application on which `ascli` can operate, while transfer agents are the underlying components that handle the actual data transfer.
@@ -10579,7 +10813,8 @@ Option `ui.web_auth` selects how the result of the login is received (see [Web l
10579
10813
  - `paste`: the browser may run on another system than `ascli` (for example, `ascli` runs on a server accessed with SSH), without tunnel.
10580
10814
  No local port is opened and `--redirect-uri` is not used.
10581
10815
  `ascli` generates a random `state` and opens the SAML login page with `RelayState` `aspera://device-code?state=<state>`.
10582
- After login, Shares displays a code (a long text of letters, digits, `-` and `_`). The user copies it and pastes it in the terminal (nothing is displayed, as the code contains a token).
10816
+ After login, Shares displays a code (a long text of letters, digits, `-` and `_`), and tells how long the code and the session token are valid. The user copies the code and pastes it in the prompt of `ascli` ([hidden](#hidden-input), as the code contains a token).
10817
+ The mark of the prompt becomes `✓` if the code is valid, else `✗`. A code that is not valid is asked again.
10583
10818
  If standard input is not a terminal, the code is read from it.
10584
10819
  `ascli` checks that the `state` of the code is the one it generated.
10585
10820
  The code is valid for **15 to 30 minutes** after its display: it is encrypted with a key derived from the `state` and from the current time in slots of 15 minutes (the previous and the next slot are also accepted).
@@ -10587,6 +10822,7 @@ Option `ui.web_auth` selects how the result of the login is received (see [Web l
10587
10822
  The code is also protected against typing errors and modification.
10588
10823
 
10589
10824
  The token is saved, and renewed with its refresh token: the browser is opened again only if this fails.
10825
+ Shares gives a token and a refresh token that both expire after 24 hours: then a new login is needed, unless the token is refreshed before (see `token_refresh_max_age` in [HTTP socket parameters](#http-socket-parameters)).
10590
10826
  Option `username` is optional: with it, the token is saved for this user.
10591
10827
 
10592
10828
  > [!IMPORTANT]
@@ -10784,6 +11020,7 @@ ascli orchestrator workflows check_import my_workflow.yml
10784
11020
  ```
10785
11021
 
10786
11022
  It displays one line per issue, or `no problem found`.
11023
+ The file is read as `@file:`: at [Security Level](#security-level) `medium`, only in `allowed_paths`, and not at level `high`.
10787
11024
  An issue has these fields:
10788
11025
 
10789
11026
  | Field | Description |
@@ -10796,6 +11033,8 @@ An issue has these fields:
10796
11033
 
10797
11034
  Checked: format of the file (YAML, number of elements, plain format layout), attributes, `error_free`, action template keys, XML of the graph, `Start`, `End`, `Fail` and `Error` nodes, unique step names, step template, prerequisites, `Synch_factor`, steps that have no output or no prerequisite, references to outputs and parameters.
10798
11035
 
11036
+ A package (`.wkf`) whose files exceed 256 MiB once decompressed is not checked: it is reported as an issue (`package.too_large`).
11037
+
10799
11038
  With the specifications of plugins (see `plugins spec show`), it also checks action templates and the inputs of steps, for the settings of each template:
10800
11039
 
10801
11040
  - plugin class name, attributes of the template, and their values (type, allowed values),
@@ -11577,7 +11816,7 @@ With both transports:
11577
11816
  - Extended value `@stdin:` is refused.
11578
11817
  - `@secret:` is entered by the user on a web page, see [Secrets entered in a web page](#secrets-entered-in-a-web-page).
11579
11818
  - Secrets are hidden in responses, also a value shorter than 8 characters as a word in a text (for example, a short password in an error message).
11580
- - The [Security Level](#security-level) is `high` by default: `@ruby:`, `@file:` (also in the parameters of stores of option `vault`), `@uri:`, and `@env:` are refused, and a secret must be the whole value: hidden in results, it cannot be processed by another extended value.
11819
+ - The [Security Level](#security-level) is `high` by default: `@ruby:`, `@file:` (also in the parameters of stores of option `vault`), `@uri:`, `@env:`, and `@zlib:` are refused, and a secret must be the whole value: hidden in results, it cannot be processed by another extended value.
11581
11820
  It applies to commands sent by the client, and to presets, because the client can modify presets.
11582
11821
  Commands sent by the client cannot change option `security`.
11583
11822
  Features that execute code, such as option `notify_template` or command `config plugins create`, plugins, and writing to a file chosen by the client (option `out.file`), are refused, see [Security Level](#security-level).
@@ -9,6 +9,7 @@ require_relative '../rest'
9
9
  require_relative '../oauth/client/factory'
10
10
  require_relative '../log'
11
11
  require_relative '../assert'
12
+ require_relative '../inflate'
12
13
  require_relative '../secret/hider'
13
14
  require_relative '../environment'
14
15
  require_relative '../rainbow'
@@ -73,7 +74,9 @@ module Aspera
73
74
  SIGNATURE_DELIMITER = '==SIGNATURE=='
74
75
  # Default validity when generating a bearer token "manually"
75
76
  BEARER_TOKEN_VALIDITY_DEFAULT = 86400
76
- private_constant :SIGNATURE_DELIMITER, :BEARER_TOKEN_VALIDITY_DEFAULT
77
+ # Maximum size of a decoded bearer token (a few kB): it is given by the user, a client, or a server
78
+ BEARER_TOKEN_MAX_INFLATED_SIZE = 65_536
79
+ private_constant :SIGNATURE_DELIMITER, :BEARER_TOKEN_VALIDITY_DEFAULT, :BEARER_TOKEN_MAX_INFLATED_SIZE
77
80
  # Node API permissions: delete list mkdir preview read rename write
78
81
  ACCESS_LEVELS = %w[delete list mkdir preview read rename write].freeze
79
82
  # Special HTTP Headers
@@ -189,8 +192,12 @@ module Aspera
189
192
  end
190
193
 
191
194
  # Decode an Aspera Node bearer token
195
+ # @param token [String] Base64 of deflated payload and signature
196
+ # @return [Hash] Payload
197
+ # @raise [ParameterError] If the decoded token is too large
192
198
  def decode_bearer_token(token)
193
- return JSON.parse(Zlib::Inflate.inflate(Base64.decode64(token)).partition(SIGNATURE_DELIMITER).first)
199
+ inflated = Inflate.limited(Base64.decode64(token), max_size: BEARER_TOKEN_MAX_INFLATED_SIZE, what: 'Node bearer token')
200
+ return JSON.parse(inflated.partition(SIGNATURE_DELIMITER).first)
194
201
  end
195
202
 
196
203
  # @return [Hash] Headers to call node API with access key and auth