From 2984dda34d26e9fa6d3bc98639e65d2bf13c3007 Mon Sep 17 00:00:00 2001 From: Shohei KAMON Date: Sat, 19 Apr 2025 01:09:01 +0800 Subject: [PATCH] docs; update readme Signed-off-by: Shohei KAMON --- README.md | 24 ++++++-- docs/spec/configure.md | 131 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 149 insertions(+), 6 deletions(-) create mode 100644 docs/spec/configure.md diff --git a/README.md b/README.md index 425c9ed..5f5978e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,18 @@ > > This project is inspired by the design philosophy and usability of the AWS CLI. +--- + +## Environment + +This tool has been tested with: + +- **Python 3.11 or newer** + +Other versions are not officially supported. +Please ensure you are using Python 3.11+ before running or contributing to this project. + +--- ## Installation @@ -65,14 +77,13 @@ fireblocks-cli --help --- -## Environment +## Directory Structure (XDG Base Directory Specification) -This tool has been tested with: +This CLI follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html): -- **Python 3.11 or newer** - -Other versions are not officially supported. -Please ensure you are using Python 3.11+ before running or contributing to this project. +- Configuration: `$XDG_CONFIG_HOME/fireblocks-cli/config.toml` (default: `~/.config/fireblocks-cli/config.toml`) +- Data: `$XDG_DATA_HOME/fireblocks-cli/` (default: `~/.local/share/fireblocks-cli/`) +- Cache: `$XDG_CACHE_HOME/fireblocks-cli/` (default: `~/.cache/fireblocks-cli/`) --- @@ -159,6 +170,7 @@ To change the copyright holder name inserted into source files: ``` > **Important**: The value in `COPYRIGHT_HOLDER` must be under 50 characters. + --- ## 🤝 Contributing diff --git a/docs/spec/configure.md b/docs/spec/configure.md new file mode 100644 index 0000000..fab0bc2 --- /dev/null +++ b/docs/spec/configure.md @@ -0,0 +1,131 @@ +# fireblocks-cli: `configure` Command Specification (Extended) + +This document outlines the behavior and structure of the `configure` subcommand group in the `fireblocks-cli` tool, including extended specifications and validation behavior. + +--- + +## ✅ General Behavior + +- The `api_secret_key` field uses `value` instead of `path` regardless of its type. +- The config file follows TOML format located at `~/.config/fireblocks-cli/config.toml`. + +--- + +## `configure init` + +- Recursively creates `~/.config/fireblocks-cli/keys` if not present. +- Generates a minimal `~/.config/fireblocks-cli/config.toml` template if not found: + +```toml +[default] +api_id = "" +api_secret_key = { type = "file", value = "" } + +# [example] +# api_id = "abcd-1234-api-key" +# api_secret_key = { type = "file", value = "~/.config/fireblocks-cli/keys/abcd.key" } +``` + +- If `[default]` section does not contain both `api_id` and `api_secret_key`, falls back to `~/.config/fireblocks-cli/credentials`. + +--- + +## `configure gen-key` + +- Creates a new private key under `~/.config/fireblocks-cli/keys`. +- Supported algorithms: `rsa2048`, `rsa4096`, `ed25519` (default). +- Key names: + - 12-character base32 string (lowercase alphanumerics only) + - Files: + - `{key_name}.key` + - `{key_name}.csr` +- Prevents key name collision. +- Prompts for organization (O=...) for CSR subject. +- CSR subject fields are extendable via CLI options. +- Optional: key name can be provided; collision causes error. +- Files are saved with permission mode `0600`. + +--- + +## `configure list` + +- Validates both `config.toml` and `credentials` files before proceeding. +- Displays all available `[profile]` names from: + - `~/.config/fireblocks-cli/credentials` + - `~/.config/fireblocks-cli/config.toml` +- Each profile includes a source tag: + ``` + default (from credentials) + example (from config) + ``` +- Secret keys or key names are **not** shown. + +--- + +## `configure edit` + +- Opens `~/.config/fireblocks-cli/config.toml` using the system's `$EDITOR`. + +--- + +## `configure validate` + +- Performs TOML syntax check on both `config.toml` and `credentials`. +- Does not require `api_id` or `api_secret_key` to be present. +- If either exists: + - `api_id` must be a string. + - `api_secret_key` must contain both: + - `type` as a string + - `value` as a string +- Key file paths listed in `value` must have file permission `0600`, or validation fails. +- Duplicate profile names across config and credentials raise an error, except for `default` (credentials takes precedence). +- Logs will indicate exact error fields and line numbers. +- Validation logic is modular and designed for extensibility. + +--- + +## `configure add` + +- Adds a new API profile to `~/.config/fireblocks-cli/config.toml`. +- Arguments: + - `name` (profile name) + - `api_id` +- Internally calls `gen-key` and generates both `.key` and `.csr` files. +- Displays paths to key and CSR. +- Appends profile to the **end of config file** without reformatting. + +```toml +[{name}] +api_id = "{api_id}" +api_secret_key = { type = "file", value = "{path}" } +``` + +- Will not overwrite existing profiles. + + +--- + +## 🔄 Additional Clarification Based on Unit Test Design + +### `configure list` (clarification) +- Profile names listed from both config and credentials. +- Source shown explicitly: `example (from config)` or `default (from credentials)`. +- Profiles are printed in order of: + 1. credentials file + 2. config file +- `key_name` values are not shown. + +### `configure validate` (clarification) +- Outputs errors with line numbers and specific field issues. +- If `api_secret_key.value` points to a file, that file must have `0600` permissions. +- Extensible to support new `type` formats like `vault`, `env`. + +### `configure gen-key` (clarification) +- Generated key names must be lowercase alphanumerics only. +- Key and CSR files must be saved with `chmod 600`. +- Algorithm defaults to `ed25519`. + +### `configure add` (clarification) +- Profile is added to the bottom of `~/.config/fireblocks-cli/config.toml`. +- Will not reorder or format the file. +- Fails if a profile of the same name already exists.