Secrets Manager

SKILL.md

---
name: secrets-manager
description: Secure secrets store for OpenClaw agents. AES-256-GCM encryption. Store, retrieve, rotate, and audit secrets. Inject secrets into commands. Zero external dependencies.
---

# Secrets Manager 🔐

**Stop hardcoding secrets. Start managing them securely.**

## The Problem

API keys, tokens, passwords — they end up in shell history, logs, or committed to git. No local secrets store means every agent session is a potential leak.

Secrets Manager fixes this with AES-256-GCM encrypted local storage and zero dependencies.

## ⚠️ Security Warning

Secrets Manager is a **local agent tool**, not a production secrets vault. Raw secrets printed via `--get --raw` or embedded via `--inject` can leak to shell history, terminal scrollback, logs, CI output, and process listings. Prefer environment-variable injection for sensitive contexts. See the Security Notes section below.

## Quick Start

### Store a secret

```bash
node skills/secrets-manager/secrets-manager.js --store openai-key sk-abc123
```

### Get a secret (masked, to stderr)

```bash
node skills/secrets-manager/secrets-manager.js --get openai-key
# Output (stderr): [secrets-manager] openai-key: sk-a****23
```

### Get raw value (⚠️ to stdout — avoid when possible)

```bash
node skills/secrets-manager/secrets-manager.js --get --raw openai-key
# ⚠️ WARNING: Outputs raw secret to stdout
```

### List all secrets

```bash
node skills/secrets-manager/secrets-manager.js --list
```

### Delete a secret

```bash
node skills/secrets-manager/secrets-manager.js --delete old-key
```

### Rotate a secret

```bash
node skills/secrets-manager/secrets-manager.js --rotate openai-key
# Generates a new random value, archives old as "retired"
# New value is never printed — secure by default
```

### Rotate all secrets

```bash
node skills/secrets-manager/secrets-manager.js --rotate --all
```

### Audit for security issues

```bash
node skills/secrets-manager/secrets-manager.js --audit
node skills/secrets-manager/secrets-manager.js --audit --expired
node skills/secrets-manager/secrets-manager.js --audit --stale
```

### Inject secrets into a command (⚠️)

```bash
node skills/secrets-manager/secrets-manager.js --inject "curl -H 'Authorization: Bearer {{openai-key}}' https://api.openai.com/v1/chat"
# ⚠️ WARNING: Output contains plaintext secrets. Piping to a shell
#            exposes them to history, process listings, and logs.
# Prefer: export TOKEN=$(... --get --raw); curl -H "Authorization: Bearer $TOKEN" ...
```

### Status overview

```bash
node skills/secrets-manager/secrets-manager.js --status
```

## Features

### AES-256-GCM Encryption

- 256-bit master key (auto-generated or set via `SECRETS_MASTER_KEY` env var)
- Per-secret random 96-bit IVs
- GCM authenticated encryption detects tampering
- Master key stored in `memory/secrets/.master-key` (mode 0600)
- Secrets stored in `memory/secrets/secrets.json` (mode 0600)

### Rotation Tracking

- 90-day default rotation cycle per secret
- Automatic expiration warnings in audit
- One-command rotation generates new random values
- Old values archived as "retired" for recovery
- New rotated values are never printed

### Audit System

- Detects expired secrets past rotation date
- Flags secrets approaching rotation deadline
- Identifies weak patterns (common prefixes, short length)
- Reports rotation age for each secret

### Command Injection (use with care)

- `{{secret_name}}` placeholders replaced with stored values
- Confirmation printed to stderr, injected command to stdout
- ⚠️ Result contains plaintext secrets — do not pipe to shell casually
- Prefer environment-variable injection for production use

## Configuration

- Secrets stored in: `memory/secrets/secrets.json`
- Master key: `memory/secrets/.master-key` or `SECRETS_MASTER_KEY` env var
- Override storage location: `--dir /path/to/secrets`

## Agent Protocol

When handling secrets:

1. **Never hardcode** — always use `--store` first
2. **Masked output** — use `--get` (not `--get --raw`) for display
3. **Audit regularly** — run `--audit` during health checks
4. **Rotate proactively** — rotate secrets flagged as expiring
5. **Inject carefully** — prefer env-var injection over `--inject`

## Security Notes

- Encryption: AES-256-GCM with 256-bit master key and per-secret random IVs
- Authenticated encryption detects tampering or corruption
- Master key stored separately from ciphertext (not in same file)
- All files set to mode `0600` (owner read/write only)
- **⚠️ Raw retrieval (`--get --raw`) prints secrets to stdout** — exposes to logs, scrollback, CI
- **⚠️ Command injection (`--inject`) embeds plaintext secrets** — exposes to shell history, `ps`, `/proc`
- For production-grade secret management, use a dedicated vault (HashiCorp Vault, AWS Secrets Manager)
- Secrets directory should be gitignored
- Back up the master key securely — if lost, all secrets become unrecoverable

## Comparison

| Approach | Encryption | Audit | Rotation | Warnings |
|----------|-----------|-------|----------|----------|
| Environment vars | None | None | Manual | None |
| .env files | None | None | Manual | None |
| **Secrets Manager** | **AES-256-GCM** | **Auto** | **Auto** | **Built-in** |
| Vault service | AES-256-GCM | Auto | Auto | Enterprise |

**Secrets Manager gives you authenticated encryption + rotation + auditing with zero external dependencies.**

## Design Principles

1. **Real encryption** — AES-256-GCM, not base64 obfuscation
2. **Zero setup** — Auto-generates master key on first use
3. **No dependencies** — Pure Node.js `crypto`, no npm packages
4. **Safe by default** — Masked output, never prints rotated values
5. **Transparent** — Audit reports show exactly what's wrong
6. **Honest** — Clear warnings about raw/inject modes, not false security claims