@jmruthers/pace-core 0.6.1 → 0.6.3

package/src/eslint-rules/pace-core-compliance.cjs

@@ -378,6 +378,112 @@ module.exports = {
           }
         };
       }
+    },
+
+    /**
+     * Disallow direct Supabase client creation - must use useSecureSupabase
+     */
+    'no-direct-supabase-client': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow direct createClient calls from @supabase/supabase-js. Use useSecureSupabase() from pace-core instead to ensure organisation context and RLS policies are enforced.',
+          category: 'Security',
+          recommended: true
+        },
+        messages: {
+          directClientCreation: "Direct Supabase client creation detected. You MUST use useSecureSupabase() from '@jmruthers/pace-core/rbac' instead to ensure organisation context and RLS policies are enforced. This prevents cross-organisation data access.",
+          directClientImport: "Direct import of createClient from @supabase/supabase-js is not allowed. Use useSecureSupabase() from '@jmruthers/pace-core/rbac' instead."
+        },
+        hasSuggestions: true
+      },
+      create(context) {
+        let hasSupabaseImport = false;
+        let createClientImported = false;
+        const filename = context.getFilename();
+        
+        // Allow createClient in specific config files (supabaseClient.ts/js, etc.)
+        const isConfigFile = /(supabase|client)\.(ts|js|tsx|jsx)$/i.test(filename) && 
+                            (filename.includes('supabase') || filename.includes('client'));
+        
+        return {
+          ImportDeclaration(node) {
+            const importSource = node.source.value;
+            
+            // Check for @supabase/supabase-js import
+            if (importSource === '@supabase/supabase-js') {
+              hasSupabaseImport = true;
+              
+              // Check if createClient is imported
+              const hasCreateClient = node.specifiers.some(spec => {
+                if (spec.type === 'ImportSpecifier') {
+                  return spec.imported.name === 'createClient';
+                }
+                if (spec.type === 'ImportNamespaceSpecifier') {
+                  return true; // import * as supabase
+                }
+                return false;
+              });
+              
+              if (hasCreateClient) {
+                createClientImported = true;
+                
+                // Only report if not in a config file
+                if (!isConfigFile) {
+                  context.report({
+                    node: node.source,
+                    messageId: 'directClientImport',
+                    suggest: [{
+                      desc: 'Replace with useSecureSupabase hook',
+                      fix(fixer) {
+                        // Remove the import
+                        return fixer.remove(node);
+                      }
+                    }]
+                  });
+                }
+              }
+            }
+          },
+          
+          CallExpression(node) {
+            // Check for createClient() calls
+            if (node.callee.type === 'Identifier' && node.callee.name === 'createClient') {
+              // Only report if not in a config file
+              if (!isConfigFile) {
+                context.report({
+                  node,
+                  messageId: 'directClientCreation',
+                  suggest: [{
+                    desc: 'Use useSecureSupabase() hook instead',
+                    fix(fixer) {
+                      // This is complex to auto-fix, so we'll just report
+                      return null;
+                    }
+                  }]
+                });
+              }
+            }
+            
+            // Check for supabase.createClient() or similar patterns
+            if (node.callee.type === 'MemberExpression' && 
+                node.callee.property?.name === 'createClient') {
+              if (!isConfigFile) {
+                context.report({
+                  node,
+                  messageId: 'directClientCreation',
+                  suggest: [{
+                    desc: 'Use useSecureSupabase() hook instead',
+                    fix(fixer) {
+                      return null;
+                    }
+                  }]
+                });
+              }
+            }
+          }
+        };
+      }
     }
   }
 };

package/src/hooks/__tests__/index.unit.test.ts

@@ -64,10 +64,7 @@ describe('hooks index exports', () => {
       expect(typeof Hooks.useOrganisationPermissions).toBe('function');
     });
 
-    it('should export useSecureDataAccess', () => {
-      expect(Hooks).toHaveProperty('useSecureDataAccess');
-      expect(typeof Hooks.useSecureDataAccess).toBe('function');
-    });
+    // useSecureDataAccess has been removed - use useSecureSupabase from @jmruthers/pace-core/rbac instead
 
     it('should export useOrganisationSecurity', () => {
       expect(Hooks).toHaveProperty('useOrganisationSecurity');
@@ -190,7 +187,7 @@ describe('hooks index exports', () => {
         'useDebounce',
         'useDataTableState',
         'useOrganisationPermissions',
-        'useSecureDataAccess',
+        // 'useSecureDataAccess', // Removed - use useSecureSupabase from @jmruthers/pace-core/rbac instead
         'useOrganisationSecurity',
         'useZodForm',
         'useComponentPerformance',

package/src/hooks/__tests__/useAppConfig.unit.test.ts

@@ -99,7 +99,7 @@ describe('useAppConfig Hook', () => {
     vi.restoreAllMocks();
   });
 
-    describe('Public Page Context', () => {
+  describe('Public Page Context', () => {
     beforeEach(() => {
       mockUseIsPublicPage.mockReturnValue(true);
     });
@@ -107,8 +107,6 @@ describe('useAppConfig Hook', () => {
     it('should return public page configuration when in public context', () => {
       const { result } = renderHook(() => useAppConfig());
 
-      expect(result.current.supportsDirectAccess).toBe(false);
-      expect(result.current.requiresEvent).toBe(true);
       expect(result.current.isLoading).toBe(false);
       // Note: If VITE_APP_NAME is set in .env (e.g., CORE), the hook will use it.
       // Otherwise, it defaults to 'PACE'. This test verifies it returns a valid string.
@@ -122,8 +120,6 @@ describe('useAppConfig Hook', () => {
       const { result } = renderHook(() => useAppConfig());
 
       // Public pages should always have these characteristics
-      expect(result.current.supportsDirectAccess).toBe(false);
-      expect(result.current.requiresEvent).toBe(true);
       expect(result.current.isLoading).toBe(false);
       expect(typeof result.current.appName).toBe('string');
     });
@@ -134,80 +130,23 @@ describe('useAppConfig Hook', () => {
       mockUseIsPublicPage.mockReturnValue(false);
       // Set default mock for useUnifiedAuth
       mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: { requires_event: true },
         appName: 'PACE',
       } as any);
     });
 
     it('should return configuration from UnifiedAuthProvider when available', () => {
-      const mockAppConfig = {
-        requires_event: false,
-      };
       const mockAppName = 'AuthApp';
 
       mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: mockAppConfig,
         appName: mockAppName,
       } as any);
 
       const { result } = renderHook(() => useAppConfig());
 
-      expect(result.current.supportsDirectAccess).toBe(true);
-      expect(result.current.requiresEvent).toBe(false);
       expect(result.current.isLoading).toBe(false);
       expect(result.current.appName).toBe('AuthApp');
     });
 
-    it('should handle requires_event: true', () => {
-      const mockAppConfig = {
-        requires_event: true,
-      };
-      const mockAppName = 'EventApp';
-
-      mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: mockAppConfig,
-        appName: mockAppName,
-      } as any);
-
-      const { result } = renderHook(() => useAppConfig());
-
-      expect(result.current.supportsDirectAccess).toBe(false);
-      expect(result.current.requiresEvent).toBe(true);
-      expect(result.current.isLoading).toBe(false);
-      expect(result.current.appName).toBe('EventApp');
-    });
-
-    it('should handle null appConfig (loading state)', () => {
-      mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: null,
-        appName: 'LoadingApp',
-      } as any);
-
-      const { result } = renderHook(() => useAppConfig());
-
-      expect(result.current.supportsDirectAccess).toBe(false);
-      expect(result.current.requiresEvent).toBe(true);
-      expect(result.current.isLoading).toBe(true);
-      expect(result.current.appName).toBe('LoadingApp');
-    });
-
-    it('should handle undefined appConfig.requires_event', () => {
-      const mockAppConfig = {};
-      const mockAppName = 'DefaultApp';
-
-      mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: mockAppConfig,
-        appName: mockAppName,
-      } as any);
-
-      const { result } = renderHook(() => useAppConfig());
-
-      expect(result.current.supportsDirectAccess).toBe(false);
-      expect(result.current.requiresEvent).toBe(true);
-      expect(result.current.isLoading).toBe(false);
-      expect(result.current.appName).toBe('DefaultApp');
-    });
-
     it('should handle UnifiedAuthProvider error and return fallback', () => {
       mockUseUnifiedAuthFn.mockImplementation(() => {
         throw new Error('Provider not available');
@@ -215,8 +154,6 @@ describe('useAppConfig Hook', () => {
 
       const { result } = renderHook(() => useAppConfig());
 
-      expect(result.current.supportsDirectAccess).toBe(false);
-      expect(result.current.requiresEvent).toBe(true);
       expect(result.current.isLoading).toBe(false);
       expect(result.current.appName).toBe('PACE');
     });
@@ -228,8 +165,6 @@ describe('useAppConfig Hook', () => {
 
       const { result } = renderHook(() => useAppConfig());
 
-      expect(result.current.supportsDirectAccess).toBe(false);
-      expect(result.current.requiresEvent).toBe(true);
       expect(result.current.isLoading).toBe(false);
       expect(result.current.appName).toBe('PACE');
     });
@@ -241,8 +176,6 @@ describe('useAppConfig Hook', () => {
 
       const { result } = renderHook(() => useAppConfig());
 
-      expect(result.current.supportsDirectAccess).toBe(false);
-      expect(result.current.requiresEvent).toBe(true);
       expect(result.current.isLoading).toBe(false);
       expect(result.current.appName).toBe('PACE');
     });
@@ -264,11 +197,9 @@ describe('useAppConfig Hook', () => {
     it('should memoize authenticated configuration based on dependencies', () => {
       mockUseIsPublicPage.mockReturnValue(false);
 
-      const mockAppConfig = { requires_event: false };
       const mockAppName = 'TestApp';
 
       mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: mockAppConfig,
         appName: mockAppName,
       } as any);
 
@@ -281,25 +212,21 @@ describe('useAppConfig Hook', () => {
 
       expect(result.current).toBe(firstResult);
 
-      // Rerender with different appConfig
+      // Rerender with different appName
       mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: { requires_event: true },
-        appName: mockAppName,
+        appName: 'DifferentApp',
       } as any);
 
       rerender();
 
       expect(result.current).not.toBe(firstResult);
-      expect(result.current.requiresEvent).toBe(true);
+      expect(result.current.appName).toBe('DifferentApp');
     });
 
     it('should memoize authenticated configuration based on appName changes', () => {
       mockUseIsPublicPage.mockReturnValue(false);
 
-      const mockAppConfig = { requires_event: false };
-
       mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: mockAppConfig,
         appName: 'App1',
       } as any);
 
@@ -309,7 +236,6 @@ describe('useAppConfig Hook', () => {
 
       // Rerender with different appName
       mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: mockAppConfig,
         appName: 'App2',
       } as any);
 
@@ -327,7 +253,6 @@ describe('useAppConfig Hook', () => {
 
       const { result: publicResult } = renderHook(() => useAppConfig());
 
-      expect(publicResult.current.supportsDirectAccess).toBe(false);
       // Note: App name depends on environment - may be 'PACE' (default) or 'CORE' (from .env)
       expect(typeof publicResult.current.appName).toBe('string');
       expect(['PACE', 'CORE']).toContain(publicResult.current.appName);
@@ -335,13 +260,11 @@ describe('useAppConfig Hook', () => {
       // Test authenticated page context separately
       mockUseIsPublicPage.mockReturnValue(false);
       mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: { requires_event: false },
         appName: 'AuthApp',
       } as any);
 
       const { result: authResult } = renderHook(() => useAppConfig());
 
-      expect(authResult.current.supportsDirectAccess).toBe(true);
       expect(authResult.current.appName).toBe('AuthApp');
     });
   });
@@ -350,30 +273,13 @@ describe('useAppConfig Hook', () => {
     it('should return correct types for all return values', () => {
       mockUseIsPublicPage.mockReturnValue(false);
       mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: { requires_event: false },
         appName: 'TypeTestApp',
       } as any);
 
       const { result } = renderHook(() => useAppConfig());
 
-      expect(typeof result.current.supportsDirectAccess).toBe('boolean');
-      expect(typeof result.current.requiresEvent).toBe('boolean');
       expect(typeof result.current.isLoading).toBe('boolean');
       expect(typeof result.current.appName).toBe('string');
     });
-
-    it('should handle malformed appConfig objects', () => {
-      mockUseIsPublicPage.mockReturnValue(false);
-      mockUseUnifiedAuthFn.mockReturnValue({
-        appConfig: { requires_event: 'not-a-boolean' },
-        appName: 'MalformedApp',
-      } as any);
-
-      const { result } = renderHook(() => useAppConfig());
-
-      // The hook uses the value directly, so it will be truthy
-      expect(result.current.requiresEvent).toBe('not-a-boolean');
-      expect(result.current.supportsDirectAccess).toBe(false);
-    });
   });
 });

package/src/hooks/index.ts

@@ -33,9 +33,8 @@ export type { UseAddressAutocompleteOptions, UseAddressAutocompleteReturn } from
 
 // === ORGANISATION HOOKS ===
 export { useOrganisationPermissions } from './useOrganisationPermissions';
-export { useSecureDataAccess } from './useSecureDataAccess';
+// useSecureDataAccess has been removed - use useSecureSupabase from @jmruthers/pace-core/rbac instead
 export type { UseOrganisationPermissionsReturn } from './useOrganisationPermissions';
-export type { SecureDataAccessReturn } from './useSecureDataAccess';
 export { useOrganisationSecurity } from './useOrganisationSecurity';
 export type { OrganisationSecurityHook } from './useOrganisationSecurity';
 

package/src/hooks/public/usePublicEvent.ts

@@ -70,6 +70,10 @@ import { logger } from '../../utils/core/logger';
 // Simple in-memory cache for public data
 const publicDataCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
 
+/**
+ * Return value of the usePublicEvent hook.
+ * Provides event data, loading state, error, and refetch function.
+ */
 export interface UsePublicEventReturn {
   /** The event data, null if not loaded or not found */
   event: Event | null;

package/src/hooks/public/usePublicEventLogo.ts

@@ -74,6 +74,10 @@ const log = createLogger('usePublicEventLogo');
 // Simple in-memory cache for public data
 const publicDataCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
 
+/**
+ * Return value of the usePublicEventLogo hook.
+ * Provides logo URL, fallback text, loading state, error, and refetch function.
+ */
 export interface UsePublicEventLogoReturn {
   /** The logo URL if available, null if not found or error */
   logoUrl: string | null;

package/src/hooks/public/usePublicFileDisplay.ts

@@ -46,6 +46,10 @@ import { logger } from '../../utils/core/logger';
 // Simple in-memory cache for public file data
 const publicFileCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
 
+/**
+ * Return value of the usePublicFileDisplay hook.
+ * Provides file URLs, references, loading state, error, and refetch function.
+ */
 export interface UsePublicFileDisplayReturn {
   /** Single file URL if category is provided and file found, null otherwise */
   fileUrl: string | null;

package/src/hooks/public/usePublicRouteParams.ts

@@ -61,6 +61,10 @@ import { useParams, useLocation } from 'react-router-dom';
 import type { Event } from '../../types/event';
 import { usePublicEvent } from './usePublicEvent';
 
+/**
+ * Return value of the usePublicRouteParams hook.
+ * Provides event code, event ID, event data, loading state, error, and refetch function.
+ */
 export interface UsePublicRouteParamsReturn {
   /** The event code from the URL */
   eventCode: string | null;

package/src/hooks/services/useAuth.ts

@@ -11,23 +11,55 @@
 import { useAuthService } from './useAuthService';
 import { type User, type Session, type SupabaseClient, AuthError } from '@supabase/supabase-js';
 
+/**
+ * Authentication state and methods returned by the useAuth hook.
+ */
 export interface AuthState {
+  /** Current authenticated user, or null if not authenticated */
   user: User | null;
+  /** Current session, or null if not authenticated */
   session: Session | null;
+  /** Whether the user is currently authenticated */
   isAuthenticated: boolean;
+  /** Whether authentication state is currently loading */
   authLoading: boolean;
+  /** Any authentication error that occurred, or null */
   authError: AuthError | null;
+  /** Supabase client instance, or null if not available */
   supabase: SupabaseClient | null;
   
   // Auth methods
+  /** Sign in with email and optional password */
   signIn: (email: string, password?: string) => Promise<{ error: AuthError | null }>;
+  /** Sign up with email and password */
   signUp: (email: string, password: string) => Promise<{ error: AuthError | null }>;
+  /** Sign out the current user */
   signOut: () => Promise<{ error: AuthError | null }>;
+  /** Request a password reset email */
   resetPassword: (email: string) => Promise<{ error: AuthError | null }>;
+  /** Update the current user's password */
   updatePassword: (password: string) => Promise<{ error: AuthError | null }>;
+  /** Refresh the current session */
   refreshSession: () => Promise<{ error: AuthError | null }>;
 }
 
+/**
+ * Convenience hook for authentication.
+ * Returns the auth state and methods needed by components.
+ * 
+ * @returns Authentication state and methods
+ * 
+ * @example
+ * ```tsx
+ * const { user, isAuthenticated, signIn, signOut } = useAuth();
+ * 
+ * if (!isAuthenticated) {
+ *   return <LoginForm onSignIn={signIn} />;
+ * }
+ * 
+ * return <Dashboard user={user} onSignOut={signOut} />;
+ * ```
+ */
 export function useAuth(): AuthState {
   const authService = useAuthService();
   

package/src/hooks/services/useCurrentEvent.ts

@@ -22,6 +22,12 @@ export interface CurrentEventState {
   refreshEvents: () => Promise<void>;
 }
 
+/**
+ * Convenience hook for accessing current event state.
+ * Returns event state and methods needed by components.
+ * 
+ * @returns Current event state including events, selected event, loading state, and methods
+ */
 export function useCurrentEvent(): CurrentEventState {
   const eventService = useEventService();
   

package/src/hooks/services/useCurrentOrganisation.ts

@@ -30,6 +30,12 @@ export interface CurrentOrganisationState {
   getPrimaryOrganisation: () => Organisation | null;
 }
 
+/**
+ * Convenience hook for accessing current organisation state.
+ * Returns organisation state and methods needed by components.
+ * 
+ * @returns Current organisation state including selected organisation, organisations, memberships, and methods
+ */
 export function useCurrentOrganisation(): CurrentOrganisationState {
   const organisationService = useOrganisationService();
   

package/src/hooks/useAppConfig.ts

@@ -4,26 +4,19 @@
  * @module Hooks/useAppConfig
  * @since 0.4.0
  *
- * Hook for accessing app configuration like direct access support and event requirements.
- * This is a convenience hook that extracts app config from the UnifiedAuthProvider.
+ * Hook for accessing app name and loading state.
+ * 
+ * NOTE: Scope configuration (requires_event) is now page-level only (rbac_app_pages.scope_type).
+ * Use getPageScopeType() to determine if a specific page requires event or organisation context.
  *
  * @example
  * ```tsx
  * function MyComponent() {
- *   const { supportsDirectAccess, requiresEvent, isLoading } = useAppConfig();
+ *   const { appName, isLoading } = useAppConfig();
  *   
  *   if (isLoading) return <div>Loading...</div>;
  *   
- *   return (
- *     <div>
- *       {supportsDirectAccess && (
- *         <div>This app supports direct access!</div>
- *       )}
- *       {requiresEvent && (
- *         <EventSelector />
- *       )}
- *     </div>
- *   );
+ *   return <div>App: {appName}</div>;
  * }
  * ```
  */
@@ -33,10 +26,8 @@ import { useUnifiedAuth } from '../providers/services/UnifiedAuthProvider';
 import { useIsPublicPage, PublicPageContext } from '../components/PublicLayout/PublicPageProvider';
 
 export interface UseAppConfigReturn {
-  supportsDirectAccess: boolean;
-  requiresEvent: boolean;
-  isLoading: boolean;
   appName: string;
+  isLoading: boolean;
 }
 
 /**
@@ -92,32 +83,26 @@ export function useAppConfig(): UseAppConfigReturn {
     };
     
     return useMemo(() => ({
-      supportsDirectAccess: false, // Public pages don't support direct access
-      requiresEvent: true, // Public pages always require an event
-      isLoading: false,
-      appName: getAppName()
+      appName: getAppName(),
+      isLoading: false
     }), [contextAppName, hasPublicContext]);
   }
   
   // For authenticated pages, use UnifiedAuthProvider
   try {
-    const { appConfig, appName } = useUnifiedAuth();
+    const { appName } = useUnifiedAuth();
     return useMemo(() => ({
-      supportsDirectAccess: !(appConfig?.requires_event ?? true),
-      requiresEvent: appConfig?.requires_event ?? true,
-      isLoading: appConfig === null,
-      appName
-    }), [appConfig?.requires_event, appName]);
+      appName,
+      isLoading: false
+    }), [appName]);
   } catch (error) {
     // Fallback if UnifiedAuthProvider is not available
     return useMemo(() => ({
-      supportsDirectAccess: false,
-      requiresEvent: true,
-      isLoading: false,
       appName: contextAppName ||
         getNodeEnvVar('VITE_APP_NAME') ||
         getNodeEnvVar('NEXT_PUBLIC_APP_NAME') ||
-        'PACE'
+        'PACE',
+      isLoading: false
     }), [contextAppName]);
   }
 } 

package/src/hooks/useDebounce.ts

@@ -1,6 +1,15 @@
 
 import { useState, useEffect } from 'react';
 
+/**
+ * Hook for debouncing a value.
+ * Returns a debounced version of the value that only updates after the specified delay.
+ * 
+ * @template T - The type of the value to debounce
+ * @param value - The value to debounce
+ * @param delay - The delay in milliseconds
+ * @returns The debounced value
+ */
 export function useDebounce<T>(value: T, delay: number): T {
   const [debouncedValue, setDebouncedValue] = useState<T>(value);
 

package/src/hooks/useEventTheme.ts

@@ -92,6 +92,12 @@ const log = createLogger('useEventTheme');
  * }
  * ```
  */
+/**
+ * Hook that automatically applies event-specific theming.
+ * Works in authenticated mode (via EventProvider) or public page mode (via event prop).
+ * 
+ * @param event - Optional event object for public page mode. If not provided, uses EventProvider context.
+ */
 export function useEventTheme(event?: Event | null): void {
   const location = useLocation();