fix(dashboard): _require_token endpoints all 401 behind the OAuth gate

[benbarclay]

Impact

On any publicly-bound dashboard (the OAuth-gated mode — Fly-hosted NAS agents, or any non-loopback bind without --insecure), every endpoint that calls _require_token directly always 401s with a popup:

401: {"detail":"Unauthorized"}

The reported symptom was plugin install failing, but the same bug breaks the whole class of _require_token endpoints behind the gate (14 in total):

• API-key reveal (POST /api/env/reveal)
• Provider key validation (POST /api/providers/validate)
• The entire OAuth-provider connect/disconnect flow (/api/providers/oauth/{id}/start, /submit, DELETE …/{id}, DELETE …/sessions/{sid})
• Plugin management (/api/dashboard/plugins/hub, agent-plugins/install, …/enable, …/disable, …/update, DELETE …/{name}, plugin-providers, plugins/{name}/visibility)

This is the common path for hosted dashboards, not an exotic config. Loopback (local hermes dashboard) users are not affected by this bug — their token-injection path is unchanged.

Root cause

Two auth schemes protect the dashboard, exactly one active per bind:

• Loopback / --insecure (auth_required False): the ephemeral _SESSION_TOKEN is injected into the SPA HTML and echoed back via X-Hermes-Session-Token. auth_middleware validates it.
• Gated / OAuth (auth_required True): _SESSION_TOKEN is not injected (_serve_index, web_server.py:9003-9018); the SPA authenticates with a session cookie. gated_auth_middleware verifies the cookie, attaches request.state.session, and 401s anything unauthenticated before the handler runs. auth_middleware correctly short-circuits in this mode (web_server.py:376-377).

The bug: the 14 handlers above call _require_token(request) directly, which only checked the legacy _SESSION_TOKEN header. In gated mode there is no such header, so the check 401'd every cookie-authenticated request — even though the gate had already authenticated it.

Fix

_require_token now defers to the active gate. When auth_required is True it accepts the request iff the gate attached a verified request.state.session (and 401s otherwise — so the endpoints stay protected, they don't become public). Loopback / --insecure behavior is byte-for-byte unchanged: it still validates the session token. Because the fix lives inside _require_token, all 14 call sites are covered.

Verified none of the 14 routes are in PUBLIC_API_PATHS (an allowlisted route would never get a gate-attached session and would then 401 after the fix). The gate matches PUBLIC_API_PATHS by exact string, so /api/dashboard/plugins being public does not leak to /api/dashboard/plugins/hub or …/{name}/visibility.

One-function change in hermes_cli/web_server.py.

Tests

In tests/hermes_cli/test_dashboard_auth_middleware.py, all driving the full in-process stub OAuth round trip (real gate, real cookies, real handler — nothing mocked):

• test_gated_require_token_endpoint_accepts_cookie_session — logged-in POST to install must not 401 (reaches the handler's own 400).
• test_gated_require_token_endpoint_still_rejects_no_cookie — unauthenticated POST must still 401.
• test_gated_require_token_routes_accept_cookie_session — parametrized over a representative spread (plugins/hub, env/reveal, providers/validate, an oauth provider route, agent-plugins/{name}/enable) proving the fix covers the whole class.

Verified the accept-test fails on the pre-fix code with the exact 401: {"detail":"Unauthorized"} bug, and passes with the fix. Full dashboard-auth + web_server suites green (346 passed). Confirmed the loopback _require_token matrix is unchanged (valid token → OK, missing/bad → 401).

Note: a separate follow-up PR will address the loopback stale-token UX (token rotates on every dashboard restart; a tab held across a restart can surface the same popup). Kept out of this PR to stay lane-pure.

[github-actions]

🔎 Lint report: fix/require-token-gated-cookie vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 10579 on HEAD, 10579 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 5557 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

[liuhao1024]

✅ Verified — OAuth gate fix for _require_token endpoints

Reviewed the diff for hermes_cli/web_server.py::_require_token and the regression tests.

• Gate delegation: Confirmed that when auth_required=True, _require_token checks request.state.session (set by gated_auth_middleware) before the handler runs. No token is required — the gate is authoritative.
• Backward compat: Loopback/--insecure mode still validates the ephemeral _SESSION_TOKEN as before. No behavior change for non-gated deployments.
• Test coverage: 3 test functions covering (1) cookie-authenticated request passes, (2) unauthenticated request still 401s, (3) parametrized sweep of all 5 representative _require_token routes. The _complete_stub_login helper correctly walks the full OAuth round-trip.

The fix is correct and well-scoped — it only changes the auth decision point without modifying any downstream handler logic. No issues found.

[tonydwb]

Code Review Summary

Verdict: Approved

Fixes a regression where _require_token endpoints 401'd cookie-authenticated requests behind the OAuth gate. The issue: _require_token checked for the ephemeral _SESSION_TOKEN which is NOT present in gated mode (the SPA uses session cookies there). The fix makes _require_token defer to the gate when auth_required is True, since the gate has already verified the cookie and attached request.state.session.

• Comprehensive test coverage: 3 new test functions covering the install endpoint + 5 other representative _require_token routes
• Fix is correct and well-documented in the docstring
• No security concerns

---

Reviewed by Hermes Agent (cron batch)