@tgtone/auth-sdk 1.1.0 → 1.2.1

package/docs/LOVABLE_QUICK_START.md

@@ -1,478 +1,226 @@
-# 🔐 TGT One Auth Client SDK
+# 🔐 TGT Auth SDK - Guía para Lovable/React
 
-SDK para integrar autenticación JWT + MFA en aplicaciones del ecosistema TGT One.
+> Integración rápida de autenticación en proyectos React/Lovable
 
 ---
 
 ## 📦 Instalación
 
 ```bash
-npm install tgtone-auth-client@latest  # v1.2.0
+npm install @tgtone/auth-sdk
 ```
 
----
-
-## 🚀 TGT Auth SDK v1.2.0 - Quick Start para Lovable
-
-## 📦 Instalación
-
-```bash
-npm install tgtone-auth-client@latest
-```
+**Versión actual:** 1.2.0
 
 ---
 
-## ⚡ Uso Básico
+## ⚡ Setup en 3 Pasos
 
-### **1. Inicializar el SDK**
+### **1. Crear AuthContext**
 
 ```typescript
-import { TGTAuthClient } from 'tgtone-auth-client';
+// src/contexts/AuthContext.tsx
+import { createContext, useContext, useEffect, useState } from 'react';
+import { TGTAuthClient, TGTSession } from '@tgtone/auth-sdk';
 
-const auth = new TGTAuthClient({
+const authClient = new TGTAuthClient({
   identityUrl: 'https://identity.tgtone.cl',
-  appDomain: window.location.hostname, // ej: 'app.lovable.dev'
-  debug: true // opcional: ver logs en consola
+  appDomain: window.location.hostname,
+  debug: import.meta.env.DEV
 });
-```
 
----
+interface AuthContextType {
+  session: TGTSession | null;
+  loading: boolean;
+  logout: () => Promise<void>;
+  hasRole: (app: string, role: string) => boolean;
+}
 
-### **2. Verificar Sesión (en App.tsx)**
+const AuthContext = createContext<AuthContextType | null>(null);
 
-```typescript
-import { useEffect, useState } from 'react';
-import { TGTAuthClient, type TGTSession } from 'tgtone-auth-client';
-
-function App() {
+export function AuthProvider({ children }: { children: React.ReactNode }) {
   const [session, setSession] = useState<TGTSession | null>(null);
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    const auth = new TGTAuthClient({
-      identityUrl: 'https://identity.tgtone.cl',
-      appDomain: window.location.hostname
-    });
-
-    auth.checkSession().then((session) => {
-      setSession(session);
+    authClient.checkSession().then(s => {
+      setSession(s);
       setLoading(false);
     });
   }, []);
 
-  if (loading) return <div>Cargando...</div>;
-  if (!session) return null; // Ya redirigió a login
+  const logout = async () => {
+    await authClient.logout();
+    setSession(null);
+  };
+
+  const hasRole = (app: string, role: string) => {
+    return authClient.hasRole(app, role);
+  };
 
   return (
-    <div>
-      <h1>Bienvenido {session.user.name}</h1>
-      <p>Tenant: {session.tenantName}</p>
-      <p>Roles: {JSON.stringify(session.roles)}</p>
-    </div>
+    <AuthContext.Provider value={{ session, loading, logout, hasRole }}>
+      {children}
+    </AuthContext.Provider>
   );
 }
-```
-
----
-
-## 🔑 Nuevas Propiedades de Sesión (v1.1)
-
-```typescript
-const session = await auth.checkSession();
 
-// ✅ Información del Tenant
-session.tenantId      // "uuid-tenant-123"
-session.tenantName    // "TGT Technology"
+export const useAuth = () => {
+  const context = useContext(AuthContext);
+  if (!context) throw new Error('useAuth must be used within AuthProvider');
+  return context;
+};
+```
 
-// ✅ Roles por Aplicación
-session.roles         // { "console": ["owner"], "crm": ["admin"] }
+### **2. Envolver App**
 
-// ✅ Usuario
-session.user.email    // "user@tgtone.cl"
-session.user.name     // "Juan Pérez"
+```tsx
+// src/App.tsx
+import { AuthProvider } from './contexts/AuthContext';
 
-// ✅ Expiración
-session.expiresAt     // Date object
+function App() {
+  return (
+    <AuthProvider>
+      {/* Tu app */}
+    </AuthProvider>
+  );
+}
 ```
 
----
+### **3. Usar en Componentes**
 
-## 🎯 Métodos Útiles
+```tsx
+import { useAuth } from './contexts/AuthContext';
 
-### **Obtener Tenant ID**
-```typescript
-const tenantId = auth.getTenantId();
-// Usar en requests al backend:
-fetch(`/api/v1/tenants/${tenantId}/data`)
-```
+function Dashboard() {
+  const { session, loading, logout, hasRole } = useAuth();
 
-### **Verificar Roles**
-```typescript
-// ¿Es admin de Console?
-if (auth.hasRole('console', 'admin')) {
-  // Mostrar panel de administración
-}
+  if (loading) return <div>Cargando...</div>;
+  
+  if (!session) return null; // Ya está redirigiendo a login
 
-// ¿Tiene acceso a CRM?
-if (auth.hasAccessToApp('crm')) {
-  // Mostrar enlace a CRM
+  return (
+    <div>
+      <h1>Bienvenido {session.user.name}</h1>
+      <p>Tenant: {session.tenantName}</p>
+      
+      {hasRole('console', 'admin') && (
+        <button>Panel Admin</button>
+      )}
+      
+      <button onClick={logout}>Cerrar Sesión</button>
+    </div>
+  );
 }
-
-// Obtener todos los roles de una app
-const roles = auth.getRoles('console'); // ["owner", "admin"]
-```
-
-### **Cerrar Sesión**
-```typescript
-<button onClick={() => auth.logout()}>
-  Cerrar Sesión
-</button>
 ```
 
 ---
 
-## 📡 Requests al Backend con Tenant
+## 🎯 Propiedades de Sesión
 
 ```typescript
-const session = await auth.checkSession();
-
-// ✅ Incluir tenantId en headers
-fetch('https://api.tgtone.cl/v1/data', {
-  headers: {
-    'Authorization': `Bearer ${localStorage.getItem('tgtone_auth_token')}`,
-    'X-Tenant-ID': session.tenantId, // ✅ Tenant context
-  }
-});
+session.user.email       // "user@empresa.cl"
+session.user.name        // "Juan Pérez"
+session.tenantId         // "uuid-tenant-123"
+session.tenantName       // "Mi Empresa"
+session.user.roles       // { console: ['owner'], crm: ['admin'] }
+session.expiresAt        // Date object
 ```
 
 ---
 
-## 🛡️ Validación Local de JWT
-
-El SDK ahora **decodifica el JWT localmente** antes de validar con el backend:
-
-✅ Verifica `tenant_id` obligatorio  
-✅ Valida expiración del token  
-✅ Extrae roles sin hacer request  
-
-**Ventaja:** Menos latencia, mejor UX.
-
----
-
-## 🔐 Soporte MFA (v1.2.0)
-
-El SDK ahora soporta **Multi-Factor Authentication** con Google Authenticator/TOTP.
-
-### Flujo de Login con MFA
-
-Si el usuario tiene MFA habilitado, el backend NO hace redirect automático. En su lugar, el frontend de Identity maneja el flujo MFA completo:
+## 🔐 Verificar Roles
 
-**1. Login con MFA habilitado:**
 ```typescript
-// El usuario hace login en Identity (https://identity.tgtone.cl)
-// Si tiene MFA habilitado:
-// → Identity muestra pantalla de código de 6 dígitos
-// → Usuario ingresa código de Google Authenticator
-// → Identity valida y redirige con token final
-```
-
-**2. Tu app en Lovable recibe el token:**
-```typescript
-// Cuando Identity redirige de vuelta a tu app:
-const session = await auth.checkSession();
-// ✅ El token ya viene validado (con MFA completado)
-```
-
-### Métodos MFA del SDK
-
-Aunque Identity maneja el flujo MFA visualmente, el SDK expone métodos para casos avanzados:
-
-```typescript
-// Verificar código MFA programáticamente (uso avanzado)
-const session = await auth.verifyMfa(tempToken, '123456');
-
-// Guardar tempToken en localStorage
-auth.storeTempToken(tempToken);
-
-// Obtener tempToken guardado
-const tempToken = auth.getTempToken();
-
-// Limpiar tempToken
-auth.clearTempToken();
-```
-
-> **💡 Nota para Lovable**: En la mayoría de casos NO necesitas llamar `verifyMfa()` directamente. Identity maneja el flujo MFA completo y tu app solo recibe el token final validado.
-
-### ¿Cuándo usar los métodos MFA?
-
-**✅ Caso común (recomendado):**
-```typescript
-// Identity maneja todo el flujo MFA
-const session = await auth.checkSession();
-// Ya viene con MFA validado si el usuario lo tiene habilitado
-```
-
-**🔧 Caso avanzado (si implementas login custom):**
-```typescript
-// Solo si NO usas el frontend de Identity
-const loginResponse = await fetch('/api/auth/login', {
-  method: 'POST',
-  body: JSON.stringify({ email, password })
-});
-
-const data = await loginResponse.json();
-
-if (data.requiresMfa && data.tempToken) {
-  auth.storeTempToken(data.tempToken);
-  // Mostrar input para código
-  const code = getUserInputCode();
-  const session = await auth.verifyMfa(data.tempToken, code);
+// ¿Es admin de Console?
+if (hasRole('console', 'admin')) {
+  // Mostrar funciones de admin
 }
-```
-
----
 
-## 🆕 Cambios por Versión
-
-### v1.2.0 (Octubre 2025)
-- ✅ **Soporte MFA** con TOTP (Google Authenticator)
-- ✅ Métodos `verifyMfa()`, `storeTempToken()`, `getTempToken()`, `clearTempToken()`
-- ✅ Detección automática de flujo MFA en `checkSession()`
-- ✅ Identity maneja UI de MFA (no requiere código custom en apps)
-
-### v1.1.0 (Octubre 2025)
-- ✅ Validación de `tenant_id` obligatorio
-- ✅ Decodificación local de JWT
-- ✅ Nuevo retorno `TGTSession` en lugar de `TGTUser`
-- ✅ Métodos `hasRole()`, `getRoles()`, `hasAccessToApp()`
-
-### v1.0.0
-- ✅ Versión inicial con SSO básico
-
----
-
-## 🔧 TypeScript Types
-
-```typescript
-import type { 
-  TGTSession,
-  TGTUser,
-  JWTPayload 
-} from 'tgtone-auth-client';
-
-interface TGTSession {
-  user: TGTUser;
-  tenantId: string;
-  tenantName: string;
-  roles: Record<string, string[]>; // { "console": ["admin"] }
-  expiresAt: Date;
+// ¿Tiene acceso a CRM?
+if (authClient.hasAccessToApp('crm')) {
+  // Mostrar enlace a CRM
 }
-```
-
----
-
-## ⚠️ Breaking Changes
-
-Si usabas v1.0, actualizar código:
 
-```typescript
-// ❌ Antes (v1.0)
-const user = await auth.checkSession();
-console.log(user.email);
-
-// ✅ Ahora (v1.1)
-const session = await auth.checkSession();
-console.log(session.user.email);
-console.log(session.tenantId); // ← NUEVO
+// Obtener todos los roles
+const roles = authClient.getRoles('console'); // ['owner', 'admin']
 ```
 
 ---
 
-## 🚨 Troubleshooting
-
-### Error: "Invalid token: missing tenant_id"
-→ Tu backend no está incluyendo `tenant_id` en el JWT. Verificar `auth.service.ts`.
-
-### Error: "Token expired"
-→ El token tiene > 90 días (dev) o > 1h (prod). Re-login automático.
-
-### No redirige a login
-→ Verificar que `identityUrl` y `appDomain` sean correctos.
-
----
-
-## 📚 Docs Completas
-
-Ver: `sdk/README.md` o https://github.com/tgt-technology/tgtone-identity-auth
-
----
-
-## 📋 API
-
-### `checkSession(): Promise<TGTUser | null>`
-Verifica sesión. Lee token de URL (si viene del redirect), lo guarda en localStorage y valida con backend.
-
-```typescript
-const user = await auth.checkSession();
-if (user) {
-  console.log('Usuario logueado:', user.email);
-}
-```
-
-### `getUser(): TGTUser | null`
-Obtiene usuario en memoria (sin request). Requiere llamar `checkSession()` primero.
-
-### `logout(): Promise<void>`
-Cierra sesión, limpia localStorage y redirige al login.
+## 🆕 Verificación Silenciosa (v1.2.0)
 
-### `hasRole(app: string, role: string): boolean`
-Verifica si tiene un rol específico.
+Para páginas que no requieren autenticación obligatoria:
 
 ```typescript
-if (auth.hasRole('console', 'admin')) {
-  // Mostrar panel admin
-}
+// Landing page o página pública
+useEffect(() => {
+  const checkAuth = async () => {
+    const session = await authClient.checkSessionSilent();
+    
+    if (session) {
+      // Usuario logeado - mostrar contenido personalizado
+      showButton('Ir al Dashboard', '/dashboard');
+    } else {
+      // Usuario no logeado - mostrar botón de login
+      showButton('Iniciar Sesión', () => authClient.redirectToLogin());
+    }
+  };
+  
+  checkAuth();
+}, []);
 ```
 
-### `getRoles(app: string): string[]`
-Obtiene roles del usuario en una app.
-
-### `redirectToLogin(): void`
-Redirige manualmente al login.
-
 ---
 
-## 🔄 Flujo Completo (con MFA)
+## 🔄 Flujo de Autenticación
 
 ```
-1. Usuario visita tu app en Lovable
-   ↓
-2. App ejecuta auth.checkSession()
+1. Usuario entra a tu app
    ↓
-3. ❌ No hay token → Redirect a Identity con ?redirect=tu-dominio
+2. checkSession() no encuentra token
    ↓
-4. Usuario ingresa email + password en Identity
+3. SDK redirige a identity.tgtone.cl/login
    ↓
-5a. ✅ Sin MFA habilitado:
-    → Identity redirige a tu-dominio?token=eyJ...
-    → SDK guarda token y retorna sesión
-   
-5b. 🔐 Con MFA habilitado:
-    → Identity muestra pantalla de código de 6 dígitos
-    → Usuario ingresa código de Google Authenticator
-    → Identity valida código con backend
-    → ✅ Código válido → Identity redirige a tu-dominio?token=eyJ...
-    → SDK guarda token y retorna sesión
+4. Usuario hace login (+ MFA si está habilitado)
    ↓
-6. SDK lee token de URL y lo guarda en localStorage
+5. Identity redirige: tu-app?token=eyJhbGci...
    ↓
-7. SDK valida token con backend (Authorization: Bearer ...)
+6. SDK guarda token y valida con backend
    ↓
-8. ✅ Retorna sesión completa
+7. ✅ Usuario autenticado
 ```
 
-**💡 Clave:** Tu app en Lovable NO necesita manejar MFA. Identity lo hace todo y te devuelve el token final ya validado.
-
 ---
 
-## 🧪 Testing Rápido (Sin Login)
-
-Para desarrollo rápido sin pasar por login:
+## 🧪 Testing sin Login
 
 ```typescript
-useEffect(() => {
-  // 1. Hacer login con curl y copiar el token
-  // 2. Guardarlo manualmente:
-  const testToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
-  localStorage.setItem('tgtone_auth_token', testToken);
-  
-  // 3. Ahora checkSession funcionará
-  auth.checkSession().then(setUser);
-}, []);
-```
+// Guardar token manualmente en localStorage
+localStorage.setItem('tgtone_auth_token', 'eyJhbGci...');
+window.location.reload();
 
-**Obtener token:**
-```bash
-curl -X POST https://identity.tgtone.cl/api/v1/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{"email": "superadmin@tgtone.cl", "password": "Tgt123."}'
+// Obtener token de prueba con curl:
+// curl -X POST https://tgtone-console-backend.run.app/api/v1/auth/login \
+//   -d '{"email": "user@test.cl", "password": "Test123!"}'
 ```
 
 ---
 
-## 👤 Estructura del Usuario
-
-```typescript
-interface TGTUser {
-  sub: string;              // ID usuario
-  email: string;
-  name: string;
-  tenant_id: string;
-  tenant_name: string;
-  roles: Record<string, string[]>; // { console: ['owner'], zenith: ['admin'] }
-}
-```
-
----
+## 📚 API Completa
 
-## ⚙️ Configuración
+Ver documentación completa: **[README.md](../README.md)**
 
-```typescript
-interface TGTAuthConfig {
-  identityUrl: string;      // URL del backend Identity
-  appDomain: string;        // Dominio de tu app (sin protocolo)
-  onAuthSuccess?: (user: TGTUser) => void;  // Callback cuando se autentica
-  onAuthFailure?: () => void;               // Callback cuando falla
-  debug?: boolean;          // Logs en consola
-}
-```
-
----
-
-## 🔐 Cómo Funciona
-
-1. **Token en URL**: Después del login, Identity redirige con `?token=...`
-2. **localStorage**: SDK guarda token en `tgtone_auth_token`
-3. **Bearer Token**: Todas las requests usan `Authorization: Bearer <token>`
-4. **Validación**: Backend valida JWT y retorna datos del usuario
-5. **No cookies**: Todo se maneja con Bearer tokens en localStorage
-
----
-
-## 🛠️ Para Producción
-
-Cambiar `identityUrl` según ambiente:
-
-```typescript
-const auth = new TGTAuthClient({
-  identityUrl: import.meta.env.PROD 
-    ? 'https://identity.tgtone.cl'
-    : 'https://identity.tgtone.cl',  // Mismo dominio en dev y prod
-  appDomain: window.location.hostname
-});
-```
-
----
-
-## 🔐 Seguridad MFA
-
-El sistema MFA de TGT One usa **TOTP (Time-based One-Time Password)** basado en RFC 6238:
-
-- 🔑 **Secret compartido**: Generado al activar MFA, guardado encriptado en BD
-- ⏱️ **Códigos temporales**: Válidos por 30 segundos
-- 🔄 **Ventana de tolerancia**: ±30 segundos para compensar desfase de reloj
-- 📱 **Compatible con**: Google Authenticator, Microsoft Authenticator, Authy, 1Password, etc.
-
-### Cómo funciona:
-```
-Usuario habilita MFA → Backend genera secret único
-                    → Muestra QR code
-                    → Usuario escanea con Google Authenticator
-                    → App genera códigos cada 30s: HMAC-SHA1(secret, tiempo)
-                    → Al login: Backend valida con mismo algoritmo
-```
+Métodos disponibles:
+- `checkSession()` - Verifica sesión (redirige si no hay)
+- `checkSessionSilent()` - Verifica sin redirigir
+- `signup()` - Crear cuenta
+- `login()` - Iniciar sesión
+- `logout()` - Cerrar sesión
+- `verifyMfa()` - Validar código MFA
+- `hasRole()` - Verificar roles
+- `redirectToLogin()` - Redirigir a login
 
 ---
 
-**Última actualización:** 2025-10-29  
-**Versión SDK:** v1.2.0
+**Última actualización:** 2025-11-03