aspera-cli 4.28.0 → 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.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/BUGS.md +5 -10
- data/CHANGELOG.md +143 -2
- data/CODE_OF_CONDUCT.md +18 -0
- data/CONTRIBUTING.md +135 -56
- data/GOVERNANCE.md +30 -0
- data/LICENSE +201 -0
- data/README.md +103 -26
- data/SECURITY.md +70 -0
- data/bin/ascli +8 -5
- data/bin/asession +9 -6
- data/docs/README.md +1633 -609
- data/docs/test-mcp-with-ai.md +8 -8
- data/lib/aspera/agent/base.rb +23 -2
- data/lib/aspera/agent/connect.rb +16 -12
- data/lib/aspera/agent/desktop.rb +10 -7
- data/lib/aspera/agent/direct.rb +20 -19
- data/lib/aspera/agent/factory.rb +6 -3
- data/lib/aspera/agent/httpgw.rb +7 -5
- data/lib/aspera/agent/node.rb +15 -7
- data/lib/aspera/agent/transferd.rb +167 -43
- data/lib/aspera/api/alee.rb +4 -1
- data/lib/aspera/api/aoc.rb +14 -11
- data/lib/aspera/api/ats.rb +4 -2
- data/lib/aspera/api/cos_node.rb +7 -4
- data/lib/aspera/api/faspex.rb +16 -9
- data/lib/aspera/api/httpgw.rb +9 -6
- data/lib/aspera/api/node.rb +20 -20
- data/lib/aspera/ascmd.rb +8 -5
- data/lib/aspera/ascp/installation.rb +71 -65
- data/lib/aspera/ascp/log.schema.yaml +1084 -0
- data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
- data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
- data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
- data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
- data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
- data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
- data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
- data/lib/aspera/ascp/log_analyzer.rb +354 -0
- data/lib/aspera/ascp/management.rb +16 -8
- data/lib/aspera/ascp/session_errors.rb +217 -0
- data/lib/aspera/assert.rb +4 -0
- data/lib/aspera/cli/ascp_actions.rb +12 -19
- data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
- data/lib/aspera/cli/async_transfer_store.rb +7 -4
- data/lib/aspera/cli/bootstrapper.rb +37 -33
- data/lib/aspera/cli/command_line.rb +24 -6
- data/lib/aspera/cli/command_registry.rb +6 -1
- data/lib/aspera/cli/command_spec.rb +34 -7
- data/lib/aspera/cli/completion/ascli.bash +19 -5
- data/lib/aspera/cli/completion/ascli.fish +13 -2
- data/lib/aspera/cli/completion/ascli.ps1 +31 -9
- data/lib/aspera/cli/completion/ascli.zsh +22 -6
- data/lib/aspera/cli/completion_actions.rb +303 -69
- data/lib/aspera/cli/context.rb +9 -4
- data/lib/aspera/cli/deprecation.rb +5 -2
- data/lib/aspera/cli/error.rb +3 -0
- data/lib/aspera/cli/extended_value.rb +61 -27
- data/lib/aspera/cli/formatter.rb +29 -22
- data/lib/aspera/cli/gem_checker.rb +9 -6
- data/lib/aspera/cli/hints.rb +22 -10
- data/lib/aspera/cli/http.rb +12 -9
- data/lib/aspera/cli/info.rb +12 -7
- data/lib/aspera/cli/mailer.rb +6 -3
- data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
- data/lib/aspera/cli/mcp/secrets.rb +8 -5
- data/lib/aspera/cli/mcp/tool.rb +15 -14
- data/lib/aspera/cli/option_declarator.rb +10 -4
- data/lib/aspera/cli/option_registry.rb +6 -3
- data/lib/aspera/cli/option_types.rb +17 -2
- data/lib/aspera/cli/option_value.rb +65 -12
- data/lib/aspera/cli/options.schema.yaml +487 -63
- data/lib/aspera/cli/parser.rb +56 -32
- data/lib/aspera/cli/plugins/alee.rb +7 -4
- data/lib/aspera/cli/plugins/aoc.rb +244 -35
- data/lib/aspera/cli/plugins/ats.rb +9 -8
- data/lib/aspera/cli/plugins/base.rb +17 -12
- data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
- data/lib/aspera/cli/plugins/config.rb +198 -103
- data/lib/aspera/cli/plugins/console.rb +6 -3
- data/lib/aspera/cli/plugins/cos.rb +8 -4
- data/lib/aspera/cli/plugins/factory.rb +21 -7
- data/lib/aspera/cli/plugins/faspex5.rb +28 -25
- data/lib/aspera/cli/plugins/faspio.rb +7 -5
- data/lib/aspera/cli/plugins/httpgw.rb +7 -4
- data/lib/aspera/cli/plugins/mcp.rb +28 -22
- data/lib/aspera/cli/plugins/node.rb +31 -30
- data/lib/aspera/cli/plugins/oauth.rb +5 -1
- data/lib/aspera/cli/plugins/orchestrator.rb +272 -72
- data/lib/aspera/cli/plugins/preview.rb +69 -44
- data/lib/aspera/cli/plugins/server.rb +63 -11
- data/lib/aspera/cli/plugins/shares.rb +86 -16
- data/lib/aspera/cli/plugins/transferd.rb +223 -0
- data/lib/aspera/cli/preset_actions.rb +144 -30
- data/lib/aspera/cli/preset_manager.rb +52 -18
- data/lib/aspera/cli/prompt.rb +4 -1
- data/lib/aspera/cli/result.rb +12 -8
- data/lib/aspera/cli/runner.rb +69 -46
- data/lib/aspera/cli/secret_finder.rb +4 -1
- data/lib/aspera/cli/security.rb +79 -9
- data/lib/aspera/cli/special_values.rb +4 -1
- data/lib/aspera/cli/sync_actions.rb +13 -10
- data/lib/aspera/cli/table_fitter.rb +3 -0
- data/lib/aspera/cli/terminal_formatter.rb +9 -6
- data/lib/aspera/cli/transfer_actions.rb +11 -8
- data/lib/aspera/cli/transfer_agent.rb +29 -20
- data/lib/aspera/cli/transfer_progress.rb +13 -45
- data/lib/aspera/cli/vault_actions.rb +45 -0
- data/lib/aspera/cli/vault_manager.rb +188 -42
- data/lib/aspera/cli/version.rb +4 -1
- data/lib/aspera/cli/web_secret.rb +12 -10
- data/lib/aspera/cli/wizard.rb +42 -39
- data/lib/aspera/command_line_builder.rb +9 -5
- data/lib/aspera/command_line_converter.rb +4 -1
- data/lib/aspera/coverage.rb +103 -33
- data/lib/aspera/data_repository.rb +4 -1
- data/lib/aspera/dot_container.rb +4 -1
- data/lib/aspera/duration.rb +5 -2
- data/lib/aspera/environment.rb +21 -12
- data/lib/aspera/exec_spec.rb +3 -0
- data/lib/aspera/faspex_gw.rb +13 -9
- data/lib/aspera/faspex_postproc.rb +15 -12
- data/lib/aspera/formatter_interface.rb +4 -1
- data/lib/aspera/graphql.rb +5 -1
- data/lib/aspera/hash_ext.rb +3 -0
- data/lib/aspera/id_generator.rb +4 -2
- data/lib/aspera/json_rpc/client.rb +6 -5
- data/lib/aspera/json_rpc/version.rb +3 -0
- data/lib/aspera/line_logger.rb +4 -1
- data/lib/aspera/link_header.rb +4 -1
- data/lib/aspera/log.rb +18 -5
- data/lib/aspera/markdown.rb +5 -2
- data/lib/aspera/mime.rb +3 -0
- data/lib/aspera/nagios.rb +6 -4
- data/lib/aspera/node_emulator.rb +15 -13
- data/lib/aspera/oauth/client/base.rb +91 -70
- data/lib/aspera/oauth/client/boot.rb +7 -4
- data/lib/aspera/oauth/client/factory.rb +6 -3
- data/lib/aspera/oauth/client/generic.rb +5 -1
- data/lib/aspera/oauth/client/json_credentials.rb +4 -1
- data/lib/aspera/oauth/client/jwt.rb +6 -3
- data/lib/aspera/oauth/client/shares_web.rb +85 -0
- data/lib/aspera/oauth/client/url_json.rb +4 -1
- data/lib/aspera/oauth/client/web.rb +39 -12
- data/lib/aspera/oauth/server/pkce.rb +6 -5
- data/lib/aspera/orchestrator_workflow_checker.rb +119 -1
- data/lib/aspera/persistency_action_once.rb +5 -3
- data/lib/aspera/persistency_folder.rb +6 -3
- data/lib/aspera/preview/file_types.rb +6 -3
- data/lib/aspera/preview/generator.rb +9 -5
- data/lib/aspera/preview/options.schema.yaml +3 -3
- data/lib/aspera/preview/terminal.rb +8 -4
- data/lib/aspera/preview/utils.rb +6 -4
- data/lib/aspera/products/connect.rb +5 -2
- data/lib/aspera/products/desktop.rb +4 -1
- data/lib/aspera/products/other.rb +4 -2
- data/lib/aspera/products/transferd.rb +6 -2
- data/lib/aspera/products/transferd_service.rb +610 -0
- data/lib/aspera/proxy_auto_config.js +2 -2
- data/lib/aspera/proxy_auto_config.rb +5 -2
- data/lib/aspera/rainbow.rb +3 -0
- data/lib/aspera/rest/aspera_errors.rb +4 -1
- data/lib/aspera/rest/call_error.rb +3 -0
- data/lib/aspera/rest/client.rb +22 -29
- data/lib/aspera/rest/error_analyzer.rb +5 -2
- data/lib/aspera/rest/list.rb +8 -4
- data/lib/aspera/rest/parameters.rb +3 -0
- data/lib/aspera/rest/util.rb +8 -5
- data/lib/aspera/rest.rb +9 -6
- data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
- data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
- data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
- data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
- data/lib/aspera/schema/async_tables.yaml +11 -10
- data/lib/aspera/schema/documentation.rb +8 -2
- data/lib/aspera/schema/reader.rb +7 -0
- data/lib/aspera/schema/registry.rb +43 -28
- data/lib/aspera/schema/transferd-config.schema.json +333 -0
- data/lib/aspera/schema/validator.rb +4 -1
- data/lib/aspera/sealed_hash.rb +166 -0
- data/lib/aspera/secret/hider.rb +201 -0
- data/lib/aspera/secret/reference.rb +150 -0
- data/lib/aspera/secret/resolver.rb +212 -0
- data/lib/aspera/secret/store/base.rb +153 -0
- data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
- data/lib/aspera/secret/store/factory.rb +103 -0
- data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
- data/lib/aspera/secret/store/keeper.rb +141 -0
- data/lib/aspera/secret/store/macos_security.rb +284 -0
- data/lib/aspera/secret/store/one_password_api.rb +99 -0
- data/lib/aspera/secret/store/one_password_base.rb +42 -0
- data/lib/aspera/secret/store/one_password_cli.rb +110 -0
- data/lib/aspera/secret/store/secret_service.rb +125 -0
- data/lib/aspera/secret/strength.rb +119 -0
- data/lib/aspera/servlet_helpers.rb +5 -2
- data/lib/aspera/ssh.rb +10 -7
- data/lib/aspera/ssl.rb +5 -2
- data/lib/aspera/string_ext.rb +3 -0
- data/lib/aspera/sync/args.schema.yaml +3 -0
- data/lib/aspera/sync/conf.schema.yaml +9 -4
- data/lib/aspera/sync/database.rb +3 -0
- data/lib/aspera/sync/operations.rb +16 -14
- data/lib/aspera/temp_file_manager.rb +8 -4
- data/lib/aspera/timer_limiter.rb +3 -0
- data/lib/aspera/transfer/error.rb +4 -1
- data/lib/aspera/transfer/faux_file.rb +4 -1
- data/lib/aspera/transfer/parameters.rb +17 -14
- data/lib/aspera/transfer/result.rb +3 -0
- data/lib/aspera/transfer/resumer.rb +6 -4
- data/lib/aspera/transfer/spec.rb +9 -22
- data/lib/aspera/transfer/units.rb +75 -0
- data/lib/aspera/uri_reader.rb +57 -7
- data/lib/aspera/web_auth/index.html.erb +6 -2
- data/lib/aspera/web_auth/paste.rb +109 -0
- data/lib/aspera/web_auth/receiver.rb +50 -0
- data/lib/aspera/web_auth/relay.rb +76 -0
- data/lib/aspera/web_auth/reply.html.erb +150 -0
- data/lib/aspera/web_auth/server.rb +47 -10
- data/lib/aspera/web_page.rb +7 -2
- data/lib/aspera/web_server_simple.rb +6 -3
- data/lib/aspera/yaml.rb +5 -1
- data/llms.txt +81 -0
- data/skills/ascli/SKILL.md +88 -0
- data.tar.gz.sig +0 -0
- metadata +72 -19
- metadata.gz.sig +0 -0
- data/lib/aspera/keychain/base.rb +0 -30
- data/lib/aspera/keychain/encrypted_hash.rb +0 -192
- data/lib/aspera/keychain/factory.rb +0 -58
- data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
- data/lib/aspera/keychain/macos_security.rb +0 -277
- data/lib/aspera/keychain/one_password_api.rb +0 -91
- data/lib/aspera/keychain/one_password_base.rb +0 -39
- data/lib/aspera/keychain/one_password_cli.rb +0 -100
- data/lib/aspera/secret_hider.rb +0 -196
- data/lib/aspera/secret_strength.rb +0 -114
data/llms.txt
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# ascli: command line interface for IBM Aspera
|
|
2
|
+
|
|
3
|
+
> `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
|
|
4
|
+
> An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
|
|
5
|
+
> transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
|
|
6
|
+
|
|
7
|
+
If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
|
|
8
|
+
|
|
9
|
+
## Products and plugins
|
|
10
|
+
|
|
11
|
+
The first word after `ascli` is a plugin: one per product.
|
|
12
|
+
|
|
13
|
+
- `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
|
|
14
|
+
- `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
|
|
15
|
+
- `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
|
|
16
|
+
- `node`: Node API of a transfer server (files, access keys, transfers, sync)
|
|
17
|
+
- `shares`: IBM Aspera Shares
|
|
18
|
+
- `console`: IBM Aspera Console
|
|
19
|
+
- `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
|
|
20
|
+
- `ats`: IBM Aspera Transfer Service
|
|
21
|
+
- `cos`: IBM Cloud Object Storage
|
|
22
|
+
- `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
|
|
23
|
+
- `preview`: generation of previews of files
|
|
24
|
+
- `transferd`: Transfer Daemon of the Transfer SDK (install, service)
|
|
25
|
+
- `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
|
|
26
|
+
- `mcp`: Model Context Protocol server
|
|
27
|
+
|
|
28
|
+
## Two ways to use it
|
|
29
|
+
|
|
30
|
+
- Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
|
|
31
|
+
Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
|
|
32
|
+
- MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
|
|
33
|
+
The description of the tool repeats the rules below.
|
|
34
|
+
|
|
35
|
+
## Discover, do not guess
|
|
36
|
+
|
|
37
|
+
Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
|
|
38
|
+
|
|
39
|
+
1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
|
|
40
|
+
2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
|
|
41
|
+
3. Filter parameters of a list command: `--query=help`.
|
|
42
|
+
4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
|
|
43
|
+
5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
|
|
44
|
+
|
|
45
|
+
## Workflow development
|
|
46
|
+
|
|
47
|
+
Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
|
|
48
|
+
|
|
49
|
+
- IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
|
|
50
|
+
Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
|
|
51
|
+
Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
|
|
52
|
+
Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
|
|
53
|
+
- IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
|
|
54
|
+
|
|
55
|
+
## Rules
|
|
56
|
+
|
|
57
|
+
- Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
|
|
58
|
+
- Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
|
|
59
|
+
- Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
|
|
60
|
+
- Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
|
|
61
|
+
- Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
|
|
62
|
+
- Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
|
|
63
|
+
- Show the user the command line that was executed.
|
|
64
|
+
|
|
65
|
+
## Examples
|
|
66
|
+
|
|
67
|
+
```shell
|
|
68
|
+
ascli config commands faspex5
|
|
69
|
+
ascli faspex5 packages send help
|
|
70
|
+
ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
|
|
71
|
+
ascli aoc files browse / --format=json
|
|
72
|
+
ascli server upload /path/to/file --to-folder=/Upload
|
|
73
|
+
ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Documentation
|
|
77
|
+
|
|
78
|
+
- [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
|
|
79
|
+
- [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
|
|
80
|
+
- [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
|
|
81
|
+
- [Source](https://github.com/IBM/aspera-cli)
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ascli
|
|
3
|
+
description: 'Operate IBM Aspera products with the ascli command line: Aspera on Cloud, Faspex 5, High-Speed Transfer Server, Node API, Shares, Console, Orchestrator, Cloud Object Storage. Use when the user wants to transfer files with FASP (ascp), send or receive packages, browse or manage remote files, administer users, workspaces, nodes or access keys, analyze ascp logs, or develop Orchestrator or Aspera on Cloud Automation workflows.'
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
compatibility: Requires the ascli command (Ruby gem aspera-cli) in the shell, or the ascli MCP server.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# ascli: command line interface for IBM Aspera
|
|
9
|
+
|
|
10
|
+
> `ascli` (Ruby gem `aspera-cli`) is the command line interface for IBM Aspera products.
|
|
11
|
+
> An AI assistant that can run a shell command, or that is connected to the `ascli` MCP server, can use it to operate these products for the user:
|
|
12
|
+
> transfer files with the FASP protocol (`ascp`), send and receive packages, browse and manage remote files, and administer the applications (users, groups, workspaces, nodes, access keys, workflows).
|
|
13
|
+
|
|
14
|
+
If the user asks for something that involves an IBM Aspera product, and `ascli` is available, use it: do not write calls to the REST APIs by hand.
|
|
15
|
+
|
|
16
|
+
## Products and plugins
|
|
17
|
+
|
|
18
|
+
The first word after `ascli` is a plugin: one per product.
|
|
19
|
+
|
|
20
|
+
- `aoc`: IBM Aspera on Cloud (files, packages, administration, Automation workflows)
|
|
21
|
+
- `faspex5`: IBM Aspera Faspex 5 (packages, shared inboxes, administration)
|
|
22
|
+
- `server`: IBM Aspera High-Speed Transfer Server, over SSH (browse, upload, download, `ascp` logs)
|
|
23
|
+
- `node`: Node API of a transfer server (files, access keys, transfers, sync)
|
|
24
|
+
- `shares`: IBM Aspera Shares
|
|
25
|
+
- `console`: IBM Aspera Console
|
|
26
|
+
- `orchestrator`: IBM Aspera Orchestrator (workflows, work orders, plugins, development guide)
|
|
27
|
+
- `ats`: IBM Aspera Transfer Service
|
|
28
|
+
- `cos`: IBM Cloud Object Storage
|
|
29
|
+
- `httpgw`, `faspio`, `alee`: HTTP Gateway, faspio Gateway, license entitlement
|
|
30
|
+
- `preview`: generation of previews of files
|
|
31
|
+
- `transferd`: Transfer Daemon of the Transfer SDK (install, service)
|
|
32
|
+
- `config`: local configuration: presets, secrets (`vault`), `ascp`, documentation
|
|
33
|
+
- `mcp`: Model Context Protocol server
|
|
34
|
+
|
|
35
|
+
## Two ways to use it
|
|
36
|
+
|
|
37
|
+
- Shell: run `ascli <plugin> <command...> [arguments] [--option=value]`.
|
|
38
|
+
Add `--interactive=no` so that a missing value is an error instead of a prompt, and `--format=json` to get results as JSON.
|
|
39
|
+
- MCP: the user starts `ascli mcp server` (transport `stdio` or `http`). It provides one tool, `execute_ascli_command`, whose argument `args` is the command line as an array of strings.
|
|
40
|
+
The description of the tool repeats the rules below.
|
|
41
|
+
|
|
42
|
+
## Discover, do not guess
|
|
43
|
+
|
|
44
|
+
Command names, argument fields and options differ between plugins and versions: read them from the tool itself.
|
|
45
|
+
|
|
46
|
+
1. Commands of a plugin, with their syntax: `ascli config commands <plugin>`. Sub-commands of a path: `ascli config commands <plugin> <command...>`.
|
|
47
|
+
2. Fields of a structured argument (shown `<name:Hash>` in the syntax): put the word `help` in place of the argument, e.g. `ascli aoc admin user create help`.
|
|
48
|
+
3. Filter parameters of a list command: `--query=help`.
|
|
49
|
+
4. Options of a plugin, with allowed values: `ascli config options <plugin>`.
|
|
50
|
+
5. Manual: `ascli config documentation toc` lists the sections (level, title, anchor), `ascli config documentation local <anchor>` displays one section.
|
|
51
|
+
|
|
52
|
+
## Workflow development
|
|
53
|
+
|
|
54
|
+
Before writing or modifying a workflow, read the development guide with `ascli`: it is large, so list its sections with `toc`, then read the ones needed with `section <anchor>`. No connection to the product is needed.
|
|
55
|
+
|
|
56
|
+
- IBM Aspera Orchestrator: `ascli orchestrator workflows development guide toc`, then `ascli orchestrator workflows development guide section <anchor>` (start with `quick-start` and `authoring-checklist`).
|
|
57
|
+
Other documents: `templates` (Action Template Reference) and `manual` (Plugin Manual), with the same `toc` and `section`.
|
|
58
|
+
Specification of an action plugin (template attributes, inputs, outputs): `ascli orchestrator plugins spec toc`, then `ascli orchestrator plugins spec show <plugin>`.
|
|
59
|
+
Check a workflow file before importing it, and fix all errors: `ascli orchestrator workflows check_import <file>`.
|
|
60
|
+
- IBM Aspera on Cloud Automation: `ascli aoc automation guide toc`, then `ascli aoc automation guide section <anchor>`.
|
|
61
|
+
|
|
62
|
+
## Rules
|
|
63
|
+
|
|
64
|
+
- Structured values: `@json:{...}` (preferred), or `@: key=value key2.sub=value`. See section `extended-value-syntax` of the manual.
|
|
65
|
+
- Credentials: saved in presets. List them with `ascli config preset overview`, select one with `--preset=<name>`; a plugin may have a default preset.
|
|
66
|
+
- Secrets: never ask the user to type a secret in the conversation. Use a preset, the vault (`@vault:<label>.<field>`), or `@secret:<name>`, which asks the user outside of the conversation. Values of secrets are hidden in results.
|
|
67
|
+
- Results: filter and reshape with `--out.query` (JMESPath), `--out.select` and `--out.fields`, instead of post-processing a large output.
|
|
68
|
+
- Transfers: source paths are the last arguments, the destination is `--to-folder=<path>`, other transfer parameters are in `--ts=@json:{...}` (schema: `ascli config ascp spec`).
|
|
69
|
+
- Exit code: `0` success, other values give the category of error (usage, authentication, not found, transfer, network): see `ascli -h`.
|
|
70
|
+
- Show the user the command line that was executed.
|
|
71
|
+
|
|
72
|
+
## Examples
|
|
73
|
+
|
|
74
|
+
```shell
|
|
75
|
+
ascli config commands faspex5
|
|
76
|
+
ascli faspex5 packages send help
|
|
77
|
+
ascli faspex5 packages send @json:'{"title":"Report","recipients":["user@example.com"]}' /path/to/file.pdf
|
|
78
|
+
ascli aoc files browse / --format=json
|
|
79
|
+
ascli server upload /path/to/file --to-folder=/Upload
|
|
80
|
+
ascli config ascp logs diagnostics /path/to/aspera-scp-transfer.log
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Documentation
|
|
84
|
+
|
|
85
|
+
- [Manual](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md): complete reference, in Markdown (large: read sections with `config documentation`)
|
|
86
|
+
- [Release notes](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/CHANGELOG.md)
|
|
87
|
+
- [Testing the MCP server with an AI agent](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/test-mcp-with-ai.md)
|
|
88
|
+
- [Source](https://github.com/IBM/aspera-cli)
|
data.tar.gz.sig
CHANGED
|
Binary file
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: aspera-cli
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 4.
|
|
4
|
+
version: 4.29.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Laurent Martin
|
|
@@ -142,14 +142,14 @@ dependencies:
|
|
|
142
142
|
requirements:
|
|
143
143
|
- - "~>"
|
|
144
144
|
- !ruby/object:Gem::Version
|
|
145
|
-
version: '
|
|
145
|
+
version: '2.1'
|
|
146
146
|
type: :runtime
|
|
147
147
|
prerelease: false
|
|
148
148
|
version_requirements: !ruby/object:Gem::Requirement
|
|
149
149
|
requirements:
|
|
150
150
|
- - "~>"
|
|
151
151
|
- !ruby/object:Gem::Version
|
|
152
|
-
version: '
|
|
152
|
+
version: '2.1'
|
|
153
153
|
- !ruby/object:Gem::Dependency
|
|
154
154
|
name: mime-types
|
|
155
155
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -184,14 +184,14 @@ dependencies:
|
|
|
184
184
|
requirements:
|
|
185
185
|
- - "~>"
|
|
186
186
|
- !ruby/object:Gem::Version
|
|
187
|
-
version: '
|
|
187
|
+
version: '8.1'
|
|
188
188
|
type: :runtime
|
|
189
189
|
prerelease: false
|
|
190
190
|
version_requirements: !ruby/object:Gem::Requirement
|
|
191
191
|
requirements:
|
|
192
192
|
- - "~>"
|
|
193
193
|
- !ruby/object:Gem::Version
|
|
194
|
-
version: '
|
|
194
|
+
version: '8.1'
|
|
195
195
|
- !ruby/object:Gem::Dependency
|
|
196
196
|
name: rainbow
|
|
197
197
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -206,6 +206,20 @@ dependencies:
|
|
|
206
206
|
- - "~>"
|
|
207
207
|
- !ruby/object:Gem::Version
|
|
208
208
|
version: '3.0'
|
|
209
|
+
- !ruby/object:Gem::Dependency
|
|
210
|
+
name: regexp_parser
|
|
211
|
+
requirement: !ruby/object:Gem::Requirement
|
|
212
|
+
requirements:
|
|
213
|
+
- - "!="
|
|
214
|
+
- !ruby/object:Gem::Version
|
|
215
|
+
version: 2.13.2
|
|
216
|
+
type: :runtime
|
|
217
|
+
prerelease: false
|
|
218
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
219
|
+
requirements:
|
|
220
|
+
- - "!="
|
|
221
|
+
- !ruby/object:Gem::Version
|
|
222
|
+
version: 2.13.2
|
|
209
223
|
- !ruby/object:Gem::Dependency
|
|
210
224
|
name: ruby-progressbar
|
|
211
225
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -318,7 +332,13 @@ dependencies:
|
|
|
318
332
|
- - "~>"
|
|
319
333
|
- !ruby/object:Gem::Version
|
|
320
334
|
version: '1.0'
|
|
321
|
-
description:
|
|
335
|
+
description: 'Open-source toolkit to automate, integrate and operate IBM Aspera products:
|
|
336
|
+
high-speed transfers with FASP (ascp), send and receive packages, manage files and
|
|
337
|
+
administer Aspera on Cloud, Faspex, Shares, Node, Console, Orchestrator and High
|
|
338
|
+
Speed Transfer Server. Structured output for scripts and pipelines, presets and
|
|
339
|
+
secret vaults for multiple environments, analysis of ascp logs. Usable by AI assistants
|
|
340
|
+
and AI agents: in a shell (see llms.txt and the agent skill), or through its MCP
|
|
341
|
+
(Model Context Protocol) server.'
|
|
322
342
|
email:
|
|
323
343
|
- laurent.martin.aspera@fr.ibm.com
|
|
324
344
|
executables:
|
|
@@ -329,8 +349,12 @@ extra_rdoc_files: []
|
|
|
329
349
|
files:
|
|
330
350
|
- BUGS.md
|
|
331
351
|
- CHANGELOG.md
|
|
352
|
+
- CODE_OF_CONDUCT.md
|
|
332
353
|
- CONTRIBUTING.md
|
|
354
|
+
- GOVERNANCE.md
|
|
355
|
+
- LICENSE
|
|
333
356
|
- README.md
|
|
357
|
+
- SECURITY.md
|
|
334
358
|
- TODO.md
|
|
335
359
|
- bin/ascli
|
|
336
360
|
- bin/asession
|
|
@@ -355,9 +379,20 @@ files:
|
|
|
355
379
|
- lib/aspera/api/queries/bss_subscription_usage.graphql
|
|
356
380
|
- lib/aspera/ascmd.rb
|
|
357
381
|
- lib/aspera/ascp/installation.rb
|
|
382
|
+
- lib/aspera/ascp/log.schema.yaml
|
|
383
|
+
- lib/aspera/ascp/log_analyzer.rb
|
|
384
|
+
- lib/aspera/ascp/log_analyzer/advice.rb
|
|
385
|
+
- lib/aspera/ascp/log_analyzer/diagnostics.rb
|
|
386
|
+
- lib/aspera/ascp/log_analyzer/lines.rb
|
|
387
|
+
- lib/aspera/ascp/log_analyzer/log_file.rb
|
|
388
|
+
- lib/aspera/ascp/log_analyzer/records.rb
|
|
389
|
+
- lib/aspera/ascp/log_analyzer/rules.rb
|
|
390
|
+
- lib/aspera/ascp/log_analyzer/session.rb
|
|
358
391
|
- lib/aspera/ascp/management.rb
|
|
392
|
+
- lib/aspera/ascp/session_errors.rb
|
|
359
393
|
- lib/aspera/assert.rb
|
|
360
394
|
- lib/aspera/cli/ascp_actions.rb
|
|
395
|
+
- lib/aspera/cli/ascp_logs_actions.rb
|
|
361
396
|
- lib/aspera/cli/async_transfer_store.rb
|
|
362
397
|
- lib/aspera/cli/bootstrapper.rb
|
|
363
398
|
- lib/aspera/cli/command_line.rb
|
|
@@ -406,6 +441,7 @@ files:
|
|
|
406
441
|
- lib/aspera/cli/plugins/preview.rb
|
|
407
442
|
- lib/aspera/cli/plugins/server.rb
|
|
408
443
|
- lib/aspera/cli/plugins/shares.rb
|
|
444
|
+
- lib/aspera/cli/plugins/transferd.rb
|
|
409
445
|
- lib/aspera/cli/preset_actions.rb
|
|
410
446
|
- lib/aspera/cli/preset_manager.rb
|
|
411
447
|
- lib/aspera/cli/prompt.rb
|
|
@@ -420,6 +456,7 @@ files:
|
|
|
420
456
|
- lib/aspera/cli/transfer_actions.rb
|
|
421
457
|
- lib/aspera/cli/transfer_agent.rb
|
|
422
458
|
- lib/aspera/cli/transfer_progress.rb
|
|
459
|
+
- lib/aspera/cli/vault_actions.rb
|
|
423
460
|
- lib/aspera/cli/vault_manager.rb
|
|
424
461
|
- lib/aspera/cli/version.rb
|
|
425
462
|
- lib/aspera/cli/web_secret.html.erb
|
|
@@ -447,14 +484,6 @@ files:
|
|
|
447
484
|
- lib/aspera/id_generator.rb
|
|
448
485
|
- lib/aspera/json_rpc/client.rb
|
|
449
486
|
- lib/aspera/json_rpc/version.rb
|
|
450
|
-
- lib/aspera/keychain/base.rb
|
|
451
|
-
- lib/aspera/keychain/encrypted_hash.rb
|
|
452
|
-
- lib/aspera/keychain/factory.rb
|
|
453
|
-
- lib/aspera/keychain/hashicorp_vault.rb
|
|
454
|
-
- lib/aspera/keychain/macos_security.rb
|
|
455
|
-
- lib/aspera/keychain/one_password_api.rb
|
|
456
|
-
- lib/aspera/keychain/one_password_base.rb
|
|
457
|
-
- lib/aspera/keychain/one_password_cli.rb
|
|
458
487
|
- lib/aspera/line_logger.rb
|
|
459
488
|
- lib/aspera/link_header.rb
|
|
460
489
|
- lib/aspera/log.rb
|
|
@@ -468,6 +497,7 @@ files:
|
|
|
468
497
|
- lib/aspera/oauth/client/generic.rb
|
|
469
498
|
- lib/aspera/oauth/client/json_credentials.rb
|
|
470
499
|
- lib/aspera/oauth/client/jwt.rb
|
|
500
|
+
- lib/aspera/oauth/client/shares_web.rb
|
|
471
501
|
- lib/aspera/oauth/client/url_json.rb
|
|
472
502
|
- lib/aspera/oauth/client/web.rb
|
|
473
503
|
- lib/aspera/oauth/server/authorize.html.erb
|
|
@@ -486,6 +516,7 @@ files:
|
|
|
486
516
|
- lib/aspera/products/desktop.rb
|
|
487
517
|
- lib/aspera/products/other.rb
|
|
488
518
|
- lib/aspera/products/transferd.rb
|
|
519
|
+
- lib/aspera/products/transferd_service.rb
|
|
489
520
|
- lib/aspera/proxy_auto_config.js
|
|
490
521
|
- lib/aspera/proxy_auto_config.rb
|
|
491
522
|
- lib/aspera/rainbow.rb
|
|
@@ -509,9 +540,23 @@ files:
|
|
|
509
540
|
- lib/aspera/schema/documentation.rb
|
|
510
541
|
- lib/aspera/schema/reader.rb
|
|
511
542
|
- lib/aspera/schema/registry.rb
|
|
543
|
+
- lib/aspera/schema/transferd-config.schema.json
|
|
512
544
|
- lib/aspera/schema/validator.rb
|
|
513
|
-
- lib/aspera/
|
|
514
|
-
- lib/aspera/
|
|
545
|
+
- lib/aspera/sealed_hash.rb
|
|
546
|
+
- lib/aspera/secret/hider.rb
|
|
547
|
+
- lib/aspera/secret/reference.rb
|
|
548
|
+
- lib/aspera/secret/resolver.rb
|
|
549
|
+
- lib/aspera/secret/store/base.rb
|
|
550
|
+
- lib/aspera/secret/store/encrypted_hash.rb
|
|
551
|
+
- lib/aspera/secret/store/factory.rb
|
|
552
|
+
- lib/aspera/secret/store/hashicorp_vault.rb
|
|
553
|
+
- lib/aspera/secret/store/keeper.rb
|
|
554
|
+
- lib/aspera/secret/store/macos_security.rb
|
|
555
|
+
- lib/aspera/secret/store/one_password_api.rb
|
|
556
|
+
- lib/aspera/secret/store/one_password_base.rb
|
|
557
|
+
- lib/aspera/secret/store/one_password_cli.rb
|
|
558
|
+
- lib/aspera/secret/store/secret_service.rb
|
|
559
|
+
- lib/aspera/secret/strength.rb
|
|
515
560
|
- lib/aspera/servlet_helpers.rb
|
|
516
561
|
- lib/aspera/ssh.rb
|
|
517
562
|
- lib/aspera/ssl.rb
|
|
@@ -529,8 +574,13 @@ files:
|
|
|
529
574
|
- lib/aspera/transfer/resumer.rb
|
|
530
575
|
- lib/aspera/transfer/spec.rb
|
|
531
576
|
- lib/aspera/transfer/spec.schema.yaml
|
|
577
|
+
- lib/aspera/transfer/units.rb
|
|
532
578
|
- lib/aspera/uri_reader.rb
|
|
533
579
|
- lib/aspera/web_auth/index.html.erb
|
|
580
|
+
- lib/aspera/web_auth/paste.rb
|
|
581
|
+
- lib/aspera/web_auth/receiver.rb
|
|
582
|
+
- lib/aspera/web_auth/relay.rb
|
|
583
|
+
- lib/aspera/web_auth/reply.html.erb
|
|
534
584
|
- lib/aspera/web_auth/server.rb
|
|
535
585
|
- lib/aspera/web_page.html.erb
|
|
536
586
|
- lib/aspera/web_page.rb
|
|
@@ -538,6 +588,8 @@ files:
|
|
|
538
588
|
- lib/aspera/yaml.rb
|
|
539
589
|
- lib/transferd_pb.rb
|
|
540
590
|
- lib/transferd_services_pb.rb
|
|
591
|
+
- llms.txt
|
|
592
|
+
- skills/ascli/SKILL.md
|
|
541
593
|
homepage: https://github.com/IBM/aspera-cli
|
|
542
594
|
licenses:
|
|
543
595
|
- Apache-2.0
|
|
@@ -555,7 +607,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
|
555
607
|
requirements:
|
|
556
608
|
- - ">="
|
|
557
609
|
- !ruby/object:Gem::Version
|
|
558
|
-
version: '3.
|
|
610
|
+
version: '3.3'
|
|
559
611
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
560
612
|
requirements:
|
|
561
613
|
- - ">="
|
|
@@ -565,6 +617,7 @@ requirements:
|
|
|
565
617
|
- Read the manual for any requirement
|
|
566
618
|
rubygems_version: 4.0.20
|
|
567
619
|
specification_version: 4
|
|
568
|
-
summary: '
|
|
569
|
-
|
|
620
|
+
summary: 'The automation interface for IBM Aspera, from command line to AI agents:
|
|
621
|
+
transfers, packages, files and administration of Aspera on Cloud, Faspex, Shares,
|
|
622
|
+
Node, Console, Orchestrator, High Speed Transfer Server'
|
|
570
623
|
test_files: []
|
metadata.gz.sig
CHANGED
|
Binary file
|
data/lib/aspera/keychain/base.rb
DELETED
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
# frozen_string_literal: true
|
|
2
|
-
|
|
3
|
-
module Aspera
|
|
4
|
-
module Keychain
|
|
5
|
-
class Base
|
|
6
|
-
CONTENT_KEYS = %i[label username password url description].freeze
|
|
7
|
-
|
|
8
|
-
# Returns a lightweight list: one Hash per secret with :label (and :id if the backend has one).
|
|
9
|
-
# Override in subclasses that can provide this cheaply without fetching full item details.
|
|
10
|
-
def ids
|
|
11
|
-
all.map { |s| s.slice(:id, :label).compact }
|
|
12
|
-
end
|
|
13
|
-
|
|
14
|
-
def validate_set(options)
|
|
15
|
-
Aspera.assert_type(options, Hash) { 'options' }
|
|
16
|
-
unsupported = options.keys - CONTENT_KEYS
|
|
17
|
-
Aspera.assert(unsupported.empty?) { "unsupported options: #{unsupported}, use #{CONTENT_KEYS.join(', ')}" }
|
|
18
|
-
options.each_pair do |k, v|
|
|
19
|
-
Aspera.assert_type(v, String) { k.to_s }
|
|
20
|
-
end
|
|
21
|
-
Aspera.assert(options.key?(:label), 'label is required')
|
|
22
|
-
end
|
|
23
|
-
|
|
24
|
-
# Labels are unique: `set` does not overwrite an existing secret
|
|
25
|
-
def assert_new_label(label)
|
|
26
|
-
Aspera.assert(get(label: label, exception: false).nil?) { "secret #{label} already exist, delete first" }
|
|
27
|
-
end
|
|
28
|
-
end
|
|
29
|
-
end
|
|
30
|
-
end
|
|
@@ -1,192 +0,0 @@
|
|
|
1
|
-
# frozen_string_literal: true
|
|
2
|
-
|
|
3
|
-
require 'aspera/hash_ext'
|
|
4
|
-
require 'aspera/environment'
|
|
5
|
-
require 'aspera/log'
|
|
6
|
-
require 'aspera/assert'
|
|
7
|
-
require 'aspera/keychain/base'
|
|
8
|
-
require 'aspera/yaml'
|
|
9
|
-
require 'openssl'
|
|
10
|
-
require 'yaml'
|
|
11
|
-
|
|
12
|
-
module Aspera
|
|
13
|
-
module Keychain
|
|
14
|
-
# Manage secrets in a simple Hash
|
|
15
|
-
class EncryptedHash < Base
|
|
16
|
-
LEGACY_CIPHER_NAME = 'aes-256-cbc'
|
|
17
|
-
DEFAULT_CIPHER_NAME = 'aes-256-cbc'
|
|
18
|
-
FILE_TYPE = 'encrypted_hash_vault'
|
|
19
|
-
FILE_KEYS = %w[version type cipher data].sort.freeze
|
|
20
|
-
FILE_KEYS_KDF = (%w[kdf] + FILE_KEYS).sort.freeze
|
|
21
|
-
# PBKDF2 parameters for new vaults
|
|
22
|
-
KDF_ITERATIONS = 200_000
|
|
23
|
-
KDF_DIGEST = 'SHA256'
|
|
24
|
-
KDF_SALT_BYTES = 16
|
|
25
|
-
private_constant :LEGACY_CIPHER_NAME, :DEFAULT_CIPHER_NAME, :FILE_TYPE, :FILE_KEYS, :FILE_KEYS_KDF,
|
|
26
|
-
:KDF_ITERATIONS, :KDF_DIGEST, :KDF_SALT_BYTES
|
|
27
|
-
|
|
28
|
-
def initialize(file:, password:)
|
|
29
|
-
super()
|
|
30
|
-
Aspera.assert_type(file, String) { 'path to vault file' }
|
|
31
|
-
@path = file
|
|
32
|
-
Log.dump(:vault_file, @path)
|
|
33
|
-
@all_secrets = {}
|
|
34
|
-
@cipher_name = DEFAULT_CIPHER_NAME
|
|
35
|
-
@kdf_params = nil
|
|
36
|
-
# true when the vault was created by v4.26.0 (password padded with zeros, no KDF)
|
|
37
|
-
@legacy_key = false
|
|
38
|
-
vault_encrypted_data = nil
|
|
39
|
-
Log.dump(:vault_file, File.expand_path(@path))
|
|
40
|
-
if File.exist?(@path)
|
|
41
|
-
vault_file = File.read(@path)
|
|
42
|
-
if vault_file.start_with?('---')
|
|
43
|
-
vault_info = Yaml.safe_load(vault_file)
|
|
44
|
-
Aspera.assert_type(vault_info, Hash) { "Invalid vault file: #{@path}" }
|
|
45
|
-
sorted_keys = vault_info.keys.sort
|
|
46
|
-
Aspera.assert(sorted_keys == FILE_KEYS || sorted_keys == FILE_KEYS_KDF) { "Invalid vault file: #{@path}: #{sorted_keys}" }
|
|
47
|
-
@cipher_name = vault_info['cipher']
|
|
48
|
-
@kdf_params = vault_info['kdf']
|
|
49
|
-
# vault created before PBKDF2 was introduced (v4.26.0 format: no kdf field)
|
|
50
|
-
@legacy_key = @kdf_params.nil?
|
|
51
|
-
vault_encrypted_data = vault_info['data']
|
|
52
|
-
else
|
|
53
|
-
# legacy vault file (binary, pre-YAML format)
|
|
54
|
-
@cipher_name = LEGACY_CIPHER_NAME
|
|
55
|
-
@legacy_key = true
|
|
56
|
-
vault_encrypted_data = File.read(@path, mode: 'rb')
|
|
57
|
-
end
|
|
58
|
-
end
|
|
59
|
-
# setting password also creates the cipher
|
|
60
|
-
@cipher = cipher(password)
|
|
61
|
-
@all_secrets = Yaml.safe_load(@cipher.decrypt(vault_encrypted_data)) || {} if !vault_encrypted_data.nil?
|
|
62
|
-
end
|
|
63
|
-
|
|
64
|
-
def info
|
|
65
|
-
return {
|
|
66
|
-
file: @path
|
|
67
|
-
}
|
|
68
|
-
end
|
|
69
|
-
|
|
70
|
-
def all
|
|
71
|
-
result = []
|
|
72
|
-
@all_secrets.each do |label, values|
|
|
73
|
-
normal = values.symbolize_keys
|
|
74
|
-
normal[:label] = label
|
|
75
|
-
CONTENT_KEYS.each { |k| normal[k] = '' unless normal.key?(k) }
|
|
76
|
-
result.push(normal)
|
|
77
|
-
end
|
|
78
|
-
return result
|
|
79
|
-
end
|
|
80
|
-
|
|
81
|
-
# set a secret
|
|
82
|
-
# @param options [Hash] with keys :label, :username, :password, :url, :description
|
|
83
|
-
def set(options)
|
|
84
|
-
validate_set(options)
|
|
85
|
-
label = options.delete(:label)
|
|
86
|
-
assert_new_label(label)
|
|
87
|
-
@all_secrets[label] = options.symbolize_keys
|
|
88
|
-
save
|
|
89
|
-
end
|
|
90
|
-
|
|
91
|
-
def get(label:, exception: true)
|
|
92
|
-
Aspera.assert(@all_secrets.key?(label)) { "Label not found: #{label}" } if exception
|
|
93
|
-
result = @all_secrets[label].clone
|
|
94
|
-
result[:label] = label if result.is_a?(Hash)
|
|
95
|
-
return result
|
|
96
|
-
end
|
|
97
|
-
|
|
98
|
-
def delete(label:)
|
|
99
|
-
Aspera.assert(@all_secrets.key?(label)) { "Label not found: #{label}" }
|
|
100
|
-
@all_secrets.delete(label)
|
|
101
|
-
save
|
|
102
|
-
end
|
|
103
|
-
|
|
104
|
-
def change_password(password)
|
|
105
|
-
# Generate new KDF params so a password change also re-salts the vault
|
|
106
|
-
# (and migrates a legacy vault to PBKDF2)
|
|
107
|
-
@legacy_key = false
|
|
108
|
-
@kdf_params = nil
|
|
109
|
-
@cipher = cipher(password)
|
|
110
|
-
save
|
|
111
|
-
end
|
|
112
|
-
|
|
113
|
-
private
|
|
114
|
-
|
|
115
|
-
# Minimal cipher wrapper using OpenSSL, compatible with the SymmetricEncryption
|
|
116
|
-
# binary format: a 6-byte header "@EnC\x00\x00" followed by AES ciphertext
|
|
117
|
-
# produced with a zero IV (encoding: :none, no random IV in header).
|
|
118
|
-
class OsslCipher
|
|
119
|
-
HEADER = "@EnC\x00\x00".b.freeze
|
|
120
|
-
HEADER_SIZE = HEADER.bytesize
|
|
121
|
-
|
|
122
|
-
def initialize(cipher_name, key)
|
|
123
|
-
@cipher_name = cipher_name
|
|
124
|
-
@key = key
|
|
125
|
-
end
|
|
126
|
-
|
|
127
|
-
def encrypt(plaintext)
|
|
128
|
-
c = OpenSSL::Cipher.new(@cipher_name)
|
|
129
|
-
c.encrypt
|
|
130
|
-
c.key = @key
|
|
131
|
-
c.iv = "\x00".b * c.iv_len
|
|
132
|
-
HEADER + c.update(plaintext.b) + c.final
|
|
133
|
-
end
|
|
134
|
-
|
|
135
|
-
def decrypt(ciphertext)
|
|
136
|
-
body = ciphertext.b[HEADER_SIZE..]
|
|
137
|
-
c = OpenSSL::Cipher.new(@cipher_name)
|
|
138
|
-
c.decrypt
|
|
139
|
-
c.key = @key
|
|
140
|
-
c.iv = "\x00".b * c.iv_len
|
|
141
|
-
(c.update(body) + c.final).force_encoding(Encoding::UTF_8)
|
|
142
|
-
end
|
|
143
|
-
end
|
|
144
|
-
|
|
145
|
-
# Derive an AES key from `new_password`.
|
|
146
|
-
# @legacy_key is true for vaults created by v4.26.0 or earlier (no kdf field):
|
|
147
|
-
# key = password truncated/zero-padded to key_bytes (same as symmetric-encryption did).
|
|
148
|
-
# Otherwise PBKDF2 is used. When @kdf_params is nil (new vault or password change)
|
|
149
|
-
# a fresh salt is generated; when already set (existing vault) it is reused.
|
|
150
|
-
def cipher(new_password)
|
|
151
|
-
key_bytes = @cipher_name.split('-')[1].to_i / Environment::BITS_PER_BYTE
|
|
152
|
-
key =
|
|
153
|
-
if @legacy_key
|
|
154
|
-
# Replicate the v4.26.0 key derivation: password + NUL padding, truncated to key_bytes
|
|
155
|
-
(new_password + ("\x00" * key_bytes))[0, key_bytes]
|
|
156
|
-
else
|
|
157
|
-
if @kdf_params.nil?
|
|
158
|
-
# New vault or password change: generate a fresh salt
|
|
159
|
-
salt = OpenSSL::Random.random_bytes(KDF_SALT_BYTES)
|
|
160
|
-
@kdf_params = {
|
|
161
|
-
'algo' => 'PBKDF2',
|
|
162
|
-
'digest' => KDF_DIGEST,
|
|
163
|
-
'iterations' => KDF_ITERATIONS,
|
|
164
|
-
'salt' => [salt].pack('m0') # base64, no newlines
|
|
165
|
-
}
|
|
166
|
-
end
|
|
167
|
-
salt = @kdf_params['salt'].unpack1('m0')
|
|
168
|
-
OpenSSL::KDF.pbkdf2_hmac(
|
|
169
|
-
new_password,
|
|
170
|
-
salt: salt,
|
|
171
|
-
iterations: @kdf_params['iterations'],
|
|
172
|
-
length: key_bytes,
|
|
173
|
-
hash: @kdf_params['digest']
|
|
174
|
-
)
|
|
175
|
-
end
|
|
176
|
-
OsslCipher.new(@cipher_name, key)
|
|
177
|
-
end
|
|
178
|
-
|
|
179
|
-
# save current data to file with format
|
|
180
|
-
def save
|
|
181
|
-
vault_info = {
|
|
182
|
-
'version' => '1.1.0',
|
|
183
|
-
'type' => FILE_TYPE,
|
|
184
|
-
'cipher' => @cipher_name,
|
|
185
|
-
'kdf' => @kdf_params,
|
|
186
|
-
'data' => @cipher.encrypt(YAML.dump(@all_secrets))
|
|
187
|
-
}
|
|
188
|
-
Environment.write_file_restricted(@path, force: true) { YAML.dump(vault_info) }
|
|
189
|
-
end
|
|
190
|
-
end
|
|
191
|
-
end
|
|
192
|
-
end
|