@jmruthers/pace-core 0.5.184 → 0.5.186

package/docs/rbac/compliance/compliance-guide.md

@@ -0,0 +1,544 @@
+# RBAC/Auth Compliance Guide
+
+> **📚 RBAC Compliance** | [← Back to RBAC Documentation](../README.md) | [Troubleshooting](./troubleshooting-compliance.md) | [Migrating Custom Auth](./migrating-custom-auth.md)
+
+This guide explains how to achieve RBAC/auth compliance in your pace app to ensure proper security and consistent usage of pace-core.
+
+## Overview
+
+The RBAC/auth compliance system ensures that:
+- All auth/rbac/permission functionality uses pace-core exclusively
+- RBAC system is properly initialized
+- All pages are protected with PagePermissionGuard
+- Supabase configuration is centralized
+- No custom auth/rbac code exists
+
+## Compliance Checks
+
+The compliance system checks for:
+
+### 1. Custom Auth/RBAC Code
+
+**What it checks:**
+- Custom auth hooks (useAuth, useLogin, useLogout, etc.)
+- Custom RBAC components (PermissionGuard, AuthGuard, etc.)
+- Custom permission utilities (checkPermission, hasAccess, etc.)
+
+**How to fix:**
+- Remove custom implementations
+- Import equivalent from `@jmruthers/pace-core` or `@jmruthers/pace-core/rbac`
+- Update all usages
+
+See [Migrating Custom Auth](./migrating-custom-auth.md) for detailed migration steps.
+
+### 2. Duplicate Supabase Configuration
+
+**What it checks:**
+- Multiple `createClient` calls
+- Supabase environment variables in multiple files
+
+**How to fix:**
+- Create a single `supabase.ts` file
+- Export the client instance
+- Import from the shared location everywhere
+
+### 3. Unprotected Pages
+
+**What it checks:**
+- Routes without PagePermissionGuard
+- Pages without permission checks
+
+**How to fix:**
+- Wrap all routes with PagePermissionGuard
+- Set `pageName` and `operation` props
+- Ensure pages exist in `rbac_app_pages` table
+
+### 4. Direct Supabase Auth Usage
+
+**What it checks:**
+- Direct calls to `supabase.auth.signIn`, `supabase.auth.signUp`, etc.
+
+**How to fix:**
+- Use `useUnifiedAuth` hook from pace-core
+- Use `UnifiedAuthProvider` to wrap your app
+- Replace all direct auth calls with pace-core methods
+
+### 5. Provider Setup Issues
+
+**What it checks:**
+- Missing `UnifiedAuthProvider` or `OrganisationProvider`
+- Incorrect provider nesting order
+- Providers placed in wrong locations
+
+**How to fix:**
+- Ensure correct nesting: `QueryClientProvider` → `BrowserRouter` → `UnifiedAuthProvider` → `OrganisationProvider` → `App`
+- Place providers in `main.tsx` or `App.tsx` entry file
+- See [Provider Setup](#provider-setup) section below
+
+### 6. Vite Configuration Issues
+
+**What it checks:**
+- `@jmruthers/pace-core` in `optimizeDeps.include` (should be excluded)
+- Missing `@jmruthers/pace-core` in `optimizeDeps.exclude`
+- Missing `react-router-dom` in `resolve.dedupe`
+
+**How to fix:**
+- Add `@jmruthers/pace-core` to `optimizeDeps.exclude`
+- Remove `@jmruthers/pace-core` from `optimizeDeps.include`
+- Add `react-router-dom` to `resolve.dedupe`
+- See [Vite Configuration](#vite-configuration) section below
+
+### 7. Router Setup Issues
+
+**What it checks:**
+- Missing `BrowserRouter`
+- `BrowserRouter` placed incorrectly (inside `UnifiedAuthProvider` instead of wrapping it)
+- `Routes` used without `BrowserRouter`
+
+**How to fix:**
+- Wrap app with `BrowserRouter` from `react-router-dom`
+- Ensure `BrowserRouter` wraps `UnifiedAuthProvider` (not the other way around)
+- See [Router Setup](#router-setup) section below
+
+## Running Compliance Checks
+
+### Static Analysis
+
+Run the compliance check script:
+
+```bash
+npm run check:pace-core
+```
+
+This will scan your codebase and report:
+- Custom auth/rbac code
+- Duplicate configurations
+- Unprotected pages
+- Direct Supabase auth usage
+- Provider setup issues
+- Vite configuration problems
+- Router setup issues
+
+### ESLint Rules
+
+The compliance system includes ESLint rules that run during development:
+
+- `no-custom-auth-code` - Disallows custom auth/rbac implementations
+- `no-duplicate-supabase-config` - Disallows multiple Supabase configurations
+- `require-page-permission-guard` - Requires PagePermissionGuard on routes
+- `no-direct-supabase-auth` - Disallows direct Supabase auth usage
+
+### Runtime Validation
+
+Check runtime compliance programmatically:
+
+```typescript
+import { checkRuntimeCompliance } from '@jmruthers/pace-core/rbac';
+
+const result = checkRuntimeCompliance();
+if (!result.setup.isCompliant) {
+  console.warn('RBAC setup issues:', result.setup.issues);
+}
+```
+
+## Achieving Compliance
+
+### Step 1: Initialize RBAC
+
+```typescript
+// main.tsx or App.tsx
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY
+);
+
+// ⚠️ REQUIRED: Call setupRBAC before rendering
+setupRBAC(supabase);
+```
+
+### Step 2: Set Up Providers
+
+**⚠️ CRITICAL: Provider nesting order matters!**
+
+The correct nesting order is:
+1. `QueryClientProvider` (outermost)
+2. `BrowserRouter`
+3. `UnifiedAuthProvider`
+4. `OrganisationProvider`
+5. `App` (innermost)
+
+```tsx
+// main.tsx - Correct setup
+import { BrowserRouter } from 'react-router-dom';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
+
+const queryClient = new QueryClient();
+
+createRoot(document.getElementById("root")!).render(
+  <QueryClientProvider client={queryClient}>
+    <BrowserRouter>
+      <UnifiedAuthProvider supabaseClient={supabase} appName={APP_NAME}>
+        <OrganisationProvider>
+          <App />
+        </OrganisationProvider>
+      </UnifiedAuthProvider>
+    </BrowserRouter>
+  </QueryClientProvider>
+);
+```
+
+**Common mistakes to avoid:**
+- ❌ `BrowserRouter` inside `UnifiedAuthProvider` (causes Router context errors)
+- ❌ `UnifiedAuthProvider` wrapping `BrowserRouter` (causes context errors)
+- ❌ Missing `BrowserRouter` (causes `useNavigate` errors)
+
+### Step 3: Protect All Pages
+
+```tsx
+// pages/Dashboard.tsx
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function Dashboard() {
+  return (
+    <PagePermissionGuard pageName="dashboard" operation="read">
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+### Step 4: Use pace-core Auth
+
+```tsx
+// components/Login.tsx
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function Login() {
+  const { signIn } = useUnifiedAuth();
+  
+  const handleLogin = async () => {
+    await signIn({ email, password });
+  };
+  
+  return <button onClick={handleLogin}>Login</button>;
+}
+```
+
+### Step 5: Configure Vite
+
+**⚠️ CRITICAL: Vite configuration prevents React context mismatches!**
+
+Add to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  resolve: {
+    dedupe: ['react', 'react-dom', 'react-router-dom']
+  },
+  optimizeDeps: {
+    include: [
+      'react',
+      'react-dom',
+      'react/jsx-runtime'
+    ],
+    // CRITICAL: Exclude pace-core to prevent React context mismatches
+    exclude: ['@jmruthers/pace-core', 'react-router-dom']
+  }
+});
+```
+
+**Why this matters:**
+- Pre-bundling `@jmruthers/pace-core` creates separate React instances
+- This causes "useUnifiedAuth must be used within a UnifiedAuthProvider" errors
+- Excluding it ensures pace-core uses the same React instance as your app
+
+### Step 6: Centralize Supabase Config
+
+```typescript
+// src/lib/supabase.ts
+import { createClient } from '@supabase/supabase-js';
+
+export const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY
+);
+```
+
+## Database Configuration
+
+Ensure your database is properly configured:
+
+1. **App Registration**: App must exist in `rbac_apps` table
+2. **Pages**: All pages must be registered in `rbac_app_pages` table
+3. **Permissions**: Permissions must be configured in `rbac_page_permissions` table
+4. **User Roles**: Users must have roles in `rbac_organisation_roles` table
+
+See [RBAC Quick Start](../quick-start.md) for database setup instructions.
+
+## Quick Fixes
+
+The compliance system provides quick fix suggestions:
+
+```typescript
+import { getQuickFixes } from '@jmruthers/pace-core/rbac';
+
+const fixes = getQuickFixes('custom-auth-code', { name: 'useAuth', type: 'hook' });
+fixes.forEach(fix => {
+  console.log(fix.suggestion);
+  console.log(fix.codeExample);
+});
+```
+
+## CI/CD Integration
+
+Add compliance checks to your CI/CD pipeline:
+
+```yaml
+# .github/workflows/compliance.yml
+- name: Check pace-core compliance
+  run: npm run check:pace-core
+```
+
+The script exits with code 1 if compliance issues are found, causing the build to fail.
+
+## Troubleshooting Common Issues
+
+### Provider Setup Issues
+
+**Issue:** "useUnifiedAuth must be used within a UnifiedAuthProvider" error
+
+**Possible causes:**
+1. `UnifiedAuthProvider` is missing or not wrapping your app
+2. `BrowserRouter` is inside `UnifiedAuthProvider` (wrong nesting)
+3. Vite is pre-bundling `@jmruthers/pace-core` (React context mismatch)
+
+**Solution:**
+1. **Check provider nesting** in `main.tsx`:
+   ```tsx
+   // ✅ CORRECT
+   <QueryClientProvider>
+     <BrowserRouter>
+       <UnifiedAuthProvider>
+         <OrganisationProvider>
+           <App />
+         </OrganisationProvider>
+       </UnifiedAuthProvider>
+     </BrowserRouter>
+   </QueryClientProvider>
+   
+   // ❌ WRONG - BrowserRouter inside UnifiedAuthProvider
+   <UnifiedAuthProvider>
+     <BrowserRouter>
+       <App />
+     </BrowserRouter>
+   </UnifiedAuthProvider>
+   ```
+
+2. **Check Vite config** - ensure `@jmruthers/pace-core` is in `optimizeDeps.exclude`:
+   ```typescript
+   optimizeDeps: {
+     exclude: ['@jmruthers/pace-core', 'react-router-dom']
+   }
+   ```
+
+3. **Clear Vite cache** and restart dev server:
+   ```bash
+   rm -rf node_modules/.vite
+   npm run dev
+   ```
+
+### Router Context Issues
+
+**Issue:** "useNavigate() may be used only in the context of a <Router> component" error
+
+**Possible causes:**
+1. Missing `BrowserRouter`
+2. `BrowserRouter` placed incorrectly
+3. `react-router-dom` being pre-bundled by Vite
+
+**Solution:**
+1. **Add BrowserRouter** wrapping your app:
+   ```tsx
+   import { BrowserRouter } from 'react-router-dom';
+   
+   <BrowserRouter>
+     <UnifiedAuthProvider>
+       <App />
+     </UnifiedAuthProvider>
+   </BrowserRouter>
+   ```
+
+2. **Update Vite config**:
+   ```typescript
+   resolve: {
+     dedupe: ['react', 'react-dom', 'react-router-dom']
+   },
+   optimizeDeps: {
+     exclude: ['react-router-dom']
+   }
+   ```
+
+3. **Clear Vite cache** and restart
+
+### Vite Configuration Issues
+
+**Issue:** React context mismatch errors, components can't find providers
+
+**Possible causes:**
+1. `@jmruthers/pace-core` is being pre-bundled by Vite
+2. Multiple React instances in the bundle
+
+**Solution:**
+1. **Exclude pace-core from pre-bundling**:
+   ```typescript
+   optimizeDeps: {
+     exclude: ['@jmruthers/pace-core']
+   }
+   ```
+
+2. **Dedupe React dependencies**:
+   ```typescript
+   resolve: {
+     dedupe: ['react', 'react-dom', 'react-router-dom']
+   }
+   ```
+
+3. **Clear Vite cache**:
+   ```bash
+   rm -rf node_modules/.vite
+   ```
+
+### Custom Auth/RBAC Code Detected
+
+**Issue:** Custom `useAuth` hook or `PermissionGuard` component found
+
+**Solution:**
+1. Remove your custom implementation
+2. Import from pace-core:
+   ```typescript
+   import { useUnifiedAuth } from '@jmruthers/pace-core';
+   import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+   ```
+3. Update all usages - see [Migration Examples](#migrating-from-custom-code) below
+
+### Duplicate Supabase Configuration
+
+**Issue:** Multiple `createClient` calls found
+
+**Solution:**
+1. Create a single `supabase.ts` file:
+   ```typescript
+   // src/lib/supabase.ts
+   export const supabase = createClient(url, key);
+   ```
+2. Remove all other `createClient` calls
+3. Import from the shared location everywhere
+
+### Unprotected Pages
+
+**Issue:** Route without PagePermissionGuard
+
+**Solution:**
+1. Wrap all routes with PagePermissionGuard:
+   ```tsx
+   <PagePermissionGuard pageName="dashboard" operation="read">
+     <Dashboard />
+   </PagePermissionGuard>
+   ```
+2. Ensure pages exist in `rbac_app_pages` table
+
+### Direct Supabase Auth Usage
+
+**Issue:** Direct `supabase.auth` calls detected
+
+**Solution:**
+1. Use `useUnifiedAuth` hook instead:
+   ```typescript
+   const { signIn } = useUnifiedAuth();
+   await signIn({ email, password });
+   ```
+2. Ensure `UnifiedAuthProvider` wraps your app
+
+### RBAC Not Initialized
+
+**Issue:** `setupRBAC()` not called
+
+**Solution:**
+```typescript
+// main.tsx - Must be called before rendering
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+setupRBAC(supabase);
+```
+
+## Migrating from Custom Code
+
+### Migrating `useAuth` Hook
+
+**Before:**
+```typescript
+// src/hooks/useAuth.ts
+export function useAuth() {
+  const [user, setUser] = useState(null);
+  // ... custom logic
+}
+```
+
+**After:**
+```typescript
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+const { user } = useUnifiedAuth();
+```
+
+### Migrating `PermissionGuard` Component
+
+**Before:**
+```tsx
+<PermissionGuard permission="read:users">
+  <UsersPage />
+</PermissionGuard>
+```
+
+**After:**
+```tsx
+<PagePermissionGuard pageName="users" operation="read">
+  <UsersPage />
+</PagePermissionGuard>
+```
+
+### Migrating `checkPermission` Utility
+
+**Before:**
+```typescript
+const hasAccess = checkPermission(user, 'read:users');
+```
+
+**After:**
+```typescript
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+const hasAccess = await isPermitted({
+  userId: user.id,
+  scope: { organisationId: org.id },
+  permission: 'read:page.users'
+});
+```
+
+### Step-by-Step Migration Process
+
+1. **Audit:** Run `npm run check:pace-core` to find all custom code
+2. **Setup:** Ensure `setupRBAC()` is called and providers are configured
+3. **Migrate:** Replace custom code with pace-core equivalents one component at a time
+4. **Test:** Verify all auth flows and permission checks work
+5. **Clean:** Remove custom files and update all imports
+
+## Next Steps
+
+- [RBAC Troubleshooting](../troubleshooting.md) - General RBAC issues
+- [RBAC Quick Start](../quick-start.md) - Getting started with RBAC
+- [RBAC API Reference](../api-reference.md) - Complete API documentation
+