# 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