feat: implement OpenAPI deprecation warnings, request signing, and Redis key expiration monitoring

[smokeylenz1-commits]

Summary

This PR resolves four issues by adding three production-ready features to the ProxyPay platform.

Closes #295
Closes #291
Closes #292
Closes #294

---

#245 — OpenAPI Deprecation Warnings for Old Endpoints

Files: src/middleware/deprecation.ts, src/openapi/deprecationHandler.ts

• DeprecationRegistry — Central registry for declaring deprecated endpoints at startup. Supports string/regex path matching and per-method filtering.
• deprecationMiddleware — Global Express middleware that auto-stamps responses with RFC 8594 (Sunset) and RFC 9110 (Deprecation) headers whenever a request hits a registered deprecated path.
• deprecate() — Per-route middleware factory for one-off deprecations without touching the registry.
• enhanceOpenApiWithDeprecations() — Post-processes the Zod-generated OpenAPI document: sets deprecated: true, adds x-sunset, x-deprecation-date, x-replacement extension fields, and appends migration guidance to operation descriptions.
• getDeprecationTimeline() — Returns a structured timeline of all deprecated endpoints for admin dashboards and automated changelog generation.

Response headers set on deprecated endpoints:

Deprecation: true  (or ISO date if deprecatedSince is supplied)
Sunset: <HTTP-date>
Link: <replacement>; rel="successor-version"
Warning: 299 - "<reason>"

---

#291 — Request Signing for High-Value Transactions

Files: src/utils/requestSigning.ts, src/middleware/requestSigningMiddleware.ts

Adds RSA-PSS cryptographic request signing for transactions above a configurable amount threshold.

Canonical message format (signed by the client, verified by the server):

METHOD\nPATH\nTIMESTAMP\nNONCE\nSHA-256(body)

Utilities (src/utils/requestSigning.ts):

• buildCanonicalMessage() — Deterministic string construction
• signMessage() / verifySignature() — RSA-PSS sign/verify primitives
• buildSigningHeaders() — Client-side convenience: returns X-Signature, X-Timestamp, X-Nonce headers
• verifyRequest() — Full server-side verification including clock-skew enforcement
• generateKeyPair() — RSA-2048 key pair generation for onboarding

Middleware (src/middleware/requestSigningMiddleware.ts):

• requireRequestSignature(resolvePublicKey, opts) factory — applies signing enforcement on any route
• Threshold: default 500 000 XAF (configurable via REQUEST_SIGNING_THRESHOLD)
• Clock-skew tolerance: default 300 s (configurable via REQUEST_SIGNING_TIMESTAMP_TOLERANCE)
• alwaysRequire option for unconditional enforcement on high-security endpoints
• Public key resolver is a callback — keys can be sourced from DB, Redis, or a secrets manager

---

#292 — Redis Key Expiration Monitoring and Cleanup

Files: src/jobs/redisKeyExpirationJob.ts, src/jobs/scheduler.ts

Scheduled job (every 10 minutes, configurable via REDIS_EXPIRY_MONITOR_CRON) that:

1. Collects Redis metrics via INFO all and publishes to Prometheus:

   • redis_memory_usage_bytes
   • redis_keyspace_hits_total / redis_keyspace_misses_total
   • redis_evicted_keys_total / redis_expired_keys_total

2. Eviction rate alerting — Computes eviction delta between runs and logs a warning + increments redis_high_eviction_alert_total when rate exceeds REDIS_EVICTION_RATE_ALERT_THRESHOLD (default: 100/s).

3. Orphan key cleanup — Uses non-blocking SCAN to find keys matching configurable prefixes (REDIS_ORPHAN_KEY_PREFIXES, default: idempotency:,session:,otp:,lock:) with no TTL or TTL exceeding REDIS_ORPHAN_MAX_TTL_SECONDS (default: 86 400 s), then deletes them.

   • Dry-run mode via REDIS_CLEANUP_DRY_RUN=true
   • Tracks deletions via redis_orphan_keys_deleted_total counter

Also fixes a pre-existing missing import: runTravelRuleAuditReportJob was referenced in the scheduler's JOBS array without a corresponding import statement.

---

Configuration Reference

Variable	Default	Description
REQUEST_SIGNING_THRESHOLD	500000	Min XAF amount requiring a signature
REQUEST_SIGNING_TIMESTAMP_TOLERANCE	300	Clock-skew tolerance in seconds
REDIS_EXPIRY_MONITOR_CRON	*/10 * * * *	Redis monitor job schedule
REDIS_EVICTION_RATE_ALERT_THRESHOLD	100	Evictions/sec before alert
REDIS_ORPHAN_KEY_PREFIXES	idempotency:,session:,otp:,lock:	Key prefixes to scan for orphans
REDIS_ORPHAN_MAX_TTL_SECONDS	86400	Max normal TTL; keys above this are orphans
REDIS_CLEANUP_DRY_RUN	false	Log orphans without deleting them

[drips-wave]

@smokeylenz1-commits 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