@jmruthers/pace-core 0.6.4 → 0.6.6

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
@@ -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

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/secure-client-protection.md

@@ -229,38 +229,6 @@ function MyComponent() {
 }
 ```
 
-## Audit Script Detection
-
-The pace-core audit script comprehensively detects insecure client usage:
-
-```bash
-npm run audit
-```
-
-The audit will report violations including:
-- ✅ Direct `createClient` imports from `@supabase/supabase-js`
-- ✅ Direct `createClient()` function calls
-- ✅ Usage of non-secure clients for database queries (`.from()` calls)
-- ✅ Files that import `createClient` but don't use `useSecureSupabase()`
-- ✅ Variables created with `createClient()` that are used for queries
-
-**Example audit output**:
-```
-❌ Direct Supabase client usage detected
-   File: src/components/UserList.tsx
-   Line: 15
-   Variable: supabase
-   Table: users
-   Reason: Direct Supabase client usage detected. Variable 'supabase' is created with createClient() and used for database queries. You MUST use useSecureSupabase() instead to ensure RLS policies and organisation context are enforced.
-   Recommendation: Replace with: import { useSecureSupabase } from '@jmruthers/pace-core/rbac'; const supabase = useSecureSupabase();
-```
-
-The audit tool provides the same level of detection as the ESLint rule, making it useful for:
-- Pre-commit checks
-- CI/CD pipelines
-- Code reviews
-- Migration validation
-
 ## Best Practices
 
 1. **Always use `useSecureSupabase()`** in React components
@@ -268,7 +236,6 @@ The audit tool provides the same level of detection as the ESLint rule, making i
 3. **Never import `createClient`** from `@supabase/supabase-js` in component files
 4. **Verify client security** in critical code paths (optional but recommended)
 5. **Run ESLint** regularly to catch violations early
-6. **Run audit script** before deploying to catch any missed violations
 
 ## Troubleshooting
 
@@ -324,7 +291,6 @@ The protection system provides:
 - ✅ **Runtime warnings** to alert developers in development mode
 - ✅ **Type safety** to verify client security
 - ✅ **Automatic marking** of secure clients
-- ✅ **Audit scripts** to catch violations before deployment
 
 By following these guidelines, you ensure that all database operations respect organisation context and RLS policies, preventing security vulnerabilities and data leakage.