forlogic-core 1.5.1 → 1.5.3

package/dist/docs/architecture/TOKENS_ARCHITECTURE.md

@@ -1,712 +0,0 @@
-# 🎫 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.**