Dominio autenticación (backend)¶

Cuentas de usuario de LogiGho: verificación de identidad, permisos, alta de usuarios, registro por autoservicio, recuperación y cambio de contraseña con código al correo, y asignación de acceso por Comercial. Contrato HTTP: API de autenticación.

Dónde vive¶

Todo en Lambdas_NET_LogiGho/LambdasLogiGho.Aplicacion/AWS/Autenticacion/, en .NET 10 salvo lo indicado:

La librería de verificación de JWT está en LambdasLogiGho.Infraestructura/SeguridadJwt (net10.0).

Arquitectura¶

Cada lambda es delgada: traduce HTTP al caso de uso y el resultado a HTTP. La regla vive en el núcleo y se prueba sin infraestructura.

flowchart LR
  A[API Gateway] --> B[Manejador HTTP]
  B --> C[Caso de uso en Nucleo]
  C --> D[IVerificadorIdentidad
SeguridadJwt]
  C --> E[Puertos
actores, cuentas, usuarios]
  E --> F[(Mongo: Users)]
  E --> G[Cognito]

Reglas de diseño que se mantienen en cada lambda nueva o modificada:

• La identidad sale del header Token verificado (firma, emisor, token_use, vigencia, client_id).
• El rol sale de Users por cognitoId; nunca del token ni del body.
• Los permisos vienen de variables de entorno y fallan cerrados.
• Errores sin mensaje interno; logs con [INFO]/[WARN]/[ERROR], resultado y tipo de excepción, sin correos, teléfonos, contraseñas, tokens ni cuerpos.
• Sin secretos en el repositorio ni en aws-lambda-tools-defaults.json.

Por qué hay una sola lambda nueva¶

Regla de Iker (2026-11-02): no llenar el repositorio de lambdas que luego hay que monitorear. Antes de crear una se revisan todas las existentes y se consulta. Aquí:

• Asignación de acceso vive dentro de ApiLambdaUser: mismo actor (token y rol leído de Users), solo Mongo.
• Cambio de contraseña con código y contraseña actual (obsoleto) vive en ApiLambdaCambioPasswordCognito.
• ApiLambdaRegistro es aparte porque es pública (sin token) y es la única que crea cuentas o cambia contraseñas a partir de un código: mezclarla con una lambda de usuarios con sesión le daría esos permisos a rutas con otra superficie. Por eso la recuperación de contraseña (también pública) se agregó aquí en vez de crear otra lambda (decisión 2026-11-03).
• No hay lambda de aprobación ni de rotación: el usuario nace activo con Red social y la clave del código se rota a mano.

Código de un solo uso (OTP)¶

Un solo motor en Autenticacion.Nucleo, usado por el registro, la recuperación y el cambio de contraseña:

• Código de 6 dígitos con RandomNumberGenerator; identificador de solicitud de 256 bits (solo se guarda su SHA-256).
• En base queda la firma HMAC-SHA256 del código (con el identificador como contexto), nunca el código. La clave sale de Secrets Manager con dos claves (actual y anterior) para rotar sin invalidar códigos vivos; la lambda la guarda 5 minutos en memoria.
• Comparación en tiempo constante. 5 intentos por código; vigencia máxima 15 minutos (el código ignora un valor mayor de OTP_VIGENCIA_MINUTOS); 60 s entre envíos y 3 por hora por correo.
• Cada cambio de estado es una operación atómica de Mongo con su condición en el filtro (dos confirmaciones simultáneas crean un solo usuario).
• Un código de registro no sirve para recuperar una contraseña ni al revés (campo tipo: REGISTRO, CAMBIO_PASSWORD o RECUPERACION), y el de recuperación queda atado a la cuenta (cuentaSub) que lo pidió. El conteo de solicitudes de registro ignora los otros tipos.

Datos¶

Infraestructura (Terraform, environments/preprod/autenticacion)¶

• Rol de ejecución propio por función, con permisos mínimos. ApiLambdaRegistro y cambio-pass pueden enviar con SES solo desde no-reply@logigho.com y leer solo el secreto de claves. Mientras SES esté en sandbox también necesitan permiso sobre la identidad del destinatario (en producción, fuera del sandbox, no hace falta). El rol de ApiLambdaRegistro también puede AdminCreateUser, AdminSetUserPassword, AdminDeleteUser, ListUsers (busca la cuenta por sub) y AdminUserGlobalSignOut (cierra sesiones tras recuperar la contraseña), solo sobre el user pool del entorno.
• Secreto logigho/<entorno>/autenticacion/otp-claves: Terraform crea el contenedor; el valor no está en el estado y se escribe con la CLI.
• Configuration set de SES logigho-autenticacion-<entorno> con métricas de rebote, queja y rechazo.
• Una métrica de CloudWatch por evento de negocio (espacio de nombres LogiGho/Autenticacion): registro.solicitud.recibida, registro.solicitud.limitada, registro.otp.enviado, registro.otp.reenviado, registro.otp.invalido, registro.solicitud.bloqueada, registro.confirmacion.exitosa, registro.compensacion.ejecutada, registro.ses.fallo, registro.contacto.sin_actualizar, y los de la recuperación: recuperacion.solicitud.recibida, .solicitud.limitada, .otp.enviado, .otp.invalido, .solicitud.bloqueada, .exitosa, .ses.fallo, .aviso.fallo, .cuenta.no_encontrada. En producción llevan alarma a Slack; en PreProd solo se miran.
• Rutas bajo /autenticacion en el REST del entorno. Un stage EDGE (CloudFront) rechaza con 403 un GET que trae cuerpo antes de llegar a la lambda: las pruebas de humo no deben mandar cuerpo en un GET.

Operación: rotar la clave del código¶

1. Leer el secreto (actual), copiarlo a anterior y escribir una actual nueva (32 bytes aleatorios en base64, con un id nuevo).
2. Los códigos ya emitidos siguen validando con anterior; los nuevos usan actual. Pasados 15 minutos se puede quitar anterior.
3. La lambda recarga el secreto sola en 5 minutos; no hace falta redesplegar. Rotar cuando se sospeche una filtración y, como rutina, cada 90 días (M-168).

Correos¶

Cuatro correos, todos con el diseño "guía de envío" del equipo de front (HTML y texto plano, sin respuesta posible):

• Las plantillas viven en Autenticacion.Nucleo/Plantillas/ (01–04, .html y .txt) y se rellenan con {{variable}}. Para cambiar el diseño se reemplazan esos archivos; no hay que tocar código. Si una plantilla pide una variable que el código no entrega, la lambda falla en vez de enviar el correo a medias.
• En el HTML todo valor (nombre, enlace) se codifica; en el texto va tal cual.
• El nombre sale del username de la cuenta (en la recuperación se lee de Users al pedir el código y se guarda en la solicitud para el aviso). Sin nombre se usa "Cliente LogiGho".
• La fecha del aviso va en hora de Colombia (UTC-5), formato 5 nov 2026 · 1:06 p. m..
• Las tres imágenes (logo-tinta.png, codigo-barras.png, icono-copiar.png) se leen de CORREO_URL_IMAGENES. Si no cargan, el correo se entiende igual (se ve el texto "LogiGho").
• El correo de cambio con sesión (/cambio-pass, obsoleto) conserva su texto antiguo hasta que se retire.
• Por qué así: dónde viven las plantillas, de dónde sale el nombre, por qué la fecha va en UTC-5, dónde van las imágenes y por qué el botón de copiar no copia solo están razonados, con las alternativas descartadas, en Decisiones de Autenticación (ADR).

Logs que se esperan¶

Buscar problemas en CloudWatch: filtrar por [ERROR] y [WARN] en el log group de cada lambda.

Variables de entorno¶

Las define el pipeline (Library) y se aplican al desplegar. Ninguna lleva secretos en el repo.

Despliegue y reversión¶

1. Ejecutar las pruebas del dominio (dotnet test de cada proyecto).
2. Publicar la lambda con runtime dotnet10 y el handler del aws-lambda-tools-defaults.json de su carpeta.
3. Aplicar las variables de la Library.
4. Probar en PreProd con la guía E2E.
5. Observar una semana en producción. Reversión: volver a la versión anterior de la lambda (alias o versión previa); los datos creados permanecen y son compatibles.

Una ruta se cierra a la vez (política M-195). El orden de las demás rutas está en Rutas y autorización.