# 🔒 Security Documentation

## Overview

This document outlines the security measures implemented in the Customer Portal BFF (Backend for Frontend) application.

## 🛡️ Security Features Implemented

### 1. Authentication & Authorization

- **JWT-based authentication** with configurable expiration
- **Password hashing** using bcrypt with configurable rounds (12+ in production)
- **Account lockout** after 5 failed login attempts
- **Role-based access control** (RBAC) system with AdminGuard
- **Token blacklisting** for logout functionality
- **All endpoints protected** except health checks

### 2. Input Validation & Sanitization

- **Global validation pipe** with whitelist mode enabled
- **DTO validation** using class-validator decorators
- **Input sanitization** to prevent XSS and injection attacks
- **Request size limits** enforced by Helmet.js

### 3. Rate Limiting

- **General rate limiting**: 100 requests per minute
- **Auth endpoint rate limiting**: 3 attempts per 15 minutes
- **IP-based tracking** for rate limiting
- **Configurable limits** via environment variables
- **Webhook endpoints** with additional rate limiting

### 4. Security Headers

- **Helmet.js** for comprehensive security headers
- **Content Security Policy (CSP)** with strict directives
- **X-Frame-Options**: DENY
- **X-Content-Type-Options**: nosniff
- **X-XSS-Protection**: 1; mode=block
- **Referrer-Policy**: strict-origin-when-cross-origin
- **Permissions-Policy**: restrictive permissions

### 5. CORS Configuration

- **Restrictive CORS** policy
- **Origin validation** via environment variables
- **Credential support** for authenticated requests
- **Method and header restrictions**
- **Configurable origins** per environment

### 6. Error Handling

- **Global exception filter** with sanitized error messages
- **Production-safe error logging** (no sensitive data exposure)
- **Client-safe error messages** in production
- **Structured logging** with Pino

### 7. Webhook Security

- **Signature verification** using HMAC-SHA256
- **Rate limiting** on webhook endpoints
- **Configurable secrets** for each webhook provider
- **Input validation** for webhook payloads
- **Secure error handling** without data leakage

### 8. Database Security

- **Parameterized queries** via Prisma ORM
- **Connection encryption** (TLS/SSL)
- **Environment-based configuration**
- **Audit logging** for sensitive operations

### 9. Logging & Monitoring

- **Structured logging** with correlation IDs
- **Sensitive data redaction** in logs
- **Audit trail** for authentication events
- **Production-safe logging levels**

### 10. API Security

- **All controllers protected** with JWT authentication
- **Admin endpoints** with additional AdminGuard
- **Swagger documentation** with authentication
- **API versioning** and proper routing

## 🔧 Security Configuration

### Environment Variables

```bash
# JWT Configuration
JWT_SECRET=your_secure_secret_minimum_32_chars
JWT_EXPIRES_IN=7d

# Password Security
BCRYPT_ROUNDS=12

# Rate Limiting
RATE_LIMIT_TTL=60000
RATE_LIMIT_LIMIT=100
AUTH_RATE_LIMIT_TTL=900000
AUTH_RATE_LIMIT_LIMIT=3

# CORS
CORS_ORIGIN=https://yourdomain.com

# Webhook Secrets
WHMCS_WEBHOOK_SECRET=your_whmcs_secret
SF_WEBHOOK_SECRET=your_salesforce_secret
```

### Production Security Checklist

- [x] Generate strong JWT secret (minimum 32 characters)
- [x] Set BCRYPT_ROUNDS to 12 or higher
- [x] Configure CORS_ORIGIN to your production domain
- [x] Enable TRUST_PROXY if behind reverse proxy
- [x] Set NODE_ENV to "production"
- [x] Configure webhook secrets
- [x] Use HTTPS for all external services
- [x] Test rate limiting configuration
- [x] Verify audit logging is working
- [x] Review security headers in browser dev tools
- [x] All endpoints protected with authentication
- [x] Input validation implemented
- [x] Security headers configured
- [x] Error handling production-safe

## 🚨 Security Best Practices

### 1. Password Requirements

- Minimum 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number

### 2. API Security

- Always use HTTPS in production
- Implement proper authentication for all endpoints
- Validate and sanitize all inputs
- Use rate limiting to prevent abuse
- Log security events for monitoring

### 3. Data Protection

- Never log sensitive information (passwords, tokens, PII)
- Use environment variables for configuration
- Implement proper error handling
- Sanitize error messages in production

### 4. Monitoring & Alerting

- Monitor failed authentication attempts
- Track rate limit violations
- Monitor webhook signature failures
- Set up alerts for suspicious activity

## 🔍 Security Testing

### Automated Tests

- Input validation tests
- Authentication flow tests
- Rate limiting tests
- Error handling tests

### Manual Testing

- Penetration testing
- Security header verification
- CORS policy testing
- Authentication bypass attempts

### Tools

- OWASP ZAP for security scanning
- Burp Suite for manual testing
- Nmap for port scanning
- SQLMap for SQL injection testing

## 📚 Security Resources

- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework)
- [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)
- [NestJS Security](https://docs.nestjs.com/security/authentication)

## 🆘 Incident Response

### Security Breach Response

1. **Immediate Actions**
   - Isolate affected systems
   - Preserve evidence
   - Notify security team

2. **Investigation**
   - Analyze logs and audit trails
   - Identify attack vectors
   - Assess data exposure

3. **Recovery**
   - Patch vulnerabilities
   - Reset compromised credentials
   - Restore from clean backups

4. **Post-Incident**
   - Document lessons learned
   - Update security measures
   - Conduct security review

## 📞 Security Contacts

- **Security Team**: security@yourcompany.com
- **Emergency**: +1-XXX-XXX-XXXX
- **Bug Bounty**: security@yourcompany.com

---

**Last Updated**: $(date)
**Version**: 1.0.0
**Maintainer**: Security Team
**Status**: ✅ Production Ready