@jmruthers/pace-core 0.5.186 → 0.5.188

package/src/rbac/audit-batched.ts

@@ -0,0 +1,223 @@
+/**
+ * Batched Audit Manager for RBAC
+ * @package @jmruthers/pace-core
+ * @module RBAC/AuditBatched
+ * @since 2.0.0
+ * 
+ * This module provides batched audit logging to reduce network requests
+ * by queuing events and sending them in batches.
+ */
+
+import { SupabaseClient } from '@supabase/supabase-js';
+import { Database } from '../types/database';
+import { RBACAuditEvent, UUID } from './types';
+import { AuditEventPayload } from './audit';
+import { logger } from '../utils/core/logger';
+
+export interface BatchedAuditConfig {
+  /** Enable batched audit logging (default: true) */
+  enabled: boolean;
+  /** Time window in milliseconds to wait before sending batch (default: 100ms) */
+  batchWindow: number;
+  /** Maximum batch size before forcing send (default: 10) */
+  batchSize: number;
+}
+
+const DEFAULT_CONFIG: BatchedAuditConfig = {
+  enabled: true,
+  batchWindow: 500, // 500ms - increased for better batching
+  batchSize: 20, // Increased from 10 to 20 for better efficiency
+};
+
+/**
+ * Batched Audit Manager
+ * 
+ * Queues audit events and sends them in batches to reduce network requests.
+ */
+export class BatchedAuditManager {
+  private supabase: SupabaseClient<Database>;
+  private config: BatchedAuditConfig;
+  private eventQueue: Array<Omit<RBACAuditEvent, 'id' | 'created_at'>> = [];
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private isFlushing: boolean = false;
+
+  constructor(supabase: SupabaseClient<Database>, config: Partial<BatchedAuditConfig> = {}) {
+    this.supabase = supabase;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<BatchedAuditConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Queue an audit event for batching
+   * 
+   * @param event - Audit event payload
+   */
+  async queueEvent(event: AuditEventPayload): Promise<void> {
+    if (!this.config.enabled) {
+      // If batching is disabled, send immediately
+      await this.sendEventImmediately(event);
+      return;
+    }
+
+    // Skip audit logging for cached checks (only log on cache miss)
+    if ('cache_hit' in event && event.cache_hit === true) {
+      return;
+    }
+
+    // Convert event payload to database format
+    const auditEvent = this.convertToAuditEvent(event);
+    if (!auditEvent) {
+      return;
+    }
+
+    // Add to queue
+    this.eventQueue.push(auditEvent);
+
+    // Check if we should flush immediately
+    if (this.eventQueue.length >= this.config.batchSize) {
+      await this.flush();
+    } else {
+      // Schedule flush after batch window
+      this.scheduleFlush();
+    }
+  }
+
+  /**
+   * Convert audit event payload to database format
+   */
+  private convertToAuditEvent(event: AuditEventPayload): Omit<RBACAuditEvent, 'id' | 'created_at'> | null {
+    // Validate required fields
+    if (!event.userId) {
+      logger.error('RBAC Audit', 'Cannot queue audit event without userId:', {
+        eventType: event.type,
+        organisationId: event.organisationId
+      });
+      return null;
+    }
+
+    // Validate pageId: only include in page_id column if it's a valid UUID
+    const rawPageId = 'pageId' in event ? event.pageId : undefined;
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const isValidPageIdUuid = rawPageId && uuidRegex.test(rawPageId);
+    const pageIdUuid: UUID | undefined = isValidPageIdUuid ? (rawPageId as UUID) : undefined;
+    const pageIdName: string | undefined = rawPageId && !isValidPageIdUuid ? rawPageId : undefined;
+
+    return {
+      event_type: event.type,
+      user_id: event.userId,
+      organisation_id: event.organisationId || null,
+      event_id: 'eventId' in event ? event.eventId : undefined,
+      app_id: 'appId' in event ? event.appId : undefined,
+      page_id: pageIdUuid,
+      permission: 'permission' in event ? event.permission : undefined,
+      decision: 'decision' in event ? event.decision : undefined,
+      source: 'source' in event ? event.source : 'api',
+      bypass: 'bypass' in event ? event.bypass : undefined,
+      duration_ms: 'duration_ms' in event ? event.duration_ms : undefined,
+      metadata: {
+        ...event.metadata,
+        cache_hit: 'cache_hit' in event ? event.cache_hit : undefined,
+        cache_source: 'cache_source' in event ? event.cache_source : undefined,
+        no_organisation_context: !event.organisationId,
+        page_name: pageIdName,
+      },
+    };
+  }
+
+  /**
+   * Schedule a flush after the batch window
+   */
+  private scheduleFlush(): void {
+    if (this.flushTimer) {
+      return; // Already scheduled
+    }
+
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.flush();
+    }, this.config.batchWindow);
+  }
+
+  /**
+   * Flush all queued events
+   */
+  async flush(): Promise<void> {
+    if (this.isFlushing || this.eventQueue.length === 0) {
+      return;
+    }
+
+    // Clear any pending timer
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    this.isFlushing = true;
+
+    try {
+      // Get all events from queue
+      const eventsToSend = [...this.eventQueue];
+      this.eventQueue = [];
+
+      if (eventsToSend.length === 0) {
+        return;
+      }
+
+      // Send batch to database
+      const { error } = await (this.supabase as any)
+        .from('rbac_audit_events')
+        .insert(eventsToSend);
+
+      if (error) {
+        logger.warn('RBAC Audit', 'Failed to insert batched audit events:', {
+          error: error.message,
+          code: error.code,
+          batchSize: eventsToSend.length,
+        });
+      }
+    } catch (error) {
+      logger.error('RBAC Audit', 'Unexpected error during batched audit logging:', error);
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+
+  /**
+   * Send event immediately (bypass batching)
+   */
+  private async sendEventImmediately(event: AuditEventPayload): Promise<void> {
+    const auditEvent = this.convertToAuditEvent(event);
+    if (!auditEvent) {
+      return;
+    }
+
+    try {
+      const { error } = await (this.supabase as any)
+        .from('rbac_audit_events')
+        .insert([auditEvent]);
+
+      if (error) {
+        logger.warn('RBAC Audit', 'Failed to insert audit event:', {
+          error: error.message,
+          code: error.code,
+        });
+      }
+    } catch (error) {
+      logger.error('RBAC Audit', 'Unexpected error during audit logging:', error);
+    }
+  }
+
+  /**
+   * Force flush and wait for completion
+   */
+  async forceFlush(): Promise<void> {
+    await this.flush();
+  }
+}
+

package/src/rbac/audit-enhanced.ts

@@ -294,7 +294,7 @@ export class EnhancedRBACAuditManager {
   async getUserAuditEvents(userId: UUID, limit: number = 100): Promise<RBACAuditEvent[]> {
     const { data, error } = await this.supabase
       .from('rbac_audit_events')
-      .select('*')
+      .select('id, event_type, user_id, organisation_id, event_id, app_id, page_id, permission, decision, source, bypass, duration_ms, metadata, created_at')
       .eq('user_id', userId)
       .order('created_at', { ascending: false })
       .limit(limit);
@@ -338,7 +338,7 @@ export class EnhancedRBACAuditManager {
   async getOrganisationAuditEvents(organisationId: UUID, limit: number = 100): Promise<RBACAuditEvent[]> {
     const { data, error } = await this.supabase
       .from('rbac_audit_events')
-      .select('*')
+      .select('id, event_type, user_id, organisation_id, event_id, app_id, page_id, permission, decision, source, bypass, duration_ms, metadata, created_at')
       .eq('organisation_id', organisationId)
       .order('created_at', { ascending: false })
       .limit(limit);

package/src/rbac/audit.test.ts

@@ -60,7 +60,8 @@ describe('RBACAuditManager', () => {
 
   beforeEach(() => {
     mockSupabase = createMockSupabaseClient();
-    auditManager = new RBACAuditManager(mockSupabase as any);
+    // Disable batching in tests for predictable behavior
+    auditManager = new RBACAuditManager(mockSupabase as any, false);
   });
 
   afterEach(() => {
@@ -544,7 +545,7 @@ describe('RBACAuditManager', () => {
         source: 'ui' as AuditEventSource,
         bypass: true,
         duration_ms: 250,
-        cache_hit: true,
+        cache_hit: false, // Set to false so event is actually logged (cached events are skipped)
         cache_source: 'memory',
         metadata: { test: 'data' }
       };
@@ -567,7 +568,7 @@ describe('RBACAuditManager', () => {
             source: 'ui',
             bypass: true,
             duration_ms: 250,
-            cache_hit: true,
+            cache_hit: false,
             cache_source: 'memory',
             metadata: { test: 'data' }
           }),
@@ -648,7 +649,7 @@ describe('Global Audit Manager', () => {
   });
 
   it('creates and sets global audit manager', () => {
-    const manager = createAuditManager(mockSupabase as any);
+    const manager = createAuditManager(mockSupabase as any, false);
     setGlobalAuditManager(manager);
 
     const globalManager = getGlobalAuditManager();
@@ -656,7 +657,7 @@ describe('Global Audit Manager', () => {
   });
 
   it('emits events through global manager', async () => {
-    const manager = createAuditManager(mockSupabase as any);
+    const manager = createAuditManager(mockSupabase as any, false);
     setGlobalAuditManager(manager);
 
     const event: PermissionCheckAuditEvent = {

package/src/rbac/audit.ts

@@ -16,6 +16,7 @@ import {
 } from './types';
 import type { AuditEventType } from './types/functions';
 import { logger } from '../utils/core/logger';
+import { BatchedAuditManager } from './audit-batched';
 
 /**
  * Audit event payload for permission checks
@@ -111,9 +112,19 @@ export class RBACAuditManager {
   private supabase: SupabaseClient<Database>;
   private enabled: boolean = true;
   private fallbackEnabled: boolean = true;
-
-  constructor(supabase: SupabaseClient<Database>) {
+  private batchedManager: BatchedAuditManager | null = null;
+  private useBatching: boolean = true;
+
+  constructor(
+    supabase: SupabaseClient<Database>, 
+    useBatching: boolean = true,
+    batchConfig?: { batchWindow?: number; batchSize?: number }
+  ) {
     this.supabase = supabase;
+    this.useBatching = useBatching;
+    if (useBatching) {
+      this.batchedManager = new BatchedAuditManager(supabase, batchConfig);
+    }
   }
 
   /**
@@ -154,6 +165,17 @@ export class RBACAuditManager {
       return;
     }
 
+    // Skip audit logging for cached checks (only log on cache miss)
+    if ('cache_hit' in event && event.cache_hit === true) {
+      return;
+    }
+
+    // Use batched manager if enabled
+    if (this.useBatching && this.batchedManager) {
+      await this.batchedManager.queueEvent(event);
+      return;
+    }
+
     // Validate required fields before attempting to insert
     // MANDATORY: All audit events must have userId
     if (!event.userId) {
@@ -332,7 +354,7 @@ export class RBACAuditManager {
   async getUserAuditEvents(userId: UUID, limit: number = 100): Promise<RBACAuditEvent[]> {
     const { data, error } = await this.supabase
       .from('rbac_audit_events')
-      .select('*')
+      .select('id, event_type, user_id, organisation_id, event_id, app_id, page_id, permission, decision, source, bypass, duration_ms, metadata, created_at')
       .eq('user_id', userId)
       .order('created_at', { ascending: false })
       .limit(limit);
@@ -376,7 +398,7 @@ export class RBACAuditManager {
   async getOrganisationAuditEvents(organisationId: UUID, limit: number = 100): Promise<RBACAuditEvent[]> {
     const { data, error } = await this.supabase
       .from('rbac_audit_events')
-      .select('*')
+      .select('id, event_type, user_id, organisation_id, event_id, app_id, page_id, permission, decision, source, bypass, duration_ms, metadata, created_at')
       .eq('organisation_id', organisationId)
       .order('created_at', { ascending: false })
       .limit(limit);
@@ -415,10 +437,16 @@ export class RBACAuditManager {
  * Create an audit manager instance
  * 
  * @param supabase - Supabase client
+ * @param useBatching - Whether to use batched audit logging (default: true)
+ * @param batchConfig - Optional batch configuration
  * @returns RBACAuditManager instance
  */
-export function createAuditManager(supabase: SupabaseClient<Database>): RBACAuditManager {
-  return new RBACAuditManager(supabase);
+export function createAuditManager(
+  supabase: SupabaseClient<Database>, 
+  useBatching: boolean = true,
+  batchConfig?: { batchWindow?: number; batchSize?: number }
+): RBACAuditManager {
+  return new RBACAuditManager(supabase, useBatching, batchConfig);
 }
 
 /**

package/src/rbac/cache-invalidation.ts

@@ -67,6 +67,7 @@ export const INVALIDATION_PATTERNS = {
 export class RBACCacheInvalidationManager {
   private supabase: SupabaseClient<Database>;
   private invalidationCallbacks: Set<(pattern: string) => void> = new Set();
+  private channels: Array<{ unsubscribe: () => void }> = [];
 
   constructor(supabase: SupabaseClient<Database>) {
     this.supabase = supabase;
@@ -179,6 +180,7 @@ export class RBACCacheInvalidationManager {
 
   /**
    * Setup realtime subscriptions for automatic cache invalidation
+   * Prevents duplicate subscriptions by checking if already set up
    */
   private setupRealtimeSubscriptions(): void {
     // Check if realtime is available (skip in test environments)
@@ -186,9 +188,15 @@ export class RBACCacheInvalidationManager {
       log.debug('Realtime not available, skipping subscriptions');
       return;
     }
+    
+    // Prevent duplicate subscriptions - if channels already exist, skip setup
+    if (this.channels.length > 0) {
+      log.debug('Realtime subscriptions already set up, skipping duplicate setup');
+      return;
+    }
 
     // Subscribe to organisation role changes
-    this.supabase
+    const orgRolesChannel = this.supabase
       .channel('rbac_organisation_roles_changes')
       .on('postgres_changes', {
         event: '*',
@@ -202,11 +210,12 @@ export class RBACCacheInvalidationManager {
         if (user_id) {
           this.invalidateUser(user_id, `organisation_role_${payload.eventType}`);
         }
-      })
-      .subscribe();
+      });
+    const orgRolesSubscription = orgRolesChannel.subscribe();
+    this.channels.push(orgRolesSubscription);
 
     // Subscribe to event app role changes
-    this.supabase
+    const eventAppRolesChannel = this.supabase
       .channel('rbac_event_app_roles_changes')
       .on('postgres_changes', {
         event: '*',
@@ -226,11 +235,12 @@ export class RBACCacheInvalidationManager {
         if (app_id) {
           this.invalidateApp(app_id, `event_app_role_${payload.eventType}`);
         }
-      })
-      .subscribe();
+      });
+    const eventAppRolesSubscription = eventAppRolesChannel.subscribe();
+    this.channels.push(eventAppRolesSubscription);
 
     // Subscribe to global role changes
-    this.supabase
+    const globalRolesChannel = this.supabase
       .channel('rbac_global_roles_changes')
       .on('postgres_changes', {
         event: '*',
@@ -241,11 +251,12 @@ export class RBACCacheInvalidationManager {
         if (user_id) {
           this.invalidateUser(user_id, `global_role_${payload.eventType}`);
         }
-      })
-      .subscribe();
+      });
+    const globalRolesSubscription = globalRolesChannel.subscribe();
+    this.channels.push(globalRolesSubscription);
 
     // Subscribe to page permission changes
-    this.supabase
+    const pagePermissionsChannel = this.supabase
       .channel('rbac_page_permissions_changes')
       .on('postgres_changes', {
         event: '*',
@@ -261,8 +272,30 @@ export class RBACCacheInvalidationManager {
         }
         // Note: We can't easily get user_id from role_id without additional query
         // This is a limitation of the current schema design
-      })
-      .subscribe();
+      });
+    const pagePermissionsSubscription = pagePermissionsChannel.subscribe();
+    this.channels.push(pagePermissionsSubscription);
+  }
+
+  /**
+   * Cleanup all realtime subscriptions
+   * Call this when the manager is no longer needed to prevent memory leaks
+   */
+  cleanup(): void {
+    // Unsubscribe from all channels
+    this.channels.forEach(channel => {
+      try {
+        if (channel && typeof channel.unsubscribe === 'function') {
+          channel.unsubscribe();
+        }
+      } catch (error) {
+        log.warn('Failed to unsubscribe from channel:', error);
+      }
+    });
+    this.channels = [];
+    
+    // Clear all callbacks
+    this.invalidationCallbacks.clear();
   }
 
   /**
@@ -302,11 +335,18 @@ let globalCacheInvalidationManager: RBACCacheInvalidationManager | null = null;
 
 /**
  * Initialize the global cache invalidation manager
+ * Ensures only one instance exists per application lifecycle
  * 
  * @param supabase - Supabase client
  * @returns Cache invalidation manager instance
  */
 export function initializeCacheInvalidation(supabase: SupabaseClient<Database>): RBACCacheInvalidationManager {
+  // Clean up existing manager if it exists (e.g., when switching Supabase clients)
+  if (globalCacheInvalidationManager) {
+    log.debug('Cleaning up existing cache invalidation manager before creating new one');
+    globalCacheInvalidationManager.cleanup();
+  }
+  
   globalCacheInvalidationManager = new RBACCacheInvalidationManager(supabase);
   return globalCacheInvalidationManager;
 }
@@ -319,3 +359,14 @@ export function initializeCacheInvalidation(supabase: SupabaseClient<Database>):
 export function getCacheInvalidationManager(): RBACCacheInvalidationManager | null {
   return globalCacheInvalidationManager;
 }
+
+/**
+ * Cleanup the global cache invalidation manager
+ * Call this when the application is shutting down or when switching Supabase clients
+ */
+export function cleanupCacheInvalidation(): void {
+  if (globalCacheInvalidationManager) {
+    globalCacheInvalidationManager.cleanup();
+    globalCacheInvalidationManager = null;
+  }
+}

package/src/rbac/cache.test.ts

@@ -81,8 +81,8 @@ describe('RBACCache', () => {
       mockDateNow.mockReturnValue(startTime);
       testCache.set('test-key', 'test-value');
       
-      // Advance time by 60 seconds (default TTL) + 1ms to ensure expiration
-      mockDateNow.mockReturnValue(startTime + 60001);
+      // Advance time by 120 seconds (default TTL) + 1ms to ensure expiration
+      mockDateNow.mockReturnValue(startTime + 120001);
       expect(testCache.get('test-key')).toBeNull();
       
       mockDateNow.mockRestore();

package/src/rbac/cache.ts

@@ -13,32 +13,50 @@ import { CacheEntry, PermissionCacheKey } from './types';
 /**
  * In-memory cache for RBAC operations
  * 
- * Provides 60-second TTL and pattern-based invalidation for permission checks.
+ * Provides two-tier caching:
+ * - Short-term cache: 120 seconds for frequently changing permissions
+ * - Session cache: 15 minutes for stable permissions (page-level checks)
  */
 export class RBACCache {
   private cache = new Map<string, CacheEntry<any>>();
-  private readonly TTL = 60 * 1000; // 60 seconds
+  private sessionCache = new Map<string, CacheEntry<any>>();
+  private readonly TTL = 120 * 1000; // 120 seconds (short-term) - increased from 60s
+  private readonly SESSION_TTL = 15 * 60 * 1000; // 15 minutes (session-level) - increased from 5min
   private invalidationCallbacks: Set<(pattern: string) => void> = new Set();
 
   /**
    * Get a value from the cache
    * 
+   * Checks both short-term cache and session cache.
+   * 
    * @param key - Cache key
+   * @param useSessionCache - Whether to check session cache (default: true)
    * @returns Cached value or null if not found/expired
    */
-  get<T>(key: string): T | null {
-    const entry = this.cache.get(key);
+  get<T>(key: string, useSessionCache: boolean = true): T | null {
+    const now = Date.now();
     
-    if (!entry) {
-      return null;
+    // Check short-term cache first
+    const entry = this.cache.get(key);
+    if (entry && now <= entry.expires) {
+      return entry.data as T;
     }
-
-    if (Date.now() > entry.expires) {
+    if (entry && now > entry.expires) {
       this.cache.delete(key);
-      return null;
     }
-
-    return entry.data as T;
+    
+    // Check session cache if enabled
+    if (useSessionCache) {
+      const sessionEntry = this.sessionCache.get(key);
+      if (sessionEntry && now <= sessionEntry.expires) {
+        return sessionEntry.data as T;
+      }
+      if (sessionEntry && now > sessionEntry.expires) {
+        this.sessionCache.delete(key);
+      }
+    }
+    
+    return null;
   }
 
   /**
@@ -47,14 +65,27 @@ export class RBACCache {
    * @param key - Cache key
    * @param data - Data to cache
    * @param ttl - Time to live in milliseconds (defaults to 60s)
+   * @param useSessionCache - Whether to also store in session cache (default: false for page-level checks)
    */
-  set<T>(key: string, data: T, ttl: number = this.TTL): void {
+  set<T>(key: string, data: T, ttl: number = this.TTL, useSessionCache: boolean = false): void {
+    const now = Date.now();
     // For zero or negative TTL, set expires to current time to make it immediately expired
-    const expires = ttl <= 0 ? Date.now() - 1 : Date.now() + ttl;
+    const expires = ttl <= 0 ? now - 1 : now + ttl;
+    
+    // Always store in short-term cache
     this.cache.set(key, {
       data,
       expires,
     });
+    
+    // Optionally store in session cache for page-level permissions
+    if (useSessionCache) {
+      const sessionExpires = ttl <= 0 ? now - 1 : now + this.SESSION_TTL;
+      this.sessionCache.set(key, {
+        data,
+        expires: sessionExpires,
+      });
+    }
   }
 
   /**
@@ -64,6 +95,7 @@ export class RBACCache {
    */
   delete(key: string): void {
     this.cache.delete(key);
+    this.sessionCache.delete(key);
   }
 
   /**
@@ -81,13 +113,23 @@ export class RBACCache {
     const matcher = this.createMatcher(trimmedPattern);
     const keysToDelete: string[] = [];
 
+    // Invalidate from both caches
     for (const key of this.cache.keys()) {
       if (matcher(key)) {
         keysToDelete.push(key);
       }
     }
+    
+    for (const key of this.sessionCache.keys()) {
+      if (matcher(key) && !keysToDelete.includes(key)) {
+        keysToDelete.push(key);
+      }
+    }
 
-    keysToDelete.forEach(key => this.cache.delete(key));
+    keysToDelete.forEach(key => {
+      this.cache.delete(key);
+      this.sessionCache.delete(key);
+    });
 
     // Notify invalidation callbacks
     this.invalidationCallbacks.forEach(callback => callback(trimmedPattern));
@@ -111,6 +153,7 @@ export class RBACCache {
    */
   clear(): void {
     this.cache.clear();
+    this.sessionCache.clear();
   }
 
   /**
@@ -118,12 +161,16 @@ export class RBACCache {
    */
   getStats(): {
     size: number;
+    sessionSize: number;
     ttl: number;
+    sessionTtl: number;
     keys: string[];
   } {
     return {
       size: this.cache.size,
+      sessionSize: this.sessionCache.size,
       ttl: this.TTL,
+      sessionTtl: this.SESSION_TTL,
       keys: Array.from(this.cache.keys()),
     };
   }