@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/migration-guides/unified-auth-provider-mandatory-timeouts.md

@@ -1,226 +0,0 @@
-# UnifiedAuthProvider Mandatory Timeouts Migration Guide
-
-> **Version**: 0.5.65+  
-> **Breaking Change**: Yes  
-> **Migration Required**: Yes
-
-## Overview
-
-As of version 0.5.65, the `UnifiedAuthProvider` now requires mandatory inactivity timeout configuration to prevent apps from accidentally bypassing auto-logout security features.
-
-## What Changed
-
-The following props are now **required** (previously optional):
-
-- `idleTimeoutMs` - Inactivity timeout in milliseconds
-- `warnBeforeMs` - Warning time before logout in milliseconds  
-- `onIdleLogout` - Callback when user is logged out due to inactivity
-
-## Migration Steps
-
-### 1. Update Your UnifiedAuthProvider
-
-**Before (❌ Will now cause TypeScript errors):**
-
-```tsx
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <UnifiedAuthProvider
-      supabaseClient={supabase}
-      appName="my-app"
-      enableRBAC={true}
-    >
-      <AppContent />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-**After (✅ Required configuration):**
-
-```tsx
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-import { useNavigate } from 'react-router-dom';
-
-function App() {
-  const navigate = useNavigate();
-
-  return (
-    <UnifiedAuthProvider
-      supabaseClient={supabase}
-      appName="my-app"
-      enableRBAC={true}
-      // Required inactivity configuration
-      idleTimeoutMs={30 * 60 * 1000}  // 30 minutes
-      warnBeforeMs={5 * 60 * 1000}    // 5 minutes warning
-      onIdleLogout={() => navigate('/login')}
-    >
-      <AppContent />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-### 2. Choose Appropriate Timeouts
-
-Select timeouts based on your security requirements:
-
-#### High Security (Sensitive Data)
-```tsx
-idleTimeoutMs={15 * 60 * 1000}  // 15 minutes
-warnBeforeMs={2 * 60 * 1000}    // 2 minutes warning
-```
-
-#### Standard Security (Most Apps)
-```tsx
-idleTimeoutMs={30 * 60 * 1000}  // 30 minutes
-warnBeforeMs={5 * 60 * 1000}    // 5 minutes warning
-```
-
-#### User-Friendly (Low Security Risk)
-```tsx
-idleTimeoutMs={60 * 60 * 1000}  // 1 hour
-warnBeforeMs={10 * 60 * 1000}   // 10 minutes warning
-```
-
-### 3. Handle the Logout Callback
-
-The `onIdleLogout` callback is called when the user is logged out due to inactivity. Implement appropriate navigation:
-
-#### React Router
-```tsx
-import { useNavigate } from 'react-router-dom';
-
-function App() {
-  const navigate = useNavigate();
-
-  return (
-    <UnifiedAuthProvider
-      // ... other props
-      onIdleLogout={() => {
-        console.log('User logged out due to inactivity');
-        navigate('/login', { replace: true });
-      }}
-    >
-      <AppContent />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-#### Next.js Router
-```tsx
-import { useRouter } from 'next/router';
-
-function App() {
-  const router = useRouter();
-
-  return (
-    <UnifiedAuthProvider
-      // ... other props
-      onIdleLogout={() => {
-        console.log('User logged out due to inactivity');
-        router.push('/login');
-      }}
-    >
-      <AppContent />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-#### Window Location (Fallback)
-```tsx
-<UnifiedAuthProvider
-  // ... other props
-  onIdleLogout={() => {
-    console.log('User logged out due to inactivity');
-    window.location.href = '/login';
-  }}
->
-  <AppContent />
-</UnifiedAuthProvider>
-```
-
-### 4. Optional: Custom Warning UI
-
-You can provide a custom inactivity warning modal:
-
-```tsx
-<UnifiedAuthProvider
-  // ... other props
-  renderInactivityWarning={({ timeRemaining, onStaySignedIn, onSignOutNow }) => (
-    <div className="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center z-50">
-      <div className="bg-white p-6 rounded-lg shadow-lg max-w-md">
-        <h3 className="text-lg font-semibold mb-4">Session Timeout Warning</h3>
-        <p className="mb-4">
-          You will be signed out in {Math.ceil(timeRemaining / 1000)} seconds due to inactivity.
-        </p>
-        <div className="flex gap-2">
-          <button 
-            onClick={onStaySignedIn}
-            className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
-          >
-            Stay Signed In
-          </button>
-          <button 
-            onClick={onSignOutNow}
-            className="px-4 py-2 bg-gray-500 text-white rounded hover:bg-gray-600"
-          >
-            Sign Out Now
-          </button>
-        </div>
-      </div>
-    </div>
-  )}
->
-  <AppContent />
-</UnifiedAuthProvider>
-```
-
-## Why This Change Was Made
-
-1. **Security**: Prevents apps from accidentally bypassing auto-logout
-2. **Explicit Configuration**: Forces developers to consciously choose timeout values
-3. **Compliance**: Ensures security requirements are met by default
-4. **Consistency**: All apps using pace-core will have proper session management
-
-## Testing Your Migration
-
-After updating your code:
-
-1. **Login to your app**
-2. **Wait for the warning** (should appear before the timeout)
-3. **Don't interact with the app** for the full timeout period
-4. **Verify you're logged out** and redirected to login
-
-## Rollback (Not Recommended)
-
-If you need to temporarily disable inactivity tracking (development only):
-
-```tsx
-<UnifiedAuthProvider
-  // ... other props
-  dangerouslyDisableInactivity={true} // Dev-only, not allowed in production
->
-  <AppContent />
-</UnifiedAuthProvider>
-```
-
-> **⚠️ Warning**: `dangerouslyDisableInactivity` is automatically disabled in production builds for security.
-
-## Support
-
-If you encounter issues during migration:
-
-1. Check the [API Reference](../api-reference/providers.md) for complete documentation
-2. Review the [Security Guide](../security/README.md) for best practices
-3. Ensure all required props are provided with appropriate values
-
-## Related Documentation
-
-- [UnifiedAuthProvider API Reference](../api-reference/providers.md)
-- [Security Best Practices](../security/README.md)
-- [Inactivity Tracking Guide](../implementation-guides/inactivity-tracking.md)