Dashboard: accept extra Host values so Tailscale MagicDNS names work

[Zeus-Deus]

What this does

The dashboard rejects any request whose Host header does not exactly match the address the server was bound to. That is good DNS rebinding protection, but it makes some very normal setups impossible. My case: the gateway runs on my home server inside my tailnet, and I want to reach it by its Tailscale MagicDNS name. If I bind to the Tailscale IP, connecting via the hostname gets a 400 Invalid Host header. Same story for tailscale serve, which proxies to a loopback bind but forwards the external hostname.

This PR adds an opt in allowlist of extra Host values the server will accept. You can set it two ways, and they merge together:

a repeatable flag: hermes serve --host 100.x.y.z --allowed-host myserver.tailnet.ts.net

config: dashboard.allowed_hosts in config.yaml

Entries are normalized the same way the Host header is parsed (case, port, IPv6 brackets, full URLs, trailing dot), and the check goes through the same helper used by the HTTP middleware and both WebSocket host and origin guards, so all three surfaces behave the same.

The security part

Setting a non empty allowlist forces the auth gate on, regardless of the bind address. Allowlisting an external hostname means you expect requests from beyond the local machine, and without this rule a loopback bind behind tailscale serve would hand the unauthenticated dashboard, including its injected session token, to everyone who can reach the proxy. The existing fail closed check applies too: if the allowlist is set and no auth provider is configured, the server refuses to start, and the error message now names the allowlist as the reason. Starting it interactively in that state offers the auth setup prompt first instead of failing right away, through the same effective_auth_required condition start_server uses. Nothing changes when the allowlist is empty, which is the default.

Testing

New unit tests cover the validator with allowed hosts on loopback and non loopback binds, the entry normalization, the config plus flag merging, the auth forcing rule, the setup preflight on a loopback bind with an allowlist, the HTTP middleware accept and reject paths, and WebSocket accept and 4403 reject. The full host header suite passes (26 tests), along with the auth gate and WebSocket auth suites (142 passed total), and ruff is clean.

I also verified it against a live server: an allowlisted MagicDNS name is accepted with and without a port and with different casing, an unknown host still gets 400, /api/status reports the forced auth gate, starting with an allowlist but no auth provider refuses to boot with a helpful message, and a server without an allowlist behaves exactly as before.

Docs updated in the web dashboard guide (flag table, DNS rebinding note, a new MagicDNS section under Tailscale), SECURITY.md, and the security user guide. I left the zh-Hans translation mirror untouched.

Related to #62293, which adds a connect to server option to the desktop app first launch. Together they make the home server setup work end to end over Tailscale.

[alt-glitch]

This was generated by AI during triage.

Related: this remains a competing reverse-proxy/MagicDNS Host-allowlist implementation alongside feature anchor #34390 and open work #37119 (durable-service consolidation) and #20515 (Tailscale identity auth). The live branch supports only repeatable --allowed-host and dashboard.allowed_hosts, applies the normalized allowlist to HTTP and WebSocket checks, and forces authentication when it is non-empty; it is not a duplicate of one narrower implementation.

[teknium1]

Thanks for addressing the real reverse-proxy/MagicDNS limitation: current main rejects a non-bound Host in both HTTP (hermes_cli/web_server.py:460-486) and WebSocket (hermes_cli/web_server.py:14284-14315) paths.

Problems

• The new forced-auth branch needs to be reflected in the interactive setup preflight. hermes_cli/main.py:11829-11834 exits early for every loopback bind, while this PR makes a loopback bind with an allowed host require auth in start_server(). An interactive user can therefore skip setup and then hit the fail-closed error.
• The new HERMES_DASHBOARD_ALLOWED_HOSTS interface is a non-secret behavioral setting. AGENTS.md requires those settings to use config.yaml; please avoid documenting a new .env configuration surface.

Suggested changes

• Share the effective auth-required condition between the preflight and start_server(), then add a loopback-plus-allowlist regression test.
• Keep dashboard.allowed_hosts as the persistent mechanism and remove the new environment-variable path.

This is an automated hermes-sweeper review.

[Zeus-Deus]

Both points addressed in b9cac28.

Env var removed. The allowlist is now set only through the repeatable --allowed-host flag or dashboard.allowed_hosts in config.yaml, merged as a union. The HERMES_DASHBOARD_ALLOWED_HOSTS path is gone from the code, .env.example is back to what main has, and every doc mention (SECURITY.md, the security guide, the web dashboard guide, the flag help, the config comment) now points at the flag and config only. I also checked against a live server that a host named only in the env var gets a 400 again while the server starts ungated on loopback, so nothing silently reads it anymore.

Preflight and start_server now share one condition. Added effective_auth_required(host, allowed_hosts) in web_server.py next to should_require_auth, which keeps its pure bind address semantics for other callers. start_server uses it for app.state.auth_required, and the interactive preflight resolves the allowlist from the args and early returns only when the shared condition says the gate stays off. So a loopback bind with an allowed host now gets the interactive auth setup instead of falling through to the fail closed SystemExit. The prompt also explains why the gate engaged in that case, since the old wording about binding to a non loopback address would be wrong there:

⚠ The dashboard has an allowed-hosts allowlist set, which requires an auth provider even on a loopback bind.
  Allowlisting an external hostname means requests can arrive from beyond this machine.

  How do you want to authenticate the dashboard?
    [1] Username & password (quickest; for a trusted LAN / VPN)
    [2] OAuth via Nous Portal (run `hermes dashboard register`)
    [3] Cancel

Tests: the new regression test runs the preflight with a loopback bind plus an allowlist and asserts it prompts instead of returning early, with a control case for the empty allowlist and unit tests for the helper. The union test now covers CLI plus config. 26 pass in the host header suite and 59 across that plus the auth gate suites, ruff clean. I also reran the live checks from the PR description: an allowlisted name is accepted with and without a port and with different casing, a config sourced entry works alongside the flag, an unknown host still gets 400, and a non TTY start with an allowlist but no provider still refuses to boot with the message naming the allowlist as the reason.

[Zeus-Deus]

@teknium1 Bumping this one too since it's been quiet for a bit. Both review points are addressed in b9cac28 and the branch is still conflict free and mergeable against current main.

Quick recap of where it stands: the HERMES_DASHBOARD_ALLOWED_HOSTS env var is gone entirely, so the allowlist is set only through the repeatable --allowed-host flag or dashboard.allowed_hosts in config.yaml, with docs and .env.example matching. And the preflight and start_server now share the effective_auth_required condition, so a loopback bind with an allowlist gets the interactive auth setup prompt instead of falling through to the fail closed error, covered by the loopback plus allowlist regression test you asked for. Host header and auth gate suites are green and the whole flow was verified against a live server, details in my previous comment.

Ready for another look whenever you get a chance.

[Kinkoolino-Hermes]

One small reviewability cleanup remains: the PR description still says the allowlist has three sources and lists HERMES_DASHBOARD_ALLOWED_HOSTS; its Testing section also still says “config plus env plus flag merging” and lists .env.example among the updated allowlist docs. At current head b9cac28, the supported sources are the repeatable --allowed-host flag plus dashboard.allowed_hosts only.

Could you update the description and test summary to match the current head so the intended config/CLI behavior is unambiguous for final review?

[Zeus-Deus]

Good catch, the description was still describing the pre review version. Updated it to match the current head: two sources only, the repeatable --allowed-host flag and dashboard.allowed_hosts in config.yaml, and the Testing section now reflects the current suites (26 in the host header suite, 142 total with the auth gate and WebSocket auth suites) plus the setup preflight coverage that was added during review. No .env.example changes anymore either since the env var path is gone.