Saltar a contenido

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 null cuando 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_id y permisos.
  • La resolución vive en un solo lugar: el helper de módulo _nombre_mostrado(empresa) en app/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 con existe_empresa y listar_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_acceso sigue armando el resto de los claims y no carga la resolución async.
  • Naming: empresa_nombre es snake_case y simétrico con el empresa_id que ya viaja, coherente con la convención de claims del ADR 0040. No cambia los claims fijos de plataforma (iss, aud); firmar_token ya mergea los claims del llamador con los fijos y no se toca app/core/security.py.
  • El pre-token no cambia: es un vale temporal de scope=pre-auth y no lleva datos de empresa ni de usuario (ADR 0031). El claim va sólo en el access.

Alternativas descartadas

  • Campo empresa_nombre en el cuerpo de TokenResponse — 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_comercial y razon_social como 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/refresh desde 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 null y la sesión sigue viva: no se inventa una cadena vacía ni se corta la sesión. En particular, /auth/refresh mantiene 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 con empresa_nombre nulo 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).