refactor: fix biome linting issues and update project documentation

- Fix 36+ biome linting issues reducing errors/warnings from 227 to 191 - Replace explicit 'any' types with proper TypeScript interfaces - Fix React hooks dependencies and useCallback patterns - Resolve unused variables and parameter assignment issues - Improve accessibility with proper label associations - Add comprehensive API documentation for admin and security features - Update README.md with accurate PostgreSQL setup and current tech stack - Create complete documentation for audit logging, CSP monitoring, and batch processing - Fix outdated project information and missing developer workflows
2026-01-16 16:32:08 +01:00 · 2025-07-11 21:50:53 +02:00
parent 3e9e75e854
commit 1eea2cc3e4
121 changed files with 28687 additions and 4895 deletions
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@ -0,0 +1,648 @@
+# LiveDash-Node API Reference
+
+This document provides a comprehensive reference for all API endpoints in the LiveDash-Node application, including authentication, security monitoring, audit logging, and administrative functions.
+
+## Base URL
+
+```
+Local Development: http://localhost:3000
+Production: https://your-domain.com
+```
+
+## Authentication
+
+All API endpoints (except public endpoints) require authentication via NextAuth.js session cookies.
+
+### Authentication Headers
+
+```http
+Cookie: next-auth.session-token=<session-token>
+```
+
+### CSRF Protection
+
+State-changing endpoints require CSRF tokens:
+
+```http
+X-CSRF-Token: <csrf-token>
+```
+
+Get CSRF token:
+```http
+GET /api/csrf-token
+```
+
+## API Endpoints Overview
+
+### Public Endpoints
+- `POST /api/csp-report` - CSP violation reporting (no auth required)
+- `OPTIONS /api/csp-report` - CORS preflight
+
+### Authentication Endpoints
+- `POST /api/auth/[...nextauth]` - NextAuth.js authentication
+- `GET /api/csrf-token` - Get CSRF token
+- `POST /api/register` - User registration
+- `POST /api/forgot-password` - Password reset request
+- `POST /api/reset-password` - Password reset completion
+
+### Admin Endpoints (ADMIN role required)
+- `GET /api/admin/audit-logs` - Retrieve audit logs
+- `POST /api/admin/audit-logs/retention` - Manage audit log retention
+- `GET /api/admin/batch-monitoring` - Batch processing monitoring
+- `POST /api/admin/batch-monitoring/{id}/retry` - Retry failed batch job
+
+### Platform Admin Endpoints (Platform admin only)
+- `GET /api/admin/security-monitoring` - Security monitoring metrics
+- `POST /api/admin/security-monitoring` - Update security configuration
+- `GET /api/admin/security-monitoring/alerts` - Alert management
+- `POST /api/admin/security-monitoring/alerts` - Acknowledge alerts
+- `GET /api/admin/security-monitoring/export` - Export security data
+- `POST /api/admin/security-monitoring/threat-analysis` - Threat analysis
+
+### Security Monitoring Endpoints
+- `GET /api/csp-metrics` - CSP violation metrics
+- `POST /api/csp-report` - CSP violation reporting
+
+### Dashboard Endpoints
+- `GET /api/dashboard/sessions` - Session data
+- `GET /api/dashboard/session/{id}` - Individual session details
+- `GET /api/dashboard/metrics` - Dashboard metrics
+- `GET /api/dashboard/config` - Dashboard configuration
+
+### Platform Management
+- `GET /api/platform/companies` - Company management
+- `POST /api/platform/companies` - Create company
+- `GET /api/platform/companies/{id}` - Company details
+- `GET /api/platform/companies/{id}/users` - Company users
+- `POST /api/platform/companies/{id}/users` - Add company user
+
+### tRPC Endpoints
+- `POST /api/trpc/[trpc]` - tRPC procedure calls
+
+## Detailed Endpoint Documentation
+
+### Admin Audit Logs
+
+#### Get Audit Logs
+```http
+GET /api/admin/audit-logs
+```
+
+**Authorization**: ADMIN role required
+
+**Query Parameters**:
+- `page` (number, optional): Page number (default: 1)
+- `limit` (number, optional): Records per page, max 100 (default: 50)
+- `eventType` (string, optional): Filter by event type
+- `outcome` (string, optional): Filter by outcome (SUCCESS, FAILURE, BLOCKED, etc.)
+- `severity` (string, optional): Filter by severity (LOW, MEDIUM, HIGH, CRITICAL)
+- `userId` (string, optional): Filter by user ID
+- `startDate` (string, optional): Start date (ISO 8601)
+- `endDate` (string, optional): End date (ISO 8601)
+
+**Response**:
+```json
+{
+  "success": true,
+  "data": {
+    "auditLogs": [...],
+    "pagination": {
+      "page": 1,
+      "limit": 50,
+      "totalCount": 150,
+      "totalPages": 3,
+      "hasNext": true,
+      "hasPrev": false
+    }
+  }
+}
+```
+
+**Rate Limit**: Inherits from auth rate limiting
+
+#### Manage Audit Log Retention
+```http
+POST /api/admin/audit-logs/retention
+```
+
+**Authorization**: ADMIN role required
+
+**Request Body**:
+```json
+{
+  "action": "cleanup" | "configure" | "status",
+  "retentionDays": 90,
+  "dryRun": true
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "data": {
+    "action": "cleanup",
+    "recordsAffected": 1250,
+    "retentionDays": 90,
+    "dryRun": true
+  }
+}
+```
+
+### Security Monitoring
+
+#### Get Security Metrics
+```http
+GET /api/admin/security-monitoring
+```
+
+**Authorization**: Platform admin required
+
+**Query Parameters**:
+- `startDate` (string, optional): Start date (ISO 8601)
+- `endDate` (string, optional): End date (ISO 8601)
+- `companyId` (string, optional): Filter by company
+- `severity` (string, optional): Filter by severity
+
+**Response**:
+```json
+{
+  "metrics": {
+    "securityScore": 85,
+    "threatLevel": "LOW",
+    "eventCounts": {...},
+    "anomalies": [...]
+  },
+  "alerts": [...],
+  "config": {...},
+  "timeRange": {...}
+}
+```
+
+#### Update Security Configuration
+```http
+POST /api/admin/security-monitoring
+```
+
+**Authorization**: Platform admin required
+
+**Request Body**:
+```json
+{
+  "thresholds": {
+    "failedLoginsPerMinute": 5,
+    "rateLimitViolationsPerMinute": 10
+  },
+  "alerting": {
+    "enabled": true,
+    "channels": ["EMAIL", "WEBHOOK"]
+  }
+}
+```
+
+### CSP Monitoring
+
+#### CSP Violation Reporting
+```http
+POST /api/csp-report
+```
+
+**Authorization**: None (public endpoint)
+
+**Headers**:
+- `Content-Type`: `application/csp-report` or `application/json`
+
+**Request Body** (automatic from browser):
+```json
+{
+  "csp-report": {
+    "document-uri": "https://example.com/page",
+    "violated-directive": "script-src 'self'",
+    "blocked-uri": "https://malicious.com/script.js",
+    "source-file": "https://example.com/page",
+    "line-number": 42
+  }
+}
+```
+
+**Rate Limit**: 10 reports per minute per IP
+
+**Response**: `204 No Content`
+
+#### Get CSP Metrics
+```http
+GET /api/csp-metrics
+```
+
+**Authorization**: Admin role required
+
+**Query Parameters**:
+- `timeRange` (string, optional): Time range (1h, 6h, 24h, 7d, 30d)
+- `format` (string, optional): Response format (json, csv)
+- `groupBy` (string, optional): Group by field (hour, directive, etc.)
+- `includeDetails` (boolean, optional): Include violation details
+
+**Response**:
+```json
+{
+  "success": true,
+  "data": {
+    "summary": {
+      "totalViolations": 45,
+      "uniqueViolations": 12,
+      "highRiskViolations": 3,
+      "bypassAttempts": 1
+    },
+    "trends": {...},
+    "topViolations": [...],
+    "riskAnalysis": {...},
+    "violations": [...]
+  }
+}
+```
+
+### Batch Monitoring
+
+#### Get Batch Monitoring Data
+```http
+GET /api/admin/batch-monitoring
+```
+
+**Authorization**: ADMIN role required
+
+**Query Parameters**:
+- `timeRange` (string, optional): Time range (1h, 6h, 24h, 7d, 30d)
+- `status` (string, optional): Filter by status (pending, completed, failed)
+- `jobType` (string, optional): Filter by job type
+- `includeDetails` (boolean, optional): Include detailed job information
+- `page` (number, optional): Page number
+- `limit` (number, optional): Records per page
+
+**Response**:
+```json
+{
+  "success": true,
+  "data": {
+    "summary": {
+      "totalJobs": 156,
+      "completedJobs": 142,
+      "failedJobs": 8,
+      "costSavings": {...}
+    },
+    "queues": {...},
+    "performance": {...},
+    "jobs": [...]
+  }
+}
+```
+
+#### Retry Batch Job
+```http
+POST /api/admin/batch-monitoring/{jobId}/retry
+```
+
+**Authorization**: ADMIN role required
+
+**Response**:
+```json
+{
+  "success": true,
+  "data": {
+    "jobId": "batch-job-123",
+    "status": "retrying",
+    "message": "Job queued for retry"
+  }
+}
+```
+
+### CSRF Token
+
+#### Get CSRF Token
+```http
+GET /api/csrf-token
+```
+
+**Authorization**: None
+
+**Response**:
+```json
+{
+  "csrfToken": "abc123..."
+}
+```
+
+**Headers Set**:
+- `Set-Cookie`: HTTP-only CSRF token cookie
+
+### Authentication
+
+#### User Registration
+```http
+POST /api/register
+```
+
+**Authorization**: None
+
+**Headers Required**:
+- `X-CSRF-Token`: CSRF token
+
+**Request Body**:
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePassword123!",
+  "name": "John Doe",
+  "companyName": "Acme Corp"
+}
+```
+
+**Rate Limit**: 3 attempts per hour per IP
+
+**Response**:
+```json
+{
+  "success": true,
+  "message": "User registered successfully",
+  "userId": "user-123"
+}
+```
+
+#### Password Reset Request
+```http
+POST /api/forgot-password
+```
+
+**Authorization**: None
+
+**Headers Required**:
+- `X-CSRF-Token`: CSRF token
+
+**Request Body**:
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+**Rate Limit**: 5 attempts per 15 minutes per IP
+
+**Response**:
+```json
+{
+  "success": true,
+  "message": "Password reset email sent"
+}
+```
+
+#### Password Reset Completion
+```http
+POST /api/reset-password
+```
+
+**Authorization**: None
+
+**Headers Required**:
+- `X-CSRF-Token`: CSRF token
+
+**Request Body**:
+```json
+{
+  "token": "reset-token-123",
+  "password": "NewSecurePassword123!"
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "message": "Password reset successfully"
+}
+```
+
+## Error Responses
+
+### Standard Error Format
+
+```json
+{
+  "success": false,
+  "error": "Error message",
+  "code": "ERROR_CODE",
+  "details": {...}
+}
+```
+
+### Common HTTP Status Codes
+
+| Status | Description | Common Causes |
+|--------|-------------|---------------|
+| 200 | OK | Successful request |
+| 201 | Created | Resource created successfully |
+| 204 | No Content | Successful request with no response body |
+| 400 | Bad Request | Invalid request parameters or body |
+| 401 | Unauthorized | Authentication required or invalid |
+| 403 | Forbidden | Insufficient permissions |
+| 404 | Not Found | Resource not found |
+| 409 | Conflict | Resource already exists or conflict |
+| 422 | Unprocessable Entity | Validation errors |
+| 429 | Too Many Requests | Rate limit exceeded |
+| 500 | Internal Server Error | Server error |
+
+### Error Codes
+
+| Code | Description | Resolution |
+|------|-------------|------------|
+| `UNAUTHORIZED` | No valid session | Login required |
+| `FORBIDDEN` | Insufficient permissions | Check user role |
+| `VALIDATION_ERROR` | Invalid input data | Check request format |
+| `RATE_LIMITED` | Too many requests | Wait and retry |
+| `CSRF_INVALID` | Invalid CSRF token | Get new token |
+| `NOT_FOUND` | Resource not found | Check resource ID |
+| `CONFLICT` | Resource conflict | Check existing data |
+
+## Rate Limiting
+
+### Authentication Endpoints
+- **Login**: 5 attempts per 15 minutes per IP
+- **Registration**: 3 attempts per hour per IP  
+- **Password Reset**: 5 attempts per 15 minutes per IP
+
+### Security Endpoints
+- **CSP Reports**: 10 reports per minute per IP
+- **Admin Endpoints**: 60 requests per minute per user
+- **Security Monitoring**: 30 requests per minute per user
+
+### General API
+- **Dashboard Endpoints**: 120 requests per minute per user
+- **Platform Management**: 60 requests per minute per user
+
+## Security Headers
+
+All API responses include security headers:
+
+```http
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+X-XSS-Protection: 1; mode=block
+Referrer-Policy: strict-origin-when-cross-origin
+Content-Security-Policy: [CSP directives]
+```
+
+## CORS Configuration
+
+### Allowed Origins
+- Development: `http://localhost:3000`
+- Production: `https://your-domain.com`
+
+### Allowed Methods
+- `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `OPTIONS`
+
+### Allowed Headers
+- `Content-Type`, `Authorization`, `X-CSRF-Token`, `X-Requested-With`
+
+## Pagination
+
+### Standard Pagination Format
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "limit": 50,
+    "totalCount": 150,
+    "totalPages": 3,
+    "hasNext": true,
+    "hasPrev": false
+  }
+}
+```
+
+### Pagination Parameters
+- `page`: Page number (1-based, default: 1)
+- `limit`: Records per page (default: 50, max: 100)
+
+## Filtering and Sorting
+
+### Common Filter Parameters
+- `startDate` / `endDate`: Date range filtering (ISO 8601)
+- `status`: Status filtering
+- `userId` / `companyId`: Entity filtering
+- `eventType`: Event type filtering
+- `severity`: Severity level filtering
+
+### Sorting Parameters
+- `sortBy`: Field to sort by
+- `sortOrder`: `asc` or `desc` (default: `desc`)
+
+## Response Caching
+
+### Cache Headers
+```http
+Cache-Control: no-cache, no-store, must-revalidate
+Pragma: no-cache
+Expires: 0
+```
+
+### Cache Strategy
+- **Security data**: Never cached
+- **Static data**: Browser cache for 5 minutes
+- **User data**: No cache for security
+
+## API Versioning
+
+### Current Version
+- Version: `v1` (implied, no version prefix required)
+- Introduced: January 2025
+
+### Future Versioning
+- Breaking changes will introduce new versions
+- Format: `/api/v2/endpoint`
+- Backward compatibility maintained for 12 months
+
+## SDK and Client Libraries
+
+### JavaScript/TypeScript Client
+
+```javascript
+// Initialize client
+const client = new LiveDashClient({
+  baseURL: 'https://your-domain.com',
+  apiKey: 'your-api-key' // For future API key auth
+});
+
+// Get audit logs
+const auditLogs = await client.admin.getAuditLogs({
+  page: 1,
+  limit: 50,
+  eventType: 'login_attempt'
+});
+
+// Get security metrics
+const metrics = await client.security.getMetrics({
+  timeRange: '24h'
+});
+```
+
+### tRPC Client
+
+```javascript
+import { createTRPCNext } from '@trpc/next';
+
+const trpc = createTRPCNext({
+  config() {
+    return {
+      url: '/api/trpc',
+    };
+  },
+});
+
+// Use tRPC procedures
+const { data: user } = trpc.auth.getUser.useQuery();
+const updateProfile = trpc.user.updateProfile.useMutation();
+```
+
+## Testing
+
+### API Testing Tools
+
+```bash
+# Test with curl
+curl -X GET "http://localhost:3000/api/admin/audit-logs" \
+  -H "Cookie: next-auth.session-token=..." \
+  -H "X-CSRF-Token: ..."
+
+# Test with HTTPie
+http GET localhost:3000/api/csp-metrics \
+  timeRange==24h \
+  Cookie:next-auth.session-token=...
+```
+
+### Integration Tests
+
+```javascript
+// Example test
+describe('Admin Audit Logs API', () => {
+  test('should return paginated audit logs', async () => {
+    const response = await request(app)
+      .get('/api/admin/audit-logs?page=1&limit=10')
+      .set('Cookie', 'next-auth.session-token=...')
+      .expect(200);
+      
+    expect(response.body.success).toBe(true);
+    expect(response.body.data.auditLogs).toHaveLength(10);
+    expect(response.body.data.pagination.page).toBe(1);
+  });
+});
+```
+
+## Related Documentation
+
+- [Admin Audit Logs API](./admin-audit-logs-api.md)
+- [CSP Metrics API](./csp-metrics-api.md)
+- [Security Monitoring](./security-monitoring.md)
+- [CSRF Protection](./CSRF_PROTECTION.md)
+- [Batch Monitoring Dashboard](./batch-monitoring-dashboard.md)
+
+This API reference provides comprehensive documentation for all endpoints in the LiveDash-Node application. For specific implementation details, refer to the individual documentation files for each feature area.