What does this PR do?

Adds an explicit trusted Host-header allowlist for the Hermes dashboard so operators can keep the dashboard bound to loopback while accessing it through a trusted local reverse proxy such as Tailscale Serve.

Today, that safer setup can fail with Invalid Host header because the browser reaches the dashboard using the reverse proxy's external hostname while Hermes is bound to 127.0.0.1. Binding the dashboard directly to 0.0.0.0 --insecure works around that, but it weakens the default safety model.

This PR keeps the existing DNS-rebinding protection by default and adds an opt-in HERMES_DASHBOARD_ALLOWED_HOSTS environment variable for trusted reverse-proxy hostnames. Host values are normalized before comparison, including host:port and bracketed IPv6 forms such as [::1]:9119.

It also documents the Tailscale Serve/reverse-proxy pattern and clarifies why these trusted proxy hosts are not added to CORS origins: navigating directly to the proxied dashboard hostname is not a cross-origin browser fetch.

Related Issue

Related to #10567 and #15731.

Also related to the currently open #20136, which takes a broader config-based approach for trusted reverse proxy hosts and WebSocket validation. This PR is the smaller environment-variable scoped approach for HTTP Host-header validation and documentation.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• hermes_cli/web_server.py
  • Add _host_header_name() to normalize Host headers consistently.
  • Add _configured_allowed_host_values() to parse HERMES_DASHBOARD_ALLOWED_HOSTS as comma- or semicolon-delimited hostnames.
  • Accept explicitly configured trusted hosts in _is_accepted_host() while preserving default localhost/DNS-rebinding protections.
  • Document that allowed hosts are matched literally and do not support wildcards/globs.
  • Clarify why reverse-proxy hostnames are intentionally not added to CORS origins.
• tests/hermes_cli/test_web_server_host_header.py
  • Add coverage for trusted proxy host allowlisting.
  • Add regression coverage for bracketed IPv6 Host headers with and without ports.
  • Add coverage for comma/semicolon-delimited allowlist entries, case normalization, port stripping, and IPv6 allowlist entries.
• website/docs/user-guide/features/web-dashboard.md
  • Add a short reverse-proxy/Tailscale Serve section showing loopback binding plus HERMES_DASHBOARD_ALLOWED_HOSTS.
  • Document delimiter behavior, port normalization, literal matching, and wildcard non-support.

How to Test

1. Run the Host-header test suite:

   python -m pytest tests/hermes_cli/test_web_server_host_header.py -q -o 'addopts='

   Expected result:

   11 passed
   

2. For a manual Tailscale Serve/local reverse-proxy setup, keep Hermes bound to loopback and set the trusted proxy hostname:

   HERMES_DASHBOARD_ALLOWED_HOSTS=dashboard.example.ts.net hermes dashboard --host 127.0.0.1 --no-open

3. Verify accepted and rejected Host headers against the loopback-bound dashboard:

   curl -i -H 'Host: dashboard.example.ts.net' http://127.0.0.1:9119/api/status
   curl -i -H 'Host: evil.example' http://127.0.0.1:9119/api/status

   The configured trusted host should be accepted, while an unlisted external host should still be rejected.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Linux 6.17.0

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A (HERMES_DASHBOARD_ALLOWED_HOSTS is an environment variable, not a config key)
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Targeted tests pass:

$ python -m pytest tests/hermes_cli/test_web_server_host_header.py -q -o 'addopts='
...........                                                              [100%]
11 passed in 0.73s

I also attempted the full suite with:

python -m pytest tests/ -q -o 'addopts='

The run does not complete cleanly on the current branch because of an existing baseline failure that is also present on origin/main:

FAILED tests/acp/test_registry_manifest.py::test_agent_json_version_matches_pyproject
FAILED tests/acp/test_registry_manifest.py::test_agent_json_pins_uvx_package_to_pyproject_version

Both origin/main and this branch currently have:

acp_registry/agent.json: 0.13.0
pyproject.toml: 0.14.0

So the full-suite checkbox is intentionally left unchecked; the targeted dashboard tests for this change pass.