@jmruthers/pace-core 0.2.4

package/src/rbac/engine.ts

@@ -0,0 +1,1026 @@
+/**
+ * RBAC Core Engine
+ * @package @jmruthers/pace-core
+ * @module RBAC/Engine
+ * @since 1.0.0
+ * 
+ * This module implements the core RBAC permission algorithm with deny-overrides-allow precedence.
+ */
+
+import { SupabaseClient } from '@supabase/supabase-js';
+import { Database } from '../types/database';
+import { 
+  UUID, 
+  Permission, 
+  Scope, 
+  PermissionCheck, 
+  AccessLevel, 
+  PermissionMap,
+  Operation,
+  OrganisationRole,
+  EventAppRole
+} from './types';
+import { rbacCache, RBACCache } from './cache';
+import { emitAuditEvent } from './audit';
+import { getCurrentAppName } from '../utils/appNameResolver';
+import { 
+  RBACSecurityValidator, 
+  RBACSecurityMiddleware, 
+  SecurityContext,
+  DEFAULT_SECURITY_CONFIG 
+} from './security';
+
+/**
+ * Grant type for permission resolution
+ */
+interface Grant {
+  type: 'allow' | 'deny';
+  permission: Permission;
+  scope: 'global' | 'organisation' | 'eventApp' | 'page';
+  source: string;
+}
+
+/**
+ * RBAC Engine
+ * 
+ * Implements the core permission algorithm with deny-overrides-allow precedence.
+ */
+export class RBACEngine {
+  private supabase: SupabaseClient<Database>;
+  private securityMiddleware: RBACSecurityMiddleware;
+
+  constructor(supabase: SupabaseClient<Database>) {
+    this.supabase = supabase;
+    this.securityMiddleware = new RBACSecurityMiddleware(DEFAULT_SECURITY_CONFIG);
+  }
+
+  /**
+   * Check if a user has a specific permission
+   * 
+   * @param input - Permission check input
+   * @param securityContext - Optional security context for enhanced validation
+   * @returns Promise resolving to permission result
+   */
+  async isPermitted(input: PermissionCheck, securityContext?: SecurityContext): Promise<boolean> {
+    const startTime = Date.now();
+    const { userId, permission, scope, pageId } = input;
+
+    try {
+      // Security validation
+      if (securityContext) {
+        const validation = await this.securityMiddleware.validateInput(input, securityContext);
+        if (!validation.isValid) {
+          RBACSecurityValidator.logSecurityEvent({
+            type: 'invalid_input',
+            userId,
+            details: { errors: validation.errors, input: JSON.stringify(input) },
+          });
+          return false;
+        }
+
+        const rateLimit = await this.securityMiddleware.checkRateLimit(securityContext);
+        if (!rateLimit.isAllowed) {
+          RBACSecurityValidator.logSecurityEvent({
+            type: 'rate_limit_exceeded',
+            userId,
+            details: { remaining: rateLimit.remaining },
+          });
+          return false;
+        }
+      }
+
+      // Input validation (only when security context is provided)
+      if (securityContext) {
+        if (!RBACSecurityValidator.validateUserId(userId)) {
+          RBACSecurityValidator.logSecurityEvent({
+            type: 'invalid_input',
+            userId,
+            details: { error: 'Invalid user ID format' },
+          });
+          return false;
+        }
+
+        if (!RBACSecurityValidator.validatePermission(permission)) {
+          RBACSecurityValidator.logSecurityEvent({
+            type: 'invalid_input',
+            userId,
+            details: { error: 'Invalid permission format', permission },
+          });
+          return false;
+        }
+
+        if (!RBACSecurityValidator.validateScope(scope)) {
+          RBACSecurityValidator.logSecurityEvent({
+            type: 'invalid_input',
+            userId,
+            details: { error: 'Invalid scope format', scope },
+          });
+          return false;
+        }
+      }
+      // 1) If GlobalRole == 'super_admin' → allow (log bypass:true)
+      const isSuperAdmin = await this.checkSuperAdmin(userId);
+      if (isSuperAdmin) {
+        const duration = Date.now() - startTime;
+        // Only emit audit event if we have a valid organisation ID
+        if (scope.organisationId) {
+          // Resolve pageId to UUID if it's a page name
+          const resolvedPageId = await this.resolvePageId(pageId, scope.appId);
+          await emitAuditEvent({
+            type: 'permission_check',
+            userId,
+            organisationId: scope.organisationId,
+            eventId: scope.eventId,
+            appId: scope.appId,
+            pageId: resolvedPageId,
+            permission,
+            decision: true,
+            source: 'api',
+            bypass: true,
+            duration_ms: duration,
+          });
+        }
+        return true;
+      }
+
+      // 2) Validate context requirements based on app configuration
+      const validatedScope = await this.validateContextRequirements(scope, scope.appId);
+      if (!validatedScope) {
+        const duration = Date.now() - startTime;
+        // Only emit audit event if we have a valid organisation ID
+        if (scope.organisationId) {
+          // Resolve pageId to UUID if it's a page name
+          const resolvedPageId = await this.resolvePageId(pageId, scope.appId);
+          await emitAuditEvent({
+            type: 'permission_denied',
+            userId,
+            organisationId: scope.organisationId,
+            eventId: scope.eventId,
+            appId: scope.appId,
+            pageId: resolvedPageId,
+            permission,
+            source: 'api',
+            metadata: {
+              reason: 'invalid_context_requirements',
+              app_requires_event: scope.appId ? await this.getAppConfig(scope.appId).then(config => config?.requires_event) : null
+            }
+          });
+        }
+        return false;
+      }
+
+      // 3) Collect active grants at page → eventApp → organisation → global
+      const grants = await this.collectActiveGrants(userId, validatedScope, pageId);
+      console.log('[RBACEngine] Collected grants:', grants);
+
+      // 4) Apply explicit denies at the closest scope first (deny overrides allow)
+      const denies = grants.filter(g => g.type === 'deny');
+      console.log('[RBACEngine] Deny grants:', denies);
+      for (const deny of denies) {
+        const matches = this.permissionMatches(deny.permission, permission);
+        console.log('[RBACEngine] Checking deny:', { 
+          denyPermission: deny.permission, 
+          requestedPermission: permission, 
+          matches 
+        });
+        if (matches) {
+          const duration = Date.now() - startTime;
+          console.log('[RBACEngine] Permission DENIED by explicit deny rule');
+          // Only emit audit event if we have a valid organisation ID
+          if (scope.organisationId) {
+            // Resolve pageId to UUID if it's a page name
+            const resolvedPageId = await this.resolvePageId(pageId, scope.appId);
+            await emitAuditEvent({
+              type: 'permission_denied',
+              userId,
+              organisationId: scope.organisationId,
+              eventId: scope.eventId,
+              appId: scope.appId,
+              pageId: resolvedPageId,
+              permission,
+              source: 'api',
+            });
+          }
+          return false;
+        }
+      }
+
+      // 5) If no deny, check allows from closest to widest scope
+      const allows = grants.filter(g => g.type === 'allow');
+      console.log('[RBACEngine] Allow grants:', allows);
+      let hasPermission = false;
+      
+      // Check allows in precedence order: page → eventApp → organisation → global
+      const scopeOrder: Array<'page' | 'eventApp' | 'organisation' | 'global'> = ['page', 'eventApp', 'organisation', 'global'];
+      
+      for (const scopeType of scopeOrder) {
+        const scopeAllows = allows.filter(g => g.scope === scopeType);
+        console.log(`[RBACEngine] Checking ${scopeType} allows:`, scopeAllows);
+        for (const allow of scopeAllows) {
+          console.log(`[RBACEngine] About to check permission match for ${scopeType}:`, {
+            allowPermission: allow.permission,
+            requestedPermission: permission,
+            scopeType
+          });
+          const matches = this.permissionMatches(allow.permission, permission);
+          console.log(`[RBACEngine] Permission match result:`, { 
+            scopeType,
+            allowPermission: allow.permission, 
+            requestedPermission: permission, 
+            matches 
+          });
+          if (matches) {
+            console.log(`[RBACEngine] Permission GRANTED by ${scopeType} allow rule`);
+            hasPermission = true;
+            break;
+          }
+        }
+        if (hasPermission) break;
+      }
+
+      // 6) Return final decision; emit audit event
+      const finalDecision = hasPermission;
+      const _duration = Date.now() - startTime;
+      
+      console.log('[RBACEngine] Final decision:', {
+        userId,
+        permission,
+        pageId,
+        hasPermission,
+        grantsCount: grants.length,
+        allowsCount: allows.length,
+        deniesCount: denies.length,
+        duration: _duration
+      });
+
+      // Only emit audit event if we have a valid organisation ID
+      if (scope.organisationId) {
+        // Resolve pageId to UUID if it's a page name
+        const resolvedPageId = await this.resolvePageId(pageId, scope.appId);
+        await emitAuditEvent({
+          type: 'permission_check',
+          userId,
+          organisationId: scope.organisationId,
+          eventId: scope.eventId,
+          appId: scope.appId,
+          pageId: resolvedPageId,
+          permission,
+          decision: finalDecision,
+          source: 'api',
+          duration_ms: _duration,
+        });
+      }
+
+      return finalDecision;
+    } catch (error) {
+      // Log security event for unexpected errors
+      RBACSecurityValidator.logSecurityEvent({
+        type: 'suspicious_activity',
+        userId,
+        details: { 
+          error: error instanceof Error ? error.message : 'Unknown error',
+          permission,
+          scope: JSON.stringify(scope)
+        },
+      });
+
+      // Permission check failed - error logged via RBAC logger
+      return false;
+    }
+  }
+
+  /**
+   * Get user's access level in a scope
+   * 
+   * @param input - Access level input
+   * @returns Promise resolving to access level
+   */
+  async getAccessLevel(input: { userId: UUID; scope: Scope }): Promise<AccessLevel> {
+    const { userId, scope } = input;
+
+    // Check super admin first - super admins don't need context validation
+    const isSuperAdmin = await this.checkSuperAdmin(userId);
+    if (isSuperAdmin) {
+      return 'super';
+    }
+
+    // Validate context requirements based on app configuration
+    const validatedScope = await this.validateContextRequirements(scope, scope.appId);
+    if (!validatedScope) {
+      return 'viewer'; // Default to lowest access level for invalid context
+    }
+
+    // Check cache first
+    const cacheKey = RBACCache.generateAccessLevelKey(
+      userId,
+      validatedScope.organisationId!,
+      validatedScope.eventId,
+      validatedScope.appId
+    );
+    
+    const cached = rbacCache.get<AccessLevel>(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    // Check organisation role
+    const orgRole = await this.getOrganisationRole(userId, validatedScope.organisationId!);
+    if (orgRole === 'org_admin') {
+      rbacCache.set(cacheKey, 'admin');
+      return 'admin';
+    }
+
+    // Check event-app role
+    if (validatedScope.eventId && validatedScope.appId) {
+      const eventRole = await this.getEventAppRole(userId, validatedScope.eventId, validatedScope.appId);
+      if (eventRole === 'event_admin') {
+        rbacCache.set(cacheKey, 'admin');
+        return 'admin';
+      }
+      if (eventRole === 'planner') {
+        rbacCache.set(cacheKey, 'planner');
+        return 'planner';
+      }
+      if (eventRole === 'participant') {
+        rbacCache.set(cacheKey, 'participant');
+        return 'participant';
+      }
+    }
+
+    // Default to viewer
+    rbacCache.set(cacheKey, 'viewer');
+    return 'viewer';
+  }
+
+  /**
+   * Get user's permission map for a scope
+   * 
+   * @param input - Permission map input
+   * @returns Promise resolving to permission map
+   */
+  async getPermissionMap(input: { userId: UUID; scope: Scope }): Promise<PermissionMap> {
+    const { userId, scope } = input;
+
+    // Check super admin first - super admins have all permissions
+    const isSuperAdmin = await this.checkSuperAdmin(userId);
+    if (isSuperAdmin) {
+      return {}; // Super admins have all permissions, return empty map
+    }
+
+    // Validate context requirements based on app configuration
+    const validatedScope = await this.validateContextRequirements(scope, scope.appId);
+    if (!validatedScope) {
+      return {}; // No permissions without valid context
+    }
+
+    // Check cache first
+    const cacheKey = RBACCache.generatePermissionMapKey(
+      userId,
+      validatedScope.organisationId!,
+      validatedScope.eventId,
+      validatedScope.appId
+    );
+    
+    const cached = rbacCache.get<PermissionMap>(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const permissionMap: PermissionMap = {};
+
+    // Get all pages for the app
+    if (validatedScope.appId) {
+      const { data: pages } = await this.supabase
+        .from('rbac_app_pages')
+        .select('id, page_name')
+        .eq('app_id', validatedScope.appId) as { data: Array<{ id: string; page_name: string }> | null };
+
+      if (pages) {
+        for (const page of pages) {
+          const operations: Operation[] = [];
+          
+          // Check each operation
+          for (const operation of ['read', 'create', 'update', 'delete', 'manage'] as Operation[]) {
+            const hasPermission = await this.isPermitted({
+              userId,
+              scope: validatedScope,
+              permission: `${operation}:${page.page_name}`,
+              pageId: page.id,
+            });
+            
+            if (hasPermission) {
+              operations.push(operation);
+            }
+          }
+          
+          permissionMap[page.id] = operations;
+        }
+      }
+    }
+
+    rbacCache.set(cacheKey, permissionMap);
+    return permissionMap;
+  }
+
+  /**
+   * Check if user is super admin
+   * 
+   * @param userId - User ID
+   * @returns Promise resolving to super admin status
+   */
+  private async checkSuperAdmin(userId: UUID): Promise<boolean> {
+    // Check cache first
+    const cacheKey = `super_admin:${userId}`;
+    const cached = rbacCache.get<boolean>(cacheKey);
+    if (cached !== null) {
+      return cached;
+    }
+
+    const { data, error } = await this.supabase
+      .from('rbac_global_roles')
+      .select('id')
+      .eq('user_id', userId)
+      .eq('role', 'super_admin')
+      .is('valid_to', null)
+      .single();
+
+    const isSuperAdmin = !error && !!data;
+    
+    // Cache the result for 60 seconds
+    rbacCache.set(cacheKey, isSuperAdmin, 60000);
+    
+    return isSuperAdmin;
+  }
+
+  /**
+   * Get app configuration including requires_event setting
+   * 
+   * @param appId - App ID
+   * @returns Promise resolving to app configuration
+   */
+  async getAppConfig(appId: UUID): Promise<{ requires_event: boolean } | null> {
+    const { data, error } = await this.supabase
+      .from('rbac_apps')
+      .select('requires_event')
+      .eq('id', appId)
+      .eq('is_active', true)
+      .single() as { data: { requires_event: boolean } | null; error: any };
+
+    if (error || !data) {
+      return null;
+    }
+
+    return { requires_event: data.requires_event };
+  }
+
+  /**
+   * Resolve organisation ID from event ID
+   * 
+   * @param eventId - Event ID
+   * @returns Promise resolving to organisation ID
+   */
+  private async resolveOrganisationFromEvent(eventId: string): Promise<UUID | null> {
+    const { data, error } = await this.supabase
+      .from('event')
+      .select('organisation_id')
+      .eq('id', eventId)
+      .single() as { data: { organisation_id: string } | null; error: any };
+
+    if (error || !data) {
+      return null;
+    }
+
+    return data.organisation_id;
+  }
+
+  /**
+   * Validate context requirements based on app configuration
+   * 
+   * @param scope - Permission scope
+   * @param appId - Optional app ID
+   * @returns Promise resolving to validated scope with resolved organisation ID
+   */
+  private async validateContextRequirements(scope: Scope, appId?: UUID): Promise<Scope | null> {
+    // If we have an app ID, check its requirements
+    if (appId) {
+      const appConfig = await this.getAppConfig(appId);
+      if (!appConfig) {
+        return null; // App not found or inactive
+      }
+
+      if (appConfig.requires_event) {
+        // Event-based app: requires eventId, organisationId is resolved from event
+        if (!scope.eventId) {
+          return null; // Event context required
+        }
+
+        // Resolve organisation from event if not provided
+        if (!scope.organisationId) {
+          const resolvedOrgId = await this.resolveOrganisationFromEvent(scope.eventId);
+          if (!resolvedOrgId) {
+            return null; // Could not resolve organisation from event
+          }
+          return {
+            ...scope,
+            organisationId: resolvedOrgId
+          };
+        }
+
+        return scope;
+      } else {
+        // Organisation-based app: requires organisationId, eventId is optional
+        if (!scope.organisationId) {
+          return null; // Organisation context required
+        }
+
+        return scope;
+      }
+    }
+
+    // No app ID provided - use legacy validation (require organisation)
+    if (!scope.organisationId) {
+      return null; // Organisation context required for legacy behavior
+    }
+
+    return scope;
+  }
+
+  /**
+   * Collect active grants for a user in a scope
+   * 
+   * @param userId - User ID
+   * @param scope - Permission scope
+   * @param pageId - Optional page ID
+   * @returns Promise resolving to grants array
+   * 
+   * PRECEDENCE ORDER (closest scope first): page → eventApp → organisation → global
+   */
+  private async collectActiveGrants(
+    userId: UUID, 
+    scope: Scope, 
+    pageId?: UUID | string
+  ): Promise<Grant[]> {
+    const grants: Grant[]  = [];
+    const now = new Date().toISOString();
+    
+    // Pre-fetch user roles once (to avoid duplicate queries)
+    const userRoles: string[] = [];
+    
+    // Get event-app roles
+    if (scope.eventId && scope.appId) {
+      const { data: eventRoles } = await this.supabase
+        .from('rbac_event_app_roles')
+        .select('role, status, valid_from, valid_to')
+        .eq('user_id', userId)
+        .eq('event_id', scope.eventId)
+        .eq('app_id', scope.appId)
+        .eq('status', 'active')
+        .lte('valid_from', now)
+        .or(`valid_to.is.null,valid_to.gte.${now}`) as { data: Array<{ role: string; status: string; valid_from: string; valid_to: string | null }> | null };
+      
+      if (eventRoles) {
+        userRoles.push(...eventRoles.map(r => r.role));
+        // Also add event-app grants
+        for (const role of eventRoles) {
+          grants.push({
+            type: 'allow',
+            permission: this.getPermissionForEventRole(role.role as EventAppRole),
+            scope: 'eventApp',
+            source: 'rbac_event_app_roles',
+          });
+        }
+      }
+    }
+    
+    // Get organisation roles
+    if (scope.organisationId) {
+      const { data: orgRoles } = await this.supabase
+        .from('rbac_organisation_roles')
+        .select('role, status, valid_from, valid_to')
+        .eq('user_id', userId)
+        .eq('organisation_id', scope.organisationId)
+        .eq('status', 'active')
+        .lte('valid_from', now)
+        .or(`valid_to.is.null,valid_to.gte.${now}`) as { data: Array<{ role: string; status: string; valid_from: string; valid_to: string | null }> | null };
+      
+      if (orgRoles) {
+        userRoles.push(...orgRoles.map(r => r.role));
+        // Also add org grants
+        for (const role of orgRoles) {
+          grants.push({
+            type: 'allow',
+            permission: this.getPermissionForOrgRole(role.role as OrganisationRole),
+            scope: 'organisation',
+            source: 'rbac_organisation_roles',
+          });
+        }
+      }
+    }
+    
+    console.log('[collectActiveGrants] User roles:', userRoles);
+
+    // 1. PAGE GRANTS (closest scope first) - Use RPC to bypass RLS
+    if (pageId) {
+      // Resolve page ID if it's a page name (string)
+      let resolvedPageId: UUID | null = null;
+      if (typeof pageId === 'string') {
+        // Check if it's already a UUID
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        if (uuidRegex.test(pageId)) {
+          resolvedPageId = pageId as UUID;
+        } else {
+          // It's a page name, resolve it to a page ID
+          const appId = scope.appId;
+          if (appId) {
+            const { data: page } = await this.supabase
+              .from('rbac_app_pages')
+              .select('id')
+              .eq('app_id', appId)
+              .eq('page_name', pageId)
+              .single() as { data: { id: UUID } | null };
+            resolvedPageId = page?.id || null;
+          }
+        }
+      } else {
+        resolvedPageId = pageId;
+      }
+
+      if (resolvedPageId && scope.appId) {
+        console.log('[collectActiveGrants] Fetching page permissions via RPC for page:', resolvedPageId);
+        
+        // Get the page name for building specific permission strings
+        let pageName: string | null = null;
+        if (typeof pageId === 'string' && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(pageId)) {
+          // pageId is already the page name
+          pageName = pageId;
+        } else {
+          // Fetch page name from database
+          const { data: page } = await this.supabase
+            .from('rbac_app_pages')
+            .select('page_name')
+            .eq('id', resolvedPageId)
+            .single() as { data: { page_name: string } | null };
+          pageName = page?.page_name || null;
+        }
+        
+        // Use RPC to get page permissions (bypasses RLS)
+        // @ts-ignore - RPC type inference is incorrect
+        const rpcResult = await this.supabase.rpc('get_rbac_permissions', {
+          p_user_id: userId,
+          p_app_id: scope.appId,
+          p_event_id: scope.eventId || null,
+          p_organisation_id: scope.organisationId || null,
+          p_page_id: resolvedPageId
+        });
+        
+        const { data: rpcPermissions } = rpcResult as { data: Array<{ permission_type: string; role_name: string; has_permission: boolean }> | null; error: any };
+        
+        console.log('[collectActiveGrants] RPC page permissions:', rpcPermissions);
+        
+        if (rpcPermissions && pageName) {
+          // Filter to only page-level permissions (not org/event-app roles)
+          const pagePerms = rpcPermissions.filter(p => 
+            p.permission_type !== 'all_permissions' && 
+            p.permission_type !== 'organisation_access' && 
+            p.permission_type !== 'event_app_access'
+          );
+          
+          for (const perm of pagePerms) {
+            // Only add if user has this role
+            if (userRoles.includes(perm.role_name)) {
+              console.log('[collectActiveGrants] Adding page grant:', { operation: perm.permission_type, role: perm.role_name, allowed: perm.has_permission, pageName });
+              grants.push({
+                type: perm.has_permission ? 'allow' : 'deny',
+                // Use page.${pageName} format for specific page permissions
+                permission: `${perm.permission_type}:page.${pageName}` as Permission,
+                scope: 'page',
+                source: 'rbac_page_permissions',
+              });
+            }
+          }
+        }
+      }
+    }
+
+    // 2. GLOBAL GRANTS (widest scope last)
+    const { data: globalRoles } = await this.supabase
+      .from('rbac_global_roles')
+      .select('role, valid_from, valid_to')
+      .eq('user_id', userId)
+      .lte('valid_from', now)
+      .or(`valid_to.is.null,valid_to.gte.${now}`) as { data: Array<{ role: string; valid_from: string; valid_to: string | null }> | null };
+
+    if (globalRoles) {
+      for (const role of globalRoles) {
+        if (role.role === 'super_admin') {
+          grants.push({
+            type: 'allow',
+            permission: 'manage:*' as Permission,
+            scope: 'global',
+            source: 'rbac_global_roles',
+          });
+        }
+      }
+    }
+    
+    console.log('[collectActiveGrants] Final grants:', grants);
+
+    return grants;
+  }
+
+  /**
+   * Check page-specific permissions
+   * 
+   * @param userId - User ID
+   * @param pageId - Page ID
+   * @param permission - Permission to check
+   * @param scope - Permission scope
+   * @returns Promise resolving to page permission result
+   */
+  private async checkPagePermissions(
+    userId: UUID,
+    pageId: UUID | string | undefined,
+    permission: Permission,
+    scope: Scope
+  ): Promise<boolean> {
+    if (!pageId) {
+      return true; // No page restrictions
+    }
+
+    const [operation] = permission.split(':') as [Operation, string];
+
+    // Get user's roles in this scope
+    const userRoles: string[] = [];
+
+    // Add organisation role
+    if (scope.organisationId) {
+      const orgRole = await this.getOrganisationRole(userId, scope.organisationId);
+      if (orgRole) {
+        userRoles.push(orgRole);
+      }
+    }
+
+    // Add event-app role
+    if (scope.eventId && scope.appId) {
+      const eventRole = await this.getEventAppRole(userId, scope.eventId, scope.appId);
+      if (eventRole) {
+        userRoles.push(eventRole);
+      }
+    }
+
+    // Resolve page ID if it's a page name (string)
+    let resolvedPageId: UUID | null = null;
+    if (typeof pageId === 'string') {
+      // Check if it's already a UUID
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (uuidRegex.test(pageId)) {
+        resolvedPageId = pageId as UUID;
+      } else {
+        // It's a page name, resolve it to a page ID
+        // First, get the app ID from scope or environment
+        let appId = scope.appId;
+        if (!appId) {
+          // Try to get app ID from environment
+          const appName = process.env.VITE_APP_NAME || process.env.REACT_APP_NAME;
+          if (appName) {
+            const { data: app } = await this.supabase
+              .from('rbac_apps')
+              .select('id')
+              .eq('name', appName)
+              .eq('is_active', true)
+              .single() as { data: { id: UUID } | null };
+            if (app) {
+              appId = app.id;
+            }
+          }
+        }
+        
+        if (appId) {
+          const { data: page } = await this.supabase
+            .from('rbac_app_pages')
+            .select('id')
+            .eq('app_id', appId)
+            .eq('page_name', pageId)
+            .single() as { data: { id: UUID } | null };
+          resolvedPageId = page?.id || null;
+        }
+      }
+    } else {
+      resolvedPageId = pageId;
+    }
+
+    if (!resolvedPageId) {
+      return false; // Page not found
+    }
+
+    // Check page permissions
+    const { data: pagePermissions } = await this.supabase
+      .from('rbac_page_permissions')
+      .select('allowed')
+      .eq('app_page_id', resolvedPageId)
+      .eq('operation', operation)
+      .in('role_name', userRoles)
+      .single() as { data: { allowed: boolean } | null };
+
+    return pagePermissions?.allowed ?? false;
+  }
+
+  /**
+   * Get organisation role for a user
+   * 
+   * @param userId - User ID
+   * @param organisationId - Organisation ID
+   * @returns Promise resolving to organisation role
+   */
+  private async getOrganisationRole(userId: UUID, organisationId: UUID): Promise<OrganisationRole | null> {
+    const { data, error } = await this.supabase
+      .from('rbac_organisation_roles')
+      .select('role')
+      .eq('user_id', userId)
+      .eq('organisation_id', organisationId)
+      .eq('status', 'active')
+      .single() as { data: { role: string } | null; error: any };
+
+    return error ? null : (data?.role as OrganisationRole) || null;
+  }
+
+  /**
+   * Get event-app role for a user
+   * 
+   * @param userId - User ID
+   * @param eventId - Event ID
+   * @param appId - App ID
+   * @returns Promise resolving to event-app role
+   */
+  private async getEventAppRole(userId: UUID, eventId: string, appId: UUID): Promise<EventAppRole | null> {
+    const { data, error } = await this.supabase
+      .from('rbac_event_app_roles')
+      .select('role, status, valid_from, valid_to')
+      .eq('user_id', userId)
+      .eq('event_id', eventId)
+      .eq('app_id', appId)
+      .eq('status', 'active')
+      .lte('valid_from', new Date().toISOString())
+      .or(`valid_to.is.null,valid_to.gte.${new Date().toISOString()}`)
+      .single() as { data: { role: string; status: string; valid_from: string; valid_to: string | null } | null; error: any };
+
+    return error ? null : (data?.role as EventAppRole) || null;
+  }
+
+  /**
+   * Get permission for organisation role
+   * 
+   * @param role - Organisation role
+   * @returns Permission string
+   */
+  private getPermissionForOrgRole(role: OrganisationRole): Permission {
+    switch (role) {
+      case 'org_admin':
+        return 'manage:*' as Permission;
+      case 'leader':
+        return 'manage:organisation.*' as Permission;
+      case 'member':
+        return 'read:organisation.*' as Permission;
+      case 'supporter':
+        return 'read:organisation.public' as Permission;
+      default:
+        return 'read:organisation.public' as Permission;
+    }
+  }
+
+  /**
+   * Get permission for event-app role
+   * 
+   * @param role - Event-app role
+   * @returns Permission string
+   */
+  private getPermissionForEventRole(role: EventAppRole): Permission {
+    switch (role) {
+      case 'event_admin':
+        return 'manage:event.*' as Permission;
+      case 'planner':
+        return 'manage:event.planning' as Permission;
+      case 'participant':
+        return 'read:event.*' as Permission;
+      case 'viewer':
+        return 'read:event.public' as Permission;
+      default:
+        return 'read:event.public' as Permission;
+    }
+  }
+
+  /**
+   * Check if a permission matches another permission
+   * 
+   * @param grantPermission - Permission from grant
+   * @param requestedPermission - Requested permission
+   * @returns True if permissions match
+   */
+  private permissionMatches(grantPermission: Permission, requestedPermission: Permission): boolean {
+    console.log('[permissionMatches] Checking:', { grantPermission, requestedPermission });
+    
+    // Exact match
+    if (grantPermission === requestedPermission) {
+      console.log('[permissionMatches] Exact match found');
+      return true;
+    }
+
+    // Wildcard match
+    if (grantPermission.endsWith(':*') || grantPermission.endsWith('.*')) {
+      const [grantOp, grantResource] = grantPermission.split(':');
+      const [requestedOp, requestedResource] = requestedPermission.split(':');
+      
+      console.log('[permissionMatches] Wildcard check:', { 
+        grantOp, 
+        grantResource, 
+        requestedOp, 
+        requestedResource,
+        operationsMatch: grantOp === requestedOp
+      });
+      
+      if (grantOp === requestedOp) {
+        // For wildcard permissions like "read:*" or "read:organisation.*", grantResource is "*" or "organisation.*"
+        // We need to check if the requested resource starts with the prefix before "*"
+        const prefix = grantResource.slice(0, -1); // Remove the "*"
+        const matches = prefix === '' || requestedResource.startsWith(prefix);
+        console.log('[permissionMatches] Wildcard match result:', { prefix, matches });
+        return matches;
+      }
+    }
+
+    // Check for other wildcard patterns
+    if (grantPermission.includes('*')) {
+      const [grantOp, grantResource] = grantPermission.split(':');
+      const [requestedOp, requestedResource] = requestedPermission.split(':');
+      
+      console.log('[permissionMatches] Other wildcard check:', { 
+        grantOp, 
+        grantResource, 
+        requestedOp, 
+        requestedResource,
+        operationsMatch: grantOp === requestedOp
+      });
+      
+      if (grantOp === requestedOp) {
+        // For wildcard permissions like "read:event*", grantResource is "event*"
+        const prefix = grantResource.replace('*', '');
+        const matches = requestedResource.startsWith(prefix);
+        console.log('[permissionMatches] Other wildcard match result:', { prefix, matches });
+        return matches;
+      }
+    }
+
+    console.log('[permissionMatches] No match found');
+    return false;
+  }
+
+  /**
+   * Resolve a page ID to UUID if it's a page name
+   * 
+   * @param pageId - Page ID (UUID) or page name (string)
+   * @param appId - App ID to look up the page
+   * @returns Resolved page ID (UUID) or original pageId if it's already a UUID or can't be resolved
+   */
+  private async resolvePageId(pageId?: UUID | string, appId?: UUID): Promise<UUID | string | undefined> {
+    if (!pageId) {
+      return undefined;
+    }
+
+    // Check if it's already a UUID
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (uuidRegex.test(pageId)) {
+      return pageId as UUID;
+    }
+
+    // It's a page name, but we need appId to resolve it
+    if (!appId) {
+      // If we can't resolve it, return the original value
+      return pageId;
+    }
+
+    // It's a page name, resolve it to a page ID
+    try {
+      const { data: page } = await this.supabase
+        .from('rbac_app_pages')
+        .select('id')
+        .eq('app_id', appId)
+        .eq('page_name', pageId)
+        .single() as { data: { id: UUID } | null };
+      
+      return page?.id || pageId; // Return original if not found
+    } catch (error) {
+      console.warn('[RBAC Engine] Failed to resolve page name to UUID:', { pageId, appId, error });
+      return pageId; // Return original on error
+    }
+  }
+}
+
+/**
+ * Create an RBAC engine instance
+ * 
+ * @param supabase - Supabase client
+ * @returns RBACEngine instance
+ */
+export function createRBACEngine(supabase: SupabaseClient<Database>): RBACEngine {
+  return new RBACEngine(supabase);
+}