secret-management

name: secret-management description: Portable credential management for AI agents using age encryption, session-scoped leases, auto-rotation, and killswitch. Use this skill when agents need secure, time-bounded access to API keys, tokens, or credentials without direct exposure to plaintext secrets. license: MIT compatibility: os: [linux, macos] shell: [bash, zsh, sh] metadata: version: 0.1.0 requires: - age encryption library - unix socket support

Secret Management for AI Agents

This skill enables AI agents to securely manage and access credentials using agent-secrets, a Go CLI that provides:

• 🔐 Age encryption for secrets at rest
• ⏱️ Session-scoped leases with automatic expiration
• 🔄 Auto-rotation hooks for dynamic credentials
• 🚨 Multi-factor killswitch for emergency revocation
• 📋 Append-only audit logging

When to Use This Skill

Use agent-secrets when your agent needs to:

• Access API keys, tokens, or credentials securely
• Prevent credential exfiltration in case of compromise
• Maintain an audit trail of secret access
• Enable time-bounded credential access with automatic expiration
• Support credential rotation without manual intervention
• Implement emergency revocation across all active sessions

Prerequisites

The secrets CLI must be installed and in your PATH:

# Install (see repo README for build instructions)
# https://github.com/joelhooks/agent-secrets

# Initialize the encrypted store (run once per machine)
secrets init

# Discover command tree and capabilities
secrets

This creates:

• ~/.agent-secrets/identity.age — X25519 private key (0600 permissions)
• ~/.agent-secrets/secrets.age — encrypted secrets store
• ~/.agent-secrets/config.json — configuration
• ~/.agent-secrets/agent-secrets.sock — daemon socket

Core Workflows

1. Discover Commands and Secret Names

Use discovery-first commands before requesting a lease:

# Root command returns JSON command tree with usage and next_actions
secrets

# List all stored secret names and lease metadata
secrets list

2. Adding Secrets

Interactive mode (prompts for secret value):

secrets add my_secret

With rotation hook (auto-refresh on expiration):

secrets add github_token --rotate-via "gh auth refresh"
secrets add aws_token --rotate-via "aws sts get-session-token --duration-seconds 3600"

From stdin (pipe secret value):

echo "sk-ant-api03-..." | secrets add anthropic_key
cat service-account.json | secrets add gcp_credentials

3. Leasing Secrets

secrets lease <name> returns ONLY the raw secret value by default, so no extra flags are needed for shell export:

# Primary pattern
export GITHUB_TOKEN=$(secrets lease github_token)

# Custom TTL
export ANTHROPIC_API_KEY=$(secrets lease anthropic_key --ttl 30m)

# With client ID for audit trail
export OPENAI_KEY=$(secrets lease openai_key --ttl 2h --client-id "claude-code-worker")

# Use --json when you need lease metadata and next_actions
secrets lease github_token --json

Example JSON envelope (--json):

{
  "ok": true,
  "command": "secrets lease",
  "result": {
    "lease_id": "lease-123",
    "secret_name": "github_token",
    "value": "ghp_xxx",
    "expires_at": "2026-02-19T12:00:00Z",
    "ttl": "1h",
    "client_id": "claude-code-worker"
  },
  "next_actions": [
    {"command": "export GITHUB_TOKEN=$(secrets lease github_token)", "description": "Export to environment"},
    {"command": "secrets revoke lease-123", "description": "Revoke this lease"}
  ]
}

Error responses include a concrete fix field:

{
  "ok": false,
  "command": "secrets lease",
  "error": {"message": "failed to acquire lease: ... secret not found", "code": "generic_error"},
  "fix": "Check available secrets: secrets status"
}

Important: Secrets cannot be accessed directly. You must acquire a lease, and leases auto-expire.

4. Checking Status

View daemon and lease status:

secrets status

Output shows:

• Daemon running state
• Start time
• Number of stored secrets
• Active lease count

5. Audit Trail

View the append-only audit log:

# Last 50 entries (default)
secrets audit

# Last 100 entries
secrets audit --tail 100

Logs include:

• Secret access events
• Lease grants and expirations
• Revocations
• Rotation events
• Killswitch activations

6. Revocation

Revoke specific lease:

secrets revoke abc123

KILLSWITCH — Revoke ALL active leases:

secrets revoke --all

Use the killswitch when:

• Agent is compromised
• Session needs immediate termination
• Emergency security event occurs

Agent Integration Patterns

Claude Code / Cline / Aider

In your agent's environment setup script:

# Session initialization
secrets list
export GITHUB_TOKEN=$(secrets lease github_token)
export ANTHROPIC_API_KEY=$(secrets lease anthropic_key)
export OPENAI_API_KEY=$(secrets lease openai_key)

# Now agent has time-bounded access
gh api /user
curl -H "Authorization: Bearer $ANTHROPIC_API_KEY" https://api.anthropic.com/...

Swarm Worker Pattern

For multi-agent swarm tasks, each worker should:

1. Lease required credentials on startup with unique client ID
2. Use --ttl matching expected task duration
3. Let leases auto-expire on completion (no manual cleanup needed)

Example:

# Worker initialization
WORKER_ID="worker-${EPIC_ID}-${TASK_ID}"
export GH_TOKEN=$(secrets lease github_token --ttl 2h --client-id "$WORKER_ID")
export VERCEL_TOKEN=$(secrets lease vercel_token --ttl 2h --client-id "$WORKER_ID")

# Work proceeds with secured credentials
# Leases auto-expire after 2 hours

Security Considerations

Encryption

• All secrets encrypted at rest using age with X25519
• Identity file permissions are 0600 (read/write owner only)
• No plaintext secrets on disk

Lease Management

• Mandatory TTL on all leases (max 24h by default)
• Expired leases automatically pruned by background process
• Leases cannot be extended—must acquire new lease

Audit

• Every operation logged with timestamp, client ID, and event type
• Append-only format (JSONL) prevents tampering
• Use audit log for security reviews and incident response

Killswitch

• revoke --all immediately invalidates all active leases
• Optional: rotate all secrets with configured hooks
• Optional: wipe entire store
• Optional: heartbeat monitor (auto-killswitch if remote endpoint fails)

Rotation Hooks

Auto-rotation commands run on lease expiration or manual trigger:

# GitHub token refresh
secrets add github_token --rotate-via "gh auth refresh"

# AWS session token
secrets add aws_token --rotate-via "aws sts get-session-token --duration-seconds 3600"

# Custom script
secrets add api_key --rotate-via "/path/to/refresh-token.sh"

Configuration

Edit ~/.agent-secrets/config.json to customize:

{
  "directory": "/home/user/.agent-secrets",
  "socket_path": "/home/user/.agent-secrets/agent-secrets.sock",
  "default_lease_ttl": "1h",
  "max_lease_ttl": "24h",
  "rotation_timeout": "30s",
  "heartbeat": {
    "enabled": false,
    "url": "https://your-endpoint.com/heartbeat",
    "interval": "1m",
    "timeout": "10s",
    "fail_action": {
      "revoke_all": true,
      "rotate_all": false,
      "wipe_store": false
    }
  }
}

Heartbeat Monitor (Optional)

Enable remote killswitch via heartbeat failure:

• Set heartbeat.enabled: true
• Configure endpoint URL
• Set fail actions (revoke_all, rotate_all, wipe_store)

If heartbeat endpoint becomes unreachable for timeout duration, configured fail actions execute automatically.

Common CLI Commands Reference

Troubleshooting

Daemon not running?

# Check status
secrets status

# Daemon auto-starts on first lease/add command
secrets lease github_token

Permission denied on identity file?

chmod 600 ~/.agent-secrets/identity.age

Forgot which secrets are stored?

secrets list

Need to rotate everything immediately?

secrets revoke --all
# Then add secrets again with fresh values

Best Practices for AI Agents

1. Use descriptive client IDs: Include agent name, task ID, or session ID for audit trail
2. Match TTL to task duration: Don't request 24h lease for 5min task
3. Let leases expire naturally: No manual cleanup needed
4. Enable rotation hooks: For dynamic credentials (GitHub, AWS, etc.)
5. Monitor audit log: Review for unexpected access patterns
6. Test killswitch: Verify revoke --all works in your environment
7. Use unique leases per worker: In swarm mode, each worker gets own lease with unique client ID

Example: Full Agent Session

#!/bin/bash
# Agent session initialization with agent-secrets

set -euo pipefail

# Navigate to agent-secrets CLI
SECRETS_CLI="/home/joel/Code/joelhooks/agent-secrets/secrets"

# Lease credentials for 2-hour work session
echo "🔐 Acquiring credentials..."
export GITHUB_TOKEN=$($SECRETS_CLI lease github_token)
export ANTHROPIC_API_KEY=$($SECRETS_CLI lease anthropic_key)
export VERCEL_TOKEN=$($SECRETS_CLI lease vercel_token)

# Verify credentials loaded
echo "✅ Credentials acquired (expire in 2h)"

# Check status
$SECRETS_CLI status

# Agent work proceeds here...
# gh pr create ...
# vercel deploy ...
# etc.

# No cleanup needed - leases auto-expire
echo "🎯 Session complete (leases will auto-expire)"

Repository Location

CLI source: /home/joel/Code/joelhooks/agent-secrets

Build the CLI:

cd /home/joel/Code/joelhooks/agent-secrets
make build
# Binary: secrets

Install system-wide:

cd /home/joel/Code/joelhooks/agent-secrets
make install
# Binary installed to $GOPATH/bin/secrets