Pular para o conteúdo principal

Autorização e Controle de Acesso Baseado em Papéis (RBAC)

Pilar: 01 — Arquitetura, Stack e Segurança
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/core/dependencies.py, app/api/web/auth.py), gatein-web (src/routes/ProtectedRoutes)

1. Visão Geral do Modelo de Permissões​

O controle de acesso no ecossistema Gatein é baseado no padrão RBAC (Role-Based Access Control). Cada usuário autenticado (seja via Firebase Auth no Web App ou via JWT no App Mobile) possui um papel de segurança (role) associado que determina os endpoints e recursos que pode manipular.

1.1 Diagrama de Avaliação de Segurança por Requisição​

flowchart TD
    A[Requisição Ingressante no Server] --> B{Possui Header Auth?}
    B -->|Não| C[HTTP 401 Unauthorized]
    B -->|Sim| D{Tipo de Token?}
    
    D -->|JWT Mobile| E[Valida JWT Secret + tax_id]
    E --> F[get_current_driver]
    F --> G{Recurso Pertence ao tax_id?}
    G -->|Não| H[HTTP 403 Forbidden]
    G -->|Sim| I[Executa Rota Mobile]
    
    D -->|Firebase Bearer| J[Valida Token no Firebase Admin SDK]
    J --> K[get_current_admin_company_user]
    K --> L{is_active == True?}
    L -->|Não| M[HTTP 403 USER_DEACTIVATED]
    L -->|Sim| N{Possui Role & Permissão Exigida?}
    N -->|Não| H
    N -->|Sim| O[Executa Query com Tenant Guard (company_id)]

2. Matriz de Papéis (Roles) e Escopos​

RoleDomínio de AcessoDescriçãoExemplo de Usuário
platform_adminGlobal (Cross-Tenant)Administrador da Plataforma Gatein. Acesso total a todas as empresas, rotas de infraestrutura e /admin/system.Equipe de Engenharia / Devops
adminTenant EspecíficoAdministrador da Empresa Cliente. Acesso irrestrito dentro da sua company_id (gestão de usuários, API Keys, layouts, geofence).Gerente de TI do Terminal
terminalOperacional PátioOperador de Pátio. Acesso a criar agendamentos, visualizar triagem, aprovar/rejeitar check-ins e emitir tickets.Balancista / Operador de Gate
transportadorOperacional FrotaOperador de Transportadora. Acesso a visualizar viagens, cadastrar motoristas frotistas e agendar cargas.Despachante da Transportadora
driverApp Mobile ApenasMotorista de Frete. Acesso exclusivo aos agendamentos, tickets e viagens associados ao seu CPF (tax_id).Motorista de Carreta

3. Matriz de Permissões por Funcionalidade (CRUD)​

Módulo / Featureplatform_adminadminterminaltransportadordriver
Usuários Web (/web/users)✅ Criar/Editar✅ Criar/Editar❌ Sem Acesso❌ Sem Acesso❌ Sem Acesso
API Keys (/web/api-key)✅ Criar/Revogar✅ Criar/Revogar❌ Sem Acesso❌ Sem Acesso❌ Sem Acesso
Layouts (/web/*-layout)✅ Publicar✅ Publicar⚠️ Apenas Leitura❌ Sem Acesso❌ Sem Acesso
Geofence (/web/config)✅ Atualizar✅ Atualizar⚠️ Apenas Leitura❌ Sem Acesso❌ Sem Acesso
Appointments (/web/appointments)✅ Total✅ Total✅ Criar/Aprovar✅ Criar (Sua Frota)⚠️ Apenas os Seus (tax_id)
Aprovação Check-in✅ Aprovar/Rejeitar✅ Aprovar/Rejeitar✅ Aprovar/Rejeitar❌ Sem Acesso❌ Sem Acesso (Dispara apenas)
Anúncios (/web/announcements)✅ Publicar✅ Publicar⚠️ Apenas Leitura❌ Sem Acesso⚠️ Visualiza (Gps/Empresa)
Homologação (/admin/system)✅ Acesso Total❌ Sem Acesso❌ Sem Acesso❌ Sem Acesso❌ Sem Acesso

4. Middlewares e Funções de Injeção em dependencies.py​

O backend FastAPI implementa verificações de segurança por injeção de dependências:

4.1 get_current_user()​

Extrai e valida o Firebase ID Token. Retorna o registro User ou CompanyUser.

4.2 require_permission(resource, action)​

Dependency Factory que recebe o nome do recurso (ex: 'geofence', 'users', 'api_key') e a ação ('read', 'write', 'delete').

def require_permission(resource: str, action: str):
    def dependency(current_user: CompanyUser = Depends(get_current_user)):
        if current_user.role == "admin" or current_user.role == "platform_admin":
            return current_user  # Bypassed para admins da empresa
        if not check_user_has_permission(current_user, resource, action):
            raise HTTPException(status_code=403, detail={"code": "INSUFFICIENT_PERMISSIONS"})
        return current_user
    return dependency

4.3 get_company_context()​

Injeta automaticamente o company_id resolvido do usuário autenticado nas queries SQLAlchemy, prevenindo vazamentos Cross-Tenant.

5. Regras de Negócio Explícitas (RN-RBAC-XXX)​

RN-RBAC-001: Impossibilidade de Manipulação de Tenant pelo Client​

Em nenhum endpoint REST do ecossistema o parâmetro company_id enviado no corpo da requisição ou na query string é utilizado como fonte de autoridade. O company_id é obrigatoriamente resolvido pelo servidor a partir do token verificado.

RN-RBAC-002: Exclusividade de Acesso a Dados do Próprio CPF (tax_id)​

No aplicativo mobile, a dependência get_current_driver extrai o CPF do token JWT. Qualquer tentativa de consultar agendamentos, tickets ou viagens informando o ID de outro motorista é bloqueada pelo filtro obrigatorio user_tax_id == current_user.tax_id (retornando HTTP 404/403).

RN-RBAC-003: Bloqueio de Acesso a Operadores Desativados​

Usuários com company_users.is_active == False têm o acesso negado em todas as chamadas de API com HTTP 403 (USER_DEACTIVATED), independente da validade do token JWT ou Firebase Auth.

RN-RBAC-004: Restrição Estrita da Rota /admin/system​

Endpoints sob o prefixo /admin/system (como geradores de senhas de staging e criação de motoristas fake) exigem incondicionalmente o papel role == "platform_admin". Operadores com papel admin de empresa cliente recebem HTTP 403 ao tentar acionar essas rotas.