Autorização (RBAC)

Guards disponíveis

Guard	Arquivo	Função
ClerkAuthGuard	config/users/clerk-auth.guard.ts	Valida JWT do Clerk
RolesGuard	config/users/roles.guard.ts	Verifica nível hierárquico do papel
PermissionsGuard	common/guards/permissions.guard.ts	Verifica permissões específicas
ReadOnlyGuard	common/guards/read-only.guard.ts	Bloqueia mutações para roles read-only
UserThrottlerGuard	common/guards/user-throttler.guard.ts	Rate limiting por usuário
InternalApiKeyGuard	common/guards/internal-api-key.guard.ts	Auth para serviços internos
AdminGuard	modules/admin/admin.guard.ts	Restringe a Super Admin (level 0)

Decorators de autenticação

// Endpoint público (sem auth)
@Public()

// Requer permissão específica (OR entre as listadas)
@Permissions('app:campaigns', 'app:campaigns:send')

// Requer papel específico
@Roles('super_admin')

// Injeta usuário atual no parâmetro
@CurrentUser() user: AuthedUser

Isolamento de tenant

O TenantInterceptor roda após o ClerkAuthGuard e define o contexto de organização via AsyncLocalStorage. Todos os services acessam TenantContext.organizationId para garantir que nenhuma query retorne dados de outra organização.

Override de Super Admin

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

Apenas Super Admin (level 0) pode usar esse header. Permite administrar qualquer organização. É logado automaticamente.

Proteção contra escalação de privilégios

O sistema valida:

1. Quem convida precisa ter level <= 10
2. Papel atribuído deve ter level > nível do convidante
3. Usuário não pode alterar seu próprio papel

Exemplo: Usuário level 5 só pode:

• Criar papéis com level 6, 7, 8...
• Atribuir papéis com level 6+ para outros

Read-only mode

Roles com readOnly: true só podem fazer GET requests. Qualquer tentativa de POST, PUT, PATCH ou DELETE retorna 403.

Uso: auditores, observadores, integrações de leitura.

Rate limiting

O UserThrottlerGuard rastreia por:

• Usuário autenticado: user-{userId}
• Anônimo: IP da conexão

Limites por endpoint:

• POST /users/invite: 30/60s
• PATCH /users/:id/role: 20/60s

Internal API Key (serviços internos)

Endpoints chamados por n8n, scripts ou outros serviços backend usam:

Authorization: Bearer {INTERNAL_API_KEY}

Implementado com crypto.timingSafeEqual() para evitar timing attacks. Falhas são logadas com IP e path.

Visibilidade de dados por loja

Usuários podem ter accessibleStores — lista de IDs de lojas que podem visualizar. Se preenchido, queries de analytics e relatórios filtram apenas essas lojas.