OpenClaw Credential Manager

MANDATORY security foundation for OpenClaw. Consolidate scattered API keys and credentials into a secure .env file with proper permissions. Includes GPG encryption for high-value secrets, credential rotation tracking, deep scanning, and backup hardening. Use when setting up OpenClaw, migrating credentials, auditing security, or enforcing the .env standard. This is not optional — centralized credential management is a core requirement for secure OpenClaw deployments.

# Credential Manager

**STATUS: MANDATORY SECURITY FOUNDATION**

Consolidate scattered API keys and credentials into a secure, centralized `.env` file.

## ⚠️ This Is Not Optional

Centralized `.env` credential management is a **core requirement** for OpenClaw security. If your credentials are scattered across multiple files, **stop and consolidate them now**.

**THE RULE:** All credentials MUST be in `~/.openclaw/.env` ONLY. No workspace, no skills, no scripts directories.

See:
- [CORE-PRINCIPLE.md](CORE-PRINCIPLE.md) - Why this is non-negotiable
- [CONSOLIDATION-RULE.md](CONSOLIDATION-RULE.md) - The single source principle

## The Foundation

**Every OpenClaw deployment MUST have:**
```
~/.openclaw/.env (mode 600)
```

This is your single source of truth for all credentials. No exceptions.

**Why?**
- Single location = easier to secure
- File mode 600 = only you can read
- Git-ignored = won't accidentally commit
- Validated format = catches errors
- Audit trail = know what changed

Scattered credentials = scattered attack surface. This skill fixes that.

## What This Skill Does

1. **Scans** for credentials in common locations (including deep scan for hardcoded secrets)
2. **Backs up** existing credential files (timestamped, mode 600)
3. **Consolidates** into `~/.openclaw/.env`
4. **Secures** with proper permissions (600 files, 700 directories)
5. **Validates** security, format, and entropy
6. **Encrypts** high-value secrets with GPG (wallet keys, private keys, mnemonics)
7. **Tracks** credential rotation schedules
8. **Enforces** best practices via fail-fast checks
9. **Cleans up** old files after migration

## Detection Parameters

The skill automatically detects credentials by scanning for:

**File Patterns:**
- `~/.config/*/credentials.json` — Service config directories
- `~/.config/*/*.credentials.json` — Nested credential files
- `~/.openclaw/*.json` — Credential files in OpenClaw root
- `~/.openclaw/*-credentials*` — Named credential files (e.g., farcaster-credentials.json)
- `~/.openclaw/workspace/memory/*-creds.json` — Memory credential files
- `~/.openclaw/workspace/memory/*credentials*.json` — Memory credential files
- `~/.openclaw/workspace/.env` — Workspace env files
- `~/.openclaw/workspace/*/.env` — Subdirectory env files
- `~/.openclaw/workspace/skills/*/.env` — Skill env files
- `~/.local/share/*/credentials.json` — Local share directories

**Sensitive Key Patterns:**
- API keys, access tokens, bearer tokens
- Secrets, passwords, passphrases
- OAuth consumer keys
- Private keys, signing keys, wallet keys
- Mnemonics and seed phrases

**Deep Scan (--deep flag):**
- Greps `.sh`, `.js`, `.py`, `.mjs`, `.ts` files for hardcoded secrets
- Detects high-entropy strings matching common key prefixes (`sk_`, `pk_`, `Bearer`, `0x` + 64 hex)
- Excludes `node_modules/`, `.git/`
- Reports file, line number, and key pattern matched

**Security Checks:**
- File permissions (must be `600` for files, `700` for directories)
- Backup permissions (must be `600` for backup files, `700` for backup dirs)
- Git-ignore protection
- Format validation (allows quoted values with spaces)
- Entropy analysis (flags suspiciously low-entropy secrets)
- Private key detection (flags `0x` + 64 hex char values)
- Mnemonic detection (flags 12/24 word values)
- Symlink detection (validates symlinked .env targets)

## Quick Start

### Full Migration (Recommended)

```bash
# Scan for credentials
./scripts/scan.py

# Deep scan (includes hardcoded secrets in scripts)
./scripts/scan.py --deep

# Review and consolidate
./scripts/consolidate.py

# Validate security
./scripts/validate.py

# Encrypt high-value secrets
./scripts/encrypt.py --keys MAIN_WALLET_PRIVATE_KEY,CUSTODY_PRIVATE_KEY

# Check rotation status
./scripts/rotation-check.py
```

### Individual Operations

```bash
# Scan only
./scripts/scan.py

# Consolidate specific service
./scripts/consolidate.py --service x

# Backup without removing
./scripts/consolidate.py --backup-only

# Clean up old files
./scripts/cleanup.py --confirm
```

## Common Credential Locations

The skill scans these locations:

```
~/.config/*/credentials.json
~/.openclaw/*.json
~/.openclaw/*-credentials*
~/.openclaw/workspace/memory/*-creds.json
~/.openclaw/workspace/memory/*credentials*.json
~/.openclaw/workspace/*/.env
~/.openclaw/workspace/skills/*/.env
~/.env (if exists, merges)
```

## Security Features

✅ **File permissions:** Sets `.env` to mode 600 (owner only)
✅ **Directory permissions:** Sets backup dirs to mode 700 (owner only)
✅ **Backup permissions:** Sets backup files to mode 600 (owner only)
✅ **Git protection:** Creates/updates `.gitignore`
✅ **Backups:** Timestamped backups before changes (secured)
✅ **Validation:** Checks format, permissions, entropy, and duplicates
✅ **Template:** Creates `.env.example` (safe to share)
✅ **GPG encryption:** Encrypts high-value secrets at rest
✅ **Rotation tracking:** Warns when credentials need rotation
✅ **Deep scan:** Detects hardcoded secrets in source files
✅ **Symlink-aware:** Validates symlinked .env targets

## Output Structure

After migration:

```
~/.openclaw/
├── .env                     # All credentials (secure, mode 600)
├── .env.secrets.gpg         # GPG-encrypted high-value keys (mode 600)
├── .env.meta                # Rotation metadata (mode 600)
├── .env.example             # Template (safe to share)
├── .gitignore               # Protects .env and .env.secrets.gpg
└── backups/                 # (mode 700)
    └── credentials-old-YYYYMMDD/  # (mode 700)
        └── *.bak            # Backup files (mode 600)
```

## GPG Encryption for High-Value Secrets

Private keys, wallet keys, and mnemonics should **never** exist as plaintext on disk. Use GPG encryption for these.

### Setup GPG

```bash
# First-time setup (generates OpenClaw GPG key, configures agent cache)
./scripts/setup-gpg.sh
```

### Encrypt High-Value Keys

```bash
# Encrypt specific keys (moves them from .env to .env.secrets.gpg)
./scripts/encrypt.py --keys MAIN_WALLET_PRIVATE_KEY,CUSTODY_PRIVATE_KEY,SIGNER_PRIVATE_KEY

# The .env will contain placeholders:
# MAIN_WALLET_PRIVATE_KEY=GPG:MAIN_WALLET_PRIVATE_KEY
```

### How Scripts Access Encrypted Keys

The `enforce.py` module handles this transparently:

```python
from enforce import get_credential

# Works for both plaintext and GPG-encrypted keys
key = get_credential('MAIN_WALLET_PRIVATE_KEY')
# If value starts with "GPG:", decrypts from .env.secrets.gpg automatically
```

### GPG Agent Caching

On headless servers (VPS), the GPG agent caches the passphrase:
- Default cache TTL: 8 hours
- Configurable via `setup-gpg.sh`
- Passphrase required once after reboot, then cached

### What to Encrypt

| Key Type | Encrypt? | Why |
|----------|----------|-----|
| Wallet private keys | ✅ Yes | Controls funds |
| Custody/signer private keys | ✅ Yes | Controls identity |
| Mnemonics / seed phrases | ✅ Yes | Master recovery |
| API keys (services) | ❌ No | Revocable, low damage |
| Agent IDs, names, URLs | ❌ No | Not secrets |

## Credential Rotation Tracking

### Setup Rotation Metadata

```bash
# Initialize rotation tracking for all keys
./scripts/rotation-check.py --init
```

Creates `~/.openclaw/.env.meta`:
```json
{
  "MAIN_WALLET_PRIVATE_KEY": {
    "created": "2026-01-15",
    "lastRotated": null,
    "rotationDays": 90,
    "risk": "critical"
  },
  "MOLTBOOK_API_KEY": {
    "created": "2026-02-04",
    "lastRotated": null,
    "rotationDays": 180,
    "risk": "low"
  }
}
```

### Check Rotation Status

```bash
# Check which keys need rotation
./scripts/rotation-check.py

# Output:
# 🔴 MAIN_WALLET_PRIVATE_KEY: 26 days old (critical, rotate every 90 days)
# ✅ MOLTBOOK_API_KEY: 7 days old (low, rotate every 180 days)
```

### Rotation Schedules

| Risk Level | Rotation Period | Examples |
|------------|----------------|----------|
| Critical | 90 days | Wallet keys, private keys |
| Standard | 180 days | API keys for paid services |
| Low | 365 days | Free-tier