@jmruthers/pace-core 0.5.109 → 0.5.111

package/src/rbac/README.md

@@ -44,25 +44,15 @@ The RBAC system includes comprehensive security measures:
 ```typescript
 import { isPermitted } from '@jmruthers/pace-core/rbac';
 
-// Basic usage (backward compatible)
+// Basic usage - organisationId is required
 const hasPermission = await isPermitted({
   userId: 'user-123',
-  scope: { organisationId: 'org-456' },
-  permission: 'manage:events'
+  scope: { organisationId: 'org-456' }, // organisationId is required
+  permission: 'update:events'
 });
 
-// Enhanced usage with security context
-const hasPermissionSecure = await isPermitted({
-  userId: 'user-123',
-  scope: { organisationId: 'org-456' },
-  permission: 'manage:events'
-}, {
-  userId: 'user-123',
-  organisationId: 'org-456',
-  ipAddress: '192.168.1.1',
-  userAgent: 'Mozilla/5.0...',
-  timestamp: new Date()
-});
+// Security context is automatically created internally
+// If organisationId is missing, OrganisationContextRequiredError is thrown
 ```
 
 ### Security Context Examples
@@ -77,17 +67,16 @@ app.get('/api/users', async (req, res) => {
   const userId = req.user.id;
   const organisationId = req.user.organisationId;
   
-  // Use security context for API routes
+  // organisationId is required - if missing, OrganisationContextRequiredError is thrown
+  if (!organisationId) {
+    return res.status(400).json({ error: 'Organisation context is required' });
+  }
+  
+  // Check permission - security context is created automatically
   const hasAccess = await isPermitted({
     userId,
-    scope: { organisationId },
+    scope: { organisationId }, // Required
     permission: 'read:users'
-  }, {
-    userId,
-    organisationId,
-    ipAddress: req.ip,
-    userAgent: req.get('User-Agent'),
-    timestamp: new Date()
   });
   
   if (!hasAccess) {
@@ -111,7 +100,7 @@ function UserManagement() {
   const { hasPermission, isLoading } = useCan(
     user.id,
     { organisationId: user.organisationId },
-    'manage:users',
+    'update:users',
     true, // useCache
     {
       userId: user.id,
@@ -172,7 +161,7 @@ function AdminDashboard() {
     [
       'read:users',
       'create:events',
-      'manage:organisations',
+      'update:organisations',
       'delete:data'
     ],
     {
@@ -190,7 +179,7 @@ function AdminDashboard() {
     <div>
       {permissions['read:users'] && <UserManagement />}
       {permissions['create:events'] && <EventCreation />}
-      {permissions['manage:organisations'] && <OrganisationSettings />}
+      {permissions['update:organisations'] && <OrganisationSettings />}
     </div>
   );
 }
@@ -283,7 +272,7 @@ function UserActions() {
   return (
     <div>
       {permissions['page-1']?.includes('read') && <ReadButton />}
-      {permissions['page-1']?.includes('manage') && <ManageButton />}
+      {permissions['page-1']?.includes('update') && <UpdateButton />}
     </div>
   );
 }
@@ -308,7 +297,7 @@ function UserActions() {
       eventId: undefined,
       appId: undefined
     },
-    'manage:users',
+    'update:users',
     'page-123' // optional pageId
   );
 
@@ -447,7 +436,7 @@ import { isPermitted, getAccessLevel, getPermissionMap } from '@jmruthers/pace-c
 const canManage = await isPermitted({
   userId: 'user-123',
   scope: { organisationId: 'org-456' },
-  permission: 'manage:events',
+  permission: 'update:events',
   pageId: 'page-789'
 });
 
@@ -482,7 +471,7 @@ function MyComponent() {
   const { can, isLoading: checking } = useCan(
     'user-123',
     { organisationId: 'org-456' },
-    'manage:events'
+    'update:events'
   );
 
   const { accessLevel } = useAccessLevel(
@@ -511,7 +500,7 @@ function App() {
   return (
     <div>
       <PermissionEnforcer
-        permissions={['manage:events']}
+        permissions={['update:events']}
         operation="event-management"
         fallback={<AccessDenied />}
       >
@@ -537,7 +526,7 @@ import { withPermissionGuard, withAccessLevelGuard } from '@jmruthers/pace-core/
 
 // Express middleware
 app.get('/admin', 
-  withPermissionGuard({ permission: 'manage:admin' }, 
+  withPermissionGuard({ permission: 'update:admin' }, 
     (req, res) => {
       res.json({ message: 'Admin access granted' });
     }
@@ -566,7 +555,7 @@ Check if a user has a specific permission.
 const hasPermission = await isPermitted({
   userId: 'user-123',
   scope: { organisationId: 'org-456' },
-  permission: 'manage:events',
+  permission: 'update:events',
   pageId: 'page-789'
 });
 ```
@@ -616,7 +605,7 @@ Hook to check if user has a specific permission.
 const { can, isLoading, error, check } = useCan(
   'user-123',
   { organisationId: 'org-456' },
-  'manage:events',
+  'update:events',
   'page-789'
 );
 ```
@@ -639,14 +628,34 @@ const { accessLevel, isLoading, error, refetch } = useAccessLevel(
 Conditionally renders children based on permissions. Works for both organization-based and event-based apps.
 
 ```tsx
+// Single permission
 <PermissionEnforcer
-  permissions={['manage:events']}
+  permissions={['update:events']}
   operation="event-management"
   fallback={<AccessDenied />}
-  onDenied={() => console.log('Access denied')}
 >
   <AdminPanel />
 </PermissionEnforcer>
+
+// Multiple permissions - require ALL (default)
+<PermissionEnforcer
+  permissions={['read:events', 'update:events']}
+  operation="event-management"
+  requireAll={true}
+  fallback={<AccessDenied />}
+>
+  <EventManagementPanel />
+</PermissionEnforcer>
+
+// Multiple permissions - require ANY
+<PermissionEnforcer
+  permissions={['read:events', 'read:reports']}
+  operation="viewing"
+  requireAll={false}
+  fallback={<AccessDenied />}
+>
+  <ViewingPanel />
+</PermissionEnforcer>
 ```
 
 #### `PagePermissionGuard`
@@ -676,6 +685,39 @@ Conditionally renders navigation items based on permissions.
 </NavigationGuard>
 ```
 
+#### `RoleBasedRouter`
+
+Centralized routing with permission enforcement and public route support.
+
+```tsx
+const routes: RouteConfig[] = [
+  {
+    path: '/dashboard',
+    component: Dashboard,
+    permissions: ['read:dashboard'],
+  },
+  {
+    path: '/login',
+    component: Login,
+    public: true, // Public route - no permission checks
+  },
+  {
+    path: '/admin',
+    component: Admin,
+    permissions: ['update:admin'],
+    accessLevel: 'admin',
+  },
+];
+
+<RoleBasedRouter
+  routes={routes}
+  fallbackRoute="/unauthorized"
+  strictMode={true}
+>
+  <App />
+</RoleBasedRouter>
+```
+
 ### Server Adapters
 
 #### `withPermissionGuard(config, handler)`
@@ -684,7 +726,7 @@ Wraps a server handler with permission checking.
 
 ```typescript
 const protectedHandler = withPermissionGuard(
-  { permission: 'manage:events', pageId: 'page-789' },
+  { permission: 'update:events', pageId: 'page-789' },
   async (req, res) => {
     // Handler logic here
     res.json({ success: true });
@@ -711,12 +753,12 @@ const adminHandler = withAccessLevelGuard(
 ### Core Types
 
 ```typescript
-type Operation = 'read' | 'create' | 'update' | 'delete' | 'manage';
+type Operation = 'read' | 'create' | 'update' | 'delete';
 type Permission = `${Operation}:${string}`;
 type AccessLevel = 'viewer' | 'participant' | 'planner' | 'admin' | 'super';
 
 interface Scope {
-  organisationId?: UUID;
+  organisationId: UUID; // Required - can always be derived from event context in event-based apps
   eventId?: string;
   appId?: UUID;
 }

package/src/rbac/__tests__/adapters.comprehensive.test.tsx

@@ -686,7 +686,7 @@ describe('RBAC Adapters - Comprehensive Tests', () => {
       it('redirects to fallback URL when permission is denied', async () => {
         const middleware = createRBACMiddleware({
           protectedRoutes: [
-            { path: '/admin', permission: 'manage:admin' as Permission }
+            { path: '/admin', permission: 'update:admin' as Permission }
           ],
           fallbackUrl: '/access-denied'
         });
@@ -710,7 +710,7 @@ describe('RBAC Adapters - Comprehensive Tests', () => {
       it('calls next when permission is granted', async () => {
         const middleware = createRBACMiddleware({
           protectedRoutes: [
-            { path: '/admin', permission: 'manage:admin' as Permission }
+            { path: '/admin', permission: 'update:admin' as Permission }
           ],
           fallbackUrl: '/access-denied'
         });
@@ -734,7 +734,7 @@ describe('RBAC Adapters - Comprehensive Tests', () => {
       it('redirects to login when user context is missing', async () => {
         const middleware = createRBACMiddleware({
           protectedRoutes: [
-            { path: '/admin', permission: 'manage:admin' as Permission }
+            { path: '/admin', permission: 'update:admin' as Permission }
           ],
           fallbackUrl: '/access-denied'
         });

package/src/rbac/__tests__/engine.comprehensive.test.ts

@@ -58,9 +58,10 @@ describe('RBACEngine - Comprehensive Tests', () => {
   });
 
   // Helper function to create security context
-  const createSecurityContext = (userId: string, organisationId?: string) => ({
+  // OrganisationId is required - use mockOrgId as default
+  const createSecurityContext = (userId: string, organisationId: string = mockOrgId) => ({
     userId: userId as UUID,
-    organisationId: organisationId as UUID | undefined,
+    organisationId: organisationId as UUID,
     timestamp: new Date()
   });
 
@@ -84,7 +85,7 @@ describe('RBACEngine - Comprehensive Tests', () => {
       const permissionCheck: PermissionCheck = {
         userId: '00000000-0000-0000-0000-000000000001' as UUID,
         scope: { organisationId: '00000000-0000-0000-0000-000000000002' as UUID },
-        permission: 'manage:everything' as Permission
+        permission: 'update:everything' as Permission
       };
 
       const securityContext = createSecurityContext('00000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000002');
@@ -103,7 +104,7 @@ describe('RBACEngine - Comprehensive Tests', () => {
       const permissionCheck: PermissionCheck = {
         userId: 'regular-user-123' as UUID,
         scope: { organisationId: '00000000-0000-0000-0000-000000000002' as UUID },
-        permission: 'manage:everything' as Permission
+        permission: 'update:everything' as Permission
       };
 
       const securityContext = {
@@ -366,6 +367,8 @@ describe('RBACEngine - Comprehensive Tests', () => {
             select: vi.fn().mockReturnThis(),
             eq: vi.fn().mockReturnThis(),
             is: vi.fn().mockReturnThis(),
+            lte: vi.fn().mockReturnThis(),
+            or: vi.fn().mockReturnThis(),
             single: vi.fn().mockResolvedValue({
               data: { role: 'org_admin' },
               error: null
@@ -427,6 +430,8 @@ describe('RBACEngine - Comprehensive Tests', () => {
             select: vi.fn().mockReturnThis(),
             eq: vi.fn().mockReturnThis(),
             is: vi.fn().mockReturnThis(),
+            lte: vi.fn().mockReturnThis(),
+            or: vi.fn().mockReturnThis(),
             single: vi.fn().mockResolvedValue({
               data: null,
               error: { code: 'PGRST116' }
@@ -495,6 +500,8 @@ describe('RBACEngine - Comprehensive Tests', () => {
             select: vi.fn().mockReturnThis(),
             eq: vi.fn().mockReturnThis(),
             is: vi.fn().mockReturnThis(),
+            lte: vi.fn().mockReturnThis(),
+            or: vi.fn().mockReturnThis(),
             single: vi.fn().mockResolvedValue({
               data: null,
               error: { code: 'PGRST116' }
@@ -780,9 +787,11 @@ describe('RBACEngine - Comprehensive Tests', () => {
       };
 
       const securityContext = {
-        userId: 'user-123',
+        userId: 'user-123' as UUID,
+        organisationId: '00000000-0000-0000-0000-000000000002' as UUID, // Required
         ipAddress: '192.168.1.1',
-        userAgent: 'test-agent'
+        userAgent: 'test-agent',
+        timestamp: new Date()
       };
 
       const result = await engine.isPermitted(permissionCheck, securityContext);

package/src/rbac/__tests__/rbac-core.test.tsx

@@ -216,7 +216,7 @@ describe('RBAC Core Functionality', () => {
         'create:events',
         'update:profiles',
         'delete:comments',
-        'manage:organisations',
+        'update:organisations',
       ];
 
       validPermissions.forEach(permission => {

package/src/rbac/__tests__/rbac-engine-core-logic.test.ts

@@ -60,7 +60,7 @@ describe('RBACEngine - Core Logic Tests', () => {
       const permissionCheck: PermissionCheck = {
         userId: '00000000-0000-0000-0000-000000000001' as UUID,
         scope: { organisationId: '00000000-0000-0000-0000-000000000002' as UUID },
-        permission: 'manage:everything' as Permission
+        permission: 'update:everything' as Permission
       };
 
       const securityContext = {
@@ -131,7 +131,7 @@ describe('RBACEngine - Core Logic Tests', () => {
       const permissionCheck: PermissionCheck = {
         userId: 'user-123' as UUID,
         scope: { organisationId: 'org-123' as UUID },
-        permission: 'manage:everything' as Permission
+        permission: 'update:everything' as Permission
       };
 
       const result = await engine.isPermitted(permissionCheck);
@@ -187,6 +187,7 @@ describe('RBACEngine - Core Logic Tests', () => {
 
     it('resolves organisation admin access level', async () => {
       // Mock the from() chain to handle both global roles and organisation roles queries
+      let organisationRoleQuery: any;
       mockSupabase.from.mockImplementation((table: string) => {
         if (table === 'rbac_global_roles') {
           return {
@@ -201,15 +202,20 @@ describe('RBACEngine - Core Logic Tests', () => {
           };
         }
         if (table === 'rbac_organisation_roles') {
-          return {
+          const query = {
             select: vi.fn().mockReturnThis(),
             eq: vi.fn().mockReturnThis(),
             is: vi.fn().mockReturnThis(),
+            lte: vi.fn().mockReturnThis(),
+            or: vi.fn().mockReturnThis(),
             single: vi.fn().mockResolvedValue({
               data: { role: 'org_admin' },
               error: null
             })
           };
+
+          organisationRoleQuery = query;
+          return query;
         }
         return {
           select: vi.fn().mockReturnThis(),
@@ -222,8 +228,55 @@ describe('RBACEngine - Core Logic Tests', () => {
 
       const scope: Scope = { organisationId: 'org-123' as UUID };
       const accessLevel = await engine.getAccessLevel({ userId: 'user-123' as UUID, scope });
-      
+
       expect(accessLevel).toBe('admin');
+      expect(organisationRoleQuery.lte).toHaveBeenCalledWith('valid_from', expect.any(String));
+      expect(organisationRoleQuery.or).toHaveBeenCalledWith(expect.stringContaining('valid_to.gte.'));
+    });
+
+    it('treats expired organisation roles as viewer access', async () => {
+      let organisationRoleQuery: any;
+      mockSupabase.from.mockImplementation((table: string) => {
+        if (table === 'rbac_global_roles') {
+          return {
+            select: vi.fn().mockReturnThis(),
+            eq: vi.fn().mockReturnThis(),
+            lte: vi.fn().mockReturnThis(),
+            or: vi.fn().mockReturnThis(),
+            limit: vi.fn().mockResolvedValue({
+              data: [],
+              error: null
+            })
+          };
+        }
+        if (table === 'rbac_organisation_roles') {
+          const query = {
+            select: vi.fn().mockReturnThis(),
+            eq: vi.fn().mockReturnThis(),
+            is: vi.fn().mockReturnThis(),
+            lte: vi.fn().mockReturnThis(),
+            or: vi.fn().mockReturnThis(),
+            single: vi.fn().mockResolvedValue({ data: null, error: null })
+          };
+
+          organisationRoleQuery = query;
+          return query;
+        }
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          lte: vi.fn().mockReturnThis(),
+          or: vi.fn().mockReturnThis(),
+          limit: vi.fn().mockResolvedValue({ data: [], error: null })
+        };
+      });
+
+      const scope: Scope = { organisationId: 'org-123' as UUID };
+      const accessLevel = await engine.getAccessLevel({ userId: 'user-123' as UUID, scope });
+
+      expect(accessLevel).toBe('viewer');
+      expect(organisationRoleQuery.lte).toHaveBeenCalledWith('valid_from', expect.any(String));
+      expect(organisationRoleQuery.or).toHaveBeenCalledWith(expect.stringContaining('valid_to.gte.'));
     });
   });
 

package/src/rbac/__tests__/rbac-engine-simplified.test.ts

@@ -71,8 +71,7 @@ describe('RBACEngine - Simplified Tests', () => {
       const invalidPermissions = [
         'invalid',
         'read',
-        'manage:organisation', // manage is no longer valid
-        'manage:*',
+        // Note: manage operations have been removed
         ':users',
         'read:user-settings', // hyphens not allowed
         'read:user_settings', // underscores not allowed
@@ -175,6 +174,8 @@ describe('RBACEngine - Simplified Tests', () => {
             select: vi.fn().mockReturnThis(),
             eq: vi.fn().mockReturnThis(),
             is: vi.fn().mockReturnThis(),
+            lte: vi.fn().mockReturnThis(),
+            or: vi.fn().mockReturnThis(),
             single: vi.fn().mockResolvedValue({
               data: { role: 'org_admin' },
               error: null

package/src/rbac/adapters.tsx

@@ -30,7 +30,7 @@ import { useUnifiedAuth } from '../providers/UnifiedAuthProvider';
  * <PermissionGuard
  *   userId="user-123"
  *   scope={{ organisationId: 'org-456' }}
- *   permission="manage:events"
+ *   permission="update:events"
  *   pageId="page-789"
  *   fallback={<AccessDenied />}
  * >
@@ -39,7 +39,7 @@ import { useUnifiedAuth } from '../providers/UnifiedAuthProvider';
  * 
  * // With context inference (requires auth context)
  * <PermissionGuard
- *   permission="manage:events"
+ *   permission="update:events"
  *   scope={{ organisationId: 'org-456' }}
  *   fallback={<AccessDenied />}
  * >
@@ -279,7 +279,7 @@ export function AccessLevelGuard({
  * @example
  * ```typescript
  * const protectedHandler = withPermissionGuard(
- *   { permission: 'manage:events', pageId: 'page-789' },
+ *   { permission: 'update:events', pageId: 'page-789' },
  *   async (req, res) => {
  *     // Handler logic here
  *     res.json({ success: true });
@@ -521,7 +521,7 @@ export function withRoleGuard<T extends any[]>(
  * 
  * export default createRBACMiddleware({
  *   protectedRoutes: [
- *     { path: '/admin', permission: 'manage:admin' },
+ *     { path: '/admin', permission: 'update:admin' },
  *     { path: '/events', permission: 'read:events' },
  *   ],
  *   fallbackUrl: '/access-denied',

package/src/rbac/api.test.ts

@@ -37,11 +37,11 @@ vi.mock('./cache', () => ({
     )
   },
   CACHE_PATTERNS: {
-    PERMISSION: vi.fn((userId, organisationId) => `permission:${userId}:${organisationId}:*`),
-    USER: vi.fn((userId) => `permission:${userId}:*`),
-    ORGANISATION: vi.fn((organisationId) => `permission:*:${organisationId}:*`),
-    EVENT: vi.fn((eventId) => `permission:*:*:${eventId}:*`),
-    APP: vi.fn((appId) => `permission:*:*:*:${appId}`)
+    PERMISSION: vi.fn((userId, organisationId) => `perm:${userId}:${organisationId}:`),
+    USER: vi.fn((userId) => `:${userId}:`),
+    ORGANISATION: vi.fn((organisationId) => `:${organisationId}:`),
+    EVENT: vi.fn((eventId) => `:${eventId}:`),
+    APP: vi.fn((appId) => `:${appId}`)
   }
 }));
 
@@ -119,7 +119,7 @@ describe('RBAC API', () => {
       
       process.env.NODE_ENV = originalEnv;
 
-      expect(mockCreateRBACEngine).toHaveBeenCalledWith(mockSupabase);
+      expect(mockCreateRBACEngine).toHaveBeenCalledWith(mockSupabase, undefined);
       expect(mockCreateAuditManager).toHaveBeenCalledWith(mockSupabase);
       expect(mockSetGlobalAuditManager).toHaveBeenCalledWith(mockAuditManager);
       expect(mockLogger.info).toHaveBeenCalledWith('RBAC system initialized successfully');
@@ -203,7 +203,7 @@ describe('RBAC API', () => {
 
       setupRBAC(mockSupabase as any);
 
-      expect(mockCreateRBACEngine).toHaveBeenCalledWith(mockSupabase);
+      expect(mockCreateRBACEngine).toHaveBeenCalledWith(mockSupabase, undefined);
     });
 
     it('handles multiple initialization calls', () => {
@@ -622,6 +622,26 @@ describe('RBAC API', () => {
           permission: 'read:users'
         })).rejects.toThrow('Engine error');
       });
+
+      it('throws OrganisationContextRequiredError when organisationId is missing', async () => {
+        const { isPermitted, OrganisationContextRequiredError } = await import('./api');
+        
+        await expect(isPermitted({
+          userId: 'user-123',
+          scope: {}, // Missing organisationId
+          permission: 'read:users'
+        })).rejects.toThrow(OrganisationContextRequiredError);
+      });
+
+      it('throws OrganisationContextRequiredError when organisationId is undefined', async () => {
+        const { isPermitted, OrganisationContextRequiredError } = await import('./api');
+        
+        await expect(isPermitted({
+          userId: 'user-123',
+          scope: { organisationId: undefined },
+          permission: 'read:users'
+        })).rejects.toThrow(OrganisationContextRequiredError);
+      });
     });
 
     describe('isPermittedCached', () => {
@@ -919,28 +939,32 @@ describe('RBAC API', () => {
         debug: vi.fn()
       });
 
+      vi.mocked(rbacCache.invalidate).mockClear();
+
       setupRBAC(mockSupabase as any);
     });
 
     describe('invalidateUserCache', () => {
       it('invalidates user cache with organisation', async () => {
         const { invalidateUserCache } = await import('./api');
-        
+
         invalidateUserCache('user-123', 'org-456');
 
-        expect(rbacCache.invalidate).toHaveBeenCalledWith(
-          expect.stringContaining('user-123')
-        );
+        expect(rbacCache.invalidate).toHaveBeenCalledWith('perm:user-123:org-456:');
+        expect(rbacCache.invalidate).toHaveBeenCalledWith('access:user-123:org-456:');
+        expect(rbacCache.invalidate).toHaveBeenCalledWith('map:user-123:org-456:');
+        expect(rbacCache.invalidate).toHaveBeenCalledTimes(3);
       });
 
       it('invalidates user cache without organisation', async () => {
         const { invalidateUserCache } = await import('./api');
-        
+
         invalidateUserCache('user-123');
 
-        expect(rbacCache.invalidate).toHaveBeenCalledWith(
-          expect.stringContaining('user-123')
-        );
+        expect(rbacCache.invalidate).toHaveBeenCalledWith('perm:user-123:');
+        expect(rbacCache.invalidate).toHaveBeenCalledWith('access:user-123:');
+        expect(rbacCache.invalidate).toHaveBeenCalledWith('map:user-123:');
+        expect(rbacCache.invalidate).toHaveBeenCalledTimes(3);
       });
     });