@jmruthers/pace-core 0.6.5 → 0.6.7

package/docs/best-practices/security.md

@@ -1,940 +0,0 @@
----
-lastUpdated: 2025-11-18T17:00:00+11:00
-version: 0.5.181
-reviewedBy: documentation-standards-audit
----
-
-# 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 { passwordSchema, securePasswordSchema, calculatePasswordStrength } from '@jmruthers/pace-core/utils/validation';
-import { isStrongPassword } from '@jmruthers/pace-core/utils/validation';
-
-// Using Zod schema (recommended)
-function validateUserPassword(password: string) {
-  const result = securePasswordSchema.safeParse(password);
-  if (!result.success) {
-    return { valid: false, errors: result.error.errors };
-  }
-  return { valid: true };
-}
-
-// Using simple validation function
-function checkPasswordStrength(password: string) {
-  const strength = calculatePasswordStrength(password);
-  return {
-    isValid: strength.level !== 'very-weak' && strength.level !== 'weak',
-    strength: strength.level,
-    score: strength.score,
-    feedback: strength.feedback
-  };
-}
-
-// Basic validation
-const isValid = isStrongPassword(password); // Returns boolean
-```
-
-### 2. Password Strength Indicator
-
-```typescript
-import { calculatePasswordStrength } from '@jmruthers/pace-core/utils/validation';
-
-function PasswordInput() {
-  const [password, setPassword] = useState('');
-  const strength = calculatePasswordStrength(password);
-
-  return (
-    <div>
-      <input 
-        type="password" 
-        value={password}
-        onChange={(e) => setPassword(e.target.value)}
-      />
-      <div className={`strength-${strength.level}`}>
-        Strength: {strength.level} ({strength.score}/100)
-      </div>
-      {strength.feedback.length > 0 && (
-        <ul>
-          {strength.feedback.map((msg, i) => (
-            <li key={i}>{msg}</li>
-          ))}
-        </ul>
-      )}
-    </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).
-
-## ♿ Accessibility
-
-Security practices should maintain accessibility:
-
-- **Error messages are accessible** - Security errors should be clearly communicated
-- **Authentication flows are keyboard accessible** - All security forms should support keyboard navigation
-- **Screen reader support** - Security messages should be properly announced
-- **Focus management** - Ensure focus is properly managed during security operations
-- **Timeouts are announced** - Session timeouts should be accessible to screen readers
-
-### Accessibility Best Practices
-
-1. **Test authentication with screen readers** - Verify login flows work with assistive technologies
-2. **Ensure keyboard access** - All security forms should be keyboard accessible
-3. **Provide clear error messages** - Security errors should be descriptive without exposing vulnerabilities
-4. **Announce security state changes** - Use ARIA live regions for security status updates
-5. **Test with assistive technologies** - Verify all security features work with screen readers
-
-## ⚠️ Edge Cases
-
-### Security vs Usability Conflicts
-
-When security measures impact usability:
-- Find balance between security and user experience
-- Provide clear guidance for security requirements
-- Implement security transparently
-- Test with real users to ensure usability
-- Document security decisions
-
-### Rate Limiting Edge Cases
-
-When rate limiting causes issues:
-- Provide clear error messages for rate limit violations
-- Implement progressive backoff for retries
-- Consider user experience when setting limits
-- Monitor rate limit effectiveness
-- Adjust limits based on legitimate use patterns
-
-### Session Management Edge Cases
-
-When session management fails:
-- Handle session expiration gracefully
-- Provide clear messages for session issues
-- Ensure proper cleanup on session end
-- Test with multiple concurrent sessions
-- Verify session security across devices