autorizacao-rbac-por-recurso
Controle de acesso baseado em papéis (admin/editor/leitor/convidado) com verificação granular por recurso individual (projeto, pasta, texto). Ativar ao implementar permissões de acesso colaborativo, c
SKILL.md.agents/skills/autorizacao-rbac-por-recurso/SKILL.md
GitHubautorizacao-rbac-por-recurso
Descrição
A skill autorizacao-rbac-por-recurso implementa o sistema de controle de acesso granular da plataforma, definindo quais papéis (roles) podem executar quais ações em cada recurso específico (projeto, pasta ou texto). Ela vai além de um RBAC global, permitindo que um mesmo usuário seja "editor" num projeto e "leitor" em outro, sem necessitar de schemas separados por tenant.
Quando usar
Gatilhos concretos e observáveis:
- Implementação dos UC relacionados a compartilhamento (UC-081, UC-083), permissões por pasta (UC-245) e papéis de equipe (UC-256).
- Adição de um novo endpoint de API que modifica dados de outro usuário.
- Implementação do painel administrativo (UC-215, UC-216).
Quando NÃO usar:
- Para o isolamento de dados entre tenants diferentes (usar
isolamento-de-banco-de-dados-com-rls). - Para autenticação e geração de tokens (usar
autenticacao-jwt-e-refresh-token).
Pré-requisitos
- Tabela
resource_permissionsno banco:(user_id, resource_type, resource_id, role). - Middleware de autenticação já injetando
user_idno contexto da requisição. - Enum de papéis:
ADMIN | OWNER | EDITOR | VIEWER | GUEST.
Processo (passo a passo executável)
Definição da Matriz de Permissões: Implementar a matriz de capacidades por papel como constante imutável:
const PERMISSIONS = { ADMIN: { read: true, write: true, delete: true, manage_members: true }, OWNER: { read: true, write: true, delete: true, manage_members: true }, EDITOR: { read: true, write: true, delete: false, manage_members: false }, VIEWER: { read: true, write: false, delete: false, manage_members: false }, GUEST: { read: true, write: false, delete: false, manage_members: false }, };Middleware de Autorização por Recurso:
- Criar função
authorize(action, resourceType)usada como middleware em cada rota. - A função consulta a tabela
resource_permissionspara o par(user_id, resource_id). - Verifica se o papel encontrado tem a capacidade
actionna matrizPERMISSIONS. - Se não houver registro direto, verificar herança: permissão na pasta pai do texto, ou no projeto pai da pasta.
- Criar função
Herança Hierárquica de Permissões:
- Permissões propagam do topo para baixo: Projeto → Pasta → Texto.
- Se um usuário tem papel
EDITORno Projeto A, herdaEDITORem todas as pastas e textos do Projeto A, a menos que haja uma permissão explícita mais restritiva no recurso filho.
API de Gerenciamento de Permissões:
POST /api/resources/:id/members— Adicionar membro com papel (apenasOWNERouADMINpode fazer).PATCH /api/resources/:id/members/:userId— Alterar papel de membro.DELETE /api/resources/:id/members/:userId— Remover membro.
Parâmetros e configuração
| Parâmetro | Descrição | Padrão |
|---|---|---|
DEFAULT_NEW_PROJECT_ROLE |
Papel atribuído ao criador do projeto | OWNER |
DEFAULT_INVITED_ROLE |
Papel padrão para usuários convidados por link | VIEWER |
PERMISSION_INHERITANCE |
Habilita herança hierárquica de permissões | true |
Armadilhas e como evitá-las
- Armadilha: Verificar permissões apenas no frontend (ocultar botões de edição para
VIEWER), sem validação no backend. Um usuário malicioso pode enviar requisições diretamente à API e modificar dados de outro usuário. Mitigação: A verificação de autorização DEVE ser executada no middleware de backend em toda rota que modifica dados, independentemente de como a UI está configurada. A UI pode ocultar botões para melhor UX, mas nunca como mecanismo de segurança.
Critérios de validação (Definition of Done)
- Um usuário com papel
VIEWERnão consegue executar operações de escrita ou deleção via API em 100% dos testes de penetração de autorização. - A herança de permissões propaga corretamente do projeto para subpastas e textos sem consultas adicionais ao banco.
Exemplos
Cenário de herança:
- Usuário Maria:
EDITORno Projeto "Romance A" (sem registro na pasta "Capítulo 3"). - Maria tenta editar texto "Cena 7" dentro de "Capítulo 3" dentro de "Romance A".
- Sistema: sem registro direto → verifica pasta pai → sem registro → verifica projeto →
EDITOR. Permissão concedida.
Cenário de bloqueio:
- Usuário João:
VIEWERno Projeto "Romance B". - João envia
PATCH /api/texts/42diretamente via curl. - Middleware
authorize('write', 'text')consulta permissão →VIEWER.write = false→ responde403 Forbidden.