Secrets with Bitwarden

All secrets live in Bitwarden and are resolved at runtime.

How It Works

  1. The bitwarden role runs first in the secrets phase.
  2. It resolves a session token in order: BW_SESSION env var → /tmp/bw_session → interactive bw unlock.
  3. It runs bw sync (with a 15 s hard timeout, so a flaky vault server can't hang the play) to refresh the local cached vault.
  4. It calls bw status and publishes a secrets_available host fact: true only if the CLI is installed, a session was resolved, and the vault actually unlocks.
  5. Every BW-using role gates on when: secrets_available | default(false). The end-of-play post_tasks summary prints one of:
    • vault unlocked — all secret roles executed normally
    • Bitwarden vault was LOCKED — … skipped. To enable: bw unlock …
    • SKIPPED (--skip-tags secrets). Run dots-apply to include …

Remote Apply

just apply-remote <host> (and just apply-remote-tags <host> <tags>):

  1. Runs scripts/bw-resolve.sh remote <host>, which unlocks Bitwarden on the remote and prints that host's session token. If the remote CLI is logged out it tries bw login --apikey with the bw-api-key item from your local vault; to unlock it pipes the master password (item James Bitwarden) over stdin, falling back to an interactive bw unlock over ssh -t.
  2. Runs ssh -t <host> "export BW_SESSION='…'; …; just apply" — the session is exported inline in the remote command, not via SendEnv. apply-remote also caches it in the remote's /tmp/bw_session.
  3. The bitwarden role on the remote runs bw status: if it reports unlocked, secrets_available becomes true and secrets work proceeds.

Caveat — session portability is not guaranteed. A BW_SESSION token is only valid on the machine that unlocked it — that's why the recipes unlock on the remote instead of forwarding yours. If the remote unlock fails, the remote bw status returns locked, the role prints a one-line warning, and every BW-touching task is skipped cleanly — nothing fails, no files get clobbered with empty values. Unlock the vault directly on that host (bw unlock, then write the session to /tmp/bw_session) to enable secrets there.

Vault Items

Every item a role or script reads (grep bw get / bw list under roles/ and scripts/):

Bitwarden ItemTypeUsed By
james@<machine>SSH Keyssh_keys role — per-machine ed25519 keys
tailscale-apikeyLogin (password)tailscale role — key for tailscale up --authkey and stale-device cleanup via the API
kubeconfigSecure Notekube role — home cluster kubeconfig
talosconfigSecure Notekube role — home cluster Talos config
kubeconfig-aws-migrationSecure Notekube role — retained kubeconfig for the terminated AWS cluster
talosconfig-aws-migrationSecure Notekube role — retained Talos config for the terminated AWS cluster
accounts.firefox.comLogin + TOTPbrowser_fxa role — Firefox Account credentials
github-tokenLogin (password)github role — PAT for gh auth login
atuin.shLogin + custom field keyshell_atuin role — atuin sync login + mnemonic
deepseek-api-keyLogin (password)shell_ai role — pi auth.json
forgejoSecure Note (API Token: line)shell_ai role — FORGEJO_TOKEN
tavily-api-keyLogin (password)shell_ai role — TAVILY_API_KEY
forgejo.manatee-basking.ts.netLoginforgejo_registry role — podman registry login
bw-api-keyLoginscripts/bw-resolve.sh — bw login --apikey on a remote
James BitwardenLoginscripts/bw-resolve.sh — non-interactive unlock on a remote

Recovery items (not read by any role)

These items are kept so that you can rebuild a lost host by hand. No role reads them.

Bitwarden ItemTypeHolds
hive-github-app-hanthor-hive-agentSecure NoteSchool's GitHub App: App ID, installation ID, PEM private key (the hub mounts the same key). See Hive
hive-github-app-tuna-reef-hiveSecure NoteReef's GitHub App: App ID, installation ID, PEM private key
hive-spindle-envSecure NoteThe hives' .env (hub secret, dashboard token, omp broker token, provider keys). It was /srv/hives/.env on spindle and is now /var/srv/hives/.env on bihar and karnataka. The item name has not changed

Running Without Secrets

For fast iteration that doesn't need the vault — packages, dotfiles, desktop config — use the explicit no-secrets path:

just apply-nosecrets   # git pull + apply with --skip-tags secrets
dots                   # alias: cd to the repo + just apply-nosecrets

The daily systemd timer (dotfiles-update.service) calls apply-nosecrets for the same reason: it can't unlock the vault non-interactively, so it doesn't try.

No Session?

If Bitwarden can't unlock (first run, no BW CLI installed, vault genuinely locked on this host), every secret-touching task is skipped automatically. Non-secret roles (system, packages, dotfiles, desktop, most services) run normally and the play exits successfully — the end-of-play summary tells you exactly which roles didn't get to do their BW work.

Seeding New Secrets

# Push kubeconfig + talosconfig (home cluster) to Bitwarden from a machine that has them:
just seed-kube

seed-kube only handles the two home-cluster notes; the *-aws-migration notes are maintained by hand.