Permisos y roles
¿Qué es esto?
Cómo funcionan la identidad y el acceso en ComStack: tres capas de identidad, roles de proyecto y aplicación en herramientas MCP y endpoints REST.
Cómo funciona
Capas de identidad
Existen tres capas de identidad independientes que funcionan en paralelo:
| Capa | Propósito |
|---|---|
| Usuario | Identidad global. Una por persona real, identificada por Firebase Auth UID. |
| Cuenta | Entidad legal y de facturación. Posee proyectos. |
| Miembro del proyecto | Acceso por proyecto con un rol asignado. |
| Administrador de plataforma | Acceso global para el equipo de ComStack: omite todas las comprobaciones a nivel de proyecto. |
Un mismo usuario puede ser miembro de múltiples proyectos en varias cuentas. La pertenencia a una cuenta y a un proyecto son independientes: ser el propietario de la cuenta no otorga acceso automático al proyecto.
Roles de proyecto
Tres roles de proyecto almacenados en el documento del miembro:
| Rol | Descripción |
|---|---|
manager | Acceso total al proyecto: contenido, configuración, miembros y todas las operaciones destructivas. |
editor | Destinado a la edición de contenido sin privilegios destructivos. Actualmente no se aplica: se comporta igual que un miembro genérico (ver Brecha de implementación más abajo). |
viewer | Destinado a acceso de solo lectura. Actualmente no se aplica: se comporta igual que un miembro genérico. |
Matriz de capacidades de herramientas MCP
| Capacidad | manager | Cualquier miembro | Admin de plataforma |
|---|---|---|---|
get-project-state, get-page-content, list-pages | ✅ | ✅ | ✅ |
create-page, update-page | ✅ | ✅ | ✅ |
delete-page, update-theme | ✅ | ❌ | ✅ |
publish, publish-confirm | ✅ | ❌ | ✅ |
connect-github, pull-and-publish, revert-publish | ✅ | ❌ | ✅ |
| Herramientas CRUD de plantillas | ❌ | ❌ | ✅ |
whoami, list-my-projects, create-project, get-guide | ✅ | ✅ | ✅ |
tools/list se filtra según el autor de la llamada: aquellos que no son manager no ven las herramientas de gestión exclusivas. El resultado del filtro se almacena en caché durante 30 segundos por usuario.
Brecha de implementación: editor/viewer no aplicados
La API acepta los valores de rol editor y viewer, pero la capa de autenticación solo distingue entre manager y “existe cualquier documento de miembro”. Editor y viewer se comportan de forma idéntica: ambos obtienen acceso de lectura/escritura no destructivo, igual que cualquier otro miembro.
No confíe en las distinciones entre editor y viewer por motivos de seguridad.
Cuándo usarlo
- Comprobar qué puede hacer un usuario con un rol determinado antes de crear un flujo de trabajo.
- Diagnosticar un error 403 en una llamada a una herramienta MCP (¿es el usuario un manager?).
- Entender qué devuelve
tools/listpara diferentes niveles de rol.
Parámetros / campos / entradas
Cómo se crean los usuarios:
- Primer inicio de sesión OAuth: el documento de usuario se crea automáticamente.
- Añadido a un proyecto por correo electrónico: si no existe un usuario de Firebase Auth para ese correo, se crea uno.
Cómo se crean los proyectos: la herramienta MCP create-project es la única forma. El creador se añade automáticamente como manager.
Cómo se añaden miembros: POST /api/projects/:projectId/members (requiere manager). Acepta email, role (manager, editor o viewer) y un display_name opcional.
Ejemplo
Un usuario con el rol manager llama a publish: tiene éxito. Un usuario con el rol editor llama a publish: devuelve 403 Forbidden.
Un usuario sin pertenencia al proyecto llama a list-my-projects: devuelve una lista vacía. create-project: tiene éxito (cualquier usuario registrado puede crear un proyecto). get-project-state para un proyecto específico: devuelve 403 (no es miembro).
Errores comunes
403 en publish o delete-page: el usuario tiene el rol editor o viewer, no manager. Actualice el rol del miembro a manager mediante PATCH /api/projects/:projectId/members/:uid.
403 en get-project-state: el usuario no es miembro del proyecto. Añádalo mediante POST /api/projects/:projectId/members.
403 en herramientas CRUD de plantillas: requieren acceso de Administrador de plataforma, no solo de gestor de proyecto. Contacte con el equipo de ComStack.
Relacionado
- Autenticación — cómo se comprueban los roles en el middleware.
- Servidor MCP — filtrado de
tools/listy la matriz de capacidades en contexto. - Planes y cuotas — la aplicación de cuotas funciona junto con las comprobaciones de roles.