npm package: @maderatools/vault
Description: Vault v3.2 - Secure secrets management with 2-file GPG architecture (UNLOCKED + PROTECTED)
Author: Madera Tools
Latest version: 3.2.1

# @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)

```bash
npm install -g @maderatools/vault
```

### Update to Latest Version

```bash
npm update -g @maderatools/vault
```

## Quick Start

### 1. Initial Setup

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

Add to your `~/.bashrc`:

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

Then reload:

```bash
source ~/.bashrc
```

### 2. Create Vault File

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

```bash
vault edit
```

This opens your editor with a template:

```ini
[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

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

### 4. Start Daemon

```bash
vault daemon start
```

## Commands

### Daemon Management

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

```bash
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)

```bash
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)

```bash
# 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)

```bash
# 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

```bash
# 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`

```ini
[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:

```bash
# 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

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

### GPG password prompt loop

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

### PROTECTED secrets not working

```bash
# 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**