Skip to content

CHANGELOG.md

Latest commit

 

History

History
491 lines (380 loc) · 24.7 KB

CHANGELOG.md

File metadata and controls

491 lines (380 loc) · 24.7 KB

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.28.0 - 2026-03-23

Added

  • Added configurable batch limit for tokenize and detokenize operations via BATCH_LIMIT_TOKENIZATION environment variable.
  • Added individual transit key retrieval API (GET /v1/transit/keys/{name}) (#115).
  • Added atomic batch tokenize and detokenize endpoints (POST /v1/tokenization/tokenize/batch, POST /v1/tokenization/detokenize/batch) (#119).
  • Added individual tokenization key retrieval API by name (GET /v1/tokenization/keys/{name}) (#116).
  • Added audit log filtering by client_id for GET /v1/audit/logs (#118).
  • Added configurable Metrics Server timeouts (METRICS_SERVER_READ_TIMEOUT, METRICS_SERVER_WRITE_TIMEOUT, METRICS_SERVER_IDLE_TIMEOUT) (#114).
  • Added database connection max idle time configuration (DB_CONN_MAX_IDLE_TIME) (#113).
  • Added client secret rotation with automatic token revocation.
  • Added strict capability validation for policies (#111).

Changed

  • Updated Transit Engine to support key deletion by name instead of UUID (#120).
  • Updated Tokenization Engine to support key deletion by name (#117).

Fixed

  • Fixed rate limiter goroutine lifecycle and resource leaks (#112).

0.27.0 - 2026-03-06

Added

  • Added global SECRET_VALUE_SIZE_LIMIT_BYTES (default 512KB) to prevent DoS attacks via excessively large secret payloads.
  • Added global HTTP request payload size limit middleware (MAX_REQUEST_BODY_SIZE, default 1MB).
  • Added Auth Token Revocation endpoints (DELETE /v1/token, DELETE /v1/clients/:id/tokens), state tracking in the database, and purge-auth-tokens CLI command.
  • Added optional AEAD context parameter for Transit key encryption and decryption to cryptographically bind ciphertext to additional context data.

0.26.0 - 2026-03-04

Added

  • Added purge-transit-keys and purge-tokenization-keys CLI commands with dry-run and formatting support for permanently deleting soft-deleted keys.

0.25.0 - 2026-03-03

Added

  • Added secret purge command (purge-secrets) with dry-run and formatting support.
  • Added configurable server read/write/idle timeouts for better resource management and security.
  • Added KMS connectivity validation at server startup.
  • Added security scanning tools to CI and development workflow.
  • Updated documentation and CI configuration to enforce coverage and code quality standards.

Fixed

  • Corrected rotate-master-key CLI flags (kms-provider and kms-key-uri) and documentation to ensure consistency and completeness.
  • Fixed integration tests setup by separating them out from unit tests.

0.24.0 - 2026-03-03

Changed

  • Refactored tokenization module to improve security for deterministic mode by adding per-key version salts and HMAC-SHA256 keyed hashing to prevent rainbow table attacks.

0.23.0 - 2026-03-02

Added

  • Added configuration validation for improved reliability and error detection at startup.

Changed

  • Refactored transit module to improve security, atomicity, and validation rules.
  • Refactored tokenization module to remove unused TxManager and improve test utilities.
  • Refactored crypto module: moved KMSService to domain and enhanced key security.
  • Refactored internal package to inject context into the DI container for better lifecycle management.
  • Refactored database layer to improve transaction management and connection pool settings.
  • Refactored http layer to refine metrics server, middleware logic, and error wrapping.
  • Refactored cli commands to standardize implementation and reduce boilerplate.
  • Refactored httputil to improve error handling.
  • Reorganized and refactored documentation structure for improved clarity and consistency.
  • Improved metrics provider, secret security, and core domain logic.

0.22.1 - 2026-02-28

Fixed

  • Corrected Goreleaser configuration to properly inject build metadata (buildDate, commitSHA) into the binary.

0.22.0 - 2026-02-28

Added

  • Added MaxTransitKeyNameLength (255 characters) constraint for transit key names to ensure database compatibility.
  • Added metrics decoration for transit and tokenization usecases for improved observability.
  • New internal testing helpers and DSN getter functions in the integration test suite.

Changed

  • Refactored tokenization domain models, repositories, and generators (Alphanumeric, Luhn, Numeric) for better maintainability and performance.
  • Reorganized transit domain models and added comprehensive unit tests for TransitKey.
  • Updated Go version to 1.26.0 in CI workflows and documentation.

Fixed

  • Corrected rotate-master-key CLI flags and documentation in scaling guides.
  • Improved error handling in transit cryptographic operations.

[0.21.0] - 2026-02-28

Added

  • Binary releases are now officially supported as a primary installation method.

Changed

  • Refactored CLI command structure: individual command files moved to cmd/app/commands/ for better maintainability.

[0.20.0] - 2026-02-28

Added

  • Upgraded to Go 1.26.0

Fixed

  • Corrected verify-audit-logs CLI documentation for time range validation and output format consistency
  • Fixed documentation for master key rotation to clarify environment variable update workflow
  • Corrected outdated environment variable names and default values in scaling guides

0.19.0 - 2026-02-27

⚠️ BREAKING CHANGES

  • KMS mode is now required. Legacy plaintext master key mode has been removed. All deployments must use a KMS provider (localsecrets, gcpkms, awskms, azurekeyvault, or hashivault).
  • create-master-key command now requires --kms-provider and --kms-key-uri flags (previously optional).
  • For local development, use localsecrets provider with base64key:// URIs.

Removed

  • Removed legacy plaintext master key loading (LoadMasterKeyChainFromEnv function)
  • Removed docs/operations/kms/plaintext-to-kms-migration.md (no longer applicable)

Changed

  • Updated all documentation to reflect KMS-only mode
  • .env.example now defaults to localsecrets provider for local development
  • Error messages updated to indicate KMS is required

Migration Guide

  • Existing users on v0.18.0 with plaintext master keys must migrate to KMS mode before upgrading
  • See docs/operations/kms/setup.md for KMS setup instructions
  • For local development: generate a KMS key with openssl rand -base64 32 and use localsecrets provider

0.18.0 - 2026-02-27

Changed

  • Refactored repository layer architecture by reorganizing database-specific implementations into dedicated mysql/ and postgresql/ subdirectories across all modules (auth, crypto, secrets, tokenization, transit). This improves code maintainability and enforces clearer separation of concerns.

0.17.0 - 2026-02-25

Changed

  • Standardized pagination logic (offset, limit) across all listing endpoints using a centralized parser in httputil

0.16.0 - 2026-02-25

Added

  • Added listing endpoints with pagination (offset, limit) for secrets (GET /v1/secrets), transit keys (GET /v1/transit/keys), and tokenization keys (GET /v1/tokenization/keys)
  • Added list DTO structures for consistent API responses across modules

0.15.0 - 2026-02-25

Added

  • Goreleaser support for automated cross-platform builds and releases.

0.14.1 - 2026-02-25

Fixed

  • Fixed panic in NewKekChain and missing error handling in Unwrap when no KEKs are found

0.14.0 - 2026-02-25

Added

  • Dedicated metrics server running on a separate port for improved security
  • METRICS_PORT environment variable (default 8081) to configure the metrics server port

Changed

  • The /metrics endpoint is no longer exposed on the main application port (8080), it is now bound to the metrics port (8081)
  • Updated deployment examples (Docker Compose, etc.) to expose and configure the new metrics port

Security

  • Strongly decouples internal telemetry from user-facing APIs, preventing accidental exposure of implementation details

0.13.0 - 2026-02-25

Documentation Context

  • Massive refactoring of documentation structure to comply with the Diátaxis framework, significantly reducing text bloat.
  • Extracted large code blocks from narrative configuration guides into centralized docs/examples/.
  • Consolidated overlapping operations and security guides into a single docs/operations/deployment/docker-hardened.md guide.
  • Pruned docs/releases/RELEASES.md into a pure changelog, removing embedded runtime troubleshooting and point-in-time deployment migration steps.
  • Centralized docs/operations/troubleshooting/index.md as the unified source for FAQ and debugging steps.
  • Pruned CLI tutorial sections from the docs/operations/kms/setup.md guide.

0.12.0 - 2026-02-24

Added

  • rewrap-deks CLI command to bulk re-encrypt existing Data Encryption Keys (DEKs) with a specific KEK version

0.11.0 - 2026-02-23

Added

  • Persistent account lockout to prevent brute-force attacks against POST /v1/token
  • Account lockout: clients are locked for 30 minutes after 10 consecutive failed authentication attempts
  • LOCKOUT_MAX_ATTEMPTS environment variable (default 10)
  • LOCKOUT_DURATION_MINUTES environment variable (default 30)
  • 423 Locked HTTP response with "error": "client_locked" when a client is locked
  • Database migration 000004_add_account_lockout

Changed

  • Failed attempt counter and lock expiry are reset automatically on successful authentication

Security

  • Complements the existing IP-based rate limiting on POST /v1/token with per-client identity lockout

Documentation

  • Added account lockout behavior to docs/api/auth/authentication.md
  • Added configuration reference for lockout to docs/configuration.md

0.10.0 - 2026-02-21

Added

  • Docker image security improvements with Google Distroless base (Debian 13 Trixie)
  • SHA256 digest pinning for immutable container builds
  • Build-time version injection via ldflags (version, buildDate, commitSHA)
  • Comprehensive OCI labels for better security scanning and SBOM generation
  • Multi-architecture build support (linux/amd64, linux/arm64) in Dockerfile
  • .dockerignore file to reduce build context size by ~90%
  • Explicit non-root user execution (UID 65532: nonroot:nonroot)
  • Read-only filesystem support for enhanced runtime security
  • Container security documentation: docs/operations/deployment/docker-hardened.md
  • Health check endpoint documentation for Kubernetes and Docker Compose
  • GitHub Actions workflow enhancements for build metadata injection
  • Version management guidelines in AGENTS.md for coding agents

Changed

  • Base builder image: golang:1.25.5-alpine → golang:1.25.5-trixie (Debian 13)
  • Final runtime image: scratch → gcr.io/distroless/static-debian13@sha256:d90359c7a3ad67b3c11ca44fd5f3f5208cbef546f2e692b0dc3410a869de46bf
  • Application version management: hardcoded → build-time injection
  • Docker image now includes default CMD ["server"] for better UX
  • Updated docs/getting-started/docker.md with security features and health check examples

Removed

  • Manual migration directory copy (now embedded in binary via Go embed.FS)
  • Manual CA certificates and timezone data copy (included in distroless)

Security

  • BREAKING: Container now runs as non-root user (UID 65532) by default
  • Minimal attack surface: no shell, package manager, or system utilities in final image
  • Regular security patches from Google Distroless project
  • Immutable builds with SHA256 digest pinning prevent supply chain attacks
  • Enhanced CVE scanning support with comprehensive OCI metadata
  • Image size reduced by 10-20% while improving security posture

Documentation

  • Added comprehensive container security guide (docs/operations/deployment/docker-hardened.md) with 10 sections covering base image security, runtime security, network security, secrets management, image scanning, health checks, build security, and deployment best practices
  • Added complete health check guide (docs/operations/observability/health-checks.md) with platform integrations for Kubernetes, Docker Compose, AWS ECS, Google Cloud Run, and monitoring tools
  • Added security scanning guide (docs/operations/security/scanning.md) covering Trivy, Docker Scout, Grype, SBOM generation, and CI/CD integration
  • Added oci labels reference (docs/operations/deployment/oci-labels.md) documenting image metadata schema for security scanning and compliance
  • Added kubernetes deployment guide (docs/operations/deployment/kubernetes.md) with production-ready manifests and security hardening
  • Added docker compose deployment guide (docs/operations/deployment/docker-compose.md) with development and production configurations
  • Added multi-architecture builds guide (docs/operations/deployment/multi-arch-builds.md) for linux/amd64 and linux/arm64
  • Added base image migration guide (docs/operations/deployment/docker-hardened.md) for alpine/scratch to distroless transitions
  • Added volume permissions troubleshooting guide (docs/operations/troubleshooting/volume-permissions.md) for non-root container issues
  • Added error reference guide (docs/operations/troubleshooting/error-reference.md) with http, database, kms, and configuration errors
  • Pruned docs/releases/RELEASES.md to remove embedded runtime troubleshooting and point-in-time deployment migration steps.
  • Updated Docker quick start guide with security features overview and health check examples
  • Updated Dockerfile with comprehensive inline documentation (~180 comment lines)
  • Added version management guidelines in AGENTS.md for AI coding agents

0.9.0 - 2026-02-20

Added

  • Added cryptographic audit log signing with HMAC-SHA256 for tamper detection
  • Added HKDF-SHA256 key derivation to separate encryption and signing key usage
  • Added verify-audit-logs CLI command for batch integrity verification with text/JSON output
  • Added database columns: signature (BYTEA), kek_id (UUID FK), is_signed (BOOLEAN)
  • Added foreign key constraints: fk_audit_logs_client_id and fk_audit_logs_kek_id to prevent orphaned records
  • Added AuditSigner service for canonical log serialization and HMAC generation
  • Added test infrastructure: CreateTestClient() and CreateTestKek() helpers for FK-compliant testing

Changed

  • Audit logs now automatically signed on creation when KEK chain is available
  • Audit log API responses now include signature metadata (signature, kek_id, is_signed)
  • Database migration 000003 required (adds signature columns and FK constraints)

Fixed

  • Fixed 46 audit log repository tests to comply with FK constraints

Security

  • Enhanced audit log tamper detection with cryptographic integrity verification
  • Enforced data integrity with FK constraints preventing orphaned client/KEK references

Documentation

  • Updated docs/cli-commands.md with verify-audit-logs command
  • Updated docs/api/observability/audit-logs.md with signature field documentation
  • Added AGENTS.md guidelines for audit signer architecture and FK testing patterns

0.8.0 - 2026-02-20

Documentation

  • Documentation consolidation: reduced from 77 to 47 markdown files (39% reduction)
  • Established 8 new Architecture Decision Records (ADR 0003-0010) covering key architectural decisions
  • Restructured API documentation with themed subdirectories (auth/, data/, observability/)
  • Consolidated operations documentation with centralized runbook hub
  • Merged all development documentation into contributing.md
  • Comprehensive cross-reference updates throughout documentation (182+ updates)

0.7.0 - 2026-02-20

Added

  • Added IP-based rate limiting middleware for unauthenticated POST /v1/token
  • Added token endpoint rate-limit configuration via RATE_LIMIT_TOKEN_ENABLED, RATE_LIMIT_TOKEN_REQUESTS_PER_SEC, and RATE_LIMIT_TOKEN_BURST

Changed

  • Token issuance endpoint can now return 429 Too Many Requests with Retry-After when per-IP limits are exceeded

Security

  • Hardened token issuance path against credential stuffing and brute-force request bursts

Documentation

  • Updated docs for token endpoint throttling behavior, configuration, and troubleshooting guidance

0.6.0 - 2026-02-19

Added

  • Added KMS-backed master key support with KMS_PROVIDER and KMS_KEY_URI
  • Added rotate-master-key CLI command for staged master key rotation
  • Added create-master-key KMS flags: --kms-provider and --kms-key-uri
  • Added gocloud-based KMS service support for localsecrets, Google Cloud KMS, AWS KMS, Azure Key Vault, and HashiCorp Vault

Changed

  • Master key loading now auto-detects KMS mode vs legacy mode and validates KMS configuration consistency at startup

Security

  • Added encrypted-at-rest master key workflow through external KMS providers
  • Added startup validation and error paths for incomplete KMS configuration and decryption failures

Documentation

  • Added KMS operations guide: docs/operations/kms/setup.md
  • Updated CLI and environment variable docs for KMS configuration and master key rotation workflows

[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

  • Updated current release references and pinned examples to v0.5.1

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/deployment/docker-hardened.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/deployment/docker-hardened.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/deployment/docker-hardened.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/observability/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