@nocios/crudify-ui 1.2.36 → 1.3.1

package/MIGRATION-GUIDE.md

@@ -0,0 +1,312 @@
+# Migration Guide: Refresh Token Pattern Implementation
+
+## Overview
+
+This guide helps you migrate from the standard JWT authentication to the new **Refresh Token Pattern** implementation in CRUDIFY v1.2.0+.
+
+The Refresh Token Pattern addresses security vulnerabilities by:
+- Using short-lived access tokens (15 minutes)
+- Implementing long-lived refresh tokens (7 days)
+- Automatic token refresh before expiration
+- Secure token storage with encryption
+- Session restoration on page reload
+
+## Prerequisites
+
+Ensure you have the following versions installed:
+- `@nocios/crudify-core` v1.2.0+
+- `@nocios/crudify-ui` v1.2.0+
+
+```bash
+npm update @nocios/crudify-core @nocios/crudify-ui
+```
+
+## Migration Steps
+
+### 1. Update Your Backend (if applicable)
+
+If you're using the CRUDIFY backend, ensure you've deployed the refresh token endpoints. The new login response now includes:
+
+```typescript
+{
+  token: string,           // Access token (short-lived)
+  refreshToken: string,    // Refresh token (long-lived)
+  expiresIn: number,       // Access token expiration
+  refreshExpiresIn: number // Refresh token expiration
+}
+```
+
+### 2. Replace SessionProvider Implementation
+
+**BEFORE (Old implementation):**
+```tsx
+import { CrudifyDataProvider } from '@nocios/crudify-ui';
+
+function App() {
+  return (
+    <CrudifyDataProvider>
+      <YourApp />
+    </CrudifyDataProvider>
+  );
+}
+```
+
+**AFTER (New Refresh Token Pattern):**
+```tsx
+import { SessionProvider } from '@nocios/crudify-ui';
+
+function App() {
+  return (
+    <SessionProvider
+      options={{
+        autoRestore: true,          // Restore session on page reload
+        enableLogging: true,        // Enable debug logs
+        onSessionExpired: () => {   // Handle session expiration
+          console.log('Session expired');
+          // Redirect to login or show modal
+        },
+        onSessionRestored: (tokens) => {
+          console.log('Session restored:', tokens);
+        }
+      }}
+    >
+      <YourApp />
+    </SessionProvider>
+  );
+}
+```
+
+### 3. Update Authentication Logic
+
+**BEFORE (Manual login handling):**
+```tsx
+import { useCrudifyLogin } from '@nocios/crudify-ui';
+
+function LoginForm() {
+  const { login, isLoading } = useCrudifyLogin();
+
+  const handleLogin = async () => {
+    const result = await login(email, password);
+    // Manual token handling
+  };
+}
+```
+
+**AFTER (Automatic session management):**
+```tsx
+import { useSessionContext } from '@nocios/crudify-ui';
+
+function LoginForm() {
+  const { login, isLoading, isAuthenticated, logout } = useSessionContext();
+
+  const handleLogin = async () => {
+    const result = await login(email, password);
+    // Session is managed automatically
+    if (result.success) {
+      // User is now authenticated
+    }
+  };
+}
+```
+
+### 4. Replace Authentication Checks
+
+**BEFORE (Manual token checking):**
+```tsx
+import { getCurrentUserEmail, isTokenExpired } from '@nocios/crudify-ui';
+
+function ProtectedComponent() {
+  const userEmail = getCurrentUserEmail();
+  const tokenExpired = isTokenExpired();
+
+  if (!userEmail || tokenExpired) {
+    return <LoginRequired />;
+  }
+
+  return <ProtectedContent />;
+}
+```
+
+**AFTER (Using ProtectedRoute):**
+```tsx
+import { ProtectedRoute } from '@nocios/crudify-ui';
+
+function ProtectedComponent() {
+  return (
+    <ProtectedRoute fallback={<LoginRequired />}>
+      <ProtectedContent />
+    </ProtectedRoute>
+  );
+}
+```
+
+### 5. Update API Calls
+
+The good news is that your existing CRUDIFY API calls **don't need to change**! The automatic refresh mechanism is built into the core library:
+
+```tsx
+import { crudify } from '@nocios/crudify-ui';
+
+// This automatically handles token refresh if needed
+const result = await crudify.getPermissions();
+```
+
+## New Features Available
+
+### 1. Session Status Component
+
+Display authentication status anywhere in your app:
+
+```tsx
+import { SessionStatus } from '@nocios/crudify-ui';
+
+function AppHeader() {
+  return (
+    <AppBar>
+      <Toolbar>
+        <Typography variant="h6">My App</Typography>
+        <SessionStatus />  {/* Shows auth status */}
+      </Toolbar>
+    </AppBar>
+  );
+}
+```
+
+### 2. Login Component (Optional)
+
+Ready-to-use login component with Material-UI:
+
+```tsx
+import { LoginComponent } from '@nocios/crudify-ui';
+
+function LoginPage() {
+  return <LoginComponent />;
+}
+```
+
+### 3. Session Debug Info
+
+For development, show detailed session information:
+
+```tsx
+import { SessionDebugInfo } from '@nocios/crudify-ui';
+
+function App() {
+  return (
+    <div>
+      <YourApp />
+      {process.env.NODE_ENV === 'development' && (
+        <SessionDebugInfo />
+      )}
+    </div>
+  );
+}
+```
+
+### 4. Session Context Hook
+
+Access session state from any component:
+
+```tsx
+import { useSessionContext } from '@nocios/crudify-ui';
+
+function MyComponent() {
+  const {
+    isAuthenticated,
+    isLoading,
+    tokens,
+    error,
+    login,
+    logout,
+    refreshTokens,
+    isExpiringSoon,
+    expiresIn
+  } = useSessionContext();
+
+  return (
+    <div>
+      {isExpiringSoon && (
+        <Alert>Token expires in {Math.round(expiresIn / 60000)} minutes</Alert>
+      )}
+    </div>
+  );
+}
+```
+
+## Migration Checklist
+
+- [ ] Update package versions to v1.2.0+
+- [ ] Replace `CrudifyDataProvider` with `SessionProvider`
+- [ ] Update login logic to use `useSessionContext`
+- [ ] Replace manual auth checks with `ProtectedRoute`
+- [ ] Test automatic token refresh functionality
+- [ ] Test session restoration on page reload
+- [ ] Update logout logic to use session context
+- [ ] Remove manual token management code
+- [ ] Test error handling for expired refresh tokens
+- [ ] Add session debug info for development
+
+## Troubleshooting
+
+### Issue: "useSessionContext must be used within a SessionProvider"
+**Solution:** Ensure your entire app is wrapped with `SessionProvider`
+
+### Issue: Session not restoring on page reload
+**Solution:** Check that `autoRestore: true` is set in SessionProvider options
+
+### Issue: Automatic refresh not working
+**Solution:** Verify that your backend returns refresh tokens in the login response
+
+### Issue: Tokens not persisting between sessions
+**Solution:** Check browser storage permissions and ensure localStorage is enabled
+
+## Example Complete Implementation
+
+```tsx
+// App.tsx
+import React from 'react';
+import { SessionProvider, ProtectedRoute } from '@nocios/crudify-ui';
+import { LoginPage } from './pages/LoginPage';
+import { Dashboard } from './pages/Dashboard';
+
+function App() {
+  return (
+    <SessionProvider
+      options={{
+        autoRestore: true,
+        enableLogging: process.env.NODE_ENV === 'development',
+        onSessionExpired: () => {
+          console.log('Session expired - redirecting to login');
+        }
+      }}
+    >
+      <AppContent />
+    </SessionProvider>
+  );
+}
+
+function AppContent() {
+  return (
+    <div>
+      <LoginPage />
+
+      <ProtectedRoute fallback={null}>
+        <Dashboard />
+      </ProtectedRoute>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## Need Help?
+
+If you encounter issues during migration:
+
+1. Check the browser console for detailed error messages
+2. Enable logging with `enableLogging: true` in SessionProvider
+3. Use `<SessionDebugInfo />` to inspect session state
+4. Verify your backend is returning refresh tokens properly
+
+The new Refresh Token Pattern provides enhanced security and better user experience with automatic session management.