@nocios/crudify-ui 1.2.36 → 1.3.0

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.

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import crudify__default from '@nocios/crudify-browser';
 export * from '@nocios/crudify-browser';
 export { default as crudify } from '@nocios/crudify-browser';
 import React, { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type BoxScreenType = "login" | "signUp" | "forgotPassword" | "resetPassword" | "checkCode";
 interface CrudifyLoginConfig {
@@ -917,4 +918,236 @@ declare function parseJavaScriptError(error: unknown): ParsedError;
  */
 declare function handleCrudifyError(error: unknown): ParsedError[];
 
-export { type ApiError, type BoxScreenType, type CrudifyApiResponse, type CrudifyConfig, type CrudifyDataContextState, CrudifyDataProvider, type CrudifyDataProviderProps, CrudifyLogin, type CrudifyLoginConfig, type CrudifyLoginProps, type CrudifyLoginTranslations, type CrudifyTransactionResponse, type CrudifyUserData, ERROR_CODES, ERROR_SEVERITY_MAP, type ErrorCode, type ErrorSeverity, type ForgotPasswordRequest, type JWTPayload$1 as JWTPayload, type JwtPayload, type LoginRequest, type LoginResponse, type ParsedError, type ResetPasswordRequest, type ResolvedConfig, type TransactionResponseData, type UseCrudifyAuthReturn, type UseCrudifyConfigReturn, type UseCrudifyDataReturn, type UseCrudifyInstanceReturn, type UseCrudifyUserOptions, type UseCrudifyUserReturn, type UserLoginData, type UserProfile, UserProfileDisplay, type ValidateCodeRequest, type ValidationError, configurationManager, crudifyInitializer, decodeJwtSafely, getCookie, getCrudifyInstanceAsync, getCrudifyInstanceSync, getCurrentUserEmail, getErrorMessage, handleCrudifyError, isTokenExpired, parseApiError, parseJavaScriptError, parseTransactionError, secureLocalStorage, secureSessionStorage, tokenManager, useCrudifyAuth, useCrudifyConfig, useCrudifyData, useCrudifyDataContext, useCrudifyInstance, useCrudifyLogin, useCrudifyUser, useUserProfile };
+type TokenData = {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    refreshExpiresAt: number;
+};
+type StorageType = 'localStorage' | 'sessionStorage' | 'none';
+declare class TokenStorage {
+    private static readonly TOKEN_KEY;
+    private static readonly ENCRYPTION_KEY;
+    private static storageType;
+    /**
+     * Configurar tipo de almacenamiento
+     */
+    static setStorageType(type: StorageType): void;
+    /**
+     * Verificar si el storage está disponible
+     */
+    private static isStorageAvailable;
+    /**
+     * Obtener instancia de storage
+     */
+    private static getStorage;
+    /**
+     * Encriptar datos sensibles
+     */
+    private static encrypt;
+    /**
+     * Desencriptar datos
+     */
+    private static decrypt;
+    /**
+     * Guardar tokens de forma segura
+     */
+    static saveTokens(tokens: TokenData): void;
+    /**
+     * Obtener tokens guardados
+     */
+    static getTokens(): TokenData | null;
+    /**
+     * Limpiar tokens almacenados
+     */
+    static clearTokens(): void;
+    /**
+     * Verificar si hay tokens válidos guardados
+     */
+    static hasValidTokens(): boolean;
+    /**
+     * Obtener información de expiración
+     */
+    static getExpirationInfo(): {
+        accessExpired: boolean;
+        refreshExpired: boolean;
+        accessExpiresIn: number;
+        refreshExpiresIn: number;
+    } | null;
+    /**
+     * Actualizar solo el access token (después de refresh)
+     */
+    static updateAccessToken(newAccessToken: string, newExpiresAt: number): void;
+}
+
+type SessionConfig = {
+    storageType?: StorageType;
+    autoRestore?: boolean;
+    enableLogging?: boolean;
+    onSessionExpired?: () => void;
+    onSessionRestored?: (tokens: TokenData) => void;
+    onLoginSuccess?: (tokens: TokenData) => void;
+    onLogout?: () => void;
+};
+type LoginResult = {
+    success: boolean;
+    tokens?: TokenData;
+    error?: string;
+};
+declare class SessionManager {
+    private static instance;
+    private config;
+    private initialized;
+    private constructor();
+    static getInstance(): SessionManager;
+    /**
+     * Inicializar el SessionManager
+     */
+    initialize(config?: SessionConfig): Promise<void>;
+    /**
+     * Login con persistencia automática
+     */
+    login(email: string, password: string): Promise<LoginResult>;
+    /**
+     * Logout con limpieza de tokens
+     */
+    logout(): Promise<void>;
+    /**
+     * Restaurar sesión desde storage
+     */
+    restoreSession(): Promise<boolean>;
+    /**
+     * Verificar si el usuario está autenticado
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Obtener información de tokens actuales
+     */
+    getTokenInfo(): {
+        isLoggedIn: boolean;
+        crudifyTokens: {
+            accessToken: string;
+            refreshToken: string;
+            expiresAt: number;
+            refreshExpiresAt: number;
+            isExpired: boolean;
+            isRefreshExpired: boolean;
+        };
+        storageInfo: {
+            accessExpired: boolean;
+            refreshExpired: boolean;
+            accessExpiresIn: number;
+            refreshExpiresIn: number;
+        } | null;
+        hasValidTokens: boolean;
+    };
+    /**
+     * Refrescar tokens manualmente
+     */
+    refreshTokens(): Promise<boolean>;
+    /**
+     * Configurar interceptor de respuesta para manejo automático de errores
+     */
+    setupResponseInterceptor(): void;
+    /**
+     * Limpiar sesión completamente
+     */
+    clearSession(): void;
+    private log;
+    private formatError;
+}
+
+type SessionState = {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    isInitialized: boolean;
+    tokens: TokenData | null;
+    error: string | null;
+};
+type UseSessionOptions = {
+    autoRestore?: boolean;
+    enableLogging?: boolean;
+    onSessionExpired?: () => void;
+    onSessionRestored?: (tokens: TokenData) => void;
+};
+declare function useSession(options?: UseSessionOptions): {
+    login: (email: string, password: string) => Promise<LoginResult>;
+    logout: () => Promise<void>;
+    refreshTokens: () => Promise<boolean>;
+    clearError: () => void;
+    getTokenInfo: () => {
+        isLoggedIn: boolean;
+        crudifyTokens: {
+            accessToken: string;
+            refreshToken: string;
+            expiresAt: number;
+            refreshExpiresAt: number;
+            isExpired: boolean;
+            isRefreshExpired: boolean;
+        };
+        storageInfo: {
+            accessExpired: boolean;
+            refreshExpired: boolean;
+            accessExpiresIn: number;
+            refreshExpiresIn: number;
+        } | null;
+        hasValidTokens: boolean;
+    };
+    isExpiringSoon: boolean;
+    expiresIn: number;
+    refreshExpiresIn: number;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    isInitialized: boolean;
+    tokens: TokenData | null;
+    error: string | null;
+};
+
+type SessionContextType = {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    isInitialized: boolean;
+    tokens: TokenData | null;
+    error: string | null;
+    login: (email: string, password: string) => Promise<LoginResult>;
+    logout: () => Promise<void>;
+    refreshTokens: () => Promise<boolean>;
+    clearError: () => void;
+    getTokenInfo: () => any;
+    isExpiringSoon: boolean;
+    expiresIn: number;
+    refreshExpiresIn: number;
+};
+type SessionProviderProps = {
+    children: ReactNode;
+    options?: UseSessionOptions;
+};
+/**
+ * Provider de sesión para envolver la aplicación
+ */
+declare function SessionProvider({ children, options }: SessionProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook para usar el contexto de sesión
+ */
+declare function useSessionContext(): SessionContextType;
+/**
+ * HOC para proteger rutas que requieren autenticación
+ */
+type ProtectedRouteProps = {
+    children: ReactNode;
+    fallback?: ReactNode;
+    redirectTo?: () => void;
+};
+declare function ProtectedRoute({ children, fallback, redirectTo }: ProtectedRouteProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Componente para mostrar información de la sesión (debug)
+ */
+declare function SessionDebugInfo(): react_jsx_runtime.JSX.Element;
+
+declare function LoginComponent(): react_jsx_runtime.JSX.Element;
+/**
+ * Componente simple de estado de sesión para mostrar en cualquier lugar
+ */
+declare function SessionStatus(): react_jsx_runtime.JSX.Element;
+
+export { type ApiError, type BoxScreenType, type CrudifyApiResponse, type CrudifyConfig, type CrudifyDataContextState, CrudifyDataProvider, type CrudifyDataProviderProps, CrudifyLogin, type CrudifyLoginConfig, type CrudifyLoginProps, type CrudifyLoginTranslations, type CrudifyTransactionResponse, type CrudifyUserData, ERROR_CODES, ERROR_SEVERITY_MAP, type ErrorCode, type ErrorSeverity, type ForgotPasswordRequest, type JWTPayload$1 as JWTPayload, type JwtPayload, LoginComponent, type LoginRequest, type LoginResponse, type LoginResult, type ParsedError, ProtectedRoute, type ProtectedRouteProps, type ResetPasswordRequest, type ResolvedConfig, type SessionConfig, SessionDebugInfo, SessionManager, SessionProvider, type SessionProviderProps, type SessionState, SessionStatus, type StorageType, type TokenData, TokenStorage, type TransactionResponseData, type UseCrudifyAuthReturn, type UseCrudifyConfigReturn, type UseCrudifyDataReturn, type UseCrudifyInstanceReturn, type UseCrudifyUserOptions, type UseCrudifyUserReturn, type UseSessionOptions, type UserLoginData, type UserProfile, UserProfileDisplay, type ValidateCodeRequest, type ValidationError, configurationManager, crudifyInitializer, decodeJwtSafely, getCookie, getCrudifyInstanceAsync, getCrudifyInstanceSync, getCurrentUserEmail, getErrorMessage, handleCrudifyError, isTokenExpired, parseApiError, parseJavaScriptError, parseTransactionError, secureLocalStorage, secureSessionStorage, tokenManager, useCrudifyAuth, useCrudifyConfig, useCrudifyData, useCrudifyDataContext, useCrudifyInstance, useCrudifyLogin, useCrudifyUser, useSession, useSessionContext, useUserProfile };