feat(security): add browser fingerprinting for rate limiting

Enhance API endpoint security by implementing browser fingerprinting
into the rate limiting mechanism. This generates a unique identifier
from IP, User-Agent, and Accept-Language headers, making it harder
to bypass rate limits via IP rotation or VPNs.

Author: teycir

README.md

@@ -175,6 +175,9 @@ sequenceDiagram
 - Key A (in the URL hash)
 - Key B (server releases only after unlock time)
 
+### "Can I bypass rate limits by rotating IPs or using VPNs?"
+**⚠️ HARDER.** Rate limiting uses browser fingerprinting (IP + User-Agent + Language), making simple IP rotation ineffective. You'd need to change your entire browser signature.
+
 ### "Can I replay old API requests to trick the server?"
 **❌ NO.** Pulse tokens include nonces and timestamps. Replay attacks are detected and rejected.
 
@@ -200,6 +203,7 @@ sequenceDiagram
 *   **Database:** `Cloudflare D1` (SQLite)
 *   **Storage:** `Cloudflare D1` (Encrypted Blobs)
 *   **Crypto:** `Web Crypto API` (Native AES-GCM)
+*   **Security:** Browser Fingerprinting, Rate Limiting, Input Validation
 *   **Styling:** `Tailwind CSS` (Cipher-punk Theme)
 
 ---

app/security/page.tsx

@@ -76,8 +76,8 @@ export default function SecurityPage() {
               <p>The server will not release Key B before the unlock time. Server-side validation using Date.now() prevents client-side time manipulation.</p>
             </div>
             <div>
-              <p className="text-neon-green font-bold mb-2 flex items-center gap-2"><CheckCircle2 className="w-4 h-4" /> Rate Limiting</p>
-              <p>API endpoints are rate-limited to 10-20 requests per minute per IP address to prevent brute-force attacks.</p>
+              <p className="text-neon-green font-bold mb-2 flex items-center gap-2"><CheckCircle2 className="w-4 h-4" /> Rate Limiting with Fingerprinting</p>
+              <p>API endpoints use browser fingerprinting (IP + User-Agent + Language) to prevent VPN/IP rotation bypass. 10-20 requests per minute per fingerprint.</p>
             </div>
             <div>
               <p className="text-neon-green font-bold mb-2 flex items-center gap-2"><CheckCircle2 className="w-4 h-4" /> No Single Point of Failure</p>
@@ -110,7 +110,8 @@ export default function SecurityPage() {
                 <li>Client-side time manipulation (server validates with Date.now())</li>
                 <li>Server compromise (split-key architecture)</li>
                 <li>Data tampering (WORM storage + AEAD)</li>
-                <li>Brute force attacks (256-bit keys + rate limiting)</li>
+                <li>Brute force attacks (256-bit keys + fingerprinted rate limiting)</li>
+                <li>IP rotation bypass (browser fingerprinting)</li>
                 <li>Automated abuse (Turnstile CAPTCHA)</li>
                 <li>Replay attacks (nonce validation on pulse tokens)</li>
               </ul>

lib/rateLimit.ts

@@ -1,7 +1,8 @@
 // Rate Limiting Middleware for Cloudflare Workers
 export interface RateLimitConfig {
   limit: number;
-  window: number; // milliseconds
+  window: number;
+  key?: string;
 }
 
 export class RateLimiter {
@@ -84,12 +85,12 @@ export async function withRateLimit(
   handler: () => Promise<Response>,
   config: RateLimitConfig = { limit: 10, window: 60000 }
 ): Promise<Response> {
-  const ip = request.headers.get('CF-Connecting-IP') || 'unknown';
+  const identifier = config.key || request.headers.get('CF-Connecting-IP') || 'unknown';
 
   const key = `${config.limit}:${config.window}`;
   const limiter = RateLimiterRegistry.getInstance().getLimiter(key, config);
 
-  const { allowed, remaining } = await limiter.check(ip);
+  const { allowed, remaining } = await limiter.check(identifier);
 
   if (!allowed) {
     return new Response(

lib/routeHelper.ts

@@ -3,6 +3,7 @@ import { getCloudflareContext } from '@opennextjs/cloudflare';
 import { createContainer } from './container';
 import { createHandler, HandlerContext } from './apiHandler';
 import { withRateLimit } from './rateLimit';
+import { getRequestFingerprint } from './security';
 
 interface RouteHandlerOptions {
   rateLimit?: { limit: number; window: number };
@@ -19,6 +20,7 @@ export function createAPIRoute(
 ) {
   return async (request: NextRequest, routeParams?: any) => {
     const ip = request.headers.get('CF-Connecting-IP') || 'unknown';
+    const fingerprint = getRequestFingerprint(request);
 
     const wrappedHandler = async () => {
       const apiHandler = createHandler(async (ctx: HandlerContext) => {
@@ -32,7 +34,7 @@ export function createAPIRoute(
     };
 
     if (options.rateLimit) {
-      return withRateLimit(request, wrappedHandler, options.rateLimit);
+      return withRateLimit(request, wrappedHandler, { ...options.rateLimit, key: fingerprint });
     }
 
     return wrappedHandler();

lib/security.ts

@@ -119,6 +119,13 @@ export async function validatePulseToken(token: string, sealId: string, secret:
   return await crypto.subtle.verify('HMAC', key, sigBytes, encoder.encode(data));
 }
 
+export function getRequestFingerprint(request: Request): string {
+  const ip = request.headers.get('CF-Connecting-IP') || 'unknown';
+  const ua = request.headers.get('user-agent') || '';
+  const lang = request.headers.get('accept-language') || '';
+  return `${ip}:${ua.slice(0, 50)}:${lang.slice(0, 20)}`;
+}
+
 export function sanitizeError(error: unknown): string {
   if (process.env.NODE_ENV === 'production') {
     return 'An error occurred. Please try again.';