# Security Architecture & Best Practices

This document outlines the security architecture and best practices for the Playwright Web Proxy.

## Table of Contents

- [Security Features](#security-features)
- [Authentication & Authorization](#authentication--authorization)
- [Rate Limiting & DDoS Protection](#rate-limiting--ddos-protection)
- [Anti-Bot Measures](#anti-bot-measures)
- [Data Security](#data-security)
- [Network Security](#network-security)
- [Secrets Management](#secrets-management)
- [Security Hardening](#security-hardening)
- [Compliance](#compliance)
- [Incident Response](#incident-response)

## Security Features

### Built-in Security Layers

1. **Authentication**: JWT-based token authentication
2. **Rate Limiting**: Per-endpoint and per-user limits
3. **IP Banning**: Automatic banning on failed auth attempts
4. **Session Isolation**: Each browser session is isolated
5. **Input Validation**: All inputs are validated and sanitized
6. **CORS**: Configurable cross-origin resource sharing
7. **Helmet**: Security headers via helmet middleware
8. **Secure Communications**: Support for TLS/HTTPS

## Authentication & Authorization

### JWT Authentication

The system uses JSON Web Tokens (JWT) for authentication:

```typescript
// Token structure
{
  "userId": "user@example.com",
  "email": "user@example.com",
  "role": "user",
  "iat": 1234567890,
  "exp": 1234654290
}
```

### Best Practices

1. **Use Strong Secrets:**
   ```bash
   # Generate secure random secrets
   openssl rand -base64 32
   ```

2. **Token Expiration:**
   - Default: 24 hours
   - Production: Consider shorter expiration (1-4 hours)
   - Implement refresh token mechanism

3. **Secure Storage:**
   - Never commit secrets to version control
   - Use environment variables or secret management systems
   - Rotate secrets regularly

### User Management

**Production Implementation:**

Replace the in-memory user store with a proper database:

```typescript
// Use PostgreSQL, MySQL, or MongoDB
import { User } from './models/User';

export async function authenticateUser(credentials: UserCredentials) {
  const user = await User.findOne({ email: credentials.email });
  // ... validation logic
}
```

### Role-Based Access Control (RBAC)

Implement roles for different access levels:

```typescript
enum UserRole {
  ADMIN = 'admin',
  USER = 'user',
  VIEWER = 'viewer'
}

// Middleware for role checking
app.get('/admin/stats', requireRole('admin'), getStats);
```

## Rate Limiting & DDoS Protection

### Rate Limiting Configuration

The application implements three levels of rate limiting:

1. **API Rate Limiting:**
   - 100 requests per 15 minutes
   - Applies to all API endpoints

2. **Authentication Rate Limiting:**
   - 5 attempts per 15 minutes
   - Prevents brute force attacks

3. **Session Creation Rate Limiting:**
   - 10 sessions per minute per user
   - Prevents resource exhaustion

### IP Banning

Automatic IP banning on suspicious activity:

- **Threshold**: 5 failed authentication attempts
- **Duration**: 1 hour (configurable)
- **Scope**: IP-based blocking

**Configuration:**

```env
ENABLE_IP_BANNING=true
MAX_FAILED_AUTH_ATTEMPTS=5
BAN_DURATION_MS=3600000
```

### DDoS Protection

**Additional Layers:**

1. **Reverse Proxy:**
   ```nginx
   limit_req_zone $binary_remote_addr zone=general:10m rate=10r/s;
   limit_conn_zone $binary_remote_addr zone=addr:10m;

   server {
       limit_req zone=general burst=20 nodelay;
       limit_conn addr 10;
   }
   ```

2. **Cloud Provider DDoS Protection:**
   - AWS Shield
   - Cloudflare DDoS protection
   - Azure DDoS Protection

3. **Rate Limiting at Infrastructure Level:**
   - Kubernetes Ingress rate limiting
   - API Gateway throttling

## Anti-Bot Measures

### Implemented Measures

1. **User Agent Randomization:**
   - Random desktop/mobile user agents
   - Configured per session

2. **Header Spoofing:**
   - Realistic HTTP headers
   - Accept-Language, Accept-Encoding, etc.

3. **Timezone Spoofing:**
   - Random timezone per session
   - Matches geolocation if provided

4. **WebDriver Detection Bypass:**
   ```javascript
   // Removes navigator.webdriver
   Object.defineProperty(navigator, 'webdriver', {
     get: () => false,
   });
   ```

5. **Chrome Runtime:**
   ```javascript
   window.chrome = { runtime: {} };
   ```

### Configuration

```env
ENABLE_HEADER_SPOOFING=true
ENABLE_UA_RANDOMIZATION=true
ENABLE_TIMEZONE_SPOOFING=true
```

### Advanced Anti-Detection

For more robust anti-detection, consider:

1. **Playwright Stealth Plugin:**
   ```bash
   npm install playwright-extra playwright-extra-plugin-stealth
   ```

2. **Fingerprint Randomization:**
   - Canvas fingerprinting prevention
   - WebGL fingerprinting prevention
   - Audio context fingerprinting prevention

## Data Security

### Session Data

- **Storage**: Redis with optional encryption
- **TTL**: Automatic expiration based on idle timeout
- **Isolation**: Each session is isolated in separate context

### Sensitive Data Handling

1. **Never log sensitive data:**
   ```typescript
   // BAD
   logger.info('User logged in', { password: user.password });

   // GOOD
   logger.info('User logged in', { userId: user.id });
   ```

2. **Sanitize inputs:**
   ```typescript
   import validator from 'validator';

   const sanitizedUrl = validator.escape(userInputUrl);
   ```

3. **Encrypt sensitive data at rest:**
   ```typescript
   import crypto from 'crypto';

   function encrypt(text: string, key: string): string {
     const cipher = crypto.createCipher('aes-256-cbc', key);
     return cipher.update(text, 'utf8', 'hex') + cipher.final('hex');
   }
   ```

### GDPR Compliance

For EU users, implement:

1. **Data Minimization:**
   - Only collect necessary data
   - Clear retention policies

2. **Right to Access:**
   - Users can request their data
   - Provide data export functionality

3. **Right to Deletion:**
   - Users can delete their accounts
   - Cascade delete all associated data

4. **Cookie Consent:**
   - Implement cookie consent banner
   - Allow users to manage preferences

## Network Security

### HTTPS/TLS

**Production deployment MUST use HTTPS:**

1. **Certificate Management:**
   ```bash
   # Using cert-manager in Kubernetes
   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
   ```

2. **Force HTTPS:**
   ```typescript
   if (config.server.nodeEnv === 'production' && !req.secure) {
     return res.redirect('https://' + req.headers.host + req.url);
   }
   ```

### CORS Configuration

**Production CORS:**

```typescript
app.use(cors({
  origin: [
    'https://yourdomain.com',
    'https://app.yourdomain.com'
  ],
  credentials: true,
  methods: ['GET', 'POST', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization']
}));
```

### WebSocket Security

1. **Authentication Required:**
   - All WebSocket connections must authenticate
   - Token verification on connection

2. **Origin Validation:**
   ```typescript
   wss.on('connection', (ws, req) => {
     const origin = req.headers.origin;
     if (!allowedOrigins.includes(origin)) {
       ws.close();
       return;
     }
   });
   ```

3. **Rate Limiting:**
   - Limit message frequency
   - Prevent flooding attacks

## Secrets Management

### Environment Variables

**Never commit secrets to Git:**

```bash
# .gitignore
.env
.env.local
.env.production
secrets/
```

### Kubernetes Secrets

1. **Create secrets:**
   ```bash
   kubectl create secret generic app-secrets \
     --from-literal=session-secret=$(openssl rand -base64 32) \
     --from-literal=jwt-secret=$(openssl rand -base64 32)
   ```

2. **Reference in deployment:**
   ```yaml
   env:
     - name: SESSION_SECRET
       valueFrom:
         secretKeyRef:
           name: app-secrets
           key: session-secret
   ```

### Vault Integration (Advanced)

For enterprise deployments, use HashiCorp Vault:

```typescript
import Vault from 'node-vault';

const vault = Vault({
  endpoint: process.env.VAULT_ADDR,
  token: process.env.VAULT_TOKEN
});

const secrets = await vault.read('secret/data/playwright-proxy');
```

## Security Hardening

### Docker Security

1. **Non-root user:**
   ```dockerfile
   USER node
   ```

2. **Read-only filesystem:**
   ```dockerfile
   RUN mkdir -p /app/logs && chown node:node /app/logs
   USER node
   ```

3. **Security scanning:**
   ```bash
   docker scan playwright-proxy:latest
   ```

### Kubernetes Security

1. **Pod Security Standards:**
   ```yaml
   securityContext:
     runAsNonRoot: true
     runAsUser: 1000
     fsGroup: 2000
     capabilities:
       drop:
         - ALL
   ```

2. **Network Policies:**
   ```yaml
   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: playwright-proxy-netpol
   spec:
     podSelector:
       matchLabels:
         app: playwright-proxy
     policyTypes:
       - Ingress
       - Egress
     ingress:
       - from:
         - namespaceSelector:
             matchLabels:
               name: ingress-nginx
     egress:
       - to:
         - namespaceSelector:
             matchLabels:
               name: kube-system
   ```

3. **RBAC:**
   ```yaml
   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: playwright-proxy-role
   rules:
     - apiGroups: [""]
       resources: ["secrets", "configmaps"]
       verbs: ["get", "list"]
   ```

### Application Security

1. **Dependency Scanning:**
   ```bash
   npm audit
   npm audit fix
   ```

2. **Regular Updates:**
   ```bash
   npm update
   npx npm-check-updates -u
   ```

3. **Code Analysis:**
   ```bash
   npm run lint
   npx eslint src --ext .ts
   ```

## Compliance

### Security Auditing

1. **Enable audit logging:**
   ```typescript
   logger.info('Security event', {
     event: 'login_attempt',
     userId: user.id,
     ip: req.ip,
     timestamp: new Date(),
     success: true
   });
   ```

2. **Log retention:**
   - Minimum 90 days
   - Secure storage
   - Regular backups

### OWASP Top 10 Protection

1. **Injection**: Input validation and parameterized queries
2. **Broken Authentication**: JWT with proper expiration
3. **Sensitive Data Exposure**: HTTPS, encrypted storage
4. **XML External Entities**: N/A (no XML processing)
5. **Broken Access Control**: RBAC implementation
6. **Security Misconfiguration**: Security headers, proper CORS
7. **XSS**: Input sanitization, CSP headers
8. **Insecure Deserialization**: JSON only, validation
9. **Using Components with Known Vulnerabilities**: Regular updates
10. **Insufficient Logging**: Comprehensive logging

## Incident Response

### Security Incident Procedure

1. **Detection:**
   - Monitor logs for anomalies
   - Set up alerts for suspicious activity

2. **Containment:**
   ```bash
   # Block malicious IP
   kubectl exec -it proxy-pod -- iptables -A INPUT -s <IP> -j DROP

   # Scale down if under attack
   kubectl scale deployment playwright-proxy --replicas=0
   ```

3. **Investigation:**
   - Review logs
   - Analyze attack patterns
   - Identify vulnerabilities

4. **Recovery:**
   - Patch vulnerabilities
   - Restore from backup if needed
   - Update security measures

5. **Post-Incident:**
   - Document incident
   - Update security policies
   - Train team on lessons learned

### Emergency Contacts

Maintain a security contact list:
- Security Team Lead
- DevOps On-Call
- Management
- Legal (for data breaches)

## Security Checklist

### Pre-Production

- [ ] All secrets rotated from defaults
- [ ] HTTPS/TLS enabled
- [ ] Rate limiting configured
- [ ] CORS properly configured
- [ ] Security headers enabled
- [ ] Input validation implemented
- [ ] Dependency audit clean
- [ ] Container security scan passed
- [ ] Kubernetes security policies applied
- [ ] Monitoring and alerting configured

### Regular Security Tasks

- [ ] Weekly: Review access logs
- [ ] Weekly: Check for failed authentication attempts
- [ ] Monthly: Rotate secrets
- [ ] Monthly: Update dependencies
- [ ] Quarterly: Security audit
- [ ] Quarterly: Penetration testing
- [ ] Annually: Third-party security assessment

## Reporting Security Issues

If you discover a security vulnerability:

1. **Do NOT** open a public GitHub issue
2. Email: security@example.com
3. Include:
   - Description of vulnerability
   - Steps to reproduce
   - Potential impact
   - Suggested fix (if any)

We will respond within 48 hours.

## Resources

- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [CIS Kubernetes Benchmark](https://www.cisecurity.org/benchmark/kubernetes)
- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework)
- [Playwright Security Best Practices](https://playwright.dev/docs/library#security)