lockbox-vault

Lockbox

Encrypted API key vault with MCP integration for AI coding tools.

Lockbox stores your API keys in an AES-256-GCM encrypted vault on your machine. Access them from the CLI, pipe them into scripts, or let AI coding agents (Claude Code, Cursor, Windsurf) retrieve secrets through the Model Context Protocol — without ever putting real keys in your codebase.

Quick Start

npm install -g lockbox-vault

lockbox init                        # create your encrypted vault
lockbox add openai API_KEY sk-...   # store a secret
lockbox get openai API_KEY          # retrieve it

Installation

npm install -g lockbox-vault

Requires Node.js 18+.

CLI Commands

Vault Lifecycle

lockbox init                # create a new encrypted vault
lockbox unlock              # unlock with your master password (15-min session)
lockbox lock                # lock the vault immediately
lockbox status              # show vault info, lock state, key count
lockbox doctor              # run health checks on the vault

Secret Management

lockbox add openai API_KEY sk-abc123              # store a secret
lockbox add stripe SECRET --project myapp         # organize by project
lockbox add aws ACCESS_KEY                        # prompts for value (hidden)
lockbox get openai API_KEY                        # print to stdout
lockbox get openai API_KEY --copy                 # copy to clipboard (clears in 30s)
lockbox remove openai API_KEY                     # delete (with confirmation)
lockbox list                                      # show all keys (never values)
lockbox list --project myapp                      # filter by project
lockbox search stripe                             # search by name, service, or notes

Import & Export

lockbox import .env                               # import from .env file
lockbox import creds.json --project myapp         # import from JSON
lockbox export > .env                             # export as .env format
lockbox export --format json                      # export as JSON
lockbox export --format shell >> ~/.bashrc        # export as shell exports

Proxy Key System

The proxy key system lets you commit .env files to git without exposing real secrets. Instead of actual values, your env file contains lockbox:// references that are resolved at runtime.

# generate a .env.proxy file (safe to commit)
lockbox proxy-init --project myapp

# the generated file looks like:
# OPENAI_API_KEY=lockbox://openai/API_KEY
# STRIPE_SECRET_KEY=lockbox://stripe/SECRET_KEY

# run your app with real values injected
lockbox run --env-file .env.proxy "npm start"
lockbox run --env-file .env.proxy "python app.py"

Non-proxy values (like DATABASE_URL=postgresql://localhost/mydb) are passed through unchanged.

Audit & Security

lockbox audit                                     # show last 50 audit entries
lockbox audit --since 2025-01-01                  # filter by date
lockbox audit -n 10                               # limit entries

MCP Setup

Lockbox exposes your vault to AI coding agents via the Model Context Protocol. The MCP server provides 6 tools: store_secret, get_secret, list_secrets, delete_secret, export_env, and list_projects.

Prerequisites: Unlock your vault before using MCP tools:

lockbox unlock

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "lockbox": {
      "command": "npx",
      "args": ["lockbox-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "lockbox": {
      "command": "npx",
      "args": ["lockbox-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "lockbox": {
      "command": "npx",
      "args": ["lockbox-mcp"]
    }
  }
}

Security Model

Layer	Implementation
Encryption	AES-256-GCM with 12-byte random IV (fresh on every save)
Key Derivation	Argon2id (64 MB memory, 3 iterations, 4 threads)
Integrity	HMAC-SHA256 verified before decryption attempt
Session	Derived key encrypted to temp file, auto-expires after 15 minutes
Rate Limiting	5 failed unlock attempts per 60s triggers 60s lockout
Audit Trail	Append-only log of all operations (values never logged)
Clipboard	Auto-clears after 30 seconds when using --copy
Memory	Derived key zeroed on lock; secrets only in memory while unlocked

Vault File Format

The vault is a single encrypted JSON file at ~/.config/lockbox/vault.enc:

{ salt, iv, tag, ciphertext, hmac }  (all base64-encoded)

The decrypted payload contains versioned key entries with per-key metadata (project, notes, timestamps, expiry).

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

git clone https://github.com/Waldo777-bh/lockbox.git
cd lockbox
npm install
npm run build
npm test

License

MIT