@jmruthers/pace-core 0.6.4 → 0.6.6

package/docs/rbac/RBAC_CONTRACT.md

@@ -0,0 +1,724 @@
+---
+lastUpdated: 2025-01-04T00:00:00+00:00
+version: 2.0.0
+reviewedBy: rbac-architecture-review
+---
+
+# RBAC Contract
+
+> **📋 The Definitive RBAC Contract** | [← Back to RBAC Documentation](./README.md) | [Quick Start](./quick-start.md) | [Migration Guide](./MIGRATION_GUIDE.md)
+
+This document defines the **mandatory contract** between `pace-core` and consuming applications for RBAC (Role-Based Access Control) integration. This contract is **enforced** by ESLint rules.
+
+**⚠️ CRITICAL**: This contract is **non-negotiable**. Violations will result in build errors.
+
+## Table of Contents
+
+1. [The Contract](#the-contract)
+2. [Architecture Boundary](#architecture-boundary)
+3. [Compliance Checklist](#compliance-checklist)
+4. [Anti-Patterns](#anti-patterns)
+5. [Enforcement](#enforcement)
+6. [enforcePermissions Configuration](#enforcepermissions-configuration)
+
+## The Contract
+
+### What Consuming Apps MUST Do
+
+#### 1. **MUST Use pace-core RBAC Components**
+
+**MUST use `PagePermissionGuard` for all protected pages:**
+
+```tsx
+// ✅ CORRECT
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function DashboardPage() {
+  return (
+    <PagePermissionGuard pageName="dashboard" operation="read">
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+**MUST use pace-core hooks for permission checks:**
+
+```tsx
+// ✅ CORRECT
+import { useCan, useResourcePermissions } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const canEdit = useCan('update:users');
+  const permissions = useResourcePermissions('users');
+  // ...
+}
+```
+
+**MUST use pace-core API functions for programmatic checks:**
+
+```tsx
+// ✅ CORRECT
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+
+const hasAccess = await isPermitted({
+  permission: 'read:dashboard',
+  pageName: 'dashboard'
+});
+```
+
+#### 2. **MUST Use Standard AccessDenied Component**
+
+**MUST use `AccessDenied` from pace-core for all access denied scenarios:**
+
+```tsx
+// ✅ CORRECT
+import { AccessDenied } from '@jmruthers/pace-core/rbac';
+
+<PagePermissionGuard 
+  pageName="dashboard" 
+  operation="read"
+  fallback={<AccessDenied />}
+>
+  <DashboardContent />
+</PagePermissionGuard>
+```
+
+#### 3. **MUST Configure enforcePermissions Correctly**
+
+**For event-based apps (where pages handle their own checks):**
+
+```tsx
+// ✅ CORRECT - Event-based app pattern
+<PaceAppLayout 
+  appName="MyApp"
+  enforcePermissions={false}  // Pages handle checks via PagePermissionGuard
+  // ...
+>
+```
+
+**For organisation-based apps (where layout handles checks):**
+
+```tsx
+// ✅ CORRECT - Organisation-based app pattern
+<PaceAppLayout 
+  appName="MyApp"
+  enforcePermissions={true}  // Layout handles checks
+  defaultPermission="read"
+  // ...
+>
+```
+
+#### 4. **MUST Use useSecureSupabase for RBAC Table Queries**
+
+**If you must query RBAC tables (rare), MUST use `useSecureSupabase`:**
+
+```tsx
+// ✅ CORRECT - Using secure client
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const secureSupabase = useSecureSupabase(supabase);
+  const { data } = await secureSupabase
+    .from('rbac_user_profiles')  // Allowed through secure client
+    .select('*');
+}
+```
+
+### What Consuming Apps MUST NOT Do
+
+#### 1. **MUST NOT Create Wrapper Components**
+
+**MUST NOT create wrapper components around `PagePermissionGuard`:**
+
+```tsx
+// ❌ FORBIDDEN - Wrapper component
+function EventPageGuard({ pageName, children }) {
+  // Event validation logic...
+  return (
+    <PagePermissionGuard pageName={pageName}>
+      {children}
+    </PagePermissionGuard>
+  );
+}
+```
+
+**Instead, handle validation directly in page components:**
+
+```tsx
+// ✅ CORRECT - Direct usage
+function DashboardPage() {
+  const { selectedEvent } = useEvents();
+  
+  if (!selectedEvent) {
+    return <EventSelectionPrompt />;
+  }
+  
+  return (
+    <PagePermissionGuard pageName="dashboard" operation="read">
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+#### 2. **MUST NOT Query RBAC Tables Directly**
+
+**MUST NOT query RBAC tables without using `useSecureSupabase`:**
+
+```tsx
+// ❌ FORBIDDEN - Direct query
+const { data } = await supabase
+  .from('rbac_user_profiles')  // ERROR: Direct RBAC table query
+  .select('*');
+```
+
+**MUST NOT query these tables directly:**
+- `rbac_organisation_roles`
+- `rbac_event_app_roles`
+- `rbac_global_roles`
+- `rbac_apps`
+- `rbac_app_pages`
+- `rbac_page_permissions`
+- `rbac_user_profiles`
+
+#### 3. **MUST NOT Call RBAC RPC Functions Directly**
+
+**MUST NOT call `rbac_check_permission_simplified` directly:**
+
+```tsx
+// ❌ FORBIDDEN - Direct RPC call
+const { data } = await supabase.rpc('rbac_check_permission_simplified', {
+  p_user_id: userId,
+  p_permission: 'read:dashboard'
+});
+```
+
+**Instead, use pace-core API:**
+
+```tsx
+// ✅ CORRECT - Using pace-core API
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+const hasAccess = await isPermitted({
+  permission: 'read:dashboard',
+  pageName: 'dashboard'
+});
+```
+
+#### 4. **MUST NOT Create Custom Access Denied Components**
+
+**MUST NOT create custom access denied components:**
+
+```tsx
+// ❌ FORBIDDEN - Custom component
+function CustomAccessDenied() {
+  return <div>Access Denied</div>;
+}
+```
+
+**MUST use standard component:**
+
+```tsx
+// ✅ CORRECT - Standard component
+import { AccessDenied } from '@jmruthers/pace-core/rbac';
+<AccessDenied />
+```
+
+#### 5. **MUST NOT Bypass PagePermissionGuard**
+
+**MUST NOT render protected content without `PagePermissionGuard`:**
+
+```tsx
+// ❌ FORBIDDEN - No guard
+function DashboardPage() {
+  return <DashboardContent />;  // ERROR: Unprotected page
+}
+```
+
+**MUST protect all pages:**
+
+```tsx
+// ✅ CORRECT - Protected page
+function DashboardPage() {
+  return (
+    <PagePermissionGuard pageName="dashboard" operation="read">
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+#### 6. **MUST NOT Implement Custom Permission Logic**
+
+**MUST NOT create custom permission checking functions:**
+
+```tsx
+// ❌ FORBIDDEN - Custom permission logic
+function checkPermission(userId, permission) {
+  // Custom logic...
+}
+```
+
+**MUST use pace-core functions:**
+
+```tsx
+// ✅ CORRECT - Using pace-core
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+const hasAccess = await isPermitted({ permission: 'read:dashboard' });
+```
+
+#### 7. **MUST NOT Use Hardcoded Role Checks**
+
+**MUST NOT compare roles directly:**
+
+```tsx
+// ❌ FORBIDDEN - Hardcoded role check
+if (user.role === 'admin') {
+  // ...
+}
+```
+
+**MUST use pace-core hooks/APIs:**
+
+```tsx
+// ✅ CORRECT - Using pace-core
+import { useAccessLevel } from '@jmruthers/pace-core/rbac';
+const { accessLevel } = useAccessLevel();
+if (accessLevel === 'admin') {
+  // ...
+}
+```
+
+#### 8. **MUST NOT Use Resource Permission String Literals**
+
+**MUST NOT use string literals in `useResourcePermissions`:**
+
+```tsx
+// ❌ FORBIDDEN - String literal
+const { canCreate } = useResourcePermissions('journal');
+```
+
+**MUST use RESOURCE_NAMES constant:**
+
+```tsx
+// ✅ CORRECT - Using constant
+import { RESOURCE_NAMES } from '@/config/resource-names';
+const { canCreate } = useResourcePermissions(RESOURCE_NAMES.JOURNAL);
+```
+
+#### 9. **MUST NOT Create Permission Wrapper Functions**
+
+**MUST NOT create wrapper functions around permission checks:**
+
+```tsx
+// ❌ FORBIDDEN - Wrapper function
+const canEdit = (postId: string) => {
+  const hasPermission = canUpdate('journal');
+  const post = posts.find(p => p.id === postId);
+  return hasPermission && !!post;
+};
+```
+
+**MUST use pace-core hooks directly:**
+
+```tsx
+// ✅ CORRECT - Direct usage
+const { canUpdate } = useResourcePermissions(RESOURCE_NAMES.JOURNAL);
+// Use canUpdate directly in components
+```
+
+### What Consuming Apps MAY Do
+
+#### 1. **MAY Configure Navigation**
+
+**MAY define navigation configuration:**
+
+```tsx
+// ✅ ALLOWED - Navigation configuration
+const navItems = [
+  { label: 'Dashboard', path: '/dashboard' },
+  { label: 'Users', path: '/users' }
+];
+
+const routePermissions = {
+  '/dashboard': 'read:dashboard',
+  '/users': 'read:users'
+};
+```
+
+#### 2. **MAY Customize AccessDenied Props**
+
+**MAY customize `AccessDenied` component with props:**
+
+```tsx
+// ✅ ALLOWED - Customized AccessDenied
+<AccessDenied 
+  message="You don't have permission to view this page."
+  onGoBack={() => navigate('/dashboard')}
+  showSignOut={true}
+/>
+```
+
+#### 3. **MAY Handle Event Context Validation**
+
+**MAY validate event context in page components:**
+
+```tsx
+// ✅ ALLOWED - Event context validation
+function DashboardPage() {
+  const { selectedEvent } = useEvents();
+  
+  if (!selectedEvent) {
+    return <EventSelectionPrompt />;
+  }
+  
+  return (
+    <PagePermissionGuard pageName="dashboard" operation="read">
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+## Architecture Boundary
+
+### What Lives in pace-core
+
+**Core Permission Logic:**
+- `RBACEngine.isPermitted` - Permission checking algorithm
+- Database RPC calls (`rbac_check_permission_simplified`)
+- Super admin detection
+- Scope resolution logic
+- Cache management
+
+**Components:**
+- `PagePermissionGuard` - Standard page protection (single canonical component)
+- `NavigationGuard` - Navigation item protection
+- `AccessDenied` - Standard access denied component
+
+**Hooks:**
+- `useCan` - Single permission check
+- `usePermissions` - Permission map retrieval
+- `useMultiplePermissions` - Multiple permission checks (covers any/all logic)
+- `useAccessLevel` - Access level checks
+- `useResourcePermissions` - Resource CRUD permissions
+- `useResolvedScope` - Scope resolution
+- `useSecureSupabase` - Secure Supabase client access
+
+**API Functions:**
+- `isPermitted` - Core permission check
+- `getRoleContext` - Role information
+- `setupRBAC` - Initialization
+
+**Types and Utilities:**
+- All RBAC types (`Permission`, `Scope`, `RBACRoleContext`)
+- Security validators
+- Cache utilities
+
+### What Lives in Consuming Apps
+
+**Configuration:**
+- Navigation configuration (`navItems`, `routePermissions`, `pageIdMapping`)
+- App-specific page names and constants
+
+**UI Integration:**
+- Permission-aware UI rendering (using pace-core hooks)
+- Custom styling of standard `AccessDenied` component (via props)
+- Event context validation (if needed)
+
+## Compliance Checklist
+
+Before deploying your application, verify:
+
+- [ ] All pages are wrapped with `PagePermissionGuard`
+- [ ] No direct queries to RBAC tables (except through `useSecureSupabase`)
+- [ ] No direct RPC calls to `rbac_check_permission_simplified`
+- [ ] No wrapper components around `PagePermissionGuard`
+- [ ] No custom access denied components
+- [ ] No hardcoded role checks (use `useAccessLevel` or `getRoleContext`)
+- [ ] No custom permission utility functions
+- [ ] No resource permission string literals (use `RESOURCE_NAMES` constants)
+- [ ] No permission wrapper functions (use pace-core hooks directly)
+- [ ] `enforcePermissions` configured correctly for your app type
+- [ ] All access denied scenarios use `AccessDenied` from pace-core
+- [ ] ESLint rules pass without errors
+
+## Anti-Patterns
+
+### Anti-Pattern 1: Wrapper Components
+
+```tsx
+// ❌ ANTI-PATTERN
+function EventPageGuard({ pageName, children }) {
+  const { selectedEvent } = useEvents();
+  if (!selectedEvent) return <EventSelectionPrompt />;
+  return <PagePermissionGuard pageName={pageName}>{children}</PagePermissionGuard>;
+}
+```
+
+**Why it's wrong:**
+- Decreases maintainability
+- Adds unnecessary abstraction
+- Duplicates logic that should be in pages
+
+**Correct pattern:**
+
+```tsx
+// ✅ CORRECT
+function DashboardPage() {
+  const { selectedEvent } = useEvents();
+  if (!selectedEvent) return <EventSelectionPrompt />;
+  return (
+    <PagePermissionGuard pageName="dashboard" operation="read">
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+### Anti-Pattern 2: Direct Database Queries
+
+```tsx
+// ❌ ANTI-PATTERN
+const { data } = await supabase
+  .from('rbac_user_profiles')
+  .select('*');
+```
+
+**Why it's wrong:**
+- Bypasses security controls
+- Violates architecture boundary
+- Not future-proof
+
+**Correct pattern:**
+
+```tsx
+// ✅ CORRECT
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+const secureSupabase = useSecureSupabase(supabase);
+const { data } = await secureSupabase
+  .from('rbac_user_profiles')
+  .select('*');
+```
+
+### Anti-Pattern 3: Custom Access Denied
+
+```tsx
+// ❌ ANTI-PATTERN
+function CustomAccessDenied() {
+  return <div>Access Denied</div>;
+}
+```
+
+**Why it's wrong:**
+- Inconsistent UX across apps
+- Duplicates standard functionality
+- Not maintainable
+
+**Correct pattern:**
+
+```tsx
+// ✅ CORRECT
+import { AccessDenied } from '@jmruthers/pace-core/rbac';
+<AccessDenied />
+```
+
+### Anti-Pattern 4: Hardcoded Role Checks
+
+```tsx
+// ❌ ANTI-PATTERN
+if (user.role === 'admin') {
+  // ...
+}
+```
+
+**Why it's wrong:**
+- Bypasses RBAC system
+- Not maintainable (role names can change)
+- Doesn't respect permission hierarchy
+
+**Correct pattern:**
+
+```tsx
+// ✅ CORRECT
+import { useAccessLevel } from '@jmruthers/pace-core/rbac';
+const { accessLevel } = useAccessLevel();
+if (accessLevel === 'admin') {
+  // ...
+}
+```
+
+### Anti-Pattern 5: Custom Permission Utilities
+
+```tsx
+// ❌ ANTI-PATTERN
+function checkPermission(userId, permission) {
+  // Custom logic...
+}
+```
+
+**Why it's wrong:**
+- Duplicates pace-core functionality
+- Bypasses centralized RBAC logic
+- Not future-proof
+
+**Correct pattern:**
+
+```tsx
+// ✅ CORRECT
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+const hasAccess = await isPermitted({ permission: 'read:dashboard' });
+```
+
+### Anti-Pattern 6: Resource Permission String Literals
+
+```tsx
+// ❌ ANTI-PATTERN
+const { canCreate } = useResourcePermissions('journal');
+```
+
+**Why it's wrong:**
+- Not type-safe (typos possible)
+- No compile-time validation
+- Maintenance burden
+
+**Correct pattern:**
+
+```tsx
+// ✅ CORRECT
+import { RESOURCE_NAMES } from '@/config/resource-names';
+const { canCreate } = useResourcePermissions(RESOURCE_NAMES.JOURNAL);
+```
+
+### Anti-Pattern 7: Permission Wrapper Functions
+
+```tsx
+// ❌ ANTI-PATTERN
+const canEdit = (postId: string) => {
+  const hasPermission = canUpdate('journal');
+  const post = posts.find(p => p.id === postId);
+  return hasPermission && !!post;
+};
+```
+
+**Why it's wrong:**
+- Unnecessary abstraction layer
+- Encourages bypassing direct pace-core usage
+- Creates maintenance burden
+
+**Correct pattern:**
+
+```tsx
+// ✅ CORRECT
+const { canUpdate } = useResourcePermissions(RESOURCE_NAMES.JOURNAL);
+// Use canUpdate directly in components
+```
+
+## Enforcement
+
+### ESLint Rules
+
+The following ESLint rules enforce this contract (all as **ERROR** severity):
+
+1. **`no-direct-rbac-rpc`** - Detects direct calls to `rbac_check_permission_simplified`
+2. **`no-direct-rbac-tables`** - Detects direct queries to RBAC tables
+3. **`no-bypass-page-guard`** - Detects routes without `PagePermissionGuard`
+4. **`no-custom-access-denied`** - Detects custom access denied components
+5. **`no-hardcoded-role-checks`** - Detects hardcoded role comparisons
+6. **`no-custom-permission-utilities`** - Detects custom permission utility functions
+7. **`no-resource-permission-string-literals`** - Detects string literals in `useResourcePermissions` calls
+8. **`no-permission-wrapper-functions`** - Detects wrapper functions around pace-core permission hooks
+
+### Runtime Compliance
+
+Use runtime compliance checking in development:
+
+```tsx
+import { checkRuntimeCompliance } from '@jmruthers/pace-core/rbac/compliance';
+
+// In development mode
+if (import.meta.env.DEV) {
+  checkRuntimeCompliance();
+}
+```
+
+## enforcePermissions Configuration
+
+### When to Use `enforcePermissions={true}`
+
+**Use for organisation-based apps** where the layout handles permission checks:
+
+```tsx
+<PaceAppLayout 
+  appName="MyApp"
+  enforcePermissions={true}  // Layout validates all routes
+  defaultPermission="read"
+  routePermissions={{
+    '/dashboard': 'read:dashboard',
+    '/users': 'read:users'
+  }}
+>
+```
+
+**Benefits:**
+- Automatic route protection
+- Safety net for forgotten permission checks
+- Centralized permission configuration
+
+### When to Use `enforcePermissions={false}`
+
+**Use for event-based apps** where pages handle their own checks:
+
+```tsx
+<PaceAppLayout 
+  appName="MyApp"
+  enforcePermissions={false}  // Pages handle checks via PagePermissionGuard
+  showEvents={true}
+>
+  {/* Pages use PagePermissionGuard directly */}
+</PaceAppLayout>
+```
+
+**Why `false` for event-based apps:**
+- Pages need event context validation before permission checks
+- `PagePermissionGuard` handles both event validation and permission checks
+- Avoids redundant checks and timing issues
+
+**Pattern:**
+
+```tsx
+// Each page handles its own checks
+function DashboardPage() {
+  const { selectedEvent } = useEvents();
+  if (!selectedEvent) return <EventSelectionPrompt />;
+  
+  return (
+    <PagePermissionGuard pageName="dashboard" operation="read">
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+## Related Documentation
+
+- [RBAC README](./README.md) - Overview and quick start
+- [Quick Start Guide](./quick-start.md) - Step-by-step setup
+- [Event-Based Apps](./event-based-apps.md) - Event-based app patterns
+- [Permission Enforcement](../implementation-guides/permission-enforcement.md) - Detailed enforcement patterns
+- [Migration Guide](./MIGRATION_GUIDE.md) - Migrating to this contract
+
+## Support
+
+If you have questions about this contract or need clarification:
+
+1. Review the [Troubleshooting Guide](./troubleshooting.md)
+2. Check [Examples](./examples.md) for common patterns
+3. Review [API Reference](./api-reference.md) for detailed API documentation
+
+---
+
+**Last Updated**: 2025-01-04  
+**Version**: 2.0.0  
+**Status**: Enforced
+