@jmruthers/pace-core 0.5.108 → 0.5.109

package/docs/api-reference/hooks.md

@@ -76,6 +76,59 @@ function App() {
 }
 ```
 
+> **Note**: Login and logout tracking is automatically handled by `UnifiedAuthProvider`. No manual intervention is required.
+
+### useSessionTracking
+
+Utility hook for manual session tracking of event switches and session expiration. **Note**: Login and logout are automatically tracked by `UnifiedAuthProvider`, so those methods are not available here.
+
+```typescript
+function useSessionTracking(
+  supabaseClient: SupabaseClient,
+  appName?: string
+): {
+  trackEventSwitch: (eventId: string) => Promise<void>;
+  trackSessionExpired: () => Promise<void>;
+}
+```
+
+#### Usage
+
+```tsx
+import { useSessionTracking } from '@jmruthers/pace-core';
+import { supabase } from './lib/supabase';
+
+function MyComponent() {
+  const { trackEventSwitch, trackSessionExpired } = useSessionTracking(
+    supabase,
+    'MY_APP'
+  );
+
+  const handleEventSwitch = async (eventId: string) => {
+    await trackEventSwitch(eventId);
+    // Event switch logic...
+  };
+
+  const handleSessionExpiration = async () => {
+    await trackSessionExpired();
+    // Session expiration logic...
+  };
+
+  return (
+    // Component JSX
+  );
+}
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `trackEventSwitch(eventId)` | Track when a user switches to a different event. |
+| `trackSessionExpired()` | Track when a session expires. |
+
+> **Automatic Tracking**: When using `UnifiedAuthProvider`, login and logout events are **automatically tracked**. You only need to use this hook for event switches or session expirations, which are not automatically tracked.
+
 
 ## Event Management Hooks
 

package/docs/api-reference/providers.md

@@ -206,6 +206,66 @@ The inactivity tracker monitors the following user interactions:
 - **Automatic cleanup**: All timers and listeners are properly cleaned up
 - **Error handling**: Graceful fallback if localStorage or BroadcastChannel fail
 
+#### Automatic Login History Tracking
+
+The `UnifiedAuthProvider` automatically tracks all user logins for security auditing and compliance:
+
+- **Automatic Tracking** - No manual intervention required, tracking happens automatically on login/logout
+- **Complete Audit Trail** - Records user ID, email, timestamp, IP address, user agent, and application context
+- **Database Storage** - All login events are stored in `rbac_user_login_history` table
+- **Application Context** - Tracks which application the user logged into (when `appName` is provided)
+- **Non-Blocking** - Tracking failures don't prevent authentication from succeeding
+- **Privacy Compliant** - Users can only view their own login history (RLS enforced)
+
+Login history is tracked automatically when you use `UnifiedAuthProvider`. No additional configuration is required:
+
+```tsx
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="MY_APP"  // Enables app-specific tracking in login history
+  // ... other props
+>
+  <AppContent />
+</UnifiedAuthProvider>
+```
+
+**What Gets Tracked:**
+
+- User ID and email
+- Login timestamp
+- Session ID
+- IP address (if available)
+- User agent string
+- Application ID (if `appName` is provided)
+- Organisation ID
+- Event ID (if applicable)
+
+**Querying Login History:**
+
+Login history can be queried directly from the database using RLS-protected queries:
+
+```sql
+-- Get user's login history
+SELECT 
+  login_timestamp,
+  email,
+  ip_address,
+  user_agent,
+  app_id,
+  event_id
+FROM rbac_user_login_history
+WHERE user_id = auth.uid()
+ORDER BY login_timestamp DESC
+LIMIT 100;
+```
+
+**Security Notes:**
+
+- Login history insertion uses `SECURITY DEFINER` functions (bypasses RLS)
+- RLS policies ensure users can only view their own login history
+- Failed tracking attempts are logged as warnings but don't break authentication
+- All tracking is asynchronous and non-blocking
+
 ## OrganisationProvider
 
 Manages multi-tenant organisation context and user organisation memberships. **Automatically sets database organisation context** to ensure RLS policies work correctly.

package/docs/core-concepts/authentication.md

@@ -77,6 +77,7 @@ sequenceDiagram
 - **Persistent State** - Authentication state persists across page reloads
 - **Multi-Tab Support** - Authentication state synchronized across tabs
 - **Graceful Degradation** - Handles network issues and token expiry
+- **Automatic Login History** - User login events are automatically tracked in `rbac_user_login_history` table
 
 ### Security Features
 
@@ -84,6 +85,7 @@ sequenceDiagram
 - **JWT Tokens** - Secure, stateless authentication
 - **CSRF Protection** - Cross-site request forgery prevention
 - **Audit Logging** - Complete action tracking for compliance
+- **Login History Tracking** - Automatic tracking of all user logins with timestamps, IP addresses, user agents, and application context
 
 ## Multi-Tenancy
 

package/docs/implementation-guides/authentication.md

@@ -23,6 +23,7 @@ PACE Core provides a comprehensive authentication system built on Supabase that
 - **🔒 Session Persistence** - Secure session management with auto-refresh
 - **🎯 Permission Integration** - Built-in RBAC integration
 - **📊 Debug Support** - Comprehensive debugging and monitoring
+- **📝 Automatic Login History** - All user logins automatically tracked for audit trails
 
 ## Quick Start
 

package/docs/security/README.md

@@ -16,6 +16,7 @@ PACE Core is designed with security as a first-class concern, providing:
 - **Comprehensive RBAC system** with fine-grained permissions
 - **Secure data access** with row-level security
 - **Audit logging** for compliance and monitoring
+- **Automatic login history tracking** for security audits and compliance
 - **Input validation** and sanitization
 - **XSS protection** and secure coding practices
 - **Auto-logout on inactivity** for enhanced security
@@ -59,6 +60,64 @@ Sessions are automatically managed by PACE Core:
 - **Session validation** on every request
 - **Automatic logout** on token expiration
 - **Inactivity auto-logout** after 30 minutes of inactivity (configurable)
+- **Automatic login history tracking** - All user logins are automatically recorded
+
+### 2.1 Login History Tracking
+
+PACE Core **automatically tracks all user logins** for security auditing and compliance - no manual intervention required.
+
+- **Fully Automatic** - Simply use `UnifiedAuthProvider` with `appName` prop - tracking happens automatically
+- **No Configuration Needed** - No calls to tracking functions, no setup code, no manual intervention
+- **Complete Audit Trail** - Records user ID, email, timestamp, IP address, user agent, and application context
+- **Database Storage** - All login events are stored in `rbac_user_login_history` table automatically
+- **Application Context** - Tracks which application the user logged into (when `appName` is provided)
+- **Non-Blocking** - Tracking failures don't prevent authentication from succeeding
+- **Privacy Compliant** - Users can only view their own login history (RLS enforced)
+
+**How It Works:**
+
+Login history tracking is **completely automatic** when you use `UnifiedAuthProvider`. Simply provide the `appName` prop (which is already required) and tracking happens automatically:
+
+```tsx
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider
+      supabaseClient={supabaseClient}
+      appName="MY_APP"  // Optional: Enables app-specific tracking
+      // ... other props
+    >
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+**Querying Login History:**
+
+Login history can be queried directly from the database:
+
+```sql
+-- Get user's login history
+SELECT 
+  login_timestamp,
+  email,
+  ip_address,
+  user_agent,
+  app_id
+FROM rbac_user_login_history
+WHERE user_id = auth.uid()
+ORDER BY login_timestamp DESC
+LIMIT 100;
+```
+
+**Security Notes:**
+
+- Login history insertion uses `SECURITY DEFINER` functions (bypasses RLS)
+- RLS policies ensure users can only view their own login history
+- Failed tracking attempts are logged but don't break authentication
+- All tracking is asynchronous and non-blocking
 
 ```tsx
 import { useUnifiedAuth } from '@jmruthers/pace-core';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.108",
+  "version": "0.5.109",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {

package/src/components/PaceAppLayout/PaceAppLayout.test.tsx

@@ -540,7 +540,7 @@ describe('PaceAppLayout Component', () => {
             eventId: 'event-123',
             appId: 'app-123',
           },
-          permission: 'update',
+          permission: 'update:page.dashboard-page',
           pageId: 'dashboard-page',
         });
       }, { timeout: 3000 });
@@ -571,7 +571,7 @@ describe('PaceAppLayout Component', () => {
             eventId: 'event-123',
             appId: 'app-123',
           },
-          permission: 'create',
+          permission: 'create:page.dashboard',
           pageId: 'dashboard',
         });
       }, { timeout: 3000 });

package/src/components/PaceAppLayout/PaceAppLayout.tsx

@@ -395,10 +395,16 @@ export function PaceAppLayout({
         return false;
       }
       
+      // Construct the full permission string in format "operation:page.pageId"
+      // If permission already includes ':', use it as-is, otherwise format as "operation:page.pageId"
+      const fullPermission: Permission = permission.includes(':')
+        ? (permission as Permission)
+        : (pageId ? `${permission}:page.${pageId}` : permission) as Permission;
+      
       return await isPermitted({
         userId: user.id,
         scope,
-        permission: permission as Permission,
+        permission: fullPermission,
         pageId
       });
     } catch (error) {
@@ -577,30 +583,56 @@ export function PaceAppLayout({
       }
 
       // Organisation context is ready - now filter items based on permissions
-      const filtered = await Promise.all(
-        baseMenuItems.map(async (item) => {
+      // OPTIMIZATION: Use batch permission map instead of individual checks to avoid rate limits
+      // This makes 1 call instead of N calls (where N = number of navigation items)
+      try {
+        const { getPermissionMap } = await import('../../rbac/api');
+        const permissionMap = await getPermissionMap({
+          userId: user.id,
+          scope,
+        });
+
+        // Filter items using the permission map (synchronous, no rate limit issues)
+        const filtered = baseMenuItems.map((item) => {
           if (!item.href) return { item, hasAccess: true };
           
           const pageId = pageIdMapping[item.href] || item.href.slice(1) || 'home';
           const permission = routePermissions[item.href] || defaultPermission;
+          const fullPermission: Permission = permission.includes(':')
+            ? (permission as Permission)
+            : (pageId ? `${permission}:page.${pageId}` : permission) as Permission;
           
-          try {
-            const hasAccess = await checkPermission(permission, pageId);
-            return { item, hasAccess };
-          } catch {
-            // On error, default to hiding the item (fail-safe)
-            return { item, hasAccess: false };
+          // Check permission map (super admin check already handled in getPermissionMap)
+          const hasAccess = permissionMap['*'] === true || permissionMap[fullPermission] === true;
+          
+          if (auditLog) {
+            console.log(`[PaceAppLayout] Navigation filtering:`, {
+              item: item.label,
+              href: item.href,
+              pageId,
+              permission: fullPermission,
+              hasAccess,
+            });
           }
-        })
-      );
+          
+          return { item, hasAccess };
+        });
 
-      if (!isMounted) return;
+        if (!isMounted) return;
 
-      const accessibleItems = filtered
-        .filter(({ hasAccess }) => hasAccess)
-        .map(({ item }) => item);
+        const accessibleItems = filtered
+          .filter(({ hasAccess }) => hasAccess)
+          .map(({ item }) => item);
 
-      setFilteredMenuItems(accessibleItems);
+        setFilteredMenuItems(accessibleItems);
+      } catch (error) {
+        // On error, fall back to showing all items (graceful degradation)
+        // This prevents navigation from being empty if permission checks fail
+        console.error('[PaceAppLayout] Failed to load permission map for navigation filtering:', error);
+        if (isMounted) {
+          setFilteredMenuItems(baseMenuItems);
+        }
+      }
     };
 
     filterItems();

package/src/components/PaceAppLayout/__tests__/PaceAppLayout.security.test.tsx

@@ -715,7 +715,8 @@ describe('PaceAppLayout Security', () => {
       const { isPermitted } = await import('../../../rbac/api');
       vi.mocked(isPermitted).mockImplementation(({ userId, scope, permission, pageId }) => {
         // Simulate user trying to access admin with read permission
-        if (pageId === 'admin' && permission === 'read') {
+        // Permission is now formatted as "operation:page.pageId"
+        if (pageId === 'admin' && permission === 'read:page.admin') {
           return Promise.resolve(false);
         }
         return Promise.resolve(true);

package/src/components/PaceAppLayout/__tests__/PaceAppLayout.unit.test.tsx

@@ -572,7 +572,7 @@ describe('PaceAppLayout Component', () => {
         expect(mockIsPermitted).toHaveBeenCalledWith({
           userId: 'test-user-id',
           scope: expect.objectContaining({ organisationId: 'test-org-123' }),
-          permission: 'delete',
+          permission: 'delete:page.test-path',
           pageId: 'test-path'
         });
       });
@@ -597,7 +597,7 @@ describe('PaceAppLayout Component', () => {
         expect(mockIsPermitted).toHaveBeenCalledWith({
           userId: 'test-user-id',
           scope: expect.objectContaining({ organisationId: 'test-org-123' }),
-          permission: 'read',
+          permission: 'read:page.custom-page-id',
           pageId: 'custom-page-id'
         });
       });
@@ -816,11 +816,8 @@ describe('PaceAppLayout Component', () => {
     });
 
     it('handles location changes correctly', async () => {
-      // Change location
-      Object.defineProperty(window, 'location', {
-        value: { pathname: '/new-path' },
-        writable: true
-      });
+      // Change location - update the mockLocation object since component uses useLocation()
+      mockLocation.pathname = '/new-path';
       
       render(
         <TestWrapper>
@@ -832,10 +829,13 @@ describe('PaceAppLayout Component', () => {
         expect(mockIsPermitted).toHaveBeenCalledWith({
           userId: 'test-user-id',
           scope: expect.objectContaining({ organisationId: 'test-org-123' }),
-          permission: 'read',
-          pageId: 'test-path'
+          permission: 'read:page.new-path',
+          pageId: 'new-path'
         });
       });
+      
+      // Reset for other tests
+      mockLocation.pathname = '/test-path';
     });
   });
 

package/src/index.ts

@@ -20,6 +20,9 @@
 export { UnifiedAuthProvider, useUnifiedAuth } from './providers/UnifiedAuthProvider';
 export type { UnifiedAuthProviderProps, UnifiedAuthContextType, UserEventAccess } from './providers/UnifiedAuthProvider';
 
+// Session tracking utility (for manual use if needed)
+export { useSessionTracking } from './utils/sessionTracking';
+
 // Provider components (using service architecture)
 export { EventProvider } from './providers/EventProvider';
 export { OrganisationProvider } from './providers/OrganisationProvider';

package/src/providers/services/AuthServiceProvider.tsx

@@ -24,13 +24,14 @@ export const AuthServiceContext = createContext<AuthServiceContextType | null>(n
 export interface AuthServiceProviderProps {
   children: React.ReactNode;
   supabaseClient: SupabaseClient;
+  appName?: string;
 }
 
-export function AuthServiceProvider({ children, supabaseClient }: AuthServiceProviderProps) {
+export function AuthServiceProvider({ children, supabaseClient, appName }: AuthServiceProviderProps) {
   // Create service instance with useMemo to prevent recreation on every render
   const authService = useMemo(
-    () => new AuthService(supabaseClient),
-    [supabaseClient]
+    () => new AuthService(supabaseClient, appName),
+    [supabaseClient, appName]
   );
 
   const [sessionRestoration, setSessionRestoration] = useState<SessionRestorationState>(

package/src/providers/services/UnifiedAuthProvider.tsx

@@ -526,7 +526,7 @@ export function UnifiedAuthProvider({
   dangerouslyDisableInactivity = false
 }: UnifiedAuthProviderProps) {
   return (
-    <AuthServiceProvider supabaseClient={supabaseClient}>
+    <AuthServiceProvider supabaseClient={supabaseClient} appName={appName}>
       <ServiceAwareProviders
         supabaseClient={supabaseClient}
         appName={appName}

package/src/rbac/engine.ts

@@ -474,11 +474,13 @@ export class RBACEngine {
 
     try {
       const { userId, scope } = input;
+      // Call unified function (tech debt removed: consolidated from 2 overloaded versions)
       const { data, error } = await (this.supabase as any).rpc('rbac_permissions_get', {
         p_user_id: userId,
         p_organisation_id: scope.organisationId || null,
         p_event_id: scope.eventId || null,
         p_app_id: scope.appId || null,
+        p_page_id: null, // Optional: can filter to specific page if needed
       });
 
       if (error) {

package/src/services/AuthService.ts

@@ -28,10 +28,12 @@ export class AuthService extends BaseService implements IAuthService {
   private restorationTimeoutId: ReturnType<typeof setTimeout> | null = null;
   private readonly restorationTimeoutMs = 5000;
   private restorationStartTime: number | null = null;
+  private appName: string | undefined = undefined;
 
-  constructor(supabaseClient: SupabaseClient) {
+  constructor(supabaseClient: SupabaseClient, appName?: string) {
     super();
     this.supabaseClient = supabaseClient;
+    this.appName = appName;
   }
 
   // Auth state getters
@@ -386,6 +388,13 @@ export class AuthService extends BaseService implements IAuthService {
               this.session = null;
               this.user = null;
               this.authError = null;
+              
+              // Automatic session tracking (non-blocking)
+              if (session?.user) {
+                this.trackSession('logout', session).catch(err => {
+                  console.warn('[AuthService] Failed to track logout session:', err);
+                });
+              }
             } else if (event === 'SIGNED_IN' || event === 'TOKEN_REFRESHED') {
               this.session = session;
               this.user = session?.user ?? null;
@@ -394,6 +403,14 @@ export class AuthService extends BaseService implements IAuthService {
               if (session) {
                 this.authError = null;
               }
+              
+              // Automatic session tracking for login (non-blocking)
+              // Only track on SIGNED_IN, not TOKEN_REFRESHED (to avoid duplicate login records)
+              if (event === 'SIGNED_IN' && session?.user) {
+                this.trackSession('login', session).catch(err => {
+                  console.warn('[AuthService] Failed to track login session:', err);
+                });
+              }
             } else if (event === 'INITIAL_SESSION') {
               if (session) {
                 this.session = session;
@@ -502,6 +519,67 @@ export class AuthService extends BaseService implements IAuthService {
     }
   }
 
+  /**
+   * Automatically track user session using rbac_session_track
+   * This method is called automatically on SIGNED_IN and SIGNED_OUT events.
+   * It's non-blocking and failures are logged as warnings.
+   */
+  private async trackSession(
+    sessionType: 'login' | 'logout',
+    session: Session | null
+  ): Promise<void> {
+    if (!this.supabaseClient || !session?.user) {
+      return;
+    }
+
+    try {
+      // Resolve app_id from appName if available
+      let appId: string | undefined = undefined;
+      if (this.appName) {
+        const { data, error } = await this.supabaseClient
+          .from('rbac_apps')
+          .select('id')
+          .eq('name', this.appName)
+          .eq('is_active', true)
+          .single();
+        
+        if (!error && data) {
+          appId = data.id;
+        }
+      }
+
+      // Get IP address and user agent from browser (if available)
+      const ipAddress = undefined; // Browser doesn't expose IP directly, could use API
+      const userAgent = typeof navigator !== 'undefined' ? navigator.userAgent : undefined;
+      
+      // Get device fingerprint from localStorage if available
+      // Note: Device fingerprinting should be done by consuming app and passed via custom header
+      // For now, we'll skip it to avoid dependencies
+      const deviceFingerprint = undefined;
+
+      // Call rbac_session_track RPC function
+      // This automatically inserts into rbac_user_sessions AND rbac_user_login_history (for login)
+      const { error } = await (this.supabaseClient as any).rpc('rbac_session_track', {
+        p_user_id: session.user.id,
+        p_session_type: sessionType,
+        p_event_id: null, // Event ID should come from context, not auth service
+        p_app_id: appId,
+        p_ip_address: ipAddress,
+        p_user_agent: userAgent,
+        p_device_fingerprint: deviceFingerprint,
+      });
+
+      if (error) {
+        console.warn(`[AuthService] Failed to track ${sessionType} session:`, error);
+      } else {
+        console.debug(`[AuthService] Successfully tracked ${sessionType} session`);
+      }
+    } catch (error) {
+      // Log error but don't throw (non-blocking)
+      console.warn(`[AuthService] Error tracking ${sessionType} session:`, error);
+    }
+  }
+
   private setupErrorHandlers(): void {
     if (typeof window === 'undefined') return;