🔐 Secrets

A lightweight secrets manager with envelope encryption, transit encryption, API auth, and audit logs.

Secrets is inspired by HashiCorp Vault ❤️, but it is intentionally much simpler and was not designed to compete with Vault.

🚀 Quick Start (Docker-first)

The default way to run Secrets is the published Docker image:

docker pull allisson/secrets:v0.6.0

Use pinned tags for reproducible setups. latest is available for dev-only fast iteration.

Docs release/API metadata source: docs/metadata.json.

Then follow the Docker setup guide in docs/getting-started/docker.md.

⚠️ After rotating a master key or KEK, restart API server instances so they load the updated key material.

🧭 Choose Your Path

1. 🐳 Run with Docker image (recommended): docs/getting-started/docker.md
2. 💻 Run locally for development: docs/getting-started/local-development.md

🆕 What's New in v0.6.0

• ☁️ Added KMS integration for master key encryption at rest (KMS_PROVIDER, KMS_KEY_URI)
• 🔁 Added rotate-master-key CLI command for safer master key lifecycle operations
• 🧭 Added provider-specific KMS setup and migration runbook documentation
• ✅ Added KMS migration checklist: docs/operations/kms-migration-checklist.md
• 📘 Added release notes: docs/releases/v0.6.0.md
• ⬆️ Added upgrade guide: docs/releases/v0.6.0-upgrade.md
• 📦 Updated pinned Docker docs/examples to allisson/secrets:v0.6.0

Release history quick links:

• Current: v0.6.0 release notes
• Previous: v0.5.1 release notes
• Previous upgrade guide: v0.5.1 upgrade guide

📚 Docs Map

• Start Here

• 🏁 Docs index: docs/README.md

• 🚀 Getting started (Docker): docs/getting-started/docker.md

• 💻 Getting started (local): docs/getting-started/local-development.md

• 🧰 Troubleshooting: docs/getting-started/troubleshooting.md

• ✅ Smoke test script: docs/getting-started/smoke-test.md

• 🧪 CLI commands reference: docs/cli/commands.md

• 🚀 v0.6.0 release notes: docs/releases/v0.6.0.md

• ⬆️ v0.6.0 upgrade guide: docs/releases/v0.6.0-upgrade.md

• 🔁 Release compatibility matrix: docs/releases/compatibility-matrix.md

• By Topic

  • ⚙️ Environment variables: docs/configuration/environment-variables.md
  • 🏗️ Architecture concepts: docs/concepts/architecture.md
  • 🔒 Security model: docs/concepts/security-model.md
  • 📘 Glossary: docs/concepts/glossary.md
  • 🔑 Key management operations: docs/operations/key-management.md
  • ☁️ KMS setup guide: docs/operations/kms-setup.md
  • ✅ KMS migration checklist: docs/operations/kms-migration-checklist.md
  • 🔐 Security hardening: docs/operations/security-hardening.md
  • 📊 Monitoring and metrics: docs/operations/monitoring.md
  • 🧯 Operator drills: docs/operations/operator-drills.md
  • 🚀 Production rollout golden path: docs/operations/production-rollout.md
  • 🚑 Failure playbooks: docs/operations/failure-playbooks.md
  • 🏭 Production deployment: docs/operations/production.md
  • 🛠️ Development and testing: docs/development/testing.md
  • 🗺️ Docs architecture map: docs/development/docs-architecture-map.md
  • 🤝 Docs contributing: docs/contributing.md
  • 🗒️ Docs changelog: docs/CHANGELOG.md

Release note location:

• Project release notes are in CHANGELOG.md

• Documentation process/history notes are in docs/CHANGELOG.md

• API Reference

• 🔐 Auth API: docs/api/authentication.md

• 👤 Clients API: docs/api/clients.md

• 📘 Policy cookbook: docs/api/policies.md

• 🗂️ Capability matrix: docs/api/capability-matrix.md

• 🚨 Error decision matrix: docs/api/error-decision-matrix.md

• 📦 Secrets API: docs/api/secrets.md

• 🚄 Transit API: docs/api/transit.md

• 🎫 Tokenization API: docs/api/tokenization.md

• 📜 Audit logs API: docs/api/audit-logs.md

• 🧩 API versioning policy: docs/api/versioning-policy.md

• Examples

• 🧪 Curl examples: docs/examples/curl.md

• 🐍 Python examples: docs/examples/python.md

• 🟨 JavaScript examples: docs/examples/javascript.md

• 🐹 Go examples: docs/examples/go.md

All detailed guides include practical use cases and copy/paste-ready examples.

✨ What You Get

• 🔐 Envelope encryption (Master Key -> KEK -> DEK -> Secret Data)
• 🔑 KMS Integration for master key encryption at rest (supports Google Cloud KMS, AWS KMS, Azure Key Vault, HashiCorp Vault, and local secrets for testing)
• 🚄 Transit encryption (/v1/transit/keys/*) for encrypt/decrypt as a service (decrypt input uses <version>:<base64-ciphertext>; see Transit API docs, create vs rotate, and error matrix)
• 🎫 Tokenization API (/v1/tokenization/*) for token generation, detokenization, validation, and revocation
• 👤 Token-based authentication and policy-based authorization
• 📦 Versioned secrets by path (/v1/secrets/*path)
• 📜 Audit logs with request correlation (request_id) and filtering
• 📊 OpenTelemetry metrics with Prometheus-compatible /metrics export

🌐 API Overview

• Health: GET /health
• Readiness: GET /ready
• Token issuance: POST /v1/token
• Clients: GET/POST /v1/clients, GET/PUT/DELETE /v1/clients/:id
• Secrets: POST/GET/DELETE /v1/secrets/*path
• Transit: POST /v1/transit/keys, POST /v1/transit/keys/:name/rotate, POST /v1/transit/keys/:name/encrypt, POST /v1/transit/keys/:name/decrypt, DELETE /v1/transit/keys/:id (create vs rotate, error matrix)
• Tokenization: POST /v1/tokenization/keys, POST /v1/tokenization/keys/:name/rotate, DELETE /v1/tokenization/keys/:id, POST /v1/tokenization/keys/:name/tokenize, POST /v1/tokenization/detokenize, POST /v1/tokenization/validate, POST /v1/tokenization/revoke
• Audit logs: GET /v1/audit-logs
• Metrics: GET /metrics (available when METRICS_ENABLED=true)

📄 License

MIT. See LICENSE.

See also

• Documentation index
• Docker getting started
• API authentication
• Production operations