Accept the backend's own origin behind a TLS-terminating proxy

Merged
MA
6d ago
+730-32

Fixes FINDING-022 (and the diagnostics part of FINDING-023) from the reflex 0.11.0a1 pre-release testing (artifacts on branch claude/vibrant-pasteur-3921g3, prerelease-testing/runs/2026-11-11-v0.11.0a1/server_net/, verify_net/ and fix022/IMPACT.md).

All Submissions:

  • Have you followed the guidelines stated in CONTRIBUTING.md?
  • Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • This change requires a documentation update (included)

Changes To Core Features:

  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your core changes, as applicable?
  • Have you successfully ran tests with your changes locally?

Defect

#7641 made the prod websocket rely on engine.io's same-origin check when deploy_url is unset. engine.io's ASGI driver ignores the ASGI scheme and takes it from X-Forwarded-Proto (default http), then requires Origin == {scheme}://{Host}. A same-origin prod app behind a TLS terminator that sends no X-Forwarded-Proto (L4/TLS load balancers, stunnel, HAProxy or nginx without the header) or rewrites it to http (Caddy behind another TLS edge: docker-example/production on Render/Heroku) therefore rejected its own https:// origin with 403. The browser shows "Cannot connect to server … check if server is reachable" while /ping answers 200. Setting REFLEX_DEPLOY_URL as a workaround locked out direct access. engine.io also trusted a client-supplied X-Forwarded-Host.

Fix

  • Reflex passes engine.io its own origin check (cors_allowed_origins callable; adds the floor python-engineio >=4.12.0, the first version that calls it with the request environ).
  • Prod default: accept deploy_url's origin, if set, plus the request's own origin — an Origin whose host and port equal Host, or the trusted X-Forwarded-Host entry. An https Origin also matches an http-looking request; an http Origin is rejected when a trusted X-Forwarded-Proto says https/wss (asymmetric scheme rule).
  • X-Forwarded-Host and X-Forwarded-Proto are read only through trusted_proxy_hops proxies, using the same entry-from-the-right rule as the client IP (now one shared helper, _trusted_forwarded_value); with the default trusted_proxy_hops=0 the decision uses Host alone.
  • Explicit cors_allowed_origins lists and * are unchanged; the HTTP CORS layer is unchanged.
  • The first rejection per worker logs a warning with the origin, what the backend saw (Host, X-Forwarded-Host, trusted_proxy_hops), and the setting to change (REFLEX_DEPLOY_URL, REFLEX_TRUSTED_PROXY_HOPS, or cors_allowed_origins).
  • Docs (self-hosting, scaling, configuration, docker-example READMEs) now say when REFLEX_DEPLOY_URL or trusted_proxy_hops is needed.

Security argument

The threat is a cross-site page in the victim's browser (CSWSH).

  • The page cannot forge Origin; Host is the host the browser connected to; a WebSocket handshake cannot carry page-set headers, and a fetch with X-Forwarded-* is preflighted.
  • Compared with engine.io's default, the only origin added is https://<the host the browser connected to>, which only that host's certificate holder can serve.
  • Forwarded headers are now trusted only behind configured proxies (tighter than 0.11.0a1, where engine.io trusted X-Forwarded-Host unconditionally).
  • A client that sets these headers directly is not a browser, carries no victim cookies, and could forge Origin anyway.
  • Exact host and port equality; null, non-http schemes, userinfo, paths and malformed hosts are rejected. DNS rebinding is not addressed (neither 0.10.1 nor engine.io's default did).

Test plan

  • tests/units/test_app.py: table-driven origin decision (trusted_proxy_hops 0/1/2, forwarded chains incl. shorter than hops, default ports, IPv6, case, attacker origins); deploy_url / explicit / * / dev cases; warning hints; an ASGI websocket handshake through app() with Origin https://app.example.com, Host app.example.com and no forwarded headers (accepted) plus a cross-site origin (rejected). 16 cases fail on main's reflex/app.py (incl. the two tightening rows: untrusted X-Forwarded-Host accepted on main) and pass here; test_app.py + test_config.py 466 passed incl. the client-IP tests.
  • Full unit suite: 15683 passed, 66 skipped, 81.46% coverage (the Playwright browser-driver module could not run locally for lack of a Chromium binary). ruff, pyright reflex tests, check_min_deps.py reflex, pre-commit, reflex-release changelog-check, docs link tests: pass.
  • End to end: reflex run --env prod behind a TLS reverse proxy emulating each front door's documented header profile, driven by Chromium, plus raw handshakes (real proxy binaries could not run in the test sandbox; vendor citations in fix022/IMPACT.md).

Deployment table (prod, websocket)

Front door0.10.10.11.0a1this PRconfig needed with this PR
Keeps Host, sends X-Forwarded-Proto: https (ALB, GCP, Heroku, Fly, Cloudflare, DO, Railway, Caddy/Traefik/ingress-nginx at the edge)okokoknone
Keeps Host, no proto (L4 TLS LB, stunnel, HAProxy/nginx without XFP)okfailoknone
Caddy behind a TLS edge (docker-example/production on Render/Heroku)okfailoknone
Render if it sends X-Forwarded-Proto: wssokfailoknone
Rewrites Host, sends X-Forwarded-Host (Azure Front Door)okokneeds configREFLEX_TRUSTED_PROXY_HOPS=1 or REFLEX_DEPLOY_URL
Rewrites Host, no X-Forwarded-Host (nginx default proxy_pass, App Gateway host override)okfailfailREFLEX_DEPLOY_URL
Split frontend/backend, static export/CDN, other portokfailfailREFLEX_DEPLOY_URL on the backend
Local reflex run --env prodokokoknone
Cross-site origin (attack)acceptedrejectedrejected—

Notes

  • Azure Front Door worked on 0.11.0a1 only through engine.io's unconditional X-Forwarded-Host; it now needs trusted_proxy_hops. Intentional.
  • Changelog: the 0.11.0a1 breaking-change entry for #7641 lives only on the release branch (main's CHANGELOG.md starts at v0.10.1). Its sentence "With deploy_url set, only that origin is allowed" is no longer true after this PR (deploy_url now adds its origin to the backend's own); correct it in the release CHANGELOG directly. The unreleased news/+cors-prod-default.breaking.md is left as on main.
  • reflex-enterprise MCP still needs REFLEX_DEPLOY_URL (FINDING-002; rxe should fall back to api_url).
  • Not addressed: the frontend toast text ("reachable but refused"), engine.io's own ERROR line, DNS rebinding.

News fragments: news/+same-origin-behind-tls-proxy.bugfix.md, packages/reflex-base/news/+cors-allowed-origins-doc.docs.md (docstring change in config.py, required by the changelog check).


Generated by Claude Code