@tgtone/auth-sdk 1.0.0

package/docs/LOVABLE_QUICK_START.md

@@ -0,0 +1,478 @@
+# 🔐 TGT One Auth Client SDK
+
+SDK para integrar autenticación JWT + MFA en aplicaciones del ecosistema TGT One.
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install tgtone-auth-client@latest  # v1.2.0
+```
+
+---
+
+## 🚀 TGT Auth SDK v1.2.0 - Quick Start para Lovable
+
+## 📦 Instalación
+
+```bash
+npm install tgtone-auth-client@latest
+```
+
+---
+
+## ⚡ Uso Básico
+
+### **1. Inicializar el SDK**
+
+```typescript
+import { TGTAuthClient } from 'tgtone-auth-client';
+
+const auth = new TGTAuthClient({
+  identityUrl: 'https://identity.tgtone.cl',
+  appDomain: window.location.hostname, // ej: 'app.lovable.dev'
+  debug: true // opcional: ver logs en consola
+});
+```
+
+---
+
+### **2. Verificar Sesión (en App.tsx)**
+
+```typescript
+import { useEffect, useState } from 'react';
+import { TGTAuthClient, type TGTSession } from 'tgtone-auth-client';
+
+function App() {
+  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);
+      setLoading(false);
+    });
+  }, []);
+
+  if (loading) return <div>Cargando...</div>;
+  if (!session) return null; // Ya redirigió a login
+
+  return (
+    <div>
+      <h1>Bienvenido {session.user.name}</h1>
+      <p>Tenant: {session.tenantName}</p>
+      <p>Roles: {JSON.stringify(session.roles)}</p>
+    </div>
+  );
+}
+```
+
+---
+
+## 🔑 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"
+
+// ✅ Roles por Aplicación
+session.roles         // { "console": ["owner"], "crm": ["admin"] }
+
+// ✅ Usuario
+session.user.email    // "user@tgtone.cl"
+session.user.name     // "Juan Pérez"
+
+// ✅ Expiración
+session.expiresAt     // Date object
+```
+
+---
+
+## 🎯 Métodos Útiles
+
+### **Obtener Tenant ID**
+```typescript
+const tenantId = auth.getTenantId();
+// Usar en requests al backend:
+fetch(`/api/v1/tenants/${tenantId}/data`)
+```
+
+### **Verificar Roles**
+```typescript
+// ¿Es admin de Console?
+if (auth.hasRole('console', 'admin')) {
+  // Mostrar panel de administración
+}
+
+// ¿Tiene acceso a CRM?
+if (auth.hasAccessToApp('crm')) {
+  // Mostrar enlace a CRM
+}
+
+// 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
+
+```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
+  }
+});
+```
+
+---
+
+## 🛡️ 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:
+
+**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);
+}
+```
+
+---
+
+## 🆕 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;
+}
+```
+
+---
+
+## ⚠️ 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
+```
+
+---
+
+## 🚨 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.
+
+### `hasRole(app: string, role: string): boolean`
+Verifica si tiene un rol específico.
+
+```typescript
+if (auth.hasRole('console', 'admin')) {
+  // Mostrar panel admin
+}
+```
+
+### `getRoles(app: string): string[]`
+Obtiene roles del usuario en una app.
+
+### `redirectToLogin(): void`
+Redirige manualmente al login.
+
+---
+
+## 🔄 Flujo Completo (con MFA)
+
+```
+1. Usuario visita tu app en Lovable
+   ↓
+2. App ejecuta auth.checkSession()
+   ↓
+3. ❌ No hay token → Redirect a Identity con ?redirect=tu-dominio
+   ↓
+4. Usuario ingresa email + password en Identity
+   ↓
+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
+   ↓
+6. SDK lee token de URL y lo guarda en localStorage
+   ↓
+7. SDK valida token con backend (Authorization: Bearer ...)
+   ↓
+8. ✅ Retorna sesión completa
+```
+
+**💡 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:
+
+```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);
+}, []);
+```
+
+**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."}'
+```
+
+---
+
+## 👤 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'] }
+}
+```
+
+---
+
+## ⚙️ Configuración
+
+```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
+```
+
+---
+
+**Última actualización:** 2025-10-29  
+**Versión SDK:** v1.2.0

package/docs/NPM_PUBLISH.md

@@ -0,0 +1,131 @@
+# 📦 Publicar SDK a NPM
+
+## ✅ Pre-requisitos
+
+1. **Cuenta en NPM**: https://www.npmjs.com/signup
+2. **Login en terminal**:
+```bash
+npm login
+# Ingresar: username, password, email, OTP (si tienes 2FA)
+```
+
+---
+
+## 🚀 Comandos para Publicar
+
+### 1. Ir a la carpeta del SDK
+```bash
+cd /home/jam/develop/tgtone/tgtone-identity-auth/sdk
+```
+
+### 2. Limpiar build anterior
+```bash
+npm run clean
+```
+
+### 3. Compilar TypeScript
+```bash
+npm run build
+```
+
+### 4. Verificar qué archivos se publicarán
+```bash
+npm pack --dry-run
+```
+
+Debería mostrar:
+```
+- README.md
+- package.json
+- dist/
+- docs/
+```
+
+### 5. Publicar
+```bash
+npm publish
+```
+
+---
+
+## 🔄 Para Actualizar Versión
+
+### Patch (1.0.2 → 1.0.3) - Bug fixes
+```bash
+npm version patch
+npm publish
+```
+
+### Minor (1.0.3 → 1.1.0) - Nuevas features
+```bash
+npm version minor
+npm publish
+```
+
+### Major (1.1.0 → 2.0.0) - Breaking changes
+```bash
+npm version major
+npm publish
+```
+
+---
+
+## ✅ Verificar Publicación
+
+Una vez publicado:
+```bash
+# Ver en NPM
+https://www.npmjs.com/package/tgtone-auth-client
+
+# Instalar en otro proyecto
+npm install tgtone-auth-client
+```
+
+---
+
+## 🔐 Configuración de Token NPM (CI/CD)
+
+Para publicar desde GitHub Actions o CI/CD:
+
+```bash
+# 1. Crear token en NPM
+https://www.npmjs.com/settings/YOUR_USER/tokens
+
+# 2. Configurar en GitHub Secrets
+Repo Settings > Secrets > New secret
+Name: NPM_TOKEN
+Value: npm_xxx...
+
+# 3. Usar en GitHub Actions
+- run: npm publish
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+---
+
+## 📋 Checklist Pre-publicación
+
+- [x] ✅ Version actualizada en package.json (1.0.2)
+- [x] ✅ Build exitoso (`npm run build`)
+- [x] ✅ Tests pasando (si los hay)
+- [x] ✅ README.md actualizado
+- [x] ✅ CHANGELOG.md actualizado
+- [x] ✅ Documentación organizada en docs/
+- [ ] ⬜ Login en NPM (`npm login`)
+
+---
+
+## 🎯 Comandos Rápidos
+
+```bash
+# Todo en uno (desde carpeta sdk/)
+cd /home/jam/develop/tgtone/tgtone-identity-auth/sdk
+npm run clean
+npm run build
+npm publish
+```
+
+---
+
+**Última actualización:** 2025-10-16

package/docs/README.md

@@ -0,0 +1,83 @@
+# 📚 TGT Auth SDK - Documentación
+
+> SDK de autenticación JWT + Bearer Token para el ecosistema TGT One
+
+---
+
+## 🚀 Quick Start
+
+**[⬆️ README principal](../README.md)** - Instalación y uso básico
+
+---
+
+## 📖 Guías de Integración
+
+### **[LOVABLE_QUICK_START.md](./LOVABLE_QUICK_START.md)** ⭐
+Guía para Lovable/React:
+- Setup en 5 minutos
+- Código completo listo para copiar
+- Testing sin pasar por login
+- Configuración recomendada
+
+### **[INTEGRATION_EXAMPLES.md](./INTEGRATION_EXAMPLES.md)**
+Ejemplos para otros frameworks:
+- Vue.js / Nuxt
+- Next.js (App Router)
+- Vanilla JavaScript
+
+---
+
+## 🛠️ Configuración
+
+### **[NPM_PUBLISH.md](./NPM_PUBLISH.md)**
+Guía para publicar actualizaciones en NPM
+
+### **[SDK_FINAL_STATUS.md](./SDK_FINAL_STATUS.md)**
+Estado actual del SDK y estructura de archivos
+
+---
+
+## 🔧 Estructura del SDK
+
+```
+sdk/
+├── tgtone-auth-client.ts       # SDK principal (Bearer Token)
+├── react-hook.tsx              # Hook de React (opcional)
+├── index.ts                    # Exports
+├── package.json                # v1.0.2
+├── README.md                   # Guía principal
+└── docs/                       # Documentación completa
+    ├── README.md               # Este archivo
+    ├── LOVABLE_QUICK_START.md
+    ├── INTEGRATION_EXAMPLES.md
+    ├── NPM_PUBLISH.md
+    └── SDK_FINAL_STATUS.md
+```
+
+---
+
+## 🎯 Por Dónde Empezar
+
+| Quiero... | Ver |
+|-----------|-----|
+| Usarlo en Lovable ahora | [LOVABLE_QUICK_START.md](./LOVABLE_QUICK_START.md) |
+| Ver API completa | [README.md](../README.md) |
+| Ejemplos Vue/Next | [INTEGRATION_EXAMPLES.md](./INTEGRATION_EXAMPLES.md) |
+| Publicar actualización | [NPM_PUBLISH.md](./NPM_PUBLISH.md) |
+
+---
+
+## 🔐 Información Clave
+
+**Autenticación:** JWT + Bearer Token en Authorization header  
+**Storage:** localStorage (`tgtone_auth_token`)  
+**Redirect:** Automático con parámetro `?token=` en URL  
+**CORS:** Backend tiene CORS abierto en staging  
+
+**Versión Actual:** 1.0.2  
+**Backend Staging:** https://tgtone-identity-backend-1086175589490.us-central1.run.app  
+**Backend Producción:** (Pendiente configurar identity.tgtone.cl)
+
+---
+
+**Última actualización:** 2025-10-16