keys-safe-guard

# AI Builder - Keys Safe Guard Manage secure key operations for `config/.env` by default, or another explicit `.env`/`.env.*` file via `--env-file`, and govern any privileged (`sudo`) action an agent needs to run. ## When to Use This Skill - User asks to enable or disable env key safeguarding. - User asks to list available key names without exposing key values. - User asks to update or insert one or more env keys safely. - User asks for secure key operations related to LLM/provider credentials. - User asks to use a GUI popup / dialog for a sudo password prompt. - A Python or background process needs to read or write protected env keys. - **Any time the agent needs to run a `sudo` command** (e.g. `sudo installer`, `sudo apt-get install`, `sudo snap install`, `sudo dnf install`, ownership/permission fixes) — apply the general sudo rule before invoking it. ## Your Roles in This Skill - **Security Engineer**: Enforce safe key handling and least-privilege behavior. - **Backend Developer (Engineer)**: Run key-safe command actions correctly. - **Technical Writer**: Report exactly what changed without leaking secret values. ## Role Communication Announce actions before performing them, using: > As a {Role, and Role-XYZ if more roles}, I will {action description} This keeps human-in-the-loop oversight at key decision points. ## General Sudo Rule For **any** agent-invoked `sudo` command, follow [references/sudo-rule.md](references/sudo-rule.md). Decision order: 1. **Passwordless sudo available** (`sudo -n true` exits 0) → show the command, get one-time user approval, run directly. 2. **GUI session available** (desktop console, not SSH) → elevate via native dialog (`osascript … with administrator privileges` on macOS; `pkexec` or `sudo -A` with `zenity`/`kdialog` askpass on Linux). 3. **Otherwise (SSH / headless)** → print the exact command for the user to run manually and wait. Do **not** invoke `sudo` directly. Never ask the user to paste a sudo password into chat, never log it, never batch unrelated privileged operations behind one approval. See the reference for examples and detection details. ## `keys-safe-guard` Operations For env actions — `enable`, `disable`, `get_key_names`, `get_key_value`, `put_key_values` — follow [references/keys-safe-guard.md](references/keys-safe-guard.md). Quick summary: - Use **`--gui`** for `enable`, `disable`, `put_key_values` (mandatory for agent-invoked runs). - `--gui` is optional for `get_key_names` (read-only, in-memory). - Use `--env-file PATH` when the user explicitly targets a non-default `.env`/`.env.*` file; omit it for `config/.env`. - Use `--auto-create` with `enable` or `put_key_values` when the target env file should be created if missing. - `.env.example` is not managed by this skill because it should not contain secrets. - In a non-GUI environment, do not retry — tell the user to configure passwordless sudo or disable safe guard from a GUI-capable session. ## Expected Output - Correct action execution. - No secret value disclosure. - Clear status message with concise next steps (e.g. engine restart after safeguard changes). ## Key Principles - Prefer minimal changes and single-action execution. - Keep secrets out of logs and responses; never print key values. - Use `get_key_names` for inspection whenever values are not required. - Treat `--gui` as mandatory for every agent-invoked `keys-safe-guard` action except `get_key_names`. - Do not rely on terminal password prompts for agent-driven privileged work — use GUI dialog, passwordless sudo, or hand the command back to the user. - Do not keep retrying when the environment cannot elevate; surface the constraint and the fix.