From 0a8813f3dd35fc523e7c7a0e0651aaf31a1cca65 Mon Sep 17 00:00:00 2001 From: Sam & Hermes Date: Fri, 29 May 2026 19:54:44 +0200 Subject: [PATCH 1/3] docs: vaultwarden bootstrap flow + verification test (Sam & Hermes) --- docs/VAULTWARDEN-SETUP.md | 51 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/docs/VAULTWARDEN-SETUP.md b/docs/VAULTWARDEN-SETUP.md index cee1dc1..3bbb70f 100644 --- a/docs/VAULTWARDEN-SETUP.md +++ b/docs/VAULTWARDEN-SETUP.md @@ -9,7 +9,56 @@ Agents use the `bw` CLI to retrieve secrets programmatically — no passwords in ## Prerequisites - Node.js (for npm install) or a pre-built `bw` binary -- Org API key from the operator (Samo or Hermes on debby) +- Org API key + master password from the operator (Samo) + +## Bootstrap Flow + +Vaultwarden has a circular bootstrap problem: an agent needs credentials to +access Vaultwarden, but those credentials can't be stored in Vaultwarden itself +as the only copy. + +**Operator's role:** +1. Generate an org API key in Vaultwarden (Organization → Settings → API Keys). +2. Store a reference copy in Vaultwarden's `agent-secrets` collection for + recovery, but keep the authoritative copy offline (password manager, encrypted + USB, printed safe — anything outside Vaultwarden itself). +3. When onboarding a new agent: hand them three values directly via a secure + channel (file drop, not chat): + - `BW_CLIENTID` — org API key client ID + - `BW_CLIENTSECRET` — org API key client secret + - `BW_PASSWORD` — Vaultwarden master password + +**Agent's role:** +1. Receive credentials, write them to a 0600 bootstrap file, use once. +2. Follow the Setup steps below to install `bw`, login, and unlock. +3. Shred the bootstrap file after the first successful `bw list items`. +4. Use `--passwordenv BW_PASSWORD` and `BW_SESSION` for all future access. + +**Why not self-serve:** a brand-new agent cannot pull the org API key from +Vaultwarden because it needs the org API key to unlock Vaultwarden. The operator +is the only out-of-band channel. + +## Verification Test + +After onboarding, verify with this smoke test — run from the agent host: + +```sh +# 1. Unlock and get session +export BW_CLIENTID="organization...." +export BW_CLIENTSECRET=*** login --apikey +bw unlock --passwordenv BW_PASSWORD +export BW_SESSION="..." + +# 2. List items in agent-secrets collection +bw list items --session "$BW_SESSION" --collectionid 94ba61b8-633c-454e-b749-f115617eeac3 + +# 3. Retrieve the hermes-debby Forgejo password +bw list items --session "$BW_SESSION" --search "hermes-debby" | jq '.[0].login.username' + +# Expected: "hermes-debby" +``` + +If the username resolves: Vaultwarden onboarding complete. Lock the vault (`bw lock`). ## Setup -- 2.45.3 From d3b0d73b7f9b024e1eed31681c2a3998659750a5 Mon Sep 17 00:00:00 2001 From: Operator & Codex Date: Fri, 29 May 2026 21:16:06 +0200 Subject: [PATCH 2/3] docs: tighten Vaultwarden bootstrap verification (Sam & Codex) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Validation: docs-only; git diff --check. --- Build: pass | Tests: FAIL — 1 failed --- docs/VAULTWARDEN-SETUP.md | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/VAULTWARDEN-SETUP.md b/docs/VAULTWARDEN-SETUP.md index 3bbb70f..293504e 100644 --- a/docs/VAULTWARDEN-SETUP.md +++ b/docs/VAULTWARDEN-SETUP.md @@ -29,10 +29,11 @@ as the only copy. - `BW_PASSWORD` — Vaultwarden master password **Agent's role:** -1. Receive credentials, write them to a 0600 bootstrap file, use once. +1. Receive credentials in a 0600 bootstrap file such as `~/.config/vault-bootstrap.env`. 2. Follow the Setup steps below to install `bw`, login, and unlock. -3. Shred the bootstrap file after the first successful `bw list items`. -4. Use `--passwordenv BW_PASSWORD` and `BW_SESSION` for all future access. +3. Run the verification test before claiming Vaultwarden access works. +4. Keep or remove the bootstrap file according to operator policy. If kept, it must stay mode 0600 and must never be committed, pasted, or logged. +5. Use `--passwordenv BW_PASSWORD` and `BW_SESSION` for all future access. **Why not self-serve:** a brand-new agent cannot pull the org API key from Vaultwarden because it needs the org API key to unlock Vaultwarden. The operator @@ -43,19 +44,24 @@ is the only out-of-band channel. After onboarding, verify with this smoke test — run from the agent host: ```sh -# 1. Unlock and get session -export BW_CLIENTID="organization...." -export BW_CLIENTSECRET=*** login --apikey -bw unlock --passwordenv BW_PASSWORD -export BW_SESSION="..." +# 1. Load bootstrap env without echoing secrets. +set -a +. ~/.config/vault-bootstrap.env +set +a -# 2. List items in agent-secrets collection -bw list items --session "$BW_SESSION" --collectionid 94ba61b8-633c-454e-b749-f115617eeac3 +# 2. Configure, login, unlock, and capture a raw session token. +bw config server https://vault.smilepowered.org +bw login --apikey +BW_SESSION="$(bw unlock --raw --passwordenv BW_PASSWORD)" +export BW_SESSION -# 3. Retrieve the hermes-debby Forgejo password -bw list items --session "$BW_SESSION" --search "hermes-debby" | jq '.[0].login.username' +# 3. List items in agent-secrets collection. +bw list items --session "$BW_SESSION" --collectionid 94ba61b8-633c-454e-b749-f115617eeac3 >/dev/null -# Expected: "hermes-debby" +# 4. Retrieve the hermes-debby Forgejo username. +bw list items --session "$BW_SESSION" --search "hermes-debby" | jq -r '.[0].login.username' + +# Expected output: hermes-debby ``` If the username resolves: Vaultwarden onboarding complete. Lock the vault (`bw lock`). @@ -133,6 +139,7 @@ bw lock ## Rules - Never store `BW_CLIENTSECRET` or `BW_PASSWORD` in git, chat logs, or AGENTS.md. +- If a client secret is pasted into an insecure channel, rotate that org API key. - Use `--passwordenv BW_PASSWORD` — the env var is safer than passing on command line. - Lock the vault (`bw lock`) after each session. Sessions auto-expire. - If you need a new secret stored, ask the operator to add it via `bw create item`. -- 2.45.3 From baa0ccb76560eb29e238e3166e2c7a32bea878c5 Mon Sep 17 00:00:00 2001 From: Sam & Hermes Date: Sat, 30 May 2026 08:25:56 +0200 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20rewrite=20vaultwarden=20setup=20?= =?UTF-8?q?=E2=80=94=20personal=20API=20keys,=20not=20org=20(Opus=20caught?= =?UTF-8?q?=20this)=20(Sam=20&=20Hermes)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/VAULTWARDEN-SETUP.md | 56 ++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/docs/VAULTWARDEN-SETUP.md b/docs/VAULTWARDEN-SETUP.md index 293504e..75fca1c 100644 --- a/docs/VAULTWARDEN-SETUP.md +++ b/docs/VAULTWARDEN-SETUP.md @@ -6,10 +6,16 @@ Collection: `agent-secrets` (94ba61b8-633c-454e-b749-f115617eeac3). Agents use the `bw` CLI to retrieve secrets programmatically — no passwords in chat. +> **Note:** `bw` CLI only accepts **personal** API keys (from Account Settings). +> Organization API keys are for the REST API, not the CLI. Do not use them here. + ## Prerequisites - Node.js (for npm install) or a pre-built `bw` binary -- Org API key + master password from the operator (Samo) +- A Vaultwarden user account — the operator (Samo) creates it and invites you to + the Clawdie org with access to the `agent-secrets` collection +- Personal API key — you generate this from Account Settings → Security → Keys +- Master password from the operator for vault unlock ## Bootstrap Flow @@ -18,26 +24,23 @@ access Vaultwarden, but those credentials can't be stored in Vaultwarden itself as the only copy. **Operator's role:** -1. Generate an org API key in Vaultwarden (Organization → Settings → API Keys). -2. Store a reference copy in Vaultwarden's `agent-secrets` collection for - recovery, but keep the authoritative copy offline (password manager, encrypted - USB, printed safe — anything outside Vaultwarden itself). -3. When onboarding a new agent: hand them three values directly via a secure - channel (file drop, not chat): - - `BW_CLIENTID` — org API key client ID - - `BW_CLIENTSECRET` — org API key client secret - - `BW_PASSWORD` — Vaultwarden master password +1. Create a Vaultwarden user account for the agent. +2. Invite the user to the Clawdie organization with access to `agent-secrets`. +3. Share the master password via a secure channel (file drop, not chat). **Agent's role:** -1. Receive credentials in a 0600 bootstrap file such as `~/.config/vault-bootstrap.env`. -2. Follow the Setup steps below to install `bw`, login, and unlock. -3. Run the verification test before claiming Vaultwarden access works. -4. Keep or remove the bootstrap file according to operator policy. If kept, it must stay mode 0600 and must never be committed, pasted, or logged. -5. Use `--passwordenv BW_PASSWORD` and `BW_SESSION` for all future access. +1. Generate personal API key: Account Settings → Security → Keys → View API Key. +2. Write `BW_CLIENTID` (starts with `user.`), `BW_CLIENTSECRET`, and + `BW_PASSWORD` to a 0600 bootstrap file: `~/.config/vault-bootstrap.env`. +3. Follow the Setup steps below to install `bw`, login, and unlock. +4. Run the verification test before claiming Vaultwarden access works. +5. Keep or remove the bootstrap file according to operator policy. If kept, it + must stay mode 0600 and must never be committed, pasted, or logged. +6. Use `--passwordenv BW_PASSWORD` and `BW_SESSION` for all future access. -**Why not self-serve:** a brand-new agent cannot pull the org API key from -Vaultwarden because it needs the org API key to unlock Vaultwarden. The operator -is the only out-of-band channel. +**Why not self-serve:** a brand-new agent cannot pull credentials from Vaultwarden +because it needs a personal API key + master password to unlock Vaultwarden. The +operator must create the user account and deliver the master password out-of-band. ## Verification Test @@ -81,15 +84,14 @@ npm install -g @bitwarden/cli bw config server https://vault.smilepowered.org ``` -### 3. Get API key from operator +### 3. Get API key -Ask Samo or Hermes to generate an org API key scoped to the `agent-secrets` collection. +Generate your personal API key: Account Settings → Security → Keys → View API Key. You'll receive: -- `BW_CLIENTID` (starts with `organization.`) +- `BW_CLIENTID` (starts with `user.`) - `BW_CLIENTSECRET` -The operator also provides the master password for unlocking. This is shared -across the org — handle it like any other secret. +The operator provides the master password (`BW_PASSWORD`). ### 4. Login and unlock @@ -100,7 +102,7 @@ bw login --apikey # Every session: unlock bw unlock --passwordenv BW_PASSWORD -# → copy the BW_SESSION value from output +# → capture BW_SESSION from output export BW_SESSION="..." ``` @@ -108,7 +110,7 @@ export BW_SESSION="..." Alternative for scripting (no prompts): ```sh -export BW_CLIENTID="organization...." +export BW_CLIENTID="user...." export BW_CLIENTSECRET="..." bw login --apikey # uses env vars if set @@ -139,7 +141,7 @@ bw lock ## Rules - Never store `BW_CLIENTSECRET` or `BW_PASSWORD` in git, chat logs, or AGENTS.md. -- If a client secret is pasted into an insecure channel, rotate that org API key. -- Use `--passwordenv BW_PASSWORD` — the env var is safer than passing on command line. +- If a client secret is exposed, rotate your personal API key immediately. +- Use `--passwordenv BW_PASSWORD` — the env var is safer than on the command line. - Lock the vault (`bw lock`) after each session. Sessions auto-expire. - If you need a new secret stored, ask the operator to add it via `bw create item`. -- 2.45.3