role

O submódulo Role é a base do sistema de Role-Based Access Control do HedHog, governando quais usuários podem acessar quais recursos em todas as partes da plataforma. Todo recurso protegido — endpoints HTTP, entradas de menu do admin e definições de screen — é registrado individualmente no sistema. As roles agrupam os recursos permitidos, e os usuários possuem uma ou mais roles cujas permissões são aditivas: o conjunto efetivo de permissões é a união de todas as roles atribuídas. Por padrão, não há hierarquia ou herança de roles.

As permissões são estruturadas em quatro eixos. As routes definem quais endpoints HTTP (método + padrão de URL) uma role pode chamar. Os menus definem quais entradas de navegação ficam visíveis no painel de administração. As screens definem quais definições de página do front-end são acessíveis. Os users definem quais contas possuem a role no momento. Cada eixo é gerenciado de forma independente, dando controle granular sobre o que cada role pode ver e fazer, sem acoplar a visibilidade da navegação ao acesso à API.

A role admin é uma role de sistema especial, inserida durante a instalação, que concede acesso irrestrito a todos os recursos. Ela não deve ser excluída. As roles de admin específicas por módulo (admin-user, admin-mail, admin-finance) fornecem escopos administrativos mais restritos para operadores que devem gerenciar apenas um subconjunto da plataforma. Essas roles granulares permitem aplicar o princípio do menor privilégio mesmo para usuários administrativos.

As atribuições de role podem ser gerenciadas em qualquer direção: pelo lado da role (PATCH /role/:roleId/user substitui todos os usuários de uma role de uma só vez) ou pelo lado do usuário (POST /user/:userId/role/:roleId atribui uma única role). Ambos os caminhos gravam na mesma tabela de junção subjacente e podem ser usados de forma intercambiável, dependendo se o administrador está raciocinando em termos de roles ou de usuários.

No fluxo YAML do HedHog, as atribuições de role para rotas e menus são declaradas em role.yaml e route.yaml, dentro do diretório hedhog/data/ de cada biblioteca. Esses arquivos são a fonte da verdade para os seeds de permissão aplicados durante o hedhog dev apply, garantindo que as mudanças de permissão trafeguem pelo controle de versão junto com os endpoints que governam.