RBAC multi-tenant por White Label
Última revisão contra o código: 19/09/2026.
Este documento descreve o modelo que está no ar. O desenho antigo com a tabela white_label_permission_scope não foi criado — o runtime usa white_label_permissao + permissao_escopo_global.
Regra central
Um usuário de White Label só exerce uma permissão se:
- a flag estiver em
permissao_usuario, e - a mesma flag estiver autorizada em
white_label_permissaodaquele WL.
Usuário de plataforma (users.white_label_id nulo/0) usa o catálogo permissao_escopo_global.
Super-admin tem bypass total em backend_permission_user_can().
Flags platform-only (white_label.*, admin.permissions, management.default_rates) nunca passam para usuário tenant.
Tabelas reais
| Tabela | Papel |
|---|---|
permissoes | Catálogo (chave canônica EN) |
permissao_usuario | Grants do usuário |
white_label_permissao | Escopo delegável do WL (white_label_id, permissao_id) |
permissao_escopo_global | Escopo da equipe de plataforma |
tenant_modules | Liga/desliga módulo (leads, tasks) por tenant — não é grant de flag |
users | role, white_label_id |
setores / user_setores | Filtro de menu (antes do RBAC de item) |
Código: backend/src/services/core/permission_service.php e permission_canonical.php. Política B documentada em permission_scope_policy_b.php.
Constante BACKEND_PERMISSION_ALLOW_FALLBACK_WITHOUT_SCOPE_TABLES default false (fail-closed se as tabelas de escopo sumirem).
Papéis
Canônicos em authorization_service.php:
| Role | Rank | Uso |
|---|---|---|
super-admin | 100 | Bypass de flag; visão global |
admin | 80 | Governança do escopo |
gestor | 50 | Gestão de time/carteira |
colaborador | 20 | Operação no próprio vínculo |
Legado normalizado para colaborador: marketplace, representante, rep, ec, operador, visualizador, etc.
Atribuição: super-admin atribui qualquer nível de cadastro; admin pode atribuir admin; demais só níveis inferiores.
Flags canônicas
Formato: modulo.acao ou modulo.recurso.acao, em inglês.
Exemplos: users.edit, establishments.change_representative, leads.stage.change, tasks.read.
Aliases PT (usuarios.editar, estabelecimentos.trocar_representante) ainda resolvem para a canônica. Código novo deve pedir a chave EN. Catálogo de UI deve mostrar só a canônica.
Fonte da verdade: backend_permission_families() em permission_canonical.php.
Runtime (can)
backend_permission_user_can($conn, $userId, $permissionKey):
- recusa
userIdinválido ou chave vazia; - libera se super-admin;
- recusa flag platform-only para tenant;
- expande aliases;
- exige linha em
permissao_usuario+ condição de escopo (white_label_permissaooupermissao_escopo_global); - tenta implicação (
backend_permission_is_implied_by_holders) se o COUNT for 0.
backend_permission_require() / require_any() existem e devolvem 403, mas os endpoints quase não as chamam — a checagem está nos services (_assert_can, backend_leads_assert_can, backend_tasks_*, temPermissao()).
Adaptador legado: backend/includes/permissoes.php → temPermissao().
Fluxos na UI
Escopo do WL
Tela frontend/pages/white-label/escopo-permissoes.php + API backend/api/permissoes/*. Admin de plataforma define o que o WL pode distribuir. Hard enforcement: se a flag sai do escopo, can() falha mesmo com grant residual.
Permissões de usuário
Tela frontend/pages/permissoes/usuarios.php. Admin WL só enxerga/atribui flags do próprio escopo (Policy B).
Menu
components/menu-lateral.php: setor → flags de sessão → tenant_modules (comercial/tarefas). data-permission é só UX.
O que o desenho antigo propunha e não entrou
- Tabela
white_label_permission_scope— não existe. permission_templatesportipo_precificacao— não existe.- Colunas
scope_level/delegavel_para_wlno catálogo — a governança equivalente veio pelo parwhite_label_permissao+permissao_escopo_global+backend_permission_is_platform_only(). - Serviço em
config/permissoes/authorization_service.php— o runtime está embackend/src/services/core/.
Não recriar essas tabelas sem migrar os grants atuais.
Checklist (estado)
- Admin WL não vê flag de plataforma.
- API de atribuição valida escopo (Policy B).
- Remoção do escopo WL corta o acesso na hora (
can). - Super-admin com governança total.
- Tentativa negada vai para log (
permission_denied). - CSRF e
backend_permission_requireem todos os endpoints mutáveis. - Testes automatizados role × flag × escopo.