Autenticación¶

Contrato de las rutas de cuentas de LogiGho. Dominio dueño: autenticacion (código en Lambdas_NET_LogiGho/LambdasLogiGho.Aplicacion/AWS/Autenticacion/). Estado (2026-11-03): desplegado y probado en PreProd createUser, users, el registro, el inicio de sesión, el cambio de contraseña con código y la asignación de acceso (PR 575, 576 y 577). La recuperación de contraseña (PR 579) y la restricción de GET /users para el rol Red social (PR 578) se activan al completar esos PR. Producción se sube junto con el front, después del aval de Iker.

Entorno de PreProd (para construir y probar el front)¶

Estos identificadores no son secretos; ya van en el bundle del front.

Cómo se autentica una persona¶

1. El front inicia sesión directo contra Cognito (SRP) con el user pool de LogiGho. No hay una ruta de login en el API.
2. Cognito devuelve un id_token (JWT RS256). El front lo guarda en sessionStorage (id_token).
3. Cada llamada del usuario al API manda ese token en el header Token (no en Authorization).
4. La lambda verifica el token (firma con las llaves públicas del pool, emisor, token_use, vigencia y que el client_id sea uno de los autorizados). Un token falso o vencido responde 401.
5. El rol del usuario nunca sale del token ni del cuerpo: la lambda lo lee de la colección Users, buscando por cognitoId (el sub del token).

Formato de respuesta de error¶

Las lambdas del dominio responden JSON con esta forma:

{ "Error": true, "Codigo": "PROHIBIDO", "Mensaje": "No tienes permiso para crear usuarios.", "Motivos": null }

• Codigo es estable y sirve para decidir qué mostrar. Mensaje es texto para la persona.
• Motivos solo trae datos útiles y seguros (motivos de la política de contraseña, roles rechazados, campos rechazados). Nunca trae la contraseña ni datos internos.
• Un error inesperado responde 500 ERROR_INTERNO sin detalle. El detalle queda en los logs del servidor, también sin datos personales.

Política de contraseña¶

La misma que exige el user pool: 8 a 256 caracteres, al menos una minúscula, una mayúscula, un número y un símbolo, sin espacios al inicio ni al final y sin caracteres de control. Símbolos válidos: ^ $ * . [ ] { } ( ) ? " ! @ # % & / \ , > < ' : ; | _ ~ = + -`.

Cuando falla, la respuesta es 400 POLITICA_CONTRASENA y Motivos lista una o varias de estas claves:

Quién puede qué¶

Las listas salen de las variables ROLES_ADMINISTRACION y ROLES_GESTION_PRIVILEGIOS de cada lambda; si faltan, nadie puede nada. Los nombres de rol se comparan exactos (sin ignorar mayúsculas).

POST /createUser — crear un usuario¶

Requiere header Token de una persona con rol de administración.

Body (la misma forma que ya envía la vista de usuarios):

{
  "Usuario": {
    "email": "nuevo@tienda.com",
    "numTelefono": "3001234567",
    "tipoDocumento": "CC",
    "documento": "123456789",
    "autorizaDatos": true,
    "roles": ["Tienda"],
    "tiendas": ["TIENDA1"]
  },
  "Contrasena": "Segura#2026x",
  "TipoUsuario": "Tienda"
}

• numTelefono y documento pueden ir como texto o número.
• TipoUsuario es una etiqueta opcional de texto libre (custom:TipoUsuario en Cognito); no decide ningún permiso. Si no hay un valor real, no lo envíes o envía N/A. Los valores de los ejemplos (Interno, etc.) no significan nada.
• El username que mande el front se ignora: se calcula como el prefijo del correo, en minúsculas.
• Al menos un rol. Ningún texto pasa de 100 caracteres y el correo no pasa de 254.

No se envía correo a la persona creada: createUser no manda mensajes. Cognito no le pide cambiar la contraseña en el primer ingreso.

Cambio de contraseña (reemplazado)¶

El cambio de contraseña con sesión y contraseña actual (POST /cambio-pass/codigo y POST /cambio-pass) ya no es parte del contrato. Se reemplazó el 2026-11-03 por la Recuperación de contraseña, que sirve igual para «olvidé mi contraseña» y para «cambiar contraseña» desde el perfil, sin contraseña actual.

/users — usuarios (GET, POST, PUT)¶

Todos los métodos requieren header Token y que la persona tenga registro en Users.

GET /users?page=1&email=...: sin cambios en la forma de la respuesta (Resultado comprimido en gzip y NumeroPaginas). Cualquier usuario con un rol de trabajo puede consultar (restringirlo más queda en M-199, porque el front lo usa al iniciar sesión y en listados). Quien solo tiene el rol Red social (o ninguno) recibe únicamente su propio registro: el filtro y la página que envíe se ignoran. Es así porque cualquier persona puede crear esa cuenta con el registro por autoservicio (PR 578).

PUT /users?_id=<id> con un cuerpo parcial de campos a cambiar:

Nombres de campo que empiezan con $ o llevan punto se rechazan (400 DATOS_INVALIDOS). Si el _id no existe responde 404 NO_ENCONTRADO.

POST /users: queda para quien tenga rol de administración y solo con roles que pueda asignar. Un documento nuevo no puede reutilizar el cognitoId de una cuenta ya registrada (409 USUARIO_DUPLICADO). Para crear personas usa /createUser, que además crea la cuenta de Cognito.

POST /registerContact — formulario de contacto (público)¶

Es el formulario de la landing y no exige sesión. Solo acepta POST (los demás métodos responden 405).

• Cuerpo: un arreglo con 1 a 3 contactos, o un contacto suelto.
• Campos aceptados: userName, email, phoneNumber, source, comienzo, city, NombreComercio, ventasPorMes, businessType (texto de hasta 200 caracteres) e isColombian (booleano). Cualquier otro campo se descarta.
• Obligatorios: userName, email válido y phoneNumber.
• fechaRegistro y estado (No Contactado) los pone el servidor; lo que mande el front se ignora.
• Responde 200 OK, 400 DATOS_INVALIDOS o 500 ERROR_INTERNO.

POST /obtenerTokenAuth — token de servicio¶

La usan servicios (Hoko Wallet, Guías, Liquidaciones, intereses de apalancamiento), no el front. Contrato de éxito sin cambios: el cuerpo trae usuario y clave (la clave en Base64) y el token vuelve en el header Token. Cambios de seguridad sin romper el contrato: un cuerpo inválido responde 400, los errores ya no devuelven el mensaje interno de Cognito y se retiró Access-Control-Allow-Credentials. La sustitución por credenciales de máquina (OAuth2 client_credentials) está en el backlog (M-194).

Registro por autoservicio con código (spec 008)¶

Rutas públicas (sin Token). La persona se registra, recibe un código de 6 dígitos por correo, define su contraseña y queda activa de inmediato con el rol Red social (sin tiendas). Después Comercial le da el acceso real desde su vista de clientes (siguiente sección). No hay aprobación previa.

sequenceDiagram
  participant P as Persona
  participant F as Front
  participant A as API
  P->>F: llena el formulario
  F->>A: POST /autenticacion/registro/solicitudes
  A-->>F: 202 (siempre igual)
  A->>P: correo con código y enlace ?solicitud=id
  P->>F: abre el enlace, escribe código y contraseña
  F->>A: POST /autenticacion/registro/confirmaciones
  A-->>F: 201 estado ACTIVO
  F->>A: login directo contra Cognito (correo + contraseña)

POST /autenticacion/registro/solicitudes¶

Usa los mismos nombres de campo del formulario público de contacto (/registerContact), más autorizaDatos:

{
  "userName": "Ana Pérez",
  "email": "ana@tienda.com",
  "phoneNumber": "3001234567",
  "source": "Instagram",
  "comienzo": "Ya vendo",
  "city": "Bogotá",
  "NombreComercio": "Tienda Ana",
  "ventasPorMes": "10-50",
  "businessType": "Moda",
  "isColombian": true,
  "autorizaDatos": true
}

• Obligatorios para crear la cuenta: el correo es lo único que usa Cognito (más la contraseña, que llega en la confirmación). userName se usa para saludar en el correo y phoneNumber se guarda en Users. El resto de campos solo sirve para crear el contacto de Comercial si el front no lo guardó antes con /registerContact; está en revisión reducirlos cuando el front confirme qué guarda por su lado. Hoy son obligatorios userName, email válido, phoneNumber y autorizaDatos: true. Los demás son opcionales. Textos de hasta 200 caracteres; cuerpo de hasta 16 KB; un campo con tipo equivocado es DATOS_INVALIDOS.
• El correo se pasa a minúsculas.
• Responde 202 con el mismo cuerpo exista o no el correo (para que nadie descubra qué correos están registrados). Si el correo ya tiene cuenta no se manda código: se manda un aviso de "este correo ya tiene una cuenta".
• Máximo 3 solicitudes por correo por hora; pasado el límite sigue respondiendo 202 pero no envía nada.

El correo trae el código, su vigencia (15 minutos), el enlace {URL_REGISTRO}?solicitud=<solicitudId> y el aviso "si no fuiste tú, ignora este correo". El enlace no lleva el código ni el correo. URL_REGISTRO hoy es https://www.logigho.com/app/registro en PreProd; las pantallas del front viven bajo /app; si la ruta cambia, se cambia con una variable de la lambda, sin redesplegar código.

POST /autenticacion/registro/solicitudes/reenvio¶

{ "solicitudId": "kT3..." }

Envía un código nuevo; el anterior deja de servir y los intentos vuelven a cero. Espera 60 segundos entre envíos y máximo 3 por hora.

POST /autenticacion/registro/confirmaciones¶

{ "solicitudId": "kT3...", "codigo": "123456", "contrasena": "Segura#2026x" }

Crea la cuenta (Cognito y Users con rol Red social) y actualiza o crea la fila de RegisterContact (estado: "Registrado en plataforma", userId), sin duplicar el contacto que el formulario de la landing ya haya guardado. Si algo falla al crear, la cuenta de Cognito se borra para no dejar huérfanos.

Recuperación de contraseña (olvidé mi contraseña y cambio desde el perfil)¶

Rutas públicas (sin Token) y un solo flujo para dos pantallas: «Olvidé mi contraseña» (en el ingreso) y «Cambiar contraseña» (en el perfil). Decisión 2026-11-03: no se pide la contraseña actual; el factor es el código de un solo uso que llega al correo de la cuenta. Es tan seguro como el resto del sistema porque quien controla el correo ya puede recuperar la cuenta, y contra quien solo tiene una sesión abierta el código basta. Desde el perfil, el front llama a las mismas rutas con el correo del usuario.

sequenceDiagram
  participant P as Persona
  participant F as Front
  participant A as API
  P->>F: escribe su correo
  F->>A: POST /autenticacion/recuperacion/solicitudes
  A-->>F: 202 (siempre igual)
  A->>P: correo con código y enlace ?solicitud=id
  P->>F: abre el enlace, escribe código y contraseña nueva
  F->>A: POST /autenticacion/recuperacion/confirmaciones
  A-->>F: 200 contraseña actualizada
  A->>P: correo de aviso del cambio
  F->>A: login directo contra Cognito con la contraseña nueva

POST /autenticacion/recuperacion/solicitudes¶

{ "email": "ana@tienda.com" }

• Responde 202 con el mismo cuerpo exista o no la cuenta (no revela qué correos están registrados). Si la cuenta existe, guarda la solicitud y manda el código al correo. Si no existe, no hace nada.
• El solicitudId no viaja en la respuesta: solo llega en el enlace del correo, {URL_RECUPERACION}?solicitud=<solicitudId>. URL_RECUPERACION hoy es https://www.logigho.com/app/recuperar; el equipo de front define la ruta final y se cambia con una variable.
• Límites: 60 segundos entre envíos y 3 por hora por correo; pasado el límite sigue respondiendo 202 sin enviar nada.
• Las cuentas creadas con una red social (Google, etc.) no tienen contraseña propia: el cambio falla con 500 en la confirmación. Pendiente decidir el mensaje (backlog).

POST /autenticacion/recuperacion/confirmaciones¶

{ "solicitudId": "kT3...", "codigo": "123456", "contrasena": "Nueva#2026y" }

Pone la contraseña nueva en la cuenta que pidió el código, cierra todas sus sesiones (refresh tokens) y manda un correo de aviso del cambio. El front debe llevar a la pantalla de ingreso. El id_token ya emitido sigue aceptándose hasta que venza (hasta 60 minutos; observación M-215).

Reglas para el front: - Pantalla «olvidé mi contraseña»: pide el correo y muestra siempre «Si existe una cuenta, te enviamos un código». - Pantalla del enlace: toma solo el valor del parámetro solicitud, guárdalo en memoria (no en localStorage) y quítalo de la barra con history.replaceState. - «Reenviar código»: vuelve a llamar a solicitudes con el correo (hay 60 s de espera y máximo 3 por hora). Cada solicitud genera un código y un enlace nuevos; los anteriores siguen valiendo hasta que venzan, así que la persona debe usar el correo más reciente. - contrasena nunca va a logs ni a la auditoría genérica (RUTAS_SIN_AUDITORIA: agrega recuperacion/solicitudes y recuperacion/confirmaciones).

Asignación de acceso por Comercial (vista de clientes)¶

Para que Comercial convierta a una persona registrada (Red social) en un cliente con acceso real sin tener la pantalla de usuarios. Ambas rutas requieren Token y rol de administración (Administrador, Comercial, CEO, Desarrollador).

GET /autenticacion/roles-asignables¶

Devuelve los roles que quien consulta puede dar. Úsalo para llenar el selector.

{ "Error": false, "Codigo": "OK", "Mensaje": "", "Motivos": null, "Roles": ["Tienda", "Inversionista", "Proveedor", "Dropshipper"] }

Para Administrador y Desarrollador son todos los roles activos; para Comercial y CEO, solo los de la lista configurable ROLES_ASIGNABLES_COMERCIAL (nunca roles de administración). Errores: 401 NO_AUTORIZADO, 403 PROHIBIDO.

POST /autenticacion/usuarios/{usuarioId}/acceso¶

{ "roles": ["Tienda"], "tiendas": ["TIENDA1"] }

• usuarioId: el userId de la fila de RegisterContact (se guarda al registrarse) o el _id del usuario en Users. Cualquiera de los dos sirve.
• roles: lista no vacía. tiendas es opcional: si no se envía, se conservan las que tiene; si se envía, reemplaza la lista.
• Quien asigna solo controla los roles que puede asignar: los demás roles del usuario se conservan. Y se quita siempre el rol inicial Red social, salvo que se pida a propósito. Ejemplo: un cliente con Red social, a quien Comercial asigna Tienda, queda solo con Tienda.
• Comercial puede cambiar a cualquier cliente, pero no a un usuario con rol de administración, ni a sí mismo.
• Queda un registro en la colección de auditoría (quién, a quién, roles antes y después), sin datos personales.

Para cambiar roles de usuarios que ya tienen acceso, o los de otro administrador, sigue sirviendo la vista de usuarios (PUT /users, solo Administrador y Desarrollador).