@jmruthers/pace-core 0.5.135 → 0.5.137

package/examples/features/rbac/CompleteRBACExample.tsx

@@ -0,0 +1,324 @@
+/**
+ * @file Complete RBAC Example
+ * @package @jmruthers/pace-core
+ * @module Examples/RBAC/CompleteRBACExample
+ * @since 2.0.0
+ *
+ * A comprehensive example showing how to use the new centralized RBAC system
+ * with all Phase 1 and Phase 2 components.
+ *
+ * This example demonstrates:
+ * - Page-level permission enforcement
+ * - Data access control
+ * - Permission enforcement
+ * - Role-based routing
+ * - Navigation control
+ * - Strict mode enforcement
+ * - Audit logging
+ */
+
+import React from 'react';
+import { BrowserRouter as Router, Routes, Route, Navigate } from 'react-router-dom';
+import { 
+  PagePermissionProvider,
+  PagePermissionGuard,
+  SecureDataProvider,
+  PermissionEnforcer,
+  RoleBasedRouter,
+  NavigationProvider,
+  NavigationGuard,
+  EnhancedNavigationMenu,
+  type NavigationItem,
+  type RouteConfig
+} from '../../src/rbac/components';
+
+// Example navigation items
+const navigationItems: NavigationItem[] = [
+  {
+    id: 'dashboard',
+    label: 'Dashboard',
+    path: '/dashboard',
+    permissions: ['read:page.dashboard'],
+    meta: { icon: '🏠', description: 'Main dashboard' }
+  },
+  {
+    id: 'events',
+    label: 'Events',
+    path: '/events',
+    permissions: ['read:page.events'],
+    meta: { icon: '📅', description: 'Event management' }
+  },
+  {
+    id: 'admin',
+    label: 'Admin',
+    path: '/admin',
+    permissions: ['read:page.admin', 'create:page.admin', 'update:page.admin', 'delete:page.admin'],
+    roles: ['admin'],
+    accessLevel: 'admin',
+    meta: { icon: '⚙️', description: 'Administration' }
+  },
+  {
+    id: 'settings',
+    label: 'Settings',
+    path: '/settings',
+    permissions: ['update:page.settings'],
+    meta: { icon: '🔧', description: 'Application settings' }
+  }
+];
+
+// Example route configuration
+const routeConfig: RouteConfig[] = [
+  {
+    path: '/dashboard',
+    component: DashboardPage,
+    permissions: ['read:page.dashboard'],
+    meta: { title: 'Dashboard', requiresAuth: true }
+  },
+  {
+    path: '/events',
+    component: EventsPage,
+    permissions: ['read:page.events'],
+    meta: { title: 'Events', requiresAuth: true }
+  },
+  {
+    path: '/admin',
+    component: AdminPage,
+    permissions: ['read:page.admin', 'create:page.admin', 'update:page.admin', 'delete:page.admin'],
+    roles: ['admin'],
+    accessLevel: 'admin',
+    strictMode: true,
+    meta: { title: 'Admin', requiresAuth: true, hidden: true }
+  },
+  {
+    path: '/settings',
+    component: SettingsPage,
+    permissions: ['update:page.settings'],
+    meta: { title: 'Settings', requiresAuth: true }
+  }
+];
+
+// Example page components
+function DashboardPage() {
+  return (
+    <PagePermissionGuard
+      pageName="dashboard"
+      operation="read"
+      fallback={<AccessDeniedPage />}
+    >
+      <div className="p-6">
+        <h1 className="text-2xl font-bold mb-4">Dashboard</h1>
+        <p>Welcome to your dashboard!</p>
+        
+        {/* Example of permission enforcement within a page */}
+        <PermissionEnforcer
+          permissions={['read:data.events']}
+          operation="view-events"
+          fallback={<div>You don't have permission to view events</div>}
+        >
+          <EventsList />
+        </PermissionEnforcer>
+      </div>
+    </PagePermissionGuard>
+  );
+}
+
+function EventsPage() {
+  return (
+    <PagePermissionGuard
+      pageName="events"
+      operation="read"
+      fallback={<AccessDeniedPage />}
+    >
+      <div className="p-6">
+        <h1 className="text-2xl font-bold mb-4">Events</h1>
+        <EventsList />
+      </div>
+    </PagePermissionGuard>
+  );
+}
+
+function AdminPage() {
+  return (
+    <PagePermissionGuard
+      pageName="admin"
+      operation="read"
+      strictMode={true}
+      fallback={<AccessDeniedPage />}
+    >
+      <div className="p-6">
+        <h1 className="text-2xl font-bold mb-4">Admin Panel</h1>
+        <p>Administrative functions</p>
+        
+        {/* Example of multiple permission enforcement */}
+        <PermissionEnforcer
+          permissions={['read:data.users', 'create:data.users', 'update:data.users', 'delete:data.users', 'read:data.organisations', 'create:data.organisations', 'update:data.organisations', 'delete:data.organisations']}
+          operation="user-management"
+          requireAll={true}
+          fallback={<div>You need both user and organisation management permissions</div>}
+        >
+          <UserManagementPanel />
+        </PermissionEnforcer>
+      </div>
+    </PagePermissionGuard>
+  );
+}
+
+function SettingsPage() {
+  return (
+    <PagePermissionGuard
+      pageName="settings"
+      operation="read"
+      fallback={<AccessDeniedPage />}
+    >
+      <div className="p-6">
+        <h1 className="text-2xl font-bold mb-4">Settings</h1>
+        <p>Application settings</p>
+      </div>
+    </PagePermissionGuard>
+  );
+}
+
+function EventsList() {
+  return (
+    <div className="bg-main-50 p-4 rounded-lg shadow">
+      <h2 className="text-lg font-semibold mb-2">Events</h2>
+      <p>List of events would go here...</p>
+    </div>
+  );
+}
+
+function UserManagementPanel() {
+  return (
+    <div className="bg-main-50 p-4 rounded-lg shadow">
+      <h2 className="text-lg font-semibold mb-2">User Management</h2>
+      <p>User management functions would go here...</p>
+    </div>
+  );
+}
+
+function AccessDeniedPage() {
+  return (
+    <div className="flex flex-col items-center justify-center min-h-screen p-8 text-center">
+      <div className="mb-4">
+        <svg className="w-16 h-16 text-acc-500 mx-auto" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L3.732 16.5c-.77.833.192 2.5 1.732 2.5z" />
+        </svg>
+      </div>
+      <h2 className="text-xl font-semibold text-sec-900 mb-2">Access Denied</h2>
+      <p className="text-sec-600 mb-4">You don't have permission to access this page.</p>
+      <button 
+        onClick={() => window.history.back()}
+        className="px-4 py-2 bg-main-600 text-main-50 rounded-md hover:bg-main-700 transition-colors"
+      >
+        Go Back
+      </button>
+    </div>
+  );
+}
+
+function AppLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen bg-sec-50">
+      <header className="bg-main-50 shadow-sm border-b">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="flex justify-between items-center h-16">
+            <div className="flex items-center">
+              <h1 className="text-xl font-semibold">PACE Core RBAC Example</h1>
+            </div>
+            
+            {/* Enhanced Navigation Menu */}
+            <EnhancedNavigationMenu
+              items={navigationItems}
+              strictMode={true}
+              auditLog={true}
+              className="flex space-x-4"
+              itemClassName="px-3 py-2 rounded-md text-sm font-medium transition-colors hover:bg-sec-100"
+              activeItemClassName="bg-main-100 text-main-700"
+              onNavigationAccess={(item, allowed) => {
+                console.log(`Navigation access: ${item.id} - ${allowed ? 'allowed' : 'denied'}`);
+              }}
+            />
+          </div>
+        </div>
+      </header>
+      
+      <main className="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
+        {children}
+      </main>
+    </div>
+  );
+}
+
+/**
+ * Complete RBAC Example Application
+ * 
+ * This example shows how to use all the new RBAC components together
+ * to create a secure, centralized permission system.
+ */
+export function CompleteRBACExample() {
+  return (
+    <Router>
+      {/* Phase 1: Core Security Enforcement */}
+      <PagePermissionProvider
+        strictMode={true}
+        auditLog={true}
+        onPageAccess={(pageName, operation, allowed) => {
+          console.log(`Page access: ${pageName} ${operation} - ${allowed ? 'allowed' : 'denied'}`);
+        }}
+        onStrictModeViolation={(pageName, operation) => {
+          console.error(`Strict mode violation: ${pageName} ${operation}`);
+        }}
+      >
+        <SecureDataProvider
+          strictMode={true}
+          auditLog={true}
+          onDataAccess={(table, operation, allowed) => {
+            console.log(`Data access: ${table} ${operation} - ${allowed ? 'allowed' : 'denied'}`);
+          }}
+          onStrictModeViolation={(table, operation) => {
+            console.error(`Data access violation: ${table} ${operation}`);
+          }}
+        >
+          {/* Phase 2: Routing and Navigation */}
+          <NavigationProvider
+            strictMode={true}
+            auditLog={true}
+            onNavigationAccess={(item, allowed) => {
+              console.log(`Navigation access: ${item.id} - ${allowed ? 'allowed' : 'denied'}`);
+            }}
+            onStrictModeViolation={(item) => {
+              console.error(`Navigation violation: ${item.id}`);
+            }}
+          >
+            <RoleBasedRouter
+              routes={routeConfig}
+              fallbackRoute="/unauthorized"
+              strictMode={true}
+              auditLog={true}
+              onRouteAccess={(route, allowed) => {
+                console.log(`Route access: ${route} - ${allowed ? 'allowed' : 'denied'}`);
+              }}
+              onStrictModeViolation={(route) => {
+                console.error(`Route violation: ${route}`);
+              }}
+            >
+              <AppLayout>
+                <Routes>
+                  <Route path="/" element={<Navigate to="/dashboard" replace />} />
+                  <Route path="/dashboard" element={<DashboardPage />} />
+                  <Route path="/events" element={<EventsPage />} />
+                  <Route path="/admin" element={<AdminPage />} />
+                  <Route path="/settings" element={<SettingsPage />} />
+                  <Route path="/unauthorized" element={<AccessDeniedPage />} />
+                </Routes>
+              </AppLayout>
+            </RoleBasedRouter>
+          </NavigationProvider>
+        </SecureDataProvider>
+      </PagePermissionProvider>
+    </Router>
+  );
+}
+
+export default CompleteRBACExample;
+

package/examples/features/rbac/EventBasedApp.tsx

@@ -0,0 +1,239 @@
+/**
+ * Event-Based App Example
+ * @package @jmruthers/pace-core
+ * @module Examples/RBAC/EventBasedApp
+ * @since 1.0.0
+ * 
+ * This example demonstrates how to build an event-based app using the RBAC system.
+ */
+
+import React from 'react';
+import { 
+  PermissionEnforcer, 
+  PagePermissionGuard, 
+  NavigationGuard,
+  useCan 
+} from '../../src/rbac';
+import { useUnifiedAuth } from '../../src/providers';
+import type { Permission } from '../../src/rbac/types';
+
+// Example navigation items for an event-based app
+const navigationItems = [
+  {
+    id: 'dashboard',
+    name: 'Dashboard',
+    label: 'Dashboard',
+    path: '/event/dashboard',
+    permissions: ['read:events'] as Permission[],
+  },
+  {
+    id: 'participants',
+    name: 'Participants',
+    label: 'Participants',
+    path: '/event/participants',
+    permissions: ['read:participants'] as Permission[],
+  },
+  {
+    id: 'settings',
+    name: 'Settings',
+    label: 'Settings',
+    path: '/event/settings',
+    permissions: ['read:events', 'create:events', 'update:events', 'delete:events'] as Permission[],
+  },
+];
+
+// Example event dashboard component
+function EventDashboard() {
+  const { user, selectedEventId } = useUnifiedAuth();
+  
+  return (
+    <div className="event-dashboard">
+      <h1>Event Dashboard</h1>
+      <p>Event ID: {selectedEventId}</p>
+      
+      {/* Example of using useCan hook with event context */}
+      <PermissionEnforcer
+        permissions={['read:events']}
+        operation="dashboard"
+      >
+        <div className="dashboard-content">
+          <h2>Event Overview</h2>
+          <p>Welcome to the event dashboard!</p>
+        </div>
+      </PermissionEnforcer>
+      
+      {/* Example of conditional rendering based on permissions */}
+      <PermissionEnforcer
+        permissions={['read:events', 'create:events', 'update:events', 'delete:events']}
+        operation="event-management"
+      >
+        <div className="admin-controls">
+          <h3>Admin Controls</h3>
+          <button>Edit Event</button>
+          <button>Delete Event</button>
+        </div>
+      </PermissionEnforcer>
+    </div>
+  );
+}
+
+// Example participants page component
+function ParticipantsPage() {
+  return (
+    <PagePermissionGuard
+      pageName="participants"
+      operation="read"
+    >
+      <div className="participants-page">
+        <h1>Participants</h1>
+        <p>Manage event participants here.</p>
+        
+        <PermissionEnforcer
+          permissions={['create:participants']}
+          operation="add-participant"
+        >
+          <button>Add Participant</button>
+        </PermissionEnforcer>
+        
+        <PermissionEnforcer
+          permissions={['delete:participants']}
+          operation="remove-participant"
+        >
+          <button>Remove Participant</button>
+        </PermissionEnforcer>
+      </div>
+    </PagePermissionGuard>
+  );
+}
+
+// Example settings page component
+function SettingsPage() {
+  return (
+    <PagePermissionGuard
+      pageName="settings"
+      operation="read"
+    >
+      <div className="settings-page">
+        <h1>Event Settings</h1>
+        <p>Configure event settings here.</p>
+        
+        <PermissionEnforcer
+          permissions={['update:events']}
+          operation="update-settings"
+        >
+          <form>
+            <label>
+              Event Name:
+              <input type="text" />
+            </label>
+            <button type="submit">Save Changes</button>
+          </form>
+        </PermissionEnforcer>
+      </div>
+    </PagePermissionGuard>
+  );
+}
+
+// Example navigation component
+function EventNavigation() {
+  return (
+    <nav className="event-navigation">
+      <ul>
+        {navigationItems.map(item => (
+          <li key={item.id}>
+            <NavigationGuard
+              navigationItem={item}
+              fallback={<span className="disabled">{item.name}</span>}
+            >
+              <a href={item.path}>{item.name}</a>
+            </NavigationGuard>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}
+
+// Example main app component
+export function EventBasedApp() {
+  const { selectedEventId, user } = useUnifiedAuth();
+  
+  // Show loading state if no event is selected
+  if (!selectedEventId) {
+    return (
+      <div className="event-app">
+        <h1>Event-Based App</h1>
+        <p>Please select an event to continue.</p>
+      </div>
+    );
+  }
+  
+  // Show loading state if no user is authenticated
+  if (!user) {
+    return (
+      <div className="event-app">
+        <h1>Event-Based App</h1>
+        <p>Please log in to continue.</p>
+      </div>
+    );
+  }
+  
+  return (
+    <div className="event-app">
+      <header>
+        <h1>Event-Based App</h1>
+        <p>User: {user.email}</p>
+        <p>Event: {selectedEventId}</p>
+      </header>
+      
+      <EventNavigation />
+      
+      <main>
+        <EventDashboard />
+        <ParticipantsPage />
+        <SettingsPage />
+      </main>
+    </div>
+  );
+}
+
+// Example of using the app with different permission scenarios
+export function EventBasedAppWithCustomScope() {
+  const { user } = useUnifiedAuth();
+  
+  // Example of providing explicit scope
+  const customScope = {
+    eventId: 'event-123',
+    appId: 'app-456'
+  };
+  
+  return (
+    <div className="event-app">
+      <h1>Event-Based App with Custom Scope</h1>
+      
+      <PermissionEnforcer
+        scope={customScope}
+        permissions={['read:events']}
+        operation="custom-scope-example"
+      >
+        <div>
+          <p>This content is shown when the user has read:events permission</p>
+          <p>for event-123 in app-456.</p>
+        </div>
+      </PermissionEnforcer>
+      
+      <PermissionEnforcer
+        scope={customScope}
+        permissions={['read:events', 'create:events', 'update:events', 'delete:events']}
+        operation="admin-example"
+        fallback={<p>You don't have admin permissions for this event.</p>}
+      >
+        <div>
+          <p>This content is shown when the user has events permissions</p>
+          <p>for event-123 in app-456.</p>
+        </div>
+      </PermissionEnforcer>
+    </div>
+  );
+}
+