Roles y control de acceso

El modelo de autorización de Pier tiene dos ámbitos. Cada usuario tiene un rol global, y además puede tener un rol de proyecto en cada proyecto del que sea miembro. La mayoría de los endpoints comprueban uno u otro; unos pocos de gran impacto están reservados para el Owner.

Roles globales

Un rol global se almacena en el registro del usuario y acompaña a cada solicitud autenticada. Hay tres, ordenados de mayor a menor privilegio.

Rol	Qué puede hacer
Owner	Todo lo que puede hacer Admin, además de los controles exclusivos del Owner: cambiar los roles globales de otros usuarios, eliminar/promover Admins, las concesiones de federación y la malla WireGuard. El primer usuario creado en la configuración es el Owner. Siempre se requiere al menos un Owner activo.
Admin	Gestionar usuarios (invitar, editar, eliminar a quienes no sean Owner), gestionar servidores, ver las métricas del sistema y el registro de auditoría, crear proyectos y operar recursos a nivel de Docker (contenedores, imágenes, stacks de compose, redes, registros). Omite la pertenencia a proyectos — un Admin llega a todos los proyectos.
User	Un miembro normal. Solo ve los proyectos de los que es miembro explícito, además de los endpoints globales de solo lectura (lista de servidores, métricas del sistema). No puede crear proyectos ni gestionar usuarios.

Los roles globales Owner y Admin omiten las comprobaciones de pertenencia a proyectos — se tratan como Admin de proyecto en cada proyecto.

Roles de proyecto

Un rol de proyecto se concede mediante la pertenencia al proyecto (la tabla project_members) y limita el alcance de un User a un único proyecto sin otorgarle poder global. Hay tres.

Rol	Qué puede hacer dentro del proyecto
Admin	Todo lo que puede hacer Editor, además de gestionar la pertenencia al proyecto (añadir/eliminar miembros, cambiar sus roles).
Editor	Desplegar y volver a desplegar servicios, cambiar variables de entorno, dominios y ajustes, reiniciar.
Viewer	Solo lectura: configuraciones, registros, métricas e historial de despliegues.

Cada proyecto conserva al menos un Admin de proyecto: Pier se niega a degradar o eliminar al último.

Cómo se controlan los endpoints

Dos mecanismos imponen los roles:

• Guardas globales a nivel de enrutador. Grupos enteros de rutas se sitúan detrás de una capa de middleware. require_global_admin controla la gestión de usuarios, las operaciones del demonio de Docker, los stacks de compose, los registros, el registro de auditoría y las mutaciones de servidores. require_global_owner controla los cambios de rol global (PUT /users/{id}/role), la malla y las concesiones de federación.
• Comprobaciones de proyecto dentro del handler. Las rutas con ámbito de proyecto (recursos, despliegues, env, copias de seguridad) llaman a enforce_project_role / enforce_resource_role al principio del handler, resolviendo el recurso hasta su proyecto y exigiendo un rol de proyecto mínimo.

Un mapa conciso de las acciones comunes:

Acción	Rol mínimo
Explorar el catálogo / ver los servicios de un proyecto	Viewer (proyecto)
Desplegar o volver a desplegar un servicio, editar env/dominios	Editor (proyecto)
Añadir o eliminar un miembro del proyecto	Admin (proyecto)
Crear un proyecto nuevo	Admin (global)
Invitar o eliminar usuarios, ver el registro de auditoría	Admin (global)
Promover a un usuario a Admin, o cambiar cualquier rol global	Owner (global)
Gestionar las concesiones de federación o la malla WireGuard	Owner (global)

Próximos pasos

• Tokens de API y despliegue desde CI
• Autenticación de dos factores
• Visión general de seguridad