# 🔐 Credential Vault MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0-green)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3%2B-blue)](https://www.typescriptlang.org/)
[![Security: Libsodium](https://img.shields.io/badge/Security-Libsodium-red)](https://doc.libsodium.org/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)

**Secure credential storage for AI agents.** Keep your passwords, API keys, and secrets encrypted and invisible to AI models. When agents need credentials, they get a secure reference—never the actual value.

## Why Credential Vault?

AI agents are incredibly powerful, but they shouldn't have access to your sensitive credentials. Credential Vault solves this with a **security-first architecture**:

- 🔒 **End-to-End Encryption**: ChaCha20-Poly1305 encryption with Argon2i key derivation
- 👻 **Agent-Invisible**: Agents see only credential IDs, never actual values
- 🛡️ **Zero Trust**: Credentials stored separately from AI context
- 📊 **Full Audit Trail**: Track every credential access and modification
- 🔄 **Conflict Detection**: Automatically detect credential changes and duplicates
- 🎯 **Easy Setup**: One-command initialization, MCP integration ready

## Security Architecture

```
┌─────────────────────────────────────────┐
│  AI Agent / Claude                       │
│  (Cannot see credential values)          │
└────────────┬────────────────────────────┘
             │
             │ Requests: "Get stripe_api_key"
             │ Receives: {credential_id: "cred_xxx", name: "stripe_api_key"}
             │
┌────────────▼────────────────────────────┐
│  MCP Tool Interface                      │
│  • store_credential                      │
│  • get_credential_reference              │
│  • list_credentials                      │
└────────────┬────────────────────────────┘
             │
┌────────────▼────────────────────────────┐
│  Credential Storage (Encrypted)          │
│  ~/.credential-vault-mcp/vault.json      │
│                                          │
│  ChaCha20-Poly1305 Encryption           │
│  Argon2i Key Derivation                 │
│  600 File Permissions (User Only)       │
└──────────────────────────────────────────┘
```

## Quick Start

### 1. Installation

```bash
npm install -g credential-vault-mcp
```

### 2. Initialize Vault

```bash
credential-vault init
```

You'll be prompted to set a master password. This password:
- Never leaves your machine
- Is never sent to any server
- Is used to derive an encryption key (not stored directly)
- Must be at least 8 characters

### 3. Add Your First Credential

```bash
credential-vault add stripe_api_key --type api_key
```

### 4. Configure MCP in Claude Code / Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "credential-vault": {
      "command": "credential-vault-mcp",
      "args": []
    }
  }
}
```

Or for development:

```json
{
  "mcpServers": {
    "credential-vault": {
      "command": "npx",
      "args": ["credential-vault-mcp"]
    }
  }
}
```

### 5. Use in Claude

Tell Claude:
> I have credentials stored in Credential Vault MCP. Can you initialize the vault with my master password, then retrieve my stripe_api_key?

Claude will:
1. Call `initialize_vault` tool with your master password
2. Call `get_credential_reference` to get credential ID
3. Never see the actual API key value

## CLI Commands

### List all credentials
```bash
credential-vault list
```

### Get a credential value
```bash
credential-vault get stripe_api_key
```

### Delete a credential
```bash
credential-vault delete stripe_api_key
```

### View audit log
```bash
credential-vault audit 100
```

### Verify vault integrity
```bash
credential-vault verify
```

## Available MCP Tools

### `initialize_vault`
Initialize the vault with master password. **Call this first.**

```json
{
  "master_password": "your-secure-password-8+chars"
}
```

### `store_credential`
Store a new credential (encrypted).

```json
{
  "name": "stripe_api_key",
  "value": "sk_live_...",
  "type": "api_key"
}
```

Types: `api_key`, `password`, `token`, `connection_string`, `ssh_key`, `custom`

### `get_credential_reference`
Get a credential reference (safe for agents).

```json
{
  "credential_name": "stripe_api_key"
}
```

Returns: `{ credential_id: "cred_xxx", name: "...", type: "..." }`

### `list_credentials`
List all stored credentials (no values).

### `delete_credential`
Permanently delete a credential.

### `get_audit_log`
View access and modification history.

## Security Best Practices

### ✅ DO

- ✅ Use a **strong, unique master password** (20+ characters recommended)
- ✅ Store your master password in a password manager
- ✅ Review audit logs regularly
- ✅ Rotate sensitive credentials periodically
- ✅ Run `credential-vault verify` to check vault integrity
- ✅ Keep your system and dependencies updated

### ❌ DON'T

- ❌ Share your master password
- ❌ Store master password in plaintext
- ❌ Use the same master password as other services
- ❌ Store credentials in public/shared environments without encryption
- ❌ Ignore audit log warnings about conflicts
- ❌ Commit `.credential-vault-mcp/` to version control

## File Structure

```
~/.credential-vault-mcp/
├── vault.json           # Encrypted credential storage (mode: 600)
└── [secure directory]   # Stored in user home, readable only by user
```

**Permissions**: Vault directory and file are created with `0700` / `0600` permissions (user read/write only).

## Encryption Details

- **Algorithm**: ChaCha20-Poly1305 (AEAD)
- **Key Derivation**: Argon2i (OPSLIMIT_MODERATE, MEMLIMIT_MODERATE)
- **Nonce**: Random 24-byte nonce per credential
- **Integrity**: Poly1305 MAC prevents tampering
- **Library**: libsodium.js (audited crypto library)

Each credential is encrypted independently with a random nonce. Even if one credential is compromised, others remain secure.

## Advanced Usage

### Using with different Claude interfaces

#### Claude.ai Code
Add to MCP settings in Code interface

#### Claude Desktop App
Edit `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "credential-vault": {
      "command": "npx",
      "args": ["credential-vault-mcp"]
    }
  }
}
```

#### VS Code Extension
Configure in extension settings for Claude extension

### Backing up credentials

**Important**: Your master password is required to decrypt credentials.

```bash
# Backup encrypted vault (safe - encrypted)
cp ~/.credential-vault-mcp/vault.json ~/backup/vault.json.backup

# Never do this:
# ❌ cp ~/.credential-vault-mcp/vault.json /public/location
# ❌ git add vault.json
```

### Handling master password changes

Currently: Delete old vault and create new one
```bash
rm ~/.credential-vault-mcp/vault.json
credential-vault init
```

Then re-add credentials with new master password.

## Troubleshooting

### "Vault not initialized" error
```bash
# Initialize first
credential-vault init
```

### "Permission denied" error
Check file permissions:
```bash
ls -la ~/.credential-vault-mcp/vault.json
# Should show: -rw------- (600)
```

Fix permissions:
```bash
chmod 600 ~/.credential-vault-mcp/vault.json
```

### Forgotten master password?
Unfortunately, there's no recovery. The password is required to decrypt credentials.

**Prevention**: Store master password in a password manager with recovery codes.

### "Conflict detected" warning
This means a credential with the same value exists under a different name. This could indicate:
- Password reuse (audit the old credential)
- Accidental duplicate entry
- Shared secret across services

Check audit log:
```bash
credential-vault audit
```

## Development

### Clone & Install

```bash
git clone https://github.com/CipherSatoru/credential-vault-mcp.git
cd credential-vault-mcp
npm install
```

### Build

```bash
npm run build
```

### Run in development

```bash
npm run dev
```

### Test CLI

```bash
npm run cli -- init
```

## Contributing

Contributions welcome! This is security-sensitive software, so:

1. **Security first**: Test all encryption paths
2. **No plaintext logging**: Credentials must never be logged
3. **Audit trail**: Track what happens
4. **Documentation**: Update SECURITY.md for significant changes

## License

MIT License - See LICENSE file for details

## Support

- 📖 [Read SECURITY.md](./SECURITY.md) for security details
- 🐛 [Report issues](https://github.com/CipherSatoru/credential-vault-mcp/issues)
- 💬 [Discussions](https://github.com/CipherSatoru/credential-vault-mcp/discussions)

## Disclaimer

This tool encrypts credentials locally on your machine. However:
- The MCP interface is only as secure as its integration
- Running on a compromised machine still exposes credentials
- Master password security is your responsibility
- No encryption is perfect - use defense in depth

Always follow your organization's security policies when handling credentials.

---

**Made with 🔒 for secure AI agent workflows**