@jmruthers/pace-core 0.2.7 → 0.4.1

package/src/rbac/adapters.tsx

@@ -1,726 +0,0 @@
-/**
- * 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';