@jmruthers/pace-core 0.6.5 → 0.6.7

package/docs/rbac/README.md

@@ -12,6 +12,8 @@ The PACE Core RBAC (Role-Based Access Control) system provides comprehensive per
 
 ## 🚨 Critical Rules (Follow These or It Won't Work)
 
+> **📋 IMPORTANT**: See [RBAC Contract](./RBAC_CONTRACT.md) for the complete, enforceable contract. This section provides a quick overview.
+
 **MANDATORY Setup Steps (in order):**
 
 1. **Call `setupRBAC(supabase)` FIRST** - Must be called before any RBAC components or hooks
@@ -42,6 +44,8 @@ The PACE Core RBAC (Role-Based Access Control) system provides comprehensive per
 6. **App name must match exactly** - Environment variable must match `rbac_apps.name` (case-sensitive)
 7. **Never query RBAC tables directly** - Always use `PagePermissionGuard` or RBAC API functions
 
+**⚠️ Contract Compliance**: All consuming apps must comply with the [RBAC Contract](./RBAC_CONTRACT.md). Violations will result in build errors.
+
 ## 🚀 Quick Start
 
 ```tsx
@@ -52,7 +56,7 @@ function MyComponent() {
     <PagePermissionGuard
       pageName="users"
       operation="read"
-      fallback={<div>Access Denied</div>}
+      fallback={<p>Access Denied</p>}
     >
       <UserList />
     </PagePermissionGuard>
@@ -62,6 +66,8 @@ function MyComponent() {
 
 ## 📖 Core Concepts
 
+- **[RBAC Contract](./RBAC_CONTRACT.md)** - ⚠️ **START HERE** - The definitive, enforceable contract (MUST read)
+- **[Migration Guide](./MIGRATION_GUIDE.md)** - Migrating to RBAC Contract v2.0.0
 - **[Quick Start](./quick-start.md)** - Get up and running in 10 minutes (foolproof guide for organisation-based apps)
 - **[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
@@ -138,11 +144,14 @@ graph TD
 - `useCan` - Check individual permissions
 - `usePermissions` - Get all permissions for a scope
 - `useAccessLevel` - Get user's access level
-- `useMultiplePermissions` - Check multiple permissions efficiently
+- `useMultiplePermissions` - Check multiple permissions efficiently (covers any/all logic)
+- `useResourcePermissions` - Resource CRUD permissions
+- `useSecureSupabase` - Secure Supabase client access
 
 ### Components
-- `PermissionGuard` - Conditional rendering based on permissions
-- `AccessLevelGuard` - Conditional rendering based on access level
+- `PagePermissionGuard` - Page-level permission protection (single canonical component)
+- `NavigationGuard` - Navigation item protection
+- `AccessDenied` - Standard access denied component
 
 ### Utilities
 - `isPermitted` - Server-side permission checking
@@ -223,9 +232,9 @@ function UsersPage() {
     <PagePermissionGuard
       pageName="users"
       operation="read"
-      fallback={<div>You don't have permission to view this page</div>}
+      fallback={<p>You don't have permission to view this page</p>}
     >
-      <div>
+      <section>
         <h1>User Management</h1>
         
         {/* Multiple operations on same page */}
@@ -252,7 +261,7 @@ function UsersPage() {
         >
           <DeleteUserButtons />
         </PagePermissionGuard>
-      </div>
+      </section>
     </PagePermissionGuard>
   );
 }
@@ -273,7 +282,7 @@ function AdminPanel() {
     <PagePermissionGuard
       pageName="admin"
       operation="read"
-      fallback={<div>Access denied</div>}
+      fallback={<p>Access denied</p>}
     >
       <UserManagement />
     </PagePermissionGuard>

package/docs/rbac/advanced-patterns.md

@@ -379,7 +379,7 @@ export function withPermission(permission: string, fallback?: React.ComponentTyp
 
 // Usage
 const ProtectedUserList = withPermission('read:users', () => (
-  <div>Access denied to user list</div>
+  <p>Access denied to user list</p>
 ))(UserList);
 
 // In component
@@ -436,16 +436,16 @@ export const useOrganisationPermissions = createPermissionHook('organisations');
 function UserManagement({ userId, scope }) {
   const { permissions, isLoading } = useUserPermissions(userId, scope);
 
-  if (isLoading) return <div>Loading permissions...</div>;
+  if (isLoading) return <p>Loading permissions...</p>;
 
   return (
-    <div>
+    <section>
       {permissions.read && <UserList />}
       {permissions.create && <CreateUserButton />}
       {permissions.update && <EditUserButton />}
       {permissions.delete && <DeleteUserButton />}
       {permissions.manage && <UserManagementPanel />}
-    </div>
+    </section>
   );
 }
 ```
@@ -647,7 +647,7 @@ import { withPermission } from './permission-decorators';
 
 // Mock component
 const TestComponent = ({ data }: { data: string }) => (
-  <div>Test Component: {data}</div>
+  <p>Test Component: {data}</p>
 );
 
 describe('Permission Decorators', () => {
@@ -684,7 +684,7 @@ describe('Permission Decorators', () => {
       })
     }));
 
-    const FallbackComponent = () => <div>Access Denied</div>;
+    const FallbackComponent = () => <p>Access Denied</p>;
     const ProtectedComponent = withPermission('read:users', FallbackComponent)(TestComponent);
 
     render(

package/docs/rbac/api-reference.md

@@ -44,13 +44,13 @@ function UserActions() {
     undefined // No pageId for event-app permissions
   );
 
-  if (error) return <div>Error: {error.message}</div>;
-  if (isLoading) return <div>Checking permissions...</div>;
+  if (error) return <p>Error: {error.message}</p>;
+  if (isLoading) return <p>Checking permissions...</p>;
 
   return (
-    <div>
+    <section>
       {can && <EventActions />}
-    </div>
+    </section>
   );
 }
 ```
@@ -87,19 +87,19 @@ function PermissionDisplay() {
     }
   );
 
-  if (isLoading) return <div>Loading permissions...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+  if (isLoading) return <p>Loading permissions...</p>;
+  if (error) return <p>Error: {error.message}</p>;
 
   return (
-    <div>
+    <section>
       <h3>User Permissions</h3>
       {Object.entries(permissions).map(([pageId, operations]) => (
-        <div key={pageId}>
+        <p key={pageId}>
           <strong>{pageId}:</strong> {operations.join(', ')}
-        </div>
+        </p>
       ))}
       <button onClick={refetch}>Refresh</button>
-    </div>
+    </section>
   );
 }
 ```
@@ -128,13 +128,13 @@ function AccessLevelDisplay({ userId, scope }) {
     scope
   });
 
-  if (isLoading) return <div>Loading access level...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+  if (isLoading) return <p>Loading access level...</p>;
+  if (error) return <p>Error: {error.message}</p>;
 
   return (
-    <div>
+    <section>
       <p>Access Level: {accessLevel || 'None'}</p>
-    </div>
+    </section>
   );
 }
 ```
@@ -183,12 +183,12 @@ function UserManagement({ userId, scope }) {
   }, [checkMultiple, isLoading, userId, scope]);
 
   return (
-    <div>
+    <section>
       {permissions['read:users'] && <UserList />}
       {permissions['create:users'] && <CreateUserButton />}
       {permissions['update:users'] && <EditUserButton />}
       {permissions['delete:users'] && <DeleteUserButton />}
-    </div>
+    </section>
   );
 }
 ```
@@ -221,12 +221,12 @@ import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
 
 function UserActions() {
   return (
-    <div>
+    <section>
       {/* Pattern 1: PermissionEnforcer - automatic scope resolution */}
       <PermissionEnforcer
         permissions={['read:users']}
         operation="user-management"
-        fallback={<div>Access Denied</div>}
+        fallback={<p>Access Denied</p>}
       >
         <UserList />
       </PermissionEnforcer>
@@ -236,11 +236,11 @@ function UserActions() {
         permissions={['create:users', 'update:users']}
         operation="user-crud"
         requireAll={true} // User needs ALL permissions
-        fallback={<div>You need create and update permissions</div>}
+        fallback={<p>You need create and update permissions</p>}
       >
         <UserManagementPanel />
       </PermissionEnforcer>
-    </div>
+    </section>
   );
 }
 ```

package/docs/rbac/edge-functions-guide.md

@@ -0,0 +1,376 @@
+---
+lastUpdated: 2025-01-28T00:00:00+11:00
+version: 0.6.0
+reviewedBy: rbac-compliance-audit
+---
+
+# Edge Functions RBAC Guide
+
+**📚 Related**: [RBAC Compliance Guide](../standards/09-rbac-compliance.md) | [RBAC API Reference](./api-reference.md)
+
+This guide explains how to use pace-core RBAC APIs in Edge Functions (Deno serverless functions). **There are NO exceptions** - Edge Functions MUST use pace-core APIs, not custom RBAC helpers.
+
+## Why No Exceptions?
+
+Edge Functions cannot use React hooks (they're Deno-based serverless functions), but pace-core provides programmatic APIs that work outside React:
+
+- ✅ `isPermitted()` - Programmatic permission checking API
+- ✅ `setupRBAC()` - Initialize RBAC engine with Supabase client
+- ✅ `getAccessLevel()` - Get user access level
+- ✅ `getRoleContext()` - Get user role context
+
+**Custom RBAC helpers are FORBIDDEN** because they:
+- Bypass security validation
+- Skip audit logging
+- Miss caching optimizations
+- Duplicate functionality that pace-core already provides
+
+## Correct Pattern
+
+### Step 1: Create Supabase Client
+
+```typescript
+import { createClient } from 'jsr:@supabase/supabase-js@2';
+
+Deno.serve(async (req: Request) => {
+  // Extract auth token from request
+  const authHeader = req.headers.get('Authorization');
+  if (!authHeader) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+  }
+
+  // Create Supabase client with auth header
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL') ?? '',
+    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
+    {
+      global: {
+        headers: { Authorization: authHeader },
+      },
+    }
+  );
+```
+
+### Step 2: Get User from Session
+
+```typescript
+  // Get authenticated user
+  const { data: { user }, error: authError } = await supabase.auth.getUser();
+  if (authError || !user) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+  }
+```
+
+### Step 3: Setup RBAC
+
+```typescript
+  // Import pace-core RBAC functions
+  import { setupRBAC, isPermitted } from 'npm:@jmruthers/pace-core@^0.6.0/rbac';
+
+  // Setup RBAC (MUST be called before using isPermitted)
+  setupRBAC(supabase);
+```
+
+### Step 4: Extract Organisation Context
+
+```typescript
+  // Extract organisation context from request
+  // Option 1: From headers
+  const organisationId = req.headers.get('x-organisation-id');
+
+  // Option 2: From request body
+  if (!organisationId) {
+    const body = await req.json();
+    organisationId = body.organisationId;
+  }
+
+  // Option 3: From query parameters
+  if (!organisationId) {
+    const url = new URL(req.url);
+    organisationId = url.searchParams.get('organisationId');
+  }
+
+  if (!organisationId) {
+    return new Response(
+      JSON.stringify({ error: 'Organisation context required' }), 
+      { status: 400 }
+    );
+  }
+```
+
+### Step 5: Check Permission
+
+```typescript
+  // Check permission using pace-core API
+  const hasPermission = await isPermitted({
+    userId: user.id,
+    scope: { 
+      organisationId,
+      eventId: req.headers.get('x-event-id'), // Optional
+      appId: req.headers.get('x-app-id'),     // Optional
+    },
+    permission: 'read:dashboard',
+    pageId: 'dashboard' // Optional, but recommended
+  });
+
+  if (!hasPermission) {
+    return new Response(
+      JSON.stringify({ error: 'Permission denied' }), 
+      { status: 403 }
+    );
+  }
+
+  // Proceed with function logic
+  return new Response(JSON.stringify({ success: true }));
+});
+```
+
+## Complete Example
+
+```typescript
+// supabase/functions/protected-endpoint/index.ts
+import { createClient } from 'jsr:@supabase/supabase-js@2';
+import { setupRBAC, isPermitted } from 'npm:@jmruthers/pace-core@^0.6.0/rbac';
+
+Deno.serve(async (req: Request) => {
+  try {
+    // 1. Extract auth token
+    const authHeader = req.headers.get('Authorization');
+    if (!authHeader) {
+      return new Response(
+        JSON.stringify({ error: 'Unauthorized' }), 
+        { status: 401, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+
+    // 2. Create Supabase client
+    const supabase = createClient(
+      Deno.env.get('SUPABASE_URL') ?? '',
+      Deno.env.get('SUPABASE_ANON_KEY') ?? '',
+      {
+        global: {
+          headers: { Authorization: authHeader },
+        },
+      }
+    );
+
+    // 3. Get authenticated user
+    const { data: { user }, error: authError } = await supabase.auth.getUser();
+    if (authError || !user) {
+      return new Response(
+        JSON.stringify({ error: 'Unauthorized' }), 
+        { status: 401, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+
+    // 4. Setup RBAC
+    setupRBAC(supabase);
+
+    // 5. Extract organisation context
+    const organisationId = req.headers.get('x-organisation-id') || 
+                          (await req.json().catch(() => ({}))).organisationId;
+
+    if (!organisationId) {
+      return new Response(
+        JSON.stringify({ error: 'Organisation context required' }), 
+        { status: 400, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+
+    // 6. Check permission
+    const hasPermission = await isPermitted({
+      userId: user.id,
+      scope: { organisationId },
+      permission: 'read:dashboard',
+      pageId: 'dashboard'
+    });
+
+    if (!hasPermission) {
+      return new Response(
+        JSON.stringify({ error: 'Permission denied' }), 
+        { status: 403, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+
+    // 7. Execute function logic
+    const result = {
+      message: 'Access granted',
+      userId: user.id,
+      organisationId
+    };
+
+    return new Response(
+      JSON.stringify(result), 
+      { 
+        status: 200, 
+        headers: { 'Content-Type': 'application/json' } 
+      }
+    );
+  } catch (error) {
+    console.error('Edge Function error:', error);
+    return new Response(
+      JSON.stringify({ error: 'Internal server error' }), 
+      { status: 500, headers: { 'Content-Type': 'application/json' } }
+    );
+  }
+});
+```
+
+## Migration Guide: Removing Custom RBAC Helpers
+
+If you have existing Edge Functions with custom RBAC helpers, follow these steps:
+
+### Step 1: Identify Custom Helpers
+
+Search for custom RBAC helpers:
+```bash
+# Find files with custom RBAC helpers
+grep -r "rbac_check_permission_simplified" supabase/functions/
+grep -r "function.*checkPermission" supabase/functions/
+grep -r "pace-core-compliance-exception" supabase/functions/
+```
+
+### Step 2: Replace Custom Helper with pace-core API
+
+**Before (❌ FORBIDDEN):**
+```typescript
+// supabase/functions/_shared/rbac.ts
+export async function checkPermission(
+  supabase: SupabaseClient,
+  userId: string,
+  permission: string,
+  organisationId: string
+): Promise<boolean> {
+  const { data, error } = await supabase.rpc('rbac_check_permission_simplified', {
+    p_user_id: userId,
+    p_permission: permission,
+    p_organisation_id: organisationId
+  });
+  return data === true;
+}
+
+// supabase/functions/my-function/index.ts
+import { checkPermission } from '../_shared/rbac.ts';
+
+const hasPermission = await checkPermission(supabase, user.id, 'read:dashboard', orgId);
+```
+
+**After (✅ CORRECT):**
+```typescript
+// supabase/functions/my-function/index.ts
+import { setupRBAC, isPermitted } from 'npm:@jmruthers/pace-core@^0.6.0/rbac';
+
+// Setup RBAC once
+setupRBAC(supabase);
+
+// Use pace-core API directly
+const hasPermission = await isPermitted({
+  userId: user.id,
+  scope: { organisationId: orgId },
+  permission: 'read:dashboard',
+  pageId: 'dashboard'
+});
+```
+
+### Step 3: Remove Custom Helper Files
+
+After migrating all Edge Functions:
+```bash
+# Remove custom RBAC helper file
+rm supabase/functions/_shared/rbac.ts
+```
+
+### Step 4: Update All Edge Functions
+
+Update each Edge Function to:
+1. Import `setupRBAC` and `isPermitted` from pace-core
+2. Call `setupRBAC(supabase)` before permission checks
+3. Use `isPermitted()` with complete `PermissionCheck` input
+4. Remove imports of custom RBAC helpers
+
+## Common Mistakes
+
+### ❌ Mistake 1: Calling RPC Directly
+
+```typescript
+// ❌ FORBIDDEN
+const { data } = await supabase.rpc('rbac_check_permission_simplified', {
+  p_user_id: userId,
+  p_permission: 'read:dashboard'
+});
+```
+
+**Fix:**
+```typescript
+// ✅ CORRECT
+setupRBAC(supabase);
+const hasPermission = await isPermitted({
+  userId,
+  scope: { organisationId },
+  permission: 'read:dashboard'
+});
+```
+
+### ❌ Mistake 2: Forgetting to Setup RBAC
+
+```typescript
+// ❌ FORBIDDEN - Missing setupRBAC
+import { isPermitted } from 'npm:@jmruthers/pace-core@^0.6.0/rbac';
+
+const hasPermission = await isPermitted({ ... }); // Will fail!
+```
+
+**Fix:**
+```typescript
+// ✅ CORRECT
+import { setupRBAC, isPermitted } from 'npm:@jmruthers/pace-core@^0.6.0/rbac';
+
+setupRBAC(supabase); // MUST be called first
+const hasPermission = await isPermitted({ ... });
+```
+
+### ❌ Mistake 3: Missing Organisation Context
+
+```typescript
+// ❌ FORBIDDEN - Missing organisationId
+const hasPermission = await isPermitted({
+  userId: user.id,
+  scope: {}, // Missing organisationId
+  permission: 'read:dashboard'
+});
+```
+
+**Fix:**
+```typescript
+// ✅ CORRECT
+const organisationId = req.headers.get('x-organisation-id');
+if (!organisationId) {
+  return new Response(JSON.stringify({ error: 'Organisation context required' }), { status: 400 });
+}
+
+const hasPermission = await isPermitted({
+  userId: user.id,
+  scope: { organisationId },
+  permission: 'read:dashboard'
+});
+```
+
+## Verification Checklist
+
+Before deploying Edge Functions, verify:
+
+- [ ] `setupRBAC(supabase)` is called before any permission checks
+- [ ] `isPermitted()` is used instead of custom helpers
+- [ ] No direct calls to `rbac_check_permission_simplified` RPC
+- [ ] Organisation context is extracted from request
+- [ ] User authentication is verified before permission checks
+- [ ] Error handling for missing auth/context
+- [ ] No custom RBAC helper files exist
+- [ ] All Edge Functions follow the correct pattern
+
+## Related Documentation
+
+- [RBAC Compliance Guide](../standards/09-rbac-compliance.md) - Complete compliance rules
+- [RBAC API Reference](./api-reference.md) - Complete API documentation
+- [RBAC Quick Start](./quick-start.md) - Getting started guide
+

package/docs/rbac/event-based-apps.md

@@ -491,7 +491,7 @@ export function Dashboard() {
   const { user, selectedEventId, selectedOrganisationId } = useUnifiedAuth()
 
   if (!user) {
-    return <div>Please log in</div>
+    return <p>Please log in</p>
   }
 
   return (
@@ -580,7 +580,7 @@ export function Participants() {
   const { user, selectedEventId, selectedOrganisationId } = useUnifiedAuth()
 
   if (!user) {
-    return <div>Please log in</div>
+    return <p>Please log in</p>
   }
 
   return (
@@ -748,7 +748,7 @@ setupRBAC(supabase) // Must be called BEFORE rendering app
        setSelectedEventId('your-event-id');
      }, []);
      
-     return <div>...</div>;
+     return <p>...</p>;
    }
    ```