diff --git a/.gitignore b/.gitignore index 2eb4ca1..060d1a4 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,6 @@ secrets/vault-pass.txt # Placeholder marker generated when password archive is absent secrets/vault-pass.txt.zip.PLACEHOLDER +# Local installer env overrides with real secrets +install.local.env +*.secret.env diff --git a/README.md b/README.md index 37f82d2..eef192a 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,15 @@ - Agent 整合補充：[`docs/agent-integration.md`](docs/agent-integration.md) - Vault 基礎說明：[`docs/secret-vault.md`](docs/secret-vault.md) +## 安裝設定檔 + +Repo 內提供： + +- `install.env.example`：給人類/agent 複製參考 +- `install.env`：空值 placeholder，可在安裝前填入 `INSTALL_VAULT_PASS_METHOD`、`VAULT_PASS_URL`、`VAULT_PASS_ZIP_PASSWORD_FILE` 等設定 + +`install.env` 不應填入真實 secrets 後再 commit；若要保存本機私密設定，使用 `install.local.env` 並透過 `INSTALL_ENV_FILE=install.local.env` 指定。 + ## 全自動 agent 安裝 ```bash diff --git a/docs/agent-install-runbook.md b/docs/agent-install-runbook.md index e6d8548..c7098fa 100644 --- a/docs/agent-install-runbook.md +++ b/docs/agent-install-runbook.md @@ -56,6 +56,43 @@ PLACEHOLDER 然後回報人類：需要把此 agent / 機器的 SSH public key 加到 Gitea 或 deploy key。 +## 2.5 設定 installer env + +Repo 內提供兩個 env 檔： + +```text +install.env.example # 範本 +install.env # 安裝用 placeholder +``` + +安裝前先設定 `install.env`： + +```bash +cd ~/projects/agent-secret-vault +cp -n install.env.example install.env +editor install.env +``` + +常用設定： + +```bash +# 一次性 URL 下載 vault-pass.txt +INSTALL_VAULT_PASS_METHOD="url" +VAULT_PASS_URL="https://example.com/one-time/vault-pass.txt" + +# 或：zip 密碼放在本機安全檔案 +INSTALL_VAULT_PASS_METHOD="archive" +VAULT_PASS_ZIP_PASSWORD_FILE="/secure/path/zip-password.txt" +``` + +若需要使用另一個 env 檔： + +```bash +INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh +``` + +不要把含真實密碼/token 的 env 檔 commit。 + ## 3. 安裝 vault password file 標準位置： @@ -123,7 +160,7 @@ export VAULT_PASS_FILE=/path/to/vault-pass.txt ### Agent 全自動安裝（避免卡在互動密碼） -若安裝由 AI agent / CI 執行，不要走互動 prompt。用以下任一非互動方式： +若安裝由 AI agent / CI 執行，不要走互動 prompt。優先把設定寫進 `install.env` 或 `install.local.env`，也可用以下任一非互動方式： ```bash # 方式 A：從安全 URL 下載 vault-pass.txt diff --git a/docs/human-guide.md b/docs/human-guide.md index 410bd35..47f3fa0 100644 --- a/docs/human-guide.md +++ b/docs/human-guide.md @@ -66,6 +66,30 @@ git push 腳本會要求互動輸入 zip 密碼。這個 zip 密碼不要寫進 repo、chat 或 log；交給安裝者時用另外的安全渠道。 +## 安裝時設定 vault-pass + +安裝流程建議先填 repo 內的 env 檔： + +```bash +cd ~/projects/agent-secret-vault +cp -n install.env.example install.env +editor install.env +./scripts/install-vault-pass.sh +``` + +`install.env` 可設定： + +- `INSTALL_VAULT_PASS_METHOD=url` + `VAULT_PASS_URL=...` +- `INSTALL_VAULT_PASS_METHOD=archive` + `VAULT_PASS_ZIP_PASSWORD_FILE=...` +- `INSTALL_VAULT_PASS_METHOD=manual` + `VAULT_PASS_CONTENT=...` +- `INSTALL_VAULT_PASS_METHOD=create` + +若 env 內含真實 secrets，不要 commit。可改用 `install.local.env`，再執行： + +```bash +INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh +``` + ## 給 agent 的全自動安裝方式 如果目標是「AI agent 直接安裝，不要卡在互動輸入密碼」，請不要讓 agent 選互動 zip 解壓。改用環境變數指定方法： diff --git a/install.env b/install.env new file mode 100644 index 0000000..86d5354 --- /dev/null +++ b/install.env @@ -0,0 +1,10 @@ +# Local installer config for agent-secret-vault. +# Fill this file before running ./scripts/install-vault-pass.sh. +# WARNING: this file may contain secrets. Do not commit real values. + +VAULT_PASS_FILE="$HOME/.config/vault-pass.txt" +INSTALL_VAULT_PASS_METHOD="" +VAULT_PASS_CONTENT="" +VAULT_PASS_URL="" +VAULT_PASS_ZIP_PASSWORD_FILE="" +VAULT_PASS_ZIP_PASSWORD="" diff --git a/install.env.example b/install.env.example new file mode 100644 index 0000000..f4f683c --- /dev/null +++ b/install.env.example @@ -0,0 +1,32 @@ +# agent-secret-vault installer env template +# +# Usage: +# cp install.env.example install.env +# editor install.env +# ./scripts/install-vault-pass.sh +# +# Keep real install.env private. It may contain secrets. + +# Where to install/read the Ansible Vault password file. +VAULT_PASS_FILE="$HOME/.config/vault-pass.txt" + +# Choose one method: create | manual | url | archive +# Leave empty for interactive menu. +INSTALL_VAULT_PASS_METHOD="" + +# Method: manual +# Direct vault-pass.txt content. Avoid this unless running in a secure local shell. +VAULT_PASS_CONTENT="" + +# Method: url +# One-time HTTPS URL containing vault-pass.txt. +VAULT_PASS_URL="" + +# Method: archive +# Password-protected zip path defaults to secrets/vault-pass.txt.zip. +# Put zip password in a local file when possible. Safer than putting it inline. +VAULT_PASS_ZIP_PASSWORD_FILE="" + +# Method: archive fallback +# Inline zip password. Avoid in shared shells/logging environments. +VAULT_PASS_ZIP_PASSWORD="" diff --git a/scripts/install-vault-pass.sh b/scripts/install-vault-pass.sh index 5070873..4eee773 100755 --- a/scripts/install-vault-pass.sh +++ b/scripts/install-vault-pass.sh @@ -5,6 +5,23 @@ REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" DEST="${VAULT_PASS_FILE:-$HOME/.config/vault-pass.txt}" ARCHIVE="${1:-$REPO_DIR/secrets/vault-pass.txt.zip}" VAULT_FILE="${VAULT_FILE:-$REPO_DIR/secrets/vault.yml}" +ENV_FILE="${INSTALL_ENV_FILE:-$REPO_DIR/install.env}" + +load_env_file() { + if [ -f "$ENV_FILE" ]; then + set -a + # shellcheck disable=SC1090 + . "$ENV_FILE" + set +a + fi +} + +load_env_file + +# Re-apply env-configurable paths after loading install.env. +DEST="${VAULT_PASS_FILE:-$HOME/.config/vault-pass.txt}" +ARCHIVE="${VAULT_PASS_ARCHIVE:-${1:-$REPO_DIR/secrets/vault-pass.txt.zip}}" +VAULT_FILE="${VAULT_FILE:-$REPO_DIR/secrets/vault.yml}" # Optional non-interactive controls: # INSTALL_VAULT_PASS_METHOD=create|manual|url|archive # VAULT_PASS_CONTENT= (for method=manual) @@ -16,6 +33,11 @@ usage() { cat <