fix: preserve master key material after load

CHANGELOG.md

@@ -5,6 +5,20 @@ 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.1] - 2026-02-19
+
+### Fixed
+- Fixed master key loading from `MASTER_KEYS` so decoded key material remains usable after secure buffer zeroing
+- Fixed `MasterKeyChain.Close()` to zero all in-memory master keys before clearing chain state
+
+### Security
+- Hardened master key memory lifecycle by zeroing temporary decode buffers and keychain-resident keys on teardown
+- Added regression tests for key usability-after-load and key zeroing-on-close behavior
+
+### Documentation
+- Added `docs/releases/v0.5.1.md` release notes and `docs/releases/v0.5.1-upgrade.md` upgrade guide
+- Updated current release references and pinned examples to `v0.5.1`
+
 ## [0.5.0] - 2026-02-19
 
 ### Added

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.5.0
+docker pull allisson/secrets:v0.5.1
 ```
 
 Use pinned tags for reproducible setups. `latest` is also available for fast iteration.
@@ -29,15 +29,20 @@ 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.5.0
+## 🆕 What's New in v0.5.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`
+- 🛠️ Fixed master key loading to preserve usable key material while zeroing temporary decoded buffers
+- 🧹 Hardened keychain teardown to zero in-memory master keys before clearing chain state
+- 🔒 Expanded regression coverage for master key memory lifecycle and close behavior
+- 📘 Added release notes: [docs/releases/v0.5.1.md](docs/releases/v0.5.1.md)
+- ⬆️ Added upgrade guide: [docs/releases/v0.5.1-upgrade.md](docs/releases/v0.5.1-upgrade.md)
+- 📦 Updated pinned Docker docs/examples to `allisson/secrets:v0.5.1`
+
+Release history quick links:
+
+- Current: [v0.5.1 release notes](docs/releases/v0.5.1.md)
+- Previous: [v0.5.0 release notes](docs/releases/v0.5.0.md)
+- Previous upgrade guide: [v0.5.0 upgrade guide](docs/releases/v0.5.0-upgrade.md)
 
 ## 📚 Docs Map
 
@@ -48,8 +53,8 @@ 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.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)
+- 🚀 **v0.5.1 release notes**: [docs/releases/v0.5.1.md](docs/releases/v0.5.1.md)
+- ⬆️ **v0.5.1 upgrade guide**: [docs/releases/v0.5.1-upgrade.md](docs/releases/v0.5.1-upgrade.md)
 - 🔁 **Release compatibility matrix**: [docs/releases/compatibility-matrix.md](docs/releases/compatibility-matrix.md)
 
 - **By Topic**

docs/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 > Last updated: 2026-02-19
 
+## 2026-02-19 (docs v11 - v0.5.1 patch release prep)
+
+- Added release notes page: `docs/releases/v0.5.1.md`
+- Added upgrade guide: `docs/releases/v0.5.1-upgrade.md`
+- Updated docs metadata source (`docs/metadata.json`) to `current_release: v0.5.1`
+- Updated root README and docs index to promote `v0.5.1` release links
+- Updated operator runbook index and production runbooks to reference `v0.5.1`
+- Updated compatibility matrix with `v0.5.0 -> v0.5.1` patch upgrade path
+- Added direct `v0.4.x -> v0.5.1` compatibility path for skip-upgrade operators
+- Updated pinned Docker image examples from `allisson/secrets:v0.5.0` to `allisson/secrets:v0.5.1`
+- Updated API docs release labels to `v0.5.1` where current-release references are shown
+- Reduced patch-version churn in OpenAPI coverage notes by using current-release wording
+- Added v0.5.1-specific master-key regression triage note to troubleshooting
+- Added copy/paste quick verification commands to `docs/releases/v0.5.1-upgrade.md`
+- Added patch-release safety note to `docs/releases/v0.5.1.md`
+- Added release history quick links in root `README.md`
+- Added runtime version fingerprint checks for mixed deployment triage
+
 ## 2026-02-19 (docs v10 - v0.5.0 security hardening release prep)
 
 - Added comprehensive security hardening guide: `docs/operations/security-hardening.md`

docs/README.md

@@ -70,14 +70,16 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 
 OpenAPI scope note:
 
-- `openapi.yaml` is a baseline subset for common API flows in `v0.5.0`
+- `openapi.yaml` is a baseline subset for common API flows in the current release (`docs/metadata.json`)
 - Full endpoint behavior is documented in the endpoint pages under `docs/api/`
-- Tokenization endpoints are included in `openapi.yaml` for `v0.5.0`
+- Tokenization endpoints are included in `openapi.yaml` for the current release
 
 ## 🚀 Releases
 
-- 📦 [releases/v0.5.0.md](releases/v0.5.0.md)
-- ⬆️ [releases/v0.5.0-upgrade.md](releases/v0.5.0-upgrade.md)
+- 📦 [releases/v0.5.1.md](releases/v0.5.1.md)
+- ⬆️ [releases/v0.5.1-upgrade.md](releases/v0.5.1-upgrade.md)
+- 📦 [releases/v0.5.0.md](releases/v0.5.0.md) (historical)
+- ⬆️ [releases/v0.5.0-upgrade.md](releases/v0.5.0-upgrade.md) (historical)
 - 🔁 [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)

docs/api/tokenization.md

@@ -14,7 +14,7 @@ with optional deterministic behavior and token lifecycle management.
 
 OpenAPI coverage note:
 
-- Tokenization endpoint coverage is included in `docs/openapi.yaml` for `v0.5.0`
+- Tokenization endpoint coverage is included in `docs/openapi.yaml` for the current release
 - This page remains the most detailed contract reference with examples and operational guidance
 
 All endpoints require `Authorization: Bearer <token>`.

docs/api/versioning-policy.md

@@ -11,17 +11,17 @@ This page defines compatibility expectations for HTTP API changes.
 - Existing endpoint paths and JSON field names are treated as stable unless explicitly deprecated
 - OpenAPI source of truth: `docs/openapi.yaml`
 
-## OpenAPI Coverage (v0.5.0)
+## OpenAPI Coverage
 
 - `docs/openapi.yaml` is a baseline subset focused on high-traffic/common integration flows
-- `docs/openapi.yaml` includes tokenization endpoint coverage in `v0.5.0`
+- `docs/openapi.yaml` includes tokenization endpoint coverage in the current release
 - `docs/openapi.yaml` includes `429 Too Many Requests` response modeling for protected routes
 - Endpoint pages in `docs/api/*.md` define full public behavior for covered operations
 - Endpoints may exist in runtime before they are expanded in OpenAPI detail
 
 ## App Version vs API Version
 
-- Application release `v0.5.0` is pre-1.0 software and may evolve quickly
+- Application release is pre-1.0 software and may evolve quickly
 - API v1 path contract (`/v1/*`) remains the compatibility baseline for consumers
 - Breaking API behavior changes require explicit documentation and migration notes
 

docs/cli/commands.md

@@ -12,10 +12,10 @@ Local binary:
 ./bin/app <command> [flags]
 ```
 
-Docker image (v0.5.0):
+Docker image (v0.5.1):
 
 ```bash
-docker run --rm --env-file .env allisson/secrets:v0.5.0 <command> [flags]
+docker run --rm --env-file .env allisson/secrets:v0.5.1 <command> [flags]
 ```
 
 ## Core Runtime
@@ -33,7 +33,7 @@ Local:
 Docker:
 
 ```bash
-docker run --rm --network secrets-net --env-file .env -p 8080:8080 allisson/secrets:v0.5.0 server
+docker run --rm --network secrets-net --env-file .env -p 8080:8080 allisson/secrets:v0.5.1 server
 ```
 
 ### `migrate`
@@ -49,7 +49,7 @@ Local:
 Docker:
 
 ```bash
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 migrate
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 migrate
 ```
 
 ## Key Management
@@ -71,7 +71,7 @@ Local:
 Docker:
 
 ```bash
-docker run --rm allisson/secrets:v0.5.0 create-master-key --id default
+docker run --rm allisson/secrets:v0.5.1 create-master-key --id default
 ```
 
 ### `create-kek`
@@ -91,7 +91,7 @@ Local:
 Docker:
 
 ```bash
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 create-kek --algorithm aes-gcm
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 create-kek --algorithm aes-gcm
 ```
 
 ### `rotate-kek`
@@ -111,7 +111,7 @@ Local:
 Docker:
 
 ```bash
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 rotate-kek --algorithm aes-gcm
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 rotate-kek --algorithm aes-gcm
 ```
 
 After master key or KEK rotation, restart API server instances so they load updated key material.
@@ -138,7 +138,7 @@ Examples:
   --deterministic \
   --algorithm aes-gcm
 
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 \
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 \
   create-tokenization-key --name payment-cards --format luhn-preserving --deterministic --algorithm aes-gcm
 ```
 
@@ -162,7 +162,7 @@ Examples:
   --deterministic \
   --algorithm chacha20-poly1305
 
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 \
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 \
   rotate-tokenization-key --name payment-cards --format luhn-preserving --deterministic --algorithm chacha20-poly1305
 ```
 
@@ -186,7 +186,7 @@ Examples:
 ./bin/app clean-expired-tokens --days 30 --format text
 
 # Docker form
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 \
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 \
   clean-expired-tokens --days 30 --dry-run --format json
 ```
 
@@ -269,7 +269,7 @@ Examples:
 ./bin/app clean-audit-logs --days 90 --format text
 
 # Docker form
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 \
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 \
   clean-audit-logs --days 90 --dry-run --format json
 
 ```

docs/getting-started/docker.md

@@ -4,25 +4,27 @@
 
 This is the default way to run Secrets.
 
-For release reproducibility, this guide uses the pinned image tag `allisson/secrets:v0.5.0`.
+For release reproducibility, this guide uses the pinned image tag `allisson/secrets:v0.5.1`.
 You can use `allisson/secrets:latest` for fast iteration.
 
 **⚠️ Security Warning:** This guide is for **development and testing only**. For production deployments, see [Security Hardening Guide](../operations/security-hardening.md) and [Production Deployment Guide](../operations/production.md).
 
-## v0.5.0 Security Defaults
+## Current Security Defaults
 
-- `AUTH_TOKEN_EXPIRATION_SECONDS` default is now `14400` (4 hours)
+- `AUTH_TOKEN_EXPIRATION_SECONDS` default is `14400` (4 hours)
 - `RATE_LIMIT_ENABLED` default is `true` (per authenticated client)
 - `CORS_ENABLED` default is `false`
 
-If upgrading from `v0.4.x`, review [v0.5.0 upgrade guide](../releases/v0.5.0-upgrade.md).
+These defaults were introduced in `v0.5.0` and remain unchanged in `v0.5.1`.
+
+If upgrading from `v0.5.0`, review [v0.5.1 upgrade guide](../releases/v0.5.1-upgrade.md).
 
 ## ⚡ Quickstart Copy Block
 
 Use this minimal flow when you just want to get a working instance quickly:
 
 ```bash
-docker pull allisson/secrets:v0.5.0
+docker pull allisson/secrets:v0.5.1
 docker network create secrets-net || true
 
 docker run -d --name secrets-postgres --network secrets-net \
@@ -31,19 +33,19 @@ docker run -d --name secrets-postgres --network secrets-net \
   -e POSTGRES_DB=mydb \
   postgres:16-alpine
 
-docker run --rm allisson/secrets:v0.5.0 create-master-key --id default
+docker run --rm allisson/secrets:v0.5.1 create-master-key --id default
 # copy generated MASTER_KEYS and ACTIVE_MASTER_KEY_ID into .env
 
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 migrate
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 create-kek --algorithm aes-gcm
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 migrate
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 create-kek --algorithm aes-gcm
 docker run --rm --name secrets-api --network secrets-net --env-file .env -p 8080:8080 \
-  allisson/secrets:v0.5.0 server
+  allisson/secrets:v0.5.1 server
 ```
 
 ## 1) Pull the image
 
 ```bash
-docker pull allisson/secrets:v0.5.0
+docker pull allisson/secrets:v0.5.1
 ```
 
 ## 2) Start PostgreSQL
@@ -61,7 +63,7 @@ docker run -d --name secrets-postgres --network secrets-net \
 ## 3) Generate a master key
 
 ```bash
-docker run --rm allisson/secrets:v0.5.0 create-master-key --id default
+docker run --rm allisson/secrets:v0.5.1 create-master-key --id default
 ```
 
 Copy the generated values into a local `.env` file.
@@ -93,15 +95,15 @@ EOF
 ## 5) Run migrations and bootstrap KEK
 
 ```bash
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 migrate
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 create-kek --algorithm aes-gcm
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 migrate
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 create-kek --algorithm aes-gcm
 ```
 
 ## 6) Start the API server
 
 ```bash
 docker run --rm --name secrets-api --network secrets-net --env-file .env -p 8080:8080 \
-  allisson/secrets:v0.5.0 server
+  allisson/secrets:v0.5.1 server
 ```
 
 ## 7) Verify
@@ -121,7 +123,7 @@ Expected:
 Use the CLI command to create your first API client and policy set:
 
 ```bash
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.0 create-client \
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.5.1 create-client \
   --name bootstrap-admin \
   --active \
   --policies '[{"path":"*","capabilities":["read","write","delete","encrypt","decrypt","rotate"]}]' \

docs/getting-started/local-development.md

@@ -6,13 +6,15 @@ Use this path if you want to modify the source code and run from your workstatio
 
 **⚠️ Security Warning:** This guide is for **development and testing only**. For production deployments, see [Security Hardening Guide](../operations/security-hardening.md) and [Production Deployment Guide](../operations/production.md).
 
-## v0.5.0 Security Defaults
+## Current Security Defaults
 
-- `AUTH_TOKEN_EXPIRATION_SECONDS` default is now `14400` (4 hours)
+- `AUTH_TOKEN_EXPIRATION_SECONDS` default is `14400` (4 hours)
 - `RATE_LIMIT_ENABLED` default is `true` (per authenticated client)
 - `CORS_ENABLED` default is `false`
 
-If upgrading from `v0.4.x`, review [v0.5.0 upgrade guide](../releases/v0.5.0-upgrade.md).
+These defaults were introduced in `v0.5.0` and remain unchanged in `v0.5.1`.
+
+If upgrading from `v0.5.0`, review [v0.5.1 upgrade guide](../releases/v0.5.1-upgrade.md).
 
 ## Prerequisites
 

docs/getting-started/smoke-test.md

@@ -56,5 +56,5 @@ If transit decrypt fails with `422`, see [Troubleshooting](troubleshooting.md#42
 - [Docker getting started](docker.md)
 - [Local development](local-development.md)
 - [Troubleshooting](troubleshooting.md)
-- [v0.5.0 release notes](../releases/v0.5.0.md)
+- [v0.5.1 release notes](../releases/v0.5.1.md)
 - [Curl examples](../examples/curl.md)