feat: add support for encrypted ssh key and ssh-agent (#337)

Closes #334

maa-cli/config_examples/cli.toml

@@ -1,44 +1,61 @@
 "$schema" = "../schemas/cli.schema.json"
 
-# Configurations for MaaCore
+# Configurations for MaaCore installation and update
 [core]
-channel = "Beta" # update channel of MaaCore, can be "Alpha", "Beta" or "Stable"
-test_time = 0    # time to test the speed of mirrors, 0 to disable
-# url of the MaaCore version api, used to get the latest version of MaaCore,
-# leave it empty to use the default url
+# Update channel of MaaCore, can be "Alpha", "Beta" or "Stable"
+channel = "Beta"
+# Time to test the speed of mirrors, in seconds, set to 0 to disable the test
+# Default value is 3, smaller value if you have a fast network
+test_time = 0
+# URL of the MaaCore version API, used to get the latest version of MaaCore,
+# leave it empty to use the default URL
 api_url = "https://github.com/MaaAssistantArknights/MaaRelease/raw/main/MaaAssistantArknights/api/version/"
 
 # Configurations for whether to install given components of MaaCore
 [core.components]
-library = true  # whether to install libraries of MaaCore
-resource = true # whether to install resources of MaaCore
+library = true  # Whether to install libraries of MaaCore
+resource = true # Whether to install resources of MaaCore
 
-# Configurations for maa-cli
+# Configurations for maa-cli self update
 [cli]
-channel = "Alpha" # update channel of maa-cli, can be "Alpha", "Beta" or "Stable"
-# url of the maa-cli version api, used to get the latest version of maa-cli,
-# if you want to use jsdelivr, the double v in @vversion is necessary instead of a typo
+# Update channel of maa-cli, can be "Alpha", "Beta" or "Stable".
+channel = "Alpha"
+# URL of the maa-cli version API, used to get the latest version of maa-cli.
 api_url = "https://cdn.jsdelivr.net/gh/MaaAssistantArknights/maa-cli@vversion/"
-# url to download latest version of maa-cli, leave it empty to use the default url
+# URL to download latest version of maa-cli, leave it empty to use the default URL.
 download_url = "https://github.com/MaaAssistantArknights/maa-cli/releases/download/"
 
 # Configurations for whether to install given components of maa-cli
 [cli.components]
-binary = false # whether to install binary of maa-cli
+binary = false # Whether to install binary of maa-cli
 
 # Configurations for hot update of resource
 # Note: this is different from `core.components.resource`, this is for hot update of resource
 # while this is hot update resource of MaaCore
-# You can not use this to hot update without any base resource
+# You cannot use this to hot update without any base resource
 [resource]
-auto_update = true  # whether to auto update resource each time run maa task
-backend = "libgit2" # backend to manipulate repository, can be "git" or "libgit2"
+auto_update = true  # Whether to auto update resource each time run maa task
+backend = "libgit2" # Backend to manipulate repository, can be `git` or `libgit2`
 
 # Configurations for remote git repository of resource
 [resource.remote]
-branch = "main" # branch of remote resource repository
-# url of remote resource repository, leave it empty to use the default url
-url = "https://github.com/MaaAssistantArknights/MaaResource.git"
-# if you want to use ssh, set url to ssh url and set ssh_key to the path of ssh key
+branch = "main" # Branch of remote resource repository
+# URL of remote resource repository, leave it empty to use the default URL
+uril = "https://github.com/MaaAssistantArknights/MaaResource.git"
+# Or you can use ssh to clone the repository
 # url = "git@github.com:MaaAssistantArknights/MaaResource.git"
-# ssh_key = "~/.ssh/id_ed25519" # path to ssh key
+# If you want to use ssh, a certificate is needed which can be "ssh-agent" or "ssh-key"
+# To use ssh-agent, set `use_ssh_agent` to true, and leave `ssh_key` and `passphrase` empty
+# use_ssh_agent = true # Use ssh-agent to authenticate
+# To use ssh-key, set `ssh_key` to path of ssh key,
+ssh_key = "~/.ssh/id_ed25519" # Path of ssh key
+# A Passphrase is needed if the ssh key is encrypted
+passphrase = "password" # Passphrase of ssh key
+# Store plain text password in configuration file is unsafe, so there are some ways to avoid it
+# 1. set `passphrase` to true, then maa-cli will prompt you to input passphrase each time
+# passphrase = true
+# 2. set `passphrase` to a environment variable, then maa-cli will use the environment variable as passphrase
+# passphrase = { env = "MAA_SSH_PASSPHRASE" }
+# 3. set `passphrase` to a command, then maa-cli will execute the command to get passphrase
+# which is useful when you use a password manager to manage your passphrase
+# passphrase = { cmd = ["pass", "show", "ssh/id_ed25519"] }

maa-cli/docs/en-US/config.md

@@ -417,11 +417,24 @@ backend = "libgit2" # the backend of resource, can be "libgit2" or "git"
 
 # the remote of resource
 [resource.remote]
-branch = "main" # the branch of remote repository
-# the url of remote repository, when using ssh, you should set ssh_key field
-url = "https://github.com/MaaAssistantArknights/MaaResource.git"
-# url = "git@github.com:MaaAssistantArknights/MaaResource.git"
-# ssh_key = "~/.ssh/id_ed25519" # path to ssh key
+branch = "main" # Branch of remote resource repository
+# URL of remote resource repository, leave it empty to use the default URL
+url = "git@github.com:MaaAssistantArknights/MaaResource.git"
+# If you want to use ssh, a certificate is needed which can be "ssh-agent" or "ssh-key"
+# To use ssh-agent, set `use_ssh_agent` to true, and leave `ssh_key` and `passphrase` empty
+# use_ssh_agent = true # Use ssh-agent to authenticate
+# To use ssh-key, set `ssh_key` to path of ssh key,
+ssh_key = "~/.ssh/id_ed25519" # Path of ssh key
+# A Passphrase is needed if the ssh key is encrypted
+passphrase = "password" # Passphrase of ssh key
+# Store plain text password in configuration file is unsafe, so there are some ways to avoid it
+# 1. set `passphrase` to true, then maa-cli will prompt you to input passphrase each time
+# passphrase = true
+# 2. set `passphrase` to a environment variable, then maa-cli will use the environment variable as passphrase
+# passphrase = { env = "MAA_SSH_PASSPHRASE" }
+# 3. set `passphrase` to a command, then maa-cli will execute the command to get passphrase
+# which is useful when you use a password manager to manage your passphrase
+# passphrase = { cmd = ["pass", "show", "ssh/id_ed25519"] }
 ```
 
 **NOTE**:

maa-cli/docs/ja-JP/config.md

@@ -408,10 +408,23 @@ backend = "libgit2" # 资源热更新后端，可选值为 "git" 或者 "libgit2
 # 资源热更新远程仓库相关配置
 [resource.remote]
 branch = "main" # 远程仓库的分支，默认为 "main"
-# 远程仓库的 url，如果你想要使用 ssh，你必须配置 ssh_key 的路径
-url = "https://github.com/MaaAssistantArknights/MaaResource.git"
-# url = "git@github.com:MaaAssistantArknights/MaaResource.git"
-# ssh_key = "~/.ssh/id_ed25519" # path to ssh key
+# 远程资源仓库的 URL，留空以使用默认 URL
+url = "git@github.com:MaaAssistantArknights/MaaResource.git"
+# 如果你想使用 ssh，那么你需要配置认证方式, 可以是 "ssh-agent" 或 "ssh-key"
+# 要使用 ssh-agent，请将 `use_ssh_agent` 设置为 true，并将 `ssh_key` 和 `passphrase` 留空
+# use_ssh_agent = true # 使用 ssh-agent 进行身份验证
+# 要使用 ssh-key，请将 `ssh_key` 设置为 ssh 密钥的路径
+ssh_key = "~/.ssh/id_ed25519" # ssh 密钥的路径
+# 如果 ssh 密钥已加密，你需要提供密码
+passphrase = "password"       # ssh 密钥的密码
+# 在配置文件中存储明文密码是不安全的，因此有一些方法可以避免这种情况
+# 1. 将 `passphrase` 设置为 true，然后 maa-cli 将每次提示你输入密码
+# passphrase = true
+# 2. 将 `passphrase` 设置为环境变量名，然后 maa-cli 将使用环境变量作为密码
+# passphrase = { env = "MAA_SSH_PASSPHRASE" }
+# 3. 将 `passphrase` 设置为命令，然后 maa-cli 将执行该命令以获取密码
+# 这在你使用密码管理器管理密码时非常有用
+# passphrase = { cmd = ["pass", "show", "ssh/id_ed25519"] }
 ```
 
 **注意事项**：

maa-cli/docs/ko-KR/config.md

@@ -398,13 +398,25 @@ binary = true # maa-cli 바이너리 파일을 설치할지 여부, 기본값은
 auto_update = true  # 각 작업 실행 시 리소스를 자동 업데이트할지 여부, 기본값은 false
 backend = "libgit2" # 리소스 핫 업데이트 백엔드, 가능한 값은 "git" 또는 "libgit2", 기본값은 "git"
 
-# 리소스 핫 업데이트 원격 저장소 관련 설정
 [resource.remote]
-branch = "main" # 원격 저장소의 분기, 기본값은 "main"
-# 원격 저장소의 URL, ssh를 사용하려면 ssh_key 경로를 설정해야 함
-url = "https://github.com/MaaAssistantArknights/MaaResource.git"
-# url = "git@github.com:MaaAssistantArknights/MaaResource.git"
-# ssh_key = "~/.ssh/id_ed25519" # ssh 키 경로
+branch = "main" # 원격 저장소의 브랜치, 기본값은 "main"입니다.
+# 원격 리소스 저장소의 URL, 기본 URL을 사용하려면 비워 두세요.
+url = "git@github.com:MaaAssistantArknights/MaaResource.git"
+# ssh를 사용하려면 인증 방식을 구성해야 하며, "ssh-agent" 또는 "ssh-key" 중 하나를 사용할 수 있습니다.
+# ssh-agent를 사용하려면 `use_ssh_agent`를 true로 설정하고, `ssh_key`와 `passphrase`는 비워 두세요.
+# use_ssh_agent = true # ssh-agent를 사용하여 인증
+# ssh-key를 사용하려면 `ssh_key`에 ssh 키의 경로를 설정하세요.
+ssh_key = "~/.ssh/id_ed25519" # ssh 키의 경로
+# ssh 키가 암호화된 경우, 암호를 입력해야 합니다.
+passphrase = "password"       # ssh 키의 암호
+# 설정 파일에 평문 암호를 저장하는 것은 안전하지 않으므로 이를 방지하기 위한 방법이 있습니다.
+# 1. `passphrase`를 true로 설정하면, maa-cli가 매번 암호를 입력하라고 요청합니다.
+# passphrase = true
+# 2. `passphrase`를 환경 변수 이름으로 설정하면, maa-cli는 해당 환경 변수를 암호로 사용합니다.
+# passphrase = { env = "MAA_SSH_PASSPHRASE" }
+# 3. `passphrase`를 명령어로 설정하면, maa-cli는 해당 명령어를 실행하여 암호를 가져옵니다.
+# 이는 암호 관리자를 사용하여 암호를 관리할 때 매우 유용합니다.
+# passphrase = { cmd = ["pass", "show", "ssh/id_ed25519"] }
 ```
 
 **주의사항**：

maa-cli/docs/zh-CN/config.md

@@ -404,10 +404,23 @@ backend = "libgit2" # 资源热更新后端，可选值为 "git" 或者 "libgit2
 # 资源热更新远程仓库相关配置
 [resource.remote]
 branch = "main" # 远程仓库的分支，默认为 "main"
-# 远程仓库的 url，如果你想要使用 ssh，你必须配置 ssh_key 的路径
-url = "https://github.com/MaaAssistantArknights/MaaResource.git"
-# url = "git@github.com:MaaAssistantArknights/MaaResource.git"
-# ssh_key = "~/.ssh/id_ed25519" # path to ssh key
+# 远程资源仓库的 URL，留空以使用默认 URL
+url = "git@github.com:MaaAssistantArknights/MaaResource.git"
+# 如果你想使用 ssh，那么你需要配置认证方式, 可以是 "ssh-agent" 或 "ssh-key"
+# 要使用 ssh-agent，请将 `use_ssh_agent` 设置为 true，并将 `ssh_key` 和 `passphrase` 留空
+# use_ssh_agent = true # 使用 ssh-agent 进行身份验证
+# 要使用 ssh-key，请将 `ssh_key` 设置为 ssh 密钥的路径
+ssh_key = "~/.ssh/id_ed25519" # ssh 密钥的路径
+# 如果 ssh 密钥已加密，你需要提供密码
+passphrase = "password"       # ssh 密钥的密码
+# 在配置文件中存储明文密码是不安全的，因此有一些方法可以避免这种情况
+# 1. 将 `passphrase` 设置为 true，然后 maa-cli 将每次提示你输入密码
+# passphrase = true
+# 2. 将 `passphrase` 设置为环境变量名，然后 maa-cli 将使用环境变量作为密码
+# passphrase = { env = "MAA_SSH_PASSPHRASE" }
+# 3. 将 `passphrase` 设置为命令，然后 maa-cli 将执行该命令以获取密码
+# 这在你使用密码管理器管理密码时非常有用
+# passphrase = { cmd = ["pass", "show", "ssh/id_ed25519"] }
 ```
 
 **注意事项**：

maa-cli/docs/zh-TW/config.md

@@ -407,11 +407,23 @@ backend = "libgit2" # 资源热更新后端，可选值为 "git" 或者 "libgit2
 
 # 资源热更新远程仓库相关配置
 [resource.remote]
-branch = "main" # 远程仓库的分支，默认为 "main"
-# 远程仓库的 url，如果你想要使用 ssh，你必须配置 ssh_key 的路径
-url = "https://github.com/MaaAssistantArknights/MaaResource.git"
-# url = "git@github.com:MaaAssistantArknights/MaaResource.git"
-# ssh_key = "~/.ssh/id_ed25519" # path to ssh key
+# 远程资源仓库的 URL，留空以使用默认 URL
+url = "git@github.com:MaaAssistantArknights/MaaResource.git"
+# 如果你想使用 ssh，那么你需要配置认证方式, 可以是 "ssh-agent" 或 "ssh-key"
+# 要使用 ssh-agent，请将 `use_ssh_agent` 设置为 true，并将 `ssh_key` 和 `passphrase` 留空
+# use_ssh_agent = true # 使用 ssh-agent 进行身份验证
+# 要使用 ssh-key，请将 `ssh_key` 设置为 ssh 密钥的路径
+ssh_key = "~/.ssh/id_ed25519" # ssh 密钥的路径
+# 如果 ssh 密钥已加密，你需要提供密码
+passphrase = "password"       # ssh 密钥的密码
+# 在配置文件中存储明文密码是不安全的，因此有一些方法可以避免这种情况
+# 1. 将 `passphrase` 设置为 true，然后 maa-cli 将每次提示你输入密码
+# passphrase = true
+# 2. 将 `passphrase` 设置为环境变量名，然后 maa-cli 将使用环境变量作为密码
+# passphrase = { env = "MAA_SSH_PASSPHRASE" }
+# 3. 将 `passphrase` 设置为命令，然后 maa-cli 将执行该命令以获取密码
+# 这在你使用密码管理器管理密码时非常有用
+# passphrase = { cmd = ["pass", "show", "ssh/id_ed25519"] }
 ```
 
 **注意事项**：

maa-cli/src/config/cli/mod.rs

@@ -196,14 +196,17 @@ mod tests {
                 Token::Str("backend"),
                 GitBackend::Libgit2.to_token(),
                 Token::Str("remote"),
-                Token::Map { len: Some(3) },
+                Token::Map { len: Some(5) },
                 Token::Str("branch"),
                 Token::Some,
                 Token::Str("main"),
-                Token::Str("ssh_key"),
-                Token::None,
                 Token::Str("url"),
                 Token::Str("https://github.com/MaaAssistantArknights/MaaResource.git"),
+                Token::Str("ssh_key"),
+                Token::Some,
+                Token::Str("~/.ssh/id_ed25519"),
+                Token::Str("passphrase"),
+                Token::Str("password"),
                 Token::MapEnd,
                 Token::MapEnd,
                 Token::MapEnd,