[Phase 2] Implement API Rate Limiting for Security

[frankbria]

Summary

Add rate limiting to API endpoints to prevent abuse and protect against denial-of-service attacks.

Context

Currently, the API endpoints have no rate limiting mechanism. This exposes the application to:

• Brute force attacks on authentication endpoints
• Resource exhaustion through excessive API calls
• Potential cost overruns from unbounded AI API usage

Requirements

• Implement per-user rate limiting for authenticated endpoints
• Implement per-IP rate limiting for unauthenticated endpoints (login, register)
• Configure appropriate limits per endpoint category:
  • Authentication: 5-10 requests/minute
  • Standard API: 60-100 requests/minute
  • AI/expensive operations: 10-20 requests/minute
• Return proper 429 Too Many Requests responses with Retry-After header
• Add rate limit headers to responses (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)

Technical Considerations

• Use FastAPI's built-in support or libraries like slowapi
• Consider Redis for distributed rate limiting in production
• In-memory rate limiting acceptable for single-instance deployments

Priority

P2 - Medium priority for beta. Important for security but not blocking MVP functionality.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• [P1] Implement user authentication and authorization with Better Auth #132
• [Phase 2] Add API pagination support for large datasets #118
• [Phase 2] Complete OpenAPI documentation for all endpoints #119

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Plan

Observations

The codebase is a FastAPI application with multiple routers handling various endpoints (projects, tasks, chat, agents, etc.). Authentication is managed via Bearer tokens stored in sessions, with an existing audit logging system. Currently, there is no rate limiting mechanism in place. The application uses SQLite with aiosqlite for persistence, and dependencies are managed via pyproject.toml. The chat endpoint represents the primary AI/expensive operation requiring stricter rate limits.

Approach

Implement rate limiting using the slowapi library, which integrates seamlessly with FastAPI and supports both in-memory and Redis-based storage. Create a dedicated rate limiting middleware module in codeframe/lib/ that provides decorators for different endpoint categories. Configure rate limits via environment variables for flexibility across deployment environments. Apply rate limits at the router level using dependency injection, with per-user limits for authenticated endpoints and per-IP limits for unauthenticated endpoints. Return proper 429 responses with standard rate limit headers.

Implementation Steps

1. Add Rate Limiting Dependencies

Add slowapi to the dependencies list in file:pyproject.toml:

• Add slowapi>=0.1.9 to the dependencies array (around line 54)
• Optionally add redis>=5.0.0 for distributed rate limiting in production (can be added later)

2. Create Rate Limiting Configuration Module

Create new file file:codeframe/config/rate_limits.py:

• Define RateLimitConfig dataclass with fields for each endpoint category:
  • auth_limit: Rate limit for authentication endpoints (default: "10/minute")
  • standard_limit: Rate limit for standard API endpoints (default: "100/minute")
  • ai_limit: Rate limit for AI/expensive operations (default: "20/minute")
  • websocket_limit: Rate limit for WebSocket connections (default: "30/minute")
• Implement from_environment() classmethod to load from environment variables:
  • RATE_LIMIT_AUTH (default: "10/minute")
  • RATE_LIMIT_STANDARD (default: "100/minute")
  • RATE_LIMIT_AI (default: "20/minute")
  • RATE_LIMIT_WEBSOCKET (default: "30/minute")
  • RATE_LIMIT_ENABLED (default: "true")
  • RATE_LIMIT_STORAGE (default: "memory", options: "memory" or "redis")
  • REDIS_URL (optional, for distributed rate limiting)
• Add global instance getter get_rate_limit_config()

3. Create Rate Limiting Middleware Module

Create new file file:codeframe/lib/rate_limiter.py:

• Import slowapi components: Limiter, _rate_limit_exceeded_handler
• Create rate limiter instance with key function that:
  • For authenticated requests: extracts user ID from Bearer token (via get_current_user_optional)
  • For unauthenticated requests: extracts client IP from X-Forwarded-For or request.client.host
• Implement get_rate_limiter() function that returns configured Limiter instance
• Create decorator functions for each category:
  • @rate_limit_auth(): Applies auth rate limit
  • @rate_limit_standard(): Applies standard rate limit
  • @rate_limit_ai(): Applies AI operation rate limit
  • @rate_limit_websocket(): Applies WebSocket rate limit
• Implement custom exception handler for 429 responses that includes:
  • Standard HTTP 429 status code
  • Retry-After header (seconds until limit resets)
  • X-RateLimit-Limit header (total allowed requests)
  • X-RateLimit-Remaining header (remaining requests)
  • X-RateLimit-Reset header (Unix timestamp when limit resets)
  • JSON response body with error details

4. Integrate Rate Limiter into FastAPI Application

Modify file:codeframe/ui/server.py:

• Import rate limiter components from codeframe.lib.rate_limiter
• Add rate limiter state to FastAPI app (around line 206, after app creation):
  • app.state.limiter = get_rate_limiter()
  • Register SlowAPIMiddleware with the app
  • Register custom exception handler for RateLimitExceeded
• Add configuration check in lifespan function to log rate limiting status

5. Apply Rate Limits to Authentication Endpoints

Since authentication is handled externally by BetterAuth, focus on session-related endpoints in file:codeframe/ui/routers/session.py:

• Import rate limit decorator: from codeframe.lib.rate_limiter import rate_limit_standard
• Apply @rate_limit_standard() decorator to get_session_state endpoint (line 21)
• Note: If BetterAuth endpoints are added to this codebase in the future, apply @rate_limit_auth() to login/register endpoints

6. Apply Rate Limits to Standard API Endpoints

Apply @rate_limit_standard() decorator to all standard CRUD endpoints across routers:

file:codeframe/ui/routers/projects.py:

• Import rate limit decorator
• Apply to all endpoints: create_project, list_projects, get_project, update_project, delete_project

file:codeframe/ui/routers/tasks.py:

• Import rate limit decorator
• Apply to all task management endpoints

file:codeframe/ui/routers/agents.py:

• Import rate limit decorator
• Apply to agent management endpoints

file:codeframe/ui/routers/blockers.py:

• Import rate limit decorator
• Apply to blocker management endpoints

file:codeframe/ui/routers/checkpoints.py:

• Import rate limit decorator
• Apply to checkpoint endpoints

file:codeframe/ui/routers/metrics.py:

• Import rate limit decorator
• Apply to metrics endpoints

file:codeframe/ui/routers/quality_gates.py:

• Import rate limit decorator
• Apply to quality gate endpoints

file:codeframe/ui/routers/review.py:

• Import rate limit decorator
• Apply to review endpoints

file:codeframe/ui/routers/context.py:

• Import rate limit decorator
• Apply to context management endpoints

file:codeframe/ui/routers/discovery.py:

• Import rate limit decorator
• Apply to discovery endpoints

file:codeframe/ui/routers/lint.py:

• Import rate limit decorator
• Apply to lint endpoints

7. Apply Rate Limits to AI/Expensive Operations

Modify file:codeframe/ui/routers/chat.py:

• Import AI rate limit decorator: from codeframe.lib.rate_limiter import rate_limit_ai
• Apply @rate_limit_ai() decorator to chat_with_lead endpoint (line 26)
• Keep @rate_limit_standard() for get_chat_history endpoint (line 105)

8. Apply Rate Limits to WebSocket Endpoints

Modify file:codeframe/ui/routers/websocket.py:

• Import WebSocket rate limit decorator: from codeframe.lib.rate_limiter import rate_limit_websocket
• Apply rate limiting to WebSocket connection endpoint
• Note: WebSocket rate limiting may require special handling; consider limiting connection attempts rather than individual messages

9. Update Environment Configuration

Update file:.env.example:

• Add new section "Rate Limiting Configuration" after line 76
• Add environment variables with descriptions:
  • RATE_LIMIT_ENABLED=true (enable/disable rate limiting)
  • RATE_LIMIT_AUTH=10/minute (authentication endpoints)
  • RATE_LIMIT_STANDARD=100/minute (standard API endpoints)
  • RATE_LIMIT_AI=20/minute (AI/expensive operations)
  • RATE_LIMIT_WEBSOCKET=30/minute (WebSocket connections)
  • RATE_LIMIT_STORAGE=memory (storage backend: memory or redis)
  • REDIS_URL=redis://localhost:6379 (optional, for distributed rate limiting)

10. Update Global Configuration

Modify file:codeframe/core/config.py:

• Add rate limiting fields to GlobalConfig class (around line 112):
  • rate_limit_enabled: bool = Field(True, alias="RATE_LIMIT_ENABLED")
  • rate_limit_storage: str = Field("memory", alias="RATE_LIMIT_STORAGE")
  • redis_url: Optional[str] = Field(None, alias="REDIS_URL")
• Add validator for rate_limit_storage to ensure it's either "memory" or "redis"

11. Enhance Audit Logging for Rate Limiting

Modify file:codeframe/lib/audit_logger.py:

• Add new audit event types to AuditEventType enum:
  • RATE_LIMIT_EXCEEDED = "rate_limit.exceeded"
  • RATE_LIMIT_WARNING = "rate_limit.warning" (for approaching limits)
• Implement logging in rate limit exception handler to track:
  • User ID (if authenticated)
  • IP address
  • Endpoint path
  • Rate limit category
  • Timestamp

12. Add Rate Limit Monitoring Endpoint

Create new endpoint in file:codeframe/ui/server.py or new router:

• GET /api/rate-limits/status - Returns current rate limit status for authenticated user:
  • Remaining requests for each category
  • Reset timestamps
  • Current limits
• Requires authentication via get_current_user dependency
• Useful for frontend to display rate limit status to users

Architecture Diagram

sequenceDiagram
    participant Client
    participant FastAPI
    participant RateLimiter
    participant Auth
    participant Router
    participant AuditLog

    Client->>FastAPI: HTTP Request
    FastAPI->>RateLimiter: Check rate limit
    
    alt Authenticated Request
        RateLimiter->>Auth: Extract user ID from token
        Auth-->>RateLimiter: User ID
        RateLimiter->>RateLimiter: Check per-user limit
    else Unauthenticated Request
        RateLimiter->>RateLimiter: Extract IP address
        RateLimiter->>RateLimiter: Check per-IP limit
    end
    
    alt Rate limit exceeded
        RateLimiter->>AuditLog: Log rate limit exceeded
        RateLimiter-->>FastAPI: 429 Too Many Requests
        FastAPI-->>Client: 429 + Headers (Retry-After, X-RateLimit-*)
    else Rate limit OK
        RateLimiter-->>FastAPI: Allow request
        FastAPI->>Router: Route to endpoint
        Router-->>FastAPI: Response
        FastAPI-->>Client: 200 + Rate limit headers
    end

Loading

Rate Limit Categories

Category	Endpoints	Default Limit	Key Type
Authentication	Login, Register, Session (external BetterAuth)	10/minute	IP address
Standard API	Projects, Tasks, Agents, Metrics, etc.	100/minute	User ID
AI Operations	Chat with Lead Agent	20/minute	User ID
WebSocket	WebSocket connections	30/minute	User ID

Configuration Summary

Environment Variable	Default Value	Description
RATE_LIMIT_ENABLED	true	Enable/disable rate limiting
RATE_LIMIT_AUTH	10/minute	Authentication endpoint limit
RATE_LIMIT_STANDARD	100/minute	Standard API endpoint limit
RATE_LIMIT_AI	20/minute	AI operation endpoint limit
RATE_LIMIT_WEBSOCKET	30/minute	WebSocket connection limit
RATE_LIMIT_STORAGE	memory	Storage backend (memory/redis)
REDIS_URL	None	Redis connection URL (optional)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase is a FastAPI application with multiple routers handling various endpoints (projects, tasks, chat, agents, etc.). Authentication is managed via Bearer tokens stored in sessions, with an existing audit logging system. Currently, there is no rate limiting mechanism in place. The application uses SQLite with aiosqlite for persistence, and dependencies are managed via `pyproject.toml`. The chat endpoint represents the primary AI/expensive operation requiring stricter rate limits.

## Approach

Implement rate limiting using the `slowapi` library, which integrates seamlessly with FastAPI and supports both in-memory and Redis-based storage. Create a dedicated rate limiting middleware module in `codeframe/lib/` that provides decorators for different endpoint categories. Configure rate limits via environment variables for flexibility across deployment environments. Apply rate limits at the router level using dependency injection, with per-user limits for authenticated endpoints and per-IP limits for unauthenticated endpoints. Return proper 429 responses with standard rate limit headers.

## Implementation Steps

### 1. Add Rate Limiting Dependencies

Add `slowapi` to the dependencies list in `file:pyproject.toml`:
- Add `slowapi>=0.1.9` to the `dependencies` array (around line 54)
- Optionally add `redis>=5.0.0` for distributed rate limiting in production (can be added later)

### 2. Create Rate Limiting Configuration Module

Create new file `file:codeframe/config/rate_limits.py`:
- Define `RateLimitConfig` dataclass with fields for each endpoint category:
  - `auth_limit`: Rate limit for authentication endpoints (default: "10/minute")
  - `standard_limit`: Rate limit for standard API endpoints (default: "100/minute")
  - `ai_limit`: Rate limit for AI/expensive operations (default: "20/minute")
  - `websocket_limit`: Rate limit for WebSocket connections (default: "30/minute")
- Implement `from_environment()` classmethod to load from environment variables:
  - `RATE_LIMIT_AUTH` (default: "10/minute")
  - `RATE_LIMIT_STANDARD` (default: "100/minute")
  - `RATE_LIMIT_AI` (default: "20/minute")
  - `RATE_LIMIT_WEBSOCKET` (default: "30/minute")
  - `RATE_LIMIT_ENABLED` (default: "true")
  - `RATE_LIMIT_STORAGE` (default: "memory", options: "memory" or "redis")
  - `REDIS_URL` (optional, for distributed rate limiting)
- Add global instance getter `get_rate_limit_config()`

### 3. Create Rate Limiting Middleware Module

Create new file `file:codeframe/lib/rate_limiter.py`:
- Import `slowapi` components: `Limiter`, `_rate_limit_exceeded_handler`
- Create rate limiter instance with key function that:
  - For authenticated requests: extracts user ID from Bearer token (via `get_current_user_optional`)
  - For unauthenticated requests: extracts client IP from `X-Forwarded-For` or `request.client.host`
- Implement `get_rate_limiter()` function that returns configured `Limiter` instance
- Create decorator functions for each category:
  - `@rate_limit_auth()`: Applies auth rate limit
  - `@rate_limit_standard()`: Applies standard rate limit
  - `@rate_limit_ai()`: Applies AI operation rate limit
  - `@rate_limit_websocket()`: Applies WebSocket rate limit
- Implement custom exception handler for 429 responses that includes:
  - Standard HTTP 429 status code
  - `Retry-After` header (seconds until limit resets)
  - `X-RateLimit-Limit` header (total allowed requests)
  - `X-RateLimit-Remaining` header (remaining requests)
  - `X-RateLimit-Reset` header (Unix timestamp when limit resets)
  - JSON response body with error details

### 4. Integrate Rate Limiter into FastAPI Application

Modify `file:codeframe/ui/server.py`:
- Import rate limiter components from `codeframe.lib.rate_limiter`
- Add rate limiter state to FastAPI app (around line 206, after app creation):
  - `app.state.limiter = get_rate_limiter()`
  - Register `SlowAPIMiddleware` with the app
  - Register custom exception handler for `RateLimitExceeded`
- Add configuration check in `lifespan` function to log rate limiting status

### 5. Apply Rate Limits to Authentication Endpoints

Since authentication is handled externally by BetterAuth, focus on session-related endpoints in `file:codeframe/ui/routers/session.py`:
- Import rate limit decorator: `from codeframe.lib.rate_limiter import rate_limit_standard`
- Apply `@rate_limit_standard()` decorator to `get_session_state` endpoint (line 21)
- Note: If BetterAuth endpoints are added to this codebase in the future, apply `@rate_limit_auth()` to login/register endpoints

### 6. Apply Rate Limits to Standard API Endpoints

Apply `@rate_limit_standard()` decorator to all standard CRUD endpoints across routers:

**file:codeframe/ui/routers/projects.py:**
- Import rate limit decorator
- Apply to all endpoints: `create_project`, `list_projects`, `get_project`, `update_project`, `delete_project`

**file:codeframe/ui/routers/tasks.py:**
- Import rate limit decorator
- Apply to all task management endpoints

**file:codeframe/ui/routers/agents.py:**
- Import rate limit decorator
- Apply to agent management endpoints

**file:codeframe/ui/routers/blockers.py:**
- Import rate limit decorator
- Apply to blocker management endpoints

**file:codeframe/ui/routers/checkpoints.py:**
- Import rate limit decorator
- Apply to checkpoint endpoints

**file:codeframe/ui/routers/metrics.py:**
- Import rate limit decorator
- Apply to metrics endpoints

**file:codeframe/ui/routers/quality_gates.py:**
- Import rate limit decorator
- Apply to quality gate endpoints

**file:codeframe/ui/routers/review.py:**
- Import rate limit decorator
- Apply to review endpoints

**file:codeframe/ui/routers/context.py:**
- Import rate limit decorator
- Apply to context management endpoints

**file:codeframe/ui/routers/discovery.py:**
- Import rate limit decorator
- Apply to discovery endpoints

**file:codeframe/ui/routers/lint.py:**
- Import rate limit decorator
- Apply to lint endpoints

### 7. Apply Rate Limits to AI/Expensive Operations

Modify `file:codeframe/ui/routers/chat.py`:
- Import AI rate limit decorator: `from codeframe.lib.rate_limiter import rate_limit_ai`
- Apply `@rate_limit_ai()` decorator to `chat_with_lead` endpoint (line 26)
- Keep `@rate_limit_standard()` for `get_chat_history` endpoint (line 105)

### 8. Apply Rate Limits to WebSocket Endpoints

Modify `file:codeframe/ui/routers/websocket.py`:
- Import WebSocket rate limit decorator: `from codeframe.lib.rate_limiter import rate_limit_websocket`
- Apply rate limiting to WebSocket connection endpoint
- Note: WebSocket rate limiting may require special handling; consider limiting connection attempts rather than individual messages

### 9. Update Environment Configuration

Update `file:.env.example`:
- Add new section "Rate Limiting Configuration" after line 76
- Add environment variables with descriptions:
  - `RATE_LIMIT_ENABLED=true` (enable/disable rate limiting)
  - `RATE_LIMIT_AUTH=10/minute` (authentication endpoints)
  - `RATE_LIMIT_STANDARD=100/minute` (standard API endpoints)
  - `RATE_LIMIT_AI=20/minute` (AI/expensive operations)
  - `RATE_LIMIT_WEBSOCKET=30/minute` (WebSocket connections)
  - `RATE_LIMIT_STORAGE=memory` (storage backend: memory or redis)
  - `REDIS_URL=redis://localhost:6379` (optional, for distributed rate limiting)

### 10. Update Global Configuration

Modify `file:codeframe/core/config.py`:
- Add rate limiting fields to `GlobalConfig` class (around line 112):
  - `rate_limit_enabled: bool = Field(True, alias="RATE_LIMIT_ENABLED")`
  - `rate_limit_storage: str = Field("memory", alias="RATE_LIMIT_STORAGE")`
  - `redis_url: Optional[str] = Field(None, alias="REDIS_URL")`
- Add validator for `rate_limit_storage` to ensure it's either "memory" or "redis"

### 11. Enhance Audit Logging for Rate Limiting

Modify `file:codeframe/lib/audit_logger.py`:
- Add new audit event types to `AuditEventType` enum:
  - `RATE_LIMIT_EXCEEDED = "rate_limit.exceeded"`
  - `RATE_LIMIT_WARNING = "rate_limit.warning"` (for approaching limits)
- Implement logging in rate limit exception handler to track:
  - User ID (if authenticated)
  - IP address
  - Endpoint path
  - Rate limit category
  - Timestamp

### 12. Add Rate Limit Monitoring Endpoint

Create new endpoint in `file:codeframe/ui/server.py` or new router:
- `GET /api/rate-limits/status` - Returns current rate limit status for authenticated user:
  - Remaining requests for each category
  - Reset timestamps
  - Current limits
- Requires authentication via `get_current_user` dependency
- Useful for frontend to display rate limit status to users

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Client
    participant FastAPI
    participant RateLimiter
    participant Auth
    participant Router
    participant AuditLog

    Client->>FastAPI: HTTP Request
    FastAPI->>RateLimiter: Check rate limit
    
    alt Authenticated Request
        RateLimiter->>Auth: Extract user ID from token
        Auth-->>RateLimiter: User ID
        RateLimiter->>RateLimiter: Check per-user limit
    else Unauthenticated Request
        RateLimiter->>RateLimiter: Extract IP address
        RateLimiter->>RateLimiter: Check per-IP limit
    end
    
    alt Rate limit exceeded
        RateLimiter->>AuditLog: Log rate limit exceeded
        RateLimiter-->>FastAPI: 429 Too Many Requests
        FastAPI-->>Client: 429 + Headers (Retry-After, X-RateLimit-*)
    else Rate limit OK
        RateLimiter-->>FastAPI: Allow request
        FastAPI->>Router: Route to endpoint
        Router-->>FastAPI: Response
        FastAPI-->>Client: 200 + Rate limit headers
    end
```

## Rate Limit Categories

| Category | Endpoints | Default Limit | Key Type |
|----------|-----------|---------------|----------|
| Authentication | Login, Register, Session (external BetterAuth) | 10/minute | IP address |
| Standard API | Projects, Tasks, Agents, Metrics, etc. | 100/minute | User ID |
| AI Operations | Chat with Lead Agent | 20/minute | User ID |
| WebSocket | WebSocket connections | 30/minute | User ID |

## Configuration Summary

| Environment Variable | Default Value | Description |
|---------------------|---------------|-------------|
| `RATE_LIMIT_ENABLED` | `true` | Enable/disable rate limiting |
| `RATE_LIMIT_AUTH` | `10/minute` | Authentication endpoint limit |
| `RATE_LIMIT_STANDARD` | `100/minute` | Standard API endpoint limit |
| `RATE_LIMIT_AI` | `20/minute` | AI operation endpoint limit |
| `RATE_LIMIT_WEBSOCKET` | `30/minute` | WebSocket connection limit |
| `RATE_LIMIT_STORAGE` | `memory` | Storage backend (memory/redis) |
| `REDIS_URL` | `None` | Redis connection URL (optional) |

---

Execution Information

Branch: main
Commit: 0c96591

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.