aspera-cli 4.27.5 → 4.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba71af1e93e41d6942ddcf6667980c1c4164fe36ad099b22745574a548bba66d
-  data.tar.gz: 83326746bc3d07843de75565f78bf57e6678a706eb0b9a66e6405f46be07cc8c
+  metadata.gz: 53275fa425245c33fe497658f6da1ba3cb13c1d02e0c0e4082d283c44b02af1c
+  data.tar.gz: 68f60148c6ec53c98143ed2211d8474dc666b29cbf41c43604dc1ec208faaa1b
 SHA512:
-  metadata.gz: 7ec3c7a4174ae432743a3215e296738c2d7cecf9a27751558dc706c4b6098b885bb0ad7cc86aebc7b4fc6e75d4197ebba74e4df20dd6c4cde7505fb297331e81
-  data.tar.gz: '04548d7fe93ac3256c1912ea39d9830c6e1ae35dd6c6d6ac470bcfbce5220ea2092a137aaf1c2d78662aaaa9dfbd05a7138933f1e8de9edabcd5ea6c069d83bf'
+  metadata.gz: b8fe08d94ac160cf2ec56a351afbb2ba4afde34ce8d80333de9400f3fd26f342041bb63167dd3ce708f3e86add4cee7d0761d843b5362f0169fb574978ff8314
+  data.tar.gz: bb0c4deb1bd46b3e04a761e7de67730cfbe293a1580fa3a84c4acd33bb7b7d146a906f99985e05b15ba74c6884be1217240d92bf48f81dc2ceb3212fe40b18a7

data/CHANGELOG.md

@@ -1,5 +1,161 @@
 # Changes (Release notes)
 
+## 4.28.0
+
+Released: 2026-10-22
+
+Highlights: security hardening of local web servers (authentication, minimum secret strength, cross-site requests refused), new option `security`, `mcp server` over HTTPS with token or OAuth authentication, JMESPath queries (`--out.query`), exit code by category of error, context-aware shell completion (also PowerShell), tables fitted to the terminal width. Ruby 3.2 or later is required.
+
+### New Features
+
+* `ascli`:
+  * Local web servers refuse a weak secret at startup (`auth_token` of `mcp server`, `secret_token` of `faspex5 postprocessing`, `password` of `node emulator` and gateways): minimum strength set by parameter `*_min_bits` (default `80`, `0` disables), estimated with gem `zxcvbn` if installed.
+  * New option `security`: level `medium` or `high` restricts extended values `@ruby:`, `@uri:`, `@env:` and `@file:` (see manual).
+  * `@secret:` asks for the secret on a local web page in the browser when option `ui` is `graphical`.
+  * Local web pages (authentication, secret request, OAuth consent) follow the light or dark theme of the system or browser.
+  * Option `ui` is extended (still compatible: `--ui=text|graphical`): sub-option `mode` (`auto`, `terminal`, `browser`) and `command` (array: browser command, URL appended). It replaces the environment variables `ASPERA_BROWSER` and `BROWSER`, which are no longer used.
+  * New option `--out.query`: [JMESPath](https://jmespath.org) expression (or `@ruby:` lambda) to filter and reshape results, as `--query` of the AWS and Azure CLIs. New gem dependency: `jmespath`.
+  * The exit code indicates the category of error (e.g. `3` authentication, `4` not found, `5` transfer, `6` network): see `ascli -h` or the manual.
+  * Tables fit the terminal width: text columns are wrapped. Parameter `width` of `--out.table` sets the maximum width.
+  * Schema tables (value `help` of an option or argument, `config ascp spec`, `config sync spec`, `config agents parameters`, manual) indicate required fields.
+  * Shell completion follows the context: options of plugin and command, values and types of options and arguments, keys of structures, aliases and abbreviations, local files for uploads, with descriptions in Zsh, Fish and PowerShell.
+  * New composite option `--temp` with sub-options `folder`, `clean` and `expiry`: age of `ascp` file lists left by interrupted commands, deleted when a command starts (a duration, e.g. `30d`, default `5d`, `false`: never, `0`: all). Options `--temp-folder` and `--clean-temp` are deprecated.
+* `config`:
+  * New command `completion powershell` displays the completion script of PowerShell (see manual).
+  * `ascp spec`: Optional argument: name of agent, to display only the parameters it supports (as `config ascp schema`), or `overview`, for one column per agent.
+* `mcp`:
+  * `server`: Authentication of transport `http` with a static token (`auth_token`) or OAuth 2.0 (`oauth`), new option `public_url`.
+  * `server`: HTTPS for transport `http` with options `url`, `cert`, `key` and `chain`. Options `bind` and `port` are deprecated: use `url`.
+  * `server`: `@secret:` asks the user on a web page (MCP URL mode elicitation): the secret is not sent to the AI model.
+* `faspex5`:
+  * `postprocessing`: New parameters `secret_token` (`?token=` in URL) and `allowed_ips` (addresses or CIDR) restrict callers.
+  * `postprocessing`: Parameter `lambda` of the URL query evaluates a Ruby script returning a lambda, called with the webhook values (was ignored).
+  * `gateway` (and `aoc gateway`): New parameters `username` and `password` (HTTP Basic, as Faspex 4).
+* `orchestrator`:
+  * New command `workflows development` displays the Workflow Authoring Guide, the Action Template Reference and the Plugin Manual (from GitHub), also used by AI assistants through `mcp server`: whole document, one section, or table of contents up to a level (default per document, or optional argument).
+  * `workflows export` with option `dependencies` saves a package (`.wkf`) with sub-workflows and remote nodes.
+  * `workflows import` takes an optional argument with options `folder_id`, `publish` and `link_to_subworkflows`. `workflows list` displays `folder_id`.
+  * New commands `monitors list` (monitors of a type: remote node monitors give the names of remote nodes), `queues list`, `pools status` and `journal files` (files recorded in a journal book). `--query=help` displays the query parameters of each API call, from the OpenAPI description of Orchestrator (corrected from the source code of Orchestrator 4.1.6, OpenAPI 3.1).
+  * New command `workflows check_import` checks a workflow file (`.yml` or `.wkf`) locally before import, and reports problems with a severity, a code and a location (as the web UI import does). `workflows import` logs these problems as warnings.
+  * New command `plugins spec` displays the specifications of action plugins (from GitHub, option `plugin_specs`): template attributes with their allowed values, inputs and outputs with the template settings they depend on. Used by AI assistants through `mcp server`, and by `workflows check_import` to check action templates and the inputs of steps (attributes and values, required inputs not mapped, inputs and outputs the plugin does not have).
+  * New command `workflows find_constraints` lists the conflicts and missing plugins found by Orchestrator for a file already on the server. `workflows import_with_constraints` refuses an import that Orchestrator would handle incorrectly (plugins not enabled, partial resolution of conflicts).
+* `shares`:
+  * New commands `share list`, `share event create`, `admin directory`, `admin user|group search`, `admin group local users`, `admin authenticate`, and `admin user|group all transfer_settings delete` (reset to global settings).
+  * `health` uses the `/health_check` endpoint: status of each license and node.
+  * Help of `admin share user_permissions|group_permissions create|modify` shows the request body.
+* `sync`:
+  * `target_rate` in `sync_info` accepts suffixes `k`, `m` and `g` (e.g. `100m`).
+
+### Issues Fixed
+
+* `ascli`:
+  * Tokens displayed by `bearer_token`, `bearer_token_node` (`aoc`, `faspex5`, `node`), `aoc admin node bearer_token` and `node basic_token` were returned to the AI client by `mcp server`. They are now hidden.
+  * Secrets are also hidden by value, wherever they appear in logs, results and `mcp server` responses (e.g. in an error message, or as a key name): values of secret options (e.g. `password`) and of presets (e.g. read alone with `@preset:<name>.password`), of `@secret:` and `@vault:`, OAuth tokens, generated bearer and basic tokens, secrets of transfer specs. In `mcp server` responses, a value shorter than 8 characters is also hidden as a word in a text.
+  * With option `security` level `medium` or `high` (default of `mcp server`), a secret read by `@secret:`, `@vault:` or `@preset:` cannot be processed by another extended value (e.g. `@list:`, `@json:`, or in a text with `@extend:`), nor be a parameter name of `config preset set`: the result could reveal it to the AI client.
+  * Secret values of URL query parameters (e.g. `token`, `client_secret`) are hidden in logs.
+  * Logs: secrets in a Ruby `Struct` or object (`password="..."`) were shown. Secrets of a dumped structure are now hidden by field name before it is rendered, whatever `log.format`.
+  * Local web servers (`faspex5 postprocessing`, `faspex5 gateway`, `aoc gateway`, `node emulator`, `mcp server`, `--auth=web`):
+    * Requests that a web page in the browser can send are refused: `Host` not loopback on a loopback server (DNS rebinding), `Origin` of another site.
+    * A `url` with an IPv6 address, or parameter `chain`, failed at startup.
+    * WEBrick messages are logged at debug level.
+  * `--auth=web`:
+    * Login could wait forever when the browser called back early, or when `redirect_uri` has a path (HTTP 404).
+    * A `redirect_uri` on loopback other than `127.0.0.1` (e.g. `[::1]`) was refused.
+    * Ctrl-C ended with an internal error instead of stopping the command.
+    * The page after login, whose URL contains the authorization code, could be cached, framed, or sent as referrer.
+  * Error messages of servers in Ruby (e.g. Orchestrator) included the backtrace of the exception: it is in the debug log only.
+  * Network errors and resources not found by name were reported as `Other(<exception class>)`.
+  * Terminal output:
+    * Unicode (`--out.utf8`): detection follows the precedence of locale variables (`LC_ALL=C` disables it), and supports Windows Terminal, VS Code, Git Bash, ConEmu and terminals setting `TERM`.
+    * Colors (`--out.colors`): `NO_COLOR`, `CLICOLOR` and `CLICOLOR_FORCE` follow conventions, and results written with `--out.file` no longer contain ANSI codes.
+    * Without Unicode, symbols are replaced with ASCII (e.g. hidden secret `🔑` becomes `***`).
+  * A boolean or decimal result (e.g. `config echo @json:true`) failed with an internal error.
+  * `--out.select` refused a Ruby lambda (`@ruby:`).
+  * Help and manual: a parameter with alternatives (`oneOf`) had no type (which broke the PDF manual), and alternatives had no title.
+  * Value `help` of an option or argument displays the schema as `config sync spec`: with fields of alternatives (`oneOf`), deprecations and examples, and for `--ts=help` the supported agents and `ascp` options. `config agents parameters` displays allowed values and defaults.
+  * Removed gem dependencies `blankslate` and `word_wrap`: descriptions in schema tables are wrapped to the terminal width instead of cut at 120 characters.
+  * Transfer spec parameter `target_rate` is in bps as documented (without suffix or with `k` it was taken as kbps, an integer was rejected), and `sync` ignored it (and `target_rate_kbps` with format `args`).
+  * An asynchronous transfer with agent `direct` (default of `mcp server`) failed with `failed to open input file list`: the file list was deleted at the end of the command. Temporary files of `ascp` are now deleted when the transfer ends.
+  * `--clean-temp=no` also kept the old `ascp` file lists left by interrupted commands, and two commands starting at the same time could fail when deleting the same old file list.
+* `config`:
+  * `preset get`: The value of a secret option (e.g. `password`) was displayed, and returned to the AI client by `mcp server`. It is now hidden, unless `--out.secrets=yes` (command line only, never in `mcp server`).
+  * `preset`: A secret made of digits only (e.g. `password`, set with `config preset set`, or not quoted in the YAML file) was a number, shown in results and `mcp server` responses: it is now a `String`, hidden.
+  * `vault`:
+    * `system` (macOS): the password and `username` were not returned, and special characters were stored escaped.
+    * `file`: `password` did not migrate a vault of version 4.26.0 or earlier to PBKDF2. The file is loaded with YAML safe loading.
+    * `vault` (HashiCorp): `list` failed after a secret was deleted.
+    * `1password`: `url` is read from the website of the item.
+    * `preset secure` failed on a missing secret (`system`, `1password`), and `@vault:` on a label containing dots.
+  * `completion words`: Extended values on the command line were evaluated at each `Tab` (e.g. `@ruby:` code executed, `@stdin:` waiting for input).
+  * `completion`: Bash: words containing `=` or `:` (e.g. a URL) broke completion of the next words, and each `Tab` checked for a newer gem version on the network.
+  * `documentation`: In `toc`, lines of code blocks (e.g. shell comments) were taken as headings, and they ended the extracted section. `--select` did not apply to `toc` (keys were symbols).
+  * `transfer status`: For agent `direct`, `bytes_transferred` (sum of `TransferBytes` of the sessions) and `ended_at` were not set.
+  * `sync translate`: Options `-C`, `--ws-connect`, `-D`, `--scan-interval` and `--remote-scan-interval` were translated incorrectly.
+* `mcp`:
+  * REST error messages were repeated once more at each tool call.
+  * `server`: Option `--out.query` was ignored.
+* `faspex5`:
+  * `postprocessing`, `gateway` (and `aoc gateway`): Invalid requests return HTTP 400, 403 or 404 instead of 500, without stack trace or path of the script.
+  * `packages send` (and `aoc packages send`): In asynchronous mode, the job id of the transfer was not returned: it is in field `transfer` of the result.
+* `node`:
+  * `emulator`: A symbolic link in the `docroot` leading out of it was followed by transfers.
+  * `emulator`: A `POST` with an empty body returned HTTP 500 instead of 400.
+* `orchestrator`:
+  * `workflows import_with_constraints` failed with an internal error of Orchestrator (plugins not enabled), or silently imported copies (partial resolution of conflicts). The OpenAPI description of `find_constraints` and `import_with_constraints` was wrong.
+  * `workflows import`, `import_with_constraints` and `publish` sent requests rejected by Orchestrator, `import` did not report workflows not imported, and `start` with `synchronous` failed to display the work order.
+  * `workstep status` displayed fields that are YAML dumps of Orchestrator objects (`prerequisites`, `work_outputs`...): they are removed, inputs and outputs are in `inputs` and `outputs`.
+* `shares`:
+  * The manual and the description of `admin user|group all share_permissions` (read-only) did not tell that permissions are granted with `admin share user_permissions|group_permissions`: AI assistants concluded that it was not possible. The argument of `show` is named `share_id`.
+
+### Breaking Changes
+
+* `ascli`:
+  * Secrets are hidden in results, whatever the output level or format (`--out.level=data`, `--format=json`...), unless `--out.secrets=yes`: before, `--out.level=data` (default with `--format=json`, `csv`...) showed them. This includes tokens displayed by `bearer_token`, `bearer_token_node`, `basic_token` and `config preset get <secret>`. Add `--out.secrets=yes` to scripts that use them (e.g. `$(ascli aoc bearer_token --out.secrets=yes)`).
+  * Ruby 3.2 or later is required (3.1 reached end of life in March 2025). Future minimum is 3.3. Policy: a Ruby version is supported until 18 months after its end of official support.
+  * The exit code on error indicates its category instead of always `1`: scripts shall test for a non-zero code. With `--format=nagios`, a failed command exits with `3` (UNKNOWN). Value `help` of a structured value exits with `0`.
+  * Local web servers on an address that is not loopback require authentication: `auth_token` for `mcp server`, `secret_token` or `allowed_ips` for `faspex5 postprocessing`, `username` and `password` for `node emulator`, `faspex5 gateway` and `aoc gateway`.
+  * Local web servers: a JSON body requires header `Content-Type: application/json`, else HTTP 415.
+  * `@secret:` asks in the browser by default on Windows and macOS (option `ui` is `graphical`): use `--ui=text` for the terminal.
+* `config`:
+  * `completion`: Completion scripts saved in a folder shall be saved again (they call new command `config completion candidates`).
+  * `vault`: `create` fails if the label exists (`vault`, `1password`), `delete` fails if the secret does not exist (`file`). `1password`: `url` is stored as website of the item.
+  * `ascp spec`, `sync spec`, `agents parameters`, value `help` of an option or argument: Columns are `name`, `type` and `description` (no `required`), and `description` is a list of lines (formats `json`, `yaml`), absent when empty.
+  * `ascp spec`: Columns per agent are displayed with argument `overview`. By default, the description lists the supported agents, if not all (e.g. `(A, N)`).
+  * `agents show`: Displays only the agent description: parameters are displayed by `config agents parameters`.
+* `mcp`:
+  * `server`: Option `security` is `high` by default and cannot be changed by the client, and `@stdin:` is refused: a preset reading a private key with `@file:` requires level `medium` or `low`.
+  * `server`: Keys of transport `http` are refused with `stdio` (the default), and `max_line_bytes` with `http`: they were ignored.
+* `faspex5`:
+  * `postprocessing`, `gateway` (and `aoc gateway`): Parameters are validated at startup: unknown keys are refused instead of ignored, and a missing `script_folder` is reported.
+  * `postprocessing`: Only webhook values whose key starts with `faspex_` are passed to the script as environment variables, and a structured value as JSON.
+* `orchestrator`:
+  * `workflows import` takes a file created by `workflows export`, and `workflows import_with_constraints` takes keys `filename`, `add_as_revision`, `subwf_constraints`, ... (see help).
+  * `monitors` is now `monitors snapshot`, with an optional type of monitors.
+  * `workorders output` displays values of variables as plain values instead of single-element arrays, and an empty value as `null`.
+
+### Server Versions
+
+| Plugin | Product | Version |
+|--------------|--------------------|------------------|
+| `aoc` | Aspera on Cloud | SaaS |
+| `console` | IBM Aspera Console | 3.4.11 |
+| `faspex5` | Faspex v5 | F5.0.17 |
+| `httpgw` | HTTP Gateway | 2.3.4 |
+| `node` | HSTS Node API | 4.4.8.2596 |
+| `orchestrator` | Orchestrator | 4.1.6.2036-00000 |
+| `shares` | IBM Aspera Shares | 1.11.5 |
+
+### Transfer Agent Versions
+
+| Agent | Product | Version |
+|-----------|--------------------------------|---------|
+| `connect` | IBM Aspera Connect Client | 4.2.14 |
+| `desktop` | IBM Aspera Desktop Client | 4.4.3 |
+| `direct` | IBM Aspera Transfer SDK (ascp) | 1.1.9 |
+| `httpgw` | IBM Aspera HTTP Gateway Agent | 1.3.0 |
+| `node` | IBM Aspera Node API Agent | 4.4.3 |
+| `transferd` | IBM Aspera transferd daemon | 1.1.9 |
+
 ## 4.27.5
 
 Released: 2026-10-06
@@ -15,7 +171,7 @@ Released: 2026-10-06
 ### Server Versions
 
 | Plugin | Product | Version |
-|--------------|--------------------|------------------|
+| -------------- | -------------------- | ------------------ |
 | `aoc` | Aspera on Cloud | SaaS |
 | `console` | IBM Aspera Console | 3.4.4 |
 | `faspex5` | Faspex v5 | F5.0.17 |
@@ -27,7 +183,7 @@ Released: 2026-10-06
 ### Transfer Agent Versions
 
 | Agent | Product | Version |
-|-----------|--------------------------------|---------|
+| ----------- | -------------------------------- | --------- |
 | `connect` | IBM Aspera Connect Client | 4.2.14 |
 | `desktop` | IBM Aspera Desktop Client | 4.4.3 |
 | `direct` | IBM Aspera Transfer SDK (ascp) | 1.1.9 |
@@ -98,7 +254,7 @@ Released: 2026-10-05
 ### Server Versions
 
 | Plugin | Product | Version |
-|--------------|--------------------|------------------|
+| -------------- | -------------------- | ------------------ |
 | `aoc` | Aspera on Cloud | SaaS |
 | `console` | IBM Aspera Console | 3.4.4 |
 | `faspex5` | Faspex v5 | F5.0.17 |
@@ -110,7 +266,7 @@ Released: 2026-10-05
 ### Transfer Agent Versions
 
 | Agent | Product | Version |
-|-----------|--------------------------------|---------|
+| ----------- | -------------------------------- | --------- |
 | `connect` | IBM Aspera Connect Client | 4.2.14 |
 | `desktop` | IBM Aspera Desktop Client | 4.4.3 |
 | `direct` | IBM Aspera Transfer SDK (ascp) | 1.1.9 |

data/CONTRIBUTING.md

@@ -127,14 +127,16 @@ Add one bullet under `### New Features` (or `### Issues Fixed` / `### Breaking C
 
 Style rules:
 
-- Plugin name in backticks: `` `config` ``, `` `aoc` ``, or `**global**` for cross-cutting changes.
+- Entries are grouped by plugin: one first-level bullet per plugin, `` `ascli` `` (cross-cutting changes) first, then `` `config` ``, `` `mcp` ``, then the other plugins in alphabetical order.
+- The entry is a second-level bullet under its plugin, prefixed with the command path inside the plugin, if any.
 - Command path and argument names in backticks.
 - One sentence per bullet; end without a period.
 
 Example:
 
 ```markdown
-* `config`: New commands `agents list`, `agents show <name>` and `agents parameters <name>` to discover available transfer agents, their short identifier and their configurable parameters
+* `config`:
+  * `agents`: New commands `list`, `show <name>` and `parameters <name>` to discover available transfer agents, their short identifier and their configurable parameters
 ```
 
 #### 5 — Static analysis

data/README.md

@@ -28,7 +28,7 @@ Choose what best suits you:
 
 ## Install
 
-Install **Ruby** ≥ 3.1
+Install **Ruby** ≥ 3.2
 
 ```bash
 gem install aspera-cli

data/bin/asession

@@ -26,7 +26,7 @@ class SimpleTransferManager
   # Default SDK location
   SDK_DEFAULT_DIR = File.join(Dir.home, '.aspera', 'sdk')
   # Place transfer spec in that
-  SAMPLE_DEMO = '"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"demoaspera"'
+  SAMPLE_DEMO = '"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"<PASSWORD>"'
   SAMPLE_DEMO2 = '"direction":"receive","destination_root":"./test.dir"'
   STDIN_INPUT = '@json:@stdin:'
   class << self