🔐 Credential Vault

Encrypted credential storage for OpenClaw agents. Stop storing API keys in plaintext.

Overview

Credential Vault provides AES-256-GCM encrypted local storage for API keys, tokens, and other secrets. Instead of scattering credentials across .env files, centralize them in an encrypted vault with audit logging and expiry tracking.

Features

• AES-256-GCM encryption with PBKDF2 key derivation (600,000 iterations)
• CRUD operations for credentials
• Tag-based organization (by skill, project, etc.)
• Environment variable injection for easy integration
• Expiry tracking with notifications
• Audit logging (who accessed what, when)
• Session-based unlocking (no password re-entry)

Installation

cd ~/ubik-collective/systems/ubik-pm/skills/credential-vault
uv sync

Quick Start

# Initialize vault (one-time setup)
uv run vault init

# Unlock vault
uv run vault unlock

# Add credentials
uv run vault add OPENAI_API_KEY "sk-..." --tag openai
uv run vault add TAVILY_API_KEY "tvly-..." --tag tavily --expires 2026-12-31

# List credentials
uv run vault list

# Get a credential
uv run vault get OPENAI_API_KEY

# Export for a skill
eval $(uv run vault env --tag tavily)

# Lock when done
uv run vault lock

Security Model

Encryption

• Master password → PBKDF2-SHA256 (600,000 iterations) → 256-bit key
• Each secret encrypted with AES-256-GCM (unique nonce per entry)
• Authentication tags verify integrity
• Master password never stored (only verification hash)

Storage

• Vault: ~/.openclaw/vault/vault.enc.json (encrypted)
• Audit log: ~/.openclaw/vault/audit.log (plaintext, no values)
• Session key: ~/.openclaw/vault/session (temporary, cleared on lock)

Permissions

• Vault file: 0600 (owner read/write only)
• Session key: deleted on vault lock

Threat Model

Protects against:

• ✅ Accidental credential leaks (git commits, logs)
• ✅ Casual file browsing
• ✅ Malware reading .env files

Does NOT protect against:

• ❌ Keyloggers (can capture master password)
• ❌ Root-level system compromise
• ❌ Memory dumps while vault is unlocked

Usage Examples

See EXAMPLE.md for detailed usage patterns.

Commands

vault init

Initialize a new vault with a master password.

vault unlock

Unlock the vault for the current session.

vault lock

Lock the vault and clear session key.

vault status

Show vault status (locked/unlocked, credential count).

vault add KEY_NAME [VALUE] [--tag TAG] [--expires DATE]

Add or update a credential. If VALUE is omitted, prompts securely.

vault get KEY_NAME

Retrieve and decrypt a credential.

vault list [--tag TAG]

List all credentials (values masked). Optionally filter by tag.

vault remove KEY_NAME [-y]

Remove a credential. Prompts for confirmation unless -y is passed.

vault env [--tag TAG]

Export credentials as KEY=VALUE for environment injection.

Example:

eval $(uv run vault env --tag openai)
echo $OPENAI_API_KEY  # Now available

vault audit [--last N]

View recent audit log entries.

vault expiring [--days N]

Check for credentials expiring within N days (default: 7).

vault rotate KEY_NAME [NEW_VALUE]

Replace a credential with a new value (preserves tags/metadata).

Integration with Skills

Pattern: Inject credentials before running a skill

# Tavily search skill
eval $(uv run vault env --tag tavily)
uv run scripts/search.py "OpenClaw release date"

Pattern: Skill checks vault directly

from lib.store import Store

store = Store()
# Assumes vault is unlocked by user beforehand
api_key = store.get("TAVILY_API_KEY")

Pattern: Auto-unlock in HEARTBEAT.md

# HEARTBEAT.md
Check if vault is locked. If so, prompt user to unlock before running daily checks.

Best Practices

1. Use tags consistently — Tag credentials by skill name for easy filtering
2. Set expiry dates — Track when API keys need rotation
3. Lock when idle — Run vault lock when not actively using credentials
4. One vault per machine — Don't sync the vault file across machines
5. Rotate regularly — Use vault expiring to track upcoming expirations
6. Review audit logs — Check vault audit periodically

Limitations

• Local only — No network sync (by design)
• Single-user — No multi-user access control
• No backup — User responsible for backing up ~/.openclaw/vault/
• Session key on disk — vault unlock stores decryption key until vault lock

Troubleshooting

"Vault is locked"

Run uv run vault unlock and enter your master password.

"Incorrect master password"

Double-check your password. If forgotten, you'll need to reinitialize (losing all credentials).

"Vault not initialized"

Run uv run vault init to create a new vault.

Session key persists after reboot

Session file is cleared on vault lock, but not automatically on reboot. Run vault lock explicitly.

Development

Run tests

uv run pytest

Add a test

See tests/test_roundtrip.py for examples.

License

MIT-0 (public domain equivalent)