# VaultBridge

> Secret management for AI coding agents. Your secrets never enter the LLM context window.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![CI](https://github.com/Code-for-100k/vaultbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/Code-for-100k/vaultbridge/actions/workflows/ci.yml)

---

## The Problem

- **29 million secrets** were leaked on GitHub in 2025 ([GitGuardian State of Secrets Sprawl](https://www.gitguardian.com/state-of-secrets-sprawl-report-2025)), up 25% year-over-year
- **AI-assisted commits leak secrets at 2x the baseline rate** — autocomplete and agent workflows bypass the muscle memory that keeps developers from pasting keys into code
- **24,000+ secrets found in MCP config files** — the new `claude_desktop_config.json` is the new `.env` committed to git
- **Every secret in the LLM context window is sent to the AI provider's servers** — even if the model never prints it, it was transmitted and processed

VaultBridge is an MCP server that gives AI agents access to your secrets *without ever exposing the values*. The agent sees metadata (names, services, env var mappings). The actual values flow through a side channel directly to their targets.

## How It Works

```
┌─── Your Machine ────────────────────────────────────────────┐
│                                                              │
│   Claude Code / Cursor / Windsurf / AI Agent                 │
│       │                                                      │
│       │ MCP Protocol (tool calls)                            │
│       ▼                                                      │
│   ┌─────────────────────────────────────────────────┐        │
│   │  VaultBridge MCP Server                         │        │
│   │  ● Returns metadata only (names, IDs, mappings) │        │
│   │  ● Secret values NEVER in tool responses        │        │
│   └────────┬───────────────────────────┬────────────┘        │
│            │                           │                     │
│     MCP Tools                    Hook API (:9847)            │
│     (search, inject,             (capture, redact,           │
│      manifest, status)            check-value, redeem)       │
│            │                           │                     │
│            ▼                           ▼                     │
│   ┌─────────────────────────────────────────────────┐        │
│   │  Bitwarden CLI (bw / rbw)                       │        │
│   └────────────────────┬────────────────────────────┘        │
│                        │                                     │
│                        ▼                                     │
│   ┌─────────────────────────────────────────────────┐        │
│   │  Vaultwarden / Bitwarden Cloud (encrypted)      │        │
│   └─────────────────────────────────────────────────┘        │
│                                                              │
│   Hooks: auto-capture · redact · leak-prevent                │
└──────────────────────────────────────────────────────────────┘
```

**Data flow:** The agent calls `vault_search` and gets back names and IDs. When it needs a value, it calls `vault_inject` which writes directly to a `.env` file, clipboard, or template — the value never appears in the tool response. Hooks intercept secrets in shell output and file writes before they reach the LLM.

## Quick Start

### Prerequisites

- **Runtime:** [Bun](https://bun.sh) 1.0+ or Node.js 18+
- **Vault CLI:** [Bitwarden CLI](https://bitwarden.com/help/cli/) (`bw`) or [rbw](https://github.com/doy/rbw)
- **Vault backend:** [Vaultwarden](https://github.com/dani-garcia/vaultwarden) (self-hosted) or Bitwarden cloud account

### 1. Install

Add to your Claude Code MCP config (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "vaultbridge": {
      "command": "bun",
      "args": ["run", "/path/to/vaultbridge-mcp-server/src/index.ts"],
      "env": {
        "BW_SESSION": "<your-bitwarden-session-key>",
        "BW_URL": "https://vault.example.com"
      }
    }
  }
}
```

### 2. Unlock your vault

```bash
# Bitwarden CLI
export BW_SESSION=$(bw unlock --raw)

# Or rbw
rbw unlock
```

### 3. Verify

Ask your agent: *"Check vault status"* — it will call `vault_status` and confirm the connection.

## MCP Tools

| Tool | Description | Returns Values? |
|------|-------------|:---------------:|
| `vault_search` | Search secrets by name, service, project, environment | Never |
| `vault_store` | Store a new secret (generated passwords only via tool) | Never |
| `vault_inject` | Inject a secret into .env, clipboard, or template file | Never |
| `vault_resolve_env` | Populate .env from .env.example using vault lookups | Never |
| `vault_manifest` | Read project secret manifest (.vault-manifest.json) | Never |
| `vault_status` | Check vault connection and lock state | N/A |

## Claude Code Hooks

VaultBridge ships with three hooks that form a defense-in-depth layer:

| Hook | Trigger | What It Does |
|------|---------|--------------|
| `post-bash` | `PostToolUse` / `Bash` | Scans shell output for secrets (pattern + entropy detection), auto-captures to vault, redacts from context |
| `pre-write` | `PreToolUse` / `Write\|Edit` | Blocks file writes containing detected secrets; suggests `vault_inject` instead |
| `session-start` | `SessionStart` | Loads project manifest, pre-warms vault connection, registers env var mappings |

Hook configuration in `.claude/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "curl -s http://127.0.0.1:9847/api/check-value -d '{\"value\":\"$TOOL_OUTPUT\"}' | jq -r '.should_block'"
        }]
      }
    ]
  }
}
```

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `VAULTBRIDGE_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
| `VAULTBRIDGE_PORT` | `9847` | Port for Hook API (and HTTP transport) |
| `VAULTBRIDGE_AUTH_TOKEN` | (generated) | Bearer token for HTTP endpoints |
| `VAULTBRIDGE_BACKEND` | `bw` | Vault CLI backend: `bw` or `rbw` |
| `BW_SESSION` | — | Bitwarden session key (required for `bw`) |
| `BW_URL` | — | Vaultwarden/Bitwarden server URL |

See [docs/configuration.md](docs/configuration.md) for the complete reference.

## Security Model

### What's protected

- Secret **values** never appear in MCP tool responses — the LLM cannot see them
- The Hook API runs on `127.0.0.1` only in stdio mode — no network exposure
- One-time redeem tokens expire in 10 seconds and are single-use
- Clipboard injection auto-clears after a configurable TTL (default 30s)

### What's visible to the agent

- Secret **metadata**: names, IDs, service labels, project/environment tags, env var mappings
- Vault connection status (locked/unlocked, server URL, email)
- Injection confirmations (target type, file path — never the value)

### Defense layers

1. **MCP layer** — Tools return metadata only; `vault_inject` writes to targets via side channel
2. **Hook layer** — `post-bash` scans output for secrets before the LLM sees it; `pre-write` blocks file writes containing secrets
3. **Vault layer** — All secrets encrypted at rest in Vaultwarden/Bitwarden; accessed via CLI with session authentication
4. **Transport layer** — HTTP mode requires Bearer token auth; stdio mode binds to localhost only

## Comparison

### vs Indie/Open-Source Projects

| Feature | VaultBridge | [AgentSecrets](https://github.com/The-17/agentsecrets) | [agent-secrets](https://github.com/joelhooks/agent-secrets) | [phantom-secrets](https://github.com/ashlrai/phantom-secrets) | [claude-secrets](https://github.com/henghonglee/claude-secrets) |
|---------|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
| Values never reach LLM | **Yes** | **Yes** | No (leases expose) | **Yes** | Partial |
| Auto-capture from output | **Yes** | No | No | No | **Yes** |
| Leak prevention (block writes) | **Yes** | No | No | No | No |
| Uses existing password manager | **Yes** (Bitwarden) | No (own store) | No (age files) | No (OS keychain) | No (Fernet vault) |
| MCP server | **Yes** | **Yes** | No | **Yes** | No |
| Claude Code hooks | **Yes** | No | No | No | Partial |
| Team/workspace support | No | **Yes** | No | No | No |
| Session leases / TTL | No | No | **Yes** | No | **Yes** |

### vs Enterprise Products

| Feature | VaultBridge | 1Password Unified | GitHub Secret Scanning | Bitwarden MCP |
|---------|:-----------:|:------------------:|:----------------------:|:-------------:|
| Auto-capture from shell output | **Yes** | No | No | No |
| Pre-LLM redaction (hooks) | **Yes** | No | No | No |
| Leak prevention on file write | **Yes** | No | Post-commit only | No |
| Metadata-only responses | **Yes** | No (returns values) | N/A | No (returns values) |
| Open source | **Yes** | No | Partial | Yes |
| Self-hostable vault | **Yes** | No | N/A | Yes |
| MCP native | **Yes** | No | No | Yes |

**VaultBridge's niche:** The only tool that combines Bitwarden integration + auto-capture + pre-LLM redaction + leak prevention in one system. AgentSecrets is the closest competitor but uses its own encrypted store and takes a network proxy approach instead of hooks.

## Development

```bash
# Clone
git clone https://github.com/Code-for-100k/vaultbridge.git
cd vaultbridge

# Install dependencies
bun install

# Type check
bun run typecheck

# Run in stdio mode (local dev)
bun run start

# Run in HTTP mode
bun run start:http

# Build
bun run build
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.

## Architecture

VaultBridge operates as a 4-layer system:

1. **Agent Layer** — Claude Code / Cursor makes MCP tool calls
2. **MCP Server Layer** — Processes requests, enforces metadata-only responses
3. **Hook Layer** — Intercepts secrets in shell output and file writes
4. **Vault Layer** — Bitwarden CLI talks to encrypted storage

See [docs/architecture.md](docs/architecture.md) for detailed diagrams and data flow documentation.

## License

[MIT](LICENSE) - Copyright 2026 Code-for-100k Contributors