Accept the backend's own origin behind a TLS-terminating proxy
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_originscallable; adds the floorpython-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 — anOriginwhose host and port equalHost, or the trustedX-Forwarded-Hostentry. An https Origin also matches an http-looking request; an http Origin is rejected when a trustedX-Forwarded-Protosays https/wss (asymmetric scheme rule). X-Forwarded-HostandX-Forwarded-Protoare read only throughtrusted_proxy_hopsproxies, using the same entry-from-the-right rule as the client IP (now one shared helper,_trusted_forwarded_value); with the defaulttrusted_proxy_hops=0the decision usesHostalone.- Explicit
cors_allowed_originslists 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, orcors_allowed_origins). - Docs (self-hosting, scaling, configuration, docker-example READMEs) now say when
REFLEX_DEPLOY_URLortrusted_proxy_hopsis needed.
Security argument
The threat is a cross-site page in the victim's browser (CSWSH).
- The page cannot forge
Origin;Hostis the host the browser connected to; a WebSocket handshake cannot carry page-set headers, and afetchwithX-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-Hostunconditionally). - A client that sets these headers directly is not a browser, carries no victim cookies, and could forge
Originanyway. - 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_hops0/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 throughapp()withOrigin https://app.example.com,Host app.example.comand no forwarded headers (accepted) plus a cross-site origin (rejected). 16 cases fail onmain'sreflex/app.py(incl. the two tightening rows: untrustedX-Forwarded-Hostaccepted on main) and pass here;test_app.py+test_config.py466 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 prodbehind 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 infix022/IMPACT.md).
Deployment table (prod, websocket)
| Front door | 0.10.1 | 0.11.0a1 | this PR | config 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) | ok | ok | ok | none |
| Keeps Host, no proto (L4 TLS LB, stunnel, HAProxy/nginx without XFP) | ok | fail | ok | none |
Caddy behind a TLS edge (docker-example/production on Render/Heroku) | ok | fail | ok | none |
Render if it sends X-Forwarded-Proto: wss | ok | fail | ok | none |
Rewrites Host, sends X-Forwarded-Host (Azure Front Door) | ok | ok | needs config | REFLEX_TRUSTED_PROXY_HOPS=1 or REFLEX_DEPLOY_URL |
Rewrites Host, no X-Forwarded-Host (nginx default proxy_pass, App Gateway host override) | ok | fail | fail | REFLEX_DEPLOY_URL |
| Split frontend/backend, static export/CDN, other port | ok | fail | fail | REFLEX_DEPLOY_URL on the backend |
Local reflex run --env prod | ok | ok | ok | none |
| Cross-site origin (attack) | accepted | rejected | rejected | — |
Notes
- Azure Front Door worked on 0.11.0a1 only through engine.io's unconditional
X-Forwarded-Host; it now needstrusted_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 "Withdeploy_urlset, 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 unreleasednews/+cors-prod-default.breaking.mdis left as onmain. - reflex-enterprise MCP still needs
REFLEX_DEPLOY_URL(FINDING-002; rxe should fall back toapi_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