Spaces:
Runtime error
Download documentation/roles.md from MateFerreyra/Modulo-6: direct link, hf CLI and curl.
- Browser
- Download file 11.2 kB
-
https://huggingface.co/spaces/MateFerreyra/Modulo-6/resolve/main/documentation/roles.md
- Command line
-
hf download hf://spaces/MateFerreyra/Modulo-6/documentation/roles.md
-
curl -L -o roles.md https://huggingface.co/spaces/MateFerreyra/Modulo-6/resolve/main/documentation/roles.md
Roles y permisos — Módulo 6
Health Grid · Internación y Gestión de Camas
Fuente de verdad de qué puede hacer cada rol en M6. La forma exacta de cada endpoint está en
M6_openapi.json; las reglas de negocio y máquinas de estado, enM6_DISEÑO.md. Este documento es la matriz de autorización.
1. Roles del sistema
M6 reconoce tres roles, transportados en el JWT (payload["rol"]) y validados en cada endpoint con require_roles(...) (app/dependencies.py):
| Rol | Perfil | Alcance general |
|---|---|---|
ADMINISTRATIVO |
Gestión operativa de camas, quirófanos y solicitudes | Acceso total — lectura y escritura sobre todo el dominio de M6 |
MEDICO |
Personal médico | Estrictamente de solo lectura sobre todo el dominio de M6, salvo crear reservas de quirófano (caso intencional, ver §3) |
LIMPIEZA |
Personal de limpieza/mantenimiento de camas | Lee todas las camas; la única escritura permitida es finalizar la limpieza de una cama propia (EN_LIMPIEZA → DISPONIBLE) |
No hay rol SISTEMA autenticado por JWT: los eventos disparados por webhooks entrantes (M1 HCE, M9 Monitoreo, M2 Turnos) no llevan actor humano y se registran en la auditoría con rol = SISTEMA, origen = WEBHOOK (ver docs/superpowers/specs/2026-06-26-auditoria-cama-design.md).
2. Principios de diseño
- MEDICO es de solo lectura. Ningún endpoint de escritura (
POST/PATCH/DELETE) sobre camas, quirófanos o solicitudes acepta el rol MEDICO. La única excepción intencional es crear reservas de cirugía — ver §3. - ADMINISTRATIVO tiene control total. Es el único rol que puede dar de alta/baja camas y quirófanos, asignar pacientes, resolver solicitudes y modificar reservas.
- LIMPIEZA está acotado al mínimo necesario. Ve el mapa completo de camas (para saber dónde está parado y planificar), pero solo puede ejecutar una transición de estado muy específica. La restricción se aplica a nivel de servicio (
app/services/cama_service.py), no solo en el frontend — un request directo a la API con un JWT de LIMPIEZA que intente otra cosa es rechazado igual. - La autorización es por rol, no por permisos granulares.
require_roles(*roles)es un dependency de FastAPI que comparapayload["rol"]contra una lista fija por endpoint. No hay un sistema de permisos (camas:read,camas:write, etc.) — el Core (M10) no expone hoypermissions:managea la cuenta de servicio de M6 para darlos de alta. La integración con el Core ya está ejecutada (ver §6): lo que queda pendiente es específicamente migrar de rol a permisos granulares.
3. Matriz de permisos por endpoint
✓ permitido · ✗ prohibido (403) · ✓* permitido con restricción adicional aplicada en la capa de servicio
Camas
| Endpoint | ADMINISTRATIVO | MEDICO | LIMPIEZA |
|---|---|---|---|
GET /camas — mapa completo |
✓ | ✓ | ✓ |
POST /camas — alta de cama |
✓ | ✗ | ✗ |
GET /camas/{camaId} — detalle |
✓ | ✓ | ✓ |
PATCH /camas/{camaId} — cambiar estado / contraindicaciones |
✓ | ✗ | ✓* |
DELETE /camas/{camaId} — baja permanente |
✓ | ✗ | ✗ |
POST /camas/{camaId}/asignar — asignar/trasladar paciente |
✓ | ✗ | ✗ |
✓* en PATCH /camas/{camaId} para LIMPIEZA — restricción aplicada en cama_service.update_cama:
- Solo puede cambiar
estado, y únicamente la transiciónEN_LIMPIEZA → DISPONIBLE. Cualquier otra transición devuelve403 NO_AUTORIZADO. - No puede tocar
contraindicaciones_incompatiblesbajo ningún escenario — incluso si no mandaestadoen el mismo request. Devuelve403 NO_AUTORIZADO.
Antes de la reforma de roles (2026-06),
GET /camasfiltraba para LIMPIEZA solo las camas enEN_LIMPIEZA. Ahora ve el mapa completo; lo que cambió es exclusivamente el alcance de escritura.
Quirófanos
| Endpoint | ADMINISTRATIVO | MEDICO | LIMPIEZA |
|---|---|---|---|
GET /quirofanos/disponibilidad |
✓ | ✓ | ✗ |
GET /quirofanos — listado |
✓ | ✓ | ✗ |
POST /quirofanos — alta |
✓ | ✗ | ✗ |
GET /quirofanos/{quirofanoId} — detalle |
✓ | ✓ | ✗ |
PATCH /quirofanos/{quirofanoId} — actualizar |
✓ | ✗ | ✗ |
GET /quirofanos/{quirofanoId}/reservas — listar reservas |
✓ | ✓ | ✗ |
POST /quirofanos/{quirofanoId}/reservas — crear reserva |
✓ | ✗ | ✗ |
GET /quirofanos/{quirofanoId}/reservas/{reservaId} — detalle reserva |
✓ | ✓ | ✗ |
PATCH /quirofanos/{quirofanoId}/reservas/{reservaId} — cambiar estado reserva |
✓ | ✗ | ✗ |
LIMPIEZA no tiene ningún acceso a quirófanos — no es parte de su responsabilidad operativa.
Corrección 2026-06:
POST /quirofanos/{quirofanoId}/reservasaceptaba MEDICO. Era la única escritura que tenía ese rol en todo M6, inconsistente con el principio de "MEDICO solo lectura". Se removió — ver changelog §14.3 deM6_DISEÑO.md.
Solicitudes
| Endpoint | ADMINISTRATIVO | MEDICO | LIMPIEZA |
|---|---|---|---|
GET /solicitudes — listado |
✓ | ✓ | ✗ |
GET /solicitudes/{solicitudId} — detalle |
✓ | ✓ | ✗ |
PATCH /solicitudes/{solicitudId} — aprobar/rechazar |
✓ | ✗ | ✗ |
Solo ADMINISTRATIVO resuelve solicitudes de internación/traslado, incluso si fue un médico quien las originó desde HCE (M1) — la decisión de qué cama concreta se asigna es administrativa, no clínica (ver M6_DISEÑO.md §1).
Auditoría
| Endpoint | ADMINISTRATIVO | MEDICO | LIMPIEZA |
|---|---|---|---|
GET /auditoria — historial de eventos |
✓ | ✓ | ✗ |
LIMPIEZA no tiene acceso al historial de auditoría — no necesita visibilidad sobre el log completo de movimientos clínicos/administrativos para hacer su trabajo.
Pacientes (consulta a M1 HCE)
| Endpoint | ADMINISTRATIVO | MEDICO | LIMPIEZA |
|---|---|---|---|
GET /pacientes/{pacienteId} — datos básicos |
✓ | ✓ | ✓ |
GET /pacientes/{pacienteId}/ficha-medica |
✓ | ✓ | ✓ |
GET /pacientes/{pacienteId}/antecedentes |
✓ | ✓ | ✓ |
Proxies de solo lectura hacia M1 (HCE), para la página de detalle de cama del front —
mismo criterio que GET /camas (mapa completo visible para los 3 roles).
Webhooks entrantes
Los endpoints bajo /webhooks/* (recepción de eventos de M1 HCE, M9 Monitoreo, M2 Turnos) no usan require_roles — no hay un usuario humano autenticado por JWT en esas llamadas. La autenticación de webhooks entrantes es un punto pendiente de definir con el Bus de Eventos de Core (ver M6_DISEÑO.md §13).
4. Implementación
app/dependencies.py—require_roles(*roles)es el dependency de FastAPI que se usa en cada router. Leepayload["rol"]del JWT decodificado y devuelve403 NO_AUTORIZADOsi no matchea.- Routers (
app/routers/camas.py,quirofanos.py,solicitudes.py,auditoria.py) — declaran los roles permitidos por endpoint conDepends(require_roles(...)). Esta es la primera línea de defensa; cubre la mayoría de los casos porque la mayoría de las restricciones son "todo o nada" por endpoint. - Capa de servicio (
app/services/cama_service.py::update_cama) — segunda línea de defensa para LIMPIEZA, porque su restricción no es "todo o nada" sobre el endpoint:PATCH /camas/{camaId}está permitido para LIMPIEZA, pero con una regla fina sobre qué puede cambiar y bajo qué condición de estado previo. Esa lógica no se puede expresar en el dependency de FastAPI — vive donde está el contexto de negocio completo (estado actual de la cama, qué campos vinieron en el body).
Regla general para agregar una restricción nueva: si es "este rol no puede llamar a este endpoint en absoluto", va en el router con require_roles. Si es "este rol puede llamar al endpoint pero con una condición sobre el contenido del request o el estado del recurso", va en el servicio — nunca confiar solo en que el frontend oculte el botón.
5. Testing
Los tests de autorización por rol viven junto a los tests de cada router (tests/test_camas.py, tests/test_quirofanos.py, tests/test_solicitudes.py, tests/test_auditoria.py), usando los fixtures admin_headers, medico_headers, limpieza_headers de tests/conftest.py. El mapeo de rol de Core → M6 tiene su propia suite en tests/test_core_auth.py; el flujo completo de canje SSO, en tests/test_sso.py. Cada endpoint restringido tiene al menos un test que verifica 403 para el/los rol(es) sin permiso, y un test de happy path para el rol permitido.
6. Integración con el Core (M10): SSO
La sesión de M6 es siempre un JWT HS256 propio (app/dependencies.py::create_access_token/decode_token). Lo que agrega la integración con el Core es una forma de adquirirlo: POST /api/v1/auth/sso-exchange (app/routers/auth.py, activo con SSO_ENABLED=true) canjea un ticket de un solo uso emitido por el Core (POST /auth/sso-ticket en el Core) contra POST /auth/sso-exchange del Core, y devuelve un JWT de M6 con el rol ya resuelto. No hay verificación de JWT del Core por-request — el Core se toca en el canje y, si hace falta, en el fallback de roles. Detalle técnico completo en M6_DISEÑO.md §11; resumen:
- La respuesta del canje (
models.AuthResponsedel Core) debería traeruser.roles[]— cada rol con suname— y de ahí sale el rol del usuario. En la práctica el Core desplegado no siempre lo puebla; cuando viene vacío,app/routers/auth.py::sso_exchangecae acore_auth.resolve_user_roles(user_id), que arma un índiceuser_id → rolesdesdeGET /roles(autenticado con la cuenta de servicio de M6 — es lo único que esa cuenta puede leer;GET /users/{id}exigeusers:read, que no tiene). - Mapeo Core → M6 (
CORE_ROLE_TO_INTERNALencore_auth.py::map_core_roles_to_internal): roles de Coreadmin_internacion→ADMINISTRATIVO,Medico→MEDICO,limpieza→LIMPIEZA,admin→ADMINISTRATIVO. Si ninguno de los roles del usuario mapea, el canje devuelve403(no entra a M6). require_roles, la capa de servicio y la auditoría no cambiaron — siguen leyendopayload["rol"]del JWT de M6, sin distinguir si la sesión se originó por SSO o por el endpoint de desarrollo (/api/v1/auth/token).- El callback del browser (
/auth/sso?ticket=…&redirect=…) y la validación anti-open-redirect delredirectson responsabilidad del frontend, no de este backend.
Fuera de alcance / pendiente
- Permisos granulares vía Core. El Core no expone
permissions:managea la cuenta de servicio de M6 hoy, y no tiene permisos de dominio M6 (camas:read, etc.) en su catálogo. Migrarrequire_rolesa un modelo de permisos queda pendiente de esa habilitación. - Autenticación de webhooks entrantes. Hoy no hay verificación de origen en
/webhooks/*más allá de lo que ya documente cada integración puntual — siguen exigiendo un JWT de usuario, que los emisores reales (M1/M9/M2) no tienen. Pendiente acordar mecanismo (secreto compartido o firma) con el Bus de Eventos de Core.