Feedemy.KeyManagement 3.2.1

• net10.0

  • Azure.Identity (>= 1.18.0)
  • Azure.Security.KeyVault.Secrets (>= 4.9.0)
  • Microsoft.Data.SqlClient (>= 6.1.4)
  • Microsoft.Data.Sqlite (>= 10.0.3)
  • Microsoft.EntityFrameworkCore.Abstractions (>= 10.0.3)
  • Microsoft.Extensions.Caching.Abstractions (>= 10.0.3)
  • Microsoft.Extensions.Caching.Memory (>= 10.0.3)
  • Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.3)
  • Microsoft.Extensions.Diagnostics.HealthChecks (>= 10.0.3)
  • Microsoft.Extensions.Hosting (>= 10.0.3)
  • Microsoft.Extensions.Hosting.Abstractions (>= 10.0.3)
  • Microsoft.Extensions.Logging.Abstractions (>= 10.0.3)
  • Microsoft.Extensions.Options (>= 10.0.3)
  • OpenTelemetry.Api (>= 1.15.0)
  • Polly (>= 8.6.5)
  • StackExchange.Redis (>= 2.11.8)

v3.2.1 — Hotfix: Private L1 cache (do not configure shared IMemoryCache)

v3.2.0 called services.AddMemoryCache(opts => { opts.SizeLimit = ... })
which reconfigured the SHARED DI-wide IMemoryCache singleton. Any host
application that also uses IMemoryCache for its own purposes was forced
to call SetSize(...) on every Set() call (otherwise InvalidOperationException).
This was a real breaking change that slipped through "zero breaking" testing.

Fix in 3.2.1:
- Introduced FeedemyKeyManagementMemoryCache (sealed, inherits MemoryCache).
 Library now owns its own private cache instance registered in DI by its
 concrete type.
- MemoryCacheProvider and KeyCacheService are registered via factory methods
 that inject the private cache, NOT the shared IMemoryCache.
- services.AddMemoryCache(...) is no longer called by the library; the host
 application's shared IMemoryCache registration (if any) is left untouched.

Upgrade from 3.2.0: drop-in. If you applied a PostConfigure<MemoryCacheOptions>
workaround to null out SizeLimit, you can remove it.

-----

v3.2.0 — Bench-Driven Reliability & Scalability Release

Produced by a 90-scenario benchmark harness (bench/ + BenchNode) and 3 h
of sustained endurance load. 31 findings documented, 21 fixed in 10 PRs,
zero breaking changes.

NEW APIS (additive):
- SecretFileKeyStorageProvider: raw-key storage for Docker Swarm / K8s
 secret mounts. Fixes the multi-node /etc/machine-id derivation trap
 (finding #3). Fluent: WithSecretFileKeyStorage("/run/secrets").
- LinuxStorageOptions: KeyringPath, SaltPath, MachineKeySource (MachineId|
 Hostname|Environment|File), EnvironmentVariableName, FilePath.
- WithLinuxKeyStorage(Action<LinuxStorageOptions>?) overload;
 parameterless overload still resolves to default.
- ExternalKeyPairDto: public record for external asymmetric key import
 (finding #17 — schema was undocumented).
- Paged repository APIs on all three repositories:
 GetPagedAsync(skip,take), GetDueForRotationPagedAsync(threshold),
 GetActiveCountAsync, GetByKeyNamePagedAsync (audit),
 GetActiveVersionCountsAsync (batched GROUP BY — kills N+1).
- PagedResult<T> model.
- KeyManagementOptions.AutoBootstrapMasterKey (default true): startup
 now creates the master EncryptionKey if missing; consumers no longer
 have to manually seed before first asymmetric create.
- KeyManagementOptions.Cache.L1MaxSize (default 100_000 units) +
 L1CompactionPercentage (default 0.25): bounded L1 IMemoryCache.
- 2 new telemetry histograms:
 keymanagement.cache.invalidation.publish.duration (ms)
 keymanagement.cache.invalidation.receive.duration (ms)
- ErrorCodes.MASTER_KEY_MISSING.

CRITICAL FIXES:
- #28 MasterKeyProvider cache stampede: per-version SemaphoreSlim +
 atomic InvalidateCache + deferred ZeroMemory. Closes the 1 h-endurance
 race that silently returned null for ~2767 reads per run.
- #29 Unbounded IMemoryCache: SizeLimit + SetSize across all five entry
 types. Working set dropped from 6.1 GB to bounded after sustained load.
- #11 Admin API O(N) scan: pagination + SQL-level filtering throughout.
 SystemHealthAsync goes from 20 k SQL queries (N+1) to 2 (single
 GROUP BY). At 5 k keys, p99 drops from 2-4 s to <100 ms.
- #1 Asymmetric silent master key dependency: auto-bootstrap hosted
 service + clean Result.Fail(MASTER_KEY_MISSING) precondition.
 Fresh deployments no longer crash on first RSA/ECDSA create.
- #3 Multi-node /etc/machine-id trap: addressed via SecretFileKeyStorage
 (primary recommendation) or LinuxStorageOptions.MachineKeySource
 override.
- #4 PostgreSQL schema init race: DatabaseMigrator now acquires
 pg_advisory_xact_lock("KMMG") on the migration transaction. Three
 replicas converge cleanly instead of racing on CREATE TABLE.
- #31 Rotation-retrieve race (regression surfaced by #28 fix):
 RetrieveKeyAsync falls back to version-1 when the new version is
 committed to DB but not yet written to storage. Closes the
 "DB-ahead-of-storage" window (~6.4 % gap under concurrent retrieve +
 rotate) transparently.

CONTRACT & BEHAVIOR FIXES:
- #16 RSA oversized plaintext: ArgumentException → CryptographicException
 (honors IAsymmetricKeyOperations XML doc).
- #25 Public key re-fetch write amplification: dedicated 15-min L1
 cache replaces per-read metadata.UpdateAsync (eliminated
 DbUpdateConcurrencyException under concurrent reads).
- #23 GetECDsaAsync raw accessor: ImportPkcs8PrivateKey errors wrapped
 with InvalidOperationException + meaningful context.
- #27 Fresh asymmetric GetCurrentVersionAsync: bypass metadata cache
 (L2 round-trip was corrupting large PublicKeyPem fields).
- #9 WithRedisCache implicitly enables EnableCacheInvalidationListener
 (opt-out still possible by explicit override).
- #12 EncryptionTotal Prometheus counter: now emits on both symmetric
 and asymmetric success paths (was a dead counter).

NEW DOCS:
- docs/claude/telemetry.md — OTel ↔ Prometheus naming reference, meter
 inventory, PromQL + Grafana snippets.
- docs/claude/security-model.md — threat matrix, per-provider guarantees
 (cold disk, container escape, host root, memory dump, network), and
 mitigation roadmap (Vault Transit, TPM sealed key, PKCS#11 softHSM).
- Expanded XML docs: LinuxKeyringStorageProvider misnomer warning,
 CreateKeyAsync concurrent-duplicate contract, RotationCheckInterval
 validation message, CreateKeyRequest.ExternalAsymmetricKeyPair schema
 (with JSON example).

UPGRADE:
Drop-in: all public APIs are additive; no signature changes. Consumers
that relied on the dead EncryptionTotal counter will now see non-zero
values. Consumers configuring Redis via WithRedisCache() will have
the cache invalidation listener enabled automatically — set
EnableCacheInvalidationListener=false explicitly to preserve the
pre-3.2 behavior.

VERIFICATION:
- 54+ unit tests pass (solution-wide 0 errors).
- Bench 69/69 scenarios green, 0 violations (was 11+ violations in
 pre-fix runs). S34 master-key-race endurance 0 bad (was 2767).
- See docs/claude/bench-findings-verified-2026-04-24.md for the full
 verification matrix.
----

v3.0.0 - Major Security, Performance & Stability Release

SECURITY (CRITICAL):
- Fixed SQL injection in PostgreSQL DatabaseMigrator (parameterized queries via NpgsqlParameter)
- Fixed plaintext Azure credential storage on Linux (AES-256-GCM encryption with machine-derived key)
- AES-GCM AAD bypass mitigation (AllowLegacyNoAadDecryption option, default false)
- DPAPI application-specific entropy ("Feedemy.KeyManagement.v1") with legacy auto-migration
- Linux per-installation random salt with .salt.bak backup/recovery chain
- Linux key re-encryption safety: write-read-verify with FixedTimeEquals, .migrating transactional backup
- Linux RetrieveKeyAsync TOCTOU fix (File.Exists moved inside lock)
- Credential JSON secure deletion after import (random-overwrite + File.Delete)
- CryptographicOperations.ZeroMemory throughout all sensitive byte array paths (12+ locations)
- IDisposable for WindowsDpapiStorageProvider, FallbackStorageProvider, MasterKeyProvider

PERFORMANCE:
- MasterKeyProvider in-memory cache with 5-min TTL (eliminates 2 IO round-trips per decryption)
- MasterKeyProvider.InvalidateCache() called after master key rotation for cache coherence
- Source-generated logging ([LoggerMessage]) for retrieval hot path
- TagList zero-allocation telemetry, Span-based IsEncryptedFormat detection
- Prefix-based cache pattern removal fast path (bypasses regex for simple patterns)
- Health check response caching (30s TTL with SemaphoreSlim double-check)
- RandomNumberGenerator.Fill / SHA256.HashData static APIs (no instance allocation)
- RegexOptions.None instead of Compiled (prevents assembly leak)
- Volatile.Read for FallbackStorageProvider._consecutiveFailures (prevents torn reads)
- Atomic RetrievalLockEntry.Dispose via Interlocked.CompareExchange
- Static eviction callback in KeyCacheService (eliminates closure allocation)

FIXED:
- Startup crash risks shifted behind DI build (ConfigurationValidationHostedService)
- Background services opt-in by default (EnableAutoRotation, EnableCacheInvalidationListener, EnableFallbackSync)
- CacheInvalidationListener resiliency with bounded retry and exponential backoff
- Double pub/sub removed from InvalidateAllVersionsAsync
- Startup ordering fixed for ServicesStartConcurrently=true
- UseAzureDefaults production safety: metadata provider validation enforced
- Rollback log level: successful rollback now logs Warning instead of Critical
- ConfigurationEnumMappings default cases now throw ArgumentOutOfRangeException
- Fire-and-forget defensive copy in FallbackStorageProvider.SyncToFallbackAsync

BREAKING CHANGES:
- OperationResult<T> now immutable (init-only properties), Warnings is IReadOnlyList<string>
- IKeyMetadataRepository has new required members (ExistsIncludingInactiveAsync, GetByKeyNameAsync)
- IMasterKeyProvider has new InvalidateCache() method (custom implementations must add it)
- MasterKeyProvider now implements IDisposable
- Background services opt-in by default
- UseAzureDefaults() requires persistent metadata provider
- GetByNameAsync/ExistsAsync targets active records by default
- See CHANGELOG.md and docs/MIGRATION_GUIDE.md for full migration guide