# Security Enhancements

This document describes the security enhancements implemented for the Ultimate Lists App as part of task 17.

## Overview

The following security measures have been implemented to protect the application and user data:

1. **Rate Limiting** (Requirement 9.3)
2. **CSRF Protection** (Requirement 9.4)
3. **Secure Session Cookie Configuration** (Requirement 9.5)
4. **Input Sanitization** (Requirement 9.5)

## 1. Rate Limiting

### Implementation

A comprehensive rate limiting system has been implemented in `lib/rate-limit.ts` to prevent brute force attacks and abuse.

### Features

- **In-memory rate limiting** with automatic cleanup to prevent memory leaks
- **Configurable limits** for different operations
- **Client identification** using IP address from headers (X-Forwarded-For, X-Real-IP)
- **Graceful degradation** in test environments where headers are not available

### Rate Limit Configurations

| Operation | Max Requests | Time Window | Purpose |
|-----------|-------------|-------------|---------|
| Login | 5 | 15 minutes | Prevent brute force attacks on user accounts |
| Registration | 3 | 1 hour | Prevent spam account creation |
| Password Reset | 3 | 1 hour | Prevent password reset abuse |
| Invitations | 10 | 1 hour | Prevent invitation spam |

### Usage

Rate limiting is automatically applied to:
- User registration (`registerUser`)
- User login (`loginUser`)
- List invitations (`inviteUserToList`)

On successful login, the rate limit is reset for that user to allow immediate subsequent logins.

### Error Messages

When rate limits are exceeded, users receive clear error messages indicating:
- The reason for the block
- How long they need to wait before trying again

Example: "Too many login attempts. Please try again in 12 minutes."

## 2. CSRF Protection

### Implementation

CSRF protection is implemented through multiple layers:

1. **SameSite Cookie Attribute** (`auth.ts`)
   - Session cookies are configured with `sameSite: 'lax'`
   - Prevents cookies from being sent in cross-site requests
   - Protects against CSRF attacks

2. **Security Headers** (`middleware.ts`)
   - `X-Content-Type-Options: nosniff` - Prevents MIME type sniffing
   - `X-Frame-Options: DENY` - Prevents clickjacking attacks
   - Additional headers for defense in depth

3. **NextAuth Built-in CSRF Protection**
   - NextAuth.js v5 includes built-in CSRF token validation
   - Automatically validates CSRF tokens on authentication requests

## 3. Secure Session Cookie Configuration

### Implementation

Session cookies are configured with security best practices in `auth.ts`:

```typescript
cookies: {
  sessionToken: {
    name: `${process.env.NODE_ENV === 'production' ? '__Secure-' : ''}next-auth.session-token`,
    options: {
      httpOnly: true,      // Prevent JavaScript access (XSS protection)
      sameSite: 'lax',     // CSRF protection
      path: '/',
      secure: process.env.NODE_ENV === 'production', // HTTPS only in production
    },
  },
}
```

### Security Features

- **httpOnly**: Prevents client-side JavaScript from accessing the cookie, protecting against XSS attacks
- **secure**: Ensures cookies are only sent over HTTPS in production
- **sameSite**: Prevents CSRF attacks by restricting cross-site cookie sending
- **__Secure- prefix**: In production, uses the `__Secure-` prefix which requires the secure flag

### Session Configuration

- **Strategy**: JWT (stateless)
- **Max Age**: 30 days
- **Update Age**: 24 hours (session refreshed daily)

## 4. Input Sanitization

### Implementation

Comprehensive input sanitization has been implemented in `lib/validation.ts` to prevent various injection attacks.

### Sanitization Functions

#### `sanitizeString(input)`
- Trims whitespace
- Removes null bytes (`\0`)
- Removes control characters (except newlines and tabs)
- Used for all text inputs

#### `sanitizeEmail(input)`
- Converts to lowercase
- Trims whitespace
- Removes internal whitespace
- Removes control characters
- Used for email inputs

#### `sanitizeHtml(input)`
- Removes script tags and their content
- Removes event handlers (onclick, onerror, etc.)
- Removes javascript: protocol
- Removes data: protocol
- Strips all HTML tags
- Encodes special HTML characters (&, <, >, ", ', /)
- Prevents XSS attacks

#### `sanitizeSqlInput(input)`
- Removes SQL comment markers (-- and /* */)
- Removes semicolons
- Defense-in-depth measure (primary protection is parameterized queries)

### Application

Input sanitization is applied to:
- All user registration and login inputs
- List titles and descriptions
- Item titles, descriptions, notes, and tags
- Email addresses for invitations
- All user profile updates

## 5. Additional Security Headers

### Implementation

Security headers are added in `middleware.ts` to all responses:

```typescript
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: [comprehensive policy]
Permissions-Policy: camera=(), microphone=(), geolocation=()
```

### Purpose

- **X-Content-Type-Options**: Prevents MIME type sniffing
- **X-XSS-Protection**: Enables browser XSS filter
- **X-Frame-Options**: Prevents clickjacking
- **Referrer-Policy**: Controls referrer information leakage
- **Content-Security-Policy**: Restricts resource loading to prevent XSS
- **Permissions-Policy**: Restricts access to browser features

## Testing

### Test Coverage

Comprehensive tests have been added in `lib/__tests__/security.test.ts`:

- **Rate Limiting Tests** (11 tests)
  - Request allowance within limits
  - Request blocking when limits exceeded
  - Rate limit reset after window expiration
  - Separate tracking for different keys
  - Rate limit reset functionality
  - Configuration validation
  - Client identifier extraction

- **Input Sanitization Tests** (19 tests)
  - String sanitization
  - Email sanitization
  - HTML sanitization
  - SQL input sanitization

- **Input Validation Tests** (11 tests)
  - Email validation
  - Password validation

All 41 security tests pass successfully.

## Production Considerations

### Rate Limiting

The current implementation uses in-memory storage for rate limits. For production deployments with multiple servers, consider:

- Using Redis or similar distributed cache
- Implementing rate limiting at the load balancer level
- Monitoring rate limit hits for security analysis

### Session Security

- Ensure `NEXTAUTH_SECRET` is set to a strong, random value
- Use HTTPS in production (enforced by secure cookie flag)
- Monitor session creation and expiration patterns

### Input Sanitization

- All user inputs are sanitized before storage
- Parameterized queries are used for database operations (Prisma ORM)
- Regular security audits recommended

### Security Headers

- CSP policy may need adjustment based on third-party integrations
- Monitor CSP violations in production
- Consider adding Subresource Integrity (SRI) for external scripts

## Compliance

These security enhancements help meet common security standards:

- **OWASP Top 10**: Addresses injection, broken authentication, XSS, and CSRF
- **GDPR**: Protects user data through secure authentication and access control
- **PCI DSS**: Implements security best practices for web applications

## Maintenance

### Regular Updates

- Keep dependencies updated (NextAuth, bcrypt, etc.)
- Review and update rate limit configurations based on usage patterns
- Monitor security advisories for Next.js and related packages

### Monitoring

Consider implementing:
- Logging of rate limit violations
- Alerting on suspicious authentication patterns
- Regular security audits and penetration testing

## References

- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/)
- [NextAuth.js Security](https://next-auth.js.org/configuration/options#security)
- [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
- [OWASP Rate Limiting](https://cheatsheetseries.owasp.org/cheatsheets/Denial_of_Service_Cheat_Sheet.html)