@jmruthers/pace-core 0.2.4

package/docs/security/README.md

@@ -0,0 +1,680 @@
+# Security Guide
+
+This guide covers security best practices, implementation patterns, and security considerations when using PACE Core.
+
+## Overview
+
+PACE Core is designed with security as a first-class concern, providing:
+
+- **Built-in authentication** with Supabase integration
+- **Comprehensive RBAC system** with fine-grained permissions
+- **Secure data access** with row-level security
+- **Audit logging** for compliance and monitoring
+- **Input validation** and sanitization
+- **XSS protection** and secure coding practices
+- **Auto-logout on inactivity** for enhanced security
+
+## Authentication Security
+
+### 1. User Authentication
+
+PACE Core uses Supabase for authentication, which provides:
+
+- **Secure password hashing** using industry-standard algorithms
+- **JWT token management** with automatic refresh
+- **Session management** with secure session handling
+- **Multi-factor authentication** support
+- **Social authentication** providers (Google, GitHub, etc.)
+
+```tsx
+import { UnifiedAuthProvider, useUnifiedAuth } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider
+      supabaseClient={supabaseClient}
+      onAuthStateChange={(user) => {
+        // Handle authentication state changes
+        console.log('User authenticated:', user);
+      }}
+    >
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+### 2. Session Management
+
+Sessions are automatically managed by PACE Core:
+
+- **Automatic token refresh** before expiration
+- **Secure session storage** using HTTP-only cookies
+- **Session validation** on every request
+- **Automatic logout** on token expiration
+- **Inactivity auto-logout** after 30 minutes of inactivity (configurable)
+
+```tsx
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function ProtectedComponent() {
+  const { user, session, isLoading } = useUnifiedAuth();
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (!user || !session) {
+    return <div>Please log in</div>;
+  }
+
+  return <div>Welcome, {user.email}!</div>;
+}
+```
+
+### 3. Inactivity Auto-Logout
+
+PACE Core includes built-in inactivity tracking for enhanced security:
+
+- **Automatic logout** after 30 minutes of inactivity (configurable)
+- **Warning modal** appears 60 seconds before logout
+- **Cross-tab synchronization** - activity in any tab resets the timer
+- **Persistence** - survives page reloads and browser restarts
+- **Production-safe** - cannot be disabled in production builds
+
+```tsx
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider
+      supabaseClient={supabaseClient}
+      appName="my-app"
+      idleTimeoutMs={30 * 60 * 1000} // 30 minutes
+      warnBeforeMs={60 * 1000}       // 60 seconds warning
+      onIdleLogout={() => {
+        // Handle redirect to login page
+        window.location.href = '/login';
+      }}
+    >
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+#### Monitored Events
+
+The inactivity tracker monitors:
+- Mouse events (click, move, scroll, wheel)
+- Touch events (start, move, end)
+- Keyboard events (keydown, keyup, keypress)
+- Focus events (focus, blur)
+- Page visibility changes
+
+#### Security Benefits
+
+- **Prevents unauthorized access** if user leaves device unattended
+- **Reduces session hijacking risk** by limiting session duration
+- **Compliance support** for security requirements
+- **Cross-tab protection** ensures consistent security across all tabs
+
+### 4. Password Security
+
+Password security is handled by Supabase:
+
+- **Bcrypt hashing** with salt rounds
+- **Password strength requirements** (configurable)
+- **Password reset** with secure tokens
+- **Account lockout** after failed attempts
+
+```tsx
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function PasswordReset() {
+  const { resetPassword } = useUnifiedAuth();
+
+  const handleResetPassword = async (email: string) => {
+    try {
+      await resetPassword(email);
+      console.log('Password reset email sent');
+    } catch (error) {
+      console.error('Password reset failed:', error);
+    }
+  };
+
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault();
+      const email = e.target.email.value;
+      handleResetPassword(email);
+    }}>
+      <input name="email" type="email" placeholder="Enter your email" />
+      <button type="submit">Reset Password</button>
+    </form>
+  );
+}
+```
+
+## RBAC Security
+
+### 1. Permission System
+
+PACE Core provides a comprehensive permission system:
+
+- **Fine-grained permissions** with operation and resource specificity
+- **Hierarchical roles** with inheritance
+- **Context-aware permissions** for organisations and events
+- **Permission caching** for performance
+
+```tsx
+import { useCan, PermissionEnforcer } from '@jmruthers/pace-core';
+
+function SecureComponent() {
+  const { hasPermission } = useCan();
+
+  // Check permission programmatically
+  const canEditUsers = hasPermission('update', 'users');
+
+  return (
+    <div>
+      {/* Use PermissionEnforcer for declarative permission checking */}
+      <PermissionEnforcer
+        operation="read"
+        resource="users"
+        fallback={<div>You don't have permission to view users</div>}
+      >
+        <UserList />
+      </PermissionEnforcer>
+
+      {/* Conditional rendering based on permissions */}
+      {canEditUsers && (
+        <button>Edit Users</button>
+      )}
+    </div>
+  );
+}
+```
+
+### 2. Role Management
+
+Roles are managed at multiple levels:
+
+- **Global roles** for system-wide permissions
+- **Organisation roles** for organisation-specific permissions
+- **Event roles** for event-specific permissions
+
+```tsx
+import { useRBAC } from '@jmruthers/pace-core';
+
+function RoleBasedComponent() {
+  const { 
+    globalRole, 
+    organisationRole, 
+    eventAppRole,
+    isSuperAdmin 
+  } = useRBAC();
+
+  return (
+    <div>
+      {isSuperAdmin && (
+        <div>Super Admin Panel</div>
+      )}
+      
+      {globalRole === 'admin' && (
+        <div>Global Admin Panel</div>
+      )}
+      
+      {organisationRole === 'admin' && (
+        <div>Organisation Admin Panel</div>
+      )}
+      
+      {eventAppRole === 'admin' && (
+        <div>Event Admin Panel</div>
+      )}
+    </div>
+  );
+}
+```
+
+### 3. Access Level Security
+
+Access levels provide additional security granularity:
+
+- **Read access** for viewing data
+- **Write access** for modifying data
+- **Admin access** for administrative functions
+- **Owner access** for full control
+
+```tsx
+import { useAccessLevel, AccessLevelGuard } from '@jmruthers/pace-core';
+
+function AccessLevelComponent() {
+  const { accessLevel, hasAccessLevel } = useAccessLevel();
+
+  return (
+    <div>
+      {/* Check access level programmatically */}
+      {hasAccessLevel('admin') && (
+        <div>Admin functions</div>
+      )}
+
+      {/* Use AccessLevelGuard for declarative checking */}
+      <AccessLevelGuard
+        requiredLevel="write"
+        fallback={<div>You need write access</div>}
+      >
+        <EditForm />
+      </AccessLevelGuard>
+    </div>
+  );
+}
+```
+
+## Data Security
+
+### 1. Row Level Security (RLS)
+
+PACE Core integrates with Supabase's Row Level Security:
+
+- **Database-level security** policies
+- **Automatic data filtering** based on user context
+- **Organisation isolation** for multi-tenant applications
+- **Event isolation** for event-based applications
+
+```sql
+-- Example RLS policy for organisations
+CREATE POLICY "Users can only see their organisation's data" ON organisations
+  FOR ALL USING (
+    id IN (
+      SELECT organisation_id 
+      FROM rbac_organisation_roles 
+      WHERE user_id = auth.uid()
+    )
+  );
+```
+
+### 2. API Security
+
+API endpoints are secured with:
+
+- **Authentication middleware** for all protected routes
+- **Permission checking** before data access
+- **Input validation** and sanitization
+- **Rate limiting** to prevent abuse
+
+```tsx
+import { createSecureClient } from '@jmruthers/pace-core';
+
+// Create a secure client with automatic permission checking
+const secureClient = createSecureClient(supabaseClient);
+
+// All queries through this client are automatically secured
+const { data, error } = await secureClient
+  .from('users')
+  .select('*')
+  .eq('organisation_id', currentOrganisationId);
+```
+
+### 3. Input Validation
+
+All inputs are validated using Zod schemas:
+
+- **Type safety** with TypeScript integration
+- **Runtime validation** for all user inputs
+- **Sanitization** of potentially dangerous content
+- **Error handling** for invalid inputs
+
+```tsx
+import { z } from 'zod';
+import { Form, FormField } from '@jmruthers/pace-core';
+
+const userSchema = z.object({
+  name: z.string().min(2, "Name must be at least 2 characters"),
+  email: z.string().email("Invalid email address"),
+  age: z.number().min(18, "Must be at least 18 years old")
+});
+
+function SecureForm() {
+  return (
+    <Form
+      schema={userSchema}
+      onSubmit={(data) => {
+        // Data is automatically validated and sanitized
+        console.log('Valid data:', data);
+      }}
+    >
+      <FormField name="name" label="Name" />
+      <FormField name="email" label="Email" type="email" />
+      <FormField name="age" label="Age" type="number" />
+    </Form>
+  );
+}
+```
+
+## Audit and Compliance
+
+### 1. Audit Logging
+
+PACE Core provides comprehensive audit logging:
+
+- **Permission checks** are logged with context
+- **Data access** is tracked with user information
+- **Administrative actions** are recorded
+- **Security events** are monitored
+
+```tsx
+import { useCan } from '@jmruthers/pace-core';
+
+function AuditedComponent() {
+  const { hasPermission } = useCan();
+
+  const handleSecureAction = async () => {
+    // Permission check is automatically logged
+    if (hasPermission('delete', 'users')) {
+      // Action is logged with user context
+      await deleteUser(userId);
+    }
+  };
+
+  return <button onClick={handleSecureAction}>Delete User</button>;
+}
+```
+
+### 2. Compliance Features
+
+Built-in compliance features include:
+
+- **GDPR compliance** with data privacy controls
+- **SOX compliance** with audit trails
+- **HIPAA compliance** with data protection
+- **PCI compliance** with secure data handling
+
+```tsx
+import { useOrganisationSecurity } from '@jmruthers/pace-core';
+
+function ComplianceComponent() {
+  const { logAccess, logDataModification } = useOrganisationSecurity();
+
+  const handleDataAccess = async (dataId: string) => {
+    // Log data access for compliance
+    await logAccess('read', 'sensitive_data', dataId);
+    
+    // Perform data access
+    const data = await fetchData(dataId);
+    return data;
+  };
+
+  const handleDataModification = async (dataId: string, changes: any) => {
+    // Log data modification for compliance
+    await logDataModification('update', 'sensitive_data', dataId, changes);
+    
+    // Perform data modification
+    await updateData(dataId, changes);
+  };
+
+  return (
+    <div>
+      {/* Component implementation */}
+    </div>
+  );
+}
+```
+
+## XSS Protection
+
+### 1. Input Sanitization
+
+All user inputs are sanitized to prevent XSS:
+
+- **HTML sanitization** removes dangerous tags
+- **Script tag removal** prevents script injection
+- **Attribute sanitization** removes dangerous attributes
+- **URL sanitization** prevents malicious links
+
+```tsx
+import { Form, FormField } from '@jmruthers/pace-core';
+
+function SafeForm() {
+  return (
+    <Form
+      schema={z.object({
+        content: z.string().min(1, "Content is required")
+      })}
+      onSubmit={(data) => {
+        // Content is automatically sanitized
+        console.log('Safe content:', data.content);
+      }}
+    >
+      <FormField 
+        name="content" 
+        label="Content" 
+        type="textarea"
+        // Input is automatically sanitized
+      />
+    </Form>
+  );
+}
+```
+
+### 2. Output Encoding
+
+All outputs are properly encoded:
+
+- **HTML encoding** for text content
+- **Attribute encoding** for HTML attributes
+- **URL encoding** for URLs
+- **JSON encoding** for JSON data
+
+```tsx
+import { Card, CardContent } from '@jmruthers/pace-core';
+
+function SafeDisplay({ userContent }: { userContent: string }) {
+  return (
+    <Card>
+      <CardContent>
+        {/* Content is automatically encoded */}
+        <p>{userContent}</p>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Security Best Practices
+
+### 1. Authentication
+
+- **Always use HTTPS** in production
+- **Implement proper session management**
+- **Use strong password policies**
+- **Enable multi-factor authentication**
+- **Regular security audits**
+
+### 2. Authorization
+
+- **Principle of least privilege** - grant minimum required permissions
+- **Regular permission reviews** - audit permissions regularly
+- **Role-based access control** - use roles instead of individual permissions
+- **Context-aware permissions** - consider organisation and event context
+
+### 3. Data Protection
+
+- **Encrypt sensitive data** at rest and in transit
+- **Use secure database connections**
+- **Implement proper backup procedures**
+- **Regular security updates**
+
+### 4. Input Validation
+
+- **Validate all inputs** on both client and server
+- **Use whitelist validation** instead of blacklist
+- **Sanitize user inputs** before processing
+- **Implement proper error handling**
+
+### 5. Monitoring
+
+- **Monitor authentication attempts** for suspicious activity
+- **Log all security events** for analysis
+- **Implement alerting** for security incidents
+- **Regular security reviews**
+
+## Security Configuration
+
+### 1. Environment Variables
+
+Secure configuration using environment variables:
+
+```bash
+# Authentication
+VITE_SUPABASE_URL=your_supabase_url
+VITE_SUPABASE_ANON_KEY=your_anon_key
+VITE_SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
+
+# Security
+VITE_SECURITY_LEVEL=high
+VITE_AUDIT_LOGGING=true
+VITE_PERMISSION_CACHING=true
+```
+
+### 2. Security Policies
+
+Configure security policies for your application:
+
+```tsx
+import { setupRBAC } from '@jmruthers/pace-core';
+
+setupRBAC(supabaseClient, {
+  security: {
+    level: 'high',
+    auditLogging: true,
+    permissionCaching: true,
+    strictMode: true
+  },
+  audit: {
+    enabled: true,
+    logLevel: 'info',
+    includeMetadata: true
+  }
+});
+```
+
+### 3. Database Security
+
+Configure database security policies:
+
+```sql
+-- Enable RLS on all tables
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+ALTER TABLE organisations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE events ENABLE ROW LEVEL SECURITY;
+
+-- Create security policies
+CREATE POLICY "Users can only see their own data" ON users
+  FOR ALL USING (id = auth.uid());
+
+CREATE POLICY "Users can only see their organisation's data" ON organisations
+  FOR ALL USING (
+    id IN (
+      SELECT organisation_id 
+      FROM rbac_organisation_roles 
+      WHERE user_id = auth.uid()
+    )
+  );
+```
+
+## Security Testing
+
+### 1. Unit Testing
+
+Test security features in isolation:
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { PermissionEnforcer } from '@jmruthers/pace-core';
+
+test('hides content when user lacks permission', () => {
+  // Mock user without permission
+  jest.mock('@jmruthers/pace-core', () => ({
+    useCan: () => ({ hasPermission: () => false })
+  }));
+
+  render(
+    <PermissionEnforcer
+      operation="read"
+      resource="users"
+      fallback={<div>Access denied</div>}
+    >
+      <div>User data</div>
+    </PermissionEnforcer>
+  );
+
+  expect(screen.getByText('Access denied')).toBeInTheDocument();
+  expect(screen.queryByText('User data')).not.toBeInTheDocument();
+});
+```
+
+### 2. Integration Testing
+
+Test security features in context:
+
+```tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import { App } from './App';
+
+test('prevents unauthorized access to protected routes', async () => {
+  // Mock unauthenticated user
+  jest.mock('@jmruthers/pace-core', () => ({
+    useUnifiedAuth: () => ({ user: null, isLoading: false })
+  }));
+
+  render(<App />);
+
+  // Try to access protected route
+  fireEvent.click(screen.getByText('Protected Page'));
+
+  // Should redirect to login
+  expect(screen.getByText('Please log in')).toBeInTheDocument();
+});
+```
+
+### 3. Security Scanning
+
+Use automated security scanning tools:
+
+- **Dependency scanning** for vulnerable packages
+- **Code scanning** for security vulnerabilities
+- **Container scanning** for image vulnerabilities
+- **Infrastructure scanning** for configuration issues
+
+## Incident Response
+
+### 1. Security Incident Plan
+
+Have a plan for security incidents:
+
+- **Detection** - Monitor for security events
+- **Response** - Immediate response procedures
+- **Containment** - Isolate affected systems
+- **Recovery** - Restore normal operations
+- **Lessons learned** - Improve security measures
+
+### 2. Monitoring and Alerting
+
+Implement comprehensive monitoring:
+
+- **Authentication monitoring** - Failed login attempts
+- **Permission monitoring** - Unauthorized access attempts
+- **Data access monitoring** - Unusual data access patterns
+- **System monitoring** - Resource usage and performance
+
+### 3. Regular Security Reviews
+
+Conduct regular security reviews:
+
+- **Code reviews** - Review code for security issues
+- **Permission reviews** - Audit user permissions
+- **Configuration reviews** - Review security configurations
+- **Dependency reviews** - Review third-party dependencies
+
+This security guide provides a comprehensive overview of security considerations when using PACE Core. Always follow security best practices and stay updated with the latest security recommendations.