webs-sdk 0.19.64 → 0.19.66

package/docs/CORP_AUTH_USAGE.md

@@ -0,0 +1,687 @@
+# Corporate Authentication - Guía de Uso
+
+## 📋 Descripción
+
+La librería `CorporateAuthManager` proporciona autenticación corporativa centralizada basada en JWT para las aplicaciones web de Telecoming.
+
+## 🚀 Instalación
+
+```bash
+npm install webs-sdk
+```
+
+## ⚡ Inicio Rápido
+
+### 🖥️ Para Next.js Middleware (Server-Side)
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+import WebsSDK from 'webs-sdk'
+
+export async function middleware(request: NextRequest) {
+    // ✨ Validación server-side simplificada
+    const result = await WebsSDK.CorporateAuthManager.validateCorporateAuthServerSide(request)
+    
+    if (!result.authenticated) {
+        return result.redirectResponse // Redirección automática al login
+    }
+    
+    console.log(`✅ Usuario autenticado: ${result.user.name}`)
+    return NextResponse.next()
+}
+
+export const config = {
+    matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)']
+}
+```
+
+### 🌐 Para Aplicaciones Client-Side
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+// ✨ Método simplificado - Maneja TODO automáticamente
+const user = await WebsSDK.CorporateAuthManager.checkCorporateLogin();
+
+if (user) {
+    console.log(`Bienvenido, ${user.name}!`);
+    // Usuario autenticado - tu código aquí
+}
+// Si no hay usuario, ya habría redirigido automáticamente al login
+```
+
+### ¿Qué hace `checkCorporateLogin()`?
+
+Este método maneja **TODO** el flujo de autenticación automáticamente:
+
+1. ✅ **Detecta callbacks**: Si vienes del login con `?auth_token=...`, lo procesa
+2. ✅ **Verifica sesión**: Comprueba si ya estás autenticado (usa caché inteligente)
+3. ✅ **Valida token**: Verifica con el servidor (o localmente si no hay conexión)
+4. ✅ **Redirige al login**: Si no estás autenticado, te lleva al login automáticamente
+5. ✅ **Retorna usuario**: Si todo está OK, te devuelve los datos del usuario
+
+**Sin configuración adicional** - Todo funciona con valores por defecto de Telecoming.
+
+## 📖 Uso Básico
+
+### 1. Importar el SDK
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+// Acceder al gestor de autenticación corporativa
+const { CorporateAuthManager } = WebsSDK;
+```
+
+### 2. Configuración (Opcional)
+
+**Nota:** La configuración es completamente opcional. Por defecto usa los endpoints de Telecoming.
+
+```typescript
+// Solo si necesitas personalizar endpoints
+CorporateAuthManager.configure({
+    authDomain: 'https://auth.telecoming.com',
+    authValidateUrl: 'https://auth.telecoming.com/auth/api/validate',
+    authLogoutUrl: 'https://auth.telecoming.com/auth/logout',
+    authLoginUrl: 'https://auth.telecoming.com',
+    appDomain: 'https://apps.telecoming.com',
+    authCookieDuration: 86400, // 24 horas
+    authRevalidationInterval: 300, // 5 minutos
+});
+```
+
+## 🔐 Métodos Principales
+
+### Validar Usuario
+
+```typescript
+// Validar usuario sin redirección automática
+const userData = await CorporateAuthManager.validateUser(false);
+
+if (userData) {
+    console.log('Usuario autenticado:', userData.email);
+    console.log('Rol:', userData.role);
+} else {
+    console.log('Usuario no autenticado');
+}
+
+// Validar con redirección automática al login si no está autenticado
+const user = await CorporateAuthManager.validateUser(true);
+```
+
+### Login
+
+```typescript
+// Redirigir al login (guarda la URL actual para volver)
+CorporateAuthManager.login();
+
+// Redirigir al login con URL de retorno personalizada
+CorporateAuthManager.login('https://apps.telecoming.com/dashboard');
+```
+
+### Logout
+
+```typescript
+// Cerrar sesión
+await CorporateAuthManager.logout();
+
+// Cerrar sesión con redirección personalizada
+await CorporateAuthManager.logout('https://apps.telecoming.com/');
+```
+
+### Verificar Estado de Autenticación
+
+```typescript
+// Verificar sin consultar al servidor (usa caché)
+const status = await CorporateAuthManager.checkAuthStatus();
+
+if (status.authenticated) {
+    console.log('Usuario:', status.user?.email);
+}
+```
+
+### Obtener Usuario Actual
+
+```typescript
+const currentUser = await CorporateAuthManager.getCurrentUser();
+
+if (currentUser) {
+    console.log('ID:', currentUser.id);
+    console.log('Email:', currentUser.email);
+    console.log('Nombre:', currentUser.name);
+    console.log('Rol:', currentUser.role);
+}
+```
+
+### Verificar Permisos de Administrador
+
+```typescript
+const isUserAdmin = await CorporateAuthManager.isAdmin();
+
+if (isUserAdmin) {
+    console.log('El usuario tiene privilegios de administrador');
+}
+```
+
+### Verificar Sesión Activa
+
+```typescript
+const hasSession = await CorporateAuthManager.hasActiveSession();
+
+if (hasSession) {
+    console.log('Hay una sesión activa');
+}
+```
+
+### Manejar Callback de Autenticación
+
+```typescript
+// Llamar después de redirigir desde el login
+const success = await CorporateAuthManager.handleAuthCallback();
+
+if (success) {
+    console.log('Autenticación completada exitosamente');
+}
+```
+
+### Forzar Revalidación
+
+```typescript
+// Forzar una nueva validación del token
+const userData = await CorporateAuthManager.forceRevalidation();
+```
+
+## 📝 Ejemplos Completos con `checkCorporateLogin()`
+
+### Ejemplo 1: Aplicación Simple (Recomendado)
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+// En tu archivo principal o componente raíz
+async function init() {
+    // ✨ Una sola línea - maneja todo el flujo
+    const user = await WebsSDK.CorporateAuthManager.checkCorporateLogin();
+    
+    if (user) {
+        // Usuario autenticado - inicializar app
+        console.log(`Bienvenido, ${user.name}!`);
+        document.getElementById('username').textContent = user.name;
+        document.getElementById('app').style.display = 'block';
+    }
+    // Si no hay usuario, ya habría redirigido al login
+}
+
+// Ejecutar al cargar la página
+init();
+```
+
+### Ejemplo 2: App con Verificación de Admin
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+async function initApp() {
+    const { CorporateAuthManager } = WebsSDK;
+    
+    // Verificar autenticación automáticamente
+    const user = await CorporateAuthManager.checkCorporateLogin();
+    
+    if (user) {
+        // Mostrar nombre de usuario
+        document.getElementById('user-name').textContent = user.name;
+        
+        // Verificar si es admin para mostrar opciones adicionales
+        const isAdmin = await CorporateAuthManager.isAdmin(user);
+        if (isAdmin) {
+            document.getElementById('admin-panel').style.display = 'block';
+        }
+        
+        // Configurar botón de logout
+        document.getElementById('logout-btn').onclick = async () => {
+            await CorporateAuthManager.logout();
+        };
+    }
+}
+
+initApp();
+```
+
+### Ejemplo 3: React Component
+
+```typescript
+import { useEffect, useState } from 'react';
+import WebsSDK from 'webs-sdk';
+
+function App() {
+    const [user, setUser] = useState(null);
+    const [loading, setLoading] = useState(true);
+    
+    useEffect(() => {
+        async function checkAuth() {
+            // ✨ Método simplificado
+            const userData = await WebsSDK.CorporateAuthManager.checkCorporateLogin();
+            setUser(userData);
+            setLoading(false);
+        }
+        
+        checkAuth();
+    }, []);
+    
+    if (loading) {
+        return <div>Verificando autenticación...</div>;
+    }
+    
+    if (!user) {
+        return <div>Redirigiendo al login...</div>;
+    }
+    
+    return (
+        <div>
+            <h1>Bienvenido, {user.name}!</h1>
+            <button onClick={() => WebsSDK.CorporateAuthManager.logout()}>
+                Cerrar Sesión
+            </button>
+        </div>
+    );
+}
+
+export default App;
+```
+
+### Ejemplo 4: Next.js Page
+
+```typescript
+// pages/dashboard.tsx
+import { useEffect, useState } from 'react';
+import WebsSDK from 'webs-sdk';
+
+export default function Dashboard() {
+    const [user, setUser] = useState(null);
+    
+    useEffect(() => {
+        async function init() {
+            const userData = await WebsSDK.CorporateAuthManager.checkCorporateLogin();
+            if (userData) {
+                setUser(userData);
+            }
+        }
+        init();
+    }, []);
+    
+    if (!user) return <div>Cargando...</div>;
+    
+    return (
+        <div>
+            <h1>Dashboard</h1>
+            <p>Usuario: {user.email}</p>
+            <p>Rol: {user.role}</p>
+        </div>
+    );
+}
+```
+
+## 📝 Ejemplos con Métodos Individuales
+
+### Ejemplo 1: Proteger una Página
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+async function initProtectedPage() {
+    const { CorporateAuthManager } = WebsSDK;
+    
+    // Validar usuario (redirige automáticamente si no está autenticado)
+    const user = await CorporateAuthManager.validateUser(true);
+    
+    if (user) {
+        console.log(`Bienvenido, ${user.name}!`);
+        
+        // Mostrar contenido protegido
+        showDashboard(user);
+    }
+}
+
+initProtectedPage();
+```
+
+### Ejemplo 2: Página de Admin
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+async function initAdminPage() {
+    const { CorporateAuthManager } = WebsSDK;
+    
+    // Validar usuario
+    const user = await CorporateAuthManager.validateUser(true);
+    
+    if (user) {
+        // Verificar permisos de admin
+        const isAdmin = await CorporateAuthManager.isAdmin(user);
+        
+        if (isAdmin) {
+            console.log('Acceso concedido al panel de administración');
+            showAdminPanel();
+        } else {
+            console.log('Acceso denegado: Se requieren privilegios de administrador');
+            window.location.href = '/';
+        }
+    }
+}
+
+initAdminPage();
+```
+
+### Ejemplo 3: Página de Login/Callback
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+async function handleAuthPage() {
+    const { CorporateAuthManager } = WebsSDK;
+    
+    // Intentar manejar el callback de autenticación
+    const success = await CorporateAuthManager.handleAuthCallback();
+    
+    if (success) {
+        console.log('Login exitoso, redirigiendo...');
+        // El callback ya manejó la redirección
+    } else {
+        // No hay callback, mostrar botón de login
+        showLoginButton();
+    }
+}
+
+function showLoginButton() {
+    const loginBtn = document.getElementById('login-btn');
+    loginBtn?.addEventListener('click', () => {
+        WebsSDK.CorporateAuthManager.login();
+    });
+}
+
+handleAuthPage();
+```
+
+### Ejemplo 4: Botón de Logout
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+function setupLogoutButton() {
+    const { CorporateAuthManager } = WebsSDK;
+    
+    const logoutBtn = document.getElementById('logout-btn');
+    logoutBtn?.addEventListener('click', async () => {
+        await CorporateAuthManager.logout();
+    });
+}
+
+setupLogoutButton();
+```
+
+### Ejemplo 5: Verificación Periódica de Sesión
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+async function setupSessionMonitor() {
+    const { CorporateAuthManager } = WebsSDK;
+    
+    // Verificar sesión cada 5 minutos
+    setInterval(async () => {
+        const userData = await CorporateAuthManager.validateUser(false);
+        
+        if (!userData) {
+            console.log('Sesión expirada, redirigiendo al login...');
+            CorporateAuthManager.login();
+        }
+    }, 5 * 60 * 1000); // 5 minutos
+}
+
+setupSessionMonitor();
+```
+
+## 🔧 Ejemplos Avanzados con Next.js
+
+### Middleware con Headers Personalizados
+
+```typescript
+// middleware.ts - Añadir info del usuario a los headers
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+import WebsSDK from 'webs-sdk'
+
+export async function middleware(request: NextRequest) {
+    const result = await WebsSDK.CorporateAuthManager.validateCorporateAuthServerSide(request)
+    
+    if (!result.authenticated) {
+        return result.redirectResponse
+    }
+    
+    // Añadir información del usuario a los headers del request
+    const requestHeaders = new Headers(request.headers)
+    requestHeaders.set('x-user-id', result.user.id)
+    requestHeaders.set('x-user-email', result.user.email)
+    requestHeaders.set('x-user-name', result.user.name)
+    requestHeaders.set('x-user-role', result.user.role)
+    
+    return NextResponse.next({
+        request: {
+            headers: requestHeaders,
+        },
+    })
+}
+```
+
+### API Route Protegida
+
+```typescript
+// app/api/protected/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import WebsSDK from 'webs-sdk'
+
+export async function GET(request: NextRequest) {
+    const result = await WebsSDK.CorporateAuthManager.validateCorporateAuthServerSide(request)
+    
+    if (!result.authenticated) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    
+    // Lógica de la API con usuario autenticado
+    return NextResponse.json({
+        message: 'Success',
+        user: result.user
+    })
+}
+```
+
+### Middleware con Rutas Específicas
+
+```typescript
+// middleware.ts - Proteger solo ciertas rutas
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+import WebsSDK from 'webs-sdk'
+
+export async function middleware(request: NextRequest) {
+    // Solo validar en rutas protegidas
+    const protectedPaths = ['/dashboard', '/admin', '/profile']
+    const isProtectedPath = protectedPaths.some(path => 
+        request.nextUrl.pathname.startsWith(path)
+    )
+    
+    if (!isProtectedPath) {
+        return NextResponse.next()
+    }
+    
+    const result = await WebsSDK.CorporateAuthManager.validateCorporateAuthServerSide(request)
+    
+    if (!result.authenticated) {
+        return result.redirectResponse
+    }
+    
+    // Verificar permisos de admin para rutas /admin
+    if (request.nextUrl.pathname.startsWith('/admin')) {
+        if (result.user.role !== 'admin') {
+            return NextResponse.redirect(new URL('/unauthorized', request.url))
+        }
+    }
+    
+    return NextResponse.next()
+}
+
+export const config = {
+    matcher: ['/dashboard/:path*', '/admin/:path*', '/profile/:path*']
+}
+```
+
+### Client Component con Callback Handler
+
+```typescript
+// app/components/AuthHandler.tsx
+'use client'
+
+import { useEffect } from 'react'
+import WebsSDK from 'webs-sdk'
+
+export function AuthHandler() {
+    useEffect(() => {
+        async function handleCallback() {
+            const urlParams = new URLSearchParams(window.location.search)
+            if (urlParams.has('auth_token')) {
+                await WebsSDK.CorporateAuthManager.handleAuthCallback()
+            }
+        }
+        handleCallback()
+    }, [])
+    
+    return null
+}
+```
+
+```typescript
+// app/layout.tsx
+import { AuthHandler } from './components/AuthHandler'
+
+export default function RootLayout({ children }) {
+    return (
+        <html>
+            <body>
+                <AuthHandler />
+                {children}
+            </body>
+        </html>
+    )
+}
+```
+
+### Server Component con User Info
+
+```typescript
+// app/dashboard/page.tsx
+import { headers } from 'next/headers'
+
+export default function DashboardPage() {
+    const headersList = headers()
+    
+    // Los headers fueron añadidos por el middleware
+    const userId = headersList.get('x-user-id')
+    const userEmail = headersList.get('x-user-email')
+    const userName = headersList.get('x-user-name')
+    
+    return (
+        <div>
+            <h1>Dashboard</h1>
+            <p>Usuario: {userName}</p>
+            <p>Email: {userEmail}</p>
+        </div>
+    )
+}
+```
+
+## 🔧 Características Avanzadas
+
+### Validación Local como Fallback
+
+Si el servicio central de autenticación no está disponible, la librería automáticamente:
+1. Intenta validar el token localmente usando JWT
+2. Verifica la firma del token
+3. Comprueba la expiración
+4. Retorna los datos del usuario con una marca `local_validation: true`
+
+### Caché de Validaciones
+
+- Las validaciones se cachean durante 5 minutos por defecto
+- Reduce llamadas innecesarias al servidor
+- Se puede forzar una revalidación con `forceRevalidation()`
+
+### Gestión de Cookies
+
+- Las cookies se establecen automáticamente con flags de seguridad
+- HttpOnly para prevenir XSS (cuando sea posible)
+- Secure en HTTPS
+- SameSite=Lax para prevenir CSRF
+
+## 📊 Tipos de Datos
+
+### UserData
+
+```typescript
+interface UserData {
+    id: string;
+    email: string;
+    name: string;
+    role: string;
+    local_validation?: boolean; // true si se validó localmente
+}
+```
+
+### CorporateAuthConfig
+
+```typescript
+interface CorporateAuthConfig {
+    authDomain: string;
+    authValidateUrl: string;
+    authLogoutUrl: string;
+    authLoginUrl: string;
+    appDomain: string;
+    authCookieDuration: number;
+    authRevalidationInterval: number;
+    jwtSecret: string;
+    authJwtIssuer: string;
+}
+```
+
+## ⚠️ Notas Importantes
+
+1. **Seguridad**: No almacenes el `jwtSecret` en el código del cliente. Debe configurarse en el servidor.
+
+2. **HTTPS**: En producción, siempre usa HTTPS para proteger los tokens.
+
+3. **Cookies**: Las cookies HttpOnly solo funcionan si se establecen desde el servidor.
+
+4. **Redirecciones**: Las redirecciones automáticas solo funcionan en entornos de navegador.
+
+5. **Fallback Local**: El fallback local no verifica la validez del token con el servidor, solo verifica su estructura y firma.
+
+## 🐛 Depuración
+
+Todos los métodos emiten logs en consola que puedes usar para depurar:
+
+```typescript
+// En desarrollo, abre la consola del navegador para ver:
+// - "CorporateAuthManager init"
+// - "Validating token with central auth service"
+// - "Token validated successfully: user@example.com"
+// - "Using cached user data"
+// - etc.
+```
+
+## 📞 Soporte
+
+Para problemas o preguntas sobre la autenticación corporativa:
+- Email: dev-team@telecoming.com
+- Documentación completa: Ver `src/libraries/corporate_auth.md`