feat: add security security hardening features

.env.example

@@ -1,5 +1,8 @@
 # Database configuration
 DB_DRIVER=postgres
+# ⚠️ SECURITY WARNING: sslmode=disable is for DEVELOPMENT ONLY
+# Production MUST use sslmode=require or sslmode=verify-full
+# See docs/operations/security-hardening.md for guidance
 DB_CONNECTION_STRING=postgres://user:password@localhost:5432/mydb?sslmode=disable
 DB_MAX_OPEN_CONNECTIONS=25
 DB_MAX_IDLE_CONNECTIONS=5
@@ -20,9 +23,29 @@ METRICS_NAMESPACE=secrets
 # Generate a new master key using: ./bin/app create-master-key
 # Each key must be exactly 32 bytes (256 bits), base64-encoded
 # Format: id1:base64key1,id2:base64key2 (comma-separated for multiple keys)
+# ⚠️ SECURITY WARNING: Store master keys in secrets manager in production
+# Never commit master keys to source control
 MASTER_KEYS=default:bEu+O/9NOFAsWf1dhVB9aprmumKhhBcE6o7UPVmI43Y=
 ACTIVE_MASTER_KEY_ID=default
 
+# Authentication configuration
+# Token expiration in seconds (default: 14400 = 4 hours)
+# Migration note: Prior to v0.5.0, default was 86400 (24 hours)
+AUTH_TOKEN_EXPIRATION_SECONDS=14400
+
+# Rate limiting configuration
+# Protects against abuse and denial-of-service attacks
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_REQUESTS_PER_SEC=10.0
+RATE_LIMIT_BURST=20
+
+# CORS configuration
+# ⚠️ SECURITY WARNING: CORS is disabled by default for server-to-server API
+# Enable only if browser-based access is required
+# Never use "*" for CORS_ALLOW_ORIGINS in production
+CORS_ENABLED=false
+CORS_ALLOW_ORIGINS=
+
 # Worker configuration
 WORKER_INTERVAL=5
 WORKER_BATCH_SIZE=10

.github/workflows/ci.yml

@@ -90,6 +90,14 @@ jobs:
             exit 1
           fi
 
+      - name: Release docs link guard (PRs)
+        if: github.event_name == 'pull_request'
+        env:
+          GITHUB_EVENT_NAME: ${{ github.event_name }}
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PR_HEAD_SHA: ${{ github.sha }}
+        run: python3 docs/tools/check_release_docs_links.py
+
       - name: Markdown lint
         uses: DavidAnson/markdownlint-cli2-action@v20
         with:
@@ -103,7 +111,22 @@ jobs:
         run: python3 docs/tools/check_example_shapes.py
 
       - name: Docs metadata checks
-        run: python3 docs/tools/check_docs_metadata.py
+        run: |
+          set -euo pipefail
+
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            export DOCS_CHANGED_FILES="$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.sha }}")"
+          else
+            export DOCS_CHANGED_FILES=""
+          fi
+
+          python3 docs/tools/check_docs_metadata.py
+
+      - name: OpenAPI validation
+        run: |
+          set -euo pipefail
+          python3 -m pip install --disable-pip-version-check --no-cache-dir openapi-spec-validator==0.7.1
+          python3 -m openapi_spec_validator docs/openapi.yaml
 
       - name: Markdown link check (offline)
         uses: lycheeverse/lychee-action@v2

CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-02-19
+
+### Added
+- Per-client rate limiting for authenticated endpoints (default: 10 req/sec, burst 20)
+- Configurable CORS support (disabled by default)
+- Comprehensive security hardening documentation (`docs/operations/security-hardening.md`)
+- Rate limiting configuration via `RATE_LIMIT_ENABLED`, `RATE_LIMIT_REQUESTS_PER_SEC`, `RATE_LIMIT_BURST`
+- CORS configuration via `CORS_ENABLED`, `CORS_ALLOW_ORIGINS`
+
+### Changed
+- **BREAKING**: Default token expiration reduced from 24 hours to 4 hours (86400 → 14400 seconds)
+- Updated environment variables documentation with security warnings
+- Updated production deployment guide with security hardening reference
+
+### Migration Notes
+
+**Token Expiration Change:**
+If you rely on the previous default token expiration of 24 hours, explicitly set `AUTH_TOKEN_EXPIRATION_SECONDS=86400` in your environment configuration. Otherwise, tokens will now expire after 4 hours by default.
+
+**Review Client Token Refresh Logic:**
+Ensure your client applications handle token refresh before expiration. The shorter default expiration improves security but may require updating client-side token refresh logic if you were relying on the previous 24-hour default.
+
+**Database SSL/TLS:**
+If you are using `sslmode=disable` (PostgreSQL) or `tls=false` (MySQL) in production, this is insecure. Update your `DB_CONNECTION_STRING` to use `sslmode=require` or `sslmode=verify-full` (PostgreSQL) or `tls=true` or `tls=custom` (MySQL). See `docs/operations/security-hardening.md` for guidance.
+
+### Security
+- Added database SSL/TLS configuration warnings in documentation
+- Added reverse proxy TLS requirements in documentation
+- Added master key storage security guidance
+- Added metrics endpoint protection recommendations
+
+### Documentation
+- Added `docs/operations/security-hardening.md` with comprehensive security guidance
+- Updated `docs/configuration/environment-variables.md` with new variables and security warnings
+- Updated `.env.example` with security warnings for development-only configurations
+- Updated `docs/getting-started/docker.md` and `docs/getting-started/local-development.md` with security warnings
+- Updated `docs/concepts/security-model.md` with production recommendations
+- Updated `README.md` with security hardening link
+
+## [0.4.1] - 2026-02-19
+
+### Fixed
+- Policy matcher now supports mid-path wildcard patterns (e.g., `/v1/transit/keys/*/rotate`)
+- Mid-path `*` wildcard now matches exactly one path segment
+- Trailing wildcard `/*` behavior remains greedy for nested subpaths
+
+### Documentation
+- Added policy path-matching behavior documentation
+- Added policy migration examples for wildcard patterns
+- Added policy review checklist for operators
+
+## [0.4.0] - 2026-02-18
+
+### Added
+- Tokenization API for token generation, detokenization, validation, and revocation
+- Tokenization key management (create, rotate, delete)
+- Deterministic and non-deterministic tokenization support
+- Token TTL and revocation capabilities
+- Token metadata support (non-encrypted)
+- CLI commands for tokenization key management
+- Expired token cleanup command (`clean-expired-tokens`)
+
+### Documentation
+- Added `docs/api/tokenization.md` with API reference
+- Added tokenization examples in curl, Python, JavaScript, and Go
+- Added tokenization monitoring and operations guidance
+- Added tokenization migration verification guide
+
+## [0.3.0] - 2026-02-16
+
+### Added
+- OpenTelemetry metrics collection with Prometheus-compatible `/metrics` endpoint
+- Configurable metrics namespace via `METRICS_NAMESPACE`
+- Metrics enable/disable toggle via `METRICS_ENABLED`
+- HTTP request metrics (total requests, duration, status codes)
+- Cryptographic operation metrics (secret operations, transit operations, audit log operations)
+
+### Documentation
+- Added `docs/operations/monitoring.md` with Prometheus and Grafana quickstart
+- Added metrics naming contract and endpoint documentation
+- Added production hardening guidance for securing `/metrics` endpoint
+
+## [0.2.0] - 2026-02-14
+
+### Added
+- Audit log retention cleanup command (`clean-audit-logs`)
+- Dry-run mode for audit log cleanup
+- JSON and text output formats for cleanup commands
+
+### Documentation
+- Added audit log retention cleanup runbook
+- Added CLI reference documentation
+- Updated production operations guide with retention workflows
+
+## [0.1.0] - 2026-02-14
+
+### Added
+- Envelope encryption with Master Key → KEK → DEK → Data hierarchy
+- Transit encryption API (encrypt/decrypt as a service)
+- Token-based authentication and capability-based authorization
+- Versioned secrets storage by path
+- Audit logging with request correlation
+- Support for PostgreSQL and MySQL databases
+- Support for AES-GCM and ChaCha20-Poly1305 encryption algorithms
+- Health and readiness endpoints
+- Client management API (create, get, update, delete)
+- Master key and KEK management CLI commands
+- Docker image distribution
+
+### Documentation
+- Initial documentation structure
+- API reference documentation
+- Getting started guides (Docker and local development)
+- Operations guides (production deployment, key management)
+- Example code (curl, Python, JavaScript, Go)
+- Security model documentation
+- Architecture documentation

README.md

@@ -13,7 +13,7 @@ Secrets is inspired by **HashiCorp Vault** ❤️, but it is intentionally **muc
 The default way to run Secrets is the published Docker image:
 
 ```bash
-docker pull allisson/secrets:v0.4.1
+docker pull allisson/secrets:v0.5.0
 ```
 
 Use pinned tags for reproducible setups. `latest` is also available for fast iteration.
@@ -29,12 +29,15 @@ Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/gett
 1. 🐳 **Run with Docker image (recommended)**: [docs/getting-started/docker.md](docs/getting-started/docker.md)
 2. 💻 **Run locally for development**: [docs/getting-started/local-development.md](docs/getting-started/local-development.md)
 
-## 🆕 What's New in v0.4.1
+## 🆕 What's New in v0.5.0
 
-- 🐛 Fixed policy path matching for authorization with mid-path wildcards (for example `/v1/transit/keys/*/rotate`)
-- ✅ Added stronger policy-matching coverage for wildcard edge cases and common role templates
-- 📘 Added bugfix release notes: [docs/releases/v0.4.1.md](docs/releases/v0.4.1.md)
-- 📦 Updated pinned Docker docs/examples to `allisson/secrets:v0.4.1`
+- 🛡️ Added per-client rate limiting for authenticated API endpoints
+- 🌐 Added configurable CORS support (disabled by default)
+- ⏱️ Changed default token expiration from 24h to 4h for stronger security
+- 🔐 Added comprehensive security hardening guide: [docs/operations/security-hardening.md](docs/operations/security-hardening.md)
+- 📘 Added release notes: [docs/releases/v0.5.0.md](docs/releases/v0.5.0.md)
+- ⬆️ Added upgrade guide: [docs/releases/v0.5.0-upgrade.md](docs/releases/v0.5.0-upgrade.md)
+- 📦 Updated pinned Docker docs/examples to `allisson/secrets:v0.5.0`
 
 ## 📚 Docs Map
 
@@ -45,26 +48,38 @@ Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/gett
 - 🧰 **Troubleshooting**: [docs/getting-started/troubleshooting.md](docs/getting-started/troubleshooting.md)
 - ✅ **Smoke test script**: [docs/getting-started/smoke-test.md](docs/getting-started/smoke-test.md)
 - 🧪 **CLI commands reference**: [docs/cli/commands.md](docs/cli/commands.md)
-- 🚀 **v0.4.1 release notes**: [docs/releases/v0.4.1.md](docs/releases/v0.4.1.md)
+- 🚀 **v0.5.0 release notes**: [docs/releases/v0.5.0.md](docs/releases/v0.5.0.md)
+- ⬆️ **v0.5.0 upgrade guide**: [docs/releases/v0.5.0-upgrade.md](docs/releases/v0.5.0-upgrade.md)
+- 🔁 **Release compatibility matrix**: [docs/releases/compatibility-matrix.md](docs/releases/compatibility-matrix.md)
 
 - **By Topic**
 - ⚙️ **Environment variables**: [docs/configuration/environment-variables.md](docs/configuration/environment-variables.md)
 - 🏗️ **Architecture concepts**: [docs/concepts/architecture.md](docs/concepts/architecture.md)
 - 🔒 **Security model**: [docs/concepts/security-model.md](docs/concepts/security-model.md)
 - 📘 **Glossary**: [docs/concepts/glossary.md](docs/concepts/glossary.md)
 - 🔑 **Key management operations**: [docs/operations/key-management.md](docs/operations/key-management.md)
+- 🔐 **Security hardening**: [docs/operations/security-hardening.md](docs/operations/security-hardening.md)
 - 📊 **Monitoring and metrics**: [docs/operations/monitoring.md](docs/operations/monitoring.md)
+- 🧯 **Operator drills**: [docs/operations/operator-drills.md](docs/operations/operator-drills.md)
+- 🚀 **Production rollout golden path**: [docs/operations/production-rollout.md](docs/operations/production-rollout.md)
 - 🚑 **Failure playbooks**: [docs/operations/failure-playbooks.md](docs/operations/failure-playbooks.md)
 - 🏭 **Production deployment**: [docs/operations/production.md](docs/operations/production.md)
 - 🛠️ **Development and testing**: [docs/development/testing.md](docs/development/testing.md)
+- 🗺️ **Docs architecture map**: [docs/development/docs-architecture-map.md](docs/development/docs-architecture-map.md)
 - 🤝 **Docs contributing**: [docs/contributing.md](docs/contributing.md)
 - 🗒️ **Docs changelog**: [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
+Release note location:
+
+- Project release notes are in [CHANGELOG.md](CHANGELOG.md)
+- Documentation process/history notes are in [docs/CHANGELOG.md](docs/CHANGELOG.md)
+
 - **API Reference**
 - 🔐 **Auth API**: [docs/api/authentication.md](docs/api/authentication.md)
 - 👤 **Clients API**: [docs/api/clients.md](docs/api/clients.md)
 - 📘 **Policy cookbook**: [docs/api/policies.md](docs/api/policies.md)
 - 🗂️ **Capability matrix**: [docs/api/capability-matrix.md](docs/api/capability-matrix.md)
+- 🚨 **Error decision matrix**: [docs/api/error-decision-matrix.md](docs/api/error-decision-matrix.md)
 - 📦 **Secrets API**: [docs/api/secrets.md](docs/api/secrets.md)
 - 🚄 **Transit API**: [docs/api/transit.md](docs/api/transit.md)
 - 🎫 **Tokenization API**: [docs/api/tokenization.md](docs/api/tokenization.md)

docs/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 > Last updated: 2026-02-19
 
+## 2026-02-19 (docs v10 - v0.5.0 security hardening release prep)
+
+- Added comprehensive security hardening guide: `docs/operations/security-hardening.md`
+- Updated docs metadata source (`docs/metadata.json`) to `current_release: v0.5.0`
+- Added release notes page: `docs/releases/v0.5.0.md` and promoted it as current in docs indexes
+- Updated environment variables documentation with rate limiting and CORS configuration
+- Added security warnings for database SSL/TLS requirements (production vs development)
+- Added migration note for token expiration default change (24h → 4h)
+- Updated `.env.example` with new configuration options and security warnings
+- Added security warnings to Docker and local development getting-started guides
+- Updated production deployment guide with security hardening reference
+- Updated security model with comprehensive production recommendations
+- Added security hardening link to root README and docs indexes
+- Updated current-release references from v0.4.1 to v0.5.0 while preserving historical links
+- Added upgrade guide: `docs/releases/v0.5.0-upgrade.md`
+- Added API rate limiting reference: `docs/api/rate-limiting.md`
+- Updated API endpoint docs with `429` behavior and rate-limiting cross-links
+- Expanded troubleshooting with `429` and CORS/preflight diagnostics
+- Added retry/backoff examples for `429` handling in curl, Python, JavaScript, and Go example docs
+- Added rate-limiting production presets in environment variables documentation
+- Added docs release checklist: `docs/development/docs-release-checklist.md`
+- Added OpenAPI validation step in CI workflow
+- Added production rollout golden path runbook: `docs/operations/production-rollout.md`
+- Added API error decision matrix: `docs/api/error-decision-matrix.md`
+- Added release compatibility matrix: `docs/releases/compatibility-matrix.md`
+- Added persona-oriented policy templates and references in `docs/api/policies.md`
+- Expanded monitoring guide with rate-limit Prometheus queries and alert examples
+- Added CORS smoke checks (copy/paste) to troubleshooting guide
+- Added quarterly operator drills runbook: `docs/operations/operator-drills.md`
+- Added dashboard artifact templates under `docs/operations/dashboards/`
+- Added docs architecture map: `docs/development/docs-architecture-map.md`
+- Added release docs CI guard: `docs/tools/check_release_docs_links.py` + workflow integration
+- Expanded policy smoke tests with pre-deploy automation wrapper pattern
+
 ## 2026-02-19 (docs v9 - v0.4.1 bugfix release prep)
 
 - Added release notes page: `docs/releases/v0.4.1.md` and promoted it as current in docs indexes

docs/README.md

@@ -18,8 +18,9 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 
 1. Start with Docker guide: [getting-started/docker.md](getting-started/docker.md)
 2. Validate end-to-end setup: [getting-started/smoke-test.md](getting-started/smoke-test.md)
-3. Apply production hardening checklist: [operations/production.md](operations/production.md)
-4. Use runbook hub for rollout and incidents: [operations/runbook-index.md](operations/runbook-index.md)
+3. Follow rollout runbook: [operations/production-rollout.md](operations/production-rollout.md)
+4. Apply production hardening checklist: [operations/production.md](operations/production.md)
+5. Use runbook hub for rollout and incidents: [operations/runbook-index.md](operations/runbook-index.md)
 
 ## 📖 Documentation by Topic
 
@@ -28,12 +29,16 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 - 🔒 [concepts/security-model.md](concepts/security-model.md)
 - 📘 [concepts/glossary.md](concepts/glossary.md)
 - 🔑 [operations/key-management.md](operations/key-management.md)
+- 🚀 [operations/production-rollout.md](operations/production-rollout.md)
 - 📊 [operations/monitoring.md](operations/monitoring.md)
+- 🧯 [operations/operator-drills.md](operations/operator-drills.md)
 - 🏭 [operations/production.md](operations/production.md)
 - 🚑 [operations/failure-playbooks.md](operations/failure-playbooks.md)
 - 🧪 [operations/policy-smoke-tests.md](operations/policy-smoke-tests.md)
 - 🧭 [operations/runbook-index.md](operations/runbook-index.md)
 - 🛠️ [development/testing.md](development/testing.md)
+- 🧾 [development/docs-release-checklist.md](development/docs-release-checklist.md)
+- 🗺️ [development/docs-architecture-map.md](development/docs-architecture-map.md)
 - 🤝 [contributing.md](contributing.md)
 - 🗒️ [CHANGELOG.md](CHANGELOG.md)
 
@@ -53,23 +58,28 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 - 👤 [api/clients.md](api/clients.md)
 - 📘 [api/policies.md](api/policies.md)
 - 🗂️ [api/capability-matrix.md](api/capability-matrix.md)
+- 🚨 [api/error-decision-matrix.md](api/error-decision-matrix.md)
 - 📦 [api/secrets.md](api/secrets.md)
 - 🚄 [api/transit.md](api/transit.md)
 - 🎫 [api/tokenization.md](api/tokenization.md)
 - 📜 [api/audit-logs.md](api/audit-logs.md)
+- 🚦 [api/rate-limiting.md](api/rate-limiting.md)
 - 🧱 [api/response-shapes.md](api/response-shapes.md)
 - 🧩 [api/versioning-policy.md](api/versioning-policy.md)
 - 📄 [openapi.yaml](openapi.yaml)
 
 OpenAPI scope note:
 
-- `openapi.yaml` is a baseline subset for common API flows in `v0.4.1`
+- `openapi.yaml` is a baseline subset for common API flows in `v0.5.0`
 - Full endpoint behavior is documented in the endpoint pages under `docs/api/`
-- Tokenization endpoints are included in `openapi.yaml` for `v0.4.1`
+- Tokenization endpoints are included in `openapi.yaml` for `v0.5.0`
 
 ## 🚀 Releases
 
-- 📦 [releases/v0.4.1.md](releases/v0.4.1.md)
+- 📦 [releases/v0.5.0.md](releases/v0.5.0.md)
+- ⬆️ [releases/v0.5.0-upgrade.md](releases/v0.5.0-upgrade.md)
+- 🔁 [releases/compatibility-matrix.md](releases/compatibility-matrix.md)
+- 📦 [releases/v0.4.1.md](releases/v0.4.1.md) (historical)
 - 📦 [releases/v0.4.0.md](releases/v0.4.0.md) (historical)
 - 📦 [releases/v0.3.0.md](releases/v0.3.0.md) (historical)
 - 📦 [releases/v0.2.0.md](releases/v0.2.0.md) (historical)