rotate-secrets — Atomic Secret Rotation
Rotate secrets in ~/.hermes/.env, propagate the new values to every service that consumes them, and restart only the affected gateways.
Procedure
Parse the pattern. Match against every key in
~/.hermes/.env. Support glob syntax (*,?,[abc]) and the literalall.For each matched key: a. Determine the secret kind from the key name:
*_HMAC_*or*_WEBHOOK_SECRET→ generateopenssl rand -hex 32*_API_KEY→ prompt the user to provide the new value (can't auto-rotate external APIs)GITHUB_*_TOKEN→ open https://github.com/settings/tokens and prompt for new PATTWILIO_AUTH_TOKEN→ direct user to rotate in Twilio console and prompt for new value- Unknown pattern → prompt user for the kind
b. Back up the current
.envas~/.hermes/.env.bak.YYYYMMDDHHMMSSbefore any write.c. Update the
.envatomically. Don't build ased s///expression from the key or value — secret values routinely contain/,&, and\, which corrupt the substitution (and switching the delimiter to|just moves the problem). Use exact-match rewrite instead:tmp=$(mktemp ~/.hermes/.env.XXXXXX) KEY="$KEY" NEW_VALUE="$NEW_VALUE" awk -F= ' $1 == ENVIRON["KEY"] { print ENVIRON["KEY"] "=" ENVIRON["NEW_VALUE"]; found=1; next } { print } END { if (!found) print ENVIRON["KEY"] "=" ENVIRON["NEW_VALUE"] } ' ~/.hermes/.env > "$tmp" && chmod 600 "$tmp" && mv "$tmp" ~/.hermes/.envThis appends the key if it was missing, keeps
0600perms, and never interprets a secret as a regex.Propagate to external services. For HMAC / webhook secrets, update the remote side:
- GitHub webhooks: use
githubMCP toPATCH /repos/{owner}/{repo}/hooks/{hook_id}withconfig.secret - Twilio: user-guided — we don't touch Twilio SMS webhook config automatically
- Slack: user-guided — rotate signing secret in App Manifest
- Discord: user-guided — rotate public key in Developer Portal
- Generic webhook: ask the user where the producer-side config lives
- GitHub webhooks: use
Restart the gateway. Platform-scoped restarts aren't a thing — one gateway process serves every platform, so any token rotation is followed by a single restart of the whole service:
hermes gateway restart# systemd/launchd service (or runhermes gateway runagain if foreground)- For the SMS/Twilio or any other adapter: same command — no per-platform flag exists.
Verify. Run
hermes doctorand fail loud if any gateway is unhealthy post-rotation. If unhealthy, restore from the.env.bak.*backup and report.Emit a rotation log entry. Append to
~/.hermes/logs/rotations.log:2026-04-17T14:22:00Z rotated webhook_hmac_github by=user result=ok prev_sha=abc123 new_sha=def456Store SHA-256 of the secret, never the plaintext.
Security notes
- Never log the plaintext new or old value.
- Never echo a secret into the Telegram/Discord channel where the rotation was requested. Approval prompts route to the originating channel (Part 19, Layer 2) — so only ever run rotations from your owner-only admin DM or the local CLI, never from a shared or public channel.
- For critical rotations (Anthropic, OpenAI, etc.), pause all gateways during rotation to prevent mid-flight requests hitting rejected keys.
- Back up
.envbefore every run; retain 30 days of backups.
Example invocation
/rotate-secrets webhook_hmac_*
/rotate-secrets TWILIO_AUTH_TOKEN
/rotate-secrets all # With interactive confirmation per key
Headless / cron use
Only the HMAC/webhook kinds are fully automatic — API keys and PATs prompt
the operator, and a prompt in a headless cron session never gets answered:
the run stalls until approvals.timeout (or the session's own timeout) kills
it. So:
- Cron
/rotate-secrets webhook_hmac_*— fine; nothing prompts. - Cron
/rotate-secrets all— don't. It will hang on the first interactive kind. Runallmanually from your admin DM/CLI, monthly.
