feat: subscription locking, DB encryption, API key rotation, and payment gateway adapter

[samsonmbah002]

Summary

This PR implements four major features addressing subscription billing race conditions, column-level encryption, API key rotation, and payment gateway extensibility.

Issues

Closes #610
Closes #604
Closes #603
Closes #581

---

#610 — Subscription Billing Race Condition Handling (Pessimistic Locking)

• AdvisoryLockService: PostgreSQL advisory lock wrapper with configurable timeout (5s), exponential backoff retry (3 attempts: 100ms, 300ms, 900ms), and deadlock detection
• Lock integration: BillingLockIntegration and SubscriptionLockIntegration wrap charge/cancel/pause/resume/upgrade operations with locks
• Lock hierarchy: subscription → invoice → payment (prevents circular waits)
• Monitoring: Lock contention count, timeout count, acquisition time histogram via Prometheus-compatible metrics

#604 — Database Encryption at Rest with Customer-Managed Keys

• ColumnEncryptionService: AES-256-GCM envelope encryption with per-row unique 12-byte IV
• Key management: Envelope encryption (DEK encrypted by KEK stored in KMS/Vault)
• KmsProvider/VaultProvider: Dual provider support for AWS KMS and HashiCorp Vault
• CMK configuration: REST API for merchants to bring their own KMS key (BYOK)

#603 — API Key Rotation Automation

• ApiKeyRotationService: Configurable rotation cadence (30/60/90 days) with grace period overlap (1-72h)
• Overlap period: Old key remains valid for configurable hours after rotation
• Automatic rotation: Cron job evaluates policies and rotates keys on schedule
• Manual rotation: Force rotation with immediate old key invalidation

#581 — Payment Gateway Adapter Pattern

• PaymentGateway interface: charge, refund, createCustomer, getPaymentMethod, createPayout
• StripeAdapter/CircleAdapter/StellarAdapter: Three gateway implementations
• PaymentRouter: Gateway selection per merchant with fallback chain
• Transactional outbox: Failed gateway attempts queued for retry on alternative gateway

Technical Details

• Follows existing project patterns: DomainError hierarchy, IoC container registration, barrel exports
• 3 new database migration files (PostgreSQL)
• Unit tests for all major services
• All new error codes registered in apiResponse.ts with proper HTTP status mappings

[drips-wave]

@samsonmbah002 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

[gitguardian]

⚠️ GitGuardian has uncovered 3 secrets following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

Since your pull request originates from a forked repository, GitGuardian is not able to associate the secrets uncovered with secret incidents on your GitGuardian dashboard.
Skipping this check run and merging your pull request will create secret incidents on your GitGuardian dashboard.

🔎 Detected hardcoded secrets in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
34266369	Triggered	Generic Password	eff1088	backend/config/tests/redis.test.ts	View secret
15742864	Triggered	Generic Password	eff1088	docker-compose.yml	View secret
15762030	Triggered	Generic Password	eff1088	docker-compose.yml	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secrets safely. Learn here the best practices.
3. Revoke and rotate these secrets.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}