@jmruthers/pace-core 0.2.4

package/docs/rbac/api-reference.md

@@ -0,0 +1,1033 @@
+# RBAC API Reference
+
+Complete API documentation for the PACE Core RBAC system.
+
+## Hooks
+
+### useCan
+
+Check individual permissions with caching and loading states. **Note**: For page-level permissions, prefer `PagePermissionGuard` component.
+
+```typescript
+interface UseCanReturn {
+  can: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  check: () => Promise<void>;
+}
+```
+
+#### Usage
+
+```tsx
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+function UserActions() {
+  const { user, selectedOrganisationId, selectedEventId } = useUnifiedAuth();
+  
+  // For non-page permissions (e.g., event-app permissions)
+  const { can, isLoading, error } = useCan(
+    user?.id || '',
+    { 
+      organisationId: selectedOrganisationId || '',
+      eventId: selectedEventId || undefined,
+      appId: undefined // Will be resolved automatically
+    },
+    'read:events', // Event-app permission
+    undefined // No pageId for event-app permissions
+  );
+
+  if (error) return <div>Error: {error.message}</div>;
+  if (isLoading) return <div>Checking permissions...</div>;
+
+  return (
+    <div>
+      {can && <EventActions />}
+    </div>
+  );
+}
+```
+
+### usePermissions
+
+Get all permissions for a user in a specific scope.
+
+```typescript
+interface UsePermissionsReturn {
+  permissions: PermissionMap;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+```
+
+#### Usage
+
+```tsx
+import { usePermissions } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+function PermissionDisplay() {
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  
+  // Explicit scope required for usePermissions
+  const { permissions, isLoading, error, refetch } = usePermissions(
+    user?.id || '',
+    { 
+      organisationId: selectedOrganisationId || '',
+      eventId: undefined,
+      appId: undefined
+    }
+  );
+
+  if (isLoading) return <div>Loading permissions...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h3>User Permissions</h3>
+      {Object.entries(permissions).map(([pageId, operations]) => (
+        <div key={pageId}>
+          <strong>{pageId}:</strong> {operations.join(', ')}
+        </div>
+      ))}
+      <button onClick={refetch}>Refresh</button>
+    </div>
+  );
+}
+```
+
+### useAccessLevel
+
+Get the user's access level in a specific scope.
+
+```typescript
+interface UseAccessLevelReturn {
+  accessLevel: AccessLevel | null;
+  isLoading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+}
+```
+
+#### Usage
+
+```tsx
+import { useAccessLevel } from '@jmruthers/pace-core/rbac';
+
+function AccessLevelDisplay({ userId, scope }) {
+  const { accessLevel, isLoading, error } = useAccessLevel({
+    userId,
+    scope
+  });
+
+  if (isLoading) return <div>Loading access level...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <p>Access Level: {accessLevel || 'None'}</p>
+    </div>
+  );
+}
+```
+
+### useMultiplePermissions
+
+Check multiple permissions efficiently in a single operation.
+
+```typescript
+interface UseMultiplePermissionsReturn {
+  checkMultiple: (checks: PermissionCheck[]) => Promise<PermissionResult[]>;
+  isLoading: boolean;
+  error: Error | null;
+}
+```
+
+#### Usage
+
+```tsx
+import { useMultiplePermissions } from '@jmruthers/pace-core/rbac';
+
+function UserManagement({ userId, scope }) {
+  const { checkMultiple, isLoading } = useMultiplePermissions();
+  const [permissions, setPermissions] = useState({});
+
+  useEffect(() => {
+    const checkAllPermissions = async () => {
+      if (!isLoading) {
+        const results = await checkMultiple([
+          { userId, scope, permission: 'read:users' },
+          { userId, scope, permission: 'create:users' },
+          { userId, scope, permission: 'update:users' },
+          { userId, scope, permission: 'delete:users' }
+        ]);
+        
+        const permMap = results.reduce((acc, result) => {
+          acc[result.permission] = result.allowed;
+          return acc;
+        }, {});
+        
+        setPermissions(permMap);
+      }
+    };
+    
+    checkAllPermissions();
+  }, [checkMultiple, isLoading, userId, scope]);
+
+  return (
+    <div>
+      {permissions['read:users'] && <UserList />}
+      {permissions['create:users'] && <CreateUserButton />}
+      {permissions['update:users'] && <EditUserButton />}
+      {permissions['delete:users'] && <DeleteUserButton />}
+    </div>
+  );
+}
+```
+
+## Components
+
+### PermissionEnforcer
+
+Conditionally render children based on user permissions. **Automatic scope resolution** - no manual context handling required.
+
+```typescript
+interface PermissionEnforcerProps {
+  permissions: Permission[];
+  operation: string;
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+  strictMode?: boolean;
+  auditLog?: boolean;
+  scope?: Scope; // Optional - will use context if not provided
+  onDenied?: (permissions: Permission[], operation: string) => void;
+  loading?: React.ReactNode;
+  requireAll?: boolean;
+}
+```
+
+#### Usage
+
+```tsx
+import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
+
+function UserActions() {
+  return (
+    <div>
+      {/* Pattern 1: PermissionEnforcer - automatic scope resolution */}
+      <PermissionEnforcer
+        permissions={['read:users']}
+        operation="user-management"
+        fallback={<div>Access Denied</div>}
+      >
+        <UserList />
+      </PermissionEnforcer>
+      
+      {/* Pattern 2: Multiple permissions */}
+      <PermissionEnforcer
+        permissions={['create:users', 'update:users']}
+        operation="user-crud"
+        requireAll={true} // User needs ALL permissions
+        fallback={<div>You need create and update permissions</div>}
+      >
+        <UserManagementPanel />
+      </PermissionEnforcer>
+    </div>
+  );
+}
+```
+
+### PagePermissionGuard
+
+Conditionally render children based on page-level permissions.
+
+```typescript
+interface PagePermissionGuardProps {
+  pageName: string;
+  operation: 'read' | 'write' | 'delete' | 'manage';
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+  strictMode?: boolean;
+  auditLog?: boolean;
+  pageId?: UUID;
+  scope?: Scope;
+  onDenied?: (pageName: string, operation: string, reason: string) => void;
+  loading?: React.ReactNode;
+}
+```
+
+#### Usage
+
+```tsx
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function AdminPage() {
+  return (
+    <div>
+      <PagePermissionGuard
+        pageName="admin"
+        operation="read"
+        fallback={<div>Admin access required</div>}
+      >
+        <AdminSettings />
+      </PagePermissionGuard>
+    </div>
+  );
+}
+```
+
+### NavigationGuard
+
+Conditionally render navigation items based on permissions.
+
+```typescript
+interface NavigationGuardProps {
+  navigationItem: NavigationItem;
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+  strictMode?: boolean;
+  auditLog?: boolean;
+  scope?: Scope;
+  onDenied?: (navigationItem: NavigationItem, reason: string) => void;
+  loading?: React.ReactNode;
+  requireAll?: boolean;
+}
+```
+
+#### Usage
+
+```tsx
+import { NavigationGuard } from '@jmruthers/pace-core/rbac';
+
+function NavigationItem({ item }) {
+  return (
+    <NavigationGuard
+      navigationItem={item}
+      fallback={<span className="disabled">{item.name}</span>}
+    >
+      <Link to={item.path}>{item.name}</Link>
+    </NavigationGuard>
+  );
+}
+```
+
+## Database Functions
+
+The RBAC system provides dedicated database functions for managing user roles. These functions offer centralized business logic, consistent validation, and proper audit trails.
+
+### Organisation Role Management
+
+#### grant_organisation_role()
+
+Grants an organisation role to a user. If the user already has a different role in the same organisation, it will revoke the old role and grant the new one.
+
+**Signature:**
+```sql
+grant_organisation_role(
+    p_user_id UUID,
+    p_organisation_id UUID,
+    p_role TEXT,
+    p_granted_by UUID DEFAULT auth.uid(),
+    p_notes TEXT DEFAULT NULL
+) RETURNS UUID
+```
+
+**Parameters:**
+- `p_user_id`: The user to grant the role to
+- `p_organisation_id`: The organisation context
+- `p_role`: Role to grant ('supporter', 'member', 'leader', 'org_admin')
+- `p_granted_by`: User granting the role (defaults to current user)
+- `p_notes`: Optional notes about the role grant
+
+**Returns:** UUID of the created role record
+
+**Example:**
+```sql
+-- Grant org_admin role to user
+SELECT grant_organisation_role(
+    'user-123'::UUID,
+    'org-456'::UUID,
+    'org_admin',
+    'admin-user-789'::UUID,
+    'Promoted to organisation administrator'
+);
+```
+
+#### revoke_organisation_role()
+
+Revokes an organisation role from a user and removes them from the organisation if they have no other roles.
+
+**Signature:**
+```sql
+revoke_organisation_role(
+    p_user_id UUID,
+    p_organisation_id UUID,
+    p_revoked_by UUID DEFAULT auth.uid(),
+    p_notes TEXT DEFAULT NULL
+) RETURNS BOOLEAN
+```
+
+**Parameters:**
+- `p_user_id`: The user to revoke the role from
+- `p_organisation_id`: The organisation context
+- `p_revoked_by`: User revoking the role (defaults to current user)
+- `p_notes`: Optional notes about the role revocation
+
+**Returns:** TRUE if successful, FALSE otherwise
+
+**Example:**
+```sql
+-- Revoke role from user
+SELECT revoke_organisation_role(
+    'user-123'::UUID,
+    'org-456'::UUID,
+    'admin-user-789'::UUID,
+    'Role revoked due to policy violation'
+);
+```
+
+### Global Role Management
+
+#### grant_global_role()
+
+Grants a global role to a user (e.g., super_admin).
+
+**Signature:**
+```sql
+grant_global_role(
+    p_user_id UUID,
+    p_role TEXT,
+    p_granted_by UUID DEFAULT auth.uid(),
+    p_notes TEXT DEFAULT NULL
+) RETURNS UUID
+```
+
+**Parameters:**
+- `p_user_id`: The user to grant the role to
+- `p_role`: Global role to grant ('super_admin')
+- `p_granted_by`: User granting the role (defaults to current user)
+- `p_notes`: Optional notes about the role grant
+
+**Returns:** UUID of the created role record
+
+**Example:**
+```sql
+-- Grant super_admin role
+SELECT grant_global_role(
+    'user-123'::UUID,
+    'super_admin',
+    'admin-user-789'::UUID,
+    'Promoted to system administrator'
+);
+```
+
+#### revoke_global_role()
+
+Revokes a global role from a user.
+
+**Signature:**
+```sql
+revoke_global_role(
+    p_user_id UUID,
+    p_role TEXT,
+    p_revoked_by UUID DEFAULT auth.uid(),
+    p_notes TEXT DEFAULT NULL
+) RETURNS BOOLEAN
+```
+
+**Example:**
+```sql
+-- Revoke super_admin role
+SELECT revoke_global_role(
+    'user-123'::UUID,
+    'super_admin',
+    'admin-user-789'::UUID,
+    'Demoted from system administrator'
+);
+```
+
+### Event-App Role Management
+
+#### grant_event_app_role()
+
+Grants an event-app specific role to a user.
+
+**Signature:**
+```sql
+grant_event_app_role(
+    p_user_id UUID,
+    p_event_id UUID,
+    p_app_id UUID,
+    p_role TEXT,
+    p_granted_by UUID DEFAULT auth.uid(),
+    p_notes TEXT DEFAULT NULL
+) RETURNS UUID
+```
+
+**Parameters:**
+- `p_user_id`: The user to grant the role to
+- `p_event_id`: The event context
+- `p_app_id`: The application context
+- `p_role`: Event-app role ('viewer', 'participant', 'planner', 'event_admin')
+- `p_granted_by`: User granting the role (defaults to current user)
+- `p_notes`: Optional notes about the role grant
+
+**Example:**
+```sql
+-- Grant event_admin role for specific event and app
+SELECT grant_event_app_role(
+    'user-123'::UUID,
+    'event-789'::UUID,
+    'app-101'::UUID,
+    'event_admin',
+    'admin-user-789'::UUID,
+    'Assigned as event administrator'
+);
+```
+
+#### revoke_event_app_role()
+
+Revokes an event-app specific role from a user.
+
+**Signature:**
+```sql
+revoke_event_app_role(
+    p_user_id UUID,
+    p_event_id UUID,
+    p_app_id UUID,
+    p_revoked_by UUID DEFAULT auth.uid(),
+    p_notes TEXT DEFAULT NULL
+) RETURNS BOOLEAN
+```
+
+**Example:**
+```sql
+-- Revoke event-app role
+SELECT revoke_event_app_role(
+    'user-123'::UUID,
+    'event-789'::UUID,
+    'app-101'::UUID,
+    'admin-user-789'::UUID,
+    'Event access revoked'
+);
+```
+
+### Role Query Functions
+
+#### get_user_roles()
+
+Retrieves all roles for a specific user across all contexts.
+
+**Signature:**
+```sql
+get_user_roles(p_user_id UUID) RETURNS TABLE(
+    role_type TEXT,
+    role_name TEXT,
+    organisation_id UUID,
+    event_id UUID,
+    app_id UUID,
+    granted_at TIMESTAMPTZ,
+    granted_by UUID,
+    notes TEXT
+)
+```
+
+**Example:**
+```sql
+-- Get all roles for a user
+SELECT * FROM get_user_roles('user-123'::UUID);
+```
+
+**Sample Output:**
+```
+role_type    | role_name  | organisation_id | event_id | app_id | granted_at           | granted_by | notes
+-------------|------------|-----------------|----------|--------|---------------------|------------|-------
+organisation | org_admin  | org-456         | NULL     | NULL   | 2024-01-15 10:30:00 | admin-789  | Promoted
+global       | super_admin| NULL            | NULL     | NULL   | 2024-01-10 09:15:00 | super-001  | System admin
+event_app    | event_admin| NULL            | event-789| app-101| 2024-01-20 14:45:00 | admin-789  | Event admin
+```
+
+### Usage in Applications
+
+These database functions can be called from your application code using the Supabase client:
+
+```typescript
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(url, key);
+
+// Grant organisation role
+const { data: roleId } = await supabase.rpc('grant_organisation_role', {
+  p_user_id: 'user-123',
+  p_organisation_id: 'org-456',
+  p_role: 'org_admin',
+  p_notes: 'Promoted to administrator'
+});
+
+// Get user roles
+const { data: roles } = await supabase.rpc('get_user_roles', {
+  p_user_id: 'user-123'
+});
+
+// Revoke role
+const { data: success } = await supabase.rpc('revoke_organisation_role', {
+  p_user_id: 'user-123',
+  p_organisation_id: 'org-456',
+  p_notes: 'Role revoked'
+});
+```
+
+## Core Functions
+
+### isPermitted
+
+Check if a user has a specific permission (server-side).
+
+```typescript
+function isPermitted(check: PermissionCheck): Promise<boolean>;
+```
+
+#### Usage
+
+```tsx
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+
+// Server-side permission check
+export async function POST(request: Request) {
+  const { userId, organisationId, permission } = await request.json();
+  
+  const allowed = await isPermitted({
+    userId,
+    scope: { organisationId },
+    permission
+  });
+  
+  if (!allowed) {
+    return Response.json({ error: 'Insufficient permissions' }, { status: 403 });
+  }
+  
+  // Proceed with operation
+}
+```
+
+### getAccessLevel
+
+Get the user's access level in a specific scope.
+
+```typescript
+function getAccessLevel(params: {
+  userId: UUID;
+  scope: Scope;
+}): Promise<AccessLevel | null>;
+```
+
+#### Usage
+
+```tsx
+import { getAccessLevel } from '@jmruthers/pace-core/rbac';
+
+// Get user's access level
+const accessLevel = await getAccessLevel({
+  userId: 'user-123',
+  scope: { organisationId: 'org-456' }
+});
+
+console.log('User access level:', accessLevel); // 'admin', 'planner', etc.
+```
+
+### getPermissionMap
+
+Get all permissions for a user in a specific scope.
+
+```typescript
+function getPermissionMap(params: {
+  userId: UUID;
+  scope: Scope;
+}): Promise<PermissionMap>;
+```
+
+#### Usage
+
+```tsx
+import { getPermissionMap } from '@jmruthers/pace-core/rbac';
+
+// Get all user permissions
+const permissions = await getPermissionMap({
+  userId: 'user-123',
+  scope: { organisationId: 'org-456' }
+});
+
+console.log('User permissions:', permissions);
+// { 'users': ['read', 'create'], 'events': ['read'] }
+```
+
+### getAppConfig
+
+Get app configuration including context requirements.
+
+```typescript
+function getAppConfig(appId: UUID): Promise<{ requires_event: boolean } | null>;
+```
+
+#### Usage
+
+```tsx
+import { getAppConfig } from '@jmruthers/pace-core/rbac';
+
+// Check app configuration
+const appConfig = await getAppConfig('app-123');
+
+if (appConfig?.requires_event) {
+  console.log('This is an event-based app');
+  // Require eventId in scope
+} else {
+  console.log('This is an organisation-based app');
+  // Require organisationId in scope
+}
+```
+
+#### Return Values
+
+- `{ requires_event: true }` - Event-based app requiring event context
+- `{ requires_event: false }` - Organisation-based app requiring organisation context
+- `null` - App not found or inactive
+
+## Secure Client
+
+### SecureSupabaseClient
+
+Secure Supabase client with organisation context enforcement.
+
+```typescript
+class SecureSupabaseClient {
+  constructor(
+    supabaseUrl: string,
+    supabaseKey: string,
+    organisationId: UUID,
+    eventId?: string,
+    appId?: UUID
+  );
+}
+```
+
+#### Usage
+
+```tsx
+import { createSecureClient } from '@jmruthers/pace-core/rbac';
+
+// Create secure client
+const secureClient = createSecureClient(
+  'https://your-project.supabase.co',
+  'your-anon-key',
+  'org-456',
+  'event-789',
+  'app-101'
+);
+
+// All queries automatically include organisation context
+const { data, error } = await secureClient
+  .from('users')
+  .select('*')
+  .eq('organisation_id', 'org-456'); // Automatically added
+```
+
+### createSecureClient
+
+Factory function to create a secure client.
+
+```typescript
+function createSecureClient(
+  supabaseUrl: string,
+  supabaseKey: string,
+  organisationId: UUID,
+  eventId?: string,
+  appId?: UUID
+): SecureSupabaseClient;
+```
+
+## Cache Management
+
+### RBACCache
+
+In-memory cache for RBAC operations.
+
+```typescript
+class RBACCache {
+  get<T>(key: string): T | null;
+  set<T>(key: string, data: T, ttl?: number): void;
+  delete(key: string): void;
+  clear(): void;
+  invalidate(pattern: string): void;
+}
+```
+
+#### Usage
+
+```tsx
+import { rbacCache } from '@jmruthers/pace-core/rbac';
+
+// Cache a permission result
+rbacCache.set('user-123:org-456:read:users', true, 60000); // 60 seconds
+
+// Get cached result
+const cached = rbacCache.get<boolean>('user-123:org-456:read:users');
+
+// Invalidate cache
+rbacCache.invalidate('user-123:*'); // Invalidate all permissions for user
+```
+
+## Audit System
+
+### emitAuditEvent
+
+Emit an audit event for permission checks.
+
+```typescript
+function emitAuditEvent(event: RBACAuditEvent): Promise<void>;
+```
+
+#### Usage
+
+```tsx
+import { emitAuditEvent } from '@jmruthers/pace-core/rbac';
+
+// Emit permission check event
+await emitAuditEvent({
+  type: 'permission_check',
+  userId: 'user-123',
+  organisationId: 'org-456',
+  permission: 'read:users',
+  decision: true,
+  source: 'compute',
+  duration_ms: 45
+});
+```
+
+### createAuditManager
+
+Create an audit manager instance.
+
+```typescript
+function createAuditManager(supabaseClient: SupabaseClient): RBACAuditManager;
+```
+
+#### Usage
+
+```tsx
+import { createAuditManager } from '@jmruthers/pace-core/rbac';
+
+const auditManager = createAuditManager(supabaseClient);
+
+// Set as global audit manager
+setGlobalAuditManager(auditManager);
+```
+
+## Types
+
+### Core Types
+
+```typescript
+type UUID = string;
+type Operation = 'read' | 'create' | 'update' | 'delete' | 'manage';
+type Permission = `${Operation}:${string}`;
+type AccessLevel = 'viewer' | 'participant' | 'planner' | 'admin' | 'super';
+
+interface Scope {
+  organisationId?: UUID;
+  eventId?: string;
+  appId?: UUID;
+}
+
+interface PermissionCheck {
+  userId: UUID;
+  scope: Scope;
+  permission: Permission;
+  pageId?: UUID;
+}
+
+type PermissionMap = Record<string, Operation[]>;
+```
+
+### Role Types
+
+```typescript
+type GlobalRole = 'super_admin';
+type OrganisationRole = 'supporter' | 'member' | 'leader' | 'org_admin';
+type EventAppRole = 'viewer' | 'participant' | 'planner' | 'event_admin';
+```
+
+### Audit Types
+
+```typescript
+interface RBACAuditEvent {
+  id: UUID;
+  user_id: UUID;
+  event_type: 'permission_check' | 'permission_denied' | 'role_granted' | 'role_revoked' | 'rls_denied';
+  event_data: {
+    permission?: string;
+    scope?: Scope;
+    result?: boolean;
+    bypass?: boolean;
+    source?: 'cache' | 'compute';
+    duration_ms?: number;
+  };
+  created_at: string;
+}
+```
+
+## Error Handling
+
+### RBACError
+
+Base error class for RBAC operations.
+
+```typescript
+class RBACError extends Error {
+  constructor(message: string, code?: string);
+}
+```
+
+### PermissionDeniedError
+
+Error thrown when permission is denied.
+
+```typescript
+class PermissionDeniedError extends RBACError {
+  constructor(permission: string, scope: Scope);
+}
+```
+
+### OrganisationContextRequiredError
+
+Error thrown when organisation context is missing.
+
+```typescript
+class OrganisationContextRequiredError extends RBACError {
+  constructor();
+}
+```
+
+#### Usage
+
+```tsx
+import { 
+  PermissionDeniedError, 
+  OrganisationContextRequiredError 
+} from '@jmruthers/pace-core/rbac';
+
+try {
+  const allowed = await hasPermission('read:users', { userId, scope });
+} catch (error) {
+  if (error instanceof PermissionDeniedError) {
+    console.log('Permission denied:', error.permission);
+  } else if (error instanceof OrganisationContextRequiredError) {
+    console.log('Organisation context required');
+  }
+}
+```
+
+## Performance Optimization
+
+### Caching
+
+The RBAC system includes intelligent caching:
+
+- **TTL**: 60 seconds by default
+- **Key Format**: `{userId}:{organisationId}:{eventId}:{appId}:{permission}`
+- **Invalidation**: Automatic on permission changes
+- **Memory Management**: LRU eviction when cache is full
+
+### Batch Operations
+
+Use `useMultiplePermissions` for checking multiple permissions efficiently:
+
+```tsx
+// Efficient batch permission check
+const results = await checkMultiple([
+  { userId, scope, permission: 'read:users' },
+  { userId, scope, permission: 'create:users' },
+  { userId, scope, permission: 'update:users' },
+  { userId, scope, permission: 'delete:users' }
+]);
+```
+
+### Lazy Loading
+
+Permissions are loaded on-demand:
+
+```tsx
+// Only loads when component mounts
+const { hasPermission } = useCan();
+
+// Only loads when permission is checked
+const canEdit = await hasPermission('update:users', { userId, scope });
+```
+
+## Best Practices
+
+### 1. Use Permission Guards
+
+```tsx
+// ✅ Good - Use PermissionGuard for UI
+<PermissionGuard userId={userId} scope={scope} permission="read:users">
+  <UserList />
+</PermissionGuard>
+
+// ❌ Avoid - Manual permission checking in render
+{hasPermission('read:users') && <UserList />}
+```
+
+### 2. Handle Loading States
+
+```tsx
+// ✅ Good - Handle loading states
+const { hasPermission, isLoading } = useCan();
+
+if (isLoading) return <LoadingSpinner />;
+if (error) return <ErrorMessage error={error} />;
+
+// ❌ Avoid - Not handling loading states
+const canEdit = await hasPermission('update:users', { userId, scope });
+```
+
+### 3. Use Appropriate Fallbacks
+
+```tsx
+// ✅ Good - Meaningful fallback
+<PermissionGuard
+  userId={userId}
+  scope={scope}
+  permission="create:users"
+  fallback={<div>Contact admin for user creation access</div>}
+>
+  <CreateUserButton />
+</PermissionGuard>
+
+// ❌ Avoid - No fallback or generic message
+<PermissionGuard userId={userId} scope={scope} permission="create:users">
+  <CreateUserButton />
+</PermissionGuard>
+```
+
+### 4. Server-Side Validation
+
+```tsx
+// ✅ Good - Always validate server-side
+export async function POST(request: Request) {
+  const allowed = await isPermitted({
+    userId: getUserIdFromRequest(request),
+    scope: { organisationId: getOrgFromRequest(request) },
+    permission: 'create:users'
+  });
+  
+  if (!allowed) {
+    return Response.json({ error: 'Insufficient permissions' }, { status: 403 });
+  }
+  
+  // Proceed with operation
+}
+```
+
+For more examples and advanced usage patterns, see the [Examples Guide](./examples.md) and [Advanced Patterns](./advanced-patterns.md).