0045. Nombre de la empresa activa como claim del access token¶
Estado: Aceptado Fecha: 2026-10-16 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/usuarios/, tests/unit/auth/, docs/adr/
Contexto¶
La empresa activa de una sesión vive en el claim empresa_id del access
token (ADR 0030). El token lleva el id, no el nombre. Por eso el frontend,
para mostrar la empresa activa en pantalla, tenía que pedirla aparte: un
round-trip HTTP extra en cada carga de página (o en cada refresco), sólo para
traducir un empresa_id a un texto.
El nombre ya está disponible en el servicio en el momento de emitir los tokens. La emisión ocurre en tres endpoints que comparten camino:
POST /auth/login/empresa(elegir empresa, ADR 0018/0030).POST /auth/refresh(rotación, ADR 0030).POST /auth/cambiar-empresa(ADR 0042).
La columna a mostrar en mae_empresas no es una sola: razon_social es
NOT NULL y nombre_comercial es nullable. El usuario reconoce su empresa
por el nombre comercial cuando lo hay.
El cliente ya decodifica el access token: lee de ahí empresa_id, username
y permisos. El nombre es un dato más del mismo carnet.
Decisión¶
El access token suma el claim empresa_nombre, con valor
nombre_comercial.strip() or razon_social.strip(), resuelto en la emisión.
Además:
- El claim siempre está presente en el payload: con el nombre resuelto
cuando la empresa existe, y con
nullcuando no existe o está borrada lógicamente. No se omite condicionalmente: el frontend no debe distinguir «claim ausente» de «empresa sin nombre». - El nombre es un dato de presentación, no autoritativo: sirve para
mostrar, no para decidir accesos. La autorización sigue leyendo
empresa_idypermisos. - La resolución vive en un solo lugar: el helper de módulo
_nombre_mostrado(empresa)enapp/domains/usuarios/service.py. El SQL vive en el repository:UsuariosRepository.obtener_empresa(empresa_id)es un SELECT por clave primaria que excluye el borrado lógico (coherente conexiste_empresaylistar_empresas_activas); el service recibe el objeto ORM (ADR 0001 transversal). El nombre comercial se recorta antes de resolver el fallback (nombre_comercial.strip()): la columna sólo limita el largo, no garantiza que venga sin espacios, y un valor con sólo espacios debe caer a la razón social en vez de mostrarse vacío en el header. - El claim se inyecta en
_emitir_tokens, el único punto por el que pasan los tres endpoints que emiten tokens._claims_accesosigue armando el resto de los claims y no carga la resolución async. - Naming:
empresa_nombreessnake_casey simétrico con elempresa_idque ya viaja, coherente con la convención de claims del ADR 0040. No cambia los claims fijos de plataforma (iss,aud);firmar_tokenya mergea los claims del llamador con los fijos y no se tocaapp/core/security.py. - El pre-token no cambia: es un vale temporal de
scope=pre-authy no lleva datos de empresa ni de usuario (ADR 0031). El claim va sólo en el access.
Alternativas descartadas¶
- Campo
empresa_nombreen el cuerpo deTokenResponse— obliga a un contrato nuevo en la respuesta para información que el cliente igual decodifica del access token. Con el claim, el frontend lo lee del token que ya tiene en la mano y no pide ni negocia nada extra. - Exponer
nombre_comercialyrazon_socialcomo dos campos separados — cada consumidor repetiría la regla «comercial si existe, si no razón social», y cada frontend podría elegir un criterio distinto. Un campo ya resuelto hace una sola cosa y no se puede interpretar de dos maneras. - Que el frontend siga consultando la empresa aparte — es exactamente el round-trip extra que este ADR elimina; el dato ya está al alcance al emitir.
- Reservar el nombre en
/auth/refreshdesde el token viejo — el nombre no está en el token anterior; habría que consultarlo igual, y peor: sin poder reflejar un cambio de nombre posterior.
Consecuencias¶
- Tradeoff de frescura: el nombre queda congelado en el token hasta el próximo refresh. Renombrar la empresa no se refleja hasta que el access rote; la cota es el TTL del access token (15 minutos). Es aceptable porque el nombre es material de presentación, no un dato autoritativo.
- La emisión hace un SELECT extra por clave primaria a
mae_empresas. Es el costo explícito de la decisión: se cambia un round-trip HTTP del frontend por una lectura indexada en el backend, en los tres endpoints que emiten tokens. - Si la empresa no existe o está borrada lógicamente, el claim vale
nully la sesión sigue viva: no se inventa una cadena vacía ni se corta la sesión. En particular,/auth/refreshmantiene su comportamiento actual cuando la empresa desapareció (el refresh se rota y el access se reemite igual). get_current_user(ADR 0031) no valida este claim: no es parte de la identidad y un access conempresa_nombrenulo o ausente sigue siendo aceptado por el verificador.
Qué no cubre¶
- Mostrar más datos de la empresa (logo, zona horaria): esto es sólo el nombre que se muestra.
- Elegir empresa al iniciar sesión: sigue siendo el login en dos pasos (ADR 0018).
- Refrescar el nombre sin rotar el token: exigiría validar el nombre contra la base en cada request, lo que rompe el diseño stateless (ADR 0031).