@jmruthers/pace-core 0.2.4

package/src/rbac/adapters.tsx

@@ -0,0 +1,726 @@
+/**
+ * RBAC Adapters
+ * @package @jmruthers/pace-core
+ * @module RBAC/Adapters
+ * @since 1.0.0
+ * 
+ * This module provides adapters for different frameworks and server runtimes.
+ */
+
+import React, { ReactNode, useContext } from 'react';
+import { UUID, Permission } from './types';
+import { useCan } from './hooks';
+import { rbacCache, RBACCache } from './cache';
+import { getRBACLogger } from './config';
+
+// ============================================================================
+// REACT COMPONENTS
+// ============================================================================
+
+/**
+ * Permission Guard Component
+ * 
+ * A React component that conditionally renders children based on permissions.
+ * Can auto-infer userId from context if not provided.
+ * 
+ * @example
+ * ```tsx
+ * // With explicit userId and scope
+ * <PermissionGuard
+ *   userId="user-123"
+ *   scope={{ organisationId: 'org-456' }}
+ *   permission="manage:events"
+ *   pageId="page-789"
+ *   fallback={<AccessDenied />}
+ * >
+ *   <AdminPanel />
+ * </PermissionGuard>
+ * 
+ * // With context inference (requires auth context)
+ * <PermissionGuard
+ *   permission="manage:events"
+ *   scope={{ organisationId: 'org-456' }}
+ *   fallback={<AccessDenied />}
+ * >
+ *   <AdminPanel />
+ * </PermissionGuard>
+ * ```
+ */
+export function PermissionGuard({
+  userId,
+  scope,
+  permission,
+  pageId,
+  children,
+  fallback = null,
+  onDenied,
+  loading = null,
+  // NEW: Phase 1 - Enhanced Security Features
+  strictMode = true,
+  auditLog = true,
+  enforceAudit = true,
+}: {
+  userId?: UUID;
+  scope: { organisationId: UUID; eventId?: string; appId?: UUID };
+  permission: Permission;
+  pageId?: UUID;
+  children: ReactNode;
+  fallback?: ReactNode;
+  onDenied?: () => void;
+  loading?: ReactNode;
+  // NEW: Phase 1 - Enhanced Security Features
+  strictMode?: boolean;
+  auditLog?: boolean;
+  enforceAudit?: boolean;
+}): React.ReactNode {
+  const logger = getRBACLogger();
+  
+  // Always call hooks at the top level
+  const authContext = useContext(React.createContext<any>(null));
+  
+  // Try to get userId from context if not provided
+  let effectiveUserId = userId;
+  if (!effectiveUserId) {
+    try {
+      // Try to get from common auth contexts
+      if (authContext?.user?.id) {
+        effectiveUserId = authContext.user.id;
+      } else {
+        // Try to get from window or global context
+        const globalUser = (window as any).__PACE_USER__;
+        if (globalUser?.id) {
+          effectiveUserId = globalUser.id;
+        }
+      }
+    } catch (error) {
+      logger.debug('Could not infer userId from context:', error);
+    }
+  }
+
+  // Always call useCan hook, but handle the case where userId might be undefined
+  const { can, isLoading, error } = useCan(effectiveUserId || '', scope, permission, pageId);
+
+  // If still no userId, show helpful error
+  if (!effectiveUserId) {
+    logger.error('PermissionGuard: No userId provided and could not infer from context');
+    return (
+      <div className="rbac-error" role="alert">
+        <p>Permission check failed: User context not available</p>
+        <details>
+          <summary>Debug info</summary>
+          <p>Make sure to either:</p>
+          <ul>
+            <li>Pass userId prop explicitly</li>
+            <li>Wrap your app with an auth provider</li>
+            <li>Set window.__PACE_USER__ with user data</li>
+          </ul>
+        </details>
+      </div>
+    );
+  }
+
+  // Handle loading state
+  if (isLoading) {
+    return loading || (
+      <div className="rbac-loading" role="status" aria-live="polite">
+        <span className="sr-only">Checking permissions...</span>
+      </div>
+    );
+  }
+
+  // Handle error state
+  if (error) {
+    logger.error('Permission check failed:', error);
+    // NEW: Phase 1 - Record failed permission check for audit
+    if (auditLog) {
+      logger.info(`[PermissionGuard] Permission check failed:`, {
+        userId: effectiveUserId,
+        scope,
+        permission,
+        pageId,
+        error: error.message,
+        timestamp: new Date().toISOString()
+      });
+    }
+    return fallback;
+  }
+
+  // Handle permission denied
+  if (!can) {
+    // NEW: Phase 1 - Record denied permission check for audit
+    if (auditLog) {
+      logger.info(`[PermissionGuard] Permission denied:`, {
+        userId: effectiveUserId,
+        scope,
+        permission,
+        pageId,
+        timestamp: new Date().toISOString()
+      });
+    }
+    
+    // NEW: Phase 1 - Handle strict mode violations
+    if (strictMode) {
+      logger.error(`[PermissionGuard] STRICT MODE VIOLATION: User attempted to access protected resource without permission`, {
+        userId: effectiveUserId,
+        scope,
+        permission,
+        pageId,
+        timestamp: new Date().toISOString()
+      });
+    }
+    
+    if (onDenied) {
+      onDenied();
+    }
+    return <>{fallback}</>;
+  }
+
+  // NEW: Phase 1 - Record successful permission check for audit
+  if (auditLog) {
+    logger.info(`[PermissionGuard] Permission granted:`, {
+      userId: effectiveUserId,
+      scope,
+      permission,
+      pageId,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  // Render children if permission granted
+  return <>{children}</>;
+}
+
+/**
+ * Access Level Guard Component
+ * 
+ * A React component that conditionally renders children based on access level.
+ * Can auto-infer userId from context if not provided.
+ * 
+ * @example
+ * ```tsx
+ * // With explicit userId and scope
+ * <AccessLevelGuard
+ *   userId="user-123"
+ *   scope={{ organisationId: 'org-456' }}
+ *   minLevel="admin"
+ *   fallback={<AccessDenied />}
+ * >
+ *   <AdminPanel />
+ * </AccessLevelGuard>
+ * 
+ * // With context inference (requires auth context)
+ * <AccessLevelGuard
+ *   minLevel="admin"
+ *   scope={{ organisationId: 'org-456' }}
+ *   fallback={<AccessDenied />}
+ * >
+ *   <AdminPanel />
+ * </AccessLevelGuard>
+ * ```
+ */
+export function AccessLevelGuard({
+  userId,
+  scope,
+  minLevel,
+  children,
+  fallback = null,
+  loading = null,
+}: {
+  userId?: UUID;
+  scope: { organisationId: UUID; eventId?: string; appId?: UUID };
+  minLevel: 'viewer' | 'participant' | 'planner' | 'admin' | 'super';
+  children: ReactNode;
+  fallback?: ReactNode;
+  loading?: ReactNode;
+}): React.ReactNode {
+  const logger = getRBACLogger();
+  
+  // Always call hooks at the top level
+  const authContext = useContext(React.createContext<any>(null));
+  
+  // Try to get userId from context if not provided
+  let effectiveUserId = userId;
+  if (!effectiveUserId) {
+    try {
+      // Try to get from common auth contexts
+      if (authContext?.user?.id) {
+        effectiveUserId = authContext.user.id;
+      } else {
+        // Try to get from window or global context
+        const globalUser = (window as any).__PACE_USER__;
+        if (globalUser?.id) {
+          effectiveUserId = globalUser.id;
+        }
+      }
+    } catch (error) {
+      logger.debug('Could not infer userId from context:', error);
+    }
+  }
+
+  // Always call useAccessLevel hook, but handle the case where userId might be undefined
+  const { accessLevel, isLoading, error } = useAccessLevel(effectiveUserId || '', scope);
+
+  // If still no userId, show helpful error
+  if (!effectiveUserId) {
+    logger.error('AccessLevelGuard: No userId provided and could not infer from context');
+    return (
+      <div className="rbac-error" role="alert">
+        <p>Access level check failed: User context not available</p>
+        <details>
+          <summary>Debug info</summary>
+          <p>Make sure to either:</p>
+          <ul>
+            <li>Pass userId prop explicitly</li>
+            <li>Wrap your app with an auth provider</li>
+            <li>Set window.__PACE_USER__ with user data</li>
+          </ul>
+        </details>
+      </div>
+    );
+  }
+
+  // Handle loading state
+  if (isLoading) {
+    return loading || (
+      <div className="rbac-loading" role="status" aria-live="polite">
+        <span className="sr-only">Checking access level...</span>
+      </div>
+    );
+  }
+
+  // Handle error state
+  if (error) {
+    logger.error('Access level check failed:', error);
+    return fallback;
+  }
+
+  // Check access level
+  const levelHierarchy = ['viewer', 'participant', 'planner', 'admin', 'super'];
+  const userLevelIndex = accessLevel ? levelHierarchy.indexOf(accessLevel) : -1;
+  const requiredLevelIndex = levelHierarchy.indexOf(minLevel);
+
+  if (userLevelIndex < requiredLevelIndex) {
+    return <>{fallback}</>;
+  }
+
+  return <>{children}</>;
+}
+
+// ============================================================================
+// SERVER ADAPTERS
+// ============================================================================
+
+/**
+ * Permission Guard for Server Handlers
+ * 
+ * Wraps a server handler with permission checking.
+ * 
+ * @param config - Permission guard configuration
+ * @param handler - Handler function to wrap
+ * @returns Wrapped handler function
+ * 
+ * @example
+ * ```typescript
+ * const protectedHandler = withPermissionGuard(
+ *   { permission: 'manage:events', pageId: 'page-789' },
+ *   async (req, res) => {
+ *     // Handler logic here
+ *     res.json({ success: true });
+ *   }
+ * );
+ * ```
+ */
+export function withPermissionGuard<T extends any[]>(
+  config: {
+    permission: Permission;
+    pageId?: UUID;
+  },
+  handler: (...args: T) => Promise<any>
+) {
+  return async (...args: T): Promise<any> => {
+    // Extract user context from request
+    const [req] = args;
+    const userId = req.user?.id;
+    const organisationId = req.organisationId;
+    const eventId = req.eventId;
+    const appId = req.appId;
+
+    if (!userId || !organisationId) {
+      throw new Error('User context required for permission check');
+    }
+
+    // Check permission
+    const { isPermitted } = await import('./api');
+    const hasPermission = await isPermitted({
+      userId,
+      scope: { organisationId, eventId, appId },
+      permission: config.permission,
+      pageId: config.pageId,
+    });
+
+    if (!hasPermission) {
+      throw new Error(`Permission denied: ${config.permission}`);
+    }
+
+    // Execute handler
+    return handler(...args);
+  };
+}
+
+/**
+ * Access Level Guard for Server Handlers
+ * 
+ * Wraps a server handler with access level checking.
+ * 
+ * @param minLevel - Minimum access level required
+ * @param handler - Handler function to wrap
+ * @returns Wrapped handler function
+ * 
+ * @example
+ * ```typescript
+ * const adminHandler = withAccessLevelGuard(
+ *   'admin',
+ *   async (req, res) => {
+ *     // Admin-only logic here
+ *     res.json({ success: true });
+ *   }
+ * );
+ * ```
+ */
+export function withAccessLevelGuard<T extends any[]>(
+  minLevel: 'viewer' | 'participant' | 'planner' | 'admin' | 'super',
+  handler: (...args: T) => Promise<any>
+) {
+  return async (...args: T): Promise<any> => {
+    // Extract user context from request
+    const [req] = args;
+    const userId = req.user?.id;
+    const organisationId = req.organisationId;
+    const eventId = req.eventId;
+    const appId = req.appId;
+
+    if (!userId || !organisationId) {
+      throw new Error('User context required for access level check');
+    }
+
+    // Check access level
+    const { getAccessLevel } = await import('./api');
+    const accessLevel = await getAccessLevel({
+      userId,
+      scope: { organisationId, eventId, appId },
+    });
+
+    const levelHierarchy = ['viewer', 'participant', 'planner', 'admin', 'super'];
+    const userLevelIndex = levelHierarchy.indexOf(accessLevel);
+    const requiredLevelIndex = levelHierarchy.indexOf(minLevel);
+
+    if (userLevelIndex < requiredLevelIndex) {
+      throw new Error(`Access level required: ${minLevel}, got: ${accessLevel}`);
+    }
+
+    // Execute handler
+    return handler(...args);
+  };
+}
+
+/**
+ * Role Guard for Server Handlers
+ * 
+ * Wraps a server handler with role-based access control.
+ * This is the primary middleware for routing protection as specified in the contract.
+ * 
+ * @param config - Role guard configuration
+ * @param handler - Handler function to wrap
+ * @returns Wrapped handler function
+ * 
+ * @example
+ * ```typescript
+ * const adminHandler = withRoleGuard(
+ *   { 
+ *     globalRoles: ['super_admin'],
+ *     organisationRoles: ['org_admin', 'leader'],
+ *     eventAppRoles: ['event_admin', 'planner']
+ *   },
+ *   async (req, res) => {
+ *     // Admin-only logic here
+ *     res.json({ success: true });
+ *   }
+ * );
+ * ```
+ */
+export function withRoleGuard<T extends any[]>(
+  config: {
+    globalRoles?: string[];
+    organisationRoles?: string[];
+    eventAppRoles?: string[];
+    requireAll?: boolean;
+  },
+  handler: (...args: T) => Promise<any>
+) {
+  return async (...args: T): Promise<any> => {
+    // Extract user context from request
+    const [req] = args;
+    const userId = req.user?.id;
+    const organisationId = req.organisationId;
+    const eventId = req.eventId;
+    const appId = req.appId;
+
+    if (!userId || !organisationId) {
+      throw new Error('User context required for role check');
+    }
+
+    // Check global roles first (super_admin bypasses all)
+    if (config.globalRoles && config.globalRoles.length > 0) {
+      const { isSuperAdmin } = await import('./api');
+      const isSuper = await isSuperAdmin(userId);
+      
+      if (isSuper) {
+        // Log bypass for super admin - only if we have a valid organisation ID
+        if (organisationId) {
+          const { emitAuditEvent } = await import('./audit');
+          await emitAuditEvent({
+            type: 'permission_check',
+            userId,
+            organisationId,
+            eventId,
+            appId,
+            permission: 'bypass:all',
+            decision: true,
+            source: 'api',
+            bypass: true,
+            duration_ms: 0,
+            metadata: {
+              operation: 'role_guard',
+              reason: 'super_admin_bypass'
+            }
+          });
+        }
+        
+        return handler(...args);
+      }
+    }
+
+    // Check organisation roles
+    if (config.organisationRoles && config.organisationRoles.length > 0) {
+      const { isOrganisationAdmin } = await import('./api');
+      const isOrgAdmin = await isOrganisationAdmin(userId, organisationId);
+      
+      if (!isOrgAdmin && config.requireAll !== false) {
+        throw new Error(`Organisation admin role required`);
+      }
+    }
+
+    // Check event-app roles if event and app context provided
+    if (config.eventAppRoles && config.eventAppRoles.length > 0 && eventId && appId) {
+      const { isEventAdmin } = await import('./api');
+      const isEventAdminUser = await isEventAdmin(userId, { organisationId, eventId, appId });
+      
+      if (!isEventAdminUser && config.requireAll !== false) {
+        throw new Error(`Event admin role required`);
+      }
+    }
+
+    // Log successful role check - only if we have a valid organisation ID
+    if (organisationId) {
+      const { emitAuditEvent } = await import('./audit');
+      await emitAuditEvent({
+        type: 'permission_check',
+        userId,
+        organisationId,
+        eventId,
+        appId,
+        permission: 'role:check',
+        decision: true,
+        source: 'api',
+        bypass: false,
+        duration_ms: 0,
+        metadata: {
+          operation: 'role_guard'
+        }
+      });
+    }
+
+    // Execute handler
+    return handler(...args);
+  };
+}
+
+// ============================================================================
+// NEXT.JS MIDDLEWARE
+// ============================================================================
+
+/**
+ * Next.js Middleware for RBAC
+ * 
+ * Middleware that checks permissions before allowing access to pages.
+ * 
+ * @param config - Middleware configuration
+ * @returns Next.js middleware function
+ * 
+ * @example
+ * ```typescript
+ * // middleware.ts
+ * import { createRBACMiddleware } from '@jmruthers/pace-core/rbac';
+ * 
+ * export default createRBACMiddleware({
+ *   protectedRoutes: [
+ *     { path: '/admin', permission: 'manage:admin' },
+ *     { path: '/events', permission: 'read:events' },
+ *   ],
+ *   fallbackUrl: '/access-denied',
+ * });
+ * ```
+ */
+export function createRBACMiddleware(config: {
+  protectedRoutes: Array<{
+    path: string;
+    permission: Permission;
+    pageId?: UUID;
+  }>;
+  fallbackUrl?: string;
+}) {
+  return async (req: { nextUrl: { pathname: string }; user?: { id: string }; organisationId?: string }, res: { redirect: (url: string) => void }, next: () => void) => {
+    const { pathname } = req.nextUrl;
+    const userId = req.user?.id;
+    const organisationId = req.organisationId;
+
+    if (!userId || !organisationId) {
+      return res.redirect(config.fallbackUrl || '/login');
+    }
+
+    // Find matching protected route
+    const protectedRoute = config.protectedRoutes.find(route => 
+      pathname.startsWith(route.path)
+    );
+
+    if (protectedRoute) {
+      try {
+        const { isPermitted } = await import('./api');
+        const hasPermission = await isPermitted({
+          userId,
+          scope: { organisationId },
+          permission: protectedRoute.permission,
+          pageId: protectedRoute.pageId,
+        });
+
+        if (!hasPermission) {
+          return res.redirect(config.fallbackUrl || '/access-denied');
+        }
+    } catch (_error) {
+      // Permission check failed - error logged via RBAC logger
+      return res.redirect(config.fallbackUrl || '/access-denied');
+    }
+    }
+
+    next();
+  };
+}
+
+// ============================================================================
+// EXPRESS MIDDLEWARE
+// ============================================================================
+
+/**
+ * Express Middleware for RBAC
+ * 
+ * Middleware that checks permissions for Express routes.
+ * 
+ * @param config - Middleware configuration
+ * @returns Express middleware function
+ * 
+ * @example
+ * ```typescript
+ * import { createRBACExpressMiddleware } from '@jmruthers/pace-core/rbac';
+ * 
+ * app.use(createRBACExpressMiddleware({
+ *   permission: 'read:api',
+ *   pageId: 'api-page-123',
+ * }));
+ * ```
+ */
+export function createRBACExpressMiddleware(config: {
+  permission: Permission;
+  pageId?: UUID;
+}) {
+  return async (req: { user?: { id: string }; organisationId?: string; eventId?: string; appId?: string }, res: { status: (code: number) => { json: (data: object) => void } }, next: () => void) => {
+    const userId = req.user?.id;
+    const organisationId = req.organisationId;
+    const eventId = req.eventId;
+    const appId = req.appId;
+
+    if (!userId || !organisationId) {
+      return res.status(401).json({ error: 'User context required' });
+    }
+
+    try {
+      const { isPermitted } = await import('./api');
+      const hasPermission = await isPermitted({
+        userId,
+        scope: { organisationId, eventId, appId },
+        permission: config.permission,
+        pageId: config.pageId,
+      });
+
+      if (!hasPermission) {
+        return res.status(403).json({ error: 'Permission denied' });
+      }
+
+      next();
+    } catch (_error) {
+      // Permission check failed - error logged via RBAC logger
+      return res.status(500).json({ error: 'Permission check failed' });
+    }
+  };
+}
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Check if a user has a permission (synchronous cache check only)
+ * 
+ * @param userId - User ID
+ * @param scope - Permission scope
+ * @param permission - Permission to check
+ * @param pageId - Optional page ID
+ * @returns True if permission is cached and granted
+ */
+export function hasPermissionCached(
+  userId: UUID,
+  scope: { organisationId: UUID; eventId?: string; appId?: UUID },
+  _permission: Permission,
+  _pageId?: UUID
+): boolean {
+  const cacheKey = RBACCache.generatePermissionKey({
+    userId,
+    organisationId: scope.organisationId,
+    eventId: scope.eventId,
+    appId: scope.appId,
+  });
+  
+  return rbacCache.get<boolean>(cacheKey) || false;
+}
+
+/**
+ * Check if a user has any of the specified permissions (synchronous cache check only)
+ * 
+ * @param userId - User ID
+ * @param scope - Permission scope
+ * @param permissions - Array of permissions to check
+ * @param pageId - Optional page ID
+ * @returns True if any permission is cached and granted
+ */
+export function hasAnyPermissionCached(
+  userId: UUID,
+  scope: { organisationId: UUID; eventId?: string; appId?: UUID },
+  permissions: Permission[],
+  pageId?: UUID
+): boolean {
+  return permissions.some(permission => 
+    hasPermissionCached(userId, scope, permission, pageId)
+  );
+}
+
+// Import useAccessLevel for AccessLevelGuard
+import { useAccessLevel } from './hooks';