Regras de Permissões (RBAC)

Modelo de permissões

Cada usuário tem um papel (role) que contém uma lista de permissões (strings). Os guards verificam se o papel do usuário tem a permissão necessária.

Usuário → Papel (Role) → Permissões (string[])

Lógica: OR entre permissões de um endpoint. Se o papel tem qualquer uma das permissões declaradas, o acesso é liberado.

Lista de permissões

Permissão	Acesso
app:dashboard	Dashboard de performance (KPIs, histórico de vendas)
app:customers	Listar e buscar clientes
app:customers:delete	Deletar registros de clientes
app:financials	Ver dados financeiros de clientes (LTV, histórico)
app:sales	Analytics de varejo, canais, origem, qualidade
app:segments	Criar e gerenciar segmentos e análise RFM
app:export	Download de CSV em todas as telas
app:campaigns	Ver e criar campanhas
app:campaigns:send	Disparar campanhas
app:integrations	WhatsApp, Chatwoot, templates, rate limits, ERP sync
app:settings	Configurações de loja, organização, campanhas
app:team	Convidar e gerenciar usuários
app:roles	Criar e editar papéis e permissões
app:audit	Ver log de auditoria
app:store-aliases	Gerenciar hierarquia de lojas

Hierarquia de nível (level)

Cada papel tem um level numérico. Menor número = maior privilégio.

Level	Papel padrão	Acesso
0	Super Admin	Tudo — bypassa todos os guards
1–4	Admin / Gestor	Nível alto de acesso
5–7	Analista / Operador	Acesso intermediário
8–10	Usuário padrão	Acesso básico

Papel somente-leitura (readOnly)

Papéis com readOnly: true não podem executar mutações (POST, PUT, PATCH, DELETE), independente das permissões listadas. Ideal para auditores ou observadores.

Exceção: Super Admin (level 0) nunca é read-only.

Proteção contra escalonamento de privilégios

• Usuário não pode criar papel com level igual ou menor ao seu próprio
• Usuário não pode atribuir papel com level igual ou menor ao seu a outro usuário
• Usuário não pode alterar seu próprio papel (exceto Super Admin)
• Usuário só pode gerenciar usuários da sua própria organização

Exemplo: Um usuário com level 5 pode criar papéis de level 6+ e atribuir para outros. Não pode criar papéis de level 5 ou menor.

Override de organização (Super Admin)

Super Admin pode impersonar qualquer organização passando o header:

x-org-id: {uuid-da-organizacao}

Isso é logado automaticamente no middleware HTTP.

Acesso por loja

Usuários podem ter acesso restrito a lojas específicas (accessibleStores). Quando configurado, queries de dados são filtradas para retornar apenas dados das lojas acessíveis.

Guards em ordem de execução

Request
  → ClerkAuthGuard (valida JWT)
  → TenantInterceptor (define organizationId no contexto)
  → PermissionsGuard (verifica permissões do papel)
  → ReadOnlyGuard (bloqueia mutações se readOnly)
  → UserThrottlerGuard (rate limiting por usuário)
  → Controller
  → AuditInterceptor (loga ação na saída)

Endpoints de sistema interno (Internal API Key)

Endpoints chamados por n8n ou outros serviços internos usam INTERNAL_API_KEY em vez de JWT do Clerk. O guard compara o header com timing-safe compare para evitar timing attacks.

Authorization: Bearer {INTERNAL_API_KEY}