From 77684ea183c45e371580801d62284947cf588653 Mon Sep 17 00:00:00 2001 From: Blomios Date: Thu, 16 Jul 2026 18:11:56 +0200 Subject: [PATCH 1/2] docs(server): clarifier le bind du cas proxy distant et l'origine stricte (#65) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit L'exemple du cas « Remote HTTPS » bindait `127.0.0.1` en supposant sans le dire que le reverse proxy tourne sur la même machine que le serveur. Suivi tel quel avec un proxy sur une autre machine, il produit un serveur injoignable — ce qui a réellement induit l'utilisateur en erreur aujourd'hui. Précise donc : le cas co-localisé vs le cas proxy distant (binder une adresse joignable par le proxy, lien proxy→serveur en HTTP clair sur le LAN), la configuration exigée pour tout bind non-loopback, l'égalité stricte de `--public-origin` contre l'`Origin` de la requête (ouvrir l'UI par le domaine et non par l'IP, sinon 403), et le pare-feu hôte comme cause de timeout depuis les autres machines. Indépendant de #68 et #71 : valeur immédiate, n'attend aucun de leurs lots. Co-Authored-By: Claude Opus 4.8 --- docs/server-client-mode-remote.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/server-client-mode-remote.md b/docs/server-client-mode-remote.md index 58e7a5b..e9cae99 100644 --- a/docs/server-client-mode-remote.md +++ b/docs/server-client-mode-remote.md @@ -59,8 +59,24 @@ idea --serve \ --trust-reverse-proxy ``` +This example is for a reverse proxy running on the same machine as the server. +If the proxy runs on another machine, bind an address reachable by that proxy, +for example `--listen 192.168.1.75:17373`, and point the proxy upstream to that +address and port. The link from proxy to server is still plain HTTP on the LAN; +only the public access is HTTPS. + +For any non-loopback bind, keep the full remote HTTPS configuration: +`--allow-remote`, `--public-origin https://...`, and `--trust-reverse-proxy`. +`ServerConfig::validate()` rejects a non-loopback bind without it. + The proxy must forward the same origin for the SPA, `/api/*`, and `/api/ws`. -Do not expose the backend on a public non-loopback address without TLS proxying. +`--public-origin` is matched by strict equality against the request `Origin`: +open the UI through the configured domain, not through the server IP, otherwise +API calls are rejected with 403. + +With a LAN bind, also check the host firewall. If the server is reachable from +the local machine but times out from every other host, open the port for the LAN +subnet or, preferably, only for the proxy IP. Avoid opening it broadly: the +server does not provide its own TLS. Secrets must never be placed in URLs; pairing uses `POST /api/pair` and then an `HttpOnly`, `Secure`, `SameSite=Strict` session cookie. - From 677f64d18ed1709ffc12907a9b439cfce9e26a78 Mon Sep 17 00:00:00 2001 From: Blomios Date: Thu, 16 Jul 2026 18:51:11 +0200 Subject: [PATCH 2/2] docs(server): restaurer l'obligation de proxy TLS, que validate() n'assure pas (#65) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit La réécriture précédente avait remplacé « Do not expose the backend on a public non-loopback address without TLS proxying » par une formulation adossée à `ServerConfig::validate()`. Littéralement vraie, mais pas équivalente : elle troque une OBLIGATION faite à l'opérateur contre une garantie automatique qui n'existe pas. `validate()` valide une configuration, pas la réalité. Rien ne vérifie qu'un proxy est réellement devant le serveur : passer les trois drapeaux en bindant `0.0.0.0` sans aucun proxy satisfait `validate()` et sert du HTTP en clair. La phrase normative est donc rétablie, avec cette limite dite explicitement. Voir #72 : `--trust-reverse-proxy` n'a par ailleurs aucun effet à l'exécution. Co-Authored-By: Claude Opus 4.8 --- docs/server-client-mode-remote.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/server-client-mode-remote.md b/docs/server-client-mode-remote.md index e9cae99..f40bf6c 100644 --- a/docs/server-client-mode-remote.md +++ b/docs/server-client-mode-remote.md @@ -68,6 +68,9 @@ only the public access is HTTPS. For any non-loopback bind, keep the full remote HTTPS configuration: `--allow-remote`, `--public-origin https://...`, and `--trust-reverse-proxy`. `ServerConfig::validate()` rejects a non-loopback bind without it. +That check covers the configuration, not reality: it cannot verify that a proxy +is actually terminating HTTPS in front of the server. Do not expose the backend +on a public non-loopback address without TLS proxying. The proxy must forward the same origin for the SPA, `/api/*`, and `/api/ws`. `--public-origin` is matched by strict equality against the request `Origin`: