# vault-broker-mcp

Kleine, zelf-gehoste MCP-server die Claude *scoped, indirecte* toegang geeft tot
credentials in Vaultwarden — zonder dat Claude ooit een plaintext wachtwoord
in zijn context krijgt.

## Waarom deze opzet

Claude mag geen wachtwoorden lezen en zelf in formulieren typen. Deze broker
lost dat op door **acties** aan te bieden in plaats van **waardes**:

- `list_credentials` → geeft alleen niet-geheime metadata terug (naam,
  gebruikersnaam, URL). Nooit het wachtwoord-veld.
- `login` → krijgt een credential-ID + doel-URL, haalt het wachtwoord
  *intern* op, vult het formulier zelf in (via Playwright) en geeft alleen
  `{success, url}` terug. Het secret verlaat de container nooit.

Zo blijft de scheiding hard: Claude kiest *welk* item gebruikt wordt, de
broker is de enige die de waarde ooit ziet.

## Vaultwarden-kant (handmatig, door Steno)

Dit deel kan Claude niet voor je doen (accounts aanmaken / wachtwoorden
instellen is voor Claude verboden terrein, ook met toestemming).

1. In de bestaande Vaultwarden-instance (container `app_a0d7b954_bitwarden`,
   poort 7277 op het `hassio`-netwerk — waarschijnlijk ontsloten via
   `secure.steno.nl`, even checken in NPM): maak een organisatie **of**
   hergebruik een bestaande, met een nieuwe collectie, bijv. `Gedeeld met Claude`.
2. Maak een aparte login aan voor de agent-identiteit, bijv.
   `steenhagen.jeroen+claude@gmail.com`, met een eigen sterk wachtwoord + 2FA.
3. Nodig die identiteit uit in de organisatie met toegang tot **alleen** de
   collectie `Gedeeld met Claude`.
4. Zet de items die je wilt delen in die collectie (kopiëren/delen, niet per
   se verplaatsen).
5. Maak voor die identiteit een **API key** aan (Account settings → Security →
   Keys) — dat is wat de broker gebruikt om in te loggen, niet het master
   password rechtstreeks.
6. Geef mij: de vault-URL, de organisatie-ID en de collectie-ID (allemaal
   niet-geheime waardes, te vinden in de URL/admin-UI). De echte secrets
   (API key, master password) zet je zelf in `.env` op de server — die stuur
   je niet naar mij door.

## Broker-kant (dit scaffold)

- `Dockerfile` — Node 20, installeert de Bitwarden CLI (`bw`).
- `server.js` — MCP-server (SSE), twee tools: `list_credentials`, `login`
  (login is nu een stub met TODO's, zie hieronder).
- `docker-compose.yml` — draait op het gedeelde `hassio`-netwerk, net als je
  andere self-hosted MCP-servers. **Niet** publiek via NPM ontsluiten — dit
  is een secrets-gateway, alleen intern/via Tailscale bereikbaar houden.

### Nog te doen voordat dit bruikbaar is

- [ ] `.env` invullen (zie `.env.example`) zodra stap 1–6 hierboven klaar zijn.
- [ ] `login`-tool afmaken: nu roept hij nog geen echte Playwright-instance
  aan. Meest voor de hand liggend: laten praten met je bestaande
  `playwright-mcp`-containers (`playwright-amazon-mcp`, `playwright-bol-mcp`)
  of een eigen headless Playwright-instance in dezelfde container.
- [ ] Testen met één laag-risico item voordat er meer gedeeld wordt.
- [ ] Pas als dit werkt: als Portainer-stack deployen (met jouw akkoord, dit
  raak ik niet zelf aan zonder te vragen).

## Bekende valkuil: bw CLI-versie vs. Vaultwarden-versie

`@bitwarden/cli@latest` (getest: 2026.7.0) crasht met een WASM-panic
("invalid type: JsValue(Object(...)), expected a string") bij `bw list items`
tegen onze Vaultwarden-instance (versie 2025.12.0, te checken via
`GET /api/config`, publiek/niet-geheim endpoint). Oorzaak: de nieuwste
officiële CLI verwacht een response-schema dat deze Vaultwarden-versie nog
niet levert.

**Fix**: CLI-versie dicht bij de serverversie pinnen — getest en werkend met
`@bitwarden/cli@2025.12.1`. Dockerfile en `test-list-credentials.sh` gebruiken
deze pin. Bij een Vaultwarden-upgrade: eerst opnieuw testen voordat je de
CLI-pin optrekt.

**Tweede addertje**: `bw config server` weigert te wijzigen zolang de CLI al
ingelogd is ("Logout required before server config update") — het lokale
`bw`-datadir (`~/.config/Bitwarden CLI` / `%APPDATA%\Bitwarden CLI`) onthoudt
de sessie ook tussen verschillende CLI-versies in. Altijd `bw logout`
(fouten negeren) vóór `bw config server` in scripts.

**Derde addertje**: `node:20-alpine` als base image laat de build wel
slagen, maar Playwright's Chromium draait niet betrouwbaar op musl
libc/Alpine, en `playwright install --with-deps` kent alleen `apt`, geen
`apk`. Ontdekt pas bij de eerste Portainer-deploy (lokaal getest zonder
Docker, dus dit verschil bleef onzichtbaar tot de echte build). Fix:
`mcr.microsoft.com/playwright:v1.48.0-jammy` als base image (zelfde familie
als `playwright-amazon-mcp`/`playwright-bol-mcp`), Chromium + OS-deps al
ingebakken.

## Beveiligingsnotities

- MCP SSE-endpoint verwacht het secret als **query-param** (`?key=...`), niet
  als pad-prefix — zie de bekende valkuil met `ah-mcp` (root-relatieve
  callback-paden breken anders).
- `list_credentials` filtert serverside altijd het `login.password`-veld
  eruit, ook als de Bitwarden CLI het teruggeeft — nooit vertrouwen op "de
  aanroeper vraagt er toch niet om".
- Container draait met een `.env`-bestand dat **niet** in git komt
  (`.gitignore` sluit 'm uit).