--- name: secrets-manager description: >- Encrypted local secret store for OpenClaw agents. AES-256-GCM authenticated encryption with per-secret random IVs, master key in chmod 0600 .master-key file. A PURE STORE: it encrypts, retrieves, lists, rotates, audits, and deletes secrets — it never writes plaintext secrets to disk or generates executable command scripts. Modes: --store (encrypt+write), --get (masked; --raw prints plaintext to stdout), --list (names+metadata only), --delete (irreversible), --rotate and --rotate --all (generate new random values, archive old as retired), --audit / --audit --expired / --audit --stale (exposure/rotation checks), --status. Supports SECRETS_DIR and SECRETS_MASTER_KEY env overrides. For injecting secrets into shell commands, use the separate `secrets-inject` skill (high-privilege). Master key is recoverable from .master-key file; losing it makes stored secrets unrecoverable. permissions: - filesystem.read-write - environment.read - crypto.aes-256-gcm --- # Secrets Manager 🔐 **Encrypted local secret store.** AES-256-GCM authenticated encryption. Master key auto-generated on first store and stored in `memory/secrets/.master-key` (chmod 0600). > **Important**: If you lose `.master-key`, all stored secrets become unrecoverable. Back it up. ## ⚠️ Important Warnings ### Encryption: AES-256-GCM (Authenticated) - 256-bit master key, per-secret 96-bit random IV, 128-bit GCM auth tag - Tampered ciphertext returns `null` from decrypt (no partial decryption) - Master key stored in `memory/secrets/.master-key` with chmod 0600 - Override via `SECRETS_MASTER_KEY=` env var - Losing the master key = all secrets unrecoverable ### `--get --raw` Prints Plaintext to stdout The secret value goes to stdout, which may be captured in: - Shell history / terminal scrollback - Process logs / journald / syslog - CI/CD pipeline output - Agent transcripts / OpenClaw session history Use only when piping to a private process: ```bash node secrets-manager.js --get --raw api-key > /tmp/api-key.txt && chmod 600 /tmp/api-key.txt ``` ### Rotation: Old Values Are Archived Rotated secrets keep the old encrypted value as `retired`. Rotate again to discard the archive. There is no `--undo` for archival. ### Storage Location `memory/secrets/secrets.json` (chmod 0600) plus `memory/secrets/.master-key` (chmod 0600). Override via `--dir ` or `SECRETS_DIR=`. ## Quick Start ### Store a secret ```bash node skills/secrets-manager/secrets-manager.js --store openai-key sk-abc123 # Output: [secrets-manager] Stored: openai-key (masked: sk-****23) ``` ### Get a secret (masked by default) ```bash node skills/secrets-manager/secrets-manager.js --get openai-key # Output: [secrets-manager] openai-key: sk-****23 ``` ### Get raw value (when you must pass it to another tool) ```bash node skills/secrets-manager/secrets-manager.js --get --raw openai-key > /tmp/key.txt # Output: sk-abc123 (captured to file) ``` ### List all secrets (names + metadata, NOT values) ```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 # New random value generated, old encrypted value archived as retired ``` ### 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 ``` ### Status overview ```bash node skills/secrets-manager/secrets-manager.js --status ``` ## Features ### Encryption - **AES-256-GCM** authenticated encryption - 256-bit master key (auto-generated on first store) - 96-bit per-secret random IV - 128-bit GCM auth tag (tamper detection) - Master key in `memory/secrets/.master-key` (chmod 0600) - `SECRETS_MASTER_KEY` env var override ### Rotation Tracking - 90-day default rotation cycle per secret - Automatic expiration warnings (audit --stale at 70% of cycle) - One-command rotation with new random value generation - Old values archived as `retired` (encrypted, recoverable until next rotate) ### Audit System - Detects expired secrets past rotation date - Flags secrets approaching rotation deadline (70% threshold) - Identifies weak patterns (common prefixes, short length <8 chars) - Detects decryption failures (tampered ciphertext or wrong master key) - Reports rotation age for each secret ## Configuration Data stored in: `memory/secrets/` - `secrets.json` — encrypted secrets (chmod 0600) - `.master-key` — 256-bit master key as hex (chmod 0600) - `permissions.json` — per-secret access rules (chmod 0600) Override storage location: ```bash --dir /path/to/secrets # or env var SECRETS_DIR=/path/to/secrets node secrets-manager.js --status ``` Override master key: ```bash SECRETS_MASTER_KEY=<64-hex-chars> node secrets-manager.js --get openai-key ``` ## Agent Protocol When handling secrets: 1. **Store with encryption** — `--store ` writes AES-256-GCM ciphertext 2. **Default to masked output** — `--get` (not `--get --raw`) for display 3. **Audit regularly** — `--audit` during heartbeats 5. **Rotate proactively** — rotate secrets flagged as expiring 6. **Back up `.master-key`** — without it, stored secrets are unrecoverable ## Security Notes - **AES-256-GCM authenticated encryption** — secrets are encrypted at rest, not base64-encoded - **Master key** in `memory/secrets/.master-key` (chmod 0600) — back it up - For production-grade secrets with HSM-backed keys, use a real vault (HashiCorp, AWS Secrets Manager, OS keychain) - `SECRETS_MASTER_KEY` env var for ephemeral/CI environments ## What This Skill Does NOT Do - Does NOT store secrets in plaintext or base64 — all values are AES-256-GCM encrypted - Does NOT print secret values to stdout unless explicitly requested via `--get --raw` - Does NOT install npm packages - Does NOT phone home or transmit secrets anywhere - Does NOT log secret values - Does NOT require a separate key server — master key is a local file ## Comparison | Approach | Encryption | Setup | Audit | Rotation | Recovery | |----------|-----------|-------|-------|----------|----------| | Environment vars | None | Medium | None | Manual | N/A | | .env files | None | Low | None | Manual | N/A | | **Secrets Manager** | **AES-256-GCM** | **None** | **Auto** | **Auto** | **With .master-key** | | Vault service | Various | High | Auto | Auto | Yes | **Secrets Manager gives you real encryption + rotation + audit with zero external dependencies.** ## Design Principles 1. **Zero setup** — Works immediately, no config needed 2. **No dependencies** — Pure Node.js crypto, no npm packages 3. **Safe by default** — Masked output, encrypted at rest, no plaintext-on-disk 4. **Transparent** — Audit reports show exactly what's wrong 5. **Recoverable** — Master key + encrypted secrets = full recovery