@jmruthers/pace-core 0.2.4

package/docs/best-practices/security.md

@@ -0,0 +1,881 @@
+# Security Best Practices
+
+Security is a critical aspect of any application. This guide provides comprehensive security best practices for using `@jmruthers/pace-core` in your applications.
+
+## Overview
+
+The security model in `@jmruthers/pace-core` is built on several layers:
+
+- **Authentication**: Secure user authentication with Supabase
+- **Authorization**: Role-based access control (RBAC)
+- **Data Isolation**: Organisation-level data separation
+- **Input Validation**: Comprehensive input sanitization
+- **CSRF Protection**: Cross-site request forgery prevention
+- **XSS Prevention**: Cross-site scripting protection
+
+## Authentication Security
+
+### 1. Secure Password Requirements
+
+```typescript
+import { validatePassword } from '@jmruthers/pace-core';
+
+const passwordRequirements = {
+  minLength: 8,
+  requireUppercase: true,
+  requireLowercase: true,
+  requireNumbers: true,
+  requireSpecialChars: true,
+};
+
+function validateUserPassword(password: string): boolean {
+  return validatePassword(password, passwordRequirements);
+}
+```
+
+### 2. Multi-Factor Authentication
+
+```typescript
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function MFASetup() {
+  const { setupMFA, verifyMFA } = useUnifiedAuth();
+
+  const handleSetupMFA = async () => {
+    try {
+      const { qrCode, secret } = await setupMFA();
+      // Display QR code to user
+      console.log('MFA Setup:', { qrCode, secret });
+    } catch (error) {
+      console.error('MFA setup failed:', error);
+    }
+  };
+
+  const handleVerifyMFA = async (token: string) => {
+    try {
+      await verifyMFA(token);
+      console.log('MFA verified successfully');
+    } catch (error) {
+      console.error('MFA verification failed:', error);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleSetupMFA}>Setup MFA</button>
+      <input type="text" placeholder="Enter MFA token" />
+      <button onClick={() => handleVerifyMFA(token)}>Verify</button>
+    </div>
+  );
+}
+```
+
+### 3. Session Management
+
+```typescript
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function SessionManager() {
+  const { session, signOut, refreshSession } = useUnifiedAuth();
+
+  // Auto-refresh session before expiry
+  useEffect(() => {
+    if (session && session.expires_at) {
+      const timeUntilExpiry = session.expires_at * 1000 - Date.now();
+      const refreshTime = Math.max(timeUntilExpiry - 5 * 60 * 1000, 0); // 5 minutes before expiry
+
+      const timer = setTimeout(() => {
+        refreshSession();
+      }, refreshTime);
+
+      return () => clearTimeout(timer);
+    }
+  }, [session, refreshSession]);
+
+  return (
+    <div>
+      <p>Session expires: {new Date(session?.expires_at * 1000).toLocaleString()}</p>
+      <button onClick={signOut}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+## Authorization Security
+
+### 1. Server-Side Permission Validation
+
+Always validate permissions on the server side:
+
+```typescript
+// Server-side middleware
+function withPermission(permission: string) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const user = req.user;
+    
+    if (!user) {
+      return res.status(401).json({ error: 'Unauthorized' });
+    }
+
+    const hasPermission = await checkUserPermission(user.id, permission);
+    
+    if (!hasPermission) {
+      return res.status(403).json({ error: 'Insufficient permissions' });
+    }
+
+    next();
+  };
+}
+
+// API route protection
+app.get('/api/users', withPermission('read:users'), (req, res) => {
+  // Handle request
+});
+```
+
+### 2. Organisation Access Validation
+
+```typescript
+// Validate organisation access
+function validateOrganisationAccess(userId: string, organisationId: string): Promise<boolean> {
+  return supabase
+    .from('organisation_members')
+    .select('*')
+    .eq('user_id', userId)
+    .eq('organisation_id', organisationId)
+    .eq('status', 'active')
+    .single()
+    .then(result => !!result.data);
+}
+
+// Use in API routes
+app.get('/api/organisations/:id/data', async (req, res) => {
+  const { id } = req.params;
+  const userId = req.user.id;
+
+  const hasAccess = await validateOrganisationAccess(userId, id);
+  
+  if (!hasAccess) {
+    return res.status(403).json({ error: 'Access denied' });
+  }
+
+  // Proceed with data access
+});
+```
+
+### 3. Row Level Security (RLS)
+
+Enable RLS on all tables and create appropriate policies:
+
+```sql
+-- Enable RLS on events table
+ALTER TABLE events ENABLE ROW LEVEL SECURITY;
+
+-- Policy for reading events
+CREATE POLICY "Users can view events in their organisation" ON events
+  FOR SELECT USING (
+    organisation_id IN (
+      SELECT organisation_id 
+      FROM organisation_members 
+      WHERE user_id = auth.uid() AND status = 'active'
+    )
+  );
+
+-- Policy for creating events
+CREATE POLICY "Users can create events in their organisation" ON events
+  FOR INSERT WITH CHECK (
+    organisation_id IN (
+      SELECT organisation_id 
+      FROM organisation_members 
+      WHERE user_id = auth.uid() AND status = 'active'
+    )
+  );
+
+-- Policy for updating events
+CREATE POLICY "Users can update events they created" ON events
+  FOR UPDATE USING (
+    created_by = auth.uid() OR
+    organisation_id IN (
+      SELECT organisation_id 
+      FROM organisation_members 
+      WHERE user_id = auth.uid() AND role IN ('admin', 'owner')
+    )
+  );
+```
+
+## Input Validation and Sanitization
+
+### 1. Form Validation
+
+```typescript
+import { useZodForm } from '@jmruthers/pace-core';
+import { z } from 'zod';
+
+const userSchema = z.object({
+  name: z.string()
+    .min(1, 'Name is required')
+    .max(100, 'Name must be less than 100 characters')
+    .regex(/^[a-zA-Z\s]+$/, 'Name can only contain letters and spaces'),
+  
+  email: z.string()
+    .email('Invalid email address')
+    .max(255, 'Email must be less than 255 characters'),
+  
+  phone: z.string()
+    .regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number')
+    .optional(),
+  
+  age: z.number()
+    .min(13, 'Must be at least 13 years old')
+    .max(120, 'Invalid age'),
+});
+
+function UserForm() {
+  const { register, handleSubmit, errors } = useZodForm(userSchema);
+
+  const onSubmit = async (data: z.infer<typeof userSchema>) => {
+    // Data is validated and sanitized
+    await createUser(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('name')} />
+      {errors.name && <span>{errors.name.message}</span>}
+      
+      <input type="email" {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
+      
+      <input type="tel" {...register('phone')} />
+      {errors.phone && <span>{errors.phone.message}</span>}
+      
+      <input type="number" {...register('age')} />
+      {errors.age && <span>{errors.age.message}</span>}
+      
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+### 2. HTML Sanitization
+
+```typescript
+import { sanitizeHtml } from '@jmruthers/pace-core';
+
+function RichTextEditor() {
+  const [content, setContent] = useState('');
+
+  const handleSave = () => {
+    // Sanitize HTML before saving
+    const sanitizedContent = sanitizeHtml(content, {
+      allowedTags: ['p', 'br', 'strong', 'em', 'ul', 'ol', 'li'],
+      allowedAttributes: {},
+    });
+
+    saveContent(sanitizedContent);
+  };
+
+  return (
+    <div>
+      <textarea
+        value={content}
+        onChange={(e) => setContent(e.target.value)}
+        placeholder="Enter content..."
+      />
+      <button onClick={handleSave}>Save</button>
+    </div>
+  );
+}
+```
+
+### 3. File Upload Security
+
+```typescript
+import { validateFileUpload } from '@jmruthers/pace-core';
+
+const fileUploadConfig = {
+  maxSize: 5 * 1024 * 1024, // 5MB
+  allowedTypes: ['image/jpeg', 'image/png', 'image/gif'],
+  allowedExtensions: ['.jpg', '.jpeg', '.png', '.gif'],
+};
+
+function FileUpload() {
+  const handleFileUpload = async (file: File) => {
+    try {
+      const validation = await validateFileUpload(file, fileUploadConfig);
+      
+      if (!validation.isValid) {
+        throw new Error(validation.error);
+      }
+
+      // Proceed with upload
+      await uploadFile(file);
+    } catch (error) {
+      console.error('File upload failed:', error);
+    }
+  };
+
+  return (
+    <input
+      type="file"
+      accept="image/*"
+      onChange={(e) => {
+        const file = e.target.files?.[0];
+        if (file) handleFileUpload(file);
+      }}
+    />
+  );
+}
+```
+
+## CSRF Protection
+
+### 1. CSRF Token Generation
+
+```typescript
+import { generateCSRFToken, validateCSRFToken } from '@jmruthers/pace-core';
+
+// Generate CSRF token
+const csrfToken = generateCSRFToken();
+
+// Include in forms
+function SecureForm() {
+  return (
+    <form>
+      <input type="hidden" name="_csrf" value={csrfToken} />
+      {/* Form fields */}
+    </form>
+  );
+}
+```
+
+### 2. CSRF Token Validation
+
+```typescript
+// Server-side validation
+function validateCSRFRequest(req: Request, res: Response, next: NextFunction) {
+  const token = req.headers['x-csrf-token'] || req.body._csrf;
+  
+  if (!validateCSRFToken(token)) {
+    return res.status(403).json({ error: 'Invalid CSRF token' });
+  }
+  
+  next();
+}
+
+// Apply to sensitive routes
+app.post('/api/users', validateCSRFRequest, (req, res) => {
+  // Handle request
+});
+```
+
+## XSS Prevention
+
+### 1. Content Security Policy (CSP)
+
+```typescript
+// Set CSP headers
+const cspHeaders = {
+  'Content-Security-Policy': [
+    "default-src 'self'",
+    "script-src 'self' 'unsafe-inline'",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data: https:",
+    "font-src 'self'",
+    "connect-src 'self'",
+    "frame-ancestors 'none'",
+  ].join('; '),
+};
+
+// Apply to all responses
+app.use((req, res, next) => {
+  Object.entries(cspHeaders).forEach(([key, value]) => {
+    res.setHeader(key, value);
+  });
+  next();
+});
+```
+
+### 2. Safe HTML Rendering
+
+```typescript
+import { sanitizeHtml } from '@jmruthers/pace-core';
+
+function SafeContent({ content }: { content: string }) {
+  const sanitizedContent = sanitizeHtml(content, {
+    allowedTags: ['p', 'br', 'strong', 'em'],
+    allowedAttributes: {},
+  });
+
+  return (
+    <div 
+      dangerouslySetInnerHTML={{ __html: sanitizedContent }}
+      className="safe-content"
+    />
+  );
+}
+```
+
+## API Security
+
+### 1. Rate Limiting
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5, // limit each IP to 5 requests per windowMs
+  message: 'Too many authentication attempts, please try again later',
+});
+
+const apiLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // limit each IP to 100 requests per windowMs
+});
+
+// Apply to routes
+app.use('/api/auth', authLimiter);
+app.use('/api', apiLimiter);
+```
+
+### 2. Request Validation
+
+```typescript
+import { validateRequest } from '@jmruthers/pace-core';
+
+const userValidationSchema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  age: z.number().min(13).max(120),
+});
+
+function createUser(req: Request, res: Response) {
+  const validation = validateRequest(req.body, userValidationSchema);
+  
+  if (!validation.isValid) {
+    return res.status(400).json({ 
+      error: 'Invalid request data',
+      details: validation.errors 
+    });
+  }
+
+  // Proceed with user creation
+}
+```
+
+### 3. Secure Headers
+
+```typescript
+import helmet from 'helmet';
+
+// Apply security headers
+app.use(helmet({
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'", "'unsafe-inline'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", "data:", "https:"],
+    },
+  },
+  hsts: {
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: true,
+  },
+}));
+```
+
+## Data Security
+
+### 1. Sensitive Data Encryption
+
+```typescript
+import { encryptData, decryptData } from '@jmruthers/pace-core';
+
+// Encrypt sensitive data before storing
+const sensitiveData = {
+  creditCard: '1234-5678-9012-3456',
+  ssn: '123-45-6789',
+};
+
+const encryptedData = encryptData(JSON.stringify(sensitiveData));
+
+// Store encrypted data
+await supabase
+  .from('user_sensitive_data')
+  .insert({
+    user_id: userId,
+    encrypted_data: encryptedData,
+  });
+
+// Decrypt when needed
+const decryptedData = JSON.parse(decryptData(encryptedData));
+```
+
+### 2. Secure Data Transmission
+
+```typescript
+// Always use HTTPS in production
+if (process.env.NODE_ENV === 'production') {
+  app.use((req, res, next) => {
+    if (!req.secure) {
+      return res.redirect(`https://${req.headers.host}${req.url}`);
+    }
+    next();
+  });
+}
+```
+
+### 3. Audit Logging
+
+```typescript
+import { createAuditLog } from '@jmruthers/pace-core';
+
+// Log security events
+async function logSecurityEvent(event: string, userId: string, details: any) {
+  await createAuditLog({
+    event,
+    user_id: userId,
+    details,
+    timestamp: new Date().toISOString(),
+    ip_address: req.ip,
+    user_agent: req.headers['user-agent'],
+  });
+}
+
+// Use in sensitive operations
+app.post('/api/users/:id/delete', async (req, res) => {
+  const { id } = req.params;
+  const userId = req.user.id;
+
+  await deleteUser(id);
+  
+  await logSecurityEvent('user_deleted', userId, {
+    deleted_user_id: id,
+    reason: req.body.reason,
+  });
+
+  res.json({ success: true });
+});
+```
+
+## Environment Security
+
+### 1. Environment Variables
+
+```typescript
+// Validate required environment variables
+const requiredEnvVars = [
+  'SUPABASE_URL',
+  'SUPABASE_ANON_KEY',
+  'SUPABASE_SERVICE_ROLE_KEY',
+  'JWT_SECRET',
+  'ENCRYPTION_KEY',
+];
+
+requiredEnvVars.forEach(varName => {
+  if (!process.env[varName]) {
+    throw new Error(`Missing required environment variable: ${varName}`);
+  }
+});
+```
+
+### 2. Secure Configuration
+
+```typescript
+// Production security settings
+const securityConfig = {
+  production: {
+    cors: {
+      origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
+      credentials: true,
+    },
+    session: {
+      secure: true,
+      httpOnly: true,
+      sameSite: 'strict',
+    },
+    rateLimit: {
+      windowMs: 15 * 60 * 1000,
+      max: 100,
+    },
+  },
+  development: {
+    cors: {
+      origin: true,
+      credentials: true,
+    },
+    session: {
+      secure: false,
+      httpOnly: true,
+      sameSite: 'lax',
+    },
+    rateLimit: {
+      windowMs: 15 * 60 * 1000,
+      max: 1000,
+    },
+  },
+};
+```
+
+## Security Testing
+
+### 1. Security Headers Testing
+
+```typescript
+import { testSecurityHeaders } from '@jmruthers/pace-core';
+
+test('security headers are set correctly', async () => {
+  const response = await request(app)
+    .get('/api/health')
+    .expect(200);
+
+  expect(response.headers).toHaveProperty('x-content-type-options');
+  expect(response.headers['x-content-type-options']).toBe('nosniff');
+  
+  expect(response.headers).toHaveProperty('x-frame-options');
+  expect(response.headers['x-frame-options']).toBe('DENY');
+  
+  expect(response.headers).toHaveProperty('x-xss-protection');
+  expect(response.headers['x-xss-protection']).toBe('1; mode=block');
+});
+```
+
+### 2. Authentication Testing
+
+```typescript
+test('unauthenticated requests are rejected', async () => {
+  await request(app)
+    .get('/api/users')
+    .expect(401);
+});
+
+test('unauthorized requests are rejected', async () => {
+  const user = await createTestUser({ role: 'user' });
+  const token = await generateAuthToken(user);
+
+  await request(app)
+    .get('/api/admin/users')
+    .set('Authorization', `Bearer ${token}`)
+    .expect(403);
+});
+```
+
+### 3. Input Validation Testing
+
+```typescript
+test('malicious input is sanitized', async () => {
+  const maliciousInput = '<script>alert("xss")</script>';
+
+  const response = await request(app)
+    .post('/api/users')
+    .send({
+      name: maliciousInput,
+      email: 'test@example.com',
+    })
+    .expect(400);
+
+  expect(response.body.error).toContain('Invalid input');
+});
+```
+
+## Security Monitoring
+
+### 1. Security Event Monitoring
+
+```typescript
+import { monitorSecurityEvents } from '@jmruthers/pace-core';
+
+// Monitor security events
+monitorSecurityEvents({
+  onFailedLogin: (event) => {
+    console.warn('Failed login attempt:', event);
+    // Send alert to security team
+  },
+  onSuspiciousActivity: (event) => {
+    console.error('Suspicious activity detected:', event);
+    // Trigger security response
+  },
+  onPermissionViolation: (event) => {
+    console.error('Permission violation:', event);
+    // Log for investigation
+  },
+});
+```
+
+### 2. Security Metrics
+
+```typescript
+import { trackSecurityMetrics } from '@jmruthers/pace-core';
+
+// Track security metrics
+trackSecurityMetrics({
+  failedLogins: 0,
+  successfulLogins: 0,
+  permissionDenials: 0,
+  suspiciousActivities: 0,
+});
+
+// Export metrics for monitoring
+app.get('/api/security/metrics', (req, res) => {
+  res.json(getSecurityMetrics());
+});
+```
+
+## Incident Response
+
+### 1. Security Incident Handling
+
+```typescript
+import { handleSecurityIncident } from '@jmruthers/pace-core';
+
+// Handle security incidents
+async function handleSecurityIncident(incident: SecurityIncident) {
+  // Log the incident
+  await logSecurityEvent('security_incident', incident.userId, incident);
+  
+  // Take immediate action
+  if (incident.type === 'brute_force') {
+    await lockUserAccount(incident.userId);
+    await notifySecurityTeam(incident);
+  }
+  
+  if (incident.type === 'data_breach') {
+    await revokeAllSessions(incident.userId);
+    await forcePasswordReset(incident.userId);
+    await notifyUser(incident.userId, 'security_alert');
+  }
+}
+```
+
+### 2. Security Alerts
+
+```typescript
+import { createSecurityAlert } from '@jmruthers/pace-core';
+
+// Create security alerts
+async function createSecurityAlert(alert: SecurityAlert) {
+  await createAuditLog({
+    event: 'security_alert',
+    user_id: alert.userId,
+    details: alert,
+    severity: alert.severity,
+    timestamp: new Date().toISOString(),
+  });
+  
+  // Send notification based on severity
+  if (alert.severity === 'high') {
+    await sendImmediateAlert(alert);
+  }
+}
+```
+
+## Compliance and Standards
+
+### 1. GDPR Compliance
+
+```typescript
+import { gdprCompliance } from '@jmruthers/pace-core';
+
+// GDPR compliance utilities
+const gdprUtils = {
+  // Right to be forgotten
+  deleteUserData: async (userId: string) => {
+    await supabase.from('users').delete().eq('id', userId);
+    await supabase.from('user_data').delete().eq('user_id', userId);
+    await logSecurityEvent('gdpr_deletion', userId, { reason: 'right_to_be_forgotten' });
+  },
+  
+  // Data portability
+  exportUserData: async (userId: string) => {
+    const userData = await supabase
+      .from('users')
+      .select('*')
+      .eq('id', userId)
+      .single();
+    
+    return JSON.stringify(userData, null, 2);
+  },
+  
+  // Consent management
+  updateConsent: async (userId: string, consent: ConsentSettings) => {
+    await supabase
+      .from('user_consent')
+      .upsert({
+        user_id: userId,
+        marketing_emails: consent.marketingEmails,
+        analytics_tracking: consent.analyticsTracking,
+        updated_at: new Date().toISOString(),
+      });
+  },
+};
+```
+
+### 2. SOC 2 Compliance
+
+```typescript
+import { soc2Compliance } from '@jmruthers/pace-core';
+
+// SOC 2 compliance monitoring
+const soc2Utils = {
+  // Access control monitoring
+  monitorAccess: async (userId: string, resource: string, action: string) => {
+    await createAuditLog({
+      event: 'access_attempt',
+      user_id: userId,
+      details: { resource, action, timestamp: new Date().toISOString() },
+    });
+  },
+  
+  // Data integrity checks
+  verifyDataIntegrity: async () => {
+    // Implement data integrity verification
+    const checksum = await calculateDataChecksum();
+    return checksum;
+  },
+  
+  // Backup verification
+  verifyBackups: async () => {
+    // Implement backup verification
+    const backupStatus = await checkBackupStatus();
+    return backupStatus;
+  },
+};
+```
+
+## Security Checklist
+
+### Pre-Deployment Checklist
+
+- [ ] All environment variables are properly set
+- [ ] HTTPS is enabled in production
+- [ ] Security headers are configured
+- [ ] Rate limiting is implemented
+- [ ] Input validation is in place
+- [ ] CSRF protection is enabled
+- [ ] XSS protection is implemented
+- [ ] SQL injection protection is active
+- [ ] File upload validation is configured
+- [ ] Audit logging is enabled
+- [ ] Error messages don't leak sensitive information
+- [ ] Session management is secure
+- [ ] Password requirements are enforced
+- [ ] Multi-factor authentication is available
+- [ ] Row-level security is enabled
+- [ ] API endpoints are properly protected
+
+### Ongoing Security Maintenance
+
+- [ ] Regular security updates
+- [ ] Dependency vulnerability scanning
+- [ ] Security audit logging review
+- [ ] Penetration testing
+- [ ] Security incident response plan
+- [ ] User access review
+- [ ] Data backup verification
+- [ ] Compliance monitoring
+
+For more information about implementing security in your application, see the [Authentication Guide](../core-concepts/authentication.md) and [RBAC System Guide](../core-concepts/rbac-system.md).