@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/implementation-guides/authentication.md

@@ -0,0 +1,1021 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
+# Authentication Implementation Guide
+
+> **📚 Complete Authentication Guide** | [← Back to Documentation](../README.md) | [Installation Guide](../getting-started/installation-guide.md)
+
+This comprehensive guide covers implementing authentication with PACE Core's UnifiedAuthProvider, including setup, configuration, troubleshooting, and best practices.
+
+> **📚 API Reference**: See [useUnifiedAuth Hook](../api-reference/hooks.md#useunifiedauth) for complete hook documentation.
+
+## Overview
+
+PACE Core provides a comprehensive authentication system built on Supabase that includes:
+
+- **🔐 Unified Authentication** - Single provider for auth, RBAC, and event management
+- **⏰ Inactivity Management** - Automatic session timeout with warnings
+- **🏢 Organisation Context** - Multi-tenant support with organisation switching
+- **📱 Event Management** - Event-based access control
+- **🔒 Session Persistence** - Secure session management with auto-refresh
+- **🎯 Permission Integration** - Built-in RBAC integration
+- **📊 Debug Support** - Comprehensive debugging and monitoring
+
+## Quick Start
+
+### 1. Project Setup
+
+```bash
+# Install PACE Core and dependencies
+npm install @jmruthers/pace-core @supabase/supabase-js react-router-dom
+
+# Install Tailwind CSS v4 (required)
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+```
+
+### 2. Environment Configuration
+
+Create `.env.local`:
+
+```bash
+# Supabase Configuration
+REACT_APP_SUPABASE_URL=https://your-project.supabase.co
+REACT_APP_SUPABASE_ANON_KEY=your-anon-key-here
+
+# ⚠️ CRITICAL: Use anon key, NOT service role key
+# The anon key starts with: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
+# The service role key has different permissions and can cause RPC timeouts
+```
+
+### 3. Supabase Client Setup
+
+```typescript
+// src/lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+
+const supabaseUrl = process.env.REACT_APP_SUPABASE_URL!
+const supabaseAnonKey = process.env.REACT_APP_SUPABASE_ANON_KEY!
+
+if (!supabaseUrl || !supabaseAnonKey) {
+  throw new Error('Missing Supabase environment variables')
+}
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+```
+
+### 4. App Setup with Authentication
+
+**CRITICAL**: UnifiedAuthProvider now requires inactivity timeout configuration:
+
+```tsx
+// src/main.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import { 
+  UnifiedAuthProvider
+} from '@jmruthers/pace-core'
+import { supabase } from './lib/supabase'
+import App from './App.tsx'
+
+// CRITICAL: Import the CSS system - includes everything you need
+import '@jmruthers/pace-core/src/styles/core.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <UnifiedAuthProvider 
+        supabaseClient={supabase} 
+        appName="my-app"
+        enableRBAC={true}
+        requireOrganisationContext={true}
+        idleTimeoutMs={30 * 60 * 1000}  // 30 minutes - REQUIRED
+        warnBeforeMs={60 * 1000}        // 60 seconds - REQUIRED
+        onIdleLogout={() => window.location.href = '/login'}  // REQUIRED
+      >
+        <App />
+      </UnifiedAuthProvider>
+    </BrowserRouter>
+  </React.StrictMode>,
+)
+```
+
+### 5. Basic Login Page
+
+```tsx
+// src/pages/LoginPage.tsx
+import { LoginForm } from '@jmruthers/pace-core';
+import { useNavigate } from 'react-router-dom';
+
+export function LoginPage() {
+  const navigate = useNavigate();
+
+  const handleLoginSuccess = () => {
+    navigate('/');
+  };
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-sec-50">
+      <div className="max-w-md w-full space-y-8">
+        <div>
+          <h2 className="mt-6 text-center text-3xl font-extrabold text-sec-900">
+            Sign in to My App
+          </h2>
+        </div>
+        <LoginForm onLoginSuccess={handleLoginSuccess} />
+      </div>
+    </div>
+  );
+}
+```
+
+### 6. Protected Routes
+
+```tsx
+// src/components/ProtectedRoute.tsx
+import { useUnifiedAuth, Navigate } from '@jmruthers/pace-core';
+
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { user, loading } = useUnifiedAuth();
+
+  if (loading) return <div>Loading...</div>;
+  if (!user) return <Navigate to="/login" />;
+
+  return <>{children}</>;
+}
+
+// Usage in App.tsx
+function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<LoginPage />} />
+      <Route path="/" element={
+        <ProtectedRoute>
+          <DashboardPage />
+        </ProtectedRoute>
+      } />
+    </Routes>
+  );
+}
+```
+
+## Configuration Options
+
+### UnifiedAuthProvider Props
+
+```typescript
+interface UnifiedAuthProviderProps {
+  // Required props
+  supabaseClient: SupabaseClient;
+  appName: string;
+  idleTimeoutMs: number;        // Session timeout in milliseconds
+  warnBeforeMs: number;         // Warning time before timeout
+  onIdleLogout: () => void;     // Callback when session times out
+  
+  // Optional props
+  enableRBAC?: boolean;         // Enable RBAC integration (default: true)
+  requireOrganisationContext?: boolean; // Require organisation selection (default: false)
+  debug?: boolean;              // Enable debug logging (default: false)
+  children: React.ReactNode;
+}
+```
+
+### Complete Configuration Example
+
+```tsx
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="meal-manager"
+  enableRBAC={true}
+  requireOrganisationContext={true}
+  debug={process.env.NODE_ENV === 'development'}
+  idleTimeoutMs={30 * 60 * 1000}  // 30 minutes
+  warnBeforeMs={5 * 60 * 1000}    // 5 minutes warning
+  onIdleLogout={() => {
+    // Custom logout logic
+    console.log('Session expired');
+    window.location.href = '/login';
+  }}
+>
+  <YourApp />
+</UnifiedAuthProvider>
+```
+
+## useUnifiedAuth Hook
+
+### Basic Usage
+
+```tsx
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function UserDashboard() {
+  const {
+    user,           // Current user object
+    loading,        // Loading state
+    error,          // Error state
+    session,        // Current session
+    signIn,         // Sign in function
+    signOut,        // Sign out function
+    signUp,         // Sign up function
+    resetPassword,  // Password reset function
+    selectedEvent,  // Currently selected event
+    setSelectedEvent, // Set selected event
+    hasEventAccess, // Check event access
+  } = useUnifiedAuth();
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!user) return <div>Please log in</div>;
+
+  return (
+    <div>
+      <h1>Welcome, {user.email}</h1>
+      <button onClick={signOut}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+### Authentication Methods
+
+#### Sign In
+
+```tsx
+const { signIn } = useUnifiedAuth();
+
+// Email/password login
+const handleLogin = async (email: string, password: string) => {
+  try {
+    await signIn({ email, password });
+    // User is now logged in
+  } catch (error) {
+    console.error('Login failed:', error);
+  }
+};
+
+// OAuth login (if configured)
+const handleGoogleLogin = async () => {
+  try {
+    await signIn({ provider: 'google' });
+  } catch (error) {
+    console.error('Google login failed:', error);
+  }
+};
+```
+
+#### Sign Up
+
+```tsx
+const { signUp } = useUnifiedAuth();
+
+const handleSignUp = async (email: string, password: string) => {
+  try {
+    await signUp({ email, password });
+    // User created, may need email confirmation
+  } catch (error) {
+    console.error('Sign up failed:', error);
+  }
+};
+```
+
+#### Password Reset
+
+```tsx
+const { resetPassword } = useUnifiedAuth();
+
+const handlePasswordReset = async (email: string) => {
+  try {
+    await resetPassword(email);
+    // Password reset email sent
+  } catch (error) {
+    console.error('Password reset failed:', error);
+  }
+};
+```
+
+#### Sign Out
+
+```tsx
+const { signOut } = useUnifiedAuth();
+
+const handleSignOut = async () => {
+  try {
+    await signOut();
+    // User is now logged out
+  } catch (error) {
+    console.error('Sign out failed:', error);
+  }
+};
+```
+
+## Event Management Integration
+
+### Event Selection
+
+```tsx
+function EventSelector() {
+  const { selectedEvent, setSelectedEvent, hasEventAccess } = useUnifiedAuth();
+
+  const handleEventChange = (eventId: string) => {
+    if (hasEventAccess(eventId)) {
+      setSelectedEvent(eventId);
+    }
+  };
+
+  return (
+    <select value={selectedEvent?.id || ''} onChange={(e) => handleEventChange(e.target.value)}>
+      <option value="">Select an event</option>
+      {/* Event options */}
+    </select>
+  );
+}
+```
+
+### Event Access Control
+
+```tsx
+function EventContent() {
+  const { selectedEvent, hasEventAccess } = useUnifiedAuth();
+
+  if (!selectedEvent) {
+    return <div>Please select an event</div>;
+  }
+
+  if (!hasEventAccess(selectedEvent.id)) {
+    return <div>You don't have access to this event</div>;
+  }
+
+  return <div>Event content for {selectedEvent.name}</div>;
+}
+```
+
+## Organisation Context
+
+### Organisation Selection
+
+```tsx
+function OrganisationSelector() {
+  const { user, selectedOrganisation, setSelectedOrganisation } = useUnifiedAuth();
+
+  const handleOrganisationChange = (orgId: string) => {
+    setSelectedOrganisation(orgId);
+  };
+
+  return (
+    <select 
+      value={selectedOrganisation?.id || ''} 
+      onChange={(e) => handleOrganisationChange(e.target.value)}
+    >
+      <option value="">Select organisation</option>
+      {user?.organisations?.map(org => (
+        <option key={org.id} value={org.id}>
+          {org.name}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+## Session Management
+
+### Session Persistence
+
+```tsx
+// Supabase client configuration for session persistence
+const supabase = createClient(url, key, {
+  auth: {
+    persistSession: true,
+    storage: window.localStorage,
+    autoRefreshToken: true,
+    detectSessionInUrl: true
+  }
+});
+```
+
+### Session Monitoring
+
+```tsx
+import { useEffect } from 'react';
+import { supabase } from './lib/supabase';
+
+function SessionMonitor() {
+  useEffect(() => {
+    const {
+      data: { subscription },
+    } = supabase.auth.onAuthStateChange((event, session) => {
+      console.log('Auth event:', event, session?.user?.id);
+      
+      if (event === 'SIGNED_IN') {
+        console.log('User signed in:', session?.user);
+      }
+      if (event === 'SIGNED_OUT') {
+        console.log('User signed out');
+      }
+      if (event === 'TOKEN_REFRESHED') {
+        console.log('Token refreshed');
+      }
+    });
+
+    return () => subscription.unsubscribe();
+  }, []);
+
+  return null;
+}
+```
+
+## Inactivity Management
+
+### Configuration
+
+```tsx
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="my-app"
+  idleTimeoutMs={30 * 60 * 1000}  // 30 minutes
+  warnBeforeMs={5 * 60 * 1000}    // 5 minutes warning
+  onIdleLogout={() => {
+    // Custom logout logic
+    localStorage.clear();
+    window.location.href = '/login';
+  }}
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+### Custom Inactivity Handling
+
+```tsx
+function InactivityHandler() {
+  const { user } = useUnifiedAuth();
+
+  useEffect(() => {
+    if (!user) return;
+
+    let inactivityTimer: NodeJS.Timeout;
+    let warningTimer: NodeJS.Timeout;
+
+    const resetTimers = () => {
+      clearTimeout(inactivityTimer);
+      clearTimeout(warningTimer);
+      
+      // Set warning timer
+      warningTimer = setTimeout(() => {
+        alert('You will be logged out in 5 minutes due to inactivity');
+      }, 25 * 60 * 1000); // 25 minutes
+      
+      // Set logout timer
+      inactivityTimer = setTimeout(() => {
+        window.location.href = '/login';
+      }, 30 * 60 * 1000); // 30 minutes
+    };
+
+    // Reset timers on user activity
+    const events = ['mousedown', 'mousemove', 'keypress', 'scroll', 'touchstart'];
+    events.forEach(event => {
+      document.addEventListener(event, resetTimers, true);
+    });
+
+    resetTimers();
+
+    return () => {
+      clearTimeout(inactivityTimer);
+      clearTimeout(warningTimer);
+      events.forEach(event => {
+        document.removeEventListener(event, resetTimers, true);
+      });
+    };
+  }, [user]);
+
+  return null;
+}
+```
+
+## Navigation Integration
+
+### Permission-Based Navigation
+
+```tsx
+import { NavigationMenu, NavigationItem } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+const navigationItems = [
+  {
+    label: 'Dashboard',
+    href: '/dashboard',
+    icon: 'Home',
+    permissions: ['read:dashboard']
+  },
+  {
+    label: 'Users',
+    href: '/users',
+    icon: 'Users',
+    permissions: ['read:users']
+  },
+  {
+    label: 'Events',
+    href: '/events',
+    icon: 'Calendar',
+    permissions: ['read:events']
+  },
+  {
+    label: 'Settings',
+    href: '/settings',
+    icon: 'Settings',
+    permissions: ['read:settings']
+  }
+];
+
+function AppNavigation() {
+  const { user } = useUnifiedAuth();
+  
+  return (
+    <NavigationMenu
+      items={navigationItems}
+      currentPath={pathname}
+      onNavigate={(href) => router.push(href)}
+      user={user}
+    />
+  );
+}
+```
+
+### User Menu Integration
+
+```tsx
+import { 
+  NavigationMenu, 
+  UserMenu, 
+  Header 
+} from '@jmruthers/pace-core';
+
+function AppHeader() {
+  const { user, signOut } = useUnifiedAuth();
+
+  const handleLogout = async () => {
+    await signOut();
+    window.location.href = '/login';
+  };
+
+  return (
+    <Header
+      title="My App"
+      user={user}
+      onLogout={handleLogout}
+      navigation={
+        <NavigationMenu
+          items={navigationItems}
+          currentPath={pathname}
+          onNavigate={(href) => router.push(href)}
+        />
+      }
+    />
+  );
+}
+```
+
+## Common Patterns
+
+### Authentication State Management
+
+```tsx
+function useAuthState() {
+  const { user, loading, error } = useUnifiedAuth();
+  
+  return {
+    isAuthenticated: !!user,
+    isLoading: loading,
+    hasError: !!error,
+    user,
+    error
+  };
+}
+```
+
+### Conditional Rendering
+
+```tsx
+function ConditionalContent() {
+  const { user, loading } = useUnifiedAuth();
+
+  if (loading) {
+    return <div>Loading...</div>;
+  }
+
+  if (!user) {
+    return <div>Please log in to continue</div>;
+  }
+
+  return <div>Welcome, {user.email}!</div>;
+}
+```
+
+### Form Integration
+
+```tsx
+function LoginForm() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const { signIn } = useUnifiedAuth();
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+
+    try {
+      await signIn({ email, password });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Login failed');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="Email"
+        required
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder="Password"
+        required
+      />
+      {error && <div className="error">{error}</div>}
+      <button type="submit" disabled={loading}>
+        {loading ? 'Signing in...' : 'Sign in'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Troubleshooting
+
+### Most Common Issues
+
+#### 1. Login Not Working
+
+**Symptoms:**
+- Login button does nothing
+- "Invalid credentials" error
+- Redirect not happening after login
+
+**Immediate Fix:**
+```tsx
+// ✅ Ensure proper provider hierarchy
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+import { supabase } from './lib/supabase';
+
+function App() {
+  return (
+    <UnifiedAuthProvider
+      supabaseClient={supabase}
+      appName="my-app"
+      idleTimeoutMs={30 * 60 * 1000}
+      warnBeforeMs={5 * 60 * 1000}
+      onIdleLogout={() => window.location.href = '/login'}
+    >
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+**Checklist:**
+- [ ] Supabase URL and key are correct
+- [ ] Provider hierarchy correct (Auth > Org > Event)
+- [ ] User credentials are valid in Supabase
+- [ ] Network connectivity working
+- [ ] Browser not blocking cookies
+
+#### 2. Session Not Persisting
+
+**Symptoms:**
+- User logged out on page refresh
+- Session cleared on browser restart
+- Need to login repeatedly
+
+**Fix:**
+```tsx
+// Check Supabase session configuration
+const supabase = createClient(url, key, {
+  auth: {
+    persistSession: true,
+    storage: window.localStorage,
+    autoRefreshToken: true,
+    detectSessionInUrl: true
+  }
+});
+
+// Verify session exists
+useEffect(() => {
+  supabase.auth.getSession().then(({ data: { session } }) => {
+    console.log('Current session:', session);
+  });
+}, []);
+```
+
+#### 3. User State Not Updating
+
+**Symptoms:**
+- Login succeeds but user state is null
+- `useUnifiedAuth()` returns undefined
+- Components don't react to auth changes
+
+**Fix:**
+```tsx
+// ✅ Ensure provider is set up correctly
+function App() {
+  return (
+    <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+      <AuthTest />
+    </UnifiedAuthProvider>
+  );
+}
+
+function AuthTest() {
+  const { user, loading, error } = useUnifiedAuth();
+  
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!user) return <div>Not logged in</div>;
+  
+  return <div>Welcome {user.email}</div>;
+}
+```
+
+### Detailed Solutions
+
+#### Wrong Supabase Configuration
+
+**Problem:** Using service role key instead of anon key
+
+```tsx
+// ❌ WRONG - Service role key
+const supabase = createClient(url, SERVICE_ROLE_KEY);
+
+// ✅ CORRECT - Anonymous key
+const supabase = createClient(url, ANON_KEY);
+
+// Check key format
+console.log('Key starts with:', ANON_KEY.substring(0, 30));
+// Should be: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
+```
+
+#### Provider Hierarchy Issues
+
+**Problem:** Providers not in correct order
+
+```tsx
+// ❌ WRONG ORDER
+<EventProvider>
+  <OrganisationProvider>
+    <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+      <App />
+    </UnifiedAuthProvider>
+  </OrganisationProvider>
+</EventProvider>
+
+// ✅ CORRECT ORDER
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <OrganisationProvider>
+    <EventProvider>
+      <App />
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+#### Missing Inactivity Timeout Props
+
+**Problem:** TypeScript error in v0.5.65+
+
+```tsx
+// ❌ OLD API (broken in v0.5.65+)
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <App />
+</UnifiedAuthProvider>
+
+// ✅ NEW API (required)
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="my-app"
+  idleTimeoutMs={30 * 60 * 1000}    // Required
+  warnBeforeMs={5 * 60 * 1000}      // Required
+  onIdleLogout={() => navigate('/login')} // Required
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+### Debugging Techniques
+
+#### Enable Debug Logging
+
+```tsx
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="my-app"
+  debug={true} // Enable debug mode
+  idleTimeoutMs={30 * 60 * 1000}
+  warnBeforeMs={5 * 60 * 1000}
+  onIdleLogout={() => window.location.href = '/login'}
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+#### Check Auth State
+
+```tsx
+function AuthDebugger() {
+  const { user, loading, error, session } = useUnifiedAuth();
+  
+  useEffect(() => {
+    console.log('Auth state:', {
+      user: user?.id,
+      email: user?.email,
+      loading,
+      error: error?.message,
+      hasSession: !!session
+    });
+  }, [user, loading, error, session]);
+  
+  return null;
+}
+
+// Add to your app
+<AuthDebugger />
+```
+
+### Common Error Messages
+
+#### "Missing supabaseClient prop"
+
+**Problem:** `UnifiedAuthProvider` not receiving supabase client
+
+**Fix:**
+```tsx
+// ✅ Ensure you're passing the client
+import { createClient } from '@supabase/supabase-js';
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+const supabase = createClient(url, key);
+
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <App />
+</UnifiedAuthProvider>
+```
+
+#### "Invalid credentials"
+
+**Problem:** Wrong email/password or user not found
+
+**Solutions:**
+1. Check user exists in Supabase Auth
+2. Verify email/password are correct
+3. Check email confirmation required
+4. Verify user is not disabled
+
+```tsx
+// Check user exists
+const { data, error } = await supabase.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'password'
+});
+console.log('Login result:', { data, error });
+```
+
+#### "Missing timeout props" (v0.5.65+)
+
+**Problem:** Required props not provided
+
+**Fix:**
+```tsx
+// Add all required props
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="my-app"
+  idleTimeoutMs={30 * 60 * 1000}    // 30 minutes
+  warnBeforeMs={5 * 60 * 1000}      // 5 minutes warning
+  onIdleLogout={() => window.location.href = '/login'}
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+## Best Practices
+
+### Security
+
+1. **Use Anonymous Key**: Never use service role key in client-side code
+2. **Enable RLS**: Use Row Level Security in Supabase
+3. **Validate Input**: Always validate user input
+4. **Secure Storage**: Use secure storage for sensitive data
+5. **HTTPS Only**: Always use HTTPS in production
+
+### Performance
+
+1. **Lazy Loading**: Load authentication components lazily
+2. **Memoization**: Use React.memo for expensive components
+3. **Debouncing**: Debounce user input in forms
+4. **Session Caching**: Cache session data appropriately
+5. **Error Boundaries**: Use error boundaries for auth components
+
+### User Experience
+
+1. **Loading States**: Always show loading states
+2. **Error Messages**: Provide clear error messages
+3. **Redirects**: Handle redirects gracefully
+4. **Session Warnings**: Warn users before session timeout
+5. **Accessibility**: Ensure auth components are accessible
+
+### Code Organization
+
+1. **Separation of Concerns**: Separate auth logic from UI
+2. **Custom Hooks**: Create custom hooks for auth logic
+3. **Type Safety**: Use TypeScript for better type safety
+4. **Error Handling**: Implement comprehensive error handling
+5. **Testing**: Write tests for auth components
+
+## Migration Guide
+
+### From v0.5.64 to v0.5.65+
+
+**Breaking Changes:**
+- Inactivity timeout props are now required
+- Provider hierarchy has changed
+- Some hook interfaces have been updated
+
+**Migration Steps:**
+
+1. **Update Provider Configuration:**
+```tsx
+// Before
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <App />
+</UnifiedAuthProvider>
+
+// After
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="my-app"
+  idleTimeoutMs={30 * 60 * 1000}
+  warnBeforeMs={5 * 60 * 1000}
+  onIdleLogout={() => window.location.href = '/login'}
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+2. **Update Hook Usage:**
+```tsx
+// Before
+const { user, signIn, signOut } = useUnifiedAuth();
+
+// After (same interface, but with additional features)
+const { user, signIn, signOut, selectedEvent, setSelectedEvent } = useUnifiedAuth();
+```
+
+3. **Test Authentication Flow:**
+- Verify login/logout works
+- Check session persistence
+- Test inactivity timeout
+- Verify error handling
+
+## Examples
+
+### Complete Authentication App
+
+See the [Authentication Implementation Guide](./authentication.md) for a complete working example with step-by-step instructions.
+
+### Advanced Patterns
+
+See the [Common Patterns Guide](./best-practices/common-patterns.md) for advanced authentication patterns.
+
+## Related Documentation
+
+- [RBAC Integration](./rbac/README.md) - Role-based access control
+- [Event Management](./events/README.md) - Event-based access control
+- [Navigation Integration](./navigation.md) - Permission-based navigation
+- [Troubleshooting Guide](./troubleshooting/README.md) - Common issues and solutions
+
+## Conclusion
+
+PACE Core's authentication system provides a comprehensive solution for user authentication, session management, and access control. With built-in RBAC integration, event management, and inactivity handling, it provides everything needed for secure, user-friendly applications.
+
+The system is designed to be both powerful and easy to use, with extensive debugging support and clear error messages to help developers build robust authentication flows.