Skip to content

BM-3003: refactor(ops-skills): migrate credentials to Bitwarden CLI#2006

Open
jonastheis wants to merge 3 commits into
mainfrom
refactor/ops-skills-bw-credentials
Open

BM-3003: refactor(ops-skills): migrate credentials to Bitwarden CLI#2006
jonastheis wants to merge 3 commits into
mainfrom
refactor/ops-skills-bw-credentials

Conversation

@jonastheis
Copy link
Copy Markdown
Contributor

@jonastheis jonastheis commented May 20, 2026

Summary

Replace the gitignored network_secrets.toml with the Bitwarden CLI as the single source of truth for credentials used by the ops-query umbrella skill and its four sub-skills (ops-indexer-query, ops-telemetry-query, ops-logs-query, ops-pipelines).

Why:

  • No plaintext secrets on disk.
  • Rotations propagate automatically (next bw sync picks up the new value).
  • A leaked laptop = one revoked Bitwarden session, not 18 keys to rotate everywhere.
  • Per-credential access control and audit already exist in Bitwarden — we get sharing for free via a shared organization/collection.

Changes

New files (under .claude/skills/ops-query/references/)

  • bw-credentials.sh — sourced bash helpers: bw_ensure_ready, bw_load_aws, bw_load_indexer, bw_load_redshift_url. All lookups go through bw_get_by_name (exact-name match via bw list items --search + jq), working around bw's fuzzy bw get item matching where e.g. prod_base also matches prod_base_sepolia.
  • bw-credentials.md — install (npm-pinned to 2026.2.0), per-shell unlock, bootstrap (one-time team seed + shared vault), troubleshooting, and a Known Issues section flagging the v2026.3.0/4.1 regression that breaks non-interactive bw use (bitwarden/clients#20703).
  • bw-migrate-from-toml.sh — idempotent one-shot migration. Reads network_secrets.toml, creates 17 items (8 indexer + 6 telemetry + 3 AWS). The 18th item boundless-ops-aws-ops is added to the shared collection separately by an admin from runbook credentials.

SKILL.md updates — each credential-loading step collapses to the same pattern:

```bash
source .claude/skills/ops-query/references/bw-credentials.sh
bw_ensure_ready || exit 1
bw_load_aws prod # or bw_load_indexer prod_base, bw_load_redshift_url prod_base, etc.
```

Plaintext TOML fallback paths are removed entirely — the skills fail loud with install/unlock instructions if bw is missing or locked.

Bitwarden item schema (18 items)

Group Count Name pattern Fields
AWS 4 boundless-ops-aws-<prod|staging|dev|ops> username = access key id, password = secret
Indexer 8 boundless-ops-indexer-<env> password = API key (+ chain, environment text fields)
Telemetry 6 boundless-ops-telemetry-<env> username = readonly, password, + db_url / chain / environment

Rollout

  1. One team member runs bash .claude/skills/ops-query/references/bw-migrate-from-toml.sh against their local TOML and moves the resulting items into the shared Boundless Ops collection (or equivalent).
  2. Admin adds boundless-ops-aws-ops to the same collection.
  3. Everyone else just needs collection access — bw sync makes the items appear locally.

Out of scope

ops-check-balances still references network_secrets.toml for QuikNode private RPC keys ([networks.<chain>.rpc]). Those blocks don't exist in the current TOML; tracked as a follow-up.

Test plan

  • bw_load_aws prod && aws sts get-caller-identity returns the prod account
  • bw_load_aws ops && aws codepipeline list-pipelines works
  • bw_load_indexer prod_base && curl -H "x-api-key: $INDEXER_API_KEY" "$MARKET_INDEXER_URL/v1/market/requests?limit=1" returns data
  • bw_load_redshift_url prod_base && psql "$REDSHIFT_URL" -c 'SELECT 1' returns one row
  • With vault locked, bw_ensure_ready exits non-zero and prints the unlock instructions
  • Run one pre-built investigation (e.g. market-summary on prod_base) end-to-end with no network_secrets.toml reads

Replace the gitignored `network_secrets.toml` with the Bitwarden CLI as
the single source of truth for credentials used by the ops-query umbrella
skill and its four sub-skills (`ops-indexer-query`, `ops-telemetry-query`,
`ops-logs-query`, `ops-pipelines`).

- New shared helpers under `.claude/skills/ops-query/references/`:
  - `bw-credentials.sh` — sourced bash helpers (`bw_ensure_ready`,
    `bw_load_aws`, `bw_load_indexer`, `bw_load_redshift_url`). All lookups
    go through `bw_get_by_name` which does an exact-name match via
    `bw list items --search` + jq, working around bw's fuzzy `bw get item`
    matching (`prod_base` would otherwise also match `prod_base_sepolia`).
  - `bw-credentials.md` — setup, bootstrap, troubleshooting, and a
    Known Issues section flagging the v2026.3.0/4.1 regression that breaks
    non-interactive use (bitwarden/clients#20703), with the v2026.2.0
    npm pin workaround.
  - `bw-migrate-from-toml.sh` — idempotent one-shot migration that reads
    `network_secrets.toml` and creates 17 derivable items. The 18th
    (`boundless-ops-aws-ops`) is seeded directly into the shared vault by
    an admin.

- Each SKILL.md credential step collapses to the same pattern:
    source .claude/skills/ops-query/references/bw-credentials.sh
    bw_ensure_ready || exit 1
    bw_load_aws prod        # or bw_load_indexer prod_base, etc.

  Plaintext TOML fallback paths are removed entirely; the skills fail
  loud with install/unlock instructions if `bw` is missing or locked.

Out of scope: `ops-check-balances` still references `network_secrets.toml`
for QuikNode RPC keys (`[networks.<chain>.rpc]`); tracked as a follow-up.
@github-actions github-actions Bot changed the title refactor(ops-skills): migrate credentials to Bitwarden CLI BM-3003: refactor(ops-skills): migrate credentials to Bitwarden CLI May 20, 2026
@linear
Copy link
Copy Markdown

linear Bot commented May 20, 2026

BM-3003

- bw_ensure_ready now probes `bw status` instead of `bw list`. The list
  probe exited 0 on a locked vault (interactive prompt fails after stdin
  is closed, but bw still returns success), so the helper falsely reported
  ready and downstream loaders surfaced the lock as "missing item".
- Rename local `status` -> `vault_state`; zsh reserves `status` as a
  read-only alias for $?, so sourcing the helper from zsh blew up.
- Fix install hint to `npm install -g @bitwarden/cli@2026.2.0`; the
  Homebrew package ships the broken 2026.3.x/2026.4.x releases that the
  docs already tell users to avoid.
- Drop the no-restart "paste !export BW_SESSION=... into the prompt"
  recovery path. Claude Code's Bash tool spawns a fresh subprocess per
  call, so an export from the prompt's shell isn't visible to subsequent
  tool calls. BW_SESSION must be exported in the parent shell before
  `claude` launches.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants