@jmruthers/pace-core 0.5.183 → 0.5.185

package/docs/implementation-guides/file-reference-system.md

@@ -475,14 +475,15 @@ const files = await service.listFileReferences('pace_person', personId, orgId);
 
 ```sql
 -- Create file reference (replaces insert_file_reference)
+-- Requires page context for context-aware permission checks
 SELECT data_file_reference_create(
   p_table_name := 'pace_person',
   p_record_id := 'person-uuid',
   p_file_path := 'org-123/profile_photos/file.jpg',
   p_organisation_id := 'org-uuid',
   p_app_id := 'app-uuid',
+  p_page_context := 'configuration',
   p_file_metadata := '{"fileName": "photo.jpg"}'::jsonb,
-  p_category := 'profile_photos',
   p_is_public := false
 );
 

package/docs/implementation-guides/file-upload-storage.md

@@ -48,6 +48,7 @@ function MyFileUpload() {
       organisation_id="org-123"
       // app_id auto-resolved from app name
       category={FileCategory.GENERAL_DOCUMENTS}
+      pageContext="configuration"
       accept=".pdf,.doc,.docx"
       maxSize={5 * 1024 * 1024} // 5MB
       showProgress={true}
@@ -127,6 +128,7 @@ interface FileUploadProps {
   organisation_id: string;
   app_id?: string; // Optional - will be resolved from app name if not provided
   category: FileCategory;
+  pageContext: string; // The page context where the file upload occurs (e.g., 'configuration', 'forms', 'applications')
   accept?: string;
   maxSize?: number;
   multiple?: boolean;
@@ -152,6 +154,7 @@ interface FileUploadProps {
   record_id="person-123"
   organisation_id={organisationId}
   category={FileCategory.PROFILE_PHOTOS}
+  pageContext="configuration"
   accept="image/*"
   maxSize={2 * 1024 * 1024} // 2MB
   onUploadSuccess={(result) => console.log('Uploaded:', result.file_reference)}
@@ -168,6 +171,7 @@ interface FileUploadProps {
   record_id="person-123"
   organisation_id={organisationId}
   category={FileCategory.GENERAL_DOCUMENTS}
+  pageContext="forms"
   multiple={true}
   accept=".pdf,.doc,.docx"
   showProgress={true}
@@ -197,6 +201,23 @@ interface FileUploadProps {
 </FileUpload>
 ```
 
+#### Page Context and Permissions
+
+The `pageContext` parameter enables context-aware permission checks for file uploads. Instead of requiring a generic `'create:files'` permission on a `'files'` page, the system checks permissions based on the actual page where the upload occurs.
+
+**Permission Check Behavior:**
+- The system checks for `'create:page.{pageContext}'` permission first
+- If that permission doesn't exist, it checks for `'update:page.{pageContext}'` permission
+- The user needs at least one of these permissions to upload files
+- This ensures file uploads are controlled by the same permissions as the page where they occur
+
+**Example Use Cases:**
+- Event logo uploads on the `'configuration'` page require `'create:page.configuration'` or `'update:page.configuration'` permission
+- Form document uploads on the `'forms'` page require `'create:page.forms'` or `'update:page.forms'` permission
+- Application file uploads on the `'applications'` page require `'create:page.applications'` or `'update:page.applications'` permission
+
+**Important:** The `pageContext` must match a page defined in your RBAC system (`rbac_app_pages` table) for the permission checks to work correctly.
+
 ### FileDisplay
 
 A component for displaying and managing files associated with database records.

package/docs/rbac/README.md

@@ -66,6 +66,7 @@ function MyComponent() {
 - **[Event-Based Apps](./event-based-apps.md)** - Get up and running in 10 minutes (foolproof guide for event-based apps)
 - **[API Reference](./api-reference.md)** - Complete API documentation
 - **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
+- **[Compliance Guide](./compliance/compliance-guide.md)** - Ensuring proper RBAC/auth setup and usage
 - **[Examples](./examples.md)** - Practical usage examples
 - **[Advanced Patterns](./advanced-patterns.md)** - Complex scenarios and optimizations
 

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
+