[security] fix(gateway): harden callbacks, CDP, and health diagnostics

[Hinotoi-agent]

Summary

This PR hardens three small security boundaries in Hermes gateway/tool surfaces:

• Telegram model-picker inline callbacks now reuse the same callback authorization path as approval-style callbacks.
• Explicit Chrome DevTools Protocol (CDP) override endpoints are validated before Hermes connects to them or performs discovery.
• /health/detailed now requires API authentication when the API server is configured with an API key.

The changes are intentionally narrow and covered by focused regression tests.

Security issues covered

Issue	Surface	Impact	Fix
Unauthorized Telegram model picker callbacks	gateway/platforms/telegram.py	A denied Telegram user who can press an inline model picker button could change a chat/session model setting	Check callback user authorization before dispatching model-picker callbacks
Unsafe explicit CDP override endpoints	tools/browser_tool.py	A malicious or unsafe CDP override URL could make Hermes connect to non-public hosts or perform discovery against internal targets	Validate explicit WebSocket/discovery endpoints with URL safety checks and disable redirects
Unauthenticated detailed API health diagnostics	gateway/platforms/api_server.py	Detailed runtime/platform status could be read without auth even when the API server has an API key configured	Require the configured API key for /health/detailed, while preserving unauthenticated /health liveness

Before this PR

• Telegram approval, slash-confirm, and prompt-update callbacks used gateway callback authorization, but model picker callbacks (mp:, mm:, mb, mx, mg:) only checked that picker state existed for the chat.
• _resolve_cdp_override() preserved full ws://.../devtools/browser/... endpoints directly and performed /json/version discovery without first rejecting unsafe endpoint hosts.
• /health/detailed explicitly skipped authentication and returned gateway runtime state, platform status, active agent count, exit reason, timestamp, and PID.

After this PR

• Model picker callbacks call _is_callback_user_authorized() with chat/thread/user context before mutating picker state.
• Explicit CDP WebSocket and discovery endpoints are blocked unless they pass the existing safe URL/IP checks; discovery requests also disable redirects.
• /health/detailed uses _check_auth() whenever an API key is configured, matching other state-bearing API routes.

Why this matters

These surfaces sit at trust boundaries that are easy to overlook because they are convenience/control-plane paths rather than primary chat message handling:

• Inline Telegram buttons can be clicked by users other than the user who opened the panel, especially in group contexts.
• CDP endpoints are powerful browser-control channels; connecting to an attacker-controlled or internal endpoint can expose browser automation capabilities or internal network metadata.
• Detailed health diagnostics are useful for operators, but they can contain platform error messages and runtime state that should not be disclosed to unauthenticated callers when an API key is configured.

How this differs from related issue/PR

• Telegram approval callbacks were already hardened in fix(telegram): enforce gateway auth for inline approval callbacks (#17862) #18180. That PR explicitly called out model picker callbacks as a separate follow-up concern. This PR addresses that separate callback family rather than approval/confirm/update-prompt callbacks.
• CDP trust semantics are related to the broader discussion in Define trust semantics for custom CDP/browser-connect endpoints #8084. This PR does not attempt to redesign all browser trust semantics; it only blocks unsafe explicit override endpoints before direct use/discovery and preserves local/allowed behavior covered by tests.
• /health/detailed is distinct from the dashboard host/plugin-auth family and from basic /health liveness checks. This PR keeps /health unauthenticated and only protects the detailed diagnostic endpoint when an API key exists.

Attack flow

1. Telegram model picker callback:

   1. An authorized user opens a model picker panel in a chat.
   2. A denied user presses one of the inline model picker buttons.
   3. Vulnerable code dispatches the callback based on chat picker state without checking the callback user.

2. Explicit CDP override endpoint:

   1. A CDP override is supplied via config/environment/provider output.
   2. Vulnerable code accepts a full ws://.../devtools/browser/... URL directly, or performs HTTP discovery against a supplied endpoint.
   3. Hermes attempts to connect to or query an unsafe host.

3. Detailed API health diagnostics:

   1. The API server is configured with an API key.
   2. An unauthenticated caller requests /health/detailed.
   3. Vulnerable code returns runtime/platform diagnostics without checking the key.

Affected code

• gateway/platforms/telegram.py — Telegram callback dispatch for model picker actions.
• tools/browser_tool.py — CDP override URL normalization/discovery.
• gateway/platforms/api_server.py — detailed health endpoint.
• Focused regression tests under:
  • tests/gateway/test_telegram_approval_buttons.py
  • tests/tools/test_browser_cdp_override.py
  • tests/gateway/test_api_server.py

Root cause

• Model picker callbacks were outside the callback authorization coverage added for approval-style callbacks.
• CDP override handling trusted explicit endpoints before applying URL/IP safety policy.
• /health/detailed treated a diagnostic endpoint as equivalent to a minimal liveness probe even when API auth was configured.

CVSS assessment

• Telegram model picker callback authorization: CVSS v3.1 4.3 — CVSS:3.1/AV:N/AC:L/PR:L/UI:R/S:U/C:N/I:L/A:N. A denied Telegram user with access to an inline button can alter model selection/state.
• Unsafe explicit CDP override endpoint: CVSS v3.1 6.5 — CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N. A malicious unsafe endpoint can drive Hermes to connect/query internal browser-control or metadata surfaces when override input is accepted from a lower-trust source.
• Unauthenticated detailed health diagnostics: CVSS v3.1 5.3 — CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:N/A:N. Detailed platform/runtime diagnostics are disclosed without auth despite API-key configuration.

Safe reproduction steps

Run the focused regression tests on vulnerable code before applying the patch:

python -m pytest tests/tools/test_browser_cdp_override.py tests/gateway/test_telegram_approval_buttons.py tests/gateway/test_api_server.py -q

The added/updated tests exercise:

• Unauthorized Telegram model-picker callback users are rejected and the picker handler is not called.
• Unsafe CDP WebSocket/discovery endpoints are rejected before connection/discovery.
• /health/detailed returns 401 without the configured API key and 200 with the key.

Expected vulnerable behavior

On vulnerable code:

• Telegram model picker callbacks route to _handle_model_picker_callback() without checking the callback user.
• Unsafe CDP override URLs are accepted or queried during discovery.
• /health/detailed returns 200 without Authorization even when platforms.api_server.key is configured.

Changes in this PR

• Added an authorization check before model picker callback dispatch.
• Added CDP endpoint safety validation for full WebSocket endpoints and discovery endpoints.
• Disabled redirects for CDP /json/version discovery requests.
• Required API key authentication for /health/detailed when API auth is configured.
• Added focused regression tests for all three behaviors.

Files changed

Category	Files	What changed
Telegram gateway	gateway/platforms/telegram.py, tests/gateway/test_telegram_approval_buttons.py	Model picker callbacks now honor callback authorization
Browser tool	tools/browser_tool.py, tests/tools/test_browser_cdp_override.py	CDP override endpoints are validated before use/discovery
API server	gateway/platforms/api_server.py, tests/gateway/test_api_server.py	Detailed health diagnostics require auth when an API key exists

Maintainer impact

• Basic /health remains unauthenticated for liveness probes.
• Existing safe/local CDP override behavior remains covered by tests.
• Authorized Telegram model picker use still works.
• The stricter /health/detailed behavior only affects deployments that configured an API key and were relying on unauthenticated detailed diagnostics.

Fix rationale

The patch enforces the security boundary at the point where each action crosses from low-trust input into control-plane behavior:

• callback user identity before model mutation,
• endpoint safety before browser-control connection/discovery,
• API key authentication before detailed runtime disclosure.

This keeps the changes focused and avoids broad rewrites of unrelated gateway/tool behavior.

Type of change

• Security hardening
• Bug fix
• Tests
• Documentation-only change

Test plan

Commands run:

python -m pytest tests/tools/test_browser_cdp_override.py tests/gateway/test_telegram_approval_buttons.py tests/gateway/test_api_server.py -q
python -m ruff check gateway/platforms/api_server.py gateway/platforms/telegram.py tools/browser_tool.py tests/gateway/test_api_server.py tests/gateway/test_telegram_approval_buttons.py tests/tools/test_browser_cdp_override.py
python -m py_compile gateway/platforms/api_server.py gateway/platforms/telegram.py tools/browser_tool.py

Results:

• 166 passed, 89 warnings
• ruff: All checks passed!
• py_compile: passed

Disclosure notes

This PR is intentionally bounded to three concrete, locally reproduced hardening fixes. It does not claim to redesign the entire Telegram callback model, CDP trust model, or API server observability model. Related public prior art is noted above where applicable so maintainers can review the differences quickly.

[teknium1]

Thanks for the focused hardening work. Two parts still address verified current-main gaps, while the health-endpoint portion has already landed.

Problems

• The /health/detailed change is redundant: current gateway/platforms/api_server.py:1383-1385 authenticates before diagnostics, with tests at tests/gateway/test_api_server.py:775-790 from 2d8d08cae.
• Telegram moved to plugins/platforms/telegram/adapter.py; its current model-picker dispatch at :5307-5311 includes mpg:, mpv:, and mc: in addition to the prefixes in this PR, and still needs the callback authorization gate.
• The CDP concern remains current: tools/browser_tool.py:407-423 directly accepts a DevTools URL and probes discovery without endpoint validation or allow_redirects=False.

Suggested changes

• Salvage only the CDP and Telegram hardening; omit the already-merged health hunk.
• Apply Telegram authorization immediately before the current dispatch and test every current callback family.

Automated hermes-sweeper review.