feat: Payment API hardening — error normalization, idempotency, balance checks, rate limiting (#173-176)

[TheHalalHunter]

Closes #173, Closes #174, Closes #175, Closes #176

---

Summary

Addresses four issues in the payment domain:

Issue	Description
#173	Standardize payment API error responses
#174	Add missing idempotency key validation for charge endpoints
#175	Enforce wallet balance checks before accepting payments
#176	Add rate limiting per-user for wallet operations

---

#173 — Standardize payment API error responses

Problem: Payment and charge endpoints returned inconsistent error formats — raw Prisma errors, mixed \code/\message\ shapes, and internal details leaking to clients.

Changes:

• \src/utils/errors.ts: Added 5 payment-specific \AppError\ subclasses (\InsufficientFundsError, \InvalidCurrencyError, \PaymentDeclinedError, \DuplicatePaymentError, \PaymentNotFoundError) with correct status codes (422/422/422/409/404)
• \src/domains/payments/payment.service.ts: All throw sites replaced with typed errors; structured \logger.warn/error({ userId, failureReason, cause })\ on every error path
• \src/domains/payments/charge.service.ts: Raw
  ew AppError(409/403)\ replaced with \DuplicatePaymentError/\ForbiddenError; structured logs added
• \src/middleware/tests/error-handler.test.ts: 10 new tests — per-class shape assertions, status code mapping, no-leak assertions

All payment/charge endpoints now return { code, message, statusCode, timestamp }. No Prisma errors or stack traces reach clients.

---

#174 — Idempotency key validation for charge endpoints

Problem: Charge endpoints accepted malformed idempotency keys and had no true idempotency guarantee — duplicate requests could create duplicate charges.

Changes:

• \src/domains/payments/charge.types.ts: \idempotencyKey\ schema tightened to \z.string().uuid()\
• \src/domains/payments/charge.routes.ts: \idempotencyKeyFrom()\ now validates the \Idempotency-Key\ header with \z.string().uuid().safeParse(), throws \ValidationError\ (400) for any non-UUID v4 or empty value
• \src/domains/payments/charge.service.ts: \createPayment()\ checks for an existing charge with the same key before processing — matching amount + creatorId returns cached result; differing amount or creatorId throws \DuplicatePaymentError\ (409)
• New tests in \charge.routes.test.ts\ and \charge.service.test.ts\ covering all deduplication and validation scenarios

---

#175 — Enforce wallet balance checks before accepting payments

Problem: Tips could be created against wallets with zero balance, resulting in failed on-chain confirmations and orphaned DB records.

Changes:

• \src/utils/errors.ts: Added \PaymentRequiredError\ (402) with typed \PaymentRequiredDetails\ interface enforcing { requiredAmount, currentBalance, currency }\
• \src/domains/payments/payment.service.ts: Balance pre-flight added in \createTip()\ — idempotency replay runs first (no unnecessary Stellar calls on retries), then \getWalletBalance()\ is called; insufficient balance → 402 with balance details; Stellar unreachable → 503
• No DB record is created if the balance check fails
• 4 new tests covering: insufficient balance (402), missing trustline (402), Stellar unavailable (503), exact-balance boundary (passes through)

Note: \ChargeService\ was intentionally excluded — it processes tokenized card payments via an external provider with no Stellar wallet concept. Documented with a #175\ comment in source.

---

#176 — Per-user rate limiting for wallet operations

Problem: Wallet auth endpoints were rate-limited globally (per-IP), allowing attackers to rotate user IDs to bypass limits or exhaust the global limit for all users.

Changes:

• \src/config/rate-limit.ts: Added \walletNonce\ (5 req/hr) and \walletVerify\ (10 req/hr) named policies; fixed stale URL rules pointing at non-existent paths
• \src/plugins/rateLimit.ts: Extended \�uthOverride\ chain with wallet route arms; existing
  esolveClientKey\ emits \user:\ for authenticated requests — no new dependency needed
• \src/config/schema.ts, \docs/CONFIGURATION.md, .env.example: 4 new env keys for configurable window/max values (ceiling raised to 24 hr)
• 26 rate limit tests pass, including per-user isolation and IP-fallback for unauthenticated requests

---

Testing

• 67 payment domain tests pass (feat: Standardize payment API error responses #173)
• 16 charge route + 32 charge service tests pass (fix: Add missing idempotency key validation for charge endpoints #174)
• 125/125 payment domain tests pass (fix: Enforce wallet balance checks before accepting payments #175)
• 26/26 rate limit tests pass (security: Add rate limiting per-user for wallet operations #176)

Non-blocking follow-ups (separate tickets recommended)

• \ ip-media.test.ts\ has a pre-existing failure unrelated to these changes (missing Prisma \Tip\ export)
• \RateLimitRule.class\ union type missing \walletNonce/\walletVerify\ values (security: Add rate limiting per-user for wallet operations #176)
• Dead
  equest.user\ branch in
  esolveClientKey\ (security: Add rate limiting per-user for wallet operations #176)
• \x-ratelimit-remaining\ header assertions missing from new wallet rate-limit tests (security: Add rate limiting per-user for wallet operations #176)

[drips-wave]

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