livedash-node/docs/security-headers.md

# HTTP Security Headers Implementation

This document describes the comprehensive HTTP security headers implementation in LiveDash-Node to protect against XSS, clickjacking, and other web vulnerabilities.

## Overview

The application implements multiple layers of HTTP security headers to provide defense-in-depth protection against common web vulnerabilities identified in OWASP Top 10 and security best practices.

## Implemented Security Headers

### Core Security Headers

#### X-Content-Type-Options: nosniff

-   **Purpose**: Prevents MIME type sniffing attacks
-   **Protection**: Stops browsers from interpreting files as different MIME types than declared
-   **Value**: `nosniff`

#### X-Frame-Options: DENY

-   **Purpose**: Prevents clickjacking attacks
-   **Protection**: Blocks embedding the site in frames/iframes
-   **Value**: `DENY`

#### X-XSS-Protection: 1; mode=block

-   **Purpose**: Enables XSS protection in legacy browsers
-   **Protection**: Activates built-in XSS filtering (primarily for older browsers)
-   **Value**: `1; mode=block`

#### Referrer-Policy: strict-origin-when-cross-origin

-   **Purpose**: Controls referrer information leakage
-   **Protection**: Limits referrer data sent to external sites
-   **Value**: `strict-origin-when-cross-origin`

#### X-DNS-Prefetch-Control: off

-   **Purpose**: Prevents DNS rebinding attacks
-   **Protection**: Disables DNS prefetching to reduce attack surface
-   **Value**: `off`

### Content Security Policy (CSP)

Comprehensive CSP implementation with the following directives:

```
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https:; frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'; upgrade-insecure-requests
```

#### Key CSP Directives

-   **default-src 'self'**: Restrictive default for all resource types
-   **script-src 'self' 'unsafe-eval' 'unsafe-inline'**: Allows Next.js dev tools and React functionality
-   **style-src 'self' 'unsafe-inline'**: Enables TailwindCSS and component styles
-   **img-src 'self' data: https:**: Allows secure image sources
-   **frame-ancestors 'none'**: Prevents embedding (reinforces X-Frame-Options)
-   **object-src 'none'**: Blocks dangerous plugins and embeds
-   **upgrade-insecure-requests**: Automatically upgrades HTTP to HTTPS

### Permissions Policy

Controls browser feature access:

```
Permissions-Policy: camera=(), microphone=(), geolocation=(), interest-cohort=(), browsing-topics=()
```

-   **camera=()**: Disables camera access
-   **microphone=()**: Disables microphone access
-   **geolocation=()**: Disables location tracking
-   **interest-cohort=()**: Blocks FLoC (privacy protection)
-   **browsing-topics=()**: Blocks Topics API (privacy protection)

### Strict Transport Security (HSTS)

**Production Only**: `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`

-   **max-age=31536000**: 1 year HSTS policy
-   **includeSubDomains**: Applies to all subdomains
-   **preload**: Ready for HSTS preload list inclusion

## Configuration

### Next.js Configuration

Headers are configured in `next.config.js`:

```javascript
headers: async () => {
  return [
    {
      source: "/(.*)",
      headers: [
        // Security headers configuration
      ],
    },
    {
      source: "/(.*)",
      headers:
        process.env.NODE_ENV === "production"
          ? [
              // HSTS header for production only
            ]
          : [],
    },
  ];
};
```

### Environment-Specific Behavior

-   **Development**: All headers except HSTS
-   **Production**: All headers including HSTS

## Testing

### Unit Tests

Location: `tests/unit/http-security-headers.test.ts`

Tests cover:

-   Individual header validation
-   CSP directive verification
-   Permissions Policy validation
-   Environment-specific configuration
-   Next.js compatibility checks

### Integration Tests

Location: `tests/integration/security-headers-basic.test.ts`

Tests cover:

-   Next.js configuration validation
-   Header generation verification
-   Environment-based header differences

### Manual Testing

Use the security headers testing script:

```bash
# Test local development server
pnpm test:security-headers http://localhost:3000

# Test production deployment
pnpm test:security-headers https://your-domain.com
```

## Security Benefits

### Protection Against OWASP Top 10

1.  **A03:2021 - Injection**: CSP prevents script injection
2.  **A05:2021 - Security Misconfiguration**: Comprehensive headers reduce attack surface
3.  **A06:2021 - Vulnerable Components**: CSP limits execution context
4.  **A07:2021 - Identification and Authentication Failures**: HSTS prevents downgrade attacks

### Additional Security Benefits

-   **Clickjacking Protection**: X-Frame-Options + CSP frame-ancestors
-   **MIME Sniffing Prevention**: X-Content-Type-Options
-   **Information Leakage Reduction**: Referrer-Policy
-   **Privacy Protection**: Permissions Policy restrictions
-   **Transport Security**: HSTS enforcement

## Maintenance

### Regular Reviews

1.  **Quarterly CSP Review**: Analyze CSP violations and tighten policies
2.  **Annual Header Audit**: Review new security headers and standards
3.  **Dependency Updates**: Ensure compatibility with framework updates

### Monitoring

-   Monitor CSP violation reports (when implemented)
-   Use online tools like securityheaders.com for validation
-   Include security header tests in CI/CD pipeline

### Future Enhancements

Planned improvements:

1.  CSP violation reporting endpoint
2.  Nonce-based CSP for inline scripts
3.  Additional Permissions Policy restrictions
4.  Content-Type validation middleware

## Compatibility

### Next.js Compatibility

Headers are configured to be compatible with:

-   Next.js 15+ App Router
-   React 19 development tools
-   TailwindCSS 4 styling system
-   Development hot reload functionality

### Browser Support

Security headers are supported by:

-   All modern browsers (Chrome 60+, Firefox 60+, Safari 12+)
-   Graceful degradation for older browsers
-   Progressive enhancement approach

## Troubleshooting

### Common Issues

1.  **CSP Violations**: Check browser console for CSP errors
2.  **Styling Issues**: Verify style-src allows 'unsafe-inline'
3.  **Script Errors**: Ensure script-src permits necessary scripts
4.  **Development Issues**: Use `pnpm dev:next-only` to isolate Next.js

### Debug Tools

-   Browser DevTools Security tab
-   CSP Evaluator: <https://csp-evaluator.withgoogle.com/>
-   Security Headers Scanner: <https://securityheaders.com/>

## References

-   [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/)
-   [MDN Security Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#security)
-   [Next.js Security Headers](https://nextjs.org/docs/app/api-reference/config/headers)
-   [Content Security Policy Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)