File size: 11,201 Bytes
d53b1d7
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e6a43c8
d53b1d7
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3bc4d13
 
 
 
56cbf83
3bc4d13
 
 
 
 
 
d53b1d7
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
624c7c9
d53b1d7
 
 
624c7c9
d53b1d7
01e0bb5
e6a43c8
01e0bb5
624c7c9
 
 
e6a43c8
 
 
624c7c9
e6a43c8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
# 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.