Modulo-6 / documentation /roles.md
juampisor's picture
Get paciente
56cbf83
|
Raw History Blame Contribute Delete
11.2 kB

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, en M6_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 compara payload["rol"] contra una lista fija por endpoint. No hay un sistema de permisos (camas:read, camas:write, etc.) — el Core (M10) no expone hoy permissions:manage a 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ón EN_LIMPIEZA → DISPONIBLE. Cualquier otra transición devuelve 403 NO_AUTORIZADO.
  • No puede tocar contraindicaciones_incompatibles bajo ningún escenario — incluso si no manda estado en el mismo request. Devuelve 403 NO_AUTORIZADO.

Antes de la reforma de roles (2026-06), GET /camas filtraba para LIMPIEZA solo las camas en EN_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}/reservas aceptaba 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 de M6_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. Lee payload["rol"] del JWT decodificado y devuelve 403 NO_AUTORIZADO si no matchea.
  • Routers (app/routers/camas.py, quirofanos.py, solicitudes.py, auditoria.py) — declaran los roles permitidos por endpoint con Depends(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.AuthResponse del Core) debería traer user.roles[] — cada rol con su name — 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_exchange cae a core_auth.resolve_user_roles(user_id), que arma un índice user_id → roles desde GET /roles (autenticado con la cuenta de servicio de M6 — es lo único que esa cuenta puede leer; GET /users/{id} exige users:read, que no tiene).
  • Mapeo Core → M6 (CORE_ROLE_TO_INTERNAL en core_auth.py::map_core_roles_to_internal): roles de Core admin_internacion → ADMINISTRATIVO, Medico → MEDICO, limpieza → LIMPIEZA, admin → ADMINISTRATIVO. Si ninguno de los roles del usuario mapea, el canje devuelve 403 (no entra a M6).
  • require_roles, la capa de servicio y la auditoría no cambiaron — siguen leyendo payload["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 del redirect son responsabilidad del frontend, no de este backend.

Fuera de alcance / pendiente

  • Permisos granulares vía Core. El Core no expone permissions:manage a la cuenta de servicio de M6 hoy, y no tiene permisos de dominio M6 (camas:read, etc.) en su catálogo. Migrar require_roles a 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.