Diseñando RBAC de 31 permisos para bases de conocimiento IA

Por qué las bases de conocimiento IA necesitan control de acceso real

Un workspace de IA concentra su conocimiento operativo más sensible: documentos internos, historiales de chat con citas RAG, configuraciones de agentes y conectores a sistemas externos. Cuando esa superficie está abierta a toda una empresa, "quién puede ver qué" deja de ser una petición de funcionalidad agradable y se convierte en la misma clase de problema que los permisos de base de datos: una decisión de diseño que tiene que ser correcta por construcción.

Simmetric Chat lo trata así. Cada solicitud autenticada pasa por un control de rol y permiso antes de tocar los datos de negocio, y el mismo modelo que protege el historial de chat también gobierna qué partes de la aplicación puede ver un usuario en la barra lateral. Este artículo explica cómo está diseñado el sistema: los 31 permisos que cubren la superficie de recursos de la plataforma, las 13 secciones de menú que mapean esos permisos a la interfaz de usuario y los guardas a nivel de solicitud que impiden que usuarios autenticados alcancen registros que no son suyos.

El modelo de permisos: 31 permisos granulares

En el núcleo del modelo hay un vocabulario fijo de 31 permisos. Cada permiso nombra un recurso y una acción, siguiendo la convención recurso:acción. Los workspaces, proyectos, chats y documentos llevan cada uno el triplete completo de lectura/escritura/eliminación, porque son los recursos que los usuarios crean y destruyen en el curso del trabajo 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

Alrededor de ese núcleo hay permisos para el flujo de creación en sí (workspace:create, project:create), para administrar la plataforma (admin:users, admin:settings, admin:roles) y para leer o configurar proveedores LLM (provider:read, provider:write). Los archivos reciben el mismo tratamiento de triplete que los recursos del núcleo, porque las conversaciones archivadas siguen siendo datos sensibles.

Un grupo de seis permisos de backup separa la gestión de destinos, la ejecución de trabajos, la inspección de registros y las operaciones de restauración: la división importa porque "poder activar un backup" y "poder restaurar datos de producción en un workspace arbitrario" son niveles de confianza diferentes. Finalmente, memory:read y memory:write cubren el sistema de memoria por usuario y por workspace, y filters:manage restringe la administración de filtros solo a administradores.

Los permisos se almacenan como una tabla de enumeración en la base de datos y se referencian por nombre. Los roles personalizados se ensamblan seleccionando del conjunto de 31 permisos, así un operador puede expresar "archivero" o "analista de solo lectura" sin tocar código:

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

Dos roles predeterminados vienen de fábrica. El rol admin posee los 31 permisos; el rol de usuario posee un subconjunto de trabajo: acceso de lectura a workspaces y proveedores, lectura/escritura en chats y documentos, lectura en archivos, creación en workspaces y proyectos, y gestión completa de sus propias memorias. Ningún rol recibe tratamiento especial en la lógica de la aplicación; ambos son filas ordinarias que el middleware de permisos resuelve como cualquier otra.

Secciones de menú: permisos que dan forma a la interfaz

Un control de acceso que solo protege las rutas API produce una experiencia confusa: los usuarios hacen clic en botones que fallan. Simmetric Chat por tanto también mapea permisos a 13 secciones de menú que controlan la visibilidad de la barra lateral. Las secciones son la anatomía estructural de la aplicación:

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

Cada rol lleva su propia lista de secciones de menú, almacenada como cadenas para que se puedan añadir nuevas secciones sin migración de base de datos. Un rol de usuario podría ver dashboard, chat, documents, knowledgeBase, workspaces, widget y uploads, mientras que el rol admin ve las 13. El resultado es que la propia interfaz refleja lo que el rol puede hacer: un usuario sin permisos de analytics nunca se encuentra con un punto de entrada de analytics que clicar.

Los controles de permiso y la visibilidad del menú son dos expresiones del mismo rol subyacente, lo que significa que hay una única fuente de verdad sobre la que razonar durante una auditoría.

Guardas a nivel de solicitud: RBAC como middleware

Cada solicitud API resuelve al usuario junto con roles y permisos (con caché) y adjunta la identidad resuelta a la solicitud. Encima hay cuatro guardas de middleware, cada una respondiendo una pregunta diferente:

• requirePermission - los admins siempre pasan; todos los demás deben tener cada permiso listado para la ruta. Las solicitudes no autenticadas reciben 401; los usuarios autenticados sin permisos suficientes reciben 403 con un error explícito "Insufficient permissions".
• requireAdmin - compuerta dura para rutas administrativas, respondiendo 403 "Admin access required" para no-admins.
• requireProjectAccess - un control IDOR contra la propiedad del proyecto y las filas de acceso explícito.
• requireWorkspaceAccess - la misma clase de control para workspaces, aceptando la propiedad del workspace, la propiedad del proyecto padre o una concesión de acceso explícita.

Los dos últimos merecen énfasis porque abordan la clase de vulnerabilidad que aqueja a los sistemas multi-tenant. Un ataque IDOR (insecure direct object reference) ocurre cuando /api/workspaces/123 confía más en el identificador de la URL que en la identidad del llamante. Un usuario autenticado - pero no autorizado para el workspace 123 - no debe poder leer sus documentos adivinando identificadores. Simmetric Chat responde a esas solicitudes con 401 cuando el usuario no está autenticado y 403 "Insufficient permissions" cuando simplemente carece de acceso, en lugar de filtrar la existencia o el contenido del recurso.

La protección de rutas es declarativa. El CRUD de workspaces requiere requireWorkspaceAccess; crear un workspace requiere el permiso workspace:create y respeta los límites del plan; la administración de roles vive detrás de requireAdmin. La tabla de rutas se lee como la política de seguridad, que es exactamente la propiedad que quieres cuando un ingeniero nuevo pregunta "¿qué puede hacer este endpoint?"

Pistas de auditoría: saber quién hizo qué

Los controles de permiso responden "¿debería permitirse esta acción?"; las pistas de auditoría responden "¿qué pasó realmente?". Simmetric Chat registra una pista de auditoría de las acciones significativas de la plataforma - eventos de autenticación, operaciones de documentos, cambios de configuración y acciones administrativas - en un registro de eventos navegable.

La combinación es lo que hace que el RBAC sea operativo en lugar de teórico. Cuando ocurre una eliminación de documento inesperada, el registro de eventos identifica al actor y la acción; el modelo de permisos explica qué rol lo permitió; y ajustar los permisos de un rol o sus secciones de menú cierra la brecha. La superficie de auditoría está a su vez protegida por permisos a través de la sección de menú eventLog, así el registro de la actividad relacionada con la seguridad solo es visible para los roles que fueron considerados dignos de confianza.

Los cambios sensibles de retención - como configurar los días de retención de mensajes de chat - también son auditados, así incluso los controles que gobiernan el ciclo de vida de los datos dejan su propia huella.

Cómo se ve esto en la práctica

Considere una implementación de tres roles. Los administradores mantienen el conjunto completo de 31 permisos y las 13 secciones de menú. Un rol de usuario diario trabaja dentro de chats, documentos y sus propios workspaces, y nunca ve el registro de eventos ni los ajustes de proveedores. Un auditor de cumplimiento obtiene permisos de solo lectura en documentos, chats y archivos, más acceso al registro de eventos: capaz de inspeccionar cualquier cosa, cambiar nada.

Nada de esto requirió bifurcar la aplicación ni escribir middleware personalizado. Requirió ensamblar permisos en roles y mapear secciones de menú. Ese es el objetivo de diseño al que sirve el modelo de 31 permisos: lo bastante granular para expresar fronteras organizativas reales, lo bastante simple para que la política quepa en la cabeza.

Para ver el vocabulario completo de permisos y los endpoints de gestión de roles, lee la referencia de API. Para un recorrido práctico de roles, permisos y secciones de menú en la interfaz de administración, consulta la guía de uso.