Saltar a contenido

0053. Escrituras de los catálogos globales exclusivas de root

Estado: Aceptado Fecha: 2026-10-26 Autor: David Garcia Módulo(s) afectado(s): app/domains/catalogos/, app/main.py, docs/adr/

Contexto

Durante la revisión del ADR 0052 se constató que las escrituras de los catálogos globales (países, tipos de identificación, géneros, monedas, provincias y ciudades) no exigían el token administrativo root: aceptaban un token normal válido con get_current_user. La frase del ADR 0048 «las escrituras de catálogos [...] permanecen protegidos por la autenticación normal» se implementó literalmente, pero ese nivel es insuficiente: cualquier usuario de cualquier empresa de la plataforma podía crear, modificar o borrar lógicamente datos de referencia globales que consumen todos los servicios, por ejemplo códigos de países o de tipos de identificación validados por otros microservicios.

La superficie administrativa tiene un principio opuesto: la edición del universo global es solo de root, como en el CRUD de empresas.

Decisión

  • Las escrituras de los catálogos globales (POST/PUT/DELETE de países, tipos de identificación, géneros, monedas, provincias y ciudades) exigen el token administrativo root mediante UsuarioAdminAutenticado (get_admin_user, ADR 0048): 403 «Acceso no autorizado» ante un token normal y 401 sin token o inválido. Revierte al criterio root-only y corrige la apertura que la lectura literal del ADR 0048 permitió: este ADR sustituye esa frase del 0048 en el punto específico de las escrituras de catálogos.
  • Sesión pelada para las escrituras globales: los endpoints viven en un sub-router propio fuera de la superficie protegida por el token normal (el router_protegido de app/main.py exige get_current_user, incompatible con el token administrativo, que no trae empresa_id). El service se arma con get_db, sin contexto de RLS: son catálogos globales sin alcance tenant, igual que el CRUD de empresas.
  • En la matriz y en el código queda marcado el 0052: el listado de las listas maestras sigue abierto a cualquier usuario autenticado (0052) y este ADR no modifica ninguna lectura.
  • Feriados y bancos no cambian: son catálogos por empresa (ámbito tenant). Siguen con autenticación normal y sesión de RLS, como ya decía el ADR 0048 para los endpoints de catálogos con ámbito tenant. Con un token administrativo responden 401, porque el router_protegido exige el token normal.

Códigos de respuesta

Petición Token normal Token admin/root Sin token o inválido
GET listado de catálogos globales (incluye existe/{id}) 200 200 401
GET /catalogos/{recurso}/{id} (detalle) 200 401 401
POST/PUT/DELETE de países, tipos de identificación, géneros, monedas, provincias y ciudades 403 201/200/204 401
POST/PUT/DELETE de feriados y bancos (por empresa) igual que antes 401 401

La fila del detalle no varía respecto del estado previo: vivía (y vive) bajo la superficie normal, y el token administrativo no la atraviesa.

Alternativas descartadas

  • Dejar las escrituras con autenticación normal — es el estado hallado. Da edición global de datos de referencia a cualquier usuario autenticado y contradice el principio de la superficie administrativa (0048).
  • Cambiar la dependencia del router_protegido — protegería las escrituras, pero rompería los demás dominios (navegación, sucursales, usuarios) que requieren explícitamente el token normal.
  • Abrir también el detalle por id al token administrativo — unificar la superficie de lectura de la ficha completa es otra decisión (la de sucursales del 0052 fue dejada abierta); acá el detalle no cambia.

Consecuencias

  • Código: los 18 endpoints de escritura global se reagrupan en catalogos_escritura_router y app/main.py los monta fuera de la superficie normal. Las firmas agregan UsuarioAdminAutenticado y el service pasa a get_db. Sin cambios de contrato: códigos 409 y 404 de negocio se conservan.
  • El token normal queda en solo lectura para los seis catálogos: afecta a cualquier integración que hoy escriba catálogos con token normal.
  • Pruebas unitarias (service falso y tokens JWT reales): listado con token normal 200 y sin token 401; POST/PUT/DELETE con token normal 403 «Acceso no autorizado»; con token administrativo, la escritura responde 201; el POST de feriados con token normal sigue 201.
  • Los otros servicios mantienen su lectura autenticada (0052): nada cambia para quien consume las listas; solo para quien las edita.