@jmruthers/pace-core 0.5.114 → 0.5.116

package/src/rbac/errors.test.ts

@@ -0,0 +1,340 @@
+/**
+ * @file RBAC Error Categorization Tests
+ * @package @jmruthers/pace-core
+ * @module RBAC/Errors
+ * @since 1.0.0
+ * 
+ * Comprehensive tests for error categorization and security event mapping.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  RBACErrorCategory,
+  categorizeError,
+  mapErrorCategoryToSecurityEventType,
+  SecurityEventType,
+} from './errors';
+import {
+  RBACError,
+  PermissionDeniedError,
+  OrganisationContextRequiredError,
+  InvalidScopeError,
+  MissingUserContextError,
+} from './types';
+
+describe('RBAC Error Categorization', () => {
+  describe('categorizeError', () => {
+    describe('RBAC Error Instances', () => {
+      it('categorizes PermissionDeniedError as AUTHORIZATION', () => {
+        const error = new PermissionDeniedError('Access denied', 'user-123', 'read:users');
+        expect(categorizeError(error)).toBe(RBACErrorCategory.AUTHORIZATION);
+      });
+
+      it('categorizes OrganisationContextRequiredError as VALIDATION', () => {
+        const error = new OrganisationContextRequiredError();
+        expect(categorizeError(error)).toBe(RBACErrorCategory.VALIDATION);
+      });
+
+      it('categorizes InvalidScopeError as VALIDATION', () => {
+        const error = new InvalidScopeError('Invalid scope provided');
+        expect(categorizeError(error)).toBe(RBACErrorCategory.VALIDATION);
+      });
+
+      it('categorizes MissingUserContextError as AUTHENTICATION', () => {
+        const error = new MissingUserContextError();
+        expect(categorizeError(error)).toBe(RBACErrorCategory.AUTHENTICATION);
+      });
+    });
+
+    describe('RBACError with Codes', () => {
+      it('categorizes PERMISSION_DENIED code as AUTHORIZATION', () => {
+        const error = new RBACError('Permission denied', 'PERMISSION_DENIED');
+        expect(categorizeError(error)).toBe(RBACErrorCategory.AUTHORIZATION);
+      });
+
+      it('categorizes ORGANISATION_CONTEXT_REQUIRED code as VALIDATION', () => {
+        const error = new RBACError('Organisation required', 'ORGANISATION_CONTEXT_REQUIRED');
+        expect(categorizeError(error)).toBe(RBACErrorCategory.VALIDATION);
+      });
+
+      it('categorizes INVALID_SCOPE code as VALIDATION', () => {
+        const error = new RBACError('Invalid scope', 'INVALID_SCOPE');
+        expect(categorizeError(error)).toBe(RBACErrorCategory.VALIDATION);
+      });
+
+      it('categorizes MISSING_USER_CONTEXT code as AUTHENTICATION', () => {
+        const error = new RBACError('User context required', 'MISSING_USER_CONTEXT');
+        expect(categorizeError(error)).toBe(RBACErrorCategory.AUTHENTICATION);
+      });
+
+      it('returns UNKNOWN for unknown RBACError codes', () => {
+        const error = new RBACError('Unknown error', 'UNKNOWN_CODE');
+        expect(categorizeError(error)).toBe(RBACErrorCategory.UNKNOWN);
+      });
+    });
+
+    describe('HTTP Status Codes', () => {
+      it('categorizes 429 status as RATE_LIMIT', () => {
+        const error = { status: 429 };
+        expect(categorizeError(error)).toBe(RBACErrorCategory.RATE_LIMIT);
+      });
+
+      it('categorizes 401 status as AUTHENTICATION', () => {
+        const error = { status: 401 };
+        expect(categorizeError(error)).toBe(RBACErrorCategory.AUTHENTICATION);
+      });
+
+      it('categorizes 403 status as AUTHORIZATION', () => {
+        const error = { status: 403 };
+        expect(categorizeError(error)).toBe(RBACErrorCategory.AUTHORIZATION);
+      });
+
+      it('categorizes 500+ status as DATABASE', () => {
+        const error500 = { status: 500 };
+        const error503 = { status: 503 };
+        const error599 = { status: 599 };
+        
+        expect(categorizeError(error500)).toBe(RBACErrorCategory.DATABASE);
+        expect(categorizeError(error503)).toBe(RBACErrorCategory.DATABASE);
+        expect(categorizeError(error599)).toBe(RBACErrorCategory.DATABASE);
+      });
+    });
+
+    describe('Error Code Strings', () => {
+      it('categorizes network-related codes as NETWORK', () => {
+        const error1 = { code: 'NETWORK_ERROR' };
+        const error2 = { code: 'NetworkTimeout' };
+        const error3 = { code: 'network_failure' };
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.NETWORK);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.NETWORK);
+        expect(categorizeError(error3)).toBe(RBACErrorCategory.NETWORK);
+      });
+
+      it('categorizes database-related codes as DATABASE', () => {
+        const error1 = { code: 'POSTGRES_ERROR' };
+        const error2 = { code: 'database_connection_failed' };
+        const error3 = { code: 'DB_TIMEOUT' };
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.DATABASE);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.DATABASE);
+        expect(categorizeError(error3)).toBe(RBACErrorCategory.DATABASE);
+      });
+
+      it('categorizes rate limit codes as RATE_LIMIT', () => {
+        const error1 = { code: 'RATE_LIMIT_EXCEEDED' };
+        const error2 = { code: 'rate_limit' };
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.RATE_LIMIT);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.RATE_LIMIT);
+      });
+
+      it('categorizes auth-related codes as AUTHENTICATION', () => {
+        const error1 = { code: 'AUTH_ERROR' };
+        const error2 = { code: 'authentication_failed' };
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.AUTHENTICATION);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.AUTHENTICATION);
+      });
+
+      it('categorizes permission-related codes as AUTHORIZATION', () => {
+        const error1 = { code: 'PERMISSION_DENIED' };
+        const error2 = { code: 'permission_error' };
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.AUTHORIZATION);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.AUTHORIZATION);
+      });
+
+      it('categorizes validation-related codes as VALIDATION', () => {
+        const error1 = { code: 'INVALID_SCOPE' };
+        const error2 = { code: 'invalid_input' };
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.VALIDATION);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.VALIDATION);
+      });
+    });
+
+    describe('Error Messages', () => {
+      it('categorizes timeout messages as NETWORK', () => {
+        const error1 = 'Request timeout';
+        const error2 = new Error('Network timeout occurred');
+        // Object with message property is handled by code path before normalize
+        // So we test it as an Error instance or string
+        const error3 = new Error('fetch timeout');
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.NETWORK);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.NETWORK);
+        expect(categorizeError(error3)).toBe(RBACErrorCategory.NETWORK);
+      });
+
+      it('categorizes network messages as NETWORK', () => {
+        const error1 = 'Network error';
+        const error2 = new Error('Network failure');
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.NETWORK);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.NETWORK);
+      });
+
+      it('categorizes database messages as DATABASE', () => {
+        const error1 = 'Postgres connection failed';
+        const error2 = 'Database error occurred';
+        const error3 = 'Connection to database lost';
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.DATABASE);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.DATABASE);
+        expect(categorizeError(error3)).toBe(RBACErrorCategory.DATABASE);
+      });
+
+      it('categorizes rate limit messages as RATE_LIMIT', () => {
+        const error1 = 'Rate limit exceeded';
+        const error2 = 'Too many requests';
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.RATE_LIMIT);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.RATE_LIMIT);
+      });
+
+      it('categorizes permission messages as AUTHORIZATION', () => {
+        const error1 = 'Permission denied';
+        const error2 = 'Forbidden access';
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.AUTHORIZATION);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.AUTHORIZATION);
+      });
+
+      it('categorizes auth messages as AUTHENTICATION', () => {
+        const error1 = 'Auth token expired';
+        const error2 = 'Session invalid';
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.AUTHENTICATION);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.AUTHENTICATION);
+      });
+
+      it('categorizes validation messages as VALIDATION', () => {
+        const error1 = 'Invalid scope provided';
+        const error2 = 'Validation error';
+        const error3 = 'Invalid input';
+        
+        expect(categorizeError(error1)).toBe(RBACErrorCategory.VALIDATION);
+        expect(categorizeError(error2)).toBe(RBACErrorCategory.VALIDATION);
+        expect(categorizeError(error3)).toBe(RBACErrorCategory.VALIDATION);
+      });
+    });
+
+    describe('Edge Cases', () => {
+      it('returns UNKNOWN for null', () => {
+        expect(categorizeError(null)).toBe(RBACErrorCategory.UNKNOWN);
+      });
+
+      it('returns UNKNOWN for undefined', () => {
+        expect(categorizeError(undefined)).toBe(RBACErrorCategory.UNKNOWN);
+      });
+
+      it('returns UNKNOWN for empty string', () => {
+        expect(categorizeError('')).toBe(RBACErrorCategory.UNKNOWN);
+      });
+
+      it('returns UNKNOWN for unknown error types', () => {
+        const error = { someProperty: 'value' };
+        expect(categorizeError(error)).toBe(RBACErrorCategory.UNKNOWN);
+      });
+
+      it('handles non-string code values', () => {
+        const error = { code: 123 };
+        expect(categorizeError(error)).toBe(RBACErrorCategory.UNKNOWN);
+      });
+
+      it('handles non-number status values', () => {
+        const error = { status: '500' };
+        expect(categorizeError(error)).toBe(RBACErrorCategory.UNKNOWN);
+      });
+    });
+
+    describe('Priority Order', () => {
+      it('prioritizes RBAC error instances over status codes', () => {
+        const error = new PermissionDeniedError('Denied', 'user-123', 'read:users');
+        // Even if status is set, RBAC error instance takes priority
+        expect(categorizeError(error)).toBe(RBACErrorCategory.AUTHORIZATION);
+      });
+
+      it('prioritizes status codes over message parsing', () => {
+        const error = { 
+          status: 429,
+          message: 'Network timeout' // Would normally be NETWORK
+        };
+        expect(categorizeError(error)).toBe(RBACErrorCategory.RATE_LIMIT);
+      });
+
+      it('prioritizes code parsing over message parsing', () => {
+        const error = {
+          code: 'NETWORK_ERROR',
+          message: 'Database error' // Would normally be DATABASE
+        };
+        expect(categorizeError(error)).toBe(RBACErrorCategory.NETWORK);
+      });
+    });
+  });
+
+  describe('mapErrorCategoryToSecurityEventType', () => {
+    it('maps AUTHORIZATION to permission_denied', () => {
+      expect(mapErrorCategoryToSecurityEventType(RBACErrorCategory.AUTHORIZATION))
+        .toBe('permission_denied');
+    });
+
+    it('maps NETWORK to network_error', () => {
+      expect(mapErrorCategoryToSecurityEventType(RBACErrorCategory.NETWORK))
+        .toBe('network_error');
+    });
+
+    it('maps DATABASE to database_error', () => {
+      expect(mapErrorCategoryToSecurityEventType(RBACErrorCategory.DATABASE))
+        .toBe('database_error');
+    });
+
+    it('maps VALIDATION to validation_error', () => {
+      expect(mapErrorCategoryToSecurityEventType(RBACErrorCategory.VALIDATION))
+        .toBe('validation_error');
+    });
+
+    it('maps RATE_LIMIT to rate_limit_error', () => {
+      expect(mapErrorCategoryToSecurityEventType(RBACErrorCategory.RATE_LIMIT))
+        .toBe('rate_limit_error');
+    });
+
+    it('maps AUTHENTICATION to authentication_error', () => {
+      expect(mapErrorCategoryToSecurityEventType(RBACErrorCategory.AUTHENTICATION))
+        .toBe('authentication_error');
+    });
+
+    it('maps UNKNOWN to unknown_error', () => {
+      expect(mapErrorCategoryToSecurityEventType(RBACErrorCategory.UNKNOWN))
+        .toBe('unknown_error');
+    });
+
+    it('maps default case to unknown_error', () => {
+      // Test with a value that shouldn't happen but ensures default works
+      const result = mapErrorCategoryToSecurityEventType('UNEXPECTED' as RBACErrorCategory);
+      expect(result).toBe('unknown_error');
+    });
+  });
+
+  describe('Integration', () => {
+    it('categorizes and maps error end-to-end', () => {
+      const error = new PermissionDeniedError('Access denied', 'user-123', 'read:users');
+      const category = categorizeError(error);
+      const eventType = mapErrorCategoryToSecurityEventType(category);
+      
+      expect(category).toBe(RBACErrorCategory.AUTHORIZATION);
+      expect(eventType).toBe('permission_denied');
+    });
+
+    it('handles network errors through full pipeline', () => {
+      const error = { status: 500, message: 'Database connection failed' };
+      const category = categorizeError(error);
+      const eventType = mapErrorCategoryToSecurityEventType(category);
+      
+      expect(category).toBe(RBACErrorCategory.DATABASE);
+      expect(eventType).toBe('database_error');
+    });
+  });
+});
+

package/src/rbac/hooks/index.ts

@@ -21,3 +21,12 @@ export {
   useHasAllPermissions,
   useCachedPermissions,
 } from './usePermissions';
+
+// Export role management hook
+export { useRoleManagement } from './useRoleManagement';
+export type {
+  EventAppRoleData,
+  RevokeEventAppRoleParams,
+  GrantEventAppRoleParams,
+  RoleManagementResult,
+} from './useRoleManagement';