@jmruthers/pace-core 0.2.7 → 0.4.1

package/src/rbac/api.ts

@@ -1,339 +0,0 @@
-/**
- * RBAC Main API Functions
- * @package @jmruthers/pace-core
- * @module RBAC/API
- * @since 1.0.0
- * 
- * This module provides the main API functions for the RBAC system.
- */
-
-import { SupabaseClient } from '@supabase/supabase-js';
-import { Database } from '../types/database';
-import { 
-  UUID, 
-  Scope, 
-  Permission, 
-  AccessLevel, 
-  PermissionMap, 
-  PermissionCheck,
-  RBACNotInitializedError
-} from './types';
-import { createRBACEngine, RBACEngine } from './engine';
-import { createAuditManager, setGlobalAuditManager } from './audit';
-import { rbacCache, RBACCache, CACHE_PATTERNS } from './cache';
-import { createRBACConfig, RBACConfig, getRBACLogger } from './config';
-
-// Global engine instance
-let globalEngine: RBACEngine | null = null;
-
-/**
- * Setup RBAC system
- * 
- * @param supabase - Supabase client
- * @param config - Optional configuration
- */
-export function setupRBAC(supabase: SupabaseClient<Database>, config?: Partial<RBACConfig>): void {
-  const logger = getRBACLogger();
-  
-  // Create full config
-  const fullConfig: RBACConfig = {
-    supabase,
-    debug: process.env.NODE_ENV === 'development',
-    logLevel: 'warn',
-    developmentMode: process.env.NODE_ENV === 'development',
-    ...config,
-  };
-  
-  createRBACConfig(fullConfig);
-  
-  globalEngine = createRBACEngine(supabase);
-  
-  // Setup audit manager
-  const auditManager = createAuditManager(supabase);
-  setGlobalAuditManager(auditManager);
-  
-  logger.info('RBAC system initialized successfully');
-}
-
-/**
- * Get the global RBAC engine
- * 
- * @returns Global RBAC engine
- * @throws Error if RBAC not initialized
- */
-function getEngine(): RBACEngine {
-  if (!globalEngine) {
-    throw new RBACNotInitializedError();
-  }
-  return globalEngine;
-}
-
-/**
- * Get user's access level in a scope
- * 
- * @param input - Access level input
- * @returns Promise resolving to access level
- * 
- * @example
- * ```typescript
- * const accessLevel = await getAccessLevel({
- *   userId: 'user-123',
- *   scope: { organisationId: 'org-456' }
- * });
- * ```
- */
-export async function getAccessLevel(input: {
-  userId: UUID;
-  scope: Scope;
-}): Promise<AccessLevel> {
-  const engine = getEngine();
-  return engine.getAccessLevel(input);
-}
-
-/**
- * Get user's permission map for a scope
- * 
- * @param input - Permission map input
- * @returns Promise resolving to permission map
- * 
- * @example
- * ```typescript
- * const permissions = await getPermissionMap({
- *   userId: 'user-123',
- *   scope: { 
- *     organisationId: 'org-456',
- *     eventId: 'event-789',
- *     appId: 'app-101'
- *   }
- * });
- * ```
- */
-export async function getPermissionMap(input: {
-  userId: UUID;
-  scope: Scope;
-}): Promise<PermissionMap> {
-  const engine = getEngine();
-  return engine.getPermissionMap(input);
-}
-
-/**
- * Check if user has a specific permission
- * 
- * @param input - Permission check input
- * @returns Promise resolving to permission result
- * 
- * @example
- * ```typescript
- * const canManage = await isPermitted({
- *   userId: 'user-123',
- *   scope: { organisationId: 'org-456' },
- *   permission: 'manage:events',
- *   pageId: 'page-789'
- * });
- * ```
- */
-export async function isPermitted(input: PermissionCheck): Promise<boolean> {
-  const engine = getEngine();
-  return engine.isPermitted(input);
-}
-
-/**
- * Check if user has a specific permission (cached version)
- * 
- * @param input - Permission check input
- * @returns Promise resolving to permission result
- */
-export async function isPermittedCached(input: PermissionCheck): Promise<boolean> {
-  const { userId, scope, permission, pageId } = input;
-  
-  // Check cache first
-  const cacheKey = RBACCache.generatePermissionKey({
-    userId,
-    organisationId: scope.organisationId!,
-    eventId: scope.eventId,
-    appId: scope.appId,
-    permission,
-    pageId,
-  });
-  
-  const cached = rbacCache.get<boolean>(cacheKey);
-  if (cached !== null) {
-    return cached;
-  }
-
-  // Check permission
-  const result = await isPermitted(input);
-  
-  // Cache result
-  rbacCache.set(cacheKey, result);
-  
-  return result;
-}
-
-/**
- * Check if a user has a specific permission (alias for isPermitted)
- * 
- * @param input - Permission check parameters
- * @returns Promise<boolean> - True if user has permission
- */
-export async function hasPermission(input: PermissionCheck): Promise<boolean> {
-  return isPermitted(input);
-}
-
-/**
- * Check if user has any of the specified permissions
- * 
- * @param input - Permission check input with array of permissions
- * @returns Promise resolving to true if user has any permission
- */
-export async function hasAnyPermission(input: {
-  userId: UUID;
-  scope: Scope;
-  permissions: Permission[];
-  pageId?: UUID;
-}): Promise<boolean> {
-  const { permissions, ...baseInput } = input;
-  
-  for (const permission of permissions) {
-    const hasPermission = await isPermitted({
-      ...baseInput,
-      permission,
-    });
-    
-    if (hasPermission) {
-      return true;
-    }
-  }
-  
-  return false;
-}
-
-/**
- * Check if user has all of the specified permissions
- * 
- * @param input - Permission check input with array of permissions
- * @returns Promise resolving to true if user has all permissions
- */
-export async function hasAllPermissions(input: {
-  userId: UUID;
-  scope: Scope;
-  permissions: Permission[];
-  pageId?: UUID;
-}): Promise<boolean> {
-  const { permissions, ...baseInput } = input;
-  
-  for (const permission of permissions) {
-    const hasPermission = await isPermitted({
-      ...baseInput,
-      permission,
-    });
-    
-    if (!hasPermission) {
-      return false;
-    }
-  }
-  
-  return true;
-}
-
-/**
- * Check if user is super admin
- * 
- * @param userId - User ID
- * @returns Promise resolving to super admin status
- */
-export async function isSuperAdmin(userId: UUID): Promise<boolean> {
-  const engine = getEngine();
-  return engine['checkSuperAdmin'](userId);
-}
-
-/**
- * Get app configuration including requires_event setting
- * 
- * @param appId - App ID
- * @returns Promise resolving to app configuration
- */
-export async function getAppConfig(appId: UUID): Promise<{ requires_event: boolean } | null> {
-  const engine = getEngine();
-  return engine['getAppConfig'](appId);
-}
-
-/**
- * Check if user is organisation admin
- * 
- * @param userId - User ID
- * @param organisationId - Organisation ID
- * @returns Promise resolving to organisation admin status
- */
-export async function isOrganisationAdmin(userId: UUID, organisationId: UUID): Promise<boolean> {
-  const accessLevel = await getAccessLevel({
-    userId,
-    scope: { organisationId },
-  });
-  
-  return accessLevel === 'admin' || accessLevel === 'super';
-}
-
-/**
- * Check if user is event admin
- * 
- * @param userId - User ID
- * @param scope - Permission scope with eventId and appId
- * @returns Promise resolving to event admin status
- */
-export async function isEventAdmin(userId: UUID, scope: Scope): Promise<boolean> {
-  if (!scope.eventId || !scope.appId) {
-    return false;
-  }
-  
-  const accessLevel = await getAccessLevel({ userId, scope });
-  return accessLevel === 'admin' || accessLevel === 'super';
-}
-
-/**
- * Invalidate user's permission cache
- * 
- * @param userId - User ID
- * @param organisationId - Organisation ID (optional)
- */
-export function invalidateUserCache(userId: UUID, organisationId?: UUID): void {
-  if (organisationId) {
-    rbacCache.invalidate(CACHE_PATTERNS.PERMISSION(userId, organisationId));
-  } else {
-    rbacCache.invalidate(CACHE_PATTERNS.USER(userId));
-  }
-}
-
-/**
- * Invalidate organisation's permission cache
- * 
- * @param organisationId - Organisation ID
- */
-export function invalidateOrganisationCache(organisationId: UUID): void {
-  rbacCache.invalidate(CACHE_PATTERNS.ORGANISATION(organisationId));
-}
-
-/**
- * Invalidate event's permission cache
- * 
- * @param eventId - Event ID
- */
-export function invalidateEventCache(eventId: string): void {
-  rbacCache.invalidate(CACHE_PATTERNS.EVENT(eventId));
-}
-
-/**
- * Invalidate app's permission cache
- * 
- * @param appId - App ID
- */
-export function invalidateAppCache(appId: UUID): void {
-  rbacCache.invalidate(CACHE_PATTERNS.APP(appId));
-}
-
-/**
- * Clear all permission cache
- */
-export function clearCache(): void {
-  rbacCache.clear();
-}

package/src/rbac/audit-enhanced.ts

@@ -1,339 +0,0 @@
-/**
- * Enhanced RBAC Audit Manager
- * @package @jmruthers/pace-core
- * @module RBAC/AuditEnhanced
- * @since 1.0.0
- * 
- * This module provides an enhanced audit manager that can handle both
- * authenticated user contexts and service role contexts for audit logging.
- */
-
-import { SupabaseClient } from '@supabase/supabase-js';
-import { Database } from '../types/database';
-import { 
-  UUID, 
-  AuditEventSource, 
-  RBACAuditEvent 
-} from './types';
-
-/**
- * Enhanced audit event payload for permission checks
- */
-export interface EnhancedPermissionCheckAuditEvent {
-  type: 'permission_check';
-  userId: UUID;
-  organisationId: UUID;
-  eventId?: string;
-  appId?: UUID;
-  pageId?: UUID;
-  permission: string;
-  decision: boolean;
-  source: AuditEventSource;
-  bypass?: boolean;
-  duration_ms: number;
-  metadata?: Record<string, any>;
-}
-
-/**
- * Enhanced audit event payload for permission denied
- */
-export interface EnhancedPermissionDeniedAuditEvent {
-  type: 'permission_denied';
-  userId: UUID;
-  organisationId: UUID;
-  eventId?: string;
-  appId?: UUID;
-  pageId?: UUID;
-  permission: string;
-  source: AuditEventSource;
-  metadata?: Record<string, any>;
-}
-
-/**
- * Enhanced audit event payload for role granted
- */
-export interface EnhancedRoleGrantedAuditEvent {
-  type: 'role_granted';
-  userId: UUID;
-  organisationId: UUID;
-  eventId?: string;
-  appId?: UUID;
-  role: string;
-  grantedBy: UUID;
-  metadata?: Record<string, any>;
-}
-
-/**
- * Enhanced audit event payload for role revoked
- */
-export interface EnhancedRoleRevokedAuditEvent {
-  type: 'role_denied';
-  userId: UUID;
-  organisationId: UUID;
-  eventId?: string;
-  appId?: UUID;
-  role: string;
-  revokedBy: UUID;
-  metadata?: Record<string, any>;
-}
-
-/**
- * Enhanced audit event payload for RLS denied
- */
-export interface EnhancedRLSDeniedAuditEvent {
-  type: 'rls_denied';
-  userId: UUID;
-  organisationId: UUID;
-  table: string;
-  operation: string;
-  metadata?: Record<string, any>;
-}
-
-/**
- * Union type for all enhanced audit events
- */
-export type EnhancedAuditEventPayload = 
-  | EnhancedPermissionCheckAuditEvent
-  | EnhancedPermissionDeniedAuditEvent
-  | EnhancedRoleGrantedAuditEvent
-  | EnhancedRoleRevokedAuditEvent
-  | EnhancedRLSDeniedAuditEvent;
-
-/**
- * Enhanced RBAC Audit Manager
- * 
- * Handles emission of structured audit events with better error handling
- * and support for both authenticated and service role contexts.
- */
-export class EnhancedRBACAuditManager {
-  private supabase: SupabaseClient<Database>;
-  private enabled: boolean = true;
-  private fallbackEnabled: boolean = true;
-
-  constructor(supabase: SupabaseClient<Database>) {
-    this.supabase = supabase;
-  }
-
-  /**
-   * Enable or disable audit logging
-   * 
-   * @param enabled - Whether to enable audit logging
-   */
-  setEnabled(enabled: boolean): void {
-    this.enabled = enabled;
-  }
-
-  /**
-   * Enable or disable fallback logging (console logging when database fails)
-   * 
-   * @param enabled - Whether to enable fallback logging
-   */
-  setFallbackEnabled(enabled: boolean): void {
-    this.fallbackEnabled = enabled;
-  }
-
-  /**
-   * Check if audit logging is enabled
-   * 
-   * @returns True if audit logging is enabled
-   */
-  isEnabled(): boolean {
-    return this.enabled;
-  }
-
-  /**
-   * Emit an audit event with enhanced error handling
-   * 
-   * @param event - Audit event payload
-   * @returns Promise that resolves when event is logged
-   */
-  async emitEvent(event: EnhancedAuditEventPayload): Promise<void> {
-    if (!this.enabled) {
-      return;
-    }
-
-    // Validate required fields before attempting to insert
-    if (!event.userId || !event.organisationId) {
-      console.warn('[RBAC Audit] Skipping audit event - missing required fields:', {
-        userId: event.userId,
-        organisationId: event.organisationId,
-        eventType: event.type
-      });
-      return;
-    }
-
-    try {
-      const auditEvent: Omit<RBACAuditEvent, 'id' | 'created_at'> = {
-        event_type: event.type,
-        user_id: event.userId,
-        organisation_id: event.organisationId,
-        event_id: 'eventId' in event ? event.eventId : undefined,
-        app_id: 'appId' in event ? event.appId : undefined,
-        page_id: 'pageId' in event ? event.pageId : undefined,
-        permission: 'permission' in event ? event.permission : undefined,
-        decision: 'decision' in event ? event.decision : undefined,
-        source: 'source' in event ? event.source : 'api', // Default to 'api' if not provided
-        bypass: 'bypass' in event ? event.bypass : undefined,
-        duration_ms: 'duration_ms' in event ? event.duration_ms : undefined,
-        metadata: event.metadata || {},
-      };
-
-      const { error } = await (this.supabase as any)
-        .from('rbac_audit_events')
-        .insert([auditEvent]);
-
-      if (error) {
-        // Log the error for debugging
-        console.warn('[RBAC Audit] Failed to insert audit event:', {
-          error: error.message,
-          code: error.code,
-          details: error.details,
-          hint: error.hint,
-          event: auditEvent
-        });
-
-        // Use fallback logging if enabled
-        if (this.fallbackEnabled) {
-          this.logFallbackEvent(event, error);
-        }
-      }
-    } catch (error) {
-      // Log unexpected errors
-      console.error('[RBAC Audit] Unexpected error during audit logging:', error);
-      
-      // Use fallback logging if enabled
-      if (this.fallbackEnabled) {
-        this.logFallbackEvent(event, error);
-      }
-    }
-  }
-
-  /**
-   * Log event to console as fallback when database logging fails
-   * 
-   * @param event - Audit event payload
-   * @param error - The error that occurred
-   */
-  private logFallbackEvent(event: EnhancedAuditEventPayload, error: any): void {
-    console.log('[RBAC Audit Fallback]', {
-      timestamp: new Date().toISOString(),
-      event,
-      error: error?.message || error,
-      note: 'Database audit logging failed, using console fallback'
-    });
-  }
-
-  /**
-   * Emit a permission check audit event
-   * 
-   * @param event - Permission check event data
-   */
-  async emitPermissionCheck(event: Omit<EnhancedPermissionCheckAuditEvent, 'type'>): Promise<void> {
-    await this.emitEvent({
-      type: 'permission_check',
-      ...event,
-    });
-  }
-
-  /**
-   * Emit a permission denied audit event
-   * 
-   * @param event - Permission denied event data
-   */
-  async emitPermissionDenied(event: Omit<EnhancedPermissionDeniedAuditEvent, 'type'>): Promise<void> {
-    await this.emitEvent({
-      type: 'permission_denied',
-      ...event,
-    });
-  }
-
-  /**
-   * Emit a role granted audit event
-   * 
-   * @param event - Role granted event data
-   */
-  async emitRoleGranted(event: Omit<EnhancedRoleGrantedAuditEvent, 'type'>): Promise<void> {
-    await this.emitEvent({
-      type: 'role_granted',
-      ...event,
-    });
-  }
-
-  /**
-   * Emit a role revoked audit event
-   * 
-   * @param event - Role revoked event data
-   */
-  async emitRoleRevoked(event: Omit<EnhancedRoleRevokedAuditEvent, 'type'>): Promise<void> {
-    await this.emitEvent({
-      type: 'role_denied',
-      ...event,
-    });
-  }
-
-  /**
-   * Emit an RLS denied audit event
-   * 
-   * @param event - RLS denied event data
-   */
-  async emitRLSDenied(event: Omit<EnhancedRLSDeniedAuditEvent, 'type'>): Promise<void> {
-    await this.emitEvent({
-      type: 'rls_denied',
-      ...event,
-    });
-  }
-
-  /**
-   * Get audit events for a user
-   * 
-   * @param userId - User ID
-   * @param limit - Maximum number of events to return
-   * @returns Promise resolving to audit events
-   */
-  async getUserAuditEvents(userId: UUID, limit: number = 100): Promise<RBACAuditEvent[]> {
-    const { data, error } = await this.supabase
-      .from('rbac_audit_events')
-      .select('*')
-      .eq('user_id', userId)
-      .order('created_at', { ascending: false })
-      .limit(limit);
-
-    if (error) {
-      throw new Error(`Failed to get audit events: ${error.message}`);
-    }
-
-    return data || [];
-  }
-
-  /**
-   * Get audit events for an organisation
-   * 
-   * @param organisationId - Organisation ID
-   * @param limit - Maximum number of events to return
-   * @returns Promise resolving to audit events
-   */
-  async getOrganisationAuditEvents(organisationId: UUID, limit: number = 100): Promise<RBACAuditEvent[]> {
-    const { data, error } = await this.supabase
-      .from('rbac_audit_events')
-      .select('*')
-      .eq('organisation_id', organisationId)
-      .order('created_at', { ascending: false })
-      .limit(limit);
-
-    if (error) {
-      throw new Error(`Failed to get audit events: ${error.message}`);
-    }
-
-    return data || [];
-  }
-}
-
-/**
- * Create an enhanced audit manager instance
- * 
- * @param supabase - Supabase client
- * @returns EnhancedRBACAuditManager instance
- */
-export function createEnhancedAuditManager(supabase: SupabaseClient<Database>): EnhancedRBACAuditManager {
-  return new EnhancedRBACAuditManager(supabase);
-}