feat: resolve cache stampede, encryption at rest, pool monitoring, and token refresh (#518, #519, #520, #521)

[ngoziimmaculatar-star]

Summary of Changes

This pull request resolves issues #518, #519, #520, and #521 across caching, database security, connection pool observability, and authentication.

1. Cache Stampede Protection (Closes #518)

• Created src/cache/stampede.js and src/cache/index.js with:
  • SingleFlight: In-process promise coalescing to deduplicate concurrent requests for the same key.
  • Distributed Redis Locking: Mutex lock with atomic compare-and-delete release script and polling/backoff.
  • Background Refresh: Stale-while-revalidate capability to serve cached data while asynchronously refreshing expired entries under lock.
• Integrated fetchWithLock into src/services/dbCache.js to protect database queries against thundering herd stampedes on cache expiry.
• Added comprehensive unit tests in test/cacheStampede.test.js.

2. Database Encryption at Rest (Closes #519)

• Implemented authenticated field-level AES-256-GCM encryption in src/database/encryption.js.
• Deterministic prefix enc:v1:<iv>:<ciphertext>:<authTag> for reliable detection and transparent legacy plaintext compatibility.
• Added support for record/row encryption and decryption (encryptRecord, decryptRecord, encryptRows, decryptRows).
• Added deterministic HMAC-SHA256 blind indexing (hashBlindIndex) to allow exact-match queries on encrypted sensitive columns.
• Added DB_ENCRYPTION_KEY configuration to src/config.js.
• Exported encryption utilities through src/database/index.js.
• Added comprehensive unit tests in test/databaseEncryption.test.js.

3. Database Connection Pool Monitoring (Closes #520)

• Implemented PoolMonitor in src/database/poolMonitor.js tracking:
  • Tarn.js connection pool events (acquireRequest, acquireSuccess, acquireFail, release, createRequest, createSuccess, createFail, destroyRequest, destroySuccess).
  • Cumulative counters for acquire attempts, successes, failures, creates, and releases.
  • Latency tracking (average, max, last duration).
  • Pool utilization ratio and saturation.
  • Health status (healthy, warning, critical) with configurable threshold alert callbacks.
  • Standard Prometheus exposition format exporter (toPrometheusMetrics()).
• Wired pool monitoring into src/database/index.js (getPoolStats(), getPoolMetrics(), auto-attach on pool creation).
• Integrated database connection pool Prometheus metrics into src/routes/metrics.js for the /metrics endpoint.
• Added comprehensive unit tests in test/poolMonitor.test.js.

4. Token Refresh Mechanism (Closes #521)

• Implemented JWT signing and token refresh with Refresh Token Rotation (RTR) in src/auth/tokenRefresh.js.
• Generates cryptographically secure access tokens (short-lived JWTs) and refresh tokens (SHA-256 hashed at rest).
• Implemented automatic token family reuse detection (revokes entire token family if an already-used token is reused).
• Added Express handlers createRefreshHandler and createRevokeHandler for POST /auth/refresh and POST /auth/revoke.
• Exported from src/auth/index.js and src/auth/authService.js.
• Added comprehensive unit tests in test/tokenRefresh.test.js.

Closes #518
Closes #519
Closes #520
Closes #521

[drips-wave]

@ngoziimmaculatar-star Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits