chatflow-agent 0.3.0__tar.gz → 0.3.2__tar.gz

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/CHANGELOG.md

@@ -12,6 +12,26 @@ Versioning / Versionado: [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## English
 
+## [Unreleased]
+
+## [0.3.2] - 2026-09-29
+
+### Security
+- **Tool Execution Error Sanitization (SEC-02):** Sanitized tool execution errors in `Runner` before exposing them to the LLM, returning a generic error with a unique `trace_id` UUID and logging the original traceback internally to prevent leakage of internal stack traces or environment variables (Issue #3).
+- **Mask Phone Numbers in Exception Logs (SEC-03):** Automatically mask phone numbers (`_mask_phone`) in exception and fallback delivery logs in `WhatsAppChannel` for privacy compliance (Issue #5).
+- **Admin-Only /reset in Telegram Groups (SEC-04):** Restricted the `/reset` command in Telegram group and supergroup chats strictly to chat creators and administrators (Issue #7).
+- **Disabled FastAPI OpenAPI / Docs Endpoints by Default (SEC-05):** `WhatsAppChannel` now sets `docs_url=None`, `redoc_url=None`, and `openapi_url=None` by default to prevent internal schema and route exposure on public webhook endpoints. Interactive documentation can be optionally enabled for development via `enable_docs=True` (Issue #9).
+- **Reverse Proxy Rate Limiting Recommendation (SEC-06):** Added production deployment guidance for placing Uvicorn behind a reverse proxy (e.g., Nginx with `limit_req_zone` or Cloudflare Rate Limiting) to protect `/webhook` and `/health` endpoints against flood attacks and CPU exhaustion from unauthenticated requests, avoiding in-app rate limiting that could drop legitimate bursts of Meta webhooks (Issue #10).
+- **API Key Leakage Prevention on Custom Base URLs (SEC-07):** `OpenAIEngine` now prevents forwarding global environment credentials (`OPENAI_API_KEY`) to untrusted or custom remote endpoints. When a custom `base_url` (not matching official presets or localhost/127.0.0.1) is provided without an explicit `api_key`, a `ValueError` is raised, requiring an explicit `api_key` (or `api_key=""` if unauthenticated) (Issue #11).
+- **Outbound Message Splitting in Telegram (SEC-08):** `TelegramChannel` now splits outbound responses exceeding Telegram's 4,096-character limit into progressive chunks using `split_message()`, preventing systematic delivery failures and error fallbacks on long LLM responses. `split_message()` now resides in `chatflow_agent.channels.base` and is re-exported from `whatsapp` for backwards compatibility (Issue #12).
+- **Async vs Sync Tool Execution Clarification and Guard (SEC-09):** Documented that asynchronous tools must always be invoked via `await tool.execute_async(**kwargs)` in asynchronous environments (FastAPI, Runners, Telegram handlers). Calling `tool.execute()` on an async tool from within an active running event loop now immediately raises a clear `ToolExecutionError` explaining why synchronous re-entry of the running event loop is unsupported and directing the caller to `execute_async()` (Issue #13).
+- **Retry and Backoff in AnthropicEngine (SEC-10):** `AnthropicEngine` now includes exponential backoff with jitter and retry handling for transient API errors (HTTP 429, 500, 502, 503, 504, 529 Overloaded, and connection errors `httpx.ConnectError`, `httpx.ConnectTimeout`). Honors the `Retry-After` header when provided (Issue #14).
+
+## [0.3.1] - 2026-09-25
+
+### Security
+- **WhatsApp Webhook Request Body Size Limit (SEC-01):** Fixed vulnerability where inbound `POST /webhook` requests did not validate the payload size prior to buffering, enabling potential Denial of Service (DoS via Out-of-Memory / OOM). The endpoint now validates the `Content-Length` header before reading the body, enforcing a configurable limit (default: 1 MB via `DEFAULT_MAX_BODY_SIZE`) and rejecting oversized payloads with HTTP 413, missing headers with HTTP 411, and malformed headers with HTTP 400.
+
 ## [0.3.0] - 2026-09-21
 
 ### Security
@@ -47,6 +67,26 @@ If you are upgrading from v0.2.0:
 
 ## Español
 
+## [Unreleased]
+
+## [0.3.2] - 2026-09-29
+
+### Seguridad
+- **Sanitización de Errores de Tools (SEC-02):** Se sanitizaron los errores de ejecución de herramientas en `Runner` antes de exponerlos al LLM, retornando un mensaje genérico con un UUID `trace_id` único y registrando el traceback internamente para prevenir la fuga de stack traces o variables de entorno (Issue #3).
+- **Enmascaramiento de Teléfonos en Logs (SEC-03):** Se enmascaran automáticamente los números telefónicos (`_mask_phone`) en logs de excepciones y fallbacks en `WhatsAppChannel` para cumplimiento de privacidad (Issue #5).
+- **Comando /reset Exclusivo para Administradores en Telegram (SEC-04):** Se restringió la ejecución del comando `/reset` en grupos y supergrupos de Telegram exclusivamente a creadores y administradores (Issue #7).
+- **Desactivación de Endpoints OpenAPI / Docs de FastAPI por Defecto (SEC-05):** `WhatsAppChannel` ahora configura `docs_url=None`, `redoc_url=None` y `openapi_url=None` por defecto para prevenir la exposición de rutas y esquemas internos en endpoints públicos de webhook. La documentación interactiva puede habilitarse opcionalmente para desarrollo mediante `enable_docs=True` (Issue #9).
+- **Recomendación de Rate Limiting con Reverse Proxy (SEC-06):** Se añadió documentación de despliegue en producción recomendando ubicar Uvicorn detrás de un reverse proxy (como Nginx con `limit_req_zone` o Cloudflare Rate Limiting) para proteger los endpoints `/webhook` y `/health` contra ataques de inundación y agotamiento de CPU por peticiones no autenticadas, evitando rate limiting a nivel aplicación que pudiera descartar ráfagas legítimas de webhooks de Meta (Issue #10).
+- **Prevención de Fuga de Claves API en Base URLs Personalizadas (SEC-07):** `OpenAIEngine` ahora previene el reenvío de credenciales globales de entorno (`OPENAI_API_KEY`) a endpoints remotos personalizados o no oficiales. Cuando se proporciona un `base_url` personalizado (que no coincide con los presets oficiales ni con localhost/127.0.0.1) sin una `api_key` explícita, se levanta un `ValueError`, exigiendo una `api_key` explícita (o `api_key=""` si no requiere autenticación) (Issue #11).
+- **División de Mensajes Salientes en Telegram (SEC-08):** `TelegramChannel` ahora divide las respuestas salientes que superan el límite de 4.096 caracteres de Telegram en fragmentos progresivos usando `split_message()`, previniendo fallos sistemáticos de entrega y respuestas de error en respuestas extensas de LLM. `split_message()` ahora reside en `chatflow_agent.channels.base` y se reexporta desde `whatsapp` para retrocompatibilidad (Issue #12).
+- **Clarificación y Validación de Ejecución de Tools Asíncronas vs Síncronas (SEC-09):** Se documentó que las herramientas asíncronas deben invocarse siempre mediante `await tool.execute_async(**kwargs)` en entornos asíncronos (FastAPI, Runners, handlers de Telegram). Ejecutar `tool.execute()` sobre una herramienta asíncrona dentro de un bucle de eventos activo ahora levanta inmediatamente un `ToolExecutionError` claro explicando que la reentrada síncrona al bucle de eventos no está soportada e indicando el uso de `execute_async()` (Issue #13).
+- **Reintentos y Backoff Exponencial en AnthropicEngine (SEC-10):** `AnthropicEngine` ahora incluye reintentos automáticos con backoff exponencial y jitter ante errores transitorios de la API (HTTP 429, 500, 502, 503, 504, 529 Sobrecargado, y errores de conexión `httpx.ConnectError`, `httpx.ConnectTimeout`). Respeta la cabecera `Retry-After` cuando está presente (Issue #14).
+
+## [0.3.1] - 2026-09-25
+
+### Seguridad
+- **Límite de Tamaño en Request Body del Webhook de WhatsApp (SEC-01):** Se corrigió una vulnerabilidad donde las peticiones entrantes `POST /webhook` no validaban el tamaño del payload antes de cargarlo en memoria, permitiendo ataques de Denegación de Servicio por agotamiento de memoria (DoS / OOM). Ahora se valida el encabezado `Content-Length` antes de leer el cuerpo, aplicando un límite configurable (por defecto 1 MB mediante `DEFAULT_MAX_BODY_SIZE`) y rechazando payloads excesivos con HTTP 413, encabezados ausentes con HTTP 411 y encabezados malformados con HTTP 400.
+
 ## [0.3.0] - 2026-09-21
 
 ### Seguridad

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chatflow-agent
-Version: 0.3.0
+Version: 0.3.2
 Summary: Lightweight, async multi-agent framework with native handoffs for Gemini, Gemma, Grok, OpenAI & Claude.
 Project-URL: Homepage, https://github.com/GustavoBaranda/chatflow-agent
 Project-URL: Source Code, https://github.com/GustavoBaranda/chatflow-agent
@@ -583,6 +583,26 @@ if __name__ == "__main__":
 
 > **Testing locally?** Use a tunnel like [ngrok](https://ngrok.com) (`ngrok http 8000`) or Cloudflare Tunnels to provide Meta with a public HTTPS URL (`https://your-domain.ngrok-free.app/webhook`).
 
+> [!NOTE]
+> **API Documentation in Development:** For security, FastAPI interactive documentation (`/docs`, `/redoc`, and `/openapi.json`) is disabled by default in production. To enable Swagger UI and OpenAPI schemas during local development or debugging, pass `enable_docs=True` when instantiating `WhatsAppChannel`:
+> ```python
+> channel = WhatsAppChannel(
+>     ...,
+>     enable_docs=True,  # Enables /docs, /redoc, and /openapi.json for local development
+> )
+> ```
+
+> [!TIP]
+> **Production Rate Limiting & Reverse Proxy:** To protect `/webhook` and `/health` endpoints against flood attacks, denial of service (DoS), and CPU exhaustion from unauthenticated requests without risking dropping legitimate Meta webhook bursts at the application level, always place Uvicorn behind a reverse proxy in production (such as Nginx with `limit_req_zone` or Cloudflare Rate Limiting):
+> ```nginx
+> limit_req_zone $binary_remote_addr zone=whatsapp_limit:10m rate=10r/s;
+> location /webhook {
+>     limit_req zone=whatsapp_limit burst=20 nodelay;
+>     proxy_pass http://127.0.0.1:8000;
+>     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+> }
+> ```
+
 ---
 
 #### Telegram Channel
@@ -1197,6 +1217,26 @@ if __name__ == "__main__":
 
 > **¿Probando localmente?** Usa un tunel como [ngrok](https://ngrok.com) (`ngrok http 8000`) o Cloudflare Tunnels para brindarle a Meta la URL publica HTTPS (`https://tu-dominio.ngrok-free.app/webhook`).
 
+> [!NOTE]
+> **Documentación interactiva en desarrollo:** Por motivos de seguridad, la documentación interactiva de FastAPI (`/docs`, `/redoc` y `/openapi.json`) está deshabilitada por defecto en producción. Para habilitar Swagger UI y los esquemas OpenAPI durante el desarrollo local o debugging, pasa `enable_docs=True` al instanciar `WhatsAppChannel`:
+> ```python
+> canal_whatsapp = WhatsAppChannel(
+>     ...,
+>     enable_docs=True,  # Habilita /docs, /redoc y /openapi.json para desarrollo local
+> )
+> ```
+
+> [!TIP]
+> **Rate Limiting y Reverse Proxy en Producción:** Para proteger los endpoints `/webhook` y `/health` contra ataques de inundación, denegación de servicio (DoS) y agotamiento de CPU por peticiones no autenticadas sin riesgo de descartar ráfagas legítimas de webhooks de Meta a nivel aplicación, ubica siempre Uvicorn detrás de un reverse proxy en producción (como Nginx con `limit_req_zone` o Cloudflare Rate Limiting):
+> ```nginx
+> limit_req_zone $binary_remote_addr zone=whatsapp_limit:10m rate=10r/s;
+> location /webhook {
+>     limit_req zone=whatsapp_limit burst=20 nodelay;
+>     proxy_pass http://127.0.0.1:8000;
+>     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+> }
+> ```
+
 ---
 
 #### Canal de Telegram

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/README.md

@@ -537,6 +537,26 @@ if __name__ == "__main__":
 
 > **Testing locally?** Use a tunnel like [ngrok](https://ngrok.com) (`ngrok http 8000`) or Cloudflare Tunnels to provide Meta with a public HTTPS URL (`https://your-domain.ngrok-free.app/webhook`).
 
+> [!NOTE]
+> **API Documentation in Development:** For security, FastAPI interactive documentation (`/docs`, `/redoc`, and `/openapi.json`) is disabled by default in production. To enable Swagger UI and OpenAPI schemas during local development or debugging, pass `enable_docs=True` when instantiating `WhatsAppChannel`:
+> ```python
+> channel = WhatsAppChannel(
+>     ...,
+>     enable_docs=True,  # Enables /docs, /redoc, and /openapi.json for local development
+> )
+> ```
+
+> [!TIP]
+> **Production Rate Limiting & Reverse Proxy:** To protect `/webhook` and `/health` endpoints against flood attacks, denial of service (DoS), and CPU exhaustion from unauthenticated requests without risking dropping legitimate Meta webhook bursts at the application level, always place Uvicorn behind a reverse proxy in production (such as Nginx with `limit_req_zone` or Cloudflare Rate Limiting):
+> ```nginx
+> limit_req_zone $binary_remote_addr zone=whatsapp_limit:10m rate=10r/s;
+> location /webhook {
+>     limit_req zone=whatsapp_limit burst=20 nodelay;
+>     proxy_pass http://127.0.0.1:8000;
+>     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+> }
+> ```
+
 ---
 
 #### Telegram Channel
@@ -1151,6 +1171,26 @@ if __name__ == "__main__":
 
 > **¿Probando localmente?** Usa un tunel como [ngrok](https://ngrok.com) (`ngrok http 8000`) o Cloudflare Tunnels para brindarle a Meta la URL publica HTTPS (`https://tu-dominio.ngrok-free.app/webhook`).
 
+> [!NOTE]
+> **Documentación interactiva en desarrollo:** Por motivos de seguridad, la documentación interactiva de FastAPI (`/docs`, `/redoc` y `/openapi.json`) está deshabilitada por defecto en producción. Para habilitar Swagger UI y los esquemas OpenAPI durante el desarrollo local o debugging, pasa `enable_docs=True` al instanciar `WhatsAppChannel`:
+> ```python
+> canal_whatsapp = WhatsAppChannel(
+>     ...,
+>     enable_docs=True,  # Habilita /docs, /redoc y /openapi.json para desarrollo local
+> )
+> ```
+
+> [!TIP]
+> **Rate Limiting y Reverse Proxy en Producción:** Para proteger los endpoints `/webhook` y `/health` contra ataques de inundación, denegación de servicio (DoS) y agotamiento de CPU por peticiones no autenticadas sin riesgo de descartar ráfagas legítimas de webhooks de Meta a nivel aplicación, ubica siempre Uvicorn detrás de un reverse proxy en producción (como Nginx con `limit_req_zone` o Cloudflare Rate Limiting):
+> ```nginx
+> limit_req_zone $binary_remote_addr zone=whatsapp_limit:10m rate=10r/s;
+> location /webhook {
+>     limit_req zone=whatsapp_limit burst=20 nodelay;
+>     proxy_pass http://127.0.0.1:8000;
+>     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+> }
+> ```
+
 ---
 
 #### Canal de Telegram

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "chatflow-agent"
-version = "0.3.0"
+version = "0.3.2"
 description = "Lightweight, async multi-agent framework with native handoffs for Gemini, Gemma, Grok, OpenAI & Claude."
 readme = "README.md"
 requires-python = ">=3.10"

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/src/chatflow_agent/__init__.py

@@ -34,7 +34,7 @@ from chatflow_agent.types import (
 # Alias for semantic consistency
 BaseSessionContext = SessionContext
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 __all__ = [
     "__version__",
     "Agent",

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/src/chatflow_agent/channels/__init__.py

@@ -1,6 +1,6 @@
 """Communication channels for chatflow-agent: CLI, WhatsApp, Telegram, and Webhook."""
 
-from chatflow_agent.channels.base import BaseChannel, ChannelError
+from chatflow_agent.channels.base import BaseChannel, ChannelError, split_message
 from chatflow_agent.channels.cli import CLIChannel
 from chatflow_agent.channels.telegram import TelegramChannel
 from chatflow_agent.channels.whatsapp import WhatsAppChannel
@@ -11,4 +11,5 @@ __all__ = [
     "ChannelError",
     "TelegramChannel",
     "WhatsAppChannel",
+    "split_message",
 ]

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/src/chatflow_agent/channels/base.py

@@ -12,6 +12,42 @@ class ChannelError(ChatFlowError):
     """Raised when an operation on a channel fails or runner is detached."""
 
 
+def split_message(text: str, max_len: int = 4096) -> list[str]:
+    """Split long outbound text into sequential chunks within max_len.
+
+    Splits progressively by paragraph (\n\n), line (\n), sentence (. ), or word ( )
+    to preserve formatting and readability across messaging channels.
+    """
+    if len(text) <= max_len:
+        return [text]
+
+    chunks: list[str] = []
+    remaining = text
+
+    while len(remaining) > max_len:
+        candidate = remaining[:max_len]
+        split_idx = -1
+
+        for sep in ("\n\n", "\n", ". ", " "):
+            idx = candidate.rfind(sep)
+            if idx != -1:
+                split_idx = idx + len(sep)
+                break
+
+        if split_idx <= 0:
+            split_idx = max_len
+
+        chunk = remaining[:split_idx].rstrip()
+        if chunk:
+            chunks.append(chunk)
+        remaining = remaining[split_idx:].lstrip()
+
+    if remaining:
+        chunks.append(remaining)
+
+    return chunks
+
+
 class BaseChannel(ABC):
     """Abstract base class for all communication channels (CLI, WhatsApp, Telegram, Webhook)."""
 

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/src/chatflow_agent/channels/telegram.py

@@ -3,7 +3,7 @@
 import logging
 from typing import Any
 
-from chatflow_agent.channels.base import BaseChannel
+from chatflow_agent.channels.base import BaseChannel, split_message
 from chatflow_agent.exceptions import DependencyError
 from chatflow_agent.types import AgentResponse
 
@@ -68,6 +68,29 @@ class TelegramChannel(BaseChannel):
         if not update.effective_chat or not update.message:
             return
 
+        # Restrict /reset in group and supergroup chats to creators and administrators
+        if getattr(update.effective_chat, "type", None) in ("group", "supergroup"):
+            is_admin = False
+            if update.effective_user and hasattr(context, "bot") and context.bot:
+                try:
+                    member = await context.bot.get_chat_member(
+                        chat_id=update.effective_chat.id,
+                        user_id=update.effective_user.id,
+                    )
+                    if getattr(member, "status", None) in ("creator", "administrator"):
+                        is_admin = True
+                except Exception as err:
+                    logger.error(
+                        f"Failed to verify chat member permissions for /reset: {err}"
+                    )
+                    is_admin = False
+
+            if not is_admin:
+                await update.message.reply_text(
+                    "Only group admins can reset the conversation."
+                )
+                return
+
         chat_id = str(update.effective_chat.id)
         if self.runner:
             session = self.runner.get_session(chat_id)
@@ -103,7 +126,9 @@ class TelegramChannel(BaseChannel):
                     "username": user_name,
                 },
             )
-            await update.message.reply_text(response.content)
+            chunks = split_message(response.content, max_len=4096)
+            for chunk in chunks:
+                await update.message.reply_text(chunk)
         except Exception as err:
             logger.error(f"Error processing Telegram message: {err}")
             await update.message.reply_text(self.fallback_message)

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/src/chatflow_agent/channels/whatsapp.py

@@ -8,13 +8,15 @@ import json
 import logging
 from typing import Any
 
-from chatflow_agent.channels.base import BaseChannel
+from chatflow_agent.channels.base import BaseChannel, split_message
 from chatflow_agent.core.memory import DEFAULT_DEDUP_TTL_HOURS
 from chatflow_agent.exceptions import DependencyError
 from chatflow_agent.types import AgentResponse
 
 logger = logging.getLogger("chatflow_agent.whatsapp")
 
+DEFAULT_MAX_BODY_SIZE = 1 * 1024 * 1024  # 1 MB maximum allowed webhook payload size
+
 
 def _mask_phone(phone: str) -> str:
     """Mask phone number for GDPR/privacy compliance in logs (e.g. 5491***678)."""
@@ -23,40 +25,7 @@ def _mask_phone(phone: str) -> str:
     return f"{phone[:4]}***{phone[-3:]}"
 
 
-def split_message(text: str, max_len: int = 4096) -> list[str]:
-    """Split long outbound text into sequential chunks within max_len.
-
-    Splits progressively by paragraph (\n\n), line (\n), sentence (. ), or word ( )
-    to preserve formatting and readability across messaging channels.
-    """
-    if len(text) <= max_len:
-        return [text]
-
-    chunks: list[str] = []
-    remaining = text
-
-    while len(remaining) > max_len:
-        candidate = remaining[:max_len]
-        split_idx = -1
-
-        for sep in ("\n\n", "\n", ". ", " "):
-            idx = candidate.rfind(sep)
-            if idx != -1:
-                split_idx = idx + len(sep)
-                break
-
-        if split_idx <= 0:
-            split_idx = max_len
-
-        chunk = remaining[:split_idx].rstrip()
-        if chunk:
-            chunks.append(chunk)
-        remaining = remaining[split_idx:].lstrip()
-
-    if remaining:
-        chunks.append(remaining)
-
-    return chunks
+__all__ = ["WhatsAppChannel", "split_message"]
 
 
 class WhatsAppChannel(BaseChannel):
@@ -83,6 +52,8 @@ class WhatsAppChannel(BaseChannel):
         outbound_max_delay: float = 30.0,
         on_24h_window_expired: Any | None = None,
         dedup_ttl_hours: float = DEFAULT_DEDUP_TTL_HOURS,
+        max_body_size: int = DEFAULT_MAX_BODY_SIZE,
+        enable_docs: bool = False,
     ) -> None:
         super().__init__()
         # SEC-01: Fail-closed — require app_secret when signature verification is active.
@@ -112,6 +83,8 @@ class WhatsAppChannel(BaseChannel):
         self.outbound_max_delay = outbound_max_delay
         self.on_24h_window_expired = on_24h_window_expired
         self.dedup_ttl_hours = dedup_ttl_hours
+        self.max_body_size = max_body_size
+        self.enable_docs = enable_docs
 
         # Verify optional dependencies
         try:
@@ -126,7 +99,16 @@ class WhatsAppChannel(BaseChannel):
 
         self._httpx = httpx
         self._uvicorn = uvicorn
-        self.app = FastAPI(title="ChatFlow WhatsApp Webhook Server")
+        # SEC-05: Disable OpenAPI schema, Swagger UI (/docs) and ReDoc (/redoc) by default in production
+        docs_url = "/docs" if enable_docs else None
+        redoc_url = "/redoc" if enable_docs else None
+        openapi_url = "/openapi.json" if enable_docs else None
+        self.app = FastAPI(
+            title="ChatFlow WhatsApp Webhook Server",
+            docs_url=docs_url,
+            redoc_url=redoc_url,
+            openapi_url=openapi_url,
+        )
         self._setup_routes()
 
     def _setup_routes(self) -> None:
@@ -164,8 +146,39 @@ class WhatsAppChannel(BaseChannel):
         async def handle_incoming_message(
             request: Request, background_tasks: BackgroundTasks
         ) -> Response:
-            """Validate HMAC, deduplicate by wamid, and dispatch processing to background tasks."""
+            """Validate Content-Length, HMAC, deduplicate by wamid, and dispatch processing to background tasks."""
+            # SEC-01: Validate Content-Length before buffering body to prevent OOM DoS
+            content_length_header = request.headers.get("Content-Length")
+            if not content_length_header:
+                raise HTTPException(
+                    status_code=status.HTTP_411_LENGTH_REQUIRED,
+                    detail="Missing Content-Length header",
+                )
+
+            try:
+                content_length = int(content_length_header)
+            except (ValueError, TypeError) as err:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Invalid Content-Length header",
+                ) from err
+
+            status_413 = getattr(
+                status, "HTTP_413_CONTENT_TOO_LARGE", status.HTTP_413_REQUEST_ENTITY_TOO_LARGE
+            )
+
+            if content_length < 0 or content_length > self.max_body_size:
+                raise HTTPException(
+                    status_code=status_413,
+                    detail=f"Payload size exceeds maximum limit of {self.max_body_size} bytes",
+                )
+
             raw_body = await request.body()
+            if len(raw_body) > self.max_body_size:
+                raise HTTPException(
+                    status_code=status_413,
+                    detail=f"Payload body exceeds maximum limit of {self.max_body_size} bytes",
+                )
 
             # SEC-01: Validate X-Hub-Signature-256 when verify_signature is active
             if self.verify_signature and self.app_secret:
@@ -273,6 +286,7 @@ class WhatsAppChannel(BaseChannel):
         self, wamid: str, sender_phone: str, user_text: str | None
     ) -> None:
         """Process one WhatsApp message asynchronously with full anti-500 error shield."""
+        masked_phone = _mask_phone(sender_phone)
         try:
             if user_text is None:
                 if self.access_token and self.phone_number_id:
@@ -293,12 +307,12 @@ class WhatsAppChannel(BaseChannel):
                 reply_text = response.content
             except asyncio.TimeoutError:
                 logger.error(
-                    f"LLM dispatch timed out after {self.llm_timeout_seconds}s for wamid={wamid} from {sender_phone}"
+                    f"LLM dispatch timed out after {self.llm_timeout_seconds}s for wamid={wamid} from {masked_phone}"
                 )
                 reply_text = self.fallback_message
             except Exception as err:
                 logger.exception(
-                    f"Error dispatching wamid={wamid} from {sender_phone}: {err}"
+                    f"Error dispatching wamid={wamid} from {masked_phone}: {err}"
                 )
                 reply_text = self.fallback_message
 
@@ -314,7 +328,7 @@ class WhatsAppChannel(BaseChannel):
                     )
                 except Exception as fb_err:
                     logger.exception(
-                        f"Failed to deliver fallback to {sender_phone}: {fb_err}"
+                        f"Failed to deliver fallback to {masked_phone}: {fb_err}"
                     )
 
     def _extract_message_and_sender(

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/src/chatflow_agent/core/engines/anthropic.py

@@ -1,7 +1,10 @@
 """Anthropic Claude engine for chatflow-agent."""
 
+import asyncio
 import json
+import logging
 import os
+import random
 from typing import TYPE_CHECKING, Any
 
 import httpx
@@ -11,6 +14,8 @@ from chatflow_agent.core.engines.openai_compatible import _lowercase_schema_type
 from chatflow_agent.exceptions import ProviderError
 from chatflow_agent.types import Message, Role, ToolCall
 
+logger = logging.getLogger("chatflow_agent.engine.anthropic")
+
 if TYPE_CHECKING:
     from chatflow_agent.core.agent import Agent
 
@@ -30,6 +35,9 @@ class AnthropicEngine(BaseEngine):
         self.base_url = base_url.rstrip("/")
         self.anthropic_version = anthropic_version
         self.timeout = timeout
+        self.max_retries = 3
+        self.base_delay = 1.0
+        self.max_delay = 10.0
         self._external_client = http_client
 
     def _format_history(self, history: list[Message]) -> list[dict[str, Any]]:
@@ -115,18 +123,55 @@ class AnthropicEngine(BaseEngine):
         }
 
         url = f"{self.base_url}/messages"
-        client = self._external_client or httpx.AsyncClient(timeout=self.timeout)
-
-        try:
-            resp = await client.post(url, json=payload, headers=headers)
-            if resp.status_code >= 400:
-                raise ProviderError(f"Anthropic API error ({resp.status_code}): {resp.text}")
-            data = resp.json()
-        except httpx.RequestError as err:
-            raise ProviderError(f"Anthropic connection error: {err}") from err
-        finally:
-            if not self._external_client:
-                await client.aclose()
+
+        retries = 0
+        while True:
+            client = self._external_client or httpx.AsyncClient(timeout=self.timeout)
+            try:
+                resp = await client.post(url, json=payload, headers=headers)
+                if resp.status_code in (429, 500, 502, 503, 504, 529):
+                    if retries < self.max_retries:
+                        retry_after_str = resp.headers.get("Retry-After")
+                        parsed_delay = None
+                        if retry_after_str:
+                            try:
+                                parsed_delay = float(retry_after_str)
+                            except (ValueError, TypeError):
+                                parsed_delay = None
+
+                        base = parsed_delay if parsed_delay is not None else self.base_delay * (2 ** retries)
+                        delay = min(self.max_delay, base + random.uniform(0.0, 0.25 * base))
+                        logger.warning(
+                            f"Anthropic returned HTTP {resp.status_code}. Retrying in {delay:.2f}s (attempt {retries + 1}/{self.max_retries})..."
+                        )
+                        await asyncio.sleep(delay)
+                        retries += 1
+                        continue
+                    raise ProviderError(
+                        f"Anthropic API error ({resp.status_code}): {resp.text}"
+                    )
+
+                if resp.status_code >= 400:
+                    raise ProviderError(f"Anthropic API error ({resp.status_code}): {resp.text}")
+
+                data = resp.json()
+                break
+            except (httpx.ConnectError, httpx.ConnectTimeout) as net_err:
+                if retries < self.max_retries:
+                    base = self.base_delay * (2 ** retries)
+                    delay = min(self.max_delay, base + random.uniform(0.0, 0.25 * base))
+                    logger.warning(
+                        f"Anthropic connect error: {net_err}. Retrying in {delay:.2f}s..."
+                    )
+                    await asyncio.sleep(delay)
+                    retries += 1
+                    continue
+                raise ProviderError(f"Anthropic connection error: {net_err}") from net_err
+            except httpx.RequestError as err:
+                raise ProviderError(f"Anthropic connection error: {err}") from err
+            finally:
+                if not self._external_client:
+                    await client.aclose()
 
         text_chunks: list[str] = []
         extracted_calls: list[ToolCall] = []

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/src/chatflow_agent/core/engines/openai_compatible.py

@@ -96,10 +96,35 @@ class OpenAIEngine(BaseEngine):
             or preset.get("base_url", "https://api.openai.com/v1")
         ).rstrip("/")
 
-        env_key_name = preset.get("env_key", "OPENAI_API_KEY")
-        self.api_key = api_key or os.environ.get(env_key_name) or (
-            "ollama" if "localhost" in self.base_url or "127.0.0.1" in self.base_url else None
+        official_base_urls = {
+            p["base_url"].rstrip("/") for p in PROVIDER_PRESETS.values()
+        }
+        is_official = self.base_url in official_base_urls
+        is_local = any(
+            host in self.base_url for host in ("localhost", "127.0.0.1", "0.0.0.0")
         )
+
+        env_key_name = preset.get("env_key", "OPENAI_API_KEY")
+
+        self.api_key: str | None
+        if api_key is not None:
+            self.api_key = api_key
+        elif is_local:
+            # For local services (Ollama, LM Studio, vLLM on localhost), do not leak global cloud API keys
+            self.api_key = (
+                os.environ.get(env_key_name)
+                if self.provider in ("ollama", "gemma")
+                else None
+            ) or "ollama"
+        elif is_official:
+            self.api_key = os.environ.get(env_key_name)
+        else:
+            raise ValueError(
+                f"A custom or unofficial base_url was provided ({self.base_url!r}) without an explicit api_key. "
+                f"To prevent accidental leakage of your global {env_key_name} to untrusted endpoints, "
+                "fallback to environment API keys is disabled. "
+                "Please provide api_key explicitly (or pass api_key='' if no authentication is required)."
+            )
         self.timeout = timeout
         self.max_retries = 3
         self.base_delay = 1.0

{chatflow_agent-0.3.0 → chatflow_agent-0.3.2}/src/chatflow_agent/core/runner.py

@@ -1,6 +1,8 @@
 """Multi-agent Swarm-style execution Runner for chatflow-agent."""
 
 import asyncio
+import logging
+import uuid
 from typing import Any
 
 from chatflow_agent.core.agent import Agent
@@ -15,6 +17,8 @@ from chatflow_agent.types import (
     ToolResult,
 )
 
+logger = logging.getLogger("chatflow_agent.runner")
+
 
 class Runner:
     """Orchestrates multi-agent conversation loops, tool calling, and autonomous handoffs."""
@@ -122,11 +126,16 @@ class Runner:
                             try:
                                 raw_output = await tool_instance.execute_async(**call.args)
                             except Exception as err:
+                                trace_id = str(uuid.uuid4())
+                                logger.error(
+                                    f"Tool execution failed [trace_id: {trace_id}] - Tool: '{call.name}' on agent '{current_agent.name}': {err}",
+                                    exc_info=True,
+                                )
                                 tool_results.append(
                                     ToolResult(
                                         tool_call_id=call.id,
                                         name=call.name,
-                                        content=f"Execution error: {err}",
+                                        content=f"Tool execution failed [trace_id: {trace_id}]. Please try a different approach or inform the user.",
                                         is_error=True,
                                     )
                                 )
@@ -226,9 +235,7 @@ class Runner:
                 self.run_async(session_id, user_message, metadata=metadata)
             )
         except RuntimeError:
-            return asyncio.run(
-                self.run_async(session_id, user_message, metadata=metadata)
-            )
+            return asyncio.run(self.run_async(session_id, user_message, metadata=metadata))
 
     def __repr__(self) -> str:
         return (