Skip to content

Commit ce7ead9

Browse files
kobzevvvclaude
kobzevvv
and
claude
committed
Initial release: MCP server for credential isolation in LLM agents
- Encrypted store (AES-256-GCM, per-credential IV, scrypt key derivation) - 4 MCP tools: vault_login, vault_api_request, vault_list, vault_status - Browser login via Chrome CDP (Playwright connectOverCDP) - CLI: add, list, remove, audit, dashboard, serve - Web dashboard on localhost:9900 (self-contained HTML) - Audit log with SHA-256 hash chain (tamper detection) - 29 tests including credential sanitization verification - CI: GitHub Actions (Node 20 + 22) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
0 parents  commit ce7ead9

26 files changed

+5447
-0
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
build-and-test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
node-version: [20, 22]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Setup Node.js ${{ matrix.node-version }}
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: ${{ matrix.node-version }}
23+
cache: npm
24+
25+
- name: Install dependencies
26+
run: npm ci
27+
28+
- name: Build
29+
run: npm run build
30+
31+
- name: Test
32+
run: npm test
33+
env:
34+
VAULT_MASTER_KEY: ci-test-key

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules/
2+
dist/
3+
*.js.map
4+
.DS_Store
5+
*.db
6+
*.jsonl
7+
.env

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 ChillAI
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Vault MCP
2+
3+
MCP server for credential isolation in LLM agents. Your bot uses passwords and API keys — but never sees them in its context window.
4+
5+
```
6+
Claude Code
7+
|
8+
vault_login("github")
9+
|
10+
Vault MCP Server
11+
/ \
12+
Encrypted Store Chrome CDP
13+
(AES-256-GCM) (fill form)
14+
|
15+
github.com ✓
16+
|
17+
→ { status: "success", page_title: "Dashboard" }
18+
(password never in LLM context)
19+
```
20+
21+
## Quickstart
22+
23+
```bash
24+
# 1. Clone and build
25+
git clone https://github.com/chillai-space/vault-mcp.git
26+
cd vault-mcp
27+
npm install
28+
npm run build
29+
30+
# 2. Add a credential
31+
node dist/index.js add --site github --email you@example.com --url https://github.com/login
32+
33+
# 3. Register with Claude Code
34+
claude mcp add -s user vault -- node ~/path/to/vault-mcp/dist/index.js
35+
36+
# 4. Use in Claude Code session
37+
# "Log me into GitHub" → Claude calls vault_login("github")
38+
# → Chrome fills the form, Claude gets { status: "success" }
39+
# → Password never appears in conversation
40+
```
41+
42+
## MCP Tools
43+
44+
| Tool | Description |
45+
|------|-------------|
46+
| `vault_login(site_id)` | Log into a website via Chrome CDP. Returns only status. |
47+
| `vault_api_request(service, url, ...)` | Make API request with stored credentials injected. |
48+
| `vault_list()` | List all credentials (no secrets shown). |
49+
| `vault_status(site_id)` | Check credential status, last used, audit count. |
50+
51+
## CLI Commands
52+
53+
```bash
54+
vault-mcp add # Interactive: add credential
55+
vault-mcp add --site X --email Y # Semi-interactive (password prompted)
56+
vault-mcp list # List credentials (no secrets)
57+
vault-mcp remove <site_id> # Remove credential
58+
vault-mcp audit [site_id] # View audit log
59+
vault-mcp dashboard # Web UI on localhost:9900
60+
vault-mcp serve # Start MCP server (stdio, for debugging)
61+
```
62+
63+
## Configuration
64+
65+
| Env Variable | Default | Description |
66+
|-------------|---------|-------------|
67+
| `VAULT_MASTER_KEY` | (auto-generated) | Master encryption key. If not set, a random key is generated at `~/.vault-mcp/.master-key` |
68+
| `VAULT_CDP_URL` | `http://localhost:9222` | Chrome DevTools Protocol endpoint |
69+
70+
### Claude Code registration with env vars
71+
72+
```bash
73+
claude mcp add -s user vault \
74+
-e VAULT_MASTER_KEY=my-secret-key \
75+
-e VAULT_CDP_URL=ws://localhost:9222 \
76+
-- node ~/path/to/vault-mcp/dist/index.js
77+
```
78+
79+
## Storage
80+
81+
All data is stored in `~/.vault-mcp/`:
82+
83+
| File | Description |
84+
|------|-------------|
85+
| `credentials.json` | Encrypted credentials (AES-256-GCM) |
86+
| `audit.jsonl` | Append-only audit log with SHA-256 hash chain |
87+
| `.master-key` | Auto-generated master key (if no env var) |
88+
89+
## Testing
90+
91+
```bash
92+
npm test # Run all tests
93+
npm run test:watch # Watch mode
94+
```
95+
96+
### Manual verification
97+
98+
```bash
99+
# 1. Add credential and verify isolation
100+
vault-mcp add --site test --email test@test.com
101+
vault-mcp list # → password NOT shown
102+
103+
# 2. Test with MCP Inspector
104+
npx @modelcontextprotocol/inspector dist/index.js
105+
# → Call vault_list, vault_status — verify no secrets in responses
106+
107+
# 3. In Claude Code: vault_login → verify no password in conversation
108+
```
109+
110+
## Security
111+
112+
See [SECURITY.md](SECURITY.md) for threat model and encryption details.
113+
114+
## License
115+
116+
MIT

‎SECURITY.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Security
2+
3+
## Threat Model
4+
5+
### What Vault MCP protects against
6+
7+
- **LLM context leakage**: Credentials never appear in the LLM's context window, conversation history, or tool responses
8+
- **Accidental exposure**: Passwords are stored encrypted at rest, not in plaintext config files
9+
- **Audit trail tampering**: SHA-256 hash chain ensures any modification to the audit log is detectable
10+
- **Unauthorized use**: Credentials can be toggled active/inactive, and every use is logged
11+
12+
### What Vault MCP does NOT protect against
13+
14+
- **Compromised host machine**: If an attacker has root access, they can read memory, intercept CDP, or extract the master key
15+
- **Malicious MCP client**: A compromised Claude Code instance could call `vault_login` for any stored credential
16+
- **Browser-level attacks**: Vault fills forms via CDP — the credentials exist briefly in Chrome's memory
17+
- **Network MITM**: Vault doesn't control the TLS connection to target sites
18+
19+
## Encryption Details
20+
21+
| Property | Value |
22+
|----------|-------|
23+
| Algorithm | AES-256-GCM |
24+
| Key derivation | scrypt (from `VAULT_MASTER_KEY` env var) |
25+
| IV | 16 bytes, random per credential |
26+
| Auth tag | 16 bytes (GCM integrity) |
27+
| Storage format | `base64(IV + ciphertext + authTag)` |
28+
29+
Each credential is encrypted independently with a unique random IV. Modifying any byte of the ciphertext will cause decryption to fail (GCM authenticated encryption).
30+
31+
## Audit Log Integrity
32+
33+
The audit log (`~/.vault-mcp/audit.jsonl`) uses a SHA-256 hash chain:
34+
35+
```
36+
Entry 1: hash = SHA-256("genesis" + JSON(entry))
37+
Entry 2: hash = SHA-256(entry1.hash + JSON(entry))
38+
Entry N: hash = SHA-256(entryN-1.hash + JSON(entry))
39+
```
40+
41+
Modifying or deleting any entry breaks the chain. Verify integrity:
42+
43+
```bash
44+
vault-mcp audit # Shows chain status at the bottom
45+
```
46+
47+
## Responsible Disclosure
48+
49+
If you find a security vulnerability, please report it via GitHub Issues with the `security` label, or email the maintainers directly. We will respond within 48 hours.
50+
51+
Please do **not** open public issues for active exploits.

0 commit comments

Comments
 (0)