fix(idempotency): isolate unauthenticated callers to prevent shared 'anonymous' bucket collisions (#55)

[gramseostudio-dev]

Closes #55

Summary

This PR implements strict key isolation for idempotency keys to resolve collision risks in unauthenticated routes.

Context/Motivation

Previously, the IdempotencyInterceptor used a shared 'anonymous' bucket for all unauthenticated requests. This introduced a significant security risk where:

1. Denial of Service: Adversarial clients could collide with legitimate requests by deliberately reusing Idempotency-Key values.
2. Response Confusion: A client could inadvertently receive a cached response meant for another client if they reused a key and the timing aligned.

Technical Changes

• Refactor resolveCallerId in IdempotencyInterceptor:
  • The interceptor now prioritizes req.user.userId if the request is authenticated.
  • For unauthenticated requests, it now generates a deterministic fingerprint combining the client's IP and User-Agent (SHA-256). This creates a unique bucket per anonymous caller, drastically reducing the collision surface area compared to the previous global 'anonymous' bucket.
• Documentation: Updated class-level and method-level JSDoc to explicitly define the new scoping strategy (Auth vs. Anonymous-IP-based).
• Test Suite: Added a robust isolation test case in src/common/idempotency/idempotency.interceptor.spec.ts ensuring authenticated users do not collide, and that anonymous callers with different IP/UA fingerprints are properly isolated.

Verification

• Unit Tests: Verified with 16 comprehensive unit tests in src/common/idempotency/idempotency.interceptor.spec.ts.
• Isolation Verification: The new test case validates that IdempotencyInterceptor correctly scopes keys based on userId (authenticated) or the derived fingerprint (anonymous), passing all verification scenarios.

[vercel]

@gramseostudio-dev is attempting to deploy a commit to the chonilius' projects Team on Vercel.

A member of the Team first needs to authorize it.