feat(backend): idempotency keys for payment, enrollment, and credential endpoints (#264)

[DanielCharis1]

Summary

Implements Stripe-style Idempotency-Key support for mutation endpoints (#264).

What ships

• New middleware backend/src/middleware/idempotency.ts:

  • Reads Idempotency-Key on POST/PUT/PATCH/DELETE
  • Validates with /^[A-Za-z0-9._:\-]{8,255}$/ → 400 on bad input
  • Redis cache + lock when available; in-process Map fallback otherwise
  • Returns the cached response with Idempotency-Replayed: true on replay
  • Returns 409 Conflict when a duplicate request is concurrently in flight
  • Per-user namespace so a key cannot replay another user's response
  • 24h TTL on cached responses, 60s lock TTL; both configurable
  • 5xx responses are not cached so retries remain safe
  • Releases in-flight lock on res.on('close') so client disconnects don't block retries
  • Fails open on storage errors

• Middleware applied to mutation endpoints:

  • POST /api/payments/create-payment-intent
  • POST /api/payments/:paymentId/refund
  • POST /api/enrollments
  • DELETE /api/enrollments/:enrollmentId
  • PUT /api/enrollments/:enrollmentId/progress
  • POST /api/credentials (new endpoint)

  POST /api/payments/webhook is not wrapped — payment-gateway webhooks carry their own gateway-level idempotency tokens.

• New credentials module (needed to provide a credential-issuance mutation endpoint that exercises the middleware):

  • backend/src/models/Credential.ts
  • backend/src/services/credentialService.ts (in-memory store; production swaps for the project's persistent layer)
  • backend/src/controllers/CredentialsController.ts
  • backend/src/routes/credentialsRoutes.ts

Tests

backend/tests/middleware/idempotency.test.ts (6 cases):

1. Pass-through when no key present
2. Bad-key format → 400
3. Duplicate request → 201 replay with Idempotency-Replayed: true
4. Concurrent duplicates (Promise.all, 80 ms handler delay) → exactly one handler invocation; one 201, one 409/replay; a third request replays from cache
5. 5xx response is not cached → next retry runs the handler again
6. Per-user key isolation → same key, different users, distinct results

Run locally:

cd backend
npx jest --config jest.isolated.config.js tests/middleware/idempotency.test.ts

jest.isolated.config.js is included so the test bypasses the broken global setupFilesAfterEnv (which transitively pulls in pre-existing TS errors elsewhere in the repo).

Acceptance-criteria mapping (#264)

• Idempotency-Key header support — yes, with case-insensitive idempotency-key fallback on input
• Key storage with TTL in Redis — yes, plus an explicit in-process fallback for tests and dev
• Return cached response for duplicate keys — yes, with Idempotency-Replayed: true
• Applied to payment, enrollment, and credential issuance endpoints — yes
• Tests for concurrent duplicate requests — yes (test [Frontend] Add loading states and skeleton UI for all async components #4 above)

Notes

• backend/src/index.js is intentionally not modified (route registration is out-of-scope here).
• The credentials service uses an in-memory Map. Replace with the project Mongo/Postgres layer in a follow-up.

Closes #264