Vault integration

Trove KB never stores passwords. Credentials live in your own vault; Trove KB stores references and brokers access.

Why this approach

• Bitwarden vault data is end-to-end encrypted. No server-side API returns plaintext items.
• The Bitwarden Public API only manages org structure (members, groups, collections, events). No item contents. Teams/Enterprise only.
• The Vault Management API (bw serve, from the official Bitwarden CLI) runs locally, holds an unlocked vault, and exposes REST endpoints for items, folders, collections, and TOTP. It works against Bitwarden cloud, self-hosted Bitwarden, and Vaultwarden. This is the integration path.

Provider modes

Mode	Works with	What you get
link	Anything	A secret field stores a deep link to the item in the web vault. Zero trust required. Default.
bw_serve	Bitwarden cloud, self-hosted Bitwarden, Vaultwarden	Search and pick items, username and URI inline, reveal password and TOTP on click, create items from a document, map companies to collections
bitwarden_public_api (add-on)	Bitwarden Teams/Enterprise	Auto-create a collection per company, grant groups, pull vault event logs into the audit view
op_connect	1Password Business/Teams	A self-hosted Connect server on your own network. Search, reveal, TOTP, item creation. A company maps to 1Password vault ids
hashicorp_kv	HashiCorp Vault, KV v2	A company maps to a path prefix; each secret under it is an item. Read-only. Not yet verified against a live Vault

An MSP inherits whatever each client already uses, so a company may name its own provider; a company that names none uses the instance default. Collection mappings are stored per provider, so two vaults can map the same company without colliding.

bw_serve

browser -> Trove KB app -> (internal docker network only) -> bw-serve sidecar -> Bitwarden/Vaultwarden

• The sidecar runs the official @bitwarden/cli, logs in with a dedicated service account (API key), unlocks, and runs bw serve.
• bw serve has no authentication. It must never publish a port. Internal network only.
• Trove KB calls /sync on a schedule (default 5 min) and before item creation.

The service account is a dedicated Bitwarden or Vaultwarden user, a member of the MSP org, with access only to the client collections Trove KB should see. “Can view” unless item creation is enabled. Login via API key (BW_CLIENTID / BW_CLIENTSECRET); master password via a Docker secret file, ./secrets/bw_master_password.txt, chmod 600.

docker compose --profile vault up -d

1Password Connect

1. In 1Password (Business or Teams), go to Developer → Infrastructure Secrets Management → Other and set up a Connect server. Choose the vaults it may read. You get a 1password-credentials.json file and an access token.
2. Put the file at ./secrets/1password-credentials.json and chmod 600 it. Put the token in .env as OP_CONNECT_TOKEN, with OP_CONNECT_URL=http://op-connect-api:8080 and VAULT_MODE=op_connect.
3. docker compose --profile onepassword up -d. Connect runs on the internal network and never publishes a port.
4. Admin → Vault, add a provider with mode op_connect, then map each company to the 1Password vault id its secrets live in.

What a secret field stores

{ "provider_id": "uuid", "item_id": "bw-item-id", "collection_id": "bw-collection-id",
  "label": "Firewall admin", "username": "admin", "uri": "https://10.0.0.1" }

Label, username, and URI are cached non-secret metadata for display and search, refreshed on sync. Password, TOTP seed, and notes are never stored or cached. They are fetched live on reveal only.

Rules

• Reveal requires can_reveal_secrets. Every reveal and copy writes audit_log (secret.reveal, secret.copy_totp).
• Revealed values are returned with Cache-Control: no-store, never logged, never included in webhooks, revisions, exports, or search.
• API keys need an explicit secrets:reveal scope. Off by default.
• The item picker only searches collections mapped to the current company.
• If the sidecar is down or locked, secret fields degrade to link mode and show a warning.

Risk statement

In bw_serve mode, anyone who fully compromises the Trove KB host can read everything the service account can read. That is the same tradeoff Hudu and IT Glue make. Scope the service account tightly, keep the sidecar internal, and use link mode if that risk is unacceptable.

What is verified

The Bitwarden path and the 1Password Connect path are covered end to end against stand-in servers in the e2e suite: picking an item, storing a reference without the secret, revealing the password and a one-time code, and degrading to a link when the server stops answering. Neither has been run against a live account by the project. The HashiCorp KV provider is written against the documented API, compiles, and has no end-to-end test. Treat it as unproven.