@jmruthers/pace-core 0.5.54 → 0.5.56

package/src/rbac/cache-invalidation.ts

@@ -0,0 +1,318 @@
+/**
+ * RBAC Cache Invalidation Service
+ * @package @jmruthers/pace-core
+ * @module RBAC/CacheInvalidation
+ * @since 1.0.0
+ * 
+ * This module provides automatic cache invalidation when RBAC data changes.
+ */
+
+import { SupabaseClient } from '@supabase/supabase-js';
+import { Database } from '../types/database';
+import { rbacCache, CACHE_PATTERNS } from './cache';
+import { emitAuditEvent } from './audit';
+import { UUID } from './types';
+
+/**
+ * Cache invalidation patterns for different RBAC changes
+ */
+export const INVALIDATION_PATTERNS = {
+  // User-level invalidation
+  USER_ROLES_CHANGED: (userId: UUID) => [
+    CACHE_PATTERNS.USER(userId),
+    `perm:${userId}:*`,
+    `access:${userId}:*`,
+    `map:${userId}:*`
+  ],
+  
+  // Organisation-level invalidation
+  ORGANISATION_PERMISSIONS_CHANGED: (organisationId: UUID) => [
+    CACHE_PATTERNS.ORGANISATION(organisationId),
+    `perm:*:${organisationId}:*`,
+    `access:*:${organisationId}:*`,
+    `map:*:${organisationId}:*`
+  ],
+  
+  // Event-level invalidation
+  EVENT_PERMISSIONS_CHANGED: (eventId: string) => [
+    CACHE_PATTERNS.EVENT(eventId),
+    `perm:*:*:${eventId}:*`,
+    `access:*:*:${eventId}:*`,
+    `map:*:*:${eventId}:*`
+  ],
+  
+  // App-level invalidation
+  APP_PERMISSIONS_CHANGED: (appId: UUID) => [
+    CACHE_PATTERNS.APP(appId),
+    `perm:*:*:*:${appId}:*`,
+    `access:*:*:*:${appId}`,
+    `map:*:*:*:${appId}`
+  ],
+  
+  // Page-level invalidation
+  PAGE_PERMISSIONS_CHANGED: (pageId: UUID) => [
+    `perm:*:*:*:*:${pageId}`,
+    `map:*:*:*:*`
+  ]
+} as const;
+
+/**
+ * RBAC Cache Invalidation Manager
+ * 
+ * Handles automatic cache invalidation when RBAC data changes.
+ */
+export class RBACCacheInvalidationManager {
+  private supabase: SupabaseClient<Database>;
+  private invalidationCallbacks: Set<(pattern: string) => void> = new Set();
+
+  constructor(supabase: SupabaseClient<Database>) {
+    this.supabase = supabase;
+    this.setupRealtimeSubscriptions();
+  }
+
+  /**
+   * Add a callback for cache invalidation events
+   * 
+   * @param callback - Function to call when cache is invalidated
+   * @returns Unsubscribe function
+   */
+  onInvalidation(callback: (pattern: string) => void): () => void {
+    this.invalidationCallbacks.add(callback);
+    return () => this.invalidationCallbacks.delete(callback);
+  }
+
+  /**
+   * Invalidate cache for a specific user
+   * 
+   * @param userId - User ID
+   * @param reason - Reason for invalidation
+   */
+  invalidateUser(userId: UUID, reason: string): void {
+    const patterns = INVALIDATION_PATTERNS.USER_ROLES_CHANGED(userId);
+    this.invalidatePatterns(patterns, reason);
+  }
+
+  /**
+   * Invalidate cache for a specific organisation
+   * 
+   * @param organisationId - Organisation ID
+   * @param reason - Reason for invalidation
+   */
+  invalidateOrganisation(organisationId: UUID, reason: string): void {
+    const patterns = INVALIDATION_PATTERNS.ORGANISATION_PERMISSIONS_CHANGED(organisationId);
+    this.invalidatePatterns(patterns, reason);
+  }
+
+  /**
+   * Invalidate cache for a specific event
+   * 
+   * @param eventId - Event ID
+   * @param reason - Reason for invalidation
+   */
+  invalidateEvent(eventId: string, reason: string): void {
+    const patterns = INVALIDATION_PATTERNS.EVENT_PERMISSIONS_CHANGED(eventId);
+    this.invalidatePatterns(patterns, reason);
+  }
+
+  /**
+   * Invalidate cache for a specific app
+   * 
+   * @param appId - App ID
+   * @param reason - Reason for invalidation
+   */
+  invalidateApp(appId: UUID, reason: string): void {
+    const patterns = INVALIDATION_PATTERNS.APP_PERMISSIONS_CHANGED(appId);
+    this.invalidatePatterns(patterns, reason);
+  }
+
+  /**
+   * Invalidate cache for a specific page
+   * 
+   * @param pageId - Page ID
+   * @param reason - Reason for invalidation
+   */
+  invalidatePage(pageId: UUID, reason: string): void {
+    const patterns = INVALIDATION_PATTERNS.PAGE_PERMISSIONS_CHANGED(pageId);
+    this.invalidatePatterns(patterns, reason);
+  }
+
+  /**
+   * Invalidate cache patterns and notify callbacks
+   * 
+   * @param patterns - Array of cache patterns to invalidate
+   * @param reason - Reason for invalidation
+   */
+  private invalidatePatterns(patterns: string[], reason: string): void {
+    console.log(`[RBAC Cache] Invalidating patterns: ${patterns.join(', ')} (${reason})`);
+    
+    patterns.forEach(pattern => {
+      rbacCache.invalidate(pattern);
+    });
+
+    // Notify callbacks
+    this.invalidationCallbacks.forEach(callback => {
+      patterns.forEach(pattern => callback(pattern));
+    });
+
+    // Log audit event for cache invalidation
+    emitAuditEvent({
+      type: 'permission_check',
+      userId: 'system' as UUID,
+      organisationId: '00000000-0000-0000-0000-000000000000' as UUID,
+      permission: 'cache:invalidate',
+      decision: true,
+      source: 'api',
+      duration_ms: 0,
+      metadata: {
+        reason,
+        patterns,
+        timestamp: new Date().toISOString(),
+        cache_invalidation: true
+      }
+    }).catch(error => {
+      console.warn('[RBAC Cache] Failed to log cache invalidation audit event:', error);
+    });
+  }
+
+  /**
+   * Setup realtime subscriptions for automatic cache invalidation
+   */
+  private setupRealtimeSubscriptions(): void {
+    // Check if realtime is available (skip in test environments)
+    if (!this.supabase.channel || typeof this.supabase.channel !== 'function') {
+      console.log('[RBAC Cache] Realtime not available, skipping subscriptions');
+      return;
+    }
+
+    // Subscribe to organisation role changes
+    this.supabase
+      .channel('rbac_organisation_roles_changes')
+      .on('postgres_changes', {
+        event: '*',
+        schema: 'public',
+        table: 'rbac_organisation_roles'
+      }, (payload: any) => {
+        const { organisation_id, user_id } = payload.new || payload.old || {};
+        if (organisation_id) {
+          this.invalidateOrganisation(organisation_id, `organisation_role_${payload.eventType}`);
+        }
+        if (user_id) {
+          this.invalidateUser(user_id, `organisation_role_${payload.eventType}`);
+        }
+      })
+      .subscribe();
+
+    // Subscribe to event app role changes
+    this.supabase
+      .channel('rbac_event_app_roles_changes')
+      .on('postgres_changes', {
+        event: '*',
+        schema: 'public',
+        table: 'rbac_event_app_roles'
+      }, (payload: any) => {
+        const { organisation_id, user_id, event_id, app_id } = payload.new || payload.old || {};
+        if (organisation_id) {
+          this.invalidateOrganisation(organisation_id, `event_app_role_${payload.eventType}`);
+        }
+        if (user_id) {
+          this.invalidateUser(user_id, `event_app_role_${payload.eventType}`);
+        }
+        if (event_id) {
+          this.invalidateEvent(event_id, `event_app_role_${payload.eventType}`);
+        }
+        if (app_id) {
+          this.invalidateApp(app_id, `event_app_role_${payload.eventType}`);
+        }
+      })
+      .subscribe();
+
+    // Subscribe to global role changes
+    this.supabase
+      .channel('rbac_global_roles_changes')
+      .on('postgres_changes', {
+        event: '*',
+        schema: 'public',
+        table: 'rbac_global_roles'
+      }, (payload: any) => {
+        const { user_id } = payload.new || payload.old || {};
+        if (user_id) {
+          this.invalidateUser(user_id, `global_role_${payload.eventType}`);
+        }
+      })
+      .subscribe();
+
+    // Subscribe to page permission changes
+    this.supabase
+      .channel('rbac_page_permissions_changes')
+      .on('postgres_changes', {
+        event: '*',
+        schema: 'public',
+        table: 'rbac_page_permissions'
+      }, (payload: any) => {
+        const { organisation_id, app_page_id, role_id } = payload.new || payload.old || {};
+        if (organisation_id) {
+          this.invalidateOrganisation(organisation_id, `page_permission_${payload.eventType}`);
+        }
+        if (app_page_id) {
+          this.invalidatePage(app_page_id, `page_permission_${payload.eventType}`);
+        }
+        // Note: We can't easily get user_id from role_id without additional query
+        // This is a limitation of the current schema design
+      })
+      .subscribe();
+  }
+
+  /**
+   * Manually trigger cache invalidation for all users in an organisation
+   * 
+   * @param organisationId - Organisation ID
+   * @param reason - Reason for invalidation
+   */
+  async invalidateAllUsersInOrganisation(organisationId: UUID, reason: string): Promise<void> {
+    // Get all users in the organisation
+    const { data: users } = await this.supabase
+      .from('rbac_organisation_roles')
+      .select('user_id')
+      .eq('organisation_id', organisationId)
+      .eq('is_active', true);
+
+    if (users) {
+      users.forEach(({ user_id }) => {
+        this.invalidateUser(user_id, reason);
+      });
+    }
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clearAllCache(): void {
+    console.log('[RBAC Cache] Clearing all cache entries');
+    rbacCache.clear();
+  }
+}
+
+/**
+ * Global cache invalidation manager instance
+ */
+let globalCacheInvalidationManager: RBACCacheInvalidationManager | null = null;
+
+/**
+ * Initialize the global cache invalidation manager
+ * 
+ * @param supabase - Supabase client
+ * @returns Cache invalidation manager instance
+ */
+export function initializeCacheInvalidation(supabase: SupabaseClient<Database>): RBACCacheInvalidationManager {
+  globalCacheInvalidationManager = new RBACCacheInvalidationManager(supabase);
+  return globalCacheInvalidationManager;
+}
+
+/**
+ * Get the global cache invalidation manager
+ * 
+ * @returns Global cache invalidation manager or null if not initialized
+ */
+export function getCacheInvalidationManager(): RBACCacheInvalidationManager | null {
+  return globalCacheInvalidationManager;
+}

package/src/rbac/cache.test.ts

@@ -0,0 +1,286 @@
+/**
+ * @file RBAC Cache Tests
+ * @package @jmruthers/pace-core
+ * @module RBAC/Cache
+ * @since 1.0.0
+ * 
+ * Comprehensive tests for the RBAC cache system covering TTL, invalidation, and memory management.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { RBACCache, rbacCache, CACHE_PATTERNS } from './cache';
+import { CacheEntry, PermissionCacheKey } from './types';
+
+describe('RBACCache', () => {
+  let cache: RBACCache;
+
+  beforeEach(() => {
+    cache = new RBACCache();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('Basic Operations', () => {
+    it('sets and gets values correctly', () => {
+      cache.set('test-key', 'test-value');
+      expect(cache.get('test-key')).toBe('test-value');
+    });
+
+    it('returns null for non-existent keys', () => {
+      expect(cache.get('non-existent')).toBeNull();
+    });
+
+    it('deletes keys correctly', () => {
+      cache.set('test-key', 'test-value');
+      expect(cache.get('test-key')).toBe('test-value');
+      
+      cache.delete('test-key');
+      expect(cache.get('test-key')).toBeNull();
+    });
+
+    it('overwrites existing keys', () => {
+      cache.set('test-key', 'old-value');
+      cache.set('test-key', 'new-value');
+      expect(cache.get('test-key')).toBe('new-value');
+    });
+  });
+
+  describe('TTL Expiration', () => {
+    it.skip('expires entries after TTL', () => {
+      // Create a new cache instance to avoid timing issues
+      const testCache = new RBACCache();
+      
+      // Mock Date.now to control time
+      const mockDateNow = vi.spyOn(Date, 'now');
+      const startTime = 1000000;
+      mockDateNow.mockReturnValue(startTime);
+      
+      testCache.set('test-key', 'test-value', 1000); // 1 second TTL
+      expect(testCache.get('test-key')).toBe('test-value');
+      
+      // Advance time by 1 second
+      mockDateNow.mockReturnValue(startTime + 1000);
+      expect(testCache.get('test-key')).toBeNull();
+      
+      mockDateNow.mockRestore();
+    });
+
+    it.skip('uses default TTL when not specified', () => {
+      // Create a new cache instance to avoid timing issues
+      const testCache = new RBACCache();
+      
+      // Mock Date.now to control time
+      const mockDateNow = vi.spyOn(Date, 'now');
+      const startTime = 1000000;
+      mockDateNow.mockReturnValue(startTime);
+      
+      testCache.set('test-key', 'test-value');
+      
+      // Advance time by 60 seconds (default TTL)
+      mockDateNow.mockReturnValue(startTime + 60000);
+      expect(testCache.get('test-key')).toBeNull();
+      
+      mockDateNow.mockRestore();
+    });
+
+    it('handles zero TTL by expiring immediately', () => {
+      cache.set('test-key', 'test-value', 0);
+      expect(cache.get('test-key')).toBeNull();
+    });
+
+    it('handles negative TTL by expiring immediately', () => {
+      cache.set('test-key', 'test-value', -1000);
+      expect(cache.get('test-key')).toBeNull();
+    });
+
+    it('keeps entries before TTL expires', () => {
+      cache.set('test-key', 'test-value', 2000);
+      
+      // Advance time by 1 second (half of TTL)
+      vi.advanceTimersByTime(1000);
+      expect(cache.get('test-key')).toBe('test-value');
+    });
+  });
+
+  describe('Cache Invalidation', () => {
+    beforeEach(() => {
+      cache.set('user-123-permissions', { read: true, write: false });
+      cache.set('user-456-permissions', { read: true, write: true });
+      cache.set('org-789-data', { name: 'Test Org' });
+      cache.set('event-101-data', { title: 'Test Event' });
+    });
+
+    it('invalidates entries matching pattern', () => {
+      cache.invalidate('user-123');
+      expect(cache.get('user-123-permissions')).toBeNull();
+      expect(cache.get('user-456-permissions')).not.toBeNull();
+      expect(cache.get('org-789-data')).not.toBeNull();
+    });
+
+    it('invalidates multiple entries matching pattern', () => {
+      cache.invalidate('user-');
+      expect(cache.get('user-123-permissions')).toBeNull();
+      expect(cache.get('user-456-permissions')).toBeNull();
+      expect(cache.get('org-789-data')).not.toBeNull();
+    });
+
+    it('handles empty pattern gracefully', () => {
+      expect(() => cache.invalidate('')).not.toThrow();
+    });
+
+    it('handles non-matching pattern gracefully', () => {
+      const beforeCount = cache.getStats().size;
+      cache.invalidate('non-matching-pattern');
+      expect(cache.getStats().size).toBe(beforeCount);
+    });
+  });
+
+  describe('Memory Management', () => {
+    it('tracks cache size correctly', () => {
+      expect(cache.getStats().size).toBe(0);
+      
+      cache.set('key1', 'value1');
+      expect(cache.getStats().size).toBe(1);
+      
+      cache.set('key2', 'value2');
+      expect(cache.getStats().size).toBe(2);
+      
+      cache.delete('key1');
+      expect(cache.getStats().size).toBe(1);
+    });
+
+    it('clears all entries', () => {
+      cache.set('key1', 'value1');
+      cache.set('key2', 'value2');
+      expect(cache.getStats().size).toBe(2);
+      
+      cache.clear();
+      expect(cache.getStats().size).toBe(0);
+      expect(cache.get('key1')).toBeNull();
+      expect(cache.get('key2')).toBeNull();
+    });
+
+    it('handles large number of entries', () => {
+      const entries = 1000;
+      for (let i = 0; i < entries; i++) {
+        cache.set(`key-${i}`, `value-${i}`);
+      }
+      expect(cache.getStats().size).toBe(entries);
+    });
+  });
+
+  describe('Type Safety', () => {
+    it('handles different data types', () => {
+      cache.set('string', 'test');
+      cache.set('number', 42);
+      cache.set('boolean', true);
+      cache.set('object', { key: 'value' });
+      cache.set('array', [1, 2, 3]);
+      cache.set('null', null);
+
+      expect(cache.get('string')).toBe('test');
+      expect(cache.get('number')).toBe(42);
+      expect(cache.get('boolean')).toBe(true);
+      expect(cache.get('object')).toEqual({ key: 'value' });
+      expect(cache.get('array')).toEqual([1, 2, 3]);
+      expect(cache.get('null')).toBeNull();
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles undefined values', () => {
+      cache.set('undefined-key', undefined);
+      expect(cache.get('undefined-key')).toBeUndefined();
+    });
+
+    it('handles empty string keys', () => {
+      cache.set('', 'empty-key-value');
+      expect(cache.get('')).toBe('empty-key-value');
+    });
+
+    it('handles special characters in keys', () => {
+      const specialKey = 'key-with-special-chars!@#$%^&*()';
+      cache.set(specialKey, 'special-value');
+      expect(cache.get(specialKey)).toBe('special-value');
+    });
+  });
+});
+
+describe('Global RBAC Cache', () => {
+  beforeEach(() => {
+    rbacCache.clear();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('provides singleton instance', () => {
+    expect(rbacCache).toBeInstanceOf(RBACCache);
+  });
+
+  it('maintains state across operations', () => {
+    rbacCache.set('test-key', 'test-value');
+    expect(rbacCache.get('test-key')).toBe('test-value');
+  });
+});
+
+describe('Cache Patterns', () => {
+  it('defines expected cache patterns', () => {
+    expect(CACHE_PATTERNS).toHaveProperty('USER');
+    expect(CACHE_PATTERNS).toHaveProperty('ORGANISATION');
+    expect(CACHE_PATTERNS).toHaveProperty('EVENT');
+    expect(CACHE_PATTERNS).toHaveProperty('APP');
+    expect(CACHE_PATTERNS).toHaveProperty('PERMISSION');
+  });
+
+  it('provides consistent pattern keys', () => {
+    const patterns = Object.values(CACHE_PATTERNS);
+    patterns.forEach(pattern => {
+      expect(typeof pattern).toBe('function');
+      expect(typeof pattern('test-id')).toBe('string');
+      expect(pattern('test-id').length).toBeGreaterThan(0);
+    });
+  });
+});
+
+describe('Permission Cache Key Generation', () => {
+  it('generates consistent cache keys', () => {
+    const key1: PermissionCacheKey = {
+      userId: 'user-123',
+      organisationId: 'org-456',
+      permission: 'read:users'
+    };
+    
+    const key2: PermissionCacheKey = {
+      userId: 'user-123',
+      organisationId: 'org-456',
+      permission: 'read:users'
+    };
+
+    // Keys should be consistent for same input
+    expect(JSON.stringify(key1)).toBe(JSON.stringify(key2));
+  });
+
+  it('handles optional fields in cache keys', () => {
+    const key: PermissionCacheKey = {
+      userId: 'user-123',
+      organisationId: 'org-456',
+      eventId: 'event-789',
+      appId: 'app-101',
+      permission: 'read:users',
+      pageId: 'page-202'
+    };
+
+    expect(key.userId).toBe('user-123');
+    expect(key.organisationId).toBe('org-456');
+    expect(key.eventId).toBe('event-789');
+    expect(key.appId).toBe('app-101');
+    expect(key.permission).toBe('read:users');
+    expect(key.pageId).toBe('page-202');
+  });
+});