50c-vault

Local-first credential manager for developers. MCP-native. Zero npm dependencies.

Your secrets never leave your machine.


Install

``bash
npm install -g 50c-vault
`

Commands available: vault and 50c-vault (both work)

Quick Start

`bash

Initialize vault (first time)

vault init
> Create master passphrase: **
> Confirm: **
> Vault initialized at %APPDATA%/50c-vault/

Add credentials

vault add whm/server1 "root:mytoken"
vault add aws/prod "AKIAIOSFODNN7EXAMPLE"
vault add cf/main "my-cloudflare-api-token"

Use credentials

vault get whm/server1
> Vault locked. Enter passphrase: **
> root:mytoken

Subsequent requests (within session)

vault get aws/prod # No prompt - already unlocked
> AKIAIOSFODNN7EXAMPLE
`

---

Security Implementation

$3

Library: Node.js crypto module (built-in)
Algorithm: AES-256-GCM (authenticated encryption)
Key Derivation: PBKDF2-SHA256, 100,000 iterations
IV Generation: Random 16 bytes per operation (crypto.randomBytes(16))
Salt: Random 32 bytes, stored in master.key.enc header

$3

1. User passphrase → PBKDF2(passphrase, salt, 100k iterations) → 32-byte master key
2. Master key encrypts AES-256 data encryption key (DEK)
3. DEK encrypts credential values
4. Session: Master key held in memory, cleared on lock

$3

`
master.key.enc (encrypted master key file):
[32 bytes: random salt]
[16 bytes: IV for this encryption]
[48 bytes: encrypted DEK + GCM auth tag]

credentials.json (encrypted JSON storage):
{
"aws/prod": {
"value": "base64_encrypted_credential",
"iv": "base64_iv_16_bytes",
"authTag": "base64_auth_tag_16_bytes"
}
}

Note: Each credential encrypted separately with unique IV.
Future versions will migrate to SQLite for better performance.
`

$3

Protects Against:
- ✅ Disk theft (credentials encrypted at rest)
- ✅ File access by other users (file permissions)
- ✅ Brute force (100k PBKDF2 iterations = slow)
- ✅ Tampering (GCM auth tags detect modifications)

Does NOT Protect Against:
- ❌ Memory dumps while vault unlocked (master key in RAM)
- ❌ Keylogger capturing passphrase during unlock
- ❌ Malware running as your user (local-first assumption)
- ❌ Physical access while vault unlocked

Use Case: Developer credentials on trusted dev machine. NOT for high-security environments.

---

Modes

$3

Prompts for passphrase on:
- First access of session
- After idle timeout (30 min default)
- After system sleep/wake
- After explicit vault lock

`bash
vault get aws/prod
> Vault locked. Enter passphrase: **
> AKIAIOSFODNN7EXAMPLE

10 min later

vault get cf/main # No prompt
> my-cloudflare-api-token

45 min idle...

vault get aws/prod
> Session expired. Enter passphrase: **
`

$3

⚠️ FOR DEV/CI ONLY. NOT PRODUCTION.

Vault stays unlocked until reboot or explicit lock.

`bash

Enable YOLO

vault yolo
> WARNING: Vault will stay unlocked until reboot or 'vault lock'
> Enter passphrase to confirm: **
> YOLO mode enabled. Stay dangerous.

Now everything works without prompts

vault get anything # No prompt, ever
50c-whm whm_list... # No prompt
50c-cf cf_list... # No prompt

Disable when needed

vault lock
> Vault locked. YOLO mode disabled.
`

#### YOLO Security Model

How it works:
1. vault yolo unlocks vault with passphrase
2. Master key written to ~/.vault-session (chmod 600)
3. File encrypted with machine-specific identifier (MAC address hash)
4. Session persists until: reboot, explicit vault lock, or 24h max

Security Guarantees:
- ✅ Other users can't read it (file permissions 600)
- ✅ Machine-specific (can't copy to another machine)
- ✅ Auto-expires after 24h

Security Risks:
- ⚠️ Processes running as YOU can read ~/.vault-session
- ❌ Docker containers with volume mounts can access it
- ❌ No defense against local malware
- ❌ No defense against memory dumps
- ❌ WSL can access Windows user files

Safe Use Cases:
- ✅ Local dev machine (trusted environment)
- ✅ CI/CD ephemeral runners (destroyed after use)
- ✅ Automation scripts on trusted servers

NEVER Use For:
- ❌ Production servers
- ❌ Shared machines
- ❌ Containers with host mounts
- ❌ Any untrusted environment

$3

For CI/CD where you can't prompt:

`bash
VAULT_PASSPHRASE=xxx vault get aws/prod

Or

vault unlock --passphrase-env VAULT_PASSPHRASE
`

Tools

| Tool | Description |
|------|-------------|
| vault_init | Create new vault with master passphrase |
| vault_unlock | Unlock vault for session |
| vault_lock | Lock vault immediately |
| vault_yolo | Enable YOLO mode (stay unlocked) |
| vault_status | Check lock status, session TTL, mode |
| vault_add | Add or update credential |
| vault_get | Retrieve credential |
| vault_list | List all credential IDs |
| vault_delete | Remove credential |
| vault_config | View/change settings |
| vault_export | Export encrypted backup |
| vault_import | Import from backup |
| vault_rotate | Change master passphrase |

Namespaces

Organize credentials by service:

`bash
vault add aws/prod-key "AKIA..."
vault add aws/dev-key "AKIA..."
vault add whm/server1 "root:token"
vault add whm/server2 "root:token"
vault add cf/main "token"
vault add docker/ghcr "ghp_xxx"
vault add ssh/deploy "-----BEGIN..."
vault add custom/anything "whatever"

vault list
> aws/prod-key
> aws/dev-key
> whm/server1
> whm/server2
> cf/main
> docker/ghcr
> ssh/deploy
> custom/anything

vault list aws
> aws/prod-key
> aws/dev-key
`

Integration with 50c Packs

50c packs automatically check vault:

`bash

Instead of setting env vars:

WHM_TOKEN=xxx 50c-whm ...

Just add to vault once:

vault add whm/default "root:mytoken"

Now 50c-whm works automatically

50c-whm whm_list_accounts # Uses vault credential
`

$3

1. Environment variable (explicit override)
2. Vault credential (if unlocked)
3. Prompt user (if neither)

Configuration

`bash
vault config
> {
> "session_ttl": 3600, # Max session: 1 hour
> "idle_timeout": 1800, # Idle lock: 30 minutes
> "lock_on_sleep": true, # Lock when laptop sleeps
> "yolo_mode": false # YOLO disabled by default
> }

vault config --idle-timeout 900 # 15 min idle
vault config --session-ttl 7200 # 2 hour sessions
vault config --lock-on-sleep false # Don't lock on sleep
`

Storage Location

| OS | Path |
|----|------|
| Windows | %APPDATA%\50c-vault\ |
| macOS | ~/Library/Application Support/50c-vault/ |
| Linux | ~/.local/share/50c-vault/ |

`
50c-vault/
├── vault.db # SQLite, encrypted credentials
├── master.key.enc # Encrypted master key
├── session.json # Active session (temp)
└── config.json # Settings
`

Security

- Encryption: AES-256-GCM
- Key Derivation: PBKDF2 with 100,000 iterations
- Storage: SQLite with encrypted values
- Session: Strict file permissions, auto-expire
- Network: Zero. Nothing ever leaves your machine.

---

MCP Integration (AI Agents)

$3

Config file location:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Add to config:
`json
{
"mcpServers": {
"vault": {
"command": "50c-vault",
"args": ["--mcp"],
"env": {
"VAULT_AUTO_UNLOCK": "false"
}
}
}
}
`

$3

vault_get(key: string)
- Get credential value
- Returns: credential string or error
- Example: vault_get("aws/prod") → "AKIAIOSFODNN7EXAMPLE"

vault_add(key: string, value: string)
- Add or update credential
- Returns: success confirmation
- Example: vault_add("github/token", "ghp_...")

vault_list(prefix?: string)
- List credential keys (not values!)
- Returns: array of key names
- Example: vault_list("aws") → ["aws/prod", "aws/dev"]

vault_delete(key: string)
- Delete credential
- Returns: success confirmation
- Example: vault_delete("old/key")

$3

1. First MCP tool call triggers passphrase prompt
2. Session persists for MCP server lifetime
3. Auto-locks when Claude exits or MCP server stops
4. Use YOLO mode for passwordless (dev only!)

$3

User: "Get my AWS credentials for production"

Claude calls: vault_get("aws/prod")
Vault prompts: "Enter passphrase:"
Vault returns: "AKIAIOSFODNN7EXAMPLE"
Claude: "Your AWS access key is AKIA..."

$3

For automation without prompts:

`bash

Before starting Claude/agent

vault yolo

Now MCP calls work without passphrase

Claude can access vault automatically

`

Security: Same YOLO risks apply (see YOLO Security Model above)

---

Why 50c-vault?

$3

| Feature | 50c-vault | 1Password CLI | HashiCorp Vault | pass | Keychain/Credential Manager |
|---------|-----------|---------------|-----------------|------|------------------------------|
| Local-first | ✅ Always | ❌ Cloud required | ⚠️ Optional | ✅ Always | ✅ Always |
| MCP Native | ✅ Built-in | ❌ None | ❌ None | ❌ None | ❌ None |
| Zero npm deps | ✅ Yes | ❌ Many deps | ❌ Many deps | ⚠️ Requires GPG | ✅ OS native |
| Cross-platform | ✅ Win/Mac/Linux | ✅ All | ✅ All | ⚠️ Unix only | ❌ OS-specific |
| YOLO mode | ✅ Built-in | ❌ No | ❌ No | ❌ No | ❌ No |
| Free | ✅ Free | ❌ $8/mo | ✅ OSS | ✅ Free | ✅ Free |
| Team sharing | ❌ No | ✅ Yes | ✅ Yes | ⚠️ Via git | ⚠️ Via AD |
| HA/Clustering | ❌ No | ✅ Cloud | ✅ Yes | ❌ No | ❌ No |
| Audit logs | ❌ No | ✅ Yes | ✅ Yes | ❌ No | ⚠️ Limited |

$3

- ✅ You want MCP integration for AI agents (Claude, Cursor, etc.)
- ✅ You need YOLO mode for CI/CD automation
- ✅ You want minimal dependencies (only keytar for OS auth)
- ✅ You're already using 50c.ai tools
- ✅ You prefer local-first (no cloud, no vendor lock-in)

$3

- 🔄 Team sharing needed → Use 1Password Teams or HashiCorp Vault
- 🔄 High availability needed → Use HashiCorp Vault (clustering)
- 🔄 Unix-only environment → Use pass (gpg-based)
- 🔄 OS integration needed → Use Keychain (macOS) or Credential Manager (Windows)
- 🔄 Enterprise compliance → Use 1Password or Vault (audit logs, RBAC)

---

License & Source

License: MIT
Package: https://www.npmjs.com/package/50c-vault
Source: Available for enterprise licensing - contact https://50c.ai

Cost: $0 (no SaaS, no API calls, no cloud storage)

Why Free?
- Local-first = no hosting costs for us
- Developer tool = community building
- Upsell: Premium features at 50c.ai (not vault itself)

Support: Contact https://50c.ai for assistance

Dependencies:
- keytar@7.9.0 (MIT license) - For Windows Hello/Touch ID support
- Built-in modules: crypto, fs, os`

Note: Passphrase mode uses zero npm dependencies. OS authentication mode requires keytar for platform credential managers (Windows Credential Manager, macOS Keychain, Linux libsecret).

Code Size: < 1000 lines. Audit the entire codebase in 30 minutes.

---

Local-first. Your secrets never leave your machine.