File size: 7,035 Bytes
4bd44c0 | 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 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 | # Integración M6 ↔ Core API (M1)
**Host:** `https://api.healthcare.cantero.ar`
**Spec:** `documentation/M1_openapi.yaml`
**Estado:** plan aprobado, pendiente de implementación
---
## Contexto
El Core API centraliza autenticación, usuarios, roles, permisos y un event bus para todo el sistema Health Grid. M6 hoy tiene su propio sistema de auth (JWT HS256 con secreto compartido, tokens generados localmente). La integración reemplaza ese sistema por el del Core API.
---
## Hallazgos clave (previos a implementar)
### Estructura del JWT del Core API
Decodificado de un token real de usuario registrado:
```json
{
"user_id": 20,
"permissions": [],
"exp": 1782858312,
"iat": 1782771912
}
```
**Diferencias críticas respecto al JWT actual de M6:**
| Campo | JWT M6 actual | JWT Core API |
|---|---|---|
| ID de usuario | `sub` (string) | `user_id` (integer) |
| Rol | `rol` (string: "MEDICO") | No existe |
| Permisos | No existe | `permissions` (array de strings) |
| Algoritmo | HS256 (secreto compartido) | RS256 (clave pública via JWKS) |
El Core API **no incluye nombres de rol en el JWT** — embebe permisos directamente. Esto impacta cómo M6 verifica acceso (ver Fase B).
### JWKS — verificación sin llamadas a M1
El Core API expone `GET /.well-known/jwks.json` con la clave pública RSA. M6 la descarga una vez, la cachea, y verifica la firma de cada token localmente sin llamar al Core API en cada request. El Core API firma con la clave privada; cualquier módulo verifica con la clave pública.
---
## Qué cambia en M6
### 1. `app/config.py`
- Eliminar: `jwt_secret`, `jwt_algorithm`, `jwt_expire_minutes`
- Agregar: `m1_core_url` con default `https://api.healthcare.cantero.ar`
- El secreto compartido desaparece — la verificación pasa a ser criptográfica
### 2. `app/dependencies.py` — `decode_token`
- Hoy: `jwt.decode(token, settings.jwt_secret, algorithms=["HS256"])`
- Después: descarga JWKS desde `{m1_core_url}/.well-known/jwks.json`, verifica con RS256, extrae `user_id` y `permissions`
- El JWKS se cachea en memoria con TTL (sugerido: 1 hora) para no hacer HTTP en cada request
### 3. `app/dependencies.py` — `require_roles` → `require_permissions`
El guard de acceso cambia de chequear un string de rol a chequear si el token contiene un permiso específico.
Hoy:
```python
require_roles("MEDICO", "ADMINISTRATIVO")
# verifica payload["rol"] in ("MEDICO", "ADMINISTRATIVO")
```
Después (dos opciones — ver decisión pendiente):
**Opción A — mapeo permiso → rol interno (mínimo impacto):**
```python
# M6 mantiene su concepto de rol internamente
# y deriva el rol desde los permisos del JWT
_PERMISOS_POR_ROL = {
"MEDICO": {"camas:read", "solicitudes:read", ...},
"ADMINISTRATIVO": {"camas:write", "solicitudes:manage", ...},
"LIMPIEZA": {"camas:limpieza", ...},
}
```
**Opción B — guards nativos de permiso (más correcto a largo plazo):**
```python
require_permissions("camas:read")
# verifica que "camas:read" esté en payload["permissions"]
```
La Opción B requiere cambiar todos los guards en todos los routers. La Opción A es un shim que deja los routers intactos.
**Decisión pendiente** (ver sección de incógnitas).
### 4. `app/main.py` — eliminar endpoint de dev token
`GET /api/v1/auth/token` genera tokens HS256 propios — ya no serán válidos cuando M6 valide con JWKS.
Reemplazar con credenciales reales del Core API en `.env` local y secretos de HF Spaces.
### 5. `app/integrations/core.py`
Actualmente vacío o stub. Agregar cliente HTTP para llamadas al Core API:
- `GET /users/{id}` — obtener datos de usuario (nombre, roles) cuando sea necesario
- `POST /auth/refresh` — renovar token si M6 necesita actuar en nombre de un usuario
---
## Plan de implementación por fases
### Fase A — Verificación de firma RS256 (independiente de permisos)
Se puede implementar ahora, sin conocer los nombres de permisos.
1. Agregar `PyJWT[crypto]` o `python-jose[cryptography]` a `requirements.txt` (verificar cuál ya está)
2. Implementar caché de JWKS en `app/dependencies.py` (dict en módulo con timestamp)
3. Cambiar `decode_token` para usar RS256 + JWKS
4. Cambiar extracción de `sub` → `user_id`
5. Eliminar `jwt_secret` de `config.py`; agregar `m1_core_url`
6. Eliminar endpoint dev token de `main.py`
7. Agregar `M1_CORE_URL` a `.env` y a los secretos de HF Spaces
8. Actualizar tests: reemplazar tokens HS256 propios por tokens mockeados con la estructura correcta del Core API
### Fase B — Mapeo de permisos (bloqueada hasta resolver incógnita #1)
9. Definir tabla de mapeo permiso → rol M6 (o migrar a guards de permiso nativos)
10. Actualizar `require_roles` / crear `require_permissions`
11. Actualizar tests de autorización
### Fase C — Event bus (opcional, posterior)
El Core API tiene un bus de eventos con suscripciones. M6 podría:
- **Publicar** eventos al bus cuando ocurren internaciones, altas, traslados (`POST /events/log`)
- **Suscribirse** a eventos de otros módulos (`POST /events/subscriptions`)
Requiere que M6 tenga un usuario de sistema con permiso `events:log:publish` configurado en el Core API.
No es necesario para la integración de auth — se puede hacer en una etapa posterior.
---
## Incógnitas bloqueantes
### #1 — Nombres de permisos para cada rol (bloqueante para Fase B)
Necesitamos saber qué permisos tiene asignados cada rol del sistema. Con un usuario sin rol asignado, `permissions: []`. Opciones para resolverlo:
- **Opción preferida:** El equipo del Core API asigna el rol MEDICO, ADMINISTRATIVO o LIMPIEZA al usuario ID 20 (`sorondojp@gmail.com`), se obtiene un token nuevo y se decodifica para ver los permisos reales.
- **Alternativa:** El equipo del Core API comparte la lista de permisos por rol directamente.
La pregunta concreta a hacerles:
> ¿Qué permisos (`permission.name`) tienen asignados los roles que corresponden a médico, administrativo y personal de limpieza en el sistema?
### #2 — Nombres exactos de roles en el Core API
Los roles de M6 son `MEDICO`, `ADMINISTRATIVO`, `LIMPIEZA`. ¿El Core API usa esos mismos strings o nombres distintos (ej: `doctor`, `admin`, `cleaning`)? Esto define si hace falta una tabla de traducción.
---
## Variables de entorno afectadas
| Variable actual | Acción | Nueva variable |
|---|---|---|
| `JWT_SECRET` | Eliminar | — |
| `JWT_ALGORITHM` | Eliminar | — |
| `JWT_EXPIRE_MINUTES` | Eliminar | — |
| — | Agregar | `M1_CORE_URL=https://api.healthcare.cantero.ar` |
En HF Spaces: agregar `M1_CORE_URL` como secreto, eliminar las tres variables de JWT.
---
## Estado actual
- [x] Spec analizado (`M1_openapi.yaml`)
- [x] JWT real decodificado — estructura conocida (`user_id`, `permissions[]`)
- [x] JWKS endpoint identificado (`/.well-known/jwks.json`)
- [ ] Nombres de permisos por rol — **pendiente** (incógnita #1)
- [ ] Fase A implementada
- [ ] Fase B implementada
- [ ] Credenciales de Core API configuradas en HF Spaces
|