rate-limiting

What this skill does

# Rate Limiting - Preventing Brute Force & Resource Abuse

## Why Rate Limiting Matters

### The Brute Force Problem

Without rate limiting, attackers can try thousands of passwords per second. A 6-character password has 308 million possible combinations.

**Without rate limiting:**
- At 1,000 attempts/second → Cracked in 5 minutes

**With our rate limiting (5 requests/minute):**
- At 5 attempts/minute → Would take 117 years

### Real-World Brute Force Attacks

**Zoom Credential Stuffing (2020):**
Attackers made over 500,000 login attempts using stolen credentials. Proper rate limiting would have detected and blocked this within the first few hundred attempts.

**WordPress Distributed Attacks (2021):**
Multiple WordPress sites were targeted by distributed brute force attacks attempting millions of login combinations. Sites without rate limiting saw server costs spike as attackers consumed resources.

### The Cost of Resource Abuse

Beyond security, rate limiting protects your infrastructure costs. Without it:

- Bots can spam your contact form thousands of times
- Attackers can abuse expensive operations (AI API calls, database queries)
- Your server bill skyrockets before you notice

**Real Story:**
One startup built a "summarize any article" AI feature without rate limiting. A malicious user scripted 10,000 requests in minutes. At AI API costs, this generated **$9,600 in charges in 10 minutes**. The attack ran 4 hours unnoticed—total cost over **$200,000**.

## Our Rate Limiting Architecture

### Implementation Features

- **5 requests per minute per IP address** - Balances usability and security
- **In-memory tracking** - Fast, no database overhead
- **IP-based identification** - Works behind proxies via x-forwarded-for
- **HTTP 429 status** - Standard "Too Many Requests" response
- **Shared budget** - All routes using withRateLimit() share same 5/min limit per IP

### Why 5 Requests Per Minute?

Research on usability vs security shows that legitimate users rarely make more than 5 requests per minute to the same endpoint. This limit:
- ✅ Stops automated attacks
- ✅ Doesn't impact real users
- ✅ Allows reasonable form resubmissions
- ✅ Permits error recovery attempts

### Why Per-IP Tracking?

- Individual users get individual limits
- An attack on one IP doesn't block others
- During distributed attack, each bot IP limited separately
- Makes attacks ineffective at scale

### Implementation Files

- `lib/withRateLimit.ts` - Rate limiting middleware
- `app/api/test-rate-limit/route.ts` - Test endpoint
- `scripts/test-rate-limit.js` - Verification script

## How to Use Rate Limiting

### Basic Usage

For any endpoint that could be abused:

```typescript
import { NextRequest, NextResponse } from 'next/server';
import { withRateLimit } from '@/lib/withRateLimit';

async function handler(request: NextRequest) {
  // Your business logic
  return NextResponse.json({ success: true });
}

// Apply rate limiting
export const POST = withRateLimit(handler);

export const config = {
  runtime: 'nodejs',
};
```

### Combined with CSRF Protection

For maximum security on state-changing operations:

```typescript
import { NextRequest, NextResponse } from 'next/server';
import { withRateLimit } from '@/lib/withRateLimit';
import { withCsrf } from '@/lib/withCsrf';

async function handler(request: NextRequest) {
  // Business logic
  return NextResponse.json({ success: true });
}

// Layer both protections (rate limit first, then CSRF)
export const POST = withRateLimit(withCsrf(handler));

export const config = {
  runtime: 'nodejs',
};
```

### When to Apply Rate Limiting

**✅ Always Apply To:**
- Contact/support forms
- Newsletter signup
- Account creation
- Password reset requests
- File upload endpoints
- Search endpoints
- Data export endpoints
- Any expensive AI/API operations
- Webhook endpoints
- Comment/review submission
- Report generation
- Bulk operations

**❌ Usually Not Needed For:**
- Static asset requests (handled by CDN)
- Simple GET endpoints that only read public data
- Health check endpoints
- Endpoints already protected by authentication rate limits

## Complete Examples

### Example 1: Contact Form with Full Protection

```typescript
// app/api/contact/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { withRateLimit } from '@/lib/withRateLimit';
import { withCsrf } from '@/lib/withCsrf';
import { validateRequest } from '@/lib/validateRequest';
import { contactFormSchema } from '@/lib/validation';
import { handleApiError } from '@/lib/errorHandler';

async function contactHandler(request: NextRequest) {
  try {
    const body = await request.json();

    const validation = validateRequest(contactFormSchema, body);
    if (!validation.success) {
      return validation.response;
    }

    const { name, email, subject, message } = validation.data;

    await sendEmail({
      to: '[email protected]',
      from: email,
      subject,
      message
    });

    return NextResponse.json({ success: true });

  } catch (error) {
    return handleApiError(error, 'contact-form');
  }
}

export const POST = withRateLimit(withCsrf(contactHandler));

export const config = {
  runtime: 'nodejs',
};
```

### Example 2: AI API Endpoint (Cost Protection)

```typescript
// app/api/summarize/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { withRateLimit } from '@/lib/withRateLimit';
import { auth } from '@clerk/nextjs/server';
import { handleApiError, handleUnauthorizedError } from '@/lib/errorHandler';
import OpenAI from 'openai';

const openai = new OpenAI();

async function summarizeHandler(request: NextRequest) {
  try {
    // Require authentication for expensive operations
    const { userId } = await auth();
    if (!userId) return handleUnauthorizedError();

    const { text } = await request.json();

    // Rate limiting prevents abuse of expensive AI API
    const response = await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [
        { role: 'system', content: 'Summarize the following text concisely.' },
        { role: 'user', content: text }
      ],
      max_tokens: 150
    });

    return NextResponse.json({
      summary: response.choices[0].message.content
    });

  } catch (error) {
    return handleApiError(error, 'summarize');
  }
}

// Protect expensive AI operations with rate limiting
export const POST = withRateLimit(summarizeHandler);

export const config = {
  runtime: 'nodejs',
};
```

### Example 3: File Upload Endpoint

```typescript
// app/api/upload/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { withRateLimit } from '@/lib/withRateLimit';
import { auth } from '@clerk/nextjs/server';
import { handleApiError, handleUnauthorizedError } from '@/lib/errorHandler';

async function uploadHandler(request: NextRequest) {
  try {
    const { userId } = await auth();
    if (!userId) return handleUnauthorizedError();

    const formData = await request.formData();
    const file = formData.get('file') as File;

    if (!file) {
      return NextResponse.json(
        { error: 'No file provided' },
        { status: 400 }
      );
    }

    // Validate file size (10MB max)
    if (file.size > 10 * 1024 * 1024) {
      return NextResponse.json(
        { error: 'File too large (max 10MB)' },
        { status: 400 }
      );
    }

    // Process upload
    const uploadResult = await processFileUpload(file, userId);

    return NextResponse.json({ success: true, fileId: uploadResult.id });

  } catch (error) {
    return handleApiError(error, 'upload');
  }
}

// Prevent upload spam
export const POST = withRateLimit(uploadHandler);

export const config = {
  runtime: 'nodejs',
};
```

## Technical Implementation Details

### Rate Limiter Code (lib/withRateLimit.ts)

```typescript
import { NextRequest, NextResponse } from 'next/server';

// In-memory storage for rate limiting
const rateLimitStore = new Map<string, { count: number; reset