forlogic-core 1.4.15 → 1.5.1

package/dist/docs/architecture/TOKENS_ARCHITECTURE.md

@@ -0,0 +1,712 @@
+# 🎫 Arquitetura de Tokens - Documentação Atualizada
+
+## 📋 Visão Geral
+
+Este projeto implementa um **sistema de autenticação tripla** que integra Qualiex OAuth 2.0 com backend Supabase, proporcionando autenticação robusta e controle de acesso multi-tenant.
+
+## 🔑 Sistema de Três Tokens
+
+### 1. **Qualiex Access Token** (`access_token`)
+
+- **Origem**: Servidor OAuth 2.0 Qualiex
+- **Formato**: JWT assinado pelo Qualiex
+- **Propósito**: Valida identidade e autorização com serviços Qualiex
+- **Armazenamento**: `localStorage` como `qualiex_access_token`
+- **Validade**: Configurada pelo Qualiex (tipicamente 1-2 horas)
+
+#### Estrutura do Payload:
+```json
+{
+  "default": "empresa_principal",
+  "co0": "empresa1;;;Nome Empresa 1;status",
+  "co1": "empresa2;;;Nome Empresa 2;status", 
+  "co2": "empresa3;;;Nome Empresa 3;status",
+  "iat": 1234567890,
+  "exp": 1234567890
+}
+```
+
+#### Campos de Empresa (`co*`):
+```
+Formato: alias;;;nome_empresa;status;;;;;;;company_id
+Posições:
+- [0]: alias da empresa
+- [3]: nome da empresa  
+- [4]: status
+- [7]: company_id (para RLS)
+```
+
+### 2. **Qualiex ID Token** (`id_token`)
+
+- **Origem**: Servidor OpenID Connect Qualiex
+- **Formato**: JWT com informações do perfil do usuário
+- **Propósito**: Contém dados de identidade e perfil detalhado
+- **Armazenamento**: `localStorage` como `qualiex_id_token`
+- **Validade**: Mesmo período do access token
+
+#### Estrutura do Payload:
+```json
+{
+  "subNewId": "user_unique_id_123",
+  "email": "usuario@empresa.com",
+  "name": "Nome Completo do Usuário",
+  "identifier": "identificador_usuario",
+  "photo-date": "timestamp_foto",
+  "default": "empresa_principal",
+  "co0": "empresa1;;;Nome Empresa 1;status;;;;;;;id_empresa_1",
+  "co1": "empresa2;;;Nome Empresa 2;status;;;;;;;id_empresa_2",
+  "iat": 1234567890,
+  "exp": 1234567890
+}
+```
+
+### 3. **Supabase Token** (`supabase_token`)
+
+- **Origem**: Gerado pela Edge Function `validate-token`
+- **Formato**: JWT assinado com secret do Supabase
+- **Propósito**: Autentica usuário com backend Supabase e habilita RLS
+- **Armazenamento**: `localStorage` como `supabase_token`
+- **Validade**: 24 horas (renovação automática)
+
+#### Estrutura do Payload:
+```json
+{
+  "sub": "user_unique_id_123",
+  "email": "usuario@empresa.com",
+  "alias": "empresa_selecionada",
+  "company_id": "id_empresa_extraido",
+  "user_metadata": {
+    "name": "Nome Completo do Usuário",
+    "identifier": "identificador_usuario"
+  },
+  "aud": "authenticated",
+  "role": "authenticated",
+  "iat": 1234567890,
+  "exp": 1234567890
+}
+```
+
+---
+
+## 🔄 Fluxo de Autenticação
+
+### Diagrama do Fluxo Completo
+
+```mermaid
+sequenceDiagram
+    participant U as Usuário
+    participant A as App Frontend
+    participant Q as Qualiex OAuth
+    participant E as Edge Function
+    participant S as Supabase
+    participant DB as PostgreSQL
+
+    Note over U,DB: Fluxo de Produção
+    
+    U->>A: 1. Clique em "Login"
+    A->>Q: 2. Redirect para OAuth Qualiex
+    Q->>U: 3. Tela de login Qualiex
+    U->>Q: 4. Credenciais válidas
+    Q->>A: 5. Callback com tokens (access + id)
+    
+    A->>A: 6. Extrai empresas do ID token
+    A->>A: 7. Usuário seleciona empresa
+    
+    A->>E: 8. POST /validate-token
+    Note right of A: { access_token, alias }
+    
+    E->>Q: 9. Valida access token
+    Q->>E: 10. Token válido ✓
+    
+    E->>E: 11. Extrai company_id do token
+    E->>E: 12. Gera Supabase JWT
+    
+    E->>A: 13. Retorna supabase_token
+    
+    A->>A: 14. Armazena todos os tokens
+    A->>A: 15. Atualiza estado auth
+    
+    A->>S: 16. Requests com supabase_token
+    S->>DB: 17. Query com RLS
+    Note right of S: WHERE alias = JWT.alias
+    DB->>S: 18. Dados filtrados
+    S->>A: 19. Resposta autorizada
+    
+    Note over U,DB: Fluxo de Desenvolvimento
+    
+    U->>A: 1. Login (Dev Mode)
+    A->>E: 2. POST /dev-tokens
+    E->>E: 3. Gera tokens mock
+    E->>A: 4. Retorna todos tokens
+    A->>A: 5. Mesmo fluxo de produção
+```
+
+### Estados do Fluxo
+
+```mermaid
+stateDiagram-v2
+    [*] --> Unauthenticated
+    
+    Unauthenticated --> OAuth_Redirect: Login Click
+    OAuth_Redirect --> Token_Validation: Callback Received
+    
+    Token_Validation --> Company_Selection: Tokens Valid
+    Token_Validation --> Unauthenticated: Tokens Invalid
+    
+    Company_Selection --> Supabase_Auth: Company Selected
+    Company_Selection --> Unauthenticated: User Cancels
+    
+    Supabase_Auth --> Authenticated: Success
+    Supabase_Auth --> Unauthenticated: Supabase Error
+    
+    Authenticated --> Token_Refresh: Token Expiring
+    Token_Refresh --> Authenticated: Refresh Success
+    Token_Refresh --> Unauthenticated: Refresh Failed
+    
+    Authenticated --> Unauthenticated: Logout
+```
+
+---
+
+## 🏗️ Arquitetura de Arquivos
+
+### Frontend (src/auth/)
+
+```
+src/auth/
+├── components/
+│   ├── ProtectedRoute.tsx        # Proteção de rotas
+│   └── UserInfo.tsx              # Exibição de dados do usuário
+├── contexts/
+│   └── AuthContext.tsx           # Estado global de autenticação
+├── pages/
+│   └── CallbackPage.tsx          # Processamento do callback OAuth
+└── services/
+    ├── AuthService.ts            # Lógica de negócio de auth
+    └── TokenManager.ts           # Gestão de armazenamento de tokens
+```
+
+### Backend (supabase/functions/)
+
+```
+supabase/functions/
+├── validate-token/               # Validação em produção
+│   └── index.ts                 # Valida Qualiex + gera Supabase token
+├── dev-tokens/                  # Desenvolvimento
+│   └── index.ts                 # Gera tokens mock para dev
+└── secure-cors-middleware/       # Middleware CORS
+    └── index.ts                 # Configurações CORS seguras
+```
+
+---
+
+## 🔧 Implementação Detalhada
+
+### AuthContext.tsx (Estado Global)
+
+```typescript
+interface AuthState {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  user: UserInfo | null;
+  alias: string | null;
+  companies: Company[];
+  tokens: {
+    accessToken: string | null;
+    idToken: string | null;
+    supabaseToken: string | null;
+  };
+}
+
+const AuthContext = createContext<{
+  ...AuthState;
+  login: () => void;
+  logout: () => void;
+  switchUnit: (alias: string) => Promise<void>;
+  refreshData: () => void;
+}>({});
+```
+
+### TokenManager.ts (Gestão de Tokens)
+
+```typescript
+export class TokenManager {
+  // Armazenamento
+  static setAccessToken(token: string): void;
+  static setIdToken(token: string): void;
+  static setSupabaseToken(token: string): void;
+  
+  // Recuperação
+  static getAccessToken(): string | null;
+  static getIdToken(): string | null;
+  static getSupabaseToken(): string | null;
+  
+  // Validação
+  static isTokenExpired(token: string): boolean;
+  static isTokenValid(token: string): boolean;
+  
+  // Limpeza
+  static clearTokens(): void;
+  static clearOAuthState(): void;
+  
+  // Decodificação
+  static decodeJWT(token: string): any;
+}
+```
+
+### AuthService.ts (Lógica de Negócio)
+
+```typescript
+export class AuthService {
+  // OAuth Flow
+  static initiateLogin(): void;
+  static handleCallback(url: string): Promise<AuthResult>;
+  
+  // Company Management
+  static extractCompanies(idToken: string): Company[];
+  static switchCompany(alias: string): Promise<void>;
+  
+  // Token Operations
+  static validateTokens(accessToken: string, alias: string): Promise<string>;
+  static refreshSupabaseToken(): Promise<void>;
+  
+  // State Management
+  static getCurrentUser(): UserInfo | null;
+  static isAuthenticated(): boolean;
+  static logout(): void;
+}
+```
+
+---
+
+## 🌍 Ambientes: Desenvolvimento vs Produção
+
+### Desenvolvimento (`dev-tokens` function)
+
+```typescript
+// Edge Function: supabase/functions/dev-tokens/index.ts
+const isDev = origin.includes('localhost') || 
+              origin.includes('sandbox.lovable.dev') ||
+              Deno.env.get('DENO_DEPLOYMENT_ID') === undefined;
+
+if (isDev) {
+  return {
+    access_token: DEV_ACCESS_TOKEN,    // Token mock Qualiex
+    id_token: DEV_ID_TOKEN             // Token mock com dados de teste
+  };
+}
+```
+
+**Características do Ambiente de Desenvolvimento:**
+- ✅ Tokens mock pré-configurados
+- ✅ Sem dependência de OAuth real
+- ✅ Dados de teste realistas
+- ✅ Múltiplas empresas de exemplo
+- ✅ Fluxo completo simulado
+
+### Produção (`validate-token` function)
+
+```typescript
+// Edge Function: supabase/functions/validate-token/index.ts
+async function validateToken(accessToken: string, alias: string) {
+  // 1. Validar token com servidor Qualiex
+  const validation = await fetch(QUALIEX_VALIDATE_ENDPOINT, {
+    headers: { 
+      'Authorization': `Bearer ${accessToken}`,
+      'un-alias': alias 
+    }
+  });
+  
+  // 2. Extrair company_id do token
+  const companyId = extractCompanyId(accessToken, alias);
+  
+  // 3. Gerar Supabase JWT
+  const supabaseToken = await createJWT({
+    sub: userId,
+    alias: alias,
+    company_id: companyId,
+    // ... outros claims
+  }, SUPABASE_JWT_SECRET);
+  
+  return supabaseToken;
+}
+```
+
+**Características do Ambiente de Produção:**
+- ✅ OAuth real com Qualiex
+- ✅ Validação de tokens em tempo real
+- ✅ Dados reais de empresas
+- ✅ Segurança completa
+- ✅ Logs de auditoria
+
+---
+
+## 📦 Storage Strategy (Armazenamento)
+
+### LocalStorage Mapping
+
+| Token | Key | Conteúdo | Persistência |
+|-------|-----|----------|--------------|
+| Access Token | `qualiex_access_token` | JWT Qualiex para API | Até logout |
+| ID Token | `qualiex_id_token` | Dados do usuário + empresas | Até logout |
+| Supabase Token | `supabase_token` | JWT para RLS Supabase | Até logout |
+
+### SessionStorage (Temporário)
+
+| Item | Key | Conteúdo | Persistência |
+|------|-----|----------|--------------|
+| OAuth State | `oauth_state` | CSRF protection | Apenas sessão |
+| Redirect URI | `qualiex_redirect_uri` | URL de retorno | Até uso |
+
+### Estratégia de Limpeza
+
+```typescript
+// Limpeza automática em diferentes cenários
+class TokenManager {
+  // Logout explícito
+  static logout(): void {
+    localStorage.removeItem('qualiex_access_token');
+    localStorage.removeItem('qualiex_id_token'); 
+    localStorage.removeItem('supabase_token');
+    sessionStorage.clear();
+  }
+  
+  // Token expirado
+  static cleanExpiredTokens(): void {
+    Object.keys(localStorage).forEach(key => {
+      if (key.includes('token') && this.isTokenExpired(localStorage.getItem(key))) {
+        localStorage.removeItem(key);
+      }
+    });
+  }
+  
+  // Mudança de empresa
+  static switchCompany(alias: string): void {
+    // Manter access_token e id_token
+    // Limpar apenas supabase_token (será regenerado)
+    localStorage.removeItem('supabase_token');
+  }
+}
+```
+
+---
+
+## 🐛 Debugging e Troubleshooting
+
+### Logs Estruturados
+
+```typescript
+// Habilitação de debug
+const DEBUG_AUTH = import.meta.env.DEV || localStorage.getItem('debug_auth');
+
+class AuthDebugger {
+  static logTokenDecoding(token: string, type: string): void {
+    if (DEBUG_AUTH) {
+      console.group(`[TokenDecoder] ${type}`);
+      console.log('Raw Token:', token.substring(0, 50) + '...');
+      console.log('Decoded:', this.decodeToken(token));
+      console.groupEnd();
+    }
+  }
+  
+  static logAuthFlow(step: string, data: any): void {
+    if (DEBUG_AUTH) {
+      console.log(`[AuthFlow] ${step}:`, data);
+    }
+  }
+  
+  static logRLSContext(): void {
+    if (DEBUG_AUTH) {
+      console.group('[RLS Context]');
+      console.log('Current alias:', this.getCurrentAlias());
+      console.log('JWT Claims:', this.getJWTClaims());
+      console.groupEnd();
+    }
+  }
+}
+```
+
+### Problemas Comuns e Soluções
+
+#### 1. **Token Parsing Errors**
+
+```typescript
+// Problema: Erro ao decodificar JWT
+// Causa: Base64 mal formado ou token corrompido
+// Solução:
+function safeDecodeJWT(token: string): any | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) throw new Error('Invalid JWT format');
+    
+    const payload = parts[1];
+    const paddedPayload = payload + '='.repeat((4 - payload.length % 4) % 4);
+    const decoded = atob(paddedPayload.replace(/-/g, '+').replace(/_/g, '/'));
+    
+    return JSON.parse(decoded);
+  } catch (error) {
+    console.error('[AuthService] Token decode failed:', error);
+    return null;
+  }
+}
+```
+
+#### 2. **Company Extraction Failures**
+
+```typescript
+// Problema: Não encontra company_id no token
+// Causa: Formato incorreto ou campo faltando
+// Solução:
+function extractCompanyId(token: string, alias: string): string | null {
+  const payload = this.safeDecodeJWT(token);
+  if (!payload) return null;
+  
+  // Buscar em todos os campos co* dinamicamente
+  for (const key in payload) {
+    if (key.startsWith('co') && /^co\d+$/.test(key)) {
+      const coField = payload[key];
+      if (typeof coField === 'string') {
+        const parts = coField.split(';');
+        // Verificar se tem alias na posição 0 e company_id na posição 7
+        if (parts.length > 7 && parts[0] === alias && parts[7]) {
+          return parts[7];
+        }
+      }
+    }
+  }
+  
+  console.warn(`[AuthService] Company ID not found for alias: ${alias}`);
+  return null;
+}
+```
+
+#### 3. **RLS Access Denied**
+
+```typescript
+// Problema: Usuário não consegue acessar dados
+// Causa: JWT não tem claims corretos ou RLS mal configurado
+// Diagnóstico:
+async function debugRLSAccess(): Promise<void> {
+  const supabaseToken = TokenManager.getSupabaseToken();
+  if (!supabaseToken) {
+    console.error('[RLS Debug] No Supabase token found');
+    return;
+  }
+  
+  const claims = TokenManager.decodeJWT(supabaseToken);
+  console.group('[RLS Debug] Token Analysis');
+  console.log('Token alias:', claims.alias);
+  console.log('Token company_id:', claims.company_id);
+  console.log('Token expiry:', new Date(claims.exp * 1000));
+  console.log('Is expired:', claims.exp < Date.now() / 1000);
+  console.groupEnd();
+  
+  // Testar acesso direto
+  try {
+    const { data, error } = await supabase
+      .from('examples')
+      .select('id, alias, title')
+      .limit(1);
+      
+    if (error) {
+      console.error('[RLS Debug] Query failed:', error);
+    } else {
+      console.log('[RLS Debug] Query success:', data);
+    }
+  } catch (err) {
+    console.error('[RLS Debug] Query exception:', err);
+  }
+}
+```
+
+#### 4. **Token Refresh Issues**
+
+```typescript
+// Problema: Token não renova automaticamente
+// Causa: Lógica de refresh não executando
+// Solução:
+class TokenRefreshManager {
+  private static refreshTimer: NodeJS.Timeout | null = null;
+  
+  static scheduleRefresh(token: string): void {
+    this.clearRefreshTimer();
+    
+    const decoded = TokenManager.decodeJWT(token);
+    if (!decoded) return;
+    
+    // Renovar 5 minutos antes de expirar
+    const expiryTime = decoded.exp * 1000;
+    const refreshTime = expiryTime - (5 * 60 * 1000);
+    const timeUntilRefresh = refreshTime - Date.now();
+    
+    if (timeUntilRefresh > 0) {
+      this.refreshTimer = setTimeout(async () => {
+        try {
+          await AuthService.refreshSupabaseToken();
+          console.log('[TokenRefresh] Auto-refresh successful');
+        } catch (error) {
+          console.error('[TokenRefresh] Auto-refresh failed:', error);
+          // Forçar re-login
+          AuthService.logout();
+        }
+      }, timeUntilRefresh);
+    }
+  }
+  
+  static clearRefreshTimer(): void {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+}
+```
+
+---
+
+## 🔒 Considerações de Segurança
+
+### Tokens em localStorage
+
+**Riscos:**
+- ❌ Vulnerável a XSS (Cross-Site Scripting)
+- ❌ Persistente entre sessões do browser
+- ❌ Acessível via JavaScript
+
+**Mitigações:**
+- ✅ CSP (Content Security Policy) rigoroso
+- ✅ HTTPS obrigatório em produção
+- ✅ Validação de origem nas Edge Functions
+- ✅ Tokens com TTL curto (24h max)
+- ✅ Limpeza automática na logout
+
+### CSRF Protection
+
+```typescript
+// Estado OAuth para prevenir CSRF
+function generateOAuthState(): string {
+  const state = crypto.randomUUID();
+  sessionStorage.setItem('oauth_state', state);
+  return state;
+}
+
+function validateOAuthState(receivedState: string): boolean {
+  const storedState = sessionStorage.getItem('oauth_state');
+  sessionStorage.removeItem('oauth_state');
+  return storedState === receivedState;
+}
+```
+
+### Token Validation
+
+```typescript
+// Validação robusta de tokens
+class TokenValidator {
+  static isValid(token: string): boolean {
+    if (!token) return false;
+    
+    try {
+      const decoded = TokenManager.decodeJWT(token);
+      if (!decoded) return false;
+      
+      // Verificar expiração
+      if (decoded.exp && decoded.exp < Date.now() / 1000) {
+        return false;
+      }
+      
+      // Verificar campos obrigatórios
+      if (!decoded.sub || !decoded.aud) {
+        return false;
+      }
+      
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  
+  static validateClaims(token: string, requiredClaims: string[]): boolean {
+    const decoded = TokenManager.decodeJWT(token);
+    if (!decoded) return false;
+    
+    return requiredClaims.every(claim => decoded[claim] !== undefined);
+  }
+}
+```
+
+---
+
+## 📊 Monitoramento e Métricas
+
+### Edge Functions Analytics
+
+```typescript
+// Logging estruturado nas Edge Functions
+function logAuthEvent(event: string, data: any): void {
+  console.log(JSON.stringify({
+    timestamp: new Date().toISOString(),
+    event: event,
+    data: data,
+    environment: Deno.env.get('DENO_DEPLOYMENT_ID') ? 'production' : 'development'
+  }));
+}
+
+// Métricas de uso
+logAuthEvent('token_validation_start', { alias });
+logAuthEvent('token_validation_success', { userId, alias });
+logAuthEvent('token_validation_error', { error: error.message });
+```
+
+### Frontend Analytics
+
+```typescript
+// Tracking de eventos de auth
+class AuthAnalytics {
+  static trackLogin(method: 'oauth' | 'dev'): void {
+    // Implementar com seu analytics favorito
+    console.log('[Analytics] Login attempt:', method);
+  }
+  
+  static trackCompanySwitch(fromAlias: string, toAlias: string): void {
+    console.log('[Analytics] Company switch:', { fromAlias, toAlias });
+  }
+  
+  static trackTokenRefresh(success: boolean): void {
+    console.log('[Analytics] Token refresh:', { success });
+  }
+}
+```
+
+---
+
+## 🚀 Próximos Passos e Melhorias
+
+### Roadmap de Melhorias
+
+1. **Segurança Avançada**
+   - [ ] Implementar httpOnly cookies para tokens
+   - [ ] Adicionar refresh token rotation
+   - [ ] Implementar device fingerprinting
+   - [ ] Rate limiting nas Edge Functions
+
+2. **Performance**
+   - [ ] Cache de validação de tokens
+   - [ ] Preload de dados de empresas
+   - [ ] Lazy loading de módulos auth
+   - [ ] Service Worker para token refresh
+
+3. **Monitoramento**
+   - [ ] Dashboard de métricas de auth
+   - [ ] Alertas de falhas de login
+   - [ ] Auditoria de mudanças de empresa
+   - [ ] Detecção de tentativas de ataque
+
+4. **Developer Experience**
+   - [ ] CLI para gerar tokens de dev
+   - [ ] Interface visual para debug de tokens
+   - [ ] Documentação interativa
+   - [ ] Testes automatizados de auth
+
+---
+
+**🎫 Arquitetura robusta e escalável para autenticação multi-tenant segura.**