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