> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/sdks/backend-sdk/iad/changelog.md). # Changelog ## \[3.0.0] - 2026-09-25 ### Cambios incompatibles * La versión `3.0.0` rompe la compatibilidad de la API REST pública con la serie `2.x`: cambian la ruta de evaluación, los valores de `diagnostic` y los campos de las respuestas correctas de evaluación. * `POST /api/v1/iad/evaluate` sustituye a `POST /api/v1/iad/liveness/evaluate`, que deja de estar registrada. * `diagnostic` devuelve `NoAttack` o `Attack` en lugar de `Live` o `NoLive`. * En `GET /api/v1/iad/metrics`, el bloque `quality.liveness` pasa a llamarse `quality.detection`, y sus contadores `live` y `noLive` pasan a ser `noAttack` y `attack`. * `GET /api/v1/iad/health` responde HTTP `503` (`ServiceUnavailable`) cuando el servicio no puede atender evaluaciones: servicio no inicializado, licencia no válida (antes, HTTP `200` con `Unhealthy: (code: )`) o motor de análisis sin responder (antes, HTTP `400`). * `POST /api/v1/iad/evaluate`, `POST /api/v1/iad/evaluate/custom` y `POST /api/v1/iad/extract` responden HTTP `503` (`ServiceUnavailable`) con `Engine communication error: ` cuando el motor de análisis no responde. Antes respondían HTTP `400` con `ErrorProcessing` (`/evaluate` y `/evaluate/custom`) o con `Engine communication error: Too many retries` (`/extract`). ### Añadido * Endpoint `POST /api/v1/iad/evaluate/custom`, que evalúa la captura con el pipeline de análisis (`iad_r01` o `iad_r00`) y la calibración (`regular` o `hardened`) elegidos por el cliente. * Campos `transactionId` (UUID v4 único por petición) y `timestamp` (ISO-8601 UTC con milisegundos) en las respuestas correctas de evaluación. * `GET /api/v1/iad/metrics/prometheus` publica ahora el snapshot completo de `/metrics`: además de las series de nivel HTTP con el prefijo `facephi_`, los bloques propios del servicio (identidad, estado, uso, calidad y alertas) con el prefijo `facephi_iad_`. * El motor integrado en la imagen Docker carga por defecto todas las combinaciones de pipeline y calibración que admite `POST /api/v1/iad/evaluate/custom`. * Parámetro `engine_health_max_age_seconds` (variable de entorno `FACEPHI_IAD_ENGINE_HEALTH_MAX_AGE_SECONDS`, 10 segundos por defecto): tiempo durante el que `GET /api/v1/iad/health` reutiliza la última comprobación del motor de análisis. * Las ventanas `1m`, `5m` y `15m` del bloque `traffic` de `GET /api/v1/iad/metrics` incluyen `clientErrors`, `serverErrors` y `unauthorized`, que `GET /api/v1/iad/metrics/prometheus` publica como `facephi_window_client_errors`, `facephi_window_server_errors` y `facephi_window_unauthorized`. * Las operaciones de captura comprueban la licencia en cada petición: si deja de ser válida con el servicio en marcha, responden HTTP `400` con `Invalid license: (code: )` sin analizar la captura. * Pruebas unitarias y de integración para el nuevo endpoint y el nuevo contrato de respuesta. ### Cambiado * El mensaje de la alerta `LOW_QUALITY` de `GET /api/v1/iad/metrics` pasa a ser `Recent evaluation results show degraded quality`. * Un veredicto `Attack`, y las puntuaciones bajas que lo acompañan, ya no cuentan como muestras de baja calidad: detectar un ataque ya no activa la alerta `LOW_QUALITY` ni deja el servicio en estado `degraded`. `quality.summary.lowQualitySamples` y `LOW_QUALITY` solo reflejan las capturas que el motor de análisis no pudo evaluar (errores `NoneBecause*`). * La validación de los JWT tolera una diferencia de reloj de 60 segundos al comprobar `exp` y `nbf`, así que un token se acepta hasta 60 segundos después de caducar. Los tokens que todavía no son válidos se rechazan con HTTP `401` y el mensaje `JWT token is not yet valid`, en lugar de tratarse como caducados. * La documentación pública describe el servicio exclusivamente como detección de ataques de inyección. * `GET /api/v1/iad/health` reutiliza la última comprobación del motor de análisis, correcta o fallida, durante `engine_health_max_age_seconds` y, cuando caduca, la repite con un único intento de 5 segundos como máximo. Antes comprobaba el motor en cada llamada, con los reintentos de `engine_max_retries`, y podía tardar varios segundos en responder. * Con la licencia no válida, `GET /api/v1/iad/metrics` informa solo de la alerta `LICENSE_EXPIRED`, sin marcar también el motor de análisis como no disponible. * `POST /api/v1/iad/extract` normaliza los errores del motor de análisis igual que `/evaluate` (`NoneBecause*`, `Replay attack detected` y `ErrorFacialImage` para los fallos sin clasificar), en lugar de devolverlos como `Engine communication error: `. * `GET /api/v1/iad/config` con el servicio sin inicializar y `POST /api/v1/iad/config` con un `config_json_string` que no se puede cargar responden HTTP `400` en lugar de `500`. * La clasificación `degraded` de `GET /api/v1/iad/metrics` solo tiene en cuenta los errores de servidor de los últimos 5 minutos, en lugar de cualquiera desde el arranque. La tasa de error con la que se clasifica el servicio y se activa `HIGH_ERROR_RATE` descuenta las capturas rechazadas con `Replay attack detected`. ### Eliminado * Los campos `probability`, `score`, `faceProbability`, `sdkDuration` y `queueDuration` de las respuestas correctas de evaluación. ### Corregido * El consumo de memoria del servicio ya no crece con cada petición. Antes conservaba en memoria toda la salida del motor de análisis mientras estaba en marcha (unos 20 KB por cada captura no válida), lo que podía agotar la memoria del contenedor. * El servicio ya no se queda en marcha sin motor de análisis cuando el proceso del motor termina (por ejemplo, porque el sistema lo detiene por falta de memoria). Ahora deja de aceptar peticiones, libera la licencia y termina con código de salida `1`, para que la política de reinicio del contenedor arranque de nuevo el servicio y el motor. Antes respondía con errores hasta que se reiniciaba el contenedor a mano. Si el motor termina durante el arranque, el servicio termina sin abrir el puerto. ## \[2.3.0] - 2026-09-22 ### Añadido * Umbrales configurables para la clasificación del estado y las alertas de `GET /api/v1/iad/metrics`: `metrics_saturation_queue_p95_ms`, `metrics_saturation_min_inflight_ratio`, `metrics_error_rate_warning`, `metrics_idle_rps_threshold` y `metrics_quality_alert_window_seconds`. Se configuran en `config.json` o con las variables de entorno `FACEPHI_IAD_REST_METRICS_*`, y son los únicos parámetros que `POST /api/v1/iad/config` aplica en tiempo de ejecución. ### Cambiado * Actualizado el motor interno de análisis. * La alerta `LOW_QUALITY` deja de ser permanente: se desactiva cuando no se observan muestras de baja calidad durante `metrics_quality_alert_window_seconds` (900 segundos por defecto), y `quality.summary.lowQualitySince` indica el inicio del episodio vigente. * La clasificación `saturated` y `saturation.backlogSuspected` exigen que las peticiones en curso superen estrictamente los hilos configurados, de modo que la propia petición que lee `/metrics` ya no cuenta como trabajo pendiente. ### Corregido * Al detener el contenedor (`docker stop`, `docker compose down`), el servicio recibe la señal de parada y termina de forma ordenada, así que libera la licencia que tenía en uso. Antes, Docker acababa forzando la parada y, con el licenciamiento offline con servidor local, la licencia flotante quedaba reservada hasta que caducaba su préstamo. ## \[2.2.0] - 2026-08-12 ### Añadido * Endpoints públicos `GET /api/v1/iad/metrics` y `GET /api/v1/iad/metrics/prometheus` para snapshots operativos y exposición en formato Prometheus. * Pruebas unitarias e integración para los snapshots de salud y los endpoints de métricas. ### Cambiado * `GET /api/v1/iad/health` mantiene la comprobación activa del engine, mientras que `/metrics` expone snapshots en caché y contadores en memoria aptos para scraping frecuente. * Actualizado el motor interno. ## \[2.1.0] - 2026-07-20 ### Añadido * Soporte opcional para autenticación JWT. * Pruebas unitarias que cubren la precedencia de la configuración JWT en tiempo de ejecución y el comportamiento de redacción/rechazo del endpoint de configuración. ### Cambiado * Los endpoints públicos de configuración ahora omiten las claves de autenticación JWT en las respuestas de `GET /api/v1/iad/config`. * Las actualizaciones públicas de configuración mediante `POST /api/v1/iad/config` ahora rechazan las claves de autenticación JWT; esos valores deben configurarse únicamente al inicio mediante `config.json` o las variables de entorno `FACEPHI_IAD_REST_*`. ## \[2.0.0] - 2026-05-26 ### Cambios incompatibles * La versión `2.0.0` rompe la compatibilidad de la API REST pública con la serie `1.x.x`: los nombres de los endpoints, los campos de las solicitudes multipart y los payloads de respuesta correctos cambiaron y requieren migración por parte del cliente. ### Añadido * Mapeo de la respuesta pública de evaluación con los campos de estilo Facephi `diagnostic`, `reason`, `probability`, `score`, `sdkDuration` y `queueDuration`. * Mitigación experimental de ataques de repetición documentada como capacidad pública de facephi-iad-service, con las variables de entorno de inicio `FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED` y `FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME`. * Pruebas unitarias para el mapeo del payload de éxito del Engine y la prevención de fugas de campos públicos. * Pruebas unitarias para el contrato del campo multipart obligatorio `capture`. ### Cambiado * Las rutas operativas públicas ahora usan `/api/v1/iad/liveness/evaluate` y `/api/v1/iad/extract`. * Los endpoints multipart ahora requieren el campo `capture` en tiempo de ejecución y rechazan las solicitudes heredadas que solo incluyen `file`. * Los fallos de arranque ahora se propagan a `main` en lugar de finalizar desde el código de arranque del servicio. * Los errores de validación del proveedor IAD se normalizan a valores de respuesta de estilo Facephi/SelphID. * Las capturas expiradas rechazadas por la protección experimental contra repeticiones ahora devuelven el mensaje público HTTP `400` documentado `Replay attack detected`. * La documentación pública de la evaluación ahora enumera los valores exactos de `reason` que devuelve el servicio: `None`, `Unknown`, `UntrustedEnvironment`, `SuspiciousActivity`, `UntrustedDevice`, `SdkIntegrityViolation`, `UntrustedCorruptedPayload`, `UntrustedContent` y `UntrustedContentLowConfidence`. * La documentación pública y los ejemplos de OpenAPI ahora describen el nuevo contrato de respuesta pública en lugar de los payloads del proveedor. ### Corregido * El manejo de señales ya no invoca logging, rutinas de apagado ni `std::exit` desde el manejador de señales. ### Eliminado * Los campos públicos de éxito con forma de Engine `capture_liveness`, `capture_type`, `rejection` y `mime_type`. ## \[1.2.0] - 2026-04-30 ### Seguridad * Los valores `LICENSE_ID` y `LICENSE_DATA` presentes en el archivo de licencia se ignoran. ### Cambiado * La documentación de la API ahora incluye los motivos de rechazo del engine IAD y los mapeos de `error_code` de validación para las respuestas del servicio. * Los ejemplos de Swagger/OpenAPI ahora documentan los errores HTTP `400` originados por el engine para `check-capture` y `extract-image`. * Se mejoró la documentación de la demo añadiendo la modificación de las direcciones IP de los servicios necesarios. ### Corregido * La documentación pública y los metadatos de versión ahora referencian la versión `1.2.0` de forma consistente. * Los ejemplos de instalación y OpenAPI se alinearon con los valores por defecto actuales del runtime y las rutas de endpoint `/api/v1/iad/*`. ## \[1.1.1] - 2026-03-30 ### Cambiado * Actualización del engine IAD a la versión 2.5.3. ### Corregido * Se corrigieron las rutas del registro Docker para usar `docker-pro-fphi` en toda la documentación y las notas de versión. * Se actualizó la especificación OpenAPI con esquemas de solicitud/respuesta precisos que coinciden con el comportamiento real de los endpoints. * Se mejoró la documentación de la API con ejemplos de los endpoints de configuración y comprobación de estado. ## \[1.1.0] - 2026-03-20 ### Añadido * Sobrescritura de la configuración en tiempo de ejecución mediante variables de entorno. * Utilidades de traducción de errores de licencia y de reporte normalizado de errores de licencia para un diagnóstico operativo más claro. ### Cambiado * Actualización del engine IAD a la versión 2.5.2. * Mejoras en la gestión de licencias para soportar escenarios de validación offline y ofrecer un reporte de errores más claro. * Dockerfile simplificado: cambio de imagen base, mejor gestión de paquetes y manejo de dependencias en tiempo de ejecución. ### Corregido * Actualizaciones de endurecimiento (hardening) del runtime Docker y de la imagen base. * Normalización de errores del proxy REST y rutas consistentes de creación/reporte de errores. * Reducción del exceso de logs detallados en las comprobaciones de Docker y los flujos de activación del engine. ## \[1.0.0] - 2026-02-03 ### Añadido * Activación automática del engine a partir de los metadatos de la licencia * Detección del entorno Docker e inicialización automática del engine * Fachada ProcessExecutor para la gestión de procesos en segundo plano * Capa de compatibilidad de sistema de archivos para GCC 7 ### Cambiado * **CAMBIO INCOMPATIBLE**: Se estandarizaron todos los endpoints con el prefijo `/iad` (por ejemplo, `/api/v1/iad/check-capture`) * Estructura de namespace unificada en todos los endpoints * Mejora en los tiempos de espera de la comprobación de estado del engine * Logging mejorado en el proceso de activación del engine * Implementación simplificada de ProcessExecutor * Refactorización del logging interno del proxy REST ### Eliminado * **CAMBIO INCOMPATIBLE**: Se eliminó el endpoint `/extract_data` (funcionalidad consolidada) ### Corregido * Problemas de compatibilidad del sistema de archivos con versiones antiguas de GCC * Sincronización de tiempos en la inicialización del engine en entornos Docker ## \[0.0.1] - 2026-01-29 ### Añadido * Lanzamiento inicial de la API REST de IAD Service * Endpoint `/api/v1/iad/check-capture` para la detección de ataques de inyección * Endpoint `/api/v1/iad/extract-image` para la extracción de imágenes de capturas validadas * Endpoint de gestión `/api/v1/iad/version` para la versión y el estado de la licencia * Endpoint de gestión `/api/v1/iad/health` para la monitorización de estado * Endpoints de gestión `/api/v1/iad/config` (GET/POST) para la gestión de la configuración * Pool de conexiones para la comunicación con el engine * Mecanismo de reintento automático con backoff configurable * Actualizaciones dinámicas de configuración sin reiniciar el servicio * Despliegue basado en Docker con Ubuntu 24.04 * Soporte para validación de licencia online y offline * Logging completo con niveles y rotación configurables * Especificación OpenAPI 3.0 (documentación Swagger)