@maderatools/vault

Vault v2.5 - Professional secrets management system with GPG encryption and daemon architecture.

Features

• 🔓 UNLOCKED Secrets: Auto-loaded 24/7 for API access (Docker, services)
• 🔒 PROTECTED Secrets: Manual unlock required, 3h timeout (sudo, SSH, git)
• 🔐 GPG Encryption: AES256 symmetric encryption
• 🚀 Daemon Architecture: Unix socket IPC, background process
• 🌐 Master/Worker: Sync secrets across multiple servers
• 🛡️ Security First: Password-protected operations, no agent bypass

Installation

Global Installation (Recommended)

npm install -g @maderatools/vault

Update to Latest Version

npm update -g @maderatools/vault

Quick Start

1. Initial Setup

After installation, the package creates ~/.vault/ directory automatically.

Add to your ~/.bashrc:

# Vault v2.5 - Secrets management
[[ -f ~/.vault/vault-helpers.sh ]] && source ~/.vault/vault-helpers.sh

Then reload:

source ~/.bashrc

2. Create Vault File

Create ~/.vault/vault.gpg with your secrets:

vault edit

This opens your editor with a template:

[UNLOCKED]
# Secrets accessible 24/7 for API Docker
ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgresql://...
STRIPE_SECRET_KEY=sk_test_...

[PROTECTED]
# Secrets requiring DEV supervision (timeout 3h)
SUDO_PASSWORD=...
GITHUB_PAT=ghp_...
SSH_PASSPHRASE=...

3. Create Password File

echo "your-gpg-password" > ~/.vault/.vault-password
chmod 600 ~/.vault/.vault-password

4. Start Daemon

vault daemon start

Commands

Daemon Management

vault daemon start      # Start daemon + load UNLOCKED
vault daemon stop       # Stop daemon
vault daemon status     # Show status
vault daemon restart    # Restart daemon
vault daemon lock       # Lock PROTECTED secrets

Secrets Access

vault list                    # List all secret keys
vault show VARIABLE_NAME      # Show specific secret value
vault edit                    # Edit vault.gpg (requires GPG password)
vault-unlock                  # Unlock PROTECTED secrets (3h)

Wrapper Functions (in scripts)

vault_check VARIABLE          # Check if secret exists
vault_sudo command            # Run sudo with SUDO_PASSWORD
vault_ssh host cmd            # SSH with password
vault_api API_KEY_NAME        # Get API key value

Architecture

UNLOCKED vs PROTECTED

| Aspect | UNLOCKED | PROTECTED | |--------|----------|-----------| | Purpose | API keys, DB passwords | Admin operations | | Loading | Auto at daemon start | Manual unlock required | | Access | 24/7 via daemon | 3h timeout after unlock | | Examples | ANTHROPIC_API_KEY | SUDO_PASSWORD | | Docker API | ✅ Can access | ❌ Cannot access |

Master/Worker Model

• Master: Laptop, DEV server (can edit vault)
• Worker: PROD, STAGING, BACKUP (read-only, sync from master)

Security Model

• GPG symmetric encryption (AES256)
• --no-use-agent flag forces interactive password
• Claude Code CANNOT bypass GPG password prompts
• Secrets stored in memory (daemon) or encrypted file only

Workflow Examples

Daily Development (UNLOCKED)

# Daemon starts automatically at boot
vault daemon status
# → 36 UNLOCKED loaded, 0 PROTECTED

# Use secrets in scripts (no password needed)
curl -H "Authorization: Bearer $(vault_api ANTHROPIC_API_KEY)" https://api.anthropic.com

Admin Operations (PROTECTED)

# Unlock PROTECTED secrets
vault-unlock
# → Enter GPG password
# → Protected secrets unlocked for 3h

# Now use admin commands
vault_sudo systemctl restart nginx
vault_ssh prod-tunnel 'docker ps'

Editing Secrets

# On master (laptop/DEV)
vault edit
# → Enter GPG password
# → Edit in nano/vim
# → Auto-saves and restarts daemon

# On worker (PROD)
vault edit
# → ❌ READ-ONLY
# → Use: ssh dev-tunnel 'vault edit'

Configuration Files

~/.vault/daemon.conf

[daemon]
mode=master              # or worker
socket=/tmp/vault-daemon.sock

[vault]
file=/home/user/.vault/vault.gpg
password_file=/home/user/.vault/.vault-password

[unlock]
timeout=10800           # 3 hours
auto_lock=true
remind_before=300       # 5 minutes

[sync]
auto_sync=true
interval=60
timeout=5

Deployment Across Servers

After installing via npm on all servers:

# On each server
npm install -g @maderatools/vault

# Copy vault.gpg from master
scp dev-tunnel:~/.vault/vault.gpg ~/.vault/vault.gpg

# Start daemon
vault daemon start

Troubleshooting

Daemon won't start

# Check if socket already exists
rm /tmp/vault-daemon.sock
vault daemon start

GPG password prompt loop

# Ensure .vault-password exists and is readable
ls -lh ~/.vault/.vault-password
# Should be: -rw------- (600)

PROTECTED secrets not working

# Check if unlocked
vault daemon status
# Should show: PROTECTED secrets: 4 (unlocked, expires in 2h 30m)

# If locked, unlock again
vault-unlock

Version History

v2.5.0 (Current)

• UNLOCKED/PROTECTED architecture
• GPG --no-use-agent security fix
• vault list/show commands
• Unified vault.gpg file
• Master/worker sync model

v2.0.0 (Legacy)

• common.gpg + private.gpg structure
• Basic daemon functionality

License

MIT

Support

• GitHub Issues: https://github.com/maderatools/vault/issues
• Documentation: https://github.com/maderatools/vault/wiki

Made with ❤️ by Madera Tools