fix: add do_OPTIONS handler for CORS preflight requests

[weidzhou]

Summary

Add do_OPTIONS() handler to respond to CORS preflight requests with 200 OK and appropriate headers.

Without this handler, browsers sending a preflight OPTIONS request receive 501 Not Implemented, blocking cross-origin API calls.

Changes

server.py — Added do_OPTIONS() method. No changes to end_headers() — CORS headers are only set on the preflight response, not broadened to all endpoints.

[nesquena-hermes]

Reading the diff at server.py:292-298 against the existing CSRF flow in api/routes.py:1246-1306 on origin/master — the addition compiles and unblocks browsers that currently see a 501, but the headers as written are likely to land users in a worse state than they expect. Worth a closer look.

What the PR adds

def do_OPTIONS(self) -> None:
    """Handle CORS preflight requests."""
    self._req_t0 = time.time()
    self.send_response(200)
    self.send_header("Access-Control-Allow-Origin", "*")
    self.send_header("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS")
    self.send_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
    self.end_headers()

This bypasses check_auth and _check_csrf entirely (which is correct — preflights are by spec unauthenticated). The browser then proceeds to the real request.

The trap

The real POST/PATCH/DELETE still goes through _check_csrf (api/routes.py:1262), which is strict:

if not _is_browser_unsafe_request(handler):
    return True  # non-browser clients (curl, MCP, agent) have no Origin
target = origin or referer
# ...
if origin_value in _allowed_public_origins():
    origin_allowed = True
if not origin_allowed:
    # Allow same-origin: check Host, X-Forwarded-Host (reverse proxy), and
    # X-Real-Host against the origin.

So after this PR, a cross-origin browser preflight succeeds with Access-Control-Allow-Origin: *, the browser concludes "great, CORS is wide open", then sends the credentialed request, which the server rejects via CSRF unless the origin is in HERMES_WEBUI_ALLOWED_PUBLIC_ORIGINS. From the user's perspective the page now sees the failure as a CSRF rejection instead of a 501 — slightly more informative but still a bounce.

The bigger problem: Access-Control-Allow-Origin: * with credentials is invalid per the CORS spec. Browsers will refuse to attach cookies when the wildcard is used, which means any same-origin assumption baked into the WebUI session model (cookie-based auth via check_auth) breaks in the cross-origin path even if CSRF were permissive. The combination here is "preflight says yes, request says no". Better to make them agree.

What I think this should look like

Echo the Origin only when it matches the same allowlist _check_csrf already enforces, and set Access-Control-Allow-Credentials: true:

def do_OPTIONS(self) -> None:
    self._req_t0 = time.time()
    origin = self.headers.get("Origin", "")
    # Reuse the same allowlist as _check_csrf — if the origin won't pass
    # the real request's CSRF check, don't pretend the preflight succeeded.
    from api.routes import _origin_is_permitted  # or whatever helper exists
    if origin and _origin_is_permitted(self, origin):
        self.send_response(204)
        self.send_header("Access-Control-Allow-Origin", origin)
        self.send_header("Vary", "Origin")
        self.send_header("Access-Control-Allow-Credentials", "true")
        self.send_header("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS")
        self.send_header("Access-Control-Allow-Headers", "Content-Type")
        self.send_header("Access-Control-Max-Age", "600")
    else:
        self.send_response(403)
    self.end_headers()

_check_csrf doesn't expose a clean predicate today — the origin-matching logic at api/routes.py:1262-1306 would need to be refactored into a helper that both _check_csrf and do_OPTIONS can call. That's the right refactor anyway: today the CSRF rules live as inline code inside the check, and any future feature that wants to know "is this origin acceptable?" would have to duplicate the host/X-Forwarded-Host normalisation.

Smaller nits

• Access-Control-Allow-Headers: Content-Type, Authorization — the WebUI doesn't actually accept Authorization headers anywhere I can see (auth is cookie-based, set by /api/auth/login). Listing it is harmless but misleading.
• No Access-Control-Max-Age, so the browser preflights every request. A Max-Age: 600 would cut request count noticeably.
• The use case driving this isn't named in the PR body. Is this for a known consumer (mobile WebView, browser extension, separate frontend)? If so, the right behaviour is to require that origin be in HERMES_WEBUI_ALLOWED_PUBLIC_ORIGINS and reject everything else. If it's not, the PR is enabling a footgun.

I'd hold this until either (a) the body explains who's consuming the preflight and the allowlist is wired through, or (b) the headers are tightened to echo Origin against the existing allowlist rather than *. The current shape advertises a CORS contract the server can't fulfill.

[nesquena-hermes]

Shipped in v0.51.120 via release/stage-batch2 (#2810). The minimal split that closed #2750 asked for — only the do_OPTIONS handler, no broader CORS posture change. Thanks for landing this cleanly.