randomayzer/docs/PRODUCTION_GUARDS.md

Randomayzer — Production Guards & Security Architecture

This document details the production integrity guards, concurrency safeguards, rate limiting, and idempotency semantics implemented in Randomayzer.

---

1. Idempotency Hardening & Request Fingerprinting

Contract

The API supports the standard Idempotency-Key HTTP header on state-mutating endpoints:

• POST /api/giveaways (Giveaway creation)
• POST /api/giveaways/[id]/participants (Participant import & enrichment)
• POST /api/giveaways/[id]/snapshot (Participant snapshot locking)

Semantics

1. Scoped Storage Key: Keys are composite and scoped by operation, giveawayId, and idempotencyKey: format: ${operation}:${giveawayId || 'global'}:${key} This prevents cross-endpoint and cross-giveaway key collision.
2. Request Fingerprinting: Every request computes a canonical SHA-256 fingerprint: requestFingerprint = SHA256(canonicalStringify(requestPayload))
3. Replay vs Conflict Handling:
   • Same Key + Same Request: Returns the previously cached status code and response body without re-executing.
   • Same Key + Different Request: Throws HTTP 409 Conflict with error code IDEMPOTENCY_KEY_REUSED.
4. Key Validation & TTL:
   • Maximum key length is 128 characters (exceeding length returns 400 VALIDATION_ERROR).
   • Default TTL is 5 minutes with proactive cleanup and upper memory bounds.

---

2. Rate Limiting & Client Identity Resolution

Client Identity Scoping Architecture

• Authenticated Routes (/api/giveaways*): Rate limits are keyed strictly by trusted server-side sessionUser.id (e.g. draw-execute:${sessionUser.id}:${id}, giveaways-list:${sessionUser.id}) after session authentication and ownership checks. This ensures:
  1. Different organizers have isolated rate limit buckets and never block each other, even when req.ip is unpopulated.
  2. Unauthenticated attackers receive 401 Unauthorized before reaching the rate limiter and cannot drain any organizer's quota.
• Anonymous / Hybrid Routes (/api/posts/preview, /api/auth/vk/start, /api/giveaways/[id]/verify):
  • POST /api/posts/preview: Uses post-preview:user:${sessionUser.id} if a valid session exists, and post-preview:anon:${clientIp} if anonymous. An anonymous attacker consuming the IP limit cannot affect authenticated organizers.
  • GET /api/auth/vk/start: Rate-limited per resolved client IP (oauth-start:${clientIp}).
  • GET /api/giveaways/[id]/verify: Rate-limited per resolved client IP and giveaway (verify-get:${clientIp}:${id}).

Centralized Client IP Resolution (src/lib/client-ip.ts)

• Untrusted Proxy Mode (Default): When TRUST_PROXY !== 'true', user-supplied X-Forwarded-For, X-Real-IP, or CF-Connecting-IP headers are strictly ignored to prevent IP spoofing attacks. The direct socket connection req.ip is used.
  • Production Behavior: If NODE_ENV=production, TRUST_PROXY !== 'true', and direct req.ip is unavailable (e.g. in self-hosted Node.js / next start behind a reverse proxy), the server emits a [SECURITY CONFIGURATION WARNING] and falls back to 'direct-client'. For production deployments behind reverse proxies, setting TRUST_PROXY=true is required.
• Trusted Proxy Mode (TRUST_PROXY=true): When deployed behind a verified reverse proxy (e.g. Nginx, Cloudflare, AWS ALB), TRUST_PROXY=true must be set. The resolver:
  • Enforces a maximum header length of 1024 characters (oversized headers are rejected as malformed).
  • Parses multi-value proxy chains (client, proxy1, proxy2), extracting and validating the leftmost IP.
  • Normalizes IPv4, IPv6 (including IPv4-mapped IPv6 ::ffff:192.0.2.1 and loopbacks ::1).
  • Validates IP syntax against IPv4/IPv6 standards.

Memory Limiter vs Multi-Instance Deployments

• The built-in SlidingWindowRateLimiter is optimized for single-instance, serverless dev, and test environments.
• In multi-instance or horizontal cluster deployments, rate limiting must be offloaded to an edge layer (e.g., Cloudflare Rate Limiting, Nginx limit_req) or a shared distributed cache (Redis/Valkey).

---

3. Winner Count Contract (Zero Under-Delivery)

Contract

Before conducting any draw, the system enforces:

\text{winnersCount} + \text{reserveWinnersCount} \le \text{eligibleParticipantsCount}

If the requested winners count plus reserve exceeds the locked snapshot's eligible participants:

• The system returns HTTP 400 VALIDATION_ERROR (or 409 CONFLICT).
• The system NEVER silently clamps or reduces the winners count.

---

4. Draw Concurrency & Terminal Retry Contract

Atomic Conditional Execution

• Draw execution (POST /api/giveaways/[id]/draw) requires the giveaway to be in SNAPSHOT_LOCKED status with an existing snapshot.
• The state transition from SNAPSHOT_LOCKED to DRAWN occurs atomically inside a database transaction (updateMany({ where: { id, status: 'SNAPSHOT_LOCKED' } })).
• In a concurrent race (e.g. 20 or 100 simultaneous draw requests), exactly one request acquires the lock and transitions to DRAWN. All competing requests receive 409 Conflict.

Terminal State Replay (DRAW_ALREADY_COMPLETED)

• Once a giveaway is in DRAWN or PUBLISHED status, subsequent draw attempts return:

  {
    "success": false,
    "error": {
      "code": "DRAW_ALREADY_COMPLETED",
      "message": "Giveaway has already been drawn and finalized. Repeat draws are not permitted."
    }
  }
  

• Clients and UI treat DRAW_ALREADY_COMPLETED as a terminal final status.

---

5. Summary of Environment Variables

Variable	Type	Default	Description
NODE_ENV	string	development	Environment mode (production, test, development)
TRUST_PROXY	boolean (true/false)	false	Enable only behind trusted upstream proxies
ALLOW_MEMORY_IDEMPOTENCY	boolean	false	Silence production warning for memory idempotency in single-instance
ALLOW_MEMORY_RATE_LIMITER	boolean	false	Silence production warning for memory rate limiter in single-instance
USE_VK_MOCK	boolean	false	Explicitly enable VkMockProvider (forbidden in production unless true)
VK_SERVICE_TOKEN	string	undefined	VK Application Service Access Token