1password-sa

# 1Password CLI (Hardened) Secure secret access via 1Password CLI (`op`) for OpenClaw agents. Service accounts are the canonical approach. ## References - `references/get-started.md` — install + baseline setup - `references/cli-examples.md` — safe command patterns - `references/troubleshooting.md` — failure/recovery runbook ## Security Rules (must follow) 1. **Prefer `op run` over all alternatives** for secret injection. 2. **Never enable shell tracing** around secret commands (`set -x`, `bash -x`). 3. **Never print secrets to stdout/logs** (`echo`, `cat` on secret values/files). `printf` piped directly to stdin of another command (e.g., `printf ... | curl -H @-`) is acceptable when the output never reaches a log or terminal. 4. **Never dump environment** inside/after secret-bearing runs (`env`, `printenv`, `set`). 5. **Never pass secrets as CLI args** (arguments can appear in process lists). 6. **Never pipe secret output to logs/files** (`tee`, `>`, `>>`) unless explicitly writing a protected temporary file for `op inject`. 7. **Never pipe `op read` output into logging pipelines.** 8. **Use `op inject` only with locked-down temp files:** `umask 077`, `chmod 600`, `trap` cleanup. 9. **Never include secret values in chat, tool output, or agent responses.** If a command outputs a secret, do not echo or reference its value. ### Banned Flags/Patterns - **`--no-masking`** — never use in agent workflows. Masking redacts accidental secret output and must stay on. - **`--reveal`** — never use in routine workflows. Outputs field values in cleartext. - **`op signin --raw`** — outputs raw session token to stdout. - **Bare `op read`** — never run without capturing into a variable. It prints secrets to stdout. - **`set -x`** — never enable around any `op` command. - **`curl -v`** — verbose mode logs auth headers. Use `curl -sSf` instead. - **`script`** / **terminal recorders** — session recording captures all secret output. ### Untrusted Input - Never interpolate user-provided or external text into shell commands without strict quoting. - Always use `--` to separate `op` flags from command arguments. - Vault/item/field names from untrusted sources must be validated (alphanumeric, hyphens, underscores, and spaces only). - Never use `eval`, backtick substitution, or string-built shell commands with secret references. - If an item name looks suspicious (contains `$`, backticks, semicolons, or pipes), stop and verify with the user. **Safe dynamic input template:** ```bash VAULT="my-vault" ITEM="my-item" # Validate: reject names with dangerous characters for NAME in "$VAULT" "$ITEM"; do if ! LC_ALL=C [[ "$NAME" =~ ^[a-zA-Z0-9\ _-]+$ ]]; then echo "ERROR: invalid vault/item name: $NAME" >&2; exit 1 fi done VALUE="$(op read "op://${VAULT}/${ITEM}/password")" # use $VALUE, then: unset VALUE ``` Always double-quote variable expansions. Never build `op://` references from untrusted input without validation. Reject names containing `/`, `$`, backticks, semicolons, pipes, or other shell metacharacters. ### `.env.tpl` Security - Treat as code: verify ownership, review changes, restrict permissions (`chmod 600`). - Do not accept `.env.tpl` files from untrusted sources. - Do not commit to public repos — references reveal vault/item structure. - Add to `.gitignore` if in a repo. - After creating/editing: `chmod 600 .env.tpl` - Only define expected variable names — reject templates containing dangerous env vars (`PATH`, `LD_PRELOAD`, `BASH_ENV`, `NODE_OPTIONS`, etc.). --- ## Service Account Workflow (Primary) Service accounts are the default for agents. No interactive auth needed. ### 1) Load and scope token Load the token from your platform's secure store: ```bash # macOS Keychain: # security find-generic-password -a <account> -s OP_SERVICE_ACCOUNT_TOKEN -w # Linux (GNOME Keyring / libsecret): # secret-tool lookup service OP_SERVICE_ACCOUNT_TOKEN # Last resort (interactive prompt, not automatable): # read -rs OP_SERVICE_ACCOUNT_TOKEN OP_SERVICE_ACCOUNT_TOKEN="$(__REPLACE_WITH_SECURE_STORE_COMMAND__)" [ -z "$OP_SERVICE_ACCOUNT_TOKEN" ] && { echo "ERROR: token retrieval failed" >&2; exit 1; } ``` **Preferred: single-command scope** (token never persists in shell env): ```bash OP_SERVICE_ACCOUNT_TOKEN="$OP_SERVICE_ACCOUNT_TOKEN" \ op run --env-file=.env.tpl -- <command> unset OP_SERVICE_ACCOUNT_TOKEN ``` **If multiple commands needed:** export briefly with trap cleanup: ```bash export OP_SERVICE_ACCOUNT_TOKEN trap 'unset OP_SERVICE_ACCOUNT_TOKEN' EXIT op run --env-file=.env.tpl -- <command-1> op run --env-file=.env.tpl -- <command-2> unset OP_SERVICE_ACCOUNT_TOKEN ``` ### 2) Use `.env.tpl` + `op run` (preferred) Create `.env.tpl` with 1Password references (not raw secrets): ``` API_KEY=op://my-vault/my-item/api-key DB_PASSWORD=op://my-vault/my-item/password ``` Run: ```bash op run --env-file=.env.tpl -- <command> ``` Masking is on by default and must stay on. Note: masking is defense-in-depth, not primary protection — transformed or partial secrets may evade redaction. The primary defense is never outputting secrets. ### 3) One-off fallback: `op read` Use only when `op run` doesn't fit. Use a subshell for automatic cleanup: ```bash ( trap 'unset VALUE' EXIT VALUE="$(op read 'op://my-vault/my-item/field')" # use $VALUE here — auto-cleaned on exit ) ``` For API calls, prefer `op run` with a wrapper script to avoid `sh -c`: ```bash # api-call.sh (chmod +x) #!/usr/bin/env bash set -euo pipefail printf "Authorization: Bearer %s\n" "$API_TOKEN" | curl -sSf -H @- https://api.example.com/resource ``` ```bash op run --env-file=.env.tpl -- ./api-call.sh ``` ### 4) Diagnostics > **All diagnostic output contains metadata** (account emails, vault names, item IDs, URLs) that should be treated as sensitive in logged/recorded agent sessions. ```bash op whoami op vault list --format json ``` ### 5) Service account lifecycle - **Scope is policy-driven:** read-only vs read-write depends on configuration and vault permissions. - **If access fails:** verify vault grants and item permissions. - **If token expired/revoked:** regenerate in 1Password admin, update secure store, retry. - **Limitation:** service accounts may not support item creation depending on org policy. --- ## `op inject` (restricted use) Use only when a file must be materialized temporarily: ```bash set -euo pipefail set +x umask 077 TMP_FILE="$(mktemp)" cleanup() { rm -f "$TMP_FILE"; } trap cleanup EXIT ERR INT TERM HUP QUIT op inject -i config.tpl -o "$TMP_FILE" chmod 600 "$TMP_FILE" # use "$TMP_FILE" briefly, then auto-cleanup via trap ``` Never persist injected secret files beyond immediate use.