vaultwarden-secrets
Open source under the MIT licence. View the source
A TypeScript/Bun library plus a small set of services that put a secret-manager control plane in front of a self-hosted Vaultwarden instance.
The problem
A homelab or single-operator setup gets GCP Secret Manager-style semantics (immutable versions, aliases, rotation) and least-privilege access for the workloads and agents that consume secrets, without multi-tenant bloat.
How it works
At the core is a caching library that reads items through the bw CLI and encrypts them at rest. On top are optional services: a REST API, an MCP server for AI agents, a credential proxy, a SQLite control plane (versions, aliases, audit ledger, outbox), a crash-safe rotation engine, a default-deny authorization engine and opaque vwsk_ workload-identity tokens. Services run as a non-root user under hardened systemd units.
Features
- Encrypted LRU cache and encrypted snapshot fallback when the vault is locked
- Immutable secret versions, atomic alias moves, hash-chained audit ledger
- Rotation engine that never revokes the old credential until the new one verifies
- Default-deny authz, enumeration-parity 404s, folder scoping per client
- Four security profiles from feeling-lucky (dev only) to trust-no-one (mTLS + JWT)
- Encrypted off-host backups with a monthly restore drill
How it was built
The project started on 2026-02-04 to give scripts and AI agents only the credentials they are allowed to see, instead of copying secrets into env files or handing an agent a full password-manager session.
The July 2026 rebuild ran from a written decision log. Encrypted values stayed in the vault, and a separate non-secret store took ids, versions, policy and audit state.
The running service was never broken during the rebuild. A compatibility baseline pinned the live tool list and response shapes, and a new server was added on a new port until it passed its gates.
Rotation became a state machine with checkpoints that resumes after a crash and revokes the old credential only after the new one verifies. Audit logs record shapes and byte counts, never values.
Claude models wrote the code as pair programmers, and each slice faced an adversarial review before merge; the rotation engine alone had 8 P0 findings fixed. Rico set the scope and the hard gate before anything went live.