50c-vault

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

Your secrets never leave your machine.

Install

npm install -g 50c-vault

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

Quick Start

# 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

Encryption Details

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

Key Flow

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

File Structure

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.

Threat Model

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

Normal Mode (Default)

Prompts for passphrase on:

• First access of session
• After idle timeout (30 min default)
• After system sleep/wake
• After explicit vault lock

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: ********

YOLO Mode (Automation)

⚠️ FOR DEV/CI ONLY. NOT PRODUCTION.

Vault stays unlocked until reboot or explicit lock.

# 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

Environment Variable Override

For CI/CD where you can't prompt:

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:

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:

# 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

Credential Lookup Order

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

Configuration

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)

Setup for Claude Desktop

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:

{
  "mcpServers": {
    "vault": {
      "command": "50c-vault",
      "args": ["--mcp"],
      "env": {
        "VAULT_AUTO_UNLOCK": "false"
      }
    }
  }
}

MCP Tools Exposed

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")

Authentication Flow

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!)

Example Usage in Claude

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..."

MCP with YOLO Mode (CI/CD)

For automation without prompts:

# 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?

Comparison to Alternatives

| 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 |

Use 50c-vault if:

• ✅ 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)

Use alternatives if:

• 🔄 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:

• [email protected] (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.