Projetando RBAC de 31 permissões para bases de conhecimento de IA

Por que bases de conhecimento de IA precisam de controle de acesso real

Um workspace de IA concentra seu conhecimento operacional mais sensível: documentos internos, históricos de chat com citações RAG, configurações de agentes e conectores para sistemas externos. Quando essa superfície está aberta a uma empresa inteira, "quem pode ver o quê" deixa de ser um pedido de recurso agradável e se torna a mesma classe de problema que permissões de banco de dados: uma decisão de design que precisa ser correta por construção.

O Simmetric Chat trata assim. Toda requisição autenticada passa por uma verificação de papel e permissão antes de tocar nos dados de negócio, e o mesmo modelo que protege o histórico de chat também governa quais partes do aplicativo um usuário pode sequer ver na barra lateral. Este artigo mostra como o sistema é projetado: as 31 permissões que cobrem a superfície de recursos da plataforma, as 13 seções de menu que mapeiam essas permissões para a interface do usuário e os guards em nível de requisição que impedem usuários autenticados de alcançar registros que não são seus.

O modelo de permissões: 31 permissões granulares

No núcleo do modelo está um vocabulário fixo de 31 permissões. Cada permissão nomeia um recurso e uma ação, seguindo a convenção recurso:ação. Workspaces, projetos, chats e documentos carregam cada um a tríade completa leitura/escrita/exclusão, porque são os recursos que os usuários criam e destroem no curso do trabalho normal:

• workspace:read, workspace:write, workspace:delete
• project:read, project:write, project:delete
• chat:read, chat:write, chat:delete
• document:read, document:write, document:delete

Em torno desse núcleo estão permissões para o próprio fluxo de criação (workspace:create, project:create), para administrar a plataforma (admin:users, admin:settings, admin:roles) e para ler ou configurar provedores LLM (provider:read, provider:write). Arquivos recebem o mesmo tratamento de tríade que os recursos centrais, porque conversas arquivadas ainda são dados sensíveis.

Um cluster de seis permissões de backup separa gerenciamento de destinos, execução de jobs, inspeção de logs e operações de restauração - a divisão importa porque "poder disparar um backup" e "poder restaurar dados de produção em um workspace arbitrário" são níveis diferentes de confiança. Finalmente, memory:read e memory:write cobrem o sistema de memória por usuário e por workspace, e filters:manage restringe a administração de filtros apenas a administradores.

As permissões são armazenadas como uma tabela de enumeração no banco de dados e referenciadas por nome. Papéis personalizados são montados selecionando do conjunto de 31 permissões, então um operador pode expressar "arquivista" ou "analista somente leitura" sem tocar em código:

{
"name": "archivist",
"permissions": ["workspace:read", "document:read", "archive:read", "chat:read"]
}

Dois papéis padrão vêm de fábrica. O papel admin detém todas as 31 permissões; o papel de usuário detém um subconjunto de trabalho - acesso de leitura a workspaces e provedores, leitura/escrita em chats e documentos, leitura em arquivos, criação em workspaces e projetos e gerenciamento completo das próprias memórias. Nenhum papel é tratado de forma especial na lógica do aplicativo; ambos são linhas comuns que o middleware de permissões resolve como qualquer outra.

Seções de menu: permissões que moldam a interface

Um controle de acesso que só protege rotas de API produz uma experiência confusa - usuários clicam em botões que falham. O Simmetric Chat portanto também mapeia permissões para 13 seções de menu que controlam a visibilidade da barra lateral. As seções são a anatomia estrutural do aplicativo:

dashboard, chat, documents, knowledgeBase, workspaces, projects, marketplace, mcpConnections, eventLog, analytics, widget, settings e uploads.

Cada papel carrega sua própria lista de seções de menu, armazenada como strings para que novas seções possam ser adicionadas sem migração de banco de dados. Um papel de usuário pode ver dashboard, chat, documents, knowledgeBase, workspaces, widget e uploads, enquanto o papel admin vê todas as 13. O resultado é que a própria interface reflete o que o papel pode fazer: um usuário sem permissões de analytics nunca encontra um ponto de entrada de analytics para clicar.

As verificações de permissão e a visibilidade do menu são duas expressões do mesmo papel subjacente, o que significa que há uma única fonte de verdade para raciocinar durante uma auditoria.

Guards em nível de requisição: RBAC como middleware

Cada requisição de API resolve o usuário junto com papéis e permissões (com cache) e anexa a identidade resolvida à requisição. Acima disso estão quatro guards de middleware, cada um respondendo a uma pergunta diferente:

• requirePermission - admins sempre passam; todos os outros devem ter cada permissão listada para a rota. Requisições não autenticadas recebem 401; usuários autenticados sem permissões suficientes recebem 403 com um erro explícito "Insufficient permissions".
• requireAdmin - portão rígido para rotas administrativas, respondendo 403 "Admin access required" para não-admins.
• requireProjectAccess - uma verificação IDOR contra a propriedade do projeto e linhas de acesso explícitas.
• requireWorkspaceAccess - a mesma classe de verificação para workspaces, aceitando propriedade do workspace, propriedade do projeto pai ou uma concessão de acesso explícita.

Os dois últimos merecem ênfase porque abordam a classe de vulnerabilidade que aflige sistemas multi-tenant. Um ataque IDOR (insecure direct object reference) acontece quando /api/workspaces/123 confia mais no identificador na URL do que na identidade do chamador. Um usuário autenticado - mas não autorizado para o workspace 123 - não deve poder ler seus documentos adivinhando identificadores. O Simmetric Chat responde a essas requisições com 401 quando o usuário não está autenticado e 403 "Insufficient permissions" quando o usuário simplesmente não tem acesso, em vez de vazar a existência ou o conteúdo do recurso.

A proteção de rotas é declarativa. CRUD de workspaces exige requireWorkspaceAccess; criar um workspace exige a permissão workspace:create e respeita os limites do plano; a administração de papéis vive atrás de requireAdmin. A tabela de rotas se lê como a política de segurança, que é exatamente a propriedade que você quer quando um novo engenheiro pergunta "o que este endpoint pode fazer?"

Trilhas de auditoria: saber quem fez o quê

Verificações de permissão respondem "essa ação deveria ser permitida?"; trilhas de auditoria respondem "o que realmente aconteceu?". O Simmetric Chat registra uma trilha de auditoria das ações significativas da plataforma - eventos de autenticação, operações de documentos, mudanças de configuração e ações administrativas - em um registro de eventos navegável.

A combinação é o que torna o RBAC operacional em vez de teórico. Quando ocorre uma exclusão inesperada de documento, o registro de eventos identifica o ator e a ação; o modelo de permissões explica qual papel permitiu; e ajustar as permissões de um papel ou suas seções de menu fecha a lacuna. A superfície de auditoria é em si protegida por permissão através da seção de menu eventLog, então o registro da atividade relacionada à segurança só é visível para papéis em que se confiou.

Mudanças sensíveis de retenção - como configurar os dias de retenção de mensagens de chat - são elas mesmas auditadas, então até os controles que governam o ciclo de vida dos dados deixam seu próprio rastro.

Como isso se parece na prática

Considere uma implantação de três papéis. Administradores mantêm o conjunto completo de 31 permissões e todas as 13 seções de menu. Um papel de usuário diário trabalha dentro de chats, documentos e seus próprios workspaces, e nunca vê o registro de eventos nem as configurações de provedores. Um auditor de conformidade obtém permissões somente leitura em documentos, chats e arquivos, mais acesso ao registro de eventos - capaz de inspecionar qualquer coisa, mudar nada.

Nada disso exigiu bifurcar o aplicativo ou escrever middleware personalizado. Exigiu montar permissões em papéis e mapear seções de menu. Esse é o objetivo de design que o modelo de 31 permissões serve: granulado o suficiente para expressar fronteiras organizacionais reais, simples o suficiente para que a política caiba na cabeça.

Para ver o vocabulário completo de permissões e os endpoints de gerenciamento de papéis, leia a referência de API. Para um tour prático de papéis, permissões e seções de menu na interface de administração, veja o guia de uso.